xtalate 0.1.0.dev0__py3-none-any.whl

xtalate/exporters/poscar.py

@@ -0,0 +1,180 @@
+"""VASP POSCAR / CONTCAR exporter (MASTER_SPEC Part 3 §3, Part 4 §1, §8.2).
+
+Writes a single-structure POSCAR. Coordinates are emitted in **Cartesian** mode with a
+scaling factor of ``1.0`` (canonical lattice vectors are already absolute Å), so a
+parsed→exported→parsed round-trip reproduces the Cartesian positions exactly with no matrix
+inversion (DECISIONS.md D8). POSCAR requires atoms of one element to be contiguous, so the
+exporter **groups by element** in first-occurrence order; that grouping is a permutation of
+the atom list (the same permutation Part 5 validation reconstructs) applied consistently to
+positions, velocities, and selective-dynamics masks. A CONTCAR velocity / predictor-corrector
+tail carried through on parse is written back so CONTCAR identity round-trips.
+
+Multi-frame input is refused here rather than silently truncated: reducing a trajectory to
+one structure is a *selective-reductive* choice the Conversion Engine records as an
+Assumption before it ever calls this exporter (Part 4 §3).
+"""
+
+from __future__ import annotations
+
+from typing import BinaryIO
+
+from xtalate.schema import CanonicalObject
+from xtalate.sdk import (
+    CapabilityLevel,
+    ExporterPlugin,
+    FieldCapability,
+    FormatCapabilities,
+)
+
+_COMMENT_KEY = "poscar:comment"
+_PREDICTOR_KEY = "contcar:predictor_corrector"
+
+
+def _fmt(x: float) -> str:
+    return repr(float(x))
+
+
+def _grouping(symbols: list[str]) -> tuple[list[str], list[int], list[int]]:
+    """Group atoms by element in first-occurrence order (POSCAR requires one element's atoms to be
+    contiguous). Returns ``(order, permutation, counts)`` where ``order`` is the element sequence,
+    ``permutation[i]`` is the source index written at output position *i* (the Part 5 permutation
+    map), and ``counts`` is the per-element atom count. Used by both ``export`` (to write the file)
+    and ``atom_permutation`` (to report the map), so the two can never disagree."""
+    order: list[str] = []
+    groups: dict[str, list[int]] = {}
+    for i, sym in enumerate(symbols):
+        if sym not in groups:
+            groups[sym] = []
+            order.append(sym)
+        groups[sym].append(i)
+    permutation = [i for sym in order for i in groups[sym]]
+    counts = [len(groups[sym]) for sym in order]
+    return order, permutation, counts
+
+
+class PoscarExporter(ExporterPlugin):
+    """POSCAR/CONTCAR writer. One class, registered under ``poscar`` and ``contcar``
+    (the canonical fields written are identical; only the reported label differs)."""
+
+    version = "0.1.0"
+
+    def __init__(self, *, format_id: str = "poscar") -> None:
+        self.format_id = format_id
+        self.format_name = "VASP POSCAR" if format_id == "poscar" else "VASP CONTCAR"
+
+    def export(self, canonical: CanonicalObject, stream: BinaryIO) -> None:
+        if len(canonical.frames) != 1:
+            raise ValueError(
+                "POSCAR holds a single structure; reduce the trajectory to one frame via the "
+                "Conversion Engine's frame_selection recovery before export (Part 4 §3)"
+            )
+        frame = canonical.frames[0]
+        atoms = frame.atoms
+        cell = frame.cell
+        if cell is None:
+            raise ValueError(
+                "POSCAR requires cell.lattice_vectors; supply it via the missing_lattice "
+                "recovery before export (Part 4 §3)"
+            )
+
+        # Group atoms by element in first-occurrence order -> a permutation applied to every
+        # per-atom array so the written file is internally consistent (Part 5 permutation map).
+        order, permutation, counts = _grouping(atoms.symbols)
+
+        title = canonical.user_metadata.custom_global.get(_COMMENT_KEY, "")
+        out: list[str] = [str(title) if title is not None else ""]
+        out.append("1.0")  # canonical lattice is absolute; no rescale needed
+        for row in cell.lattice_vectors:
+            out.append(f"  {_fmt(row[0])} {_fmt(row[1])} {_fmt(row[2])}")
+        out.append(" ".join(order))
+        out.append(" ".join(str(c) for c in counts))
+
+        # Selective dynamics: present (even all-T) => write the block so [] round-trips as
+        # distinct from None (Part 3 §3 n.7).
+        constraints = frame.dynamics.constraints
+        mask_by_atom: list[list[bool]] | None = None
+        if constraints is not None:
+            out.append("Selective dynamics")
+            if constraints:
+                # Exactly one selective_dynamics constraint carrying a per-atom mask.
+                raw = constraints[0].parameters.get("mask", [])
+                mask_by_atom = [list(m) for m in raw]
+            else:
+                mask_by_atom = [[True, True, True] for _ in atoms.symbols]
+
+        out.append("Cartesian")
+        for atom_idx in permutation:
+            pos = atoms.positions[atom_idx]
+            line = f"  {_fmt(pos[0])} {_fmt(pos[1])} {_fmt(pos[2])}"
+            if mask_by_atom is not None:
+                flags = mask_by_atom[atom_idx]
+                line += " " + " ".join("T" if f else "F" for f in flags)
+            out.append(line)
+
+        velocities = frame.dynamics.velocities
+        if velocities is not None:
+            out.append("")  # blank separator before the velocity block
+            out.append("Cartesian")
+            for atom_idx in permutation:
+                v = velocities[atom_idx]
+                out.append(f"  {_fmt(v[0])} {_fmt(v[1])} {_fmt(v[2])}")
+
+        predictor = canonical.user_metadata.custom_global.get(_PREDICTOR_KEY)
+        if isinstance(predictor, str) and predictor:
+            out.append("")
+            out.append(predictor)
+
+        stream.write(("\n".join(out) + "\n").encode("utf-8"))
+
+    def capabilities(self) -> FormatCapabilities:
+        full = FieldCapability(level=CapabilityLevel.FULL)
+        none = FieldCapability(level=CapabilityLevel.NONE)
+        return FormatCapabilities(
+            format_id=self.format_id,
+            format_name=self.format_name,
+            direction="write",
+            fields={
+                "atoms.symbols": full,
+                "atoms.positions": full,
+                "cell.lattice_vectors": full,
+                "cell.pbc": FieldCapability(
+                    level=CapabilityLevel.PARTIAL,
+                    notes="Only fully periodic (T,T,T); other PBC combinations cannot be "
+                    "represented.",
+                ),
+                "cell.space_group": none,
+                "dynamics.velocities": full,
+                "dynamics.forces": none,
+                "dynamics.constraints": FieldCapability(
+                    level=CapabilityLevel.PARTIAL,
+                    notes="Only per-axis fixed-atom masks (selective dynamics).",
+                ),
+                "electronic.total_energy": none,
+                "electronic.stress": none,
+                "electronic.charges": none,
+                "electronic.magnetic_moments": none,
+                "simulation.*": none,
+                "user_metadata.custom_global": FieldCapability(
+                    level=CapabilityLevel.PARTIAL,
+                    notes="Only the POSCAR title (poscar:comment) and CONTCAR predictor-corrector "
+                    "block (contcar:predictor_corrector); other custom_global keys are dropped.",
+                ),
+                "user_metadata.custom_per_atom": none,
+                "user_metadata.custom_per_frame": none,
+            },
+            max_frames=1,
+            required_fields=["atoms.symbols", "atoms.positions", "cell.lattice_vectors"],
+            native_coordinate_system="both",
+            lossy_notes=[
+                "Positions written with full float64 precision; sub-ulp differences possible "
+                "on round-trip through fixed-width VASP readers."
+            ],
+        )
+
+
+def make_poscar_exporter() -> PoscarExporter:
+    return PoscarExporter(format_id="poscar")
+
+
+def make_contcar_exporter() -> PoscarExporter:
+    return PoscarExporter(format_id="contcar")

