vibe-sketcherDocumentation

Source code for vibesketcher.inputs.aiccm

"""Explicit AICCM planning for vibe-qc: capabilities, torus record and convergence series (#194).

The ab initio cyclic cluster model (AICCM) replaces Bloch sampling by a finite
Born-von Karman torus of ``N_c = N1 N2 N3`` copies of the input cell. vibe-qc
runs it as ``run_periodic_job(method="aiccm", variant=...)``, and the four
variants are four distinct constructions, not four spellings of one:

- ``real-gamma`` and ``neutral-bloch``: the neutral Gamma-CCM torus in its
  real-Gamma supercell and in its Bloch representation (one Hamiltonian, two
  representations per the engine's Theorem 1, but recorded as two variants
  here and never compared across);
- ``four-center``: bare 1/r on the torus with Wigner-Seitz supercell integral
  weights, the lineage of M. F. Peintinger and T. Bredow, J. Comput. Chem. 35,
  839 (2014), doi:10.1002/jcc.23550: an interaction on the border of the
  Wigner-Seitz supercell (WSSC) that occurs ``n`` times gets the two-centre
  weight ``1/n``; three- and four-centre weights are built from the two-centre
  ones over unions of WSSCs (that paper, "Two-center interactions" and
  Table 1). vibe-qc executes the symmetric torus form of those weights;
- ``chi``: finite translation-group characters on the torus' character mesh;
  for an even order ``N`` the boundary images at ``+/- N/2`` are tied and
  share exact weights (vibe-qc ``periodic.chi.scf``).

What this module owns:

- :data:`CAPABILITIES`, the engine-version-pinned table of what the writer may
  ask for (variant x SCF reference x periodic dimension, plus correlation),
  read from vibe-qc's AICCM manual and ``run_periodic_job`` front door. The
  writer consults it and refuses every row it does not admit; nothing is
  inferred from a nearby row.
- :func:`torus_record`, the convention record written beside every AICCM
  input: torus repeats, the primitive-site to torus-image mapping, the physical
  supercell, the electronic mesh (derived from the torus by the engine), the
  shell control, the energy normalisation and the *interaction weighting* of
  the variant. The weighting is a property of the Hamiltonian; the Wigner-Seitz
  cell the figure renderer draws is a geometric drawing aid and is never read
  as integral weights.
- :func:`plan_series` and :func:`compare_series`, the repeat/shell convergence
  study: one Hamiltonian, a ladder of tori, and a comparison that refuses runs
  whose conventions or engine versions differ. A finite torus is a finite
  torus: no member is ever labelled converged bulk.

AICCM is experimental in vibe-qc; nothing here asserts scientific validity.
"""

from __future__ import annotations

import hashlib
import json
import math
import re
from collections.abc import Sequence
from dataclasses import asdict, dataclass
from typing import Any, Literal

from vibesketcher.document.model import PeriodicStructure
from vibesketcher.elements import ATOMIC_NUMBER
from vibesketcher.inputs.base import InputBundle
from vibesketcher.inputs.vibeqc_periodic import (
    AICCM_DEFAULT_ENGINE,
    AICCMOptions,
    PeriodicJobSpec,
)

__all__ = [
    "AICCMOptions",
    "CAPABILITIES",
    "CONTRACT",
    "Capability",
    "SERIES_SCHEMA",
    "RESULT_SCHEMA",
    "aiccm_refusals",
    "capability",
    "capability_table",
    "compare_series",
    "hamiltonian_identity",
    "plan_series",
    "resolve_reference",
    "resolve_torus",
    "torus_record",
]

Variant = Literal["real-gamma", "neutral-bloch", "four-center", "chi"]
Reference = Literal["RHF", "UHF", "RKS", "UKS", "ROHF", "ROKS"]
Correlation = Literal["mp2", "ccsd", "dlpno-mp2", "dlpno-ccsd"]

VARIANTS: tuple[Variant, ...] = ("real-gamma", "neutral-bloch", "four-center", "chi")
REFERENCES: tuple[Reference, ...] = ("RHF", "UHF", "RKS", "UKS", "ROHF", "ROKS")
CORRELATIONS: tuple[Correlation, ...] = ("mp2", "ccsd", "dlpno-mp2", "dlpno-ccsd")
CHI_BACKENDS = ("four_center", "ri", "rijcosx")

