Visualizing Optimization Trajectories

eOn can embed structured per-iteration metadata directly into trajectory movie frames when write_movies = true is set in the [Debug] section of config.ini. These metadata-rich .con movies enable rich 2D reaction-valley projections and convergence plots via rgpycrumbs and chemparseplot.

For one compatibility window, write_deprecated_outs = true can also be used to emit the older minimization and saddle-search .dat sidecars. NEB continues to write its existing neb.dat / neb_*.dat outputs alongside the .con movies.

Tip

Prefer the built-in potential systems under Real systems for documentation (Morse Pt NEB, LJ minimization) when you want CI-stable examples without downloading a metatomic model. This page keeps the PET-MAD vinyl alcohol case as the metatomic consumer walkthrough.

This tutorial walks through two complete workflows with PET-MAD:

  • a single-ended minimization of a perturbed vinyl alcohol structure

  • an OCI-NEB calculation for vinyl alcohol -> acetaldehyde

For each workflow we run eonclient, then visualize the result through the public rgpycrumbs dispatcher so the tutorial matches current command-line usage.

Plotting conventions used here (and in Real systems for documentation):

Job

CLI

Notes

NEB profile

plt-neb --plot-type profile --highlight-last --plot-structures all

Gold SP star on the final band; full structure strip

NEB landscape

plt-neb --plot-type landscape --project-path --landscape-path all

True 1:1 Å (s, d) panel; two-row strip when many images

Min profile / conv

plt-min --plot-type profile|convergence

Overlay multiple --job-dir / --label pairs

Min landscape

plt-min --plot-type landscape --label reactant

One landscape per endpoint; title + initial/minimized labels

Setup

Minimization

We start by minimizing a slightly distorted vinyl alcohol molecule to demonstrate the single-ended optimization outputs consumed by rgpycrumbs eon plt-min.

Energy profile

min_profile = plot_dir / "min_profile.png"
run_rgpycrumbs(
    "eon", "plt-min",
    "--job-dir", str(min_dir),
    "--label", "vinyl alcohol",
    "--prefix", "minimization",
    "--plot-type", "profile",
    "--dpi", "150",
    "--output", str(min_profile),
)
show_plot(min_profile)

2D optimization landscape

One landscape for this job only (do not overlay unrelated endpoints on a shared (s, d) frame). The title and strip use the --label.

min_landscape = plot_dir / "min_landscape.png"
run_rgpycrumbs(
    "eon", "plt-min",
    "--job-dir", str(min_dir),
    "--label", "vinyl alcohol",
    "--prefix", "minimization",
    "--plot-type", "landscape",
    "--project-path",
    "--surface-type", "grad_imq",
    "--plot-structures", "endpoints",
    "--strip-renderer", "xyzrender",
    "--strip-dividers",
    "--xyzrender-config", "paton",
    "--rotation", "90x,0y,0z",
    "--dpi", "150",
    "--output", str(min_landscape),
)
show_plot(min_landscape)

Convergence panel

min_convergence = plot_dir / "min_convergence.png"
run_rgpycrumbs(
    "eon", "plt-min",
    "--job-dir", str(min_dir),
    "--label", "vinyl alcohol",
    "--prefix", "minimization",
    "--plot-type", "convergence",
    "--dpi", "150",
    "--output", str(min_convergence),
)
show_plot(min_convergence)

Nudged Elastic Band

We run an OCI-NEB calculation on the vinyl alcohol -> acetaldehyde keto-enol tautomerization using PET-MAD.

Energy profile

neb_profile = plot_dir / "neb_profile.png"
run_rgpycrumbs(
    "eon", "plt-neb",
    "--input-dat-pattern", str(neb_dir / "neb_*.dat"),
    "--con-file", str(neb_dir / "neb.con"),
    "--ira-kmax", "14",
    "--force-recompute",
    "--plot-type", "profile",
    "--highlight-last",
    "--show-pts",
    # Full band strip (use crit_points for a lighter R/SP/P-only strip).
    "--plot-structures", "all",
    "--strip-renderer", "xyzrender",
    "--strip-dividers",
    "--xyzrender-config", "paton",
    "--rotation", "90x,0y,0z",
    "--show-legend",
    "--title", "Vinyl alcohol NEB path optimization",
    "--dpi", "150",
    "--output-file", str(neb_profile),
)
show_plot(neb_profile)

2D reaction landscape

neb_landscape = plot_dir / "neb_landscape.png"
run_rgpycrumbs(
    "eon", "plt-neb",
    "--input-dat-pattern", str(neb_dir / "neb_*.dat"),
    "--input-path-pattern", str(neb_dir / "neb_path_*.con"),
    "--con-file", str(neb_dir / "neb.con"),
    "--ira-kmax", "14",
    "--force-recompute",
    "--plot-type", "landscape",
    "--rc-mode", "path",
    "--landscape-mode", "surface",
    "--surface-type", "grad_imq",
    "--show-pts",
    "--highlight-last",
    # Full history for the GP surface; 1:1 Å (s, d) panel via --project-path.
    "--landscape-path", "all",
    "--project-path",
    "--plot-structures", "all",
    "--strip-renderer", "xyzrender",
    "--strip-dividers",
    "--xyzrender-config", "paton",
    "--rotation", "90x,0y,0z",
    "--show-legend",
    "--title", "Vinyl alcohol NEB-RMSD surface",
    "--dpi", "150",
    "--output-file", str(neb_landscape),
)
show_plot(neb_landscape)

See also

For producing your own NEB trajectories beyond this tutorial:

  • Real systems for documentation — built-in Morse Pt NEB, LJ minimization, and Pt saddle systems (recommended for docs / CI)

  • The eon-pet-neb example in the lab-cosmo/atomistic-cookbook: a step-by-step PET-MAD NEB walkthrough using ASE for path setup. This is the canonical metatomic-consumer integration test for eOn.

  • HaoZeke/eon_orchestrator: Snakemake-orchestrated workflow for batches of NEB calculations with PET-MAD, including IRA pre-alignment, endpoint minimization, energy profiles, and 2D RMSD landscapes. The vinyl alcohol config used in this tutorial is taken from examples/vinyl_alcohol/.

Further reading