xtalate/exporters/xyz.py

@@ -0,0 +1,67 @@
+"""Plain XYZ exporter (MASTER_SPEC Part 3 §3, Part 4 §1).
+
+The mirror of ``parsers.xyz``: it writes exactly what plain XYZ can express — element
+symbols, Cartesian positions, and the per-frame comment line — and nothing else. Fields
+the format cannot hold (cell, velocities, energies, ...) are *not* this exporter's concern
+to lose quietly: the Conversion Engine's capability pre-flight (Part 4) reports them as
+``removed`` before a byte is written. Coordinates are emitted with Python's shortest
+round-tripping float ``repr`` (DECISIONS.md D8), so ``float64 → text → float64`` is lossless
+and identity round-trips are exact.
+"""
+
+from __future__ import annotations
+
+from typing import BinaryIO
+
+from xtalate.schema import CanonicalObject
+from xtalate.sdk import (
+    CapabilityLevel,
+    ExporterPlugin,
+    FieldCapability,
+    FormatCapabilities,
+)
+
+FORMAT_ID = "xyz"
+_COMMENT_KEY = "xyz:comment"
+
+
+class XyzExporter(ExporterPlugin):
+    format_id = FORMAT_ID
+    format_name = "Plain XYZ"
+    version = "0.1.0"
+
+    def export(self, canonical: CanonicalObject, stream: BinaryIO) -> None:
+        comments = canonical.user_metadata.custom_per_frame.get(_COMMENT_KEY)
+        out: list[str] = []
+        for i, frame in enumerate(canonical.frames):
+            atoms = frame.atoms
+            out.append(str(len(atoms.symbols)))
+            # Per-frame comment carried through on parse; empty string when the source had none.
+            comment = ""
+            if comments is not None and i < len(comments):
+                value = comments[i]
+                comment = value if isinstance(value, str) else str(value)
+            out.append(comment)
+            for symbol, pos in zip(atoms.symbols, atoms.positions, strict=True):
+                x, y, z = (repr(float(c)) for c in pos)
+                out.append(f"{symbol} {x} {y} {z}")
+        stream.write(("\n".join(out) + "\n").encode("utf-8"))
+
+    def capabilities(self) -> FormatCapabilities:
+        full = FieldCapability(level=CapabilityLevel.FULL)
+        return FormatCapabilities(
+            format_id=FORMAT_ID,
+            format_name=self.format_name,
+            direction="write",
+            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=["atoms.symbols", "atoms.positions"],
+            native_coordinate_system="cartesian",
+            lossy_notes=[],
+        )