SERIES_SCHEMA = "vibesketcher.aiccm-series/1"
RECORD_SCHEMA = "vibesketcher.aiccm-record/1"
RESULT_SCHEMA = "vibesketcher.aiccm-result/1"

#: Where the table was read and which engine releases it is pinned to. The
#: AICCM front door of 0.18.11 (the release the fleet runs) and 0.18.12 are
#: identical; 0.18.12 only adds the executed exchange_q0 to the manifest.
CONTRACT: dict[str, Any] = {
    "engine": "vibe-qc",
    "versions": ["0.18.11", "0.18.12"],
    "default_version": AICCM_DEFAULT_ENGINE,
    "read_from": [
        "vibe-qc user guide 'AICCM: the ab initio cyclic cluster model' (user_guide/aiccm.md)",
        "vibe-qc run_periodic_job AICCM front door (periodic_runner.py)",
        "vibe-qc periodic.chi.scf cyclic_lattice_extension (torus and shell resolution)",
    ],
    "read_on": "2026-11-11",
    "pending_upstream": [
        "neutral-bloch RHF/RKS on dim = 2 slabs is on vibe-qc main after 0.18.12 "
        "(vibe-qc#1089) and in no release yet; this table refuses it until a pinned "
        "release carries it",
    ],
    "status": "experimental",
}

_SHAPE = {
    "real-gamma": {
        "hamiltonian": "neutral finite torus (Gamma-CCM)",
        "representation": "real-Gamma supercell",
        "interaction_weighting": "none: neutral fitted torus lattice sums, no Wigner-Seitz "
        "integral weights",
        "mesh": "Gamma-centred torus mesh",
        "citation_route": "real-gamma",
    },
    "neutral-bloch": {
        "hamiltonian": "neutral finite torus (Gamma-CCM)",
        "representation": "Bloch on the Gamma-centred torus mesh",
        "interaction_weighting": "none: neutral fitted torus lattice sums, no Wigner-Seitz "
        "integral weights",
        "mesh": "Gamma-centred torus mesh",
        "citation_route": "neutral-bloch",
    },
    "four-center": {
        "hamiltonian": "bare 1/r on the torus (union-and-weight four-centre lineage)",
        "representation": "real-space supercell",
        "interaction_weighting": "Wigner-Seitz supercell integral weights, symmetric BvK-torus "
        "form (two-centre 1/n for n border occurrences; three- and four-centre from "
        "unions of WSSCs; Peintinger and Bredow 2014)",
        "mesh": "Gamma-centred torus mesh",
        "citation_route": "aiccm2026dev-a",
    },
    "chi": {
        "hamiltonian": "chi-defined neutral torus (finite translation-group characters)",
        "representation": "character mesh",
        "interaction_weighting": "character construction; for even N the boundary images at "
        "+/- N/2 are tied and carry exact shared weights",
        "mesh": "Gamma-centred character mesh",
        "citation_route": "aiccm2026dev-b",
    },
}

_CORRELATION: dict[tuple[str, str], tuple[Correlation, ...]] = {
    ("four-center", "RHF"): ("mp2", "ccsd"),
    ("four-center", "UHF"): ("mp2",),
    ("real-gamma", "RHF"): CORRELATIONS,
    ("real-gamma", "UHF"): CORRELATIONS,
    ("neutral-bloch", "RHF"): CORRELATIONS,
    ("neutral-bloch", "UHF"): ("mp2", "dlpno-mp2", "dlpno-ccsd"),
}

#: The energy the engine reports for every variant: the torus total divided by
#: the number of cells, i.e. per *input* cell (which is the primitive cell only
#: when the structure is primitive).
NORMALISATION = "Ha per input cell (torus total / N_c)"


