vibeqc.run_job

vibeqc.run_job(molecule, *, basis=None, fetch_from_bse=None, method='auto', functional=None, initial_guess=None, orbital_optimizer=None, opentrustregion_options=None, citype=None, triples=None, output='output', name_molecule=True, optimize=False, write_molden_file=None, write_xyz_file=True, write_population_file=None, iao_analysis=False, iao_bond_threshold=0.05, write_cube=False, cube_spacing=0.2, cube_padding=4.0, citations=True, dry_run=False, fmax=0.05, max_opt_steps=200, optimizer_backend='auto', geom_opt=None, geom_coords='cartesian', geom_target='minimum', geom_hessian_init='diagonal', geom_hessian_update='none', geom_line_search='backtracking', geom_conv_gmax=None, geom_freeze=None, geom_opt_options=None, geom_restart=None, geom_checkpoint=None, memory_override=False, memory_budget_bytes=None, num_threads=None, dispersion=None, solvent=None, cosmors=None, density_fit=None, aux_basis=None, cosx=False, integral_engine=None, coulomb=None, exchange=None, symmetry_reduction=None, grid_level='orca-defgrid3', record_hostname=True, rhf_options=None, uhf_options=None, rks_options=None, uks_options=None, rohf_options=None, roks_options=None, cisd_options=None, cc3_options=None, ccsdt_options=None, selected_ci_options=None, dmrg_options=None, v2rdm_options=None, transcorrelated_options=None, casci_options=None, caspt2_options=None, nevpt2_options=None, casscf_options=None, ccsd_options=None, ccsd_reference='uhf', mp2_reference='uhf', mp2_options=None, ump2_options=None, dlpno_options=None, dlpno_ccsd_options=None, frozen_core=None, dlpno_thresholds=None, active_space=None, cas_reference=None, mlip_options=None, ccm_options=None, read_from=None, fragments=None, progress=None, verbose=None, use_logging=False, perf_log=None, structured_log=False, crash_dump=True, output_qvf=True, trexio=False, trexio_backend='hdf5', checkpoint_qvf=None, checkpoint_every=0, qtaim=False, localize=None, tddft=False, tddft_n_states=5, tddft_type='tda', tddft_gradient=False, tddft_spectrum=False, tddft_molden=False, nto=False, hessian=False, hessian_frozen_indices=None, thermo_options=None, atomization=False, dft_plus_u=None, nddo=False, solver='dense', smearing_temperature=0.0, smearing_method='fermi-dirac', kpoints=None, dos_kmesh=None, jk_method=None, bz_integration=None, cutoff_ha=None)

Run a vibe-qc SCF job and write the standard output files.

Parameters:

• molecule (Molecule) – The Molecule describing the system (bohr coordinates).

• basis (Optional[str]) – libint-recognized basis-set name.

• fetch_from_bse (Optional[bool]) – When true, a basis name the bundled library does not carry is rendered from the Basis Set Exchange into the per-user cache and made resolvable for this process; see vibeqc.basis_fetch. Needs the optional [bse] extra. None (the default) consults $VIBEQC_FETCH_BSE; with neither, an unbundled name refuses exactly as before. A bundled name is unaffected, and a bundled basis that is merely missing one of the molecule’s elements is refused by the coverage guard rather than patched from BSE.

• method (Method) –

  "rhf", "uhf", "rks", "uks", "auto", "ccsd", "ccsd(t)", "cc3", "ccsdt", "cc2", "bccd", "bccd(t)", "qcisd", or "qcisd(t)". CC2 and the coupled-pair/QCI variants require a closed-shell reference; CCSD picks restricted vs unrestricted from molecule.multiplicity. CC3 iterates singles and doubles with approximate triples; CCSDT is the dense full iterative singles/doubles/triples solver. CC3 requires a closed-shell RHF reference.

  The double hybrids "b2plyp", "dsd-pbep86", "revdsd-pbep86" and "pwpb95" are methods here, not functionals: each names a hybrid SCF step plus a scaled MP2 correction on its orbitals, and run_job hands the pair to vibeqc.run_double_hybrid(), returning a DoubleHybridResult. Open shell runs a spin-pure ROKS SCF with a semicanonical RI-ROHF-MP2 doubles-only correction. The route carries the basis, grid, density-fitting, dispersion and output keywords and refuses the rest, so a feature the dispatcher lacks cannot be dropped silently; of mp2_options it reads only density_fit and aux_basis and refuses any other field set away from its default. method="rks" with a double-hybrid functional still raises: that asks for the SCF half alone, which is not the method it names.

