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