xtalate 0.1.0.dev0__py3-none-any.whl

xtalate/parsers/xyz.py

@@ -0,0 +1,286 @@
+"""Plain XYZ parser (MASTER_SPEC Part 3 §3, §8.1).
+
+Hand-rolled (DECISIONS.md D7): the grammar is trivial and hand-rolling avoids importing a
+library that would invent defaults we would then have to launder back into absences. XYZ
+carries exactly three things — element symbols, Cartesian positions (Å), and a free-text
+comment line per frame — and *nothing* else. Every other canonical field is therefore
+``None`` on the resulting object; that is the absence convention (Part 2 §2), not a gap to
+be filled.
+
+Grammar (one or more concatenated frames)::
+
+    <atom count N>
+    <comment: free text, may be empty>
+    <symbol> <x> <y> <z>        # N lines
+    ...                          # next frame's count, or EOF
+
+Comment lines are information (they routinely hold frame labels / energies as free text),
+so they are carried verbatim — one per frame — under
+``user_metadata.custom_per_frame["xyz:comment"]`` (Part 3 §6.1 carry-through rule).
+"""
+
+from __future__ import annotations
+
+from typing import BinaryIO
+
+import numpy as np
+from pydantic import JsonValue
+
+from xtalate.parsers._common import build_provenance
+from xtalate.schema import (
+    AtomsBlock,
+    CanonicalObject,
+    Frame,
+    TrajectoryMetadata,
+    UserMetadata,
+)
+from xtalate.schema.elements import is_valid_symbol
+from xtalate.sdk import (
+    CapabilityLevel,
+    FieldCapability,
+    FormatCapabilities,
+    ParseError,
+    ParseIssue,
+    ParseResult,
+    ParserPlugin,
+)
+
+FORMAT_ID = "xyz"
+_COMMENT_KEY = "xyz:comment"
+# extXYZ (an XYZ superset, Part 3 §3 n.2) puts key=value metadata on the comment line;
+# these markers let plain XYZ yield to a future extXYZ parser (M3c) on such files (§6.1).
+_EXTXYZ_MARKERS = ("Lattice=", "Properties=")
+
+
+def _looks_like_coordinate(line: str) -> bool:
+    """True if ``line`` is ``<symbol> <float> <float> <float>`` (the XYZ atom row)."""
+    parts = line.split()
+    if len(parts) < 4:
+        return False
+    if not is_valid_symbol(parts[0]):
+        return False
+    try:
+        float(parts[1]), float(parts[2]), float(parts[3])
+    except ValueError:
+        return False
+    return True
+
+
+class XyzParser(ParserPlugin):
+    format_id = FORMAT_ID
+    format_name = "Plain XYZ"
+    version = "0.1.0"
+    file_extensions = (".xyz",)
+
+    def sniff(self, head: bytes, filename: str | None) -> float:
+        # Cheap, never raises (§2): structural check on the first frame only.
+        text = head.decode("utf-8", errors="replace")
+        lines = text.splitlines()
+        if not lines:
+            return 0.0
+        try:
+            count = int(lines[0].strip())
+        except ValueError:
+            return 0.0  # first line is not an atom count — not XYZ
+        if count <= 0:
+            return 0.0
+        extxyz_comment = False
+        if len(lines) < 3:
+            # Header parses but we cannot see a coordinate row (tiny head); weak signal,
+            # leaned on the .xyz filename hint if present.
+            score = 0.4
+        else:
+            score = 0.9 if _looks_like_coordinate(lines[2]) else 0.3
+            extxyz_comment = any(marker in lines[1] for marker in _EXTXYZ_MARKERS)
+        if filename is not None and filename.lower().endswith(".xyz"):
+            score = max(score, 0.7)
+        if extxyz_comment:
+            # extXYZ territory (a superset): cap last — after the filename hint, which does
+            # not distinguish the two — so the more-expressive parser wins when registered.
+            score = min(score, 0.6)
+        return score
+
+    def parse(self, stream: BinaryIO, *, filename: str | None) -> ParseResult:
+        lines = stream.read().decode("utf-8").splitlines()
+        frames: list[Frame] = []
+        comments: list[JsonValue] = []
+        i = 0
+        n_lines = len(lines)
+
+        # Skip any leading blank lines, but a wholly blank/empty file is a parse error.
+        while i < n_lines and lines[i].strip() == "":
+            i += 1
+        if i >= n_lines:
+            raise ParseError(
+                [ParseIssue(severity="error", code="XYZ_EMPTY", message="file contains no frames")]
+            )
+
+        frame_index = 0
+        while i < n_lines:
+            header = lines[i].strip()
+            if header == "":
+                i += 1
+                continue  # tolerate blank separators between frames
+            try:
+                count = int(header)
+            except ValueError as exc:
+                raise ParseError(
+                    [
+                        ParseIssue(
+                            severity="error",
+                            code="XYZ_MALFORMED_HEADER",
+                            message=f"expected an integer atom count, found {header!r}",
+                            location=f"line {i + 1}",
+                        )
+                    ]
+                ) from exc
+            if count <= 0:
+                raise ParseError(
+                    [
+                        ParseIssue(
+                            severity="error",
+                            code="XYZ_MALFORMED_HEADER",
+                            message=f"atom count must be positive, found {count}",
+                            location=f"line {i + 1}",
+                        )
+                    ]
+                )
+            # Comment line (may be empty; the line must still exist).
+            if i + 1 >= n_lines:
+                raise ParseError(
+                    [
+                        ParseIssue(
+                            severity="error",
+                            code="XYZ_INCONSISTENT_ATOM_COUNT",
+                            message=(
+                                f"frame {frame_index} declares {count} atoms but the file ends "
+                                "before its comment line and coordinates"
+                            ),
+                            location=f"frame {frame_index}",
+                            recovery_hint="truncate_at_last_valid_frame",
+                        )
+                    ]
+                )
+            comment = lines[i + 1]
+            body_start = i + 2
+            body_end = body_start + count
+            if body_end > n_lines:
+                found = n_lines - body_start
+                raise ParseError(
+                    [
+                        ParseIssue(
+                            severity="error",
+                            code="XYZ_INCONSISTENT_ATOM_COUNT",
+                            message=(
+                                f"frame {frame_index} declares {count} atoms but only {found} "
+                                "coordinate lines are present before end of file"
+                            ),
+                            location=f"frame {frame_index}",
+                            recovery_hint="truncate_at_last_valid_frame",
+                        )
+                    ]
+                )
+
+            symbols: list[str] = []
+            positions: list[list[float]] = []
+            for j in range(body_start, body_end):
+                parts = lines[j].split()
+                if len(parts) < 4:
+                    # Fewer tokens than "<symbol> x y z" means the declared count is wrong:
+                    # a coordinate row is missing (Part 3 §5 rule 4 — mid-file corruption).
+                    raise ParseError(
+                        [
+                            ParseIssue(
+                                severity="error",
+                                code="XYZ_INCONSISTENT_ATOM_COUNT",
+                                message=(
+                                    f"frame {frame_index} declares {count} atoms but line "
+                                    f"{j + 1} is not a '<symbol> x y z' coordinate row: "
+                                    f"{lines[j]!r}"
+                                ),
+                                location=f"frame {frame_index}",
+                                recovery_hint="truncate_at_last_valid_frame",
+                            )
+                        ]
+                    )
+                symbol = parts[0]
+                if not is_valid_symbol(symbol):
+                    raise ParseError(
+                        [
+                            ParseIssue(
+                                severity="error",
+                                code="XYZ_INVALID_SYMBOL",
+                                message=(
+                                    f"unknown element symbol {symbol!r} at line {j + 1} "
+                                    "(use 'X' for a genuinely unknown species, Part 2 §3.3)"
+                                ),
+                                location=f"line {j + 1}",
+                            )
+                        ]
+                    )
+                try:
+                    xyz = [float(parts[1]), float(parts[2]), float(parts[3])]
+                except ValueError as exc:
+                    raise ParseError(
+                        [
+                            ParseIssue(
+                                severity="error",
+                                code="XYZ_MALFORMED_COORDINATE",
+                                message=f"non-numeric coordinate at line {j + 1}: {lines[j]!r}",
+                                location=f"line {j + 1}",
+                            )
+                        ]
+                    ) from exc
+                symbols.append(symbol)
+                positions.append(xyz)
+
+            frames.append(
+                Frame(
+                    index=frame_index,
+                    atoms=AtomsBlock(symbols=symbols, positions=np.asarray(positions, dtype=float)),
+                )
+            )
+            comments.append(comment)
+            frame_index += 1
+            i = body_end
+
+        # Comment lines are information — one per frame, carried verbatim (§6.1).
+        user_metadata = UserMetadata(custom_per_frame={_COMMENT_KEY: comments})
+        provenance = build_provenance(
+            format_id=FORMAT_ID,
+            filename=filename,
+            original_coordinate_system="cartesian",
+            source_units={"positions": "angstrom"},
+            parse_notes=[
+                "comment lines preserved in user_metadata.custom_per_frame['xyz:comment']"
+            ],
+        )
+        # A single-frame XYZ is a static structure (trajectory=None, Part 2 §3.2); multiple
+        # frames form a trajectory whose source declares no time base (timestep=None, §8.1).
+        trajectory = None if len(frames) == 1 else TrajectoryMetadata(timestep=None)
+        canonical = CanonicalObject(
+            frames=frames,
+            trajectory=trajectory,
+            provenance=provenance,
+            user_metadata=user_metadata,
+        )
+        return ParseResult(canonical=canonical)
+
+    def capabilities(self) -> FormatCapabilities:
+        full = FieldCapability(level=CapabilityLevel.FULL)
+        return FormatCapabilities(
+            format_id=FORMAT_ID,
+            format_name=self.format_name,
+            direction="read",
+            fields={
+                "atoms.symbols": full,
+                "atoms.positions": full,
+                "user_metadata.custom_per_frame": FieldCapability(
+                    level=CapabilityLevel.FULL, notes="Free-text comment line, one per frame."
+                ),
+            },
+            max_frames=None,
+            required_fields=[],
+            native_coordinate_system="cartesian",
+            lossy_notes=[],
+        )

