vibe-sketcherDocumentation

Source code for vibesketcher.document.porosity_store

"""Porosity estimates stored on a periodic structure, with undo and stale marking (#206).

:func:`store` attaches a reference estimate (:func:`vibesketcher.document.porosity.analyse`)
to its structure's ``provenance["porosity"]`` as one revision-checked edit. The
record keeps the structure's content digest (the digest leaves provenance out, so
storing changes no digest). An estimate whose digest no longer matches its
structure is *stale*: :func:`stored` marks it, :func:`undo` refuses once the
structure changed, and the publication table writers refuse to write it.

Stored estimates travel with the document: in the ``.vsk`` file and in the QVF
document section. QVF has no porosity contract, so the QVF writers also add a
non-critical vendor section ``x_vibesketch.porosity`` (:data:`QVF_KIND`) holding
every stored estimate with its structure digest; :func:`from_qvf` reads it.

Every record is labelled a geometric planning estimate: geometric void is not
adsorption capacity, and no surface area here is a BET surface area.
"""

from __future__ import annotations

import json
import re
from typing import Any

from vibesketcher.document.guest_loading import content_digest
from vibesketcher.document.model import Document, PeriodicStructure
from vibesketcher.document.porosity import (
    LABEL,
    NOTE,
    RESULT_SCHEMA,
    PorosityRefused,
    _refusal,
)

STORE_SCHEMA = "vibesketcher.porosity-store/1"
QVF_KIND = "x_vibesketch.porosity"
KEY = "porosity"
#: Stored estimates one structure may hold.
MAX_STORED = 16
TABLE_LABEL = "geometric planning estimate, not BET/adsorption capacity"
_ID = re.compile(r"^[A-Za-z0-9_.-]{1,40}$")


def _structure(document: Document, identifier: str) -> PeriodicStructure:
    found = {s.id: s for s in document.periodic_structures}
    if identifier not in found:
        raise KeyError(f"periodic structure {identifier!r} not found")
    return found[identifier]


def _entries(structure: PeriodicStructure) -> list[dict[str, Any]]:
    record = structure.provenance.get(KEY)
    if not isinstance(record, dict):
        return []
    entries = record.get("estimates")
    return [dict(e) for e in entries if isinstance(e, dict)] if isinstance(entries, list) else []


