chemparseplot 1.4.1__tar.gz → 1.5.0__tar.gz

{chemparseplot-1.4.1 → chemparseplot-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemparseplot
-Version: 1.4.1
+Version: 1.5.0
 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.4.1 → chemparseplot-1.5.0}/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.4.1'
-__version_tuple__ = version_tuple = (1, 4, 1)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)
 
 __commit_id__ = commit_id = None

{chemparseplot-1.4.1 → chemparseplot-1.5.0}/chemparseplot/parse/__init__.py

@@ -2,8 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 
-from chemparseplot.parse import orca, patterns
+from chemparseplot.parse import eon, orca, patterns
 
 # Lazy imports for modules with optional heavy deps (h5py, pandas)
 # Import directly: from chemparseplot.parse.chemgp_hdf5 import read_h5_table
-# Or: from chemparseplot.parse import plumed
+# Or: from chemparseplot.parse import plumed, projection

chemparseplot-1.5.0/chemparseplot/parse/eon/__init__.py

@@ -0,0 +1 @@
+"""eOn trajectory parsers."""

chemparseplot-1.5.0/chemparseplot/parse/eon/dimer_trajectory.py

@@ -0,0 +1,154 @@
+"""Dimer/saddle search trajectory parser for eOn output.
+
+Reads structured per-iteration data from ``climb.dat`` (TSV) and
+concatenated trajectory from ``climb.con`` (movie file), as produced
+by eOn with ``write_movies=true``.
+
+.. versionadded:: 1.5.0
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import polars as pl
+from ase import Atoms
+from ase.io import read as ase_read
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class DimerTrajectoryData:
+    """Container for a dimer/saddle search trajectory.
+
+    Attributes
+    ----------
+    atoms_list
+        Per-iteration structures from the movie file.
+    dat_df
+        Polars DataFrame with per-iteration metrics from ``climb.dat``.
+    initial_atoms
+        Starting structure (from ``reactant.con`` or ``pos.con``).
+    saddle_atoms
+        Final saddle point structure (from ``saddle.con``), or None.
+    mode_vector
+        Eigenvector at the saddle (from ``mode.dat``), or None.
+    """
+
+    atoms_list: list[Atoms]
+    dat_df: pl.DataFrame
+    initial_atoms: Atoms
+    saddle_atoms: Atoms | None = None
+    mode_vector: np.ndarray | None = None
+
+
+def parse_climb_dat(path: Path) -> pl.DataFrame:
+    """Read the structured ``climb.dat`` TSV file.
+
+    Parameters
+    ----------
+    path
+        Path to the ``climb.dat`` file.
+
+    Returns
+    -------
+    pl.DataFrame
+        DataFrame with columns matching the TSV header.
+    """
+    return pl.read_csv(path, separator="\t")
+
+
+def parse_climb_con(path: Path) -> list[Atoms]:
+    """Read concatenated structures from the ``climb.con`` movie file.
+
+    Parameters
+    ----------
+    path
+        Path to the ``climb`` or ``climb.con`` file.
+
+    Returns
+    -------
+    list[Atoms]
+        List of ASE Atoms objects, one per iteration.
+    """
+    # eOn .con files may not have a .con extension for movie files
+    atoms_list = ase_read(str(path), index=":", format="eon")
+    return list(atoms_list)
+
+
+def _find_initial_structure(job_dir: Path) -> Atoms | None:
+    """Locate the initial/reactant structure in the job directory."""
+    for name in ("reactant.con", "pos.con"):
+        p = job_dir / name
+        if p.exists():
+            return ase_read(str(p), format="eon")
+    return None
+
+
+def _load_mode_dat(path: Path) -> np.ndarray | None:
+    """Load eigenvector from mode.dat (Nx3 whitespace-separated)."""
+    if not path.exists():
+        return None
+    return np.loadtxt(path)
+
+
+def load_dimer_trajectory(job_dir: Path) -> DimerTrajectoryData:
+    """Load a complete dimer/saddle search trajectory from an eOn job directory.
+
+    Expects the job to have been run with ``write_movies=true``.
+
+    Parameters
+    ----------
+    job_dir
+        Path to the eOn job output directory containing ``climb``,
+        ``climb.dat``, ``saddle.con``, etc.
+
+    Returns
+    -------
+    DimerTrajectoryData
+        Combined trajectory data.
+
+    Raises
+    ------
+    FileNotFoundError
+        If required files (``climb``, ``climb.dat``) are missing.
+    """
+    # Find the movie file (may be "climb" or "climb.con")
+    climb_con = job_dir / "climb"
+    if not climb_con.exists():
+        climb_con = job_dir / "climb.con"
+    if not climb_con.exists():
+        msg = f"No climb movie file found in {job_dir}"
+        raise FileNotFoundError(msg)
+
+    climb_dat = job_dir / "climb.dat"
+    if not climb_dat.exists():
+        msg = f"No climb.dat found in {job_dir} (was write_movies enabled?)"
+        raise FileNotFoundError(msg)
+
+    log.info("Loading dimer trajectory from %s", job_dir)
+    atoms_list = parse_climb_con(climb_con)
+    dat_df = parse_climb_dat(climb_dat)
+    log.info("Loaded %d frames, %d data rows", len(atoms_list), dat_df.height)
+
+    initial = _find_initial_structure(job_dir)
+    if initial is None:
+        log.warning("No reactant.con or pos.con found; using first movie frame")
+        initial = atoms_list[0]
+
+    saddle_path = job_dir / "saddle.con"
+    saddle = ase_read(str(saddle_path), format="eon") if saddle_path.exists() else None
+
+    mode = _load_mode_dat(job_dir / "mode.dat")
+
+    return DimerTrajectoryData(
+        atoms_list=atoms_list,
+        dat_df=dat_df,
+        initial_atoms=initial,
+        saddle_atoms=saddle,
+        mode_vector=mode,
+    )

chemparseplot-1.5.0/chemparseplot/parse/eon/min_trajectory.py

@@ -0,0 +1,133 @@
+"""Minimization trajectory parser for eOn output.
+
+Reads structured per-iteration data from the minimization ``.dat`` file
+and concatenated trajectory from the movie ``.con`` file, as produced
+by eOn with ``write_movies=true``.
+
+.. versionadded:: 1.5.0
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import polars as pl
+from ase import Atoms
+from ase.io import read as ase_read
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class MinTrajectoryData:
+    """Container for a minimization trajectory.
+
+    Attributes
+    ----------
+    atoms_list
+        Per-iteration structures from the movie file.
+    dat_df
+        Polars DataFrame with per-iteration metrics.
+    initial_atoms
+        Starting structure (first frame).
+    final_atoms
+        Final minimized structure (from ``min.con`` or last frame).
+    """
+
+    atoms_list: list[Atoms]
+    dat_df: pl.DataFrame
+    initial_atoms: Atoms
+    final_atoms: Atoms
+
+
+def parse_min_dat(path: Path) -> pl.DataFrame:
+    """Read the structured minimization TSV data file.
+
+    Parameters
+    ----------
+    path
+        Path to the minimization ``.dat`` file.
+
+    Returns
+    -------
+    pl.DataFrame
+        DataFrame with columns: iteration, step_size, convergence, energy.
+    """
+    return pl.read_csv(path, separator="\t")
+
+
+def parse_min_con(path: Path) -> list[Atoms]:
+    """Read concatenated structures from the minimization movie file.
+
+    Parameters
+    ----------
+    path
+        Path to the movie ``.con`` file.
+
+    Returns
+    -------
+    list[Atoms]
+        List of ASE Atoms objects, one per iteration.
+    """
+    atoms_list = ase_read(str(path), index=":", format="eon")
+    return list(atoms_list)
+
+
+def load_min_trajectory(
+    job_dir: Path,
+    prefix: str = "min",
+) -> MinTrajectoryData:
+    """Load a complete minimization trajectory from an eOn job directory.
+
+    Expects the job to have been run with ``write_movies=true``.
+
+    Parameters
+    ----------
+    job_dir
+        Path to the eOn job output directory.
+    prefix
+        Movie file prefix (default ``"min"``). The movie file is
+        ``{prefix}`` and the data file is ``{prefix}.dat``.
+
+    Returns
+    -------
+    MinTrajectoryData
+        Combined trajectory data.
+
+    Raises
+    ------
+    FileNotFoundError
+        If required files are missing.
+    """
+    movie_file = job_dir / prefix
+    if not movie_file.exists():
+        movie_file = job_dir / f"{prefix}.con"
+    if not movie_file.exists():
+        msg = f"No minimization movie file ({prefix}) found in {job_dir}"
+        raise FileNotFoundError(msg)
+
+    dat_file = job_dir / f"{prefix}.dat"
+    if not dat_file.exists():
+        msg = f"No {prefix}.dat found in {job_dir} (was write_movies enabled?)"
+        raise FileNotFoundError(msg)
+
+    log.info("Loading minimization trajectory from %s", job_dir)
+    atoms_list = parse_min_con(movie_file)
+    dat_df = parse_min_dat(dat_file)
+    log.info("Loaded %d frames, %d data rows", len(atoms_list), dat_df.height)
+
+    # Final structure: prefer explicit min.con, fall back to last movie frame
+    min_con = job_dir / "min.con"
+    if min_con.exists():
+        final = ase_read(str(min_con), format="eon")
+    else:
+        final = atoms_list[-1]
+
+    return MinTrajectoryData(
+        atoms_list=atoms_list,
+        dat_df=dat_df,
+        initial_atoms=atoms_list[0],
+        final_atoms=final,
+    )

