chemparseplot 1.9.16__tar.gz → 1.10.0__tar.gz

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemparseplot
-Version: 1.9.16
+Version: 1.10.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
@@ -65,6 +65,7 @@ Requires-Dist: wheel>=0.40; extra == 'release'
 Provides-Extra: test
 Requires-Dist: ase>=3.22; extra == 'test'
 Requires-Dist: h5py>=3.0; extra == 'test'
+Requires-Dist: jax[cpu]>=0.4; 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'
@@ -73,6 +74,7 @@ Requires-Dist: pytest>=7.4.3; extra == 'test'
 Requires-Dist: readcon>=0.13.1; extra == 'test'
 Requires-Dist: rgpycrumbs; extra == 'test'
 Requires-Dist: scipy>=1.11; extra == 'test'
+Requires-Dist: xyzrender>=0.1.3; extra == 'test'
 Provides-Extra: xyzrender
 Requires-Dist: xyzrender>=0.1.2; extra == 'xyzrender'
 Description-Content-Type: text/markdown

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.9.16'
-__version_tuple__ = version_tuple = (1, 9, 16)
+__version__ = version = '1.10.0'
+__version_tuple__ = version_tuple = (1, 10, 0)
 
 __commit_id__ = commit_id = None

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/api.py

@@ -101,7 +101,6 @@ def parse_orca_final_energy(path_or_text: str):
     return summary.final_energy
 
 
-
 def extract_orca_geomscan_energy(
     data: str, energy_type: str = "Actual Energy"
 ) -> tuple[Q_, Q_]:
@@ -138,6 +137,6 @@ def suite_pins() -> dict[str, str]:
     try:
         cfg = load_config()
         pins.update(cfg.merged_package_pins_normalized())
-    except Exception:  # noqa: BLE001 — soft fail for consumers
+    except Exception:
         pass
     return pins

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/chemgp_hdf5.py

@@ -22,6 +22,7 @@ HDF5 Layout
 from typing import Any
 
 import numpy as np
