Python API reference¶

Autogenerated from the docstrings on the vibe-qc Python module. Fall back to the source for anything not yet documented inline.

Molecular¶

`vibeqc.Atom`
`vibeqc.Molecule`
`vibeqc.BasisSet`
`vibeqc.ShellInfo`
`vibeqc.from_xyz`	Parse a standard XYZ file (positions in Ångström) into a Molecule.
`vibeqc.RHFOptions`
`vibeqc.RHFResult`
`vibeqc.run_rhf`	Restricted Hartree-Fock SCF on a closed-shell molecule.
`vibeqc.UHFOptions`
`vibeqc.UHFResult`
`vibeqc.run_uhf`	Unrestricted Hartree-Fock SCF on an open-shell molecule.
`vibeqc.RKSOptions`
`vibeqc.RKSResult`
`vibeqc.run_rks`	Restricted Kohn-Sham SCF on a closed-shell molecule.
`vibeqc.UKSOptions`
`vibeqc.UKSResult`
`vibeqc.run_uks`	Unrestricted Kohn-Sham SCF on an open-shell molecule.
`vibeqc.MP2Result`
`vibeqc.run_mp2`
`vibeqc.UMP2Result`
`vibeqc.run_ump2`

Input / output workflow¶

High-level “run a job” driver plus external-format writers.

`vibeqc.run_job`	Run a vibe-qc SCF job and write the standard output files.
`vibeqc.write_molden`	Write geometry, basis, and molecular orbitals to a Molden-format file.
`vibeqc.write_orca_hess`	Write a vibe-qc `HessianResult` to an ORCA-format `.hess` file.
`vibeqc.write_xyz_trajectory`	Write a sequence of `Molecule` frames as a multi-XYZ trajectory file.
`vibeqc.write_opt_trajectory`	Write a geometry-optimization history as a multi-XYZ trajectory with per-step energies on the comment line.
`vibeqc.normal_mode_trajectory`	Generate a list of `Molecule` frames sampling one vibrational normal mode for animated visualization.
`vibeqc.format_scf_trace`	Return a multi-line string with a header, per-iteration lines and a summary.
`vibeqc.log_scf_trace`	Emit the SCF trace through the `logging` module.

The trajectory trio above (Phase M2) writes the multi-XYZ format that moltui, ASE, OVITO, Avogadro, and PyMOL all read directly:

:func:vibeqc.write_xyz_trajectory — generic multi-frame writer.
:func:vibeqc.write_opt_trajectory — geometry-optimization history with auto-formatted comment lines ("step N E = … |grad| = …"). Default extension .opt by ORCA-style convention; on-disk format is identical to a plain multi-XYZ.
:func:vibeqc.normal_mode_trajectory — discretise one vibrational mode into n_frames displaced geometries for an animated normal-mode movie. Pair with :func:~vibeqc.write_xyz_trajectory.

Integrals, basis, XC¶

`vibeqc.compute_overlap`
`vibeqc.compute_kinetic`
`vibeqc.compute_nuclear`
`vibeqc.compute_eri`
`vibeqc.compute_gradient`	RHF analytic nuclear gradient (Ha/bohr, per atom).
`vibeqc.compute_gradient_uhf`	UHF analytic nuclear gradient (Ha/bohr, per atom).
`vibeqc.compute_gradient_rks`	RKS analytic nuclear gradient (Ha/bohr, per atom).
`vibeqc.compute_gradient_uks`	UKS analytic nuclear gradient (Ha/bohr, per atom).
`vibeqc.Functional`
`vibeqc.XCKind`
`vibeqc.build_grid`
`vibeqc.Grid`
`vibeqc.GridOptions`
`vibeqc.evaluate_ao`
`vibeqc.evaluate_ao_with_gradient`

Periodic¶

