IOP: fine-grained options

The public signatures (chk.new, scf, ints, …) stay focused on the common controls. The rare, low-level numerical knobs are collected into a single iop={...} dictionary — a cross-cutting channel inspired by Gaussian’s IOp, but with readable namespaced names and typed values instead of numeric IDs.

Setting IOP keys

Pass iop= on qc.chk.new(...), or overlay per calculation with mychk.with_iop({...}) (which returns a new checkpoint):

import qc
m = qc.chk.new(
    atom="O 0 0 0; H 0 0.76 0.59; H 0 -0.76 0.59",
    ao="def2-svp",
    iop={"ri.metric_cutoff": 1e-10, "integral.screen.schwarz_tol": 1e-12},
)

m2 = m.with_iop({"scf.conv_tol_grad": 1e-7})   # overlay, returns a new checkpoint
m2.scf(ref="r").run()

Keys are dotted <area>.<subsystem>.<knob> names validated against a central registry. Unknown keys are an error (with a suggestion), not silently ignored:

m.with_iop({"not.a.real.key": 1})
# ValueError: unknown iop key "not.a.real.key"

Discovering keys: qc.iop

The registry is introspectable — you never have to guess a key or its default:

qc.iop.list()                       # all 47 keys (a set of dotted names)
qc.iop.defaults()                   # {key: default_value} for every key
qc.iop.describe("scf.conv_tol_grad")
# {'type': 'float', 'default': 1e-06, 'min': 0.0, 'max': 1.0,
#  'consumer': 'scf', 'scientific': False,
#  'doc': 'Commutator-RMS convergence threshold (the SCF gradient tolerance).'}

describe(key) returns the value type, default, allowed range, which subsystem consumes it, and a one-line doc.

The key registry by area

There are 47 keys in 9 areas. The most commonly reached-for ones:

scf.* — SCF solver

key	meaning
scf.conv_tol_grad	commutator-RMS gradient convergence threshold (default 1e-6)
scf.diis.variant / .max_vectors / .start_cycle	DIIS flavor, subspace size, first cycle
scf.incremental / .incremental.reset	incremental Fock build on/off, reset period
scf.qc_start / scf.soscf_start	when the 2nd-order ladder / SOSCF engages
scf.qc.max_conventional / .max_nr / .full_linear	QC-family ladder controls
scf.trah.max_step, scf.yqc.stabilize_tol	TRAH / YQC tuning
scf.symmetrize_fock, scf.salc_cutoff, scf.orbital_ordering, scf.orthogonalization_cutoff	symmetry / orthogonalization
scf.adaptive_screening	adaptive integral screening in the SCF

integral.* — integral assembly & screening

key	meaning
integral.screen.schwarz_tol	Cauchy–Schwarz quartet screening tolerance (default 1e-12, loss-free)
integral.screen.density_tol / .nuclear_tol / .qqr / .qqr_extent_tau	density / nuclear / QQR screening
integral.precision	integral precision target
integral.disk.sparse_layout / .io_mode / .restart	out-of-core (4c-disk) layout, I/O, restart
integral.screen.disk_block_tol / .disk_int_tol	disk-backend drop tolerances
integral.incore.* (k_kernel, rank_balance, s4_max_gb, screened_fill)	incore-4c tuning

ri.* — RI / density fitting

key	meaning
ri.metric_cutoff	RI metric eigenvalue cutoff (default 1e-10)
ri.ram.kdist	ri-ram store-B K distribution (p-transpose / mu-stream)
ri.recomp.occ_batch / .kcomm / .resort_max_mb	ri-recomp occ-batching, exchange comm, resort budget
ri.store.sparse	sparse store-B

lct.* — correlation (RI-MP2)

key	meaning
lct.frozen_core	freeze core orbitals in the correlation sum
lct.rohf_mp2	ROHF-MP2 convention ("pyscf" / "qcrs")
lct.rimp2_fp32	single-precision RI-MP2
lct.laplace_points	Laplace quadrature points (SOS-MP2)

Other areas

key	meaning
guess.gwh.scale	the GWH guess scaling factor
pcm.discretization	PCM cavity discretization
parallel.strict	oversubscription policy (True = error, False = warn)
log.timing	emit timing spans

For the exact default, type, and range of any key, call qc.iop.describe(key). The registry is the single source of truth (crates/qc-workflow/src/iop.rs); this list mirrors it.

Which controls are IOP vs public kwargs

Some knobs migrated from public keyword arguments to IOP keys to keep the main signatures focused — e.g. scf.conv_tol_grad, scf.symmetrize_fock, scf.salc_cutoff, scf.orbital_ordering, integral.screen.nuclear_tol, integral.precision are IOP keys, read from the checkpoint iop by scf(...) / ints(...). The everyday controls (ref, xc, grid, conv_tol, algorithm, pcm, …) stay as direct keyword arguments (the SCF chapter).