+
 from chemparseplot.parse.types import ArrayGroup, ParserAttrs
 
 

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

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""eOn trajectory parsers.
+
+``con_io`` is always importable (readcon loads on first CON call).
+``frame_series`` needs the ``neb`` extra (readcon + polars + ase) and is
+lazy so bare ``import chemparseplot.parse`` stays light.
+"""
+
+from chemparseplot.parse.eon import con_io
+
+__all__ = ["con_io", "frame_series"]
+
+
+def __getattr__(name: str):
+    if name == "frame_series":
+        from chemparseplot.parse.eon import frame_series as _frame_series
+
+        return _frame_series
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/eon/_trajectory_common.py

@@ -141,7 +141,10 @@ def frame_rows_to_table(
     rows: list[dict[str, Any]] = []
     saw_complete_row = False
     for frame in frames:
-        row = {column: coerce_metadata_value(column, metadata_value(frame, column)) for column in columns}
+        row = {
+            column: coerce_metadata_value(column, metadata_value(frame, column))
+            for column in columns
+        }
         if any(value is None for value in row.values()):
             if saw_complete_row or not allow_leading_incomplete:
                 return pl.DataFrame()

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/eon/dimer_trajectory.py

@@ -16,11 +16,10 @@ from pathlib import Path
 import numpy as np
 import polars as pl
 import readcon
-
-from chemparseplot.parse.eon import con_io
 from ase import Atoms
 
-from ._trajectory_common import (
+from chemparseplot.parse.eon import con_io
+from chemparseplot.parse.eon._trajectory_common import (
     frame_rows_to_table,
     load_movie_and_table,
     load_optional_payload,

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/eon/frame_series.py

@@ -25,12 +25,10 @@ from chemparseplot.parse.eon._trajectory_common import (
     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,
 )
@@ -121,7 +119,11 @@ def neb_path_arrays(frames: Sequence[Any]) -> dict[str, Any]:
         ok = True
         for frame in frames:
             v = metadata_value(frame, key)
-            if v is None and key in ("reaction_coordinate", "relative_energy", "parallel_force"):
+            if v is None and key in (
+                "reaction_coordinate",
+                "relative_energy",
+                "parallel_force",
+            ):
                 # optional NEB stamps
                 ok = False
                 break

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/eon/min_trajectory.py

@@ -15,14 +15,12 @@ from pathlib import Path
 
 import polars as pl
 import readcon
-
-from chemparseplot.parse.eon import con_io
 from ase import Atoms
 
-from ._trajectory_common import (
+from chemparseplot.parse.eon import con_io
+from chemparseplot.parse.eon._trajectory_common import (
     frame_rows_to_table,
     load_movie_and_table,
-    read_first_structure,
     read_optional_first,
 )
 

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/eon/saddle_search.py

@@ -369,9 +369,7 @@ def parse_eon_saddle(eresp: Path, rloc: "SpinID") -> "SaddleMeasure":
         dimer_trans=meth.trans,
         init_energy=init_energy,
         barrier=(
-            results_data.saddle_energy - init_energy
-            if init_energy is not None
-            else None
+            results_data.saddle_energy - init_energy if init_energy is not None else None
         ),
         mol_id=getattr(rloc, "mol_id", None),
         spin=getattr(rloc, "spin", None),

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/grammar/__init__.py

@@ -30,7 +30,13 @@ __all__ = [
 
 
 def __getattr__(name: str):
-    if name in ("parse_xyz_text", "parse_xyz_file", "XyzFrame", "XyzAtom", "write_xyz_text"):
+    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)

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/grammar/orca_text.py

@@ -151,7 +151,7 @@ def extract_final_energies_hartree(text: str) -> list[float]:
         line = m.group(0).strip()
         try:
             tree = g.parse(line)
-        except Exception:  # noqa: BLE001 — skip non-conforming noise
+        except Exception:
             continue
         v = EnergyVisitor()
         v.visit(tree)
@@ -192,14 +192,13 @@ def extract_cartesian_angstrom_blocks(text: str) -> list[list[OrcaAtomCoord]]:
     for m in _CART_BLOCK_RE.finditer(text):
         chunk = (
             "CARTESIAN COORDINATES (ANGSTROEM)\n"
-            "---------------------------------\n"
-            + m.group(1)
+            "---------------------------------\n" + m.group(1)
         )
         if not chunk.endswith("\n"):
             chunk += "\n"
         try:
             tree = g.parse(chunk)
-        except Exception:  # noqa: BLE001
+        except Exception:
             continue
         v = CartVisitor()
         v.visit(tree)

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/grammar/xyz.py

@@ -29,8 +29,8 @@ _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?
+coord_block   = (atom_line newline?)+
+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"
@@ -107,26 +107,29 @@ def _make_visitor() -> Any:
             self.comment: str = ""
             self.atoms: list[XyzAtom] = []
 
-        def visit_natoms(self, node: Any, visited_children: Any) -> int:
+        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:
+        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:
+        def visit_atom_line(self, node: Any, visited_children: Any) -> XyzAtom:
+            del node  # structure from visited_children
             flat = _flatten(visited_children)
-            symbol = next(x for x in flat if isinstance(x, str) and x.strip() and x[0].isalpha())
+            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:
+        def visit_atype(self, node: Any, _visited_children: Any) -> str:
             return node.text
 
-        def visit_float_(self, node: Any, visited_children: Any) -> float:
+        def visit_float_(self, node: Any, _visited_children: Any) -> float:
             return float(node.text)
 
         def generic_visit(self, node: Any, visited_children: Any) -> Any:

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/sella/saddle_search.py

@@ -18,13 +18,14 @@ except ImportError:
 
 log = logging.getLogger(__name__)
 
+
 @dataclass(frozen=True, slots=True)
 class SellaLog:
     """Typed record for a single Sella geometry-step log entry.
 