xtalate/recovery/__init__.py

@@ -0,0 +1,41 @@
+"""Recovery Engine — explicit, never-guessed handling of target-required-but-absent fields.
+
+Implements the three-way hazard model and the fabricative bright line (Part 4 §3):
+every applied recovery records an ``Assumption`` (and a ``supplied`` entry when it
+fabricates); no default is ever applied silently. v0.1 scenarios: ``missing_lattice``
+and ``frame_selection`` (preset-only). Implemented in M5.
+
+Sits below ``conversion`` in the import graph (Part 1 §5.1), so it returns plain result
+types (``AppliedAssumption`` etc.) the ``ConversionEngine`` maps onto the Conversion Report;
+it never imports ``conversion``.
+"""
+
+from __future__ import annotations
+
+from xtalate.recovery.engine import (
+    AppliedAssumption,
+    FrameDrop,
+    RecoveryEngine,
+    RecoveryError,
+    RecoveryResult,
+    SuppliedField,
+)
+from xtalate.recovery.scenarios import (
+    SCENARIO_HAZARD,
+    HazardClass,
+    UnresolvedScenario,
+    available_options,
+)
+
+__all__ = [
+    "SCENARIO_HAZARD",
+    "AppliedAssumption",
+    "FrameDrop",
+    "HazardClass",
+    "RecoveryEngine",
+    "RecoveryError",
+    "RecoveryResult",
+    "SuppliedField",
+    "UnresolvedScenario",
+    "available_options",
+]

