Keyword index¶

Common SCF and job option keywords in vibe-qc, with their default values. These options live on the per-method option objects (RHFOptions, RKSOptions, UHFOptions, UKSOptions, and their periodic counterparts PeriodicRHFOptions and PeriodicKSOptions), which you pass to a run via rhf_options=, rks_options=, ks_options=, and so on. The defaults below are the values a freshly constructed options object carries; this page is the flat lookup, and each section links the topic page with the physics.

Convergence and tolerances¶

Keyword	Default	Meaning
`max_iter`	`100`	Maximum SCF iterations.
`conv_tol_energy`	`1e-8`	SCF energy-change convergence threshold (Hartree).
`conv_tol_grad`	`1e-6`	Orbital-gradient (DIIS-error) convergence threshold.

See scf_convergence.

SCF acceleration and damping¶

Keyword	Default	Meaning
`scf_accelerator`	`EDIIS_DIIS` (molecular + periodic)	Extrapolation scheme; one of `DIIS`, `EDIIS`, `EDIIS_DIIS`, `ADIIS`, `ADIIS_DIIS`, `KDIIS`, `R_CDIIS`, `AD_CDIIS`.
`use_diis`	`True`	Enable DIIS extrapolation.
`diis_start_iter`	`2`	Iteration at which DIIS begins.
`diis_subspace_size`	`8`	Number of stored DIIS vectors.
`ediis_diis_switch_threshold`	`0.1`	DIIS-error at which EDIIS hands over to plain DIIS.
`diis_restart_tau`	`1e-4`	R_CDIIS restart parameter τ ∈ (0,1) (Chupin et al. 2021); smaller ⇒ deeper history.
`diis_adaptive_delta`	`1e-4`	AD_CDIIS depth parameter δ > 0 (Chupin et al. 2021); smaller ⇒ deeper history.
`damping`	`0.5`	Static density/Fock damping fraction.
`dynamic_damping`	`True` (molecular + periodic)	Adjust the damping factor automatically (ORCA/CRYSTAL-style; default v0.15.x).
`dynamic_damping_min` / `_max`	`0.0` / `0.95`	Bounds for dynamic damping.
`fock_mixing`	`0.0`	CRYSTAL-style static Fock mixing (FMIXING).
`level_shift`	`0.0`	Saunders-Hillier virtual-orbital level shift (Hartree). Molecular + periodic.
`level_shift_warmup_cycles`	`-1`	Auto-reducing shift warm-up: `-1` auto (shift a few startup cycles then release), `0` persistent, `N` explicit length. Molecular + periodic.
`level_shift_schedule`	`[]`	Explicit per-iteration shift curve (CRYSTAL `LEVSHIFT B IRESET`); supersedes `level_shift` + warm-up. Lower a `LevelShiftSchedule` via `.apply_to(opts)`. Molecular + periodic.

See scf_convergence.

Second-order and Newton methods¶

Each is off (0.0) by default and turns on when the DIIS error drops below the given threshold.

Keyword	Default	Meaning
`newton_threshold`	`0.0` (off)	Switch to full-Hessian Newton below this DIIS error.
`soscf_threshold`	`0.0` (off)	Opt-in: switch to the second-order SOSCF (L-BFGS quasi-Newton) finalizer below this error norm; `0.0` disables.
`trah_threshold`	`0.0` (off)	Switch to trust-region augmented-Hessian (TRAH).
`quadratic_fallback_iter`	`0` (off)	Iteration at which to trigger the quadratic fallback.

Iterative diagonalization (Davidson)¶

Keyword	Default	Meaning
`use_davidson`	`False`	Replace full diagonalization with blocked Davidson.
`davidson_min_dim`	`100`	Minimum AO basis size to activate Davidson.
`davidson`	`DavidsonOptions()`	Per-knob Davidson control.
`solver`	`"dense"`	Diagonalization keyword: `"dense"`, `"davidson"`, or `"lobpcg"`.

Initial guess¶

Keyword	Default	Meaning
`initial_guess`	`PATOM` (molecular); `AUTO` (periodic)	Starting density; one of `AUTO`, `HCORE`, `SAD`, `SAP`, `PATOM`, `HUECKEL` (`HUCKEL` alias), `MINAO`, `READ`, or molecular-only `FRAGMO`.
`read_path`	`''`	File (`.qvf` / `.molden`) to read orbitals from, for `initial_guess=READ`.

See initial_guess.

Fock-build strategy¶

Keyword	Default	Meaning
`scf_mode`	`AUTO`	`AUTO`, `CONVENTIONAL` (in-core), or `DIRECT` (on-the-fly, screened).
`scf_mode_auto_threshold`	`140`	Basis size above which `AUTO` selects `DIRECT`.
`density_fit`	`False`	Use RI / density fitting for the Coulomb (J) build.
`cosx`	`False`	Use COSX-K inside the density-fitting route. `run_job(cosx=True)` enables DF automatically; low-level option objects must also set `density_fit=True`.
`schwarz_threshold`	`1e-10`	Schwarz integral-screening threshold.
`schwarz_threshold_loose`	`1e-7`	Early-iteration Schwarz threshold; set no larger than `schwarz_threshold` to disable loose screening.
`schwarz_threshold_tighten_at`	`1e-3`	SCF gradient norm below which direct SCF switches to `schwarz_threshold`.
`incremental_fock`	`True`	Build the Fock matrix incrementally between iterations on the direct path.
`incremental_fock_reset_freq`	`8`	Full direct-Fock rebuild interval used to bound incremental drift.

See scf_modes and density_fitting.

