chemparseplot 1.8.0__tar.gz → 1.9.0__tar.gz

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemparseplot
-Version: 1.8.0
+Version: 1.9.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
@@ -26,7 +26,7 @@ Requires-Dist: cmcrameri>=1.7; extra == 'all'
 Requires-Dist: h5py>=3.0; extra == 'all'
 Requires-Dist: matplotlib>=3.8.2; extra == 'all'
 Requires-Dist: polars>=0.20; extra == 'all'
-Requires-Dist: readcon>=0.7.0; extra == 'all'
+Requires-Dist: readcon>=0.13.1; extra == 'all'
 Requires-Dist: xyzrender>=0.1.2; extra == 'all'
 Provides-Extra: doc
 Requires-Dist: mdit-py-plugins>=0.3.4; extra == 'doc'
@@ -45,7 +45,7 @@ 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.7.0; extra == 'neb'
+Requires-Dist: readcon>=0.13.1; extra == 'neb'
 Provides-Extra: plot
 Requires-Dist: cmcrameri>=1.7; extra == 'plot'
 Requires-Dist: matplotlib>=3.8.2; extra == 'plot'
@@ -61,7 +61,7 @@ Requires-Dist: matplotlib>=3.8.2; extra == 'test'
 Requires-Dist: polars>=0.20; extra == 'test'
 Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
 Requires-Dist: pytest>=7.4.3; extra == 'test'
-Requires-Dist: readcon>=0.7.0; extra == 'test'
+Requires-Dist: readcon>=0.13.1; extra == 'test'
 Requires-Dist: rgpycrumbs; extra == 'test'
 Requires-Dist: scipy>=1.11; extra == 'test'
 Provides-Extra: xyzrender

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/_version.py

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