[docs] @dataclass(frozen=True) class Capability: """One row of the pinned table: may the writer ask for this combination?""" variant: str reference: str dim: int admitted: bool correlation: tuple[str, ...] backends: tuple[str, ...] hamiltonian: str representation: str interaction_weighting: str mesh: str reason: str
def _row(variant: Variant, reference: Reference, dim: int) -> Capability: shape = _SHAPE[variant] reason = "" if dim != 3: reason = ( f"vibe-qc {'/'.join(CONTRACT['versions'])} admits AICCM for three-dimensional " "cells only" ) if variant == "neutral-bloch" and dim == 2 and reference in ("RHF", "RKS"): reason += ( "; neutral-bloch RHF/RKS slabs are on vibe-qc main after 0.18.12 " "(vibe-qc#1089), not in a pinned release" ) elif reference == "ROKS": reason = "no AICCM variant admits an ROKS reference" elif reference == "ROHF": reason = ( "chi ROHF needs aiccm_backend='ri', fit_source='classic' and explicit " "chi_coulomb_controls, which this writer does not express" if variant == "chi" else f"{variant} has no restricted open-shell entry" ) admitted = not reason return Capability( variant=variant, reference=reference, dim=dim, admitted=admitted, correlation=_CORRELATION.get((variant, reference), ()) if admitted else (), backends=CHI_BACKENDS if variant == "chi" and admitted else (), hamiltonian=shape["hamiltonian"], representation=shape["representation"], interaction_weighting=shape["interaction_weighting"], mesh=shape["mesh"], reason=reason, ) CAPABILITIES: tuple[Capability, ...] = tuple( _row(v, r, d) for v in VARIANTS for r in REFERENCES for d in (1, 2, 3) )
[docs] def capability(variant: str, reference: str, dim: int) -> Capability | None: """The table row, or None for a variant/reference the table does not know.""" for row in CAPABILITIES: if (row.variant, row.reference, row.dim) == (variant, reference, dim): return row return None
[docs] def capability_table() -> dict[str, Any]: """The pinned table as plain data (SDK, CLI, REST and MCP).""" return { "contract": CONTRACT, "energy_normalisation": NORMALISATION, "variants": {v: dict(_SHAPE[v]) for v in VARIANTS}, "rows": [asdict(row) for row in CAPABILITIES], "notes": [ "correlation= needs a Hartree-Fock reference; chi correlation uses separate " "explicit-source routes this writer does not express", "real-gamma and neutral-bloch are one neutral Hamiltonian in two " "representations; a series never mixes variants", "the Wigner-Seitz cell drawn by the figure renderer is a geometric aid; " "interaction_weighting is the Hamiltonian's and is never read from a drawing", ], }
def _electrons(structure: PeriodicStructure, spec: PeriodicJobSpec) -> tuple[int, int]: charge = spec.charge if spec.charge is not None else structure.charge or 0 electrons = sum(ATOMIC_NUMBER[s.symbol] for s in structure.sites) - charge return electrons, spec.multiplicity or structure.multiplicity or 1
[docs] def resolve_reference(structure: PeriodicStructure, spec: PeriodicJobSpec) -> tuple[str, str]: """The SCF reference vibe-qc will run, and a refusal reason ('' when fine). Mirrors the engine's inference: ``functional=None`` is Hartree-Fock, a functional Kohn-Sham; a singlet with an even electron count is restricted, anything else unrestricted. Explicit ``rhf``/``uhf``/``rohf`` reject a functional and ``roks`` requires one. """ options = spec.aiccm or AICCMOptions() hf = spec.method.lower() == "hf" electrons, multiplicity = _electrons(structure, spec) explicit = options.scf_reference if explicit is None: restricted = multiplicity == 1 and electrons % 2 == 0 return ("R" if restricted else "U") + ("HF" if hf else "KS"), "" if explicit == "roks": return "ROKS", "" if not hf else "scf_reference 'roks' needs a functional" if not hf: return explicit.upper(), f"scf_reference {explicit!r} is Hartree-Fock; drop the functional" if explicit == "rhf" and (multiplicity != 1 or electrons % 2): return "RHF", "scf_reference 'rhf' needs a closed-shell cell" return explicit.upper(), ""
[docs] def resolve_torus( structure: PeriodicStructure, spec: PeriodicJobSpec ) -> tuple[tuple[int, int, int] | None, str]: """The torus repeats (N1, N2, N3), or None with a refusal reason.""" options = spec.aiccm or AICCMOptions() dim = sum(structure.pbc) extension, shells = spec.lattice_extension, options.wigner_seitz_shells if extension is not None and shells is not None: return None, "give lattice_extension or wigner_seitz_shells, not both" if shells is not None: if any(s < 0 for s in shells) or any(shells[a] for a in range(dim, 3)): return None, "wigner_seitz_shells are nonnegative and 0 along nonperiodic axes" repeats = tuple(2 * shells[a] + 1 if a < dim else 1 for a in range(3)) elif extension is not None: if any(n < 1 for n in extension) or any(extension[a] != 1 for a in range(dim, 3)): return None, "lattice_extension entries are >= 1 and 1 along nonperiodic axes" repeats = tuple(extension) else: return None, "AICCM needs a lattice_extension torus such as (2, 2, 2)" if math.prod(repeats) > 4096: return None, "the torus holds more than 4096 cells" return (repeats[0], repeats[1], repeats[2]), ""
[docs] def aiccm_refusals(structure: PeriodicStructure, spec: PeriodicJobSpec) -> list[str]: """Everything in an AICCM request the pinned table does not admit.""" options = spec.aiccm or AICCMOptions() reasons: list[str] = [] dim = sum(structure.pbc) if options.engine_version not in CONTRACT["versions"]: reasons.append( f"no AICCM capability table for vibe-qc {options.engine_version!r}; pinned: " + ", ".join(CONTRACT["versions"]) ) if spec.variant not in VARIANTS: reasons.append(f"AICCM needs variant, one of {', '.join(VARIANTS)}") _, why = resolve_torus(structure, spec) if why: reasons.append(why) if spec.task != "sp": reasons.append("AICCM inputs are single points") reference, why = resolve_reference(structure, spec) if why: reasons.append(why) if spec.variant not in VARIANTS: return reasons row = capability(spec.variant, reference, dim) if row is None or not row.admitted: reasons.append( f"AICCM {spec.variant} {reference} in {dim}D is not admitted: " + (row.reason if row else "not in the table") ) return reasons if options.correlation is not None and options.correlation not in row.correlation: offered = ", ".join(row.correlation) or "none" reasons.append( f"correlation {options.correlation!r} is not admitted on {spec.variant} {reference} " f"(admitted: {offered})" ) if options.backend is not None and options.backend not in row.backends: reasons.append("an AICCM backend is a chi control") return reasons
def _round(x: float) -> float: return round(float(x), 8)
[docs] def hamiltonian_identity(structure: PeriodicStructure, spec: PeriodicJobSpec) -> dict[str, Any]: """Everything that defines the Hamiltonian of one torus member except the torus. Two inputs belong in one convergence series exactly when their identities (and hence :func:`identity_digest`) agree. """ options = spec.aiccm or AICCMOptions() reference, _ = resolve_reference(structure, spec) electrons, multiplicity = _electrons(structure, spec) variant = spec.variant or "" return { "engine": CONTRACT["engine"], "engine_version": options.engine_version, "variant": variant, "scf_reference": reference, "functional": None if spec.method.lower() == "hf" else spec.method.lower(), "basis": (spec.basis or "").lower(), "correlation": options.correlation, "backend": options.backend, "electrons_per_cell": electrons, "multiplicity": multiplicity, "max_iter": spec.max_iter, "interaction_weighting": _SHAPE.get(variant, {}).get("interaction_weighting"), "energy_normalisation": NORMALISATION, "cell": { "setting": structure.cell_setting, "lattice_angstrom": [[_round(x) for x in row] for row in structure.lattice_angstrom], "pbc": list(structure.pbc), "sites": [[s.symbol, *(_round(x) for x in s.fractional)] for s in structure.sites], }, }
def identity_digest(identity: dict[str, Any]) -> str: text = json.dumps(identity, sort_keys=True, separators=(",", ":")) return hashlib.sha256(text.encode()).hexdigest() def _formula_units(structure: PeriodicStructure) -> tuple[str, int]: counts: dict[str, int] = {} for site in structure.sites: counts[site.symbol] = counts.get(site.symbol, 0) + 1 z = math.gcd(*counts.values()) formula = "".join(f"{el}{'' if n // z == 1 else n // z}" for el, n in sorted(counts.items())) return formula, z _SITE_MAP_LIMIT = 20000
[docs] def torus_record(structure: PeriodicStructure, spec: PeriodicJobSpec) -> dict[str, Any]: """The convention record of one admitted AICCM input (call after the refusals).""" options = spec.aiccm or AICCMOptions() repeats, why = resolve_torus(structure, spec) if repeats is None: raise ValueError(why) dim = sum(structure.pbc) n_cells = math.prod(repeats) variant = spec.variant or "" shape = _SHAPE[variant] formula, z = _formula_units(structure) identity = hamiltonian_identity(structure, spec) images = [ (i, j, k) for i in range(repeats[0]) for j in range(repeats[1]) for k in range(repeats[2]) ] site_map: dict[str, Any] = { "convention": "supercell site '<site>@n1,n2,n3' at fractional (f + n) / N; " "image (0, 0, 0) is the input cell", "sites_per_cell": len(structure.sites), "sites_in_torus": len(structure.sites) * n_cells, } if len(structure.sites) * n_cells <= _SITE_MAP_LIMIT: site_map["images"] = { s.id: [f"{s.id}@{i},{j},{k}" for i, j, k in images] for s in structure.sites } else: site_map["images"] = None site_map["omitted"] = f"more than {_SITE_MAP_LIMIT} torus sites; use the convention" supercell = [ [_round(x * repeats[a]) for x in row] for a, row in enumerate(structure.lattice_angstrom) ] reference, _ = resolve_reference(structure, spec) return { "schema": RECORD_SCHEMA, "status": "experimental; a finite torus, not converged bulk", "contract": { "engine": CONTRACT["engine"], "pinned_versions": CONTRACT["versions"], "written_for": options.engine_version, }, "variant": variant, "scf_reference": reference, "correlation": options.correlation, "backend": options.backend, "hamiltonian": shape["hamiltonian"], "representation": shape["representation"], "citation_route": shape["citation_route"], "torus": { "repeats": list(repeats), "n_cells": n_cells, "control": "wigner_seitz_shells" if options.wigner_seitz_shells else "lattice_extension", "wigner_seitz_shells": ( list(options.wigner_seitz_shells) if options.wigner_seitz_shells else None ), "periodic_dimension": dim, }, "input_cell": { "setting": structure.cell_setting, "formula": formula, "formula_units": z, "lattice_angstrom": [list(row) for row in structure.lattice_angstrom], }, "physical_supercell": {"lattice_angstrom": supercell}, "site_mapping": site_map, "electronic_mesh": { "kind": shape["mesh"], "shape": list(repeats), "independent": False, "note": "vibe-qc derives the mesh from the torus; a kpoints mesh beside the " "torus is refused", }, "interaction_weighting": shape["interaction_weighting"], "geometric_wigner_seitz_figure": "drawing aid only; never read as integral weights", "energy_normalisation": NORMALISATION, "hamiltonian_identity": identity, "hamiltonian_digest": identity_digest(identity), }
def _torus_tag(repeats: Sequence[int]) -> str: return "t" + "x".join(str(n) for n in repeats)
[docs] def plan_series( structure: PeriodicStructure, spec: PeriodicJobSpec, *, extensions: Sequence[Sequence[int]] | None = None, shells: Sequence[Sequence[int]] | None = None, ) -> tuple[dict[str, Any], InputBundle]: """A repeat/shell convergence series: one Hamiltonian, two or more tori. Every member is the same ``spec`` with only the torus changed, written by the fail-closed periodic writer. The plan records the shared Hamiltonian identity; :func:`compare_series` refuses results that do not carry it. """ from vibesketcher.inputs.base import InputFile, WriterRefusal from vibesketcher.inputs.vibeqc_periodic import write_periodic_input if spec.model != "aiccm": raise WriterRefusal("vibeqc-periodic", ["a torus series is an AICCM study"]) if (extensions is None) == (shells is None): raise WriterRefusal("vibeqc-periodic", ["give the series as extensions or as shells"]) ladder = [tuple(int(n) for n in m) for m in (extensions if extensions is not None else shells)] # type: ignore[union-attr] if len(ladder) < 2 or len(ladder) > 12: raise WriterRefusal("vibeqc-periodic", ["a series has 2 to 12 tori"]) options = spec.aiccm or AICCMOptions() members: list[dict[str, Any]] = [] files: list[InputFile] = [] seen: set[tuple[int, ...]] = set() digest = "" for step in ladder: if len(step) != 3: raise WriterRefusal("vibeqc-periodic", ["each torus has three entries"]) member_options = options.model_copy( update={"wigner_seitz_shells": step if shells is not None else None} ) member = spec.model_copy( update={ "lattice_extension": step if extensions is not None else None, "aiccm": member_options, } ) bundle = write_periodic_input(structure, member) record = torus_record(structure, member) repeats = tuple(record["torus"]["repeats"]) if repeats in seen: raise WriterRefusal("vibeqc-periodic", [f"torus {repeats} appears twice"]) seen.add(repeats) if digest and record["hamiltonian_digest"] != digest: # pragma: no cover - by design raise WriterRefusal("vibeqc-periodic", ["series members differ in the Hamiltonian"]) digest = record["hamiltonian_digest"] files += bundle.files members.append( { "torus": list(repeats), "n_cells": record["torus"]["n_cells"], "script": bundle.files[0].name, "result": bundle.files[0].name.removesuffix(".py") + ".aiccm-result.json", } ) members.sort(key=lambda m: (m["n_cells"], m["torus"])) plan = { "schema": SERIES_SCHEMA, "status": "experimental; finite-torus differences, not a converged-bulk claim", "structure": structure.id, "control": "wigner_seitz_shells" if shells is not None else "lattice_extension", "spec": spec.model_dump(mode="json"), "hamiltonian_digest": digest, "hamiltonian_identity": hamiltonian_identity(structure, spec), "energy_normalisation": NORMALISATION, "members": members, } stem = re.sub(r"[^A-Za-z0-9_.-]+", "-", f"{structure.id}-aiccm-series") files.append(InputFile(f"{stem}.json", json.dumps(plan, indent=1) + "\n", "application/json")) return plan, InputBundle(program="vibeqc", species=structure.id, files=tuple(files))
[docs] def compare_series(plan: dict[str, Any], results: Sequence[dict[str, Any]]) -> dict[str, Any]: """Tabulate a finished series, or raise ValueError naming every mismatch. A comparison is refused when any result was computed under another Hamiltonian identity, another engine version, another normalisation or another variant than the plan, when a torus is missing, foreign or repeated, or when a run did not converge. """ if plan.get("schema") != SERIES_SCHEMA: raise ValueError(f"not an AICCM series plan (schema {SERIES_SCHEMA})") digest = plan.get("hamiltonian_digest") identity = plan.get("hamiltonian_identity") or {} planned = {tuple(m["torus"]): m for m in plan.get("members", [])} reasons: list[str] = [] by_torus: dict[tuple[int, ...], dict[str, Any]] = {} versions: set[str] = set() for index, result in enumerate(results): label = f"result {index + 1}" if result.get("schema") != RESULT_SCHEMA: reasons.append(f"{label} is not an AICCM result ({RESULT_SCHEMA})") continue torus = tuple(int(n) for n in result.get("torus", ())) label = f"result {_torus_tag(torus)}" if result.get("hamiltonian_digest") != digest: reasons.append(f"{label} was computed under another Hamiltonian or convention") if result.get("energy_normalisation") != plan.get("energy_normalisation"): reasons.append(f"{label} uses another energy normalisation") if result.get("variant") != identity.get("variant"): reasons.append(f"{label} ran variant {result.get('variant')!r}") version = str(result.get("engine_version_executed")) versions.add(version) if version != identity.get("engine_version"): reasons.append( f"{label} ran on vibe-qc {version}, planned {identity['engine_version']}" ) if torus not in planned: reasons.append(f"{label} is not a planned torus") elif torus in by_torus: reasons.append(f"{label} appears twice") if not result.get("converged"): reasons.append(f"{label} did not converge") energy = result.get("energy_per_cell_ha") if not isinstance(energy, (int, float)) or not math.isfinite(energy): reasons.append(f"{label} has no finite energy") by_torus[torus] = result if len(versions) > 1: reasons.append( "results come from different vibe-qc versions: " + ", ".join(sorted(versions)) ) missing = [t for t in planned if t not in by_torus] if len(by_torus) < 2: reasons.append("a comparison needs at least two finished tori") if reasons: raise ValueError("cannot compare this series: " + "; ".join(reasons)) order = sorted(by_torus, key=lambda t: (math.prod(t), t)) largest = float(by_torus[order[-1]]["energy_per_cell_ha"]) rows: list[dict[str, Any]] = [] previous: float | None = None for torus in order: energy = float(by_torus[torus]["energy_per_cell_ha"]) rows.append( { "torus": list(torus), "n_cells": math.prod(torus), "energy_per_cell_ha": energy, "delta_previous_ha": None if previous is None else energy - previous, "delta_largest_ha": energy - largest, } ) previous = energy return { "status": "experimental; finite-torus differences, not a converged-bulk claim", "variant": identity.get("variant"), "engine_version": versions.pop(), "hamiltonian_digest": digest, "energy_normalisation": plan.get("energy_normalisation"), "rows": rows, "missing": [list(t) for t in missing], }