xtalate 0.1.0.dev0__py3-none-any.whl

xtalate/conversion/report.py

@@ -0,0 +1,74 @@
+"""The Conversion Report — exact schema (MASTER_SPEC Part 4 §2).
+
+The structured record of what a conversion kept, dropped, fabricated, transformed, or
+assumed — **Preserved / Removed / Supplied / Assumptions / Warnings** (Part 0 §6 plus the
+normative `Supplied` addition of §2). One schema serves both the *pre-flight draft* (shown
+before conversion; Part 3 §4.3) and the *final report*, distinguished by `stage`, so the
+promise and the record are structurally comparable and any divergence is itself a defect the
+Validation Engine flags (Part 5).
+
+`Removed` entries each carry their own `reason` — "Reason" is not a separate list (§2).
+`Supplied` and `Assumptions` are one-to-(one-or-more): an `Assumption` records the *decision*,
+each `SuppliedEntry` the *canonical field that decision wrote* (§2). Every field is a canonical
+path (Part 2 §3); these are the vocabulary the completeness invariant (§2) is stated over.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class PreservedEntry(_Model):
+    path: str  # Canonical field path, e.g. "atoms.positions" (Part 2 §3).
+    detail: str | None = None  # e.g. "1 frame × 64 atoms", "converted to fractional (Direct)".
+
+
+class RemovedEntry(_Model):
+    path: str  # Canonical path present in the source but absent from the output.
+    reason: str  # REQUIRED. From the target FieldCapability.notes, or generated from the level.
+    detail: str | None = None  # e.g. "10 frames × 64 atoms × 3 dropped".
+
+
+class SuppliedEntry(_Model):
+    path: str  # Canonical path fabricated by Recovery and written out — absent on the source.
+    from_assumption: str  # REQUIRED. The Assumption.id that authorized this value (P4).
+    detail: str | None = None  # e.g. "3×3 lattice; pbc (T,T,T) — bounding box of frame 9 + 5 Å".
+
+
+class Assumption(_Model):
+    id: str  # Stable per-report identifier, e.g. "A1".
+    scenario: str  # Machine code: "missing_lattice", "frame_selection", … (Part 4 §3).
+    choice: str  # Machine code of the selected option: "bounding_box", … (Part 4 §3).
+    parameters: dict[str, Any] = Field(default_factory=dict)  # e.g. {"padding_ang": 5.0}.
+    origin: Literal["user", "preset"]  # Interactive choice vs pre-supplied in the API call.
+    description: str  # Human-readable sentence describing the decision.
+
+
+class ReportWarning(_Model):
+    code: str  # Stable machine code, e.g. "COORDINATE_REPRESENTATION_CHANGED".
+    message: str
+    # ParseIssue echo (Part 3 §5 rule 5), lossy_notes/capability caveat, or exporter transform.
+    source: Literal["parse", "capability", "export"]
+
+
+class ConversionReport(_Model):
+    report_id: str  # UUID.
+    stage: Literal["preflight", "final"]
+    status: Literal["completed", "awaiting_recovery", "refused"]
+    mode: Literal["strict", "permissive"]  # Part 4 §4.
+    created_at: str  # ISO 8601 UTC.
+    source: dict[str, Any]  # { format_id, filename, sha256, schema_version }.
+    target: dict[str, Any]  # { format_id, filename }.
+    preserved: list[PreservedEntry] = Field(default_factory=list)
+    removed: list[RemovedEntry] = Field(default_factory=list)  # Every entry carries its Reason.
+    supplied: list[SuppliedEntry] = Field(default_factory=list)  # [] = nothing fabricated.
+    assumptions: list[Assumption] = Field(default_factory=list)  # [] = no fabricated information.
+    warnings: list[ReportWarning] = Field(default_factory=list)
+    # Populated iff status="refused": { code, message, unresolved_scenarios: [...] } (Part 4 §4).
+    refusal: dict[str, Any] | None = None

xtalate/discovery/__init__.py

@@ -0,0 +1,28 @@
+"""Discovery — Format Sniffer + Information Discovery Engine (Part 3 §6).
+
+Generic by construction: no per-format logic. Sniffs via each registered parser's
+``sniff()`` (incl. the POSCAR⇄CONTCAR filename rule, Part 3 §6.1), parses via the
+winning parser, and produces the ``DiscoveryReport`` from ``field_presence()``.
+Sniffer + registry in M2; the Discovery Report in M6's inspect command.
+"""
+
+from xtalate.discovery.engine import DiscoveryEngine
+from xtalate.discovery.report import DiscoveryReport, FieldPresenceEntry
+from xtalate.discovery.sniffer import (
+    DEFAULT_ACCEPT_THRESHOLD,
+    DEFAULT_AMBIGUITY_MARGIN,
+    SniffCandidate,
+    Sniffer,
+    SniffResult,
+)
+
+__all__ = [
+    "DEFAULT_ACCEPT_THRESHOLD",
+    "DEFAULT_AMBIGUITY_MARGIN",
+    "DiscoveryEngine",
+    "DiscoveryReport",
+    "FieldPresenceEntry",
+    "SniffCandidate",
+    "SniffResult",
+    "Sniffer",
+]

xtalate/discovery/engine.py

@@ -0,0 +1,202 @@
+"""The Information Discovery Engine (MASTER_SPEC Part 3 §6.1).
+
+Generic by construction: **sniff → parse → introspect → report**, with no per-format logic.
+The winning parser produces the Canonical Object under the full absence convention, and the
+report is derived from ``field_presence()`` — so *discovery is exactly as trustworthy as
+parsing* (§6.1): there is no separate lightweight "peek" path that could disagree with a real
+conversion. A file whose format cannot be determined, or that fails to parse, raises
+``ParseError`` — the same error contract every parser obeys (§5), which the CLI maps to its
+parse-error exit code.
+
+Layering (Part 1 §5.1): ``discovery`` sits above ``capabilities``/``parsers``/``exporters``,
+so it drives the registry and reads the Capability Matrix, but is itself consumed only by
+``conversion`` and the CLI.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from io import BytesIO
+
+from xtalate.capabilities import Registry
+from xtalate.discovery.report import DiscoveryReport, FieldPresenceEntry
+from xtalate.discovery.sniffer import Sniffer, SniffResult
+from xtalate.schema import CanonicalObject
+from xtalate.sdk import CapabilityLevel, ParseError, ParseIssue
+
+# The canonical scientific leaf paths the Discovery Report is complete over (Part 3 §6.2, §6.3):
+# Part 2 §3.3–§3.7 plus frame.time and trajectory.timestep, in the §6.3 worked-example order.
+# `atoms.atomic_numbers` (a derived mirror of symbols) and the metadata containers are excluded —
+# they are summarized in `structure`/`extras`, not enumerated as losable leaf fields.
+_LEAF_PATHS: tuple[str, ...] = (
+    "atoms.symbols",
+    "atoms.positions",
+    "atoms.masses",
+    "frame.time",
+    "cell.lattice_vectors",
+    "cell.pbc",
+    "cell.space_group",
+    "trajectory.timestep",
+    "dynamics.velocities",
+    "dynamics.forces",
+    "dynamics.constraints",
+    "electronic.total_energy",
+    "electronic.stress",
+    "electronic.charges",
+    "electronic.magnetic_moments",
+    "electronic.total_spin",
+)
+
+
+class DiscoveryEngine:
+    def __init__(self, registry: Registry) -> None:
+        self._registry = registry
+        self._sniffer = Sniffer(registry)
+
+    def discover(
+        self, data: bytes, *, filename: str | None = None, format_override: str | None = None
+    ) -> DiscoveryReport:
+        """Inspect ``data`` and return its Discovery Report (Part 3 §6). ``format_override``
+        forces a parser (the sniff-override of §6.1); otherwise the sniffer selects one, and an
+        undetermined format raises ``ParseError`` (nothing can be inspected without a parser)."""
+        sniff = self._sniffer.sniff(data, filename)
+        format_id = format_override or sniff.format_id
+        if format_id is None:
+            raise ParseError(
+                [
+                    ParseIssue(
+                        severity="error",
+                        code="UNKNOWN_FORMAT",
+                        message=(
+                            "no registered format matched with sufficient confidence "
+                            f"(top score {sniff.confidence:.2f}); pass an explicit "
+                            "format to override"
+                        ),
+                    )
+                ]
+            )
+        if format_id not in {p.format_id for p in self._registry.parsers()}:
+            raise ParseError(
+                [
+                    ParseIssue(
+                        severity="error",
+                        code="UNKNOWN_FORMAT",
+                        message=f"no parser registered for format {format_id!r}",
+                    )
+                ]
+            )
+
+        result = self._registry.get_parser(format_id).parse(BytesIO(data), filename=filename)
+        canonical = result.canonical
+
+        return DiscoveryReport(
+            file={
+                "filename": filename,
+                "size_bytes": len(data),
+                "sha256": hashlib.sha256(data).hexdigest(),
+            },
+            format=self._format_block(format_id, sniff, format_override),
+            structure=_structure(canonical),
+            fields=self._fields(canonical, format_id),
+            extras=_extras(canonical),
+            issues=list(result.issues),
+            schema_version=canonical.schema_version,
+        )
+
+    def _format_block(
+        self, format_id: str, sniff: SniffResult, override: str | None
+    ) -> dict[str, object]:
+        caps = self._registry.capability_matrix()
+        try:
+            format_name = caps.get(format_id, "read").format_name
+        except KeyError:
+            format_name = format_id
+        # Confidence is the sniffer's own score for the *selected* format — one honest rule for
+        # both paths: the winning score when the sniffer chose, or the overridden format's real
+        # score when the caller forced one (never a fabricated 1.0; the override is recorded
+        # separately). A forced format that sniffed poorly shows its poor score, by design.
+        confidence = next((c.confidence for c in sniff.candidates if c.format_id == format_id), 0.0)
+        # Evidence = every *other* scored candidate, so the reader sees the full ranking that led
+        # to this pick — including the format the sniffer *would* have chosen when overridden
+        # (P1: show the alternatives, never just the winner).
+        evidence = [
+            {"format_id": c.format_id, "confidence": c.confidence}
+            for c in sniff.candidates
+            if c.format_id != format_id
+        ]
+        return {
+            "format_id": format_id,
+            "format_name": format_name,
+            "confidence": confidence,
+            "overridden": override is not None,
+            "ambiguous": sniff.ambiguous,
+            "sniff_evidence": evidence,
+        }
+
+    def _fields(self, canonical: CanonicalObject, format_id: str) -> list[FieldPresenceEntry]:
+        presence = canonical.field_presence()
+        by_path = {e.path: e for e in presence.entries}
+        caps = self._registry.capability_matrix()
+        entries: list[FieldPresenceEntry] = []
+        for path in _LEAF_PATHS:
+            pres = by_path.get(path)
+            status = pres.status if pres is not None else "absent"
+            present_frames = pres.present_frames if pres is not None else None
+            level = caps.field_capability(format_id, "read", path).level
+            detail = _detail(canonical, path) if status != "absent" else None
+            entries.append(
+                FieldPresenceEntry(
+                    path=path,
+                    status=status,
+                    present_frames=present_frames,
+                    format_capability=level,
+                    detail=detail,
+                )
+            )
+        return entries
+
+
+def _structure(obj: CanonicalObject) -> dict[str, object]:
+    symbols = obj.frames[0].atoms.symbols if obj.frames else []
+    # Constant atom count across frames (Part 2 §3.2 invariant), so a single integer suffices.
+    species: list[str] = []
+    for sym in symbols:
+        if sym not in species:
+            species.append(sym)  # first-occurrence order, matching the §6.3 example (["O", "H"]).
+    return {"frame_count": obj.frame_count, "atom_count": len(symbols), "species": species}
+
+
+def _extras(obj: CanonicalObject) -> list[str]:
+    """Carried-through keys not part of the fixed leaf schema (Part 3 §6.2): the per-file
+    ``custom_*`` namespaces and ``simulation.extra`` keys, reported at container granularity."""
+    um = obj.user_metadata
+    extras: list[str] = []
+    for container, keys in (
+        ("user_metadata.custom_global", um.custom_global),
+        ("user_metadata.custom_per_atom", um.custom_per_atom),
+        ("user_metadata.custom_per_frame", um.custom_per_frame),
+    ):
+        extras.extend(f"{container}['{key}']" for key in keys)
+    if obj.simulation is not None and obj.simulation.extra:
+        extras.extend(f"simulation.extra['{key}']" for key in obj.simulation.extra)
+    return extras
+
+
+def _detail(obj: CanonicalObject, path: str) -> str | None:
+    """A short human-readable descriptor for a present field (Part 3 §6.3). Detail richness is a
+    documented cut-line (IMPLEMENTATION_PLAN M6); the high-value cases are covered, others None."""
+    frames = obj.frame_count
+    atoms = len(obj.frames[0].atoms.symbols) if obj.frames else 0
+    if path == "atoms.symbols":
+        return ", ".join(obj.frames[0].atoms.symbols) if obj.frames else None
+    if path == "atoms.positions":
+        return f"{frames} frame(s) × {atoms} atoms, Cartesian (Å)"
+    if path == "cell.lattice_vectors":
+        return "3×3 lattice (Å)"
+    if path in ("dynamics.velocities", "dynamics.forces"):
+        return f"{frames} frame(s) × {atoms} atoms × 3"
+    return None
+
+
+# `CapabilityLevel` is re-exported for renderers that annotate the inventory by capability.
+__all__ = ["DiscoveryEngine", "DiscoveryReport", "FieldPresenceEntry", "CapabilityLevel"]

