plt-min

Visualizing Minimization Optimization

This tool generates energy profiles, 2D optimization landscapes, and convergence plots from minimization calculations. The CLI also shares the same structure-strip renderer contract as plt-neb and plt-saddle, so the same backend and viewing controls work across the full eOn plotting stack.

*

Library API

from rgpycrumbs.eon import plot_min, plot

# Job directory (write_movies=true)
plot_min(job_dir="results/", plot_type="profile", output="out.pdf")

# Live object frames (Matter.movie_frames / MinModeSaddleSearch.climb_frames)
# or a ConFrame sequence with kind="min"
plot(frames, kind="min", plot_type="profile", output="out.pdf")

Same pipeline as the CLI. Heavy deps stage via ensure_import when RGPYCRUMBS_AUTO_DEPS is on (library entries enable it by default).

Method

Same projection approach as NEB/saddle search but using (initial, minimum) as references. The 2D landscape shows s = optimization progress toward the minimum and d = lateral deviation during optimization.

Requires eOn output with write_movies=true and a concatenated minimization movie. Metadata-rich full CON movies are treated as the canonical structured source; minimization.dat is retained as a compatibility and export layer when present.

Prefer TOML for dense option sets

Pipeline

        flowchart LR
  JOB[job-dir movie.con] --> LOAD[load_min_trajectory]
  LOAD --> CFG{plot.toml\nauto_thin?}
  CFG -->|false| FULL[full frames]
  CFG -->|true| THIN[fit subsample]
  FULL --> RENDER[render_single_ended_landscape]
  THIN --> RENDER
  RENDER --> PNG[min_2D.png]

Important

Surface-fit knobs are TOML-only. Do not expect --auto-thin on the CLI.

Long option lists belong in a plot config file (--config plot.toml), not ever-growing CLI flags. Shared style, strip rendering, and surface-fit knobs live under [shared]; job paths and plot type under [min]. Explicit CLI flags still override the file for one-off runs.

Surface-fit keys (auto_thin, max_surface_points) are TOML-only (defaults: auto_thin = false, max_surface_points = 64). They forward to chemparseplot SurfaceFitConfig / plot_landscape_surface (requires chemparseplot ≥ 1.9.10).

Example package path: rgpycrumbs/eon/examples/plot_config.example.toml.

# plot.toml — dense min movies (eOn write_movies force-eval dumps)
[shared]
energy_unit = "eV"
theme = "ruhi"
dpi = 200
strip_renderer = "xyzrender"
xyzrender_config = "paton"
ira_kmax = 14.0
auto_thin = false
max_surface_points = 64

[min]
job_dir = ["min_reactant"]
plot_type = "landscape"
prefix = "minimization"
surface_type = "grad_imq"
plot_structures = "endpoints"
# Opt in when LBFGS movies are very dense (~100+ force evals):
# auto_thin = true
# max_surface_points = 64
output = "min_2D.pdf"

rgpycrumbs eon plt-min --config plot.toml

Plot Types

Energy Profile

rgpycrumbs eon plt-min --job-dir results/ --plot-type profile

Shows energy vs iteration. Useful for checking monotonic descent and convergence.

2D Optimization Landscape

rgpycrumbs eon plt-min --job-dir results/ --plot-type landscape

Projects the minimization trajectory into (s, d) coordinates. A good optimizer produces a path with d near zero (straight line to the minimum).

For dense force-eval movies that make GradientIMQ surfaces non-finite, set auto_thin = true in the TOML config (see above) rather than adding more CLI flags.

Convergence Panel

rgpycrumbs eon plt-min --job-dir results/ --plot-type convergence

Side-by-side plots of force norm and step size vs iteration.

Options (CLI)

Common one-off flags. Prefer --config for surface-fit and suite style.

Option

Default

Description

--config

(none)

TOML plot config ([shared] / [min])

--job-dir

(required*)

eOn output directory (*or [min].job_dir in config)

--prefix

minimization

Movie file prefix

--plot-type

profile

profile, landscape, convergence

--project-path

True

Project into (s, d) coordinates

--surface-type

grad_matern

Surface method; dense-fit knobs only via TOML

--ira-kmax

14.0

IRA kmax for RMSD calculation

--energy-unit

eV

Presentation unit: eV, kcal/mol, kJ/mol

--theme

ruhi

Plot theme

--plot-structures

none

Structure strip below landscape: none, endpoints

--strip-renderer

xyzrender

Renderer backend for structure strips

--xyzrender-config

paton

xyzrender preset for strip rendering

--rotation

auto

Shared viewing rotation control

--perspective-tilt

0.0

Small off-axis tilt to reveal occluded atoms

-o

min_{type}.pdf

Output file path

--dpi

200

Resolution

TOML surface-fit keys (not CLI)

Key

Default

Description

auto_thin

false

Subsample dense movies for the GP fit only (endpoints kept; scatter/viewport stay full)

max_surface_points

64

Cap on fit observations when auto_thin is true

Keys may appear under [shared] or override under [min] / [neb].

Structure Rendering

Landscape plots can render the initial and final structures as a strip below the axes:

rgpycrumbs eon plt-min \
  --job-dir results/ \
  --plot-type landscape \
  --plot-structures endpoints \
  --strip-renderer xyzrender \
  --rotation auto \
  --perspective-tilt 6

The shared renderer flags behave the same as in plt-neb: --rotation auto lets xyzrender choose a good view, while ASE-style strings such as --rotation "0x,90y,0z" force a manual orientation for all backends.

Required eOn Output Files

File

Required

Description

minimization (or minimization.con)

Yes

Concatenated structure movie

minimization.dat

Fallback

Compatibility/export TSV when the movie does not carry full per-frame metadata

<prefix>.con

No

Explicit final minimized structure matching the movie prefix

min.con

No

Legacy fallback final structure when <prefix>.con is absent

See Also