Installation and Quick Start

This guide covers installation of HPFRACC with various configurations and provides quick start examples to get you up and running immediately.

Basic Installation

Install the core library:

pip install hpfracc

This installs HPFRACC with all core dependencies including NumPy, SciPy, and Matplotlib.

Installation with GPU Support

For GPU acceleration with PyTorch and JAX:

Recommended Installation for CUDA 12.8 (PyTorch) and CUDA 12 (JAX):

# Install PyTorch with CUDA 12.8 first
pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cu128

# Then install JAX with CUDA 12 support
pip install --upgrade "jax[cuda12]"

# Install HPFRACC with GPU extras
pip install hpfracc[gpu]

Note: JAX’s CUDA 12 wheels are built with CUDA 12.3 but are compatible with CUDA ≥12.1, which includes CUDA 12.8. CUDA libraries are backward compatible, so JAX will work with PyTorch’s CUDA 12.8 installation.

Alternative (simpler but may have version conflicts):

pip install hpfracc[gpu]

Installation with Machine Learning Dependencies

For full machine learning capabilities including PyTorch, JAX, and NUMBA with intelligent backend selection:

pip install hpfracc[ml]

Development Installation

For development and contribution:

git clone https://github.com/dave2k77/fractional_calculus_library.git
cd fractional_calculus_library
pip install -e .[dev]
pip install -e .[ml]

Requirements

Python: 3.9+ (dropped 3.8 support)

Required Dependencies: - NumPy >= 1.21.0 - SciPy >= 1.7.0 - Matplotlib >= 3.5.0

Optional Dependencies: - PyTorch >= 1.12.0 (for GPU acceleration and ML) - JAX >= 0.4.0 (for JAX backend and GPU) - Numba >= 0.56.0 (for JIT compilation) - NumPyro >= 0.13.0 (for probabilistic programming)

GPU Support: - CUDA-compatible GPU (optional) - CuDNN >= 9.12.0 (for JAX 0.8.0)

GPU Setup Details

JAX GPU Configuration

HPFRACC automatically configures JAX to use GPU when available:

  1. Auto-detection: On import, hpfracc.jax_gpu_setup automatically detects GPU availability

  2. Library path setup: Automatically prioritizes pip-installed CuDNN over conda’s older versions

  3. Environment setup: Configures LD_LIBRARY_PATH to find correct CuDNN libraries

  4. Graceful fallback: Falls back to CPU when GPU is not supported

  5. No user intervention: Works automatically without any configuration needed

CuDNN Compatibility

If you encounter CuDNN version mismatch errors:

  1. Upgrade CuDNN to 9.12.0+: .. code-block:: bash

    pip install –upgrade “nvidia-cudnn-cu12>=9.12.0”

  2. Configure library paths (if conda CuDNN conflicts): .. code-block:: bash

    source scripts/setup_jax_gpu_env.sh

  3. Verify installation: .. code-block:: bash

    python -c “import jax; print(jax.devices()); print(jax.default_backend())”

CUDA Version Compatibility

Key Point: JAX’s CUDA 12 wheels are built with CUDA 12.3 but work with CUDA ≥12.1, including 12.8. This ensures compatibility between JAX and PyTorch installations.

Quick Start Examples

Basic Fractional Derivative

import hpfracc
import numpy as np
from hpfracc import FractionalOrder, optimized_riemann_liouville

# Create a test function
def f(x):
    return np.sin(x)

# Define fractional order
alpha = FractionalOrder(0.5)

# Compute fractional derivative
x = np.linspace(0, 2*np.pi, 100)
result = optimized_riemann_liouville(x, f(x), alpha)

print(f"Fractional derivative computed for {len(x)} points")
print(f"First 5 values: {result[:5]}")

Spectral Autograd with PyTorch

import torch
from hpfracc.ml import SpectralFractionalDerivative, BoundedAlphaParameter

