Installation Guide ¶

Author:

Rohit Goswami

Installation Guide ¶

Quick Install ¶

pip install rgpycrumbs

Preferred CLI entry ¶

Use the dispatcher — not raw uv run path/to/script.py as the primary path:

rgpycrumbs eon plt-neb --help
python -m rgpycrumbs.cli eon plt-neb --help

The dispatcher sets PYTHONPATH, defaults RGPYCRUMBS_AUTO_DEPS=1, and can honor an optional **Python lock** the uv resolver already uses:

# Any of: uv.lock | pylock.toml | CycloneDX JSON
export RGPKGS_LOCK=/path/to/uv.lock
# or: RGPKGS_LOCK=pylock.toml
# or: RGPYCRUMBS_SBOM=stack.cdx.json   # alias for --sbom
rgpycrumbs --lock "$RGPKGS_LOCK" eon plt-neb ...

Formats (auto-detected):

uv.lock — native uv lock
pylock.toml / pylock.*.toml — PEP 751 (e.g. uv export --format pylock.toml)
CycloneDX JSON — e.g. eb-stack --sbom-out, uv export --format cyclonedx1.5

PyPI packages become name==version constraints for uv run --constraints and ensure_import. Non-PyPI CDX rows (pkg:generic/...) are skipped. No lock → floating PEP 723 / AUTO_DEPS.

Layered TOML config ¶

# global
mkdir -p ~/.config/rgpkgs
cp docs/examples/rgpkgs.config.toml ~/.config/rgpkgs/config.toml

# project (overrides global; walk-up from CWD)
cp docs/examples/rgpkgs.config.toml ./rgpkgs.toml

Layer	Location
`[dispatch]`	`auto_deps`, `force_uv`
`[pins]`	default `lock` path (uv.lock / pylock / CDX)
`[pins.packages]`	explicit `name = "version"` overrides

Precedence: CLI --lock → env RGPKGS_LOCK → project TOML → /.config/rgpkgs/config.toml. Optional RGPKGS_CONFIG merges last among files.

Optional Dependencies ¶

There are **no runtime feature extras**. Scientific backends (jax, scipy, ase, chemparseplot, …) resolve on demand:

export RGPYCRUMBS_AUTO_DEPS=1
# library: ensure_import installs into the uv/cache on first use
# CLI:     PEP 723 + uv run (dispatch defaults AUTO_DEPS=1)

Or install specific packages yourself when you prefer an explicit host env:

pip install jax scipy ase

Platform Notes ¶

Linux: Full support
macOS: Full support
Windows: Most features work

Verification ¶

python -c "import rgpycrumbs; print(rgpycrumbs.__version__)"

Surface Fitting (JAX)¶

For Gaussian Process surface fitting and landscape visualization:

# JAX for surface fitting
pip install jax  # or: export RGPYCRUMBS_AUTO_DEPS=1

# Or with uv
uv pip install jax  # or: export RGPYCRUMBS_AUTO_DEPS=1

# Or enable auto-install (installs on first use)
export RGPYCRUMBS_AUTO_DEPS=1

Testing Installation ¶

python3 -c "from rgpycrumbs.surfaces import FastTPS; print('JAX working!')"

Automatic Dependency Installation ¶

rgpycrumbs supports automatic installation of optional dependencies on first use. This is useful for:

Trying features without pre-installing all dependencies
Reducing initial installation size
CI/CD pipelines where you want minimal setup
Users who only need specific features occasionally

Enabling Auto-Install ¶

Temporary (Current Session)¶

export RGPYCRUMBS_AUTO_DEPS=1
python3 -c "from rgpycrumbs.surfaces import FastTPS"  # Auto-installs JAX

Permanent (All Sessions)¶

Add to your shell configuration file:

# ~/.bashrc or ~/.zshrc
export RGPYCRUMBS_AUTO_DEPS=1

One-Command ¶

Prefix any command:

RGPYCRUMBS_AUTO_DEPS=1 python3 my_script.py

How It Works ¶

When RGPYCRUMBS_AUTO_DEPS=1 is set:

Module import is attempted normally
If module is missing, rgpycrumbs checks if it’s an optional dependency
If yes, uv pip install is run automatically
Module is imported after installation
Subsequent imports use cached installation

Supported Optional Dependencies ¶

Module	Extra	Auto-Installed	Use Case
jax	surfaces	✓	GP surface fitting, landscape plots
scipy	interpolation	✓	Spline interpolation
ase	analysis	✓	Structure analysis, RMSD

Cache Location ¶

Auto-installed packages are cached in:

~/.cache/rgpycrumbs/deps/

This cache is shared across all Python environments.

Disabling Auto-Install ¶

To disable:

export RGPYCRUMBS_AUTO_DEPS=0
# Or unset
unset RGPYCRUMBS_AUTO_DEPS

Troubleshooting ¶

“Failed to install” Error ¶

Ensure uv or pip is available:

which uv
which pip

Slow First Import ¶

First import is slow due to installation. Subsequent imports are fast.

Permission Errors ¶

Use user installation:

export RGPYCRUMBS_AUTO_DEPS=1
pip install --user jax  # or AUTO_DEPS

Examples ¶

Using Surface Fitting Without Pre-Installation ¶

# Enable auto-install
export RGPYCRUMBS_AUTO_DEPS=1

# Run script that uses JAX
python3 my_gp_script.py
# JAX is automatically installed on first import

CI/CD Pipeline ¶

# .github/workflows/ci.yml
- name: Run tests
  env:
    RGPYCRUMBS_AUTO_DEPS: "1"
  run: pytest

Jupyter Notebook ¶

import os
os.environ["RGPYCRUMBS_AUTO_DEPS"] = "1"

from rgpycrumbs.surfaces import FastTPS  # Auto-installs JAX

from rgpycrumbs.eon import plot_neb / plot_min / plot() call enable_library_auto_deps(), so RGPYCRUMBS_AUTO_DEPS defaults on (same as CLI). That stages chemparseplot, jax, adjustText, and xyzrender without host pins. Structure strips use the xyzrender Python API (not a PATH binary).

Installation Guide ¶