{chemparseplot-1.4.1 → chemparseplot-1.5.0}/chemparseplot/parse/neb_utils.py

@@ -8,6 +8,8 @@ RMSD landscape coordinate calculation, synthetic 2D gradient projection,
 and landscape DataFrame construction.
 """
 
+from __future__ import annotations
+
 import logging
 
 import numpy as np
@@ -18,43 +20,56 @@ log = logging.getLogger(__name__)
 
 
 def calculate_landscape_coords(
-    atoms_list: list[Atoms], ira_instance, ira_kmax: float
+    atoms_list: list[Atoms],
+    ira_instance,
+    ira_kmax: float,
+    ref_a: Atoms | None = None,
+    ref_b: Atoms | None = None,
 ) -> tuple[np.ndarray, np.ndarray]:
-    """Calculate 2D landscape coordinates (RMSD-R, RMSD-P) for a path.
+    """Calculate 2D landscape coordinates (RMSD-A, RMSD-B) for a path.
 
     ```{versionadded} 1.2.0
     ```
 
-    Uses the first frame as reactant reference and the last as product.
+    ```{versionchanged} 1.5.0
+    Added *ref_a* and *ref_b* parameters for explicit reference structures.
+    ```
 
     :param atoms_list: List of ASE Atoms objects representing the path.
     :param ira_instance: An instantiated IRA object (or None).
     :param ira_kmax: kmax factor for IRA.
-    :return: A tuple of (rmsd_r, rmsd_p) arrays.
+    :param ref_a: Reference structure A. Defaults to ``atoms_list[0]``.
+    :param ref_b: Reference structure B. Defaults to ``atoms_list[-1]``.
+    :return: A tuple of (rmsd_a, rmsd_b) arrays.
     """
     from concurrent.futures import ThreadPoolExecutor
 
     from rgpycrumbs.geom.api.alignment import calculate_rmsd_from_ref
 