• functional (Optional[str]) – XC functional for RKS / UKS (e.g. "PBE", "B3LYP"). Ignored for HF, and redundant for a double-hybrid method (which already names its functional); a conflicting pair raises.

• initial_guess (Optional[object]) – High-level SCF initial-guess selector for molecular RHF/UHF/RKS/UKS and their post-SCF reference SCFs. Accepts vibeqc.InitialGuess or spellings such as "auto", "sad", "sap", "patom", "hcore", "huckel", "minao", "read", and "fragmo".

• citype (Any) – AutoCI-style selector for single-reference CI/CC methods. Supported now: "cisd", "ccsd", "ccsd(t)", "cc3", "ccsdt", "bccd", "bccd(t)", "cc2", "ccd", "lccd", "lccsd", "cepa(0)"..``”cepa(3)”, ``"qcisd", and "qcisd(t)" (the Brueckner/coupled-pair/QCI variants require a closed-shell RHF reference). CC3 also requires a closed-shell RHF reference.

• cisd_options (Optional[CISDOptions]) – Optional vibeqc.CISDOptions controlling the high-level CISD route: max_excitation (2 for CISD, 1 for CIS), nroots, and max_det.

• cc3_options (Optional[CC3Options]) – Optional vibeqc.CC3Options controlling CC3 convergence thresholds, DIIS history, iteration limit, and frozen-core count. n_frozen_core=None uses the chemical-core default in run_job().

• ccsdt_options (Optional[CCSDTOptions]) – Optional vibeqc.CCSDTOptions controlling the full iterative CCSDT convergence thresholds, DIIS history, iteration limit, and frozen-core count. n_frozen_core=None uses the chemical-core default in run_job().

• triples (Any) – CCSD perturbative-triples selector. Use "none" for plain CCSD, "(t)" for the standard Raghavachari correction, "[t]" (equivalently "+T(CCSD)") for the fourth-order bracket correction CCSD[T], or "A-CCSD(T)" for the closed-shell asymmetric/Lambda triples correction.

• ccsd_options (Optional['CCSDOptions']) – Optional vibeqc.CCSDOptions controlling canonical CCSD iteration thresholds, density-fitting settings, frozen-core count, and triples memory mode. In run_job the effective triples calculation is selected by method / triples so output labels and citations stay aligned.

• mp2_options (Optional[MP2Options]) – Optional vibeqc.MP2Options / vibeqc.UMP2Options for the native post-SCF MP2 step. mp2_options applies to closed-shell RMP2, ump2_options to open-shell UMP2. Set density_fit=True to run RI-MP2/RI-UMP2 through run_job; if aux_basis is empty, the per-zeta RI auxiliary basis is auto-detected when available.

• ump2_options (Optional[UMP2Options]) – Optional vibeqc.MP2Options / vibeqc.UMP2Options for the native post-SCF MP2 step. mp2_options applies to closed-shell RMP2, ump2_options to open-shell UMP2. Set density_fit=True to run RI-MP2/RI-UMP2 through run_job; if aux_basis is empty, the per-zeta RI auxiliary basis is auto-detected when available.

• frozen_core (object) – Uniform frozen-core selector for MP2, CCSD, and DLPNO MP2/CCSD routes. None (default), True, "published", or "chemical" use the ORCA 6.1 Table 2.69 published element-count convention; False or "all-electron" correlate every occupied orbital; a non-negative integer freezes exactly that many lowest-energy spatial orbitals. Do not combine this selector with an explicit route-option frozen-core count.