chemparseplot-1.9.0/chemparseplot/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
+#
+# SPDX-License-Identifier: MIT
+"""chemparseplot public surface with deferred heavy submodules.
+
+``parse`` and ``units`` remain attributes; they load via importlib on first
+access so a bare ``import chemparseplot`` does not construct the pint registry
+or pull the full parse package graph until needed.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+__all__ = ["parse", "units"]
+
+if TYPE_CHECKING:
+    from chemparseplot import parse as parse
+    from chemparseplot import units as units
+
+
+def __getattr__(name: str) -> Any:
+    if name == "parse":
+        return importlib.import_module("chemparseplot.parse")
+    if name == "units":
+        return importlib.import_module("chemparseplot.units")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{chemparseplot-1.8.0/chemparseplot → chemparseplot-1.9.0/chemparseplot/parse/eon}/__init__.py

@@ -1,7 +1,8 @@
 # SPDX-FileCopyrightText: 2023-present Rohit Goswami <rog32@hi.is>
 #
 # SPDX-License-Identifier: MIT
+"""eOn trajectory parsers."""
 
-from chemparseplot import parse, units
+from chemparseplot.parse.eon import con_io
 
-__all__ = ["parse", "units"]
+__all__ = ["con_io"]

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/chemparseplot/parse/eon/_trajectory_common.py

@@ -8,9 +8,10 @@ from pathlib import Path
 from typing import Any, TypeVar
 
 import polars as pl
-import readcon
 from ase import Atoms
 
+from chemparseplot.parse.eon import con_io
+
 log = logging.getLogger(__name__)
 
 T = TypeVar("T")
@@ -67,7 +68,7 @@ def require_dat_file(job_dir: Path, name: str) -> Path:
 def read_first_structure(path: Path) -> Atoms:
     """Read the first structure from an eOn CON file."""
 
-    return readcon.read_con_as_ase(str(path))[0]
+    return con_io.read_first_atoms(path)
 
 
 def read_optional_first(job_dir: Path, names: Sequence[str]) -> Atoms | None:
@@ -87,14 +88,14 @@ def load_movie_and_table(
     dat_name: str,
     parse_dat: Callable[[Path], pl.DataFrame],
     metadata_columns: Sequence[str],
-    build_table_from_metadata: Callable[[Sequence[readcon.ConFrame]], pl.DataFrame],
+    build_table_from_metadata: Callable[[Sequence[object]], pl.DataFrame],
     log_label: str,
 ) -> tuple[list[Atoms], pl.DataFrame]:
     """Load the shared movie/data payload for an eOn trajectory parser."""
 
     movie_file = resolve_movie_file(job_dir, movie_stem)
     log.info("Loading %s trajectory from %s", log_label, job_dir)
-    frames = readcon.read_con(str(movie_file))
+    frames = con_io.read_con_frames(movie_file)
     atoms_list = [frame.to_ase() for frame in frames]
 
     dat_df = build_table_from_metadata(frames)
@@ -119,7 +120,7 @@ def load_movie_and_table(
     return atoms_list, dat_df
 
 
-def metadata_value(frame: readcon.ConFrame, key: str) -> Any:
+def metadata_value(frame: object, key: str) -> Any:
     """Return a typed metadata value from a readcon frame."""
 
     if key == "frame_index":
@@ -130,7 +131,7 @@ def metadata_value(frame: readcon.ConFrame, key: str) -> Any:
 
 
 def frame_rows_to_table(
-    frames: Sequence[readcon.ConFrame],
+    frames: Sequence[object],
     columns: Sequence[str],
     *,
     allow_leading_incomplete: bool = False,

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

@@ -0,0 +1,136 @@
+# 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 should go through this module so
+metadata-native energies (``readcon>=0.7``) stay on one code path. ``readcon``
+remains an optional extra (``chemparseplot[neb]``); import errors surface only
+when these helpers are called.
+
+```{versionadded} 1.8.1
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "CON_SUFFIXES",
+    "frame_with_energy",
+    "is_con_path",
+    "read_con_as_ase",
+    "read_con_frames",
+    "read_first_atoms",
+    "write_atoms_as_con",
+    "write_con_frames",
+]
+
+CON_SUFFIXES = (".con", ".convel")
+
+
+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
+        msg = (
+            "readcon is required for CON I/O. Install with: "
+            "pip install 'chemparseplot[neb]' (readcon>=0.7.0)"
+        )
+        raise ImportError(msg) from exc
+    return readcon
+
+
+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 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_atoms(path: str | Path):
+    """Read the first frame of a CON file as an ASE ``Atoms`` object."""
+    return read_con_as_ase(path)[0]
+
+
+def frame_with_energy(frame: Any, energy: float) -> Any:
+    """Return a ``ConFrame`` copy with per-frame total ``energy`` set (eV).
+
+    Uses ``ConFrame.set_energy`` when available (readcon>=0.7) so metadata stays
+    schema-valid; falls back to reconstructing the frame with string metadata.
+    """
+    readcon = _readcon()
+    ConFrame = readcon.ConFrame
+    metadata = frame.metadata
+    if hasattr(metadata, "items"):
+        metadata_dict = {str(k): v for k, v in metadata.items()}
+    else:
+        metadata_dict = dict(metadata or {})
+    clone = ConFrame(
+        frame.cell,
+        frame.angles,
+        frame.atoms,
+        frame.prebox_header,
+        frame.postbox_header,
+        metadata_dict,
+    )
+    value = float(energy)
+    setter = getattr(clone, "set_energy", None)
+    if callable(setter):
+        setter(value)
+        return clone
+    scalar = getattr(clone, "set_scalar_metadata", None)
+    if callable(scalar):
+        scalar("energy", value)
+        return clone
+    metadata_dict["energy"] = str(value)
+    return ConFrame(
+        frame.cell,
+        frame.angles,
+        frame.atoms,
+        frame.prebox_header,
+        frame.postbox_header,
+        metadata_dict,
+    )
+
+
+def write_con_frames(path: str | Path, frames: Sequence[Any]) -> Path:
+    """Write ``ConFrame`` objects to *path* via ``readcon.write_con``."""
+    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`` to ``ConFrame`` and write a CON file.
+
+    Optional *energies* (eV) are attached per frame with :func:`frame_with_energy`.
+    """
+    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)

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/chemparseplot/parse/eon/dimer_trajectory.py