-```{versionadded} 0.0.3
-```
-"""
+    ```{versionadded} 0.0.3
+    ```
+    """
 
     step_id: int
     time_float: float

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/parse/types.py

@@ -84,7 +84,7 @@ class OrcaNebResult(DataclassMapping):
 
     def __post_init__(self) -> None:
         if self.n_images is None:
-            object.__setattr__(self, "n_images", int(len(self.energies)))
+            object.__setattr__(self, "n_images", len(self.energies))
 
     @classmethod
     def from_mapping(cls, data: Mapping[str, Any]) -> OrcaNebResult:

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/plot/__init__.py

@@ -25,7 +25,14 @@ __all__ = [
 def __getattr__(name):
     import importlib
 
-    lazy_submodules = {"geomscan", "structs", "chemgp", "optimization"}
+    lazy_submodules = {
+        "geomscan",
+        "structs",
+        "chemgp",
+        "optimization",
+        "landscape",
+        "disconnectivity",
+    }
     if name in lazy_submodules:
         return importlib.import_module(f".{name}", __name__)
     if name == "ureg":

chemparseplot-1.10.0/chemparseplot/plot/disconnectivity.py

@@ -0,0 +1,323 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""Approximate disconnectivity graphs from minima databases.
+
+The classic disconnectivity graph needs transition states; a hopping
+campaign records only quenched minima. These helpers draw the superbasin
+merge tree of a descriptor-space k-nearest-neighbour graph instead: at each
+energy level the minima below it split into connected components, and
+components merge as the level rises. That approximation is a rendering of
+the database made for reading the figure; it should never feed a reported
+statistic.
+
+Basins can be lumped for display by spectral clustering on the same graph.
+Everything is iterative: with a thousand minima the merge chains grow
+deeper than any recursion limit.
+
+```{versionadded} 1.10.0
+```
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.sparse import coo_matrix
+from scipy.sparse.csgraph import connected_components, laplacian
+
+from chemparseplot.plot.theme import RUHI_COLORS
+
+BASIN_PALETTE = [
+    RUHI_COLORS[c] for c in ["teal", "sky", "magenta", "coral", "sunshine"]
+]
+
+
+def dedup(matrix, energies, tol):
+    """Merge near-identical minima, keeping the lowest-energy representative.
+
+    Returns the kept row indices, lowest energy first.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    order = np.argsort(energies)
+    rep_idx = []
+    for i in order:
+        if any(np.linalg.norm(matrix[i] - matrix[j]) < tol for j in rep_idx):
+            continue
+        rep_idx.append(i)
+    return np.array(rep_idx)
+
+
+def knn_graph(matrix, k=6):
+    """Symmetric k-nearest-neighbour adjacency in descriptor space.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    d = np.linalg.norm(matrix[:, None, :] - matrix[None, :, :], axis=-1)
+    np.fill_diagonal(d, np.inf)
+    n = len(matrix)
+    rows, cols = [], []
+    for i in range(n):
+        for j in np.argsort(d[i])[:k]:
+            rows += [i, j]
+            cols += [j, i]
+    data = np.ones(len(rows))
+    return coo_matrix((data, (rows, cols)), shape=(n, n)).tocsr()
+
+
+def bridge_components(adjacency, matrix, weight=0.1):
+    """Weakly connect graph components through their closest point pairs.
+
+    Spectral clustering assumes a connected graph; a k-NN graph over a
+    minima database often fragments. One weak edge per component pair
+    (closest points in descriptor space) restores the geometry without
+    drowning the strong intra-basin structure.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    n_comp, labels = connected_components(adjacency, directed=False)
+    if n_comp == 1:
+        return adjacency
+    adjacency = adjacency.tolil()
+    for a in range(n_comp):
+        for b in range(a + 1, n_comp):
+            ia = np.where(labels == a)[0]
+            ib = np.where(labels == b)[0]
+            d = np.linalg.norm(
+                matrix[ia][:, None, :] - matrix[ib][None, :, :], axis=-1
+            )
+            i, j = np.unravel_index(int(np.argmin(d)), d.shape)
+            adjacency[ia[i], ib[j]] = weight
+            adjacency[ib[j], ia[i]] = weight
+    return adjacency.tocsr()
+
+
+def spectral_basins(adjacency, n_basins, rng, matrix=None):
+    """Display-only basin assignment by spectral clustering on the graph.
+
+    With ``matrix`` given, disconnected components are weakly bridged
+    through their closest descriptor pairs first.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    if matrix is not None:
+        adjacency = bridge_components(adjacency, matrix)
+    lap = laplacian(adjacency.astype(float), normed=True)
+    k = min(n_basins, adjacency.shape[0] - 1)
+    # Dense eigendecomposition: minima databases stay around a thousand
+    # nodes, and iterative smallest-magnitude solvers are unreliable on
+    # the near-singular Laplacians of disconnected graphs.
+    _, vecs = np.linalg.eigh(np.asarray(lap.todense()))
+    x = vecs[:, :k]
+    x = x / (np.linalg.norm(x, axis=1, keepdims=True) + 1e-12)
+    # Farthest-point seeding: deterministic given the first pick, and it
+    # cannot drop both centers into one embedded cloud.
+    first = int(rng.integers(len(x)))
+    centers = [x[first]]
+    while len(centers) < k:
+        d = np.min(
+            [np.linalg.norm(x - c, axis=1) for c in centers], axis=0
+        )
+        centers.append(x[int(np.argmax(d))])
+    centers = np.array(centers)
+    for _ in range(60):
+        assign = np.argmin(
+            np.linalg.norm(x[:, None, :] - centers[None, :, :], axis=-1), axis=1
+        )
+        new = np.array(
+            [
+                x[assign == c].mean(axis=0) if (assign == c).any() else centers[c]
+                for c in range(k)
+            ]
+        )
+        if np.allclose(new, centers):
+            break
+        centers = new
+    return assign
+
+
+class Node:
+    """A merge-tree node; leaves carry their minimum's index.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+
+    __slots__ = ("level", "children", "leaf", "x", "emin", "argmin")
+
+    def __init__(self, level, children=None, leaf=None):
+        self.level = level
+        self.children = children or []
+        self.leaf = leaf
+        self.x = None
+        if self.leaf is not None:
+            self.emin = level
+            self.argmin = leaf
+        else:
+            self.emin = min(c.emin for c in self.children)
+            self.argmin = min(self.children, key=lambda c: c.emin).argmin
+
+
+def merge_tree(adjacency, energies, levels):
+    """Superbasin merge tree over an energy-threshold sweep.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    n = len(energies)
+    leaves = [Node(energies[i], leaf=i) for i in range(n)]
+    active = {}
+    prev_sets = []
+    for lev in levels:
+        mask = energies <= lev
+        if not mask.any():
+            continue
+        sub = np.where(mask)[0]
+        _, labels = connected_components(
+            adjacency[sub][:, sub], directed=False
+        )
+        comps = {}
+        for local, g in enumerate(sub):
+            comps.setdefault(labels[local], []).append(g)
+        new_sets = [frozenset(v) for v in comps.values()]
+        for s in new_sets:
+            if s in active:
+                continue
+            parts = [p for p in prev_sets if p <= s and p in active]
+            merged = [active[p] for p in parts]
+            covered = frozenset().union(*parts) if parts else frozenset()
+            for p in parts:
+                del active[p]
+            extra = sorted(s - covered, key=lambda i: energies[i])
+            if not merged:
+                node = leaves[extra[0]]
+                for m in extra[1:]:
+                    node = Node(
+                        max(energies[m], node.level), children=[node, leaves[m]]
+                    )
+            else:
+                node = merged[0] if len(merged) == 1 else Node(lev, children=merged)
+                for m in extra:
+                    node = Node(lev, children=[node, leaves[m]])
+            active[s] = node
+        prev_sets = new_sets
+    roots = list(active.values())
+    if len(roots) > 1:
+        return Node(levels[-1], children=roots)
+    return roots[0]
+
+
+def iter_nodes(root):
+    """Post-order traversal without recursion.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    out, stack = [], [(root, False)]
+    while stack:
+        node, done = stack.pop()
+        if done or node.leaf is not None:
+            out.append(node)
+            continue
+        stack.append((node, True))
+        for c in reversed(node.children):
+            stack.append((c, False))
+    return out
+
+
+def layout(root):
+    """Leaf x positions in tree order, children sorted deepest-first.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    for node in iter_nodes(root):
+        if node.leaf is None:
+            node.children.sort(key=lambda c: c.emin)
+    x = 0.0
+    for node in iter_nodes(root):
+        if node.leaf is not None:
+            node.x = x
+            x += 1.0
+        else:
+            node.x = float(np.mean([c.x for c in node.children]))
+
+
+def paint(root, assign, palette=None):
+    """Colour each subtree by the spectral basin of its deepest minimum.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    palette = palette or BASIN_PALETTE
+    colors = {}
+    for node in iter_nodes(root):
+        colors[id(node)] = palette[int(assign[node.argmin]) % len(palette)]
+    return colors
+
+
+def draw(ax, root, colors, lw=1.1):
+    """Vertical stems to the merge level, horizontal bars at merges.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    for node in iter_nodes(root):
+        if node.leaf is not None:
+            continue
+        for c in node.children:
+            ax.plot(
+                [c.x, c.x],
+                [c.level, node.level],
+                color=colors.get(id(c), "#444444"),
+                lw=lw,
+                solid_capstyle="round",
+                zorder=2,
+            )
+        xs = [c.x for c in node.children]
+        ax.plot(
+            [min(xs), max(xs)],
+            [node.level, node.level],
+            color="#444444",
+            lw=0.9,
+            zorder=1,
+        )
+
+
+def plot_disconnectivity(
+    ax,
+    matrix,
+    energies,
+    *,
+    dedup_tol=0.15,
+    knn=6,
+    n_levels=48,
+    n_basins=5,
+    rng=None,
+):
+    """Full pipeline: dedup, graph, merge tree, spectral paint, draw.
+
+    Returns ``(kept_indices, root)`` so callers can label leaves.
+
+    ```{versionadded} 1.10.0
+    ```
+    """
+    rng = rng or np.random.default_rng(11)
+    reps = dedup(matrix, energies, dedup_tol)
+    m = matrix[reps]
+    en = energies[reps]
+    adjacency = knn_graph(m, knn)
+    levels = np.linspace(en.min(), en.max(), n_levels)[1:]
+    root = merge_tree(adjacency, en, levels)
+    layout(root)
+    assign = spectral_basins(adjacency, n_basins, rng, matrix=m)
+    colors = paint(root, assign)
+    draw(ax, root, colors)
+    ax.set_xticks([])
+    ax.set_ylabel("quenched energy")
+    ax.spines["bottom"].set_visible(False)
+    return reps, root

{chemparseplot-1.9.16 → chemparseplot-1.10.0}/chemparseplot/plot/geomscan.py

@@ -1,6 +1,12 @@
 import matplotlib.pyplot as plt
 
-from chemparseplot.plot.structs import AxisUnits, BasePlotter, EnergyPath, axis_label, to_magnitude
+from chemparseplot.plot.structs import (
+    AxisUnits,
+    BasePlotter,
+    EnergyPath,
+    axis_label,
+    to_magnitude,
+)
 
 
 def plot_energy_paths(