[docs] def stored(structure: PeriodicStructure) -> list[dict[str, Any]]: """The stored estimates, oldest first, each marked ``stale`` against the structure now.""" current = content_digest(structure) return [ {**entry, "stale": entry.get("structure_sha256") != current, "current_sha256": current} for entry in _entries(structure) ]
[docs] def summaries(structure: PeriodicStructure) -> list[dict[str, Any]]: """The stored estimates without their full estimate payload.""" return [{k: v for k, v in e.items() if k != "estimate"} for e in stored(structure)]
[docs] def entry(structure: PeriodicStructure, identifier: str | None = None) -> dict[str, Any]: """One stored estimate (the latest when ``identifier`` is None), marked stale or not.""" entries = stored(structure) if not entries: raise PorosityRefused( [_refusal("porosity.no_estimate", f"{structure.id} has no stored estimate")] ) if identifier is None: return entries[-1] for item in entries: if item["id"] == identifier: return item raise KeyError(f"no stored porosity estimate {identifier!r} on {structure.id}")
[docs] def fresh(structure: PeriodicStructure, identifier: str | None = None) -> dict[str, Any]: """A stored estimate that still matches its structure; a stale one is refused.""" item = entry(structure, identifier) if item["stale"]: raise PorosityRefused( [ _refusal( "porosity.stale_estimate", f"estimate {item['id']} was computed for structure digest " f"{str(item['structure_sha256'])[:12]}; {structure.id} has changed since " "(now " + str(item["current_sha256"])[:12] + "); re-run and store it again", ) ] ) return item
def _replace(document: Document, structure: PeriodicStructure) -> Document: """``document`` with ``structure`` replaced in place (the order is kept).""" data = document.to_json_data() data["periodic_structures"] = [ (structure if s.id == structure.id else s).model_dump(mode="json", exclude_none=True) for s in document.periodic_structures ] return Document.model_validate(data) def _check_revision(document: Document, revision: int | None) -> None: if revision is not None and revision != document.revision: raise PorosityRefused( [ _refusal( "porosity.revision_conflict", f"the edit is based on revision {revision}; the document is at " f"{document.revision}", ) ] ) def _with_entries(structure: PeriodicStructure, entries: list[dict[str, Any]]) -> PeriodicStructure: provenance: dict[str, Any] = {k: v for k, v in structure.provenance.items() if k != KEY} if entries: provenance[KEY] = {"schema": STORE_SCHEMA, "estimates": entries} data = structure.model_dump(mode="json", exclude_none=True) data["provenance"] = provenance return PeriodicStructure.model_validate(data)
[docs] def store( document: Document, result: dict[str, Any], *, revision: int | None = None, identifier: str | None = None, ) -> tuple[Document, dict[str, Any]]: """Attach ``result`` to its structure as one undoable edit; returns (document, entry). Refuses (:class:`PorosityRefused`) when ``revision`` is not the document's, when the result belongs to another version of the structure, or when the structure already holds :data:`MAX_STORED` estimates. """ _check_revision(document, revision) if result.get("schema") != RESULT_SCHEMA or not result.get("source", {}).get( "structure_sha256" ): raise ValueError("not a porosity estimate with a structure digest; refusing to store") structure = _structure(document, str(result["source"]["structure"])) digest = content_digest(structure) if result["source"]["structure_sha256"] != digest: raise PorosityRefused( [ _refusal( "porosity.stale_estimate", "the estimate belongs to another version of the structure; re-run it", ) ] ) entries = _entries(structure) if len(entries) >= MAX_STORED: raise PorosityRefused( [ _refusal( "porosity.too_large", f"{structure.id} already holds {MAX_STORED} stored estimates; undo one first", ) ] ) taken = {str(e.get("id")) for e in entries} if identifier is None: k = len(entries) + 1 while f"porosity-{k}" in taken: k += 1 identifier = f"porosity-{k}" elif not _ID.match(identifier): raise ValueError("an estimate id takes 1-40 letters, digits, '.', '_' or '-'") elif identifier in taken: raise ValueError(f"{structure.id} already holds an estimate {identifier!r}") # A JSON round trip both copies the payload and refuses anything not plain JSON. payload = json.loads(json.dumps({k: v for k, v in result.items() if k != "codes"})) plan = result["plan"] item = { "id": identifier, "schema": STORE_SCHEMA, "label": LABEL, "note": NOTE, "structure": structure.id, "structure_sha256": digest, "stored_at_revision": document.revision, "probe": plan["probe"], "surface": plan["surface"], "outcome": result["outcome"]["status"], "estimate": payload, } made = _replace(document, _with_entries(structure, [*entries, item])) return made, {**item, "stale": False, "current_sha256": digest}
[docs] def undo(document: Document, structure_id: str, *, revision: int | None = None) -> Document: """Remove the last stored estimate; refused once the structure changed since.""" _check_revision(document, revision) structure = _structure(document, structure_id) entries = _entries(structure) if not entries: raise PorosityRefused( [_refusal("porosity.nothing_to_undo", f"{structure_id} has no stored estimate")] ) last = entries[-1] if last.get("structure_sha256") != content_digest(structure): raise PorosityRefused( [ _refusal( "porosity.stale_estimate", f"{structure_id} changed after estimate {last.get('id')} was stored; " "undo refused", ) ] ) return _replace(document, _with_entries(structure, entries[:-1]))
# --- QVF vendor section ------------------------------------------------------------------
[docs] def qvf_members(structures: list[PeriodicStructure]) -> dict[str, Any] | None: """The ``x_vibesketch.porosity`` members for these structures, or None when none stores any.""" rows = [] for structure in structures: entries = stored(structure) if entries: rows.append( { "structure": structure.id, "structure_sha256": content_digest(structure), "estimates": entries, } ) if not rows: return None return { "estimates": { "schema": STORE_SCHEMA, "label": TABLE_LABEL, "note": NOTE, "structures": rows, } }
[docs] def from_qvf(data: bytes) -> list[dict[str, Any]]: """The stored estimates of a QVF's ``x_vibesketch.porosity`` section ([] when absent).""" import io from vibesketcher.document.qvf import _modules _, qvf_reader = _modules() with qvf_reader.QvfReader(io.BytesIO(data)) as reader: section = next((s for s in reader.sections if s.get("kind") == QVF_KIND), None) if section is None: return [] payload = reader.read_json(section["members"]["estimates"]) if not isinstance(payload, dict) or payload.get("schema") != STORE_SCHEMA: raise ValueError("the QVF porosity section has an unknown schema") rows = payload.get("structures") return list(rows) if isinstance(rows, list) else []