• dlpno_thresholds (object) – Named DLPNO cutoff set: "normal" (the default), "loose", or "tight". The Liakos NormalPNO triple is vibe-qc’s shared cross-route default. Each solver applies only cutoffs its algorithm consumes and reports unsupported or inactive components. A named selector cannot be combined with dlpno_options or dlpno_ccsd_options; use vibeqc.dlpno.options_from_dlpno_thresholds() for a preset plus explicit overrides.

• output (str | os.PathLike) – Path stem for the generated files.

• name_molecule (bool) – If True (default), print the IUPAC name of molecule to the .out header and live progress log. {output}.out always; also {output}.molden unless disabled; and {output}.traj when optimize=True.

• optimize (bool) – Run a BFGS geometry optimization first (via ASE), then the final SCF on the optimized geometry. The trajectory is written for animation (openable with ASE-aware viewers).

• write_molden_file (bool | None) – Emit {output}.molden at the converged geometry. None (the default) emits it when the selected route exposes a Gaussian AO wavefunction. Explicit True is a guarantee and fails before the calculation on an unsupported route; False disables it.

• iao_analysis (bool) – Opt in to molecular determinant IAO charges, spin populations and spin-resolved IAO-Wiberg bond orders. Independent of localization and QVF. The returned result exposes .iao_analysis; text goes to .out and the population text/JSON sidecars when enabled. Unsupported analyses carry an explicit unavailable reason and no physical zeros.

• iao_bond_threshold (float) – Nonnegative text display threshold (default 0.05); the stored dense IAO bond-order matrix is never thresholded.

• write_population_file (bool | None) – Emit {output}.population.{txt,json}. It follows the same capability-aware None / guaranteed True / disabled False contract as write_molden_file.

• trexio (bool | str | os.PathLike) – Also export the converged wavefunction as a TREXIO file (Posenitskiy et al. 2023; optional [trexio] extra). trexio=True writes {output}.trexio.h5 with the HDF5 back end, or {output}.trexio (a directory of per-group text files) with trexio_backend="text"; a path writes there instead. Written groups: metadata, nucleus, electron, basis, ao, mo, ao_1e_int, rdm, state and ecp when applied. Requires a route that exposes a Gaussian AO wavefunction (fails before calculation otherwise). See TREXIO wavefunction files.

• trexio_backend (str) – Also export the converged wavefunction as a TREXIO file (Posenitskiy et al. 2023; optional [trexio] extra). trexio=True writes {output}.trexio.h5 with the HDF5 back end, or {output}.trexio (a directory of per-group text files) with trexio_backend="text"; a path writes there instead. Written groups: metadata, nucleus, electron, basis, ao, mo, ao_1e_int, rdm, state and ecp when applied. Requires a route that exposes a Gaussian AO wavefunction (fails before calculation otherwise). See TREXIO wavefunction files.

• fmax (float) – Optimizer tolerance (eV/Å) and iteration limit. Ignored unless optimize=True. On the ASE, optimizer_backend="native" and "brent" backends an optimization that stops short of the tolerance ends the job: the .out says NOT CONVERGED with the final largest gradient component, the last geometry is written to the .xyz, the manifest is marked crashed, and a RuntimeError is raised (vibeqc.geomopt.GeomOptNotConvergedError for the native and Brent backends, which carries the last geometry as .system and the full outcome as .result). The final single point and frequencies do not run.

• max_opt_steps (int) – Optimizer tolerance (eV/Å) and iteration limit. Ignored unless optimize=True. On the ASE, optimizer_backend="native" and "brent" backends an optimization that stops short of the tolerance ends the job: the .out says NOT CONVERGED with the final largest gradient component, the last geometry is written to the .xyz, the manifest is marked crashed, and a RuntimeError is raised (vibeqc.geomopt.GeomOptNotConvergedError for the native and Brent backends, which carries the last geometry as .system and the full outcome as .result). The final single point and frequencies do not run.

