vibe-sketcherDocumentation

Source code for vibesketcher.document.guest_loading

"""Reproducible guest loading: complete molecules packed into a periodic host (#203).

A loading request names a host structure, the guest components (SMILES, a
document species or explicit atoms) with an explicit count or density each, a
random seed, an orientation policy, a radius table, a collision scale, an
attempt budget and the host-symmetry choice. The preview returns a *derived*
model under a new ID with the requested and placed counts, the rejected trial
insertions by cause, every guest's parent identity and the source digest, or
refusals with stable codes. Nothing is stored until the derived model is
applied, and an applied loading can be undone while the derived model is
unchanged (the same contract as :mod:`vibesketcher.document.periodic_prepare`).

Method. Guests are placed by random sequential insertion of rigid bodies,
the trial-insertion scheme of Monte Carlo packing (Allen and Tildesley,
*Computer Simulation of Liquids*, 2nd ed., 2017, sections 4.4 and 5.3): a
uniformly random centre in the region and, with ``orientation="random"``, a
uniformly random rotation from a unit quaternion (K. Shoemake, "Uniform random
rotations", *Graphics Gems III*, 1992, 124-132). A trial is accepted when no
guest atom comes closer than ``collision_scale (r_i + r_j)`` to a host atom,
an earlier guest or a periodic image of itself; overlap is judged per atom
pair with a per-element radius, as in Packmol's distance tolerance (L.
Martinez, R. Andrade, E. G. Birgin and J. M. Martinez, *J. Comput. Chem.* 30,
2157-2164 (2009), doi:10.1002/jcc.21224). Packmol minimises an overlap
penalty over all molecules at once; this module does not optimise and never
moves an accepted guest, so it fills loosely packed regions and runs out of
budget earlier near close packing, which it reports instead of hiding.
Packmol is not used or required. Neighbour lookup is a linked-cell grid over
lattice planes, as in :func:`vibesketcher.document.periodic_graph.neighbours`.

Every guest keeps its own bond graph (from the SMILES, or explicit bonds), is
stored whole (``coordinates="unwrapped"``: its centre in the home cell, its
atoms contiguous across the faces) or wrapped site by site with bond images,
and never bonds to the host or another guest by proximity. A host symmetry is
never assumed: ``symmetry="p1"`` treats the host as a P1 cell, and
``symmetry="orbit"`` places every guest together with its images under the
host's space-group operations (given, or found by spglib from the
``symmetry`` extra). Charged guests need an explicit compensation statement.

Geometric packing is not adsorption equilibrium, an accessible loading
capacity or a thermodynamic ensemble; a loaded model is a reviewed starting
geometry.
"""

from __future__ import annotations

import hashlib
import json
import math
from collections import Counter
from dataclasses import dataclass, field
from typing import Annotated, Any, Literal, Self

import numpy as np
from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, model_validator

from vibesketcher.document import crystal
from vibesketcher.document import periodic_graph as pg
from vibesketcher.document.model import Document, PeriodicStructure
from vibesketcher.elements import ATOMIC_NUMBER
from vibesketcher.limits import MAX_ATOMS

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

NOTE = (
    "Geometric packing is not adsorption equilibrium, an accessible loading capacity or a "
    "thermodynamic ensemble; the loaded model is a reviewed starting geometry."
)
METHOD = "random sequential rigid-body insertion"
REFERENCES = [
    "M. P. Allen and D. J. Tildesley, Computer Simulation of Liquids, 2nd ed. (2017), 4.4, 5.3",
    "K. Shoemake, Uniform random rotations, Graphics Gems III (1992) 124-132",
    "L. Martinez et al., J. Comput. Chem. 30, 2157 (2009), doi:10.1002/jcc.21224 (tolerance)",
]
#: Trial insertions one request may make.
MAX_ATTEMPTS = 1_000_000
#: Guest molecules one request may ask for.
MAX_GUESTS = 25_000
#: Two orbit copies whose atoms agree within this distance (angstrom) are one molecule.
#: It is far below any collision distance: a guest *near* a special position is
#: rejected as overlapping its image, never merged (which would break the symmetry).
ORBIT_TOLERANCE = 1e-3

