# HPFracc Development Guide

## 🚀 **Getting Started with Development**

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

### **Development Setup**
```bash
# 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**
```bash
python -m pytest tests/
```

### **Run Specific Test Categories**
```bash
# 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**
```bash
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):

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

See [ALGORITHMS_ARCHITECTURE.md](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](SPECIAL_ARCHITECTURE.md). For **fractional ODE/PDE/SDE** modules, aliases, and JAX/Diffrax integration, see [SOLVERS_ARCHITECTURE.md](SOLVERS_ARCHITECTURE.md).

## 🔧 **Code Quality**

### **Code Formatting**
```bash
# Format code with black
black hpfracc/ tests/

# Check code style
flake8 hpfracc/ tests/
```

### **Type Checking**
```bash
# 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**
```bash
python -m build
```

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

### **PyPI Publishing**
```bash
# 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**
```python
from hpfracc.analytics import PerformanceMonitor

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

### **Error Analysis**
```python
from hpfracc.analytics import ErrorAnalyzer

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

## 🔬 **Research and Development**

### **Adding New Methods**
1. Create new method in appropriate module
2. Add comprehensive tests
3. Update documentation
4. Add performance benchmarks
5. Update API reference

### **Machine Learning Integration**
1. Follow the backend management system
2. Implement unified tensor operations
3. Add fractional autograd support
4. Test across all backends (PyTorch, JAX, NUMBA)

### **Fractional Autograd Framework**
1. Implement spectral, stochastic, or probabilistic methods
2. Add variance-aware training support
3. Test gradient flow and backpropagation
4. 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**
1. **Import Errors**: Check module structure and `__init__.py` files
2. **GPU Issues**: Verify CUDA installation and compatibility
3. **Memory Issues**: Use memory profiling tools
4. **Performance Issues**: Use performance monitoring

### **Debug Tools**
```python
# ``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**
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Update documentation
6. Run all tests and checks
7. 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**
1. Update version in `pyproject.toml`
2. Update version in `hpfracc/__init__.py`
3. Update changelog
4. Tag release
5. Build and upload to PyPI

### **Release Checklist**
- [ ] All tests pass
- [ ] Documentation updated
- [ ] Performance benchmarks updated
- [ ] Version numbers updated
- [ ] Changelog updated
- [ ] Release notes prepared
- [ ] PyPI package built and tested

## 🔍 **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