-    log.info("Calculating landscape coordinates (RMSD-R, RMSD-P)...")
+    if ref_a is None:
+        ref_a = atoms_list[0]
+    if ref_b is None:
+        ref_b = atoms_list[-1]
+
+    log.info("Calculating landscape coordinates (RMSD-A, RMSD-B)...")
     with ThreadPoolExecutor(max_workers=2) as pool:
-        fut_r = pool.submit(
+        fut_a = pool.submit(
             calculate_rmsd_from_ref,
             atoms_list,
             ira_instance,
-            ref_atom=atoms_list[0],
+            ref_atom=ref_a,
             ira_kmax=ira_kmax,
         )
-        fut_p = pool.submit(
+        fut_b = pool.submit(
             calculate_rmsd_from_ref,
             atoms_list,
             ira_instance,
-            ref_atom=atoms_list[-1],
+            ref_atom=ref_b,
             ira_kmax=ira_kmax,
         )
-        rmsd_r = fut_r.result()
-        rmsd_p = fut_p.result()
-    return rmsd_r, rmsd_p
+        rmsd_a = fut_a.result()
+        rmsd_b = fut_b.result()
+    return rmsd_a, rmsd_b
 
 
 def compute_synthetic_gradients(

{chemparseplot-1.4.1 → chemparseplot-1.5.0}/chemparseplot/parse/plumed.py

@@ -196,6 +196,12 @@ def calculate_fes_from_hills(hills, imin=1, imax=None, xlim=None, ylim=None, npo
 
             dx = max_cv1 - min_cv1
             dy = max_cv2 - min_cv2
+            if dx == 0:
+                sigma_x = np.max(hills_data[:, 3])
+                dx = 6 * sigma_x
+            if dy == 0:
+                sigma_y = np.max(hills_data[:, 4])
+                dy = 6 * sigma_y
             xlims = [min_cv1 - 0.05 * dx, max_cv1 + 0.05 * dx]
             ylims = [min_cv2 - 0.05 * dy, max_cv2 + 0.05 * dy]
 
@@ -247,6 +253,10 @@ def calculate_fes_from_hills(hills, imin=1, imax=None, xlim=None, ylim=None, npo
             # Determine grid boundaries
             min_cv1, max_cv1 = np.min(hills_data[:, 1]), np.max(hills_data[:, 1])
             dx = max_cv1 - min_cv1
+            if dx == 0:
+                # Single-point CV range: use 3*sigma as padding
+                sigma = np.max(hills_data[:, 2])
+                dx = 6 * sigma
             xlims = [min_cv1 - 0.05 * dx, max_cv1 + 0.05 * dx]
 
             # Override with user-defined or periodic limits

chemparseplot-1.5.0/chemparseplot/parse/projection.py

@@ -0,0 +1,149 @@
+"""Reaction valley (s, d) projection utilities.
+
+Extracts the 2D RMSD-plane rotation into reusable functions.
+The projection maps ``(rmsd_a, rmsd_b)`` coordinates into
+progress ``s`` (along the path) and deviation ``d`` (perpendicular).
+
+For NEB paths, reference A is the reactant and B is the product.
+For single-ended methods, A is the initial structure and B is the
+final (saddle or minimum).
+
+Implements the method from :cite:`goswami2026valley`.
+
+.. versionadded:: 1.5.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectionBasis:
+    """Orthonormal basis for the (s, d) reaction valley projection.
+
+    Attributes
+    ----------
+    a_start, b_start
+        RMSD values of the first point (origin of the rotated frame).
+    u_a, u_b
+        Unit vector along the path direction in (a, b) space.
+    v_a, v_b
+        Unit vector perpendicular to the path (``v = rotate(u, +90deg)``).
+    path_norm
+        Euclidean length of the path vector in (a, b) space.
+    """
+
+    a_start: float
+    b_start: float
+    u_a: float
+    u_b: float
+    v_a: float
+    v_b: float
+    path_norm: float
+
+
+def compute_projection_basis(
+    rmsd_a: np.ndarray,
+    rmsd_b: np.ndarray,
+) -> ProjectionBasis:
+    """Compute the projection basis from first/last points of the arrays.
+
+    Parameters
+    ----------
+    rmsd_a, rmsd_b
+        RMSD distance arrays (to reference A and B respectively).
+        The first element defines the origin; the last defines the
+        path direction.
+
+    Returns
+    -------
+    ProjectionBasis
+        Frozen dataclass with the orthonormal basis vectors.
+
+    Raises
+    ------
+    ValueError
+        If the path has zero length (first and last points coincide
+        in RMSD space).
+    """
+    a_start, b_start = float(rmsd_a[0]), float(rmsd_b[0])
+    a_end, b_end = float(rmsd_a[-1]), float(rmsd_b[-1])
+
+    vec_a, vec_b = a_end - a_start, b_end - b_start
+    path_norm = np.hypot(vec_a, vec_b)
+
+    if path_norm < 1e-12:  # noqa: PLR2004
+        msg = (
+            "Path has zero length in RMSD space "
+            f"(start=({a_start:.6f}, {b_start:.6f}), "
+            f"end=({a_end:.6f}, {b_end:.6f}))"
+        )
+        raise ValueError(msg)
+
+    u_a = vec_a / path_norm
+    u_b = vec_b / path_norm
+
+    return ProjectionBasis(
+        a_start=a_start,
+        b_start=b_start,
+        u_a=u_a,
+        u_b=u_b,
+        v_a=-u_b,
+        v_b=u_a,
+        path_norm=path_norm,
+    )
+
+
+def project_to_sd(
+    rmsd_a: np.ndarray,
+    rmsd_b: np.ndarray,
+    basis: ProjectionBasis,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Project (rmsd_a, rmsd_b) into (s, d) reaction valley coordinates.
+
+    Parameters
+    ----------
+    rmsd_a, rmsd_b
+        RMSD arrays to project.
+    basis
+        Pre-computed projection basis.
+
+    Returns
+    -------
+    s, d
+        Progress and deviation arrays.
+    """
+    da = rmsd_a - basis.a_start
+    db = rmsd_b - basis.b_start
+    s = da * basis.u_a + db * basis.u_b
+    d = da * basis.v_a + db * basis.v_b
+    return s, d
+
+
+def inverse_sd_to_ab(
+    s: np.ndarray,
+    d: np.ndarray,
+    basis: ProjectionBasis,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Map (s, d) grid coordinates back to (a, b) RMSD space.
+
+    Used for evaluating the RBF surface on a projected grid.
+
+    Parameters
+    ----------
+    s, d
+        Progress and deviation arrays (can be meshgrid raveled).
+    basis
+        Pre-computed projection basis.
+
+    Returns
+    -------
+    rmsd_a, rmsd_b
+        Coordinates in the original RMSD plane.
+    """
+    rmsd_a = basis.a_start + s * basis.u_a + d * basis.v_a
+    rmsd_b = basis.b_start + s * basis.u_b + d * basis.v_b
+    return rmsd_a, rmsd_b

{chemparseplot-1.4.1 → chemparseplot-1.5.0}/chemparseplot/plot/__init__.py

@@ -14,18 +14,11 @@ from chemparseplot.plot.theme import (
 
 # Lazy imports for submodules with heavy deps (cmcrameri, pint, etc.)
 def __getattr__(name):
-    if name == "geomscan":
-        from chemparseplot.plot import geomscan as _mod
+    import importlib
 
-        return _mod
-    if name == "structs":
-        from chemparseplot.plot import structs as _mod
-
-        return _mod
-    if name == "chemgp":
-        from chemparseplot.plot import chemgp as _mod
-
-        return _mod
+    lazy_submodules = {"geomscan", "structs", "chemgp", "optimization"}
+    if name in lazy_submodules:
+        return importlib.import_module(f".{name}", __name__)
     if name == "ureg":
         from chemparseplot.units import ureg as _ureg