scf controls in .oqp

.oqp control reference

Use canonical routes and controls in input files. Raw names identify implementation storage. A control without an accepted canonical spelling is not available in .oqp files.

The scf section controls the reference wavefunction and SCF convergence strategy. It is required for HF, DFT, MP2, TDHF/TDDFT, SF-TDDFT, MRSF-TDDFT, SOC, NACME, and EKT workflows.

Minimal Examples

Closed-shell singlet:

rhf/6-31g*
geom="molecule.xyz"

Triplet ROHF reference for MRSF-TDDFT:

rohf/6-31g* mult=3
geom="molecule.xyz"

Keywords

type

Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.

Field	Value
Type	string
Default	rhf
Values	rhf, rohf, uhf
Used by	reference selection

Selects the SCF reference. Use rhf for closed-shell singlets, rohf for the high-spin reference commonly used by SF/MRSF workflows, and uhf for unrestricted references including UMRSF-TDDFT and UHF-referenced SF-TDDFT. Standalone MP2 supports RHF, UHF, and ROHF references.

The input checker rejects type=rhf with multiplicity>1.

multiplicity

Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.

Field	Value
Type	integer
Default	1
Used by	spin state and electron occupation

Sets the spin multiplicity, 2S+1. SF/MRSF examples usually use a triplet ROHF reference with multiplicity=3. In the high-level Python API, job.theory.mrsf(...) supplies this usual MRSF reference multiplicity implicitly; set multiplicity in job.molecule(...) for ordinary HF/DFT references or when overriding the default deliberately.

maxit

