HPFracc Development Guide

🚀 Getting Started with Development

Prerequisites

Python 3.8+
Git
CUDA toolkit (for GPU development)
Development tools (make, cmake)

Development Setup

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

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e .[dev,ml,gpu]

# Install pre-commit hooks
pre-commit install

🏗️ Project Structure

hpfracc/
├── core/                    # Core fractional calculus definitions
├── algorithms/              # Numerical algorithms and methods (see ALGORITHMS_ARCHITECTURE.md)
├── ml/                     # Machine learning integration
├── analytics/              # Performance monitoring and analytics
├── solvers/                # Fractional ODE/PDE/SDE solvers (see SOLVERS_ARCHITECTURE.md)
├── special/                # Special functions (see SPECIAL_ARCHITECTURE.md)
├── utils/                  # Utility functions (see UTILS_ARCHITECTURE.md)
└── validation/             # Validation and testing utilities (see VALIDATION_ARCHITECTURE.md)

tests/                      # Comprehensive test suite
examples/                   # Example scripts and tutorials
docs/                       # Documentation
scripts/                    # Utility scripts

🧪 Testing

Run All Tests

python -m pytest tests/

Run Specific Test Categories

# Core functionality tests
python -m pytest tests/test_core/

# Machine learning tests
python -m pytest tests/test_ml/

# GPU tests (requires CUDA)
python -m pytest tests/test_gpu/ -m gpu

# Performance tests
python -m pytest tests/test_performance/

Test Coverage

python -m pytest --cov=hpfracc --cov-report=html

Algorithms test tree + coverage (measure hpfracc and read algorithms/ rows—see architecture note on --cov=hpfracc.algorithms vs JAX):

python -m pytest tests/test_algorithms/ --cov=hpfracc --cov-report=term-missing:skip-covered -q

See ALGORITHMS_ARCHITECTURE.md for a dependency diagram, risk notes, and a sample coverage table. For Γ / binomial / Mittag–Leffler layout and import conventions, see SPECIAL_ARCHITECTURE.md. For fractional ODE/PDE/SDE modules, aliases, and JAX/Diffrax integration, see SOLVERS_ARCHITECTURE.md.

🔧 Code Quality

Code Formatting

# Format code with black
black hpfracc/ tests/

# Check code style
flake8 hpfracc/ tests/

Type Checking

# Run mypy type checking
mypy hpfracc/

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality:

Black formatting
Flake8 linting
MyPy type checking
Import sorting

📦 Building and Distribution

Build Package

python -m build

Install from Source

# Minimal (library runtime dependencies only)
pip install -e .
# Contributors: tests, coverage, formatters (matches CI)
pip install -e ".[dev]"

PyPI Publishing

# Build and upload to PyPI
python -m build
twine upload dist/*

🚀 Performance Optimization

GPU Development

Use hpfracc.ml.gpu_optimization for GPU-specific optimizations
Test with different CUDA versions
Profile memory usage with memory_usage_decorator

Parallel Computing

Use NUMBA for JIT compilation
Implement parallel processing with joblib
Monitor performance with PerformanceMonitor

Memory Management

Use chunked operations for large datasets
Implement memory-efficient algorithms
Monitor memory usage with analytics

📊 Analytics and Monitoring

Performance Monitoring

from hpfracc.analytics import PerformanceMonitor

monitor = PerformanceMonitor()
# Your code here
monitor.report()

Error Analysis

from hpfracc.analytics import ErrorAnalyzer

analyzer = ErrorAnalyzer()
# Your code here
analyzer.analyze_errors()

🔬 Research and Development

Adding New Methods

Create new method in appropriate module
Add comprehensive tests
Update documentation
Add performance benchmarks
Update API reference

Machine Learning Integration

Follow the backend management system
Implement unified tensor operations
Add fractional autograd support
Test across all backends (PyTorch, JAX, NUMBA)

Fractional Autograd Framework

Implement spectral, stochastic, or probabilistic methods
Add variance-aware training support
Test gradient flow and backpropagation
Benchmark performance

📚 Documentation

API Documentation

Update docs/API_REFERENCE_v2.md for new features
Use docstrings following NumPy style
Include examples in docstrings

User Guides

Update docs/user_guide.rst for new features
Add tutorials for complex features
Include performance benchmarks

Examples

Add examples in examples/ directory
Organize by category (ml_examples, physics_examples, etc.)
Include comprehensive README files

🐛 Debugging

Common Issues

Import Errors: Check module structure and __init__.py files
GPU Issues: Verify CUDA installation and compatibility
Memory Issues: Use memory profiling tools
Performance Issues: Use performance monitoring

Debug Tools

# ``timing_decorator`` / ``memory_usage_decorator`` resolve via lazy import on ``hpfracc.core``
from hpfracc.core import timing_decorator, memory_usage_decorator

@timing_decorator
@memory_usage_decorator
def your_function():
    pass

🤝 Contributing

Pull Request Process

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Update documentation
Run all tests and checks
Submit a pull request

Code Review Guidelines

Ensure all tests pass
Check code quality and style
Verify documentation is updated
Test performance impact
Review for security issues

📈 Release Process

Version Bumping

Update version in pyproject.toml
Update version in hpfracc/__init__.py
Update changelog
Tag release
Build and upload to PyPI

🔍 Troubleshooting

Development Environment Issues

Check Python version compatibility
Verify all dependencies are installed
Check CUDA installation for GPU features
Ensure proper virtual environment setup

Build Issues

Check setuptools and wheel versions
Verify all dependencies are available
Check for circular imports
Validate package structure

Test Issues

Check test data availability
Verify GPU availability for GPU tests
Check memory requirements
Validate test environment setup

📞 Support

For development questions and issues:

Create an issue on GitHub
Check existing documentation
Review test cases for examples
Contact: d.r.chin@pgr.reading.ac.uk