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.

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.

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),
    "--prefix", "minimization",
    "--plot-type", "profile",
    "--dpi", "150",
    "--output", str(min_profile),
)
show_plot(min_profile)

$ /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/bin/python3.12 -m rgpycrumbs.cli eon plt-min --job-dir /tmp/eon_tutorial_s2gxfva8/minimization --prefix minimization --plot-type profile --dpi 150 --output /tmp/eon_tutorial_s2gxfva8/plots/min_profile.png

--> Dispatching to: uv run --with-editable /home/runner/work/eOn/eOn /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/lib/python3.12/site-packages/rgpycrumbs/eon/plt_min.py --job-dir /tmp/eon_tutorial_s2gxfva8/minimization --prefix minimization --plot-type profile --dpi 150 --output /tmp/eon_tutorial_s2gxfva8/plots/min_profile.png
[06/13/26 11:49:20] INFO     INFO - Loading minimization trajectory from        
                             /tmp/eon_tutorial_s2gxfva8/minimization            
                    INFO     INFO - Using minimization metrics from frame       
                             metadata (17 rows)                                 
                    INFO     INFO - Loaded 17 frames, 17 data rows              
                    INFO     INFO - Loaded minimization trajectory from         
                             /tmp/eon_tutorial_s2gxfva8/minimization (17 frames)
                    INFO     INFO - Setting global rcParams for ruhi theme      
                    WARNING  WARNING - Font 'Atkinson Hyperlegible' not found.  
                             Falling back to 'sans-serif'.                      
[06/13/26 11:49:21] INFO     INFO - Saved                                       
                             /tmp/eon_tutorial_s2gxfva8/plots/min_profile.png   

Downloading numpy (15.9MiB)
Downloading ml-dtypes (4.8MiB)
Downloading polars-runtime-32 (53.8MiB)
Downloading scipy (33.6MiB)
Downloading fonttools (4.8MiB)
Downloading matplotlib (9.6MiB)
Downloading jedi (4.7MiB)
Downloading debugpy (3.8MiB)
Downloading pygments (1.2MiB)
Downloading pillow (6.8MiB)
Downloading jax (3.0MiB)
Downloading kiwisolver (1.4MiB)
Downloading jaxlib (81.9MiB)
Downloading ase (2.8MiB)
Downloading rdkit (35.5MiB)
Downloading networkx (2.0MiB)
Downloading resvg-py (1.1MiB)
 Downloaded resvg-py
 Downloaded kiwisolver
 Downloaded pygments
 Downloaded networkx
 Downloaded debugpy
 Downloaded jax
 Downloaded ml-dtypes
 Downloaded fonttools
 Downloaded pillow
 Downloaded ase
 Downloaded matplotlib
 Downloaded numpy
 Downloaded polars-runtime-32
 Downloaded scipy
 Downloaded rdkit
 Downloaded jaxlib
 Downloaded jedi
Installed 72 packages in 215ms
   Building eon @ file:///home/runner/work/eOn/eOn
      Built eon @ file:///home/runner/work/eOn/eOn
Installed 3 packages in 15ms

2D optimization landscape

min_landscape = plot_dir / "min_landscape.png"
run_rgpycrumbs(
    "eon", "plt-min",
    "--job-dir", str(min_dir),
    "--prefix", "minimization",
    "--plot-type", "landscape",
    "--project-path",
    "--surface-type", "grad_matern",
    "--plot-structures", "endpoints",
    "--strip-renderer", "xyzrender",
    "--perspective-tilt", "8",
    "--dpi", "150",
    "--output", str(min_landscape),
)
show_plot(min_landscape)

$ /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/bin/python3.12 -m rgpycrumbs.cli eon plt-min --job-dir /tmp/eon_tutorial_s2gxfva8/minimization --prefix minimization --plot-type landscape --project-path --surface-type grad_matern --plot-structures endpoints --strip-renderer xyzrender --perspective-tilt 8 --dpi 150 --output /tmp/eon_tutorial_s2gxfva8/plots/min_landscape.png

--> Dispatching to: uv run --with-editable /home/runner/work/eOn/eOn /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/lib/python3.12/site-packages/rgpycrumbs/eon/plt_min.py --job-dir /tmp/eon_tutorial_s2gxfva8/minimization --prefix minimization --plot-type landscape --project-path --surface-type grad_matern --plot-structures endpoints --strip-renderer xyzrender --perspective-tilt 8 --dpi 150 --output /tmp/eon_tutorial_s2gxfva8/plots/min_landscape.png
[06/13/26 11:49:22] INFO     INFO - Loading minimization trajectory from        
                             /tmp/eon_tutorial_s2gxfva8/minimization            
                    INFO     INFO - Using minimization metrics from frame       
                             metadata (17 rows)                                 
                    INFO     INFO - Loaded 17 frames, 17 data rows              
                    INFO     INFO - Loaded minimization trajectory from         
                             /tmp/eon_tutorial_s2gxfva8/minimization (17 frames)
                    INFO     INFO - Setting global rcParams for ruhi theme      
                    WARNING  WARNING - Font 'Atkinson Hyperlegible' not found.  
                             Falling back to 'sans-serif'.                      
                    INFO     INFO - Calculating landscape coordinates (RMSD-A,  
                             RMSD-B)...                                         
                    INFO     INFO - Generating 2D surface using grad_matern     
                             (Projected: True)...                               
