xtalate 0.1.0.dev0__py3-none-any.whl

xtalate/recovery/scenarios.py

@@ -0,0 +1,86 @@
+"""Recovery scenario catalog: hazard classes and per-scenario option computation (Part 4 §3).
+
+Every conversion hazard the pre-flight diff detects (Part 3 §4.3) falls into exactly one of
+three hazard classes (Part 4 §3.1), and the class governs what the Recovery Engine may do:
+
+* **bulk reductive** — information the target cannot carry is dropped wholesale; no scientific
+  choice selects *which* survives. Never a recovery scenario: it is reported as ``removed`` and
+  (in permissive mode) proceeds without a choice.
+* **selective reductive** — data is dropped but *which subset is kept changes the scientific
+  meaning*; Xtalate will not choose unrecorded. Requires an explicit choice, records an
+  ``Assumption``, produces **no** ``supplied`` entry (the kept data is genuine source data).
+* **fabricative** — information required/offered by the target does not exist in the source; it
+  must be *created*. Requires an explicit choice, records an ``Assumption`` **and** a ``supplied``
+  entry. Never automatic in any mode (**P4**).
+
+The bright line is deliberately discrete (a three-value enum, not a risk scale) so no mode or
+future convenience can make Xtalate invent scientific data or silently choose which real data
+to discard (Part 4 §3.1, "Alternative rejected: a single risk-level scale").
+
+**v0.1 scope (review §4.4 trim).** Two scenarios resolve: ``missing_lattice`` (fabricative) and
+``frame_selection`` (selective reductive), preset-only. Option lists are **computed**, not static
+(Part 4 §3.3): a choice that is not scientifically coherent for the concrete source/target pair,
+or not implemented in v0.1, is honestly absent from ``available_options`` rather than offered and
+then refused. ``missing_species``/``missing_velocities``/``missing_masses``/``missing_energy``/
+``truncate_corrupt_tail``/``constraint_representation`` are catalogued in the spec but not
+triggered by any v0.1 (source, target) pair; they attach at this same seam later (**P6**).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+@dataclass
+class UnresolvedScenario:
+    """A recovery the pre-flight diff detected but has not resolved (Part 4 §3).
+
+    Emitted by ``conversion.preflight`` (conversion → recovery is a legal downward import) and
+    consumed by ``RecoveryEngine.resolve``; it lives here, in the recovery layer, so both sides
+    share one descriptor. ``path`` is the canonical field a *fabricative* scenario would supply
+    (``None`` for a selective-reductive one like ``frame_selection``)."""
+
+    scenario: str  # e.g. "missing_lattice" | "frame_selection".
+    path: str | None = None
+    detail: str | None = None
+
+
+class HazardClass(StrEnum):
+    """The three-way classification of Part 4 §3.1. Discrete by design."""
+
+    BULK_REDUCTIVE = "bulk_reductive"
+    SELECTIVE_REDUCTIVE = "selective_reductive"
+    FABRICATIVE = "fabricative"
+
+
+# The v0.1 resolvable scenarios and their hazard class. A scenario absent here is not one the
+# Recovery Engine resolves in v0.1 (it either does not arise for the implemented formats, or is a
+# bulk-reductive drop handled by the mode table, not by a choice).
+SCENARIO_HAZARD: dict[str, HazardClass] = {
+    "frame_selection": HazardClass.SELECTIVE_REDUCTIVE,
+    "missing_lattice": HazardClass.FABRICATIVE,
+}
+
+
+def available_options(scenario: str, *, target_can_be_nonperiodic: bool = False) -> list[str]:
+    """The *computed* option list for ``scenario`` (Part 4 §3.3), honestly excluding choices not
+    offered for this pair or not implemented in v0.1.
+
+    ``missing_lattice``: ``manual_input`` (user supplies a 3×3 lattice) and ``bounding_box``
+    (axis-aligned box of the selected frame's positions + ``padding_ang``). ``non_periodic`` is
+    offered only when the target can express ``pbc=(F,F,F)`` — never for POSCAR, whose ``cell.pbc``
+    is PARTIAL/fully-periodic-only (Part 3 §4.2). ``upload_reference`` (lattice from a second file)
+    needs a second input stream and is out of v0.1 scope, so it is honestly not listed.
+
+    ``frame_selection``: ``first`` / ``last`` / ``index``. ``split_all`` (one file per frame)
+    needs a multi-file output mode absent from the v0.1 library API, so it is not listed.
+    """
+    if scenario == "missing_lattice":
+        options = ["manual_input", "bounding_box"]
+        if target_can_be_nonperiodic:
+            options.append("non_periodic")
+        return options
+    if scenario == "frame_selection":
+        return ["first", "last", "index"]
+    return []

xtalate/registry.py

@@ -0,0 +1,28 @@
+"""``default_registry()`` — the standard first-party registry (MASTER_SPEC Part 3 §7.1).
+
+A convenience factory that registers every built-in parser and exporter into one
+:class:`~xtalate.capabilities.Registry`, so callers (the CLI, examples, and any embedder)
+get the full v0.1 format set without hand-wiring it. This is the "explicit first-party
+registration list" the spec calls sufficient before entry-point plugin discovery exists
+(Part 3 §7.1); third-party plugins attach at the same registry later (**P6**).
+
+Lives at the package root, not in ``capabilities``: the registry *machinery* must not depend on
+the concrete parsers/exporters (that would invert the import graph), so the wiring that pulls
+them together sits above both — the same reason the CLI, not the engine, composes the pipeline.
+"""
+
+from __future__ import annotations
+
+from xtalate.capabilities import Registry
+from xtalate.exporters import builtin_exporters
+from xtalate.parsers import builtin_parsers
+
+
+def default_registry() -> Registry:
+    """A fresh :class:`Registry` with all built-in parsers and exporters registered."""
+    registry = Registry()
+    for parser in builtin_parsers():
+        registry.register_parser(parser)
+    for exporter in builtin_exporters():
+        registry.register_exporter(exporter)
+    return registry

xtalate/schema/__init__.py

@@ -0,0 +1,40 @@
+"""Canonical Model — the single in-memory/serialized representation (MASTER_SPEC Part 2).
+
+Depends on nothing else in the package (lowest layer of the P2 dependency graph, Part 1
+§5.1). Implemented in M1.
+"""
+
+from xtalate.schema.models import (
+    SCHEMA_VERSION,
+    AtomsBlock,
+    CanonicalObject,
+    Cell,
+    Constraint,
+    ConversionRecord,
+    Dynamics,
+    Electronic,
+    Frame,
+    Provenance,
+    SimulationMetadata,
+    TrajectoryMetadata,
+    UserMetadata,
+)
+from xtalate.schema.presence import PathPresence, PresenceMap
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "AtomsBlock",
+    "CanonicalObject",
+    "Cell",
+    "Constraint",
+    "ConversionRecord",
+    "Dynamics",
+    "Electronic",
+    "Frame",
+    "PathPresence",
+    "PresenceMap",
+    "Provenance",
+    "SimulationMetadata",
+    "TrajectoryMetadata",
+    "UserMetadata",
+]

xtalate/schema/arrays.py

@@ -0,0 +1,115 @@
+"""NumPy array field types for the Canonical Model (MASTER_SPEC Part 2 §1, §3).
+
+Numeric array fields (``positions``, ``lattice_vectors``, ``velocities``, ...) are
+``np.ndarray`` of ``float64`` in memory — for zero-copy interop with the array-native
+scientific libraries (ASE) the pipeline delegates to — and serialize to **nested JSON
+lists**. This module provides the pydantic v2 custom types that enforce that contract.
+
+Design (DECISIONS.md D8):
+
+* In memory: ``np.ndarray``, dtype ``float64``, always a fresh copy (inputs are never
+  aliased, so a caller mutating the array it passed in cannot corrupt the model).
+* Serialized (JSON mode): nested lists via ``ndarray.tolist()`` — Python's default
+  shortest-round-tripping float ``repr``, making ``float64 -> JSON -> float64`` lossless.
+* Golden equality is defined as *deserialize-then-compare* (``np.array_equal`` on the
+  parsed values), never a comparison of serialized text — see the round-trip tests.
+
+Each type validates only its **local** shape (rank and any fixed axis, e.g. the trailing
+``3`` of an ``(N, 3)`` array). Cross-field agreement — that ``positions``,
+``velocities`` and ``forces`` share one ``N``, that ``N`` is constant across frames — is a
+*model*-level invariant enforced by validators on the models (§3.3, §3.2), not here: a
+lone array cannot know the object's atom count.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+import numpy as np
+from numpy.typing import NDArray
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+
+@dataclass(frozen=True)
+class _ArraySpec:
+    """pydantic-v2 metadata object describing a ``float64`` ndarray field.
+
+    Placed inside ``Annotated[...]``; pydantic calls ``__get_pydantic_core_schema__``
+    to obtain the validate/serialize schema for the annotated field.
+    """
+
+    # Exact rank, or None for "any rank >= 1" (the custom-array case, Part 2 §3.10,
+    # whose trailing shape is arbitrary and whose first-axis == N/F is a model check).
+    ndim: int | None
+    # (axis_index, required_size) pairs, e.g. (1, 3) for the trailing 3 of an (N, 3) array.
+    fixed_axes: tuple[tuple[int, int], ...] = ()
+
+    def _shape_label(self) -> str:
+        if self.ndim is None:
+            return "(first-axis, ...)"
+        dims = ["?"] * self.ndim
+        for axis, size in self.fixed_axes:
+            dims[axis] = str(size)
+        return "(" + ", ".join(dims) + ")"
+
+    def _validate(self, value: Any) -> NDArray[np.float64]:
+        if isinstance(value, np.ndarray) and value.dtype == np.float64:
+            # Copy so a later mutation of the caller's array cannot reach into the model.
+            arr = value.copy()
+        else:
+            try:
+                arr = np.asarray(value, dtype=np.float64)
+            except (ValueError, TypeError) as exc:
+                raise ValueError(
+                    f"expected a real-valued array coercible to float64, got {value!r}"
+                ) from exc
+        if self.ndim is None:
+            if arr.ndim < 1:
+                raise ValueError(
+                    f"expected an array of rank >= 1 {self._shape_label()}, got a 0-D array"
+                )
+        elif arr.ndim != self.ndim:
+            raise ValueError(
+                f"expected a {self.ndim}-D array of shape {self._shape_label()}, "
+                f"got a {arr.ndim}-D array of shape {arr.shape}"
+            )
+        for axis, size in self.fixed_axes:
+            if arr.shape[axis] != size:
+                raise ValueError(
+                    f"expected axis {axis} of length {size} "
+                    f"(shape {self._shape_label()}), got shape {arr.shape}"
+                )
+        if not np.all(np.isfinite(arr)):
+            raise ValueError("array contains non-finite values (nan/inf); refusing")
+        return arr
+
+    def __get_pydantic_core_schema__(
+        self, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        return core_schema.no_info_plain_validator_function(
+            self._validate,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda arr: arr.tolist(),
+                when_used="json",
+            ),
+        )
+
+
+# --- Concrete field types, named after their canonical shapes (Part 2 §3). -----------
+
+#: ``(N, 3)`` — per-atom Cartesian triples: positions, velocities, forces.
+ArrayN3 = Annotated[NDArray[np.float64], _ArraySpec(ndim=2, fixed_axes=((1, 3),))]
+
+#: ``(N,)`` — per-atom scalars: masses, charges, magnetic moments.
+ArrayN = Annotated[NDArray[np.float64], _ArraySpec(ndim=1)]
+
+#: ``(3, 3)`` — lattice vectors (rows a, b, c) and the stress tensor.
+Array33 = Annotated[NDArray[np.float64], _ArraySpec(ndim=2, fixed_axes=((0, 3), (1, 3)))]
+
+#: First dimension ``N`` (per-atom), any trailing shape — ``user_metadata.custom_per_atom``.
+ArrayNx = Annotated[NDArray[np.float64], _ArraySpec(ndim=None)]
+
+#: First dimension ``F`` (per-frame), any trailing shape — ``user_metadata.custom_per_frame``.
+ArrayFx = Annotated[NDArray[np.float64], _ArraySpec(ndim=None)]

xtalate/schema/elements.py

@@ -0,0 +1,150 @@
+"""Chemical element symbol <-> atomic number table (MASTER_SPEC Part 2 §3.3).
+
+``AtomsBlock`` carries both ``symbols`` and ``atomic_numbers``; the numbers are derived
+from the symbols at construction (§3.3) and validated for agreement. This module is the
+single source of that mapping. The reserved pseudo-element ``"X"`` (unknown species,
+atomic number 0) is valid, but a parser emitting it must accompany it with a warning
+(§3.3) — that policy lives in the parsers, not here.
+"""
+
+from __future__ import annotations
+
+# Symbols indexed by atomic number: SYMBOLS[Z] == symbol. Index 0 is the reserved
+# unknown-species marker "X" (§3.3). Covers Z = 1..118 (all IUPAC-named elements).
+_SYMBOLS: tuple[str, ...] = (
+    "X",
+    "H",
+    "He",
+    "Li",
+    "Be",
+    "B",
+    "C",
+    "N",
+    "O",
+    "F",
+    "Ne",
+    "Na",
+    "Mg",
+    "Al",
+    "Si",
+    "P",
+    "S",
+    "Cl",
+    "Ar",
+    "K",
+    "Ca",
+    "Sc",
+    "Ti",
+    "V",
+    "Cr",
+    "Mn",
+    "Fe",
+    "Co",
+    "Ni",
+    "Cu",
+    "Zn",
+    "Ga",
+    "Ge",
+    "As",
+    "Se",
+    "Br",
+    "Kr",
+    "Rb",
+    "Sr",
+    "Y",
+    "Zr",
+    "Nb",
+    "Mo",
+    "Tc",
+    "Ru",
+    "Rh",
+    "Pd",
+    "Ag",
+    "Cd",
+    "In",
+    "Sn",
+    "Sb",
+    "Te",
+    "I",
+    "Xe",
+    "Cs",
+    "Ba",
+    "La",
+    "Ce",
+    "Pr",
+    "Nd",
+    "Pm",
+    "Sm",
+    "Eu",
+    "Gd",
+    "Tb",
+    "Dy",
+    "Ho",
+    "Er",
+    "Tm",
+    "Yb",
+    "Lu",
+    "Hf",
+    "Ta",
+    "W",
+    "Re",
+    "Os",
+    "Ir",
+    "Pt",
+    "Au",
+    "Hg",
+    "Tl",
+    "Pb",
+    "Bi",
+    "Po",
+    "At",
+    "Rn",
+    "Fr",
+    "Ra",
+    "Ac",
+    "Th",
+    "Pa",
+    "U",
+    "Np",
+    "Pu",
+    "Am",
+    "Cm",
+    "Bk",
+    "Cf",
+    "Es",
+    "Fm",
+    "Md",
+    "No",
+    "Lr",
+    "Rf",
+    "Db",
+    "Sg",
+    "Bh",
+    "Hs",
+    "Mt",
+    "Ds",
+    "Rg",
+    "Cn",
+    "Nh",
+    "Fl",
+    "Mc",
+    "Lv",
+    "Ts",
+    "Og",
+)
+
+#: symbol -> atomic number (Z). "X" maps to 0.
+SYMBOL_TO_Z: dict[str, int] = {sym: z for z, sym in enumerate(_SYMBOLS)}
+
+#: The reserved symbol for an unidentified species (§3.3).
+UNKNOWN_SYMBOL = "X"
+
+
+def is_valid_symbol(symbol: str) -> bool:
+    """True if ``symbol`` is an element symbol or the reserved ``"X"`` (§3.3)."""
+    return symbol in SYMBOL_TO_Z
+
+
+def atomic_number(symbol: str) -> int:
+    """Atomic number for ``symbol``. Raises ``KeyError`` for an unknown symbol."""
+    return SYMBOL_TO_Z[symbol]