vibeview.qvf

QVF reader — the core file-open lifecycle.

Responsibilities: - Open .qvf zip archive, extract + validate manifest.json - Parse sections into pydantic models - Verify sha256 of every binary member before use (Rule 4) - Lazy extraction of volumetric .dat blobs

Module Attributes

MAX_ATOMIC_NUMBER

the int64 maximum.

RELOCALIZED_PREFIX

Section-id prefix of wavefunction overlays computed by re-localization (vibeview.relocalize); a geometry edit invalidates every one of them.

STRUCTURE_IDENTITY_FIELDS

The identity fields a structure section object may carry (QVF spec § 5.1, "Chemical identity"), besides the generic label.

REACTION_ARROWS

The arrows of a reaction step (QVF spec § 5.14); absent means forward.

PREVIEW_RASTER_TYPES

Raster types a preview thumbnail may have (QVF spec § 5.15).

MANIFEST_SCHEMA_URI

The $id of the vendored v1 schema, the schema_uri of a v1 manifest.

QVFSource

a filesystem path, raw zip bytes, or a seekable binary file-like object (BytesIO, an opened file, etc.).

Functions

clamp_replication(replication, pbc)

Force the replication count to 1 on every non-periodic axis.

scf_energy_eh(provenance)

provenance["scf_energy"] as a float in hartree, or None.

Classes

Atom(symbol, position, atomic_number[, ...])

One atom.

AtomPropertiesData(mulliken_charges, ...[, ...])

BandsData(kpath, eigenvalues, fermi)

BasisShell(center, l, exponents, coefficients)

One contracted shell of the GTO basis (§ 1.5).

BondOrdersData(method, pairs)

Bond-order analysis section.

CitationsData(bibtex)

BibTeX bibliography embedded in the QVF.

DOSCOOPData(energies, projections, ...)

COOP/COHP bonding analysis section (dos.coop or dos.cohp).

DOSData(energies, values, channels, projected)

A dos.total or dos.projected section (spec § 4.8 / § 4.9).

EPRData(raw)

EPR section payload.

EquationOfStateData(volumes, energies, fit)

FermiSurfaceData(energies, mesh)

A fermi_surface section: the energy mesh and its metadata.

GridData(origin, voxel_vectors, shape[, units])

Geometry of a scalar field on a regular grid.

JobSpecData(job_type, method, basis, ...)

job.spec section payload — the declarative specification of the calculation the archive requests (spec § 5.9).

Manifest(*, qvf_version, source, sections[, ...])

MemberSpec(*, path, format, sha256[, dtype, ...])

One member of a section (a file inside the zip).

NMRData(raw)

NMR section payload.

PhononBandsData(qpath, frequencies)

PhononDOSData(frequencies, dos, meta)

PreviewImage(role, media_type, data)

One verified preview member: its declared type and its bytes.

QTAIMData(points, bond_paths)

QTAIM topological analysis section.

QVFReader(source)

Read a .qvf archive and provide lazy access to sections.

ReactionParticipant(structure_ref[, coefficient])

One species of a reaction step: a structure section and its coefficient.

ReactionPathData(atoms, coords, energies, ...)

Self-contained reaction path (reaction.path).

ReactionSchemeData(steps)

A reaction.scheme payload: its steps in reading order.

ReactionStep(id, reactants, products[, ...])

One step of a reaction.scheme (QVF spec § 5.14).

ReactionWaypoint(frame_index, label, kind[, ...])

One reaction-path waypoint annotation.

ReactionWaypointsData(trajectory_ref, ...)

Waypoint annotations layered on a referenced trajectory.

RunRecordData(program, program_version, ...)

run.record section payload — the self-contained record of one program invocation (verbatim input + full log, spec § 5.8).

SCFHistoryData(iterations)

Per-iteration SCF trail.

ScanSurfaceData(axis_a, axis_b, energies[, ...])

2D relaxed-scan energy surface (scan.surface).

Section(*, id, kind[, members, component, ...])

One section from the manifest.

Source(*, program, version, calculation)

SpectraData(frequencies, intensities[, labels])

StructureData(atoms, pbc, lattice_vectors, bonds)

A unit cell, or a molecule when pbc is all-False.

StructureIdentity([label, name, charge, ...])

Which chemical species a structure section holds (QVF spec § 5.1).

SymmetryData(raw)

spglib-style symmetry analysis embedded in the QVF.

TrajectoryData(atoms, coords, energies)

TransitionOrbitals([role, state_index, ...])

The excited state a set of natural transition orbitals describes (spec § 5.3).

VibrationsData(atoms, frequencies, displacements)

ViewerDefaults(*[, auto_open])

Viewer defaults from manifest.json.

WavefunctionGTOData(structure_ref, pure, ...)

wavefunction.gto payload.

Exceptions

CriticalSectionUnsupportedError

A section (or root extension) flagged critical: true has a kind the viewer cannot render.

ManifestValidationError

manifest.json failed JSON Schema validation.

QVFError

Base for all QVF reader errors.

QVFOpenError(message, *[, validation_report])

Cannot open/read the file; validation may attach its reference report.

SHA256MismatchError

sha256 of a member does not match the manifest.

SectionNotFoundError

Requested section id not found in manifest.
class vibeview.qvf.Source(*, program, version, calculation)[source]

Bases: BaseModel

Parameters:

  • program (str)

  • version (str)

  • calculation (str)

program: str
version: str
calculation: str
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibeview.qvf.MemberSpec(*, path, format, sha256, dtype=None, shape=None, media_type=None)[source]

Bases: BaseModel

One member of a section (a file inside the zip).

Parameters:
path: str
format: str
sha256: str
dtype: str | None
shape: list[int] | None
media_type: str | None
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibeview.qvf.Section(*, id, kind, members=<factory>, component=None, trajectory_ref=None, **extra_data)[source]

Bases: BaseModel

One section from the manifest.

Parameters:
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str
kind: str
members: dict[str, MemberSpec]
component: str | None
trajectory_ref: str | None
class vibeview.qvf.ViewerDefaults(*, auto_open=<factory>, **extra_data)[source]

Bases: BaseModel

Viewer defaults from manifest.json.

Known fields (auto_open) are explicit. All other keys are per-section hints (e.g. "density": {"isovalue": 0.05, ...}) and are captured via Pydantic’s extra=”allow” in model_extra.

Parameters:
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

auto_open: list[str]
class vibeview.qvf.Manifest(*, qvf_version, source, sections, viewer_defaults=None, **extra_data)[source]

Bases: BaseModel

Parameters:
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

qvf_version: int
source: Source
sections: list[Section]
viewer_defaults: ViewerDefaults | None
exception vibeview.qvf.QVFError[source]

Bases: Exception

Base for all QVF reader errors.