Basis, auxiliary, and ECP¶

Keyword	Default	Meaning
`aux_basis`	`''`	Auxiliary fitting-basis label. `run_job` auto-selects one for DF/COSX when possible; low-level `run_rhf` / `run_rks` / `run_uhf` / `run_uks` require an explicit value.
`ecp_library`	`''`	Effective-core-potential library name.
`ecp_centers`	`[]`	Per-center ECP assignments.
`linear_dep_threshold`	`1e-7`	Overlap-eigenvalue cutoff for linear-dependence filtering.

See basis_sets, ecp, linear_dependence.

DFT (RKS / UKS)¶

Keyword	Default	Meaning
`functional`	`'LDA'`	XC functional: a libxc name or a weighted-sum specification.
`grid`	(medium grid)	XC quadrature grid; a `GridOptions` object (see below).

See functionals.

XC grid (`GridOptions`)¶

Keyword	Default	Meaning
`partition`	`Becke`	Atomic partitioning scheme.
`angular`	`ProductGaussLegendre`	Angular quadrature; `ProductGaussLegendre` or `Lebedev`.
`n_radial`	`75`	Radial quadrature points.
`n_theta` / `n_phi`	`17` / `36`	Product-grid angular points.
`lebedev_order`	`29`	Lebedev order (used when `angular=Lebedev`).
`becke_k`	`3`	Becke partition smoothing order.

Open-shell (UHF / UKS, and periodic)¶

Keyword	Default	Meaning
`atomic_spins`	`[]`	Per-atom broken-symmetry spin seed (the ATOMSPIN analogue).
`spinlock_mode`	`OFF`	Broken-symmetry hold mode for the spin pattern.
`spinlock_iterations`	`0`	Iterations to hold the spin pattern.
`spinlock_value`	`0`	The locked spin value.
`stability_check`	`True`	Molecular UHF/UKS: post-convergence internal stability analysis + corrective restart; implicit meta-GGA UKS checks skip until tau-dependent fxc is available (details).
`stability_tol`	`1e-4`	Instability threshold on the lowest orbital-rotation Hessian eigenvalue.
`stability_max_retries`	`3`	Rotate-and-reconverge escapes before reporting the instability unresolved.
`stability_davidson_max_iter`	`60`	Matvec cap per stability eigensolve (one J + two K builds each).

Periodic (`PeriodicRHFOptions` / `PeriodicKSOptions`)¶

The periodic option objects share the convergence, acceleration, damping, level-shift, initial-guess, and iterative-diagonalization controls above. They do not carry the molecular scf_mode, density-fitting, COSX, or direct-SCF screening fields; periodic J/K algorithms are selected by route instead. The periodic scf_accelerator default is EDIIS_DIIS, the same as molecular. Periodic jobs additionally expose:

Keyword	Default	Meaning
`jk_method`	`AUTO` (argument of `run_periodic_job`)	Coulomb route: `GDF`, `BIPOLE`, `GPW`, `GAPW`, `RSGDF`, and others. See choosing a periodic method.
`smearing_temperature`	`0.0`	Fermi-Dirac smearing temperature (Hartree); `0.0` is no smearing.
`use_periodic_becke`	`True` (KS)	Use the periodic Becke partition for the XC grid.
`becke_image_radius_bohr`	`10.0` (KS)	Image radius for the periodic Becke partition.
`lattice_opts`	(`LatticeSumOptions`)	Real-space cutoffs for the lattice sums (`cutoff_bohr`, `nuclear_cutoff_bohr`, …).
`bipole_cutoff_bohr`	`15.0` (argument of `run_periodic_job`, BIPOLE route)	Direct-lattice cutoff of the electronic BIPOLE Fock sums; raise until the reported Bloch-overlap fold drift is < 1e-4 (a drift ≥ 1e-2 refuses SCF).
`use_exchange_ewald_split`	`None` (auto)	Corrected Ewald exchange split (`K = K_SR + K_LR + G=0` term). Auto-ON for 3D BIPOLE runs at Γ and Monkhorst-Pack multi-k; `False` restores the legacy Γ-locality gauge.
`exchange_exxdiv`	`"ewald"`	Exact-exchange G=0 convention: `"ewald"` (probe-charge Madelung, PySCF-equivalent, already near the k-converged limit) or `"none"`. The two differ by exactly `½·N_e·ξ_M(BvK supercell)`; see from_crystal § Comparing total energies.
`ewald_precision`	`1e-8`	Truncation target of the real/reciprocal Ewald lattice sums (BIPOLE route).

See periodic_methods, smearing, multi_k_scf.

Enumerations¶

The values each option enum accepts (the default is marked):

InitialGuess: AUTO (periodic default), HCORE, SAD, SAP, PATOM (molecular default), HUECKEL (HUCKEL alias), MINAO, READ, FRAGMO (molecular only).
SCFAccelerator: DIIS, EDIIS, EDIIS_DIIS (molecular and periodic default), ADIIS, ADIIS_DIIS, KDIIS, R_CDIIS, AD_CDIIS (adaptive-depth CDIIS, Chupin et al. 2021).
SCFMode: AUTO (default), CONVENTIONAL, DIRECT.
PeriodicJKMethod: AUTO (default), GDF, AICCM2026DEV_B, BIPOLE, GPW, GAPW, RSGDF, RIJCOSX, FFT_POISSON, CFMM, DIRECT.
CoulombMethod: EWALD_3D, DIRECT_TRUNCATED, NEUTRALIZED_1D, SLAB_EWALD_2D.
SpinlockMode: OFF (default), and the broken-symmetry hold modes.