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] class Preparation(_Op): source: _ID identifier: _ID | None = None step: PrepareOp
[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)