vibe-sketcherDocumentation

Source code for vibesketcher.document.periodic_graph

"""Periodic chemical graphs: edge kinds, perception, diagnostics and edits (#200).

A periodic edge joins site ``a`` in the home cell to site ``b`` in the cell
displaced by the integer ``image``: the labelled quotient graph of Chung, Hahn
and Klee (Acta Cryst. A40, 42 (1984), doi:10.1107/S0108767384000088). The edge
``kind`` keeps apart what someone authored (the chemical graph), what a
distance rule perceived (candidates awaiting review), what a crystallographic
distance table lists, net/topology edges and pairs someone suppressed.

Nothing here runs implicitly. Geometry edits keep the stored edges as they are;
:func:`report` says when perceived edges predate the current geometry or an
authored bond is stretched, and a new perception only happens through an
explicit ``perceive`` operation, which records its rule and parameters.

Distances use covalent radii from RDKit's table (Cordero et al., Dalton
Trans. 2008, 2832, doi:10.1039/b801115j). Neighbour search is a linked-cell
list (Allen and Tildesley, *Computer Simulation of Liquids*, section 5.3) over
the minimum images within the cutoff, bounded by :data:`MAX_PAIRS`.

A fragment's dimensionality is the rank of the lattice translations carried by
its cycles: walk the component assigning each site an image offset; an edge
closing a cycle contributes ``offset[a] + image - offset[b]``. Rank 0 is a
molecule (possibly drawn across a cell face), 1 a chain, 2 a layer, 3 a net.
"""

from __future__ import annotations

import hashlib
import itertools
import json
import math
from collections import defaultdict
from dataclasses import dataclass, field
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.model import PeriodicBond, PeriodicStructure
from vibesketcher.elements import ATOMIC_NUMBER

