vibe-sketcherDocumentation

Source code for vibesketcher.document.displacements

"""Carrying measured displacement tensors through structure edits (#199).

CIF import keeps anisotropic displacement tensors (``_atom_site_aniso`` U, B
or beta) in ``provenance["displacement_parameters"]``, keyed by site ID and
stamped with the cell rows they refer to (``cell_angstrom``). Every edit that
derives a structure from such a parent either transforms the record or
refuses:

* Relabelling, lattice translations, supercells and other re-expressions of
  the same crystal in the same Cartesian frame (primitive, conventional,
  standard, Niggli/Delaunay-reduced and setting-transformed cells) leave the
  Cartesian tensor of each atom unchanged; only the site keys are mapped
  through the new site map (:func:`carry`, :func:`carry_by_position`).
* A rotation R of the Cartesian frame (a slab cut, a rigid rotation of
  selected sites) maps U_cart -> R U_cart R^T (R. W. Grosse-Kunstleve and
  P. D. Adams, J. Appl. Cryst. 35, 477 (2002), Section 2).
* A strain or deformation of the periodic cell, symmetry idealisation of the
  metric, or a change of the element on a measured site is not a symmetry of
  the measurement: the tensors are not physically transferable, and the edit
  is refused (:func:`refuse`) until the caller drops them explicitly with
  :func:`drop`, which records the reason and the dropped record in
  ``provenance["displacement_parameters_dropped"]``.

The model itself refuses a record whose site keys or cell no longer match the
structure (``model._check_displacement_record``), so an edit that copies the
record without passing through here fails instead of keeping stale tensors.
"""

from __future__ import annotations

from collections.abc import Mapping
from datetime import UTC, datetime
from typing import Any

import numpy as np

from vibesketcher.document import crystal
from vibesketcher.document.model import Document, PeriodicStructure

KEY = "displacement_parameters"
DROPPED_KEY = "displacement_parameters_dropped"
REFERENCE = "R. W. Grosse-Kunstleve and P. D. Adams, J. Appl. Cryst. 35, 477 (2002)"