[06/13/26 11:49:23] INFO     INFO - Unable to initialize backend 'tpu':         
                             INTERNAL: Failed to open libtpu.so: libtpu.so:     
                             cannot open shared object file: No such file or    
                             directory                                          
[06/13/26 11:49:31] INFO     INFO - Calculating landscape coordinates (RMSD-A,  
                             RMSD-B)...                                         
[06/13/26 11:49:32] INFO     INFO - Saved                                       
                             /tmp/eon_tutorial_s2gxfva8/plots/min_landscape.png 

Convergence panel

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

$ /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/bin/python3.12 -m rgpycrumbs.cli eon plt-min --job-dir /tmp/eon_tutorial_s2gxfva8/minimization --prefix minimization --plot-type convergence --dpi 150 --output /tmp/eon_tutorial_s2gxfva8/plots/min_convergence.png

--> Dispatching to: uv run --with-editable /home/runner/work/eOn/eOn /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/lib/python3.12/site-packages/rgpycrumbs/eon/plt_min.py --job-dir /tmp/eon_tutorial_s2gxfva8/minimization --prefix minimization --plot-type convergence --dpi 150 --output /tmp/eon_tutorial_s2gxfva8/plots/min_convergence.png
[06/13/26 11:49:34] INFO     INFO - Loading minimization trajectory from        
                             /tmp/eon_tutorial_s2gxfva8/minimization            
                    INFO     INFO - Using minimization metrics from frame       
                             metadata (17 rows)                                 
                    INFO     INFO - Loaded 17 frames, 17 data rows              
                    INFO     INFO - Loaded minimization trajectory from         
                             /tmp/eon_tutorial_s2gxfva8/minimization (17 frames)
                    INFO     INFO - Setting global rcParams for ruhi theme      
                    WARNING  WARNING - Font 'Atkinson Hyperlegible' not found.  
                             Falling back to 'sans-serif'.                      
                    INFO     INFO - Saved                                       
                             /tmp/eon_tutorial_s2gxfva8/plots/min_convergence.pn
                             g                                                  

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",
    "--rc-mode", "rmsd",
    "--plot-type", "profile",
    "--plot-structures", "crit_points",
    "--strip-renderer", "xyzrender",
    "--perspective-tilt", "8",
    "--zoom-ratio", "0.15",
    "--dpi", "150",
    "--output-file", str(neb_profile),
)
show_plot(neb_profile)

$ /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/bin/python3.12 -m rgpycrumbs.cli eon plt-neb --input-dat-pattern /tmp/eon_tutorial_s2gxfva8/neb/neb_*.dat --con-file /tmp/eon_tutorial_s2gxfva8/neb/neb.con --ira-kmax 14 --force-recompute --rc-mode rmsd --plot-type profile --plot-structures crit_points --strip-renderer xyzrender --perspective-tilt 8 --zoom-ratio 0.15 --dpi 150 --output-file /tmp/eon_tutorial_s2gxfva8/plots/neb_profile.png

--> Dispatching to: uv run --with-editable /home/runner/work/eOn/eOn /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/lib/python3.12/site-packages/rgpycrumbs/eon/plt_neb.py --input-dat-pattern /tmp/eon_tutorial_s2gxfva8/neb/neb_*.dat --con-file /tmp/eon_tutorial_s2gxfva8/neb/neb.con --ira-kmax 14 --force-recompute --rc-mode rmsd --plot-type profile --plot-structures crit_points --strip-renderer xyzrender --perspective-tilt 8 --zoom-ratio 0.15 --dpi 150 --output-file /tmp/eon_tutorial_s2gxfva8/plots/neb_profile.png
[06/13/26 11:49:46] INFO     INFO - Setting global rcParams for ruhi theme      
                    WARNING  WARNING - Font 'Atkinson Hyperlegible' not found.  
                             Falling back to 'sans-serif'.                      
                    INFO     INFO - Reading structures from                     
                             /tmp/eon_tutorial_s2gxfva8/neb/neb.con             
                    INFO     INFO - Loaded 19 structures.                       
                    INFO     INFO - Searching for files with pattern:           
                             '/tmp/eon_tutorial_s2gxfva8/neb/neb_*.dat'         
                    INFO     INFO - Found 39 file(s).                           
                    INFO     INFO - Computing Profile RMSD data...              
                    INFO     INFO - Saving Profile RMSD cache to                
                             .neb_landscape.parquet...                          