xtalate/discovery/report.py

@@ -0,0 +1,50 @@
+"""The Discovery Report — exact schema (MASTER_SPEC Part 3 §6.2).
+
+The ✓/✗ inventory the Information Discovery Engine produces: for a sniffed-and-parsed file,
+which canonical fields it contains, each annotated with the *read-side* capability of the
+detected format (so a reader sees not just "present" but "and this format could express it").
+The ``fields`` list is **complete over the canonical scientific leaf paths** (Part 2 §3.3–§3.7
+plus ``frame.time`` and ``trajectory.timestep``) — every one appears exactly once, present or
+absent, so "not shown" can never be mistaken for "not checked" (§6.3). Root metadata containers
+and carried-through user data are summarized in ``structure``/``extras`` instead, since their
+contents are format-specific rather than a fixed schema of leaf paths.
+
+Emitted verbatim by the API's ``/v1/inspect`` (Part 6) and the CLI's ``inspect`` (Appendix A);
+the CLI renders it as a terminal inventory, never a parallel DTO.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from xtalate.sdk import CapabilityLevel, ParseIssue
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class FieldPresenceEntry(_Model):
+    path: str  # Canonical field path, e.g. "dynamics.velocities".
+    status: (
+        str  # Literal["present", "absent", "mixed"] — "mixed" mirrors PresenceMap (Part 2 §3.11).
+    )
+    # Populated only when status="mixed": the frame indices where the field is present.
+    present_frames: list[int] | None = None
+    format_capability: CapabilityLevel  # Read-side capability of the detected format for this path.
+    detail: str | None = None  # e.g. "2 frames × 3 atoms, Cartesian (Å)".
+
+
+class DiscoveryReport(_Model):
+    file: dict[str, Any]  # { filename, size_bytes, sha256 }.
+    # { format_id, format_name, confidence, sniff_evidence: [{format_id, confidence}, ...] }.
+    format: dict[str, Any]
+    structure: dict[str, Any]  # { frame_count, atom_count, species: [...] }.
+    fields: list[FieldPresenceEntry] = Field(default_factory=list)  # One entry per leaf path.
+    extras: list[str] = Field(
+        default_factory=list
+    )  # Carried-through custom_* / simulation.extra keys.
+    issues: list[ParseIssue] = Field(default_factory=list)  # Warnings from the parse (Part 3 §5).
+    schema_version: str  # Of the Canonical Object produced.

xtalate/discovery/sniffer.py

@@ -0,0 +1,95 @@
+"""Format Sniffer (MASTER_SPEC Part 3 §6.1).
+
+Generic by construction — **no per-format logic** (§6.1). Every registered parser scores
+the file head via its own ``sniff(head, filename)``; the sniffer only ranks the scores and
+applies two instance-configurable thresholds:
+
+* ``accept_threshold`` (default **0.5**): the top score must reach this or the file is
+  ``UNKNOWN_FORMAT`` (``format_id = None``), all candidates recorded so the caller can see
+  why — a low-confidence guess silently applied would be a misparse waiting to happen.
+* ``ambiguity_margin`` (default **0.2**): if the top two scores are within this, the result
+  is flagged ``ambiguous`` and every candidate is kept as evidence for a user override.
+
+Format-specific tie preferences are expressed through the *parsers' own scores and
+filename handling*, not hardcoded here. The **POSCAR ⇄ CONTCAR** case (§6.1) is the
+canonical example: each parser returns 1.0 for its exact conventional filename, and the
+more-specific CONTCAR reading scores marginally lower on a generic file, so POSCAR wins a
+nameless tie while the ambiguity is still surfaced — all without the sniffer knowing either
+format exists. When two formats genuinely tie, the deterministic pick is the top score,
+ties broken by ``format_id`` order, always with ``ambiguous=True``.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from xtalate.capabilities import Registry
+
+DEFAULT_ACCEPT_THRESHOLD = 0.5
+DEFAULT_AMBIGUITY_MARGIN = 0.2
+HEAD_SIZE = 64 * 1024  # Parsers see at most the first 64 KiB (§2).
+
+
+class SniffCandidate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    format_id: str
+    confidence: float
+
+
+class SniffResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    format_id: str | None  # None => UNKNOWN_FORMAT (top score below accept_threshold).
+    confidence: float  # The top score (0.0 when there are no parsers / unknown).
+    ambiguous: bool  # True when the top two scores are within ambiguity_margin.
+    candidates: list[SniffCandidate]  # All scored parsers, highest first — the sniff evidence.
+
+
+class Sniffer:
+    def __init__(
+        self,
+        registry: Registry,
+        *,
+        accept_threshold: float = DEFAULT_ACCEPT_THRESHOLD,
+        ambiguity_margin: float = DEFAULT_AMBIGUITY_MARGIN,
+    ) -> None:
+        self._registry = registry
+        self.accept_threshold = accept_threshold
+        self.ambiguity_margin = ambiguity_margin
+
+    def sniff(self, data: bytes, filename: str | None = None) -> SniffResult:
+        head = data[:HEAD_SIZE]
+        candidates: list[SniffCandidate] = []
+        for parser in self._registry.parsers():
+            try:
+                score = float(parser.sniff(head, filename))
+            except Exception:
+                # sniff() "must never raise" (§2); a misbehaving plugin scores 0, never
+                # crashes detection of the other formats.
+                score = 0.0
+            score = max(0.0, min(1.0, score))
+            candidates.append(SniffCandidate(format_id=parser.format_id, confidence=score))
+
+        # Highest confidence first; ties broken by format_id for a deterministic winner.
+        candidates.sort(key=lambda c: (-c.confidence, c.format_id))
+
+        if not candidates:
+            return SniffResult(format_id=None, confidence=0.0, ambiguous=False, candidates=[])
+
+        best = candidates[0]
+        if best.confidence < self.accept_threshold:
+            # UNKNOWN_FORMAT: below the acceptance bar. Report candidates so the caller can
+            # override, but select nothing (§6.1).
+            return SniffResult(
+                format_id=None, confidence=best.confidence, ambiguous=False, candidates=candidates
+            )
+
+        runner_up = candidates[1].confidence if len(candidates) > 1 else 0.0
+        ambiguous = (best.confidence - runner_up) < self.ambiguity_margin
+        return SniffResult(
+            format_id=best.format_id,
+            confidence=best.confidence,
+            ambiguous=ambiguous,
+            candidates=candidates,
+        )