xtalate/parsers/__init__.py

@@ -0,0 +1,31 @@
+"""Parsers — one ``ParserPlugin`` per format: native file → Canonical Object (Part 3).
+
+Never reads another format, calls another parser, writes files, or defaults an
+absent field (Part 1 §2, Part 2 §2). Depends on ``schema`` and ``sdk``.
+XYZ in M3a, POSCAR/CONTCAR in M3b, extXYZ in M3c.
+
+``builtin_parsers()`` is a pure list of the v0.1 parsers a higher layer (discovery /
+conversion) assembles into a Registry — it lives here, in the parsers layer, so that
+assembly imports *downward* only and the P2 import contract holds.
+"""
+
+from __future__ import annotations
+
+from xtalate.parsers.extxyz import ExtxyzParser
+from xtalate.parsers.poscar import PoscarParser, make_contcar_parser, make_poscar_parser
+from xtalate.parsers.xyz import XyzParser
+from xtalate.sdk import ParserPlugin
+
+__all__ = [
+    "ExtxyzParser",
+    "PoscarParser",
+    "XyzParser",
+    "builtin_parsers",
+    "make_contcar_parser",
+    "make_poscar_parser",
+]
+
+
+def builtin_parsers() -> list[ParserPlugin]:
+    """The parsers shipped in v0.1 (M3a XYZ, M3b POSCAR/CONTCAR, M3c extXYZ)."""
+    return [XyzParser(), ExtxyzParser(), make_poscar_parser(), make_contcar_parser()]

xtalate/parsers/_common.py

@@ -0,0 +1,57 @@
+"""Shared parser helpers (MASTER_SPEC Part 3 §2, §5).
+
+Every parser establishes Provenance the same way: it records the source format, the
+coordinate system the *source* used, the source units, and appends exactly one
+``ConversionRecord(operation="parse")`` to the history (Part 2 §3.9). This module holds
+that boilerplate so each format module stays focused on its grammar. It imports only
+``schema`` (and the package version), never another parser — the P2 boundary holds.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from xtalate import __version__
+from xtalate.schema import ConversionRecord, Provenance
+
+
+def utc_now() -> str:
+    """Current UTC instant as an ISO-8601 ``...Z`` string (Part 2 §3.9 timestamp form).
+
+    Seconds precision, ``Z`` suffix — matching the worked-example fixtures (Part 2 §8).
+    """
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_record(format_id: str) -> ConversionRecord:
+    """The single ``operation="parse"`` history entry a successful parse appends (§3.9)."""
+    return ConversionRecord(
+        timestamp=utc_now(),
+        operation="parse",
+        source_format=format_id,
+        target_format=None,
+        tool_version=__version__,
+        parser_version=f"{format_id}-parser {__version__}",
+        assumptions=[],
+    )
+
+
+def build_provenance(
+    *,
+    format_id: str,
+    filename: str | None,
+    original_coordinate_system: str,
+    source_units: dict[str, str],
+    parse_notes: list[str],
+) -> Provenance:
+    """Assemble the Provenance for a freshly parsed object, history seeded with the parse
+    record (§3.9). ``original_coordinate_system`` is what the *source* used, not what the
+    canonical object stores (canonical positions are always Cartesian, §4)."""
+    return Provenance(
+        source_filename=filename,
+        source_format=format_id,
+        source_units=source_units,
+        original_coordinate_system=original_coordinate_system,
+        parse_notes=list(parse_notes),
+        history=[parse_record(format_id)],
+    )