_ID = Annotated[str, Field(pattern=r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")]
Image = tuple[int, int, int]
Key = tuple[str, str, Image]

#: Pair results a neighbour search may return before it refuses.
MAX_PAIRS = 2_000_000
#: The largest neighbour cutoff (angstrom) the diagnostics accept.
MAX_CUTOFF = 8.0
#: Graph edit records kept for undo; older records lose their inverse.
MAX_UNDO_CHANGES = 50_000

#: Default perception rule: d <= scale * (r_a + r_b).
DEFAULT_SCALE = 1.15
#: Closer than this fraction of the radius sum (or 0.5 A) is a clash.
CLASH_FRACTION = 0.6
#: An authored bond longer than this fraction of the radius sum is stretched.
STRETCH_FRACTION = 1.5

# Elements whose coordination number and formal valence a graph cannot fix.
_NONMETALS = {
    "H",
    "He",
    "B",
    "C",
    "N",
    "O",
    "F",
    "Ne",
    "Si",
    "P",
    "S",
    "Cl",
    "Ar",
    "Ge",
    "As",
    "Se",
    "Br",
    "Kr",
    "Sb",
    "Te",
    "I",
    "Xe",
    "At",
    "Rn",
}
_NOBLE = {"He", "Ne", "Ar", "Kr", "Xe", "Rn"}
#: Upper bounds on neighbours for a light main-group atom (a diagnostic, not a rule).
_MAX_NEIGHBOURS = {"H": 1, "F": 1, "Cl": 1, "Br": 1, "I": 1, "O": 2, "C": 4, "N": 4, "B": 4}
#: Typical valence of light main-group atoms, for the bond-order sum diagnostic.
_VALENCE = {"H": 1, "C": 4, "N": 3, "O": 2, "F": 1, "Cl": 1, "Br": 1, "I": 1}


[docs] def is_metal(symbol: str) -> bool: return symbol not in _NONMETALS
[docs] def covalent_radius(symbol: str) -> float: from rdkit import Chem return float(Chem.GetPeriodicTable().GetRcovalent(ATOMIC_NUMBER[symbol]))
def _neg(image: Image) -> Image: return (-image[0], -image[1], -image[2])
[docs] def edge_key(a: str, b: str, image: Image) -> Key: """One key for an edge and its reverse (``b`` to ``a`` in cell ``-image``).""" image = (int(image[0]), int(image[1]), int(image[2])) if (a, image) <= (b, _neg(image)) if a == b else a < b: return (a, b, image) return (b, a, _neg(image))
[docs] def key_of(bond: PeriodicBond) -> Key: return edge_key(bond.a, bond.b, bond.image)
[docs] def geometry_fingerprint(structure: PeriodicStructure) -> str: """A digest of the cell, the sites' elements and positions (1e-6 resolution).""" data = { "lattice": [[round(x, 6) for x in row] for row in structure.lattice_angstrom], "pbc": list(structure.pbc), "sites": [[s.id, s.symbol, *(round(x, 6) for x in s.fractional)] for s in structure.sites], } return hashlib.sha256(json.dumps(data, sort_keys=True).encode()).hexdigest()
# Neighbour search ------------------------------------------------------------
[docs] @dataclass(frozen=True) class Pair: i: int j: int image: Image distance: float
def _heights(rows: np.ndarray) -> np.ndarray: """Interplanar spacing along each lattice row (cell volume over face area).""" volume = abs(float(np.linalg.det(rows))) faces = [np.linalg.norm(np.cross(rows[(k + 1) % 3], rows[(k + 2) % 3])) for k in range(3)] return np.asarray([volume / f for f in faces])
[docs] def neighbours(structure: PeriodicStructure, cutoff: float) -> list[Pair]: """Every site pair (each once) closer than ``cutoff`` over all periodic images.""" if not (math.isfinite(cutoff) and 0 < cutoff <= MAX_CUTOFF): raise ValueError(f"the neighbour cutoff must be in (0, {MAX_CUTOFF}] angstrom") rows = crystal.lattice_rows(structure) frac = np.asarray([s.fractional for s in structure.sites], dtype=float) heights = _heights(rows) axes: list[tuple[int, list[tuple[int, int]]]] = [] # bins, [(offset, image range)] bins = np.zeros((len(frac), 3), dtype=int) for axis in range(3): if structure.pbc[axis]: frac[:, axis] -= np.floor(frac[:, axis]) count = int(heights[axis] // cutoff) if count >= 3: bins[:, axis] = np.minimum((frac[:, axis] * count).astype(int), count - 1) axes.append((count, [(o, 0) for o in (-1, 0, 1)])) else: reach = math.ceil(cutoff / heights[axis]) axes.append((1, [(0, n) for n in range(-reach, reach + 1)])) else: t = frac[:, axis] * heights[axis] low = float(t.min()) if len(t) else 0.0 bins[:, axis] = ((t - low) // cutoff).astype(int) axes.append((int(bins[:, axis].max()) + 1, [(o, 0) for o in (-1, 0, 1)])) xyz = frac @ rows members: dict[tuple[int, int, int], np.ndarray] = {} order = np.lexsort((bins[:, 2], bins[:, 1], bins[:, 0])) for key, group in itertools.groupby(order, key=lambda n: tuple(int(x) for x in bins[n])): members[(key[0], key[1], key[2])] = np.asarray(list(group), dtype=int) found: list[Pair] = [] for home, atoms in members.items(): options = [] for axis in range(3): count, moves = axes[axis] these = [] for offset, extra in moves: target = home[axis] + offset if structure.pbc[axis]: cell = math.floor(target / count) + extra target %= count else: if not 0 <= target < count: continue cell = 0 these.append((target, cell)) # Two offsets can reach the same bin and image in a short axis. options.append(sorted(set(these))) for (bx, ix), (by, iy), (bz, iz) in itertools.product(*options): other = members.get((bx, by, bz)) if other is None: continue image = (ix, iy, iz) displaced = xyz[other] + np.asarray(image, dtype=float) @ rows delta = displaced[None, :, :] - xyz[atoms][:, None, :] distance = np.sqrt(np.einsum("ijk,ijk->ij", delta, delta)) hits = np.argwhere(distance < cutoff) for p, q in hits: i, j = int(atoms[p]), int(other[q]) if i == j and image == (0, 0, 0): continue if (i, image) > (j, _neg(image)) if i == j else i > j: continue # the reverse visit records it found.append(Pair(i, j, image, float(distance[p, q]))) if len(found) > MAX_PAIRS: raise ValueError( f"more than {MAX_PAIRS} neighbour pairs within {cutoff:g} A; " "use a smaller cutoff or cell" ) # Sites were wrapped into the home cell for the search; give images back in # the stored fractional frame so edges refer to the sites as recorded. stored = np.asarray([s.fractional for s in structure.sites], dtype=float) wrap = np.zeros_like(stored, dtype=int) for axis in range(3): if structure.pbc[axis]: wrap[:, axis] = np.floor(stored[:, axis]).astype(int) out = [] for pair in found: # f_j + I' - f_i = (f_j - W_j) + I - (f_i - W_i) => I' = I - W_j + W_i moved = np.asarray(pair.image) - wrap[pair.j] + wrap[pair.i] image = (int(moved[0]), int(moved[1]), int(moved[2])) out.append(Pair(pair.i, pair.j, image, pair.distance)) out.sort(key=lambda p: (p.i, p.j, p.image)) return out
[docs] def edge_vector(structure: PeriodicStructure, a: str, b: str, image: Image) -> np.ndarray: """Cartesian vector from site ``a`` to site ``b`` in cell ``image`` (angstrom).""" by_id = {s.id: s for s in structure.sites} rows = crystal.lattice_rows(structure) delta = np.asarray(by_id[b].fractional) + np.asarray(image) - np.asarray(by_id[a].fractional) return np.asarray(delta @ rows)
[docs] def minimum_image(structure: PeriodicStructure, a: str, b: str) -> tuple[Image, float]: """The image of ``b`` nearest to ``a`` and its distance (angstrom).""" by_id = {s.id: s for s in structure.sites} rows = crystal.lattice_rows(structure) delta = np.asarray(by_id[b].fractional) - np.asarray(by_id[a].fractional) base = [-round(delta[k]) if structure.pbc[k] else 0 for k in range(3)] best: tuple[Image, float] | None = None ranges = [(-1, 0, 1) if structure.pbc[k] else (0,) for k in range(3)] for extra in itertools.product(*ranges): image = (base[0] + extra[0], base[1] + extra[1], base[2] + extra[2]) d = float(np.linalg.norm((delta + image) @ rows)) if (a != b or any(image)) and (best is None or d < best[1] - 1e-12): best = (image, d) if best is None: raise ValueError("a site has no other image in a nonperiodic cell") return best
# Perception ------------------------------------------------------------------
[docs] def perceive( structure: PeriodicStructure, *, scale: float = DEFAULT_SCALE, metals: bool = True, metal_metal: bool = False, ) -> list[PeriodicBond]: """Perceived candidates ``d <= scale (r_a + r_b)`` not already stored as an edge. Pairs stored as authored or suppressed edges are not proposed again; the candidates carry ``kind="perceived"``, order 1 and the rule text. With ``metals=False`` no pair involving a metal is proposed; metal-metal pairs are proposed only with ``metal_metal=True`` (radius sums of two metals reach the next coordination shell of most ionic solids). """ if not (math.isfinite(scale) and 0.5 <= scale <= 2.0): raise ValueError("the perception scale must be between 0.5 and 2.0") radii = [covalent_radius(s.symbol) for s in structure.sites] cutoff = min(MAX_CUTOFF, scale * 2 * max(radii)) rule = ( f"covalent-radii scale={scale:g}" + ("" if metals else " no-metals") + (" metal-metal" if metal_metal and metals else "") ) taken = {key_of(b) for b in structure.bonds if b.kind != "distance"} out = [] for pair in neighbours(structure, cutoff): a, b = structure.sites[pair.i], structure.sites[pair.j] metal_a, metal_b = is_metal(a.symbol), is_metal(b.symbol) if (not metals and (metal_a or metal_b)) or (metal_a and metal_b and not metal_metal): continue if pair.distance > scale * (radii[pair.i] + radii[pair.j]): continue if edge_key(a.id, b.id, pair.image) in taken: continue out.append( PeriodicBond( a=a.id, b=b.id, image=pair.image, order=1, kind="perceived", order_source="perceived", rule=rule, ) ) return out
# Fragments -------------------------------------------------------------------
[docs] @dataclass class Fragment: sites: list[str] dimension: int translations: list[Image] crosses_boundary: bool formula: str
[docs] def as_json(self, index: int) -> dict[str, Any]: return { "index": index, "sites": self.sites, "dimension": self.dimension, "kind": ("molecule", "chain", "layer", "framework")[self.dimension], "translations": [list(t) for t in self.translations], "crosses_boundary": self.crosses_boundary, "formula": self.formula, }
def _formula(symbols: list[str]) -> str: counts: dict[str, int] = defaultdict(int) for s in symbols: counts[s] += 1 first = [e for e in ("C", "H") if e in counts] if "C" in counts else [] rest = sorted(e for e in counts if e not in first) return "".join(f"{e}{counts[e] if counts[e] > 1 else ''}" for e in [*first, *rest])
[docs] def chemical_edges(structure: PeriodicStructure, *, perceived: bool = True) -> list[PeriodicBond]: """Authored edges, plus stored perceived candidates unless ``perceived=False``.""" kinds = {"authored", "perceived"} if perceived else {"authored"} return [b for b in structure.bonds if b.kind in kinds]
[docs] def fragments(structure: PeriodicStructure, edges: list[PeriodicBond]) -> list[Fragment]: """Connected components of ``edges``, each with its periodic dimensionality.""" index = {s.id: n for n, s in enumerate(structure.sites)} adjacency: dict[int, list[tuple[int, Image]]] = defaultdict(list) for bond in edges: i, j = index[bond.a], index[bond.b] adjacency[i].append((j, bond.image)) adjacency[j].append((i, _neg(bond.image))) offset: dict[int, np.ndarray] = {} out = [] for start in range(len(structure.sites)): if start in offset: continue offset[start] = np.zeros(3, dtype=int) stack, members, cycles = [start], [start], [] while stack: i = stack.pop() for j, image in adjacency[i]: reached = offset[i] + np.asarray(image) if j not in offset: offset[j] = reached members.append(j) stack.append(j) elif np.any(reached != offset[j]): cycles.append(reached - offset[j]) rank = int(np.linalg.matrix_rank(np.asarray(cycles))) if cycles else 0 members.sort() basis: list[Image] = [] for vector in cycles: trial = [*basis, (int(vector[0]), int(vector[1]), int(vector[2]))] if np.linalg.matrix_rank(np.asarray(trial)) > len(basis): basis = trial if len(basis) == rank: break crosses = rank == 0 and any(np.any(offset[m] != 0) for m in members) out.append( Fragment( sites=[structure.sites[m].id for m in members], dimension=rank, translations=basis, crosses_boundary=bool(crosses), formula=_formula([structure.sites[m].symbol for m in members]), ) ) return out
[docs] def unwrapped_offsets(structure: PeriodicStructure, edges: list[PeriodicBond]) -> dict[str, Image]: """Image offsets that draw each 0-D fragment whole (the first site stays put).""" index = {s.id: n for n, s in enumerate(structure.sites)} adjacency: dict[str, list[tuple[str, Image]]] = defaultdict(list) for bond in edges: adjacency[bond.a].append((bond.b, bond.image)) adjacency[bond.b].append((bond.a, _neg(bond.image))) offsets: dict[str, Image] = {} for site in sorted(structure.sites, key=lambda s: index[s.id]): if site.id in offsets: continue offsets[site.id] = (0, 0, 0) stack = [site.id] while stack: a = stack.pop() for b, image in adjacency[a]: if b not in offsets: o = offsets[a] offsets[b] = (o[0] + image[0], o[1] + image[1], o[2] + image[2]) stack.append(b) return offsets
# Diagnostics ----------------------------------------------------------------- Severity = Literal["error", "warning", "info"]
[docs] @dataclass class Diagnostic: code: str severity: Severity message: str remedy: str sites: list[str] = field(default_factory=list) edges: list[list[Any]] = field(default_factory=list)
[docs] def as_json(self) -> dict[str, Any]: return { "code": self.code, "severity": self.severity, "message": self.message, "remedy": self.remedy, "sites": self.sites, "edges": self.edges, }
#: Every diagnostic code with its meaning; codes are stable API. CODES: dict[str, str] = { "geometry.clash": "two atoms (or an atom and an image) are far closer than a bond", "geometry.duplicate_site": "two sites of one element coincide", "site.partial_occupancy": "a site is partially occupied or in a disorder group", "graph.none": "no chemical graph is stored", "graph.unreviewed_perceived": "perceived candidates await review", "graph.distance_table_only": "only crystallographic distance-table edges are stored", "graph.perception_stale": "the geometry changed after the perception", "graph.perception_unrecorded": "perceived edges carry no perception record", "graph.bond_stretched": "an authored bond is much longer than a covalent bond", "graph.bond_not_minimum_image": "an authored bond joins an image farther than the nearest", "graph.missing_contact": "a close pair has no authored, perceived or suppressed edge", "graph.duplicate_edge": "an edge is stored twice", "graph.self_edge": "a site is bonded to itself in its own cell", "coordination.isolated_site": "a site has no chemical edge", "coordination.overcoordinated": "a light main-group atom has too many neighbours", "coordination.valence_sum": "a light atom's bond-order sum differs from its valence", "coordination.metal_ambiguous": "a metal's coordination and valence stay a reviewer's call", "coordination.aromatic_ambiguous": "aromatic (1.5) orders leave the Kekule structure open", "fragment.crosses_boundary": "a molecule is drawn across a cell face", "fragment.extended": "a fragment is periodic (chain, layer or framework)", "fragment.several": "the cell holds more than one fragment", } def _perception_record(structure: PeriodicStructure) -> dict[str, Any] | None: graph = structure.provenance.get("graph") if not isinstance(graph, dict): return None record = graph.get("perception") return record if isinstance(record, dict) else None
[docs] def report(structure: PeriodicStructure) -> dict[str, Any]: """Graph summary, fragments and diagnostics with stable codes and remedies.""" sites = structure.sites by_id = {s.id: s for s in sites} radii = {s.id: covalent_radius(s.symbol) for s in sites} out: list[Diagnostic] = [] counts: dict[str, int] = defaultdict(int) seen: dict[tuple[Key, str], int] = defaultdict(int) for bond in structure.bonds: counts[bond.kind] += 1 seen[(key_of(bond), bond.kind)] += 1 if bond.a == bond.b and bond.image == (0, 0, 0): out.append( Diagnostic( "graph.self_edge", "error", f"{bond.a} is bonded to itself", "remove the edge", [bond.a], [_edge(bond)], ) ) for (key, kind), n in seen.items(): if n > 1: out.append( Diagnostic( "graph.duplicate_edge", "warning", f"the {kind} edge {key[0]}-{key[1]} {key[2]} is stored {n} times", "remove the copies", [key[0], key[1]], [[key[0], key[1], list(key[2]), kind]], ) ) # Pair geometry within the clash, duplicate and perception range. largest = max(radii.values()) pairs = neighbours(structure, min(MAX_CUTOFF, DEFAULT_SCALE * 2 * largest)) stored = {key_of(b) for b in structure.bonds if b.kind != "distance"} missing: list[list[Any]] = [] for pair in pairs: a, b = sites[pair.i], sites[pair.j] limit = radii[a.id] + radii[b.id] if a.symbol == b.symbol and pair.distance < 0.1: out.append( Diagnostic( "geometry.duplicate_site", "error", f"{a.id} and {b.id} coincide ({pair.distance:.3f} A)", "preview prepare remove_duplicates", [a.id, b.id], ) ) elif pair.distance < max(0.5, CLASH_FRACTION * limit): partial = a.occupancy < 1 or b.occupancy < 1 or a.disorder_group or b.disorder_group out.append( Diagnostic( "geometry.clash", "warning" if partial else "error", f"{a.id}-{b.id} {pair.distance:.3f} A apart" + (" (disorder alternatives)" if partial else ""), "choose one disorder alternative" if partial else "move or remove one of the sites", [a.id, b.id], ) ) elif ( pair.distance <= DEFAULT_SCALE * limit and edge_key(a.id, b.id, pair.image) not in stored and not (is_metal(a.symbol) and is_metal(b.symbol)) ): missing.append([a.id, b.id, list(pair.image), round(pair.distance, 4)]) authored = [b for b in structure.bonds if b.kind == "authored"] perceived = [b for b in structure.bonds if b.kind == "perceived"] if not authored and not perceived: if counts.get("distance"): out.append( Diagnostic( "graph.distance_table_only", "info", f"{counts['distance']} distance-table edges, no chemical graph", "a distance table is not a bond graph: perceive or author the bonds", ) ) else: out.append( Diagnostic( "graph.none", "info", "no chemical graph is stored", "run the graph operation perceive, then review it", ) ) if perceived: out.append( Diagnostic( "graph.unreviewed_perceived", "warning", f"{len(perceived)} perceived candidates are not reviewed", "accept_perceived, suppress or remove them", edges=[_edge(b) for b in perceived[:50]], ) ) record = _perception_record(structure) if record is None: out.append( Diagnostic( "graph.perception_unrecorded", "info", "perceived edges carry no perception record", "perceive again to record the rule and geometry", ) ) elif record.get("geometry") != geometry_fingerprint(structure): out.append( Diagnostic( "graph.perception_stale", "warning", "the geometry changed after the bonds were perceived; " "the stored edges were kept as they were", "review the edges, or clear_perceived and perceive again", ) ) if missing and (authored or perceived): out.append( Diagnostic( "graph.missing_contact", "info", f"{len(missing)} close pairs have no edge", "perceive, add_bond or suppress them", sorted({x for m in missing[:50] for x in m[:2]}), missing[:50], ) ) for bond in authored: if bond.a not in by_id or bond.b not in by_id: continue d = float(np.linalg.norm(edge_vector(structure, bond.a, bond.b, bond.image))) limit = radii[bond.a] + radii[bond.b] if d > STRETCH_FRACTION * limit: out.append( Diagnostic( "graph.bond_stretched", "warning", f"{bond.a}-{bond.b} {tuple(bond.image)} is {d:.2f} A (covalent {limit:.2f} A)", "check the geometry or remove the bond", [bond.a, bond.b], [_edge(bond)], ) ) if any(structure.pbc): _, nearest = minimum_image(structure, bond.a, bond.b) if d > nearest + 1e-3 and d > STRETCH_FRACTION * limit: out.append( Diagnostic( "graph.bond_not_minimum_image", "warning", f"{bond.a}-{bond.b} joins an image {d:.2f} A away; the " f"nearest is {nearest:.2f} A", "set the bond's image to the nearest one", [bond.a, bond.b], [_edge(bond)], ) ) # Coordination from the chemical edges. edges = chemical_edges(structure) neighbours_of: dict[str, list[PeriodicBond]] = defaultdict(list) for bond in edges: neighbours_of[bond.a].append(bond) if bond.b != bond.a or bond.image != (0, 0, 0): neighbours_of[bond.b].append(bond) coordination = {s.id: len(neighbours_of[s.id]) for s in sites} if edges: isolated = [s.id for s in sites if not neighbours_of[s.id] and s.symbol not in _NOBLE] if isolated: out.append( Diagnostic( "coordination.isolated_site", "warning", f"{len(isolated)} sites have no chemical edge", "add their bonds or confirm they are ions or guests", isolated[:200], ) ) over, sums, metals_seen, aromatic = [], [], [], set() for site in sites: mine = neighbours_of[site.id] max_light = _MAX_NEIGHBOURS.get(site.symbol) # Bridging oxo, hydroxo and halide ligands of metals are not overcoordinated. light = [b for b in mine if not is_metal(by_id[b.b if b.a == site.id else b.a].symbol)] if max_light is not None and len(light) > max_light: over.append(site.id) if is_metal(site.symbol) and site.symbol not in _NOBLE: metals_seen.append(site.id) total = sum(b.order for b in mine) if any(abs(b.order - 1.5) < 1e-9 for b in mine): aromatic.add(site.id) valence = _VALENCE.get(site.symbol) authored_only = all(b.kind == "authored" for b in mine) no_metal = all(not is_metal(by_id[b.b if b.a == site.id else b.a].symbol) for b in mine) reviewed = authored_only and no_metal and site.id not in aromatic if valence is not None and mine and reviewed and total > valence + 1e-6: sums.append(site.id) if over: out.append( Diagnostic( "coordination.overcoordinated", "warning", f"{len(over)} light atoms have more neighbours than expected", "check for clashes, disorder or extra bonds", over[:200], ) ) if sums: out.append( Diagnostic( "coordination.valence_sum", "warning", f"{len(sums)} atoms exceed their usual valence", "check the bond orders or record a charge", sums[:200], ) ) if metals_seen: cn = {s: coordination[s] for s in metals_seen[:200]} out.append( Diagnostic( "coordination.metal_ambiguous", "info", "metal coordination numbers " + ", ".join(f"{k}:{v}" for k, v in list(cn.items())[:12]), "review metal-ligand edges and oxidation states yourself; nothing assigns them", metals_seen[:200], ) ) if aromatic: out.append( Diagnostic( "coordination.aromatic_ambiguous", "info", f"{len(aromatic)} atoms carry aromatic (1.5) orders", "set Kekule orders by hand where a writer needs them", sorted(aromatic)[:200], ) ) for site in sites: if site.occupancy < 1 or site.disorder_group: out.append( Diagnostic( "site.partial_occupancy", "warning", f"{site.id} occupancy {site.occupancy:g}" + (f", disorder group {site.disorder_group}" if site.disorder_group else ""), "choose an ordered model before a calculation", [site.id], ) ) found = fragments(structure, edges) if edges else [] if found: crossing = [f for f in found if f.crosses_boundary] if crossing: out.append( Diagnostic( "fragment.crosses_boundary", "info", f"{len(crossing)} molecules are drawn across a cell face", "nothing to fix: edges carry the images", [s for f in crossing for s in f.sites][:200], ) ) extended = [f for f in found if f.dimension > 0] if extended: kinds = ", ".join( sorted({("chain", "layer", "framework")[f.dimension - 1] for f in extended}) ) out.append( Diagnostic( "fragment.extended", "info", f"periodic fragments: {kinds}", "none needed; guests are the 0-D fragments", ) ) if len(found) > 1: out.append( Diagnostic( "fragment.several", "info", f"{len(found)} fragments: " + ", ".join(f.formula for f in found[:12]), "preview prepare remove_fragments to drop guests or solvent", ) ) rank = {"error": 0, "warning": 1, "info": 2} out.sort(key=lambda d: (rank[d.severity], d.code)) return { "structure": structure.id, "geometry": geometry_fingerprint(structure), "edges": { k: counts.get(k, 0) for k in ("authored", "perceived", "distance", "topology", "suppressed") }, "perception": _perception_record(structure), "coordination": coordination, "fragments": [f.as_json(n) for n, f in enumerate(found)], "diagnostics": [d.as_json() for d in out], "codes": CODES, }
def _edge(bond: PeriodicBond) -> list[Any]: return [bond.a, bond.b, list(bond.image), bond.kind] # Graph edits ----------------------------------------------------------------- class _Op(BaseModel): model_config = ConfigDict(extra="forbid")
[docs] class AddBond(_Op): op: Literal["add_bond"] = "add_bond" a: _ID b: _ID image: Image | None = None order: float = Field(default=1, gt=0, le=4)
[docs] class SetOrder(_Op): op: Literal["set_order"] = "set_order" a: _ID b: _ID image: Image = (0, 0, 0) order: float = Field(gt=0, le=4)
[docs] class RemoveBond(_Op): op: Literal["remove_bond"] = "remove_bond" a: _ID b: _ID image: Image = (0, 0, 0) kind: Literal["authored", "perceived", "distance", "topology", "suppressed"] | None = None
[docs] class Suppress(_Op): op: Literal["suppress"] = "suppress" a: _ID b: _ID image: Image | None = None reason: str | None = Field(default=None, max_length=200)
[docs] class Perceive(_Op): op: Literal["perceive"] = "perceive" scale: float = Field(default=DEFAULT_SCALE, ge=0.5, le=2.0) metals: bool = True metal_metal: bool = False
[docs] class AcceptPerceived(_Op): op: Literal["accept_perceived"] = "accept_perceived" #: Edges to accept as ``[a, b, image]``; all perceived edges when omitted. edges: list[tuple[str, str, Image]] | None = Field(default=None, max_length=100000)
[docs] class ClearPerceived(_Op): op: Literal["clear_perceived"] = "clear_perceived"
[docs] class ImportCifDistances(_Op): op: Literal["import_cif_distances"] = "import_cif_distances" cif: str = Field(max_length=67108864) block: str | None = None tolerance: float = Field(default=0.02, gt=0, le=0.2)
GraphOp = Annotated[ AddBond | SetOrder | RemoveBond | Suppress | Perceive | AcceptPerceived | ClearPerceived | ImportCifDistances, Field(discriminator="op"), ] GRAPH_OPS = ( "add_bond", "set_order", "remove_bond", "suppress", "perceive", "accept_perceived", "clear_perceived", "import_cif_distances", )
[docs] class GraphEdit(_Op): """Operations applied in order and recorded as one undoable step.""" structure: _ID operations: list[GraphOp] = Field(min_length=1, max_length=1000)
[docs] def parse_graph_edit(data: dict[str, Any]) -> GraphEdit: return TypeAdapter(GraphEdit).validate_python(data)
def _find(bonds: list[PeriodicBond], key: Key, kinds: set[str]) -> int | None: for n, bond in enumerate(bonds): if bond.kind in kinds and key_of(bond) == key: return n return None def _cif_distances(structure: PeriodicStructure, op: ImportCifDistances) -> list[PeriodicBond]: """The ``_geom_bond`` loop as distance-table edges (never as chemical bonds). Rows name asymmetric-unit labels; each is matched to every expanded site pair (through the import's ``cif_label_of_site``) whose minimum-image distance agrees with the tabulated one within ``tolerance``. """ from vibesketcher.document import cif_import blocks = cif_import.parse(op.cif) if op.block is not None: blocks = [b for b in blocks if b.name.lower() == op.block.lower()] with_loop = [b for b in blocks if b.column("_geom_bond_atom_site_label_1") is not None] if len(with_loop) != 1: raise ValueError(f"the CIF has {len(with_loop)} blocks with a _geom_bond loop; choose one") block = with_loop[0] def col(tag: str) -> list[str]: found = block.column(tag) if found is None: raise ValueError(f"the _geom_bond loop has no {tag}") return found[0][tag] first, second = col("_geom_bond_atom_site_label_1"), col("_geom_bond_atom_site_label_2") distances = col("_geom_bond_distance") labels = structure.provenance.get("cif_label_of_site") label_of: dict[str, str] = ( {str(k): str(v) for k, v in labels.items()} if isinstance(labels, dict) else {s.id: s.id for s in structure.sites} ) sites_of: dict[str, list[str]] = defaultdict(list) for sid, label in label_of.items(): sites_of[label].append(sid) wanted: dict[tuple[str, str], list[float]] = defaultdict(list) for la, lb, text in zip(first, second, distances, strict=True): value = cif_import.number(text, "_geom_bond_distance")[0] wanted[(min(la, lb), max(la, lb))].append(value) if not wanted: return [] cutoff = min(MAX_CUTOFF, max(v for vs in wanted.values() for v in vs) + op.tolerance) out = [] unmatched = set(wanted) for pair in neighbours(structure, cutoff): a, b = structure.sites[pair.i].id, structure.sites[pair.j].id la, lb = label_of.get(a, a), label_of.get(b, b) labels_ab = (min(la, lb), max(la, lb)) listed = wanted.get(labels_ab) if not listed: continue match = min(listed, key=lambda v: abs(v - pair.distance)) if abs(match - pair.distance) <= op.tolerance: unmatched.discard(labels_ab) out.append( PeriodicBond( a=a, b=b, image=pair.image, kind="distance", rule="cif:_geom_bond", distance_angstrom=match, ) ) if unmatched: names = ", ".join("-".join(p) for p in sorted(unmatched)[:8]) raise ValueError(f"no expanded site pair matches the tabulated distance of {names}") return out
[docs] def apply_graph_edit(structure: PeriodicStructure, edit: GraphEdit) -> PeriodicStructure: """Apply the operations and record them with their inverse for :func:`undo_graph_edit`.""" known = {s.id for s in structure.sites} bonds = list(structure.bonds) removed: list[PeriodicBond] = [] added: list[PeriodicBond] = [] recorded = structure.provenance.get("graph") graph: dict[str, Any] = dict(recorded) if isinstance(recorded, dict) else {} perception = graph.get("perception") def take(n: int) -> None: bond = bonds.pop(n) if bond in added: added.remove(bond) else: removed.append(bond) def put(bond: PeriodicBond) -> None: bonds.append(bond) added.append(bond) def check(*ids: str) -> None: unknown = sorted(set(ids) - known) if unknown: raise ValueError(f"sites not in the structure: {', '.join(unknown)}") for op in edit.operations: if isinstance(op, (AddBond, Suppress)): check(op.a, op.b) image = op.image if op.image is not None else minimum_image(structure, op.a, op.b)[0] if op.a == op.b and image == (0, 0, 0): raise ValueError("a site cannot bond to itself in its own cell") if any(image[k] and not structure.pbc[k] for k in range(3)): raise ValueError("an edge image crosses a nonperiodic direction") key = edge_key(op.a, op.b, image) for kind in ("authored", "perceived", "suppressed"): n = _find(bonds, key, {kind}) if n is not None: if isinstance(op, AddBond) and kind == "authored": raise ValueError(f"{op.a}-{op.b} {image} is already a bond") take(n) if isinstance(op, AddBond): put( PeriodicBond( a=key[0], b=key[1], image=key[2], order=op.order, kind="authored", order_source="manual", ) ) else: put( PeriodicBond( a=key[0], b=key[1], image=key[2], kind="suppressed", rule=op.reason ) ) elif isinstance(op, SetOrder): check(op.a, op.b) key = edge_key(op.a, op.b, op.image) n = _find(bonds, key, {"authored", "perceived"}) if n is None: raise ValueError(f"{op.a}-{op.b} {op.image} is not a bond") old = bonds[n] take(n) put( old.model_copy( update={"order": op.order, "order_source": "manual", "kind": "authored"} ) ) elif isinstance(op, RemoveBond): check(op.a, op.b) key = edge_key(op.a, op.b, op.image) kinds: set[str] = ( {op.kind} if op.kind else {"authored", "perceived", "distance", "topology"} ) n = _find(bonds, key, kinds) if n is None: raise ValueError(f"no such edge {op.a}-{op.b} {op.image}") take(n) elif isinstance(op, Perceive): current = structure.model_copy(update={"bonds": bonds}) found = perceive(current, scale=op.scale, metals=op.metals, metal_metal=op.metal_metal) for bond in found: put(bond) perception = { "rule": "covalent-radii", "scale": op.scale, "metals": op.metals, "metal_metal": op.metal_metal, "radii": "RDKit covalent radii (Cordero et al. 2008)", "geometry": geometry_fingerprint(structure), } elif isinstance(op, AcceptPerceived): wanted = ( None if op.edges is None else {edge_key(a, b, tuple(i)) for a, b, i in op.edges} # type: ignore[arg-type] ) for n in [n for n, b in enumerate(bonds) if b.kind == "perceived"][::-1]: bond = bonds[n] if wanted is None or key_of(bond) in wanted: take(n) put(bond.model_copy(update={"kind": "authored"})) if wanted is not None: wanted.discard(key_of(bond)) if wanted: raise ValueError(f"{len(wanted)} requested edges are not perceived candidates") elif isinstance(op, ClearPerceived): for n in [n for n, b in enumerate(bonds) if b.kind == "perceived"][::-1]: take(n) perception = None else: current = structure.model_copy(update={"bonds": bonds}) for n in [n for n, b in enumerate(bonds) if b.kind == "distance"][::-1]: take(n) for bond in _cif_distances(current, op): put(bond) if len(bonds) > 100000: raise ValueError("the graph would exceed 100000 edges") previous = graph.get("edits") edits: list[Any] = list(previous) if isinstance(previous, list) else [] record: dict[str, Any] = {"operations": [o.op for o in edit.operations]} if len(added) + len(removed) <= MAX_UNDO_CHANGES: record["added"] = [b.model_dump(mode="json", exclude_none=True) for b in added] record["removed"] = [b.model_dump(mode="json", exclude_none=True) for b in removed] record["perception_before"] = graph.get("perception") edits.append(record) graph["edits"] = edits[-20:] graph["perception"] = perception data = structure.model_dump(mode="json", exclude_none=True) data["bonds"] = [b.model_dump(mode="json", exclude_none=True) for b in bonds] data["provenance"] = {**structure.provenance, "graph": crystal._json(graph)} return PeriodicStructure.model_validate(data)
[docs] def undo_graph_edit(structure: PeriodicStructure) -> PeriodicStructure: """Revert the last recorded graph edit, refusing when its edges changed since.""" graph = structure.provenance.get("graph") previous = graph.get("edits") if isinstance(graph, dict) else None edits: list[Any] = list(previous) if isinstance(previous, list) else [] if not edits: raise ValueError("no graph edit to undo") record = edits[-1] if not isinstance(record, dict) or "added" not in record: raise ValueError("the last graph edit was too large to record its inverse") bonds = list(structure.bonds) for data in record["added"]: bond = PeriodicBond.model_validate(data) if bond not in bonds: raise ValueError("the graph changed after that edit; undo refused") bonds.remove(bond) bonds.extend(PeriodicBond.model_validate(d) for d in record["removed"]) assert isinstance(graph, dict) restored = {**graph, "edits": edits[:-1], "perception": record.get("perception_before")} data = structure.model_dump(mode="json", exclude_none=True) data["bonds"] = [b.model_dump(mode="json", exclude_none=True) for b in bonds] data["provenance"] = {**structure.provenance, "graph": crystal._json(restored)} return PeriodicStructure.model_validate(data)