vibeqc.run_job

vibeqc.run_job(molecule, *, basis, method='auto', functional=None, output='output', optimize=False, write_molden_file=True, fmax=0.05, max_opt_steps=200, memory_override=False, num_threads=None, dispersion=None, record_hostname=True, rhf_options=None, uhf_options=None, rks_options=None, uks_options=None, progress=None, verbose=None, use_logging=False, perf_log=None, structured_log=False, crash_dump=True)

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

Parameters:

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

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

• method (Literal['rhf', 'rks', 'uhf', 'uks', 'auto']) – "rhf", "uhf", "rks", "uks", or "auto" (picks restricted vs unrestricted from molecule.multiplicity and switches between HF/KS based on whether functional is set).

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

• output (str | 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 (int | None) – 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 (object | None) –

  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.

• 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 (vibeqc._vibeqc_core.UKSOptions | None) – Optional override for the respective SCF options struct.

• progress (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 (int | None) –

  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 (str | PathLike | bool | None) – 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 (bool | str | 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 (bool | str | 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.

• rhf_options (vibeqc._vibeqc_core.RHFOptions | None)

• uhf_options (vibeqc._vibeqc_core.UHFOptions | None)

• rks_options (vibeqc._vibeqc_core.RKSOptions | None)

• uks_options

Return type:

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