Downloading h5py (5.2MiB)
 Downloaded h5py
Installed 74 packages in 156ms

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",
    "--rc-mode", "rmsd",
    "--plot-type", "landscape",
    "--surface-type", "grad_imq",
    "--show-pts",
    "--landscape-path", "all",
    "--project-path",
    "--plot-structures", "crit_points",
    "--strip-renderer", "xyzrender",
    "--strip-dividers",
    "--perspective-tilt", "8",
    "--zoom-ratio", "0.2",
    "--show-legend",
    "--dpi", "150",
    "--output-file", str(neb_landscape),
)
show_plot(neb_landscape)

$ /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/bin/python3.12 -m rgpycrumbs.cli eon plt-neb --input-dat-pattern /tmp/eon_tutorial_s2gxfva8/neb/neb_*.dat --input-path-pattern /tmp/eon_tutorial_s2gxfva8/neb/neb_path_*.con --con-file /tmp/eon_tutorial_s2gxfva8/neb/neb.con --ira-kmax 14 --force-recompute --rc-mode rmsd --plot-type landscape --surface-type grad_imq --show-pts --landscape-path all --project-path --plot-structures crit_points --strip-renderer xyzrender --strip-dividers --perspective-tilt 8 --zoom-ratio 0.2 --show-legend --dpi 150 --output-file /tmp/eon_tutorial_s2gxfva8/plots/neb_landscape.png

--> Dispatching to: uv run --with-editable /home/runner/work/eOn/eOn /home/runner/work/eOn/eOn/.pixi/envs/docs-mta/lib/python3.12/site-packages/rgpycrumbs/eon/plt_neb.py --input-dat-pattern /tmp/eon_tutorial_s2gxfva8/neb/neb_*.dat --input-path-pattern /tmp/eon_tutorial_s2gxfva8/neb/neb_path_*.con --con-file /tmp/eon_tutorial_s2gxfva8/neb/neb.con --ira-kmax 14 --force-recompute --rc-mode rmsd --plot-type landscape --surface-type grad_imq --show-pts --landscape-path all --project-path --plot-structures crit_points --strip-renderer xyzrender --strip-dividers --perspective-tilt 8 --zoom-ratio 0.2 --show-legend --dpi 150 --output-file /tmp/eon_tutorial_s2gxfva8/plots/neb_landscape.png
[06/13/26 11:49:50] INFO     INFO - Setting global rcParams for ruhi theme      
                    WARNING  WARNING - Font 'Atkinson Hyperlegible' not found.  
                             Falling back to 'sans-serif'.                      
                    INFO     INFO - Reading structures from                     
                             /tmp/eon_tutorial_s2gxfva8/neb/neb.con             
                    INFO     INFO - Loaded 19 structures.                       
                    INFO     INFO - Searching for files with pattern:           
                             '/tmp/eon_tutorial_s2gxfva8/neb/neb_*.dat'         
                    INFO     INFO - Found 39 file(s).                           
                    INFO     INFO - Searching for files with pattern:           
                             '/tmp/eon_tutorial_s2gxfva8/neb/neb_path_*.con'    
                    INFO     INFO - Found 39 file(s).                           
                    INFO     INFO - Computing Landscape data...                 
[06/13/26 11:49:51] INFO     INFO - Saving Landscape cache to                   
                             .neb_landscape.parquet...                          
                    INFO     INFO - Calculated heuristic RBF smoothing: 0.1086  
                    INFO     INFO - Generating 2D surface using grad_imq        
                             (Projected: True)...                               
                    INFO     INFO - Unable to initialize backend 'tpu':         
                             INTERNAL: Failed to open libtpu.so: libtpu.so:     
                             cannot open shared object file: No such file or    
                             directory                                          
[06/13/26 11:50:07] WARNING  WARNING - Looks like you are using a tranform that 
                             doesn't support FancyArrowPatch, using ax.annotate 
                             instead. The arrows might strike through texts.    
                             Increasing shrinkA in arrowprops might help.       
                    INFO     INFO - Set symmetric Y-axis limits: [-1.01, 1.01]  

See also

For producing your own NEB trajectories beyond this tutorial:

• 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

• rgpycrumbs documentation for advanced options (structure rendering, multiple trajectory overlays, custom themes)

• Minimization and Saddle Search for output file details

• Dictionary-Style Configuration for programmatic configuration