xtalate/exporters/__init__.py

@@ -0,0 +1,34 @@
+"""Exporters — one ``ExporterPlugin`` per format: Canonical Object → native file (Part 4 §1).
+
+Writes exactly the ``write_plan`` handed to it; never reads native files, calls a
+parser, or fabricates absent fields (Part 1 §2, Part 4 §1). Depends on ``schema``
+and ``sdk``. Lands alongside its paired parser in M3.
+
+``builtin_exporters()`` mirrors ``parsers.builtin_parsers()`` — a downward-only list a
+higher layer assembles into a Registry.
+"""
+
+from __future__ import annotations
+
+from xtalate.exporters.extxyz import ExtxyzExporter
+from xtalate.exporters.poscar import (
+    PoscarExporter,
+    make_contcar_exporter,
+    make_poscar_exporter,
+)
+from xtalate.exporters.xyz import XyzExporter
+from xtalate.sdk import ExporterPlugin
+
+__all__ = [
+    "ExtxyzExporter",
+    "PoscarExporter",
+    "XyzExporter",
+    "builtin_exporters",
+    "make_contcar_exporter",
+    "make_poscar_exporter",
+]
+
+
+def builtin_exporters() -> list[ExporterPlugin]:
+    """The exporters shipped in v0.1 (M3a XYZ, M3b POSCAR/CONTCAR, M3c extXYZ)."""
+    return [XyzExporter(), ExtxyzExporter(), make_poscar_exporter(), make_contcar_exporter()]

