chemparseplot.plot.optimization

Visualization functions for optimization trajectories.

Provides 2D landscape and 1D profile plots for single-ended methods (dimer/saddle search, minimization) using the generalized (s, d) reaction valley projection.

The key semantic difference from NEB plots:

• s = optimization progress (toward saddle or minimum)

• d = lateral deviation (wasted sideways motion)

.. versionadded:: 1.5.0

Module Contents

Functions

create_landscape_axes	Create a landscape figure with an optional structure strip axis.
project_landscape_path	Project an optimization path into display coordinates.
annotate_endpoint	Annotate an optimization endpoint consistently.
default_strip_zoom	Scale strip zoom gently with atom count.
render_endpoint_strip	Render the standard endpoint strip for single-ended plots.
enforce_strip_clearance	Ensure a minimum pixel gap between x-axis text and the strip axis.
save_landscape_figure	Save optimization landscapes; always crop with a pad so labels stay visible.
save_standard_figure	Save a standard figure with tight layout.
plot_single_ended_profile	Plot shared single-ended optimization profiles.
plot_single_ended_convergence	Plot shared convergence panels for single-ended optimizers.
render_single_ended_landscape	Full single-ended landscape pipeline shared by min/saddle CLIs.
plot_optimization_landscape	Plot 2D landscape for an optimization trajectory.
plot_optimization_profile	Plot energy (and optionally eigenvalue) vs iteration.
plot_convergence_panel	Plot convergence metrics from a trajectory DataFrame.
plot_dimer_mode_evolution	Plot how the dimer mode aligns with the final mode over iterations.

Data

log
_LABELS
OVERLAY_COLORS

API

chemparseplot.plot.optimization.log

‘getLogger(…)’

chemparseplot.plot.optimization._LABELS

None

chemparseplot.plot.optimization.OVERLAY_COLORS

