Minimization Visualization

This tutorial shows how to visualize energy minimization trajectories using plt-min. You will produce energy profiles, 2D optimization landscapes, and convergence panels.

Reference

The 2D projection method used here is described in:

R. Goswami, “Two-dimensional RMSD projections for reaction path visualization and validation,” MethodsX, p. 103851, Mar. 2026, doi:10.1016/j.mex.2026.103851.

Prerequisites

plt-min reads eOn minimization output: a movie file (multi-frame .con), a .dat iteration log, and optionally the final structure.

pip install "rgpycrumbs[all]"

The expected directory layout:

min_job/
  min            # multi-frame .con trajectory (movie file)
  min.dat        # TSV: iteration, step_size, convergence, energy
  min.con        # (optional) final minimized structure

The file prefix defaults to min but can be changed with --prefix (e.g., --prefix qm_min for qm_min, qm_min.dat, qm_min.con).

Step 1: Energy Profile

The profile plot shows total energy vs iteration. A successful minimization shows monotonically decreasing energy converging to a plateau.

rgpycrumbs eon plt-min \
  --job-dir min_job/ \
  --plot-type profile \
  -o min_profile.pdf
Energy profile for minimization

The exponential decay shape is typical for gradient descent minimization. The curve should flatten as forces approach zero.

Step 2: 2D Optimization Landscape

The landscape projects the trajectory into (s, d) coordinates:

  • s (progress): RMSD distance from initial to final structure

  • d (deviation): lateral displacement from the direct path

rgpycrumbs eon plt-min \
  --job-dir min_job/ \
  --plot-type landscape \
  --surface-type grad_matern \
  --project-path \
  -o min_landscape.pdf
2D optimization landscape for minimization

For a well-behaved minimization, the trajectory should follow the energy valley from the initial displaced geometry toward the minimum. Large lateral deviations indicate the optimizer is exploring off-pathway configurations.

Step 3: Convergence Panel

The convergence panel monitors the force norm and step size to diagnose optimization quality.

rgpycrumbs eon plt-min \
  --job-dir min_job/ \
  --plot-type convergence \
  -o min_convergence.pdf
Convergence panel for minimization

Both curves should decrease monotonically. Oscillations in the force norm suggest the step size is too large or the optimizer is struggling with the PES topology.

Custom File Prefix

eOn minimization jobs can use different prefixes depending on the job type. Use --prefix to match:

# For jobs with qm_min, qm_min.dat, qm_min.con
rgpycrumbs eon plt-min --job-dir job/ --prefix qm_min --plot-type profile

Step 4: Comparing Optimizers

Use --job-dir multiple times to overlay trajectories from different optimizers (FIRE, LBFGS, SD) on the same plot:

rgpycrumbs eon plt-min \
  --job-dir fire_min/ --label FIRE \
  --job-dir lbfgs_min/ --label LBFGS \
  --job-dir sd_min/ --label SD \
  --plot-type profile \
  -o optimizer_comparison.pdf

Each trajectory is plotted with a different color and appears in the legend. This works for profile, landscape, and convergence plots. On the landscape, the GP surface is fitted from the primary (first) trajectory, and all paths are overlaid.

# Convergence comparison
rgpycrumbs eon plt-min \
  --job-dir fire_min/ --label FIRE \
  --job-dir lbfgs_min/ --label LBFGS \
  --plot-type convergence \
  -o convergence_comparison.pdf

Summary

Feature

Flag

Notes

Energy profile

--plot-type profile

Energy vs iteration

2D landscape

--plot-type landscape

GP surface fit

Convergence

--plot-type convergence

Force + step size

Multi-trajectory

--job-dir A --job-dir B

Overlay with legend

Structure strip

--plot-structures endpoints

Init and Min below

Custom prefix

--prefix qm_min

For non-default file names

Projection toggle

--project-path / --no-project-path

Default: on

See Also