feat: structured trajectory output + visualization tutorial#331
Open
HaoZeke wants to merge 44 commits intoTheochemUI:mainfrom
Open
feat: structured trajectory output + visualization tutorial#331HaoZeke wants to merge 44 commits intoTheochemUI:mainfrom
HaoZeke wants to merge 44 commits intoTheochemUI:mainfrom
Conversation
eOn Documentation PreviewDownload: documentation.zip Unzip and open |
Benchmark ResultsTip 1 benchmark(s) improved
Improvements
7 unchanged benchmark(s)
Details
Raw asv-spyglass output |
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
force-pushed
the
feat/structured-trajectory-output
branch
from
410617d to
5a19e63
Compare
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.
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.
The jupyter kernel spawned by myst-nb may not inherit shell LD_LIBRARY_PATH. Set it inside the notebook Cell 1 so subprocess.run(eonclient) finds libmetatensor.so and libtorch.so.
myst-nb kernel dies immediately when torch is loaded in CI's jupyter context. Disable execution; tutorial outputs will be pre-cached or generated locally. The notebook remains executable for local use.
myst-nb's direct kernel executor crashes with torch on CI runners. Work around by pre-executing the notebook outside sphinx: 1. jupytext converts MyST .md -> .ipynb 2. nbconvert --execute runs the notebook (uses nbclient directly) 3. jcache stores executed outputs for sphinx to render Add jupytext, nbconvert, jupyter-cache to docs pypi-dependencies.
The nbconvert kernel may not have CONDA_PREFIX set. Use sys.prefix/lib as fallback -- this is where libmetatensor.so lives in pixi/conda envs. Also search all torch/metatensor/metatomic lib subdirs.
os.environ changes may not propagate to the dynamic linker in all kernel contexts. Pass env explicitly to subprocess.run() with sys.prefix/lib prepended to LD_LIBRARY_PATH.
Derive the prefix from which(eonclient) -> parent.parent/lib instead of relying on sys.prefix or CONDA_PREFIX. Include LD_LIBRARY_PATH and eonclient path in error message for debugging.
myst-nb spawns a jupyter kernel that doesn't inherit shell env vars. Patch the python3 kernel.json to include LD_LIBRARY_PATH so the kernel process can find libmetatensor.so and other shared libs. Also switch to run_command_or_exit from rgpycrumbs (same as atomistic cookbook) and restore nb_execution_mode=force.
run_command_or_exit() calls sys.exit() on eonclient failure, which raises SystemExit (BaseException). This kills the Jupyter kernel outright, producing an opaque DeadKernelError that jupyter-cache cannot catch (it only handles CellExecutionError/CellTimeoutError). The result is a silent ExecutionError with no traceback in CI. Replace with subprocess.run + RuntimeError so the kernel stays alive and myst-nb can report the actual cell error. Also enable nb_execution_show_tb so any future errors produce visible tracebacks.
nb_execution_show_tb only fires on the warning path (raise_on_error=False). With raise_on_error=True, the traceback is chained but Sphinx's crash handler truncates it. Temporarily disable to see the actual cell error.
eonclient exits 127 (command not found) because the myst-nb kernel subprocess does not inherit the pixi-activated PATH. The kernel spec patching only set LD_LIBRARY_PATH but not PATH. Fix: use os.environ.get() to resolve both PATH and LD_LIBRARY_PATH directly in Python (no more shell variable + sed indirection), and write both into the kernel.json env block. Also restore nb_execution_raise_on_error=True now that the root cause is identified.
The kernel spec env patching sets LD_LIBRARY_PATH on the kernel process, but subprocess.run() from within the kernel inherits os.environ which may not reflect kernel spec env vars. The actual error was: eonclient: error while loading shared libraries: libmetatensor.so: cannot open shared object file: No such file or directory Fix: compute and set LD_LIBRARY_PATH in os.environ inside the notebook setup cell so child processes inherit it.
…r.so libmetatensor.so is installed to $CONDA_PREFIX/lib by meson install, not in the Python package dirs. Add sys.prefix/lib (which equals CONDA_PREFIX in pixi) to LD_LIBRARY_PATH. Also temporarily set raise_on_error=False to verify the fix.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add per-iteration
.datoutput for minimization and saddle search whenwrite_movies=true:HelperFunctions.cpp: Writes{prefix}.datTSV alongside movie.confiles. Columns: iteration, step_size, convergence, energy.MinModeSaddleSearch.cpp: Writesclimb.datTSV alongsideclimb.con. Columns: iteration, step_size, delta_e, convergence, eigenvalue, torque, angle, rotations.Add visualization tutorial (
tutorials/visualization.md) with figures:Figures generated from real eOn runs, however given the newest con-file spec this may be reworked after #307.
Needs: