chemparseplot 1.9.6__tar.gz → 1.9.8__tar.gz

{chemparseplot-1.9.6 → chemparseplot-1.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemparseplot
-Version: 1.9.6
+Version: 1.9.8
 Summary: Parsers and plotting tools for computational chemistry
 Project-URL: Documentation, https://chemparseplot.rgoswami.me
 Project-URL: Issues, https://github.com/HaoZeke/chemparseplot/issues
@@ -115,6 +115,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.6 → chemparseplot-1.9.8}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.9.6'
-__version_tuple__ = version_tuple = (1, 9, 6)
+__version__ = version = '1.9.8'
+__version_tuple__ = version_tuple = (1, 9, 8)
 
 __commit_id__ = commit_id = None

chemparseplot-1.9.8/chemparseplot/api.py

@@ -0,0 +1,91 @@
+# 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",
+    "normalize_energy_unit",
+    "suite_pins",
+]
+
+
+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.6 → chemparseplot-1.9.8}/chemparseplot/plot/optimization.py

@@ -59,13 +59,15 @@ def create_landscape_axes(
     dpi: int,
     has_strip: bool,
     theme,
-    base_size: float = 5.37,
-    strip_height_ratio: float = 0.24,
-    strip_hspace: float = 0.30,
+    base_size: float = 6.0,
+    strip_height_ratio: float = 0.38,
+    strip_hspace: float = 0.22,
 ):
     """Create a landscape figure with an optional structure strip axis."""
 
