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=True, write_xyz_file=True, write_population_file=True, 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, num_threads=None, dispersion=None, solvent=None, 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, 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', 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) – Emit {output}.molden at the converged geometry. Default True.

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

• 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) dispersion correction. Accepts:

  • None (default) – no dispersion.

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

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

• 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 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_population_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['DLPNOCCSDPilotOptions'])

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

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

• kpoints (object)

• dos_kmesh (object)

• jk_method (object)

• bz_integration (object)

• cutoff_ha (object)

Return type:

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