exception vibeview.qvf.QVFOpenError(message, *, validation_report=None)[source]

Bases: QVFError

Cannot open/read the file; validation may attach its reference report.

Parameters:

  • message (str)

  • validation_report (dict[str, Any] | None)

Return type:

None

vibeview.qvf.MAX_ATOMIC_NUMBER = 9223372036854775807

the int64 maximum. Numbers beyond the element table are kept on purpose (a converter labels Atom(999) “Z999”, and frame metadata keeps unknown display labels); the bond search stores atomic numbers as int64.

Type:

Largest atomic_number the reader accepts

exception vibeview.qvf.ManifestValidationError[source]

Bases: QVFError

manifest.json failed JSON Schema validation.

exception vibeview.qvf.SHA256MismatchError[source]

Bases: QVFError

sha256 of a member does not match the manifest. Hard error for that section.

exception vibeview.qvf.SectionNotFoundError[source]

Bases: QVFError

Requested section id not found in manifest.

exception vibeview.qvf.CriticalSectionUnsupportedError[source]

Bases: QVFError

A section (or root extension) flagged critical: true has a kind the viewer cannot render. Per the QVF spec (§2.2 / §5.5 / §7) the consumer MUST refuse to open such a file rather than silently render a partial, misleading view.

class vibeview.qvf.Atom(symbol, position, atomic_number, atom_name=None, residue_name=None, residue_seq=None, chain_id=None, b_factor=None)[source]

Bases: object

One atom. The biomolecular fields are optional and default to None.

Chemistry files (XYZ, a computed structure) carry none of them; a PDB carries all five, and the cartoon/ribbon work (roadmap workstream D) is built on them — atom_name identifies the backbone trace, chain_id + residue_seq order it, residue_name colours it, b_factor carries the temperature factor (or, for a predicted structure, the per-residue confidence a predictor writes into that column). Optional rather than required so every existing archive, and every non-biomolecular producer, keeps working untouched.

Parameters:

  • symbol (str)

  • position (ndarray)

  • atomic_number (int)

  • atom_name (str | None)

  • residue_name (str | None)

  • residue_seq (int | None)

  • chain_id (str | None)

  • b_factor (float | None)

symbol: str
position: ndarray
atomic_number: int
atom_name: str | None = None
residue_name: str | None = None
residue_seq: int | None = None
chain_id: str | None = None
b_factor: float | None = None
vibeview.qvf.RELOCALIZED_PREFIX = 'wf_relocalized_'

Section-id prefix of wavefunction overlays computed by re-localization (vibeview.relocalize); a geometry edit invalidates every one of them.

vibeview.qvf.clamp_replication(replication, pbc)[source]

Force the replication count to 1 on every non-periodic axis.

Replicating along a non-periodic axis would tile the structure along a synthesized, non-physical lattice column — for a 2D slab that fabricates a stack of sheets that the calculation never contained.

Parameters:
Return type:

tuple[int, int, int]

class vibeview.qvf.StructureData(atoms, pbc, lattice_vectors, bonds, dim=-1, supplied_residues=None, supplied_chains=None, supplied_secondary_structure=None)[source]

Bases: object

A unit cell, or a molecule when pbc is all-False.

For dim < 3 the lattice rows dim..2 are non-physical: the producer synthesizes them so AO integrals and spglib always see a full-rank 3x3 matrix, and the SCF energy is provably invariant to their length. They are NOT cell edges and must never be drawn, replicated along, or used as a geometric extent. pbc is the only signal that separates a synthesized column from a real lattice vector — a synthesized 30-bohr normal and a real 30-bohr vacuum gap are numerically identical in lattice_vectors.

Parameters:
atoms: list[Atom]
pbc: tuple[bool, bool, bool]
lattice_vectors: ndarray | None
bonds: list[tuple[int, int, float, tuple[int, int, int]]] | None
dim: int = -1
supplied_residues: list[dict[str, Any]] | None = None
supplied_chains: list[str] | None = None
supplied_secondary_structure: list[dict[str, Any]] | None = None
property has_residues: bool

True when this structure carries biomolecular identity.

Either carrier counts: per-atom residue numbers, or a producer-supplied residues list on the section object. A producer may legitimately supply the second without the first.

chain_ids()[source]

Chain ids, in presentation order.

The producer-supplied chains list when the archive has one (it may order chains for presentation, and may name a chain that contributes no residue), otherwise the chains chains() derived.

Return type:

list[str]

chains()[source]

{chain_id: [(residue_seq, [atom indices]), ...]}.

A producer-supplied residues list wins over the derivation below (spec § 5.1 precedence). Everything after this paragraph describes that derivation, which is what runs for a PDB import and for every archive whose producer supplied nothing.

Residues appear in the order the file lists them, which for a PDB is the order along the chain — the ribbon must follow the actual connectivity, and sorting by residue number would silently reorder insertion codes or non-monotonic numbering. Atoms with no residue identity are skipped rather than lumped into a fake chain; a file with none simply yields {}.

Grouping is by contiguous run of (chain, sequence, name), not by a global key. PDB residue numbers are only four columns wide and wrap at 9999, so a solvated system reuses them: keying globally merged a lipid and a water that happened to share number 1001 into one 80-atom “residue” (measured: 1,256 such collisions on a 150k-atom membrane protein, 9,999 buckets where the file holds 12,010 residues). Contiguity is also what makes insertion codes behave, since those too are listed in order.

Return type:

dict[str, list[tuple[int, list[int]]]]

ca_residues(chain_id=None)[source]

(chain, residue_seq, CA atom index) for each CA-bearing residue.

The single ordering used by backbone_trace() and by the supplied-assignment branch of secondary_structure(), so the two cannot drift apart: a per-CA label list that did not line up with the trace it is zipped against would mislabel a whole chain.

Public because renderers need it. Anything building a per-CA array to zip against backbone_trace() — a selection mask, a colour array — must walk this exact ordering rather than re-deriving it, since a second copy of the walk can drift. It was private until 2026-07-26, which forced the cartoon renderer to reach in through getattr and carry a duplicated fallback.

Parameters:

chain_id (str | None)

Return type:

list[tuple[str, int, int]]

backbone_trace(chain_id=None)[source]

Alpha-carbon coordinates, in chain order — the ribbon spine.

[N, 3]; empty when the structure has no CA atoms. Pass chain_id for a single chain, or leave it None to concatenate every chain (callers drawing one ribbon per chain should ask per chain, so the spline does not jump between them).

Parameters:

chain_id (str | None)

Return type:

ndarray

secondary_structure(chain_id=None, *, detailed=False)[source]

Per-alpha-carbon secondary structure, aligned with backbone_trace().

One character per CA: "H" helix, "E" extended strand, "C" coil. The list is always the same length as the trace for the same chain_id, so a renderer can zip the two.

