chemparseplot 1.9.7__tar.gz → 1.9.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemparseplot
-Version: 1.9.7
+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'
@@ -115,6 +122,18 @@ publication-quality plots.
 ## Installation
 
     pip install chemparseplot
+
+Suite config (shared with rgpycrumbs — **no** `~/.config/chemparseplot`):
+
+    # ~/.config/rgpkgs/config.toml  or  ./rgpkgs.toml
+    # [pins] lock = "uv.lock"
+    # [pins.packages] …
+
+Feature extras (`plot`, `neb`, …) are *transitional* install convenience. Target
+is the same on-demand uv / `ensure_import` design as the rgpycrumbs hub; prefer
+bare install + suite pins for new work.
+
+    # transitional:
     # With plotting support
     pip install "chemparseplot[plot]"
     # Everything

{chemparseplot-1.9.7 → 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.7'
-__version_tuple__ = version_tuple = (1, 9, 7)
+__version__ = version = '1.9.9'
+__version_tuple__ = version_tuple = (1, 9, 9)
 
 __commit_id__ = commit_id = None

chemparseplot-1.9.9/chemparseplot/api.py

@@ -0,0 +1,143 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""Stable public library entry points for chemparseplot.
+
+Prefer this module for new consumers (cookbooks, wailord, notebooks).
+
+**Representative in-process path (parse → typed result):**
+
+.. code-block:: python
+
+    from chemparseplot.api import extract_orca_geomscan_energy
+
+    dist_bohr, energy_Eh = extract_orca_geomscan_energy(orca_out_text, "Actual Energy")
+    # dist_bohr, energy_Eh are pint Quantities (bohr, hartree)
+
+Heavy plot stacks still live under ``chemparseplot.plot`` (optional deps /
+transitional extras until suite uv design fully covers them).
+
+Suite pins/config: use ``rgpycrumbs.api`` (shared rgpkgs TOML) — this package
+does **not** invent ``~/.config/chemparseplot``.
+
+.. versionadded:: 1.9.8
+.. versionchanged:: 1.9.9
+   Expose ORCA geomscan energy parse as the stable library path.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from chemparseplot.parse.orca.geomscan import extract_energy_data
+from chemparseplot.units import (
+    ENERGY_UNITS,
+    convert_energy_magnitude,
+    energy_quantity,
+    normalize_energy_unit,
+)
+
+if TYPE_CHECKING:
+    from chemparseplot.units import Q_
+
+__all__ = [
+    "ENERGY_UNITS",
+    "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_]:
+    """Parse ORCA geometry-scan surface energies from output text.
+
+    In-process library path: text → typed ``(distance, energy)`` pint Quantities
+    in Bohr and Hartree (ORCA defaults).
+
+    Parameters
+    ----------
+    data:
+        Blob of ORCA output containing ``Calculated Surface`` blocks.
+    energy_type:
+        ``\"Actual Energy\"`` or ``\"SCF energy\"`` (substring match in the block).
+
+    Returns
+    -------
+    tuple[Q_, Q_]
+        Distances (bohr) and energies (hartree). Empty quantities if no match.
+    """
+    return extract_energy_data(data, energy_type)
+
+
+def suite_pins() -> dict[str, str]:
+    """Return suite package pins from rgpkgs config + env (soft on old hub).
+
+    Empty dict if rgpycrumbs is missing or too old.
+    """
+    try:
+        from rgpycrumbs.api import load_config, pins_from_env
+    except ImportError:
+        return {}
+    pins = dict(pins_from_env())
+    try:
+        cfg = load_config()
+        pins.update(cfg.merged_package_pins_normalized())
+    except Exception:  # noqa: BLE001 — soft fail for consumers
+        pass
+    return pins

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())