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_6g2sf7md/minimization --prefix minimization --plot-type profile --dpi 150 --output /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/minimization --prefix minimization --plot-type profile --dpi 150 --output /tmp/eon_tutorial_6g2sf7md/plots/min_profile.png
[05/10/26 19:39:42] INFO     INFO - Loading minimization trajectory from        
                             /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/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_6g2sf7md/plots/min_profile.png   

Downloading pillow (6.8MiB)
Downloading kiwisolver (1.4MiB)
Downloading debugpy (4.1MiB)
Downloading polars-runtime-32 (53.6MiB)
Downloading networkx (2.0MiB)
Downloading pygments (1.2MiB)
Downloading jax (3.0MiB)
Downloading ml-dtypes (4.8MiB)
Downloading rdkit (35.3MiB)
Downloading ase (2.8MiB)
Downloading jaxlib (81.1MiB)
Downloading resvg-py (1.1MiB)
Downloading scipy (33.6MiB)
Downloading fonttools (4.8MiB)
Downloading matplotlib (8.4MiB)
Downloading numpy (15.9MiB)
Downloading jedi (4.7MiB)
 Downloaded resvg-py
 Downloaded kiwisolver
 Downloaded pygments
 Downloaded networkx
 Downloaded debugpy
 Downloaded ml-dtypes
 Downloaded jax
 Downloaded fonttools
 Downloaded pillow
 Downloaded matplotlib
 Downloaded ase
 Downloaded numpy
 Downloaded polars-runtime-32
 Downloaded scipy
 Downloaded rdkit
 Downloaded jaxlib
 Downloaded jedi
Installed 72 packages in 234ms
   Building eon @ file:///home/runner/work/eOn/eOn
      Built eon @ file:///home/runner/work/eOn/eOn
Installed 3 packages in 19ms

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_6g2sf7md/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_6g2sf7md/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_6g2sf7md/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_6g2sf7md/plots/min_landscape.png
[05/10/26 19:39:44] INFO     INFO - Loading minimization trajectory from        
                             /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/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)...                                         
[05/10/26 19:39:45] INFO     INFO - Generating 2D surface using grad_matern     
                             (Projected: True)...                               
[05/10/26 19:39:46] 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                                          
[05/10/26 19:39:56] INFO     INFO - Calculating landscape coordinates (RMSD-A,  
                             RMSD-B)...                                         
                    INFO     INFO - Saved                                       
                             /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/minimization --prefix minimization --plot-type convergence --dpi 150 --output /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/minimization --prefix minimization --plot-type convergence --dpi 150 --output /tmp/eon_tutorial_6g2sf7md/plots/min_convergence.png
[05/10/26 19:39:58] INFO     INFO - Loading minimization trajectory from        
                             /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/minimization (17 frames)
                    INFO     INFO - Setting global rcParams for ruhi theme      
                    WARNING  WARNING - Font 'Atkinson Hyperlegible' not found.  
                             Falling back to 'sans-serif'.                      
[05/10/26 19:39:59] INFO     INFO - Saved                                       
                             /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/neb/neb_*.dat --con-file /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/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_6g2sf7md/neb/neb_*.dat --con-file /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/plots/neb_profile.png
[05/10/26 19:40:16] INFO     INFO - Setting global rcParams for ruhi theme      
                    WARNING  WARNING - Font 'Atkinson Hyperlegible' not found.  
                             Falling back to 'sans-serif'.                      
[05/10/26 19:40:17] INFO     INFO - Reading structures from                     
                             /tmp/eon_tutorial_6g2sf7md/neb/neb.con             
                    INFO     INFO - Loaded 19 structures.                       
                    INFO     INFO - Searching for files with pattern:           
                             '/tmp/eon_tutorial_6g2sf7md/neb/neb_*.dat'         
                    INFO     INFO - Found 46 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 214ms

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_6g2sf7md/neb/neb_*.dat --input-path-pattern /tmp/eon_tutorial_6g2sf7md/neb/neb_path_*.con --con-file /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/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_6g2sf7md/neb/neb_*.dat --input-path-pattern /tmp/eon_tutorial_6g2sf7md/neb/neb_path_*.con --con-file /tmp/eon_tutorial_6g2sf7md/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_6g2sf7md/plots/neb_landscape.png
[05/10/26 19:40:19] 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_6g2sf7md/neb/neb.con             
                    INFO     INFO - Loaded 19 structures.                       
                    INFO     INFO - Searching for files with pattern:           
                             '/tmp/eon_tutorial_6g2sf7md/neb/neb_*.dat'         
                    INFO     INFO - Found 46 file(s).                           
                    INFO     INFO - Searching for files with pattern:           
                             '/tmp/eon_tutorial_6g2sf7md/neb/neb_path_*.con'    
                    INFO     INFO - Found 46 file(s).                           
                    INFO     INFO - Computing Landscape data...                 
[05/10/26 19:40:20] INFO     INFO - Saving Landscape cache to                   
                             .neb_landscape.parquet...                          
[05/10/26 19:40:21] INFO     INFO - Calculated heuristic RBF smoothing: 0.1114  
                    INFO     INFO - Generating 2D surface using grad_imq        
                             (Projected: True)...                               
[05/10/26 19:40:22] 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                                          
[05/10/26 19:40:44] 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