xtalate/recovery/engine.py

@@ -0,0 +1,321 @@
+"""The Recovery Engine — explicit, never-guessed resolution of conversion hazards (Part 4 §3).
+
+Given the scenarios the pre-flight diff could not resolve and a set of caller-supplied choices
+(v0.1 is **preset-only**, DECISIONS.md D22), the engine either resolves *every* scenario — each
+producing exactly one recorded ``Assumption`` — or resolves **none** and reports the refusal
+(Part 4 §3.2: "refusal is the default"; there is no timeout-triggered or per-scenario silent
+fallback). It never applies a choice the caller did not name (**P4**).
+
+Layering (Part 1 §5.1). This module sits *below* ``conversion`` in the import graph, so it may
+not import the Conversion Report schema (``conversion.report``). It returns its own plain result
+types (``AppliedAssumption``, ``SuppliedField``, ``FrameDrop``); the ``ConversionEngine`` (top
+layer) maps them onto ``Assumption``/``SuppliedEntry``/``RemovedEntry`` for the report. It depends
+only on ``schema``.
+
+**Dependency ordering (Part 4 §3.3).** ``frame_selection`` is resolved before ``missing_lattice``
+because a ``bounding_box`` lattice is computed on the *selected* frame's positions. Assumptions are
+numbered ``A1, A2, …`` in application order, matching the worked example (A1 = frame_selection,
+A2 = missing_lattice; Part 4 §5).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from xtalate.recovery.scenarios import (
+    SCENARIO_HAZARD,
+    UnresolvedScenario,
+    available_options,
+)
+from xtalate.schema import AtomsBlock, CanonicalObject, Cell, Frame
+
+# Resolution order (Part 4 §3.3): a bounding box is computed on the frame chosen by
+# frame_selection, so frame_selection must run first.
+_DEP_ORDER = ("frame_selection", "missing_lattice")
+
+
+class RecoveryError(ValueError):
+    """A preset named an option that is not offered for this pair, or omitted a required
+    parameter. Distinct from a *refusal* (no choice supplied): a refusal is a legitimate
+    conversion outcome (Part 4 §4); an invalid preset is a caller error."""
+
+
+@dataclass
+class SuppliedField:
+    """One canonical field a fabricative recovery wrote into the object (Part 4 §2, `supplied`)."""
+
+    path: str
+    detail: str | None = None
+
+
+@dataclass
+class FrameDrop:
+    """The `removed` accounting for a selective-reductive frame reduction (Part 4 §5 removed[0])."""
+
+    path: str
+    reason: str
+    detail: str
+
+
+@dataclass
+class AppliedAssumption:
+    """One recorded recovery decision (Part 4 §2 `Assumption`), plus its field-level effects.
+
+    ``supplied`` is non-empty only for fabricative scenarios; ``removed`` only for selective-
+    reductive ones. The two never overlap — the bright line of Part 4 §3.1."""
+
+    id: str
+    scenario: str
+    choice: str
+    parameters: dict[str, Any]
+    origin: str  # "preset" | "user". v0.1 is preset-only (D22).
+    description: str
+    supplied: list[SuppliedField] = field(default_factory=list)
+    removed: list[FrameDrop] = field(default_factory=list)
+
+
+@dataclass
+class RecoveryResult:
+    """Outcome of ``resolve``. ``canonical`` is ``None`` iff the conversion is refused, in which
+    case ``unresolved`` lists the scenarios that lacked a choice (Part 4 §3.2)."""
+
+    canonical: CanonicalObject | None
+    assumptions: list[AppliedAssumption]
+    unresolved: list[UnresolvedScenario]
+
+
+class RecoveryEngine:
+    def resolve(
+        self,
+        source: CanonicalObject,
+        scenarios: list[UnresolvedScenario],
+        recovery_choices: dict[str, dict[str, Any]],
+        *,
+        origin: str = "preset",
+    ) -> RecoveryResult:
+        """Resolve every scenario in ``scenarios`` using ``recovery_choices`` (keyed by scenario
+        code, each ``{"choice": str, "parameters": {...}}``), or refuse if any lacks a choice.
+
+        Resolution is all-or-nothing: a single missing choice refuses the whole conversion, so
+        no partially-recovered object is ever produced (a half-recovered structure presented as
+        complete would be the very silent failure this engine exists to prevent)."""
+        # A scenario is unresolvable if v0.1 does not know how to resolve it, or the caller
+        # supplied no choice for it. Both refuse (Part 4 §3.2).
+        unresolved = [
+            s
+            for s in scenarios
+            if s.scenario not in SCENARIO_HAZARD or s.scenario not in recovery_choices
+        ]
+        if unresolved:
+            return RecoveryResult(canonical=None, assumptions=[], unresolved=unresolved)
+
+        working = source
+        assumptions: list[AppliedAssumption] = []
+        selected_source_index = 0  # threaded from frame_selection into bounding_box's description.
+        counter = 1
+        for scenario_code in _DEP_ORDER:
+            match = next((s for s in scenarios if s.scenario == scenario_code), None)
+            if match is None:
+                continue
+            aid = f"A{counter}"
+            counter += 1
+            choice = recovery_choices[scenario_code]
+            if scenario_code == "frame_selection":
+                working, applied, selected_source_index = _apply_frame_selection(
+                    working, aid, choice, origin
+                )
+            else:  # missing_lattice
+                working, applied = _apply_missing_lattice(
+                    working, aid, choice, origin, computed_on_frame=selected_source_index
+                )
+            assumptions.append(applied)
+
+        return RecoveryResult(canonical=working, assumptions=assumptions, unresolved=[])
+
+
+def _choice_code(choice: dict[str, Any], scenario: str) -> str:
+    code = choice.get("choice")
+    if not isinstance(code, str) or code not in available_options(scenario):
+        raise RecoveryError(
+            f"{scenario!r}: choice {code!r} is not an offered option "
+            f"{available_options(scenario)!r}"
+        )
+    return code
+
+
+def _apply_frame_selection(
+    canonical: CanonicalObject, aid: str, choice: dict[str, Any], origin: str
+) -> tuple[CanonicalObject, AppliedAssumption, int]:
+    """Reduce a multi-frame object to the single chosen frame (selective reductive, Part 4 §3.1).
+
+    Records an ``Assumption`` and a ``FrameDrop`` (the dropped frames as a `removed` entry) but
+    **no** ``SuppliedField`` — the retained frame is genuine source data, not fabricated."""
+    code = _choice_code(choice, "frame_selection")
+    params = choice.get("parameters", {}) or {}
+    n = canonical.frame_count
+    if code == "first":
+        index = 0
+    elif code == "last":
+        index = n - 1
+    else:  # "index"
+        raw = params.get("frame_index")
+        if not isinstance(raw, int) or isinstance(raw, bool) or not (0 <= raw < n):
+            raise RecoveryError(
+                f"frame_selection 'index' needs an in-range integer frame_index (0..{n - 1}), "
+                f"got {raw!r}"
+            )
+        index = raw
+
+    selected = canonical.frames[index]
+    reduced_frame = selected.model_copy(update={"index": 0})
+    # custom_per_frame arrays carry first-dim = frame count (Part 2 §3.10); slice to the kept frame.
+    um = canonical.user_metadata
+    sliced_per_frame: dict[str, Any] = {}
+    for key, val in um.custom_per_frame.items():
+        sliced_per_frame[key] = (
+            val[index : index + 1] if isinstance(val, np.ndarray) else [val[index]]
+        )
+    new_um = um.model_copy(update={"custom_per_frame": sliced_per_frame})
+
+    reduced = canonical.model_copy(
+        update={"frames": [reduced_frame], "trajectory": None, "user_metadata": new_um}
+    )
+    dropped = n - 1
+    assumption = AppliedAssumption(
+        id=aid,
+        scenario="frame_selection",
+        choice=code,
+        parameters={"frame_index": index},
+        origin=origin,
+        description=(
+            f"Frame {index} of {n} selected for the single-structure target; the other "
+            f"{dropped} frame(s) are dropped. Which frame survives changes the scientific "
+            "meaning of the output, so this is a recorded choice, not a silent default."
+        ),
+        removed=[
+            FrameDrop(
+                path="atoms.positions",
+                reason="Target format stores a single structure (max_frames = 1).",
+                detail=f"{dropped} of {n} frames dropped; frame {index} retained per {aid}.",
+            )
+        ],
+    )
+    return reduced, assumption, index
+
+
+def _apply_missing_lattice(
+    canonical: CanonicalObject,
+    aid: str,
+    choice: dict[str, Any],
+    origin: str,
+    *,
+    computed_on_frame: int,
+) -> tuple[CanonicalObject, AppliedAssumption]:
+    """Fabricate the target-required lattice the source lacks (fabricative, Part 4 §3.1).
+
+    Writes ``cell.lattice_vectors`` and ``cell.pbc`` into every frame and records an
+    ``Assumption`` **and** two ``SuppliedField`` entries — the cell did not exist in the source,
+    so it is filed as created, never carried (**P4**). ``pbc`` is set to (T,T,T): POSCAR, the only
+    v0.1 lattice-requiring target, is fully periodic by definition (Part 3 §3 n.3)."""
+    code = _choice_code(choice, "missing_lattice")
+    params = choice.get("parameters", {}) or {}
+    pbc = (True, True, True)
+
+    if code == "manual_input":
+        raw = params.get("lattice")
+        lattice = _as_lattice(raw)
+        new_frames = [_frame_with_cell(f, lattice, pbc) for f in canonical.frames]
+        report_params: dict[str, Any] = {"lattice_ang": lattice.tolist()}
+        description = (
+            "Lattice supplied manually by the caller; pbc set to (T,T,T) as required by the "
+            "target. The source expressed no lattice — this cell is an artifact of conversion, "
+            "not simulation data."
+        )
+    else:  # "bounding_box"
+        padding = params.get("padding_ang")
+        if not isinstance(padding, (int, float)) or padding < 0:
+            raise RecoveryError(
+                f"missing_lattice 'bounding_box' needs a non-negative padding_ang, got {padding!r}"
+            )
+        padding = float(padding)
+        # Box is computed on the (already-selected) single frame; if several frames remain the
+        # same box is applied to each (no v0.1 pair reaches here multi-frame).
+        positions = canonical.frames[0].atoms.positions
+        lattice, shift = _bounding_box(positions, padding)
+        new_frames = [_frame_with_cell(f, lattice, pbc, shift=shift) for f in canonical.frames]
+        report_params = {"padding_ang": padding, "computed_on_frame": computed_on_frame}
+        description = (
+            f"Lattice constructed as the axis-aligned bounding box of frame {computed_on_frame}'s "
+            f"positions plus {padding} Å padding on each side; atoms rigidly translated into that "
+            "box (a shift preserves all interatomic distances). pbc set to (T,T,T) as required by "
+            "the target. The source expressed no lattice — this cell is a conversion artifact, "
+            "not simulation data."
+        )
+
+    updated = canonical.model_copy(update={"frames": new_frames})
+    assumption = AppliedAssumption(
+        id=aid,
+        scenario="missing_lattice",
+        choice=code,
+        parameters=report_params,
+        origin=origin,
+        description=description,
+        supplied=[
+            SuppliedField(
+                path="cell.lattice_vectors",
+                detail="3×3 lattice fabricated by recovery — not present in the source.",
+            ),
+            SuppliedField(
+                path="cell.pbc",
+                detail="(T, T, T) — required by the target; set by the same recovery choice.",
+            ),
+        ],
+    )
+    return updated, assumption
+
+
+def _bounding_box(positions: np.ndarray, padding: float) -> tuple[np.ndarray, np.ndarray]:
+    """Return (orthorhombic lattice, translation) for an axis-aligned box of ``positions`` with
+    ``padding`` on every side. Atoms are shifted by ``-min + padding`` so they sit inside the box
+    with a ``padding`` margin from each face; the box side per axis is ``extent + 2·padding``."""
+    lo = positions.min(axis=0)
+    hi = positions.max(axis=0)
+    extent = hi - lo
+    side = extent + 2.0 * padding
+    lattice = np.diag(side).astype(np.float64)
+    shift = padding - lo
+    return lattice, shift
+
+
+def _frame_with_cell(
+    frame: Frame,
+    lattice: np.ndarray,
+    pbc: tuple[bool, bool, bool],
+    *,
+    shift: np.ndarray | None = None,
+) -> Frame:
+    atoms = frame.atoms
+    if shift is not None:
+        atoms = AtomsBlock(
+            symbols=list(atoms.symbols),
+            positions=atoms.positions + shift,
+            masses=atoms.masses,
+        )
+    return frame.model_copy(update={"atoms": atoms, "cell": Cell(lattice_vectors=lattice, pbc=pbc)})
+
+
+def _as_lattice(raw: Any) -> np.ndarray:
+    try:
+        lattice = np.asarray(raw, dtype=np.float64)
+    except (TypeError, ValueError) as exc:
+        raise RecoveryError(
+            f"missing_lattice 'manual_input' lattice is not numeric: {exc}"
+        ) from exc
+    if lattice.shape != (3, 3):
+        raise RecoveryError(
+            f"missing_lattice 'manual_input' needs a 3×3 lattice, got shape {lattice.shape}"
+        )
+    return lattice