#: Stable refusal and notice codes.
CODES: dict[str, str] = {
    "guest.budget_exhausted": "the attempt budget ran out before every guest was placed",
    "guest.partial_placement": "fewer guests were placed than requested (partial result)",
    "guest.nothing_requested": "every component asks for zero guests",
    "guest.too_many_sites": "the loaded model would exceed the site limit",
    "guest.charge_compensation_unstated": "charged guests need a charge_compensation choice",
    "guest.charge_not_compensated": "the stated compensation does not balance the charges",
    "guest.host_charge_unstated": "the compensation needs the host's charge to be stated",
    "guest.symmetry_unavailable": "orbit placement needs operations or the symmetry extra",
    "guest.orbit_region": "orbit placement fills the whole cell, not a region",
    "guest.orbit_density": "a density target is ambiguous under orbit placement",
    "guest.region_empty": "the region has no volume, or the host leaves no vacuum gap",
    "guest.host_partial_occupancy": "the host has partially occupied or disordered sites",
    "guest.host_symmetry_record": "the host's recorded space group describes the host only",
    "guest.multiplicity_unstated": "the loaded model's spin multiplicity is left unstated",
    "guest.bonds_perceived": "a guest's bonds were perceived from its geometry, not drawn",
    "guest.charged_cell": "the loaded model carries a net charge by request",
}


class _Model(BaseModel):
    model_config = ConfigDict(extra="forbid")