With detailed=True, supplied subtype annotations additionally return G (3-10 helix), I (pi helix) and B (beta bridge). Geometric assignment always returns the coarse H/E/C labels.

A producer-supplied secondary_structure range list wins, per chain, over the geometric assignment described below (spec § 5.1 precedence). That is not a preference for tidiness: the CA-only assignment below genuinely cannot tell an alpha- from a pi- from a 3-10 helix, or a beta-bridge from a sheet, and a producer can.

Assignment is from the CA trace alone. Real DSSP (Kabsch & Sander, Biopolymers 22, 2577 (1983)) reads backbone N/CA/C/O and assigns from hydrogen-bond energies; a QVF is not guaranteed to carry O at all, and vibe-view needs this only to decide ribbon geometry. CA-only assignment is an established family of approximations to it, the reference implementation being P-SEA (Labesse, Colloc’h, Pothier & Mornon, Comput. Appl. Biosci. 13, 291 (1997)), which discriminates on CA(i)-CA(i+k) distances plus the virtual CA angle and dihedral. This uses those same descriptors.

The numeric windows below are this implementation’s, chosen to bracket ideal geometry rather than transcribed from the paper. tests/test_secondary_structure.py constructs an ideal right-handed alpha-helix (1.5 A rise, 100 deg/residue, CA on a 2.3 A radius) and an ideal extended strand (3.34 A rise) and measures, under this module’s dihedral sign convention:

helix d2 5.43 d3 5.05 d4 6.20 tau 90.4 alpha 50.0 strand d2 6.68 d3 10.20 d4 13.36 tau 120.7 alpha 180.0

A left-handed helix measures alpha -50.0, so the dihedral sign is what keeps one from being read as the other.

Assignment is per chain even when chain_id is None: running the window across a chain boundary would invent structure out of two unrelated termini that happen to be adjacent in the file.

Parameters:

  • chain_id (str | None)

  • detailed (bool)

Return type:

list[str]

class vibeview.qvf.GridData(origin, voxel_vectors, shape, units='bohr')[source]

Bases: object

Geometry of a scalar field on a regular grid.

A stored QVF volume keeps origin and voxel_vectors in bohr (design § 1.3a), the default. Fields the viewer samples itself, such as an orbital evaluated from the GTO wavefunction, are laid out in Å alongside the atoms and say so with units="angstrom". Anything that places a grid in the Å scene scales by to_angstrom instead of assuming one convention.

Parameters:
origin: ndarray
voxel_vectors: ndarray
shape: tuple[int, int, int]
units: Literal['bohr', 'angstrom'] = 'bohr'
property to_angstrom: float

Factor that takes this grid’s coordinates into Å.

class vibeview.qvf.BandsData(kpath: 'dict[str, Any]', eigenvalues: 'np.ndarray', fermi: 'float | None')[source]

Bases: object

Parameters:
kpath: dict[str, Any]
eigenvalues: ndarray
fermi: float | None
class vibeview.qvf.PhononBandsData(qpath: 'dict[str, Any]', frequencies: 'np.ndarray')[source]

Bases: object

Parameters:
qpath: dict[str, Any]
frequencies: ndarray
class vibeview.qvf.PhononDOSData(frequencies: 'np.ndarray', dos: 'np.ndarray', meta: 'dict[str, Any]')[source]

Bases: object

Parameters:
frequencies: ndarray
dos: ndarray
meta: dict[str, Any]
class vibeview.qvf.EquationOfStateData(volumes: 'np.ndarray', energies: 'np.ndarray', fit: 'dict[str, Any]')[source]

Bases: object

Parameters:
volumes: ndarray
energies: ndarray
fit: dict[str, Any]
class vibeview.qvf.SpectraData(frequencies: 'np.ndarray', intensities: 'np.ndarray', labels: 'list[str] | None' = None)[source]

Bases: object

Parameters:
frequencies: ndarray
intensities: ndarray
labels: list[str] | None = None
class vibeview.qvf.TrajectoryData(atoms: 'list[Atom]', coords: 'np.ndarray', energies: 'list[float] | None')[source]

Bases: object

Parameters:
atoms: list[Atom]
coords: ndarray
energies: list[float] | None
class vibeview.qvf.VibrationsData(atoms: 'list[Atom]', frequencies: 'np.ndarray', displacements: 'np.ndarray')[source]

Bases: object

Parameters:
atoms: list[Atom]
frequencies: ndarray
displacements: ndarray
class vibeview.qvf.AtomPropertiesData(mulliken_charges: 'np.ndarray | None', loewdin_charges: 'np.ndarray | None', spin_populations: 'np.ndarray | None' = None, hirshfeld_charges: 'np.ndarray | None' = None, iao_charges: 'np.ndarray | None' = None)[source]

Bases: object

Parameters:
mulliken_charges: ndarray | None
loewdin_charges: ndarray | None
spin_populations: ndarray | None = None
hirshfeld_charges: ndarray | None = None
iao_charges: ndarray | None = None
class vibeview.qvf.CitationsData(bibtex)[source]

Bases: object

BibTeX bibliography embedded in the QVF.

The writer stores references.bib as a binary member (utf-8 bytes + sha256). We decode here so renderers see a string.

Parameters:

bibtex (str)

bibtex: str
class vibeview.qvf.RunRecordData(program, program_version, command, exit_status, started_utc, finished_utc, sequence, input_text, input_size, log_text, log_size, files, attachment_roles)[source]

Bases: object

run.record section payload — the self-contained record of one program invocation (verbatim input + full log, spec § 5.8).

input_text / log_text are decoded UTF-8 (None when the member is absent); input_size / log_size are the uncompressed byte counts from the ZIP central directory so a renderer can size-gate what it pushes to the DOM. files is the optional filename index; attachment_roles lists attachment members present (their bytes are not read here).

Parameters:

  • program (str)

  • program_version (str | None)

  • command (str | None)

  • exit_status (int | None)

  • started_utc (str | None)

  • finished_utc (str | None)

  • sequence (int | None)

  • input_text (str | None)

  • input_size (int)

  • log_text (str | None)

  • log_size (int)

  • files (dict[str, Any])

  • attachment_roles (list[str])

program: str
program_version: str | None
command: str | None
exit_status: int | None
started_utc: str | None
finished_utc: str | None
sequence: int | None
input_text: str | None
input_size: int
log_text: str | None
log_size: int
files: dict[str, Any]
attachment_roles: list[str]
class vibeview.qvf.JobSpecData(job_type, method, basis, functional, charge, multiplicity, kpoints, tasks, options, raw)[source]

Bases: object

job.spec section payload — the declarative specification of the calculation the archive requests (spec § 5.9). raw keeps the full JobSpecPayload (open for forward growth); the typed fields mirror its portable top level.

