Installation Guide

This guide will help you install lrdbenchmark and its dependencies.

Requirements

• Python 3.10–3.12 (primary test matrix)

• NumPy 2.x preferred (NumPy 1.26.x supported on a best-effort basis)

• pip (Python package installer)

• Optional: CUDA-compatible GPU for accelerated computations

Machine Learning Dependencies: * scikit-learn (for SVR, Gradient Boosting, Random Forest) * PyTorch (for CNN and deep learning models) * JAX (optional, for GPU acceleration) * NumPy, SciPy (for numerical computations)

Basic Installation

Install lrdbenchmark from PyPI:

pip install lrdbenchmark

This will install lrdbenchmark with all required dependencies including:

• 15+ Estimators: Classical, Machine Learning, and Neural Network methods

• Unified ML Features: 76-feature extraction pipeline with pre-trained models

• Production-Ready ML: SVR (29 features), Gradient Boosting (54 features), Random Forest (76 features)

• Neural Networks: CNN, LSTM, GRU, Transformer with automatic device selection

• Comprehensive Benchmarking: End-to-end benchmarking system with statistical analysis

• Demonstration Notebooks: 5 comprehensive Jupyter notebooks showcasing all features

Installation with Optional Dependencies

Supported environment policy

LRDBenchmark is validated in CI on Linux, macOS, and Windows for Python 3.10–3.12 with NumPy 2.x. NumPy 1.26.x remains available for legacy stacks, but new features are only guaranteed on the NumPy 2.x toolchain. GPU extras require the latest compatible backends (JAX ≥ 0.4.28, PyTorch ≥ 2.2, Numba ≥ 0.60) to ensure Python 3.12 support.

For GPU acceleration and additional features:

# All acceleration libraries (JAX, PyTorch, Numba)
pip install lrdbenchmark[accel-all]

# Specific acceleration libraries
pip install lrdbenchmark[accel-jax]      # JAX acceleration
pip install lrdbenchmark[accel-pytorch]  # PyTorch acceleration
pip install lrdbenchmark[accel-numba]    # Numba acceleration

# Install with development dependencies
pip install lrdbenchmark[dev]

# Install with documentation dependencies
pip install lrdbenchmark[docs]

Pretrained model artefacts

Large pretrained estimators (Random Forest, SVR, Gradient Boosting, reference neural networks) are distributed separately to keep the repository slim. Use the helper script to download and verify the artefacts you need:

python tools/fetch_pretrained_models.py                # download everything
python tools/fetch_pretrained_models.py --list         # inspect available keys
python tools/fetch_pretrained_models.py --models svr_estimator

By default artefacts are cached under ~/.cache/lrdbenchmark/models. Override the directory with LRDBENCHMARK_MODELS_DIR=/path/to/cache if you prefer a project-local cache such as artifacts/models (which is ignored by git).

CPU-only guard

For predictable imports on headless machines, LRDBenchmark masks GPUs unless you opt in. Set LRDBENCHMARK_AUTO_CPU=0 before importing the package to keep your CUDA/JAX environment untouched.

Development Installation

To install LRDBenchmark in development mode:

# Clone the repository
git clone https://github.com/dave2k77/lrdbenchmark.git
cd lrdbenchmark

# Install in development mode
pip install -e .

# Install with dashboard support
pip install -e .[dashboard]

# Install development dependencies
pip install -r requirements-dev.txt

Conda Installation

Using conda:

# Create a new conda environment with Python 3.11 (GPU-ready stack)
conda create -n lrdbenchmark python=3.11
conda activate lrdbenchmark

# Install PyTorch with CUDA 12.1 support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Install JAX with CUDA 13 support
pip install "jax[cuda13_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html

# Install additional dependencies and the package
conda install numpy scipy pandas scikit-learn numba -c conda-forge
pip install lrdbenchmark

Docker Installation

Pull the official LRDBenchmark Docker image:

docker pull lrdbenchmark/lrdbenchmark:latest

# Run with GPU support
docker run --gpus all -it lrdbenchmark/lrdbenchmark:latest

Or build from Dockerfile:

git clone https://github.com/dave2k77/lrdbenchmark.git
cd lrdbenchmark
docker build -t lrdbenchmark .
docker run -it lrdbenchmark

Verification

After installation, verify that LRDBenchmark is working correctly:

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

# Test simplified API imports
from lrdbenchmark import FBMModel, RSEstimator, CNNEstimator, LSTMEstimator
print("Simplified API imports working!")

# Test basic functionality
model = FBMModel(H=0.7, sigma=1.0)
data = model.generate(length=100, seed=42)
print(f"Generated {len(data)} samples")

# Test estimator
estimator = RSEstimator()
result = estimator.estimate(data)
print(f"Hurst estimate: {result['hurst_parameter']:.3f}")

Troubleshooting

Common Installation Issues

ImportError: No module named ‘torch’

Install PyTorch separately: pip install torch

CUDA not found

Install CUDA toolkit or use CPU-only version: pip install lrdbenchmark[cpu]

JAX installation issues

On Windows, JAX may require special installation. See JAX installation guide.

Memory issues with large datasets

Consider using smaller batch sizes or reducing data length in benchmarks.

Performance Optimization

For optimal performance:

1. Use GPU acceleration when available

2. Install optimized BLAS libraries (Intel MKL, OpenBLAS)

3. Enable JIT compilation for JAX backends

4. Use appropriate batch sizes for your hardware

Environment Variables

Set these environment variables for optimal performance:

# Enable JAX optimizations
export XLA_PYTHON_CLIENT_PREALLOCATE=false
export XLA_PYTHON_CLIENT_ALLOCATOR=platform

# PyTorch optimizations
export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1

Next Steps

After successful installation, proceed to:

• Quick Start Guide - Get started with LRDBenchmark

• Demonstration Notebooks Overview - Comprehensive demonstration notebooks

• Estimators API - Detailed estimator documentation

• Comprehensive LRDBench Demonstration - Example notebooks and scripts

Recommended Learning Path:

1. Start with Notebooks: Run the 5 demonstration notebooks in order

2. Quick Start Guide: Learn basic usage patterns

3. API Documentation: Explore detailed estimator documentation

4. Examples: Try advanced usage scenarios