@@ -16,6 +16,8 @@ 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 (
@@ -95,7 +97,7 @@ def parse_climb_con(path: Path) -> list[Atoms]:
         List of ASE Atoms objects, one per iteration.
     """
     # eOn .con files may not have a .con extension for movie files
-    return readcon.read_con_as_ase(str(path))
+    return con_io.read_con_as_ase(path)
 
 
 def _load_mode_dat(path: Path) -> np.ndarray | None:

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/chemparseplot/parse/eon/min_trajectory.py

@@ -15,6 +15,8 @@ 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 (
@@ -80,7 +82,7 @@ def parse_min_con(path: Path) -> list[Atoms]:
     list[Atoms]
         List of ASE Atoms objects, one per iteration.
     """
-    return readcon.read_con_as_ase(str(path))
+    return con_io.read_con_as_ase(path)
 
 
 def table_from_min_metadata(frames: list[readcon.ConFrame]) -> pl.DataFrame:

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/chemparseplot/parse/eon/stitch.py

@@ -37,19 +37,10 @@ log = logging.getLogger(__name__)
 
 
 def _frame_with_energy(frame, energy: float):
-    """Return a ConFrame copy with ``energy`` set in metadata (readcon is read-only)."""
-    from readcon import ConFrame
-
-    metadata = {str(k): str(v) for k, v in (frame.metadata or {}).items()}
-    metadata["energy"] = str(float(energy))
-    return ConFrame(
-        frame.cell,
-        frame.angles,
-        frame.atoms,
-        frame.prebox_header,
-        frame.postbox_header,
-        metadata,
-    )
+    """Return a ConFrame copy with ``energy`` set via :mod:`con_io`."""
+    from chemparseplot.parse.eon.con_io import frame_with_energy
+
+    return frame_with_energy(frame, energy)
 
 
 @dataclass(frozen=True, slots=True)
@@ -90,11 +81,20 @@ def _cartesian_rmsd(atoms_a, atoms_b) -> float:
 
 
 def _cumulative_rmsd(atoms_list) -> list[float]:
-    """Cumulative consecutive-frame RMSD, starting at 0 for the first frame."""
-    coords = [0.0]
-    for prev, cur in zip(atoms_list[:-1], atoms_list[1:], strict=True):
-        coords.append(coords[-1] + _cartesian_rmsd(prev, cur))
-    return coords
+    """Cumulative consecutive-frame RMSD, starting at 0 for the first frame.
+
+    Stacks positions once and uses vectorized pairwise steps instead of a
+    Python loop over ASE frames (hot path for multi-segment stitch bands).
+    """
+    if not atoms_list:
+        return []
+    if len(atoms_list) == 1:
+        return [0.0]
+    # Materialize positions in one array: (n_frames, n_atoms, 3)
+    pos = np.stack([np.asarray(a.get_positions(), dtype=float) for a in atoms_list])
+    deltas = pos[1:] - pos[:-1]
+    step = np.sqrt(np.mean(np.sum(deltas * deltas, axis=2), axis=1))
+    return [0.0, *np.cumsum(step).tolist()]
 
 
 def stitch_neb_segments(
@@ -129,7 +129,11 @@ def stitch_neb_segments(
     StitchSummary
         Boundary indices, per-segment barriers, and the overall highest point.
     """
-    from readcon import read_con, write_con
+    from chemparseplot.parse.eon.con_io import (
+        read_con_frames,
+        write_atoms_as_con,
+        write_con_frames,
+    )
 
     saddle_overrides = saddle_overrides or {}
     out_dir = Path(out_dir)
@@ -144,7 +148,7 @@ def stitch_neb_segments(
     sp_best: tuple[float, object] | None = None  # (referenced energy, saddle atoms)
 
     for seg_idx, (label, con_path, start, end) in enumerate(segments):
-        frames = read_con(str(con_path))
+        frames = read_con_frames(con_path)
         seg_frames = list(frames[start:end])
         if not seg_frames:
             msg = f"Segment '{label}' ({con_path}) sliced to zero frames."
@@ -181,7 +185,7 @@ def stitch_neb_segments(
         if label in saddle_overrides:
             sad_path, sad_abs = saddle_overrides[label]
             peak_energy = float(sad_abs) + shift - ref
-            sad_atoms = read_con(str(sad_path))[0].to_ase()
+            sad_atoms = read_con_frames(sad_path)[0].to_ase()
             if sp_best is None or peak_energy > sp_best[0]:
                 sp_best = (peak_energy, sad_atoms)
         else:
@@ -199,8 +203,8 @@ def stitch_neb_segments(
         )
 
     # --- Write the combined band ---
-    write_con(str(out_dir / "neb.con"), out_frames)
-    write_con(str(out_dir / "neb_path_000.con"), out_frames)
+    write_con_frames(out_dir / "neb.con", out_frames)
+    write_con_frames(out_dir / "neb_path_000.con", out_frames)
 
     atoms_list = [f.to_ase() for f in out_frames]
     rxn_coord = _cumulative_rmsd(atoms_list)
@@ -214,14 +218,11 @@ def stitch_neb_segments(
 
     # --- Saddle overlay (sp.con) ---
     if sp_best is not None:
-        from readcon import ConFrame
-
-        sp_frame = _frame_with_energy(ConFrame.from_ase(sp_best[1]), float(sp_best[0]))
-        write_con(str(out_dir / "sp.con"), [sp_frame])
+        write_atoms_as_con(out_dir / "sp.con", [sp_best[1]], energies=[float(sp_best[0])])
     else:
         # Fallback: the global band maximum so the landscape overlay still works.
         peak_idx = int(np.argmax(energies))
-        write_con(str(out_dir / "sp.con"), [out_frames[peak_idx]])
+        write_con_frames(out_dir / "sp.con", [out_frames[peak_idx]])
 
     highest_index = int(np.argmax(energies))
     summary = StitchSummary(

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/chemparseplot/plot/optimization.py

@@ -14,6 +14,7 @@ The key semantic difference from NEB plots:
 from __future__ import annotations
 
 import logging
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Any
 
@@ -298,6 +299,163 @@ def plot_single_ended_convergence(trajs, labels, output: Path, dpi: int) -> None
     save_standard_figure(fig, output, dpi=dpi)
 
 
+def render_single_ended_landscape(
+    *,
+    atoms_list: Sequence[Any],
+    energies_eV: np.ndarray,
+    ref_a: Any,
+    ref_b: Any,
+    overlay_atom_lists: Sequence[Sequence[Any]] | None = None,
+    overlay_labels: Sequence[str] | None = None,
+    ira_instance: Any | None = None,
+    ira_kmax: float = 14.0,
+    project_path: bool = True,
+    surface_type: str = "grad_matern",
+    energy_unit: str = "eV",
+    energy_cap: float | None = None,
+    energy_cap_window: float | None = None,
+    cmap: str = "viridis",
+    output: Path,
+    dpi: int = 150,
+    theme: Any | None = None,
+    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_boxed: bool = True,
+    annotate_overlay_starts: bool = False,
+    overlay_start_label: str = "R",
+    strip_renderer: str = "xyzrender",
+    xyzrender_config: str = "paton",
+    strip_spacing: float = 1.5,
+    strip_zoom: float | None = None,
+    strip_dividers: bool = False,
+    rotation: str = "auto",
+    perspective_tilt: float = 0.0,
+) -> None:
+    """Full single-ended landscape pipeline shared by min/saddle CLIs.
+
+    Coordinates use :func:`~chemparseplot.parse.neb_utils.calculate_landscape_coords`
+    and synthetic gradients; the surface/path overlay uses
+    :func:`plot_optimization_landscape`. Energies are passed in **eV** and
+    converted once for display (avoids double conversion when ``energy_unit``
+    is not eV).
+
+    ```{versionadded} 1.8.1
+    ```
+    """
+    from chemparseplot.parse.neb_utils import (
+        calculate_landscape_coords,
+        compute_synthetic_gradients,
+    )
+
+    has_strip = plot_structures == "endpoints" and strip_structs is not None
+    fig, ax, ax_strip = create_landscape_axes(dpi=dpi, has_strip=has_strip, theme=theme)
+
+    rmsd_a, rmsd_b = calculate_landscape_coords(
+        atoms_list,
+        ira_instance,
+        ira_kmax,
+        ref_a=ref_a,
+        ref_b=ref_b,
+    )
+    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)
+    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)
+
+    f_para = -np.gradient(energies)
+    grad_a, grad_b = compute_synthetic_gradients(rmsd_a, rmsd_b, f_para)
+
+    plot_optimization_landscape(
+        ax,
+        rmsd_a,
+        rmsd_b,
+        grad_a,
+        grad_b,
+        energies,
+        project_path=project_path,
+        method=surface_type,
+        cmap=cmap,
+        label_mode="optimization",
+        energy_unit=energy_unit,
+    )
+
+    basis = None
+    if project_path:
+        _, _, basis = project_landscape_path(rmsd_a, rmsd_b, project_path=True)
+
+    overlays = overlay_atom_lists or ()
+    labels = list(overlay_labels or ())
+    for idx, atoms_ov in enumerate(overlays):
+        lbl = labels[idx] if idx < len(labels) else f"path{idx}"
+        ra, rb = calculate_landscape_coords(
+            atoms_ov,
+            ira_instance,
+            ira_kmax,
+            ref_a=ref_a,
+            ref_b=ref_b,
+        )
+        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)
+        color = OVERLAY_COLORS[idx % len(OVERLAY_COLORS)]
+        if len(overlays) > 1:
+            ax.plot(
+                px,
+                py,
+                "o-",
+                color=color,
+                markersize=3,
+                linewidth=1.5,
+                alpha=0.8,
+                zorder=55,
+                label=lbl,
+            )
+        if annotate_overlay_starts and len(px):
+            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
+    )
+    annotate_endpoint(
+        ax, float(plot_x[-1]), float(plot_y[-1]), endpoint_end_label, boxed=endpoint_boxed
+    )
+
+    if overlays and len(overlays) > 1:
+        ax.legend(frameon=True, framealpha=0.9, loc="best")
+
+    if has_strip and ax_strip is not None and strip_structs is not None:
+        render_endpoint_strip(
+            ax_strip,
+            list(strip_structs),
+            list(strip_labels or []),
+            strip_zoom=strip_zoom,
+            rotation=rotation,
+            theme=theme,
+            strip_renderer=strip_renderer,
+            strip_spacing=strip_spacing,
+            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)
+
+
 def plot_optimization_landscape(
     ax,
     rmsd_a: np.ndarray,

{chemparseplot-1.8.0 → chemparseplot-1.9.0}/chemparseplot/plot/structs.py

@@ -44,10 +44,31 @@ def axis_label(label: str, unit: str) -> str:
 
 
 def convert_energy(values: Any, unit: str, *, source_unit: str = "eV") -> np.ndarray:
-    """Convert energy-like values between supported presentation units."""
+    """Convert energy-like values between supported presentation units.
 
-    factor = _ENERGY_FACTORS[unit] / _ENERGY_FACTORS[source_unit]
-    return np.asarray(values, dtype=float) * factor
+    Delegates to :func:`chemparseplot.units.convert_energy_magnitude` (pint-backed).
+    Accepts plain arrays or pint ``Quantity`` instances (converted via ``.to``).
+    """
+    from chemparseplot.units import convert_energy_magnitude, normalize_energy_unit
+
+    # Pint Quantity with a compatible unit → magnitude in target presentation unit.
+    to_method = getattr(values, "to", None)
+    magnitude = getattr(values, "magnitude", None)
+    units = getattr(values, "units", None)
+    if callable(to_method) and magnitude is not None and units is not None:
+        try:
+            # Prefer chemical presentation units when already tagged.
+            unit_s = str(units)
+            if "chem_" in unit_s or "chem_eV" in unit_s:
+                return convert_energy_magnitude(magnitude, unit, source_unit=source_unit)
+            # Generic energy Quantity: convert to eV then to presentation unit.
+            in_eV = np.asarray(values.to("eV").magnitude, dtype=float)
+            return convert_energy_magnitude(in_eV, unit, source_unit="eV")
+        except Exception:
+            # Fall through to array path.
+            values = magnitude
+
+    return convert_energy_magnitude(values, unit, source_unit=source_unit)
 
 
 def convert_energy_curvature(