Parameters:
job_type: str
method: str | None
basis: str | None
functional: str | None
charge: int | None
multiplicity: int | None
kpoints: list[Any] | None
tasks: list[Any]
options: dict[str, Any]
raw: dict[str, Any]
vibeview.qvf.STRUCTURE_IDENTITY_FIELDS: tuple[str, ...] = ('name', 'charge', 'multiplicity', 'smiles', 'inchi', 'inchikey')

The identity fields a structure section object may carry (QVF spec § 5.1, “Chemical identity”), besides the generic label.

class vibeview.qvf.StructureIdentity(label=None, name=None, charge=None, multiplicity=None, smiles=None, inchi=None, inchikey=None)[source]

Bases: object

Which chemical species a structure section holds (QVF spec § 5.1).

Read from the section object, never from a member. Every field is optional, and an absent one states nothing: a structure without charge is not declared neutral. label is the generic section label, the short compound label a scheme shows (“1”, “3a”); name is the chemical name. A value of the wrong type reads as absent.

Parameters:

  • label (str | None)

  • name (str | None)

  • charge (int | None)

  • multiplicity (int | None)

  • smiles (str | None)

  • inchi (str | None)

  • inchikey (str | None)

label: str | None = None
name: str | None = None
charge: int | None = None
multiplicity: int | None = None
smiles: str | None = None
inchi: str | None = None
inchikey: str | None = None
property title: str

"<label> · <name>", either alone, or "" when neither is given.

as_dict()[source]

The fields that are present, for JSON output.

Return type:

dict[str, Any]

vibeview.qvf.REACTION_ARROWS: tuple[str, ...] = ('forward', 'equilibrium', 'retrosynthetic', 'resonance')

The arrows of a reaction step (QVF spec § 5.14); absent means forward.

class vibeview.qvf.ReactionParticipant(structure_ref, coefficient=1.0)[source]

Bases: object

One species of a reaction step: a structure section and its coefficient.

Parameters:

  • structure_ref (str)

  • coefficient (float)

structure_ref: str
coefficient: float = 1.0
class vibeview.qvf.ReactionStep(id, reactants, products, reagents=<factory>, label=None, arrow='forward', conditions=<factory>, yield_percent=None, yield_text=None)[source]

Bases: object

One step of a reaction.scheme (QVF spec § 5.14).

Roles are chemical: reactants are consumed and products formed in the step’s forward direction whatever the arrow.

Parameters:
id: str
reactants: list[ReactionParticipant]
products: list[ReactionParticipant]
reagents: list[ReactionParticipant]
label: str | None = None
arrow: str = 'forward'
conditions: list[str]
yield_percent: float | None = None
yield_text: str | None = None
class vibeview.qvf.ReactionSchemeData(steps)[source]

Bases: object

A reaction.scheme payload: its steps in reading order.

Parameters:

steps (list[ReactionStep])

steps: list[ReactionStep]
vibeview.qvf.PREVIEW_RASTER_TYPES: frozenset[str] = frozenset({'image/jpeg', 'image/png'})

Raster types a preview thumbnail may have (QVF spec § 5.15).

class vibeview.qvf.PreviewImage(role, media_type, data)[source]

Bases: object

One verified preview member: its declared type and its bytes.

Parameters:
role: str
media_type: str
data: bytes
class vibeview.qvf.NMRData(raw)[source]

Bases: object

NMR section payload.

Writer (qvf.py::_write_spectra_nmr_section) pass-through of a dict with conventional keys: chemical_shifts, shielding_tensors, j_couplings, isotope, reference, solvent. Shape of each field is not schema-enforced, so we keep the raw dict and let the renderer decide what to surface.

Parameters:

raw (dict[str, Any])

raw: dict[str, Any]
class vibeview.qvf.EPRData(raw)[source]

Bases: object

EPR section payload.

Writer (qvf.py::_write_spectra_epr_section) pass-through of a dict with conventional keys: g_tensor, hyperfine, zero_field_splitting. Shape of each field is not schema-enforced, so we keep the raw dict and let the renderer decide what to surface.

Parameters:

raw (dict[str, Any])

raw: dict[str, Any]
class vibeview.qvf.SymmetryData(raw)[source]

Bases: object

spglib-style symmetry analysis embedded in the QVF.

Writer (qvf.py::_write_symmetry_section) passes through whatever dict the producer hands it (space group number, symbol, point group, Hall symbol, …). Keys are conventional, not enforced by schema. The renderer surfaces every key it finds.

Parameters:

raw (dict[str, Any])

raw: dict[str, Any]
class vibeview.qvf.SCFHistoryData(iterations)[source]

Bases: object

Per-iteration SCF trail.

Writer (qvf.py::_write_scf_history_section) stores a JSON document {“iterations”: [{“iter”, “energy_eh”, “delta_e”, “diis_error”}, …]}. Field set is conventional, not enforced by schema — keep them as plain dicts so the renderer can degrade gracefully when a key is missing (e.g. non-DIIS solvers have no diis_error).

Parameters:

iterations (list[dict[str, float | int]])

iterations: list[dict[str, float | int]]
class vibeview.qvf.BondOrdersData(method, pairs)[source]

Bases: object

Bond-order analysis section.

Parameters:
method: str
pairs: list[dict[str, object]]
class vibeview.qvf.QTAIMData(points, bond_paths)[source]

Bases: object

QTAIM topological analysis section.

Parameters:
points: list[dict[str, object]]
bond_paths: list[dict[str, object]] | None
class vibeview.qvf.DOSData(energies, values, channels, projected)[source]

Bases: object

A dos.total or dos.projected section (spec § 4.8 / § 4.9).

values is the DOS [n_pts] or [2, n_pts] (spin axis leading) for a total DOS, and the per-channel projections [n_ch, n_pts] for a projected one, with a spin axis already summed away. channels is the section’s channel list, empty for a total DOS.

Parameters:
energies: ndarray
values: ndarray
channels: list[object]
projected: bool
class vibeview.qvf.FermiSurfaceData(energies, mesh)[source]

Bases: object

A fermi_surface section: the energy mesh and its metadata.

Parameters:
energies: ndarray
mesh: dict[str, object]
class vibeview.qvf.DOSCOOPData(energies, projections, integrated, meta)[source]

Bases: object

COOP/COHP bonding analysis section (dos.coop or dos.cohp).

Parameters:
energies: ndarray
projections: ndarray
integrated: ndarray
meta: dict[str, object]
class vibeview.qvf.BasisShell(center, l, exponents, coefficients, pure=True)[source]

Bases: object

One contracted shell of the GTO basis (§ 1.5).

Parameters:
center: int
l: int
exponents: ndarray
coefficients: ndarray
pure: bool = True
class vibeview.qvf.TransitionOrbitals(role=None, state_index=None, excitation_energy_ev=None, states_ref=None)[source]

