chemparseplot 1.9.8__tar.gz → 1.9.9__tar.gz

{chemparseplot-1.9.8 → chemparseplot-1.9.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemparseplot
-Version: 1.9.8
+Version: 1.9.9
 Summary: Parsers and plotting tools for computational chemistry
 Project-URL: Documentation, https://chemparseplot.rgoswami.me
 Project-URL: Issues, https://github.com/HaoZeke/chemparseplot/issues
@@ -25,6 +25,8 @@ Requires-Dist: ase>=3.22; extra == 'all'
 Requires-Dist: cmcrameri>=1.7; extra == 'all'
 Requires-Dist: h5py>=3.0; extra == 'all'
 Requires-Dist: matplotlib>=3.8.2; extra == 'all'
+Requires-Dist: orca-pi>=0.1.0; extra == 'all'
+Requires-Dist: parsimonious>=0.10.0; extra == 'all'
 Requires-Dist: polars>=0.20; extra == 'all'
 Requires-Dist: readcon>=0.13.1; extra == 'all'
 Requires-Dist: xyzrender>=0.1.2; extra == 'all'
@@ -39,6 +41,8 @@ Requires-Dist: sphinx-sitemap>=2.5.1; extra == 'doc'
 Requires-Dist: sphinx-togglebutton>=0.3.2; extra == 'doc'
 Requires-Dist: sphinx>=7.2.6; extra == 'doc'
 Requires-Dist: sphinxcontrib-apidoc>=0.4; extra == 'doc'
+Provides-Extra: grammar
+Requires-Dist: parsimonious>=0.10.0; extra == 'grammar'
 Provides-Extra: lint
 Requires-Dist: ruff>=0.1.6; extra == 'lint'
 Provides-Extra: neb
@@ -46,6 +50,8 @@ Requires-Dist: ase>=3.22; extra == 'neb'
 Requires-Dist: h5py>=3.0; extra == 'neb'
 Requires-Dist: polars>=0.20; extra == 'neb'
 Requires-Dist: readcon>=0.13.1; extra == 'neb'
+Provides-Extra: opi
+Requires-Dist: orca-pi>=0.1.0; extra == 'opi'
 Provides-Extra: plot
 Requires-Dist: cmcrameri>=1.7; extra == 'plot'
 Requires-Dist: matplotlib>=3.8.2; extra == 'plot'
@@ -58,6 +64,7 @@ Provides-Extra: test
 Requires-Dist: ase>=3.22; extra == 'test'
 Requires-Dist: h5py>=3.0; extra == 'test'
 Requires-Dist: matplotlib>=3.8.2; extra == 'test'
+Requires-Dist: parsimonious>=0.10.0; extra == 'test'
 Requires-Dist: polars>=0.20; extra == 'test'
 Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
 Requires-Dist: pytest>=7.4.3; extra == 'test'

{chemparseplot-1.9.8 → chemparseplot-1.9.9}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.9.8'
-__version_tuple__ = version_tuple = (1, 9, 8)
+__version__ = version = '1.9.9'
+__version_tuple__ = version_tuple = (1, 9, 9)
 
 __commit_id__ = commit_id = None

{chemparseplot-1.9.8 → chemparseplot-1.9.9}/chemparseplot/api.py

@@ -45,11 +45,63 @@ __all__ = [
     "convert_energy_magnitude",
     "energy_quantity",
     "extract_orca_geomscan_energy",
+    "grammar_available",
     "normalize_energy_unit",
+    "parse_orca_final_energy",
+    "parse_xyz",
     "suite_pins",
 ]
 
 
+def grammar_available() -> bool:
+    """True if the optional parsimonious grammar track is importable."""
+    from chemparseplot.parse.grammar import grammar_available as _ga
+
+    return _ga()
+
+
+def _looks_like_path(s: str) -> bool:
+    """True for short path-like strings (avoid Path on multi-line blobs)."""
+    if "\n" in s or len(s) > 4096:
+        return False
+    from pathlib import Path
+
+    try:
+        return Path(s).is_file()
+    except OSError:
+        return False
+
+
+def parse_xyz(path_or_text: str):
+    """Parse XYZ via grammar track (file path if exists, else text).
+
+    Requires ``chemparseplot[grammar]``.
+    """
+    from chemparseplot.parse.grammar.xyz import parse_xyz_file, parse_xyz_text
+
+    if _looks_like_path(path_or_text):
+        return parse_xyz_file(path_or_text)
+    return parse_xyz_text(path_or_text)
+
+
+def parse_orca_final_energy(path_or_text: str):
+    """Last ``FINAL SINGLE POINT ENERGY`` as a hartree Quantity.
+
+    Grammar track; requires ``chemparseplot[grammar]``.
+    """
+    from chemparseplot.parse.grammar.orca_text import (
+        parse_orca_text_file,
+        parse_orca_text_summary,
+    )
+
+    if _looks_like_path(path_or_text):
+        summary = parse_orca_text_file(path_or_text)
+    else:
+        summary = parse_orca_text_summary(path_or_text)
+    return summary.final_energy
+
+
+
 def extract_orca_geomscan_energy(
     data: str, energy_type: str = "Actual Energy"
 ) -> tuple[Q_, Q_]:

chemparseplot-1.9.9/chemparseplot/parse/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+
+from chemparseplot.parse import eon, orca, patterns
+
+__all__ = ["eon", "grammar", "orca", "patterns"]
+
+# Lazy imports for modules with optional heavy deps (h5py, pandas, parsimonious)
+# Import directly: from chemparseplot.parse.chemgp_hdf5 import read_h5_table
+# Or: from chemparseplot.parse import plumed, projection
+# Grammar track: from chemparseplot.parse.grammar import parse_xyz_text
+
+
+def __getattr__(name: str):
+    if name == "grammar":
+        from chemparseplot.parse import grammar as _grammar
+
+        return _grammar
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

chemparseplot-1.9.9/chemparseplot/parse/grammar/__init__.py

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""Grammar / AST track for text-heavy formats (parsimonious).
+
+Optional extra: ``pip install 'chemparseplot[grammar]'``.
+
+Prefer structured APIs (OPI) for ORCA products that expose them; use this
+package for XYZ and text-only ORCA sections (energy lines, Cartesian blocks).
+
+```{versionadded} 1.9.9
+```
+"""
+
+from __future__ import annotations
+
+from chemparseplot.parse.grammar._deps import (
+    grammar_available,
+    reset_grammar_cache,
+)
+
+__all__ = [
+    "grammar_available",
+    "parse_orca_text_file",
+    "parse_orca_text_summary",
+    "parse_xyz_file",
+    "parse_xyz_text",
+    "reset_grammar_cache",
+]
+
+
+def __getattr__(name: str):
+    if name in ("parse_xyz_text", "parse_xyz_file", "XyzFrame", "XyzAtom", "write_xyz_text"):
+        from chemparseplot.parse.grammar import xyz as _xyz
+
+        return getattr(_xyz, name)
+    if name in (
+        "parse_orca_text_summary",
+        "parse_orca_text_file",
+        "OrcaTextSummary",
+        "OrcaAtomCoord",
+        "extract_final_energies_hartree",
+        "extract_cartesian_angstrom_blocks",
+    ):
+        from chemparseplot.parse.grammar import orca_text as _ot
+
+        return getattr(_ot, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

chemparseplot-1.9.9/chemparseplot/parse/grammar/_deps.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""Lazy loading for optional ``parsimonious`` (grammar track).
+
+```{versionadded} 1.9.9
+```
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+from typing import Any
+
+_grammar_mod: Any | None = None
+_nodes_mod: Any | None = None
+_probe: bool | None = None
+
+_INSTALL_HINT = (
+    "parsimonious is not installed. "
+    "Install with: pip install 'chemparseplot[grammar]' "
+    "for grammar/AST text parsers (XYZ, text-heavy ORCA sections)."
+)
+
+
+def grammar_available() -> bool:
+    """Return True if ``parsimonious`` can be imported."""
+    global _probe
+    if _probe is not None:
+        return _probe
+    try:
+        _probe = importlib.util.find_spec("parsimonious") is not None
+    except (ImportError, ModuleNotFoundError, ValueError):
+        _probe = False
+    return _probe
+
+
+def get_grammar_class() -> Any:
+    """Return ``parsimonious.grammar.Grammar``, importing lazily."""
+    global _grammar_mod
+    if _grammar_mod is not None:
+        return _grammar_mod.Grammar
+    try:
+        _grammar_mod = importlib.import_module("parsimonious.grammar")
+    except ImportError as exc:
+        raise ImportError(_INSTALL_HINT) from exc
+    return _grammar_mod.Grammar
+
+
+def get_node_visitor_class() -> Any:
+    """Return ``parsimonious.nodes.NodeVisitor``, importing lazily."""
+    global _nodes_mod
+    if _nodes_mod is not None:
+        return _nodes_mod.NodeVisitor
+    try:
+        _nodes_mod = importlib.import_module("parsimonious.nodes")
+    except ImportError as exc:
+        raise ImportError(_INSTALL_HINT) from exc
+    return _nodes_mod.NodeVisitor
+
+
+def reset_grammar_cache() -> None:
+    """Clear cached parsimonious import state (tests only)."""
+    global _grammar_mod, _nodes_mod, _probe
+    _grammar_mod = None
+    _nodes_mod = None
+    _probe = None

chemparseplot-1.9.9/chemparseplot/parse/grammar/orca_text.py

@@ -0,0 +1,235 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""Grammar-oriented extractors for text-heavy ORCA output sections.
+
+Prefer structured backends (OPI) when available. This module covers sections
+that remain text dumps: final single-point energies and Cartesian geometry
+blocks. Foundation for VPT2/IR/populations ports from wailord.
+
+```{versionadded} 1.9.9
+```
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from chemparseplot.parse.grammar._deps import (
+    get_grammar_class,
+    get_node_visitor_class,
+)
+from chemparseplot.units import Q_
+
+# Named rules are real expressions (not aliases) so visitors fire reliably.
+_ENERGY_LINE_GRAMMAR_SRC = r"""
+energy_line = label ws value ws?
+label       = "FINAL SINGLE POINT ENERGY"
+value       = ~r"[+-]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?"
+ws          = ~r"[ \t]+"
+"""
+
+_CART_BLOCK_GRAMMAR_SRC = r"""
+cart_block  = header newline dashes newline (atom_line newline)+
+header      = "CARTESIAN COORDINATES (ANGSTROEM)"
+dashes      = ~r"-{3,}"
+atom_line   = ws? atype ws float_ ws float_ ws float_ ws?
+atype       = ~r"[A-Za-z][a-zA-Z0-9]{0,2}"
+float_      = ~r"[+-]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?"
+newline     = ~r"\n"
+ws          = ~r"[ \t]+"
+"""
+
+_energy_grammar: Any | None = None
+_cart_grammar: Any | None = None
+
+_ENERGY_LINE_RE = re.compile(
+    r"^.*FINAL SINGLE POINT ENERGY[ \t]+"
+    r"([+-]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?).*$",
+    re.MULTILINE,
+)
+
+_CART_BLOCK_RE = re.compile(
+    r"CARTESIAN COORDINATES \(ANGSTROEM\)\n"
+    r"-{3,}\n"
+    r"((?:[ \t]*[A-Za-z][a-zA-Z0-9]{0,2}[ \t]+"
+    r"[+-]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?[ \t]+"
+    r"[+-]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?[ \t]+"
+    r"[+-]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?[ \t]*\n)+)",
+    re.MULTILINE,
+)
+
+_N_ATOMS_RE = re.compile(
+    r"Number of atoms\s*(?:\.{3,}|\.\.\.)\s*(\d+)",
+)
+
+
+def _energy_g() -> Any:
+    global _energy_grammar
+    if _energy_grammar is None:
+        Grammar = get_grammar_class()
+        _energy_grammar = Grammar(_ENERGY_LINE_GRAMMAR_SRC)
+    return _energy_grammar
+
+
+def _cart_g() -> Any:
+    global _cart_grammar
+    if _cart_grammar is None:
+        Grammar = get_grammar_class()
+        _cart_grammar = Grammar(_CART_BLOCK_GRAMMAR_SRC)
+    return _cart_grammar
+
+
+def _flatten(xs: Any) -> list[Any]:
+    out: list[Any] = []
+    if isinstance(xs, list):
+        for x in xs:
+            out.extend(_flatten(x))
+    elif xs is not None and xs != "":
+        out.append(xs)
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class OrcaAtomCoord:
+    """One atom in an ORCA Cartesian (Å) block."""
+
+    symbol: str
+    x: float
+    y: float
+    z: float
+
+
+@dataclass(frozen=True, slots=True)
+class OrcaTextSummary:
+    """Structured slice of text ORCA output."""
+
+    energies_hartree: tuple[float, ...]
+    last_geometry: tuple[OrcaAtomCoord, ...]
+    n_atoms: int | None
+
+    @property
+    def final_energy_hartree(self) -> float | None:
+        if not self.energies_hartree:
+            return None
+        return self.energies_hartree[-1]
+
+    @property
+    def final_energy(self) -> Any:
+        """Last final single-point energy as a pint Quantity (hartree)."""
+        e = self.final_energy_hartree
+        if e is None:
+            return Q_([], "hartree")
+        return Q_(e, "hartree")
+
+
+def extract_final_energies_hartree(text: str) -> list[float]:
+    """All ``FINAL SINGLE POINT ENERGY`` values in document order.
+
+    Candidate lines are selected with a line scan; each is validated and
+    extracted with a parsimonious line grammar.
+    """
+    g = _energy_g()
+    NodeVisitor = get_node_visitor_class()
+
+    class EnergyVisitor(NodeVisitor):
+        def __init__(self) -> None:
+            self.value: float | None = None
+
+        def visit_value(self, node: Any, visited_children: Any) -> float:
+            self.value = float(node.text)
+            return self.value
+
+        def generic_visit(self, node: Any, visited_children: Any) -> Any:
+            return visited_children or node.text
+
+    out: list[float] = []
+    for m in _ENERGY_LINE_RE.finditer(text):
+        line = m.group(0).strip()
+        try:
+            tree = g.parse(line)
+        except Exception:  # noqa: BLE001 — skip non-conforming noise
+            continue
+        v = EnergyVisitor()
+        v.visit(tree)
+        if v.value is not None:
+            out.append(v.value)
+    return out
+
+
+def extract_cartesian_angstrom_blocks(text: str) -> list[list[OrcaAtomCoord]]:
+    """Parse every ``CARTESIAN COORDINATES (ANGSTROEM)`` block via grammar."""
+    g = _cart_g()
+    NodeVisitor = get_node_visitor_class()
+
+    class CartVisitor(NodeVisitor):
+        def __init__(self) -> None:
+            self.atoms: list[OrcaAtomCoord] = []
+
+        def visit_atom_line(self, node: Any, visited_children: Any) -> OrcaAtomCoord:
+            flat = _flatten(visited_children)
+            symbol = next(
+                x for x in flat if isinstance(x, str) and x.strip() and x[0].isalpha()
+            )
+            nums = [x for x in flat if isinstance(x, float)]
+            atom = OrcaAtomCoord(symbol=symbol, x=nums[0], y=nums[1], z=nums[2])
+            self.atoms.append(atom)
+            return atom
+
+        def visit_atype(self, node: Any, visited_children: Any) -> str:
+            return node.text
+
+        def visit_float_(self, node: Any, visited_children: Any) -> float:
+            return float(node.text)
+
+        def generic_visit(self, node: Any, visited_children: Any) -> Any:
+            return visited_children or node.text
+
+    blocks: list[list[OrcaAtomCoord]] = []
+    for m in _CART_BLOCK_RE.finditer(text):
+        chunk = (
+            "CARTESIAN COORDINATES (ANGSTROEM)\n"
+            "---------------------------------\n"
+            + m.group(1)
+        )
+        if not chunk.endswith("\n"):
+            chunk += "\n"
+        try:
+            tree = g.parse(chunk)
+        except Exception:  # noqa: BLE001
+            continue
+        v = CartVisitor()
+        v.visit(tree)
+        if v.atoms:
+            blocks.append(v.atoms)
+    return blocks
+
+
+def extract_n_atoms(text: str) -> int | None:
+    """Best-effort ``Number of atoms`` from ORCA text (last occurrence)."""
+    matches = _N_ATOMS_RE.findall(text)
+    if not matches:
+        return None
+    return int(matches[-1])
+
+
+def parse_orca_text_summary(text: str) -> OrcaTextSummary:
+    """Summarize final energies and last Cartesian geometry from ORCA text."""
+    energies = extract_final_energies_hartree(text)
+    blocks = extract_cartesian_angstrom_blocks(text)
+    last_geom: tuple[OrcaAtomCoord, ...] = ()
+    if blocks:
+        last_geom = tuple(blocks[-1])
+    return OrcaTextSummary(
+        energies_hartree=tuple(energies),
+        last_geometry=last_geom,
+        n_atoms=extract_n_atoms(text),
+    )
+
+
+def parse_orca_text_file(path: str | Path) -> OrcaTextSummary:
+    """Read an ORCA ``.out`` and return :class:`OrcaTextSummary`."""
+    return parse_orca_text_summary(Path(path).read_text())

chemparseplot-1.9.9/chemparseplot/parse/grammar/xyz.py

@@ -0,0 +1,181 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""XYZ grammar (parsimonious) for multi-atom frames.
+
+Port of the wailord paper thesis: structured grammar parsing for XYZ rather
+than ad-hoc line splits. Multi-character element symbols and scientific
+floats are supported.
+
+```{versionadded} 1.9.9
+```
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from chemparseplot.parse.grammar._deps import (
+    get_grammar_class,
+    get_node_visitor_class,
+)
+
+# Each rule that needs a visitor must be a real expression (not an alias);
+# parsimonious collapses pure aliases so visit_natoms would never fire.
+_XYZ_GRAMMAR_SRC = r"""
+meta          = natoms newline comment_line newline coord_block ws?
+natoms        = ~r"\d+"
+comment_line  = ~r"[^\n]*"
+coord_block   = (aline newline?)+
+aline         = ws? atype ws float_ ws float_ ws float_ ws?
+atype         = ~r"[A-Za-z][a-zA-Z0-9]{0,2}"
+float_        = ~r"[+-]?(?:\d+\.\d*|\.\d+|\d+)(?:[eE][+-]?\d+)?"
+newline       = ~r"\n"
+ws            = ~r"[ \t]+"
+"""
+
+_grammar_cache: Any | None = None
+
+
+def xyz_grammar() -> Any:
+    """Compiled XYZ grammar (cached)."""
+    global _grammar_cache
+    if _grammar_cache is None:
+        Grammar = get_grammar_class()
+        _grammar_cache = Grammar(_XYZ_GRAMMAR_SRC)
+    return _grammar_cache
+
+
+@dataclass(frozen=True, slots=True)
+class XyzAtom:
+    """One atom line: element symbol and Cartesian coordinates (Å)."""
+
+    symbol: str
+    x: float
+    y: float
+    z: float
+
+
+@dataclass(frozen=True, slots=True)
+class XyzFrame:
+    """Parsed single-frame XYZ."""
+
+    natoms: int
+    comment: str
+    atoms: tuple[XyzAtom, ...]
+
+    @property
+    def symbols(self) -> list[str]:
+        return [a.symbol for a in self.atoms]
+
+    @property
+    def counts(self) -> Counter:
+        return Counter(self.symbols)
+
+    @property
+    def system(self) -> str:
+        """Composition slug as ``ElementCount`` joined (e.g. ``H2``, ``C1O2``)."""
+        flat: list[str] = []
+        for elem, n in self.counts.items():
+            flat.append(elem)
+            flat.append(str(n))
+        return "".join(flat)
+
+    def coordinates(self) -> list[tuple[float, float, float]]:
+        return [(a.x, a.y, a.z) for a in self.atoms]
+
+
+def _flatten(xs: Any) -> list[Any]:
+    out: list[Any] = []
+    if isinstance(xs, list):
+        for x in xs:
+            out.extend(_flatten(x))
+    elif xs is not None and xs != "":
+        out.append(xs)
+    return out
+
+
+def _make_visitor() -> Any:
+    NodeVisitor = get_node_visitor_class()
+
+    class XyzVisitor(NodeVisitor):
+        def __init__(self) -> None:
+            self.natoms: int | None = None
+            self.comment: str = ""
+            self.atoms: list[XyzAtom] = []
+
+        def visit_natoms(self, node: Any, visited_children: Any) -> int:
+            self.natoms = int(node.text)
+            return self.natoms
+
+        def visit_comment_line(self, node: Any, visited_children: Any) -> str:
+            self.comment = node.text
+            return self.comment
+
+        def visit_aline(self, node: Any, visited_children: Any) -> XyzAtom:
+            flat = _flatten(visited_children)
+            symbol = next(x for x in flat if isinstance(x, str) and x.strip() and x[0].isalpha())
+            nums = [x for x in flat if isinstance(x, float)]
+            atom = XyzAtom(symbol=symbol, x=nums[0], y=nums[1], z=nums[2])
+            self.atoms.append(atom)
+            return atom
+
+        def visit_atype(self, node: Any, visited_children: Any) -> str:
+            return node.text
+
+        def visit_float_(self, node: Any, visited_children: Any) -> float:
+            return float(node.text)
+
+        def generic_visit(self, node: Any, visited_children: Any) -> Any:
+            return visited_children or node.text
+
+    return XyzVisitor()
+
+
+def parse_xyz_text(text: str) -> XyzFrame:
+    """Parse a single-frame XYZ string with the grammar visitor.
+
+    Parameters
+    ----------
+    text:
+        Full XYZ content including atom count and comment line.
+
+    Returns
+    -------
+    XyzFrame
+        Structured frame (natoms, comment, atoms).
+    """
+    body = text if text.endswith("\n") else text + "\n"
+    tree = xyz_grammar().parse(body)
+    visitor = _make_visitor()
+    visitor.visit(tree)
+    natoms = visitor.natoms if visitor.natoms is not None else len(visitor.atoms)
+    if natoms != len(visitor.atoms):
+        msg = f"XYZ natoms={natoms} but parsed {len(visitor.atoms)} atom lines"
+        raise ValueError(msg)
+    return XyzFrame(
+        natoms=natoms,
+        comment=visitor.comment,
+        atoms=tuple(visitor.atoms),
+    )
+
+
+def parse_xyz_file(path: str | Path) -> XyzFrame:
+    """Read and parse an XYZ file."""
+    return parse_xyz_text(Path(path).read_text())
+
+
+def write_xyz_text(
+    frame: XyzFrame,
+    *,
+    comment: str | None = None,
+) -> str:
+    """Serialize a frame back to XYZ text (Å)."""
+    c = frame.comment if comment is None else comment
+    lines = [str(frame.natoms), c.rstrip("\n")]
+    for a in frame.atoms:
+        lines.append(f"{a.symbol:3s} {a.x:12.5f} {a.y:12.5f} {a.z:12.5f}")
+    return "\n".join(lines) + "\n"