[docs] def has_tensors(structure: PeriodicStructure) -> bool: return structure.provenance.get(KEY) is not None
[docs] def tensors(structure: PeriodicStructure) -> tuple[str, dict[str, np.ndarray]] | None: """(convention, {site: U_cart in angstrom^2}) of the recorded tensors, or None.""" from vibesketcher.document.symmetry_ops import displacement_tensors return displacement_tensors(structure)
[docs] def stamped(structure: PeriodicStructure) -> dict[str, Any]: """The cell the record of ``structure`` refers to (its own lattice rows).""" rows = structure.lattice_angstrom return {"cell_angstrom": [[crystal._clean(x) for x in row] for row in rows]}
def _with_record( parent: PeriodicStructure, child: PeriodicStructure, convention: str, cartesian: dict[str, np.ndarray], how: str, ) -> PeriodicStructure: from vibesketcher.document.symmetry_ops import _six, from_cartesian previous = parent.provenance.get(KEY) base: dict[str, Any] = dict(previous) if isinstance(previous, dict) else {} lattice = crystal.lattice_rows(child) unmeasured = sorted(s.id for s in child.sites if s.id not in cartesian) base.update( convention=convention, sites={k: _six(from_cartesian(v, convention, lattice)) for k, v in cartesian.items()}, transformed=how, derived_from=parent.id, reference=REFERENCE, **stamped(child), ) if unmeasured: base["unmeasured_sites"] = unmeasured else: base.pop("unmeasured_sites", None) provenance = dict(child.provenance) provenance[KEY] = crystal._json(base) return child.model_copy(update={"provenance": provenance}) def _keep_drop_marker(parent: PeriodicStructure, child: PeriodicStructure) -> PeriodicStructure: marker = parent.provenance.get(DROPPED_KEY) if marker is None or child.provenance.get(DROPPED_KEY) is not None: return child return child.model_copy(update={"provenance": {**child.provenance, DROPPED_KEY: marker}})
[docs] def carry( parent: PeriodicStructure, child: PeriodicStructure, site_map: Mapping[str, str], *, how: str, rotation: np.ndarray | None = None, rotations: Mapping[str, np.ndarray] | None = None, ) -> PeriodicStructure: """``child`` with the parent's tensors mapped through ``site_map`` (child -> parent ID). ``rotation`` is the proper Cartesian rotation R (column vectors, x' = R x) taking the parent's frame to the child's; U' = R U R^T. Without it the frames coincide and U is copied. ``rotations`` gives a rotation for single child sites instead (a rigid rotation of a selection). Child sites without a measured parent (added atoms) are listed as ``unmeasured_sites``. """ found = tensors(parent) if found is None: return _keep_drop_marker(parent, child) convention, by_site = found default = np.eye(3) if rotation is None else np.asarray(rotation, dtype=float) every = [default, *(np.asarray(r, dtype=float) for r in (rotations or {}).values())] if any(not np.allclose(r @ r.T, np.eye(3), atol=1e-8) or np.linalg.det(r) < 0 for r in every): raise ValueError("displacement tensors are carried only by a proper rotation") ids = {s.id for s in child.sites} out = {} for new, old in site_map.items(): if new in ids and old in by_site: r = np.asarray((rotations or {}).get(new, default), dtype=float) out[new] = r @ by_site[old] @ r.T if not out: refuse(parent, "this edit (no measured site survives it)") return _with_record(parent, child, convention, out, how)
def _translations(parent: PeriodicStructure, vectors: np.ndarray, tolerance: float) -> bool: """Whether every Cartesian vector maps the parent crystal onto itself.""" lattice = crystal.lattice_rows(parent) inverse = np.linalg.inv(lattice) frac = np.asarray([s.fractional for s in parent.sites], dtype=float) symbols = np.asarray([s.symbol for s in parent.sites]) periodic = np.asarray(parent.pbc) for vector in vectors: step = vector @ inverse if np.any(np.abs(step[~periodic]) > tolerance / 10): return False for start in range(0, len(frac), 256): # bounded memory: 256 x N pairs at a time moved = frac[start : start + 256] + step delta = frac[None, :, :] - moved[:, None, :] delta[..., periodic] -= np.round(delta[..., periodic]) distance = np.linalg.norm(delta @ lattice, axis=-1) same = symbols[start : start + 256, None] == symbols[None, :] if not np.all(np.any((distance < tolerance) & same, axis=1)): return False return True
[docs] def site_map_by_position( parent: PeriodicStructure, child: PeriodicStructure, *, tolerance: float = 1e-3, rotation: np.ndarray | None = None, origin: np.ndarray | None = None, translate: bool = False, ) -> dict[str, str] | None: """child -> parent site IDs when ``child`` re-expresses the parent crystal, else None. Each child atom must coincide (within ``tolerance`` angstrom, same element) with a parent atom or one of its lattice images after x -> R^T x - origin (``translate=True`` searches the rigid origin shift), and each periodic child cell vector must be a translation of the parent crystal, which excludes any strain of the cell. Cartesian U is invariant under the translation. """ lattice = crystal.lattice_rows(parent) inverse = np.linalg.inv(lattice) r = np.eye(3) if rotation is None else np.asarray(rotation, dtype=float) rows = crystal.lattice_rows(child)[list(child.pbc)] @ r # row form of R^T v if not _translations(parent, rows, tolerance): return None frac = np.asarray([s.fractional for s in parent.sites], dtype=float) symbols = np.asarray([s.symbol for s in parent.sites]) periodic = np.asarray(parent.pbc) child_xyz = crystal.cartesian(child) @ r if origin is not None: origins = [np.asarray(origin, dtype=float) @ r] elif translate: # A rigid shift of the origin (a setting's p): try the shifts that put the # first child atom on a parent atom of its element. first = child.sites[0].symbol parent_xyz = frac @ lattice origins = [child_xyz[0] - p for p, z in zip(parent_xyz, symbols, strict=True) if z == first] else: origins = [np.zeros(3)] for shift in origins: out: dict[str, str] | None = {} for site, xyz in zip(child.sites, child_xyz, strict=True): delta = frac - (xyz - shift) @ inverse delta[:, periodic] -= np.round(delta[:, periodic]) distance = np.linalg.norm(delta @ lattice, axis=1) distance[symbols != site.symbol] = np.inf best = int(np.argmin(distance)) if distance[best] >= tolerance: out = None break out[site.id] = parent.sites[best].id # type: ignore[index] if out is not None: return out return None
[docs] def carry_by_position( parent: PeriodicStructure, child: PeriodicStructure, *, how: str, what: str, tolerance: float = 1e-3, translate: bool = False, ) -> PeriodicStructure: """Carry the tensors onto a re-expression of the same crystal in the same frame. The site map is found geometrically (:func:`site_map_by_position`); a child that is not such a re-expression (a strained or idealised cell, moved atoms) is refused while the parent carries tensors. """ if not has_tensors(parent): return _keep_drop_marker(parent, child) mapping = site_map_by_position(parent, child, tolerance=tolerance, translate=translate) if mapping is None: refuse(parent, f"{what} (the new cell is not the same crystal in the same frame)") assert mapping is not None return carry(parent, child, mapping, how=how)
[docs] def refuse(parent: PeriodicStructure, what: str) -> None: """Raise when ``parent`` carries tensors that ``what`` cannot transform.""" if not has_tensors(parent): return raise ValueError( f"{parent.id} carries measured anisotropic displacement tensors, which {what} cannot " "transform; they are refused rather than dropped. Drop them first with a recorded " f"reason (drop_displacements / `solid drop-displacements {parent.id} --reason ...`)" )
[docs] def loss(structure: PeriodicStructure) -> str | None: """The export-loss line for a writer that cannot carry the tensors, or None.""" record = structure.provenance.get(KEY) if record is None: return None sites = record.get("sites") if isinstance(record, dict) else None count = len(sites) if isinstance(sites, dict) else 0 return f"anisotropic displacement tensors ({count} sites)"
[docs] def refuse_export(structure: PeriodicStructure, writer: str) -> None: """Writers without a tensor field fail closed instead of dropping the tensors.""" lost = loss(structure) if lost is not None: raise ValueError( f"{writer} cannot carry the {lost} of {structure.id}; export CIF (which writes the " "_atom_site_aniso loop) or drop them first with a recorded reason (drop_displacements)" )
[docs] def require_carried( parents: list[PeriodicStructure], child: PeriodicStructure, what: str ) -> PeriodicStructure: """Refuse a derived structure that lost its parents' tensors without a record.""" if has_tensors(child): return child for parent in parents: refuse(parent, what) return child
[docs] def drop(structure: PeriodicStructure, reason: str) -> PeriodicStructure: """``structure`` without its displacement tensors; the reason and record are kept. The dropped record is stored whole under ``displacement_parameters_dropped`` so the drop is explicit and reviewable; later edits carry that marker. """ record = structure.provenance.get(KEY) if record is None: raise ValueError(f"{structure.id} carries no displacement tensors to drop") text = reason.strip() if not text: raise ValueError("dropping displacement tensors needs a reason") sites = record.get("sites") if isinstance(record, dict) else None provenance = dict(structure.provenance) provenance.pop(KEY) provenance[DROPPED_KEY] = crystal._json( { "reason": text, "sites": len(sites) if isinstance(sites, dict) else 0, "dropped_at": datetime.now(UTC).isoformat(timespec="seconds"), "record": record, } ) return structure.model_copy(update={"provenance": provenance})
[docs] def drop_in_document(document: Document, structure: str, reason: str) -> Document: """The document with ``structure``'s tensors dropped for ``reason``.""" from vibesketcher.document.periodic import with_periodic found = {s.id: s for s in document.periodic_structures} if structure not in found: raise ValueError(f"periodic structure {structure!r} not found") return with_periodic(document, drop(found[structure], reason))
[docs] def referenced(document: Document, recipe: Any) -> list[PeriodicStructure]: """Document structures with tensors that a recipe names anywhere in its fields.""" names: set[str] = set() def walk(value: Any) -> None: if isinstance(value, str): names.add(value) elif isinstance(value, dict): for item in value.values(): walk(item) elif isinstance(value, (list, tuple)): for item in value: walk(item) walk(recipe.model_dump() if hasattr(recipe, "model_dump") else recipe) return [s for s in document.periodic_structures if s.id in names and has_tensors(s)]