# Create input with gradient support
x = torch.randn(32, requires_grad=True)
alpha = 0.5  # fractional order

# Apply spectral fractional derivative
result = SpectralFractionalDerivative.apply(x, alpha, -1, "fft")

# Gradients flow properly through fractional derivatives
loss = torch.sum(result)
loss.backward()

print(f"Input gradient norm: {x.grad.norm().item():.6f}")

Learnable Fractional Orders

import torch
from hpfracc.ml import SpectralFractionalDerivative, BoundedAlphaParameter

# Create learnable alpha parameter
alpha_param = BoundedAlphaParameter(alpha_init=1.0)

x = torch.randn(32, requires_grad=True)

# Use in computation
alpha_val = alpha_param()
result = SpectralFractionalDerivative.apply(x, alpha_val, -1, "fft")

# Alpha gradients are computed automatically
loss = torch.sum(result)
loss.backward()

print(f"Alpha value: {alpha_val.item():.4f}")
print(f"Alpha gradient: {alpha_param.rho.grad.item():.6f}")

Intelligent Backend Selection

import hpfracc
from hpfracc.ml.intelligent_backend_selector import IntelligentBackendSelector
from hpfracc.ml.intelligent_backend_selector import WorkloadCharacteristics

# Create intelligent backend selector
selector = IntelligentBackendSelector(enable_learning=True)

# Define workload characteristics
workload = WorkloadCharacteristics(
    operation_type="fractional_derivative",
    data_size=10000,
    data_shape=(100, 100),
    requires_gradient=True
)

# Select optimal backend automatically
backend = selector.select_backend(workload)
print(f"Selected backend: {backend}")

# Use with fractional operations
frac_deriv = hpfracc.create_fractional_derivative(alpha=0.5, definition="caputo")
result = frac_deriv(f, x)  # Automatically uses optimal backend

Verification

Check Installation

import hpfracc
print(f"HPFRACC version: {hpfracc.__version__}")

# Test basic functionality
from hpfracc.core.derivatives import CaputoDerivative
caputo = CaputoDerivative(order=0.5)
print("✅ Installation successful!")

Check GPU Availability

# Check PyTorch GPU
import torch
print(f"PyTorch CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"PyTorch CUDA version: {torch.version.cuda}")

# Check JAX GPU
try:
    import jax
    print(f"JAX devices: {jax.devices()}")
    print(f"JAX backend: {jax.default_backend()}")
except ImportError:
    print("JAX not installed")

# Check HPFRACC GPU setup
from hpfracc.jax_gpu_setup import JAX_GPU_AVAILABLE
print(f"HPFRACC JAX GPU available: {JAX_GPU_AVAILABLE}")

Troubleshooting Installation

Common Issues

Import Errors After Installation: - Ensure you’re using Python 3.9+ - Try reinstalling: pip install --upgrade --force-reinstall hpfracc - Check that dependencies are installed: pip list | grep hpfracc

GPU Not Detected: - Verify CUDA is installed: nvidia-smi - Check PyTorch CUDA: python -c "import torch; print(torch.cuda.is_available())" - For JAX, ensure jax[cuda12] is installed correctly

CuDNN Version Mismatch: - Upgrade CuDNN: pip install --upgrade "nvidia-cudnn-cu12>=9.12.0" - Use setup script: source scripts/setup_jax_gpu_env.sh - Check library paths match installed CuDNN version

Package Conflicts: - Use virtual environment: python -m venv venv && source venv/bin/activate - Install in isolated environment to avoid conflicts - Consider using conda if pip conflicts persist

Next Steps

Once installation is complete:

  1. Start with: Basic Examples for basic usage examples

  2. Explore: Advanced Features for advanced capabilities

  3. Learn: Integrals and Derivatives for comprehensive operator guide

  4. Build: Fractional Neural Networks for ML integration

For detailed GPU setup information, see JAX GPU Setup for HPFRACC Library.