`vibeqc.PeriodicSystem`
`vibeqc.LatticeCell`
`vibeqc.LatticeMatrixSet`
`vibeqc.LatticeSumOptions`
`vibeqc.CoulombMethod`
`vibeqc.BlochKMesh`
`vibeqc.BandDiag`
`vibeqc.direct_lattice_cells`
`vibeqc.bloch_sum`
`vibeqc.monkhorst_pack`	Build a legacy `BlochKMesh` Monkhorst-Pack mesh.
`vibeqc.diagonalize_bloch`
`vibeqc.compute_overlap_lattice`
`vibeqc.compute_kinetic_lattice`
`vibeqc.compute_nuclear_lattice`
`vibeqc.nuclear_repulsion_per_cell`
`vibeqc.compute_nuclear_erfc_lattice`
`vibeqc.EwaldOptions`
`vibeqc.ewald_point_charge_energy`
`vibeqc.ewald_nuclear_repulsion`
`vibeqc.build_jk_gamma_molecular_limit`
`vibeqc.build_fock_2e_real_space`
`vibeqc.build_xc_periodic`
`vibeqc.real_space_density_from_kpoints`
`vibeqc.PeriodicRHFOptions`
`vibeqc.PeriodicRHFResult`
`vibeqc.run_rhf_periodic_gamma`	Γ-only closed-shell RHF for a periodic system (molecular-limit regime).
`vibeqc.PeriodicSCFOptions`
`vibeqc.run_rhf_periodic`
`vibeqc.PeriodicKSOptions`
`vibeqc.PeriodicKSResult`
`vibeqc.run_rks_periodic`	Multi-k closed-shell periodic Kohn-Sham SCF (DIRECT_TRUNCATED).
`vibeqc.AtomicRadialGrid`	Per-atom radial × Lebedev quadrature grid.
`vibeqc.default_alpha_for_element`	Mura-Knowles radial scale `α` (bohr) for element `Z`.
`vibeqc.lebedev_supported_orders`	Return the Lebedev orders scipy.integrate.lebedev_rule supports.

The AtomicRadialGrid family (per-atom Mura-Knowles radial × Lebedev-Laikov angular quadrature) is the M3b-aug-A infrastructure for GAPW augmentation. Not yet wired into the SCF — see gapw.md for the user- facing surface and vibeqc.periodic_gapw_atomic_grid for the module-level entry.

Crystal / symmetry¶

`vibeqc.Crystal`
`vibeqc.SpaceGroup`
`vibeqc.SymmetryOp`
`vibeqc.IrreducibleKMesh`
`vibeqc.analyze_symmetry`
`vibeqc.attach_symmetry`
`vibeqc.to_primitive`
`vibeqc.irreducible_kpoints`
`vibeqc.read_poscar`	Parse a VASP 5 POSCAR/CONTCAR file into a `Crystal`.
`vibeqc.write_poscar`	Write a Crystal to VASP 5 POSCAR (Direct coordinates, Å lattice).
`vibeqc.spglib_version`

Properties¶

`vibeqc.mulliken_charges`	Mulliken atomic partial charges q_A = Z_A − Σ_{μ ∈ A} (P·S)_μμ.
`vibeqc.loewdin_charges`	Löwdin (symmetric orthogonalisation) atomic partial charges:
`vibeqc.mayer_bond_orders`	Mayer bond-order matrix, shape (n_atoms, n_atoms).
`vibeqc.dipole_moment`	Electric dipole moment of a converged SCF calculation.
`vibeqc.DipoleMoment`	Dipole moment components in atomic units (e·bohr), plus Debye.
`vibeqc.center_of_mass`	Center of mass (bohr).
`vibeqc.compute_dipole`
`vibeqc.DipoleIntegrals`

Live progress, runtime manifest, and perf log¶

Observability surface — defeats output buffering on long runs (v0.5.1), pins the runtime environment alongside every job (v0.5.1), writes a post-mortem perf breakdown when opted in (v0.5.2), exposes a verbosity knob plus a stdlib logging adapter (v0.5.3), writes a machine-readable NDJSON convergence log (v0.6), writes a crash dump on SCF failure (v0.6), and records the external-program validation boundary in the .system manifest.

run_job accepts verbose: int = None (PySCF-convention 0..9; None reads $VIBEQC_VERBOSE, default 4) and use_logging: bool = False (route emits through logging.getLogger("vibeqc.run_job") — banners + milestones land at INFO, per-iter SCF rows at DEBUG, warnings at WARNING). The same verbose= kwarg is threaded through every periodic SCF entry point (run_rhf_periodic_gamma_ewald3d, run_rks_periodic_multi_k_ewald3d, …) so direct callers of the lower-level drivers can dial verbosity without going through run_job. See docs/user_guide/output_files.md § “Verbosity” for the level table.