xtalate/exporters/extxyz.py

@@ -0,0 +1,140 @@
+"""Extended XYZ exporter (MASTER_SPEC Part 3 §2, Part 4 §1).
+
+The mirror of ``parsers.extxyz``: it rebuilds an ASE ``Atoms`` per frame from the Canonical
+Object and lets ASE serialise the ``Lattice=`` / ``Properties=`` grammar. Every mapping is the
+exact inverse of the parser's (DECISIONS.md D18), including the velocity unit conversion
+(canonical Å/fs → ASE internal units) so that ``A → Canonical → A' → Canonical'`` reproduces
+the scientific content exactly. Fields extXYZ cannot express are the Conversion Engine's to
+report as ``removed`` (Part 4); this exporter simply writes what the object holds.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any, BinaryIO
+
+import numpy as np
+from ase import Atoms
+from ase import units as ase_units
+from ase.calculators.singlepoint import SinglePointCalculator
+from ase.io import write as ase_write
+
+from xtalate.schema import CanonicalObject, Frame
+from xtalate.sdk import (
+    CapabilityLevel,
+    ExporterPlugin,
+    FieldCapability,
+    FormatCapabilities,
+)
+
+FORMAT_ID = "extxyz"
+_KEY_PREFIX = "extxyz:"
+_STRESS_KEY = "extxyz:stress"
+# Å/fs → ASE internal velocity units: the exact inverse of the parser's conversion. Defined
+# here (not imported from parsers) because exporters and parsers are import-sibling layers
+# that must not depend on each other (pyproject import-linter contract, P2).
+_VEL_ASE_TO_ANG_PER_FS = ase_units.fs
+
+
+class ExtxyzExporter(ExporterPlugin):
+    format_id = FORMAT_ID
+    format_name = "Extended XYZ"
+    version = "0.1.0"
+
+    def export(self, canonical: CanonicalObject, stream: BinaryIO) -> None:
+        images = [self._frame_to_atoms(canonical, frame) for frame in canonical.frames]
+        buf = io.StringIO()
+        ase_write(buf, images, format="extxyz")
+        stream.write(buf.getvalue().encode("utf-8"))
+
+    def _frame_to_atoms(self, canonical: CanonicalObject, frame: Frame) -> Atoms:
+        atoms = Atoms(
+            symbols=list(frame.atoms.symbols),
+            positions=np.asarray(frame.atoms.positions, dtype=float),
+        )
+        if frame.atoms.masses is not None:
+            atoms.set_masses(np.asarray(frame.atoms.masses, dtype=float))
+        if frame.cell is not None:
+            atoms.set_cell(np.asarray(frame.cell.lattice_vectors, dtype=float))
+            atoms.set_pbc(frame.cell.pbc)
+        if frame.dynamics.velocities is not None:
+            v_ase = np.asarray(frame.dynamics.velocities, dtype=float) / _VEL_ASE_TO_ANG_PER_FS
+            atoms.set_velocities(v_ase)
+
+        # Object-level per-atom carry-through columns apply to every frame (Part 2 §3.10).
+        for key, values in canonical.user_metadata.custom_per_atom.items():
+            atoms.new_array(_strip(key), np.asarray(values))
+
+        # Per-frame comment key-values (+ stress) for this frame index.
+        stress = None
+        for key, per_frame in canonical.user_metadata.custom_per_frame.items():
+            value = per_frame[frame.index] if frame.index < len(per_frame) else None
+            if value is None:
+                continue
+            if key == _STRESS_KEY:
+                stress = np.asarray(value, dtype=float)
+            else:
+                atoms.info[_strip(key)] = value
+
+        results: dict[str, Any] = {}
+        if frame.electronic.total_energy is not None:
+            results["energy"] = float(frame.electronic.total_energy)
+        if frame.dynamics.forces is not None:
+            results["forces"] = np.asarray(frame.dynamics.forces, dtype=float)
+        if frame.electronic.charges is not None:
+            results["charges"] = np.asarray(frame.electronic.charges, dtype=float)
+        if frame.electronic.magnetic_moments is not None:
+            results["magmoms"] = np.asarray(frame.electronic.magnetic_moments, dtype=float)
+        if stress is not None:
+            results["stress"] = stress
+        if results:
+            atoms.calc = SinglePointCalculator(atoms, **results)
+        return atoms
+
+    def capabilities(self) -> FormatCapabilities:
+        full = FieldCapability(level=CapabilityLevel.FULL)
+        partial = CapabilityLevel.PARTIAL
+        return FormatCapabilities(
+            format_id=FORMAT_ID,
+            format_name=self.format_name,
+            direction="write",
+            fields={
+                "atoms.symbols": full,
+                "atoms.positions": full,
+                "atoms.masses": FieldCapability(level=partial, notes="Written as a masses column."),
+                "cell.lattice_vectors": FieldCapability(
+                    level=partial, notes="Written as the Lattice= key when a cell is present."
+                ),
+                "cell.pbc": FieldCapability(level=partial, notes="Written as the pbc= key."),
+                "dynamics.velocities": FieldCapability(
+                    level=partial, notes="Written as a momenta column; unit-converted."
+                ),
+                "dynamics.forces": FieldCapability(
+                    level=partial, notes="Written as a forces column."
+                ),
+                "electronic.total_energy": FieldCapability(
+                    level=partial, notes="Written as the energy= key."
+                ),
+                "electronic.charges": FieldCapability(
+                    level=partial, notes="Written as a per-atom charge column."
+                ),
+                "electronic.magnetic_moments": FieldCapability(
+                    level=partial, notes="Written as a per-atom magmoms column."
+                ),
+                "user_metadata.custom_per_atom": FieldCapability(
+                    level=CapabilityLevel.FULL, notes="Written back as Properties= columns."
+                ),
+                "user_metadata.custom_per_frame": FieldCapability(
+                    level=CapabilityLevel.FULL, notes="Written back as comment key-values."
+                ),
+            },
+            max_frames=None,
+            required_fields=["atoms.symbols", "atoms.positions"],
+            native_coordinate_system="cartesian",
+            lossy_notes=[],
+        )
+
+
+def _strip(key: str) -> str:
+    """``'extxyz:foo'`` → ``'foo'``; a user/plugin key without the prefix is written as-is."""
+    return key[len(_KEY_PREFIX) :] if key.startswith(_KEY_PREFIX) else key