Installation Guide ¶

Author:

Rohit Goswami

Installation Guide ¶

Quick Install ¶

pip install rgpycrumbs

Optional Dependencies ¶

# Surface fitting (JAX)
pip install "rgpycrumbs[surfaces]"

# Interpolation (scipy)
pip install "rgpycrumbs[interpolation]"

# All optional
pip install "rgpycrumbs[all]"

Auto-Install ¶

Enable automatic dependency installation:

export RGPYCRUMBS_AUTO_DEPS=1

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:

# Recommended: Install with surfaces extra
pip install "rgpycrumbs[surfaces]"

# Or with uv
uv pip install "rgpycrumbs[surfaces]"

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

GPU Support ¶

For GPU-accelerated surface fitting:

# CUDA 12
pip install "jax[cuda12]"

# CUDA 11
pip install "jax[cuda11]"

See: JAX Installation Guide

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 "rgpycrumbs[surfaces]"

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

Installation Guide ¶