chemparseplot 1.9.13__tar.gz → 1.9.15__tar.gz

{chemparseplot-1.9.13 → chemparseplot-1.9.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemparseplot
-Version: 1.9.13
+Version: 1.9.15
 Summary: Parsers and plotting tools for computational chemistry
 Project-URL: Documentation, https://chemparseplot.rgoswami.me
 Project-URL: Issues, https://github.com/HaoZeke/chemparseplot/issues

{chemparseplot-1.9.13 → chemparseplot-1.9.15}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.9.13'
-__version_tuple__ = version_tuple = (1, 9, 13)
+__version__ = version = '1.9.15'
+__version_tuple__ = version_tuple = (1, 9, 15)
 
 __commit_id__ = commit_id = None

{chemparseplot-1.9.13 → chemparseplot-1.9.15}/chemparseplot/parse/eon/__init__.py

@@ -3,6 +3,6 @@
 # SPDX-License-Identifier: MIT
 """eOn trajectory parsers."""
 
-from chemparseplot.parse.eon import con_io
+from chemparseplot.parse.eon import con_io, frame_series
 
-__all__ = ["con_io"]
+__all__ = ["con_io", "frame_series"]

chemparseplot-1.9.15/chemparseplot/parse/eon/frame_series.py

@@ -0,0 +1,191 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""ConFrame sequence → series / trajectory DTOs for eOn plots.
+
+The plot packet is an ordered sequence of ``readcon.ConFrame`` (or duck-typed
+frames with ``energy``, ``metadata``, ``to_ase`` / geometry). ASE and Matter
+are adapters into this wire format; this module does not invent a second schema.
+
+```{versionadded} 1.9.14
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+import polars as pl
+from ase import Atoms
+
+from chemparseplot.parse.eon._trajectory_common import (
+    frame_rows_to_table,
+    metadata_value,
+)
+from chemparseplot.parse.eon.dimer_trajectory import (
+    DIMER_METADATA_COLUMNS,
+    DimerTrajectoryData,
+    table_from_dimer_metadata,
+)
+from chemparseplot.parse.eon.min_trajectory import (
+    MIN_METADATA_COLUMNS,
+    MinTrajectoryData,
+    table_from_min_metadata,
+)
+
+__all__ = [
+    "atoms_list_from_frames",
+    "dimer_trajectory_from_frames",
+    "energies_from_frames",
+    "min_trajectory_from_frames",
+    "neb_path_arrays",
+    "series_from_frames",
+]
+
+
+def energies_from_frames(frames: Sequence[Any]) -> np.ndarray:
+    """Total energy (eV) per frame; raises if any frame lacks energy."""
+    if not frames:
+        msg = "energies_from_frames: empty frame sequence"
+        raise ValueError(msg)
+    out = np.empty(len(frames), dtype=float)
+    for i, frame in enumerate(frames):
+        e = metadata_value(frame, "energy")
+        if e is None:
+            msg = f"frame {i} has no energy stamp"
+            raise ValueError(msg)
+        out[i] = float(e)
+    return out
+
+
+def atoms_list_from_frames(frames: Sequence[Any]) -> list[Atoms]:
+    """Convert frames to ASE Atoms with energy stored in ``atoms.info``."""
+    atoms_list: list[Atoms] = []
+    for i, frame in enumerate(frames):
+        to_ase = getattr(frame, "to_ase", None)
+        if not callable(to_ase):
+            msg = f"frame {i} has no to_ase(); need readcon.ConFrame or equivalent"
+            raise TypeError(msg)
+        atoms = to_ase()
+        e = metadata_value(frame, "energy")
+        if e is not None:
+            atoms.info["energy"] = float(e)
+        atoms_list.append(atoms)
+    return atoms_list
+
+
+def series_from_frames(
+    frames: Sequence[Any],
+    columns: Sequence[str],
+    *,
+    allow_leading_incomplete: bool = False,
+) -> pl.DataFrame:
+    """Build a polars table of metadata columns from frames (empty if incomplete)."""
+    return frame_rows_to_table(
+        frames,
+        columns,
+        allow_leading_incomplete=allow_leading_incomplete,
+    )
+
+
+def neb_path_arrays(frames: Sequence[Any]) -> dict[str, Any]:
+    """Extract NEB path series from stamped frames (writePathCon / path_frames).
+
+    Returns
+    -------
+    dict
+        ``atoms_list``, ``energies``, optional ``reaction_coordinate``,
+        ``relative_energy``, ``parallel_force``, ``neb_bead``, ``frame_index``.
+    """
+    if not frames:
+        msg = "neb_path_arrays: empty frame sequence"
+        raise ValueError(msg)
+    atoms_list = atoms_list_from_frames(frames)
+    energies = energies_from_frames(frames)
+    result: dict[str, Any] = {
+        "atoms_list": atoms_list,
+        "energies": energies,
+        "n_frames": len(frames),
+    }
+    for key in (
+        "reaction_coordinate",
+        "relative_energy",
+        "parallel_force",
+        "neb_bead",
+        "frame_index",
+        "lowest_eigenvalue",
+    ):
+        vals = []
+        ok = True
+        for frame in frames:
+            v = metadata_value(frame, key)
+            if v is None and key in ("reaction_coordinate", "relative_energy", "parallel_force"):
+                # optional NEB stamps
+                ok = False
+                break
+            vals.append(v)
+        if ok and any(v is not None for v in vals):
+            result[key] = np.array(
+                [np.nan if v is None else float(v) for v in vals],
+                dtype=float,
+            )
+    return result
+
+
+def min_trajectory_from_frames(frames: Sequence[Any]) -> MinTrajectoryData:
+    """Build :class:`MinTrajectoryData` from stamped minimization ConFrames."""
+    if not frames:
+        msg = "min_trajectory_from_frames: empty frame sequence"
+        raise ValueError(msg)
+    atoms_list = atoms_list_from_frames(frames)
+    dat_df = table_from_min_metadata(list(frames))
+    if dat_df.is_empty():
+        # Minimal table from energy + sequential iteration
+        energies = energies_from_frames(frames)
+        dat_df = pl.DataFrame(
+            {
+                "iteration": list(range(len(frames))),
+                "step_size": [0.0] * len(frames),
+                "convergence": [0.0] * len(frames),
+                "energy": energies.tolist(),
+            }
+        )
+    return MinTrajectoryData(
+        atoms_list=atoms_list,
+        dat_df=dat_df,
+        initial_atoms=atoms_list[0],
+        final_atoms=atoms_list[-1],
+    )
+
+
+def dimer_trajectory_from_frames(frames: Sequence[Any]) -> DimerTrajectoryData:
+    """Build :class:`DimerTrajectoryData` from stamped climb ConFrames."""
+    if not frames:
+        msg = "dimer_trajectory_from_frames: empty frame sequence"
+        raise ValueError(msg)
+    atoms_list = atoms_list_from_frames(frames)
+    dat_df = table_from_dimer_metadata(list(frames))
+    if dat_df.is_empty():
+        energies = energies_from_frames(frames)
+        e0 = float(energies[0])
+        dat_df = pl.DataFrame(
+            {
+                "iteration": list(range(len(frames))),
+                "step_size": [0.0] * len(frames),
+                "delta_e": (energies - e0).tolist(),
+                "convergence": [0.0] * len(frames),
+                "eigenvalue": [0.0] * len(frames),
+                "torque": [0.0] * len(frames),
+                "angle": [0.0] * len(frames),
+                "rotations": [0] * len(frames),
+            }
+        )
+    return DimerTrajectoryData(
+        atoms_list=atoms_list,
+        dat_df=dat_df,
+        initial_atoms=atoms_list[0],
+        saddle_atoms=atoms_list[-1],
+        mode_vector=None,
+    )

{chemparseplot-1.9.13 → chemparseplot-1.9.15}/chemparseplot/plot/neb.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import io
 import logging
 import shutil
-import subprocess
 import tempfile
 from dataclasses import dataclass
 from pathlib import Path
@@ -198,20 +197,40 @@ def render_structure_to_image(atoms, zoom, rotation):  # noqa: ARG001
     return img_data
 
 
+def _import_xyzrender():
+    """Import xyzrender via ensure_import (AUTO_DEPS) or a normal import.
+
+    Prefer the Python API over a PATH binary. Matches the suite lazy-dep model
+    (rgpycrumbs ``ensure_import`` / ``RGPYCRUMBS_AUTO_DEPS``).
+    """
+    try:
+        from rgpycrumbs._aux import enable_library_auto_deps, ensure_import
+
+        enable_library_auto_deps()
+        return ensure_import("xyzrender")
+    except ImportError:
+        pass
+    try:
+        import xyzrender
+    except ImportError as exc:
+        msg = (
+            "xyzrender is required for strip_renderer='xyzrender'. "
+            "Install with: pip install 'xyzrender>=0.1.3' "
+            "(or set RGPYCRUMBS_AUTO_DEPS=1 so ensure_import can stage it)"
+        )
+        raise RuntimeError(msg) from exc
+    return xyzrender
+
+
 def _check_xyzrender():
-    """Verify that the ``xyzrender`` binary is on PATH.
+    """Verify xyzrender is importable (package or ensure_import cache).
 
     Raises
     ------
     RuntimeError
-        If xyzrender is not found, with install instructions.
+        If xyzrender cannot be imported, with install instructions.
     """
-    if shutil.which("xyzrender") is None:
-        msg = (
-            "xyzrender binary not found on PATH. "
-            "Install with: pip install 'xyzrender>=0.1.3'"
-        )
-        raise RuntimeError(msg)
+    _import_xyzrender()
 
 
 def _apply_perspective_tilt(atoms, tilt_deg=8.0):
@@ -267,9 +286,8 @@ def _parse_rotation_angles(rotation_str):
 def _render_xyzrender(atoms, rotation="auto", canvas_size=400, config="paton"):
     """Render an ASE Atoms object to a numpy RGBA array via xyzrender.
 
-    Uses the specified config preset (default: ``paton`` for ball-and-stick).
-    Other useful presets: ``bubble`` (space-filling, good for surfaces),
-    ``flat``, ``tube``, ``wire``, ``skeletal``.
+    Uses the **Python API** (``xyzrender.render``), staged through
+    ``ensure_import`` when ``RGPYCRUMBS_AUTO_DEPS=1`` — not a PATH binary.
 
     Parameters
     ----------
@@ -280,15 +298,18 @@ def _render_xyzrender(atoms, rotation="auto", canvas_size=400, config="paton"):
         Any ASE-style string (e.g. ``"0x,90y,0z"``) disables auto-orient
         and pre-rotates the atoms.
     canvas_size : int
-        Output image width/height in pixels (passed as ``-S``).
+        Output image width/height in pixels.
 
     Returns
     -------
     numpy.ndarray
         RGBA image array with shape ``(H, W, 4)`` and float dtype.
     """
+    import os
+
     from ase.io import write as _ase_write
 
+    xr = _import_xyzrender()
     with tempfile.NamedTemporaryFile(suffix=".xyz", delete=False) as xyz_fh:
         xyz_path = xyz_fh.name
     png_path = xyz_path.rsplit(".", 1)[0] + ".png"
@@ -299,31 +320,23 @@ def _render_xyzrender(atoms, rotation="auto", canvas_size=400, config="paton"):
 
         if has_custom_rotation:
             rx, ry, rz = _parse_rotation_angles(rotation)
-            # Pre-rotate and disable auto-orient
             atoms.rotate(rx, "x", center="COP")
             atoms.rotate(ry, "y", center="COP")
             atoms.rotate(rz, "z", center="COP")
 
         _ase_write(xyz_path, atoms, format="xyz")
-        cmd = [
-            "xyzrender",
+        # Python API: same knobs as CLI --hy -t -S --config
+        xr.render(
             xyz_path,
-            "-o",
-            png_path,
-            "-S",
-            str(canvas_size),
-            "--config",
-            config,
-            "--hy",
-            "-t",
-        ]
-        if has_custom_rotation:
-            cmd.append("--no-orient")
-        subprocess.run(cmd, check=True, capture_output=True)  # noqa: S603
+            config=config,
+            canvas_size=canvas_size,
+            hy=True,
+            transparent=True,
+            orient=not has_custom_rotation,
+            output=png_path,
+        )
         img_data = plt.imread(png_path)
     finally:
-        import os
-
         for p in (xyz_path, png_path):
             try:
                 os.unlink(p)

chemparseplot-1.9.15/tests/parse/test_frame_series.py

@@ -0,0 +1,121 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""ConFrame sequence → series used by eOn plot paths."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+pytest.importorskip("readcon")
+pytest.importorskip("ase")
+pytest.importorskip("polars")
+
+from ase import Atoms
+
+from chemparseplot.parse.eon.frame_series import (
+    atoms_list_from_frames,
+    dimer_trajectory_from_frames,
+    energies_from_frames,
+    min_trajectory_from_frames,
+    neb_path_arrays,
+)
+
+
+def _h_frame(energy: float, z: float, *, frame_index: int, **scalars):
+    import readcon
+
+    atoms = Atoms("H", positions=[[0.0, 0.0, z]], cell=[10, 10, 10], pbc=False)
+    frame = readcon.ConFrame.from_ase(atoms)
+    frame.set_energy(float(energy))
+    frame.set_frame_index(int(frame_index))
+    for key, value in scalars.items():
+        frame.set_scalar_metadata(key, float(value) if isinstance(value, float) else value)
+    return frame
+
+
+def test_energies_from_frames_match_stamps():
+    frames = [_h_frame(1.0 + 0.1 * i, float(i), frame_index=i) for i in range(4)]
+    e = energies_from_frames(frames)
+    assert e.shape == (4,)
+    assert np.allclose(e, [1.0, 1.1, 1.2, 1.3])
+
+
+def test_energies_from_frames_missing_raises():
+    import readcon
+    from ase import Atoms
+
+    bare = readcon.ConFrame.from_ase(Atoms("H", positions=[[0, 0, 0]]))
+    with pytest.raises(ValueError, match="no energy"):
+        energies_from_frames([bare])
+
+
+def test_neb_path_arrays_length_and_stamps():
+    frames = []
+    for i in range(5):
+        fr = _h_frame(
+            -10.0 + i,
+            0.1 * i,
+            frame_index=i,
+            reaction_coordinate=0.2 * i,
+            relative_energy=float(i),
+            parallel_force=-0.01 * i,
+        )
+        fr.set_neb_bead(i)
+        frames.append(fr)
+    path = neb_path_arrays(frames)
+    assert path["n_frames"] == 5
+    assert len(path["atoms_list"]) == 5
+    assert np.allclose(path["energies"], [-10, -9, -8, -7, -6])
+    assert np.allclose(path["reaction_coordinate"], [0.0, 0.2, 0.4, 0.6, 0.8])
+    assert np.allclose(path["relative_energy"], [0, 1, 2, 3, 4])
+    assert path["atoms_list"][0].info["energy"] == pytest.approx(-10.0)
+
+
+def test_min_trajectory_from_frames_metrics():
+    frames = [
+        _h_frame(
+            -5.0 + 0.5 * i,
+            0.0,
+            frame_index=i,
+            step_size=0.1 * (i + 1),
+            convergence=1.0 / (i + 1),
+        )
+        for i in range(3)
+    ]
+    traj = min_trajectory_from_frames(frames)
+    assert len(traj.atoms_list) == 3
+    assert traj.dat_df.height == 3
+    assert "energy" in traj.dat_df.columns
+    assert traj.dat_df["energy"].to_list() == pytest.approx([-5.0, -4.5, -4.0])
+    assert traj.final_atoms is traj.atoms_list[-1]
+
+
+def test_dimer_trajectory_from_frames_metrics():
+    frames = [
+        _h_frame(
+            0.0 + i,
+            0.0,
+            frame_index=i,
+            step_size=0.05,
+            delta_e=float(i),
+            convergence=0.1,
+            eigenvalue=-1.0,
+            torque=0.0,
+            angle=0.0,
+            rotations=0,
+        )
+        for i in range(3)
+    ]
+    # rotations may need int via set_scalar_metadata
+    traj = dimer_trajectory_from_frames(frames)
+    assert len(traj.atoms_list) == 3
+    assert traj.dat_df.height == 3
+    assert "delta_e" in traj.dat_df.columns or "energy" in traj.dat_df.columns
+
+
+def test_atoms_list_from_frames_preserves_energy_info():
+    frames = [_h_frame(2.5, 0.0, frame_index=0)]
+    atoms = atoms_list_from_frames(frames)
+    assert atoms[0].info["energy"] == pytest.approx(2.5)

{chemparseplot-1.9.13 → chemparseplot-1.9.15}/tests/plot/test_neb_renderers.py

@@ -44,26 +44,33 @@ class TestRenderStructureToImage:
 
 
 class TestCheckXyzrender:
-    """Binary availability check."""
+    """Package importability (ensure_import / site-packages), not PATH binary."""
 
-    def test_missing_binary_raises(self):
-        with patch.object(shutil, "which", return_value=None):
-            with pytest.raises(RuntimeError, match="xyzrender binary not found"):
+    def test_missing_package_raises(self):
+        import builtins
+        real_import = builtins.__import__
+
+        def fake_import(name, *a, **k):
+            if name == "xyzrender" or name.startswith("xyzrender."):
+                raise ImportError("blocked")
+            if name == "rgpycrumbs" or name.startswith("rgpycrumbs."):
+                raise ImportError("blocked")
+            return real_import(name, *a, **k)
+
+        with patch.object(builtins, "__import__", side_effect=fake_import):
+            with pytest.raises(RuntimeError, match="xyzrender is required"):
                 _check_xyzrender()
 
-    def test_present_binary_passes(self):
-        with patch.object(shutil, "which", return_value="/usr/bin/xyzrender"):
-            _check_xyzrender()
+    def test_present_package_passes(self):
+        pytest.importorskip("xyzrender")
+        _check_xyzrender()
 
 
 class TestRenderXyzrender:
-    """xyzrender subprocess renderer."""
+    """xyzrender Python API renderer."""
 
-    @pytest.mark.skipif(
-        shutil.which("xyzrender") is None,
-        reason="xyzrender not installed",
-    )
     def test_produces_image(self, water):
+        pytest.importorskip("xyzrender")
         img = _render_xyzrender(water, canvas_size=200)
         assert isinstance(img, np.ndarray)
         assert img.ndim == 3