Bases: object

The excited state a set of natural transition orbitals describes (spec § 5.3).

Read from the canonical carriers first: state_index and the excitation_energy of that state in the excited_states section state_ref names. Archives written before those existed carry the deprecated excitation_index and excitation_energy_ev instead, which are read when the canonical carrier is absent, so both show the same state. Each field is None when the archive does not say.

Parameters:

  • role (str | None)

  • state_index (int | None)

  • excitation_energy_ev (float | None)

  • states_ref (str | None)

role: str | None = None

"hole" or "particle", from nto_role.

state_index: int | None = None

state_index, else excitation_index.

Type:

The state’s number

excitation_energy_ev: float | None = None

The state’s excitation energy in eV.

states_ref: str | None = None

The excited_states section that state_ref names.

class vibeview.qvf.WavefunctionGTOData(structure_ref, pure, n_ao, shells, spin, orbital_kind, energies, occupations, symmetry_labels, alpha_energies, alpha_occupations, beta_energies, beta_occupations, mo_coefficients, mo_coefficients_alpha, mo_coefficients_beta, symmetry_labels_beta=None, atom_populations=None, centroids_bohr=None, n_centres=None, localization_method=None, occupation_semantics=None, k_point=None, relocalization=None, density_unavailable_reason=None, transition_orbitals=None)[source]

Bases: object

wavefunction.gto payload.

For restricted: mo_coefficients is set, mo_coefficients_alpha and mo_coefficients_beta are None.

For unrestricted: the per-spin variants are set, and mo_coefficients is None.

Each coefficient matrix is row-major [n_mo, n_ao].

Parameters:
structure_ref: str
pure: bool
n_ao: int
shells: list[BasisShell]
spin: str
orbital_kind: str
energies: ndarray | None
occupations: ndarray | None
symmetry_labels: list[str] | None
alpha_energies: ndarray | None
alpha_occupations: ndarray | None
beta_energies: ndarray | None
beta_occupations: ndarray | None
mo_coefficients: ndarray | None
mo_coefficients_alpha: ndarray | None
mo_coefficients_beta: ndarray | None
symmetry_labels_beta: list[str] | None = None
atom_populations: ndarray | None = None
centroids_bohr: ndarray | None = None
n_centres: ndarray | None = None
localization_method: str | None = None
occupation_semantics: str | None = None
k_point: ndarray | None = None
relocalization: dict[str, Any] | None = None
density_unavailable_reason: str | None = None
transition_orbitals: TransitionOrbitals | None = None
class vibeview.qvf.ReactionWaypoint(frame_index, label, kind, energy_eh=None)[source]

Bases: object

One reaction-path waypoint annotation.

Parameters:
frame_index: int
label: str
kind: str
energy_eh: float | None = None
class vibeview.qvf.ReactionPathData(atoms, coords, energies, reaction_coordinate, waypoints, lattice=None, dim=None, dim_per_frame=None, reaction_coordinate_label=None, reaction_coordinate_unit=None, frame_volumes=None, volume_grid=None, volume_frame_index=None, volume_label=None, volume_isovalue=None)[source]

Bases: object

Self-contained reaction path (reaction.path).

Binary layout matches trajectory: coords[n_frames, n_atoms, 3] in Å.

Periodic reaction paths additionally carry the per-frame lattice + dimensionality so the renderer can draw the cell and wrap atoms across periodic boundaries. A path is periodic when it has the lattice member, never because of the manifest’s qvf_version (QVF spec § 3.1):

  • lattice is None for molecular paths. Otherwise a float64 array of shape (3, 3) when every frame shares the same lattice (the fixed-cell common case) or (n_frames, 3, 3) for variable- cell paths. Columns are a, b, c, in bohr — matching vibeqc.PeriodicSystem.lattice. The renderer is responsible for the bohr→Å conversion (coords are already Å).

  • dim is None for molecular paths. Otherwise an int in {1, 2, 3}; dim_per_frame is set instead when frames carry different dimensionalities.

Parameters:
atoms: list[Atom]
coords: ndarray
energies: list[float] | None
reaction_coordinate: list[float] | None
waypoints: list[ReactionWaypoint]
lattice: ndarray | None = None
dim: int | None = None
dim_per_frame: list[int] | None = None
reaction_coordinate_label: str | None = None
reaction_coordinate_unit: str | None = None
frame_volumes: ndarray | None = None
volume_grid: GridData | None = None
volume_frame_index: list[int] | None = None
volume_label: str | None = None
volume_isovalue: float | None = None
class vibeview.qvf.ReactionWaypointsData(trajectory_ref, waypoints, reaction_coordinate)[source]

Bases: object

Waypoint annotations layered on a referenced trajectory.

Parameters:
trajectory_ref: str
waypoints: list[ReactionWaypoint]
reaction_coordinate: list[float] | None
class vibeview.qvf.ScanSurfaceData(axis_a, axis_b, energies, coordinate_a_label=None, coordinate_a_unit=None, coordinate_b_label=None, coordinate_b_unit=None, atoms=None, geometries=None)[source]

Bases: object

2D relaxed-scan energy surface (scan.surface).

energies is [nA, nB] (Hartree); axis_a / axis_b are the 1D driven-coordinate values. Optional geometries is the relaxed structure at each node, flattened [nA*nB, n_atoms, 3] in Å (row-major over (a, b)); atoms carries the element symbols.

Parameters:
axis_a: ndarray
axis_b: ndarray
energies: ndarray
coordinate_a_label: str | None = None
coordinate_a_unit: str | None = None
coordinate_b_label: str | None = None
coordinate_b_unit: str | None = None
atoms: list[Atom] | None = None
geometries: ndarray | None = None
vibeview.qvf.scf_energy_eh(provenance)[source]

provenance["scf_energy"] as a float in hartree, or None.

Producers write the energy either as a bare number or as {"value": E, "unit": "hartree"}; every surface that prints or compares energies reads it through here.

Parameters:

provenance (Mapping[str, Any])

Return type:

float | None

vibeview.qvf.MANIFEST_SCHEMA_URI: str = 'https://vibe-qc.org/spec/qvf/1/manifest.schema.json'

The $id of the vendored v1 schema, the schema_uri of a v1 manifest.

vibeview.qvf.QVFSource

a filesystem path, raw zip bytes, or a seekable binary file-like object (BytesIO, an opened file, etc.).

Used by vibe-qc to hand a freshly built QVF over to the viewer without touching disk.

Type:

Anything QVFReader can open

alias of str | Path | bytes | bytearray | memoryview | IO[bytes]

class vibeview.qvf.QVFReader(source)[source]

Bases: object

Read a .qvf archive and provide lazy access to sections.

