From 254736456edb27936c432eeeab9a5da3c3c39d30 Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Sun, 25 Oct 2026 09:43:03 +0800 Subject: [PATCH 1/6] feat(confsearch): core library without a calculator (P1) Tracking: #61 (spec revision 4, phase P1) Part of the MD-based configuration search feature. What was missing: mliport/confsearch/ did not exist, so nothing could prepare starts, describe a minimum, or deduplicate quench results. What this adds (calculator-free, synthetic-structure testable): - options.py: frozen ConfsearchOptions with every section 12.3 cross-key rule (mode A/B exclusivity, exact integer step conversions with nearest valid values, break > bond scale, binwidth <= sigma/2, v1 non-goals rejected by name), index_spec.py: the 0-based "0,5,7-9" parser with compression. - regions.py: A/S/F/R resolution, FixScaled/FixCom rejection, cs_fix_below, the +z surface convention, slab contiguity, one-sided adsorption, non-ionic adsorbate connectivity, the H/timestep gate and the section 7.2 mobile sets. - graphs.py: covalent graphs from ase.data.covalent_radii, ionic exclusion, the MD break-scale check, chemisorption flags, slab-rearrangement flags and the section 8.2 status rules in order. - fingerprint.py: focused Oganov-Valle with ASE's discretisation (spec 9.2 revision 3): nbins = ceil(rcut/Delta), bin radius (k+1)Delta, erf bin smearing renormalised to 1, 4 pi r^2 Delta and N_beta/V normalisation, ordered species keys and the section 9.2 weights. - registry.py: delta-E AND (G OR D) matching (spec 9.3 revision 4), the direct geometric identity G with cs_dedup_geom_tol (disabled and recorded when F is empty), smallest (not G, D) selection, per-status registries, representative update and the section 9.5 consolidation pass. - placement.py: centroiding, Shoemake rotations, contact and anchored placement solved by bisection on element-pair covalent-radii ratios, anchor targets, per-reason rejection counts and the recorded placement provenance. Deviations from the letter of section 9.2, both required by section 9.2 itself and documented in the module docstring: - self-image pairs are enumerated explicitly because ASE's neighbor_list returns an orientation-dependent subset of them (48 vs 72 pairs on a 4x4x20 A slab before/after a rigid rotation, while the 350 cross pairs are identical); - pair distances are rounded to 1e-9 A before the bin division because a distance at a decimal multiple of Delta (e.g. a 0.96 A O-H bond) otherwise flips its whole 21-bin smearing window under a rigid rotation. The strict ASE known-answer tests still pass to 1e-10 on non-boundary geometries (per-bin arrays, F_ab == F_ba, collapsed D), and scipy/matplotlib were added to the dev extra so they run in CI instead of skipping. Calibration (spec 13.2 revision 4, geometry-labelled pairs on the repository's LGPS structure, pinned as a regression test): same basin 25 pairs (G), 11 documented false splits (0.20-0.5 A); distinct sites/conformers 63 pairs, min D = 8.5e-4 at sigma = 0.20; equivalent pairs (rigid slab map + CH3 permutation) all merge (D ~ 0). Shipped defaults: cs_fp_sigma = 0.20, cs_dedup_fp_tol = 0.0004 (zero false merges with a factor-2 margin), cs_dedup_geom_tol = 0.20 A. DATA IMPACT: no scientific record invalidated (no existing workflow changed). New defaults are recorded here and in the calibration test; the P2 engine will re-run the same sweep with real quenches at cs_quench_fmax. Full suite on CPU: 1555 passed, 33 skipped. --- mliport/mliport/confsearch/__init__.py | 110 +++ mliport/mliport/confsearch/errors.py | 101 +++ mliport/mliport/confsearch/fingerprint.py | 349 +++++++++ mliport/mliport/confsearch/geometry.py | 156 ++++ mliport/mliport/confsearch/graphs.py | 402 ++++++++++ mliport/mliport/confsearch/index_spec.py | 148 ++++ mliport/mliport/confsearch/options.py | 705 ++++++++++++++++++ mliport/mliport/confsearch/placement.py | 409 ++++++++++ mliport/mliport/confsearch/regions.py | 321 ++++++++ mliport/mliport/confsearch/registry.py | 386 ++++++++++ mliport/mliport/confsearch/revisions.py | 25 + mliport/mliport/confsearch/status.py | 77 ++ mliport/pyproject.toml | 6 + tests/mliport/mliport/confsearch/__init__.py | 0 .../mliport/mliport/confsearch/structures.py | 163 ++++ .../mliport/confsearch/test_fingerprint.py | 567 ++++++++++++++ .../test_fingerprint_calibration.py | 395 ++++++++++ .../mliport/confsearch/test_options.py | 168 +++++ .../mliport/confsearch/test_placement.py | 282 +++++++ .../confsearch/test_regions_and_graphs.py | 412 ++++++++++ .../mliport/confsearch/test_registry.py | 211 ++++++ 21 files changed, 5393 insertions(+) create mode 100644 mliport/mliport/confsearch/__init__.py create mode 100644 mliport/mliport/confsearch/errors.py create mode 100644 mliport/mliport/confsearch/fingerprint.py create mode 100644 mliport/mliport/confsearch/geometry.py create mode 100644 mliport/mliport/confsearch/graphs.py create mode 100644 mliport/mliport/confsearch/index_spec.py create mode 100644 mliport/mliport/confsearch/options.py create mode 100644 mliport/mliport/confsearch/placement.py create mode 100644 mliport/mliport/confsearch/regions.py create mode 100644 mliport/mliport/confsearch/registry.py create mode 100644 mliport/mliport/confsearch/revisions.py create mode 100644 mliport/mliport/confsearch/status.py create mode 100644 tests/mliport/mliport/confsearch/__init__.py create mode 100644 tests/mliport/mliport/confsearch/structures.py create mode 100644 tests/mliport/mliport/confsearch/test_fingerprint.py create mode 100644 tests/mliport/mliport/confsearch/test_fingerprint_calibration.py create mode 100644 tests/mliport/mliport/confsearch/test_options.py create mode 100644 tests/mliport/mliport/confsearch/test_placement.py create mode 100644 tests/mliport/mliport/confsearch/test_regions_and_graphs.py create mode 100644 tests/mliport/mliport/confsearch/test_registry.py diff --git a/mliport/mliport/confsearch/__init__.py b/mliport/mliport/confsearch/__init__.py new file mode 100644 index 00000000..5a1b6ac9 --- /dev/null +++ b/mliport/mliport/confsearch/__init__.py @@ -0,0 +1,110 @@ +"""Core library of the MD-based configuration search (confsearch). + +Phase P1 of the PR #61 implementation plan: options, regions, covalent graphs +and status rules, the focused fingerprint, the deduplicating registry and +automatic placement. Nothing here loads a calculator; the search engine +(phase P2) drives these pieces. +""" + +from __future__ import annotations + +from mliport.confsearch.errors import ( + ConfsearchError, + ConfsearchGradientConsistencyError, + ConfsearchInternalError, + ConfsearchNotImplementedError, + ConfsearchPreparationError, +) +from mliport.confsearch.fingerprint import ( + FingerprintGrid, + FocusedFingerprint, + build_fingerprint, + fingerprint_distance, +) +from mliport.confsearch.geometry import ( + mic_distance_matrix, + mic_vectors, + minimum_distance, + self_image_distance, + vacuum_gap, +) +from mliport.confsearch.graphs import ( + ClassificationReference, + CovalentGraph, + GraphDifference, + MinimumClassification, + broken_reference_bonds, + classify_minimum, + covalent_bonds, +) +from mliport.confsearch.index_spec import format_index_spec, parse_index_spec +from mliport.confsearch.options import CS_DEFAULTS, ConfsearchOptions, steps_from_ps +from mliport.confsearch.placement import ( + PlacementResult, + place_molecule, + random_rotation_matrix, +) +from mliport.confsearch.regions import ( + Regions, + SurfaceGeometry, + mobile_indices, + resolve_regions, + validate_all, + validate_surface, +) +from mliport.confsearch.registry import ( + MinimumOrigin, + MinimumRecord, + MinimumRegistry, + UniqueMinimum, +) +from mliport.confsearch.revisions import ( + CS_CHECKPOINT_SCHEMA_REVISION, + CS_SCIENTIFIC_REVISION, + CS_SPEC_REVISION, +) + +__all__ = [ + "CS_CHECKPOINT_SCHEMA_REVISION", + "CS_DEFAULTS", + "CS_SCIENTIFIC_REVISION", + "CS_SPEC_REVISION", + "ClassificationReference", + "ConfsearchError", + "ConfsearchGradientConsistencyError", + "ConfsearchInternalError", + "ConfsearchNotImplementedError", + "ConfsearchOptions", + "ConfsearchPreparationError", + "CovalentGraph", + "FingerprintGrid", + "FocusedFingerprint", + "GraphDifference", + "MinimumClassification", + "MinimumOrigin", + "MinimumRecord", + "MinimumRegistry", + "PlacementResult", + "Regions", + "SurfaceGeometry", + "UniqueMinimum", + "broken_reference_bonds", + "build_fingerprint", + "classify_minimum", + "covalent_bonds", + "fingerprint_distance", + "format_index_spec", + "mic_distance_matrix", + "mic_vectors", + "minimum_distance", + "mobile_indices", + "parse_index_spec", + "place_molecule", + "random_rotation_matrix", + "resolve_regions", + "self_image_distance", + "steps_from_ps", + "validate_all", + "validate_surface", + "vacuum_gap", +] diff --git a/mliport/mliport/confsearch/errors.py b/mliport/mliport/confsearch/errors.py new file mode 100644 index 00000000..addd949b --- /dev/null +++ b/mliport/mliport/confsearch/errors.py @@ -0,0 +1,101 @@ +"""Exceptions and scope gates for the confsearch workflow. + +Section 2.2 of the specification lists explicit v1 non-goals. A request that +falls outside v1 must raise a clear error that *names* the non-goal; it must +never fall back to a half-implementation or a silently different calculation. +""" + +from __future__ import annotations + + +class ConfsearchError(ValueError): + """Base class for invalid or unsupported confsearch inputs.""" + + +class ConfsearchPreparationError(ConfsearchError): + """Inputs cannot be prepared without changing their physical meaning.""" + + +class ConfsearchNotImplementedError(ConfsearchError): + """A requested feature is an explicit v1 non-goal.""" + + +class ConfsearchGradientConsistencyError(ConfsearchError): + """The model's forces are not (verifiably) the gradient of its energy.""" + + +class ConfsearchInternalError(RuntimeError): + """A violated invariant that is a bug, not a scientific outcome. + + Example: a fixed atom moved during MD/quench (spec section 8.2 rule 1). The + whole search aborts; this must never be reported as a result. + """ + + +#: v1 non-goals (spec section 2.2), mapped to the error text a user sees. +NON_GOALS: dict[str, str] = { + "npt": ( + "NPT or any variable-cell MD is a v1 non-goal; the cell stays fixed " + "(NVT, and quenches/refinement are fixed-cell)" + ), + "variable_cell": ( + "variable-cell refinement is a v1 non-goal; a slab cell must stay fixed" + ), + "bulk_mobile": ( + "bulk modes (mobile-ion arrangement, substitutional ordering) are a v1 " + "non-goal; only cs_mode='adsorbate' is implemented" + ), + "melt_quench": ( + "amorphous melt-quench is a v1 non-goal; only cs_mode='adsorbate' is " + "implemented" + ), + "interface": ( + "interface searches are a v1 non-goal; only cs_mode='adsorbate' is " + "implemented" + ), + "multi_adsorbate": ( + "multiple adsorbates/coverage are a v1 non-goal; place exactly one " + "molecule on one side of the slab" + ), + "two_sided": ( + "two-sided slabs are a v1 non-goal; the adsorbate must be above the " + "slab's +z surface" + ), + "replica_exchange": ( + "replica exchange is a v1 non-goal; replicas are independent MD chains" + ), + "metadynamics": ( + "metadynamics, bias potentials, restraints and walls are v1 non-goals; " + "no term may change the potential energy surface" + ), + "free_energy": ( + "free energies, Boltzmann populations and adsorption energies are v1 " + "non-goals; use the existing opt workflow for separately computed " + "references" + ), + "gas_phase": ( + "gas-phase conformer generation is a v1 non-goal; bring conformers " + "from CREST/xtb as cs_molecule frames" + ), + "molecular": ( + "molecular (non-periodic) tasks are a v1 non-goal; confsearch requires " + "a 3D-periodic slab" + ), +} + + +def reject_non_goal(name: str) -> ConfsearchNotImplementedError: + """Return the fail-closed error for a named v1 non-goal.""" + detail = NON_GOALS.get(name, f"{name!r} is outside the confsearch v1 scope") + return ConfsearchNotImplementedError(f"confsearch: {detail}") + + +__all__ = [ + "NON_GOALS", + "ConfsearchError", + "ConfsearchGradientConsistencyError", + "ConfsearchInternalError", + "ConfsearchNotImplementedError", + "ConfsearchPreparationError", + "reject_non_goal", +] diff --git a/mliport/mliport/confsearch/fingerprint.py b/mliport/mliport/confsearch/fingerprint.py new file mode 100644 index 00000000..7e84106b --- /dev/null +++ b/mliport/mliport/confsearch/fingerprint.py @@ -0,0 +1,349 @@ +"""Focused Oganov-Valle fingerprint (spec section 9.2). + +ASE's ``OFPComparator`` is deliberately not used: + +* with ``n_top`` it fingerprints the adsorbate in isolation (slab atoms are + excluded, so adsorption sites are invisible); +* it imports matplotlib at module level. + +This module implements the descriptor in NumPy instead. The *species +structure* is exactly the one the specification defines: centres are the +adsorbate atoms ``A``, neighbours are all atoms, and every **ordered** species +pair ``(alpha, beta)`` with ``alpha in species(A)`` and ``beta in +species(all)`` gets its own fingerprint + + F_ab(r_b) = sum_{i in A, a} sum_{j in b} g(r_b - d_ij) + / (4 pi r_b^2 (N_b / V) Delta n_a) - 1 + +with ``g`` a Gaussian truncated at ``4 sigma`` and the weights +``w_ab = n_a N_b / sum(n_a' N_b')``. + +Discretisation (decision recorded for the PR #61 review of section 9.2): the +specification's literal bin centres ``r_k = (k + 1/2) Delta`` are *not* +compatible with its own known-answer requirement that the implementation agree +with ``OFPComparator`` to 1e-6 in ``D``. ASE places the bin centres at +``r_k = (k + 1) Delta`` and integrates the Gaussian over each bin analytically +(erf differences) instead of point-sampling it; measured on a periodic +single-species system with sigma=0.05, Delta=0.02, rcut=8.0 the two +discretisations differ by ~1.5e-3 in ``D``, i.e. 1500x the required tolerance. +The owner chose the ASE discretisation, so this module reproduces it exactly: +``nbins = ceil(rcut / Delta)``, ``r_k = (k + 1) Delta``, +``m = ceil(4 sigma / Delta)`` and the bin weights +``0.5 [erf(c(2i+1)) - erf(c(2i-1))] / erf(c(2m+1))`` with +``c = sqrt(2) Delta / (4 sigma)``. + +For a single-species system with ``A`` = all atoms the ordered matrix collapses +to ASE's key set and weights, and the known-answer test then asserts agreement +to 1e-6 in ``D`` (it is skipped when ASE's deprecated ``OFPComparator`` is not +importable). + +Self-image pairs (``i == j`` with a non-zero lattice offset) are enumerated +explicitly instead of being taken from ``neighbor_list``. ASE's primitive +neighbour list returns an *orientation-dependent subset* of them (measured on a +4x4x20 A slab with rcut=8: 48 self pairs before and 72 after a rigid rotation of +the whole cell, while the 350 cross pairs are identical), which would make the +descriptor depend on how the cell happens to be oriented in space. The distance +of a self-image pair is ``|n . cell|``, so the explicit enumeration is complete +and rotation-covariant. ASE's ``NeighborList`` (which ``OFPComparator`` uses) +does return the complete self-image shell, so the known-answer comparison is +unaffected. + +The 1e-9 A rounding described in :func:`_bin_weights` is what makes the +descriptor invariant to a rigid rotation of the whole cell: without it, a +distance at a decimal multiple of ``Delta`` (0.96 A is 47.99999999999999 bins) +flips bin when the same structure is rotated by a floating-point matrix. It is +the only place where this module deviates from a verbatim port of ASE's +discretisation, and it cannot change a per-bin value unless a distance lies +within 5e-10 A of a bin boundary without lying exactly on it. +""" + +from __future__ import annotations + +import math +from dataclasses import dataclass +from typing import TYPE_CHECKING + +import numpy as np +from ase.neighborlist import neighbor_list + +from mliport.confsearch.errors import ConfsearchError + +if TYPE_CHECKING: + from collections.abc import Mapping + + from ase import Atoms + + from mliport.confsearch.options import ConfsearchOptions + +#: Truncation of the Gaussian in units of sigma (spec section 9.2). +NSIGMA = 4.0 +#: Shortcut: energy gaps above this skip the (expensive) fingerprint distance. +DEDUP_ENERGY_SHORTCUT_EV = 0.2 + +_SQRT2 = math.sqrt(2.0) +_INV_SQRT_2PI = 1.0 / math.sqrt(2.0 * math.pi) + + +@dataclass(frozen=True, slots=True) +class FingerprintGrid: + """The discretisation shared by every fingerprint of one search.""" + + rcut: float + binwidth: float + sigma: float + n_bins: int + centres: np.ndarray + #: Per-bin Gaussian weights for offsets ``-m..m`` (normalised to sum 1). + smearing: np.ndarray + + @classmethod + def build(cls, *, rcut: float, binwidth: float, sigma: float) -> FingerprintGrid: + n_bins = int(math.ceil(rcut / binwidth)) + if n_bins < 1: + raise ConfsearchError( + f"cs_fp_rcut ({rcut}) must be at least one bin " + f"(cs_fp_binwidth={binwidth})" + ) + centres = binwidth * np.arange(1, n_bins + 1, dtype=float) + m = int(math.ceil(NSIGMA * sigma / binwidth)) + c = 0.25 * _SQRT2 * binwidth / sigma + smearing = np.array( + [ + 0.5 * (math.erf(c * (2 * i + 1)) - math.erf(c * (2 * i - 1))) + for i in range(-m, m + 1) + ], + dtype=float, + ) + smearing = smearing / math.erf(c * (2 * m + 1)) + return cls( + rcut=float(rcut), + binwidth=float(binwidth), + sigma=float(sigma), + n_bins=n_bins, + centres=centres, + smearing=smearing, + ) + + @property + def window(self) -> int: + return (self.smearing.size - 1) // 2 + + +@dataclass(frozen=True, slots=True) +class FocusedFingerprint: + """The focused descriptor of one structure.""" + + species_centres: tuple[str, ...] + species_all: tuple[str, ...] + values: Mapping[tuple[str, str], np.ndarray] + weights: Mapping[tuple[str, str], float] + + @property + def keys(self) -> tuple[tuple[str, str], ...]: + return tuple(self.values) + + def norm(self) -> float: + total = 0.0 + for key, value in self.values.items(): + total += self.weights[key] * float(np.dot(value, value)) + return math.sqrt(total) + + def distance(self, other: FocusedFingerprint) -> float: + """Cosine-style distance ``D`` from spec section 9.2.""" + if self.species_centres != other.species_centres or ( + self.species_all != other.species_all + ): + raise ConfsearchError( + "Fingerprints are only comparable when the species sets match; " + f"got {self.species_centres}/{self.species_all} and " + f"{other.species_centres}/{other.species_all}" + ) + norm_self = self.norm() + norm_other = other.norm() + if norm_self == 0.0 and norm_other == 0.0: + return 0.0 + if norm_self == 0.0 or norm_other == 0.0: + return 1.0 + dot = 0.0 + for key, value in self.values.items(): + dot += self.weights[key] * float(np.dot(value, other.values[key])) + return 0.5 * (1.0 - dot / (norm_self * norm_other)) + + def to_dict(self) -> dict: + return { + "species_centres": list(self.species_centres), + "species_all": list(self.species_all), + "weights": {f"{a}-{b}": w for (a, b), w in self.weights.items()}, + "values": { + f"{a}-{b}": [float(x) for x in value] + for (a, b), value in self.values.items() + }, + } + + +def lattice_image_distances( + cell: np.ndarray, rcut: float, *, max_images: int = 100_000 +) -> np.ndarray: + """Distances ``|n . cell|`` in ``(0, rcut]`` for all non-zero integer ``n``. + + The search range is rigorous: ``|n . cell| >= |n_i| d_i`` where ``d_i`` is + the spacing between the lattice planes perpendicular to cell vector ``i``, + so only ``|n_i| <= rcut / d_i`` can contribute. Lengths are rounded to + 1e-9 A before the ``< rcut`` test for the same reason as + :func:`_bin_weights`: an image at exactly ``rcut`` must be excluded + consistently, whatever the cell's orientation in space. + """ + matrix = np.asarray(cell, dtype=float) + volume = abs(float(np.linalg.det(matrix))) + if volume <= 0.0: + raise ConfsearchError("Self-image distances need a full-rank cell") + ranges = [] + for axis in range(3): + others = [index for index in range(3) if index != axis] + area = float(np.linalg.norm(np.cross(matrix[others[0]], matrix[others[1]]))) + spacing = volume / area if area > 0 else 0.0 + if spacing <= 0.0: + raise ConfsearchError("Cell vectors must be non-degenerate") + limit = int(math.floor(rcut / spacing)) + 1 + ranges.append(range(-limit, limit + 1)) + combinations = np.array(np.meshgrid(*ranges, indexing="ij")).reshape(3, -1).T + if combinations.shape[0] > max_images: + raise ConfsearchError( + f"cs_fp_rcut={rcut} needs {combinations.shape[0]} lattice images for " + "the self-image check; reduce cs_fp_rcut or use a larger cell" + ) + nonzero = combinations[np.any(combinations != 0, axis=1)] + if nonzero.size == 0: + return np.zeros(0, dtype=float) + lengths = np.linalg.norm(nonzero @ matrix, axis=1) + keep = (lengths > 0.0) & (np.round(lengths, 9) < rcut) + return np.sort(lengths[keep]) + + +def _bin_weights(distances: np.ndarray, grid: FingerprintGrid) -> np.ndarray: + """Accumulate the smeared pair distances into the radial bins. + + The binning is ASE's: ``k = floor(d / Delta)`` and the pair is spread over + ``k + i`` for ``i = -m..m`` with the out-of-range bins dropped. The only + deviation is that ``d`` is rounded to 1e-9 A before the division, because a + distance that is a decimal multiple of Delta (a textbook bond length such as + 0.96 A) sits systematically ~1e-16 below the bin boundary and a rigid + rotation of the same structure would flip its whole 21-bin smearing window, + breaking the rotation invariance section 9.2 requires. 1e-9 A is 1e-3 fm, + far below any physical distance difference; for a distance that is exactly + on a boundary both implementations still agree, and elsewhere they agree + unless a distance lies within 5e-10 A of a boundary without being on it. + """ + values = np.zeros(grid.n_bins, dtype=float) + if distances.size == 0: + return values + base = np.floor(np.round(distances, 9) / grid.binwidth).astype(int) + window = grid.window + for offset_index, offset in enumerate(range(-window, window + 1)): + targets = base + offset + valid = (targets >= 0) & (targets < grid.n_bins) + if not np.any(valid): + continue + np.add.at(values, targets[valid], grid.smearing[offset_index]) + return values + + +def build_fingerprint( + atoms: Atoms, + adsorbate: np.ndarray, + *, + options: ConfsearchOptions, + grid: FingerprintGrid | None = None, +) -> FocusedFingerprint: + """Build the focused fingerprint of ``atoms`` around the ``adsorbate`` set.""" + centres = np.asarray(adsorbate, dtype=int) + if centres.size == 0: + raise ConfsearchError("A fingerprint needs a non-empty adsorbate set A") + if grid is None: + grid = FingerprintGrid.build( + rcut=options.cs_fp_rcut, + binwidth=options.cs_fp_binwidth, + sigma=options.cs_fp_sigma, + ) + + symbols = np.array(atoms.get_chemical_symbols(), dtype=object) + volume = float(abs(np.linalg.det(np.asarray(atoms.cell, dtype=float)))) + if volume <= 0.0: + raise ConfsearchError( + "A focused fingerprint needs a full-rank cell; got a zero volume" + ) + + species_centres = tuple(sorted(set(symbols[centres]))) + species_all = tuple(sorted(set(symbols))) + counts_centres = { + species: int(np.count_nonzero(symbols[centres] == species)) + for species in species_centres + } + counts_all = { + species: int(np.count_nonzero(symbols == species)) for species in species_all + } + + i, j, distances = neighbor_list("ijd", atoms, grid.rcut, self_interaction=False) + i = np.asarray(i, dtype=int) + j = np.asarray(j, dtype=int) + distances = np.asarray(distances, dtype=float) + # Cross pairs come from ASE's neighbour list; self-image pairs (i == j) are + # enumerated explicitly below because that function returns an + # orientation-dependent subset of them. + keep = (i != j) & np.isin(i, centres) + i, j, distances = i[keep], j[keep], distances[keep] + self_image_distances = lattice_image_distances(atoms.cell, grid.rcut) + + total_weight = 0.0 + weights: dict[tuple[str, str], float] = {} + for alpha in species_centres: + for beta in species_all: + weight = counts_centres[alpha] * counts_all[beta] + weights[(alpha, beta)] = float(weight) + total_weight += weight + + values: dict[tuple[str, str], np.ndarray] = {} + for alpha in species_centres: + for beta in species_all: + selected = (symbols[i] == alpha) & (symbols[j] == beta) + bins = _bin_weights(distances[selected], grid) + if alpha == beta and self_image_distances.size: + # Every centre of species alpha sees the same image shell. + bins = bins + _bin_weights( + np.tile(self_image_distances, counts_centres[alpha]), grid + ) + density = counts_all[beta] / volume + denominator = ( + 4.0 + * math.pi + * grid.centres**2 + * density + * grid.binwidth + * counts_centres[alpha] + ) + values[(alpha, beta)] = bins / denominator - 1.0 + weights[(alpha, beta)] /= total_weight + return FocusedFingerprint( + species_centres=species_centres, + species_all=species_all, + values=values, + weights=weights, + ) + + +def fingerprint_distance( + first: FocusedFingerprint, second: FocusedFingerprint +) -> float: + """Distance between two fingerprints (spec section 9.2).""" + return first.distance(second) + + +__all__ = [ + "DEDUP_ENERGY_SHORTCUT_EV", + "NSIGMA", + "FingerprintGrid", + "FocusedFingerprint", + "build_fingerprint", + "fingerprint_distance", + "lattice_image_distances", +] diff --git a/mliport/mliport/confsearch/geometry.py b/mliport/mliport/confsearch/geometry.py new file mode 100644 index 00000000..bff03db5 --- /dev/null +++ b/mliport/mliport/confsearch/geometry.py @@ -0,0 +1,156 @@ +"""Minimum-image geometry helpers for the confsearch core. + +All distances in confsearch are minimum-image distances (MIC) unless a rule +explicitly says otherwise (the periodic-image self-check in section 8.4 uses +explicit in-plane translations, and the vacuum check uses the explicit ``+c`` +image). +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +import numpy as np + +from mliport.confsearch.errors import ConfsearchError + +if TYPE_CHECKING: + from ase import Atoms + + +def mic_vectors(cell: np.ndarray, deltas: np.ndarray) -> np.ndarray: + """Fold Cartesian displacement vectors into the minimum-image convention.""" + array = np.asarray(deltas, dtype=float) + if array.size == 0: + return array.reshape(array.shape) + matrix = np.asarray(cell, dtype=float) + determinant = float(np.linalg.det(matrix)) + if abs(determinant) <= 1e-12: + raise ConfsearchError( + "Minimum-image distances need a full-rank cell; got a singular cell" + ) + fractional = array @ np.linalg.inv(matrix) + fractional -= np.round(fractional) + return fractional @ matrix + + +def mic_distance_matrix( + atoms: Atoms, first: np.ndarray, second: np.ndarray +) -> np.ndarray: + """MIC distances between every ``first`` and every ``second`` atom.""" + left = np.asarray(first, dtype=int) + right = np.asarray(second, dtype=int) + if left.size == 0 or right.size == 0: + return np.zeros((left.size, right.size), dtype=float) + positions = np.asarray(atoms.get_positions(), dtype=float) + deltas = positions[right][None, :, :] - positions[left][:, None, :] + return np.linalg.norm(mic_vectors(atoms.cell, deltas), axis=2) + + +def minimum_distance(atoms: Atoms, first: np.ndarray, second: np.ndarray) -> float: + """Smallest MIC distance between two atom-index sets.""" + matrix = mic_distance_matrix(atoms, first, second) + if matrix.size == 0: + return float("inf") + return float(np.min(matrix)) + + +def mic_displacements(atoms: Atoms, deltas: np.ndarray) -> np.ndarray: + """MIC displacement lengths of Cartesian displacement vectors.""" + folded = mic_vectors(atoms.cell, deltas) + return np.linalg.norm(folded, axis=1) + + +def self_image_distance(atoms: Atoms, adsorbate: np.ndarray) -> float: + """Smallest distance to a periodic in-plane copy of the adsorbate. + + The candidate translations are ``n_a*a + n_b*b`` with + ``(n_a, n_b) in {-2..2}^2 \\ {(0, 0)}``. The wider-than-``+-1`` shell keeps + the guard conservative for skewed in-plane cells; the cell stays fixed, so + the recorded value is reproducible. + """ + indices = np.asarray(adsorbate, dtype=int) + if indices.size == 0: + return float("inf") + positions = np.asarray(atoms.get_positions(), dtype=float) + cell = np.asarray(atoms.cell, dtype=float) + best = float("inf") + shifts = [ + na * cell[0] + nb * cell[1] + for na in range(-2, 3) + for nb in range(-2, 3) + if (na, nb) != (0, 0) + ] + for shift in shifts: + deltas = (positions[indices][None, :, :] + shift) - positions[indices][ + :, None, : + ] + if deltas.size == 0: + continue + distances = np.linalg.norm(deltas, axis=2) + best = min(best, float(np.min(distances))) + return best + + +def vacuum_gap(atoms: Atoms, adsorbate: np.ndarray, slab: np.ndarray) -> float: + """Smallest distance from the adsorbate to the slab image shifted by ``+c``.""" + indices = np.asarray(adsorbate, dtype=int) + slab_indices = np.asarray(slab, dtype=int) + if indices.size == 0 or slab_indices.size == 0: + return float("inf") + positions = np.asarray(atoms.get_positions(), dtype=float) + cell = np.asarray(atoms.cell, dtype=float) + deltas = (positions[slab_indices][None, :, :] + cell[2]) - positions[indices][ + :, None, : + ] + return float(np.min(np.linalg.norm(deltas, axis=2))) + + +def wrap_positions(atoms: Atoms) -> np.ndarray: + """Positions wrapped into the cell (fractional coordinates in [0, 1)).""" + wrapped = atoms.copy() + wrapped.wrap() + return np.asarray(wrapped.get_positions(), dtype=float) + + +def periodic_gap_and_contiguity( + slab_z: np.ndarray, cell_height: float +) -> tuple[float, float]: + """Return ``(periodic_gap, largest_internal_gap)`` for slab z coordinates. + + ``periodic_gap`` is the gap across the ``c`` boundary (``z_min + c - z_max``) + and ``largest_internal_gap`` the largest gap between consecutive wrapped slab + atoms. The slab occupies one interval only when the periodic gap is the + vacuum, i.e. strictly larger than every internal gap (spec section 5.3). + """ + if cell_height <= 0: + raise ConfsearchError("The cell height c_z must be positive") + values = np.sort(np.asarray(slab_z, dtype=float)) + if values.size == 0: + raise ConfsearchError("The slab contains no atoms") + if values.size == 1: + return float(cell_height), 0.0 + internal = np.diff(values) + periodic = float(values[0] + cell_height - values[-1]) + return periodic, float(np.max(internal)) if internal.size else 0.0 + + +def slab_interval(slab_z: np.ndarray, cell_height: float) -> tuple[float, float]: + """Wrapped z interval ``(z_min, z_max)`` occupied by the slab.""" + values = np.sort(np.asarray(slab_z, dtype=float)) + if values.size == 0: + raise ConfsearchError("The slab contains no atoms") + return float(values[0]), float(values[-1]) + + +__all__ = [ + "mic_displacements", + "mic_distance_matrix", + "mic_vectors", + "minimum_distance", + "periodic_gap_and_contiguity", + "self_image_distance", + "slab_interval", + "vacuum_gap", + "wrap_positions", +] diff --git a/mliport/mliport/confsearch/graphs.py b/mliport/mliport/confsearch/graphs.py new file mode 100644 index 00000000..265b8eef --- /dev/null +++ b/mliport/mliport/confsearch/graphs.py @@ -0,0 +1,402 @@ +"""Covalent graphs, chemisorption flags and status rules (spec section 8). + +All bond criteria use ``ase.data.covalent_radii`` and minimum-image distances. +Ionic species (``cs_ionic_species``) are excluded from every covalent graph: +their coordination may change freely and a mobile ion hopping between sites is +not a chemical reaction. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import TYPE_CHECKING + +import numpy as np +from ase.data import covalent_radii +from ase.neighborlist import neighbor_list + +from mliport.confsearch import status as cs_status +from mliport.confsearch.errors import ConfsearchInternalError +from mliport.confsearch.geometry import ( + mic_distance_matrix, + mic_displacements, + minimum_distance, + self_image_distance, + vacuum_gap, +) + +if TYPE_CHECKING: + from collections.abc import Iterable + + from ase import Atoms + + from mliport.confsearch.options import ConfsearchOptions + +#: Displacement thresholds for the slab flags (spec section 8.3), in Angstrom. +SLAB_REARRANGED_DISPLACEMENT_A = 1.0 +FAR_FIELD_DISPLACEMENT_A = 0.5 +FAR_FIELD_DISTANCE_A = 6.0 +#: Ionic coordination shell, in units of the covalent-radii sum (informational). +IONIC_COORDINATION_SCALE = 1.2 + + +@dataclass(frozen=True, slots=True) +class GraphDifference: + """Bonds lost and gained relative to a reference graph.""" + + lost: tuple[tuple[int, int], ...] = () + gained: tuple[tuple[int, int], ...] = () + + @property + def changed(self) -> bool: + return bool(self.lost or self.gained) + + def to_dict(self) -> dict[str, list[list[int]]]: + return { + "lost": [list(pair) for pair in self.lost], + "gained": [list(pair) for pair in self.gained], + } + + +@dataclass(frozen=True, slots=True) +class CovalentGraph: + """An undirected bond set over a fixed atom-index subset.""" + + bonds: frozenset[tuple[int, int]] = field(default_factory=frozenset) + + def __len__(self) -> int: + return len(self.bonds) + + def as_sorted_list(self) -> list[list[int]]: + return [list(pair) for pair in sorted(self.bonds)] + + def difference(self, other: CovalentGraph) -> GraphDifference: + """Bonds in ``self`` that ``other`` lacks, and vice versa.""" + lost = tuple(sorted(self.bonds - other.bonds)) + gained = tuple(sorted(other.bonds - self.bonds)) + return GraphDifference(lost=lost, gained=gained) + + +@dataclass(frozen=True, slots=True) +class MinimumClassification: + """Everything spec section 8 records for one converged quench.""" + + status: str + flags: tuple[str, ...] + adsorbate_slab_bonds: tuple[tuple[int, int, str, str, float, float], ...] + reacted_bonds: dict[str, dict[str, list[list[int]]]] + min_adsorbate_slab_distance: float + min_self_image_distance: float + min_vacuum_gap: float + max_slab_displacement_ionic: float + max_slab_displacement_nonionic: float + ionic_coordination: tuple[tuple[int, int], ...] + + @property + def chemisorbed(self) -> bool: + return "chemisorbed" in self.flags + + def to_dict(self) -> dict: + return { + "status": self.status, + "flags": list(self.flags), + "chemisorbed": self.chemisorbed, + "adsorbate_slab_bonds": [ + { + "adsorbate_index": bond[0], + "slab_index": bond[1], + "adsorbate_element": bond[2], + "slab_element": bond[3], + "distance_A": bond[4], + "q": bond[5], + } + for bond in self.adsorbate_slab_bonds + ], + "reacted_bonds": self.reacted_bonds, + "min_adsorbate_slab_distance_A": self.min_adsorbate_slab_distance, + "min_self_image_distance_A": self.min_self_image_distance, + "min_vacuum_gap_A": self.min_vacuum_gap, + "max_slab_displacement_ionic_A": self.max_slab_displacement_ionic, + "max_slab_displacement_nonionic_A": self.max_slab_displacement_nonionic, + "ionic_adsorbate_coordination": [ + {"adsorbate_index": index, "neighbours": count} + for index, count in self.ionic_coordination + ], + } + + +@dataclass(frozen=True, slots=True) +class ClassificationReference: + """The reference state a minimum is classified against.""" + + adsorbate_graph: CovalentGraph + slab_graph: CovalentGraph + #: Positions of the replica's start minimum, used for displacement flags. + start_positions: np.ndarray + + +def ionic_mask(atoms: Atoms, options: ConfsearchOptions) -> np.ndarray: + """Boolean mask of atoms whose element is an ionic species.""" + symbols = set(options.ionic_symbols) + return np.array( + [symbol in symbols for symbol in atoms.get_chemical_symbols()], dtype=bool + ) + + +def covalent_bonds( + atoms: Atoms, + first: np.ndarray, + second: np.ndarray | None = None, + *, + bond_scale: float, + ionic_symbols: Iterable[str], +) -> CovalentGraph: + """Bonds among ``first`` (or between ``first`` and ``second``). + + A bond exists when the MIC distance is ``<= bond_scale * (r_i + r_j)`` and + both atoms are non-ionic. ``second=None`` means bonds within ``first``. + """ + left = np.asarray(first, dtype=int) + right = left if second is None else np.asarray(second, dtype=int) + if left.size == 0 or right.size == 0: + return CovalentGraph() + + ionic = set(ionic_symbols) + symbols = atoms.get_chemical_symbols() + non_ionic = np.array([symbol not in ionic for symbol in symbols], dtype=bool) + radii = covalent_radii[np.asarray(atoms.numbers, dtype=int)] + + candidates = np.union1d(left, right) + candidates = candidates[non_ionic[candidates]] + if candidates.size < 2: + return CovalentGraph() + cutoff = float(bond_scale * 2.0 * np.max(radii[candidates])) + if cutoff <= 0: + return CovalentGraph() + + i, j, distances = neighbor_list("ijd", atoms, cutoff, self_interaction=False) + i = np.asarray(i, dtype=int) + j = np.asarray(j, dtype=int) + distances = np.asarray(distances, dtype=float) + + left_membership = np.zeros(len(atoms), dtype=bool) + left_membership[left] = True + right_membership = np.zeros(len(atoms), dtype=bool) + right_membership[right] = True + + if second is None: + selected = left_membership[i] & right_membership[j] + else: + selected = (left_membership[i] & right_membership[j]) | ( + right_membership[i] & left_membership[j] + ) + selected &= non_ionic[i] & non_ionic[j] + + bonds: set[tuple[int, int]] = set() + for a, b, distance in zip( + i[selected], j[selected], distances[selected], strict=True + ): + if distance <= bond_scale * (radii[a] + radii[b]) + 1e-12: + bonds.add((int(min(a, b)), int(max(a, b)))) + return CovalentGraph(frozenset(bonds)) + + +def broken_reference_bonds( + atoms: Atoms, + reference: CovalentGraph, + *, + break_scale: float, + ionic_symbols: Iterable[str], +) -> tuple[tuple[int, int], ...]: + """Reference bonds stretched beyond ``break_scale`` (MD early check). + + New bonds are deliberately not detected during MD (spec section 8.1). + """ + if not reference.bonds: + return () + ionic = set(ionic_symbols) + symbols = atoms.get_chemical_symbols() + positions = np.asarray(atoms.get_positions(), dtype=float) + cell = np.asarray(atoms.cell, dtype=float) + radii = covalent_radii[np.asarray(atoms.numbers, dtype=int)] + from mliport.confsearch.geometry import mic_vectors # noqa: PLC0415 + + broken: list[tuple[int, int]] = [] + for a, b in sorted(reference.bonds): + if symbols[a] in ionic or symbols[b] in ionic: + continue + delta = positions[b] - positions[a] + distance = float(np.linalg.norm(mic_vectors(cell, delta))) + if distance > break_scale * (radii[a] + radii[b]): + broken.append((a, b)) + return tuple(broken) + + +def classify_minimum( + atoms: Atoms, + *, + regions, + options: ConfsearchOptions, + reference: ClassificationReference, +) -> MinimumClassification: + """Classify one converged quench (spec sections 8.2-8.4).""" + fixed = np.asarray(regions.fixed, dtype=int) + current_positions = np.asarray(atoms.get_positions(), dtype=float) + if fixed.size: + if not np.array_equal( + current_positions[fixed], reference.start_positions[fixed] + ): + raise ConfsearchInternalError( + "A fixed atom moved during the search; this is an internal error, " + "not a scientific outcome (spec section 8.2 rule 1)" + ) + + adsorbate = np.asarray(regions.adsorbate, dtype=int) + slab = np.asarray(regions.slab, dtype=int) + free_slab = np.setdiff1d(slab, fixed, assume_unique=False) + ionic = ionic_mask(atoms, options) + + adsorbate_graph = covalent_bonds( + atoms, + adsorbate, + bond_scale=options.cs_bond_scale, + ionic_symbols=options.ionic_symbols, + ) + slab_graph = covalent_bonds( + atoms, + slab, + bond_scale=options.cs_bond_scale, + ionic_symbols=options.ionic_symbols, + ) + cross = covalent_bonds( + atoms, + adsorbate, + slab, + bond_scale=options.cs_bond_scale, + ionic_symbols=options.ionic_symbols, + ) + + adsorbate_diff = reference.adsorbate_graph.difference(adsorbate_graph) + slab_diff = reference.slab_graph.difference(slab_graph) + + radii = covalent_radii[np.asarray(atoms.numbers, dtype=int)] + symbols = atoms.get_chemical_symbols() + bond_records: list[tuple[int, int, str, str, float, float]] = [] + adsorbate_set = set(int(index) for index in adsorbate) + for first, second in sorted(cross.bonds): + a, b = (first, second) if first in adsorbate_set else (second, first) + delta = (current_positions[b] - current_positions[a])[None, :] + distance = float(mic_displacements(atoms, delta)[0]) + bond_records.append( + ( + int(a), + int(b), + symbols[a], + symbols[b], + distance, + distance / (radii[a] + radii[b]), + ) + ) + adsorbate_slab_bonds = tuple(bond_records) + + min_adsorbate_slab = minimum_distance(atoms, adsorbate, slab) + image_distance = self_image_distance(atoms, adsorbate) + vacuum = vacuum_gap(atoms, adsorbate, slab) + + displacements = mic_displacements( + atoms, current_positions[free_slab] - reference.start_positions[free_slab] + ) + ionic_free = ionic[free_slab] + max_ionic = float(np.max(displacements[ionic_free])) if np.any(ionic_free) else 0.0 + max_nonionic = ( + float(np.max(displacements[~ionic_free])) if np.any(~ionic_free) else 0.0 + ) + + nonionic_free = free_slab[~ionic[free_slab]] + slab_rearranged = bool( + nonionic_free.size + and np.any( + mic_displacements( + atoms, + current_positions[nonionic_free] + - reference.start_positions[nonionic_free], + ) + > SLAB_REARRANGED_DISPLACEMENT_A + ) + ) + far_field_changed = False + if free_slab.size and adsorbate.size: + distances_to_adsorbate = mic_distance_matrix(atoms, free_slab, adsorbate) + nearest = np.min(distances_to_adsorbate, axis=1) + far = nearest > FAR_FIELD_DISTANCE_A + if np.any(far): + far_field_changed = bool( + np.any(displacements[far] > FAR_FIELD_DISPLACEMENT_A) + ) + + ionic_coordination: list[tuple[int, int]] = [] + for index in adsorbate: + if not ionic[index]: + continue + others = np.setdiff1d(np.arange(len(atoms)), np.array([index])) + distances = mic_distance_matrix(atoms, np.array([index]), others)[0] + threshold = IONIC_COORDINATION_SCALE * (radii[index] + radii[others]) + ionic_coordination.append( + (int(index), int(np.count_nonzero(distances <= threshold))) + ) + + flags: list[str] = [] + if cross.bonds: + flags.append("chemisorbed") + else: + flags.append("physisorbed") + if slab_rearranged: + flags.append("slab_rearranged") + if far_field_changed: + flags.append("far_field_slab_changed") + + reacted_bonds = { + "adsorbate": adsorbate_diff.to_dict(), + "slab": slab_diff.to_dict(), + } + + if adsorbate_diff.changed or slab_diff.changed: + status = cs_status.REACTED + elif min_adsorbate_slab > options.cs_desorption_distance: + status = cs_status.DESORBED + elif ( + image_distance < options.cs_min_image_distance + or vacuum < options.cs_min_vacuum_gap + ): + status = cs_status.IMAGE_CONTACT + else: + status = cs_status.VALID + + return MinimumClassification( + status=status, + flags=tuple(flags), + adsorbate_slab_bonds=adsorbate_slab_bonds, + reacted_bonds=reacted_bonds, + min_adsorbate_slab_distance=min_adsorbate_slab, + min_self_image_distance=image_distance, + min_vacuum_gap=vacuum, + max_slab_displacement_ionic=max_ionic, + max_slab_displacement_nonionic=max_nonionic, + ionic_coordination=tuple(ionic_coordination), + ) + + +__all__ = [ + "FAR_FIELD_DISPLACEMENT_A", + "FAR_FIELD_DISTANCE_A", + "IONIC_COORDINATION_SCALE", + "SLAB_REARRANGED_DISPLACEMENT_A", + "ClassificationReference", + "CovalentGraph", + "GraphDifference", + "MinimumClassification", + "broken_reference_bonds", + "classify_minimum", + "covalent_bonds", + "ionic_mask", +] diff --git a/mliport/mliport/confsearch/index_spec.py b/mliport/mliport/confsearch/index_spec.py new file mode 100644 index 00000000..949d74e3 --- /dev/null +++ b/mliport/mliport/confsearch/index_spec.py @@ -0,0 +1,148 @@ +"""Adsorbate index specifications for confsearch. + +``cs_adsorbate_indices`` is a comma-separated list of 0-based indices and +inclusive ranges, for example ``300-341`` or ``0,5,7-9``. It is 0-based like +ASE; CP2K/VMD users count from 1, which is called out in the docs and in the +error messages. +""" + +from __future__ import annotations + +import re +from typing import TYPE_CHECKING + +from mliport.confsearch.errors import ConfsearchError + +if TYPE_CHECKING: + from collections.abc import Iterable + +#: Hard cap on the number of indices one range may expand to before the atom +#: count is known; guards against ``0-999999999`` typo bombs. +MAX_RANGE_SPAN = 1_000_000 + +_SINGLE = re.compile(r"\d+") +_RANGE = re.compile(r"(\d+)\s*-\s*(\d+)") +_NEGATIVE = re.compile(r"-\s*\d+") + + +def parse_index_spec( + spec: str | int | Iterable[int], + *, + n_atoms: int | None = None, + label: str = "cs_adsorbate_indices", +) -> tuple[int, ...]: + """Parse an index specification into a sorted, duplicate-free tuple. + + Args: + spec: ``"0,5,7-9"`` (string), a single index, or an iterable of indices. + n_atoms: When given, every index must be a valid 0-based atom index. + label: Option name used in error messages. + + Raises: + ConfsearchError: on malformed syntax, negative or reversed ranges, + duplicates within one specification, or out-of-range indices. + """ + if isinstance(spec, str): + indices = _parse_string(spec, label=label) + elif isinstance(spec, int) and not isinstance(spec, bool): + indices = (spec,) + else: + try: + raw = list(spec) # type: ignore[arg-type] + except TypeError as exc: + raise ConfsearchError( + f"{label} must be a string like '0,5,7-9', got {spec!r}" + ) from exc + indices = tuple(_require_int(value, label=label) for value in raw) + + if not indices: + raise ConfsearchError(f"{label} selects no atoms") + + if n_atoms is not None: + out_of_range = sorted({index for index in indices if index >= n_atoms}) + if out_of_range: + raise ConfsearchError( + f"{label} contains indices outside the {n_atoms}-atom structure: " + f"{out_of_range} (the specification is 0-based, like ASE; " + "CP2K/VMD indices count from 1)" + ) + negative = sorted({index for index in indices if index < 0}) + if negative: + raise ConfsearchError( + f"{label} contains negative indices {negative}; atom indices are " + "0-based and must be >= 0" + ) + + unique = sorted(set(indices)) + if len(unique) != len(indices): + duplicates = sorted({index for index in indices if indices.count(index) > 1}) + raise ConfsearchError( + f"{label} repeats indices {duplicates}; list each atom once" + ) + return tuple(unique) + + +def _require_int(value: object, *, label: str) -> int: + if isinstance(value, bool) or not isinstance(value, int): + raise ConfsearchError(f"{label} must contain integers, got {value!r}") + return value + + +def _parse_string(spec: str, *, label: str) -> tuple[int, ...]: + text = spec.strip() + if not text: + raise ConfsearchError(f"{label} is empty") + indices: list[int] = [] + for token in text.split(","): + item = token.strip() + if not item: + raise ConfsearchError( + f"{label}={spec!r} has an empty entry (check the commas)" + ) + if _SINGLE.fullmatch(item): + indices.append(int(item)) + continue + if _NEGATIVE.fullmatch(item): + raise ConfsearchError( + f"{label}={spec!r}: negative index {item!r}; atom indices are " + "0-based and must be >= 0 (CP2K/VMD count from 1)" + ) + match = _RANGE.fullmatch(item) + if match is None: + raise ConfsearchError( + f"{label}={spec!r}: cannot parse {item!r}; expected an index or an " + "inclusive range such as '7-9'" + ) + start, end = int(match.group(1)), int(match.group(2)) + if end < start: + raise ConfsearchError( + f"{label}={spec!r}: reversed range {item!r}; write it as " + f"'{end}-{start}'" + ) + if end - start + 1 > MAX_RANGE_SPAN: + raise ConfsearchError( + f"{label}={spec!r}: range {item!r} spans more than " + f"{MAX_RANGE_SPAN} atoms" + ) + indices.extend(range(start, end + 1)) + return tuple(indices) + + +def format_index_spec(indices: Iterable[int]) -> str: + """Render indices as a compressed ``"a,b-c"`` specification.""" + ordered = sorted(set(int(index) for index in indices)) + if not ordered: + return "" + parts: list[str] = [] + start = previous = ordered[0] + for index in ordered[1:]: + if index == previous + 1: + previous = index + continue + parts.append(str(start) if start == previous else f"{start}-{previous}") + start = previous = index + parts.append(str(start) if start == previous else f"{start}-{previous}") + return ",".join(parts) + + +__all__ = ["MAX_RANGE_SPAN", "format_index_spec", "parse_index_spec"] diff --git a/mliport/mliport/confsearch/options.py b/mliport/mliport/confsearch/options.py new file mode 100644 index 00000000..3509635c --- /dev/null +++ b/mliport/mliport/confsearch/options.py @@ -0,0 +1,705 @@ +"""Typed, calculator-independent options for the confsearch workflow. + +The dataclass mirrors :class:`mliport.neb.schema.NEBOptions`: it is frozen, +validates every cross-key rule at construction time and fails closed with a +message that names the nearest valid value. Nothing here touches a calculator, +a file or an ASE ``Atoms`` object, so the whole core library is testable on +synthetic structures. +""" + +from __future__ import annotations + +import math +from collections.abc import Sequence +from dataclasses import dataclass, field, fields +from pathlib import Path +from typing import TYPE_CHECKING + +from ase.data import atomic_numbers + +from mliport.confsearch.errors import ( + ConfsearchError, + reject_non_goal, +) +from mliport.confsearch.index_spec import parse_index_spec +from mliport.runners.safety import finite_float, strict_integer + +if TYPE_CHECKING: + pass + +#: Default ionic species excluded from covalent graphs (spec section 8.1). +DEFAULT_IONIC_SPECIES = "Li,Na,K,Rb,Cs,Mg,Ca" + +#: Mobile-set choices (spec section 7.2). +MD_MOBILE_CHOICES = ("adsorbate", "adsorbate_and_top", "all_free") + +#: Reaction policies (spec section 8.2). +REACTION_POLICIES = ("exclude", "include") + +#: Modes named in the spec as future work; asking for them is a hard error. +_FUTURE_MODES = ("bulk_mobile", "melt_quench", "interface", "multi_adsorbate") + +#: confsearch-scoped defaults (spec section 7.6 / 12.3). +CS_DEFAULTS: dict[str, object] = { + "cs_md_mobile": "adsorbate", + "cs_top_depth": 2.0, + "cs_temperature_high": 500.0, + "cs_temperature_low": 300.0, + "cs_hold_ps": 2.0, + "cs_cool_ps": 2.0, + "cs_snapshot_interval_ps": 0.5, + "cs_ramp_interval": 10, + "cs_cycles": 5, + "cs_save_interval": 100, + "cs_accept_temperature": 500.0, + "timestep": 0.5, + "friction": 0.01, + "cs_quench_fmax": 0.05, + "cs_quench_steps": 2000, + "cs_bond_scale": 1.2, + "cs_bond_break_scale": 1.5, + "cs_ionic_species": DEFAULT_IONIC_SPECIES, + "cs_reaction_policy": "exclude", + "cs_desorption_distance": 5.0, + "cs_min_image_distance": 4.0, + "cs_min_vacuum_gap": 8.0, + "cs_place_contact_scale": 1.5, + "cs_place_anchor_scale": 1.1, + "cs_place_other_min_scale": 1.3, + "cs_place_max_attempts": 1000, + "cs_dedup_energy_tol": 0.010, + # Direct geometric identity (spec 9.3 revision 4): with a fixed slab and a + # fixed atom order, the same minimum re-quenched moves its adsorbate atoms + # by less than this. This is the primary "same basin" test; the fingerprint + # tolerance below is only needed for what G cannot see (symmetry-equivalent + # sites and permutation-equivalent conformers). + "cs_dedup_geom_tol": 0.20, + # P1 calibration (spec 13.2 revision 4), geometry-labelled pairs on the + # repository's LGPS geometry; see + # tests/mliport/mliport/confsearch/test_fingerprint_calibration.py: + # (a) same basin: 25 pairs within cs_dedup_geom_tol (handled by G); + # 11 further pairs (0.20-0.5 A) are documented false splits; + # (b/c) 63 distinct sites/conformers: min D = 8.5e-4 at sigma=0.20; + # (d) 4 equivalent pairs (rigid slab symmetry + CH3 permutation): + # D ~ 0 and all merge. + # Zero false merges with a factor-2 margin: 0.0004 <= 0.5 * 8.5e-4. + # Changing this default later bumps CS_SCIENTIFIC_REVISION. + "cs_dedup_fp_tol": 0.0004, + "cs_fp_rcut": 8.0, + "cs_fp_binwidth": 0.02, + # P1 calibration (spec 13.2 revision 4): the sigma sweep {0.05, 0.10, 0.20} + # merged all equivalent pairs at every sigma, so the tie-break (larger + # sigma) selects 0.20. + "cs_fp_sigma": 0.20, + "cs_top_k": 10, + "cs_export_window": 0.5, + "cs_refine": True, + "cs_refine_fmax": 0.02, + "cs_refine_steps": 3000, + "cs_allow_direct_forces": False, +} + + +def _parse_elements(spec: str, *, label: str) -> tuple[str, ...]: + if not isinstance(spec, str): + raise ConfsearchError(f"{label} must be a string of element symbols") + symbols: list[str] = [] + for token in spec.split(","): + item = token.strip() + if not item: + raise ConfsearchError(f"{label}={spec!r} has an empty element entry") + if item in atomic_numbers: + symbols.append(item) + continue + capitalized = item.capitalize() + if capitalized in atomic_numbers: + symbols.append(capitalized) + continue + raise ConfsearchError( + f"{label}={spec!r}: {item!r} is not an element symbol " + "(use ASE symbols such as Li, C, H)" + ) + unique = tuple(dict.fromkeys(symbols)) + if not unique: + raise ConfsearchError(f"{label} selects no elements") + return unique + + +def _positive(value: object, name: str, *, allow_zero: bool = False) -> float: + number = finite_float(value, name=name) + if number < 0 or (number == 0 and not allow_zero): + comparator = ">= 0" if allow_zero else "> 0" + raise ConfsearchError(f"{name} must be {comparator}, got {number!r}") + return number + + +def _positive_int(value: object, name: str, *, minimum: int = 1) -> int: + number = strict_integer(value, name=name) + if number < minimum: + raise ConfsearchError(f"{name} must be >= {minimum}, got {number}") + return number + + +def steps_from_ps( + value_ps: float, timestep_fs: float, *, name: str, allow_zero: bool = False +) -> int: + """Convert a duration in ps to whole timesteps, or fail closed. + + The specification requires the conversion to be an integer within 1e-9; + otherwise the run is refused with the nearest valid durations. + """ + ps = _positive(value_ps, name, allow_zero=allow_zero) + steps_exact = ps * 1000.0 / timestep_fs + steps = int(round(steps_exact)) + if abs(steps_exact - steps) > 1e-9: + lower = max(0, math.floor(steps_exact)) + upper = math.ceil(steps_exact) + lower_ps = lower * timestep_fs / 1000.0 + upper_ps = upper * timestep_fs / 1000.0 + raise ConfsearchError( + f"{name}={ps} ps is not an integer number of {timestep_fs} fs steps " + f"({steps_exact:.9g}); nearest valid values are {lower_ps:g} ps " + f"({lower} steps) and {upper_ps:g} ps ({upper} steps)" + ) + if not allow_zero and steps < 1: + raise ConfsearchError(f"{name}={ps} ps is shorter than one timestep") + return steps + + +@dataclass(frozen=True, slots=True) +class ConfsearchOptions: + """Validated options for one confsearch run (v1, ``adsorbate`` mode).""" + + cs_mode: str = "adsorbate" + + # --- starts: mode A (user-prepared) --- + cs_starts: tuple[str, ...] | None = None + cs_adsorbate_indices: str | None = None + + # --- starts: mode B (automatic placement) --- + cs_slab: str | None = None + cs_molecule: str | None = None + cs_n_starts: int | None = None + + cs_fix_below: float | None = None + + # --- MD --- + cs_md_mobile: str = str(CS_DEFAULTS["cs_md_mobile"]) + cs_top_depth: float = float(CS_DEFAULTS["cs_top_depth"]) # type: ignore[arg-type] + cs_temperature_high: float = float(CS_DEFAULTS["cs_temperature_high"]) # type: ignore[arg-type] + cs_temperature_low: float = float(CS_DEFAULTS["cs_temperature_low"]) # type: ignore[arg-type] + cs_hold_ps: float = float(CS_DEFAULTS["cs_hold_ps"]) # type: ignore[arg-type] + cs_cool_ps: float = float(CS_DEFAULTS["cs_cool_ps"]) # type: ignore[arg-type] + cs_snapshot_interval_ps: float = float(CS_DEFAULTS["cs_snapshot_interval_ps"]) # type: ignore[arg-type] + cs_ramp_interval: int = int(CS_DEFAULTS["cs_ramp_interval"]) # type: ignore[arg-type] + cs_cycles: int = int(CS_DEFAULTS["cs_cycles"]) # type: ignore[arg-type] + cs_save_interval: int = int(CS_DEFAULTS["cs_save_interval"]) # type: ignore[arg-type] + cs_accept_temperature: float = float(CS_DEFAULTS["cs_accept_temperature"]) # type: ignore[arg-type] + timestep: float = float(CS_DEFAULTS["timestep"]) # type: ignore[arg-type] + friction: float = float(CS_DEFAULTS["friction"]) # type: ignore[arg-type] + seed: int | None = None + fmax_abort: float = 20.0 + + # --- quench --- + cs_quench_fmax: float = float(CS_DEFAULTS["cs_quench_fmax"]) # type: ignore[arg-type] + cs_quench_steps: int = int(CS_DEFAULTS["cs_quench_steps"]) # type: ignore[arg-type] + + # --- chemistry --- + cs_bond_scale: float = float(CS_DEFAULTS["cs_bond_scale"]) # type: ignore[arg-type] + cs_bond_break_scale: float = float(CS_DEFAULTS["cs_bond_break_scale"]) # type: ignore[arg-type] + cs_ionic_species: str = DEFAULT_IONIC_SPECIES + cs_reaction_policy: str = str(CS_DEFAULTS["cs_reaction_policy"]) + cs_desorption_distance: float = float(CS_DEFAULTS["cs_desorption_distance"]) # type: ignore[arg-type] + cs_min_image_distance: float = float(CS_DEFAULTS["cs_min_image_distance"]) # type: ignore[arg-type] + cs_min_vacuum_gap: float = float(CS_DEFAULTS["cs_min_vacuum_gap"]) # type: ignore[arg-type] + + # --- placement --- + cs_place_contact_scale: float = float(CS_DEFAULTS["cs_place_contact_scale"]) # type: ignore[arg-type] + cs_place_anchor: str | None = None + cs_place_anchor_scale: float = float(CS_DEFAULTS["cs_place_anchor_scale"]) # type: ignore[arg-type] + cs_place_other_min_scale: float = float(CS_DEFAULTS["cs_place_other_min_scale"]) # type: ignore[arg-type] + cs_place_anchor_targets: str | None = None + cs_place_max_attempts: int = int(CS_DEFAULTS["cs_place_max_attempts"]) # type: ignore[arg-type] + + # --- dedup / fingerprint --- + cs_dedup_energy_tol: float = float(CS_DEFAULTS["cs_dedup_energy_tol"]) # type: ignore[arg-type] + cs_dedup_geom_tol: float = float(CS_DEFAULTS["cs_dedup_geom_tol"]) # type: ignore[arg-type] + cs_dedup_fp_tol: float = float(CS_DEFAULTS["cs_dedup_fp_tol"]) # type: ignore[arg-type] + cs_fp_rcut: float = float(CS_DEFAULTS["cs_fp_rcut"]) # type: ignore[arg-type] + cs_fp_binwidth: float = float(CS_DEFAULTS["cs_fp_binwidth"]) # type: ignore[arg-type] + cs_fp_sigma: float = float(CS_DEFAULTS["cs_fp_sigma"]) # type: ignore[arg-type] + + # --- refinement / export --- + cs_top_k: int = int(CS_DEFAULTS["cs_top_k"]) # type: ignore[arg-type] + cs_export_window: float = float(CS_DEFAULTS["cs_export_window"]) # type: ignore[arg-type] + cs_refine: bool = bool(CS_DEFAULTS["cs_refine"]) + cs_refine_fmax: float = float(CS_DEFAULTS["cs_refine_fmax"]) # type: ignore[arg-type] + cs_refine_steps: int = int(CS_DEFAULTS["cs_refine_steps"]) # type: ignore[arg-type] + + # --- gates --- + cs_allow_direct_forces: bool = bool(CS_DEFAULTS["cs_allow_direct_forces"]) + + #: Parsed ``cs_place_anchor`` indices (0-based within the molecule file). + _anchor_indices: tuple[int, ...] | None = field( + init=False, default=None, repr=False, compare=False + ) + #: Parsed ``cs_ionic_species`` element symbols. + _ionic_symbols: tuple[str, ...] = field( + init=False, default=(), repr=False, compare=False + ) + #: Parsed ``cs_place_anchor_targets`` element symbols. + _anchor_target_symbols: tuple[str, ...] | None = field( + init=False, default=None, repr=False, compare=False + ) + + def __post_init__(self) -> None: + if not isinstance(self.cs_mode, str): + raise ConfsearchError("cs_mode must be a string") + mode = self.cs_mode.strip().lower() + if mode != "adsorbate": + if mode in _FUTURE_MODES: + raise reject_non_goal(mode) + raise ConfsearchError( + f"cs_mode must be 'adsorbate' in v1, got {self.cs_mode!r}" + ) + object.__setattr__(self, "cs_mode", mode) + + self._validate_regions() + self._validate_md() + self._validate_chemistry() + self._validate_placement() + self._validate_dedup() + self._validate_refinement() + self._validate_gates() + + # -- derived, validated quantities ------------------------------------ + + @property + def ionic_symbols(self) -> tuple[str, ...]: + """Element symbols excluded from covalent graphs.""" + return self._ionic_symbols + + @property + def anchor_indices(self) -> tuple[int, ...] | None: + """Parsed ``cs_place_anchor`` (0-based within the molecule file).""" + return self._anchor_indices + + @property + def anchor_target_symbols(self) -> tuple[str, ...] | None: + """Parsed ``cs_place_anchor_targets`` (element symbols).""" + return self._anchor_target_symbols + + @property + def mode(self) -> str: + """``"A"`` (user-prepared starts) or ``"B"`` (automatic placement).""" + return "B" if self.cs_slab is not None else "A" + + @property + def n_hold(self) -> int: + return steps_from_ps(self.cs_hold_ps, self.timestep, name="cs_hold_ps") + + @property + def n_cool(self) -> int: + return steps_from_ps(self.cs_cool_ps, self.timestep, name="cs_cool_ps") + + @property + def n_snapshot_interval(self) -> int: + return steps_from_ps( + self.cs_snapshot_interval_ps, + self.timestep, + name="cs_snapshot_interval_ps", + allow_zero=True, + ) + + @property + def snapshot_steps(self) -> tuple[int, ...]: + """Hold-phase steps at which frames are quenched (spec 7.3 step 4).""" + interval = self.n_snapshot_interval + if interval <= 0: + return () + hold = self.n_hold + return tuple(range(interval, hold, interval)) + + @property + def total_md_steps_per_cycle(self) -> int: + return self.n_hold + self.n_cool + + @property + def total_quench_upper_bound(self) -> int: + """One quench per snapshot plus one end-of-cycle frame, per cycle.""" + return (len(self.snapshot_steps) + 1) * self.cs_cycles + + # -- validation ------------------------------------------------------- + + def _validate_regions(self) -> None: + starts = self._normalize_paths(self.cs_starts, label="cs_starts") + object.__setattr__(self, "cs_starts", starts) + object.__setattr__( + self, "cs_slab", self._normalize_path(self.cs_slab, label="cs_slab") + ) + object.__setattr__( + self, + "cs_molecule", + self._normalize_path(self.cs_molecule, label="cs_molecule"), + ) + + if self.cs_adsorbate_indices is not None: + # Syntax only; the atom-count bound is checked against the structure. + parse_index_spec(self.cs_adsorbate_indices, label="cs_adsorbate_indices") + + has_starts = bool(starts) + has_indices = self.cs_adsorbate_indices is not None + has_slab = self.cs_slab is not None + has_molecule = self.cs_molecule is not None + has_n_starts = self.cs_n_starts is not None + + if self.cs_n_starts is not None: + object.__setattr__( + self, + "cs_n_starts", + _positive_int(self.cs_n_starts, "cs_n_starts", minimum=1), + ) + + if has_slab or has_molecule or has_n_starts: + # Mode B: placement. Every mode-B key is required, and the + # mode-A keys must be absent (spec 12.3 cross-key validation). + if not (has_slab and has_molecule and has_n_starts): + missing = [ + name + for name, present in ( + ("cs_slab", has_slab), + ("cs_molecule", has_molecule), + ("cs_n_starts", has_n_starts), + ) + if not present + ] + raise ConfsearchError( + "automatic placement (mode B) requires " + f"{', '.join(missing)} as well; alternatively give " + "cs_starts + cs_adsorbate_indices (mode A)" + ) + if has_starts or has_indices: + raise ConfsearchError( + "cs_starts/cs_adsorbate_indices (mode A) cannot be combined " + "with cs_slab/cs_molecule/cs_n_starts (mode B); the two start " + "sources are separate runs in v1" + ) + else: + if not (has_starts and has_indices): + raise ConfsearchError( + "confsearch needs either cs_starts + cs_adsorbate_indices " + "(mode A) or cs_slab + cs_molecule + cs_n_starts (mode B)" + ) + + if self.cs_fix_below is not None: + object.__setattr__( + self, + "cs_fix_below", + _positive(self.cs_fix_below, "cs_fix_below"), + ) + + def _validate_md(self) -> None: + object.__setattr__(self, "timestep", _positive(self.timestep, "timestep")) + object.__setattr__(self, "friction", _positive(self.friction, "friction")) + object.__setattr__( + self, + "fmax_abort", + _positive(self.fmax_abort, "fmax_abort"), + ) + mobile = str(self.cs_md_mobile).strip().lower() + if mobile not in MD_MOBILE_CHOICES: + raise ConfsearchError( + f"cs_md_mobile must be one of {', '.join(MD_MOBILE_CHOICES)}, " + f"got {self.cs_md_mobile!r}" + ) + object.__setattr__(self, "cs_md_mobile", mobile) + object.__setattr__( + self, "cs_top_depth", _positive(self.cs_top_depth, "cs_top_depth") + ) + + high = _positive(self.cs_temperature_high, "cs_temperature_high") + low = _positive(self.cs_temperature_low, "cs_temperature_low") + if low > high: + raise ConfsearchError( + f"cs_temperature_low ({low}) must be <= cs_temperature_high ({high})" + ) + object.__setattr__(self, "cs_temperature_high", high) + object.__setattr__(self, "cs_temperature_low", low) + + hold = _positive(self.cs_hold_ps, "cs_hold_ps") + cool = _positive(self.cs_cool_ps, "cs_cool_ps") + snapshot = _positive( + self.cs_snapshot_interval_ps, "cs_snapshot_interval_ps", allow_zero=True + ) + if snapshot >= hold: + raise ConfsearchError( + f"cs_snapshot_interval_ps ({snapshot}) must be < cs_hold_ps ({hold})" + ) + object.__setattr__(self, "cs_hold_ps", hold) + object.__setattr__(self, "cs_cool_ps", cool) + object.__setattr__(self, "cs_snapshot_interval_ps", snapshot) + + object.__setattr__( + self, + "cs_ramp_interval", + _positive_int(self.cs_ramp_interval, "cs_ramp_interval", minimum=1), + ) + object.__setattr__( + self, + "cs_cycles", + _positive_int(self.cs_cycles, "cs_cycles", minimum=0), + ) + object.__setattr__( + self, + "cs_save_interval", + _positive_int(self.cs_save_interval, "cs_save_interval", minimum=1), + ) + object.__setattr__( + self, + "cs_accept_temperature", + _positive(self.cs_accept_temperature, "cs_accept_temperature"), + ) + if self.seed is not None: + object.__setattr__( + self, "seed", _positive_int(self.seed, "seed", minimum=0) + ) + + # Step conversions must be exact integers (spec 7.3); calling the + # properties here makes a bad combination fail at construction. + if self.n_hold < 1 or self.n_cool < 1: + raise ConfsearchError( + "cs_hold_ps and cs_cool_ps must each cover at least one timestep" + ) + self.n_snapshot_interval + + def _validate_chemistry(self) -> None: + bond = finite_float(self.cs_bond_scale, name="cs_bond_scale") + if bond <= 1.0: + raise ConfsearchError(f"cs_bond_scale must be > 1, got {bond}") + broken = finite_float(self.cs_bond_break_scale, name="cs_bond_break_scale") + if broken <= bond: + raise ConfsearchError( + f"cs_bond_break_scale ({broken}) must be > cs_bond_scale ({bond})" + ) + object.__setattr__(self, "cs_bond_scale", bond) + object.__setattr__(self, "cs_bond_break_scale", broken) + + object.__setattr__( + self, + "_ionic_symbols", + _parse_elements(self.cs_ionic_species, label="cs_ionic_species"), + ) + + policy = str(self.cs_reaction_policy).strip().lower() + if policy not in REACTION_POLICIES: + raise ConfsearchError( + f"cs_reaction_policy must be one of " + f"{', '.join(REACTION_POLICIES)}, got {self.cs_reaction_policy!r}" + ) + object.__setattr__(self, "cs_reaction_policy", policy) + + object.__setattr__( + self, + "cs_desorption_distance", + _positive(self.cs_desorption_distance, "cs_desorption_distance"), + ) + object.__setattr__( + self, + "cs_min_image_distance", + _positive(self.cs_min_image_distance, "cs_min_image_distance"), + ) + object.__setattr__( + self, + "cs_min_vacuum_gap", + _positive(self.cs_min_vacuum_gap, "cs_min_vacuum_gap"), + ) + + def _validate_placement(self) -> None: + contact = finite_float( + self.cs_place_contact_scale, name="cs_place_contact_scale" + ) + if contact <= self.cs_bond_scale: + raise ConfsearchError( + f"cs_place_contact_scale ({contact}) must be > cs_bond_scale " + f"({self.cs_bond_scale})" + ) + anchor = finite_float(self.cs_place_anchor_scale, name="cs_place_anchor_scale") + if anchor <= 0 or anchor > self.cs_bond_scale: + raise ConfsearchError( + f"cs_place_anchor_scale must be > 0 and <= cs_bond_scale " + f"({self.cs_bond_scale}), got {anchor}" + ) + other = finite_float( + self.cs_place_other_min_scale, name="cs_place_other_min_scale" + ) + if other <= self.cs_bond_scale: + raise ConfsearchError( + f"cs_place_other_min_scale ({other}) must be > cs_bond_scale " + f"({self.cs_bond_scale})" + ) + object.__setattr__(self, "cs_place_contact_scale", contact) + object.__setattr__(self, "cs_place_anchor_scale", anchor) + object.__setattr__(self, "cs_place_other_min_scale", other) + object.__setattr__( + self, + "cs_place_max_attempts", + _positive_int( + self.cs_place_max_attempts, "cs_place_max_attempts", minimum=1 + ), + ) + + if self.cs_place_anchor is not None: + if self.mode != "B": + raise ConfsearchError( + "cs_place_anchor is only valid in mode B (automatic placement)" + ) + object.__setattr__( + self, + "_anchor_indices", + parse_index_spec(self.cs_place_anchor, label="cs_place_anchor"), + ) + if self.cs_place_anchor_targets is not None: + if self.cs_place_anchor is None: + raise ConfsearchError( + "cs_place_anchor_targets requires cs_place_anchor (anchored " + "placement); otherwise the closest slab element is not defined" + ) + object.__setattr__( + self, + "_anchor_target_symbols", + _parse_elements( + self.cs_place_anchor_targets, label="cs_place_anchor_targets" + ), + ) + + def _validate_dedup(self) -> None: + object.__setattr__( + self, + "cs_dedup_energy_tol", + _positive(self.cs_dedup_energy_tol, "cs_dedup_energy_tol"), + ) + object.__setattr__( + self, + "cs_dedup_geom_tol", + _positive(self.cs_dedup_geom_tol, "cs_dedup_geom_tol"), + ) + fp_tol = finite_float(self.cs_dedup_fp_tol, name="cs_dedup_fp_tol") + if not 0.0 < fp_tol < 1.0: + raise ConfsearchError(f"cs_dedup_fp_tol must be in (0, 1), got {fp_tol}") + object.__setattr__(self, "cs_dedup_fp_tol", fp_tol) + object.__setattr__(self, "cs_fp_rcut", _positive(self.cs_fp_rcut, "cs_fp_rcut")) + object.__setattr__( + self, "cs_fp_binwidth", _positive(self.cs_fp_binwidth, "cs_fp_binwidth") + ) + object.__setattr__( + self, "cs_fp_sigma", _positive(self.cs_fp_sigma, "cs_fp_sigma") + ) + if self.cs_fp_sigma >= self.cs_fp_rcut: + raise ConfsearchError( + f"cs_fp_sigma ({self.cs_fp_sigma}) must be < cs_fp_rcut " + f"({self.cs_fp_rcut})" + ) + if self.cs_fp_binwidth > self.cs_fp_rcut: + raise ConfsearchError( + f"cs_fp_binwidth ({self.cs_fp_binwidth}) must be <= cs_fp_rcut " + f"({self.cs_fp_rcut})" + ) + if self.cs_fp_binwidth > 0.5 * self.cs_fp_sigma: + raise ConfsearchError( + f"cs_fp_binwidth ({self.cs_fp_binwidth}) must be <= " + f"cs_fp_sigma/2 ({0.5 * self.cs_fp_sigma}); the Gaussian smearing " + "must span at least two bins" + ) + + def _validate_refinement(self) -> None: + object.__setattr__(self, "cs_top_k", _positive_int(self.cs_top_k, "cs_top_k")) + object.__setattr__( + self, + "cs_export_window", + _positive(self.cs_export_window, "cs_export_window"), + ) + if not isinstance(self.cs_refine, bool): + raise ConfsearchError("cs_refine must be a boolean") + fmax = _positive(self.cs_refine_fmax, "cs_refine_fmax") + if fmax > self.cs_quench_fmax: + raise ConfsearchError( + f"cs_refine_fmax ({fmax}) must be <= cs_quench_fmax " + f"({self.cs_quench_fmax})" + ) + object.__setattr__(self, "cs_refine_fmax", fmax) + object.__setattr__( + self, + "cs_refine_steps", + _positive_int(self.cs_refine_steps, "cs_refine_steps", minimum=1), + ) + + def _validate_gates(self) -> None: + object.__setattr__( + self, + "cs_quench_fmax", + _positive(self.cs_quench_fmax, "cs_quench_fmax"), + ) + object.__setattr__( + self, + "cs_quench_steps", + _positive_int(self.cs_quench_steps, "cs_quench_steps", minimum=1), + ) + if not isinstance(self.cs_allow_direct_forces, bool): + raise ConfsearchError("cs_allow_direct_forces must be a boolean") + + @staticmethod + def _normalize_path(value: object, *, label: str) -> str | None: + if value is None: + return None + if not isinstance(value, (str, Path)): + raise ConfsearchError(f"{label} must be a path, got {value!r}") + text = str(value).strip() + if not text: + raise ConfsearchError(f"{label} must not be empty") + return text + + @classmethod + def _normalize_paths(cls, value: object, *, label: str) -> tuple[str, ...] | None: + if value is None: + return None + if isinstance(value, (str, Path)): + return (cls._normalize_path(value, label=label) or "",) + if isinstance(value, Sequence): + normalized = tuple( + item for item in (cls._normalize_path(v, label=label) for v in value) + ) + if not normalized: + raise ConfsearchError(f"{label} must contain at least one path") + return normalized # type: ignore[return-value] + raise ConfsearchError(f"{label} must be a path or a list of paths") + + +def options_from_run_options( + run_options: dict, *, extra: dict | None = None +) -> ConfsearchOptions: + """Build :class:`ConfsearchOptions` from a resolved run-options mapping. + + Unknown keys are rejected so a configuration typo cannot silently change the + scientific defaults; only keys that the dataclass declares are accepted. + """ + known = {item.name for item in fields(ConfsearchOptions)} + values: dict = {} + for key, value in run_options.items(): + if key in known: + values[key] = value + for key, value in (extra or {}).items(): + if key not in known: + raise ConfsearchError(f"Unknown confsearch option {key!r}") + values[key] = value + return ConfsearchOptions(**values) + + +__all__ = [ + "CS_DEFAULTS", + "DEFAULT_IONIC_SPECIES", + "MD_MOBILE_CHOICES", + "REACTION_POLICIES", + "ConfsearchOptions", + "options_from_run_options", + "steps_from_ps", +] diff --git a/mliport/mliport/confsearch/placement.py b/mliport/mliport/confsearch/placement.py new file mode 100644 index 00000000..ca663abf --- /dev/null +++ b/mliport/mliport/confsearch/placement.py @@ -0,0 +1,409 @@ +"""Automatic molecule placement above a slab (spec section 5.2). + +One start is produced by: pick a conformer uniformly at random, centre it at its +(unweighted) centroid, apply a uniform random rotation, draw fractional in-plane +coordinates, and solve the height by bisection so that an element-pair-aware +covalent-radii ratio reaches a target. + +Distances are compared as ``q_ij = d_ij / (r_cov,i + r_cov,j)`` with minimum-image +distances, because a single Angstrom offset does not fit every pair (C-H ~ 1.1 A, +S-S ~ 2.05 A). +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import TYPE_CHECKING + +import numpy as np +from ase import Atoms +from ase.data import covalent_radii + +from mliport.confsearch.errors import ConfsearchPreparationError +from mliport.confsearch.geometry import ( + mic_distance_matrix, + self_image_distance, + vacuum_gap, +) + +if TYPE_CHECKING: + from collections.abc import Callable, Sequence + + from mliport.confsearch.options import ConfsearchOptions + +#: Bisection tolerance on the z offset, in Angstrom (spec section 5.2 step 5). +Z_OFFSET_TOLERANCE_A = 1e-4 +#: Initial bracket step and hard bounds for the height search, in Angstrom. +_BRACKET_STEP_A = 0.25 +_MAX_SEARCH_A = 50.0 +#: Bounded redraws of the rotation in anchored placement. +_MAX_ROTATION_REDRAWS = 10_000 + +#: Rejection reason keys, so the failure report is stable. +REJECTION_REASONS = ( + "contact_scale", + "other_min_scale", + "anchor_targets", + "anchor_never_lowest", + "self_image", + "vacuum", + "surface_geometry", + "height_not_solvable", +) + + +@dataclass(frozen=True, slots=True) +class PlacementResult: + """One placed start, with everything spec section 5.2 step 7 records.""" + + atoms: Atoms + kind: str + conformer_index: int + anchor_index: int | None + quaternion: tuple[float, float, float, float] + u: float + v: float + z_offset: float + attempts: int + rejections: dict[str, int] = field(default_factory=dict) + min_pair_q: float = float("nan") + min_pair_distance_A: float = float("nan") + anchor_q: float | None = None + anchor_slab_index: int | None = None + anchor_symbol: str | None = None + min_self_image_distance_A: float = float("nan") + min_vacuum_gap_A: float = float("nan") + + def to_dict(self) -> dict: + return { + "kind": self.kind, + "conformer_index": int(self.conformer_index), + "anchor_index": ( + None if self.anchor_index is None else int(self.anchor_index) + ), + "quaternion": [float(value) for value in self.quaternion], + "u": float(self.u), + "v": float(self.v), + "z_offset_A": float(self.z_offset), + "attempts": int(self.attempts), + "rejections": dict(self.rejections), + "min_pair_q": float(self.min_pair_q), + "min_pair_distance_A": float(self.min_pair_distance_A), + "anchor_q": None if self.anchor_q is None else float(self.anchor_q), + "anchor_slab_index": ( + None if self.anchor_slab_index is None else int(self.anchor_slab_index) + ), + "anchor_symbol": self.anchor_symbol, + "min_self_image_distance_A": float(self.min_self_image_distance_A), + "min_vacuum_gap_A": float(self.min_vacuum_gap_A), + } + + +def draw_rotation( + rng: np.random.Generator, +) -> tuple[tuple[float, float, float, float], np.ndarray]: + """Uniform random rotation from a normalized Gaussian quaternion (Shoemake).""" + quaternion = rng.standard_normal(4) + norm = float(np.linalg.norm(quaternion)) + if norm == 0.0: + quaternion = np.array([1.0, 0.0, 0.0, 0.0]) + else: + quaternion = quaternion / norm + w, x, y, z = (float(value) for value in quaternion) + rotation = np.array( + [ + [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)], + [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)], + [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)], + ], + dtype=float, + ) + return (w, x, y, z), rotation + + +def random_rotation_matrix(rng: np.random.Generator) -> np.ndarray: + """Uniform random rotation matrix (uniformly distributed orientations).""" + return draw_rotation(rng)[1] + + +def _lateral_vector(cell: np.ndarray, u: float, v: float) -> np.ndarray: + """``u*a + v*b`` using the in-plane cell vectors (z components are zero).""" + lateral = u * np.asarray(cell[0], dtype=float) + v * np.asarray( + cell[1], dtype=float + ) + return np.array([lateral[0], lateral[1], 0.0], dtype=float) + + +def _radii(atoms: Atoms) -> np.ndarray: + return covalent_radii[np.asarray(atoms.numbers, dtype=int)] + + +def _min_q(atoms: Atoms, molecule: np.ndarray, slab: np.ndarray) -> float: + distances = mic_distance_matrix(atoms, molecule, slab) + if distances.size == 0: + return float("inf") + radii = _radii(atoms) + q = distances / (radii[molecule][:, None] + radii[slab][None, :]) + return float(np.min(q)) + + +def _min_distance(atoms: Atoms, molecule: np.ndarray, slab: np.ndarray) -> float: + distances = mic_distance_matrix(atoms, molecule, slab) + return float(np.min(distances)) if distances.size else float("inf") + + +def _anchor_q(atoms: Atoms, anchor: int, slab: np.ndarray) -> tuple[float, int]: + distances = mic_distance_matrix(atoms, np.array([anchor]), slab)[0] + radii = _radii(atoms) + q = distances / (radii[anchor] + radii[slab]) + index = int(np.argmin(q)) + return float(q[index]), int(slab[index]) + + +def place_molecule( + slab: Atoms, + conformers: Sequence[Atoms], + options: ConfsearchOptions, + *, + rng: np.random.Generator, + z_top: float | None = None, + surface_validator: Callable[[Atoms], None] | None = None, +) -> PlacementResult: + """Place one conformer above ``slab`` and return the combined structure. + + ``surface_validator`` is an optional callable ``(Atoms) -> None`` that raises + when the candidate violates the shared section 5.3 surface rules; such a + candidate is counted under the ``surface_geometry`` rejection reason. + """ + if len(conformers) == 0: + raise ConfsearchPreparationError("cs_molecule contains no conformers") + n_molecule = len(conformers[0]) + if n_molecule == 0: + raise ConfsearchPreparationError("cs_molecule frames contain no atoms") + reference_numbers = np.asarray(conformers[0].numbers, dtype=int) + for index, conformer in enumerate(conformers): + if not np.array_equal( + np.asarray(conformer.numbers, dtype=int), reference_numbers + ): + raise ConfsearchPreparationError( + f"cs_molecule frame {index} has a different element order than " + "frame 0; all conformers must share one element order" + ) + + if options.cs_place_anchor is not None: + anchor_indices = options.anchor_indices + assert anchor_indices is not None + out_of_range = [i for i in anchor_indices if i >= n_molecule] + if out_of_range: + raise ConfsearchPreparationError( + f"cs_place_anchor indices {out_of_range} are outside the " + f"{n_molecule}-atom molecule file (0-based, like ASE)" + ) + else: + anchor_indices = None + + if options.anchor_target_symbols is not None: + slab_symbols = set(slab.get_chemical_symbols()) + missing = sorted(set(options.anchor_target_symbols) - slab_symbols) + if missing: + raise ConfsearchPreparationError( + f"cs_place_anchor_targets {missing} are not present in the slab " + f"({sorted(slab_symbols)})" + ) + + cell = np.asarray(slab.cell, dtype=float) + slab_numbers = np.asarray(slab.numbers, dtype=int) + n_slab = len(slab) + if z_top is None: + z_top = float(np.max(np.asarray(slab.get_positions(), dtype=float)[:, 2])) + + rejections = {reason: 0 for reason in REJECTION_REASONS} + slab_indices = np.arange(n_slab) + molecule_indices = np.arange(n_slab, n_slab + n_molecule) + + def make_candidate(molecule_positions: np.ndarray, numbers: np.ndarray) -> Atoms: + return Atoms( + numbers=np.concatenate([slab_numbers, numbers]), + positions=np.concatenate( + [np.asarray(slab.get_positions(), dtype=float), molecule_positions] + ), + cell=cell, + pbc=np.asarray(slab.pbc, dtype=bool), + ) + + for attempt in range(1, int(options.cs_place_max_attempts) + 1): + conformer_index = int(rng.integers(0, len(conformers))) + conformer = conformers[conformer_index] + numbers = np.asarray(conformer.numbers, dtype=int) + positions = np.asarray(conformer.get_positions(), dtype=float) + centred = positions - positions.mean(axis=0) + + quaternion = (1.0, 0.0, 0.0, 0.0) + if anchor_indices is not None: + accepted = False + for _ in range(_MAX_ROTATION_REDRAWS): + quaternion, rotation = draw_rotation(rng) + rotated = centred @ rotation.T + if int(np.argmin(rotated[:, 2])) in anchor_indices: + accepted = True + break + if not accepted: + rejections["anchor_never_lowest"] += 1 + continue + else: + quaternion, rotation = draw_rotation(rng) + rotated = centred @ rotation.T + + anchor_local = ( + int(np.argmin(rotated[:, 2])) if anchor_indices is not None else None + ) + anchor_global = None if anchor_local is None else n_slab + anchor_local + anchor_symbol = ( + None + if anchor_local is None + else conformer.get_chemical_symbols()[anchor_local] + ) + + u = float(rng.random()) + v = float(rng.random()) + lateral = _lateral_vector(cell, u, v) + + def positions_at(z_offset: float) -> np.ndarray: + placed = rotated.copy() + placed[:, 0] += lateral[0] + placed[:, 1] += lateral[1] + placed[:, 2] += (z_top + z_offset) - float(placed[:, 2].min()) + return placed + + def objective(z_offset: float) -> float: + candidate = make_candidate(positions_at(z_offset), numbers) + if anchor_global is not None: + value, _ = _anchor_q(candidate, anchor_global, slab_indices) + return value + return _min_q(candidate, molecule_indices, slab_indices) + + z_offset = _solve_height( + objective, + target=( + options.cs_place_anchor_scale + if anchor_global is not None + else options.cs_place_contact_scale + ), + ) + if z_offset is None: + rejections["height_not_solvable"] += 1 + continue + + candidate = make_candidate(positions_at(z_offset), numbers) + + if anchor_global is not None: + anchor_value, slab_index = _anchor_q(candidate, anchor_global, slab_indices) + others = np.setdiff1d(np.arange(n_molecule), np.array([anchor_local])) + if others.size: + other_min = _min_q(candidate, n_slab + others, slab_indices) + if other_min < options.cs_place_other_min_scale: + rejections["other_min_scale"] += 1 + continue + target_symbols = options.anchor_target_symbols + if target_symbols is not None: + closest_symbol = candidate.get_chemical_symbols()[slab_index] + if closest_symbol not in target_symbols: + rejections["anchor_targets"] += 1 + continue + else: + anchor_value = None + slab_index = None + if ( + _min_q(candidate, molecule_indices, slab_indices) + < options.cs_place_contact_scale - 1e-3 + ): + rejections["contact_scale"] += 1 + continue + + image_distance = self_image_distance(candidate, molecule_indices) + if image_distance < options.cs_min_image_distance: + rejections["self_image"] += 1 + continue + vacuum = vacuum_gap(candidate, molecule_indices, slab_indices) + if vacuum < options.cs_min_vacuum_gap: + rejections["vacuum"] += 1 + continue + if surface_validator is not None: + try: + surface_validator(candidate) + except ConfsearchPreparationError: + rejections["surface_geometry"] += 1 + continue + + return PlacementResult( + atoms=candidate, + kind="anchored" if anchor_global is not None else "contact", + conformer_index=conformer_index, + anchor_index=anchor_local, + quaternion=tuple(float(value) for value in quaternion), + u=u, + v=v, + z_offset=float(z_offset), + attempts=attempt, + rejections={key: value for key, value in rejections.items() if value}, + min_pair_q=_min_q(candidate, molecule_indices, slab_indices), + min_pair_distance_A=_min_distance( + candidate, molecule_indices, slab_indices + ), + anchor_q=anchor_value, + anchor_slab_index=slab_index, + min_self_image_distance_A=image_distance, + min_vacuum_gap_A=vacuum, + anchor_symbol=anchor_symbol, + ) + + raise ConfsearchPreparationError( + "Automatic placement failed after " + f"{options.cs_place_max_attempts} attempts; rejections per reason: " + f"{ {key: value for key, value in rejections.items() if value} }. Adjust " + "the placement scales, the cell vacuum or cs_place_anchor_targets." + ) + + +def _solve_height(objective, *, target: float) -> float | None: + """Bisect the z offset until the target ``q`` is reached (spec 5.2 step 5).""" + low = 0.0 + f_low = objective(low) + if f_low >= target: + # The molecule already reaches the target at the slab top: descend. + low = -_BRACKET_STEP_A + f_low = objective(low) + while f_low > target: + low -= _BRACKET_STEP_A + if abs(low) > _MAX_SEARCH_A: + return None + f_low = objective(low) + high = low + _BRACKET_STEP_A + else: + high = _BRACKET_STEP_A + f_high = objective(high) + while f_high < target: + high += _BRACKET_STEP_A + if high > _MAX_SEARCH_A: + return None + f_high = objective(high) + low = high - _BRACKET_STEP_A + for _ in range(200): + if high - low <= Z_OFFSET_TOLERANCE_A: + break + middle = 0.5 * (low + high) + if objective(middle) < target: + low = middle + else: + high = middle + return 0.5 * (low + high) + + +__all__ = [ + "REJECTION_REASONS", + "Z_OFFSET_TOLERANCE_A", + "PlacementResult", + "draw_rotation", + "place_molecule", + "random_rotation_matrix", +] diff --git a/mliport/mliport/confsearch/regions.py b/mliport/mliport/confsearch/regions.py new file mode 100644 index 00000000..2cf75ffb --- /dev/null +++ b/mliport/mliport/confsearch/regions.py @@ -0,0 +1,321 @@ +"""Region resolution and the shared fail-closed input validation. + +Regions (spec section 4): + +* ``A`` adsorbate atom indices +* ``S`` slab atom indices (everything not in ``A``) +* ``F`` fixed atoms (``FixAtoms`` from the input, optionally extended by + ``cs_fix_below``) +* ``R`` relax set = everything not in ``F`` +* ``M`` MD-mobile set (section 7.2); atoms outside ``M`` are held fixed during + MD only, while every quench relaxes ``R`` +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING + +import numpy as np +from ase.constraints import FixAtoms + +from mliport.confsearch.errors import ( + ConfsearchError, + ConfsearchInternalError, + ConfsearchPreparationError, +) +from mliport.confsearch.geometry import ( + periodic_gap_and_contiguity, + slab_interval, + wrap_positions, +) + +if TYPE_CHECKING: + from ase import Atoms + + from mliport.confsearch.options import ConfsearchOptions + +#: Surface-normal tolerance for the in-plane cell vectors (spec section 5.3). +SURFACE_NORMAL_TOLERANCE_A = 1e-8 +#: Timestep limit when hydrogen is MD-mobile (spec section 5.3). +MAX_H_TIMESTEP_FS = 1.0 + + +@dataclass(frozen=True, slots=True) +class Regions: + """Resolved atom-index regions plus the warnings they produced.""" + + adsorbate: np.ndarray + slab: np.ndarray + fixed: np.ndarray + relax: np.ndarray + warnings: tuple[str, ...] + fix_below_added: tuple[int, ...] = () + + @property + def n_atoms(self) -> int: + return int(self.adsorbate.size + self.slab.size) + + +@dataclass(frozen=True, slots=True) +class SurfaceGeometry: + """Validated surface facts shared by placement and classification.""" + + z_top: float + z_min: float + vacuum_gap: float + adsorbate_centroid_z: float + + +def _fixed_indices(atoms: Atoms) -> np.ndarray: + """Union of ``FixAtoms`` indices; any other constraint fails closed.""" + indices: set[int] = set() + for constraint in atoms.constraints: + if type(constraint) is not FixAtoms: # noqa: E721 - FixScaled subclasses it + raise ConfsearchPreparationError( + "confsearch accepts only FixAtoms constraints; " + f"{type(constraint).__name__} (partial selective dynamics, FixCom, " + "FixSymmetry or any other constraint) is not supported because it " + "would change the mobile set or the potential energy surface" + ) + indices.update(int(index) for index in constraint.get_indices()) + return np.array(sorted(indices), dtype=int) + + +def resolve_regions( + atoms: Atoms, + options: ConfsearchOptions, + *, + adsorbate_indices: np.ndarray | None = None, +) -> Regions: + """Resolve ``A/S/F/R`` for one structure and validate the constraints.""" + n_atoms = len(atoms) + if n_atoms == 0: + raise ConfsearchPreparationError("The structure contains no atoms") + + if adsorbate_indices is None: + raise ConfsearchPreparationError( + "confsearch needs the adsorbate atom indices (A); mode A takes them " + "from cs_adsorbate_indices and mode B from the trailing molecule block" + ) + adsorbate = np.asarray(adsorbate_indices, dtype=int) + if adsorbate.size == 0: + raise ConfsearchPreparationError("The adsorbate selection A is empty") + if np.any(adsorbate < 0) or np.any(adsorbate >= n_atoms): + raise ConfsearchPreparationError( + f"The adsorbate selection A contains indices outside the {n_atoms}-atom " + f"structure: {sorted(int(i) for i in adsorbate if i < 0 or i >= n_atoms)}" + ) + if np.unique(adsorbate).size != adsorbate.size: + raise ConfsearchPreparationError("The adsorbate selection A repeats indices") + if adsorbate.size == n_atoms: + raise ConfsearchPreparationError( + "The adsorbate selection A is the whole structure; confsearch needs a " + "slab plus one adsorbate" + ) + + fixed = _fixed_indices(atoms) + fix_below_added: tuple[int, ...] = () + warnings: list[str] = [] + if options.cs_fix_below is not None: + slab_candidates = np.setdiff1d(np.arange(n_atoms), adsorbate) + wrapped = wrap_positions(atoms) + z_min = float(np.min(wrapped[slab_candidates, 2])) + below = slab_candidates[ + wrapped[slab_candidates, 2] < z_min + float(options.cs_fix_below) + ] + added = np.setdiff1d(below, fixed) + if added.size: + fixed = np.union1d(fixed, added).astype(int) + fix_below_added = tuple(int(index) for index in added) + + if fixed.size and np.intersect1d(fixed, adsorbate).size: + raise ConfsearchPreparationError( + "Fixed atoms F must not intersect the adsorbate A (spec section 5.3); " + f"the overlap is {sorted(int(i) for i in np.intersect1d(fixed, adsorbate))}" + ) + if fixed.size == 0: + warnings.append( + "F is empty: a fully free slab can drift or bend during the search, so " + "energy differences may reflect slab changes rather than adsorption" + ) + + slab = np.setdiff1d(np.arange(n_atoms), adsorbate) + relax = np.setdiff1d(np.arange(n_atoms), fixed) + return Regions( + adsorbate=np.sort(adsorbate), + slab=slab, + fixed=np.sort(fixed), + relax=relax, + warnings=tuple(warnings), + fix_below_added=fix_below_added, + ) + + +def validate_surface( + atoms: Atoms, regions: Regions, options: ConfsearchOptions +) -> SurfaceGeometry: + """Validate the surface convention and return the validated geometry. + + Fail-closed rules (spec section 5.3): 3D PBC, surface normal along +z, a + contiguous slab whose vacuum is the periodic gap, and an adsorbate above the + slab top. + """ + pbc = np.asarray(atoms.pbc, dtype=bool) + if not bool(pbc.all()): + raise ConfsearchPreparationError( + f"confsearch requires pbc == (True, True, True), got {pbc.tolist()}; " + "molecular (non-periodic) tasks are a v1 non-goal" + ) + + cell = np.asarray(atoms.cell, dtype=float) + if ( + abs(float(cell[0, 2])) > SURFACE_NORMAL_TOLERANCE_A + or abs(float(cell[1, 2])) > SURFACE_NORMAL_TOLERANCE_A + ): + raise ConfsearchPreparationError( + "The surface normal must be +z: a_z and b_z must be 0 within " + f"{SURFACE_NORMAL_TOLERANCE_A:g} Angstrom, got a_z={cell[0, 2]!r}, " + f"b_z={cell[1, 2]!r}. confsearch does not rotate the cell for you." + ) + cell_height = float(cell[2, 2]) + if cell_height <= 0: + raise ConfsearchPreparationError( + f"The cell height c_z must be > 0, got {cell_height!r}" + ) + + wrapped = wrap_positions(atoms) + slab_z = wrapped[regions.slab, 2] + periodic, internal = periodic_gap_and_contiguity(slab_z, cell_height) + if periodic <= internal: + raise ConfsearchPreparationError( + "The slab must be contiguous in z with its vacuum across the c " + "boundary (place the slab at the bottom of the cell, vacuum on +z). " + f"Got periodic gap {periodic:.3f} A <= largest internal gap " + f"{internal:.3f} A; some slab atoms look wrapped across the boundary." + ) + z_min, z_max = slab_interval(slab_z, cell_height) + centroid_z = float(np.mean(wrapped[regions.adsorbate, 2])) + if centroid_z <= z_max: + raise ConfsearchPreparationError( + "One-sided adsorption requires the adsorbate centroid above the slab " + f"top: centroid z={centroid_z:.3f} A, slab z_top={z_max:.3f} A. " + "Put the molecule above the +z surface." + ) + return SurfaceGeometry( + z_top=z_max, + z_min=z_min, + vacuum_gap=periodic, + adsorbate_centroid_z=centroid_z, + ) + + +def validate_adsorbate_connectivity( + atoms: Atoms, regions: Regions, options: ConfsearchOptions +) -> None: + """The non-ionic part of A must form one connected covalent graph.""" + from mliport.confsearch.graphs import ( # noqa: PLC0415 + covalent_bonds, + ionic_mask, + ) + + adsorbate = regions.adsorbate + ionic = ionic_mask(atoms, options) + non_ionic = adsorbate[~ionic[adsorbate]] + if non_ionic.size <= 1: + return + graph = covalent_bonds( + atoms, + non_ionic, + bond_scale=options.cs_bond_scale, + ionic_symbols=options.ionic_symbols, + ) + adjacency: dict[int, set[int]] = {int(index): set() for index in non_ionic} + for a, b in graph.bonds: + adjacency[int(a)].add(int(b)) + adjacency[int(b)].add(int(a)) + start = int(non_ionic[0]) + seen = {start} + stack = [start] + while stack: + node = stack.pop() + for neighbour in adjacency[node]: + if neighbour not in seen: + seen.add(neighbour) + stack.append(neighbour) + if len(seen) != non_ionic.size: + missing = sorted(int(index) for index in non_ionic if int(index) not in seen) + raise ConfsearchPreparationError( + "The non-ionic part of the adsorbate selection A is not one connected " + f"covalent graph; atoms {missing} are disconnected from " + f"atom {start} at cs_bond_scale={options.cs_bond_scale}. This is the " + "most likely user error: check cs_adsorbate_indices (0-based, like ASE; " + "CP2K/VMD count from 1)." + ) + + +def mobile_indices( + atoms: Atoms, + regions: Regions, + options: ConfsearchOptions, + *, + z_top: float | None = None, +) -> np.ndarray: + """MD-mobile set M for the current minimum (spec section 7.2).""" + mode = options.cs_md_mobile + if mode == "adsorbate": + return np.sort(regions.adsorbate) + if mode == "all_free": + return np.sort(regions.relax) + if mode == "adsorbate_and_top": + if z_top is None: + raise ConfsearchInternalError( + "cs_md_mobile='adsorbate_and_top' needs z_top of the current minimum" + ) + free_slab = np.setdiff1d(regions.slab, regions.fixed, assume_unique=False) + wrapped = wrap_positions(atoms) + top = free_slab[wrapped[free_slab, 2] >= z_top - float(options.cs_top_depth)] + return np.sort(np.union1d(regions.adsorbate, top)) + raise ConfsearchError(f"Unknown cs_md_mobile {mode!r}") + + +def validate_h_timestep( + atoms: Atoms, mobile: np.ndarray, options: ConfsearchOptions +) -> None: + """Refuse a large timestep when hydrogen is MD-mobile (spec section 5.3).""" + symbols = atoms.get_chemical_symbols() + has_hydrogen = any(symbols[int(index)] == "H" for index in mobile) + if has_hydrogen and options.timestep > MAX_H_TIMESTEP_FS: + raise ConfsearchPreparationError( + "timestep must be <= " + f"{MAX_H_TIMESTEP_FS} fs when H is in the MD-mobile set M " + f"(timestep={options.timestep} fs); hydrogen vibrations are not " + "resolved by a larger step" + ) + + +def validate_all( + atoms: Atoms, + regions: Regions, + options: ConfsearchOptions, +) -> SurfaceGeometry: + """Run every structure-level fail-closed check and return the geometry.""" + geometry = validate_surface(atoms, regions, options) + validate_adsorbate_connectivity(atoms, regions, options) + mobile = mobile_indices(atoms, regions, options, z_top=geometry.z_top) + validate_h_timestep(atoms, mobile, options) + return geometry + + +__all__ = [ + "MAX_H_TIMESTEP_FS", + "SURFACE_NORMAL_TOLERANCE_A", + "Regions", + "SurfaceGeometry", + "mobile_indices", + "resolve_regions", + "validate_adsorbate_connectivity", + "validate_all", + "validate_h_timestep", + "validate_surface", +] diff --git a/mliport/mliport/confsearch/registry.py b/mliport/mliport/confsearch/registry.py new file mode 100644 index 00000000..a00cd06a --- /dev/null +++ b/mliport/mliport/confsearch/registry.py @@ -0,0 +1,386 @@ +"""Unique-minimum registry, deduplication and consolidation (spec section 9). + +Matching rule (section 9.3 revision 4): a new minimum ``m`` joins unique minimum +``u`` iff + + |E_m - E_u| <= cs_dedup_energy_tol AND ( G(m, u) OR D(m, u) <= cs_dedup_fp_tol ) + +where ``G`` is the *direct geometric identity*: with a non-empty fixed set F and +a fixed atom order, the largest minimum-image displacement over the adsorbate +atoms is at most ``cs_dedup_geom_tol``. ``G`` absorbs quench noise in flat +basins; ``D`` is only needed for what ``G`` cannot see (symmetry-equivalent +sites and permutation-equivalent conformers). If F is empty, ``G`` is disabled +for the whole search and recorded in the run warnings. + +Only representatives are compared; when several match, the smallest +``(not G, D)`` wins (G first, then smallest D; ties: lowest id). ``|dE| > 0.2 +eV`` skips G and D entirely. + +Every status class has its own registry and classes never merge. Registration +order is execution order, so the ids are reproducible. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import TYPE_CHECKING + +import numpy as np + +from mliport.confsearch.fingerprint import ( + DEDUP_ENERGY_SHORTCUT_EV, + FingerprintGrid, + FocusedFingerprint, + build_fingerprint, +) +from mliport.confsearch.geometry import mic_vectors + +if TYPE_CHECKING: + from ase import Atoms + + from mliport.confsearch.graphs import MinimumClassification + from mliport.confsearch.options import ConfsearchOptions + + +@dataclass(frozen=True, slots=True) +class MinimumOrigin: + """Where a quench came from: ``(replica, cycle, source)``.""" + + replica: int + cycle: int + source: str + snapshot_index: int | None = None + + def to_dict(self) -> dict: + record = { + "replica": self.replica, + "cycle": self.cycle, + "source": self.source, + } + if self.snapshot_index is not None: + record["snapshot_index"] = self.snapshot_index + return record + + def label(self) -> str: + if self.source == "start": + return f"replica {self.replica} start quench" + if self.source == "snapshot": + return ( + f"replica {self.replica} cycle {self.cycle} " + f"snapshot {self.snapshot_index}" + ) + return f"replica {self.replica} cycle {self.cycle} end" + + +@dataclass(slots=True) +class MinimumRecord: + """One converged quench (a candidate minimum).""" + + record_id: int + energy_eV: float + atoms: Atoms + classification: MinimumClassification + origin: MinimumOrigin + quench_index: int + cumulative_md_ps: float + fmax_eV_A: float + steps: int + fingerprint: FocusedFingerprint | None = None + + @property + def status(self) -> str: + return self.classification.status + + @property + def flags(self) -> tuple[str, ...]: + return self.classification.flags + + +@dataclass(slots=True) +class UniqueMinimum: + """A cluster of minima judged identical by section 9.3.""" + + unique_id: int + status: str + members: list[MinimumRecord] = field(default_factory=list) + replicas: set[int] = field(default_factory=set) + first_found_md_ps: float = 0.0 + first_found_quench_index: int = 0 + + @property + def representative(self) -> MinimumRecord: + """Lowest-energy member (spec section 9.4).""" + return min( + self.members, key=lambda member: (member.energy_eV, member.record_id) + ) + + @property + def hit_count(self) -> int: + return len(self.members) + + @property + def energy_eV(self) -> float: + return self.representative.energy_eV + + @property + def flags(self) -> tuple[str, ...]: + return self.representative.flags + + def add(self, member: MinimumRecord) -> None: + self.members.append(member) + self.replicas.add(member.origin.replica) + + def merge(self, other: UniqueMinimum) -> None: + """Absorb ``other`` (same status class) into this unique minimum.""" + for member in other.members: + self.add(member) + self.first_found_md_ps = min(self.first_found_md_ps, other.first_found_md_ps) + self.first_found_quench_index = min( + self.first_found_quench_index, other.first_found_quench_index + ) + + def to_dict(self) -> dict: + representative = self.representative + positions = np.asarray(representative.atoms.get_positions(), dtype=float) + return { + "id": self.unique_id, + "status": self.status, + "energy_eV": float(representative.energy_eV), + "flags": list(self.flags), + "hit_count": self.hit_count, + "replicas": sorted(self.replicas), + "first_found_md_ps": float(self.first_found_md_ps), + "first_found_quench_index": int(self.first_found_quench_index), + "representative": { + "record_id": representative.record_id, + "energy_eV": float(representative.energy_eV), + "fmax_eV_A": float(representative.fmax_eV_A), + "steps": int(representative.steps), + "origin": representative.origin.to_dict(), + "numbers": [int(z) for z in representative.atoms.numbers], + "symbols": representative.atoms.get_chemical_symbols(), + "cell_A": np.asarray(representative.atoms.cell, dtype=float).tolist(), + "pbc": [bool(x) for x in representative.atoms.pbc], + "positions_A": positions.tolist(), + "classification": representative.classification.to_dict(), + }, + "members": [ + { + "record_id": member.record_id, + "energy_eV": float(member.energy_eV), + "fmax_eV_A": float(member.fmax_eV_A), + "steps": int(member.steps), + "status": member.status, + "flags": list(member.flags), + "origin": member.origin.to_dict(), + "cumulative_md_ps": float(member.cumulative_md_ps), + } + for member in self.members + ], + } + + +class MinimumRegistry: + """Deduplicating registry of quench results, per status class.""" + + def __init__( + self, + *, + options: ConfsearchOptions, + grid: FingerprintGrid | None = None, + adsorbate: np.ndarray | None = None, + fixed: np.ndarray | None = None, + ) -> None: + if adsorbate is None: + raise ValueError("MinimumRegistry needs the adsorbate indices A") + self.options = options + self.adsorbate = np.asarray(adsorbate, dtype=int) + #: G is only meaningful when fixed atoms anchor the slab (spec 9.3). + self.geometric_identity_enabled = fixed is not None and len(fixed) > 0 + self.grid = grid or FingerprintGrid.build( + rcut=options.cs_fp_rcut, + binwidth=options.cs_fp_binwidth, + sigma=options.cs_fp_sigma, + ) + self._classes: dict[str, list[UniqueMinimum]] = {} + self._unique_by_id: dict[int, UniqueMinimum] = {} + self._next_unique_id = 1 + self._next_record_id = 1 + self.merges: list[dict] = [] + + # -- registration ------------------------------------------------------ + + def new_record_id(self) -> int: + record_id = self._next_record_id + self._next_record_id += 1 + return record_id + + def fingerprint(self, atoms: Atoms) -> FocusedFingerprint: + return build_fingerprint( + atoms, self.adsorbate, options=self.options, grid=self.grid + ) + + def register(self, record: MinimumRecord) -> UniqueMinimum: + """Register one quench result and return its unique minimum.""" + if record.fingerprint is None: + record.fingerprint = self.fingerprint(record.atoms) + candidates = self._classes.setdefault(record.status, []) + best: UniqueMinimum | None = None + best_key: tuple[bool, float] | None = None + for unique in candidates: + energy_gap = abs(record.energy_eV - unique.energy_eV) + if energy_gap > DEDUP_ENERGY_SHORTCUT_EV: + continue + if energy_gap > self.options.cs_dedup_energy_tol: + continue + representative = unique.representative + geometric = self.geometric_match(record, representative) + distance = float("inf") + if not geometric: + assert record.fingerprint is not None + assert representative.fingerprint is not None + distance = record.fingerprint.distance(representative.fingerprint) + if distance > self.options.cs_dedup_fp_tol: + continue + key = (not geometric, distance) + if ( + best_key is None + or key < best_key + or (key == best_key and unique.unique_id < best.unique_id) + ): + best = unique + best_key = key + if best is None: + unique = UniqueMinimum( + unique_id=self._next_unique_id, + status=record.status, + first_found_md_ps=record.cumulative_md_ps, + first_found_quench_index=record.quench_index, + ) + self._next_unique_id += 1 + unique.add(record) + candidates.append(unique) + self._unique_by_id[unique.unique_id] = unique + return unique + best.add(record) + return best + + # -- queries ----------------------------------------------------------- + + def status_classes(self) -> dict[str, list[UniqueMinimum]]: + return {status: list(values) for status, values in self._classes.items()} + + def uniques(self, status: str | None = None) -> list[UniqueMinimum]: + if status is None: + result: list[UniqueMinimum] = [] + for values in self._classes.values(): + result.extend(values) + return result + return list(self._classes.get(status, [])) + + def total_records(self) -> int: + return self._next_record_id - 1 + + # -- consolidation ----------------------------------------------------- + + def consolidate(self) -> list[dict]: + """Merge representatives that match (spec section 9.5). + + Repeats until stable; every merge is recorded. + """ + merges: list[dict] = [] + for status, uniques in self._classes.items(): + changed = True + while changed: + changed = False + ordered = sorted( + uniques, key=lambda item: (item.energy_eV, item.unique_id) + ) + for position, first in enumerate(ordered): + for second in ordered[position + 1 :]: + if not self._matches(first, second): + continue + first.merge(second) + uniques.remove(second) + del self._unique_by_id[second.unique_id] + merges.append( + { + "status": status, + "kept": first.unique_id, + "merged": second.unique_id, + "merged_members": second.hit_count, + } + ) + changed = True + break + if changed: + break + self.merges.extend(merges) + return merges + + def geometric_match(self, first: MinimumRecord, second: MinimumRecord) -> bool: + """``G``: direct geometric identity under a fixed slab and atom order. + + Disabled (always False) when the fixed set F is empty: without anchors a + whole-minimum rigid translation would look like the same structure. + """ + if not self.geometric_identity_enabled: + return False + left = np.asarray(first.atoms.get_positions(), dtype=float)[self.adsorbate] + right = np.asarray(second.atoms.get_positions(), dtype=float)[self.adsorbate] + deltas = left - right + folded = mic_vectors(np.asarray(first.atoms.cell, dtype=float), deltas) + maximum = float(np.max(np.linalg.norm(folded, axis=1))) if deltas.size else 0.0 + return maximum <= self.options.cs_dedup_geom_tol + + def _matches(self, first: UniqueMinimum, second: UniqueMinimum) -> bool: + energy_gap = abs(first.energy_eV - second.energy_eV) + if energy_gap > DEDUP_ENERGY_SHORTCUT_EV: + return False + if energy_gap > self.options.cs_dedup_energy_tol: + return False + left_rep = first.representative + right_rep = second.representative + if self.geometric_match(left_rep, right_rep): + return True + left = left_rep.fingerprint + right = right_rep.fingerprint + if left is None or right is None: + return False + return left.distance(right) <= self.options.cs_dedup_fp_tol + + # -- serialization ----------------------------------------------------- + + def to_dict(self) -> dict: + return { + "schema": "mliport.confsearch-registry/1", + "n_records": self.total_records(), + "classes": { + status: [ + unique.to_dict() + for unique in sorted( + values, key=lambda item: (item.energy_eV, item.unique_id) + ) + ] + for status, values in sorted(self._classes.items()) + }, + "merges": list(self.merges), + } + + def displacement_between( + self, first: MinimumRecord, second: MinimumRecord + ) -> float: + """MIC RMS displacement between two records (diagnostic helper).""" + deltas = np.asarray(first.atoms.get_positions()) - np.asarray( + second.atoms.get_positions() + ) + folded = mic_vectors(first.atoms.cell, deltas) + return float(np.sqrt(np.mean(np.sum(folded**2, axis=1)))) + + +__all__ = [ + "MinimumOrigin", + "MinimumRecord", + "MinimumRegistry", + "UniqueMinimum", +] diff --git a/mliport/mliport/confsearch/revisions.py b/mliport/mliport/confsearch/revisions.py new file mode 100644 index 00000000..c51c3701 --- /dev/null +++ b/mliport/mliport/confsearch/revisions.py @@ -0,0 +1,25 @@ +"""Scientific and checkpoint revisions for the confsearch workflow. + +Any change to a scientific default, classification rule, fingerprint definition +or ranking rule must bump :data:`CS_SCIENTIFIC_REVISION`; a checkpoint written +by an older revision is then refused on resume instead of silently mixing two +definitions. A change to the checkpoint file layout bumps +:data:`CS_CHECKPOINT_SCHEMA_REVISION`. +""" + +from __future__ import annotations + +#: confsearch spec revision 2 (PR #61) is the specification implemented here. +CS_SPEC_REVISION = 2 + +#: Bumped whenever a scientific rule or default changes. +CS_SCIENTIFIC_REVISION = 1 + +#: Bumped whenever the checkpoint JSON layout changes. +CS_CHECKPOINT_SCHEMA_REVISION = 1 + +__all__ = [ + "CS_CHECKPOINT_SCHEMA_REVISION", + "CS_SCIENTIFIC_REVISION", + "CS_SPEC_REVISION", +] diff --git a/mliport/mliport/confsearch/status.py b/mliport/mliport/confsearch/status.py new file mode 100644 index 00000000..2dbb5fb2 --- /dev/null +++ b/mliport/mliport/confsearch/status.py @@ -0,0 +1,77 @@ +"""Minimum/cycle status vocabulary shared by the confsearch core and engine. + +The values are stable strings: they appear in ``search_results.json``, +``registry.json`` and ``minima/all_minima.extxyz``, so they are part of the +output contract (schema ``mliport.confsearch-results/1``). +""" + +from __future__ import annotations + +#: Classification of a converged quench (spec section 8.2). +VALID = "valid" +REACTED = "reacted" +DESORBED = "desorbed" +IMAGE_CONTACT = "image_contact" + +#: Quench outcomes (spec section 7.4). +QUENCH_FAILED = "quench_failed" +QUENCH_NOT_CONVERGED = "quench_not_converged" + +#: Start-stage outcomes (spec section 7.1). +FAILED_START = "failed_start" + +#: MD segment outcomes (spec section 7.3 step 6/7). +MD_FORCE_ABORT = "md_force_abort" +MD_INTEGRITY_ABORT = "md_integrity_abort" +MD_NONFINITE_ABORT = "md_nonfinite_abort" + +#: Statuses produced by the classification rules, in rule order. +CLASSIFICATION_STATUSES = (VALID, REACTED, DESORBED, IMAGE_CONTACT) + +#: Every status the engine can write for a stored structure. +ALL_STATUSES = ( + *CLASSIFICATION_STATUSES, + QUENCH_FAILED, + QUENCH_NOT_CONVERGED, + FAILED_START, + MD_FORCE_ABORT, + MD_INTEGRITY_ABORT, + MD_NONFINITE_ABORT, +) + +#: Statuses that are neither ranked nor chain states, ever. +NEVER_RANKED = frozenset( + { + QUENCH_FAILED, + QUENCH_NOT_CONVERGED, + FAILED_START, + MD_FORCE_ABORT, + MD_INTEGRITY_ABORT, + MD_NONFINITE_ABORT, + } +) + + +def rankable_statuses(reaction_policy: str) -> frozenset[str]: + """Statuses that enter the ranking for a given ``cs_reaction_policy``.""" + if reaction_policy == "include": + return frozenset({VALID, REACTED}) + return frozenset({VALID}) + + +__all__ = [ + "ALL_STATUSES", + "CLASSIFICATION_STATUSES", + "DESORBED", + "FAILED_START", + "IMAGE_CONTACT", + "MD_FORCE_ABORT", + "MD_INTEGRITY_ABORT", + "MD_NONFINITE_ABORT", + "NEVER_RANKED", + "QUENCH_FAILED", + "QUENCH_NOT_CONVERGED", + "REACTED", + "VALID", + "rankable_statuses", +] diff --git a/mliport/pyproject.toml b/mliport/pyproject.toml index 2b03cb58..bc170b95 100644 --- a/mliport/pyproject.toml +++ b/mliport/pyproject.toml @@ -55,6 +55,12 @@ dev = [ "mypy", # GitHub Actions workflow hygiene tests parse .github/workflows/*.yml "pyyaml", + # ase.ga.ofp_comparator (the confsearch fingerprint known-answer test) + # imports scipy and matplotlib at module level; the bounds match the + # `analysis` extra so the confsearch known-answer test runs on every CI + # Python instead of skipping. + "scipy>=1.11", + "matplotlib>=3.7", ] [project.scripts] diff --git a/tests/mliport/mliport/confsearch/__init__.py b/tests/mliport/mliport/confsearch/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/mliport/mliport/confsearch/structures.py b/tests/mliport/mliport/confsearch/structures.py new file mode 100644 index 00000000..f8008362 --- /dev/null +++ b/tests/mliport/mliport/confsearch/structures.py @@ -0,0 +1,163 @@ +"""Synthetic structures and options shared by the confsearch tests. + +Everything here is calculator-free: a small periodic "slab", a bonded +two-atom "molecule", and the option sets for the two start modes. +""" + +from __future__ import annotations + +from dataclasses import replace + +import numpy as np +from ase import Atoms + +from mliport.confsearch.graphs import ( + ClassificationReference, + MinimumClassification, + covalent_bonds, +) +from mliport.confsearch.options import ConfsearchOptions + +#: A slab of sulfur-like atoms: 2x2 grid, S-S bonds at 2.0 A (1.2 * 2.05 = 2.46). +SLAB_SPACING_A = 2.0 +SLAB_Z_A = 1.0 +SLAB_HEIGHT_A = 20.0 + + +def slab_atoms( + *, + spacing: float = SLAB_SPACING_A, + z: float = SLAB_Z_A, + height: float = SLAB_HEIGHT_A, + element: str = "S", + n: int = 2, +) -> Atoms: + """Periodic single-layer slab at the bottom of the cell, vacuum on +z.""" + positions = [ + [0.5 + i * spacing, 0.5 + j * spacing, z] for i in range(n) for j in range(n) + ] + cell = [n * spacing, n * spacing, height] + return Atoms(element * (n * n), positions=positions, cell=cell, pbc=True) + + +def oh_molecule(*, offset: float = 0.0) -> Atoms: + """A bonded O-H molecule (d(O,H) = 0.96 A < 1.2 * (0.66 + 0.31)).""" + return Atoms( + "OH", + positions=[[0.0, 0.0, 0.0], [0.96 + offset, 0.0, 0.0]], + cell=[10.0, 10.0, 10.0], + pbc=False, + ) + + +def combine(slab: Atoms, molecule: Atoms, *, shift=(0.0, 0.0, 3.0)) -> Atoms: + """Append the molecule to the slab after a rigid shift.""" + positions = np.asarray(molecule.get_positions(), dtype=float) + np.asarray( + shift, dtype=float + ) + return Atoms( + numbers=np.concatenate([slab.numbers, molecule.numbers]), + positions=np.concatenate([slab.get_positions(), positions]), + cell=slab.cell, + pbc=slab.pbc, + ) + + +def adsorbate_indices(slab: Atoms, molecule: Atoms) -> np.ndarray: + return np.arange(len(slab), len(slab) + len(molecule)) + + +def mode_a_options(**overrides) -> ConfsearchOptions: + base = { + "cs_starts": ("starts.xyz",), + "cs_adsorbate_indices": "4-5", + "cs_cycles": 0, + } + base.update(overrides) + return ConfsearchOptions(**base) + + +def mode_b_options(**overrides) -> ConfsearchOptions: + base = { + "cs_slab": "slab.vasp", + "cs_molecule": "molecule.xyz", + "cs_n_starts": 1, + "cs_cycles": 0, + } + base.update(overrides) + return ConfsearchOptions(**base) + + +def reference_for( + atoms: Atoms, + regions, + options: ConfsearchOptions, + *, + start_positions: np.ndarray | None = None, +) -> ClassificationReference: + """Build the reference graphs a minimum is classified against.""" + return ClassificationReference( + adsorbate_graph=covalent_bonds( + atoms, + regions.adsorbate, + bond_scale=options.cs_bond_scale, + ionic_symbols=options.ionic_symbols, + ), + slab_graph=covalent_bonds( + atoms, + regions.slab, + bond_scale=options.cs_bond_scale, + ionic_symbols=options.ionic_symbols, + ), + start_positions=( + np.asarray(atoms.get_positions(), dtype=float).copy() + if start_positions is None + else np.asarray(start_positions, dtype=float).copy() + ), + ) + + +def fake_classification(status: str = "valid", **overrides) -> MinimumClassification: + base = { + "status": status, + "flags": ("physisorbed",), + "adsorbate_slab_bonds": (), + "reacted_bonds": { + "adsorbate": {"lost": [], "gained": []}, + "slab": {"lost": [], "gained": []}, + }, + "min_adsorbate_slab_distance": 3.0, + "min_self_image_distance": 6.0, + "min_vacuum_gap": 12.0, + "max_slab_displacement_ionic": 0.0, + "max_slab_displacement_nonionic": 0.0, + "ionic_coordination": (), + } + base.update(overrides) + return MinimumClassification(**base) + + +def with_energy(atoms: Atoms, energy: float) -> Atoms: + """Attach a SinglePointCalculator with a fixed energy (no forces needed).""" + from ase.calculators.singlepoint import SinglePointCalculator + + result = atoms.copy() + result.calc = SinglePointCalculator(result, energy=float(energy)) + return result + + +__all__ = [ + "SLAB_HEIGHT_A", + "SLAB_SPACING_A", + "SLAB_Z_A", + "adsorbate_indices", + "combine", + "fake_classification", + "mode_a_options", + "mode_b_options", + "oh_molecule", + "reference_for", + "replace", + "slab_atoms", + "with_energy", +] diff --git a/tests/mliport/mliport/confsearch/test_fingerprint.py b/tests/mliport/mliport/confsearch/test_fingerprint.py new file mode 100644 index 00000000..afeb91cc --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_fingerprint.py @@ -0,0 +1,567 @@ +"""Focused fingerprint: invariances, discrimination and the OFP known answer.""" + +from __future__ import annotations + +import math +from pathlib import Path + +import numpy as np +import pytest +from ase import Atoms +from ase.data import covalent_radii +from ase.io import read + +from mliport.confsearch.fingerprint import ( + FingerprintGrid, + build_fingerprint, + lattice_image_distances, +) +from mliport.confsearch.placement import random_rotation_matrix +from tests.mliport.mliport.confsearch.structures import ( + combine, + mode_a_options, + oh_molecule, + slab_atoms, +) + +LGPS_PATH = ( + Path(__file__).resolve().parents[4] + / "examples/structures/li10gep2s12_primitive.vasp" +) + + +def _options(**overrides): + return mode_a_options(**overrides) + + +def _adsorbate(slab, molecule): + return np.arange(len(slab), len(slab) + len(molecule)) + + +def test_grid_binning_follows_the_documented_convention(): + grid = FingerprintGrid.build(rcut=8.0, binwidth=0.02, sigma=0.05) + assert grid.n_bins == math.ceil(8.0 / 0.02) + assert grid.centres[0] == pytest.approx(0.02) + assert grid.centres[-1] == pytest.approx(8.0) + assert grid.window == math.ceil(4 * 0.05 / 0.02) + assert float(np.sum(grid.smearing)) == pytest.approx(1.0, abs=1e-12) + + +def test_fingerprint_keys_are_the_ordered_species_matrix(): + slab = slab_atoms(element="S") + molecule = oh_molecule() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + options = _options() + fingerprint = build_fingerprint(atoms, _adsorbate(slab, molecule), options=options) + assert fingerprint.species_centres == ("H", "O") + assert fingerprint.species_all == ("H", "O", "S") + assert set(fingerprint.keys) == { + ("H", "H"), + ("H", "O"), + ("H", "S"), + ("O", "H"), + ("O", "O"), + ("O", "S"), + } + assert sum(fingerprint.weights.values()) == pytest.approx(1.0) + assert fingerprint.norm() > 0.0 + + +def test_fingerprint_of_a_structure_with_itself_is_zero(): + slab = slab_atoms(element="S") + molecule = oh_molecule() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + options = _options() + adsorbate = _adsorbate(slab, molecule) + first = build_fingerprint(atoms, adsorbate, options=options) + second = build_fingerprint(atoms.copy(), adsorbate, options=options) + assert first.distance(second) == pytest.approx(0.0, abs=1e-15) + + +def _noncommensurate_structure(): + """A cell whose distances are not near-multiples of Delta = 0.02 A. + + The bin index is ASE's raw ``floor(d / Delta)``; a distance that is a + near-exact multiple of Delta can flip its bin under a 1e-15 rotation + difference, so the invariance tests deliberately avoid that knife edge + (see the fingerprint module docstring). + """ + slab = Atoms( + "S4", + positions=[ + [0.53, 0.57, 1.01], + [2.61, 0.55, 1.03], + [0.59, 2.59, 0.99], + [2.57, 2.63, 1.02], + ], + cell=[4.13, 4.19, 20.11], + pbc=True, + ) + molecule = oh_molecule() + return slab, molecule, combine(slab, molecule, shift=(0.53, 0.57, 2.51)) + + +def test_fingerprint_is_invariant_to_lattice_translation(): + slab, molecule, atoms = _noncommensurate_structure() + options = _options() + adsorbate = _adsorbate(slab, molecule) + shifted = atoms.copy() + shifted.positions = shifted.positions + np.array([4.13, 0.0, 0.0]) + first = build_fingerprint(atoms, adsorbate, options=options) + second = build_fingerprint(shifted, adsorbate, options=options) + assert first.distance(second) == pytest.approx(0.0, abs=1e-12) + + +@pytest.mark.parametrize("reflection", [False, True]) +def test_fingerprint_is_invariant_to_rigid_rotation_and_reflection(reflection): + slab, molecule, atoms = _noncommensurate_structure() + options = _options() + adsorbate = _adsorbate(slab, molecule) + + rng = np.random.default_rng(11) + rotation = random_rotation_matrix(rng) + if reflection: + rotation = rotation @ np.diag([1.0, 1.0, -1.0]) + + rotated = atoms.copy() + rotated.cell = np.asarray(atoms.cell) @ rotation.T + rotated.positions = np.asarray(atoms.positions) @ rotation.T + + first = build_fingerprint(atoms, adsorbate, options=options) + second = build_fingerprint(rotated, adsorbate, options=options) + assert first.distance(second) == pytest.approx(0.0, abs=1e-12) + + +def test_fingerprint_is_invariant_to_relabelling_within_a_species(): + slab = slab_atoms(element="S") + molecule = oh_molecule() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + options = _options() + adsorbate = _adsorbate(slab, molecule) + + permutation = [3, 1, 2, 0, 4, 5] + shuffled = atoms[permutation] + shuffled_adsorbate = np.array( + [permutation.index(int(index)) for index in adsorbate] + ) + + first = build_fingerprint(atoms, adsorbate, options=options) + second = build_fingerprint(shuffled, shuffled_adsorbate, options=options) + assert first.distance(second) == pytest.approx(0.0, abs=1e-12) + + +def test_fingerprint_merges_symmetry_equivalent_sites_of_a_symmetric_slab(): + """A slab with an exact in-cell translation makes two sites identical.""" + slab = slab_atoms(element="S") # 2x2 grid, 4 A cell + molecule = oh_molecule() + options = _options() + adsorbate = _adsorbate(slab, molecule) + on_site_a = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + on_site_b = combine(slab, molecule, shift=(2.5, 0.5, 2.5)) + first = build_fingerprint(on_site_a, adsorbate, options=options) + second = build_fingerprint(on_site_b, adsorbate, options=options) + assert first.distance(second) == pytest.approx(0.0, abs=1e-12) + + +def test_fingerprint_distinguishes_sites_and_conformers(): + # A deliberately non-symmetric slab: no in-cell translation maps site A + # onto site B, so the two adsorption sites must be distinguished. + slab = Atoms( + "S4", + positions=[ + [0.5, 0.5, 1.0], + [2.7, 0.5, 1.0], + [0.5, 2.6, 1.0], + [2.9, 2.7, 1.0], + ], + cell=[6.0, 6.0, 20.0], + pbc=True, + ) + molecule = oh_molecule() + options = _options() + adsorbate = _adsorbate(slab, molecule) + + on_site_a = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + on_site_b = combine(slab, molecule, shift=(2.7, 0.5, 2.5)) + # A conformer that points the hydroxyl H at the surface: a large change in + # the local environment, not a rigid rotation that the radial descriptor is + # known to treat as similar. + conformer = Atoms( + "OH", + positions=[[0.0, 0.0, 0.0], [0.0, 0.0, -0.9637]], + cell=[10.0, 10.0, 10.0], + pbc=False, + ) + other_conformer = combine(slab, conformer, shift=(0.5, 0.5, 2.5)) + + reference = build_fingerprint(on_site_a, adsorbate, options=options) + assert ( + reference.distance(build_fingerprint(on_site_b, adsorbate, options=options)) + > options.cs_dedup_fp_tol + ) + assert ( + reference.distance( + build_fingerprint(other_conformer, adsorbate, options=options) + ) + > options.cs_dedup_fp_tol + ) + + +def test_self_image_distances_are_complete_and_rotation_invariant(): + cell = np.array([[4.0, 0.0, 0.0], [0.0, 4.0, 0.0], [0.0, 0.0, 20.0]]) + distances = lattice_image_distances(cell, 8.0) + assert np.all(distances > 0.0) + assert np.all(distances <= 8.0) + # 4 A in-plane translations (x, y, x+y, x-y) plus their 5.657 A diagonals + assert np.count_nonzero(np.isclose(distances, 4.0)) == 4 + assert np.count_nonzero(np.isclose(distances, math.sqrt(32.0))) == 4 + + rng = np.random.default_rng(7) + rotation = random_rotation_matrix(rng) + rotated = lattice_image_distances(cell @ rotation.T, 8.0) + assert np.allclose(distances, rotated, atol=1e-12) + + +def test_fingerprint_matches_a_brute_force_periodic_sum(): + """The neighbor_list path must reproduce a naive sum over images.""" + rng = np.random.default_rng(5) + atoms = Atoms( + "SO2H4", + positions=rng.uniform(0, 10.0, (7, 3)), + cell=[10.0, 10.0, 10.0], + pbc=True, + ) + adsorbate = np.array([0, 1, 2]) + options = _options(cs_fp_rcut=8.0, cs_fp_binwidth=0.02, cs_fp_sigma=0.05) + fingerprint = build_fingerprint(atoms, adsorbate, options=options) + + grid = FingerprintGrid.build(rcut=8.0, binwidth=0.02, sigma=0.05) + positions = np.asarray(atoms.get_positions(), dtype=float) + cell = np.asarray(atoms.cell, dtype=float) + symbols = atoms.get_chemical_symbols() + volume = float(abs(np.linalg.det(cell))) + + for alpha in fingerprint.species_centres: + for beta in fingerprint.species_all: + values = np.zeros(grid.n_bins) + centres = [i for i in adsorbate if symbols[i] == alpha] + neighbours = [j for j in range(len(atoms)) if symbols[j] == beta] + for i in centres: + for j in neighbours: + for na in (-1, 0, 1): + for nb in (-1, 0, 1): + for nc in (-1, 0, 1): + shift = np.array([na, nb, nc], dtype=float) @ cell + distance = float( + np.linalg.norm(positions[j] + shift - positions[i]) + ) + if distance > grid.rcut: + continue + if i == j and (na, nb, nc) == (0, 0, 0): + continue # self_interaction=False + base = int(np.floor(distance / grid.binwidth)) + for offset_index, offset in enumerate( + range(-grid.window, grid.window + 1) + ): + target = base + offset + if 0 <= target < grid.n_bins: + values[target] += grid.smearing[offset_index] + density = len(neighbours) / volume + denominator = ( + 4.0 * math.pi * grid.centres**2 * density * grid.binwidth * len(centres) + ) + expected = values / denominator - 1.0 + assert np.allclose(fingerprint.values[(alpha, beta)], expected, atol=1e-12) + + +def test_fingerprint_of_different_species_sets_is_not_comparable(): + slab = slab_atoms(element="S") + molecule = oh_molecule() + first = build_fingerprint( + combine(slab, molecule, shift=(0.5, 0.5, 2.5)), + _adsorbate(slab, molecule), + options=_options(), + ) + other_slab = Atoms("C4", positions=slab.get_positions(), cell=slab.cell, pbc=True) + second = build_fingerprint( + combine(other_slab, molecule, shift=(0.5, 0.5, 2.5)), + _adsorbate(other_slab, molecule), + options=_options(), + ) + from mliport.confsearch.errors import ConfsearchError + + with pytest.raises(ConfsearchError, match="only comparable"): + first.distance(second) + + +# --------------------------------------------------------------------------- +# Known answer: ASE's Oganov-Valle fingerprint +# --------------------------------------------------------------------------- + + +class _ReferenceOFP: + """Oracle copy of ASE 3.26's ``ase.ga.ofp_comparator.OFPComparator``. + + ASE 3.29 replaced ``ase.ga.ofp_comparator`` with a deprecation shim, so the + real class is used when it is importable and this verbatim copy (MIT + licensed, ASE project) is used otherwise. Only the fingerprint and cosine + distance are kept; the copy exists so the section 9.2 known-answer check + actually runs instead of silently skipping. + """ + + def __init__(self, *, rcut, binwidth, sigma, nsigma=4): + self.rcut = rcut + self.binwidth = binwidth + self.sigma = sigma + self.nsigma = nsigma + self.dimensions = 3 + + def _fingerprint(self, atoms): + from itertools import combinations_with_replacement + + from ase.neighborlist import NeighborList + from scipy.spatial.distance import cdist + + positions = atoms.get_positions() + numbers = atoms.get_atomic_numbers() + cell = atoms.get_cell() + unique_types = np.unique(numbers) + typedic = {} + for value in unique_types: + typedic[value] = [i for i, atom in enumerate(atoms) if atom.number == value] + volume = abs(np.dot(np.cross(cell[0], cell[1]), cell[2])) + + neighbour_list = NeighborList( + [self.rcut / 2.0] * len(atoms), + skin=0.0, + self_interaction=False, + bothways=True, + ) + neighbour_list.update(atoms) + + m = int(np.ceil(self.nsigma * self.sigma / self.binwidth)) + smearing_norm = math.erf( + 0.25 * np.sqrt(2) * self.binwidth * (2 * m + 1) / self.sigma + ) + nbins = int(np.ceil(self.rcut / self.binwidth)) + bindist = self.binwidth * np.arange(1, nbins + 1) + weights = 1.0 / (4.0 * np.pi * bindist**2) / self.binwidth + + def individual_rdf(index, unique_type): + rdf = np.zeros(nbins) + indices, offsets = neighbour_list.get_neighbors(index) + valid = np.where(numbers[indices] == unique_type) + points = positions[indices[valid]] + np.dot(offsets[valid], cell) + distances = cdist(points, [positions[index]]) + bins = np.floor(distances / self.binwidth) + for i in range(-m, m + 1): + newbins = bins + i + keep = np.where((newbins >= 0) & (newbins < nbins)) + valid_bins = newbins[keep].astype(int) + values = weights[valid_bins] + c = 0.25 * np.sqrt(2) * self.binwidth / self.sigma + values = values * ( + 0.5 * math.erf(c * (2 * i + 1)) - 0.5 * math.erf(c * (2 * i - 1)) + ) + values /= smearing_norm + for j, valid_bin in enumerate(valid_bins): + rdf[valid_bin] += values[j] + rdf /= len(typedic[unique_type]) / volume + return rdf + + fingerprints = {} + for t1, t2 in combinations_with_replacement(unique_types, r=2): + fingerprint = np.zeros(nbins) + for i in typedic[t1]: + fingerprint += individual_rdf(i, t2) + fingerprint /= len(typedic[t1]) + fingerprint -= 1 + fingerprints[(t1, t2)] = fingerprint + return fingerprints, typedic + + def _take_fingerprints(self, atoms): + """ASE's public-enough entry point: (fingerprints, typedic).""" + return self._fingerprint(atoms) + + def _compare_structure(self, a1, a2): + fp1, typedic1 = self._fingerprint(a1) + fp2, typedic2 = self._fingerprint(a2) + return self._cosine_distance(fp1, fp2, typedic1) + + def _cosine_distance(self, fp1, fp2, typedic1): + keys = sorted(fp1) + weights = {} + total = 0.0 + for key in keys: + weight = len(typedic1[key[0]]) * len(typedic1[key[1]]) + weights[key] = weight + total += weight + for key in keys: + weights[key] /= total + norm1 = math.sqrt( + sum(float(np.linalg.norm(fp1[key]) ** 2) * weights[key] for key in keys) + ) + norm2 = math.sqrt( + sum(float(np.linalg.norm(fp2[key]) ** 2) * weights[key] for key in keys) + ) + distance = 0.0 + for key in keys: + distance += float(np.sum(fp1[key] * fp2[key])) * weights[key] + return 0.5 * (1.0 - distance / (norm1 * norm2)) + + +def _ase_ofp_comparator(sigma: float = 0.05): + """The real ASE comparator when importable, else the verbatim oracle. + + ASE 3.29 replaced ``ase.ga.ofp_comparator`` with a deprecation shim, so on + current ASE the oracle is used. The test never skips: scipy and matplotlib + are in the ``dev`` extra so the known answer runs on every CI Python. + """ + try: + from ase.ga.ofp_comparator import OFPComparator + except Exception: # pragma: no cover - depends on the ASE version + return _ReferenceOFP(rcut=8.0, binwidth=0.02, sigma=sigma) + try: + return OFPComparator(n_top=None, rcut=8.0, binwidth=0.02, sigma=sigma, pbc=True) + except Exception: # pragma: no cover - deprecated shim + return _ReferenceOFP(rcut=8.0, binwidth=0.02, sigma=sigma) + + +def _known_answer_structure(): + """A slab + molecule cell whose distances avoid every bin boundary. + + ASE's binning is ``floor(d / Delta)``, so a pair whose distance is an exact + multiple of ``Delta`` (a textbook bond length such as 0.96 A, or a height + such as 1.50 A) can land on either side of the boundary depending on how the + neighbour list expresses the periodic image. The strict per-bin comparison + is therefore made away from the boundaries; the invariance tests below + deliberately keep the round distances to pin the deterministic rounding. + """ + slab = Atoms( + "S4", + positions=[ + [0.5317, 0.5743, 1.0113], + [2.6129, 0.5501, 1.0337], + [0.5939, 2.5891, 0.9917], + [2.5717, 2.6329, 1.0219], + ], + cell=[4.1327, 4.1913, 20.1137], + pbc=True, + ) + molecule = Atoms( + "OH", + positions=[[0.0, 0.0, 0.0], [0.9637, 0.0, 0.0]], + pbc=False, + ) + return combine(slab, molecule, shift=(0.5317, 0.5743, 2.5137)) + + +def _known_answer_structures(): + """The >= 3 structure pairs the strict known-answer test compares.""" + lgps = read(LGPS_PATH) + rng = np.random.default_rng(4) + first = lgps.copy() + first.positions = first.positions + rng.normal(0.0, 0.05, first.positions.shape) + second = lgps.copy() + second.positions = second.positions + rng.normal(0.0, 0.12, second.positions.shape) + combined = _known_answer_structure() + rotation = random_rotation_matrix(np.random.default_rng(21)) + rotated = combined.copy() + rotated.cell = np.asarray(combined.cell) @ rotation.T + rotated.positions = np.asarray(combined.positions) @ rotation.T + return [ + (lgps, first), + (first, second), + (combined, rotated), + (lgps, second), + ] + + +def _symbols(numbers): + from ase.data import chemical_symbols + + return [chemical_symbols[int(number)] for number in numbers] + + +def test_known_answer_per_bin_arrays_match_ase(): + """Spec 9.2 revision 3: per-bin equality to 1e-10, and F_ab == F_ba.""" + from ase.data import atomic_numbers + + options = _options() + comparator = _ase_ofp_comparator(sigma=options.cs_fp_sigma) + for atoms in (_known_answer_structures()[0][0], _known_answer_structure()): + fingerprint = build_fingerprint(atoms, np.arange(len(atoms)), options=options) + ase_arrays, _typedic = comparator._take_fingerprints(atoms.copy()) + for (t1, t2), expected in ase_arrays.items(): + left, right = _symbols((t1, t2)) + assert np.allclose( + fingerprint.values[(left, right)], expected, atol=1e-10 + ), (left, right) + # Symmetry of the full-system RDF: F_ab == F_ba. + assert np.allclose( + fingerprint.values[(left, right)], + fingerprint.values[(right, left)], + atol=1e-10, + ), (left, right) + assert atomic_numbers[left] <= atomic_numbers[right] or True + + +def _collapsed(fingerprint): + """My ordered keys collapsed to ASE's unordered (t1 <= t2) keys.""" + from ase.data import atomic_numbers + + collapsed = {} + for (left, right), value in fingerprint.values.items(): + key = ( + (left, right) + if atomic_numbers[left] <= atomic_numbers[right] + else (right, left) + ) + collapsed[key] = value + return collapsed + + +def _ase_weighted_distance(first, second, counts): + keys = sorted(first) + weights = {key: counts[key[0]] * counts[key[1]] for key in keys} + total = float(sum(weights.values())) + for key in keys: + weights[key] /= total + norm_first = math.sqrt( + sum(float(np.sum(first[key] ** 2)) * weights[key] for key in keys) + ) + norm_second = math.sqrt( + sum(float(np.sum(second[key] ** 2)) * weights[key] for key in keys) + ) + dot = sum(float(np.sum(first[key] * second[key])) * weights[key] for key in keys) + return 0.5 * (1.0 - dot / (norm_first * norm_second)) + + +def test_known_answer_collapsed_distance_matches_ase(): + """Spec 9.2 revision 3: collapsed D equals ASE's `_cosine_distance`.""" + options = _options() + comparator = _ase_ofp_comparator(sigma=options.cs_fp_sigma) + for first_atoms, second_atoms in _known_answer_structures(): + ase_first, typedic = comparator._take_fingerprints(first_atoms.copy()) + ase_second, _ = comparator._take_fingerprints(second_atoms.copy()) + expected = comparator._cosine_distance(ase_first, ase_second, typedic) + + first = build_fingerprint( + first_atoms, np.arange(len(first_atoms)), options=options + ) + second = build_fingerprint( + second_atoms, np.arange(len(second_atoms)), options=options + ) + counts = {} + for symbol in first_atoms.get_chemical_symbols(): + counts[symbol] = counts.get(symbol, 0) + 1 + ours = _ase_weighted_distance(_collapsed(first), _collapsed(second), counts) + assert abs(ours - expected) <= 1e-10 + + +def test_fingerprint_uses_covalent_radii_only_via_the_caller(): + """A sanity check that the module never silently invents its own radii.""" + from mliport.confsearch import fingerprint as module + + assert not hasattr(module, "covalent_radii") + assert covalent_radii[16] > 0.0 diff --git a/tests/mliport/mliport/confsearch/test_fingerprint_calibration.py b/tests/mliport/mliport/confsearch/test_fingerprint_calibration.py new file mode 100644 index 00000000..bd5336ea --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_fingerprint_calibration.py @@ -0,0 +1,395 @@ +"""Calibration of ``cs_fp_sigma`` and ``cs_dedup_fp_tol`` (spec 13.2, revision 4). + +Procedure implemented here (P1, geometry-labelled pairs; the P2 engine re-runs +it with real quenches at ``cs_quench_fmax``): + +1. Pair classes labelled by geometry: + * (a) *same*: perturbations of the reference minimum whose largest + minimum-image adsorbate displacement is within ``cs_dedup_geom_tol`` + (0.20 A). Perturbations landing more than 0.5 A away are a different + basin and are excluded and counted. + * (b) *different sites* and (c) *different conformers*: with a largest + adsorbate displacement > 0.5 A. + * (d) *equivalent*: the same minimum rigidly mapped by a slab symmetry + operation, or a permutation of equivalent atoms (a CH3/water rotation). +2. Sweep ``cs_fp_sigma`` in {0.05, 0.10, 0.20} A at binwidth 0.02 A, rcut 8 A. +3. ``D_tol(sigma) = 0.5 * min D`` over (b u c) pairs: zero false merges with a + factor-2 margin. +4. Default sigma maximises the (d) merge fraction; ties go to the larger sigma. +5. If (d) cannot be fully merged, keep the zero-false-merge tolerance and record + the residual split rate as a known limitation instead of widening into the + overlap. + +The measured table is asserted against the shipped defaults, so the defaults +cannot drift without re-running this calibration. +""" + +from __future__ import annotations + +from pathlib import Path + +import numpy as np +import pytest +from ase import Atoms +from ase.io import read + +from mliport.confsearch.fingerprint import build_fingerprint +from mliport.confsearch.geometry import mic_vectors +from mliport.confsearch.options import CS_DEFAULTS, ConfsearchOptions +from mliport.confsearch.placement import random_rotation_matrix + +SIGMA_CANDIDATES = (0.05, 0.10, 0.20) +#: Probe perturbations (A) applied to the adsorbate before the "re-quench". +PERTURBATIONS_A = (0.02, 0.05, 0.10) +DIFFERENT_BASIN_A = 0.5 +REPEATS = 12 + + +def _repository_root() -> Path: + for parent in Path(__file__).resolve().parents: + if (parent / "examples" / "structures").is_dir(): + return parent + return Path(__file__).resolve().parents[4] + + +LGPS_PATH = _repository_root() / "examples/structures/li10gep2s12_primitive.vasp" + + +def _adsorbate(torsion_deg: float = 0.0) -> Atoms: + """A CH3OH-like 6-atom adsorbate with a definable O-H torsion.""" + angle = np.deg2rad(torsion_deg) + positions = [[0.0, 0.0, 0.0], [1.43, 0.0, 0.0]] + oh = 0.9637 + bend = np.deg2rad(108.0) + positions.append( + [ + 1.43 + oh * np.cos(bend), + oh * np.sin(bend) * np.cos(angle), + oh * np.sin(bend) * np.sin(angle), + ] + ) + for phase in (0.0, 120.0, 240.0): + phi = np.deg2rad(phase) + positions.append([-1.09 * np.cos(phi), 1.09 * np.sin(phi), 0.35]) + return Atoms("COH4", positions=positions, pbc=False) + + +def _combine(slab: Atoms, molecule: Atoms, shift) -> Atoms: + return Atoms( + numbers=np.concatenate([slab.numbers, molecule.numbers]), + positions=np.concatenate( + [slab.get_positions(), molecule.get_positions() + np.asarray(shift)] + ), + cell=slab.cell, + pbc=slab.pbc, + ) + + +def _lgps_setup(): + if not LGPS_PATH.is_file(): + pytest.skip(f"LGPS structure not available at {LGPS_PATH}") + slab = read(LGPS_PATH) + symbols = np.array(slab.get_chemical_symbols()) + sulfur = np.where(symbols == "S")[0] + reference_shift = slab.get_positions()[sulfur[0]] + np.array([0.0, 0.0, 2.07]) + reference = _combine(slab, _adsorbate(), reference_shift) + return slab, sulfur, reference_shift, reference + + +def _symmetric_setup(): + """A slab and adsorbate with a mirror plane at y = 0 and 3-fold methyl H.""" + slab = Atoms( + "S4", + positions=[ + [-2.0371, -1.9837, 1.0137], + [2.0413, -1.9917, 1.0213], + [-2.0243, 2.0317, 0.9937], + [2.0117, 2.0271, 1.0173], + ], + cell=[8.1371, 8.0917, 20.1137], + pbc=True, + ) + reference = _combine(slab, _adsorbate(), np.array([0.0, 0.0, 2.5137])) + return slab, reference + + +def _slab_symmetry_operations(slab: Atoms): + """Slab symmetry operations as ``(rotation, translation)`` in fractional coords.""" + import spglib + + cell = ( + np.asarray(slab.cell, dtype=float), + np.asarray(slab.get_scaled_positions(), dtype=float), + np.asarray(slab.numbers, dtype=int), + ) + symmetry = spglib.get_symmetry(cell, symprec=1e-3) + if symmetry is None: + return [] + return list(zip(symmetry["rotations"], symmetry["translations"], strict=False)) + + +def _apply_symmetry(atoms: Atoms, rotation, translation) -> Atoms: + fractional = np.asarray(atoms.get_scaled_positions(), dtype=float) + moved = (fractional @ np.asarray(rotation, dtype=float).T) + np.asarray( + translation, dtype=float + ) + return Atoms( + numbers=np.asarray(atoms.numbers, dtype=int), + scaled_positions=moved % 1.0, + cell=np.asarray(atoms.cell, dtype=float), + pbc=np.asarray(atoms.pbc, dtype=bool), + ) + + +def _same_structure(first: Atoms, second: Atoms, *, tolerance: float = 0.05) -> bool: + """True when the two structures coincide atom by atom (wrapped, MIC).""" + cell = np.asarray(first.cell, dtype=float) + deltas = np.asarray(first.get_positions()) - np.asarray(second.get_positions()) + folded = mic_vectors(cell, deltas) + return bool(np.all(np.linalg.norm(folded, axis=1) <= tolerance)) + + +def _symmetry_related(reference: Atoms, candidate: Atoms, operations) -> bool: + """True when a slab symmetry operation maps the reference onto the candidate.""" + for rotation, translation in operations: + mapped = _apply_symmetry(reference, rotation, translation) + if _same_structure(mapped, candidate): + return True + return False + + +def _max_adsorbate_displacement(first: Atoms, second: Atoms, adsorbate) -> float: + indices = np.asarray(adsorbate, dtype=int) + deltas = ( + np.asarray(first.get_positions())[indices] + - np.asarray(second.get_positions())[indices] + ) + folded = mic_vectors(np.asarray(first.cell, dtype=float), deltas) + return float(np.max(np.linalg.norm(folded, axis=1))) + + +def _same_minimum_pairs(reference: Atoms, adsorbate, *, rng): + """Class (a): perturbed adsorbate within the geometric tolerance.""" + indices = np.asarray(adsorbate, dtype=int) + same = [] + different_basin = 0 + excluded = 0 + for perturbation in PERTURBATIONS_A: + for _ in range(REPEATS): + candidate = reference.copy() + noise = np.zeros_like(candidate.positions) + noise[indices] = rng.normal(0.0, perturbation, (len(indices), 3)) + candidate.positions = candidate.positions + noise + displacement = _max_adsorbate_displacement(candidate, reference, adsorbate) + if displacement > DIFFERENT_BASIN_A: + different_basin += 1 + elif displacement <= float(CS_DEFAULTS["cs_dedup_geom_tol"]): + same.append(candidate) + else: + excluded += 1 + return same, different_basin, excluded + + +def _distinct_pairs(slab: Atoms, reference: Atoms, adsorbate, *, rng): + """Classes (b) and (c): genuinely different sites and conformers.""" + symbols = np.array(slab.get_chemical_symbols()) + sulfur = np.where(symbols == "S")[0] + base_shift = reference.get_positions()[len(slab)].copy() + candidates = [] + for index in sulfur: + for height in (1.83, 2.41): + shift = slab.get_positions()[index] + np.array([0.0, 0.0, height]) + candidates.append(_combine(slab, _adsorbate(), shift)) + candidates.extend( + _combine(slab, _adsorbate(torsion), base_shift) + for torsion in range(30, 360, 30) + ) + for _ in range(8): + rotation = random_rotation_matrix(rng) + molecule = _adsorbate() + centroid = molecule.get_positions().mean(axis=0) + molecule.positions = ( + molecule.get_positions() - centroid + ) @ rotation.T + centroid + candidates.append(_combine(slab, molecule, base_shift)) + + operations = _slab_symmetry_operations(slab) + distinct = [] + for candidate in candidates: + if ( + _max_adsorbate_displacement(candidate, reference, adsorbate) + <= DIFFERENT_BASIN_A + ): + continue + if _symmetry_related(reference, candidate, operations): + continue + distinct.append(candidate) + return distinct + + +def _equivalent_pairs(slab: Atoms, reference: Atoms): + """Class (d): rigid symmetry map and permutation of equivalent atoms.""" + equivalent = [] + # A rigid rotation of the whole structure (the same minimum mapped by a + # slab symmetry operation) and its reflection. + for reflection in (False, True): + rotation = random_rotation_matrix(np.random.default_rng(17)) + if reflection: + rotation = rotation @ np.diag([1.0, -1.0, 1.0]) + mapped = reference.copy() + mapped.cell = np.asarray(reference.cell) @ rotation.T + mapped.positions = np.asarray(reference.positions) @ rotation.T + equivalent.append(mapped) + + # A permutation of equivalent atoms: the three methyl H atoms sit on a + # circle about the molecule's C3 axis (z through the C at z = 0.35), so + # rotating them by 120/240 degrees maps the set onto itself. + axis = np.array([0.0, 0.0, 1.0]) + centre = np.array([0.0, 0.0, 0.35]) + for angle in (120.0, 240.0): + molecule = _adsorbate() + positions = molecule.get_positions() + theta = np.deg2rad(angle) + for index in (3, 4, 5): + point = positions[index] - centre + cos_theta, sin_theta = np.cos(theta), np.sin(theta) + positions[index] = ( + centre + + point * cos_theta + + np.cross(axis, point) * sin_theta + + axis * np.dot(axis, point) * (1 - cos_theta) + ) + molecule.positions = positions + equivalent.append( + _combine(slab, molecule, reference.get_positions()[len(slab)]) + ) + return equivalent + + +def _fingerprint(atoms, adsorbate, options): + return build_fingerprint(atoms, adsorbate, options=options) + + +def _sweep(): + slab, _sulfur, _reference_shift, reference = _lgps_setup() + adsorbate = np.arange(len(slab), len(slab) + 6) + rng = np.random.default_rng(20261024) + same, different_basin, excluded = _same_minimum_pairs(reference, adsorbate, rng=rng) + distinct = _distinct_pairs(slab, reference, adsorbate, rng=rng) + + symmetric_slab, symmetric_reference = _symmetric_setup() + symmetric_adsorbate = np.arange(len(symmetric_slab), len(symmetric_slab) + 6) + equivalent = _equivalent_pairs(symmetric_slab, symmetric_reference) + + table = {} + for sigma in SIGMA_CANDIDATES: + options = ConfsearchOptions( + cs_slab="s", cs_molecule="m", cs_n_starts=1, cs_fp_sigma=sigma + ) + reference_fp = _fingerprint(reference, adsorbate, options) + distinct_distances = [ + reference_fp.distance(_fingerprint(candidate, adsorbate, options)) + for candidate in distinct + ] + symmetric_reference_fp = _fingerprint( + symmetric_reference, symmetric_adsorbate, options + ) + equivalent_distances = [ + symmetric_reference_fp.distance( + _fingerprint(candidate, symmetric_adsorbate, options) + ) + for candidate in equivalent + ] + tolerance = 0.5 * min(distinct_distances) + merged = sum(1 for distance in equivalent_distances if distance <= tolerance) + table[sigma] = { + "tolerance": tolerance, + "min_distinct": min(distinct_distances), + "max_distinct": max(distinct_distances), + "equivalent_distances": equivalent_distances, + "equivalent_merge_fraction": merged / len(equivalent), + } + chosen = max( + SIGMA_CANDIDATES, + key=lambda sigma: (table[sigma]["equivalent_merge_fraction"], sigma), + ) + return { + "table": table, + "chosen_sigma": chosen, + "chosen_tolerance": table[chosen]["tolerance"], + "n_same": len(same), + "n_different_basin": different_basin, + "n_excluded": excluded, + "n_distinct": len(distinct), + "n_equivalent": len(equivalent), + } + + +def test_calibration_sweep_matches_the_shipped_defaults(capsys): + result = _sweep() + table = result["table"] + with capsys.disabled(): + print("\nconfsearch fingerprint calibration (spec 13.2 rev 4)") + print( + " same-basin: %d, different-basin: %d, excluded: %d" + % (result["n_same"], result["n_different_basin"], result["n_excluded"]) + ) + print( + " distinct: %d, equivalent: %d" + % (result["n_distinct"], result["n_equivalent"]) + ) + for sigma, row in table.items(): + print( + " sigma={:.2f} D_tol={:.5f} min(b,c)={:.5f} max(b,c)={:.5f} " + "(d) merged={:.0f}%".format( + sigma, + row["tolerance"], + row["min_distinct"], + row["max_distinct"], + 100 * row["equivalent_merge_fraction"], + ) + ) + print( + " chosen: sigma={:.2f} D_tol={:.5f}".format( + result["chosen_sigma"], result["chosen_tolerance"] + ) + ) + + assert result["chosen_sigma"] == pytest.approx(CS_DEFAULTS["cs_fp_sigma"]) + assert result["chosen_tolerance"] == pytest.approx( + CS_DEFAULTS["cs_dedup_fp_tol"], abs=5e-4 + ) + # Zero false merges with a factor-2 margin at the shipped tolerance. + assert ( + float(CS_DEFAULTS["cs_dedup_fp_tol"]) + <= 0.5 * min(row["min_distinct"] for row in table.values()) + 1e-12 + ) + + +def test_same_basin_pairs_are_caught_by_the_geometry_rule(): + """Class (a) must merge through G, not through the fingerprint.""" + slab, _sulfur, _shift, reference = _lgps_setup() + adsorbate = np.arange(len(slab), len(slab) + 6) + rng = np.random.default_rng(20261024) + same, _different, _excluded = _same_minimum_pairs(reference, adsorbate, rng=rng) + assert same + for candidate in same: + assert _max_adsorbate_displacement(candidate, reference, adsorbate) <= float( + CS_DEFAULTS["cs_dedup_geom_tol"] + ) + + +def test_equivalent_pairs_merge_at_the_shipped_default(): + slab, reference = _symmetric_setup() + adsorbate = np.arange(len(slab), len(slab) + 6) + equivalent = _equivalent_pairs(slab, reference) + options = ConfsearchOptions(cs_slab="s", cs_molecule="m", cs_n_starts=1) + reference_fp = _fingerprint(reference, adsorbate, options) + for candidate in equivalent: + distance = reference_fp.distance(_fingerprint(candidate, adsorbate, options)) + assert distance <= options.cs_dedup_fp_tol, distance + + +def test_shipped_sigma_satisfies_the_binwidth_bound(): + options = ConfsearchOptions(cs_slab="s", cs_molecule="m", cs_n_starts=1) + assert options.cs_fp_binwidth <= 0.5 * options.cs_fp_sigma diff --git a/tests/mliport/mliport/confsearch/test_options.py b/tests/mliport/mliport/confsearch/test_options.py new file mode 100644 index 00000000..bb02137e --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_options.py @@ -0,0 +1,168 @@ +"""Options, index specifications and the v1 scope gates (spec sections 5, 12.3).""" + +from __future__ import annotations + +import pytest + +from mliport.confsearch.errors import ( + ConfsearchError, + ConfsearchNotImplementedError, +) +from mliport.confsearch.index_spec import format_index_spec, parse_index_spec +from mliport.confsearch.options import ConfsearchOptions, steps_from_ps +from tests.mliport.mliport.confsearch.structures import ( + mode_a_options, + mode_b_options, +) + + +def test_mode_a_requires_starts_and_indices(): + options = mode_a_options() + assert options.mode == "A" + with pytest.raises(ConfsearchError, match="cs_starts"): + ConfsearchOptions(cs_starts=("a.xyz",)) + with pytest.raises(ConfsearchError, match="cs_adsorbate_indices"): + ConfsearchOptions(cs_adsorbate_indices="0-1") + + +def test_mode_b_requires_slab_molecule_and_n_starts(): + options = mode_b_options(cs_n_starts=3) + assert options.mode == "B" + assert options.cs_n_starts == 3 + with pytest.raises(ConfsearchError, match="automatic placement"): + ConfsearchOptions(cs_slab="s.vasp", cs_molecule="m.xyz") + with pytest.raises(ConfsearchError, match="cannot be combined"): + ConfsearchOptions( + cs_starts=("a.xyz",), + cs_adsorbate_indices="0-1", + cs_slab="s.vasp", + cs_molecule="m.xyz", + cs_n_starts=1, + ) + + +def test_future_modes_are_rejected_by_name(): + with pytest.raises(ConfsearchNotImplementedError, match="bulk modes"): + ConfsearchOptions( + cs_mode="bulk_mobile", cs_starts=("a.xyz",), cs_adsorbate_indices="0-1" + ) + with pytest.raises(ConfsearchNotImplementedError, match="melt-quench"): + ConfsearchOptions( + cs_mode="melt_quench", cs_starts=("a.xyz",), cs_adsorbate_indices="0-1" + ) + with pytest.raises(ConfsearchError, match="cs_mode must be 'adsorbate'"): + ConfsearchOptions( + cs_mode="nonsense", cs_starts=("a.xyz",), cs_adsorbate_indices="0-1" + ) + + +@pytest.mark.parametrize( + ("overrides", "match"), + [ + ({"cs_temperature_low": 600.0}, "cs_temperature_low"), + ({"cs_temperature_high": 0.0}, "cs_temperature_high"), + ({"cs_snapshot_interval_ps": 2.0}, "cs_snapshot_interval_ps"), + ({"cs_snapshot_interval_ps": -0.5}, "cs_snapshot_interval_ps"), + ({"cs_bond_scale": 1.0}, "cs_bond_scale"), + ({"cs_bond_break_scale": 1.1}, "cs_bond_break_scale"), + ({"cs_reaction_policy": "maybe"}, "cs_reaction_policy"), + ({"cs_place_contact_scale": 1.1}, "cs_place_contact_scale"), + ({"cs_place_other_min_scale": 1.1}, "cs_place_other_min_scale"), + ({"cs_dedup_fp_tol": 1.5}, "cs_dedup_fp_tol"), + ({"cs_refine_fmax": 0.2}, "cs_refine_fmax"), + ({"cs_md_mobile": "everything"}, "cs_md_mobile"), + ({"cs_fix_below": 0.0}, "cs_fix_below"), + ({"cs_ionic_species": "Li,Xx"}, "not an element symbol"), + ({"timestep": 0.0}, "timestep"), + ({"cs_hold_ps": 0.0}, "cs_hold_ps"), + ({"cs_fp_sigma": 9.0}, "cs_fp_sigma"), + ({"cs_top_k": 0}, "cs_top_k"), + ({"cs_cycles": -1}, "cs_cycles"), + ], +) +def test_cross_key_validation_fails_closed(overrides, match): + with pytest.raises(ConfsearchError, match=match): + mode_a_options(**overrides) + + +def test_anchor_options_are_mode_b_only_and_parse_indices(): + options = mode_b_options(cs_place_anchor="0,2-3", cs_place_anchor_targets="P,S") + assert options.anchor_indices == (0, 2, 3) + assert options.anchor_target_symbols == ("P", "S") + with pytest.raises(ConfsearchError, match="only valid in mode B"): + mode_a_options(cs_place_anchor="0") + with pytest.raises(ConfsearchError, match="requires cs_place_anchor"): + mode_b_options(cs_place_anchor_targets="S") + with pytest.raises(ConfsearchError, match="cannot parse"): + mode_b_options(cs_place_anchor="0;1") + + +def test_steps_must_be_exact_integers(): + options = mode_a_options(cs_hold_ps=2.0, timestep=0.5) + assert options.n_hold == 4000 + assert options.n_cool == 4000 + assert options.n_snapshot_interval == 1000 + assert options.snapshot_steps == (1000, 2000, 3000) + assert options.total_md_steps_per_cycle == 8000 + assert options.total_quench_upper_bound == 4 * options.cs_cycles + + with pytest.raises(ConfsearchError, match="nearest valid values"): + mode_a_options(cs_hold_ps=2.0001, timestep=0.5) + + +def test_snapshot_interval_zero_means_no_snapshots(): + options = mode_a_options(cs_snapshot_interval_ps=0.0) + assert options.n_snapshot_interval == 0 + assert options.snapshot_steps == () + + +def test_steps_from_ps_helper(): + assert steps_from_ps(2.0, 0.5, name="x") == 4000 + assert steps_from_ps(0.0, 0.5, name="x", allow_zero=True) == 0 + with pytest.raises(ConfsearchError, match="nearest valid values"): + steps_from_ps(0.0011, 0.5, name="x") + with pytest.raises(ConfsearchError, match="must be"): + steps_from_ps(-1.0, 0.5, name="x") + + +def test_index_spec_parsing(): + assert parse_index_spec("300-302") == (300, 301, 302) + assert parse_index_spec("0,5,7-9") == (0, 5, 7, 8, 9) + assert parse_index_spec(" 3 , 1 ") == (1, 3) + assert parse_index_spec(4) == (4,) + assert parse_index_spec([7, 3]) == (3, 7) + + +@pytest.mark.parametrize( + ("spec", "match"), + [ + ("", "empty"), + ("0,,1", "empty entry"), + ("1-", "cannot parse"), + ("a-3", "cannot parse"), + ("9-7", "reversed range"), + ("0,0", "repeats indices"), + ("2-3,3-4", "repeats indices"), + ("-1", "negative index"), + ("0.5", "cannot parse"), + ], +) +def test_index_spec_rejects_malformed_input(spec, match): + with pytest.raises(ConfsearchError, match=match): + parse_index_spec(spec) + + +def test_index_spec_bounds_are_checked_against_the_structure(): + with pytest.raises(ConfsearchError, match="outside the 4-atom structure"): + parse_index_spec("0,4", n_atoms=4) + with pytest.raises(ConfsearchError, match="0-based"): + parse_index_spec("-1", n_atoms=4) + with pytest.raises(ConfsearchError, match="negative indices"): + parse_index_spec([-1], n_atoms=4) + assert parse_index_spec("0-3", n_atoms=4) == (0, 1, 2, 3) + + +def test_format_index_spec_round_trips(): + assert format_index_spec([0, 1, 2, 5, 7, 8]) == "0-2,5,7-8" + assert format_index_spec([]) == "" + assert parse_index_spec(format_index_spec([1, 3, 4])) == (1, 3, 4) diff --git a/tests/mliport/mliport/confsearch/test_placement.py b/tests/mliport/mliport/confsearch/test_placement.py new file mode 100644 index 00000000..62267b64 --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_placement.py @@ -0,0 +1,282 @@ +"""Automatic placement: determinism, distances, targets and rejections (spec 5.2).""" + +from __future__ import annotations + +import numpy as np +import pytest +from ase import Atoms +from ase.data import covalent_radii + +from mliport.confsearch.errors import ConfsearchPreparationError +from mliport.confsearch.geometry import ( + mic_distance_matrix, + self_image_distance, + vacuum_gap, +) +from mliport.confsearch.placement import ( + draw_rotation, + place_molecule, + random_rotation_matrix, +) +from tests.mliport.mliport.confsearch.structures import ( + mode_b_options, + oh_molecule, + slab_atoms, +) + + +def _slab(): + return slab_atoms(spacing=3.0) # 6 A cell, 20 A vacuum + + +def _options(**overrides): + return mode_b_options(**overrides) + + +def _molecule_indices(slab, molecule): + return np.arange(len(slab), len(slab) + len(molecule)) + + +def test_placement_is_deterministic_for_a_seed(): + slab = _slab() + molecule = oh_molecule() + first = place_molecule(slab, [molecule], _options(), rng=np.random.default_rng(7)) + second = place_molecule(slab, [molecule], _options(), rng=np.random.default_rng(7)) + assert np.array_equal(first.atoms.positions, second.atoms.positions) + assert first.conformer_index == second.conformer_index + assert first.quaternion == second.quaternion + assert (first.u, first.v, first.z_offset) == (second.u, second.v, second.z_offset) + # A different seed gives a different placement. + third = place_molecule(slab, [molecule], _options(), rng=np.random.default_rng(8)) + assert not np.array_equal(first.atoms.positions, third.atoms.positions) + + +def test_placed_structure_keeps_the_slab_and_appends_the_molecule(): + slab = _slab() + molecule = oh_molecule() + result = place_molecule(slab, [molecule], _options(), rng=np.random.default_rng(1)) + assert len(result.atoms) == len(slab) + len(molecule) + assert np.array_equal(result.atoms.positions[: len(slab)], slab.get_positions()) + assert result.atoms.get_chemical_symbols()[len(slab) :] == ["O", "H"] + + +def test_random_rotation_matrix_is_orthogonal(): + rng = np.random.default_rng(2) + for _ in range(20): + rotation = random_rotation_matrix(rng) + assert np.allclose(rotation @ rotation.T, np.eye(3), atol=1e-12) + assert np.linalg.det(rotation) == pytest.approx(1.0) + + +def test_random_rotations_are_uniform_on_the_sphere(): + """Section 13.2: rotated unit vectors have mean ~ 0 and ~ I/3.""" + rng = np.random.default_rng(1234) + vector = np.array([0.0, 0.0, 1.0]) + samples = np.array([random_rotation_matrix(rng) @ vector for _ in range(10_000)]) + mean = samples.mean(axis=0) + second = samples[:, :, None] * samples[:, None, :] + second = second.mean(axis=0) + assert np.all(np.abs(mean) < 0.03) + assert np.allclose(second, np.eye(3) / 3.0, atol=0.02) + + +def test_contact_placement_reaches_the_contact_scale(): + slab = _slab() + molecule = oh_molecule() + options = _options() + result = place_molecule(slab, [molecule], options, rng=np.random.default_rng(4)) + indices = _molecule_indices(slab, molecule) + assert result.kind == "contact" + assert result.min_pair_q == pytest.approx(options.cs_place_contact_scale, abs=1e-3) + + distances = mic_distance_matrix(result.atoms, indices, np.arange(len(slab))) + radii = covalent_radii[np.asarray(result.atoms.numbers, dtype=int)] + q = distances / (radii[indices][:, None] + radii[np.arange(len(slab))][None, :]) + assert np.min(q) == pytest.approx(options.cs_place_contact_scale, abs=1e-3) + assert result.min_pair_distance_A == pytest.approx(np.min(distances)) + assert result.min_self_image_distance_A >= options.cs_min_image_distance + assert result.min_vacuum_gap_A >= options.cs_min_vacuum_gap + + +def test_anchored_placement_starts_already_bonded(): + slab = _slab() + molecule = oh_molecule() + options = _options(cs_place_anchor="0") + result = place_molecule(slab, [molecule], options, rng=np.random.default_rng(5)) + indices = _molecule_indices(slab, molecule) + assert result.kind == "anchored" + assert result.anchor_index == 0 + assert result.anchor_symbol == "O" + assert result.anchor_q == pytest.approx(options.cs_place_anchor_scale, abs=1e-3) + assert result.anchor_slab_index is not None + + # The anchor is the lowest adsorbate atom and no other pair is bonded. + molecule_z = result.atoms.positions[indices, 2] + assert int(np.argmin(molecule_z)) == 0 + anchor_q = mic_distance_matrix( + result.atoms, np.array([indices[0]]), np.arange(len(slab)) + )[0] / ( + covalent_radii[result.atoms.numbers[indices[0]]] + + covalent_radii[np.asarray(result.atoms.numbers[: len(slab)], dtype=int)] + ) + assert np.min(anchor_q) == pytest.approx(options.cs_place_anchor_scale, abs=1e-3) + other_q = mic_distance_matrix( + result.atoms, np.array([indices[1]]), np.arange(len(slab)) + )[0] / ( + covalent_radii[result.atoms.numbers[indices[1]]] + + covalent_radii[np.asarray(result.atoms.numbers[: len(slab)], dtype=int)] + ) + assert np.min(other_q) >= options.cs_place_other_min_scale + + +def test_anchored_placement_respects_the_target_elements(): + slab = _slab() + molecule = oh_molecule() + options = _options(cs_place_anchor="0", cs_place_anchor_targets="S") + result = place_molecule(slab, [molecule], options, rng=np.random.default_rng(6)) + assert result.anchor_slab_index is not None + assert result.atoms.get_chemical_symbols()[result.anchor_slab_index] == "S" + + with pytest.raises(ConfsearchPreparationError, match="not present in the slab"): + place_molecule( + slab, + [molecule], + _options(cs_place_anchor="0", cs_place_anchor_targets="P"), + rng=np.random.default_rng(6), + ) + + +def test_anchor_indices_are_validated_against_the_molecule(): + slab = _slab() + molecule = oh_molecule() + with pytest.raises(ConfsearchPreparationError, match="outside the 2-atom molecule"): + place_molecule( + slab, + [molecule], + _options(cs_place_anchor="5"), + rng=np.random.default_rng(6), + ) + + +def test_conformers_must_share_one_element_order(): + slab = _slab() + first = oh_molecule() + second = Atoms("HO", positions=[[0.0, 0.0, 0.0], [0.96, 0.0, 0.0]]) + with pytest.raises(ConfsearchPreparationError, match="different element order"): + place_molecule(slab, [first, second], _options(), rng=np.random.default_rng(6)) + + +def test_conformer_choice_is_recorded(): + slab = _slab() + first = oh_molecule() + second = Atoms("OH", positions=[[0.0, 0.0, 0.0], [0.0, 0.96, 0.0]]) + result = place_molecule( + slab, [first, second], _options(), rng=np.random.default_rng(3) + ) + assert result.conformer_index in (0, 1) + + +def test_self_image_rejection_is_counted(): + slab = slab_atoms(spacing=1.5) # 3 A cell: molecule images are too close + molecule = oh_molecule() + with pytest.raises(ConfsearchPreparationError, match="self_image"): + place_molecule( + slab, + [molecule], + _options(cs_place_max_attempts=5), + rng=np.random.default_rng(9), + ) + + +def test_vacuum_rejection_is_counted(): + slab = slab_atoms(spacing=3.0, height=6.0) # only 6 A of cell height + molecule = oh_molecule() + with pytest.raises(ConfsearchPreparationError, match="vacuum"): + place_molecule( + slab, + [molecule], + _options(cs_place_max_attempts=5), + rng=np.random.default_rng(9), + ) + + +def test_anchored_other_min_scale_failure_reports_counts(): + slab = _slab() + molecule = oh_molecule() + with pytest.raises(ConfsearchPreparationError, match="other_min_scale"): + place_molecule( + slab, + [molecule], + _options( + cs_place_anchor="0", + cs_place_other_min_scale=5.0, + cs_place_max_attempts=7, + ), + rng=np.random.default_rng(10), + ) + + +def test_orientation_distribution_under_the_anchor_condition_is_uniform(): + """Rejection sampling must match brute-force rejection (section 13.2).""" + molecule = oh_molecule() + centred = np.asarray(molecule.get_positions()) - np.mean( + molecule.get_positions(), axis=0 + ) + rng = np.random.default_rng(4321) + samples = 2000 + + sampled = [] + for _ in range(samples): + for _ in range(1000): + _, rotation = draw_rotation(rng) + rotated = centred @ rotation.T + if int(np.argmin(rotated[:, 2])) == 0: + sampled.append(rotated[0] / np.linalg.norm(rotated[0])) + break + + brute = [] + while len(brute) < samples: + _, rotation = draw_rotation(rng) + rotated = centred @ rotation.T + if int(np.argmin(rotated[:, 2])) == 0: + brute.append(rotated[0] / np.linalg.norm(rotated[0])) + + sampled = np.array(sampled) + brute = np.array(brute) + assert sampled.shape == (samples, 3) + assert np.allclose(sampled.mean(axis=0), brute.mean(axis=0), atol=0.05) + assert np.allclose( + (sampled[:, :, None] * sampled[:, None, :]).mean(axis=0), + (brute[:, :, None] * brute[:, None, :]).mean(axis=0), + atol=0.03, + ) + + +def test_surface_validator_rejections_are_counted(): + slab = _slab() + molecule = oh_molecule() + + def always_reject(_atoms): + raise ConfsearchPreparationError("nope") + + with pytest.raises(ConfsearchPreparationError, match="surface_geometry"): + place_molecule( + slab, + [molecule], + _options(cs_place_max_attempts=4), + rng=np.random.default_rng(11), + surface_validator=always_reject, + ) + + +def test_self_image_distance_helper_matches_the_placement_record(): + slab = _slab() + molecule = oh_molecule() + result = place_molecule(slab, [molecule], _options(), rng=np.random.default_rng(12)) + indices = _molecule_indices(slab, molecule) + assert result.min_self_image_distance_A == pytest.approx( + self_image_distance(result.atoms, indices) + ) + assert result.min_vacuum_gap_A == pytest.approx( + vacuum_gap(result.atoms, indices, np.arange(len(slab))) + ) diff --git a/tests/mliport/mliport/confsearch/test_regions_and_graphs.py b/tests/mliport/mliport/confsearch/test_regions_and_graphs.py new file mode 100644 index 00000000..110333eb --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_regions_and_graphs.py @@ -0,0 +1,412 @@ +"""Regions, surface validation, covalent graphs and status rules (spec section 5, 8).""" + +from __future__ import annotations + +from dataclasses import replace + +import numpy as np +import pytest +from ase import Atoms +from ase.constraints import FixAtoms, FixScaled + +from mliport.confsearch.errors import ( + ConfsearchInternalError, + ConfsearchPreparationError, +) +from mliport.confsearch.geometry import periodic_gap_and_contiguity +from mliport.confsearch.graphs import ( + broken_reference_bonds, + classify_minimum, + covalent_bonds, +) +from mliport.confsearch.regions import ( + mobile_indices, + resolve_regions, + validate_all, + validate_surface, +) +from tests.mliport.mliport.confsearch.structures import ( + adsorbate_indices, + combine, + mode_a_options, + oh_molecule, + reference_for, + slab_atoms, +) + +# --------------------------------------------------------------------------- +# regions +# --------------------------------------------------------------------------- + + +def test_regions_split_adsorbate_slab_fixed_and_relax(): + slab = slab_atoms() + molecule = oh_molecule() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + atoms.set_constraint(FixAtoms(indices=[0, 1])) + options = mode_a_options() + regions = resolve_regions( + atoms, options, adsorbate_indices=adsorbate_indices(slab, molecule) + ) + + assert regions.adsorbate.tolist() == [4, 5] + assert regions.slab.tolist() == [0, 1, 2, 3] + assert regions.fixed.tolist() == [0, 1] + assert regions.relax.tolist() == [2, 3, 4, 5] + assert regions.warnings == () + + +def test_regions_reject_partial_selective_dynamics(): + slab = slab_atoms() + atoms = combine(slab, oh_molecule()) + atoms.set_constraint(FixScaled([0], mask=[True, False, False])) + options = mode_a_options() + with pytest.raises(ConfsearchPreparationError, match="only FixAtoms"): + resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + + +def test_regions_reject_fixed_adsorbate_overlap(): + slab = slab_atoms() + atoms = combine(slab, oh_molecule()) + atoms.set_constraint(FixAtoms(indices=[4])) + with pytest.raises(ConfsearchPreparationError, match="must not intersect"): + resolve_regions(atoms, mode_a_options(), adsorbate_indices=np.array([4, 5])) + + +def test_regions_warn_when_no_atoms_are_fixed(): + atoms = combine(slab_atoms(), oh_molecule()) + regions = resolve_regions( + atoms, mode_a_options(), adsorbate_indices=np.array([4, 5]) + ) + assert regions.fixed.size == 0 + assert any("F is empty" in warning for warning in regions.warnings) + + +def test_fix_below_extends_the_fixed_set(): + slab = slab_atoms(height=20.0) + slab.positions[:, 2] = [1.0, 1.0, 1.0, 1.0] + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + regions = resolve_regions( + atoms, + mode_a_options(cs_fix_below=0.5), + adsorbate_indices=np.array([4, 5]), + ) + assert regions.fixed.tolist() == [0, 1, 2, 3] + assert set(regions.fix_below_added) == {0, 1, 2, 3} + + +def test_regions_validate_the_adsorbate_selection(): + atoms = combine(slab_atoms(), oh_molecule()) + options = mode_a_options() + with pytest.raises(ConfsearchPreparationError, match="empty"): + resolve_regions(atoms, options, adsorbate_indices=np.array([], dtype=int)) + with pytest.raises(ConfsearchPreparationError, match="whole structure"): + resolve_regions(atoms, options, adsorbate_indices=np.arange(len(atoms))) + with pytest.raises(ConfsearchPreparationError, match="outside the"): + resolve_regions(atoms, options, adsorbate_indices=np.array([99])) + with pytest.raises(ConfsearchPreparationError, match="repeats"): + resolve_regions(atoms, options, adsorbate_indices=np.array([4, 4])) + + +# --------------------------------------------------------------------------- +# surface validation +# --------------------------------------------------------------------------- + + +def test_validate_surface_accepts_a_conventional_slab(): + slab = slab_atoms() + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + regions = resolve_regions( + atoms, mode_a_options(), adsorbate_indices=np.array([4, 5]) + ) + geometry = validate_all(atoms, regions, mode_a_options()) + assert geometry.z_top == pytest.approx(1.0) + assert geometry.vacuum_gap == pytest.approx(20.0) + assert geometry.adsorbate_centroid_z == pytest.approx(2.5) + + +def test_validate_surface_requires_3d_pbc(): + slab = slab_atoms() + slab.pbc = (True, True, False) + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + regions = resolve_regions( + atoms, mode_a_options(), adsorbate_indices=np.array([4, 5]) + ) + with pytest.raises(ConfsearchPreparationError, match="pbc"): + validate_surface(atoms, regions, mode_a_options()) + + +def test_validate_surface_requires_the_normal_to_be_z(): + slab = slab_atoms() + slab.cell[0] = [4.0, 0.0, 0.5] + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + regions = resolve_regions( + atoms, mode_a_options(), adsorbate_indices=np.array([4, 5]) + ) + with pytest.raises(ConfsearchPreparationError, match="surface normal must be \\+z"): + validate_surface(atoms, regions, mode_a_options()) + + +def test_validate_surface_rejects_a_wrapped_slab(): + slab = slab_atoms(height=6.0) + # Move one slab atom across the cell boundary: the vacuum is no longer the + # periodic gap, so the slab is not contiguous inside the cell. + slab.positions[3] = [2.5, 2.5, 5.0] + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 1.0)) + regions = resolve_regions( + atoms, mode_a_options(), adsorbate_indices=np.array([4, 5]) + ) + with pytest.raises(ConfsearchPreparationError, match="contiguous in z"): + validate_surface(atoms, regions, mode_a_options()) + + +def test_validate_surface_requires_the_adsorbate_above_the_slab(): + atoms = combine(slab_atoms(), oh_molecule(), shift=(0.5, 0.5, 0.2)) + regions = resolve_regions( + atoms, mode_a_options(), adsorbate_indices=np.array([4, 5]) + ) + with pytest.raises(ConfsearchPreparationError, match="centroid above the slab top"): + validate_surface(atoms, regions, mode_a_options()) + + +def test_periodic_gap_helper(): + periodic, internal = periodic_gap_and_contiguity( + np.array([1.0, 1.0, 1.0, 1.0]), 20.0 + ) + assert periodic == pytest.approx(20.0) + assert internal == pytest.approx(0.0) + periodic, internal = periodic_gap_and_contiguity( + np.array([1.0, 1.5, 5.0, 5.5]), 20.0 + ) + assert periodic == pytest.approx(15.5) + assert internal == pytest.approx(3.5) + + +def test_adsorbate_connectivity_is_enforced(): + slab = slab_atoms() + molecule = oh_molecule() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + validate_all(atoms, regions, options) + + # A molecule whose two non-ionic atoms are not bonded is not one graph. + wider = slab_atoms(spacing=3.0) + stretched = combine(wider, oh_molecule(offset=3.0), shift=(0.5, 0.5, 2.5)) + disconnected = resolve_regions( + stretched, options, adsorbate_indices=np.array([4, 5]) + ) + with pytest.raises(ConfsearchPreparationError, match="not one connected"): + validate_all(stretched, disconnected, options) + + +def test_ionic_only_adsorbate_is_allowed(): + slab = slab_atoms() + atoms = combine(slab, Atoms("Li", positions=[[0.5, 0.5, 2.5]])) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4])) + validate_all(atoms, regions, options) + + +def test_mobile_sets_follow_the_option(): + slab = slab_atoms(height=20.0) + slab.positions[:, 2] = [0.5, 1.5, 2.5, 3.5] + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 6.0)) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + + assert mobile_indices(atoms, regions, options).tolist() == [4, 5] + top = mobile_indices( + atoms, + regions, + replace(options, cs_md_mobile="adsorbate_and_top"), + z_top=3.5, + ) + assert top.tolist() == [1, 2, 3, 4, 5] + all_free = replace(options, cs_md_mobile="all_free") + assert mobile_indices(atoms, regions, all_free).tolist() == [0, 1, 2, 3, 4, 5] + + +def test_h_timestep_rule(): + slab = slab_atoms() + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + options = mode_a_options(timestep=2.0, cs_hold_ps=4.0, cs_cool_ps=4.0) + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + with pytest.raises(ConfsearchPreparationError, match="H is in the MD-mobile"): + validate_all(atoms, regions, options) + + +# --------------------------------------------------------------------------- +# covalent graphs +# --------------------------------------------------------------------------- + + +def test_covalent_bonds_respect_the_scale_and_ionic_exclusion(): + slab = slab_atoms() # S-S at 2.0 A, 1.2 * 2.05 = 2.46 + graph = covalent_bonds( + slab, np.arange(len(slab)), bond_scale=1.2, ionic_symbols=("Li",) + ) + assert graph.as_sorted_list() == [[0, 1], [0, 2], [1, 3], [2, 3]] + + tight = covalent_bonds(slab, np.arange(len(slab)), bond_scale=0.9, ionic_symbols=()) + assert len(tight) == 0 + + with_lithium = Atoms( + "LiS", + positions=[[0.0, 0.0, 0.0], [1.5, 0.0, 0.0]], + cell=[10.0, 10.0, 10.0], + pbc=True, + ) + assert ( + len( + covalent_bonds( + with_lithium, np.arange(2), bond_scale=1.2, ionic_symbols=("Li",) + ) + ) + == 0 + ) + + +def test_broken_reference_bonds_use_the_break_scale(): + molecule = Atoms( + "OH", + positions=[[0.0, 0.0, 0.0], [0.96, 0.0, 0.0]], + cell=[20.0, 20.0, 20.0], + pbc=True, + ) + reference = covalent_bonds(molecule, np.arange(2), bond_scale=1.2, ionic_symbols=()) + assert reference.as_sorted_list() == [[0, 1]] + assert ( + broken_reference_bonds(molecule, reference, break_scale=1.5, ionic_symbols=()) + == () + ) + + stretched = molecule.copy() + stretched.positions[1, 0] = 1.35 # broken at 1.2x, intact at 1.5x + assert broken_reference_bonds( + stretched, reference, break_scale=1.2, ionic_symbols=() + ) == ((0, 1),) + assert ( + broken_reference_bonds(stretched, reference, break_scale=1.5, ionic_symbols=()) + == () + ) + + +# --------------------------------------------------------------------------- +# classification +# --------------------------------------------------------------------------- + + +def _chemisorbed_case(): + slab = slab_atoms(spacing=3.0) # 6 A cell: molecule images stay >= 4 A away + molecule = oh_molecule() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + return atoms, regions, options + + +def test_adsorbate_slab_bond_is_chemisorbed_not_reacted(): + atoms, regions, options = _chemisorbed_case() + reference = reference_for(atoms, regions, options) + classification = classify_minimum( + atoms, regions=regions, options=options, reference=reference + ) + assert classification.status == "valid" + assert classification.chemisorbed + assert classification.reacted_bonds["adsorbate"]["lost"] == [] + assert len(classification.adsorbate_slab_bonds) == 1 + bond = classification.adsorbate_slab_bonds[0] + assert bond[0] == 4 and bond[1] == 0 + assert bond[4] == pytest.approx(1.5) + assert classification.min_adsorbate_slab_distance == pytest.approx(1.5) + + +def test_broken_skeleton_bond_is_reacted(): + atoms, regions, options = _chemisorbed_case() + reference = reference_for(atoms, regions, options) + broken = atoms.copy() + broken.positions[5] += [2.0, 0.0, 0.0] + classification = classify_minimum( + broken, regions=regions, options=options, reference=reference + ) + assert classification.status == "reacted" + assert classification.reacted_bonds["adsorbate"]["lost"] == [[4, 5]] + + +def test_desorbed_minimum(): + slab = slab_atoms(spacing=3.0) + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 8.0)) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + reference = reference_for(atoms, regions, options) + classification = classify_minimum( + atoms, regions=regions, options=options, reference=reference + ) + assert classification.status == "desorbed" + assert not classification.chemisorbed + + +def test_image_contact_via_self_image(): + slab = slab_atoms(spacing=1.5) + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + reference = reference_for(atoms, regions, options) + classification = classify_minimum( + atoms, regions=regions, options=options, reference=reference + ) + assert classification.min_self_image_distance < 4.0 + assert classification.status == "image_contact" + + +def test_image_contact_via_vacuum_image(): + slab = slab_atoms(spacing=3.0, height=6.0) + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 4.0)) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + reference = reference_for(atoms, regions, options) + classification = classify_minimum( + atoms, regions=regions, options=options, reference=reference + ) + assert classification.min_vacuum_gap < 8.0 + assert classification.status == "image_contact" + + +def test_slab_flags_are_recorded_without_changing_status(): + slab = slab_atoms(spacing=5.0, n=3) + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([9, 10])) + reference = reference_for(atoms, regions, options) + + rearranged = atoms.copy() + rearranged.positions[8] += [0.0, 0.0, 1.2] # far corner, > 1.0 A + classification = classify_minimum( + rearranged, regions=regions, options=options, reference=reference + ) + assert classification.status == "valid" + assert "slab_rearranged" in classification.flags + assert "far_field_slab_changed" in classification.flags + assert classification.max_slab_displacement_nonionic == pytest.approx(1.2) + + nudged = atoms.copy() + nudged.positions[8] += [0.0, 0.0, 0.6] # > 0.5 A but < 1.0 A + classification = classify_minimum( + nudged, regions=regions, options=options, reference=reference + ) + assert "far_field_slab_changed" in classification.flags + assert "slab_rearranged" not in classification.flags + + +def test_fixed_atom_movement_is_an_internal_error(): + slab = slab_atoms() + atoms = combine(slab, oh_molecule(), shift=(0.5, 0.5, 2.5)) + atoms.set_constraint(FixAtoms(indices=[0])) + options = mode_a_options() + regions = resolve_regions(atoms, options, adsorbate_indices=np.array([4, 5])) + reference = reference_for(atoms, regions, options) + moved = atoms.copy() + moved.positions[0] += [0.0, 0.0, 0.01] + with pytest.raises(ConfsearchInternalError, match="fixed atom moved"): + classify_minimum(moved, regions=regions, options=options, reference=reference) diff --git a/tests/mliport/mliport/confsearch/test_registry.py b/tests/mliport/mliport/confsearch/test_registry.py new file mode 100644 index 00000000..9a389217 --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_registry.py @@ -0,0 +1,211 @@ +"""Deduplication, representative bookkeeping and consolidation (spec section 9).""" + +from __future__ import annotations + +from dataclasses import replace + +import numpy as np +import pytest + +from mliport.confsearch.registry import ( + MinimumOrigin, + MinimumRecord, + MinimumRegistry, +) +from tests.mliport.mliport.confsearch.structures import ( + adsorbate_indices, + combine, + fake_classification, + mode_a_options, + oh_molecule, + slab_atoms, +) + + +def _registry(*, fp_tol=0.05, energy_tol=0.010, spacing=3.0, fixed=None): + slab = slab_atoms(spacing=spacing) + molecule = oh_molecule() + options = mode_a_options(cs_dedup_fp_tol=fp_tol, cs_dedup_energy_tol=energy_tol) + return ( + slab, + molecule, + options, + MinimumRegistry( + options=options, + adsorbate=adsorbate_indices(slab, molecule), + fixed=np.asarray([], dtype=int) if fixed is None else fixed, + ), + ) + + +def _record( + registry, + atoms, + *, + energy, + replica=0, + cycle=0, + source="end", + md_ps=1.0, + status="valid", +): + return MinimumRecord( + record_id=registry.new_record_id(), + energy_eV=energy, + atoms=atoms, + classification=fake_classification(status=status), + origin=MinimumOrigin(replica=replica, cycle=cycle, source=source), + quench_index=registry.total_records(), + cumulative_md_ps=md_ps, + fmax_eV_A=0.04, + steps=10, + ) + + +def test_identical_minima_join_one_unique_minimum(): + slab, molecule, _options, registry = _registry() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + + first = registry.register(_record(registry, atoms, energy=-10.0)) + second = registry.register( + _record(registry, atoms.copy(), energy=-10.001, replica=1, cycle=1, md_ps=2.0) + ) + + assert first is second + assert first.hit_count == 2 + assert first.replicas == {0, 1} + assert first.first_found_md_ps == pytest.approx(1.0) + assert first.first_found_quench_index == 1 + assert first.energy_eV == pytest.approx(-10.001) # representative updated + + +def test_energy_gap_beyond_tolerance_creates_a_new_unique_minimum(): + slab, molecule, _options, registry = _registry() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + registry.register(_record(registry, atoms, energy=-10.0)) + other = registry.register(_record(registry, atoms.copy(), energy=-9.5)) + assert other.hit_count == 1 + assert len(registry.uniques("valid")) == 2 + + +def test_fingerprint_gap_beyond_tolerance_creates_a_new_unique_minimum(): + slab, molecule, _options, registry = _registry(fp_tol=0.001) + on_site = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + other_site = combine(slab, molecule, shift=(2.5, 2.5, 2.5)) + registry.register(_record(registry, on_site, energy=-10.0)) + other = registry.register(_record(registry, other_site, energy=-10.0005)) + assert other.hit_count == 1 + assert len(registry.uniques("valid")) == 2 + + +def test_energy_shortcut_skips_the_fingerprint(monkeypatch): + slab, molecule, _options, registry = _registry() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + calls = {"n": 0} + original = registry.fingerprint + + def counting(atoms_arg): + calls["n"] += 1 + return original(atoms_arg) + + monkeypatch.setattr(registry, "fingerprint", counting) + registry.register(_record(registry, atoms, energy=-10.0)) + calls_after_first = calls["n"] + registry.register(_record(registry, atoms.copy(), energy=-9.5)) # > 0.2 eV + assert calls["n"] == calls_after_first + 1 # only the new record is fingerprinted + + +def test_status_classes_never_merge(): + slab, molecule, _options, registry = _registry() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + valid = registry.register(_record(registry, atoms, energy=-10.0, status="valid")) + reacted = registry.register( + _record(registry, atoms.copy(), energy=-10.0, status="reacted") + ) + assert valid is not reacted + assert len(registry.uniques("valid")) == 1 + assert len(registry.uniques("reacted")) == 1 + + +def test_consolidation_merges_matching_representatives(): + slab, molecule, options, registry = _registry(fp_tol=0.001) + on_site = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + other_site = combine(slab, molecule, shift=(2.5, 2.5, 2.5)) + + registry.register(_record(registry, on_site, energy=-10.0)) + registry.register(_record(registry, other_site, energy=-10.0)) + assert len(registry.uniques("valid")) == 2 + + # Widen the fingerprint tolerance (a scientific revision change) and run + # the final consolidation pass: the two representatives now match. + registry.options = replace(options, cs_dedup_fp_tol=0.5) + merges = registry.consolidate() + assert len(merges) == 1 + assert merges[0]["kept"] == 1 and merges[0]["merged"] == 2 + assert len(registry.uniques("valid")) == 1 + assert registry.uniques("valid")[0].hit_count == 2 + + +def test_registry_serializes_everything_the_exporter_needs(): + slab, molecule, _options, registry = _registry() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + registry.register(_record(registry, atoms, energy=-10.0)) + payload = registry.to_dict() + assert payload["schema"] == "mliport.confsearch-registry/1" + entry = payload["classes"]["valid"][0] + assert entry["id"] == 1 + assert entry["hit_count"] == 1 + assert entry["replicas"] == [0] + assert len(entry["representative"]["positions_A"]) == len(atoms) + assert entry["representative"]["numbers"] == [int(z) for z in atoms.numbers] + assert entry["representative"]["classification"]["status"] == "valid" + assert entry["members"][0]["origin"] == { + "replica": 0, + "cycle": 0, + "source": "end", + } + + +def test_geometric_identity_merges_a_moved_adsorbate_when_f_is_non_empty(): + slab, molecule, _options, registry = _registry(fixed=np.array([0, 1])) + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + moved = atoms.copy() + moved.positions[4] += [0.05, 0.0, 0.0] # 0.05 A < cs_dedup_geom_tol + moved.positions[5] += [0.0, -0.05, 0.0] + first = registry.register(_record(registry, atoms, energy=-10.0)) + second = registry.register(_record(registry, moved, energy=-10.0)) + assert first is second + assert first.hit_count == 2 + + +def test_geometric_identity_is_disabled_when_f_is_empty(): + slab, molecule, _options, registry = _registry(fixed=None) + assert registry.geometric_identity_enabled is False + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + moved = atoms.copy() + moved.positions[4] += [0.05, 0.0, 0.0] + first = _record(registry, atoms, energy=-10.0) + second = _record(registry, moved, energy=-10.0) + # Without anchors a whole-minimum rigid translation must not count as the + # same structure: G is disabled, so the fingerprint decides. + assert registry.geometric_match(second, first) is False + + +def test_geometric_identity_rejects_a_large_movement(): + slab, molecule, _options, registry = _registry(fixed=np.array([0, 1])) + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + moved = atoms.copy() + moved.positions[4] += [0.5, 0.0, 0.0] # > cs_dedup_geom_tol + first = registry.register(_record(registry, atoms, energy=-10.0)) + second = registry.register(_record(registry, moved, energy=-10.0)) + assert first is not second + + +def test_registration_order_is_deterministic(): + slab, molecule, _options, registry = _registry() + atoms = combine(slab, molecule, shift=(0.5, 0.5, 2.5)) + other = combine(slab, molecule, shift=(2.5, 2.5, 2.5)) + registry.register(_record(registry, atoms, energy=-10.0)) + registry.register(_record(registry, other, energy=-9.0)) + assert [unique.unique_id for unique in registry.uniques("valid")] == [1, 2] + assert registry.total_records() == 2 From 1079eef158559e9f5ca147495979d2d0cd4aada0 Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Sun, 25 Oct 2026 23:45:41 +0800 Subject: [PATCH 2/6] =?UTF-8?q?fix(confsearch):=20anchor=20against=20the?= =?UTF-8?q?=20non-ionic=20partner=20set=20(spec=20rev=205=20=C2=A75.2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tracking: #61 (spec revision 5, PR #63 review) Addresses review items 1-3 on #63. - Anchored placement now solves the height against the anchor's **partner set**: the non-ionic slab atoms by default, or exactly the `cs_place_anchor_targets` elements when that option is set. Previously the minimum `q` was taken over every slab atom, so an anchor O could be placed at 1.1x the O+Li radii sum from a lithium: an ionic contact that §8.1/§8.2 then classify as physisorbed, i.e. the "chemisorption-first" start was not chemisorbed. `anchor_partner_indices()` fails closed when the slab has no partner at all (all-ionic slab without targets). - Tests: a Li-terminated slab must bond the O anchor to a sulfur (and the recomputed min q over non-ionic atoms equals `cs_place_anchor_scale`), `cs_place_anchor_targets="Li"` is the explicit opt-in to an ionic partner, and an all-ionic slab without targets is refused. - `fingerprint.py` docstring rewritten for revisions 3-5: ASE discretisation, the withdrawn pre-rev-3 point-sampled formula, the strict per-bin 1e-10 known-answer test that never skips (ASE 3.26 oracle when the ASE 3.29 shim is in place), and the self-image paragraph reworded as a cutoff-boundary effect (images at exactly rcut) rather than an ASE defect. - `placement.py` documents that `min q` is monotone except in the descent branch, where atoms can end up slightly below the slab top. - `options.py` and the calibration test now state the P1 calibration's known limitations (bulk-cell geometry, perturbations instead of quenches, exact rigid images) and point at a real-slab/real-model recalibration as a P5 validation item. DATA IMPACT: no scientific record invalidated. Placement semantics change only for anchored starts on slabs containing ionic species; the shipped defaults and the fingerprint/dedup behaviour are unchanged. Full confsearch suite on CPU: 112 passed. --- mliport/mliport/confsearch/fingerprint.py | 99 +++++++++---------- mliport/mliport/confsearch/options.py | 9 ++ mliport/mliport/confsearch/placement.py | 57 +++++++++-- .../test_fingerprint_calibration.py | 14 +++ .../mliport/confsearch/test_placement.py | 65 ++++++++++++ 5 files changed, 188 insertions(+), 56 deletions(-) diff --git a/mliport/mliport/confsearch/fingerprint.py b/mliport/mliport/confsearch/fingerprint.py index 7e84106b..315c681a 100644 --- a/mliport/mliport/confsearch/fingerprint.py +++ b/mliport/mliport/confsearch/fingerprint.py @@ -1,60 +1,59 @@ -"""Focused Oganov-Valle fingerprint (spec section 9.2). +"""Focused Oganov-Valle fingerprint (spec section 9.2 revision 5). -ASE's ``OFPComparator`` is deliberately not used: +ASE's ``OFPComparator`` is deliberately not called: with ``n_top`` it +fingerprints the adsorbate in isolation (slab atoms are excluded, so adsorption +sites are invisible) and it imports matplotlib at module level. This module +implements the descriptor in NumPy instead. -* with ``n_top`` it fingerprints the adsorbate in isolation (slab atoms are - excluded, so adsorption sites are invisible); -* it imports matplotlib at module level. +Species structure: centres are the adsorbate atoms ``A``, neighbours are all +atoms, and every **ordered** species pair ``(alpha, beta)`` with +``alpha in species(A)`` and ``beta in species(all)`` gets its own fingerprint -This module implements the descriptor in NumPy instead. The *species -structure* is exactly the one the specification defines: centres are the -adsorbate atoms ``A``, neighbours are all atoms, and every **ordered** species -pair ``(alpha, beta)`` with ``alpha in species(A)`` and ``beta in -species(all)`` gets its own fingerprint - - F_ab(r_b) = sum_{i in A, a} sum_{j in b} g(r_b - d_ij) + F_ab(r_b) = sum_{i in A, a} sum_{j in b} g_bin(d_ij) / (4 pi r_b^2 (N_b / V) Delta n_a) - 1 -with ``g`` a Gaussian truncated at ``4 sigma`` and the weights -``w_ab = n_a N_b / sum(n_a' N_b')``. - -Discretisation (decision recorded for the PR #61 review of section 9.2): the -specification's literal bin centres ``r_k = (k + 1/2) Delta`` are *not* -compatible with its own known-answer requirement that the implementation agree -with ``OFPComparator`` to 1e-6 in ``D``. ASE places the bin centres at -``r_k = (k + 1) Delta`` and integrates the Gaussian over each bin analytically -(erf differences) instead of point-sampling it; measured on a periodic -single-species system with sigma=0.05, Delta=0.02, rcut=8.0 the two -discretisations differ by ~1.5e-3 in ``D``, i.e. 1500x the required tolerance. -The owner chose the ASE discretisation, so this module reproduces it exactly: -``nbins = ceil(rcut / Delta)``, ``r_k = (k + 1) Delta``, -``m = ceil(4 sigma / Delta)`` and the bin weights -``0.5 [erf(c(2i+1)) - erf(c(2i-1))] / erf(c(2m+1))`` with -``c = sqrt(2) Delta / (4 sigma)``. - -For a single-species system with ``A`` = all atoms the ordered matrix collapses -to ASE's key set and weights, and the known-answer test then asserts agreement -to 1e-6 in ``D`` (it is skipped when ASE's deprecated ``OFPComparator`` is not -importable). +with the weights ``w_ab = n_a N_b / sum(n_a' N_b')`` and +``D(1,2) = 0.5 (1 - sum w F1.F2 / (|F1| |F2|))``, ``|F| = sqrt(sum w F.F)``. +With ``A`` = all atoms the ordered matrix is symmetric (``F_ab == F_ba``), which +is what makes the strict known-answer comparison below possible. + +Discretisation: **ASE's, exactly** (spec section 9.2 revision 3). The +pre-revision-3 text described a point-sampled Gaussian on bins +``r_k = (k + 1/2) Delta`` with an extra ``1/Delta`` and could not satisfy the +known-answer requirement; that formulation is withdrawn. This module uses +``nbins = ceil(rcut / Delta)``, bin radius ``r_k = (k + 1) Delta``, a pair in +bin ``k = floor(d / Delta)`` spread over ``k + i`` for ``i = -m..m`` with +``m = ceil(4 sigma / Delta)`` and the analytic bin-integrated weights +``0.5 [erf(c(2i+1)) - erf(c(2i-1))] / erf(c(2m+1))``, ``c = sqrt(2) Delta / (4 sigma)``, +renormalised to sum to 1, with out-of-range bins dropped exactly as ASE does. + +Known answer (strict, always runs in CI): for every unordered key the per-bin +arrays equal ``OFPComparator(rcut, binwidth, sigma, nsigma=4)._take_fingerprints`` +to **1e-10 absolute**, ``F_ab == F_ba`` to 1e-10, and collapsing to unordered +keys with ASE's weights reproduces ASE's ``_cosine_distance`` to 1e-10 on +several structure pairs. ASE 3.29 turned ``ase.ga.ofp_comparator`` into a +deprecation shim, so the test falls back to a verbatim copy of the ASE 3.26 +algorithm (MIT) and therefore never skips; ``scipy`` and ``matplotlib`` are in +the ``dev`` extra so the real class is used when it is importable. Self-image pairs (``i == j`` with a non-zero lattice offset) are enumerated -explicitly instead of being taken from ``neighbor_list``. ASE's primitive -neighbour list returns an *orientation-dependent subset* of them (measured on a -4x4x20 A slab with rcut=8: 48 self pairs before and 72 after a rigid rotation of -the whole cell, while the 350 cross pairs are identical), which would make the -descriptor depend on how the cell happens to be oriented in space. The distance -of a self-image pair is ``|n . cell|``, so the explicit enumeration is complete -and rotation-covariant. ASE's ``NeighborList`` (which ``OFPComparator`` uses) -does return the complete self-image shell, so the known-answer comparison is -unaffected. - -The 1e-9 A rounding described in :func:`_bin_weights` is what makes the -descriptor invariant to a rigid rotation of the whole cell: without it, a -distance at a decimal multiple of ``Delta`` (0.96 A is 47.99999999999999 bins) -flips bin when the same structure is rotated by a floating-point matrix. It is -the only place where this module deviates from a verbatim port of ASE's -discretisation, and it cannot change a per-bin value unless a distance lies -within 5e-10 A of a bin boundary without lying exactly on it. +explicitly instead of being taken from ``neighbor_list``. ``neighbor_list``'s +self-image shell depends on where an image falls relative to the cutoff: on a +4x4x20 A slab with rcut=8 (images at exactly 8.0 A) it returned 48 self pairs +before and 72 after a rigid rotation of the whole cell, while the 350 cross pairs +were identical. That is a cutoff-boundary effect, not a claim about ASE's +correctness, and it is not acceptable here because it would make the descriptor +depend on the cell's orientation in space. A self-image distance is +``|n . cell|``, so the explicit enumeration is complete and rotation-covariant; +ASE's ``NeighborList`` (which ``OFPComparator`` uses) does return the complete +shell, so the known-answer comparison is unaffected. + +The 1e-9 A rounding in :func:`_bin_weights` keeps the bin index stable when the +same structure is rigidly rotated: without it, a distance at a decimal multiple +of ``Delta`` (a 0.96 A O-H bond is 47.99999999999999 bins) flips its whole +21-bin smearing window. It is the only deviation from a verbatim port of ASE's +discretisation and cannot change a per-bin value unless a distance lies within +5e-10 A of a bin boundary without lying exactly on it. """ from __future__ import annotations diff --git a/mliport/mliport/confsearch/options.py b/mliport/mliport/confsearch/options.py index 3509635c..70ff1161 100644 --- a/mliport/mliport/confsearch/options.py +++ b/mliport/mliport/confsearch/options.py @@ -83,6 +83,15 @@ # (d) 4 equivalent pairs (rigid slab symmetry + CH3 permutation): # D ~ 0 and all merge. # Zero false merges with a factor-2 margin: 0.0004 <= 0.5 * 8.5e-4. + # + # Known limitation (PR #63 review, spec rev 5): the calibration geometry is + # CH3OH inside the LGPS bulk cell, class (a) comes from random perturbations + # rather than quenches, and class (d) uses exact rigid images (D ~ 0). The + # shipped tolerance is therefore proven to give zero false merges but is + # untested for *noisy* equivalent minima: in practice D merges little beyond + # exact images and the geometric rule G does most of the work. That is the + # safe direction (duplicates instead of deleted candidates), and a real-slab + # / real-model recalibration is a P5 item in the validation campaign. # Changing this default later bumps CS_SCIENTIFIC_REVISION. "cs_dedup_fp_tol": 0.0004, "cs_fp_rcut": 8.0, diff --git a/mliport/mliport/confsearch/placement.py b/mliport/mliport/confsearch/placement.py index ca663abf..2d705c93 100644 --- a/mliport/mliport/confsearch/placement.py +++ b/mliport/mliport/confsearch/placement.py @@ -8,6 +8,19 @@ Distances are compared as ``q_ij = d_ij / (r_cov,i + r_cov,j)`` with minimum-image distances, because a single Angstrom offset does not fit every pair (C-H ~ 1.1 A, S-S ~ 2.05 A). + +Anchored placement solves the height against the anchor's **partner set**, not +against every slab atom (spec revision 5, section 5.2): the partner set is the +non-ionic slab atoms, because ionic species cannot form the covalent bond +section 8.1 counts as chemisorption (an O placed at 1.1x the O+Li radii sum is an +ionic contact, not a chemisorbed start). Naming ``cs_place_anchor_targets`` +replaces the partner set with exactly those slab elements, which is the explicit +way to anchor onto an ionic species. + +Numerical note: the objective ``min q`` is monotone in the z offset except in the +descent branch (``f(0) >= target``), where the molecule is pushed down until the +target is reached; atoms can then sit slightly below the slab top. Bisection +still finds a crossing of the target, which is what the start needs. """ from __future__ import annotations @@ -152,12 +165,40 @@ def _min_distance(atoms: Atoms, molecule: np.ndarray, slab: np.ndarray) -> float return float(np.min(distances)) if distances.size else float("inf") -def _anchor_q(atoms: Atoms, anchor: int, slab: np.ndarray) -> tuple[float, int]: - distances = mic_distance_matrix(atoms, np.array([anchor]), slab)[0] +def _anchor_q(atoms: Atoms, anchor: int, partners: np.ndarray) -> tuple[float, int]: + """Smallest ``q`` between the anchor and its partner set, and that partner.""" + distances = mic_distance_matrix(atoms, np.array([anchor]), partners)[0] radii = _radii(atoms) - q = distances / (radii[anchor] + radii[slab]) + q = distances / (radii[anchor] + radii[partners]) index = int(np.argmin(q)) - return float(q[index]), int(slab[index]) + return float(q[index]), int(partners[index]) + + +def anchor_partner_indices(slab: Atoms, options: ConfsearchOptions) -> np.ndarray: + """Slab atoms the anchored height is solved against (spec 5.2 revision 5). + + Non-ionic slab atoms by default; exactly the ``cs_place_anchor_targets`` + elements when that option is set. + """ + symbols = np.asarray(slab.get_chemical_symbols(), dtype=object) + targets = options.anchor_target_symbols + if targets is not None: + mask = np.isin(symbols, list(targets)) + else: + mask = ~np.isin(symbols, list(options.ionic_symbols)) + partners = np.arange(len(slab))[mask] + if partners.size == 0: + if targets is not None: + raise ConfsearchPreparationError( + f"cs_place_anchor_targets {sorted(targets)} select no slab atoms; " + "anchored placement has no partner to bond to" + ) + raise ConfsearchPreparationError( + "The slab has no non-ionic atoms, so anchored placement has no partner " + "to form the section 8.1 covalent bond with; name the ionic element in " + "cs_place_anchor_targets to anchor onto it explicitly" + ) + return partners def place_molecule( @@ -220,6 +261,8 @@ def place_molecule( rejections = {reason: 0 for reason in REJECTION_REASONS} slab_indices = np.arange(n_slab) molecule_indices = np.arange(n_slab, n_slab + n_molecule) + # Spec 5.2 revision 5: the anchor height is solved against the partner set. + partner_indices = anchor_partner_indices(slab, options) def make_candidate(molecule_positions: np.ndarray, numbers: np.ndarray) -> Atoms: return Atoms( @@ -278,7 +321,7 @@ def positions_at(z_offset: float) -> np.ndarray: def objective(z_offset: float) -> float: candidate = make_candidate(positions_at(z_offset), numbers) if anchor_global is not None: - value, _ = _anchor_q(candidate, anchor_global, slab_indices) + value, _ = _anchor_q(candidate, anchor_global, partner_indices) return value return _min_q(candidate, molecule_indices, slab_indices) @@ -297,7 +340,9 @@ def objective(z_offset: float) -> float: candidate = make_candidate(positions_at(z_offset), numbers) if anchor_global is not None: - anchor_value, slab_index = _anchor_q(candidate, anchor_global, slab_indices) + anchor_value, slab_index = _anchor_q( + candidate, anchor_global, partner_indices + ) others = np.setdiff1d(np.arange(n_molecule), np.array([anchor_local])) if others.size: other_min = _min_q(candidate, n_slab + others, slab_indices) diff --git a/tests/mliport/mliport/confsearch/test_fingerprint_calibration.py b/tests/mliport/mliport/confsearch/test_fingerprint_calibration.py index bd5336ea..eb626adc 100644 --- a/tests/mliport/mliport/confsearch/test_fingerprint_calibration.py +++ b/tests/mliport/mliport/confsearch/test_fingerprint_calibration.py @@ -22,6 +22,20 @@ The measured table is asserted against the shipped defaults, so the defaults cannot drift without re-running this calibration. + +Known limitations of this P1 calibration (PR #63 review, spec rev 5), which the +shipped defaults inherit: + +* the geometry is CH3OH inside the LGPS **bulk** cell, not a cleaved slab; +* class (a) is built from random perturbations, not from quenches, in this + module (the real-quench variant below uses the egg-crate model); +* class (d) uses exact rigid images and permutation-equivalent conformers, whose + D is ~0, so the tolerance is untested for *noisy* equivalent minima. + +Consequence: `D` merges little beyond exact images and the geometric rule `G` +carries same-basin merging; the energy tolerance remains the primary +discriminator. This is the conservative (false-split) direction, and a +real-slab/real-model recalibration is listed as a P5 validation-campaign item. """ from __future__ import annotations diff --git a/tests/mliport/mliport/confsearch/test_placement.py b/tests/mliport/mliport/confsearch/test_placement.py index 62267b64..28a3f616 100644 --- a/tests/mliport/mliport/confsearch/test_placement.py +++ b/tests/mliport/mliport/confsearch/test_placement.py @@ -280,3 +280,68 @@ def test_self_image_distance_helper_matches_the_placement_record(): assert result.min_vacuum_gap_A == pytest.approx( vacuum_gap(result.atoms, indices, np.arange(len(slab))) ) + + +def _li_terminated_slab(): + """A slab whose topmost atom is an ionic Li (spec 5.2 revision 5 case).""" + slab = slab_atoms(spacing=3.0) # 4 S at z = 1.0, cell 6 x 6 x 20 + slab += Atoms("Li", positions=[[0.5, 0.5, 2.0]], cell=slab.cell, pbc=True) + return slab + + +def test_anchored_placement_bonds_to_the_non_ionic_partner_not_to_lithium(): + """The anchor height is solved against the partner set, not every slab atom. + + With the pre-revision-5 behaviour the O would be placed at 1.1x the O+Li + radii sum from the Li (an ionic contact, classified physisorbed); the partner + set must exclude the ionic Li and bond to the sulfur instead. + """ + slab = _li_terminated_slab() + molecule = oh_molecule() + options = _options(cs_place_anchor="0") + result = place_molecule(slab, [molecule], options, rng=np.random.default_rng(5)) + + symbols = result.atoms.get_chemical_symbols() + assert result.anchor_symbol == "O" + assert result.anchor_slab_index is not None + assert symbols[result.anchor_slab_index] == "S" + assert result.anchor_q == pytest.approx(options.cs_place_anchor_scale, abs=1e-3) + + # Recompute against the non-ionic slab atoms: the same value. + non_ionic = np.array( + [index for index, symbol in enumerate(symbols[: len(slab)]) if symbol != "Li"] + ) + radii = covalent_radii[np.asarray(result.atoms.numbers, dtype=int)] + anchor_global = len(slab) + int(result.anchor_index or 0) + q = mic_distance_matrix(result.atoms, np.array([anchor_global]), non_ionic)[0] / ( + radii[anchor_global] + radii[non_ionic] + ) + assert float(np.min(q)) == pytest.approx(options.cs_place_anchor_scale, abs=1e-3) + + +def test_anchor_targets_can_explicitly_bond_to_an_ionic_partner(): + """Naming the ionic element in cs_place_anchor_targets is the opt-in.""" + slab = _li_terminated_slab() + molecule = oh_molecule() + options = _options(cs_place_anchor="0", cs_place_anchor_targets="Li") + result = place_molecule(slab, [molecule], options, rng=np.random.default_rng(5)) + assert result.anchor_slab_index is not None + assert result.atoms.get_chemical_symbols()[result.anchor_slab_index] == "Li" + assert result.anchor_q == pytest.approx(options.cs_place_anchor_scale, abs=1e-3) + + +def test_anchored_placement_requires_a_partner_set(): + """A slab made only of ionic species cannot form the covalent bond.""" + slab = Atoms( + "Li4", + positions=[[0.5, 0.5, 1.0], [3.5, 0.5, 1.0], [0.5, 3.5, 1.0], [3.5, 3.5, 1.0]], + cell=[6.0, 6.0, 20.0], + pbc=True, + ) + with pytest.raises(ConfsearchPreparationError, match="no non-ionic atoms"): + place_molecule( + slab, + [oh_molecule()], + _options(cs_place_anchor="0"), + rng=np.random.default_rng(5), + ) From 41102c7898cf614108d9c121c474c37d2f8e27c7 Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Mon, 26 Oct 2026 10:49:10 +0800 Subject: [PATCH 3/6] fix(confsearch): only anchored placement needs the partner set Tracking: #61 (spec revision 6, second review of PR #63) `place_molecule` computed `anchor_partner_indices(slab, options)` before it knew whether an anchor had been requested, so **contact** placement on a slab without non-ionic atoms (a Li-metal surface) was refused with an anchored-placement error. The partner set is now computed only when `cs_place_anchor` selects an anchor (the objective and the final check assert it is present), which keeps the revision 5 semantics for anchored starts. Test: contact placement of OH on an all-Li slab succeeds, reports no anchor, and still satisfies the contact rule (min q = cs_place_contact_scale to 1e-3). DATA IMPACT: no scientific record invalidated. Anchored placement is unchanged; contact placement on all-ionic slabs now works instead of failing closed. Placement suite on CPU: 20 passed. --- mliport/mliport/confsearch/placement.py | 11 ++++-- .../mliport/confsearch/test_placement.py | 36 +++++++++++++++++++ 2 files changed, 45 insertions(+), 2 deletions(-) diff --git a/mliport/mliport/confsearch/placement.py b/mliport/mliport/confsearch/placement.py index 2d705c93..01043b60 100644 --- a/mliport/mliport/confsearch/placement.py +++ b/mliport/mliport/confsearch/placement.py @@ -261,8 +261,6 @@ def place_molecule( rejections = {reason: 0 for reason in REJECTION_REASONS} slab_indices = np.arange(n_slab) molecule_indices = np.arange(n_slab, n_slab + n_molecule) - # Spec 5.2 revision 5: the anchor height is solved against the partner set. - partner_indices = anchor_partner_indices(slab, options) def make_candidate(molecule_positions: np.ndarray, numbers: np.ndarray) -> Atoms: return Atoms( @@ -306,6 +304,13 @@ def make_candidate(molecule_positions: np.ndarray, numbers: np.ndarray) -> Atoms if anchor_local is None else conformer.get_chemical_symbols()[anchor_local] ) + # Spec 5.2 revision 5: the anchor height is solved against the partner + # set, computed only when an anchor exists -- contact placement on an + # all-ionic slab (a Li-metal surface) is a valid contact target and must + # not be refused with an anchored-placement error. + partner_indices = ( + anchor_partner_indices(slab, options) if anchor_local is not None else None + ) u = float(rng.random()) v = float(rng.random()) @@ -321,6 +326,7 @@ def positions_at(z_offset: float) -> np.ndarray: def objective(z_offset: float) -> float: candidate = make_candidate(positions_at(z_offset), numbers) if anchor_global is not None: + assert partner_indices is not None # set whenever an anchor exists value, _ = _anchor_q(candidate, anchor_global, partner_indices) return value return _min_q(candidate, molecule_indices, slab_indices) @@ -340,6 +346,7 @@ def objective(z_offset: float) -> float: candidate = make_candidate(positions_at(z_offset), numbers) if anchor_global is not None: + assert partner_indices is not None anchor_value, slab_index = _anchor_q( candidate, anchor_global, partner_indices ) diff --git a/tests/mliport/mliport/confsearch/test_placement.py b/tests/mliport/mliport/confsearch/test_placement.py index 28a3f616..c40f20c4 100644 --- a/tests/mliport/mliport/confsearch/test_placement.py +++ b/tests/mliport/mliport/confsearch/test_placement.py @@ -345,3 +345,39 @@ def test_anchored_placement_requires_a_partner_set(): _options(cs_place_anchor="0"), rng=np.random.default_rng(5), ) + + +def test_contact_placement_works_on_an_all_ionic_slab(): + """Contact placement must not need the anchored-placement partner set. + + Regression from the rev 5 review: `anchor_partner_indices()` was computed + unconditionally, so placing a molecule in *contact* mode on a slab without + non-ionic atoms (a Li-metal surface) was refused with an anchored-placement + error even though no anchor was requested. + """ + slab = Atoms( + "Li4", + positions=[[0.5, 0.5, 1.0], [3.5, 0.5, 1.0], [0.5, 3.5, 1.0], [3.5, 3.5, 1.0]], + cell=[6.0, 6.0, 20.0], + pbc=True, + ) + result = place_molecule( + slab, + [oh_molecule()], + _options(), # no cs_place_anchor: contact placement + rng=np.random.default_rng(11), + ) + assert result.anchor_slab_index is None + assert result.anchor_q is None + assert len(result.atoms) == len(slab) + 2 + # The contact rule is satisfied: the smallest q is at the contact scale. + radii = covalent_radii[np.asarray(result.atoms.numbers, dtype=int)] + q = mic_distance_matrix( + result.atoms, + np.arange(len(slab), len(result.atoms)), + np.arange(len(slab)), + ) + q = q / (radii[len(slab) :, None] + radii[None, : len(slab)]) + assert float(np.min(q)) == pytest.approx( + _options().cs_place_contact_scale, abs=1e-3 + ) From c78a4509d2f0fa1a87450c7a4a706a4205946e13 Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Sun, 25 Oct 2026 10:03:48 +0800 Subject: [PATCH 4/6] feat(confsearch): search engine, checkpoint/resume, results and exports (P2) Tracking: #61 (spec revision 4, phase P2) Part of the MD-based configuration search feature. What was missing: P1 had no way to run a search - no MD cycles, no quench pipeline, no Metropolis, no checkpointing and no results. What this adds: - quench.py: fixed-cell FIRE on R with only FixAtoms, per-step finite/force gates, quench_failed / quench_not_converged as outcomes, and refine(). - engine.py: the section 7.1 schedule (start quench -> round-robin cycles -> consolidation -> refinement -> ranking), the section 7.2 mobile sets, the section 7.3 cycle (Maxwell-Boltzmann over the mobile DOF with zero fixed momenta, Langevin hold, linear cool ramp with set_temperature every cs_ramp_interval, snapshot frames, per-step safety, early integrity abort, end-of-cycle Metropolis with the uniform draw taken every eligible proposal), the section 7.5 SeedSequence streams, raw/replica_RRR/cycle_CCC output through AsyncMDOutputWriter (unchanged MD_CSV_HEADER) and cycle.json, and the section 7.1 failed_start handling. - checkpoint.py: atomic JSON checkpoints after every unit, resume fingerprint (version, revisions, model, input hashes, regions, seed, every option except output/verbosity), key-level diffing on refusal, and incomplete-attempt archiving that never deletes raw files. - results.py: discovery.csv, saturation diagnostics ("lowest found", never "global minimum"), baseline vs search, the section 8.5 warnings, top-K refinement, ranking in separate refined/unrefined tables, artifacts.json and the section 10.5 exports (POSCAR with selective dynamics, structure.extxyz, cp2k_coord.xyz, cp2k_cell.inc, cp2k_fixed_atoms.inc, minimum.json) with the slab wrapped and the adsorbate made whole under MIC. Tests (spec 13.1/13.2): test-only synthetic calculators (egg-crate with three known sites and exactly known energies, shallow-Morse bond breaking, direct force, non-finite) plus end-to-end tests that the search finds every known minimum to 1e-6 eV, that same-basin quenches merge through G, that fixed atoms never move, that the temperature ramp is the documented linear schedule, that force/non-finite/integrity aborts are recorded and the search continues, that two runs with one seed are identical, that an interrupted run resumed from its checkpoint reproduces the uninterrupted ranking exactly, and that exports re-read equal to the minimum up to lattice translations. DATA IMPACT: no scientific record invalidated. New outputs only. Full suite on CPU: 1569 passed, 33 skipped. --- mliport/mliport/confsearch/checkpoint.py | 201 ++++ mliport/mliport/confsearch/engine.py | 922 ++++++++++++++++++ mliport/mliport/confsearch/graphs.py | 12 +- mliport/mliport/confsearch/quench.py | 174 ++++ mliport/mliport/confsearch/registry.py | 146 ++- mliport/mliport/confsearch/results.py | 648 ++++++++++++ .../mliport/mliport/confsearch/calculators.py | 242 +++++ .../mliport/mliport/confsearch/test_engine.py | 445 +++++++++ 8 files changed, 2779 insertions(+), 11 deletions(-) create mode 100644 mliport/mliport/confsearch/checkpoint.py create mode 100644 mliport/mliport/confsearch/engine.py create mode 100644 mliport/mliport/confsearch/quench.py create mode 100644 mliport/mliport/confsearch/results.py create mode 100644 tests/mliport/mliport/confsearch/calculators.py create mode 100644 tests/mliport/mliport/confsearch/test_engine.py diff --git a/mliport/mliport/confsearch/checkpoint.py b/mliport/mliport/confsearch/checkpoint.py new file mode 100644 index 00000000..287f76db --- /dev/null +++ b/mliport/mliport/confsearch/checkpoint.py @@ -0,0 +1,201 @@ +"""Atomic checkpoints, resume fingerprint and incomplete-attempt archiving. + +Reuses the NEB helpers (``atomic_write_json``, ``canonical_fingerprint``) so the +durability and identity contracts are the same ones the rest of mliport already +relies on. Spec section 11.2: a checkpoint is written after the start-quench +stage and after every (replica, cycle) unit, and resuming re-runs the +interrupted unit from the checkpointed RNG state. Raw files of an interrupted +attempt are moved to ``incomplete_attempt_N/`` and never deleted +(AGENTS.md rule 11). +""" + +from __future__ import annotations + +import json +from collections.abc import Mapping +from dataclasses import dataclass, field +from pathlib import Path +from typing import TYPE_CHECKING + +import numpy as np + +from mliport.confsearch.errors import ConfsearchPreparationError +from mliport.confsearch.revisions import ( + CS_CHECKPOINT_SCHEMA_REVISION, + CS_SCIENTIFIC_REVISION, +) +from mliport.neb.io import atomic_write_json, canonical_fingerprint + +if TYPE_CHECKING: + from typing import Any + +CHECKPOINT_SCHEMA = "mliport.confsearch-checkpoint/1" +RESUME_FINGERPRINT_SCHEMA = "mliport.confsearch-resume-fingerprint/1" + + +@dataclass +class CheckpointData: + """Everything needed to resume a search exactly where it stopped.""" + + unit_index: int = 0 + stage: str = "prepared" + replicas: list[dict] = field(default_factory=list) + rng_states: dict[str, Any] = field(default_factory=dict) + registry: dict = field(default_factory=dict) + discovery: list[dict] = field(default_factory=list) + baseline: dict = field(default_factory=dict) + cumulative_md_ps: float = 0.0 + quench_index: int = 0 + + def to_dict(self) -> dict: + return { + "schema": CHECKPOINT_SCHEMA, + "checkpoint_schema_revision": CS_CHECKPOINT_SCHEMA_REVISION, + "scientific_revision": CS_SCIENTIFIC_REVISION, + "unit_index": int(self.unit_index), + "stage": self.stage, + "replicas": self.replicas, + "rng_states": self.rng_states, + "registry": self.registry, + "discovery": self.discovery, + "baseline": self.baseline, + "cumulative_md_ps": float(self.cumulative_md_ps), + "quench_index": int(self.quench_index), + } + + @classmethod + def from_dict(cls, payload: Mapping[str, Any]) -> CheckpointData: + return cls( + unit_index=int(payload.get("unit_index", 0)), + stage=str(payload.get("stage", "prepared")), + replicas=list(payload.get("replicas") or []), + rng_states=dict(payload.get("rng_states") or {}), + registry=dict(payload.get("registry") or {}), + discovery=list(payload.get("discovery") or []), + baseline=dict(payload.get("baseline") or {}), + cumulative_md_ps=float(payload.get("cumulative_md_ps", 0.0)), + quench_index=int(payload.get("quench_index", 0)), + ) + + +def build_resume_fingerprint( + *, + options, + model: Mapping[str, Any] | None, + input_hashes: Mapping[str, Any], + regions: Mapping[str, Any], + seed: int | None, + mliport_version: str, +) -> tuple[dict[str, Any], str]: + """Identity of a search: everything except pure output/verbosity settings. + + ``cs_cycles`` is deliberately included: ``extend`` is the only supported way + to change the budget, and it records the extension instead of pretending the + fingerprint is unchanged. + """ + import dataclasses # noqa: PLC0415 + + options_dict = { + item.name: _jsonable(getattr(options, item.name)) + for item in dataclasses.fields(options) + if not item.name.startswith("_") + } + value = { + "schema": RESUME_FINGERPRINT_SCHEMA, + "software": { + "mliport_version": mliport_version, + "cs_scientific_revision": CS_SCIENTIFIC_REVISION, + "cs_checkpoint_schema_revision": CS_CHECKPOINT_SCHEMA_REVISION, + }, + "model": dict(model or {}), + "input_hashes": dict(input_hashes), + "regions": dict(regions), + "seed": seed, + "options": options_dict, + } + return canonical_fingerprint(value) + + +def _jsonable(value: Any) -> Any: + if isinstance(value, (str, int, float, bool)) or value is None: + return value + if isinstance(value, (list, tuple)): + return [_jsonable(item) for item in value] + if isinstance(value, dict): + return {str(key): _jsonable(item) for key, item in value.items()} + if isinstance(value, np.ndarray): + return value.tolist() + return str(value) + + +def compare_fingerprints( + recorded: Mapping[str, Any], current: Mapping[str, Any] +) -> list[str]: + """Return the differing key paths between two resume fingerprints.""" + differences: list[str] = [] + + def walk(left: Any, right: Any, path: str) -> None: + if isinstance(left, Mapping) and isinstance(right, Mapping): + for key in sorted(set(left) | set(right)): + walk(left.get(key), right.get(key), f"{path}.{key}") + return + if left != right: + differences.append(f"{path}: recorded {left!r} != current {right!r}") + + walk(recorded, current, "") + return differences + + +class ConfsearchCheckpointStore: + """Write/read the single ``checkpoints/confsearch.json`` of one run.""" + + def __init__(self, run_dir: str | Path) -> None: + self.run_dir = Path(run_dir) + self.directory = self.run_dir / "checkpoints" + self.path = self.directory / "confsearch.json" + + def write(self, data: CheckpointData, fingerprint: Mapping[str, Any]) -> Path: + self.directory.mkdir(parents=True, exist_ok=True) + payload = data.to_dict() + payload["resume_fingerprint"] = dict(fingerprint) + payload["resume_fingerprint_sha256"] = canonical_fingerprint(dict(fingerprint))[ + 1 + ] + atomic_write_json(self.path, payload) + return self.path + + def load(self) -> tuple[CheckpointData, dict[str, Any]]: + if not self.path.is_file(): + raise ConfsearchPreparationError(f"No confsearch checkpoint at {self.path}") + payload = json.loads(self.path.read_text(encoding="utf-8")) + recorded = payload.get("resume_fingerprint") + if not isinstance(recorded, Mapping): + raise ConfsearchPreparationError("Checkpoint has no resume fingerprint") + expected = payload.get("resume_fingerprint_sha256") + actual = canonical_fingerprint(dict(recorded))[1] + if expected is not None and expected != actual: + raise ConfsearchPreparationError( + "Checkpoint resume fingerprint is corrupted (sha256 mismatch)" + ) + return CheckpointData.from_dict(payload), dict(recorded) + + def archive_incomplete(self, *, replica: int, cycle: int) -> Path | None: + """Move an interrupted cycle's raw directory aside; never delete it.""" + source = self.run_dir / "raw" / f"replica_{replica:03d}" / f"cycle_{cycle:03d}" + if not source.is_dir(): + return None + attempt = 1 + while (target := source.parent / f"incomplete_attempt_{attempt}").exists(): + attempt += 1 + source.rename(target) + return target + + +__all__ = [ + "CHECKPOINT_SCHEMA", + "RESUME_FINGERPRINT_SCHEMA", + "CheckpointData", + "ConfsearchCheckpointStore", + "build_resume_fingerprint", + "compare_fingerprints", +] diff --git a/mliport/mliport/confsearch/engine.py b/mliport/mliport/confsearch/engine.py new file mode 100644 index 00000000..92b2dad9 --- /dev/null +++ b/mliport/mliport/confsearch/engine.py @@ -0,0 +1,922 @@ +"""Confsearch search engine: cycles, MD segments, quench, Metropolis (spec 7). + +The engine is calculator-agnostic: it takes any ASE calculator with energy and +forces, which is what makes the synthetic-model end-to-end tests possible. The +model identity, gradient pre-flight and CLI/API wiring live one layer above +(phase P3). + +Flow (spec 7.1):: + + prepare starts -> stage "start_quench" (quench every start) + -> for cycle c = 1..cs_cycles: + for replica r = 0..n-1 (round robin, skip finished/failed): + run cycle (r, c); register its minima; checkpoint + -> consolidation -> refinement of top-K -> ranking, exports, diagnostics + +One model instance is used for the whole search. Every stochastic draw comes +from a per-replica ``SeedSequence`` stream (section 7.5), and every checkpoint +stores the bit-generator state before the next unit of work, so an interrupted +search resumes bitwise-identically. +""" + +from __future__ import annotations + +import json +import math +import time +from dataclasses import dataclass, field +from pathlib import Path +from typing import TYPE_CHECKING, Any + +import numpy as np +from ase import units +from ase.constraints import FixAtoms +from ase.md.langevin import Langevin +from ase.md.velocitydistribution import MaxwellBoltzmannDistribution + +from mliport.confsearch import status as cs_status +from mliport.confsearch.checkpoint import ( + CheckpointData, + ConfsearchCheckpointStore, +) +from mliport.confsearch.errors import ( + ConfsearchInternalError, + ConfsearchPreparationError, +) +from mliport.confsearch.geometry import wrap_positions +from mliport.confsearch.graphs import ( + ClassificationReference, + broken_reference_bonds, + classify_minimum, + covalent_bonds, +) +from mliport.confsearch.options import ConfsearchOptions +from mliport.confsearch.quench import QuenchResult, quench +from mliport.confsearch.regions import ( + Regions, + SurfaceGeometry, + mobile_indices, +) +from mliport.confsearch.registry import ( + MinimumOrigin, + MinimumRecord, + MinimumRegistry, +) +from mliport.confsearch.results import build_results +from mliport.runners.md_output import ( + AsyncMDOutputWriter, + MDFrameSnapshot, +) +from mliport.runners.safety import ( + evaluate_force_abort, + force_magnitudes, + force_views, + validate_safe_point, +) + +if TYPE_CHECKING: + from collections.abc import Callable, Sequence + + from ase import Atoms + +#: Sampling distance for the "unique minima within 0.2 eV" discovery column. +DISCOVERY_WINDOW_EV = 0.2 + + +@dataclass(frozen=True, slots=True) +class PreparedStart: + """One validated start structure plus its regions and surface facts.""" + + index: int + atoms: Atoms + regions: Regions + surface: SurfaceGeometry + label: str + placement: Any = None + + def to_dict(self) -> dict: + return { + "index": self.index, + "label": self.label, + "n_atoms": len(self.atoms), + "regions": { + "adsorbate": self.regions.adsorbate.tolist(), + "slab": self.regions.slab.tolist(), + "fixed": self.regions.fixed.tolist(), + "relax": self.regions.relax.tolist(), + "fix_below_added": list(self.regions.fix_below_added), + "warnings": list(self.regions.warnings), + }, + "surface": { + "z_top_A": self.surface.z_top, + "z_min_A": self.surface.z_min, + "vacuum_gap_A": self.surface.vacuum_gap, + "adsorbate_centroid_z_A": self.surface.adsorbate_centroid_z, + }, + "placement": ( + self.placement.to_dict() if self.placement is not None else None + ), + } + + +@dataclass +class ReplicaState: + """One independent search chain.""" + + index: int + start: PreparedStart + md_rng: np.random.Generator + mc_rng: np.random.Generator + status: str = "active" + current: Atoms | None = None + current_energy: float | None = None + reference: ClassificationReference | None = None + start_minimum_energy: float | None = None + cycle_count: int = 0 + cycles_completed: list[int] = field(default_factory=list) + + def to_checkpoint(self) -> dict: + return { + "index": self.index, + "status": self.status, + "cycle_count": self.cycle_count, + "cycles_completed": list(self.cycles_completed), + "current_energy_eV": self.current_energy, + "start_minimum_energy_eV": self.start_minimum_energy, + "current": ( + None + if self.current is None + else { + "numbers": [int(z) for z in self.current.numbers], + "cell_A": np.asarray(self.current.cell, dtype=float).tolist(), + "pbc": [bool(value) for value in self.current.pbc], + "positions_A": np.asarray( + self.current.get_positions(), dtype=float + ).tolist(), + } + ), + "reference_start_positions_A": ( + None + if self.reference is None + else np.asarray(self.reference.start_positions, dtype=float).tolist() + ), + } + + +class _MDAbort(RuntimeError): + """Internal signal: the MD segment stopped with a recorded status.""" + + def __init__(self, status: str, message: str, frame: Atoms | None = None): + super().__init__(message) + self.status = status + self.frame = frame + + +class SearchEngine: + """Run one confsearch search (or resume one) with a single model instance.""" + + def __init__( + self, + *, + calculator, + options: ConfsearchOptions, + starts: Sequence[PreparedStart], + output_dir: str | Path, + seed: int, + model_record: dict | None = None, + gradient_preflight: dict | None = None, + resume: CheckpointData | None = None, + resume_fingerprint: dict | None = None, + log: Callable[[str], None] | None = None, + ) -> None: + if not starts: + raise ConfsearchPreparationError("confsearch needs at least one start") + self.calculator = calculator + self.options = options + self.starts = list(starts) + self.output_dir = Path(output_dir) + self.seed = int(seed) + self.model_record = dict(model_record or {}) + self.gradient_preflight = dict(gradient_preflight or {}) + self.resume = resume + self.resume_fingerprint = dict(resume_fingerprint or {}) + self._log_lines: list[str] = [] + self._log_callback = log + self.warnings: list[str] = [] + self.started = time.time() + + self.store = ConfsearchCheckpointStore(self.output_dir) + self.registry: MinimumRegistry + self.replicas: list[ReplicaState] + self.discovery: list[dict] = [] + self.baseline: dict = {} + self.cumulative_md_ps = 0.0 + self.quench_index = 0 + self.completed_units = 0 + self.stage = "prepared" + self._reference_graphs: tuple[Any, Any] | None = None + self._initialize_state() + + # -- logging ---------------------------------------------------------- + + def log(self, message: str) -> None: + self._log_lines.append(message) + if self._log_callback is not None: + self._log_callback(message) + + def log_lines(self) -> list[str]: + return list(self._log_lines) + + # -- state ------------------------------------------------------------ + + def _initialize_state(self) -> None: + adsorbate = np.asarray(self.starts[0].regions.adsorbate, dtype=int) + fixed = np.asarray(self.starts[0].regions.fixed, dtype=int) + self.registry = MinimumRegistry( + options=self.options, adsorbate=adsorbate, fixed=fixed + ) + seed_sequence = np.random.SeedSequence(self.seed) + placement_ss, *replica_sequences = seed_sequence.spawn(1 + len(self.starts)) + self.placement_seed_sequence = placement_ss + self.replicas = [] + for index, start in enumerate(self.starts): + md_ss, mc_ss = replica_sequences[index].spawn(2) + self.replicas.append( + ReplicaState( + index=index, + start=start, + md_rng=np.random.default_rng(md_ss), + mc_rng=np.random.default_rng(mc_ss), + ) + ) + if fixed.size == 0: + self.warnings.append( + "F is empty: the geometric identity rule G is disabled for this " + "search, so dedup relies on the fingerprint alone" + ) + + def _reference_identity(self) -> tuple[Any, Any]: + """Graphs shared by every start (section 8.1); fail closed on mismatch.""" + if self._reference_graphs is not None: + return self._reference_graphs + reference: tuple[Any, Any] | None = None + for start in self.starts: + regions = start.regions + graphs = ( + covalent_bonds( + start.atoms, + regions.adsorbate, + bond_scale=self.options.cs_bond_scale, + ionic_symbols=self.options.ionic_symbols, + ), + covalent_bonds( + start.atoms, + regions.slab, + bond_scale=self.options.cs_bond_scale, + ionic_symbols=self.options.ionic_symbols, + ), + ) + if reference is None: + reference = graphs + continue + if ( + graphs[0].bonds != reference[0].bonds + or graphs[1].bonds != reference[1].bonds + ): + raise ConfsearchPreparationError( + f"Start {start.index} has a different covalent graph than " + "start 0; all starts must describe the same molecule on the " + "same slab (section 8.1)" + ) + assert reference is not None + self._reference_graphs = reference + return reference + + # -- checkpoint ------------------------------------------------------- + + def _rng_states(self) -> dict: + return { + "replicas": [ + { + "index": replica.index, + "md": replica.md_rng.bit_generator.state, + "mc": replica.mc_rng.bit_generator.state, + } + for replica in self.replicas + ], + } + + def _write_checkpoint(self) -> None: + data = CheckpointData( + unit_index=self.completed_units, + stage=self.stage, + replicas=[replica.to_checkpoint() for replica in self.replicas], + rng_states=self._rng_states(), + registry=self.registry.to_dict(), + discovery=list(self.discovery), + baseline=dict(self.baseline), + cumulative_md_ps=self.cumulative_md_ps, + quench_index=self.quench_index, + ) + self.store.write(data, self.resume_fingerprint) + + def _restore(self) -> None: + assert self.resume is not None + self.completed_units = int(self.resume.unit_index) + self.stage = str(self.resume.stage) + self.discovery = list(self.resume.discovery) + self.baseline = dict(self.resume.baseline) + self.cumulative_md_ps = float(self.resume.cumulative_md_ps) + self.quench_index = int(self.resume.quench_index) + adsorbate = np.asarray(self.starts[0].regions.adsorbate, dtype=int) + fixed = np.asarray(self.starts[0].regions.fixed, dtype=int) + self.registry = MinimumRegistry.from_dict( + self.resume.registry, + options=self.options, + adsorbate=adsorbate, + fixed=fixed, + ) + states = { + int(entry["index"]): entry + for entry in (self.resume.rng_states or {}).get("replicas", []) + } + for entry in self.resume.replicas: + index = int(entry["index"]) + replica = self.replicas[index] + replica.status = str(entry.get("status", "active")) + replica.cycle_count = int(entry.get("cycle_count", 0)) + replica.cycles_completed = [ + int(value) for value in entry.get("cycles_completed", []) + ] + replica.current_energy = entry.get("current_energy_eV") + replica.start_minimum_energy = entry.get("start_minimum_energy_eV") + geometry = entry.get("current") + if geometry is not None: + from ase import Atoms # noqa: PLC0415 + + replica.current = Atoms( + numbers=np.asarray(geometry["numbers"], dtype=int), + positions=np.asarray(geometry["positions_A"], dtype=float), + cell=np.asarray(geometry["cell_A"], dtype=float), + pbc=np.asarray(geometry["pbc"], dtype=bool), + ) + reference_positions = entry.get("reference_start_positions_A") + if reference_positions is not None: + adsorbate_graph, slab_graph = self._reference_identity() + replica.reference = ClassificationReference( + adsorbate_graph=adsorbate_graph, + slab_graph=slab_graph, + start_positions=np.asarray(reference_positions, dtype=float), + ) + if index in states: + replica.md_rng.bit_generator.state = states[index]["md"] + replica.mc_rng.bit_generator.state = states[index]["mc"] + # Raw files of the interrupted attempt must survive (AGENTS.md rule 11). + for replica in self.replicas: + if replica.status != "active": + continue + cycle = replica.cycle_count + 1 + archived = self.store.archive_incomplete(replica=replica.index, cycle=cycle) + if archived is not None: + self.log(f"Archived interrupted attempt to {archived.name}") + + # -- plan ------------------------------------------------------------- + + def _plan(self) -> list[tuple[str, int, int]]: + units: list[tuple[str, int, int]] = [("start", 0, 0)] + for cycle in range(1, int(self.options.cs_cycles) + 1): + for replica in self.replicas: + units.append(("cycle", replica.index, cycle)) + return units + + # -- public entry point ----------------------------------------------- + + def run(self) -> dict: + self.output_dir.mkdir(parents=True, exist_ok=True) + if self.resume is not None: + self._restore() + self._reference_identity() + self._log_budget() + plan = self._plan() + for index, (kind, replica_index, cycle) in enumerate(plan): + if index < self.completed_units: + continue + if kind == "start": + self._run_start_stage() + self.stage = "start_quench_done" + else: + self._run_cycle_unit(replica_index, cycle) + self.stage = "cycles" + self.completed_units = index + 1 + self._write_checkpoint() + return self._finish() + + # -- budget / diagnostics --------------------------------------------- + + def _log_budget(self) -> None: + options = self.options + n_replicas = len(self.replicas) + md_steps = n_replicas * options.total_md_steps_per_cycle * options.cs_cycles + self.log( + "confsearch budget: " + f"{n_replicas} replicas x {options.cs_cycles} cycles, " + f"{md_steps} MD steps, <= {n_replicas * options.total_quench_upper_bound} " + "quenches" + ) + + def _discovery_row(self, record: MinimumRecord) -> dict: + valid = [ + unique + for unique in self.registry.uniques(cs_status.VALID) + if math.isfinite(unique.energy_eV) + ] + energies = [unique.energy_eV for unique in valid] + best = min(energies) if energies else None + within = ( + sum(1 for energy in energies if best is not None and energy - best <= 0.2) + if best is not None + else 0 + ) + energy = float(record.energy_eV) + return { + "cumulative_md_ps": float(self.cumulative_md_ps), + "quench_index": int(record.quench_index), + "unique_valid": len(valid), + "unique_valid_within_0p2eV": int(within), + "current_best_eV": best, + "energy_eV": energy if math.isfinite(energy) else None, + "status": record.status, + } + + # -- start stage ------------------------------------------------------ + + def _run_start_stage(self) -> None: + self.log("stage: quench every start") + adsorbate_graph, slab_graph = self._reference_identity() + for replica in self.replicas: + start = replica.start + result = quench( + start.atoms, + self.calculator, + self.options, + fixed_indices=start.regions.fixed, + ) + reference = ClassificationReference( + adsorbate_graph=adsorbate_graph, + slab_graph=slab_graph, + start_positions=np.asarray(result.atoms.get_positions(), dtype=float), + ) + record = self._register( + result, + regions=start.regions, + reference=reference, + origin=MinimumOrigin(replica=replica.index, cycle=0, source="start"), + md_ps=0.0, + ) + replica.reference = reference + replica.start_minimum_energy = record.energy_eV + if record.status != cs_status.VALID: + replica.status = cs_status.FAILED_START + replica.current = None + self.log( + f"replica {replica.index}: start quench is {record.status}; " + "marked failed_start (no cycles)" + ) + continue + replica.current = record.atoms.copy() + replica.current_energy = record.energy_eV + self.log( + f"replica {replica.index}: start minimum {record.energy_eV:.6f} eV" + ) + valid = [unique.energy_eV for unique in self.registry.uniques(cs_status.VALID)] + self.baseline = { + "stage": "start_quench", + "n_replicas": len(self.replicas), + "n_surviving": sum( + 1 for replica in self.replicas if replica.status == "active" + ), + "best_energy_eV": min(valid) if valid else None, + } + if not any(replica.status == "active" for replica in self.replicas): + raise ConfsearchPreparationError( + "No replica survived the start-quench stage; the search cannot " + "continue (section 7.1)" + ) + + # -- cycles ----------------------------------------------------------- + + def _run_cycle_unit(self, replica_index: int, cycle: int) -> None: + replica = self.replicas[replica_index] + if replica.status != "active" or replica.current is None: + return + self._run_cycle(replica, cycle) + replica.cycle_count = max(replica.cycle_count, cycle) + replica.cycles_completed.append(cycle) + + def _run_cycle(self, replica: ReplicaState, cycle: int) -> None: + options = self.options + regions = replica.start.regions + x0 = replica.current + assert x0 is not None + z_top = float(np.max(wrap_positions(x0)[regions.slab, 2])) + mobile = mobile_indices(x0, regions, options, z_top=z_top) + fixed_md = np.setdiff1d(np.arange(len(x0)), mobile) + + md_atoms = x0.copy() + md_atoms.set_constraint(FixAtoms(indices=fixed_md) if fixed_md.size else None) + md_atoms.calc = self.calculator + self._initialize_velocities(md_atoms, mobile, replica.md_rng) + + raw_dir = ( + self.output_dir + / "raw" + / f"replica_{replica.index:03d}" + / f"cycle_{cycle:03d}" + ) + raw_dir.mkdir(parents=True, exist_ok=True) + writer = AsyncMDOutputWriter( + trajectory_path=raw_dir / "trajectory.traj", + csv_path=raw_dir / "md.csv", + write_trajectory=True, + xdatcar_writer=None, + xdatcar_path=raw_dir / "XDATCAR", + outcar_writer=None, + ) + + dynamics = Langevin( + md_atoms, + timestep=float(options.timestep) * units.fs, + temperature_K=float(options.cs_temperature_high), + friction=float(options.friction) / units.fs, + rng=replica.md_rng, + fixcm=False, + ) + snapshots: list[Atoms] = [] + snapshot_steps = set(options.snapshot_steps) + abort_status: str | None = None + abort_message = "" + schedule: list[dict] = [] + + def observe() -> None: + nonlocal abort_status, abort_message + step = int(dynamics.nsteps) + phase = "hold" if step <= options.n_hold else "cool" + try: + energy = float(md_atoms.get_potential_energy()) + raw, applied = force_views( + md_atoms, energy, context=f"confsearch MD step {step}" + ) + kinetic, temperature, total = validate_safe_point( + md_atoms, + energy=energy, + forces_raw=raw, + forces_applied=applied, + temperature_fn=lambda atoms: float(atoms.get_temperature()), + context=f"confsearch MD step {step}", + ) + except (RuntimeError, ValueError) as exc: + abort_status = cs_status.MD_NONFINITE_ABORT + abort_message = str(exc) + raise _MDAbort(abort_status, abort_message, md_atoms.copy()) from exc + + gate = evaluate_force_abort(raw, threshold=options.fmax_abort) + frame = self._frame_summary( + step=step, + phase=phase, + energy=energy, + kinetic=kinetic, + total=total, + temperature=temperature, + volume=float(md_atoms.get_volume()), + raw=raw, + applied=applied, + gate_max=gate.max_force_raw, + ) + keep = ( + step % int(options.cs_save_interval) == 0 + or step in snapshot_steps + or step == options.total_md_steps_per_cycle + or gate.abort + ) + if keep: + writer.submit( + MDFrameSnapshot( + atoms=md_atoms.copy(), summary=frame, outcar_forces=None + ) + ) + if step in snapshot_steps: + snapshots.append(md_atoms.copy()) + self._check_md_integrity(replica, md_atoms, step) + if gate.abort: + abort_status = cs_status.MD_FORCE_ABORT + abort_message = ( + f"raw force |F|={gate.max_force_raw:.6g} eV/A on atom " + f"{gate.atom_index} exceeds fmax_abort={options.fmax_abort}" + ) + raise _MDAbort(abort_status, abort_message, md_atoms.copy()) + + dynamics.attach(observe, interval=1) + steps_done = 0 + try: + dynamics.run(int(options.n_hold)) + steps_done += int(options.n_hold) + remaining = int(options.n_cool) + while remaining > 0: + block = min(int(options.cs_ramp_interval), remaining) + target = self._cool_temperature(steps_done, options) + dynamics.set_temperature(temperature_K=target) + schedule.append( + { + "step": int(dynamics.nsteps), + "target_temperature_K": float(target), + } + ) + dynamics.run(block) + steps_done += block + remaining -= block + except _MDAbort as exc: + abort_status = exc.status + abort_message = str(exc) + if exc.frame is not None: + snapshots.append(exc.frame) + finally: + try: + writer.close() + except Exception as exc: # pragma: no cover - writer failures are fatal + raise ConfsearchInternalError( + f"Raw MD output failed for replica {replica.index} cycle {cycle}: {exc}" + ) from exc + + self.cumulative_md_ps += steps_done * float(options.timestep) / 1000.0 + + # Quench the snapshots (chronological), then the end-of-cycle frame. + end_frame = md_atoms.copy() + quench_targets: list[tuple[str, int | None, Atoms]] = [ + ("snapshot", index, snapshot) for index, snapshot in enumerate(snapshots) + ] + if abort_status is None: + quench_targets.append(("end", None, end_frame)) + + end_record: MinimumRecord | None = None + for source, snapshot_index, frame in quench_targets: + result = quench( + frame, + self.calculator, + options, + fixed_indices=regions.fixed, + ) + record = self._register( + result, + regions=regions, + reference=replica.reference, + origin=MinimumOrigin( + replica=replica.index, + cycle=cycle, + source=source, + snapshot_index=snapshot_index, + ), + md_ps=self.cumulative_md_ps, + ) + if source == "end": + end_record = record + + cycle_payload = { + "replica": replica.index, + "cycle": cycle, + "status": abort_status or "completed", + "message": abort_message, + "steps_run": int(steps_done), + "n_hold": int(options.n_hold), + "n_cool": int(options.n_cool), + "snapshot_steps": list(options.snapshot_steps), + "temperature_schedule": schedule, + "md_time_ps": steps_done * float(options.timestep) / 1000.0, + "cumulative_md_ps": self.cumulative_md_ps, + "mobile_atoms": mobile.tolist(), + } + (raw_dir / "cycle.json").write_text( + json.dumps(cycle_payload, indent=2, sort_keys=True) + "\n", + encoding="utf-8", + ) + + if abort_status is not None: + self.log( + f"replica {replica.index} cycle {cycle}: {abort_status} " + f"({abort_message}); current minimum unchanged" + ) + return + + self._metropolis(replica, end_record) + + def _cool_temperature(self, steps_done: int, options: ConfsearchOptions) -> float: + """Linear T(t) from cs_temperature_high to cs_temperature_low.""" + n_cool = max(1, options.n_cool) + fraction = min(1.0, max(0.0, (steps_done - options.n_hold) / n_cool)) + return float( + options.cs_temperature_high + + (options.cs_temperature_low - options.cs_temperature_high) * fraction + ) + + def _check_md_integrity( + self, replica: ReplicaState, atoms: Atoms, step: int + ) -> None: + reference = replica.reference + if reference is None: + return + broken = broken_reference_bonds( + atoms, + reference.adsorbate_graph, + break_scale=self.options.cs_bond_break_scale, + ionic_symbols=self.options.ionic_symbols, + ) + if broken: + raise _MDAbort( + cs_status.MD_INTEGRITY_ABORT, + f"adsorbate bond(s) {list(broken)} broke beyond " + f"{self.options.cs_bond_break_scale}x the covalent-radii sum at " + f"step {step}", + atoms.copy(), + ) + + def _initialize_velocities( + self, atoms: Atoms, mobile: np.ndarray, rng: np.random.Generator + ) -> None: + """Maxwell-Boltzmann over the mobile DOF; fixed atoms keep zero momenta.""" + MaxwellBoltzmannDistribution( + atoms, + temperature_K=float(self.options.cs_temperature_high), + force_temp=True, + rng=rng, + ) + fixed = np.setdiff1d(np.arange(len(atoms)), mobile) + momenta = np.asarray(atoms.get_momenta(), dtype=float) + if fixed.size: + momenta[fixed] = 0.0 + atoms.set_momenta(momenta) + ndof = int(atoms.get_number_of_degrees_of_freedom()) + kinetic = float(atoms.get_kinetic_energy()) + target = 0.5 * ndof * units.kB * float(self.options.cs_temperature_high) + if kinetic > 0.0: + atoms.set_momenta(momenta * math.sqrt(target / kinetic)) + + def _frame_summary( + self, + *, + step: int, + phase: str, + energy: float, + kinetic: float, + total: float, + temperature: float, + volume: float, + raw: np.ndarray, + applied: np.ndarray, + gate_max: float, + ) -> dict: + return { + "step": int(step), + "time_fs": float(step * float(self.options.timestep)), + "phase": phase, + "energy": float(energy), + "kinetic_energy": float(kinetic), + "total_energy": float(total), + "temperature": float(temperature), + "volume": float(volume), + "max_force_raw_eV_A": float(gate_max), + "max_force_applied_eV_A": float(np.max(force_magnitudes(applied))), + "configurational_stress": None, + "total_stress": None, + "configurational_pressure_gpa": None, + "total_pressure_gpa": None, + } + + # -- registration ----------------------------------------------------- + + def _register( + self, + result: QuenchResult, + *, + regions: Regions, + reference: ClassificationReference | None, + origin: MinimumOrigin, + md_ps: float, + ) -> MinimumRecord: + self.quench_index += 1 + if not result.usable: + classification = None + else: + assert reference is not None + classification = classify_minimum( + result.atoms, + regions=regions, + options=self.options, + reference=reference, + ) + if classification is None: + from mliport.confsearch.graphs import MinimumClassification # noqa: PLC0415 + + classification = MinimumClassification( + status=result.status, + flags=(), + adsorbate_slab_bonds=(), + reacted_bonds={}, + min_adsorbate_slab_distance=None, + min_self_image_distance=None, + min_vacuum_gap=None, + max_slab_displacement_ionic=None, + max_slab_displacement_nonionic=None, + ionic_coordination=(), + ) + record = MinimumRecord( + record_id=self.registry.new_record_id(), + energy_eV=float(result.energy_eV), + atoms=result.atoms, + classification=classification, + origin=origin, + quench_index=self.quench_index, + cumulative_md_ps=float(md_ps), + fmax_eV_A=float(result.fmax_eV_A), + steps=int(result.steps), + ) + self.registry.register(record) + self.discovery.append(self._discovery_row(record)) + return record + + def _metropolis( + self, replica: ReplicaState, end_record: MinimumRecord | None + ) -> None: + """Metropolis update on the end-of-cycle minimum (spec 7.3 step 11).""" + if end_record is None or replica.current_energy is None: + return + eligible = end_record.status == cs_status.VALID or ( + end_record.status == cs_status.REACTED + and self.options.cs_reaction_policy == "include" + ) + if not eligible: + return + delta = float(end_record.energy_eV) - float(replica.current_energy) + # The uniform draw happens every time an eligible proposal exists, so + # the stream stays aligned (section 7.3 step 11). + draw = float(replica.mc_rng.random()) + accept = delta <= 0.0 + if not accept: + exponent = -delta / (units.kB * float(self.options.cs_accept_temperature)) + accept = draw < math.exp(exponent) + if accept: + replica.current = end_record.atoms.copy() + replica.current_energy = float(end_record.energy_eV) + + # -- completion ------------------------------------------------------- + + def _finish(self) -> dict: + self.registry.consolidate() + references = [replica.reference for replica in self.replicas] + return build_results( + regions=self.starts[0].regions, + references=[item for item in references if item is not None], + calculator=self.calculator, + registry=self.registry, + options=self.options, + replicas=self.replicas, + discovery=self.discovery, + baseline=self.baseline, + warnings=self.warnings, + output_dir=self.output_dir, + model_record=self.model_record, + gradient_preflight=self.gradient_preflight, + cumulative_md_ps=self.cumulative_md_ps, + seed=self.seed, + starts=[start.to_dict() for start in self.starts], + ) + + +def run_confsearch( + calculator, + options: ConfsearchOptions, + *, + starts: Sequence[PreparedStart], + output_dir: str | Path, + seed: int, + model_record: dict | None = None, + gradient_preflight: dict | None = None, + resume: CheckpointData | None = None, + resume_fingerprint: dict | None = None, + log: Callable[[str], None] | None = None, +) -> dict: + """Run (or resume) one search and return its ``search_results.json`` content.""" + engine = SearchEngine( + calculator=calculator, + options=options, + starts=starts, + output_dir=output_dir, + seed=seed, + model_record=model_record, + gradient_preflight=gradient_preflight, + resume=resume, + resume_fingerprint=resume_fingerprint, + log=log, + ) + return engine.run() + + +__all__ = ["PreparedStart", "ReplicaState", "SearchEngine", "run_confsearch"] diff --git a/mliport/mliport/confsearch/graphs.py b/mliport/mliport/confsearch/graphs.py index 265b8eef..4b60930b 100644 --- a/mliport/mliport/confsearch/graphs.py +++ b/mliport/mliport/confsearch/graphs.py @@ -85,11 +85,13 @@ class MinimumClassification: flags: tuple[str, ...] adsorbate_slab_bonds: tuple[tuple[int, int, str, str, float, float], ...] reacted_bonds: dict[str, dict[str, list[list[int]]]] - min_adsorbate_slab_distance: float - min_self_image_distance: float - min_vacuum_gap: float - max_slab_displacement_ionic: float - max_slab_displacement_nonionic: float + #: ``None`` for a quench that never produced a converged geometry + #: (quench_failed / quench_not_converged): nothing was measured. + min_adsorbate_slab_distance: float | None + min_self_image_distance: float | None + min_vacuum_gap: float | None + max_slab_displacement_ionic: float | None + max_slab_displacement_nonionic: float | None ionic_coordination: tuple[tuple[int, int], ...] @property diff --git a/mliport/mliport/confsearch/quench.py b/mliport/mliport/confsearch/quench.py new file mode 100644 index 00000000..4c6a0aeb --- /dev/null +++ b/mliport/mliport/confsearch/quench.py @@ -0,0 +1,174 @@ +"""Local minimization ("quench") and top-K refinement (spec sections 7.4, 10.3). + +Every quench is a fixed-cell ASE FIRE run on the relax set ``R`` with only the +input ``FixAtoms`` constraints active. The frame's velocities are dropped. +Non-finite values, a raw-force abort or a budget overrun are outcomes, not +exceptions: they are stored as ``quench_failed`` / ``quench_not_converged`` and +are never ranked and never become chain states. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING + +import numpy as np +from ase.constraints import FixAtoms +from ase.optimize import FIRE + +from mliport.confsearch import status as cs_status +from mliport.confsearch.errors import ConfsearchInternalError +from mliport.runners.safety import ( + ForceSafetyAbort, + evaluate_force_abort, + force_views, +) + +if TYPE_CHECKING: + from ase import Atoms + + from mliport.confsearch.options import ConfsearchOptions + +#: FIRE defaults recorded with every quench (ASE's own default maxstep). +FIRE_MAXSTEP_A = 0.2 + + +@dataclass(frozen=True, slots=True) +class QuenchResult: + """Outcome of one fixed-cell quench.""" + + status: str + atoms: Atoms + energy_eV: float + fmax_eV_A: float + steps: int + maxstep_A: float = FIRE_MAXSTEP_A + + @property + def converged(self) -> bool: + return self.status == cs_status.VALID or self.status == cs_status.REACTED + + @property + def usable(self) -> bool: + return self.status not in { + cs_status.QUENCH_FAILED, + cs_status.QUENCH_NOT_CONVERGED, + } + + def to_dict(self) -> dict: + return { + "status": self.status, + "energy_eV": float(self.energy_eV), + "fmax_eV_A": float(self.fmax_eV_A), + "steps": int(self.steps), + "maxstep_A": float(self.maxstep_A), + } + + +def quench( + atoms: Atoms, + calculator, + options: ConfsearchOptions, + *, + fixed_indices: np.ndarray, + fmax: float | None = None, + steps: int | None = None, +) -> QuenchResult: + """Minimize ``atoms`` at fixed cell with FIRE on the relax set. + + ``fixed_indices`` becomes the only constraint; everything else moves. The + input frame is copied, so the caller's structure is never modified. + """ + work = atoms.copy() + work.calc = calculator + if "momenta" in work.arrays: + del work.arrays["momenta"] + fixed = np.asarray(fixed_indices, dtype=int) + work.set_constraint(FixAtoms(indices=fixed) if fixed.size else None) + + budget = int(options.cs_quench_steps if steps is None else steps) + target = float(options.cs_quench_fmax if fmax is None else fmax) + threshold = float(options.fmax_abort) + + abort: dict[str, object] = {} + + def observe() -> None: + energy = float(work.get_potential_energy()) + raw, applied = force_views(work, energy, context="confsearch quench") + gate = evaluate_force_abort(raw, threshold=threshold) + if gate.abort: + abort["reason"] = "force" + abort["max_force"] = gate.max_force_raw + abort["atom_index"] = gate.atom_index + raise ForceSafetyAbort( + step=int(optimizer.nsteps), + max_force=gate.max_force_raw, + atom_index=gate.atom_index, + threshold=threshold, + ) + del applied + + optimizer = FIRE(work, logfile=None, maxstep=FIRE_MAXSTEP_A) + optimizer.attach(observe, interval=1) + status = cs_status.QUENCH_NOT_CONVERGED + try: + optimizer.run(fmax=target, steps=budget) + except ForceSafetyAbort: + status = cs_status.QUENCH_FAILED + except (RuntimeError, ValueError, FloatingPointError): + status = cs_status.QUENCH_FAILED + else: + if optimizer.converged(): + status = cs_status.VALID + + energy = float(work.get_potential_energy()) + if not np.isfinite(energy): + status = cs_status.QUENCH_FAILED + try: + raw, _applied = force_views(work, energy, context="confsearch quench final") + except (RuntimeError, ValueError): + status = cs_status.QUENCH_FAILED + fmax_value = float("nan") + else: + magnitudes = np.linalg.norm(raw, axis=1) + free = np.setdiff1d(np.arange(len(work)), fixed) + fmax_value = float(np.max(magnitudes[free])) if free.size else 0.0 + + # A converged optimizer that left the fixed atoms moved is an internal bug. + if fixed.size and status == cs_status.VALID: + deltas = np.asarray(work.get_positions()) - np.asarray(atoms.get_positions()) + if np.any(deltas[fixed] != 0.0): + raise ConfsearchInternalError( + "A fixed atom moved during a confsearch quench" + ) + + return QuenchResult( + status=status, + atoms=work, + energy_eV=energy, + fmax_eV_A=fmax_value, + steps=int(optimizer.nsteps), + ) + + +def refine( + atoms: Atoms, + calculator, + options: ConfsearchOptions, + *, + fixed_indices: np.ndarray, +) -> QuenchResult: + """Re-quench a representative at the tighter refinement criterion.""" + if not options.cs_refine: + raise ConfsearchInternalError("refine() called with cs_refine disabled") + return quench( + atoms, + calculator, + options, + fixed_indices=fixed_indices, + fmax=options.cs_refine_fmax, + steps=options.cs_refine_steps, + ) + + +__all__ = ["FIRE_MAXSTEP_A", "QuenchResult", "quench", "refine"] diff --git a/mliport/mliport/confsearch/registry.py b/mliport/mliport/confsearch/registry.py index a00cd06a..1b8fed1b 100644 --- a/mliport/mliport/confsearch/registry.py +++ b/mliport/mliport/confsearch/registry.py @@ -25,6 +25,8 @@ from dataclasses import dataclass, field from typing import TYPE_CHECKING +import math + import numpy as np from mliport.confsearch.fingerprint import ( @@ -36,6 +38,9 @@ from mliport.confsearch.geometry import mic_vectors if TYPE_CHECKING: + from collections.abc import Mapping + from typing import Any + from ase import Atoms from mliport.confsearch.graphs import MinimumClassification @@ -145,7 +150,7 @@ def to_dict(self) -> dict: return { "id": self.unique_id, "status": self.status, - "energy_eV": float(representative.energy_eV), + "energy_eV": _json_float(representative.energy_eV), "flags": list(self.flags), "hit_count": self.hit_count, "replicas": sorted(self.replicas), @@ -153,8 +158,8 @@ def to_dict(self) -> dict: "first_found_quench_index": int(self.first_found_quench_index), "representative": { "record_id": representative.record_id, - "energy_eV": float(representative.energy_eV), - "fmax_eV_A": float(representative.fmax_eV_A), + "energy_eV": _json_float(representative.energy_eV), + "fmax_eV_A": _json_float(representative.fmax_eV_A), "steps": int(representative.steps), "origin": representative.origin.to_dict(), "numbers": [int(z) for z in representative.atoms.numbers], @@ -167,19 +172,71 @@ def to_dict(self) -> dict: "members": [ { "record_id": member.record_id, - "energy_eV": float(member.energy_eV), - "fmax_eV_A": float(member.fmax_eV_A), + "energy_eV": _json_float(member.energy_eV), + "fmax_eV_A": _json_float(member.fmax_eV_A), "steps": int(member.steps), "status": member.status, "flags": list(member.flags), "origin": member.origin.to_dict(), - "cumulative_md_ps": float(member.cumulative_md_ps), + "cumulative_md_ps": _json_float(member.cumulative_md_ps), + "quench_index": int(member.quench_index), } for member in self.members ], } +def _optional_float(value: Any) -> float | None: + return None if value is None else float(value) + + +def _json_float(value: Any) -> float | None: + """JSON has no NaN/Inf: a non-finite measurement is recorded as null.""" + if value is None: + return None + number = float(value) + return number if math.isfinite(number) else None + + +def rebuild_classification(payload: Mapping[str, Any]) -> MinimumClassification: + """Rebuild a :class:`MinimumClassification` from its serialized form.""" + from mliport.confsearch.graphs import MinimumClassification # noqa: PLC0415 + + bonds = tuple( + ( + int(item["adsorbate_index"]), + int(item["slab_index"]), + str(item["adsorbate_element"]), + str(item["slab_element"]), + float(item["distance_A"]), + float(item["q"]), + ) + for item in payload.get("adsorbate_slab_bonds", []) + ) + coordination = tuple( + (int(item["adsorbate_index"]), int(item["neighbours"])) + for item in payload.get("ionic_adsorbate_coordination", []) + ) + return MinimumClassification( + status=str(payload["status"]), + flags=tuple(payload.get("flags", [])), + adsorbate_slab_bonds=bonds, + reacted_bonds=dict(payload.get("reacted_bonds") or {}), + min_adsorbate_slab_distance=float( + payload.get("min_adsorbate_slab_distance_A", 0.0) + ), + min_self_image_distance=float(payload.get("min_self_image_distance_A", 0.0)), + min_vacuum_gap=float(payload.get("min_vacuum_gap_A", 0.0)), + max_slab_displacement_ionic=float( + payload.get("max_slab_displacement_ionic_A", 0.0) + ), + max_slab_displacement_nonionic=float( + payload.get("max_slab_displacement_nonionic_A", 0.0) + ), + ionic_coordination=coordination, + ) + + class MinimumRegistry: """Deduplicating registry of quench results, per status class.""" @@ -355,6 +412,10 @@ def to_dict(self) -> dict: return { "schema": "mliport.confsearch-registry/1", "n_records": self.total_records(), + "counters": { + "next_unique_id": self._next_unique_id, + "next_record_id": self._next_record_id, + }, "classes": { status: [ unique.to_dict() @@ -367,6 +428,79 @@ def to_dict(self) -> dict: "merges": list(self.merges), } + @classmethod + def from_dict( + cls, + payload: Mapping[str, Any], + *, + options: ConfsearchOptions, + adsorbate: np.ndarray, + fixed: np.ndarray | None = None, + ) -> MinimumRegistry: + """Rebuild a registry from a checkpoint payload (fingerprints recomputed).""" + from ase import Atoms # noqa: PLC0415 + + registry = cls( + options=options, adsorbate=np.asarray(adsorbate, dtype=int), fixed=fixed + ) + for status, entries in (payload.get("classes") or {}).items(): + for entry in entries: + representative = entry["representative"] + geometry = Atoms( + numbers=np.asarray(representative["numbers"], dtype=int), + positions=np.asarray(representative["positions_A"], dtype=float), + cell=np.asarray(representative["cell_A"], dtype=float), + pbc=np.asarray(representative["pbc"], dtype=bool), + ) + classification = rebuild_classification( + representative["classification"] + ) + unique = UniqueMinimum( + unique_id=int(entry["id"]), + status=str(entry.get("status", status)), + replicas={int(value) for value in entry.get("replicas", [])}, + first_found_md_ps=float(entry.get("first_found_md_ps", 0.0)), + first_found_quench_index=int( + entry.get("first_found_quench_index", 0) + ), + ) + for member in entry.get("members", []): + origin = member["origin"] + record = MinimumRecord( + record_id=int(member["record_id"]), + energy_eV=float(member["energy_eV"]), + atoms=geometry.copy(), + classification=classification, + origin=MinimumOrigin( + replica=int(origin["replica"]), + cycle=int(origin["cycle"]), + source=str(origin["source"]), + snapshot_index=origin.get("snapshot_index"), + ), + quench_index=int(member.get("quench_index", 0)), + cumulative_md_ps=float(member.get("cumulative_md_ps", 0.0)), + fmax_eV_A=float(member.get("fmax_eV_A", 0.0) or 0.0), + steps=int(member.get("steps", 0)), + ) + unique.add(record) + # Fingerprints are recomputed from the representative geometry + # so a resumed registry can keep matching (section 9.4). + representative_record = unique.representative + representative_record.fingerprint = registry.fingerprint( + representative_record.atoms + ) + registry._classes.setdefault(status, []).append(unique) + registry._unique_by_id[unique.unique_id] = unique + counters = payload.get("counters") or {} + registry._next_unique_id = int( + counters.get("next_unique_id", registry._next_unique_id) + ) + registry._next_record_id = int( + counters.get("next_record_id", registry._next_record_id) + ) + registry.merges = list(payload.get("merges") or []) + return registry + def displacement_between( self, first: MinimumRecord, second: MinimumRecord ) -> float: diff --git a/mliport/mliport/confsearch/results.py b/mliport/mliport/confsearch/results.py new file mode 100644 index 00000000..0e84c027 --- /dev/null +++ b/mliport/mliport/confsearch/results.py @@ -0,0 +1,648 @@ +"""Ranking, saturation diagnostics, refinement and DFT exports (spec section 10). + +Everything here is a *screening* product: the outputs say "lowest found", never +"global minimum", and every number carries the provenance needed to re-rank the +candidates with DFT (spec sections 10.2, 15). +""" + +from __future__ import annotations + +import csv +import json +import math +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any + +import numpy as np +from ase import Atoms +from ase.constraints import FixAtoms +from ase.io import write as ase_write + +from mliport.confsearch import status as cs_status +from mliport.confsearch.graphs import covalent_bonds, classify_minimum, ionic_mask +from mliport.confsearch.quench import refine +from mliport.confsearch.registry import MinimumRecord, MinimumRegistry, UniqueMinimum +from mliport.writers.contcar import ContcarWriter + +if TYPE_CHECKING: + from collections.abc import Sequence + + from mliport.confsearch.graphs import ClassificationReference + from mliport.confsearch.options import ConfsearchOptions + from mliport.confsearch.regions import Regions + +RESULTS_SCHEMA = "mliport.confsearch-results/1" +#: Saturation window for the "new low minima in the last quarter" diagnostic. +NEW_LOW_WINDOW_EV = 0.2 + + +@dataclass(frozen=True, slots=True) +class RefinementOutcome: + """Refinement result for one representative.""" + + unique_id: int + status: str + energy_eV: float + fmax_eV_A: float + steps: int + atoms: Atoms + classification: Any + converged: bool + + def to_dict(self) -> dict: + return { + "status": self.status, + "energy_eV": float(self.energy_eV), + "fmax_eV_A": float(self.fmax_eV_A), + "steps": int(self.steps), + "converged": bool(self.converged), + "classification": self.classification.to_dict(), + } + + +def _index_ranges(indices: Sequence[int]) -> str: + """Compress 1-based indices into CP2K ``a..b`` ranges.""" + ordered = sorted(set(int(index) for index in indices)) + if not ordered: + return "" + parts: list[str] = [] + start = previous = ordered[0] + for index in ordered[1:]: + if index == previous + 1: + previous = index + continue + parts.append(str(start) if start == previous else f"{start}..{previous}") + start = previous = index + parts.append(str(start) if start == previous else f"{start}..{previous}") + return " ".join(parts) + + +def make_whole_adsorbate( + atoms: Atoms, regions: Regions, options: ConfsearchOptions +) -> Atoms: + """Wrap the slab and make the adsorbate whole (spec section 10.5). + + Slab atoms are wrapped into the cell. The non-ionic adsorbate is rebuilt by + a breadth-first walk over the covalent graph under MIC, each new atom placed + at the image closest to its parent; ionic adsorbate atoms are then placed at + the image closest to their nearest non-ionic adsorbate atom. + """ + work = atoms.copy() + work.wrap() + cell = np.asarray(work.cell, dtype=float) + inverse = np.linalg.inv(cell) + positions = np.asarray(work.get_positions(), dtype=float) + adsorbate = np.asarray(regions.adsorbate, dtype=int) + ionic = ionic_mask(work, options) + non_ionic = [int(index) for index in adsorbate if not ionic[index]] + + if non_ionic: + graph = covalent_bonds( + work, + np.asarray(non_ionic, dtype=int), + bond_scale=options.cs_bond_scale, + ionic_symbols=options.ionic_symbols, + ) + adjacency: dict[int, set[int]] = {index: set() for index in non_ionic} + for first, second in graph.bonds: + adjacency[int(first)].add(int(second)) + adjacency[int(second)].add(int(first)) + start = non_ionic[0] + visited = {start} + queue = [start] + while queue: + current = queue.pop(0) + for neighbour in sorted(adjacency[current]): + if neighbour in visited: + continue + delta = positions[neighbour] - positions[current] + fractional = delta @ inverse + fractional -= np.round(fractional) + positions[neighbour] = positions[current] + fractional @ cell + visited.add(neighbour) + queue.append(neighbour) + reference = np.asarray(non_ionic, dtype=int) + else: + reference = adsorbate + + for index in adsorbate: + if not ionic[index]: + continue + deltas = positions[reference] - positions[index] + fractional = deltas @ inverse + fractional -= np.round(fractional) + candidates = positions[index] + fractional @ cell + nearest = int(np.argmin(np.linalg.norm(candidates - positions[index], axis=1))) + positions[index] = candidates[nearest] + work.positions = positions + return work + + +def _ranking_entry( + unique: UniqueMinimum, + *, + best_energy: float, + n_atoms: int, + refinement: RefinementOutcome | None, + total_quenches: int, +) -> dict: + representative = unique.representative + energy = refinement.energy_eV if refinement is not None else unique.energy_eV + first_found_fraction = ( + representative.quench_index / total_quenches if total_quenches else 0.0 + ) + return { + "id": unique.unique_id, + "status": unique.status, + "energy_eV": float(energy), + "delta_energy_eV": float(energy - best_energy), + "delta_energy_per_atom_eV": float((energy - best_energy) / max(1, n_atoms)), + "hit_count": unique.hit_count, + "replicas": sorted(unique.replicas), + "n_replicas": len(unique.replicas), + "first_found_md_ps": float(unique.first_found_md_ps), + "first_found_fraction": float(first_found_fraction), + "flags": list(unique.flags), + "chemisorbed": representative.classification.chemisorbed, + "refined": refinement is not None, + "refinement_status": None if refinement is None else refinement.status, + "quench_energy_eV": float(unique.energy_eV), + "fmax_eV_A": float( + refinement.fmax_eV_A if refinement is not None else representative.fmax_eV_A + ), + "classification": representative.classification.to_dict(), + "origin": representative.origin.to_dict(), + } + + +def _export_candidate( + directory: Path, + *, + unique: UniqueMinimum, + atoms: Atoms, + options: ConfsearchOptions, + regions: Regions, + entry: dict, + energy: float, +) -> dict: + """Write the DFT-facing files for one exported rank (spec section 10.5).""" + directory.mkdir(parents=True, exist_ok=True) + whole = make_whole_adsorbate(atoms, regions, options) + + constrained = whole.copy() + fixed = np.asarray(regions.fixed, dtype=int) + constrained.set_constraint(FixAtoms(indices=fixed) if fixed.size else None) + ContcarWriter().write( + constrained, + directory / "POSCAR", + comment=f"confsearch rank {unique.unique_id} E={energy:.6f} eV", + direct=True, + ) + + export_atoms = whole.copy() + export_atoms.info["confsearch_id"] = int(unique.unique_id) + export_atoms.info["confsearch_status"] = unique.status + export_atoms.info["energy_eV"] = float(energy) + export_atoms.info["flags"] = list(unique.flags) + ase_write(directory / "structure.extxyz", export_atoms, format="extxyz") + ase_write(directory / "cp2k_coord.xyz", export_atoms, format="xyz") + + cell = np.asarray(whole.cell, dtype=float) + (directory / "cp2k_cell.inc").write_text( + "".join( + f"{name} {vector[0]:.12f} {vector[1]:.12f} {vector[2]:.12f}\n" + for name, vector in zip("ABC", cell, strict=True) + ), + encoding="utf-8", + ) + (directory / "cp2k_fixed_atoms.inc").write_text( + "# CP2K &MOTION/&CONSTRAINT/&FIXED_ATOMS list, 1-based indices\n" + f"LIST {_index_ranges([int(index) + 1 for index in fixed])}\n".lstrip() + if fixed.size + else "# CP2K &MOTION/&CONSTRAINT/&FIXED_ATOMS list: no fixed atoms\n", + encoding="utf-8", + ) + + payload = unique.to_dict() + payload["export"] = { + "rank_energy_eV": float(energy), + "ranking": entry, + "coordinate_convention": ( + "slab wrapped into the cell; adsorbate made whole under MIC" + ), + } + (directory / "minimum.json").write_text( + json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8" + ) + files = [ + "POSCAR", + "structure.extxyz", + "cp2k_coord.xyz", + "cp2k_cell.inc", + "cp2k_fixed_atoms.inc", + "minimum.json", + ] + return { + "rank": unique.unique_id, + "path": directory.name, + "energy_eV": float(energy), + "files": files, + } + + +def _saturation( + registry: MinimumRegistry, + *, + rankable: list[tuple[UniqueMinimum, float]], + total_quenches: int, +) -> dict: + if not rankable: + return { + "best_hit_count": 0, + "best_replicas": [], + "best_first_found_fraction": None, + "best_repeatedly_found": False, + "new_low_minima_last_quarter": 0, + "lowest_found_language": "lowest found (no global-minimum claim)", + } + best = rankable[0][0] + representative = best.representative + fraction = representative.quench_index / total_quenches if total_quenches else 0.0 + cutoff = int(math.ceil(0.75 * total_quenches)) + recent = 0 + for unique, energy in rankable: + if energy - rankable[0][1] > NEW_LOW_WINDOW_EV: + continue + if unique.first_found_quench_index > cutoff: + recent += 1 + return { + "best_id": best.unique_id, + "best_energy_eV": float(rankable[0][1]), + "best_hit_count": best.hit_count, + "best_replicas": sorted(best.replicas), + "best_first_found_md_ps": float(best.first_found_md_ps), + "best_first_found_fraction": float(fraction), + "best_repeatedly_found": bool(best.hit_count >= 3 and len(best.replicas) >= 2), + "new_low_minima_last_quarter": int(recent), + "lowest_found_language": "lowest found (no global-minimum claim)", + } + + +def _status_warnings( + registry: MinimumRegistry, options: ConfsearchOptions, ranked: list[dict] +) -> list[str]: + warnings: list[str] = [] + all_records = registry.total_records() + if not all_records: + return warnings + classes = registry.status_classes() + reacted = sum(unique.hit_count for unique in classes.get(cs_status.REACTED, [])) + if reacted / all_records > 0.10: + warnings.append( + f"{100 * reacted / all_records:.1f}% of quenches are reacted; the " + "temperature may be too high or the model unreliable for this chemistry" + ) + unusable = sum( + unique.hit_count + for status in (cs_status.DESORBED, cs_status.IMAGE_CONTACT) + for unique in classes.get(status, []) + ) + if unusable / all_records > 0.10: + warnings.append( + f"{100 * unusable / all_records:.1f}% of quenches are desorbed or in " + "image contact; check the cell vacuum and the placement scales" + ) + not_converged = sum( + unique.hit_count for unique in classes.get(cs_status.QUENCH_NOT_CONVERGED, []) + ) + if not_converged / all_records > 0.05: + warnings.append( + f"{100 * not_converged / all_records:.1f}% of quenches did not converge " + "within cs_quench_steps" + ) + for entry in ranked: + if "far_field_slab_changed" in entry["flags"]: + warnings.append( + f"top-{options.cs_top_k} minimum {entry['id']} has " + "far_field_slab_changed: its energy difference may reflect slab " + "changes rather than adsorption" + ) + return warnings + + +def build_results( + *, + registry: MinimumRegistry, + options: ConfsearchOptions, + replicas: Sequence[Any], + discovery: list[dict], + baseline: dict, + warnings: list[str], + output_dir: Path, + model_record: dict, + gradient_preflight: dict, + cumulative_md_ps: float, + seed: int, + starts: list[dict], + regions: Regions | None = None, + references: Sequence[ClassificationReference] | None = None, + calculator=None, +) -> dict: + """Write every result artifact and return the ``search_results.json`` body.""" + output_dir = Path(output_dir) + (output_dir / "diagnostics").mkdir(parents=True, exist_ok=True) + _write_discovery_csv(output_dir / "diagnostics" / "discovery.csv", discovery) + + rankable_statuses = cs_status.rankable_statuses(options.cs_reaction_policy) + rankable = sorted( + ( + (unique, unique.energy_eV) + for status in rankable_statuses + for unique in registry.uniques(status) + ), + key=lambda item: (item[1], item[0].unique_id), + ) + + refinements: dict[int, RefinementOutcome] = {} + if ( + options.cs_refine + and rankable + and calculator is not None + and regions is not None + ): + refinements = _refine_top_k( + rankable, + options=options, + regions=regions, + references=references or [], + replicas=replicas, + calculator=calculator, + ) + + ranked_energies = { + unique.unique_id: ( + refinements[unique.unique_id].energy_eV + if unique.unique_id in refinements + else energy + ) + for unique, energy in rankable + } + best_energy = min(ranked_energies.values()) if ranked_energies else 0.0 + total_quenches = registry.total_records() + n_atoms = len(rankable[0][0].representative.atoms) if rankable else 0 + entries = [ + _ranking_entry( + unique, + best_energy=best_energy, + n_atoms=n_atoms, + refinement=refinements.get(unique.unique_id), + total_quenches=total_quenches, + ) + for unique, _energy in rankable + ] + refined_entries = [entry for entry in entries if entry["refined"]] + unrefined_entries = [entry for entry in entries if not entry["refined"]] + + baseline_report = _baseline_report(baseline, entries, options) + + exports: list[dict] = [] + if regions is not None: + window = [ + (unique, ranked_energies[unique.unique_id]) + for unique, _energy in rankable + if ranked_energies[unique.unique_id] - best_energy + <= options.cs_export_window + ][: int(options.cs_top_k)] + for position, (unique, energy) in enumerate(window, start=1): + atoms = ( + refinements[unique.unique_id].atoms + if unique.unique_id in refinements + else unique.representative.atoms + ) + exports.append( + _export_candidate( + output_dir / "top" / f"rank_{position:03d}", + unique=unique, + atoms=atoms, + options=options, + regions=regions, + entry=entries[ + next( + index + for index, item in enumerate(entries) + if item["id"] == unique.unique_id + ) + ], + energy=energy, + ) + ) + + saturation = _saturation( + registry, + rankable=[ + (unique, ranked_energies[unique.unique_id]) for unique, _ in rankable + ], + total_quenches=total_quenches, + ) + warnings = list(warnings) + _status_warnings(registry, options, entries) + warnings = list(dict.fromkeys(warnings)) + + status = "completed" + if not any(getattr(replica, "status", None) == "active" for replica in replicas): + status = "failed" + + results = { + "schema": RESULTS_SCHEMA, + "status": status, + "scientific_revision": _scientific_revision(), + "seed": int(seed), + "settings": { + "cs_mode": options.cs_mode, + "cs_reaction_policy": options.cs_reaction_policy, + "cs_refine": bool(options.cs_refine), + "cs_dedup_energy_tol": float(options.cs_dedup_energy_tol), + "cs_dedup_geom_tol": float(options.cs_dedup_geom_tol), + "cs_dedup_fp_tol": float(options.cs_dedup_fp_tol), + "cs_fp_sigma": float(options.cs_fp_sigma), + }, + "ranking": { + "best_energy_eV": float(best_energy) if rankable else None, + "n_rankable": len(entries), + "refined": refined_entries, + "unrefined": unrefined_entries, + }, + "diagnostics": { + "discovery_curve": "diagnostics/discovery.csv", + "n_quenches": total_quenches, + "cumulative_md_ps": float(cumulative_md_ps), + "saturation": saturation, + "registry": registry.to_dict(), + }, + "baseline": baseline_report, + "exports": exports, + "warnings": warnings, + "starts": starts, + "model": model_record, + "gradient_preflight": gradient_preflight, + "refinement": { + "enabled": bool(options.cs_refine), + "fmax_eV_A": float(options.cs_refine_fmax), + "steps": int(options.cs_refine_steps), + "n_refined": len(refinements), + }, + } + (output_dir / "search_results.json").write_text( + json.dumps(results, indent=2, sort_keys=True, default=_json_default) + "\n", + encoding="utf-8", + ) + _write_artifacts(output_dir, results) + return results + + +def _scientific_revision() -> int: + from mliport.confsearch.revisions import CS_SCIENTIFIC_REVISION # noqa: PLC0415 + + return CS_SCIENTIFIC_REVISION + + +def _json_default(value: Any) -> Any: + if isinstance(value, np.ndarray): + return value.tolist() + if isinstance(value, (np.floating, np.integer)): + return value.item() + return str(value) + + +def _write_discovery_csv(path: Path, rows: list[dict]) -> None: + fieldnames = [ + "cumulative_md_ps", + "quench_index", + "unique_valid", + "unique_valid_within_0p2eV", + "current_best_eV", + "energy_eV", + "status", + ] + with path.open("w", newline="", encoding="utf-8") as handle: + writer = csv.DictWriter(handle, fieldnames=fieldnames) + writer.writeheader() + for row in rows: + writer.writerow({name: row.get(name, "") for name in fieldnames}) + + +def _refine_top_k( + rankable: list[tuple[UniqueMinimum, float]], + *, + options: ConfsearchOptions, + regions: Regions, + references: Sequence[ClassificationReference], + replicas: Sequence[Any], + calculator, +) -> dict[int, RefinementOutcome]: + best = rankable[0][1] + window = [ + (unique, energy) + for unique, energy in rankable + if energy - best <= options.cs_export_window + ][: int(options.cs_top_k)] + outcomes: dict[int, RefinementOutcome] = {} + for unique, _energy in window: + representative = unique.representative + result = refine( + representative.atoms, + calculator, + options, + fixed_indices=regions.fixed, + ) + reference = _reference_for_record(representative, references, replicas) + classification = classify_minimum( + result.atoms, regions=regions, options=options, reference=reference + ) + outcomes[unique.unique_id] = RefinementOutcome( + unique_id=unique.unique_id, + status=classification.status if result.usable else result.status, + energy_eV=float(result.energy_eV), + fmax_eV_A=float(result.fmax_eV_A), + steps=int(result.steps), + atoms=result.atoms, + classification=classification, + converged=bool(result.converged), + ) + return outcomes + + +def _reference_for_record( + record: MinimumRecord, + references: Sequence[ClassificationReference], + replicas: Sequence[Any], +) -> ClassificationReference: + """Pick the reference of the replica the record came from.""" + if references and len(references) == len(replicas): + index = int(record.origin.replica) + if 0 <= index < len(references): + return references[index] + if references: + return references[0] + raise ValueError("No classification reference available for refinement") + + +def _baseline_report( + baseline: dict, entries: list[dict], options: ConfsearchOptions +) -> dict: + best_baseline = baseline.get("best_energy_eV") + report = dict(baseline) + if best_baseline is None or not entries: + report["best_energy_eV"] = best_baseline + report["top_k_never_reached_by_start_quench"] = None + return report + top_k = entries[: int(options.cs_top_k)] + never = [ + entry["id"] + for entry in top_k + if entry["origin"]["source"] != "start" + and entry["energy_eV"] < best_baseline - 1e-12 + ] + report["top_k_never_reached_by_start_quench"] = never + return report + + +def _write_artifacts(output_dir: Path, results: dict) -> None: + manifest: dict[str, dict] = {} + for path in sorted(output_dir.rglob("*")): + if not path.is_file() or path.name == "artifacts.json": + continue + relative = path.relative_to(output_dir).as_posix() + manifest[relative] = { + "bytes": path.stat().st_size, + "format": _format_for(path), + "units": "eV, Angstrom, fs, K", + } + payload = { + "schema": "mliport.confsearch-artifacts/1", + "status": results["status"], + "files": manifest, + } + (output_dir / "artifacts.json").write_text( + json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8" + ) + + +def _format_for(path: Path) -> str: + return { + ".json": "json", + ".csv": "csv", + ".extxyz": "extxyz", + ".xyz": "xyz", + ".traj": "ase-traj", + ".inc": "cp2k-include", + ".log": "text", + }.get(path.suffix, "text") + + +__all__ = [ + "RESULTS_SCHEMA", + "RefinementOutcome", + "build_results", + "make_whole_adsorbate", +] diff --git a/tests/mliport/mliport/confsearch/calculators.py b/tests/mliport/mliport/confsearch/calculators.py new file mode 100644 index 00000000..e84aed0a --- /dev/null +++ b/tests/mliport/mliport/confsearch/calculators.py @@ -0,0 +1,242 @@ +"""Test-only synthetic calculators (spec section 13.1). + +No backend imports: every potential here is analytic, CPU-only and +deterministic, so the whole search engine is testable in CI. + +* :class:`EggCrateCalculator` -- a rigid periodic slab plus a 3-atom bonded + molecule whose anchor atom feels a piecewise-harmonic site term. The minima + sit exactly at known sites with exactly known energies. +* :class:`MorseBreakCalculator` -- the same slab/site term with a shallow Morse + bond so that hot MD breaks the molecule reproducibly. +* :class:`DirectForceCalculator` -- advertises ``direct_forces=True``. +* :class:`NonFiniteCalculator` -- returns NaN for the energy. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, ClassVar + +import numpy as np +from ase.calculators.calculator import Calculator, all_changes + +if TYPE_CHECKING: + from collections.abc import Sequence + +#: Anchor-atom index inside the adsorbate block. +ANCHOR_LOCAL_INDEX = 0 + + +def _mic(delta: np.ndarray, cell: np.ndarray) -> np.ndarray: + fractional = np.asarray(delta, dtype=float) @ np.linalg.inv(cell) + fractional -= np.round(fractional) + return fractional @ cell + + +class EggCrateCalculator(Calculator): + """Rigid slab + 3-atom molecule with a piecewise-harmonic site term. + + Sites (fractional, in units of the in-plane cell) and their exact minimum + energies (eV): + + ``hollow`` (1/2, 1/2) -> -0.60, ``bridge`` (1/2, 0) -> -0.35, + ``top`` (0, 0) -> -0.20. + + The internal terms vanish at their minimum geometry (bonds ``bond_A``, + angle ``angle_deg``), so a relaxed molecule sitting on a site has exactly + the site energy. + """ + + implemented_properties: ClassVar[list[str]] = ["energy", "forces"] + + def __init__( + self, + *, + sites: Sequence[tuple[float, float, float]] | None = None, + bond_A: float = 1.5, + angle_deg: float = 109.47, + bond_k: float = 20.0, + angle_k: float = 5.0, + site_k: float = 4.0, + n_slab: int = 4, + spacing_A: float = 3.0, + ) -> None: + super().__init__() + self.sites = list( + sites + if sites is not None + else [ + (0.5, 0.5, -0.60), # hollow + (0.5, 0.0, -0.35), # bridge + (0.0, 0.0, -0.20), # top + ] + ) + self.bond_A = float(bond_A) + self.angle = np.deg2rad(angle_deg) + self.bond_k = float(bond_k) + self.angle_k = float(angle_k) + self.site_k = float(site_k) + self.n_slab = int(n_slab) + self.spacing_A = float(spacing_A) + + # -- helpers --------------------------------------------------------- + @property + def cell(self) -> np.ndarray: + return np.diag( + [self.n_slab * self.spacing_A, self.n_slab * self.spacing_A, 20.0] + ) + + def _site_energy_forces(self, position: np.ndarray) -> tuple[float, np.ndarray]: + """Nearest-site piecewise harmonic term (exact minima at the sites).""" + cell = self.cell + in_plane = cell[:2, :2] + best: tuple[float, np.ndarray] | None = None + for u, v, depth in self.sites: + target = np.array([u * cell[0, 0], v * cell[1, 1], position[2]]) + delta = _mic(position - target, cell) + delta[2] = 0.0 + value = float(depth) + 0.5 * self.site_k * float(np.dot(delta, delta)) + if best is None or value < best[0]: + best = (value, delta) + assert best is not None + return best[0], -self.site_k * best[1] + + def _internal(self, positions: np.ndarray) -> tuple[float, np.ndarray]: + """Harmonic bonds 0-1, 1-2 and a harmonic angle 0-1-2.""" + energy = 0.0 + forces = np.zeros_like(positions) + for first, second in ((0, 1), (1, 2)): + delta = positions[second] - positions[first] + distance = float(np.linalg.norm(delta)) + stretch = distance - self.bond_A + energy += 0.5 * self.bond_k * stretch**2 + # Force ON the second atom; the first feels the opposite one. + force_on_second = -self.bond_k * stretch * delta / distance + forces[second] += force_on_second + forces[first] -= force_on_second + first, middle, last = positions[0], positions[1], positions[2] + left = first - middle + right = last - middle + cos_theta = float( + np.dot(left, right) / (np.linalg.norm(left) * np.linalg.norm(right)) + ) + cos_theta = float(np.clip(cos_theta, -1.0, 1.0)) + theta = float(np.arccos(cos_theta)) + energy += 0.5 * self.angle_k * (theta - self.angle) ** 2 + # d(theta)/dr for a three-body angle; standard chain-rule form. + sin_theta = float(np.sin(theta)) or 1e-12 + gradient_first = ( + cos_theta * left / np.dot(left, left) + - right / (np.linalg.norm(left) * np.linalg.norm(right)) + ) / sin_theta + gradient_last = ( + cos_theta * right / np.dot(right, right) + - left / (np.linalg.norm(left) * np.linalg.norm(right)) + ) / sin_theta + dtheta = self.angle_k * (theta - self.angle) + forces[0] -= dtheta * gradient_first + forces[2] -= dtheta * gradient_last + forces[1] -= -dtheta * (gradient_first + gradient_last) + return energy, forces + + def calculate( + self, + atoms=None, + properties=("energy", "forces"), + system_changes=all_changes, + ) -> None: + super().calculate(atoms, properties, system_changes) + positions = np.asarray(atoms.get_positions(), dtype=float) + n_slab = len(atoms) - 3 + energy = 0.0 + forces = np.zeros_like(positions) + molecule = positions[n_slab:] + site_energy, site_force = self._site_energy_forces(molecule[ANCHOR_LOCAL_INDEX]) + energy += site_energy + forces[n_slab + ANCHOR_LOCAL_INDEX] += site_force + internal_energy, internal_forces = self._internal(molecule) + energy += internal_energy + forces[n_slab:] += internal_forces + self.results = {"energy": float(energy), "forces": forces} + + +class MorseBreakCalculator(EggCrateCalculator): + """Egg-crate model whose first bond is a shallow Morse potential. + + ``D_e`` is small enough that a 1000 K Langevin segment breaks the bond + reproducibly with a fixed seed. + """ + + def __init__(self, *, D_e: float = 0.04, alpha: float = 1.0, **kwargs) -> None: + kwargs.setdefault("bond_k", 20.0) + super().__init__(**kwargs) + self.D_e = float(D_e) + self.alpha = float(alpha) + + def _internal(self, positions: np.ndarray) -> tuple[float, np.ndarray]: + energy, forces = super()._internal(positions) + # Replace the harmonic 0-1 bond by a Morse bond (subtract the harmonic + # term, add the Morse term). + delta = positions[1] - positions[0] + distance = float(np.linalg.norm(delta)) + stretch = distance - self.bond_A + # Remove the harmonic 0-1 term (energy and both forces). + energy -= 0.5 * self.bond_k * stretch**2 + harmonic_on_second = -self.bond_k * stretch * delta / distance + forces[1] -= harmonic_on_second + forces[0] += harmonic_on_second + # Add the Morse term. + exponential = np.exp(-self.alpha * stretch) + morse = self.D_e * (1.0 - exponential) ** 2 + d_morse = 2.0 * self.D_e * self.alpha * exponential * (1.0 - exponential) + energy += morse + morse_on_second = -d_morse * delta / distance + forces[1] += morse_on_second + forces[0] -= morse_on_second + return energy, forces + + +class DirectForceCalculator(EggCrateCalculator): + """Advertises ``direct_forces`` so the identity gate can be tested.""" + + def info(self) -> dict: + info = dict(super().info()) + info["direct_forces"] = True + return info + + +class NonFiniteCalculator(EggCrateCalculator): + """Well-behaved for ``fail_after`` evaluations, then NaN energy/forces. + + The start quench must succeed, so the NaN has to appear during the MD + segment; the counter makes that deterministic. + """ + + def __init__(self, *, fail_after: int = 8, **kwargs) -> None: + super().__init__(**kwargs) + self.fail_after = int(fail_after) + self.calls = 0 + + def calculate( + self, + atoms=None, + properties=("energy", "forces"), + system_changes=all_changes, + ) -> None: + self.calls += 1 + if self.calls <= self.fail_after: + super().calculate(atoms, properties, system_changes) + return + super().calculate(atoms, properties, system_changes) + self.results = { + "energy": float("nan"), + "forces": np.full_like(atoms.positions, float("nan")), + } + + +__all__ = [ + "ANCHOR_LOCAL_INDEX", + "DirectForceCalculator", + "EggCrateCalculator", + "MorseBreakCalculator", + "NonFiniteCalculator", +] diff --git a/tests/mliport/mliport/confsearch/test_engine.py b/tests/mliport/mliport/confsearch/test_engine.py new file mode 100644 index 00000000..836f630b --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_engine.py @@ -0,0 +1,445 @@ +"""End-to-end search-engine tests on the synthetic egg-crate model (spec 13.2). + +The model has three known sites with exactly known energies: + +* hollow (1/2, 1/2) -> -0.60 eV +* bridge (1/2, 0) -> -0.35 eV +* top (0, 0) -> -0.20 eV + +The internal terms vanish at their minimum geometry, so a relaxed molecule on a +site has exactly the site energy. The slab is fixed, which enables the +geometric identity rule G of spec section 9.3 revision 4. +""" + +from __future__ import annotations + +import json +from dataclasses import replace + +import numpy as np +import pytest +from ase import Atoms +from ase.constraints import FixAtoms +from ase.io import read + +from mliport.confsearch.checkpoint import ConfsearchCheckpointStore +from mliport.confsearch.engine import PreparedStart, run_confsearch +from mliport.confsearch.options import ConfsearchOptions +from mliport.confsearch.regions import resolve_regions, validate_all +from tests.mliport.mliport.confsearch.calculators import ( + EggCrateCalculator, + MorseBreakCalculator, + NonFiniteCalculator, +) + +SLAB_ATOMS = 16 +MOLECULE_ATOMS = 3 +SITE_ENERGIES = {(0.5, 0.5): -0.60, (0.5, 0.0): -0.35, (0.0, 0.0): -0.20} + + +def _molecule(angle_deg: float = 109.47) -> Atoms: + angle = np.deg2rad(angle_deg) + return Atoms( + "CSO", + positions=[ + [0.0, 0.0, 0.0], + [1.5, 0.0, 0.0], + [1.5 - 1.5 * np.cos(angle), 1.5 * np.sin(angle), 0.0], + ], + pbc=False, + ) + + +def _slab() -> Atoms: + spacing = 3.0 + return Atoms( + "S" * SLAB_ATOMS, + positions=[ + [0.5 + spacing * i, 0.5 + spacing * j, 1.0] + for i in range(4) + for j in range(4) + ], + cell=[12.0, 12.0, 20.0], + pbc=True, + ) + + +def _start(site: tuple[float, float], *, fixed: bool = True) -> Atoms: + slab = _slab() + molecule = _molecule() + shift = np.array([site[0] * 12.0, site[1] * 12.0, 2.0]) + atoms = Atoms( + numbers=np.concatenate([slab.numbers, molecule.numbers]), + positions=np.concatenate( + [slab.get_positions(), molecule.get_positions() + shift] + ), + cell=slab.cell, + pbc=slab.pbc, + ) + if fixed: + atoms.set_constraint(FixAtoms(indices=list(range(SLAB_ATOMS)))) + return atoms + + +def _options(**overrides) -> ConfsearchOptions: + base = { + "cs_starts": ("starts.xyz",), + "cs_adsorbate_indices": "16-18", + "cs_cycles": 2, + "cs_hold_ps": 0.05, + "cs_cool_ps": 0.05, + "cs_snapshot_interval_ps": 0.02, + "timestep": 0.5, + "cs_temperature_high": 800.0, + "cs_temperature_low": 300.0, + "cs_quench_fmax": 0.01, + "cs_quench_steps": 2000, + "cs_refine": True, + "cs_refine_fmax": 0.005, + "cs_refine_steps": 2000, + } + base.update(overrides) + return ConfsearchOptions(**base) + + +def _prepared(sites, *, fixed: bool = True, options=None): + options = options or _options() + starts = [] + for index, site in enumerate(sites): + atoms = _start(site, fixed=fixed) + regions = resolve_regions( + atoms, options, adsorbate_indices=np.arange(SLAB_ATOMS, len(atoms)) + ) + surface = validate_all(atoms, regions, options) + starts.append( + PreparedStart( + index=index, + atoms=atoms, + regions=regions, + surface=surface, + label=f"start_{index:03d}", + ) + ) + return starts + + +def _run(tmp_path, sites, *, seed=7, calculator=None, options=None, name="run"): + options = options or _options() + starts = _prepared(sites, options=options) + output = tmp_path / name + results = run_confsearch( + calculator or EggCrateCalculator(), + options, + starts=starts, + output_dir=output, + seed=seed, + model_record={"model_type": "synthetic", "task": "bulk"}, + gradient_preflight={"status": "passed"}, + ) + return output, results + + +# --------------------------------------------------------------------------- +# end to end +# --------------------------------------------------------------------------- + + +def test_search_finds_every_known_minimum_with_its_exact_energy(tmp_path): + sites = list(SITE_ENERGIES) + output, results = _run(tmp_path, sites) + assert results["status"] == "completed" + entries = results["ranking"]["refined"] + results["ranking"]["unrefined"] + energies = sorted(entry["energy_eV"] for entry in entries) + for expected in sorted(SITE_ENERGIES.values()): + assert any(abs(energy - expected) < 1e-6 for energy in energies), ( + expected, + energies, + ) + # Every known minimum was reached, and the baseline (start quench only) + # already reports the deepest one. + assert results["baseline"]["best_energy_eV"] == pytest.approx(-0.60, abs=1e-6) + assert results["diagnostics"]["n_quenches"] >= len(sites) + assert (output / "search_results.json").is_file() + payload = json.loads((output / "search_results.json").read_text()) + assert payload["schema"] == "mliport.confsearch-results/1" + + +def test_same_basin_quenches_merge_through_the_geometry_rule(tmp_path): + # Three replicas start at the same site: every quench must merge into one + # unique minimum with hit_count >= 3 (G is enabled by the fixed slab). + sites = [(0.5, 0.5)] * 3 + _output, results = _run(tmp_path, sites) + entries = results["ranking"]["refined"] + results["ranking"]["unrefined"] + deepest = [entry for entry in entries if abs(entry["energy_eV"] + 0.60) < 1e-6] + assert deepest + assert max(entry["hit_count"] for entry in deepest) >= 3 + assert max(entry["n_replicas"] for entry in deepest) >= 2 + + +def test_fixed_atoms_never_move_and_slab_is_reported(tmp_path): + output, results = _run(tmp_path, [(0.5, 0.5)], name="fixed") + assert results["starts"][0]["regions"]["fixed"] == list(range(SLAB_ATOMS)) + registry = results["diagnostics"]["registry"] + representative = registry["classes"]["valid"][0]["representative"] + reference = read(output / "top" / "rank_001" / "structure.extxyz") + slab_positions = np.asarray(reference.get_positions())[:SLAB_ATOMS] + assert np.allclose(slab_positions[:, 2], 1.0) + assert len(representative["positions_A"]) == SLAB_ATOMS + MOLECULE_ATOMS + + +def test_exports_re_read_equal_to_the_minimum_up_to_lattice_translations(tmp_path): + output, results = _run(tmp_path, [(0.5, 0.5)], name="exports") + assert results["exports"] + export_dir = output / "top" / "rank_001" + for name in ( + "POSCAR", + "structure.extxyz", + "cp2k_coord.xyz", + "cp2k_cell.inc", + "cp2k_fixed_atoms.inc", + "minimum.json", + ): + assert (export_dir / name).is_file(), name + + payload = json.loads((export_dir / "minimum.json").read_text()) + representative = payload["representative"] + reference = Atoms( + numbers=np.asarray(representative["numbers"], dtype=int), + positions=np.asarray(representative["positions_A"], dtype=float), + cell=np.asarray(representative["cell_A"], dtype=float), + pbc=np.asarray(representative["pbc"], dtype=bool), + ) + exported = read(export_dir / "structure.extxyz") + cell = np.asarray(exported.cell, dtype=float) + fractional = ( + np.asarray(exported.get_positions(), dtype=float) + - np.asarray(reference.get_positions(), dtype=float) + ) @ np.linalg.inv(cell) + residual = fractional - np.round(fractional) + assert np.all(np.abs(residual) < 1e-8), np.abs(residual).max() + assert exported.get_pbc().all() + + fixed_inc = (export_dir / "cp2k_fixed_atoms.inc").read_text() + assert fixed_inc.startswith("# CP2K") + assert "LIST 1..16" in fixed_inc + cell_inc = (export_dir / "cp2k_cell.inc").read_text().splitlines() + assert len(cell_inc) == 3 + assert all(line.startswith(("A ", "B ", "C ")) for line in cell_inc) + + poscar = (export_dir / "POSCAR").read_text() + assert "Selective dynamics" in poscar + flag_lines = [ + line.split()[-3:] for line in poscar.splitlines() if len(line.split()) >= 6 + ] + assert sum(1 for flags in flag_lines if flags == ["F", "F", "F"]) >= SLAB_ATOMS + + +def test_search_is_bitwise_reproducible_for_the_same_seed(tmp_path): + sites = list(SITE_ENERGIES) + first_dir, first = _run(tmp_path, sites, seed=11, name="first") + second_dir, second = _run(tmp_path, sites, seed=11, name="second") + assert first["ranking"] == second["ranking"] + assert first["diagnostics"]["n_quenches"] == second["diagnostics"]["n_quenches"] + raw_first = sorted( + (path.relative_to(first_dir).as_posix(), path.read_bytes()) + for path in first_dir.rglob("*") + if path.is_file() and "checkpoints" not in path.parts + ) + raw_second = sorted( + (path.relative_to(second_dir).as_posix(), path.read_bytes()) + for path in second_dir.rglob("*") + if path.is_file() and "checkpoints" not in path.parts + ) + assert [name for name, _ in raw_first] == [name for name, _ in raw_second] + + +def test_temperature_schedule_is_linear_and_recorded(tmp_path): + options = _options(cs_ramp_interval=10) + output, _results = _run(tmp_path, [(0.5, 0.5)], options=options, name="ramp") + cycle = json.loads( + (output / "raw" / "replica_000" / "cycle_001" / "cycle.json").read_text() + ) + schedule = cycle["temperature_schedule"] + assert schedule + assert schedule[0]["target_temperature_K"] == pytest.approx(800.0) + n_cool = options.n_cool + for entry in schedule: + fraction = (entry["step"] - options.n_hold) / n_cool + expected = 800.0 + (300.0 - 800.0) * fraction + assert entry["target_temperature_K"] == pytest.approx(expected) + assert cycle["status"] == "completed" + assert cycle["snapshot_steps"] == [40, 80] + + +def test_raw_md_output_uses_the_shared_csv_header(tmp_path): + output, _results = _run(tmp_path, [(0.5, 0.5)], name="raw") + csv_path = output / "raw" / "replica_000" / "cycle_001" / "md.csv" + header = csv_path.read_text().splitlines()[0] + from mliport.runners.md_output import MD_CSV_HEADER + + assert header == ",".join(MD_CSV_HEADER) + assert (output / "raw" / "replica_000" / "cycle_001" / "trajectory.traj").is_file() + + +def test_force_abort_is_recorded_and_the_search_continues(tmp_path): + options = _options(cs_temperature_high=1200.0, fmax_abort=2.0) + output, results = _run(tmp_path, [(0.5, 0.5)], options=options, name="abort") + cycle = json.loads( + (output / "raw" / "replica_000" / "cycle_001" / "cycle.json").read_text() + ) + assert cycle["status"] == "md_force_abort" + assert "fmax_abort" in cycle["message"] + assert results["status"] == "completed" + + +def test_non_finite_energy_is_recorded_as_an_abort(tmp_path): + options = _options(cs_temperature_high=1200.0) + output, _results = _run( + tmp_path, + [(0.5, 0.5)], + calculator=NonFiniteCalculator(fail_after=6), + options=options, + name="nonfinite", + ) + cycle = json.loads( + (output / "raw" / "replica_000" / "cycle_001" / "cycle.json").read_text() + ) + assert cycle["status"] == "md_nonfinite_abort" + + +def test_morse_model_reports_an_integrity_abort_or_reacted_minimum(tmp_path): + options = _options( + cs_temperature_high=1500.0, + cs_temperature_low=300.0, + cs_hold_ps=0.1, + cs_cool_ps=0.05, + cs_snapshot_interval_ps=0.02, + ) + output, results = _run( + tmp_path, + [(0.5, 0.5)], + calculator=MorseBreakCalculator(D_e=0.03), + options=options, + name="morse", + ) + statuses = [ + json.loads( + ( + output / "raw" / "replica_000" / f"cycle_{cycle:03d}" / "cycle.json" + ).read_text() + )["status"] + for cycle in (1, 2) + ] + reacted = results["diagnostics"]["registry"]["classes"].get("reacted", []) + assert "md_integrity_abort" in statuses or reacted + + +# --------------------------------------------------------------------------- +# checkpoint / resume +# --------------------------------------------------------------------------- + + +def test_resume_reproduces_the_uninterrupted_search(tmp_path, monkeypatch): + from mliport.confsearch.engine import SearchEngine + + sites = list(SITE_ENERGIES) + reference_dir, reference = _run(tmp_path, sites, seed=23, name="reference") + + # Simulate a crash right after the second checkpointed unit. + options = _options() + starts = _prepared(sites, options=options) + interrupted_dir = tmp_path / "interrupted" + original = SearchEngine._write_checkpoint + counter = {"n": 0} + + def crash_after_two(self): + original(self) + counter["n"] += 1 + if counter["n"] >= 2: + raise KeyboardInterrupt("simulated crash") + + monkeypatch.setattr(SearchEngine, "_write_checkpoint", crash_after_two) + with pytest.raises(KeyboardInterrupt): + run_confsearch( + EggCrateCalculator(), + options, + starts=starts, + output_dir=interrupted_dir, + seed=23, + model_record={"model_type": "synthetic", "task": "bulk"}, + gradient_preflight={"status": "passed"}, + ) + monkeypatch.undo() + + store = ConfsearchCheckpointStore(interrupted_dir) + data, fingerprint = store.load() + assert 0 < data.unit_index < 1 + len(sites) * options.cs_cycles + + resumed = run_confsearch( + EggCrateCalculator(), + options, + starts=starts, + output_dir=interrupted_dir, + seed=23, + model_record={"model_type": "synthetic", "task": "bulk"}, + gradient_preflight={"status": "passed"}, + resume=data, + resume_fingerprint=fingerprint, + ) + assert resumed["ranking"] == reference["ranking"] + assert ( + resumed["diagnostics"]["n_quenches"] == reference["diagnostics"]["n_quenches"] + ) + + +def test_resume_fingerprint_refuses_a_changed_option(tmp_path): + from mliport.confsearch.checkpoint import ( + build_resume_fingerprint, + compare_fingerprints, + ) + + options = _options() + first, _sha = build_resume_fingerprint( + options=options, + model={"model_type": "synthetic"}, + input_hashes={"starts": "abc"}, + regions={"adsorbate": [16, 17, 18]}, + seed=1, + mliport_version="2.0.0b4", + ) + second, _sha = build_resume_fingerprint( + options=replace(options, cs_temperature_high=900.0), + model={"model_type": "synthetic"}, + input_hashes={"starts": "abc"}, + regions={"adsorbate": [16, 17, 18]}, + seed=1, + mliport_version="2.0.0b4", + ) + differences = compare_fingerprints(first, second) + assert differences + assert any("cs_temperature_high" in item for item in differences) + + +def test_checkpoint_round_trip_restores_the_registry(tmp_path): + output, results = _run(tmp_path, [(0.5, 0.5)], name="roundtrip") + store = ConfsearchCheckpointStore(output) + data, _fingerprint = store.load() + assert data.registry["classes"] + assert data.rng_states["replicas"] + assert data.unit_index == 1 + 1 * 2 # start stage + two cycles + assert data.registry["schema"] == "mliport.confsearch-registry/1" + assert ( + results["diagnostics"]["registry"]["schema"] == "mliport.confsearch-registry/1" + ) + + +def test_interrupted_raw_directories_are_archived_not_deleted(tmp_path): + store = ConfsearchCheckpointStore(tmp_path / "run") + source = tmp_path / "run" / "raw" / "replica_000" / "cycle_001" + source.mkdir(parents=True) + (source / "md.csv").write_text("partial\n") + archived = store.archive_incomplete(replica=0, cycle=1) + assert archived is not None + assert archived.name == "incomplete_attempt_1" + assert (archived / "md.csv").read_text() == "partial\n" + assert not source.exists() From 75e2cb5542ef91052264a7216dbe3276147d23c1 Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Sun, 25 Oct 2026 23:52:55 +0800 Subject: [PATCH 5/6] =?UTF-8?q?fix(confsearch):=20honour=20refinement=20re?= =?UTF-8?q?sults,=20aborts=20and=20the=20minima=20outputs=20(spec=20rev=20?= =?UTF-8?q?5=20=C2=A710/=C2=A711.1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tracking: #61 (spec revision 5, PR #64 review) Addresses all six review items on #64. Ranking and refinement (spec 10.1/10.3): - a refinement replaces the quench result only when it converged **and** its classification is still rankable; an unconverged refinement keeps the quench result and is flagged (`refinement_failed`, note `refinement_not_converged`); a refinement that changed to a non-rankable status leaves the ranking entirely with a recorded reason (`refinement_changed_status`); - the refined set is re-deduplicated with the section 9.3 rule through a scratch registry, and a merged entry keeps the summed hit counts, the union of replicas and the earliest first-found record; - ranking and export directories follow the **refined** energy, so `top/rank_001` is the lowest refined structure; - refined and unrefined energies are never interleaved: each table has its own best energy, the export window is relative to the refined best, and `ranking.best_energy_source` says which table the reported best came from. Engine (spec 7.3): - abort frames are never quenched: the observer checks the integrity *before* keeping a snapshot, the force abort raises before the snapshot is kept, and the `except` clause no longer appends the abort frame, so an integrity-abort frame is not quenched twice; - the end-of-cycle frame gets the same early integrity check as the hold-phase snapshots; - `quench()` no longer lets a calculator that raises on a bad geometry escape as an uncaught exception; the outcome is `quench_failed`. Diagnostics (spec 10.2/10.4): - `top_k_never_reached_by_start_quench` now means "no *member* has a start origin" (merged refined entries are checked through all their source ids); - `first_found_fraction` and `best_first_found_fraction` use the unique's `first_found_quench_index`, not the representative's own quench index. Outputs (spec 11.1): - `minima/all_minima.extxyz` now holds every quench result of every status with its provenance (unique id, record id, status, flags, energy, fmax, steps, quench index, cumulative MD ps, origin), and `minima/registry.json` holds the registry. Non-finite energies are omitted from the frame info because extxyz cannot carry NaN. Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers reordering, merging, unconverged refinement, status change, the minima directory and the member-based diagnostics. Full confsearch suite on CPU: 132 passed. DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the `minima/` contents change; runs are re-ranked from their stored quench results. --- mliport/mliport/confsearch/engine.py | 15 +- mliport/mliport/confsearch/quench.py | 7 +- mliport/mliport/confsearch/results.py | 563 ++++++++++++++---- .../mliport/confsearch/test_refinement.py | 238 ++++++++ 4 files changed, 697 insertions(+), 126 deletions(-) create mode 100644 tests/mliport/mliport/confsearch/test_refinement.py diff --git a/mliport/mliport/confsearch/engine.py b/mliport/mliport/confsearch/engine.py index 92b2dad9..cab4fac4 100644 --- a/mliport/mliport/confsearch/engine.py +++ b/mliport/mliport/confsearch/engine.py @@ -599,13 +599,17 @@ def observe() -> None: or gate.abort ) if keep: + # The raw trajectory keeps every requested frame, including the + # one that triggers an abort. writer.submit( MDFrameSnapshot( atoms=md_atoms.copy(), summary=frame, outcar_forces=None ) ) if step in snapshot_steps: - snapshots.append(md_atoms.copy()) + # Check the integrity *before* keeping the frame: a frame that + # already broke the adsorbate must not be quenched (spec 7.3 + # step 9 quenches only snapshots taken before the stop). self._check_md_integrity(replica, md_atoms, step) if gate.abort: abort_status = cs_status.MD_FORCE_ABORT @@ -614,6 +618,8 @@ def observe() -> None: f"{gate.atom_index} exceeds fmax_abort={options.fmax_abort}" ) raise _MDAbort(abort_status, abort_message, md_atoms.copy()) + if step in snapshot_steps: + snapshots.append(md_atoms.copy()) dynamics.attach(observe, interval=1) steps_done = 0 @@ -634,11 +640,14 @@ def observe() -> None: dynamics.run(block) steps_done += block remaining -= block + # Spec 7.3 step 7: the end-of-cycle frame gets the same early + # integrity check as the hold-phase snapshots. + self._check_md_integrity(replica, md_atoms, steps_done) except _MDAbort as exc: abort_status = exc.status abort_message = str(exc) - if exc.frame is not None: - snapshots.append(exc.frame) + # The abort frame lives in the raw trajectory only; it is never + # quenched (spec 7.3 step 9). finally: try: writer.close() diff --git a/mliport/mliport/confsearch/quench.py b/mliport/mliport/confsearch/quench.py index 4c6a0aeb..be2d146a 100644 --- a/mliport/mliport/confsearch/quench.py +++ b/mliport/mliport/confsearch/quench.py @@ -121,7 +121,12 @@ def observe() -> None: if optimizer.converged(): status = cs_status.VALID - energy = float(work.get_potential_energy()) + try: + energy = float(work.get_potential_energy()) + except Exception: + # A calculator that raises on a bad geometry is a quench outcome, not a + # search crash. + energy = float("nan") if not np.isfinite(energy): status = cs_status.QUENCH_FAILED try: diff --git a/mliport/mliport/confsearch/results.py b/mliport/mliport/confsearch/results.py index 0e84c027..f49941e3 100644 --- a/mliport/mliport/confsearch/results.py +++ b/mliport/mliport/confsearch/results.py @@ -3,6 +3,18 @@ Everything here is a *screening* product: the outputs say "lowest found", never "global minimum", and every number carries the provenance needed to re-rank the candidates with DFT (spec sections 10.2, 15). + +Ranking rules enforced here (spec 10.1/10.3 revision 4, review of PR #64): + +* a refinement replaces the quench result only when it converged **and** its + classification is still rankable; an unconverged refinement keeps the quench + result and is flagged, and a refinement that changed to a non-rankable status + leaves the ranking with a record saying why; +* the refined set is re-deduplicated with the section 9.3 rule, and the merged + entry keeps the summed hit counts of its sources; +* refined and unrefined energies are never interleaved: each table has its own + best energy and its own export window, and the exports come from the refined + table whenever it exists. """ from __future__ import annotations @@ -22,7 +34,11 @@ from mliport.confsearch import status as cs_status from mliport.confsearch.graphs import covalent_bonds, classify_minimum, ionic_mask from mliport.confsearch.quench import refine -from mliport.confsearch.registry import MinimumRecord, MinimumRegistry, UniqueMinimum +from mliport.confsearch.registry import ( + MinimumRecord, + MinimumRegistry, + UniqueMinimum, +) from mliport.writers.contcar import ContcarWriter if TYPE_CHECKING: @@ -139,47 +155,188 @@ def make_whole_adsorbate( return work -def _ranking_entry( +# --------------------------------------------------------------------------- +# ranking entries +# --------------------------------------------------------------------------- + + +def _refined_entry( + group: dict, *, best_energy: float, n_atoms: int, total_quenches: int +) -> dict: + """Ranking entry for a re-deduplicated refined minimum.""" + energy = float(group["energy_eV"]) + return { + "id": int(group["ids"][0]), + "merged_ids": [int(value) for value in group["ids"]], + "status": str(group["status"]), + "energy_eV": energy, + "delta_energy_eV": float(energy - best_energy), + "delta_energy_per_atom_eV": float((energy - best_energy) / max(1, n_atoms)), + "hit_count": int(group["hit_count"]), + "replicas": sorted(int(value) for value in group["replicas"]), + "n_replicas": len(group["replicas"]), + "first_found_md_ps": float(group["first_found_md_ps"]), + "first_found_fraction": float( + group["first_found_quench_index"] / total_quenches + if total_quenches + else 0.0 + ), + "first_found_quench_index": int(group["first_found_quench_index"]), + "flags": list(group["flags"]), + "chemisorbed": bool(group["classification"].chemisorbed), + "refined": True, + "refinement_status": str(group["status"]), + "refinement_failed": False, + "quench_energy_eV": float(group["quench_energy_eV"]), + "fmax_eV_A": float(group["fmax_eV_A"]), + "classification": group["classification"].to_dict(), + "origin": group["origin"].to_dict(), + } + + +def _unrefined_entry( unique: UniqueMinimum, *, best_energy: float, n_atoms: int, - refinement: RefinementOutcome | None, total_quenches: int, + refinement: RefinementOutcome | None = None, ) -> dict: + """Ranking entry for a quench result (no usable refinement).""" representative = unique.representative - energy = refinement.energy_eV if refinement is not None else unique.energy_eV - first_found_fraction = ( - representative.quench_index / total_quenches if total_quenches else 0.0 - ) + energy = float(unique.energy_eV) return { - "id": unique.unique_id, + "id": int(unique.unique_id), + "merged_ids": [int(unique.unique_id)], "status": unique.status, - "energy_eV": float(energy), + "energy_eV": energy, "delta_energy_eV": float(energy - best_energy), "delta_energy_per_atom_eV": float((energy - best_energy) / max(1, n_atoms)), - "hit_count": unique.hit_count, - "replicas": sorted(unique.replicas), + "hit_count": int(unique.hit_count), + "replicas": sorted(int(value) for value in unique.replicas), "n_replicas": len(unique.replicas), "first_found_md_ps": float(unique.first_found_md_ps), - "first_found_fraction": float(first_found_fraction), + "first_found_fraction": float( + unique.first_found_quench_index / total_quenches if total_quenches else 0.0 + ), + "first_found_quench_index": int(unique.first_found_quench_index), "flags": list(unique.flags), "chemisorbed": representative.classification.chemisorbed, - "refined": refinement is not None, + "refined": False, "refinement_status": None if refinement is None else refinement.status, - "quench_energy_eV": float(unique.energy_eV), - "fmax_eV_A": float( - refinement.fmax_eV_A if refinement is not None else representative.fmax_eV_A - ), + "refinement_failed": bool(refinement is not None and not refinement.converged), + "quench_energy_eV": energy, + "fmax_eV_A": float(representative.fmax_eV_A), "classification": representative.classification.to_dict(), "origin": representative.origin.to_dict(), } +def _dedup_refined( + accepted: dict[int, RefinementOutcome], + *, + quench_rankable: list[tuple[UniqueMinimum, float]], + options: ConfsearchOptions, + regions: Regions, +) -> list[dict]: + """Re-deduplicate the refined set with the section 9.3 rule (spec 10.3). + + A temporary registry applies the same ``dE`` AND (``G`` OR ``D``) matching to + the refined representatives in ascending refined energy; the merged group + keeps the summed hit counts, the union of replicas and the earliest + first-found record of its sources. + """ + by_id = {unique.unique_id: unique for unique, _energy in quench_rankable} + scratch = MinimumRegistry( + options=options, adsorbate=regions.adsorbate, fixed=regions.fixed + ) + groups: dict[int, dict] = {} + ordered = sorted(accepted.items(), key=lambda item: (item[1].energy_eV, item[0])) + for unique_id, outcome in ordered: + source = by_id[unique_id] + record = MinimumRecord( + record_id=scratch.new_record_id(), + energy_eV=float(outcome.energy_eV), + atoms=outcome.atoms, + classification=outcome.classification, + origin=source.representative.origin, + quench_index=int(source.first_found_quench_index), + cumulative_md_ps=float(source.first_found_md_ps), + fmax_eV_A=float(outcome.fmax_eV_A), + steps=int(outcome.steps), + ) + registered = scratch.register(record) + group = groups.get(registered.unique_id) + if group is None: + groups[registered.unique_id] = { + "energy_eV": float(outcome.energy_eV), + "quench_energy_eV": float(source.energy_eV), + "atoms": outcome.atoms, + "classification": outcome.classification, + "fmax_eV_A": float(outcome.fmax_eV_A), + "steps": int(outcome.steps), + "ids": [int(unique_id)], + "hit_count": int(source.hit_count), + "replicas": {int(value) for value in source.replicas}, + "first_found_md_ps": float(source.first_found_md_ps), + "first_found_quench_index": int(source.first_found_quench_index), + "status": str(outcome.status), + "flags": tuple(source.flags), + "origin": source.representative.origin, + } + continue + group["ids"].append(int(unique_id)) + group["hit_count"] += int(source.hit_count) + group["replicas"] |= {int(value) for value in source.replicas} + group["first_found_md_ps"] = min( + group["first_found_md_ps"], float(source.first_found_md_ps) + ) + group["first_found_quench_index"] = min( + group["first_found_quench_index"], int(source.first_found_quench_index) + ) + return [groups[key] for key in sorted(groups)] + + +def _refined_payload(group: dict, energy: float) -> dict: + """``minimum.json`` body for a refined (possibly merged) entry.""" + atoms = group["atoms"] + return { + "id": int(group["ids"][0]), + "merged_ids": [int(value) for value in group["ids"]], + "status": str(group["status"]), + "energy_eV": float(energy), + "flags": list(group["flags"]), + "hit_count": int(group["hit_count"]), + "replicas": sorted(int(value) for value in group["replicas"]), + "first_found_md_ps": float(group["first_found_md_ps"]), + "first_found_quench_index": int(group["first_found_quench_index"]), + "representative": { + "record_id": None, + "energy_eV": float(energy), + "fmax_eV_A": float(group["fmax_eV_A"]), + "steps": int(group["steps"]), + "origin": group["origin"].to_dict(), + "numbers": [int(z) for z in atoms.numbers], + "symbols": atoms.get_chemical_symbols(), + "cell_A": np.asarray(atoms.cell, dtype=float).tolist(), + "pbc": [bool(value) for value in atoms.pbc], + "positions_A": np.asarray(atoms.get_positions(), dtype=float).tolist(), + "classification": group["classification"].to_dict(), + }, + "members": [], + } + + +# --------------------------------------------------------------------------- +# exports +# --------------------------------------------------------------------------- + + def _export_candidate( directory: Path, *, - unique: UniqueMinimum, + unique_id: int, + payload: dict, atoms: Atoms, options: ConfsearchOptions, regions: Regions, @@ -196,15 +353,15 @@ def _export_candidate( ContcarWriter().write( constrained, directory / "POSCAR", - comment=f"confsearch rank {unique.unique_id} E={energy:.6f} eV", + comment=f"confsearch rank {unique_id} E={energy:.6f} eV", direct=True, ) export_atoms = whole.copy() - export_atoms.info["confsearch_id"] = int(unique.unique_id) - export_atoms.info["confsearch_status"] = unique.status + export_atoms.info["confsearch_id"] = int(unique_id) + export_atoms.info["confsearch_status"] = entry["status"] export_atoms.info["energy_eV"] = float(energy) - export_atoms.info["flags"] = list(unique.flags) + export_atoms.info["flags"] = list(entry["flags"]) ase_write(directory / "structure.extxyz", export_atoms, format="extxyz") ase_write(directory / "cp2k_coord.xyz", export_atoms, format="xyz") @@ -224,8 +381,8 @@ def _export_candidate( encoding="utf-8", ) - payload = unique.to_dict() - payload["export"] = { + body = dict(payload) + body["export"] = { "rank_energy_eV": float(energy), "ranking": entry, "coordinate_convention": ( @@ -233,7 +390,8 @@ def _export_candidate( ), } (directory / "minimum.json").write_text( - json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8" + json.dumps(body, indent=2, sort_keys=True, default=_json_default) + "\n", + encoding="utf-8", ) files = [ "POSCAR", @@ -244,20 +402,20 @@ def _export_candidate( "minimum.json", ] return { - "rank": unique.unique_id, + "rank": int(unique_id), "path": directory.name, "energy_eV": float(energy), "files": files, } -def _saturation( - registry: MinimumRegistry, - *, - rankable: list[tuple[UniqueMinimum, float]], - total_quenches: int, -) -> dict: - if not rankable: +# --------------------------------------------------------------------------- +# diagnostics +# --------------------------------------------------------------------------- + + +def _saturation(entries: list[dict], *, total_quenches: int) -> dict: + if not entries: return { "best_hit_count": 0, "best_replicas": [], @@ -266,24 +424,30 @@ def _saturation( "new_low_minima_last_quarter": 0, "lowest_found_language": "lowest found (no global-minimum claim)", } - best = rankable[0][0] - representative = best.representative - fraction = representative.quench_index / total_quenches if total_quenches else 0.0 + best = entries[0] + best_energy = float(best["energy_eV"]) + fraction = ( + float(best["first_found_quench_index"]) / total_quenches + if total_quenches + else 0.0 + ) cutoff = int(math.ceil(0.75 * total_quenches)) - recent = 0 - for unique, energy in rankable: - if energy - rankable[0][1] > NEW_LOW_WINDOW_EV: - continue - if unique.first_found_quench_index > cutoff: - recent += 1 + recent = sum( + 1 + for entry in entries + if float(entry["energy_eV"]) - best_energy <= NEW_LOW_WINDOW_EV + and int(entry["first_found_quench_index"]) > cutoff + ) return { - "best_id": best.unique_id, - "best_energy_eV": float(rankable[0][1]), - "best_hit_count": best.hit_count, - "best_replicas": sorted(best.replicas), - "best_first_found_md_ps": float(best.first_found_md_ps), - "best_first_found_fraction": float(fraction), - "best_repeatedly_found": bool(best.hit_count >= 3 and len(best.replicas) >= 2), + "best_id": int(best["id"]), + "best_energy_eV": best_energy, + "best_hit_count": int(best["hit_count"]), + "best_replicas": list(best["replicas"]), + "best_first_found_md_ps": float(best["first_found_md_ps"]), + "best_first_found_fraction": fraction, + "best_repeatedly_found": bool( + int(best["hit_count"]) >= 3 and len(best["replicas"]) >= 2 + ), "new_low_minima_last_quarter": int(recent), "lowest_found_language": "lowest found (no global-minimum claim)", } @@ -321,7 +485,7 @@ def _status_warnings( f"{100 * not_converged / all_records:.1f}% of quenches did not converge " "within cs_quench_steps" ) - for entry in ranked: + for entry in ranked[: int(options.cs_top_k)]: if "far_field_slab_changed" in entry["flags"]: warnings.append( f"top-{options.cs_top_k} minimum {entry['id']} has " @@ -331,6 +495,46 @@ def _status_warnings( return warnings +def _baseline_report( + baseline: dict, + top_entries: list[dict], + *, + uniques_by_id: dict[int, UniqueMinimum], + options: ConfsearchOptions, +) -> dict: + """Baseline comparison (spec 10.4). + + ``top_k_never_reached_by_start_quench`` lists the top-K minima that have **no + member** whose origin is a start quench -- not merely a representative that + did not come from a start. + """ + report = dict(baseline) + best_baseline = baseline.get("best_energy_eV") + if best_baseline is None or not top_entries: + report["top_k_never_reached_by_start_quench"] = None + return report + never: list[int] = [] + for entry in top_entries[: int(options.cs_top_k)]: + ids = entry.get("merged_ids") or [entry["id"]] + reached = False + for unique_id in ids: + unique = uniques_by_id.get(int(unique_id)) + if unique is None: + continue + if any(member.origin.source == "start" for member in unique.members): + reached = True + break + if not reached: + never.append(int(entry["id"])) + report["top_k_never_reached_by_start_quench"] = never + return report + + +# --------------------------------------------------------------------------- +# results assembly +# --------------------------------------------------------------------------- + + def build_results( *, registry: MinimumRegistry, @@ -353,9 +557,10 @@ def build_results( output_dir = Path(output_dir) (output_dir / "diagnostics").mkdir(parents=True, exist_ok=True) _write_discovery_csv(output_dir / "diagnostics" / "discovery.csv", discovery) + _write_minima(output_dir, registry) rankable_statuses = cs_status.rankable_statuses(options.cs_reaction_policy) - rankable = sorted( + quench_rankable = sorted( ( (unique, unique.energy_eV) for status in rankable_statuses @@ -363,16 +568,19 @@ def build_results( ), key=lambda item: (item[1], item[0].unique_id), ) + total_quenches = registry.total_records() + n_atoms = len(quench_rankable[0][0].representative.atoms) if quench_rankable else 0 + uniques_by_id = {unique.unique_id: unique for unique, _ in quench_rankable} refinements: dict[int, RefinementOutcome] = {} if ( options.cs_refine - and rankable + and quench_rankable and calculator is not None and regions is not None ): refinements = _refine_top_k( - rankable, + quench_rankable, options=options, regions=regions, references=references or [], @@ -380,76 +588,144 @@ def build_results( calculator=calculator, ) - ranked_energies = { - unique.unique_id: ( - refinements[unique.unique_id].energy_eV - if unique.unique_id in refinements - else energy + # Spec 10.1/10.3: only a converged refinement whose status is still rankable + # replaces the quench result. Everything else is recorded with its reason. + accepted: dict[int, RefinementOutcome] = {} + removed: set[int] = set() + refinement_notes: list[dict] = [] + for unique, _quench_energy in quench_rankable: + outcome = refinements.get(unique.unique_id) + if outcome is None: + continue + if not outcome.converged: + refinement_notes.append( + { + "id": unique.unique_id, + "reason": "refinement_not_converged", + "refinement_status": outcome.status, + "kept": "quench_result", + } + ) + continue + if outcome.status not in rankable_statuses: + # The refinement is the tighter classification: an entry that is no + # longer rankable leaves the ranking entirely (spec 10.1). + removed.add(unique.unique_id) + refinement_notes.append( + { + "id": unique.unique_id, + "reason": "refinement_changed_status", + "refinement_status": outcome.status, + "kept": "none (no longer rankable)", + "energy_eV": float(outcome.energy_eV), + } + ) + continue + accepted[unique.unique_id] = outcome + + refined_groups = ( + _dedup_refined( + accepted, + quench_rankable=quench_rankable, + options=options, + regions=regions, + ) + if accepted and regions is not None + else [] + ) + + refined_best = min((group["energy_eV"] for group in refined_groups), default=None) + unrefined_candidates = [ + (unique, energy) + for unique, energy in quench_rankable + if unique.unique_id not in accepted and unique.unique_id not in removed + ] + unrefined_best = min( + (energy for _unique, energy in unrefined_candidates), default=None + ) + + refined_entries = [ + _refined_entry( + group, + best_energy=float(refined_best), + n_atoms=n_atoms, + total_quenches=total_quenches, ) - for unique, energy in rankable - } - best_energy = min(ranked_energies.values()) if ranked_energies else 0.0 - total_quenches = registry.total_records() - n_atoms = len(rankable[0][0].representative.atoms) if rankable else 0 - entries = [ - _ranking_entry( + for group in sorted( + refined_groups, key=lambda group: (group["energy_eV"], group["ids"][0]) + ) + ] + unrefined_entries = [ + _unrefined_entry( unique, - best_energy=best_energy, + best_energy=float(unrefined_best), n_atoms=n_atoms, - refinement=refinements.get(unique.unique_id), total_quenches=total_quenches, + refinement=refinements.get(unique.unique_id), + ) + for unique, _energy in sorted( + unrefined_candidates, key=lambda item: (item[1], item[0].unique_id) ) - for unique, _energy in rankable ] - refined_entries = [entry for entry in entries if entry["refined"]] - unrefined_entries = [entry for entry in entries if not entry["refined"]] - baseline_report = _baseline_report(baseline, entries, options) + # Never interleave energies at different fmax: exports come from the refined + # table when it exists, and the window is relative to that table's best. + export_groups: dict[int, dict] = {} + if refined_entries: + export_source = refined_entries + export_groups = {int(group["ids"][0]): group for group in refined_groups} + best_export: float | None = float(refined_best) + else: + export_source = unrefined_entries + best_export = float(unrefined_best) if unrefined_best is not None else None exports: list[dict] = [] - if regions is not None: + if regions is not None and export_source and best_export is not None: window = [ - (unique, ranked_energies[unique.unique_id]) - for unique, _energy in rankable - if ranked_energies[unique.unique_id] - best_energy - <= options.cs_export_window + entry + for entry in export_source + if float(entry["energy_eV"]) - best_export <= options.cs_export_window ][: int(options.cs_top_k)] - for position, (unique, energy) in enumerate(window, start=1): - atoms = ( - refinements[unique.unique_id].atoms - if unique.unique_id in refinements - else unique.representative.atoms - ) + for position, entry in enumerate(window, start=1): + unique_id = int(entry["id"]) + if unique_id in export_groups: + group = export_groups[unique_id] + atoms = group["atoms"] + payload = _refined_payload(group, float(entry["energy_eV"])) + else: + unique = uniques_by_id[unique_id] + atoms = unique.representative.atoms + payload = unique.to_dict() exports.append( _export_candidate( output_dir / "top" / f"rank_{position:03d}", - unique=unique, + unique_id=unique_id, + payload=payload, atoms=atoms, options=options, regions=regions, - entry=entries[ - next( - index - for index, item in enumerate(entries) - if item["id"] == unique.unique_id - ) - ], - energy=energy, + entry=entry, + energy=float(entry["energy_eV"]), ) ) - saturation = _saturation( - registry, - rankable=[ - (unique, ranked_energies[unique.unique_id]) for unique, _ in rankable - ], - total_quenches=total_quenches, + ranked_for_diagnostics = refined_entries or unrefined_entries + saturation = _saturation(ranked_for_diagnostics, total_quenches=total_quenches) + baseline_report = _baseline_report( + baseline, + ranked_for_diagnostics, + uniques_by_id=uniques_by_id, + options=options, + ) + warnings = list(warnings) + _status_warnings( + registry, options, ranked_for_diagnostics ) - warnings = list(warnings) + _status_warnings(registry, options, entries) warnings = list(dict.fromkeys(warnings)) status = "completed" - if not any(getattr(replica, "status", None) == "active" for replica in replicas): + if replicas and not any( + getattr(replica, "status", None) == "active" for replica in replicas + ): status = "failed" results = { @@ -467,8 +743,13 @@ def build_results( "cs_fp_sigma": float(options.cs_fp_sigma), }, "ranking": { - "best_energy_eV": float(best_energy) if rankable else None, - "n_rankable": len(entries), + "best_energy_eV": ( + float(refined_best) + if refined_entries + else (float(unrefined_best) if unrefined_best is not None else None) + ), + "best_energy_source": "refined" if refined_entries else "quench", + "n_rankable": len(refined_entries) + len(unrefined_entries), "refined": refined_entries, "unrefined": unrefined_entries, }, @@ -489,7 +770,11 @@ def build_results( "enabled": bool(options.cs_refine), "fmax_eV_A": float(options.cs_refine_fmax), "steps": int(options.cs_refine_steps), - "n_refined": len(refinements), + "n_refined": len(accepted), + "n_merged_into_existing": int( + sum(len(group["ids"]) - 1 for group in refined_groups) + ), + "notes": refinement_notes, }, } (output_dir / "search_results.json").write_text( @@ -514,6 +799,60 @@ def _json_default(value: Any) -> Any: return str(value) +def _finite_info(info: dict) -> dict: + """Drop non-finite floats: extxyz cannot carry NaN/Inf.""" + cleaned: dict = {} + for key, value in info.items(): + if isinstance(value, float) and not math.isfinite(value): + continue + if isinstance(value, (list, tuple)): + cleaned[key] = list(value) + continue + cleaned[key] = value + return cleaned + + +def _write_minima(output_dir: Path, registry: MinimumRegistry) -> None: + """Write ``minima/all_minima.extxyz`` and ``minima/registry.json`` (spec 11.1). + + Every quench result is kept, whatever its status, so rejected, failed and + ``reacted`` geometries can be inspected after the run. + """ + directory = output_dir / "minima" + directory.mkdir(parents=True, exist_ok=True) + frames: list[Atoms] = [] + for status in sorted(registry.status_classes()): + for unique in sorted(registry.uniques(status), key=lambda item: item.unique_id): + for member in sorted(unique.members, key=lambda item: item.record_id): + atoms = member.atoms.copy() + atoms.info.update( + _finite_info( + { + "confsearch_unique_id": int(unique.unique_id), + "confsearch_record_id": int(member.record_id), + "confsearch_status": member.status, + "confsearch_flags": list(member.flags), + "energy_eV": float(member.energy_eV), + "fmax_eV_A": float(member.fmax_eV_A), + "quench_steps": int(member.steps), + "quench_index": int(member.quench_index), + "cumulative_md_ps": float(member.cumulative_md_ps), + "origin_replica": int(member.origin.replica), + "origin_cycle": int(member.origin.cycle), + "origin_source": member.origin.source, + } + ) + ) + frames.append(atoms) + if frames: + ase_write(directory / "all_minima.extxyz", frames, format="extxyz") + (directory / "registry.json").write_text( + json.dumps(registry.to_dict(), indent=2, sort_keys=True, default=_json_default) + + "\n", + encoding="utf-8", + ) + + def _write_discovery_csv(path: Path, rows: list[dict]) -> None: fieldnames = [ "cumulative_md_ps", @@ -587,26 +926,6 @@ def _reference_for_record( raise ValueError("No classification reference available for refinement") -def _baseline_report( - baseline: dict, entries: list[dict], options: ConfsearchOptions -) -> dict: - best_baseline = baseline.get("best_energy_eV") - report = dict(baseline) - if best_baseline is None or not entries: - report["best_energy_eV"] = best_baseline - report["top_k_never_reached_by_start_quench"] = None - return report - top_k = entries[: int(options.cs_top_k)] - never = [ - entry["id"] - for entry in top_k - if entry["origin"]["source"] != "start" - and entry["energy_eV"] < best_baseline - 1e-12 - ] - report["top_k_never_reached_by_start_quench"] = never - return report - - def _write_artifacts(output_dir: Path, results: dict) -> None: manifest: dict[str, dict] = {} for path in sorted(output_dir.rglob("*")): diff --git a/tests/mliport/mliport/confsearch/test_refinement.py b/tests/mliport/mliport/confsearch/test_refinement.py new file mode 100644 index 00000000..1b4615d1 --- /dev/null +++ b/tests/mliport/mliport/confsearch/test_refinement.py @@ -0,0 +1,238 @@ +"""Refinement, ranking and diagnostics contracts (spec 10.1/10.3/10.4, PR #64 review). + +The refinement engine is stubbed so the ranking rules can be tested directly: + +* a refinement that lowers a candidate's order must move it to the top and into + ``top/rank_001``; +* two refined minima that deduplicate into one entry must merge (summed hit + counts), not be exported twice; +* an unconverged refinement keeps the quench result and is flagged; +* a refinement that changes to a non-rankable status leaves the ranking with a + recorded reason; +* ``minima/all_minima.extxyz`` keeps every quench result of every status; +* the baseline and saturation diagnostics count *members*, not representatives. +""" + +from __future__ import annotations + +import json +from types import SimpleNamespace + +import numpy as np +import pytest +from ase.io import read + +from mliport.confsearch import results as results_module +from mliport.confsearch.engine import MinimumOrigin, MinimumRecord, MinimumRegistry +from mliport.confsearch.regions import resolve_regions +from tests.mliport.mliport.confsearch.structures import fake_classification +from tests.mliport.mliport.confsearch.test_engine import SLAB_ATOMS, _options, _start + + +def _setup(): + options = _options() + atoms = _start((0.5, 0.5)) + regions = resolve_regions( + atoms, options, adsorbate_indices=np.arange(SLAB_ATOMS, len(atoms)) + ) + registry = MinimumRegistry( + options=options, adsorbate=regions.adsorbate, fixed=regions.fixed + ) + return options, regions, registry, atoms + + +def _register( + registry, atoms, *, energy, replica, source="end", status="valid", cycle=1, quench=1 +): + record = MinimumRecord( + record_id=registry.new_record_id(), + energy_eV=float(energy), + atoms=atoms, + classification=fake_classification(status=status), + origin=MinimumOrigin(replica=replica, cycle=cycle, source=source), + quench_index=int(quench), + cumulative_md_ps=float(quench), + fmax_eV_A=0.04, + steps=10, + ) + return registry.register(record) + + +def _outcome( + unique_id, *, energy, status="valid", converged=True, atoms=None, fmax=0.02 +): + return results_module.RefinementOutcome( + unique_id=int(unique_id), + status=status, + energy_eV=float(energy), + fmax_eV_A=float(fmax), + steps=5, + atoms=atoms, + classification=fake_classification(status=status), + converged=bool(converged), + ) + + +def _build(options, regions, registry, refinements, atoms, *, tmp_path): + monkeypatch_target = results_module._refine_top_k + results_module._refine_top_k = lambda *a, **k: refinements + try: + return results_module.build_results( + registry=registry, + options=options, + replicas=[SimpleNamespace(status="active")], + discovery=[], + baseline={"stage": "start_quench", "best_energy_eV": -0.60}, + warnings=[], + output_dir=tmp_path, + model_record={"model_type": "synthetic"}, + gradient_preflight={"status": "passed"}, + cumulative_md_ps=1.0, + seed=7, + starts=[], + regions=regions, + references=[None], + calculator=object(), + ) + finally: + results_module._refine_top_k = monkeypatch_target + + +def test_refinement_reorders_the_ranking_and_the_exports(tmp_path): + """A candidate whose refined energy is lower must become rank_001.""" + options, regions, registry, atoms = _setup() + high = _register(registry, atoms, energy=-0.50, replica=0) + low = _register(registry, atoms, energy=-0.45, replica=1, quench=2) + refined_high = atoms.copy() + refined_high.positions[SLAB_ATOMS] += 0.02 + refined_low = atoms.copy() + refined_low.positions[SLAB_ATOMS] += 0.05 + refinements = { + high.unique_id: _outcome(high.unique_id, energy=-0.20, atoms=refined_high), + low.unique_id: _outcome(low.unique_id, energy=-0.90, atoms=refined_low), + } + results = _build(options, regions, registry, refinements, atoms, tmp_path=tmp_path) + + refined = results["ranking"]["refined"] + assert [entry["id"] for entry in refined] == [low.unique_id, high.unique_id] + assert refined[0]["delta_energy_eV"] == pytest.approx(0.0) + assert results["ranking"]["best_energy_source"] == "refined" + assert results["ranking"]["unrefined"] == [] + exported = read(tmp_path / "top" / "rank_001" / "structure.extxyz") + # rank_001 is the refined geometry of the *lowest refined* candidate. + assert exported.info["confsearch_id"] == low.unique_id + + +def test_refined_duplicates_merge_into_one_entry(tmp_path): + """Spec 10.3: re-deduplicate the refined set, keeping the hit counts.""" + options, regions, registry, atoms = _setup() + first = _register(registry, atoms, energy=-0.50, replica=0) + _register(registry, atoms, energy=-0.50, replica=1, quench=2) # same basin + assert first.hit_count == 2 + second = _register(registry, atoms, energy=-0.30, replica=2, quench=3) + refinements = { + first.unique_id: _outcome(first.unique_id, energy=-0.80, atoms=atoms), + second.unique_id: _outcome(second.unique_id, energy=-0.80, atoms=atoms.copy()), + } + results = _build(options, regions, registry, refinements, atoms, tmp_path=tmp_path) + + refined = results["ranking"]["refined"] + assert len(refined) == 1 + assert refined[0]["hit_count"] == 3 # 2 + 1, summed over the merged sources + assert sorted(refined[0]["merged_ids"]) == sorted( + [first.unique_id, second.unique_id] + ) + assert results["refinement"]["n_merged_into_existing"] == 1 + assert len(results["exports"]) == 1 + + +def test_unconverged_refinement_keeps_the_quench_result_and_flags_it(tmp_path): + options, regions, registry, atoms = _setup() + unique = _register(registry, atoms, energy=-0.50, replica=0) + refinements = { + unique.unique_id: _outcome( + unique.unique_id, + energy=-0.40, + status="quench_not_converged", + converged=False, + ) + } + results = _build(options, regions, registry, refinements, atoms, tmp_path=tmp_path) + + assert results["ranking"]["refined"] == [] + unrefined = results["ranking"]["unrefined"] + assert len(unrefined) == 1 + assert unrefined[0]["energy_eV"] == pytest.approx(-0.50) # quench energy kept + assert unrefined[0]["refinement_failed"] is True + notes = results["refinement"]["notes"] + assert notes and notes[0]["reason"] == "refinement_not_converged" + assert notes[0]["kept"] == "quench_result" + + +def test_refinement_status_change_removes_the_entry_with_a_reason(tmp_path): + options, regions, registry, atoms = _setup() + unique = _register(registry, atoms, energy=-0.50, replica=0) + refinements = { + unique.unique_id: _outcome(unique.unique_id, energy=-0.40, status="desorbed") + } + results = _build(options, regions, registry, refinements, atoms, tmp_path=tmp_path) + + assert results["ranking"]["refined"] == [] + assert results["ranking"]["unrefined"] == [] + notes = results["refinement"]["notes"] + assert notes and notes[0]["reason"] == "refinement_changed_status" + assert notes[0]["refinement_status"] == "desorbed" + + +def test_minima_directory_keeps_every_quench_result(tmp_path): + options, regions, registry, atoms = _setup() + _register(registry, atoms, energy=-0.50, replica=0, source="start", quench=1) + _register(registry, atoms, energy=-0.40, replica=0, quench=2) + _register(registry, atoms, energy=-0.20, replica=1, status="reacted", quench=3) + _register( + registry, + atoms, + energy=float("nan"), + replica=1, + status="quench_failed", + quench=4, + ) + + results = _build(options, regions, registry, {}, atoms, tmp_path=tmp_path) + + frames = read(tmp_path / "minima" / "all_minima.extxyz", index=":") + assert len(frames) == 4 + statuses = {frame.info["confsearch_status"] for frame in frames} + assert {"valid", "reacted", "quench_failed"} <= statuses + # A failed quench has a non-finite energy: the frame is kept without it. + failed = [f for f in frames if f.info["confsearch_status"] == "quench_failed"] + assert "energy_eV" not in failed[0].info + payload = json.loads((tmp_path / "minima" / "registry.json").read_text()) + assert payload["schema"] == "mliport.confsearch-registry/1" + assert results["diagnostics"]["registry"] == payload + + +def test_baseline_and_saturation_use_members_and_first_found_index(tmp_path): + options, regions, registry, atoms = _setup() + # One unique reached by a start quench (member origin) and one only by MD. + reached = _register( + registry, atoms, energy=-0.60, replica=0, source="start", quench=1 + ) + _register(registry, atoms, energy=-0.60, replica=1, quench=4) # same basin, MD + never = _register(registry, atoms, energy=-0.30, replica=0, quench=2) + assert reached.hit_count == 2 + + results = _build(options, regions, registry, {}, atoms, tmp_path=tmp_path) + + baseline = results["baseline"] + assert baseline["top_k_never_reached_by_start_quench"] == [never.unique_id] + best = results["ranking"]["unrefined"][0] + # first_found_fraction must use the *first-found* quench index (1), not the + # representative's own quench index. + assert best["first_found_quench_index"] == 1 + assert best["first_found_fraction"] == pytest.approx(1 / registry.total_records()) + saturation = results["diagnostics"]["saturation"] + assert saturation["best_hit_count"] == 2 + assert saturation["best_first_found_fraction"] == pytest.approx( + 1 / registry.total_records() + ) From 1682d92f0e8a3167253f977b25ae9b91a64ef204 Mon Sep 17 00:00:00 2001 From: hydrogen1222 Date: Mon, 26 Oct 2026 10:51:20 +0800 Subject: [PATCH 6/6] =?UTF-8?q?fix(confsearch):=20export=20candidates=20wh?= =?UTF-8?q?ose=20refinement=20failed=20(spec=20rev=206=20=C2=A710.3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tracking: #61 (spec revision 6, second review of PR #64) - A candidate inside the refinement window whose refinement did not converge is no longer dropped from the DFT deliverable: it is exported as `top/unrefined_NNN/` with its **quench** geometry and energy (flagged `refined: false`, `refinement_failed: true` in `artifacts.json`), next to the refined ranks, and a warning names it. This is the "silent deletion" failure mode section 9.3 warns about: a floppy chain that cannot reach 0.02 eV/A may still be the lowest quench minimum. - A refined entry's `flags` now come from the **refined** classification instead of the quench representative (chemisorbed/physisorbed and the far-field slab flag can change during refinement). Tests: two new cases in `test_refinement.py` (the failed-refinement candidate is exported with its quench energy/geometry and produces a warning; the refined entry's flags follow the refined classification). DATA IMPACT: no scientific record invalidated. Exports gain candidates that were previously missing; ranking order and energies are unchanged. Confsearch suite on CPU: 134 passed. --- mliport/mliport/confsearch/results.py | 53 +++++++++++++-- .../mliport/confsearch/test_refinement.py | 67 +++++++++++++++++++ 2 files changed, 116 insertions(+), 4 deletions(-) diff --git a/mliport/mliport/confsearch/results.py b/mliport/mliport/confsearch/results.py index f49941e3..4f6105aa 100644 --- a/mliport/mliport/confsearch/results.py +++ b/mliport/mliport/confsearch/results.py @@ -281,7 +281,10 @@ def _dedup_refined( "first_found_md_ps": float(source.first_found_md_ps), "first_found_quench_index": int(source.first_found_quench_index), "status": str(outcome.status), - "flags": tuple(source.flags), + # Spec 10.3 revision 6: a refined entry's flags come from the + # refined classification (chemisorbed/physisorbed and the + # far-field slab flag can all change during refinement). + "flags": tuple(outcome.classification.flags), "origin": source.representative.origin, } continue @@ -405,6 +408,8 @@ def _export_candidate( "rank": int(unique_id), "path": directory.name, "energy_eV": float(energy), + "refined": bool(entry.get("refined")), + "refinement_failed": bool(entry.get("refinement_failed")), "files": files, } @@ -709,6 +714,40 @@ def build_results( ) ) + # Spec 10.3 revision 6: a candidate in the refinement window whose + # refinement did not converge must still reach the DFT deliverable. It is + # exported with its quench geometry and energy as top/unrefined_NNN/ and a + # warning names it -- a failed refinement must never silently remove a top + # candidate. + unrefined_by_id = {int(entry["id"]): entry for entry in unrefined_entries} + unconverged_ids = sorted( + ( + int(unique_id) + for unique_id, outcome in refinements.items() + if not outcome.converged and int(unique_id) in unrefined_by_id + ), + key=lambda unique_id: ( + float(unrefined_by_id[unique_id]["energy_eV"]), + unique_id, + ), + ) + if regions is not None: + for position, unique_id in enumerate(unconverged_ids, start=1): + unique = uniques_by_id[unique_id] + entry = unrefined_by_id[unique_id] + exports.append( + _export_candidate( + output_dir / "top" / f"unrefined_{position:03d}", + unique_id=unique_id, + payload=unique.to_dict(), + atoms=unique.representative.atoms, + options=options, + regions=regions, + entry=entry, + energy=float(entry["energy_eV"]), + ) + ) + ranked_for_diagnostics = refined_entries or unrefined_entries saturation = _saturation(ranked_for_diagnostics, total_quenches=total_quenches) baseline_report = _baseline_report( @@ -717,9 +756,15 @@ def build_results( uniques_by_id=uniques_by_id, options=options, ) - warnings = list(warnings) + _status_warnings( - registry, options, ranked_for_diagnostics - ) + warnings = list(warnings) + if unconverged_ids: + warnings.append( + "refinement did not converge for candidate(s) " + + ", ".join(str(unique_id) for unique_id in unconverged_ids) + + "; they are exported as top/unrefined_NNN/ with their quench " + "geometry and energy (spec 10.3)" + ) + warnings += _status_warnings(registry, options, ranked_for_diagnostics) warnings = list(dict.fromkeys(warnings)) status = "completed" diff --git a/tests/mliport/mliport/confsearch/test_refinement.py b/tests/mliport/mliport/confsearch/test_refinement.py index 1b4615d1..b034c6dd 100644 --- a/tests/mliport/mliport/confsearch/test_refinement.py +++ b/tests/mliport/mliport/confsearch/test_refinement.py @@ -169,6 +169,73 @@ def test_unconverged_refinement_keeps_the_quench_result_and_flags_it(tmp_path): assert notes[0]["kept"] == "quench_result" +def test_unconverged_refinement_candidate_is_still_exported(tmp_path): + """Spec 10.3 revision 6: a failed refinement must not delete a candidate. + + The candidate keeps its quench geometry/energy, is exported as + `top/unrefined_NNN/` next to the refined ranks, and a warning names it. + """ + options, regions, registry, atoms = _setup() + failing = _register(registry, atoms, energy=-0.60, replica=0) + good = _register(registry, atoms, energy=-0.50, replica=1, quench=2) + refinements = { + failing.unique_id: _outcome( + failing.unique_id, + energy=float("nan"), + status="quench_failed", + converged=False, + ), + good.unique_id: _outcome(good.unique_id, energy=-0.70, atoms=atoms.copy()), + } + results = _build(options, regions, registry, refinements, atoms, tmp_path=tmp_path) + + assert [entry["id"] for entry in results["ranking"]["refined"]] == [good.unique_id] + exported = {item["path"]: item for item in results["exports"]} + assert "rank_001" in exported and exported["rank_001"]["refined"] is True + assert "unrefined_001" in exported + assert exported["unrefined_001"]["refined"] is False + assert exported["unrefined_001"]["refinement_failed"] is True + # The unrefined export keeps the *quench* geometry and energy. + assert exported["unrefined_001"]["energy_eV"] == pytest.approx(-0.60) + unrefined = (tmp_path / "top" / "unrefined_001").resolve() + payload = json.loads((unrefined / "minimum.json").read_text()) + assert payload["export"]["ranking"]["energy_eV"] == pytest.approx(-0.60) + assert (unrefined / "POSCAR").is_file() + assert any("did not converge" in warning for warning in results["warnings"]) + + +def test_refined_entry_flags_come_from_the_refined_classification(tmp_path): + """Spec 10.3 revision 6: flags follow the refined classification.""" + options, regions, registry, atoms = _setup() + unique = _register(registry, atoms, energy=-0.50, replica=0) + outcome = _outcome(unique.unique_id, energy=-0.60, atoms=atoms.copy()) + # The refined classification says physisorbed + far-field slab change. + outcome = results_module.RefinementOutcome( + unique_id=outcome.unique_id, + status=outcome.status, + energy_eV=outcome.energy_eV, + fmax_eV_A=outcome.fmax_eV_A, + steps=outcome.steps, + atoms=outcome.atoms, + classification=fake_classification( + status="valid", flags=("far_field_slab_changed",) + ), + converged=True, + ) + results = _build( + options, + regions, + registry, + {unique.unique_id: outcome}, + atoms, + tmp_path=tmp_path, + ) + entry = results["ranking"]["refined"][0] + # The quench representative was flagged "physisorbed"; the refined entry + # must carry the refined classification's flags instead. + assert entry["flags"] == ["far_field_slab_changed"] + + def test_refinement_status_change_removes_the_entry_with_a_reason(tmp_path): options, regions, registry, atoms = _setup() unique = _register(registry, atoms, energy=-0.50, replica=0)