vibeqc.output.formats.qvf.write_qvf

vibeqc.output.formats.qvf.write_qvf(stem, plan, *, compression=8, volume_dtype='float32', **context)

Write {stem}.qvf.

Parameters:

• stem (PathLike | str) – Path stem; .qvf suffix is appended.

• plan (OutputPlan) – OutputPlan declaring what artefacts are expected.

• compression (int) – zipfile.ZIP_DEFLATED (default), zipfile.ZIP_STORED, or the zstd constant if zipfile-zstd is importable.

• volume_dtype (str) – "float32" (default) or "float64" for volumetric grids.

• **context (Any) –

  Data objects the section writers need. Typical keys:

  • molecule / system — Molecule or PeriodicSystem

  • result — converged SCF result object

  • basis — BasisSet

  • population_summary — PopulationSummary

  • hessian_result — HessianResult

  • band_structure — BandStructure

  • trajectory_frames — list of Molecule

  • trajectory_energies — list of float (Hartree)

  • trajectory_rms_grad — list of float (optional)

  • bibtex_content — str, the full BibTeX file body

  • volume_data — dict of {label: (data_3d, origin, span)}

  • mo_data — list of dicts with keys label, data, origin, span, band_index, energy_eh, occupation, spin, component

  • spin_data — dict of {label: (data_3d, origin, span)}

  • elf_data — dict of {label: (data_3d, origin, span)}

  • generic_volume_data — dict of {label: (data_3d, origin, span)} for volume.generic (escape hatch for any scalar field that doesn’t fit density/orbital/spin/elf/difference)

  • potential_data — dict of {label: (data_3d, origin, span)} for volume.potential (electrostatic potential grid; same member structure as volume.density, QVF spec § 4.10)

  • rdg_data — dict of {label: (data_3d, origin, span)} for volume.rdg (reduced density gradient for NCI analysis; same member structure, QVF spec § 4.11)

  • diff_data — dict of {label: spec} for difference density (e.g. ρ(product) − ρ(reactant)). spec is either a 3-tuple (data_3d, origin, span) for an unannotated difference, or a dict with keys data, origin, span, and optionally operand_a (str, section id of minuend), operand_b (str, section id of subtrahend), description.

  • reaction_path — dict {frames, waypoints, energies?, reaction_coordinate?} for a self-contained reaction.path section. waypoints is a list of {frame_index, label, kind, energy_eh?} records where kind is one of "reactant" | "transition_state" | "intermediate" | "product" | "point".

  • reaction_waypoints — dict {trajectory_ref, waypoints, reaction_coordinate?} for a lightweight reaction.waypoints annotation over an already-emitted trajectory section. trajectory_ref must name a trajectory section emitted in the same archive; the writer raises if it doesn’t resolve.

  • viewer_defaults — dict written verbatim to the manifest root. Recognised keys: auto_open (list of section ids), per-section render hints, and bookmarks (ordered list of {name, camera} records using the VTK camera model).

  • thermochemistry_data — dict with keys zpve_eh, enthalpy_eh, entropy_cal_mol_k, gibbs_free_energy_eh, temperature_k, pressure_atm for a root thermochemistry field (QVF spec § 4.7).

  • dipole_moment_data — dict with keys total_debye, vector_debye (3-vector), origin (str) for a root dipole_moment field (QVF spec § 4.7).

  • constraints_data — dict with keys frozen_atoms (list of int), distance_constraints (list of {atoms, target_angstrom}) for a root constraints field (QVF spec § 4.7).

  • extensions — dict of {vendor_ns: {version, schema_uri?, critical?}} for the root extensions governance block (QVF spec § 5.4).

  • eos_data — dict with keys volumes (float64 [n_points]), energies (float64 [n_points]), fit (dict with model, V0, E0, B0, B0_prime, etc.) for an equation_of_state section (QVF spec § 4.14).

  • fermi_surface_data — dict with keys nk1, nk2, nk3 (int), energies (float64 [nk1, nk2, nk3, n_bands]), band_indices (list of int), lattice_vectors (3×3), fermi_energy_ev (float), and optional n_spin (int, default 1) for a fermi_surface section (QVF spec § 4.12).

  • wf_data — dict with keys basis (list of shell dicts), mo_metadata (dict), mo_coefficients (2D || [n_mo, n_ao]), and optionally mo_coefficients_alpha / mo_coefficients_beta for unrestricted

  • ao_data — list of dicts from qvf_ao_data(), each with keys label, data (3-D array), origin, span, ao_metadata, section_id. Emitted as basis.ao sections.

Returns:

The on-disk {stem}.qvf path.

Return type:

pathlib.Path