The archive can come from any of:

  • a filesystem path (str / pathlib.Path ending in .qvf)

  • raw zip bytes (bytes / bytearray / memoryview) — vibe-qc can build a QVF in memory via qvf_bytes(...) and pass them in

  • a seekable binary file-like object (BytesIO, opened binary file, …)

The zip handle is kept open for the lifetime of the reader so lazy binary blobs can be read on demand. close() (or use as a context manager) releases it; if the reader owns an in-memory buffer that is released too.

Parameters:

source (QVFSource)

source_path: Path | None
property manifest: Manifest
property path: Path | None

Path to the .qvf file on disk, or None for in-memory archives.

property source: Source
property sections: list[Section]
property viewer_defaults: ViewerDefaults | None
property provenance: dict[str, Any]

The manifest’s open provenance block ({} when absent).

scf_energy_eh()[source]

The provenance’s SCF energy in hartree, or None when it records none.

Return type:

float | None

property dipole_moment: dict[str, Any]

The manifest’s root dipole_moment block ({} when absent).

Root, not ``provenance`` – QVF spec § 4.7 puts it there and the schema declares it as a root property. Reading it off provenance silently yields None for every file ever written, which is what left the dipole arrow and the dipole readout dead.

Keys: total_debye, vector_debye (3), origin (3).

property thermochemistry: dict[str, Any]

The manifest’s root thermochemistry block ({} when absent).

Root, for the same reason as dipole_moment. Producer keys (python/vibeqc/runner.py) are zpve_eh, enthalpy_eh, entropy_cal_mol_k, gibbs_free_energy_eh, temperature_k and pressure_atm.

Note the entropy is cal/mol/K, not Eh/K – the one field here whose unit is not atomic.

property run_status: str | None

The archive’s place in a calculation lifecycle (spec § 3.2): "pending" for a job container that has not yet run, "running" while the job is in flight (live checkpoint), then "converged" or "failed". None when not stated (an ordinary results archive).

property checkpoint_info: dict[str, Any]

seq (monotonic), wall_time_s, written_at, optionally scf_iteration / energy_eh on mid-SCF snapshots.

Type:

provenance.checkpoint ({} when absent)

run_record_sections()[source]

All run.record sections in run-history order.

Ordered by their sequence field (spec § 5.8; a record without one sorts before sequenced records, keeping manifest order among themselves). The last entry is the latest run — the one whose results the archive’s other sections describe.

Return type:

list[Section]

run_record_position(section_id)[source]

(1-based position, total) of a run.record in run history.

Position total is the latest run. (0, 0) when the section is not a run.record of this archive.

Parameters:

section_id (str)

Return type:

tuple[int, int]

validation_report(*, limits=None)[source]

Validate the open archive with qvf; preserve its handle and edit overlay.

Parameters:

limits (dict[str, Any] | None)

Return type:

dict[str, Any]

manifest_warnings()[source]

Non-fatal findings about the manifest, made when the archive opened.

Each warning starts with its QVF warning code. The one there is today is W_VERSION_WITHDRAWN: the manifest declares the withdrawn qvf_version 2, which vibe-view reads and checks as version 1 (spec § 3.1). The archive is valid; the warning records that its producer wrote a version producers must not write. Empty for an archive with nothing to report.

Return type:

list[str]

lifecycle_warnings()[source]

Container-lifecycle consistency warnings (spec § 3.2, § 5.9).

“Done” means a terminal run_status (converged / failed) plus a complete latest run.record — one that carries both its input and log members (an empty log is complete: a run that failed before output began legitimately logged zero bytes). Returns human-readable warnings, empty when the archive is consistent. Non-terminal and unstated statuses never warn.

Return type:

list[str]

section_is_partial(section_id)[source]

True when the producer marked this section partial — still growing in a live checkpoint (e.g. an optimization trajectory).

Parameters:

section_id (str)

Return type:

bool

has_section(section_id)[source]
Parameters:

section_id (str)

Return type:

bool

get_section(section_id)[source]
Parameters:

section_id (str)

Return type:

Section

property structure_sections: list[Section]

Every structure section, in sections order.

property first_structure_id: str | None

The archive’s first structure (QVF spec § 4.1), or None without one.

The first structure section that viewer_defaults.auto_open lists, else the first section of kind structure in sections order.

property shown_structure_id: str | None

The structure shown and used where none is named, or None without one.

The first structure until show_structure() picks another. read_structure() without an id reads it, and every consumer that shows or exports “the structure” goes through that.

property shown_structure: Section | None

The section of shown_structure_id, or None.

show_structure(section_id)[source]

Make section_id the shown structure; None returns to the first one.

Raises SectionNotFoundError for an unknown id and QVFError for a section of another kind, leaving the choice unchanged. An edit made on a structure stays with it (see set_edit_overlay()). Changing the choice bumps geometry_revision, since read_structure() now returns other atoms.

Parameters:

section_id (str | None)

Return type:

None

structure_ref_of(section_id)[source]

The structure a section describes (QVF spec § 4.1), or None.

A structure describes itself. Any other section describes the structure its structure_ref names; one without a usable reference makes no statement, and the reader keeps its usual behaviour of relating it to the first structure.

Parameters:

section_id (str)

Return type:

str | None

structure_identity(section_id=None)[source]

The chemical identity a structure section object states (spec § 5.1).

section_id defaults to the shown structure. Without a structure, or for fields of the wrong type, the identity states nothing.

Parameters:

section_id (str | None)

Return type:

StructureIdentity

declared_charge_multiplicity(section_id=None)[source]

The charge and multiplicity the archive states for a structure.

Each from the structure’s identity (spec § 5.1, section_id defaulting to the shown structure), else from provenance (§ 3.2) when the archive has at most one structure section: with several, the provenance describes none of them in particular. A missing, non-integer or (for multiplicity) non-positive value is None.

Parameters:

section_id (str | None)

Return type:

tuple[int | None, int | None]

section_error(section_id)[source]

Return the first recorded member error for this section, or None.

Parameters:

section_id (str)

Return type:

str | None

section_error_kind(section_id)[source]

Return the recorded error category for a section, or None.

Parameters:

section_id (str)

Return type:

str | None

read_member_bytes(path)[source]

The raw bytes of zip entry path, unverified.

