QVF consumer reference — reading a .qvf file in Python

The manifest shape matches the vibe-view consumer (vibe-view/src/vibeview/qvf.py).

import zipfile, json, hashlib
import numpy as np

# ── Open ───────────────────────────────────────────────────────────────
path = "h2o.qvf"
zf = zipfile.ZipFile(path, "r")
manifest = json.loads(zf.read("manifest.json"))

print(f"QVF v{manifest['qvf_version']} from {manifest['source']['program']}")

# ── Verify sha256 of every member ──────────────────────────────────────
for section in manifest["sections"]:
    for _key, member in section.get("members", {}).items():
        sha = member.get("sha256")
        if sha is not None:
            got = hashlib.sha256(zf.read(member["path"])).hexdigest()
            assert got == sha, f"sha256 mismatch for {member['path']}"

# ── Structure → atoms ──────────────────────────────────────────────────
for s in manifest["sections"]:
    if s["kind"] == "structure":
        struct = json.loads(zf.read(s["members"]["structure"]["path"]))
        for a in struct["atoms"]:
            print(f"  {a['symbol']} at {a['position']}")
        print(f"  pbc={struct['pbc']}")
        if "lattice_vectors" in struct:
            print(f"  lattice={struct['lattice_vectors']}")

# ── Volume.density → numpy array ──────────────────────────────────────
for s in manifest["sections"]:
    if s["kind"] == "volume.density":
        dm = s["members"]["data"]
        raw = zf.read(dm["path"])
        grid_data = np.frombuffer(raw, dtype=np.float32).reshape(dm["shape"])
        # Grid descriptor is a JSON member
        g = json.loads(zf.read(s["members"]["grid"]["path"]))
        print(f"Density: {dm['shape']}, origin={g['origin']}")

# ── Vibrations ────────────────────────────────────────────────────────
for s in manifest["sections"]:
    if s["kind"] == "vibrations":
        meta = json.loads(zf.read(s["members"]["metadata"]["path"]))
        print(f"Frequencies: {len(meta['frequencies'])} modes")

zf.close()

Consumer contract (v1)

1. Kind strings from the registry or x_<vendor>.*.

2. Every member in members has path, format (“json”|”binary”), sha256.

3. Structure is a JSON member "structure" under section id="structure".

4. Volumes have binary "data" + JSON "grid" members. The grid JSON carries origin, voxel_vectors, shape.

5. Spectra have JSON "spectrum" member with frequencies and intensities.

6. Vibrations have JSON "metadata" (with atoms and frequencies) + binary "displacements".

7. Trajectory has JSON "metadata" (with atoms and energies) + binary "coords".

8. Bands has JSON "kpath" (with fermi key) + binary "eigenvalues".