vibeqc.output.formats.qvf.write_qvf

vibeqc.output.formats.qvf.write_qvf(stem, plan, *, compression=8, volume_dtype='float32', atomic=False, **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.

• atomic (bool) – When True, write the archive to a temporary sibling file and os.replace it onto {stem}.qvf only after write-time validation passes. A concurrent reader then sees either the previous complete archive or the new complete archive – never a half-written zip. Used by the live-checkpoint path so vibe-view can hot-reload a running job’s QVF safely. Default False preserves the historical in-place write.

• **context (Any) –

  Data objects the section writers need. Typical keys:

  • run_status – "running" | "converged" | "failed"; emitted at provenance.run_status. Lets a live consumer tell a mid-run checkpoint from the settled final archive.

  • checkpoint – dict with seq (monotonic int), wall_time_s (float), written_at (ISO-8601 str), and optional scf_iteration / energy_eh running hints; emitted at provenance.checkpoint.

  • partial_sections – True to mark every section partial: true, or an iterable of section ids / kind strings (e.g. {"trajectory"}) to flag only the still-growing ones in a checkpoint snapshot.

  • biomolecule_data – optional dict adding biomolecule metadata to the structure section for ribbon/cartoon rendering: chains (list[str]), residues (list of {name, seq, chain, atom_indices}, 0-based atom indices), and secondary_structure (list of {type, chain, start_seq, end_seq}). Additive peer keys on the section object; all three independently optional. See _normalize_biomolecule().

  • molecule / system – Molecule or PeriodicSystem

  • structure_lattice_bohr – optional 3x3 lattice override for the structure section, using the same bohr column-vector convention as PeriodicSystem.lattice. Periodic CCM callers use this to emit the full BvK torus cell while keeping the primitive input system intact.

  • 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

  • bond_orders_data – dict with keys method (str, e.g. "mayer") and pairs (list of dicts each with i, j, order and optional distance_ang, symbol_i, symbol_j). Emitted as a bond_orders section.

  • 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 Sec. 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 Sec. 4.11)

  • diff_data – dict of {label: spec} for difference density (e.g. r(product) - r(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 Sec. 4.7).

  • dipole_moment_data – dict with keys total_debye, vector_debye (3-vector), origin (str) for a root dipole_moment field (QVF spec Sec. 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 Sec. 4.7).

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

  • vendor_json_sections – list of first- or third-party vendor JSON sections. Each entry is {id, kind, payload} with optional member (default "data"), label, and critical. The kind must live in the x_<vendor>.* namespace.

  • 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 Sec. 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 (3x3), fermi_energy_ev (float), and optional n_spin (int, default 1) for a fermi_surface section (QVF spec Sec. 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. Emitted as wavefunction.gto with id "wf".

  • bloch_wf_data – dict from qvf_bloch_wf_data() carrying all-k closed-shell Bloch coefficients, occupations, and k-point metadata for QVF-backed periodic READ restarts. Emitted as the first-party vendor section x_vibeqc.bloch_wavefunction.

  • wf_localized_data – same shape as wf_data but emitted as a second wavefunction.gto section with id "wf_localized". mo_metadata["orbital_kind"] should be "localized".

  • wf_nto_hole_data – same shape as wf_data, emitted as wavefunction.gto with id "wf_nto_hole" and orbital_kind="natural". The “hole” side of a single NTO pair (simplest post-TD-DFT path).

  • wf_nto_electron_data – same shape as wf_data, emitted as wavefunction.gto with id "wf_nto_electron" and orbital_kind="natural". The “electron” side of a single NTO pair.

  • nto_data – list of {"hole": wf_dict, "electron": wf_dict, "state_index": int, "excitation_energy_ev": float} records, one per excited state. Each emits two wavefunction.gto sections with orbital_kind="natural" and ids "wf_nto_S{n}_hole" / "wf_nto_S{n}_electron". Intended for Natural Transition Orbitals (post-TD-DFT).

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

  • coop_data – dict with keys energies (float64 [n_points] in eV), projections (float64 [n_pairs, n_points] or [n_spin, n_pairs, n_points]), integrated (float64 [n_pairs]), energies_units, n_spin, fermi_energy_ev, sigma_ev, pairs for a dos.coop section (QVF spec Sec. 4.8b).

  • cohp_data – dict with keys energies, projections, integrated, energies_units, n_spin, fermi_energy_ev, sigma_ev, pairs for a dos.cohp section (QVF spec Sec. 4.8c).

Returns:

The on-disk {stem}.qvf path.

Return type:

pathlib.Path