Every failure to read the entry is a QVFError naming it: a missing entry, a CRC or deflate error, an encrypted entry or an unsupported compression method. Only BadZipFile was mapped before, so the rest reached the CLI as tracebacks (#39-35).

Parameters:

path (str)

Return type:

bytes

manifest_json()[source]

A fresh copy of manifest.json as parsed JSON, unknown fields included.

The reader parsed it once while opening, so this does not read the archive again (and cannot fail on it).

Return type:

dict[str, Any]

stored_size(member)[source]

Uncompressed size in bytes of member in the archive, or None if absent.

Parameters:

member (MemberSpec)

Return type:

int | None

cached_bytes()[source]

Bytes of decoded binary members this reader holds, per section id.

The binary cache is where a volume’s or trajectory’s arrays live once read, so this is the figure a memory readout wants (#35-12); the wrapper objects around it are a few dozen bytes.

Return type:

dict[str, int]

drop_cached(section_id)[source]

Release the cached arrays of one section; return the bytes released.

The next read decodes the member from the archive again. Arrays a caller still references stay alive until the caller lets go.

Parameters:

section_id (str)

Return type:

int

set_edit_overlay(positions, symbols, *, lattice_vectors=None, section_id=None)[source]

Record viewer-side edited geometry (see _edit_overlays).

positions is an (n, 3) sequence in angstroms, symbols the matching element symbols. Raises ValueError, leaving the current overlay untouched, for a wrong shape, a non-finite coordinate, a symbol outside the element table, or an archive without the structure. Subsequent read_structure() calls for that structure return this geometry (with explicit bonds dropped — atom indices from the file no longer apply) instead of the archive’s.

The edit belongs to section_id, by default the shown structure, and stays with it while another structure is shown.

lattice_vectors replaces the current edit-overlay lattice when supplied. Omitting it preserves the current lattice, which lets ordinary atom edits made after a supercell build keep that expanded cell. The lattice is reset together with the atoms by clear_edit_overlay().

Parameters:
Return type:

None

clear_edit_overlay(section_id=None)[source]

Drop viewer-side edits; read_structure() returns the file again.

section_id drops only that structure’s edit; by default every structure’s edit is dropped.

Parameters:

section_id (str | None)

Return type:

None

property has_edit_overlay: bool

Whether any structure carries viewer-side edits.

property edited_structure_ids: list[str]

The structure sections that carry viewer-side edits, in edit order.

set_wavefunction_overlay(section_id, wavefunction)[source]

Register a viewer-computed wavefunction under section_id.

The id also gets a synthetic Section so the sidebar and every reader.sections consumer see it exactly like an archived one. The section carries no members: nothing will read them, because read_wavefunction_gto() short-circuits on the overlay first.

Registering the same id twice replaces the payload and leaves the single synthetic section in place, so re-running a criterion does not accumulate sidebar rows.

Parameters:
Return type:

None

clear_wavefunction_overlays(section_ids=None)[source]

Drop selected (or all) viewer-computed wavefunctions and their sections.

Parameters:

section_ids (list[str] | None)

Return type:

None

property wavefunction_overlay_ids: list[str]

Section ids currently backed by a viewer-computed wavefunction.

read_structure(section_id=None, *, apply_edits=True)[source]

Read + verify a structure section. Always eager.

section_id defaults to the shown structure (shown_structure_id, the first structure unless show_structure() chose another); an archive without one raises SectionNotFoundError. Wavefunctions may reference a different structure, which callers can request explicitly so the displayed atoms, cell, and AO centres stay registered.

Set apply_edits=False to read the archived reference geometry, for example when constructing a displacement from a normal mode. When an edit overlay is set (set_edit_overlay()), it applies only to the structure it was made on. Its returned atoms are the edited geometry and bonds is None (auto-bonding applies). PBC/dimensionality still come from the file; the lattice comes from the overlay when an edit replaced it. The file’s biomolecular metadata does not survive an edit: the overlay atoms carry no residue, chain or B-factor fields, and the producer-supplied residues, chains and secondary structure index the replaced atom list, so they are dropped.

Parameters:

  • section_id (str | None)

  • apply_edits (bool)

Return type:

StructureData

read_bonds(section_id, *, n_atoms=None)[source]

Read explicit pairs, checking their original structure when available.

Omitted orders retain 1.0. Explicit payload images are not specified by QVF v0.1.0 §5.1; retain the existing zero-image convention.

Parameters:

  • section_id (str)

  • n_atoms (int | None)

Return type:

list[tuple[int, int, float, tuple[int, int, int]]]

connectivity(structure, section_id=None)[source]

The bonds every surface draws for structure.

The producer’s explicit bonds when the structure carries them, otherwise the covalent-radius inference (vibeview.bonds. structure_bonds()); inferred bonds carry order 1.0, since radii cannot recover multiplicity. When the archive has a bond_orders section for the structure section structure was read from (section_id, by default the shown structure), its per-pair orders (Mayer/Wiberg, computed from the wavefunction) replace the orders for the pairs it lists.

Parameters:
Return type:

list[tuple[int, int, float, tuple[int, int, int]]]

read_volume_grid(section_id)[source]

Read a finite grid descriptor consistent with its lazy binary member.

Parameters:

section_id (str)

Return type:

GridData

read_volume_data(section_id)[source]

Read + verify volume data, including its pairing with the grid.

Parameters:

section_id (str)

Return type:

ndarray

read_bands(section_id)[source]
Parameters:

section_id (str)

Return type:

BandsData

read_phonon_bands(section_id)[source]

Read a phonon_bands section (QVF spec §4.13).

qpath mirrors the electronic kpath (labeled segments with n_points); frequencies is [n_qpoints, n_modes] in cm^-1.

Parameters:

section_id (str)

Return type:

PhononBandsData

read_phonon_dos(section_id)[source]

Read a phonon_dos section (QVF spec §4.13).

frequencies and dos are [n_points]; meta is required producer metadata (smearing, n_atoms, …), possibly an empty object.

Parameters:

section_id (str)

Return type:

PhononDOSData

read_equation_of_state(section_id)[source]

Read an equation_of_state section (QVF spec §4.14).

volumes / energies are the sampled V-E points (Angstrom^3 / eV); fit carries the producer’s fitted EOS params (model, V0, E0, B0 in GPa, B0_prime, optional unit strings).

Parameters:

section_id (str)

Return type:

EquationOfStateData

read_spectra(section_id)[source]

Read a spectra.* section.

frequencies and intensities must be flat lists of finite numbers with one shared length; anything else is a QVFError recorded against the section (#66).

Parameters:

section_id (str)

Return type:

SpectraData

read_trajectory(section_id)[source]
Parameters:

section_id (str)

Return type:

TrajectoryData

read_vibrations(section_id)[source]
Parameters:

section_id (str)

Return type:

VibrationsData

read_wavefunction_gto(section_id)[source]

Read a wavefunction.gto section (basis + MO coefficients).

A malformed basis or mo_metadata payload (a missing shell key, a non-object, a non-numeric value) raises QVFError and is recorded against the section, never a bare KeyError (#35-3).

Parameters:

section_id (str)

Return type:

WavefunctionGTOData

read_reaction_path(section_id)[source]

Read a reaction.path section (self-contained: frames + waypoints).

v2 archives may carry a lattice binary member + a dim integer in the metadata JSON; both surface on the returned ReactionPathData (None on v1 / molecular).

Parameters:

section_id (str)

Return type:

ReactionPathData

read_reaction_waypoints(section_id)[source]

Read a reaction.waypoints annotation that points at a trajectory.

Parameters:

section_id (str)

Return type:

ReactionWaypointsData

read_scan_surface(section_id)[source]

Read a scan.surface section (2D relaxed energy grid).

Parameters:

section_id (str)

Return type:

ScanSurfaceData

read_atom_properties(section_id)[source]

Read population-analysis charges and spin populations.

Parameters:

section_id (str)

Return type:

AtomPropertiesData

read_nmr(section_id)[source]

Read the NMR spectrum payload from a spectra.nmr section.

The producer hands the writer an opaque dict with conventional keys (chemical_shifts, shielding_tensors, j_couplings, isotope, reference, solvent); we surface the dict as-is.

Parameters:

section_id (str)

Return type:

NMRData

read_epr(section_id)[source]

Read the EPR parameter payload from a spectra.epr section.

The producer hands the writer an opaque dict with conventional keys (g_tensor, hyperfine, zero_field_splitting); we surface it as-is.

Parameters:

section_id (str)

Return type:

EPRData

read_symmetry(section_id)[source]

Read the spglib-style symmetry summary from a structure.symmetry section.

Parameters:

section_id (str)

Return type:

SymmetryData

read_scf_history(section_id)[source]

Read the per-iteration SCF history from a scf_history section.

Iteration record keys are conventional (see SCFHistoryData); the renderer tolerates missing keys.

Parameters:

section_id (str)

Return type:

SCFHistoryData

read_citations(section_id)[source]

Read the BibTeX bytes from a citations section.

The writer stores them as a binary member (utf-8) per design § 1.4 / qvf.py::_write_citations_section. We decode to str here so renderers don’t need to know the on-disk encoding.

Parameters:

section_id (str)

Return type:

CitationsData

read_run_record(section_id)[source]

Read a run.record section — verbatim input + full log of one program invocation (spec § 5.8).

Text members are decoded UTF-8 with errors="replace" (the format requires UTF-8; a lenient decode keeps a slightly broken producer viewable). Attachment members are listed but not read — they can be arbitrary bytes and are only surfaced by name.

Parameters:

section_id (str)

Return type:

RunRecordData

read_run_record_attachment(section_id, role, *, max_bytes=4194304)[source]

Decode a run.record attachment.* member as UTF-8 text.

Attachments are arbitrary bytes; this returns None (rather than raising) when the member is absent, larger than max_bytes (uncompressed, checked from the ZIP central directory before reading), or not valid UTF-8 — the renderer then falls back to listing the attachment by name.

Parameters:

  • section_id (str)

  • role (str)

  • max_bytes (int)

Return type:

str | None

ATTACHMENT_DOWNLOAD_MAX_BYTES = 67108864

Hard ceiling on a single attachment download. The bytes are base64-encoded into a state value and pushed over the websocket, so this bounds memory and socket pressure, not disk.

run_record_attachments(section_id)[source]

Describe a run.record’s attachment.* members for listing.

Metadata only — no payload is read. Each entry carries role, a filename (sanitised to a bare basename; the files index is producer-supplied and must never steer a write), size in bytes, and too_large against ATTACHMENT_DOWNLOAD_MAX_BYTES.

Parameters:

section_id (str)

Return type:

list[dict[str, Any]]

read_run_record_attachment_bytes(section_id, role)[source]

Raw bytes of one attachment.* member, for download only.

Deliberately separate from read_run_record_attachment(), which decodes text for rendering: attachments are arbitrary bytes by spec and callers must not be tempted to put these in the DOM. Returns None when the member is absent or exceeds ATTACHMENT_DOWNLOAD_MAX_BYTES (checked from the ZIP central directory before reading, so a zip bomb cannot be expanded into memory first).

Parameters:
Return type:

bytes | None

read_job_spec(section_id)[source]

Read a job.spec section — the declarative request the archive carries (spec § 5.9). Pair with run_status to tell a pending container from a settled one.

Parameters:

section_id (str)

Return type:

JobSpecData

read_reaction_scheme(section_id)[source]

Read a reaction.scheme section (QVF spec § 5.14).

The payload relates the archive’s structure sections as the reactants, reagents and products of each step. A participant that names no structure section, a repeated step id or a step without reactants or products raises QVFError, recorded against the section. Vendor x_ keys are ignored.

Parameters:

section_id (str)

Return type:

ReactionSchemeData

PREVIEW_MAX_BYTES = 4194304

the spec recommends at most 1 MiB, and the bytes travel to the browser as a data URL.

Type:

Largest preview member read for display

read_preview(section_id, role='thumbnail')[source]

One verified member of a preview section (QVF spec § 5.15).

role is thumbnail or image. Returns None when the member is absent, declares no media_type, or exceeds PREVIEW_MAX_BYTES (checked from the ZIP directory before reading). The picture describes the archive and is not data: nothing reads chemistry from it, and it is never drawn in the 3D scene.

Parameters:
Return type:

PreviewImage | None

read_bond_orders(section_id)[source]

Read analysis pairs validated against original file geometry.

Edit overlays do not change the atom identities of archived analyses. Standalone analysis sections still validate without an upper bound.

Parameters:

section_id (str)

Return type:

BondOrdersData

read_topology_qtaim(section_id)[source]

Read a topology.qtaim section (critical points + bond paths).

Parameters:

section_id (str)

Return type:

QTAIMData

read_dos(section_id)[source]

Read a dos.total or dos.projected section.

A spin-projected [2, n_ch, n_pts] projection is summed over spin so a consumer sees one series per channel; a total DOS keeps its [2, n_pts] spin axis for the caller to split.

Parameters:

section_id (str)

Return type:

DOSData

read_bands_projections(section_id)[source]

Optional fat-band projections of a bands section.

Returns (projections [n_kpoints, n_bands, n_channels], channel labels), or (None, []) when the section carries none.

Parameters:

section_id (str)

Return type:

tuple[ndarray | None, list[str]]

read_fermi_surface(section_id)[source]

Read a fermi_surface section: energy mesh plus its metadata.

Parameters:

section_id (str)

Return type:

FermiSurfaceData

read_json_member(section_id, member_name)[source]

The parsed JSON of one member, verified against the manifest.

For kinds without a typed reader (vendor sections, wannier centres); the typed read_* methods are preferred where one exists.

Parameters:

  • section_id (str)

  • member_name (str)

Return type:

Any

read_dos_coop(section_id)[source]

Read a dos.coop or dos.cohp section.

Parameters:

section_id (str)

Return type:

DOSCOOPData

close()[source]
Return type:

None