• memory_override (bool) – If False (default), the driver estimates peak memory and aborts with InsufficientMemoryError when the estimate exceeds the machine’s available RAM. Set to True to proceed anyway – at the risk of swap-thrashing or a system freeze.

• memory_budget_bytes (Optional[int]) – Requested peak-memory budget in bytes for bounded correlated-method kernels. The effective value is capped by scheduler, cgroup, and host availability. None (default) uses that detected allocation. memory_override may bypass preflight admission, but it never disables an explicit execution budget.

• num_threads (Optional[int]) – If set, pin the OpenMP thread count for the duration of the calculation. None (default) leaves the current setting in place – which is usually “all cores” unless the environment variable OMP_NUM_THREADS is set or vibeqc.set_num_threads() was called earlier. The actual thread count used is recorded in the output log for reproducibility.

• dispersion (DispersionSpec) –

  Post-SCF D3(BJ) or D4 dispersion correction. Accepts:

  • None (default) – no dispersion.

  • True or "d3bj" – use D3-BJ params for the current DFT functional.

  • "d4" – use D4 parameters for the current functional through the optional dftd4 backend.

  • A functional name ("pbe", "b3lyp", …) – use its D3-BJ params (useful for method="rhf" + "hf" dispersion, or for overriding the SCF functional in the damping lookup).

  • A D3BJParams instance – used directly.

  The energy correction is written to the .out file, added to the returned object as e_dispersion / energy_total (the raw SCF .energy is preserved untouched), and, when optimize=True, added to the forces the optimizer sees. Routes through vibeqc.compute_d3bj() with backend="auto" – the reference dftd3 backend is used when installed, otherwise the D1a framework stub. See vibeqc.dispersion for details.

• solvent (object) –

  v0.9.0 CPCM / COSMO implicit solvation. Accepts:

  • None (default) – gas-phase SCF.

  • A preset name ("water", "dmso", "acetonitrile", "chloroform", "benzene", …) – looks up the static dielectric e from vibeqc.SOLVENT_PRESETS.

  • A numeric e (e.g. 78.39) – custom dielectric.

  • A dict ({"epsilon": 25.0, "variant": "cosmo", ...}) or a vibeqc.SolventModel instance for full control over cavity construction (Bondi radii, Lebedev order, switching width, max macro-iterations).

  Routes through vibeqc.run_cpcm_scf(); macro-iterates the apparent surface charge against the SCF density until ΔE_solv < 1e-6 Ha (typically 3-5 outer cycles). The total energy is the in-solvent value; the gas-phase reference is retained on result.solvent_result.e_gas. See Implicit solvation (CPCM / COSMO) for the full theory and the cavity / preset table.

• cosmors (Optional[object]) – A vibeqc.CosmoRSOptions requests a COSMO-RS solvation free energy (Klamt 1998; ideal gas at 1 bar to 1 mol/mol in the solvent) for the solute in the pure solvent whose sigma potential it carries. The solute runs as an ideal conductor (epsilon=inf) on the fine cavity at the parameterization’s radii; leave solvent unset and that model is built, or pass a compatible one. The solute’s method and basis must be the solvent potential’s, which is refused otherwise. Mean-field single points only (rhf/uhf/rks/uks, no optimization). The .out gets a ## COSMO-RS block and the result a cosmors attribute (vibeqc.CosmoRSResult).

• integral_engine (object) – Optional IntegralEngineOptions, CoulombBuildOptions and ExchangeBuildOptions for the experimental molecular engine route. With no keywords, the existing route is unchanged. Selected gas-phase RHF/UHF/RKS/UKS single points retain independent J/K choices through terminal confirmation, RKS READ retries, properties, citations and QVF. Omitted SCF options use HCORE; supplied options must choose HCORE or same-basis READ. Static and IAO properties and closed-shell localization retain the executed provider. Selected RHF/UHF exact/RI sources also support geom_opt with HCORE starts and the original auxiliary content recentered at each geometry and the final single point. See the MANTA manual for current limits.