[‘#004D40’, ‘#FF655D’, ‘#3F51B5’, ‘#FF9800’, ‘#9C27B0’, ‘#009688’]

chemparseplot.plot.optimization.create_landscape_axes(*, dpi: int, has_strip: bool, theme, 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.

chemparseplot.plot.optimization.project_landscape_path(rmsd_a, rmsd_b, *, project_path: bool, basis=None)

Project an optimization path into display coordinates.

chemparseplot.plot.optimization.annotate_endpoint(ax, x: float, y: float, label: str, *, boxed: bool)

Annotate an optimization endpoint consistently.

chemparseplot.plot.optimization.default_strip_zoom(structs) → float

Scale strip zoom gently with atom count.

chemparseplot.plot.optimization.render_endpoint_strip(ax_strip, structs, labels, *, strip_zoom, rotation, theme, strip_renderer, strip_spacing, strip_dividers, perspective_tilt, xyzrender_config)

Render the standard endpoint strip for single-ended plots.

chemparseplot.plot.optimization.enforce_strip_clearance(fig, ax, ax_strip, *, min_clearance_px: float = 32.0) → None

Ensure a minimum pixel gap between x-axis text and the strip axis.

chemparseplot.plot.optimization.save_landscape_figure(fig, output: pathlib.Path, *, dpi: int, has_strip: bool, ax=None, ax_strip=None) → None

Save optimization landscapes; always crop with a pad so labels stay visible.

chemparseplot.plot.optimization.save_standard_figure(fig, output: pathlib.Path, *, dpi: int) → None

Save a standard figure with tight layout.

chemparseplot.plot.optimization.plot_single_ended_profile(trajs, labels, output: pathlib.Path, dpi: int, *, energy_unit: str, energy_column: str, title: str, eigen_column: str | None = None) → None

Plot shared single-ended optimization profiles.

chemparseplot.plot.optimization.plot_single_ended_convergence(trajs, labels, output: pathlib.Path, dpi: int) → None

Plot shared convergence panels for single-ended optimizers.

chemparseplot.plot.optimization.render_single_ended_landscape(*, atoms_list: collections.abc.Sequence[Any], energies_eV: numpy.ndarray, ref_a: Any, ref_b: Any, overlay_atom_lists: collections.abc.Sequence[collections.abc.Sequence[Any]] | None = None, overlay_labels: collections.abc.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, relative_energy: bool = True, title: str | None = None, cmap: str = 'viridis', output: pathlib.Path, dpi: int = 150, theme: Any | None = None, plot_structures: str = 'none', strip_structs: collections.abc.Sequence[Any] | None = None, strip_labels: collections.abc.Sequence[str] | None = None, endpoint_start_label: str = 'initial', endpoint_end_label: str = 'minimized', 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, auto_thin: bool = False, max_surface_points: int = 64, surface_fit: Any | None = None) → 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).

Parameters

auto_thin Forwarded to :func:~chemparseplot.plot.neb.plot_landscape_surface (default False: opt-in subsampling of dense fit clouds). max_surface_points Cap on fit observations when auto_thin is True. surface_fit Optional :class:~chemparseplot.plot.neb.SurfaceFitConfig or mapping (TOML table keys). When set, overrides auto_thin / max_surface_points.

Added in version 1.8.1.

Added in version 1.9.9: Added auto_thin and max_surface_points.

Added in version 1.9.10: Added surface_fit.

chemparseplot.plot.optimization.plot_optimization_landscape(ax, rmsd_a: numpy.ndarray, rmsd_b: numpy.ndarray, grad_a: numpy.ndarray, grad_b: numpy.ndarray, z_data: numpy.ndarray, *, label_mode: str = 'optimization', project_path: bool = True, method: str = 'grad_matern', cmap: str = 'viridis', energy_unit: str = 'eV', z_label: str | None = None, **surface_kwargs) → Any

Plot 2D landscape for an optimization trajectory.

Wraps :func:plot_landscape_surface and :func:plot_landscape_path_overlay with semantically correct axis labels for single-ended methods.

Parameters

ax Matplotlib axes. rmsd_a, rmsd_b RMSD distances to reference A and B. grad_a, grad_b Synthetic gradients in A and B directions. z_data Energy values for surface fitting. label_mode "optimization" (default) or "reaction" for NEB-style labels. project_path Whether to project into (s, d) coordinates. method Surface fitting method (passed to plot_landscape_surface). cmap Colormap name. z_label Label for the colorbar. **surface_kwargs Extra keyword arguments passed to :func:plot_landscape_surface.

Returns

colorbar or None

chemparseplot.plot.optimization.plot_optimization_profile(ax, iterations: numpy.ndarray, energies: numpy.ndarray, *, eigenvalues: numpy.ndarray | None = None, ax_eigen: Any = None, color: str = '#004D40', eigen_color: str = '#FF655D', energy_unit: str = 'eV') → None

Plot energy (and optionally eigenvalue) vs iteration.

Parameters

ax Matplotlib axes for the energy profile. iterations Iteration numbers. energies Energy values per iteration. eigenvalues Eigenvalue per iteration (dimer only). Plotted on ax_eigen. ax_eigen Secondary axes for eigenvalue subplot. Required if eigenvalues given. color Energy line color. eigen_color Eigenvalue line color.

chemparseplot.plot.optimization.plot_convergence_panel(ax_force, ax_step, dat_df: polars.DataFrame, *, force_col: str = 'convergence', step_col: str = 'step_size', iter_col: str = 'iteration', color: str = '#004D40') → None

Plot convergence metrics from a trajectory DataFrame.

Parameters

ax_force Axes for force/convergence metric. ax_step Axes for step size. dat_df Polars DataFrame with iteration data, usually reconstructed from embedded CON metadata and only falling back to sidecar TSV data when needed for compatibility. force_col, step_col, iter_col Column names. color Line color.

chemparseplot.plot.optimization.plot_dimer_mode_evolution(ax, mode_vectors: list[numpy.ndarray], *, color: str = '#004D40') → None

Plot how the dimer mode aligns with the final mode over iterations.

Shows the dot product of each iteration’s mode vector with the final converged mode, indicating rotation convergence.

Parameters

ax Matplotlib axes. mode_vectors List of mode vectors per iteration. The last is the reference. color Line color.