[docs] class GuestAtom(_Model): symbol: str xyz: tuple[float, float, float]
[docs] class GuestComponent(_Model): """One guest species and how many copies of it to place.""" label: str | None = Field(default=None, max_length=80) smiles: str | None = Field(default=None, min_length=1, max_length=2000) species: str | None = None atoms: list[GuestAtom] = Field(default_factory=list, max_length=500) #: Bonds of explicit atoms as ``[i, j, order]`` (0-based); perceived when omitted. bonds: list[tuple[int, int, float]] | None = Field(default=None, max_length=2000) #: Net charge of explicit atoms; SMILES and species state their own. charge: int | None = None count: int | None = Field(default=None, ge=0, le=MAX_GUESTS) #: Or a nominal density over the region's volume (host volume not excluded). density_g_cm3: float | None = Field(default=None, gt=0, le=25, allow_inf_nan=False) @model_validator(mode="after") def _one_source(self) -> Self: given = [x for x in (self.smiles, self.species, self.atoms or None) if x] if len(given) != 1: raise ValueError("give exactly one of smiles, species or atoms for a guest") if (self.count is None) == (self.density_g_cm3 is None): raise ValueError("give exactly one of count or density_g_cm3 for a guest") if not self.atoms and (self.bonds is not None or self.charge is not None): raise ValueError("bonds and charge belong to explicit atoms only") for atom in self.atoms: if atom.symbol not in ATOMIC_NUMBER: raise ValueError(f"unknown element {atom.symbol!r}") return self
[docs] class Region(_Model): """Where guest atoms may go: the whole cell, a fractional box or a slab's vacuum gap.""" kind: Literal["cell", "box", "vacuum_gap"] = "cell" lower: _Frac | None = None upper: _Frac | None = None #: vacuum_gap: lattice axis (0, 1 or 2) across the gap, and the clearance kept (angstrom). axis: int = Field(default=2, ge=0, le=2) margin: float = Field(default=1.0, ge=0, le=20, allow_inf_nan=False) @model_validator(mode="after") def _box(self) -> Self: if (self.kind == "box") != (self.lower is not None and self.upper is not None): raise ValueError("a box region takes lower and upper fractional corners, others none") if ( self.lower is not None and self.upper is not None and not all(0 <= lo < hi <= 1 for lo, hi in zip(self.lower, self.upper, strict=True)) ): raise ValueError("box corners need 0 <= lower < upper <= 1 on every axis") return self
[docs] class GuestLoading(_Model): source: _ID identifier: _ID | None = None guests: list[GuestComponent] = Field(min_length=1, max_length=20) seed: int = Field(ge=0, lt=2**63) symmetry: Literal["p1", "orbit"] #: Orbit placement: operations as ``x,y,z`` strings; found by spglib when omitted. operations: list[str] | None = Field(default=None, min_length=1, max_length=192) symprec: float = Field(default=1e-3, gt=0, le=1) orientation: Literal["random", "as_is"] = "random" radii: Literal["vdw", "covalent"] = "vdw" radius_overrides: dict[str, float] = Field(default_factory=dict, max_length=118) collision_scale: float = Field(default=0.75, ge=0.3, le=1.5, allow_inf_nan=False) max_attempts: int = Field(default=10_000, ge=1, le=MAX_ATTEMPTS) on_exhausted: Literal["refuse", "partial"] = "refuse" charge_compensation: Literal["guest_neutral", "host_compensates", "net_charge"] | None = None region: Region = Field(default_factory=Region) coordinates: Literal["unwrapped", "wrapped"] = "unwrapped" @model_validator(mode="after") def _radii(self) -> Self: for symbol, radius in self.radius_overrides.items(): if symbol not in ATOMIC_NUMBER: raise ValueError(f"unknown element {symbol!r} in radius_overrides") if not (math.isfinite(radius) and 0.1 <= radius <= 4.0): raise ValueError("override radii must be between 0.1 and 4 angstrom") if self.operations is not None and self.symmetry != "orbit": raise ValueError("operations belong to symmetry='orbit'") return self
[docs] def parse_loading(data: dict[str, Any]) -> GuestLoading: return TypeAdapter(GuestLoading).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 []} # Guest geometry --------------------------------------------------------------- @dataclass class _Guest: label: str symbols: list[str] #: Cartesian coordinates about the geometric centre (angstrom). xyz: np.ndarray bonds: list[tuple[int, int, float]] bond_kind: Literal["authored", "perceived"] charge: int parent: dict[str, Any] mass: float = 0.0 notices: list[dict[str, Any]] = field(default_factory=list) def _smiles_graph(smiles: str) -> tuple[list[str], list[tuple[int, int, float]], int]: """Symbols (heavy atoms, then RDKit's explicit hydrogens), bonds and the net charge.""" from rdkit import Chem from vibesketcher.chem.species import mol_from_smiles mol = mol_from_smiles(smiles) with_h = Chem.AddHs(mol) bonds = [ (b.GetBeginAtomIdx(), b.GetEndAtomIdx(), float(b.GetBondTypeAsDouble())) for b in with_h.GetBonds() ] return [a.GetSymbol() for a in with_h.GetAtoms()], bonds, int(Chem.GetFormalCharge(mol)) def _perceived(symbols: list[str], xyz: np.ndarray) -> list[tuple[int, int, float]]: """Intramolecular covalent-radii bonds, d <= 1.15 (r_a + r_b), within one guest.""" radii = [pg.covalent_radius(s) for s in symbols] out = [] for i in range(len(symbols)): for j in range(i + 1, len(symbols)): if float(np.linalg.norm(xyz[i] - xyz[j])) <= pg.DEFAULT_SCALE * (radii[i] + radii[j]): out.append((i, j, 1.0)) return out def _mass(symbols: list[str]) -> float: from rdkit import Chem table = Chem.GetPeriodicTable() return float(sum(table.GetAtomicWeight(ATOMIC_NUMBER[s]) for s in symbols)) def _guest(document: Document | None, component: GuestComponent) -> _Guest: notices: list[dict[str, Any]] = [] kind: Literal["authored", "perceived"] if component.atoms: symbols = [a.symbol for a in component.atoms] xyz = np.asarray([a.xyz for a in component.atoms], dtype=float) if component.bonds is None: bonds, kind = _perceived(symbols, xyz), "perceived" else: for i, j, order in component.bonds: if not (0 <= i < len(symbols) and 0 <= j < len(symbols) and i != j and order > 0): raise ValueError("guest bonds take two distinct atom indices and an order > 0") bonds, kind = [(int(i), int(j), float(o)) for i, j, o in component.bonds], "authored" charge = component.charge or 0 label = component.label or "".join(symbols)[:40] parent: dict[str, Any] = {"source": "atoms", "atoms": len(symbols)} else: smiles = component.smiles conformer = None charge = 0 label = component.label or smiles or "" parent = {"source": "smiles", "smiles": smiles} if component.species: if document is None: raise ValueError("a species guest needs the document") found = {s.id: s for s in document.species} if component.species not in found: raise ValueError(f"species {component.species!r} not found") species = found[component.species] label = component.label or species.label or species.id smiles = species.smiles charge = species.charge parent = {"source": "species", "species": species.id, "smiles": smiles} if species.conformers: conformer = species.conformers[0] graph = _smiles_graph(smiles) if smiles else None if graph is not None and not component.species: charge = graph[2] if conformer is None: if smiles is None: raise ValueError("the species has neither 3D coordinates nor SMILES") from vibesketcher.chem.embed import embed_3d conformer = embed_3d(smiles).conformers[0] parent["embedding"] = conformer.method symbols = list(conformer.symbols) xyz = np.asarray(conformer.xyz_angstrom, dtype=float) if graph is not None and graph[0] == symbols: bonds, kind = graph[1], "authored" else: bonds, kind = _perceived(symbols, xyz), "perceived" if kind == "perceived" and len(symbols) > 1: notices.append( _refusal( "guest.bonds_perceived", f"{label}: bonds perceived from the geometry; review them in the graph report", ) ) centre = xyz.mean(axis=0) return _Guest( label=label, symbols=symbols, xyz=xyz - centre, bonds=bonds, bond_kind=kind, charge=int(charge), parent=parent, mass=_mass(symbols), notices=notices, ) # Collision grid ---------------------------------------------------------------
[docs] def radius_of(symbol: str, table: Literal["vdw", "covalent"], overrides: dict[str, float]) -> float: """The collision radius: an override, or RDKit's van der Waals or covalent radius.""" if symbol in overrides: return float(overrides[symbol]) if table == "covalent": return pg.covalent_radius(symbol) from rdkit import Chem return float(Chem.GetPeriodicTable().GetRvdw(ATOMIC_NUMBER[symbol]))
class _Grid: """Occupied atoms binned between lattice planes (bin height >= the largest cutoff). A linked-cell list (Allen and Tildesley 2017, 5.3): a trial atom is compared only with the atoms of its own and the neighbouring bins, over the periodic images that the cutoff can reach. """ def __init__(self, structure: PeriodicStructure, cutoff: float, scale: float) -> None: self.rows = crystal.lattice_rows(structure) self.pbc = structure.pbc self.scale = scale heights = pg._heights(self.rows) self.count = np.asarray([max(1, int(heights[k] // cutoff)) for k in range(3)]) reach = [max(1, math.ceil(cutoff / heights[k])) if self.pbc[k] else 0 for k in range(3)] ranges = [range(-r, r + 1) for r in reach] self.shifts = np.asarray( [(i, j, k) for i in ranges[0] for j in ranges[1] for k in ranges[2]], dtype=float ) self.frac = np.zeros((0, 3)) self.radius = np.zeros(0) self.owner = np.zeros(0, dtype=int) self.bins: dict[tuple[int, int, int], list[int]] = {} self._around: dict[tuple[int, int, int], list[tuple[int, int, int]]] = {} def _bins(self, frac: np.ndarray) -> list[tuple[int, int, int]]: x = np.asarray(frac, dtype=float).copy() for k in range(3): x[:, k] = x[:, k] - np.floor(x[:, k]) if self.pbc[k] else np.clip(x[:, k], 0, 1 - 1e-12) keys = np.minimum((x * self.count).astype(int), self.count - 1) return [(int(i), int(j), int(k)) for i, j, k in keys] def add(self, frac: np.ndarray, radii: list[float], owner: int) -> list[int]: start = len(self.frac) self.frac = np.vstack([self.frac, frac]) self.radius = np.concatenate([self.radius, radii]) self.owner = np.concatenate([self.owner, np.full(len(frac), owner, dtype=int)]) for n, key in enumerate(self._bins(frac)): self.bins.setdefault(key, []).append(start + n) return list(range(start, start + len(frac))) def remove(self, made: list[int]) -> None: """Forget the last atoms added (a rejected trial's copies).""" if not made: return for n, key in zip(made, self._bins(self.frac[made]), strict=True): self.bins[key].remove(n) keep = min(made) self.frac, self.radius, self.owner = self.frac[:keep], self.radius[:keep], self.owner[:keep] def _near(self, home: tuple[int, int, int]) -> list[tuple[int, int, int]]: if home not in self._around: options = [] for k in range(3): c = int(self.count[k]) if self.pbc[k]: these = set(range(c)) if c < 3 else {(home[k] + o) % c for o in (-1, 0, 1)} else: these = {home[k] + o for o in (-1, 0, 1) if 0 <= home[k] + o < c} options.append(sorted(these)) self._around[home] = [ (i, j, k) for i in options[0] for j in options[1] for k in options[2] ] return self._around[home] def distances(self, delta: np.ndarray) -> np.ndarray: """Shortest image distances for fractional differences ``delta`` (... x 3).""" delta = np.array(delta, dtype=float) for k in range(3): if self.pbc[k]: delta[..., k] -= np.round(delta[..., k]) cart = (delta[..., None, :] + self.shifts) @ self.rows return np.asarray(np.sqrt(np.einsum("...i,...i->...", cart, cart)).min(axis=-1)) def clash(self, frac: np.ndarray, radii: list[float]) -> int | None: """The owner of an occupied atom the trial atoms overlap, or ``None``.""" keys = self._bins(frac) r = np.asarray(radii) for start in range(0, len(frac), 32): chosen: set[int] = set() for key in set(keys[start : start + 32]): for near in self._near(key): chosen.update(self.bins.get(near, ())) if not chosen: continue index = np.fromiter(chosen, dtype=int) block = frac[start : start + 32] d = self.distances(self.frac[index][None, :, :] - block[:, None, :]) limit = self.scale * (r[start : start + 32, None] + self.radius[index][None, :]) hit = np.argwhere(d < limit) if len(hit): owners = self.owner[index[hit[:, 1]]] return -1 if np.any(owners == -1) else int(owners.max()) return None def self_image(self, frac: np.ndarray, radii: list[float]) -> bool: """Whether a molecule overlaps one of its own periodic images.""" nonzero = self.shifts[np.any(self.shifts != 0, axis=1)] if not len(nonzero): return False r = np.asarray(radii) delta = frac[None, :, :] - frac[:, None, :] # (i, j, 3) cart = (delta[:, :, None, :] + nonzero) @ self.rows d = np.sqrt(np.einsum("ijsx,ijsx->ijs", cart, cart)).min(axis=-1) return bool(np.any(d < self.scale * (r[:, None] + r[None, :]))) # Placement ---------------------------------------------------------------------- def _rotation(rng: np.random.Generator) -> np.ndarray: """A uniformly distributed rotation matrix (Shoemake 1992, unit quaternion).""" u1, u2, u3 = rng.random(3) a, b = math.sqrt(1 - u1), math.sqrt(u1) x, y = a * math.sin(2 * math.pi * u2), a * math.cos(2 * math.pi * u2) z, w = b * math.sin(2 * math.pi * u3), b * math.cos(2 * math.pi * u3) return np.asarray( [ [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)], [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)], [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)], ] ) def _region_box( host: PeriodicStructure, region: Region, refusals: list[dict[str, Any]] ) -> tuple[np.ndarray, np.ndarray]: """Lower corner and widths (fractional) of the region.""" lower, width = np.zeros(3), np.ones(3) if region.kind == "box": assert region.lower is not None and region.upper is not None lower = np.asarray(region.lower, dtype=float) width = np.asarray(region.upper, dtype=float) - lower elif region.kind == "vacuum_gap": axis = region.axis height = float(pg._heights(crystal.lattice_rows(host))[axis]) values = np.asarray([s.fractional[axis] for s in host.sites], dtype=float) if host.pbc[axis]: values = np.sort(values - np.floor(values)) gaps = np.diff(np.append(values, values[0] + 1.0)) n = int(np.argmax(gaps)) start, size = float(values[n]), float(gaps[n]) else: top, bottom = float(values.max()), float(values.min()) start, size = (top, 1.0 - top) if 1.0 - top >= bottom else (0.0, bottom) clearance = region.margin / height lower[axis] = start + clearance width[axis] = size - 2 * clearance if np.any(width <= 0) or np.any(width > 1 + 1e-9): refusals.append( _refusal("guest.region_empty", "the region has no room between its bounds and margins") ) return lower, width def _symmetry_operations( host: PeriodicStructure, loading: GuestLoading, refusals: list[dict[str, Any]] ) -> tuple[list[tuple[np.ndarray, np.ndarray]], str]: if loading.operations is not None: return [crystal.parse_operation(t) for t in loading.operations], "given" from vibesketcher.document import symmetry try: return symmetry.operations(host, symprec=loading.symprec), "spglib" except (symmetry.SymmetryUnavailable, ValueError) as error: refusals.append(_refusal("guest.symmetry_unavailable", str(error))) return [], "none" def _recorded_symmetry(host: PeriodicStructure) -> dict[str, Any] | None: builder = crystal._builder(host) group = builder.get("space_group") if isinstance(group, dict) and isinstance(group.get("operations"), int): return { "space_group": group.get("hm"), "number": group.get("number"), "operations": group["operations"], } if isinstance(group, dict) and isinstance(builder.get("operations"), int): return { "space_group": group.get("hm"), "number": group.get("number"), "operations": builder["operations"], } return None def _same_molecule(a: np.ndarray, b: np.ndarray, symbols: list[str], grid: _Grid) -> bool: """Whether two copies occupy the same positions with the same elements.""" d = grid.distances(b[None, :, :] - a[:, None, :]) # (i in a, j in b) same = np.asarray(symbols)[:, None] == np.asarray(symbols)[None, :] return bool(np.all(np.any((d < ORBIT_TOLERANCE) & same, axis=1))) def _orbit_copies( base: np.ndarray, operations: list[tuple[np.ndarray, np.ndarray]], symbols: list[str], grid: _Grid, ) -> list[tuple[np.ndarray, np.ndarray]]: """The symmetry images of ``base`` as (unshifted, centred) pairs. Each copy's centre is moved into the home cell along the periodic axes. A copy that lands on an earlier one atom for atom is the same molecule (a guest on a special position) and is dropped. """ copies: list[tuple[np.ndarray, np.ndarray]] = [] centres: list[np.ndarray] = [] for rotation, translation in operations: copy = base @ rotation.T + translation centre = copy.mean(axis=0) shift = np.asarray([math.floor(centre[k]) if grid.pbc[k] else 0 for k in range(3)]) moved = copy - shift if centres: close = np.nonzero(grid.distances(np.asarray(centres) - (centre - shift)) < 0.5)[0] if any(_same_molecule(moved, copies[n][1], symbols, grid) for n in close): continue copies.append((copy, moved)) centres.append(centre - shift) return copies def _collisions( copies: list[tuple[np.ndarray, np.ndarray]], radii: list[float], grid: _Grid, orbit: int ) -> str | None: """Why the copies cannot all be placed, or ``None`` (then they stay in the grid).""" made: list[int] = [] reason = None for _, copy in copies: if grid.self_image(copy, radii): reason = "self_image" break hit = grid.clash(copy, radii) if hit is not None: reason = "host" if hit == -1 else "orbit_overlap" if hit == orbit else "guest" break made += grid.add(copy, radii, orbit) if reason is not None: grid.remove(made) return reason
[docs] def preview( host: PeriodicStructure, loading: GuestLoading, document: Document | None = None ) -> dict[str, Any]: """The loaded model, its counts, rejections, refusals and provenance; nothing is stored.""" refusals: list[dict[str, Any]] = [] notices: list[dict[str, Any]] = [] identifier = loading.identifier or f"{host.id}-loaded"[:64] guests = [_guest(document, c) for c in loading.guests] for g in guests: notices += g.notices if any(s.occupancy < 1 or s.disorder_group for s in host.sites): refusals.append( _refusal( "guest.host_partial_occupancy", "choose an ordered host model before loading guests", [s.id for s in host.sites if s.occupancy < 1 or s.disorder_group][:50], ) ) recorded = _recorded_symmetry(host) if recorded is not None and recorded["operations"] > 1: notices.append( _refusal( "guest.host_symmetry_record", f"the host records {recorded['space_group']} ({recorded['operations']} " f"operations); guests are placed by the {loading.symmetry} choice", ) ) operations: list[tuple[np.ndarray, np.ndarray]] = [(np.eye(3), np.zeros(3))] operations_from = "identity" if loading.symmetry == "orbit": if loading.region.kind != "cell": refusals.append(_refusal("guest.orbit_region", CODES["guest.orbit_region"])) if any(c.density_g_cm3 is not None for c in loading.guests): refusals.append(_refusal("guest.orbit_density", CODES["guest.orbit_density"])) operations, operations_from = _symmetry_operations(host, loading, refusals) lower, width = _region_box(host, loading.region, refusals) rows = crystal.lattice_rows(host) volume = abs(float(np.linalg.det(rows))) * float(np.prod(np.clip(width, 0, None))) requested: list[int] = [] for c, g in zip(loading.guests, guests, strict=True): if c.count is not None: requested.append(c.count) else: assert c.density_g_cm3 is not None # n = rho V N_A / M with V in cm^3 (1 A^3 = 1e-24 cm^3); N_A from CODATA 2018. requested.append(int(round(c.density_g_cm3 * volume * 1e-24 * 6.02214076e23 / g.mass))) if sum(requested) == 0: refusals.append(_refusal("guest.nothing_requested", CODES["guest.nothing_requested"])) if sum(requested) > MAX_GUESTS: refusals.append(_refusal("guest.too_many_sites", f"more than {MAX_GUESTS} guests")) planned_sites = len(host.sites) + sum( n * len(g.symbols) * (len(operations) if loading.symmetry == "orbit" else 1) for n, g in zip(requested, guests, strict=True) ) if loading.symmetry == "p1" and planned_sites > MAX_ATOMS: refusals.append( _refusal("guest.too_many_sites", f"{planned_sites} sites exceed {MAX_ATOMS}") ) charges = [g.charge for g in guests] if any(charges) and loading.charge_compensation is None: refusals.append( _refusal( "guest.charge_compensation_unstated", "charged guests: choose guest_neutral, host_compensates or net_charge", ) ) if loading.charge_compensation in ("host_compensates", "net_charge") and host.charge is None: refusals.append( _refusal("guest.host_charge_unstated", "state the host's charge before loading ions") ) record_base: dict[str, Any] = { "operation": "load_guests", "method": METHOD, "references": REFERENCES, "parameters": loading.model_dump(mode="json", exclude={"source", "identifier"}), "source": host.id, "source_sha256": content_digest(host), "host_symmetry_recorded": recorded, "symmetry": { "choice": loading.symmetry, "operations": len(operations), "operations_from": operations_from, }, "note": NOTE, } result: dict[str, Any] = { "source": host.id, "identifier": identifier, "applicable": False, "refusals": refusals, "notices": notices, "requested": requested, "placed": [0] * len(guests), "molecules": [0] * len(guests), "attempts": 0, "rejections": {}, "guests": [], "source_sha256": record_base["source_sha256"], "provenance": record_base, "derived": None, "codes": CODES, "note": NOTE, } if refusals: return result table = loading.radii overrides = loading.radius_overrides symbols_all = {s.symbol for s in host.sites} | {x for g in guests for x in g.symbols} radius = {s: radius_of(s, table, overrides) for s in symbols_all} cutoff = loading.collision_scale * 2 * max(radius.values()) grid = _Grid(host, cutoff, loading.collision_scale) grid.add( np.asarray([s.fractional for s in host.sites], dtype=float), [radius[s.symbol] for s in host.sites], -1, ) inverse = np.linalg.inv(rows) rng = np.random.Generator(np.random.PCG64(loading.seed)) rejections: Counter[str] = Counter() placements: list[dict[str, Any]] = [] # one per molecule placed = [0] * len(guests) molecules = [0] * len(guests) attempts = 0 exhausted = False orbits = 0 # Axes along which the region (or a nonperiodic face) bounds the atoms. limited = [k for k in range(3) if width[k] < 1 - 1e-12 or not host.pbc[k]] top = lower + width for k in range(3): if not host.pbc[k]: lower[k], top[k] = max(lower[k], 0.0), min(top[k], 1.0) for index, (g, want) in enumerate(zip(guests, requested, strict=True)): radii = [radius[s] for s in g.symbols] for _ in range(want): accepted = False while attempts < loading.max_attempts: attempts += 1 centre = lower + rng.random(3) * width body = g.xyz @ _rotation(rng).T if loading.orientation == "random" else g.xyz base = centre + body @ inverse # unwrapped fractional coordinates first = grid.clash(base, radii) if first is not None: rejections["host" if first == -1 else "guest"] += 1 continue copies = _orbit_copies(base, operations, g.symbols, grid) reason = None for k in limited: values = np.concatenate([c[0][:, k] for c in copies]) if values.min() < lower[k] - 1e-12 or values.max() > top[k] + 1e-12: reason = "outside_region" break if reason is None: reason = _collisions(copies, radii, grid, orbits) if reason is not None: rejections[reason] += 1 continue for n, (_, copy) in enumerate(copies): placements.append( { "component": index, "coordinates": copy, "orbit": orbits, "operation": n, "attempt": attempts, } ) orbits += 1 placed[index] += 1 molecules[index] += len(copies) accepted = True break if not accepted: exhausted = True break if exhausted: break result.update( { "placed": placed, "molecules": molecules, "attempts": attempts, "rejections": dict(sorted(rejections.items())), } ) if exhausted: message = ( f"placed {sum(placed)} of {sum(requested)} guests in {attempts} attempts " f"(rejected: {dict(sorted(rejections.items()))})" ) if loading.on_exhausted == "refuse" or not any(placed): refusals.append(_refusal("guest.budget_exhausted", message)) else: notices.append(_refusal("guest.partial_placement", message)) total_sites = len(host.sites) + sum(len(guests[p["component"]].symbols) for p in placements) if total_sites > MAX_ATOMS: refusals.append(_refusal("guest.too_many_sites", f"{total_sites} sites exceed {MAX_ATOMS}")) guest_charge = sum(guests[p["component"]].charge for p in placements) charge = host.charge if any(charges): mode = loading.charge_compensation if mode == "guest_neutral" and guest_charge != 0: refusals.append( _refusal( "guest.charge_not_compensated", f"the placed guests carry {guest_charge:+d}; guest_neutral needs 0", ) ) elif mode == "host_compensates": assert host.charge is not None if host.charge + guest_charge != 0: refusals.append( _refusal( "guest.charge_not_compensated", f"host {host.charge:+d} and guests {guest_charge:+d} do not cancel", ) ) charge = 0 elif mode == "net_charge": assert host.charge is not None charge = host.charge + guest_charge if charge: notices.append(_refusal("guest.charged_cell", f"net charge {charge:+d}")) multiplicity = host.multiplicity if multiplicity is not None and placements: multiplicity = None notices.append( _refusal("guest.multiplicity_unstated", "state the loaded model's multiplicity") ) result["refusals"], result["notices"] = refusals, notices if refusals: return result # The derived model: the host as it is, then each guest whole with its own bonds. counts = Counter(s.symbol for s in host.sites) taken = {s.id for s in host.sites} sites = [s.model_dump(mode="json", exclude_none=True) for s in host.sites] bonds = [b.model_dump(mode="json", exclude_none=True) for b in host.bonds] records = [] for number, p in enumerate(placements): g = guests[p["component"]] coordinates: np.ndarray = p["coordinates"] wrap = np.zeros((len(coordinates), 3), dtype=int) if loading.coordinates == "wrapped": for k in range(3): if host.pbc[k]: wrap[:, k] = np.floor(coordinates[:, k]).astype(int) ids = [] for symbol, f, w in zip(g.symbols, coordinates, wrap, strict=True): counts[symbol] += 1 while f"{symbol}{counts[symbol]}" in taken: counts[symbol] += 1 sid = f"{symbol}{counts[symbol]}" taken.add(sid) ids.append(sid) sites.append( {"id": sid, "symbol": symbol, "fractional": [crystal._clean(x) for x in f - w]} ) for i, j, order in g.bonds: image = wrap[j] - wrap[i] bonds.append( { "a": ids[i], "b": ids[j], "image": [int(x) for x in image], "order": order, "kind": g.bond_kind, "order_source": "builder", "rule": f"guest {g.label}"[:200], } ) records.append( { "index": number, "component": p["component"], "label": g.label, "parent": g.parent, "charge": g.charge, "sites": ids, "orbit": p["orbit"], "operation": p["operation"], "attempt": p["attempt"], } ) record = { **record_base, "requested": requested, "placed": placed, "molecules": molecules, "attempts": attempts, "rejections": dict(sorted(rejections.items())), "partial": exhausted, "charge_before": host.charge, "charge_after": charge, "guest_charge": guest_charge, "host_sites": len(host.sites), "guests": records, } data = host.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 host.provenance.items() if k not in ("graph", "preparation", "guests") } provenance["guests"] = crystal._json(record) data["provenance"] = provenance made = PeriodicStructure.model_validate(data) provenance["guests"] = {**provenance["guests"], "derived_sha256": content_digest(made)} # type: ignore[dict-item] made = made.model_copy(update={"provenance": provenance}) result.update( { "applicable": True, "guests": records, "provenance": provenance["guests"], "derived": made.model_dump(mode="json", exclude_none=True), } ) return result
[docs] def apply( document: Document, loading: GuestLoading, *, source_sha256: str | None = None ) -> Document: """Add the loaded 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 loading.source not in existing: raise ValueError(f"periodic structure {loading.source!r} not found") source = existing[loading.source] if source_sha256 is not None and source_sha256 != content_digest(source): raise ValueError("the host structure changed since the preview") result = preview(source, loading, document) 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 placed" raise ValueError(f"guest loading refused: {reasons}") return with_periodic(document, PeriodicStructure.model_validate(result["derived"]))
[docs] def undo(document: Document, identifier: str) -> Document: """Remove a loaded model again, if it is unchanged since it was loaded.""" 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("guests") if not isinstance(record, dict) or "derived_sha256" not in record: raise ValueError(f"{identifier} is not a guest-loaded model") if record["derived_sha256"] != content_digest(structure): raise ValueError(f"{identifier} changed after it was loaded; 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)