`vibeqc.ProgressLogger`	Per-stage progress emitter for long-running calculations.
`vibeqc.resolve_progress`	Normalize the `progress=` argument every SCF entry point takes.
`vibeqc.system_info`	Collect the runtime environment as a nested dict.
`vibeqc.write_system_manifest`	Write the per-job system manifest next to `out_path`.
`vibeqc.PerfTracker`	Accumulator for per-phase wall/CPU timings, per-iteration SCF rows, and memory snapshots over the course of a calculation.
`vibeqc.PerfScope`	Context manager that times its body and pushes the wall + CPU delta into the currently active `PerfTracker`.
`vibeqc.perf_log`	Activate a fresh `PerfTracker` for the duration of the block; write the formatted report to `path` on exit.
`vibeqc.active_tracker`	The currently active `PerfTracker`, or `None` if no `perf_log()` block is open.
`vibeqc.format_perf_report`	Render `tracker` as the on-disk perf report text.
`vibeqc.StructuredLog`	One-record-per-line NDJSON writer with line-flushed I/O.
`vibeqc.structured_log`	Activate a fresh `StructuredLog` for the duration of the block; close on exit.
`vibeqc.active_structured_log`	The currently active `StructuredLog`, or `None` if no `structured_log()` block is open.
`vibeqc.run_fingerprint`	A short hex digest summarizing a job's identifying inputs.
`vibeqc.dump_on_failure`	Write `{out_stem}.dump` (TOML) plus binary attachments capturing the last known SCF state.
`vibeqc.load_dump`	Parse a `.dump` TOML file and load its sibling `.npy` attachments.
`vibeqc.classify_failure`	Return a one-line `likely_cause` string for the dump's `[hint]` section.
`vibeqc.crash_dump_context`	Register a crash-dump stem for the duration of the block.

ProgressLogger is wired into every periodic SCF entry point (and into run_job); system_info() / write_system_manifest() are the public hooks for users driving the SCF drivers directly without run_job. perf_log() is the context-manager entry point for post-mortem perf logging, paired with PerfScope for instrumenting custom code. structured_log() is the v0.6 NDJSON entry point — one JSON record per SCF transition, format-stable, jq-friendly. dump_on_failure() / load_dump() are the v0.6 crash-dump pair: a snapshot on disk when an SCF fails ungracefully, round-trippable via load_dump() for bit-for-bit failure reproduction. See docs/user_guide/output_files.md for the user-facing walkthrough.

Memory budget¶

`vibeqc.MemoryEstimate`	Peak memory estimate for a calculation.
`vibeqc.InsufficientMemoryError`	Raised by `check_memory` when the estimate exceeds available RAM and the caller did not request an override.
`vibeqc.estimate_memory`	Peak memory estimate for `method`.
`vibeqc.check_memory`	Abort if `estimate.total_bytes > available` and `allow_exceed` is false.
`vibeqc.available_memory_bytes`	Best-effort available-RAM probe.
`vibeqc.format_memory_report`	One-stop formatter for the run_job output block.

Basis-set utilities¶

vibeqc.basis_crystal

CRYSTAL-format basis-set parser and NWChem/.g94 emitter.

Bands, DOS, plotting¶

`vibeqc.KPath`	A discretised k-path — sequence of k-points with cumulative arc length (for the x-axis when plotting) and labeled high-symmetry points (for the x-axis tick marks).
`vibeqc.BandStructure`	Eigenvalues at every k along a path.
`vibeqc.DensityOfStates`	Total density of states.
`vibeqc.kpath_from_segments`	Stitch a piecewise-linear k-path through high-symmetry points.
`vibeqc.band_structure`	Sample a real-space Fock matrix along a k-path.
`vibeqc.band_structure_hcore`	Non-interacting (Hcore) band structure: eigenvalues of T + V at every k-point.
`vibeqc.density_of_states`	Total DOS computed by Gaussian-broadening every eigenvalue of `F(k)` over `kmesh` onto an energy grid.
`vibeqc.density_of_states_hcore`	Non-interacting DOS for a system on a Monkhorst–Pack mesh.
`vibeqc.plot.band_structure_figure`	Draw a band-structure plot.
`vibeqc.plot.dos_figure`	Draw a density-of-states plot.
`vibeqc.plot.bands_dos_figure`	Combined band structure + DOS panel — the standard solid-state layout (bands on the left with shared y-axis to a horizontal DOS on the right).

