vibe-sketcherDocumentation
Source code for vibesketcher.document.periodic_prepare
"""Reviewable crystal preparation: previews of derived models with deltas (#200).
Each operation reads one periodic structure and proposes a *derived* model under
a new ID, together with its site, stoichiometry, charge and edge deltas and the
source digest it was computed from. Nothing is removed, ordered, protonated or
repaired silently: an operation whose choice is ambiguous lists refusals with
stable codes and cannot be applied until the request is narrowed.
Prepared means a reviewed starting model, not a validated electronic state or
an equilibrium structure.
* ``remove_duplicates`` drops sites of one element that coincide (minimum image
within ``tolerance``); coincident sites that are partially occupied, in a
disorder group or of different elements are refused, not merged.
* ``remove_fragments`` drops chosen 0-D fragments (guests, solvent) of the stored
chemical graph; periodic fragments are refused, and a charged structure needs
the removed fragments' total charge.
* ``complete_hydrogens`` adds hydrogen to carbon whose authored graph fixes the
geometry (sp3 CH and CH2, sp2 CH, sp CH, from the bond-order sum and the
neighbour directions; bond lengths 1.09, 1.08 and 1.06 A, an idealised
tetrahedral H-C-H angle of 109.47 degrees). Protonation of heteroatoms is
never guessed, and rotors (CH3, terminal =CH2), metal neighbours,
non-integer (aromatic) order sums, disordered sites and unreviewed perceived
bonds are refused.
"""
from __future__ import annotations
import hashlib
import json
import math
from collections import Counter
from typing import Annotated, Any, Literal
import numpy as np
from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
from vibesketcher.document import crystal
from vibesketcher.document import periodic_graph as pg
from vibesketcher.document.model import Document, PeriodicBond, PeriodicStructure
_ID = Annotated[str, Field(pattern=r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")]
NOTE = "Prepared means a reviewed starting model, not a validated electronic state or equilibrium."
#: Stable refusal and notice codes of the preparation operations.
CODES: dict[str, str] = {
"prepare.duplicate_disordered": "coincident sites are partially occupied or disordered",
"prepare.coincident_elements": "sites of different elements coincide",
"prepare.no_duplicates": "no coincident sites of one element",
"prepare.no_chemical_graph": "the operation needs a stored chemical graph",
"prepare.fragment_unknown": "no fragment with that index or site",
"prepare.fragment_periodic": "a chain, layer or framework cannot be removed as a guest",
"prepare.removes_everything": "the selection removes every site",
"prepare.charge_unstated": "the structure is charged; state the removed charge",
"prepare.no_authored_graph": "hydrogen completion reads the authored graph only",
"prepare.unreviewed_bonds": "the site has perceived bonds nobody accepted",
"prepare.metal_coordination": "metal neighbours leave the valence ambiguous",
"prepare.aromatic_ambiguous": "a non-integer bond-order sum leaves the hydrogen count open",
"prepare.disordered_site": "the site is partially occupied or disordered",
"prepare.overvalent": "the bond-order sum exceeds the valence",
"prepare.rotor_ambiguous": "the hydrogen positions need a torsion nobody chose",
"prepare.geometry_ambiguous": "the neighbour directions do not fix the hydrogen direction",
"prepare.not_carbon": "only carbon is completed; protonation is never guessed",
"prepare.protonation_not_guessed": "a heteroatom below its valence keeps its hydrogen count",
"prepare.hydrogen_clash": "a new hydrogen would sit too close to another atom",
"prepare.nothing_to_add": "every selected carbon is saturated",
}
class _Op(BaseModel):
model_config = ConfigDict(extra="forbid")
[docs]
class RemoveDuplicates(_Op):
operation: Literal["remove_duplicates"] = "remove_duplicates"
tolerance: float = Field(default=0.1, gt=0, le=0.5)
[docs]
class RemoveFragments(_Op):
operation: Literal["remove_fragments"] = "remove_fragments"
#: Fragment indices from the graph report.
fragments: list[int] = Field(default_factory=list, max_length=25000)
#: Or sites: each selects its whole fragment.
sites: list[str] = Field(default_factory=list, max_length=25000)
removed_charge: int | None = None
[docs]
class CompleteHydrogens(_Op):
operation: Literal["complete_hydrogens"] = "complete_hydrogens"
#: Carbon sites to complete; every unsaturated carbon when omitted.
sites: list[str] | None = Field(default=None, max_length=25000)
PrepareOp = Annotated[
RemoveDuplicates | RemoveFragments | CompleteHydrogens, Field(discriminator="operation")
]
OPERATIONS = ("remove_duplicates", "remove_fragments", "complete_hydrogens")
_SUFFIX = {"remove_duplicates": "dedup", "remove_fragments": "nofrag", "complete_hydrogens": "h"}
[docs]
def parse_preparation(data: dict[str, Any]) -> Preparation:
return TypeAdapter(Preparation).validate_python(data)
[docs]
def content_digest(structure: PeriodicStructure) -> str:
"""Digest of a structure without its provenance (which records the digest)."""
data = structure.model_dump(mode="json", exclude={"provenance", "source_cif"})
return hashlib.sha256(json.dumps(data, sort_keys=True).encode()).hexdigest()
def _refusal(code: str, message: str, sites: list[str] | None = None) -> dict[str, Any]:
return {"code": code, "message": message, "sites": sites or []}
def _without(
structure: PeriodicStructure, removed: set[str]
) -> tuple[list[dict[str, Any]], list[dict[str, Any]], int]:
sites = [s.model_dump(mode="json", exclude_none=True) for s in structure.sites]
bonds = [b.model_dump(mode="json", exclude_none=True) for b in structure.bonds]
kept_bonds = [b for b in bonds if b["a"] not in removed and b["b"] not in removed]
return (
[s for s in sites if s["id"] not in removed],
kept_bonds,
len(bonds) - len(kept_bonds),
)
def _duplicates(structure: PeriodicStructure, step: RemoveDuplicates) -> dict[str, Any]:
refusals: list[dict[str, Any]] = []
parent = list(range(len(structure.sites)))
def root(i: int) -> int:
while parent[i] != i:
parent[i] = parent[parent[i]]
i = parent[i]
return i
pairs = []
for pair in pg.neighbours(structure, step.tolerance):
a, b = structure.sites[pair.i], structure.sites[pair.j]
if a.symbol != b.symbol:
refusals.append(
_refusal(
"prepare.coincident_elements",
f"{a.id} ({a.symbol}) and {b.id} ({b.symbol}) are {pair.distance:.3f} A apart",
[a.id, b.id],
)
)
elif a.occupancy < 1 or b.occupancy < 1 or a.disorder_group or b.disorder_group:
refusals.append(
_refusal(
"prepare.duplicate_disordered",
f"{a.id} and {b.id} coincide but are partially occupied "
"or disordered: choose the disorder first",
[a.id, b.id],
)
)
else:
pairs.append(pair)
parent[root(pair.j)] = root(pair.i)
removed = {structure.sites[n].id for n in range(len(parent)) if root(n) != n}
kept_by = {
structure.sites[n].id: structure.sites[root(n)].id
for n in range(len(parent))
if root(n) != n
}
notices = (
[]
if removed or refusals
else [_refusal("prepare.no_duplicates", CODES["prepare.no_duplicates"])]
)
return {
"removed": removed,
"added": [],
"refusals": refusals,
"notices": notices,
"details": {"kept_instead": kept_by, "distances": [round(p.distance, 4) for p in pairs]},
}
def _fragments(structure: PeriodicStructure, step: RemoveFragments) -> dict[str, Any]:
edges = pg.chemical_edges(structure)
refusals: list[dict[str, Any]] = []
if not edges:
return {
"removed": set(),
"added": [],
"notices": [],
"details": {},
"refusals": [
_refusal("prepare.no_chemical_graph", "perceive or author the bond graph first")
],
}
found = pg.fragments(structure, edges)
of_site = {sid: n for n, f in enumerate(found) for sid in f.sites}
chosen: set[int] = set()
for index in step.fragments:
if not 0 <= index < len(found):
refusals.append(_refusal("prepare.fragment_unknown", f"no fragment {index}"))
else:
chosen.add(index)
for sid in step.sites:
if sid not in of_site:
refusals.append(_refusal("prepare.fragment_unknown", f"no site {sid}", [sid]))
else:
chosen.add(of_site[sid])
if not chosen and not refusals:
refusals.append(_refusal("prepare.fragment_unknown", "choose fragments or sites"))
for index in sorted(chosen):
if found[index].dimension > 0:
refusals.append(
_refusal(
"prepare.fragment_periodic",
f"fragment {index} ({found[index].formula}) is periodic",
found[index].sites[:50],
)
)
removed = {sid for n in chosen for sid in found[n].sites}
if len(removed) == len(structure.sites):
refusals.append(_refusal("prepare.removes_everything", CODES["prepare.removes_everything"]))
if structure.charge not in (None, 0) and step.removed_charge is None:
refusals.append(
_refusal(
"prepare.charge_unstated",
f"the structure has charge {structure.charge}; give "
"removed_charge for the fragments",
)
)
return {
"removed": removed,
"added": [],
"refusals": refusals,
"notices": [],
"details": {"fragments": [found[n].as_json(n) for n in sorted(chosen)]},
}
def _unit(v: np.ndarray) -> np.ndarray:
return np.asarray(v / np.linalg.norm(v))
def _hydrogens(structure: PeriodicStructure, step: CompleteHydrogens) -> dict[str, Any]:
by_id = {s.id: s for s in structure.sites}
authored = [b for b in structure.bonds if b.kind == "authored"]
if not authored:
return {
"removed": set(),
"added": [],
"notices": [],
"details": {},
"refusals": [
_refusal(
"prepare.no_authored_graph", "accept or author the bonds and their orders first"
)
],
}
touching: dict[str, list[tuple[PeriodicBond, np.ndarray]]] = {s.id: [] for s in structure.sites}
for bond in structure.bonds:
if bond.kind not in ("authored", "perceived"):
continue
v = pg.edge_vector(structure, bond.a, bond.b, bond.image)
touching[bond.a].append((bond, v))
touching[bond.b].append((bond, -v))
refusals: list[dict[str, Any]] = []
notices: list[dict[str, Any]] = []
explicit = step.sites is not None
if step.sites is not None:
unknown = sorted(set(step.sites) - set(by_id))
if unknown:
raise ValueError(f"sites not in the structure: {', '.join(unknown)}")
chosen = [by_id[s] for s in dict.fromkeys(step.sites)]
else:
chosen = list(structure.sites)
planned: list[tuple[str, np.ndarray, float]] = [] # carbon, direction, length
for site in chosen:
mine = touching[site.id]
if site.symbol != "C":
valence = pg._VALENCE.get(site.symbol)
total = sum(b.order for b, _ in mine)
if explicit:
refusals.append(
_refusal(
"prepare.not_carbon",
f"{site.id} is {site.symbol}: protonation is not "
"guessed; add its hydrogen explicitly",
[site.id],
)
)
elif valence is not None and site.symbol != "H" and total < valence - 1e-6:
notices.append(
_refusal(
"prepare.protonation_not_guessed",
f"{site.id} ({site.symbol}) bond-order sum {total:g}",
[site.id],
)
)
continue
total = sum(b.order for b, _ in mine)
deficit = 4 - total
if abs(deficit) < 1e-6:
continue
if any(b.kind == "perceived" for b, _ in mine):
refusals.append(
_refusal(
"prepare.unreviewed_bonds",
f"{site.id} has perceived bonds; accept or remove them",
[site.id],
)
)
continue
others = [by_id[b.b if b.a == site.id else b.a] for b, _ in mine]
if any(pg.is_metal(o.symbol) for o in others):
refusals.append(
_refusal(
"prepare.metal_coordination",
f"{site.id} binds a metal; its hydrogen count is a reviewer's call",
[site.id],
)
)
continue
if site.occupancy < 1 or site.disorder_group:
refusals.append(
_refusal("prepare.disordered_site", f"{site.id} is disordered", [site.id])
)
continue
if abs(deficit - round(deficit)) > 1e-6:
refusals.append(
_refusal(
"prepare.aromatic_ambiguous",
f"{site.id} bond-order sum {total:g} is not an integer",
[site.id],
)
)
continue
if deficit < 0:
refusals.append(
_refusal(
"prepare.overvalent", f"{site.id} bond-order sum {total:g} exceeds 4", [site.id]
)
)
continue
count = round(deficit)
units = [_unit(v) for _, v in mine]
n = len(units)
if n == 0 or (n == 1 and count >= 2):
refusals.append(
_refusal(
"prepare.rotor_ambiguous",
f"{site.id} needs {count} H on {n} neighbour(s): choose "
"the torsion by placing them explicitly",
[site.id],
)
)
continue
if n == 1: # count == 1: sp carbon (one triple bond, or =C= is overvalent)
if abs(mine[0][0].order - 3) > 1e-6:
refusals.append(
_refusal(
"prepare.geometry_ambiguous",
f"{site.id}: one neighbour without a triple bond",
[site.id],
)
)
continue
planned.append((site.id, -units[0], 1.06))
continue
total_u = np.sum(units, axis=0)
if n == 2 and count == 2:
if np.linalg.norm(total_u) < 0.1:
refusals.append(
_refusal(
"prepare.geometry_ambiguous", f"{site.id}: linear neighbours", [site.id]
)
)
continue
bisector = -_unit(total_u)
normal = _unit(np.cross(units[0], units[1]))
half = math.radians(109.47) / 2
for sign in (1, -1):
planned.append(
(site.id, math.cos(half) * bisector + sign * math.sin(half) * normal, 1.09)
)
continue
if count == 1 and n in (2, 3) and np.linalg.norm(total_u) >= 0.1:
planned.append((site.id, -_unit(total_u), 1.08 if n == 2 else 1.09))
continue
refusals.append(
_refusal(
"prepare.geometry_ambiguous",
f"{site.id}: {n} neighbours and {count} missing H do not fix "
"the hydrogen directions",
[site.id],
)
)
if not planned and not refusals:
notices.append(_refusal("prepare.nothing_to_add", CODES["prepare.nothing_to_add"]))
rows = crystal.lattice_rows(structure)
inverse = np.linalg.inv(rows)
taken = {s.id for s in structure.sites}
counter = sum(1 for s in structure.sites if s.symbol == "H")
added = []
for carbon, direction, length in planned:
counter += 1
while f"H{counter}" in taken:
counter += 1
hid = f"H{counter}"
taken.add(hid)
start = np.asarray(by_id[carbon].fractional)
raw = start + (length * _unit(direction)) @ inverse
wrap = np.asarray([math.floor(raw[k]) if structure.pbc[k] else 0 for k in range(3)])
added.append(
{
"site": {
"id": hid,
"symbol": "H",
"fractional": [crystal._clean(x) for x in raw - wrap],
},
"bond": {
"a": carbon,
"b": hid,
"image": [int(x) for x in wrap],
"order": 1,
"kind": "authored",
"order_source": "prepared",
"rule": "complete_hydrogens",
},
}
)
return {
"removed": set(),
"added": added,
"refusals": refusals,
"notices": notices,
"details": {},
}
[docs]
def preview(structure: PeriodicStructure, preparation: Preparation) -> dict[str, Any]:
"""The derived model, its deltas, refusals and provenance; nothing is stored."""
step = preparation.step
if isinstance(step, RemoveDuplicates):
plan = _duplicates(structure, step)
elif isinstance(step, RemoveFragments):
plan = _fragments(structure, step)
else:
plan = _hydrogens(structure, step)
identifier = preparation.identifier or f"{structure.id}-{_SUFFIX[step.operation]}"[:64]
removed: set[str] = plan["removed"]
sites, bonds, dropped = _without(structure, removed)
sites += [a["site"] for a in plan["added"]]
bonds += [a["bond"] for a in plan["added"]]
charge = structure.charge
if isinstance(step, RemoveFragments) and charge is not None:
charge = charge - (step.removed_charge or 0)
multiplicity = structure.multiplicity
electrons_changed = len(plan["added"]) + sum(
1 for s in structure.sites if s.id in removed and s.symbol == "H"
)
if multiplicity is not None and (
isinstance(step, RemoveFragments) or electrons_changed % 2 == 1
):
multiplicity = None # the spin of the derived model is the reviewer's to state
before = Counter(s.symbol for s in structure.sites)
after = Counter(s["symbol"] for s in sites)
deltas = {
"sites_removed": sorted(removed),
"sites_added": [a["site"]["id"] for a in plan["added"]],
"stoichiometry_before": dict(sorted(before.items())),
"stoichiometry_after": dict(sorted(after.items())),
"stoichiometry_change": {
e: after[e] - before[e]
for e in sorted(set(before) | set(after))
if after[e] != before[e]
},
"charge_before": structure.charge,
"charge_after": charge,
"multiplicity_before": structure.multiplicity,
"multiplicity_after": multiplicity,
"edges_removed": dropped,
"edges_added": len(plan["added"]),
}
source_digest = content_digest(structure)
record = {
"operation": step.operation,
"parameters": step.model_dump(mode="json", exclude={"operation"}),
"source": structure.id,
"source_sha256": source_digest,
"deltas": deltas,
"details": crystal._json(plan["details"]),
"note": NOTE,
}
applicable = not plan["refusals"] and bool(removed or plan["added"])
derived: dict[str, Any] | None = None
if applicable and sites:
data = structure.model_dump(mode="json", exclude_none=True)
data.update(
{
"id": identifier,
"sites": sites,
"bonds": bonds,
"charge": charge,
"multiplicity": multiplicity,
"parent": None,
"supercell_matrix": None,
"source_cif": None,
"source_model_sha256": None,
}
)
data = {k: v for k, v in data.items() if v is not None}
provenance = {k: v for k, v in structure.provenance.items() if k != "graph"}
provenance["preparation"] = record
data["provenance"] = provenance
made = PeriodicStructure.model_validate(data)
if isinstance(step, CompleteHydrogens):
new = {a["site"]["id"] for a in plan["added"]}
for pair in pg.neighbours(made, 1.0):
a, b = made.sites[pair.i].id, made.sites[pair.j].id
if a in new or b in new:
plan["refusals"].append(
_refusal("prepare.hydrogen_clash", f"{a}-{b} {pair.distance:.2f} A", [a, b])
)
applicable = not plan["refusals"]
if applicable:
provenance["preparation"] = {**record, "derived_sha256": content_digest(made)}
made = made.model_copy(update={"provenance": provenance})
derived = made.model_dump(mode="json", exclude_none=True)
return {
"source": structure.id,
"identifier": identifier,
"operation": step.operation,
"applicable": applicable and derived is not None,
"refusals": plan["refusals"],
"notices": plan["notices"],
"deltas": deltas,
"source_sha256": source_digest,
"provenance": record,
"derived": derived,
"codes": CODES,
}
[docs]
def apply(
document: Document, preparation: Preparation, *, source_sha256: str | None = None
) -> Document:
"""Add the derived model to a copy of ``document``; refusals and stale sources fail."""
from vibesketcher.document.periodic import with_periodic
existing = {s.id: s for s in document.periodic_structures}
if preparation.source not in existing:
raise ValueError(f"periodic structure {preparation.source!r} not found")
source = existing[preparation.source]
if source_sha256 is not None and source_sha256 != content_digest(source):
raise ValueError("the source structure changed since the preview")
result = preview(source, preparation)
if result["identifier"] in existing:
raise ValueError(f"periodic structure {result['identifier']!r} already exists")
if not result["applicable"]:
reasons = "; ".join(r["message"] for r in result["refusals"]) or "nothing to change"
raise ValueError(f"preparation refused: {reasons}")
return with_periodic(document, PeriodicStructure.model_validate(result["derived"]))
[docs]
def undo(document: Document, identifier: str) -> Document:
"""Remove a derived model again, if it is unchanged since it was prepared."""
found = {s.id: s for s in document.periodic_structures}
structure = found.get(identifier)
if structure is None:
raise ValueError(f"periodic structure {identifier!r} not found")
record = structure.provenance.get("preparation")
if not isinstance(record, dict) or "derived_sha256" not in record:
raise ValueError(f"{identifier} is not a prepared model")
if record["derived_sha256"] != content_digest(structure):
raise ValueError(f"{identifier} changed after it was prepared; undo refused")
data = document.to_json_data()
data["periodic_structures"] = [
s.model_dump(mode="json", exclude_none=True)
for s in document.periodic_structures
if s.id != identifier
]
return Document.model_validate(data)