• coulomb (object) – Optional IntegralEngineOptions, CoulombBuildOptions and ExchangeBuildOptions for the experimental molecular engine route. With no keywords, the existing route is unchanged. Selected gas-phase RHF/UHF/RKS/UKS single points retain independent J/K choices through terminal confirmation, RKS READ retries, properties, citations and QVF. Omitted SCF options use HCORE; supplied options must choose HCORE or same-basis READ. Static and IAO properties and closed-shell localization retain the executed provider. Selected RHF/UHF exact/RI sources also support geom_opt with HCORE starts and the original auxiliary content recentered at each geometry and the final single point. See the MANTA manual for current limits.

• exchange (object) – Optional IntegralEngineOptions, CoulombBuildOptions and ExchangeBuildOptions for the experimental molecular engine route. With no keywords, the existing route is unchanged. Selected gas-phase RHF/UHF/RKS/UKS single points retain independent J/K choices through terminal confirmation, RKS READ retries, properties, citations and QVF. Omitted SCF options use HCORE; supplied options must choose HCORE or same-basis READ. Static and IAO properties and closed-shell localization retain the executed provider. Selected RHF/UHF exact/RI sources also support geom_opt with HCORE starts and the original auxiliary content recentered at each geometry and the final single point. See the MANTA manual for current limits.

