rgpycrumbs

Author:

Rohit Goswami

Ecosystem Overview

The rgpycrumbs suite consists of several interlinked projects designed to streamline computational chemistry workflows.

Overview

rgpycrumbs is a computational library and CLI toolkit for chemical physics research. It provides both importable library modules for computational tasks and a dispatcher-based CLI for running self-contained research scripts.

Library Modules

Importable Python modules for surface fitting (JAX-based kernel methods), structure analysis (distance matrices, fragment detection), IRA matching (RMSD-based structure comparison), spline interpolation, and shared data types for NEB paths and saddle searches.

CLI Dispatcher

A unified command-line interface that employs PEP 723 metadata to isolate dependencies per script via uv for conflict-free, reproducible execution.

Broadly speaking, the tooling here assists with computational methods to find reaction pathways, along with packaging helpers.

Advanced NEB Visualization

The plt-neb tool offers novel visualization capabilities for Nudged Elastic Band calculations:

Force-Corrected Interpolation

Uses Hermite splines incorporating force projections to produce physically consistent energy profiles.

2D Energy Landscapes

Projects reaction paths onto Reactant/Product RMSD coordinates to reveal path complexity often hidden in 1D profiles.

Structural Context

Automatically renders and embeds atomic structure insets for critical points or all images directly onto the plots.

Simulation Setup & Analysis

eOn

NEB initial path generation

con-splitter simplifies the generation of initial paths enabling for instance IDPP initialization through ase by processing multi-image trajectories into eOn-compatible input lists.

Defect Identification

ptmdisp employs Polyhedral Template Matching via OVITO to algorithmically identify and index interstitial defects in crystalline systems.

NWChem Input Generation

generate-nwchem-input generates complete input files compatible with eOn’s SocketNWChemPot, merging geometry data with calculation settings.

ORCA

Input Generation

generate-orca-input generates ORCA input files from TOML configurations, supporting NEB and single-point runs.

PLUMED

Free Energy Reconstruction

Pure-python implementations for reconstructing bias potentials from PLUMED hills files.

Infrastructure & Maintenance

Prefix.dev Management

delete_packages helps maintain custom Conda/Pixi channels by automating the cleanup of old or specific package versions on prefix.dev.

Library API

Beyond the CLI tools, rgpycrumbs provides importable library modules:

rgpycrumbs.surfaces

JAX-based surface fitting with TPS, RBF, Matern 5/2, SE, and IMQ kernels. Includes gradient-enhanced variants for energy landscape interpolation. Install with pip install rgpycrumbs[surfaces].

rgpycrumbs.geom.analysis

Structure analysis: distance matrices, bond matrices, and fragment detection via ASE’s NeighborList. Install with pip install rgpycrumbs[analysis].

rgpycrumbs.geom.ira

Iterative Rotations and Assignments (IRA) for RMSD-based structure comparison. Install with pip install rgpycrumbs[ira].

rgpycrumbs.interpolation

Spline interpolation utilities built on SciPy. Install with pip install rgpycrumbs[interpolation].

rgpycrumbs.basetypes

Shared data structures (nebiter, nebpath, SaddleMeasure, DimerOpt, MolGeom, SpinID) used across rgpycrumbs and chemparseplot. No extra dependencies required.

On-Demand Dependency Resolution

A bare pip install rgpycrumbs gives access to the full API surface. Heavy optional dependencies (JAX, SciPy, ASE) are resolved lazily at first use through a five-step priority chain:

1. Current Python environment

2. Parent environment (via RGPYCRUMBS_PARENT_SITE_PACKAGES)

3. Shared cache ($XDG_CACHE_HOME/rgpycrumbs/deps/)

4. Automatic uv installation into the cache (opt-in: RGPYCRUMBS_AUTO_DEPS=1)

5. Actionable error message with install instructions

CUDA-aware resolution selects CPU-only package variants (e.g. jax[cpu]) on machines without a GPU, avoiding large downloads. See the quickstart for configuration details.

Utility Functions

The package also includes pure-python helpers for parsing logs like those from bless and managing data structures in Jupyter notebooks.

Getting Started

Getting Started

• Quickstart

Tool Categories

Tools

• eOn Helpers
  • Splitting con files
  • Generators for NWChem
  • MLFlow Logging for eOn
  • Plotting NEB paths
  • Polyhedral Template Matcher
• ORCA Tools
  • ORCA Input Generator
• Geometry Helpers
  • Robust Structural Alignment
  • Fragment Detection
• Surface Fitting with Kernel Methods
• General Utilities
  • Jupyter Notebook Helpers
• Prefix Helpers
  • Prefix Channel Package Deletion

Developer Reference

For details on the dispatcher architecture or internal API:

Reference

• Used By
• Changelog
• rgpycrumbs Design & Architecture Notes
• Contributing to rgpycrumbs
  • Documentation Standards & Authoring
  • Testing & Environment Requirements
  • Code of Conduct
  • Release Management
• API Reference
  • helpers
  • rgpycrumbs
  • generate_orca_input