vibeqc.run_job

vibeqc.run_job(molecule, *, basis=None, method='auto', functional=None, output='output', 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', 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, selected_ci_options=None, dmrg_options=None, v2rdm_options=None, transcorrelated_options=None, active_space=None, progress=None, verbose=None, use_logging=False, perf_log=None, structured_log=False, crash_dump=True, output_qvf=False, hessian=False, dft_plus_u=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", or "ccsd(t)" (picks restricted vs unrestricted from molecule.multiplicity and switches between HF/KS based on whether functional is set).

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

• output (str | os.PathLike) – Path stem for the generated files. {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 ε from vibeqc.SOLVENT_PRESETS.

  • A numeric ε (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 — engineering’s bundled docs runs use the env var so example outputs in docs/_static/examples/ don’t leak machine names. 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.

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

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

• rhf_options (Optional[RHFOptions])

• uhf_options (Optional[UHFOptions])

• rks_options (Optional[RKSOptions])

• uks_options

• selected_ci_options (Optional[SelectedCIOptions])

• dmrg_options (Optional[DMRGOptions])

• v2rdm_options (Optional[V2RDMOptions])

• transcorrelated_options (Optional[TranscorrelatedOptions])

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

• output_qvf (bool)

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

Return type:

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