Canonical input call: scf(maxit=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	30
Used by	SCF iteration loop

Maximum number of SCF iterations before failure or fallback handling.

conv

Canonical input call: scf(conv=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	1.0e-6
Used by	SCF convergence test

Energy/density convergence threshold for the SCF cycle. Tighten this for high-precision properties or difficult state comparisons.

maxdiis

Canonical input call: scf(maxdiis=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	7
Used by	DIIS subspace

Maximum number of vectors kept in the DIIS extrapolation space. Set maxdiis <= 13 whenever an active DIIS stage uses ediis, adiis, vdiis, or any nonzero vshift; those paths use the deterministic simplex solver, whose exact supported history limit is 13 states. The rule applies to the primary DIIS/auto/ml converger, to an enabled init_scf stage when its effective init_converger is DIIS, and to any DIIS stage selected through escalation or alternative_scf. A calculation using only soscf or trah, or unshifted cdiis, may use a larger history.

diis_type

Canonical input call: scf(diis_type=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	cdiis
Values	none, cdiis, ediis, adiis, vdiis
Used by	DIIS convergence accelerator

Selects the DIIS variant. cdiis is the default. vdiis can be useful for difficult cases with level shifting. Active ediis, adiis, and vdiis stages require maxdiis <= 13.

diis_reset_mod

Canonical input call: scf(diis_reset_mod=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	10
Used by	DIIS reset logic

Controls periodic DIIS reset behavior.

diis_reset_conv

Canonical input call: scf(diis_reset_conv=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.005
Used by	DIIS reset logic

Convergence threshold used by the DIIS reset heuristic.

cdiis_switch

Canonical input call: scf(cdiis_switch=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.3
Used by	CDIIS switching heuristic

Threshold for switching into CDIIS-style extrapolation.

vdiis_vshift_switch

Canonical input call: scf(vdiis_vshift_switch=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.003
Used by	VDIIS level-shift behavior

Threshold for VDIIS/level-shift switching.

vshift

Canonical input call: scf(vshift=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.0
Used by	virtual-orbital level shift

Applies a level shift during SCF. Larger values can stabilize convergence but may slow final convergence. For an active DIIS stage, any nonzero value selects the C-DIIS/E-DIIS/C-DIIS cascade regardless of diis_type, so maxdiis must not exceed 13.

incremental

Canonical input call: scf(incremental=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	True
Used by	incremental Fock build

Enables incremental Fock builds where supported.

mom

Canonical input call: scf(mom=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	False
Used by	maximum-overlap method

Enables MOM occupation tracking for challenging electronic states. In every iteration, after the new Fock matrix is diagonalised, MOM occupies the orbitals with the largest overlap with the previous orbitals instead of the lowest ones. The first reference is the guess orbitals, so a non-aufbau guess (for example one prepared with swapmo) is kept from the first iteration, as long as MOM is already active there (see mom_switch):

rhf/6-31g* scf(mom=true,mom_switch=100)
geom="molecule.xyz"

MOM cannot be combined with TRAH. TRAH minimises the energy and never rediagonalises the Fock matrix, so it would leave the targeted state. converger_type=trah or init_converger=trah together with mom=true is an input error. The escalation ladder, the stability pass and converger_type=ml never use TRAH for a MOM calculation.

mom_switch

Canonical input call: scf(mom_switch=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.003
Used by	MOM activation heuristic

MOM becomes active once the DIIS error drops below this value. Before that, each iteration fills the lowest orbitals. To keep a non-aufbau guess, set it above the first DIIS error, for example mom_switch=100.

pfon

Canonical input call: scf(pfon=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	False
Used by	pseudo-fractional occupation number method

Enables pFON smoothing for difficult SCF cases.

pfon_start_temp

Canonical input call: scf(pfon_start_temp=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	2000.0
Used by	pFON schedule

Initial pFON electronic temperature.

pfon_cooling_rate

Canonical input call: scf(pfon_cooling_rate=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	50.0
Used by	pFON schedule

Cooling rate used as pFON occupations are annealed.

pfon_nsmear

Canonical input call: scf(pfon_nsmear=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	5.0
Used by	pFON occupation smoothing

Controls the smearing width/count used by the pFON method.

converger_type

Canonical input call: scf(converger_type=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	diis
Values	diis, soscf, trah, auto, ml
Used by	SCF convergence manager

Selects the main SCF convergence strategy. auto and ml are Python-side manager modes that choose a concrete native converger before dispatch.

trah is rejected together with mom=true or rstctmo=true. When ml would choose TRAH for such a calculation, DIIS is used instead.

init_converger

Canonical input call: scf(init_converger=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	None
Values	empty, none, diis, soscf, trah, auto, ml
Used by	initial SCF phase

Overrides the converger used during an optional initial SCF stage. As with converger_type, trah is rejected together with mom=true or rstctmo=true.

alternative_scf

Canonical input call: scf(alternative_scf=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	trah
Values	diis, soscf, trah, auto, ml
Used by	fallback SCF attempts

Fallback converger after repeated SCF difficulty.

escalation

Canonical input call: scf(escalation=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	comma-separated string
Default	empty
Values	diis, soscf, trah stages
Used by	custom fallback ladder

Overrides the default escalation ladder. With mom=true or rstctmo=true the TRAH stage is dropped from any ladder, because TRAH cannot keep the selected occupation. Example:

rhf/6-31g* scf(escalation="soscf,trah")
geom="molecule.xyz"

forced_attempt

Canonical input call: scf(forced_attempt=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	2
Used by	repeated SCF attempts

Controls how many attempts the SCF manager can force before declaring failure or escalating.

init_scf

Canonical input call: scf(init_scf=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	no
Values	no, rhf, uhf, rohf, rks, uks, roks
Used by	initial low-cost SCF stage

Requests an initial SCF calculation before the main SCF. KS-style initial SCF values (rks, uks, roks) require input.functional.

init_basis

Canonical input call: scf(init_basis=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	none
Used by	initial SCF basis selection

Basis used for the initial SCF stage. library can be used with init_library.

init_library

Canonical input call: scf(init_library=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	multiline string
Default	empty
Used by	tagged basis mapping for init_basis=library

Maps atom tags to basis names for the initial SCF basis.

init_it

Canonical input call: scf(init_it=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	15
Used by	initial SCF stage

Maximum number of iterations in the initial SCF stage.

init_conv

Canonical input call: scf(init_conv=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.001
Used by	initial SCF stage

Convergence threshold for the initial SCF stage.

save_molden

Canonical input call: scf(save_molden=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	True
Used by	Molden output

Writes Molden orbital files when supported. Hessian calculations combine SCF orbitals and normal modes in the frequency Molden file. MRSF-EKT calculations also write a state-labeled Dyson Molden file after the EKT kernel completes. See Orbital and Vibrational Output.

rstctmo

Canonical input call: scf(rstctmo=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	False
Used by	MO ordering

Restricts molecular-orbital ordering in workflows that need stable state or orbital labels. The occupation chosen in the guess (for example with swapmo) is kept through the iterations. This is the delta-CHP core-hole route.

Like mom, rstctmo cannot be combined with TRAH (converger_type=trah or init_converger=trah is an input error), and TRAH is never used for escalation or stability.

scal_rel

Canonical input call: scf(scal_rel=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	0
Values	0, 1, 2
Used by	scalar-relativistic one-electron Hamiltonian

Selects the scalar relativistic Douglas-Kroll-Hess correction applied to the spin-free one-electron core Hamiltonian:

Value	Meaning
0	Disabled.
1	First-order Douglas-Kroll-Hess correction.
2	First- and second-order Douglas-Kroll-Hess correction.

This is not the SOC switch. scal_rel changes the scalar, spin-free Hamiltonian; SOC is selected separately with input.runtype=soc and input.soc_2e. See References for the DKH background.

The input-file default is scal_rel=0. In the high-level Python API, job.workflow.soc(...) sets scal_rel=2 by default for the SOC workflow because the documented SOC path uses a DKH2 spin-free Hamiltonian before the SOC matrix is formed. Pass scal_rel=0, 1, or 2 to override that helper default.

scal_rel_decontract

Canonical input call: scf(scal_rel_decontract=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	1
Values	0, 1
Used by	scalar-relativistic one-electron Hamiltonian (scal_rel=1 or 2)

Selects the basis in which the Douglas-Kroll-Hess decoupling is carried out:

Value	Meaning
1	The basis is decontracted (one shell per unique primitive exponent per atom, angular momentum and angular type), the decoupling is carried out there, and the relativistic correction to the core Hamiltonian is projected back onto the contracted basis with the contraction matrix.
0	The decoupling is carried out directly in the contracted basis (the behaviour before this keyword existed).

Use the default. The contracted basis truncates the kinetic-balance space of the decoupling, and with contracted relativistic basis sets the resulting Hamiltonian is not variational: the DKH2 energy of the mercury atom in a contracted Sapporo-DKH3-DZP basis is about 2300 Hartree below the energy obtained with the same basis fully uncontracted, and about 2300 Hartree below the Dirac-Coulomb Hartree-Fock limit. With scal_rel_decontract=1 the contracted-basis energy lies within the usual contraction error above the uncontracted-basis value (0.56 Hartree for that case; 0.1 Hartree for krypton in x2c-TZVPall). For an already uncontracted basis both values give the same result.

The decontraction applies only to the construction of the relativistic core Hamiltonian; the SCF itself still uses the contracted basis. 0 is kept to reproduce earlier results and for comparison.

stability

Canonical input call: scf(stability=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	False
Used by	SCF stability analysis

Requests stability analysis where wired. The analysis uses TRAH and is skipped for mom=true and rstctmo=true calculations.

soscf_lvl_shift

Canonical input call: scf(soscf_lvl_shift=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0
Used by	SOSCF convergence

Level shift used by the SOSCF converger.

verbose

Canonical input call: scf(verbose=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	1 (0 for runtype = md and namd)
Values	0, 1, 2, 3
Used by	the text log of the whole run

Older spelling of input.verbose, which sets the log level for the whole run. It is still read: when both are given, the one that differs from the default 1 wins, input first. Its effect on the molecular-orbital table after each SCF is:

Value	Effect
0	No molecular-orbital table.
1	Orbital energies, without coefficients, after a converged SCF (the default).
2 and above	Orbital energies and coefficients, also when the SCF did not converge.

The orbital table is written after every SCF, and a dynamics run calls the SCF at least once per step, so at the default it is repeated for every step of the trajectory: a 100-step QM/MM surface-hopping run of an 18-atom QM region wrote 405 tables and 83 MB of log, in which the 101 lines that report the dynamics are impossible to find. runtype = md and namd therefore default this keyword to 0 unless input.verbose or scf.verbose is set to a value other than 1; write verbose = 2 in the deck to get the tables back for a trajectory.

Only the log is affected. The orbitals of any frame remain available from the Molden file, the restart record and the trajectory file, and the setting does not change any computed quantity.

TRAH Keywords

TRAH is the trust-region augmented Hessian SCF converger. It is implemented natively; the external OpenTrustRegion (OpenTRAH) backend was removed.

trh_impl

Canonical input call: scf(trh_impl=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	auto
Accepted	auto, native
Used by	TRAH implementation selection

Selects the TRAH implementation. Both accepted values resolve to the native trust-region augmented-Hessian solver, which is the only implementation.

otr, which selected the external OpenTrustRegion backend, is no longer accepted: the backend was removed and an input requesting it now fails with a ValueError naming the accepted values, rather than silently running the native solver instead.

trh_stab

Canonical input call: scf(trh_stab=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	False
Used by	TRAH stability mode

Enables TRAH stability behavior.

trh_ls

Canonical input call: scf(trh_ls=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	boolean
Default	False
Used by	TRAH line search

Enables line search inside TRAH.

trh_sub_solver

Canonical input call: scf(trh_sub_solver=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	davidson
Used by	TRAH micro-iteration solver

Selects the subsystem solver used by TRAH.

trh_nrtv

Canonical input call: scf(trh_nrtv=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	1
Used by	TRAH random trial vectors

Number of random trial vectors used in the TRAH subsystem.

trh_r0

Canonical input call: scf(trh_r0=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.4
Used by	TRAH trust radius

Initial TRAH trust radius.

trh_jd_start

Canonical input call: scf(trh_jd_start=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	30
Used by	TRAH Jacobi-Davidson switch

Iteration threshold for the Jacobi-Davidson path in TRAH.

trh_nmic

Canonical input call: scf(trh_nmic=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	integer
Default	50
Used by	TRAH micro-iterations

Maximum number of TRAH micro-iterations.

trh_gred

Canonical input call: scf(trh_gred=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.001
Used by	TRAH global reduction

Global reduction factor for the TRAH microproblem.

trh_lred

Canonical input call: scf(trh_lred=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	0.0001
Used by	TRAH local reduction

Local reduction factor for the TRAH microproblem.

xc_c2f

Canonical input call: scf(xc_c2f=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	auto (follows perf)
Values	on, off, auto
Used by	DFT SCF — coarse-to-fine XC grid during descent

Use a coarse XC grid during the SCF descent and the full grid in the convergence tail. Exact at convergence. See Performance.

xc_phi_cache

Canonical input call: scf(xc_phi_cache=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	auto (follows perf; no preset enables it)
Values	on, off, auto
Used by	DFT SCF — collocation-Φ cache

Cache the collocation Φ across SCF iterations (exact). Opt-in; on the CPU benchmark it was net-negative, so no preset enables it.

xc_incdft

Canonical input call: scf(xc_incdft=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	string
Default	auto (follows perf; no preset enables it)
Values	on, off, auto
Used by	DFT SCF — incremental DFT (experimental)

Incremental XC from density differences. Experimental; typically slows SCF convergence. Opt-in only.

grad_cutoff

Canonical input call: scf(grad_cutoff=VALUE); VALUE is a placeholder for the documented value.

Field	Value
Type	float
Default	auto (follows perf; 1.0d-10 baseline)
Used by	gradients — 2e-derivative Schwarz cutoff

Schwarz block cutoff for the 2e-derivative gradient build. Looser values trade a small gradient error for speed (1.0d-8 ≈ 5×10⁻⁷ a.u.).

Progressive Screening Keywords

Progressive screening is an opt-in SCF acceleration path. During the early descent it may use looser integral and XC-grid thresholds; once the DIIS error falls below pscreen_tight, it returns to the normal converged thresholds. No performance preset enables it automatically.

pscreen, pscreen_k, pscreen_cap, pscreen_tight

Keyword	Type	Default	Meaning
pscreen	boolean	False	Enable progressive integral/grid screening.
pscreen_k	float	1.0e-2	Safety factor in the iteration-dependent cutoff, approximately pscreen_k * DIIS error.
pscreen_cap	float	1.0e-8	Loosest permitted integral cutoff. Values looser than 1e-8 can risk changing the SCF state.
pscreen_tight	float	1.0e-4	DIIS-error threshold for returning to tight cutoffs; the effective value is at least 10 * scf.conv.

pscreen_xc_dcut, pscreen_xc_aocut, pscreen_grid_rad, pscreen_grid_ang

Keyword	Type	Default	Meaning
pscreen_xc_dcut	float	0.0	Loose XC density cutoff during descent; zero disables this ramp.
pscreen_xc_aocut	float	0.0	Loose XC AO-pruning threshold during descent; zero disables it.
pscreen_grid_rad	integer	0	Coarse radial-grid size during descent; both grid sizes must be positive to enable this progressive-screening override.
pscreen_grid_ang	integer	0	Coarse angular-grid size during descent; zero disables this override, independent of the separate xc_c2f schedule.

Keep pscreen_tight safely above the final SCF convergence threshold so the calculation reaches the normal integral and grid accuracy before convergence.

Scientific references

HF and density functional theory; SCF convergence and response solvers.