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]