chemparseplot 1.10.2__tar.gz → 1.12.0__tar.gz

{chemparseplot-1.10.2 → chemparseplot-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: chemparseplot
-Version: 1.10.2
+Version: 1.12.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
@@ -13,7 +13,6 @@ Keywords: compchem,parser,plot
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: Implementation :: CPython
@@ -28,8 +27,11 @@ 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'
+Requires-Dist: pydseamslib>=2.11.1; extra == 'all'
+Requires-Dist: readcon-db>=0.2.0; extra == 'all'
+Requires-Dist: readcon>=0.17.1; extra == 'all'
+Requires-Dist: resvg-py>=0.5.0; extra == 'all'
+Requires-Dist: xyzrender>=0.3.8; extra == 'all'
 Provides-Extra: doc
 Requires-Dist: mdit-py-plugins>=0.3.4; extra == 'doc'
 Requires-Dist: myst-nb>=1; extra == 'doc'
@@ -51,7 +53,8 @@ Provides-Extra: neb
 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'
+Requires-Dist: readcon-db>=0.2.0; extra == 'neb'
+Requires-Dist: readcon>=0.17.1; extra == 'neb'
 Provides-Extra: opi
 Requires-Dist: orca-pi>=0.1.0; extra == 'opi'
 Provides-Extra: plot
@@ -62,6 +65,9 @@ Requires-Dist: build>=0.10; extra == 'release'
 Requires-Dist: towncrier>=24.8.0; extra == 'release'
 Requires-Dist: twine>=4.0; extra == 'release'
 Requires-Dist: wheel>=0.40; extra == 'release'
+Provides-Extra: rings
+Requires-Dist: pydseamslib>=2.11.1; extra == 'rings'
+Requires-Dist: xyzrender>=0.3.8; extra == 'rings'
 Provides-Extra: test
 Requires-Dist: ase>=3.22; extra == 'test'
 Requires-Dist: h5py>=3.0; extra == 'test'
@@ -69,14 +75,17 @@ 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'
+Requires-Dist: pydseamslib>=2.11.1; extra == 'test'
 Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
 Requires-Dist: pytest>=7.4.3; extra == 'test'
-Requires-Dist: readcon>=0.13.1; extra == 'test'
+Requires-Dist: readcon-db>=0.2.0; extra == 'test'
+Requires-Dist: readcon>=0.17.1; extra == 'test'
 Requires-Dist: rgpycrumbs; extra == 'test'
 Requires-Dist: scipy>=1.11; extra == 'test'
-Requires-Dist: xyzrender>=0.1.3; extra == 'test'
+Requires-Dist: xyzrender>=0.3.8; extra == 'test'
 Provides-Extra: xyzrender
-Requires-Dist: xyzrender>=0.1.2; extra == 'xyzrender'
+Requires-Dist: resvg-py>=0.5.0; extra == 'xyzrender'
+Requires-Dist: xyzrender>=0.3.8; extra == 'xyzrender'
 Description-Content-Type: text/markdown
 
 

{chemparseplot-1.10.2 → chemparseplot-1.12.0}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.10.2'
-__version_tuple__ = version_tuple = (1, 10, 2)
+__version__ = version = '1.12.0'
+__version_tuple__ = version_tuple = (1, 12, 0)
 
 __commit_id__ = commit_id = None

{chemparseplot-1.10.2 → chemparseplot-1.12.0}/chemparseplot/api.py

@@ -46,9 +46,12 @@ __all__ = [
     "energy_quantity",
     "extract_orca_geomscan_energy",
     "grammar_available",
+    "load_trajectory",
     "normalize_energy_unit",
     "parse_orca_final_energy",
     "parse_xyz",
+    "plot_con_overlay",
+    "plot_con_overview",
     "suite_pins",
 ]
 
@@ -124,6 +127,32 @@ def extract_orca_geomscan_energy(
     return extract_energy_data(data, energy_type)
 
 
+def load_trajectory(path: str):
+    """Load a ``.con`` / ``.convel`` file, or an ASE trajectory of another suffix.
+
+    ``.con`` goes through :mod:`chemparseplot.parse.eon.con_io`. ``fmax`` comes
+    from ``frame.frc`` when a forces section is present. The extxyz reader in
+    :mod:`chemparseplot.parse.trajectory.neb` is a different function.
+    """
+    from chemparseplot.parse.eon.con_trajectory import load_trajectory as _load
+
+    return _load(path)
+
+
+def plot_con_overview(*args, **kwargs):
+    """Draw one loaded trajectory. This does not parse a file."""
+    from chemparseplot.plot.con import plot_con_overview as _plot
+
+    return _plot(*args, **kwargs)
+
+
+def plot_con_overlay(*args, **kwargs):
+    """Draw several loaded trajectories on one axes. This does not parse."""
+    from chemparseplot.plot.con import plot_con_overlay as _plot
+
+    return _plot(*args, **kwargs)
+
+
 def suite_pins() -> dict[str, str]:
     """Return suite package pins from rgpkgs config + env (soft on old hub).
 

chemparseplot-1.12.0/chemparseplot/contracts/__init__.py

@@ -0,0 +1 @@
+"""Readers for control-plane contracts."""

chemparseplot-1.12.0/chemparseplot/contracts/load_outcome.py

@@ -0,0 +1,34 @@
+"""Decode an eOn Outcome JSON record.
+
+The record is job type and status. Trajectories stay readcon frames.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+_FIELDS = ("jobType", "statusCode", "statusText")
+
+
+def load_outcome(payload: str | Mapping[str, Any]) -> dict[str, Any]:
+    """Return job type and status from the outcome JSON debug form."""
+    if isinstance(payload, str):
+        data = json.loads(payload)
+    else:
+        data = dict(payload)
+    if not isinstance(data, dict):
+        message = "outcome payload must be an object"
+        raise TypeError(message)
+    if "positions" in data or "trajectory" in data:
+        message = "trajectories stay readcon"
+        raise ValueError(message)
+    missing = [key for key in _FIELDS if key not in data]
+    if missing:
+        raise KeyError(",".join(missing))
+    return {
+        "jobType": str(data["jobType"]),
+        "statusCode": int(data["statusCode"]),
+        "statusText": str(data["statusText"]),
+    }

chemparseplot-1.12.0/chemparseplot/parse/benchmark.py

@@ -0,0 +1,185 @@
+"""Paired search costs and complete reaction outcomes from campaign tables."""
+
+from __future__ import annotations
+
+import csv
+import math
+from pathlib import Path
+
+
+def load_benchmark_exports(paths, panels):
+    """Read verified cells.csv exports without silently dropping failed cases.
+
+    ``panels`` maps each panel name to its expected number of reactions. Costs
+    include initialization when the export provides that count. A repeated GP
+    reference must agree, including its result hash and source revision.
+    """
+    records, references = {}, {}
+
+    def flag(value):
+        if value not in ("True", "False"):
+            raise ValueError(f"Invalid acceptance: {value!r}")
+        return value == "True"
+
+    def number(value):
+        if value in (None, ""):
+            return None
+        result = float(value)
+        if not math.isfinite(result) or result < 0:
+            msg = "Costs must be finite and nonnegative"
+            raise ValueError(msg)
+        return result
+
+    for path in paths:
+        with Path(path).open(newline="") as stream:
+            for raw in csv.DictReader(stream):
+                panel, method, label = raw["set"], raw["method"], raw["label"]
+                if panel not in panels or method == "gpridge":
+                    raise ValueError(f"Unexpected export group: {panel}/{method}")
+                key = panel, method, label
+                if key in records:
+                    raise ValueError(f"Duplicate measurement: {key}")
+                records[key] = {
+                    "set": panel,
+                    "method": method,
+                    "label": label,
+                    "accepted": flag(raw["accepted"]),
+                    "search_calls": number(
+                        raw.get("search_calls_with_initialization", raw["search_calls"])
+                    ),
+                    "search_wall_s": number(raw["search_wall_s"]),
+                    "error": raw.get("error", ""),
+                    "run_sha256": raw["run_sha256"],
+                }
+                reference = {
+                    "set": panel,
+                    "method": "gpridge",
+                    "label": label,
+                    "accepted": flag(raw["gp_accepted"]),
+                    "search_calls": number(raw["gp_search_calls"]),
+                    "search_wall_s": number(raw["gp_search_wall_s"]),
+                    "run_sha256": raw["gp_result_sha256"],
+                    "source_revision": raw["gp_revision"],
+                }
+                refkey = panel, "gpridge", label
+                if refkey in references and references[refkey] != reference:
+                    raise ValueError(f"Conflicting reference: {refkey}")
+                references[refkey] = reference
+    records.update(references)
+    for panel, count in panels.items():
+        expected = {label for p, m, label in references if p == panel}
+        if len(expected) != count:
+            raise ValueError(f"Incomplete reference panel: {panel}")
+        for method in {m for p, m, _ in records if p == panel}:
+            labels = {label for p, m, label in records if p == panel and m == method}
+            if labels != expected:
+                raise ValueError(f"Incomplete campaign: {panel}/{method}")
+    for row in records.values():
+        if row["accepted"] and any(
+            row[k] is None or row[k] <= 0 for k in ("search_calls", "search_wall_s")
+        ):
+            msg = "Accepted searches require positive measured costs"
+            raise ValueError(msg)
+    return list(records.values())
+
+
+def paired_costs(rows, panel, method, reference="gpridge"):
+    """Ratio of total costs on the exact intersection of accepted reactions."""
+    selected = {
+        r["label"]: r for r in rows if r["set"] == panel and r["method"] == method
+    }
+    refs = {r["label"]: r for r in rows if r["set"] == panel and r["method"] == reference}
+    if set(selected) != set(refs):
+        msg = "Methods must contain the same complete reaction panel"
+        raise ValueError(msg)
+    labels = sorted(
+        k for k in selected if selected[k]["accepted"] and refs[k]["accepted"]
+    )
+    result = {
+        "labels": labels,
+        "accepted": sum(r["accepted"] for r in selected.values()),
+        "reference_accepted": sum(r["accepted"] for r in refs.values()),
+        "total": len(refs),
+    }
+    for metric in ("search_calls", "search_wall_s"):
+        a = sum(selected[k][metric] for k in labels)
+        b = sum(refs[k][metric] for k in labels)
+        result[metric] = {
+            "method_total": a,
+            "reference_total": b,
+            "ratio": a / b if labels else None,
+        }
+    return result
+
+
+def performance_ratios(rows, panel, methods, metric):
+    """Return cost/best accepted cost; failed checks retain their denominator."""
+    selected = [r for r in rows if r["set"] == panel and r["method"] in methods]
+    group = {(r["method"], r["label"]): r for r in selected}
+    if len(group) != len(selected):
+        msg = "Duplicate reaction in performance profile"
+        raise ValueError(msg)
+    labels = sorted({r["label"] for r in selected})
+    if not labels or any((m, label) not in group for m in methods for label in labels):
+        msg = "Methods must contain the same complete reaction set"
+        raise ValueError(msg)
+    ratios = {m: [] for m in methods}
+    for label in labels:
+        costs = {}
+        for method in methods:
+            row = group[method, label]
+            if row["accepted"]:
+                value = row[metric]
+                if not math.isfinite(value) or value <= 0:
+                    msg = "Accepted performance costs must be finite and positive"
+                    raise ValueError(msg)
+                costs[method] = value
+        best = min(costs.values(), default=None)
+        for method in methods:
+            ratios[method].append(costs[method] / best if method in costs else None)
+    return {"labels": labels, "ratios": ratios}
+
+
+def cost_frontier(rows, panel, methods, *, exclude=("plain",)):
+    """Mean costs on the same successful cases, retaining full-panel acceptance.
+
+    Equal points both belong to the frontier. A method dominates another only
+    when neither cost is larger and at least one is strictly smaller.
+    """
+    checked = performance_ratios(rows, panel, methods, "search_calls")
+    performance_ratios(rows, panel, methods, "search_wall_s")
+    labels = checked["labels"]
+    group = {(r["method"], r["label"]): r for r in rows if r["set"] == panel}
+    locators = [m for m in methods if m not in exclude]
+    common = [k for k in labels if all(group[m, k]["accepted"] for m in locators)]
+    points = []
+    if locators and common:
+        for method in locators:
+            points.append(
+                {
+                    "method": method,
+                    **{
+                        f"mean_{key}": sum(group[method, k][key] for k in common)
+                        / len(common)
+                        for key in ("search_calls", "search_wall_s")
+                    },
+                }
+            )
+        for point in points:
+            point["nondominated"] = not any(
+                all(
+                    other[key] <= point[key]
+                    for key in ("mean_search_calls", "mean_search_wall_s")
+                )
+                and any(
+                    other[key] < point[key]
+                    for key in ("mean_search_calls", "mean_search_wall_s")
+                )
+                for other in points
+            )
+    return {
+        "common_accepted_labels": common if locators else [],
+        "points": points,
+        "acceptance": {m: sum(group[m, k]["accepted"] for k in labels) for m in methods},
+        "cases": len(labels),
+    }

{chemparseplot-1.10.2 → chemparseplot-1.12.0}/chemparseplot/parse/eon/_trajectory_common.py

@@ -124,9 +124,10 @@ def metadata_value(frame: object, key: str) -> Any:
     """Return a typed metadata value from a readcon frame."""
 
     if key == "frame_index":
-        return frame.frame_index
+        value = frame.metadata.get(key)
+        return frame.frame_index if value is None else value
     if key == "energy":
-        return frame.energy
+        return con_io.frame_energy_ev(frame)
     return frame.metadata.get(key)
 
 

chemparseplot-1.12.0/chemparseplot/parse/eon/con_io.py

@@ -0,0 +1,233 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""Public readcon-backed CON/convel helpers for eOn parsers.
+
+All ``.con`` / ``.convel`` I/O in chemparseplot goes through this module.
+``readcon`` stays an optional extra (``chemparseplot[neb]``). Import errors
+surface only when these helpers are called. Writers omit precision and leave
+canonical off, which is RoundTrip on ``readcon>=0.17.1``. Corpus selection
+opens stores read-only and decodes selected frames as they are consumed.
+
+```{versionadded} 1.8.1
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+__all__ = [
+    "CON_SUFFIXES",
+    "frame_energy_ev",
+    "frame_positions_angstrom",
+    "frame_with_energy",
+    "frame_with_positions",
+    "is_con_path",
+    "iter_con_frames",
+    "iter_corpus_frames",
+    "read_con_as_ase",
+    "read_con_frames",
+    "read_first_atoms",
+    "read_first_frame",
+    "write_atoms_as_con",
+    "write_con_frames",
+]
+
+CON_SUFFIXES = (".con", ".convel")
+
+_READCON_HINT = (
+    "readcon is required for CON I/O. Install with: "
+    "pip install 'chemparseplot[neb]' (readcon>=0.17.1)"
+)
+
+
+def is_con_path(path: str | Path) -> bool:
+    """Return True when *path* looks like an eOn CON/convel file."""
+    return Path(path).suffix.lower() in CON_SUFFIXES
+
+
+def _readcon():
+    try:
+        import readcon
+    except ImportError as exc:  # pragma: no cover - exercised when extra missing
+        raise ImportError(_READCON_HINT) from exc
+    return readcon
+
+
+def _metadata_dict(frame: Any) -> dict[str, Any]:
+    metadata = deepcopy(frame.metadata)
+    if hasattr(metadata, "items"):
+        return {str(key): value for key, value in metadata.items()}
+    return dict(metadata or {})
+
+
+def _clone_frame(frame: Any) -> Any:
+    """Copy a frame through the ``ConFrame`` constructor so Atom sections travel."""
+    readcon = _readcon()
+    return readcon.ConFrame(
+        frame.cell,
+        frame.angles,
+        list(frame.atoms),
+        frame.prebox_header,
+        frame.postbox_header,
+        _metadata_dict(frame),
+    )
+
+
+def read_con_frames(path: str | Path) -> list[Any]:
+    """Read all frames from a CON/convel file as ``readcon.ConFrame`` objects."""
+    readcon = _readcon()
+    return list(readcon.read_con(str(path)))
+
+
+def iter_con_frames(path: str | Path) -> Iterator[Any]:
+    """Yield CON frames without retaining the complete trajectory."""
+    yield from _readcon().iter_con(str(path))
+
+
+def iter_corpus_frames(
+    path: str | Path,
+    *,
+    trajectory: int | None = None,
+    require_energy: bool = False,
+    require_forces: bool = False,
+) -> Iterator[Any]:
+    """Yield selected stored frames in trajectory and frame-index order.
+
+    The corpus is opened read-only. Frame decoding is lazy; selection retains
+    only the trajectory and frame keys, including for compressed stores.
+    """
+    from readcon_db import ConCorpus
+
+    corpus = ConCorpus(str(path), readonly=True)
+    keys = corpus.select(
+        traj_id=trajectory, require_energy=require_energy, require_forces=require_forces
+    )
+    for trajectory_id, frame_index in sorted(keys):
+        yield corpus.get_frame(trajectory_id, frame_index)
+
+
+def _energy_unit(frame: Any) -> str:
+    return frame.metadata.get("units", {}).get("energy", "eV")
+
+
+def _unit_factor(source: str, target: str) -> float:
+    if source == target:
+        return 1.0
+    from readcon_db import unit_conversion_factor
+
+    return unit_conversion_factor(source, target)
+
+
+def frame_energy_ev(frame: Any) -> float | None:
+    """Return the stored total energy in eV without evaluating a potential."""
+    value = frame.metadata.get("energy")
+    if value is None:
+        value = getattr(frame, "energy", None)
+    if value is None:
+        return None
+    return float(value) * _unit_factor(_energy_unit(frame), "eV")
+
+
+def read_con_as_ase(path: str | Path) -> list:
+    """Read all frames from a CON/convel file as ASE ``Atoms`` objects."""
+    readcon = _readcon()
+    return list(readcon.read_con_as_ase(str(path)))
+
+
+def read_first_frame(path: str | Path) -> Any:
+    """Read the first CON frame and stop. Later frames are not parsed."""
+    readcon = _readcon()
+    return readcon.read_first_frame(str(path))
+
+
+def read_first_atoms(path: str | Path):
+    """Read the first frame of a CON file as an ASE ``Atoms`` object."""
+    return read_first_frame(path).to_ase()
+
+
+def frame_positions_angstrom(frame: Any) -> np.ndarray:
+    """Return Cartesian positions in Angstrom using the declared length unit."""
+    source = frame.metadata.get("units", {}).get("length", "angstrom")
+    return np.asarray(frame.xyz, dtype=float) * _unit_factor(source, "angstrom")
+
+
+def frame_with_energy(frame: Any, energy: float) -> Any:
+    """Return a ``ConFrame`` copy with the supplied total energy in eV.
+
+    The stored number uses the frame's declared energy unit. Geometry, atom
+    sections, and their unit declarations are retained. ``ConFrame.set_energy``
+    validates that the stored value is finite.
+    """
+    clone = _clone_frame(frame)
+    value = float(energy) * _unit_factor("eV", _energy_unit(frame))
+    setter = getattr(clone, "set_energy", None)
+    if not callable(setter):
+        raise ImportError(_READCON_HINT)
+    setter(value)
+    return clone
+
+
+def frame_with_positions(frame: Any, positions: Any) -> Any:
+    """Return a ``ConFrame`` copy with Cartesian positions replaced.
+
+    Each ``Atom`` row is copied and only ``x`` / ``y`` / ``z`` are written.
+    ``fixed``, ``atom_id``, ``mass``, velocities, forces, displacements, and
+    spreads stay. That is correct for an unmoved slice or a pure translation.
+    It is the wrong helper for ``displacement.con``: a rotation or a reorder
+    must drop those sections and let eOn recompute them.
+    """
+    coords = np.asarray(positions, dtype=np.float64)
+    n_atoms = len(frame.atoms)
+    if coords.shape != (n_atoms, 3):
+        msg = f"positions must have shape ({n_atoms}, 3), got {tuple(coords.shape)}"
+        raise ValueError(msg)
+    clone = _clone_frame(frame)
+    for atom, xyz in zip(clone.atoms, coords, strict=True):
+        atom.x = xyz[0].item()
+        atom.y = xyz[1].item()
+        atom.z = xyz[2].item()
+    return clone
+
+
+def write_con_frames(path: str | Path, frames: Sequence[Any]) -> Path:
+    """Write ``ConFrame`` objects to *path* via ``readcon.write_con``.
+
+    Precision is omitted and canonical stays off. There is no corpus write.
+    """
+    readcon = _readcon()
+    out = Path(path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    readcon.write_con(str(out), list(frames))
+    return out
+
+
+def write_atoms_as_con(
+    path: str | Path,
+    atoms_list: Sequence[Any],
+    *,
+    energies: Sequence[float | None] | None = None,
+) -> Path:
+    """Convert ASE ``Atoms`` that were never a ``ConFrame`` and write CON.
+
+    Optional *energies* (eV) are attached per frame with
+    :func:`frame_with_energy`. ``from_ase`` drops displacements and spreads.
+    ASE tags become atom ids only when they are distinct and non-negative;
+    otherwise ids are sequential. Two atoms of one symbol whose masses
+    disagree past the reader tolerance fail at ``build``. Precision is
+    omitted and canonical stays off.
+    """
+    readcon = _readcon()
+    frames = []
+    for idx, atoms in enumerate(atoms_list):
+        frame = readcon.ConFrame.from_ase(atoms)
+        if energies is not None and idx < len(energies) and energies[idx] is not None:
+            frame = frame_with_energy(frame, float(energies[idx]))
+        frames.append(frame)
+    return write_con_frames(path, frames)