Volumetric output¶

`vibeqc.CubeGrid`	Uniform axis-aligned grid in bohr.
`vibeqc.make_uniform_grid`	Wrap an axis-aligned box around the molecule with `padding` bohr of headroom and a cubic voxel of `spacing` bohr.
`vibeqc.write_cube_density`	Write the total electron density ρ(r) = ⟨D, χ⊗χ⟩ to a Gaussian cube file.
`vibeqc.write_cube_mo`	Write a single molecular orbital `φ_index(r)` to a cube file.
`vibeqc.write_cube_mos`	Write a stack of MOs in a single multi-value cube file.
`vibeqc.write_xsf_structure`	Write a structure-only XSF file (CRYSTAL block).
`vibeqc.write_xsf_volume`	Write a periodic XSF file with a single 3D scalar grid.
`vibeqc.write_bxsf`	Write a BXSF file (band XSF) for Fermi-surface visualization in XCrySDen.

SCF accelerators + initial guess¶

`vibeqc.SCFAccelerator`
`vibeqc.InitialGuess`
`vibeqc.ADIIS`
`vibeqc.EDIIS`
`vibeqc.SCFMode`
`vibeqc.NewtonOptions`
`vibeqc.SOSCFOptions`
`vibeqc.SmearingOptions`	Canonical user-facing smearing configuration.

Wavefunction methods (non-mean-field solvers)¶

The v0.9.0 vibeqc.solvers family: Full CI, Selected CI, DMRG, variational 2-RDM, and the transcorrelated Hamiltonian.

`vibeqc.Hamiltonian`	One- and two-electron integrals in an orthonormal spatial-orbital basis.
`vibeqc.solve_selected_ci`	One-shot Selected-CI solve.
`vibeqc.SelectedCIOptions`	Options for the Selected-CI solver.
`vibeqc.solve_dmrg`
`vibeqc.DMRGOptions`	Options for the DMRG solver.
`vibeqc.solve_v2rdm`	One-shot v2RDM solve.
`vibeqc.V2RDMOptions`	Options for the v2RDM solver.
`vibeqc.build_transcorrelated_hamiltonian`	Apply the transcorrelated similarity transformation to a Hamiltonian.
`vibeqc.TranscorrelatedOptions`	Options for the transcorrelated Hamiltonian builder.
`vibeqc.SolverResult`	Common result container for all non-mean-field solvers.
`vibeqc.solvers.generate_determinants`	Generate all determinants for `nalpha` α + `nbeta` β electrons in `norb` orbitals.
`vibeqc.solvers.build_hamiltonian_matrix_unrestricted`	Build the full CI Hamiltonian matrix in the unrestricted determinant basis.
`vibeqc.solvers.diagonal_matrix_element_unrestricted`	⟨D\|H\|D⟩ for an unrestricted determinant.
`vibeqc.get_hf_orbital_provider`	Run vibe-qc's RHF and return the MO coefficient matrix.
`vibeqc.build_hamiltonian_mo`	Build a `Hamiltonian` in the MO basis.
`vibeqc.solvers.transform_hamiltonian`	Transform a Hamiltonian into a new orthonormal basis given by `C`.

Composite methods (3c family) + double hybrids + range-separated hybrids¶

