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 []