• density_fit (Optional[bool]) –

  Use density fitting (RI-J) for the Coulomb build and, together with cosx=True, the chain-of-spheres (COSX) exchange build (RIJCOSX). When True, the JK auxiliary basis is resolved from aux_basis or autodetected from the orbital basis name (e.g. "def2-svp" → "def2-svp-jk"). Honoured by every molecular mean-field reference: RHF, UHF, RKS, UKS, ROHF and ROKS (the last two through ROHFOptions / ROKSOptions, #361). Reduces SCF wall time 10–50× for larger basis sets and cuts CPCM peak memory by avoiding the in-core four-index ERI tensor path.

  Default None – not specified. The SCF then runs the four-index path (as the historical False default did) and every post-SCF method keeps its own documented default, which for coupled cluster is density fitting on (see CC2, CC3, CCSD, CCSDT, QCISD, and perturbative triples).

  An explicit True or False is a request about the whole job, not only the SCF: it selects the integral route for the coupled-cluster step too, so run_job(method="ccsd(t)", density_fit=False) runs conventional CCSD(T). This is the only way to reach the canonical route from a payload, which has no ccsd_options= surface. Passing both this kwarg and a ccsd_options= whose density_fit disagrees is an error rather than a silently-picked winner.

• aux_basis (Optional[str]) –

  Auxiliary basis name for density fitting. For the SCF layer this is the JK auxiliary (e.g. "def2-tzvp-jk"); when empty and density_fit=True, the matching per-zeta JKfit basis is autodetected from the orbital basis name. Ignored by the SCF when density_fit=False.

  The same kwarg also names the correlation auxiliary for every post-SCF route that uses one: canonical mp2/ump2, dlpno-mp2, dlpno-ccsd, and the ccsd/lccsd/… family when it runs density fitted. There it means the RI-fit basis (e.g. "cc-pvdz-ri"), not the JKfit; when empty, those routes autodetect from the orbital basis or read their own options object. An explicit value here and one on the route’s options object must agree – a contradiction raises rather than silently picking one.

• cosx (bool) – Enable chain-of-spheres exchange (COSX) together with density_fit=True (RIJCOSX). Semi-numerical exchange build on a quadrature grid; faster than RI-JK for large basis sets at the cost of a few μHa grid noise. Default False.

• grid_level (str) –

  DFT integration-grid resolution for RKS / UKS / ROKS (ignored for HF, semiempirical, and post-SCF methods). Accepts a string preset:

  • "orca-defgrid3" (DEFAULT) – Lebedev-302 with NWChem pruning + Stratmann partition, matches ORCA’s DefGrid3 to < 0.01 mHa for first-row systems. 75 radial shells.

  • "fine" – Lebedev-590 order-35 with 99 radial shells. Grid-converged benchmarks; ~20× the point count of the default.

  • "coarse" – Lebedev-194 order-23 with 50 radial shells. Rapid screening and geometry pre-optimization; ~0.5 mHa energy error relative to the default.

  • "legacy" – v0.15 default: product Gauss-Legendre 17×36, no pruning, Becke partition. Backward-compatible with published v0.15 results.

  • "skala" – vibe-qc’s pinned PySCF-2.14 level-3 atomic-grid parity profile for Microsoft SKALA-1.1.

  The preset is applied whenever the method’s RKS / UKS / ROKS options carry an untouched grid: no options object, an options object whose grid was never customised (RKSOptions() passed to set max_iter still runs on the documented grid, GitLab #663), or a ROKSOptions whose grid is None. A grid the caller customised in any field wins and grid_level leaves it alone. Pass grid_level="legacy" to reproduce v0.15 energies exactly; that is also the supported way to request the C++ construction defaults, which are indistinguishable from an untouched grid. The preset is written into the options object you pass, so the object records the grid that ran; reuse it in a later call and that grid counts as chosen, i.e. a different grid_level there is ignored (unless the recorded preset was "legacy", which is indistinguishable from an untouched grid and is replaced). Build a fresh options object per call, or set the grid yourself, when you need different grids from one script.

• record_hostname (bool) – If False, the per-job {output}.system manifest writes hostname = "<redacted>" instead of the live hostname. The VIBEQC_NO_HOSTNAME=1 environment variable does the same thing globally. Use it for public examples, paper artifacts, and shared reproductions so machine names do not leak. Other manifest fields (CPU model, OS, memory, library versions) are not redacted; the redaction is scoped to the hostname only.

• uks_options (Optional[UKSOptions]) – Optional override for the respective SCF options struct.

• read_from (Optional[object]) – Prior result object, .qvf path, or .molden path (including ORCA’s .molden.input suffix) for initial_guess="read"; rejected unless the resolved guess is READ.

• fragments (Optional[object]) – Fragment partition for initial_guess="fragmo"; same format as the direct SCF wrappers accept.

• casci_options (Optional[CASCIOptions]) – CASCI knobs for method="casci" (the active space itself comes from active_space=). CASCIOptions(nroots=N) requests N CI roots: result.energy stays the ground root, per-root energies land in result.root_energies (per-root <S^2> in result.root_s2) and the .out solver block prints the root table. Ignored by every other method – the SA-CASSCF root count is casscf_options.nroots, the MS-CASPT2 model-space size caspt2_options.nroots.

• progress (Union[bool, ProgressLogger, None]) –

  Live progress logger for long-running jobs. Default behavior is ON – the job emits a banner, per-stage milestones, and a final summary to stdout (line-flushed) so the canonical nohup python LiH.py > LiH.log 2>&1 & + tail -f LiH.log workflow shows progress in real time. The .out file is also line-buffered so tail -f output-LiH.out works without any extra setup.

  Pass progress=False to silence stdout (the .out file is still written normally – only the live mirror is suppressed). Pass a vibeqc.ProgressLogger instance for fully custom routing (tee to a persistent file, mute, thread one logger through nested calls).

  Set VIBEQC_LIVE_LOGGING=0 in the environment to disable live progress globally – useful for batch scripts that don’t want to edit every input file. The env var only takes effect when progress is left at its default (None); explicit progress=True / progress=False / a ProgressLogger instance always wins, so a debugging session can re-enable progress for one shell.

  Per-iteration progress for periodic SCFs (which run in Python) is streamed live through this same logger via the lower-level run_*_periodic_* entry points; molecular SCFs run in C++ and only emit a pre-SCF banner + post-SCF summary live, with the per-iteration trace landing in the .out when the SCF returns.

• verbose (Optional[int]) –

  Integer verbosity level (PySCF convention, 0..9, default 4). Each level is a strict superset of the one below, so bumping verbose only adds output:

  • 0 – silent (nothing live; .out is still written)

  • 1 – banner + warnings + final SCF summary only

  • 2 – add per-stage milestones + info() lines

  • 3 – add per-stage timing on stage exit

  • 4 – add per-iteration SCF rows (DEFAULT)

  • 5 – add inline RSS-memory snapshots

  • 6+ – phase-level wall-clock breakdown live (overlaps the post-mortem .perf log on purpose)

  Pass verbose=None (the default) to read the VIBEQC_VERBOSE env var; if unset, falls back to 4. Ignored when progress is a ProgressLogger instance – that logger’s own level wins.

• use_logging (bool) –

  If True, route progress through logging.getLogger("vibeqc.run_job") instead of bare stdout writes. Banner / stage milestones land at INFO; per-iteration SCF rows at DEBUG; warnings at WARNING. Composes naturally with stdlib handlers (RotatingFileHandler, syslog, dictConfig):

  import logging
  logging.basicConfig(level=logging.INFO)
  vq.run_job(..., use_logging=True)
  

  progress=False still wins as a hard kill switch – the verbose-level gate runs before the logging call, so a silent run stays silent regardless of the active logging config. Ignored when progress is a pre-built ProgressLogger instance.

• perf_log (Optional[Union[str, os.PathLike, bool]]) – Optional path (or True to use {output}.perf) to write a post-mortem performance / debug breakdown – phase-level wall + CPU times, memory snapshots, parallelism flags. The live progress= log shows progress during the run; the perf log shows where the time went afterwards. Off by default. Pass an explicit path, True to emit alongside {output}.out, or set the VIBEQC_PERFLOG=path env var (which wins when perf_log is left at None). See vibeqc.perf for the full instrumentation surface.

• structured_log (Union[bool, str, os.PathLike, None]) – Optional NDJSON (one-JSON-record-per-line) log capturing every SCF transition – banner, job_start, memory_estimate, per-iter rows, scf_converged, properties, job_end. Off by default. Pass True to emit {output}.scf.jsonl, a path-like to write there explicitly, or set the VIBEQC_STRUCTURED_LOG=path env var (which wins when structured_log is left at False). When neither is given and $VQ_WORKDIR is set (a vq job), the log is auto-enabled at {output}.scf.jsonl. The format is stable: events are append-only, fields are never renamed or removed. See vibeqc.structured_log for the full event catalog.

• crash_dump (Union[bool, str, os.PathLike, None]) – Write a snapshot to {output}.dump (TOML) plus binary attachments (.dump.density.npy, .dump.fock.npy, .dump.mo.npy) when the SCF fails ungracefully – raised exception (NaN, linear dependence, memory error). Default True: post-mortem reproducibility costs nothing on success and saves a re-run on failure. Pass False (or set VIBEQC_NO_CRASH_DUMP=1 in the environment) to disable. The dump is written alongside {output}.out in the standard output.* family – re-attach the .dump + .dump.density.npy to a bug report and the maintainer can reconstruct the failing state via vibeqc.load_dump(). See vibeqc.crash_dump for the dump format. The exception is always re-raised after the dump is written; crash_dump=True does not swallow failures.

• tddft (bool) – When True, compute TD-DFT vertical excitation energies via the Tamm-Dancoff approximation (TDA, default) or the full Casida linear-response formalism (tddft_type=”casida”). Requires a converged SCF that produces MO coefficients (RHF/RKS/UHF/UKS). An ROHF reference runs ROHF TDA/CIS over the doubly-occupied → virtual space only, labelled TDA-ROHF in the .out; tddft_type="casida" on ROHF and any tddft=True on ROKS are refused before the SCF with the missing capability named (#361).

• tddft_n_states (int) – Number of excited states to compute when tddft=True. Default 5.

• tddft_type (Literal['tda', 'casida']) – "tda" (Tamm-Dancoff, default) or "casida" (full Casida). Casida includes the B matrix and is the complete linear-response TD-DFT; TDA is faster, Hermitian, and usually within 0.1-0.3 eV of Casida for valence states.

• tddft_gradient (bool) – When True, compute the finite-difference nuclear gradient of the lowest excited state on the closed-shell RHF + CIS (TDA) surface, the one energy function wired into vibeqc.excited_gradient (state-tracked central differences, step 1e-3 Å), and write it to the .out labelled with that surface. Any other run (an RKS or open-shell reference, or tddft_type="casida") is refused before the calculation with the missing capability named (issue #570). Cost: ~6N additional SCF + CIS evaluations. Opt-in; not computed by default.

• tddft_n_states – Number of excited states to compute when tddft=True. Default 5.

• nto (bool) – When True (and tddft=True), compute Natural Transition Orbitals for each TD-DFT excited state and embed paired hole/particle NTOs into the QVF archive as wavefunction.gto sections with orbital_kind="natural". Requires output_qvf=True.

• hessian (bool) – When True, compute harmonic vibrational frequencies via finite-difference Hessian. Default False. Cost: ~6N SCF evals. Results printed to .out and embedded in QVF for vibe-view.

• orbital_optimizer (Optional[str])

• opentrustregion_options (Optional[object])

• write_xyz_file (bool)

• write_cube (Union[bool, str, int, list, tuple, None])

• cube_spacing (float)

• cube_padding (float)

• citations (bool)

• dry_run (bool)

• optimizer_backend (str)

• geom_opt (Optional[str])

• geom_coords (str)

• geom_target (str)

• geom_hessian_init (str)

• geom_hessian_update (str)

• geom_line_search (str)

• geom_conv_gmax (Optional[float])

• geom_freeze (Optional[List[int]])

• geom_opt_options (Optional[dict[str, Any]])

• geom_restart (Optional[str])

• geom_checkpoint (Optional[str])

• symmetry_reduction (object)

• rhf_options (Optional[RHFOptions])

• uhf_options (Optional[UHFOptions])

• rks_options (Optional[RKSOptions])

• uks_options

• rohf_options (Optional[ROHFOptions])

• roks_options (Optional[ROKSOptions])

• selected_ci_options (Optional[SelectedCIOptions])

• dmrg_options (Optional[DMRGOptions])

• v2rdm_options (Optional[V2RDMOptions])

• transcorrelated_options (Optional[TranscorrelatedOptions])

• caspt2_options (Optional[CASPT2Options])

• nevpt2_options (Optional[NEVPT2Options])

• casscf_options (Optional[CASSCFOptions])

• ccsd_reference (str)

• mp2_reference (str)

• dlpno_options (Optional['DLPNOMP2Options'])

• dlpno_ccsd_options (Optional[object])

• active_space (Optional[tuple[int, int]])

• cas_reference (Optional[str])

• mlip_options (Optional[MLIPOptions])

• ccm_options (Optional['CCMOptions'])

• output_qvf (bool)

• checkpoint_qvf (Optional[Union[str, os.PathLike]])

• checkpoint_every (int)

• qtaim (bool)

• localize (Union[bool, str, Sequence[str], None])

• tddft_spectrum (bool)

• tddft_molden (bool)

• hessian_frozen_indices (Optional[List[int]])

• thermo_options (Optional['ThermoOptions'])

• atomization (bool)

• dft_plus_u (Optional[List['HubbardSite']])

• nddo (bool)

• solver (str)

• smearing_temperature (float)

• smearing_method (str)

• kpoints (object)

• dos_kmesh (object)

• jk_method (object)

• bz_integration (object)

• cutoff_ha (object)

Returns:

• The SCF result object (RHFResult / UHFResult / RKSResult / UKSResult),

• or a DoubleHybridResult for a double-hybrid method.

Return type:

object