`vibeqc.run_double_hybrid`	Generic double-hybrid dispatcher.
`vibeqc.DoubleHybridResult`	Result of a double-hybrid run: the SCF (hybrid-DFT) result, the post-SCF MP2 correction result, optionally a dispersion correction, and the combined total energy.
`vibeqc.run_wb97x_d`	ωB97X-D (Chai & Head-Gordon, *Phys.
`vibeqc.WB97XDResult`	Result of an ωB97X-D run: the range-separated-hybrid SCF result, the Chai-Head-Gordon empirical dispersion correction, and the combined total energy.
`vibeqc.ShortRangeCorrection`	Canonical short-range bond (SRB) correction of the 3c stack.
`vibeqc.MP2Options`

Dispersion (D3 / D4 + counterpoise + EEQ)¶

`vibeqc.compute_d3bj`	Pairwise D3(BJ) dispersion energy (and optionally gradient).
`vibeqc.compute_d4`	D4 dispersion correction (Caldeweyher et al. 2019).
`vibeqc.compute_chg_dispersion`
`vibeqc.compute_gcp`	Geometric counterpoise correction (Kruse & Grimme 2012).
`vibeqc.eeq_charges`
`vibeqc.DispersionResult`
`vibeqc.D4Result`	Result of a `compute_d4()` call.
`vibeqc.GCPResult`	Return value of `compute_gcp()`.
`vibeqc.EEQResult`
`vibeqc.EEQOptions`
`vibeqc.PeriodicDispersionResult`	Per-unit-cell dispersion energy plus optional gradient.

Implicit solvation (CPCM / COSMO)¶

`vibeqc.CPCMResult`	Outcome of one apparent-surface-charge solve.
`vibeqc.SolventResult`	Outcome of a CPCM-coupled SCF run.

Geometry optimization + Hessian¶

`vibeqc.optimize_molecule`	Relax molecular geometry using analytic gradients + L-BFGS-B.
`vibeqc.MolecularOptimizeResult`	Container for molecular geometry optimization results.
`vibeqc.OptimizeResult`	Container for optimization results.
`vibeqc.HessianFDOptions`	Knobs for `compute_hessian_fd()`.
`vibeqc.HessianResult`	Output of `compute_hessian_fd()`.
`vibeqc.CPHFOptions`	Knobs for `cphf_solve_rhf()`.
`vibeqc.NEBResult`	Outcome of a `run_neb()` run.
`vibeqc.ScanResult`	Container for the output of `relaxed_scan()`.

Periodic SCF (full driver matrix)¶

The Γ-only entry points already appear under “Periodic” above. The multi-k drivers, the BIPOLE family, and the Ewald and GDF variants land here.

`vibeqc.run_rhf_periodic_gamma_gdf`	Run Γ-only closed-shell periodic RHF/RKS via native GDF.
`vibeqc.run_krhf_periodic_gdf`	Run closed-shell periodic HF / KS multi-k SCF via native GDF.
`vibeqc.run_krks_periodic_gdf`	Run closed-shell periodic KS-DFT multi-k SCF via native GDF.
`vibeqc.run_rhf_periodic_gamma_ewald3d`	Γ-point closed-shell periodic RHF SCF with Ewald-3D Coulomb.
`vibeqc.run_rks_periodic_gamma_ewald3d`	Γ-point closed-shell periodic Kohn-Sham SCF with Ewald-3D Coulomb.
`vibeqc.run_uhf_periodic_gamma_ewald3d`	Γ-point open-shell UHF SCF with the EWALD_3D Coulomb dispatch.
`vibeqc.run_uks_periodic_gamma_ewald3d`	Γ-point open-shell periodic Kohn-Sham SCF with Ewald-3D Coulomb.
`vibeqc.run_rhf_periodic_multi_k_ewald3d`	Multi-k closed-shell periodic RHF SCF with EWALD_3D Coulomb.
`vibeqc.run_rks_periodic_multi_k_ewald3d`	Multi-k closed-shell periodic RKS SCF with EWALD_3D Coulomb.
`vibeqc.run_uhf_periodic_multi_k_ewald3d`	Multi-k open-shell UHF SCF with EWALD_3D Coulomb.
`vibeqc.run_pbc_bipole_rhf`	Multi-k closed-shell RHF via the CRYSTAL-gauge BIPOLE scaffold.
`vibeqc.run_pbc_bipole_uhf`	Multi-k open-shell UHF via the CRYSTAL-gauge BIPOLE scaffold.
`vibeqc.run_pbc_bipole_rks`	Multi-k closed-shell RKS via the CRYSTAL-gauge BIPOLE scaffold.
`vibeqc.run_pbc_bipole_uks`	Multi-k open-shell UKS via the CRYSTAL-gauge BIPOLE scaffold.
`vibeqc.run_periodic_job`	Run a periodic SCF job and write the standard output files.
`vibeqc.PeriodicRHFGDFResult`	Result of `run_rhf_periodic_gamma_gdf()`.
`vibeqc.PeriodicRHFEwaldResult`	Result of `run_rhf_periodic_gamma_ewald3d()`.
`vibeqc.PeriodicRHFMultiKEwaldResult`	Result of `run_rhf_periodic_multi_k_ewald3d()`.
`vibeqc.PeriodicRKSEwaldResult`	Result of `run_rks_periodic_gamma_ewald3d()`.
`vibeqc.PeriodicRKSMultiKEwaldResult`	Result of `run_rks_periodic_multi_k_ewald3d()`.
`vibeqc.PeriodicUHFEwaldResult`	Result of `run_uhf_periodic_gamma_ewald3d()`.
`vibeqc.PeriodicUHFMultiKEwaldResult`	Result of `run_uhf_periodic_multi_k_ewald3d()`.
`vibeqc.PeriodicUKSEwaldResult`	Result of `run_uks_periodic_gamma_ewald3d()`.
`vibeqc.PeriodicUKSMultiKEwaldResult`	Result of `run_uks_periodic_multi_k_ewald3d()`.
`vibeqc.PeriodicKRHFGDFResult`	Result of `run_krhf_periodic_gdf()`.
`vibeqc.PeriodicKRKSGDFResult`	Result of `run_krks_periodic_gdf()`.
`vibeqc.PBCBipoleRHFResult`	Result of `run_pbc_bipole_rhf()`.
`vibeqc.PBCBipoleUHFResult`	Result of `run_pbc_bipole_uhf()`.
`vibeqc.PBCBipoleRKSResult`	Result of `run_pbc_bipole_rks()`.
`vibeqc.PBCBipoleUKSResult`	Result of `run_pbc_bipole_uks()`.
`vibeqc.PBCGDFResult`	SCF result from `run_pbc_gdf_rhf()`.

Periodic gradients + stress + properties¶

`vibeqc.compute_gradient_periodic_rhf_gamma`	Analytic Γ-only periodic RHF atomic gradient.
`vibeqc.compute_gradient_periodic_rks_gamma`	Analytic Γ-only periodic RKS atomic gradient (closed-shell DFT).
`vibeqc.compute_stress_tensor`	Force-based stress tensor from atomic gradients.
`vibeqc.hirshfeld_charges`	Classical Hirshfeld atomic partial charges from a converged SCF.
`vibeqc.HirshfeldResult`	Output of `hirshfeld_charges()`.

ECPs + auto-population¶

`vibeqc.ECPCenter`
`vibeqc.auto_ecp_centers`	Build `(ecp_centers, library_name)` from a Molecule + basis name.
`vibeqc.compute_ecp_matrix`	Compute the AO-basis ECP matrix V_ECP_{μν} = ⟨χ_μ\|V_ECP\|χ_ν⟩ via libecpint's built-in XML library (ecp10mdf, ecp28mdf, ecp46mdf, ecp60mdf, ecp78mdf, lanl2dz).

QVF output¶

`vibeqc.output.formats.qvf.write_qvf`	Write `{stem}.qvf`.
`vibeqc.output.formats.qvf.validate_qvf`	Validate a QVF against the canonical SSOT schema.
`vibeqc.output.formats.qvf.qvf_density_data`	Evaluate total electron density on a uniform grid and return a dict suitable for `write_qvf(..., volume_data=...)`.
`vibeqc.output.formats.qvf.qvf_mo_data`	Evaluate MO wavefunctions on a uniform grid and return a list suitable for `write_qvf(..., mo_data=...)`.

Thermodynamics¶

vibeqc.ThermoResult

Output of compute_thermochemistry().

`vibeqc.VIBEQC_VERSION`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`vibeqc.banner`	Return the full banner as a single string, no trailing newline.
`vibeqc.print_banner`	Print the banner to `file` (default: stdout).
`vibeqc.library_versions`	Return the version strings of vibe-qc itself and its native dependencies.
`vibeqc.libint_version`
`vibeqc.libxc_version`
`vibeqc.spglib_version`