vibeqc.run_job

vibeqc.run_job(molecule, *, basis=None, method='auto', functional=None, initial_guess=None, citype=None, triples=None, output='output', name_molecule=True, optimize=False, write_molden_file=None, write_xyz_file=True, write_population_file=None, 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, density_fit=None, aux_basis=None, cosx=False, 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, 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, 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.

• 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.

• functional (Optional[str]) – XC functional for RKS / UKS (e.g. "PBE", "B3LYP"). Ignored for HF.

• 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 "sad", "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.

• 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.

• 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.

• fmax (float) – Optimizer tolerance (eV/Å) and iteration limit. Ignored unless optimize=True.

• max_opt_steps (int) – Optimizer tolerance (eV/Å) and iteration limit. Ignored unless optimize=True.

• 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.

• 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"). 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: 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 (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.

  The grid is applied only when rks_options / uks_options are not explicitly provided. When they are, their grid settings (if any) win. Pass grid_level="legacy" to reproduce v0.15 energies exactly.

• 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). 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).

• 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 finite-difference excited-state nuclear gradients for the lowest TD-DFT state. Cost: ~6N additional SCF evaluations per state. Writes the gradient to the .out file. 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.

• 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])

• 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)

Return type:

The SCF result object (RHFResult / UHFResult / RKSResult / UKSResult).