Skip to content

feat: structured trajectory output + visualization tutorial#331

Open
HaoZeke wants to merge 30 commits intoTheochemUI:mainfrom
HaoZeke:feat/structured-trajectory-output
Open

feat: structured trajectory output + visualization tutorial#331
HaoZeke wants to merge 30 commits intoTheochemUI:mainfrom
HaoZeke:feat/structured-trajectory-output

Conversation

@HaoZeke
Copy link
Copy Markdown
Collaborator

@HaoZeke HaoZeke commented Mar 25, 2026

Add per-iteration .dat output for minimization and saddle search when write_movies=true:

  • HelperFunctions.cpp: Writes {prefix}.dat TSV alongside movie .con files. Columns: iteration, step_size, convergence, energy.
  • MinModeSaddleSearch.cpp: Writes climb.dat TSV alongside climb.con. Columns: iteration, step_size, delta_e, convergence, eigenvalue, torque, angle, rotations.

Add visualization tutorial (tutorials/visualization.md) with figures:

  • Minimization: profile, convergence panel, 2D optimization landscape (Pt heptamer, Morse)
  • Saddle search: profile, convergence panel, 2D optimization landscape (Pt heptamer, dimer)
  • NEB: energy profile, 2D reaction valley projection (Diels-Alder, PET-MAD)

Figures generated from real eOn runs, however given the newest con-file spec this may be reworked after #307.

Needs:

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 25, 2026

eOn Documentation Preview

Download: documentation.zip

Unzip and open index.html to view.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 26, 2026

Benchmark Results

Tip

1 benchmark(s) improved

Count
🟢 Improved 1
⚪ Unchanged 7

Improvements

Benchmark Before After Ratio
🟢 bench_eonclient.TimeMinimizationLJCluster.time_minimization_lbfgs 25.4±0ms 23.0±0ms 0.91x
7 unchanged benchmark(s)
Benchmark Before After Ratio
bench_eonclient.TimeMinimizationLJCluster.peakmem_minimization_lbfgs 27.1M 27.3M ~1.01x
bench_eonclient.TimeNEBMorsePt.peakmem_neb 27.2M 27.3M ~1x
bench_eonclient.TimeNEBMorsePt.time_neb 394±0ms 391±0ms ~0.99x
bench_eonclient.TimePointMorsePt.peakmem_point_evaluation 27.1M 27.3M ~1.01x
bench_eonclient.TimePointMorsePt.time_point_evaluation 7.98±0ms 7.91±0ms ~0.99x
bench_eonclient.TimeSaddleSearchMorseDimer.peakmem_saddle_search_dimer 27.2M 27.3M ~1x
bench_eonclient.TimeSaddleSearchMorseDimer.time_saddle_search_dimer 55.2±0ms 52.2±0ms ~0.95x
Details
  • Base: 5991d8bc
  • Head: 6ada6f37
  • Runner: ubuntu-22.04
Raw asv-spyglass output
All benchmarks:

| Change   | Before   | After    |   Ratio | Benchmark (Parameter)                                                  |
|----------|----------|----------|---------|------------------------------------------------------------------------|
|          | 27.1M    | 27.3M    |    1.01 | bench_eonclient.TimeMinimizationLJCluster.peakmem_minimization_lbfgs   |
| -        | 25.4±0ms | 23.0±0ms |    0.91 | bench_eonclient.TimeMinimizationLJCluster.time_minimization_lbfgs      |
|          | 27.2M    | 27.3M    |    1    | bench_eonclient.TimeNEBMorsePt.peakmem_neb                             |
|          | 394±0ms  | 391±0ms  |    0.99 | bench_eonclient.TimeNEBMorsePt.time_neb                                |
|          | 27.1M    | 27.3M    |    1.01 | bench_eonclient.TimePointMorsePt.peakmem_point_evaluation              |
|          | 7.98±0ms | 7.91±0ms |    0.99 | bench_eonclient.TimePointMorsePt.time_point_evaluation                 |
|          | 27.2M    | 27.3M    |    1    | bench_eonclient.TimeSaddleSearchMorseDimer.peakmem_saddle_search_dimer |
|          | 55.2±0ms | 52.2±0ms |    0.95 | bench_eonclient.TimeSaddleSearchMorseDimer.time_saddle_search_dimer    |

HaoZeke added 11 commits March 27, 2026 20:39
Add per-iteration .dat output for minimization and saddle search:
- HelperFunctions.cpp: writes {prefix}.dat TSV (iteration, step_size,
  convergence, energy) alongside movie .con when write_movies=true
- MinModeSaddleSearch.cpp: writes climb.dat TSV (iteration, step_size,
  delta_e, convergence, eigenvalue, torque, angle, rotations)

Add visualization tutorial (tutorials/visualization.md) with 8 figures
generated from real eOn runs:
- Minimization: profile, convergence, landscape (Pt heptamer, Morse)
- Saddle search: profile, convergence, landscape (Pt heptamer, dimer)
- NEB: profile, 2D landscape (Diels-Alder, PET-MAD via eOn+metatomic)

Update user guide output sections for minimization and saddle search.
Add ira>=2 to pixi docs environment for IRA-based RMSD in landscapes.
Convert tutorial from static markdown + pre-committed PNGs to a MyST-NB
executable notebook that runs on CI:

- Downloads PET-MAD xs v1.5.0 from HuggingFace
- Runs eonclient for minimization + NEB on HCN isomerization
- Generates all figures via rgpycrumbs at build time
- Only initial .con structures are committed (960 bytes)

CI changes:
- ci_docs.yml: uses docs-mta env (has eonclient + metatomic)
- Builds eonclient before sphinx-build
- sphinx-build -W catches broken references

Config changes:
- conf.py: myst_nb replaces myst_parser, nb_execution_mode="auto"
- pixi.toml: docs-mta env, myst-nb + rgpycrumbs + chemparseplot deps
@HaoZeke HaoZeke force-pushed the feat/structured-trajectory-output branch from 410617d to 5a19e63 Compare March 27, 2026 19:40
HaoZeke and others added 16 commits March 27, 2026 19:52
readcon-core subproject requires cbindgen to generate C headers.
…ras for docs

The visualization tutorial imports modules that need polars, ase, matplotlib.
eonclient reads ini.Get("Metatomic", "model_path", "") -- the wrong key
name caused an empty path passed to torch, crashing with SIGABRT.
- Replace ase.io.read/write(format="eon") with readcon.read_con_as_ase()
  and readcon.write_con() in visualization tutorial
- Bump readcon pin from >=0.4.2 to >=0.7.0 for read_con_as_ase API
- Set RGPYCRUMBS_AUTO_DEPS=1 for runtime dep auto-resolution
readcon 0.7 renamed the Atom constructor kwarg from is_fixed (bool) to
fixed ([bool, bool, bool]) for per-direction constraints. Update both
the write path (_atoms_to_frame) and read path (_frame_to_atoms).
eonclient links against libmetatensor.so from PyPI packages at build time,
but the dynamic linker can't find them at runtime without LD_LIBRARY_PATH.
HaoZeke added 3 commits March 28, 2026 04:36
Add all relevant lib dirs from torch, metatensor.torch, and
metatomic.torch packages. Log LD_LIBRARY_PATH and ldd check.
libmetatensor.so is installed by the metatensor conda package into
CONDA_PREFIX/lib, which isn't on LD_LIBRARY_PATH when subprocess.run()
spawns eonclient from a jupyter kernel.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant