vibe-sketcherDocumentation
Source code for vibesketcher.document.diffraction_store
"""Measured and calculated powder patterns stored in a document, with undo (#207).
:func:`store_measured` keeps a pattern read by
:func:`vibesketcher.document.measured_patterns.read_measured` (digest of the original
bytes, stated axis, intensity unit and wavelength, instrument fields and header lines as
given, and the points); :func:`store_calculated` keeps a
:func:`vibesketcher.document.diffraction.calculate` result with its structure's digest.
Both are one edit checked against the document revision; :func:`undo` removes the last
stored pattern and :func:`remove` any one. The records live in the document's
``diffraction_patterns`` list (:class:`vibesketcher.document.diffraction_model.DiffractionPattern`),
so they travel in the ``.vsk`` file and the QVF document section; the QVF writers also add a
non-critical vendor section ``x_vibesketch.diffraction`` (:data:`QVF_KIND`), because QVF has
no diffraction contract, and :func:`from_qvf` reads it.
A calculated pattern is *stale* once its structure changed or was removed. :func:`stored`
marks it; overlays, comparisons and CSV exports refuse it (re-calculate and store again).
Overlays and comparisons of stored patterns use the same wavelength rule as
:mod:`vibesketcher.render.diffraction`: a measured 2theta axis is compared in 2theta only at
the calculated wavelength. Nothing here fits or refines; the display scale is not a fit.
"""
from __future__ import annotations
import json
from typing import Any
from vibesketcher.document.diffraction import structure_digest
from vibesketcher.document.diffraction_model import (
MAX_DOCUMENT_POINTS,
MAX_PATTERNS,
MAX_STORED_POINTS,
MAX_STORED_REFLECTIONS,
DiffractionPattern,
)
from vibesketcher.document.model import Document
STORE_SCHEMA = "vibesketcher.diffraction-store/1"
QVF_KIND = "x_vibesketch.diffraction"
_PROFILE_ARRAYS = ("two_theta_deg", "intensity")
[docs]
class DiffractionStoreRefused(ValueError):
"""A stored-pattern edit or read cannot be done faithfully; ``code`` says why."""
def __init__(self, code: str, message: str) -> None:
super().__init__(message)
self.code = code
def _check_revision(document: Document, revision: int | None) -> None:
if revision is not None and revision != document.revision:
raise DiffractionStoreRefused(
"diffraction.revision_conflict",
f"the edit is based on revision {revision}; the document is at {document.revision}",
)
def _with_patterns(document: Document, patterns: list[DiffractionPattern]) -> Document:
data = document.to_json_data()
data["diffraction_patterns"] = [p.model_dump(mode="json", exclude_none=True) for p in patterns]
return Document.model_validate(data)
def _new_id(document: Document, identifier: str | None, prefix: str) -> str:
taken = {p.id for p in document.diffraction_patterns}
if identifier is not None:
if identifier in taken:
raise ValueError(f"the document already holds a pattern {identifier!r}")
return identifier
k = 1
while f"{prefix}-{k}" in taken:
k += 1
return f"{prefix}-{k}"
def _room(document: Document, points: int) -> None:
if len(document.diffraction_patterns) >= MAX_PATTERNS:
raise DiffractionStoreRefused(
"diffraction.too_large",
f"the document already holds {MAX_PATTERNS} stored patterns; remove one first",
)
if points > MAX_STORED_POINTS:
raise DiffractionStoreRefused(
"diffraction.too_large",
f"{points} points exceed the {MAX_STORED_POINTS} a stored pattern may hold; "
"crop or rebin the data first",
)
total = points + sum(len(p.x) for p in document.diffraction_patterns)
if total > MAX_DOCUMENT_POINTS:
raise DiffractionStoreRefused(
"diffraction.too_large",
f"the stored patterns would hold {total} points; at most {MAX_DOCUMENT_POINTS}",
)
[docs]
def store_measured(
document: Document,
measured: dict[str, Any],
*,
revision: int | None = None,
identifier: str | None = None,
label: str | None = None,
) -> tuple[Document, dict[str, Any]]:
"""Keep a :func:`read_measured` result in the document; returns (document, summary)."""
_check_revision(document, revision)
if measured.get("kind") != "measured_powder_pattern" or "provenance" not in measured:
raise ValueError("not a measured powder pattern with provenance; refusing to store")
prov = measured["provenance"]
_room(document, len(measured["x"]))
pattern = DiffractionPattern(
id=_new_id(document, identifier, "measured"),
kind="measured",
label=label,
axis=prov["axis"],
intensity_unit=prov["intensity_unit"],
wavelength_angstrom=prov.get("wavelength_angstrom"),
x=list(measured["x"]),
intensity=list(measured["intensity"]),
esd=list(measured["esd"]) if measured.get("esd") else None,
measured={
k: prov[k]
for k in (
"file_name",
"sha256",
"bytes",
"encoding",
"format",
"instrument",
"sample",
"header",
"columns",
)
},
stored_at_revision=document.revision,
)
made = _with_patterns(document, [*document.diffraction_patterns, pattern])
return made, summary(made, pattern)
[docs]
def store_calculated(
document: Document,
result: dict[str, Any],
*,
revision: int | None = None,
identifier: str | None = None,
label: str | None = None,
) -> tuple[Document, dict[str, Any]]:
"""Keep a calculated pattern of one of the document's structures, with its digest."""
_check_revision(document, revision)
source = result.get("source") or {}
if result.get("kind") != "calculated_powder_pattern":
raise ValueError("not a calculated powder pattern; refusing to store")
if source.get("kind") != "periodic_structure":
raise DiffractionStoreRefused(
"diffraction.unlinked",
"only a pattern of one of the document's periodic structures is stored (it is "
"linked to the structure digest); import the CIF as a structure first",
)
found = {s.id: s for s in document.periodic_structures}
structure = found.get(str(source.get("structure")))
if structure is None:
raise KeyError(f"periodic structure {source.get('structure')!r} not found")
digest = structure_digest(structure)
if source.get("structure_sha256") != digest:
raise DiffractionStoreRefused(
"diffraction.stale_pattern",
"the pattern belongs to another version of the structure; re-calculate it",
)
if len(result["reflections"]) > MAX_STORED_REFLECTIONS:
raise DiffractionStoreRefused(
"diffraction.too_large",
f"{len(result['reflections'])} reflections exceed the {MAX_STORED_REFLECTIONS} a "
"stored pattern may hold; narrow the 2theta range",
)
profile = result.get("profile")
x = list(profile["two_theta_deg"]) if profile else []
_room(document, len(x))
# 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 != "profile"}))
if profile:
payload["profile"] = {k: v for k, v in profile.items() if k not in _PROFILE_ARRAYS}
pattern = DiffractionPattern(
id=_new_id(document, identifier, "calculated"),
kind="calculated",
label=label,
axis="two_theta_deg",
intensity_unit="relative",
wavelength_angstrom=float(result["wavelength_angstrom"]),
x=x,
intensity=list(profile["intensity"]) if profile else [],
structure=structure.id,
structure_sha256=digest,
result=payload,
stored_at_revision=document.revision,
)
made = _with_patterns(document, [*document.diffraction_patterns, pattern])
return made, summary(made, pattern)
def _stale(document: Document, pattern: DiffractionPattern) -> tuple[bool, str | None, str | None]:
"""(stale, reason, the structure's digest now) of a pattern."""
if pattern.kind == "measured":
return False, None, None
found = {s.id: s for s in document.periodic_structures}
structure = found.get(str(pattern.structure))
if structure is None:
return True, f"structure {pattern.structure} no longer exists", None
current = structure_digest(structure)
if current != pattern.structure_sha256:
return True, f"structure {pattern.structure} changed since the pattern was stored", current
return False, None, current
[docs]
def summary(document: Document, pattern: DiffractionPattern) -> dict[str, Any]:
"""A stored pattern without its points or reflections, marked stale or current."""
stale, reason, current = _stale(document, pattern)
record: dict[str, Any] = {
"id": pattern.id,
"kind": pattern.kind,
"label": pattern.label,
"axis": pattern.axis,
"intensity_unit": pattern.intensity_unit,
"wavelength_angstrom": pattern.wavelength_angstrom,
"points": len(pattern.x),
"x_range": [min(pattern.x), max(pattern.x)] if pattern.x else None,
"stored_at_revision": pattern.stored_at_revision,
"stale": stale,
"stale_reason": reason,
}
if pattern.measured is not None:
record["measured"] = pattern.measured.model_dump(mode="json")
record["has_esd"] = pattern.esd is not None
if pattern.result is not None:
reflections = pattern.result.get("reflections")
record.update(
structure=pattern.structure,
structure_sha256=pattern.structure_sha256,
current_sha256=current,
reflections=len(reflections) if isinstance(reflections, list) else 0,
settings=pattern.result.get("settings"),
)
return record
[docs]
def stored(document: Document) -> list[dict[str, Any]]:
"""Summaries of every stored pattern, oldest first."""
return [summary(document, p) for p in document.diffraction_patterns]
[docs]
def get(document: Document, identifier: str) -> DiffractionPattern:
"""The stored pattern ``identifier``; ``KeyError`` when there is none."""
for pattern in document.diffraction_patterns:
if pattern.id == identifier:
return pattern
raise KeyError(f"no stored diffraction pattern {identifier!r}")
[docs]
def record(document: Document, identifier: str) -> dict[str, Any]:
"""One stored pattern in full (points, reflections), marked stale or current."""
pattern = get(document, identifier)
return {
**summary(document, pattern),
"pattern": pattern.model_dump(mode="json", exclude_none=True),
}
[docs]
def fresh(document: Document, identifier: str) -> DiffractionPattern:
"""A stored pattern that still matches its structure; a stale one is refused."""
pattern = get(document, identifier)
stale, reason, _ = _stale(document, pattern)
if stale:
raise DiffractionStoreRefused(
"diffraction.stale_pattern",
f"calculated pattern {identifier} is stale ({reason}); re-calculate and store it",
)
return pattern
[docs]
def remove(document: Document, identifier: str, *, revision: int | None = None) -> Document:
"""The document without the stored pattern ``identifier`` (stale or not)."""
_check_revision(document, revision)
get(document, identifier)
return _with_patterns(
document, [p for p in document.diffraction_patterns if p.id != identifier]
)
[docs]
def undo(document: Document, *, revision: int | None = None) -> Document:
"""Remove the last stored pattern; refused for a calculated one gone stale since."""
_check_revision(document, revision)
if not document.diffraction_patterns:
raise DiffractionStoreRefused("diffraction.nothing_to_undo", "no stored pattern to undo")
last = document.diffraction_patterns[-1]
if _stale(document, last)[0]:
raise DiffractionStoreRefused(
"diffraction.stale_pattern",
f"the structure changed after pattern {last.id} was stored; undo refused (remove "
"it by id instead)",
)
return _with_patterns(document, document.diffraction_patterns[:-1])
# --- Back to the reader's and the calculator's shapes ------------------------------------
[docs]
def as_measured(pattern: DiffractionPattern) -> dict[str, Any]:
"""A stored measured pattern in the shape :func:`read_measured` returns."""
if pattern.measured is None:
raise ValueError(f"pattern {pattern.id} is not a measured pattern")
provenance = {
**pattern.measured.model_dump(mode="json"),
"axis": pattern.axis,
"intensity_unit": pattern.intensity_unit,
"wavelength_angstrom": pattern.wavelength_angstrom,
"points": len(pattern.x),
"x_range": [min(pattern.x), max(pattern.x)],
"has_esd": pattern.esd is not None,
"stored_pattern": pattern.id,
}
return {"kind": "measured_powder_pattern", "x": list(pattern.x),
"intensity": list(pattern.intensity), "esd": pattern.esd,
"provenance": provenance} # fmt: skip
[docs]
def as_calculated(document: Document, identifier: str) -> dict[str, Any]:
"""A current stored calculated pattern in the shape :func:`calculate` returns."""
pattern = fresh(document, identifier)
if pattern.result is None:
raise ValueError(f"pattern {identifier} is not a calculated pattern")
result: dict[str, Any] = json.loads(json.dumps(pattern.result))
if "profile" in result:
result["profile"] = {
**result["profile"],
"two_theta_deg": list(pattern.x),
"intensity": list(pattern.intensity),
}
result["source"] = {**result.get("source", {}), "stored_pattern": pattern.id}
return result
def _measured_of(document: Document, identifier: str) -> dict[str, Any]:
pattern = get(document, identifier)
if pattern.kind != "measured":
raise ValueError(f"pattern {identifier} is calculated; give a measured pattern")
return as_measured(pattern)
[docs]
def overlay(
document: Document,
calculated: str | dict[str, Any],
measured: str | None = None,
options: Any = None,
fmt: str = "svg",
*,
dpi: int = 300,
) -> bytes:
"""The overlay figure of stored patterns (no re-upload).
``calculated`` is a stored calculated pattern id or a fresh :func:`calculate` result;
``measured`` a stored measured pattern id. The wavelength rule and the formats are
those of :func:`vibesketcher.render.diffraction.overlay_figure`.
"""
from vibesketcher.render.diffraction import overlay_figure
calc = as_calculated(document, calculated) if isinstance(calculated, str) else calculated
meas = _measured_of(document, measured) if measured is not None else None
return overlay_figure(calc, meas, options, fmt, dpi=dpi)
[docs]
def comparison(
document: Document,
measured: str,
calculated: str | dict[str, Any],
axis: str = "two_theta_deg",
) -> dict[str, Any]:
"""Which reflections fall in the measured range, on one axis, with both provenances.
A pairing record, not a fit: no agreement factor is computed, and agreement would
not show the structure is unique. Refused like the overlay when a 2theta comparison
has a mismatched or unstated measured wavelength.
"""
from vibesketcher.document.measured_patterns import AXES
from vibesketcher.render.diffraction import _measured_x
if axis not in AXES:
raise ValueError(f"unknown axis {axis!r}; one of {', '.join(AXES)}")
calc = as_calculated(document, calculated) if isinstance(calculated, str) else calculated
meas = _measured_of(document, measured)
wavelength = float(calc["wavelength_angstrom"])
mx = _measured_x(meas, axis, wavelength)
lo, hi = min(mx), max(mx)
inside = [r for r in calc["reflections"] if lo <= float(r[axis]) <= hi]
return {
"kind": "powder_pattern_comparison",
"axis": axis,
"measured": {"id": measured, **meas["provenance"]},
"calculated": {
"source": calc.get("source"),
"wavelength_angstrom": wavelength,
"wavelength_source": calc.get("wavelength_source"),
"reflections": len(calc["reflections"]),
},
"measured_range": [lo, hi],
"reflections_in_range": [
{"hkl": r["hkl"], axis: r[axis], "relative_intensity": r["relative_intensity"]}
for r in inside
],
"note": "positions only; no fit, agreement factor or refinement, and agreement would "
"not show that the structure is unique",
}
# --- CSV export ---------------------------------------------------------------------------
[docs]
def pattern_csv(document: Document, identifier: str) -> str:
"""A stored pattern as CSV with a provenance header; a stale calculated one is refused.
A measured pattern writes its points (x, intensity and esd when present); a calculated
one its profile curve when stored with one, else its reflection list.
"""
from vibesketcher.document.diffraction import reflections_csv
pattern = fresh(document, identifier)
wl = pattern.wavelength_angstrom
lines = [
f"# vibe-sketcher stored powder pattern {pattern.id} ({pattern.kind})",
f"# axis {pattern.axis}; intensity {pattern.intensity_unit}; wavelength "
+ (f"{wl:.7f} A" if wl is not None else "not stated"),
]
if pattern.label:
lines.append(f"# label {pattern.label}")
if pattern.measured is not None:
src = pattern.measured
lines.append(f"# measured file {src.file_name}; sha256 {src.sha256}; {src.bytes} bytes; "
f"{src.format}, {src.encoding}") # fmt: skip
lines += [f"# instrument {k}: {v}" for k, v in src.instrument.items()]
if src.sample:
lines.append(f"# sample {src.sample}")
lines += [f"# original header: {h}" for h in src.header]
columns = ["x", "intensity", *(["esd"] if pattern.esd is not None else [])]
lines.append(",".join(columns))
for i, (x, y) in enumerate(zip(pattern.x, pattern.intensity, strict=True)):
row = f"{x!r},{y!r}"
if pattern.esd is not None:
row += f",{pattern.esd[i]!r}"
lines.append(row)
return "\n".join(lines) + "\n"
lines.append(f"# structure {pattern.structure}; sha256 {pattern.structure_sha256}")
result = as_calculated(document, identifier)
if not pattern.x:
return "\n".join(lines) + "\n" + reflections_csv(result)
lines.append(f"# {result['polarisation']}; form factors: {result['form_factors']}")
lines.append(f"# settings {json.dumps(result.get('settings', {}), sort_keys=True)}")
lines.append(f"# profile normalised {result['profile'].get('normalised')}; no background")
lines.append("two_theta_deg,relative_intensity")
lines += [f"{x!r},{y!r}" for x, y in zip(pattern.x, pattern.intensity, strict=True)]
return "\n".join(lines) + "\n"
# --- QVF vendor section -----------------------------------------------------------------
[docs]
def qvf_members(document: Document, structures: set[str] | None = None) -> dict[str, Any] | None:
"""The ``x_vibesketch.diffraction`` members, or None when nothing is stored.
``structures`` limits the section to the calculated patterns of those structures (a
single-structure QVF); measured patterns then stay out.
"""
patterns = [
p
for p in document.diffraction_patterns
if structures is None or (p.structure is not None and p.structure in structures)
]
if not patterns:
return None
rows = [
{**summary(document, p), "pattern": p.model_dump(mode="json", exclude_none=True)}
for p in patterns
]
return {
"patterns": {
"schema": STORE_SCHEMA,
"note": "stored powder patterns; measured provenance names the original bytes by "
"SHA-256, calculated patterns name their structure digest; no fit or refinement",
"patterns": rows,
}
}
[docs]
def from_qvf(data: bytes) -> list[DiffractionPattern]:
"""The stored patterns of a QVF's ``x_vibesketch.diffraction`` 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"]["patterns"])
if not isinstance(payload, dict) or payload.get("schema") != STORE_SCHEMA:
raise ValueError("the QVF diffraction section has an unknown schema")
rows = payload.get("patterns")
if not isinstance(rows, list):
raise ValueError("the QVF diffraction section has no pattern list")
return [DiffractionPattern.model_validate(row["pattern"]) for row in rows]