-    fig = plt.figure(figsize=(base_size, base_size + (1.20 if has_strip else 0)), dpi=dpi)
+    # Extra bottom room so x-label / ticks are not crushed by the strip.
+    fig_h = base_size + (2.15 if has_strip else 0.35)
+    fig = plt.figure(figsize=(base_size + 1.1, fig_h), dpi=dpi)
     if has_strip:
         gs = GridSpec(
             2,
@@ -73,6 +75,10 @@ def create_landscape_axes(
             height_ratios=[1, strip_height_ratio],
             hspace=strip_hspace,
             figure=fig,
+            left=0.14,
+            right=0.86,
+            top=0.90,
+            bottom=0.08,
         )
         ax = fig.add_subplot(gs[0])
         ax_strip = fig.add_subplot(gs[1])
@@ -102,22 +108,24 @@ def annotate_endpoint(ax, x: float, y: float, label: str, *, boxed: bool):
     """Annotate an optimization endpoint consistently."""
 
     kwargs = {
-        "fontsize": 10,
+        "fontsize": 12,
         "fontweight": "bold",
+        "color": "black",
         "ha": "center",
         "va": "bottom",
-        "zorder": 60,
+        "zorder": 120,
     }
     if boxed:
         kwargs.update(
             {
-                "xytext": (0, 6),
+                "xytext": (0, 8),
                 "textcoords": "offset points",
                 "bbox": {
-                    "boxstyle": "round,pad=0.2",
+                    "boxstyle": "round,pad=0.25",
                     "facecolor": "white",
-                    "edgecolor": "none",
-                    "alpha": 0.85,
+                    "edgecolor": "black",
+                    "linewidth": 0.8,
+                    "alpha": 0.95,
                 },
             }
         )
@@ -160,7 +168,8 @@ def render_endpoint_strip(
         show_dividers=strip_dividers,
         perspective_tilt=perspective_tilt,
         xyzrender_config=xyzrender_config,
-        width_fill_fraction=0.86,
+        width_fill_fraction=0.72,
+        prefer_single_row=True,
     )
 
 
@@ -204,15 +213,21 @@ def save_landscape_figure(
     ax=None,
     ax_strip=None,
 ) -> None:
-    """Save optimization landscapes without tight-layout strip warnings."""
+    """Save optimization landscapes; always crop with a pad so labels stay visible."""
 
     if has_strip and ax is not None and ax_strip is not None:
-        enforce_strip_clearance(fig, ax, ax_strip)
-    if not has_strip:
+        enforce_strip_clearance(fig, ax, ax_strip, min_clearance_px=40.0)
+    elif not has_strip:
         fig.tight_layout()
-        fig.savefig(str(output), dpi=dpi, bbox_inches="tight")
-    else:
-        fig.savefig(str(output), dpi=dpi)
+    # Always tight-crop: without it strip layouts left large white margins and
+    # could hide axis labels depending on the viewer/frame.
+    fig.savefig(
+        str(output),
+        dpi=dpi,
+        bbox_inches="tight",
+        pad_inches=0.25,
+        facecolor=fig.get_facecolor(),
+    )
     plt.close(fig)
 
 
@@ -314,6 +329,8 @@ def render_single_ended_landscape(
     energy_unit: str = "eV",
     energy_cap: float | None = None,
     energy_cap_window: float | None = None,
+    relative_energy: bool = True,
+    title: str | None = None,
     cmap: str = "viridis",
     output: Path,
     dpi: int = 150,
@@ -321,8 +338,8 @@ def render_single_ended_landscape(
     plot_structures: str = "none",
     strip_structs: Sequence[Any] | None = None,
     strip_labels: Sequence[str] | None = None,
-    endpoint_start_label: str = "Init",
-    endpoint_end_label: str = "Min",
+    endpoint_start_label: str = "initial",
+    endpoint_end_label: str = "minimized",
     endpoint_boxed: bool = True,
     annotate_overlay_starts: bool = False,
     overlay_start_label: str = "R",
@@ -345,6 +362,8 @@ def render_single_ended_landscape(
     ```{versionadded} 1.8.1
     ```
     """
+    from matplotlib import ticker
+
     from chemparseplot.parse.neb_utils import (
         calculate_landscape_coords,
         compute_synthetic_gradients,
@@ -363,33 +382,46 @@ def render_single_ended_landscape(
     energies = np.asarray(energies_eV, dtype=float)
     n = min(len(rmsd_a), len(energies))
     rmsd_a, rmsd_b, energies = rmsd_a[:n], rmsd_b[:n], energies[:n]
-    display_e = convert_energy(energies, energy_unit)
+    # Relative energy keeps colorbars readable (absolute eV often span <0.2 eV
+    # and all ticks collapse to the same printed value).
+    e_ref = float(np.min(energies)) if relative_energy else 0.0
+    energies_plot = energies - e_ref
+    display_e = convert_energy(energies_plot, energy_unit)
     cap = energy_cap
     if cap is None and energy_cap_window is not None:
         cap = float(np.min(display_e)) + energy_cap_window
     if cap is not None:
-        # Cap in display units, map back to eV for the surface routine which
-        # converts from eV once.
         factor = float(convert_energy(np.array([1.0]), energy_unit)[0])
-        energies = np.minimum(energies, cap / factor if factor else cap)
-        display_e = convert_energy(energies, energy_unit)
+        energies_plot = np.minimum(
+            energies_plot, cap / factor if factor else cap
+        )
+        display_e = convert_energy(energies_plot, energy_unit)
 
-    f_para = -np.gradient(energies)
+    f_para = -np.gradient(energies_plot)
     grad_a, grad_b = compute_synthetic_gradients(rmsd_a, rmsd_b, f_para)
 
-    plot_optimization_landscape(
+    z_label = (
+        f"Relative energy ({energy_unit})"
+        if relative_energy
+        else energy_axis_label(energy_unit)
+    )
+    cb = plot_optimization_landscape(
         ax,
         rmsd_a,
         rmsd_b,
         grad_a,
         grad_b,
-        energies,
+        energies_plot,
         project_path=project_path,
         method=surface_type,
         cmap=cmap,
         label_mode="optimization",
         energy_unit=energy_unit,
+        z_label=z_label,
     )
+    if cb is not None:
+        cb.ax.yaxis.set_major_formatter(ticker.FormatStrFormatter("%.3f"))
+        cb.set_label(z_label, rotation=270, labelpad=18)
 
     basis = None
     if project_path:
@@ -408,7 +440,9 @@ def render_single_ended_landscape(
         )
         m = min(len(ra), len(atoms_ov))
         ra, rb = ra[:m], rb[:m]
-        px, py, _ = project_landscape_path(ra, rb, project_path=project_path, basis=basis)
+        px, py, _ = project_landscape_path(
+            ra, rb, project_path=project_path, basis=basis
+        )
         color = OVERLAY_COLORS[idx % len(OVERLAY_COLORS)]
         if len(overlays) > 1:
             ax.plot(
@@ -423,37 +457,77 @@ def render_single_ended_landscape(
                 label=lbl,
             )
         if annotate_overlay_starts and len(px):
-            annotate_endpoint(ax, float(px[0]), float(py[0]), overlay_start_label, boxed=False)
+            annotate_endpoint(
+                ax, float(px[0]), float(py[0]), overlay_start_label, boxed=False
+            )
 
     plot_x, plot_y, _ = project_landscape_path(
         rmsd_a, rmsd_b, project_path=project_path, basis=basis
     )
     annotate_endpoint(
-        ax, float(plot_x[0]), float(plot_y[0]), endpoint_start_label, boxed=endpoint_boxed
+        ax,
+        float(plot_x[0]),
+        float(plot_y[0]),
+        endpoint_start_label,
+        boxed=endpoint_boxed,
     )
     annotate_endpoint(
-        ax, float(plot_x[-1]), float(plot_y[-1]), endpoint_end_label, boxed=endpoint_boxed
+        ax,
+        float(plot_x[-1]),
+        float(plot_y[-1]),
+        endpoint_end_label,
+        boxed=endpoint_boxed,
     )
 
+    # True 1:1 Å panel: Δd window matches Δs (same RMSD metric).
+    if project_path and len(plot_x) > 1:
+        x0, x1 = float(np.min(plot_x)), float(np.max(plot_x))
+        y0, y1 = float(np.min(plot_y)), float(np.max(plot_y))
+        s_pad = max((x1 - x0) * 0.06, 0.01)
+        x0, x1 = x0 - s_pad, x1 + s_pad
+        half = max(0.5 * (x1 - x0), abs(y0), abs(y1), 0.02)
+        x_mid = 0.5 * (x0 + x1)
+        ax.set_xlim(x_mid - half, x_mid + half)
+        ax.set_ylim(-half, half)
+        ax.set_aspect("equal", adjustable="box")
+
+    # Re-assert axis labels after surface/path (bold, large enough to read).
+    if project_path:
+        ax.set_xlabel(_LABELS["optimization"]["x"], fontweight="bold", fontsize=12)
+        ax.set_ylabel(_LABELS["optimization"]["y"], fontweight="bold", fontsize=12)
+    else:
+        ax.set_xlabel(r"RMSD from ref A ($\AA$)", fontweight="bold", fontsize=12)
+        ax.set_ylabel(r"RMSD from ref B ($\AA$)", fontweight="bold", fontsize=12)
+    ax.tick_params(axis="both", labelsize=10)
+    if title:
+        ax.set_title(title, fontweight="bold", fontsize=13, pad=10)
+
     if overlays and len(overlays) > 1:
-        ax.legend(frameon=True, framealpha=0.9, loc="best")
+        ax.legend(frameon=True, framealpha=0.95, loc="best")
 
     if has_strip and ax_strip is not None and strip_structs is not None:
+        zoom = (
+            strip_zoom
+            if strip_zoom is not None
+            else max(0.45, default_strip_zoom(list(strip_structs)) * 1.6)
+        )
         render_endpoint_strip(
             ax_strip,
             list(strip_structs),
             list(strip_labels or []),
-            strip_zoom=strip_zoom,
+            strip_zoom=zoom,
             rotation=rotation,
             theme=theme,
             strip_renderer=strip_renderer,
-            strip_spacing=strip_spacing,
+            strip_spacing=max(strip_spacing, 2.2),
             strip_dividers=strip_dividers,
             perspective_tilt=perspective_tilt,
             xyzrender_config=xyzrender_config,
         )
 
-    save_landscape_figure(fig, output, dpi=dpi, has_strip=has_strip, ax=ax, ax_strip=ax_strip)
+    save_landscape_figure(
+        fig, output, dpi=dpi, has_strip=has_strip, ax=ax, ax_strip=ax_strip
+    )
 
 
 def plot_optimization_landscape(
@@ -533,11 +607,11 @@ def plot_optimization_landscape(
 
     labels = _LABELS.get(label_mode, _LABELS["optimization"])
     if project_path:
-        ax.set_xlabel(labels["x"])
-        ax.set_ylabel(labels["y"])
+        ax.set_xlabel(labels["x"], fontweight="bold", fontsize=12)
+        ax.set_ylabel(labels["y"], fontweight="bold", fontsize=12)
     else:
-        ax.set_xlabel(r"RMSD from ref A ($\AA$)")
-        ax.set_ylabel(r"RMSD from ref B ($\AA$)")
+        ax.set_xlabel(r"RMSD from ref A ($\AA$)", fontweight="bold", fontsize=12)
+        ax.set_ylabel(r"RMSD from ref B ($\AA$)", fontweight="bold", fontsize=12)
 
     return cb
 

{chemparseplot-1.9.6 → chemparseplot-1.9.8}/readme.md

@@ -45,6 +45,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.8/tests/fixtures_geomscan_snippet.txt

@@ -0,0 +1,9 @@
+The Calculated Surface using the 'Actual Energy'
+   7.55890395  -0.74239862
+   7.32930292  -0.74349939
+   7.09970189  -0.74467446
+
+The Calculated Surface using the SCF energy
+   7.55890395  -0.74239862
+   7.32930292  -0.74349939
+   7.09970189  -0.74467446

chemparseplot-1.9.8/tests/test_public_api.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""Drive shipped chemparseplot.api entry points (parse → typed result)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from chemparseplot.api import (
+    convert_energy_magnitude,
+    extract_orca_geomscan_energy,
+    normalize_energy_unit,
+    suite_pins,
+)
+
+# Inline fixture (same content as tests/fixtures_geomscan_snippet.txt)
+_GEOMSCAN_SNIPPET = """
+The Calculated Surface using the 'Actual Energy'
+   7.55890395  -0.74239862
+   7.32930292  -0.74349939
+   7.09970189  -0.74467446
+
+The Calculated Surface using the SCF energy
+   7.55890395  -0.74239862
+   7.32930292  -0.74349939
+   7.09970189  -0.74467446
+"""
+
+FIXTURE_FILE = Path(__file__).parent / "fixtures_geomscan_snippet.txt"
+
+
+def test_normalize_and_convert_energy_library_path():
+    assert normalize_energy_unit("ev") == "eV"
+    kcal = convert_energy_magnitude(1.0, "kcal/mol")
+    val = float(np.asarray(kcal).reshape(-1)[0])
+    assert 20.0 < val < 25.0
+    back = float(np.asarray(convert_energy_magnitude(val, "eV", source_unit="kcal/mol")))
+    assert abs(back - 1.0) < 1e-6
+
+
+def test_extract_orca_geomscan_energy_typed_nonempty():
+    """Public parse path: ORCA geomscan text → pint Quantities with data."""
+    dist, energy = extract_orca_geomscan_energy(_GEOMSCAN_SNIPPET, "Actual Energy")
+    assert dist.size == 3
+    assert energy.size == 3
+    assert str(dist.units) == "bohr"
+    assert str(energy.units) == "hartree"
+    np.testing.assert_allclose(
+        dist.magnitude,
+        [7.55890395, 7.32930292, 7.09970189],
+    )
+    np.testing.assert_allclose(
+        energy.magnitude,
+        [-0.74239862, -0.74349939, -0.74467446],
+    )
+
+
+def test_extract_orca_geomscan_energy_from_fixture_file():
+    text = FIXTURE_FILE.read_text(encoding="utf-8")
+    dist, energy = extract_orca_geomscan_energy(text, "SCF energy")
+    assert dist.size >= 1
+    assert energy.size == dist.size
+    assert dist.size == 3
+
+
+def test_suite_pins_returns_dict():
+    pins = suite_pins()
+    assert isinstance(pins, dict)