Quickstart¶

This page walks through the main features of rgpycrumbs with minimal examples.

        flowchart TB
  subgraph install["Install"]
    CORE[pip install rgpycrumbs]
    AUTO[RGPYCRUMBS_AUTO_DEPS / uv PEP 723]
  end
  subgraph use["Use"]
    SURF[surfaces GP]
    CLI[plot_neb / eon plt-neb]
    TOML[--config plot.toml]
  end
  CORE --> AUTO
  AUTO --> SURF
  AUTO --> CLI
  TOML --> CLI
  CLI --> CPP[chemparseplot plot APIs]

Surfaces JAX kernel models for PES-style interpolation.

eOn library + CLI plots from rgpycrumbs.eon import plot, plot_neb; TOML for surface-fit knobs.

Installation¶

There are three installation modes depending on your needs.

Core only (deps resolve on first use)¶

pip install rgpycrumbs

This gives you the full import surface. Optional dependencies (jax, scipy, ase) are resolved on demand when you first use a module that needs them, provided uv is on PATH and auto-resolution is enabled:

export RGPYCRUMBS_AUTO_DEPS=1
python -c "from rgpycrumbs.surfaces import FastTPS"  # jax installed automatically

The resolver is CUDA-aware: on machines without an NVIDIA GPU it installs CPU-only variants (e.g. jax[cpu]) to avoid pulling hundreds of megabytes of unused CUDA libraries.

Optional backends¶

No feature extras. Use export RGPYCRUMBS_AUTO_DEPS=1 (library) or the CLI uv PEP 723 path. Install jax~/~scipy~/~ase yourself only if you want them preloaded in the host env.

Full stack (including pixi-only and heavy deps)¶

pixi install

This resolves the full project stack, including pixi-only packages like tblite and ira_mod, plus heavier optional tools such as ovito.

Environment Variables¶

Variable	Effect
`RGPYCRUMBS_AUTO_DEPS=1`	Enable on-demand dependency installation via uv/pip
`RGPYCRUMBS_PARENT_SITE_PACKAGES`	Colon-separated paths to parent env site-packages

Library eOn plots¶

Prefer the Python API for notebooks and scripts (same pipelines as the CLI). Heavy deps (chemparseplot, jax, xyzrender, adjustText) stage through ensure_import; library entry points enable RGPYCRUMBS_AUTO_DEPS by default.

from rgpycrumbs.eon import plot, plot_neb, plot_min

plot_neb(plot_type="profile", con_file="neb.con", output_file="1d.pdf")
plot_min(job_dir="minimization_run", plot_type="landscape", output="min.pdf")

# Live pyeonclient objects or ConFrame lists
# plot(neb, plot_type="profile", output_file="1d.pdf")
# plot(frames, kind="neb", plot_type="profile", output_file="1d.pdf")

Use config="plot.toml" for strip / surface-fit settings. See plot TOML config and the eOn tool pages under Tools.

Surface Fitting¶

The surfaces module provides JAX-based kernel methods for fitting energy landscapes from sparse data. The factory function get_surface_model returns the appropriate class.

import numpy as np
from rgpycrumbs.surfaces import get_surface_model

# Generate sample 2D data
rng = np.random.default_rng(42)
x_train = rng.uniform(-2, 2, size=(30, 2))
y_train = np.sin(x_train[:, 0]) * np.cos(x_train[:, 1])

# Fit a thin-plate spline surface
TPS = get_surface_model("tps")
model = TPS(x_train, y_train)

# Predict on a grid
x_grid = np.mgrid[-2:2:50j, -2:2:50j].reshape(2, -1).T
y_pred = model(x_grid)

# Posterior variance (uncertainty estimate)
y_var = model.predict_var(x_grid)

Other available models include "matern", "imq" (standard kernels) and "grad_matern", "grad_se", "grad_imq", "grad_rq" (gradient-enhanced kernels that incorporate force data for smoother interpolation from fewer points).

Spline Interpolation¶

For 1D energy profiles (e.g. along a reaction coordinate), spline_interp provides a quick B-spline fit:

import numpy as np
from rgpycrumbs.interpolation import spline_interp

# Coarse energy profile along a reaction coordinate
rc = np.linspace(0, 1, 10)
energy = np.array([0.0, -0.3, -0.8, -1.0, -0.5, 0.2, 0.8, 0.5, -0.1, 0.0])

# Interpolate to 200 points
rc_fine, energy_fine = spline_interp(rc, energy, num=200)

Data Types¶

The basetypes module provides lightweight containers used across rgpycrumbs and chemparseplot for NEB paths and saddle search results:

from rgpycrumbs.basetypes import nebpath, SaddleMeasure

# Store a NEB path snapshot
path = nebpath(
    norm_dist=[0.0, 0.25, 0.5, 0.75, 1.0],
    arc_dist=[0.0, 1.2, 2.4, 3.6, 4.8],
    energy=[0.0, -0.5, 0.3, -0.2, 0.0],
)

# Track saddle search results
result = SaddleMeasure(
    pes_calls=142,
    success=True,
    barrier=0.35,
    method="gprdimer",
)

CLI Dispatcher¶

The CLI uses a PEP 723 dispatcher that runs each script in an isolated uv environment. List available commands with:

rgpycrumbs --help

Plotting NEB paths (eOn)¶

# Plot NEB energy profiles from eOn .dat files (iterations 100-150)
rgpycrumbs eon plt-neb --start 100 --end 150 -o neb_profile.pdf

# Interactive plot of the latest iterations
rgpycrumbs eon plt-neb --start 280

Plotting ChemGP figures¶

# Single convergence plot from an HDF5 file
rgpycrumbs chemgp plt-gp convergence -i output/leps_minimize.h5 -o convergence.pdf

# Batch generation from a TOML config
rgpycrumbs chemgp plt-gp batch --config figures.toml

See plt-gp for the full CLI reference and Batch tutorial for a tutorial on batch figure generation.

Splitting trajectory files¶

# Split a multi-image .con trajectory into individual frames
rgpycrumbs eon con-splitter neb_final_path.con -o initial_images

This creates initial_images/ipath_000.con, ipath_001.con, etc., suitable for initializing a new NEB calculation (e.g. with IDPP via ASE).