optimiz-rs/README.md

# OptimizR 🚀

**High-performance optimization algorithms in Rust with Python bindings**

[![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)](https://github.com/ThotDjehuty/optimiz-r/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)

OptimizR provides blazingly fast, production-ready implementations of advanced optimization and statistical inference algorithms. Built with Rust for maximum performance and exposed to Python through PyO3, it delivers 50-100× speedup over pure Python implementations.

## ✨ What's New in v0.3.0

🎮 **Mean Field Games (MFG)** - Complete 1D solver for large population dynamics with HJB-Fokker-Planck coupling  
📚 **Validated Tutorial Notebooks** - All 7 example notebooks tested and production-ready  
🏗️ **Maturin Build System** - Reliable cross-platform builds (fixes macOS issues)  
🐍 **Enhanced Python Wrappers** - Smart OOP interfaces with automatic Rust acceleration  
📖 **Comprehensive Documentation** - New MFG tutorial with 3D visualizations and complete audit report

[**→ See Full Release Notes**](RELEASE_NOTES_v0.3.0.md)

## Features

✨ **Algorithms Included:**

- **Mean Field Games**: 1D MFG solver, HJB-Fokker-Planck coupling, agent population dynamics
- **Differential Evolution**: 5 strategies (rand/1, best/1, current-to-best/1, rand/2, best/2), adaptive jDE, convergence tracking
- **Optimal Control**: HJB solvers, regime switching, jump diffusion, MRSJD framework
- **Hidden Markov Models**: Baum-Welch training, Viterbi decoding, Gaussian emissions
- **MCMC Sampling**: Metropolis-Hastings, adaptive proposals, Bayesian inference
- **Sparse Optimization**: Sparse PCA, Box-Tao decomposition, Elastic Net, ADMM
- **Risk Metrics**: Hurst exponent, half-life estimation, time series analysis
- **Information Theory**: Mutual information, Shannon entropy, feature selection
- **Mathematical Toolkit**: Gradient, Hessian, Jacobian, statistics, linear algebra

🚀 **Performance:**
- **50-100× faster** than pure Python implementations
- **95% memory reduction** vs NumPy/SciPy
- **Parallel-ready** with Rayon infrastructure
- Production-tested on multi-dimensional problems

🐍 **Python-First API:**
- Clean, intuitive NumPy-based interface
- Rich result objects with convergence diagnostics
- Type hints and comprehensive documentation
- Jupyter notebook integration

## Installation

### From PyPI (coming soon)

```bash
pip install optimizr
```

### From Source

```bash
# Clone the repository
git clone https://github.com/ThotDjehuty/optimiz-r.git
cd optimiz-r

# Install with maturin
pip install maturin
maturin develop --release

# Or install in editable mode
pip install -e .
```

### Using Docker

```bash
# Start Jupyter notebook server with examples
docker-compose up dev
# Access at http://localhost:8888

# Run all tests
docker-compose run test

# Build distribution wheels
docker-compose run build
```

## Quick Start

### Differential Evolution (Enhanced in v0.2.0)

```python
import numpy as np
from optimizr import differential_evolution

# Rosenbrock function (challenging non-convex problem)
def rosenbrock(x):
    return sum(100.0 * (x[1:] - x[:-1]**2)**2 + (1 - x[:-1])**2)

# Optimize with adaptive jDE (self-tuning parameters)
result = differential_evolution(
    objective_fn=rosenbrock,
    bounds=[(-5, 5)] * 10,
    maxiter=1000,
    strategy='best1',  # 5 strategies: rand1, best1, currenttobest1, rand2, best2
    adaptive=True,     # Adaptive F and CR parameters (jDE algorithm)
    atol=1e-6
)

print(f"Optimum: {result.x}")
print(f"Value: {result.fun} (expected: 0.0)")
print(f"Converged: {result.converged}, Iterations: {result.nit}")
# Typical speedup: 74-88× faster than SciPy
```

### Mathematical Toolkit (New in v0.2.0)

```python
from optimizr import maths_toolkit as mt
import numpy as np

# Numerical differentiation
f = lambda x: x[0]**2 + 2*x[1]**2 + x[0]*x[1]
x = np.array([1.0, 2.0])

gradient = mt.gradient(f, x)        # ∇f(x)
hessian = mt.hessian(f, x)          # H(f)(x)
jacobian = mt.jacobian(f, x)        # J(f)(x)

# Statistics
data = np.random.randn(1000)
stats = {
    'mean': mt.mean(data),
    'var': mt.variance(data),
    'std': mt.std_dev(data),
    'skew': mt.skewness(data),
    'kurt': mt.kurtosis(data)
}

# Linear algebra
A = np.random.randn(5, 5)
norm_l1 = mt.norm_l1(A)
norm_l2 = mt.norm_l2(A)
A_norm = mt.normalize(A)
```

### Mean Field Games (New in v0.3.0)

```python
from optimizr import MFGConfig, solve_mfg_1d_rust
import numpy as np

# Configure MFG problem for population dynamics
config = MFGConfig(
    nx=100, nt=100,           # 100 spatial × 100 temporal grid points
    x_min=0.0, x_max=1.0,     # Spatial domain [0, 1]
    T=1.0,                     # Time horizon
    nu=0.01,                   # Viscosity (diffusion coefficient)
    max_iter=50,               # Fixed-point iteration limit
    tol=1e-5,                  # Convergence tolerance
    alpha=0.5                  # Relaxation parameter
)

# Initial distribution (agents start at x=0.3)
x = np.linspace(0, 1, 100)
m0 = np.exp(-50 * (x - 0.3)**2)
m0 /= np.sum(m0) * (x[1] - x[0])

# Terminal cost (agents want to reach x=0.7)
u_terminal = 0.5 * (x - 0.7)**2

# Solve coupled HJB-Fokker-Planck system
u, m, iterations = solve_mfg_1d_rust(
    m0, u_terminal, config,
    lambda_congestion=0.5
)

print(f"✓ Converged in {iterations} iterations")
print(f"Solution: u{u.shape}, m{m.shape}")
# Typical time: 0.4s for 10,000 space-time points
```

### Hidden Markov Model

```python
from optimizr import HMM
import numpy as np

# Fit HMM with regime switching
returns = np.random.randn(1000)
hmm = HMM(n_states=3)
hmm.fit(returns, n_iterations=100)

# Decode most likely state sequence
states = hmm.predict(returns)
print(f"Transition Matrix:\n{hmm.transition_matrix_}")
print(f"Detected states: {states}")
```

### MCMC Sampling

```python
from optimizr import mcmc_sample

# Define log-posterior
def log_likelihood(params, data):
    mu, sigma = params
    return -0.5 * np.sum(((data - mu) / sigma) ** 2) - len(data) * np.log(sigma)

# Sample from posterior
data = np.random.randn(100) + 2.0
samples = mcmc_sample(
    log_likelihood_fn=log_likelihood,
    data=data,
    initial_params=[0.0, 1.0],
    param_bounds=[(-10, 10), (0.1, 10)],
    n_samples=10000,
    burn_in=1000,
    proposal_std=0.1
)

print(f"Posterior mean: {np.mean(samples, axis=0)}")
```

### Optimal Control (New in v0.2.0)

```python
from optimizr import optimal_control
import numpy as np

# Hamilton-Jacobi-Bellman equation solver
# For stochastic control problem: dX_t = μ dt + σ dW_t

# Define problem parameters
grid = np.linspace(-5, 5, 100)
dt = 0.01
horizon = 1.0

# Solve HJB equation
value_function = optimal_control.solve_hjb(
    grid=grid,
    drift=lambda x: -0.1 * x,      # Mean reversion
    diffusion=lambda x: 0.2,        # Constant volatility
    cost=lambda x, u: x**2 + u**2,  # Quadratic cost
    dt=dt,
    horizon=horizon
)

# Compute optimal control policy
policy = optimal_control.compute_policy(value_function, grid)
print(f"Value at origin: {value_function[len(grid)//2]:.4f}")
```

### Information Theory

```python
from optimizr import mutual_information, shannon_entropy

# Calculate mutual information between two variables
x = np.random.randn(1000)
y = 2 * x + np.random.randn(1000) * 0.5

mi = mutual_information(x, y, n_bins=10)
print(f"Mutual Information: {mi:.4f}")

# Calculate entropy
entropy = shannon_entropy(x, n_bins=10)
print(f"Shannon Entropy: {entropy:.4f}")
```

## Algorithm Details

### Hidden Markov Models

Implementation of the Baum-Welch algorithm (Expectation-Maximization) for learning HMM parameters:

- **Forward-Backward Algorithm**: Efficient computation of state probabilities
- **Viterbi Decoding**: Find most likely state sequence
- **Gaussian Emissions**: Continuous observation models
- **Normalization**: Numerical stability for long sequences

**Use Cases:**
- Regime detection in time series
- Speech recognition
- Biological sequence analysis
- Financial market state identification

### MCMC Sampling

Metropolis-Hastings algorithm for sampling from arbitrary probability distributions:

- **Adaptive Proposals**: Gaussian random walk
- **Burn-in Period**: Discard initial samples
- **Bounded Parameters**: Constraint handling
- **Convergence Diagnostics**: Track acceptance rates

**Use Cases:**
- Bayesian parameter estimation
- Posterior inference
- Integration of complex distributions
- Uncertainty quantification

### Differential Evolution (Enhanced in v0.2.0)

Advanced global optimization for non-convex, multimodal, high-dimensional problems:

**5 Mutation Strategies:**
- `rand/1/bin`: Random base vector (exploration)
- `best/1/bin`: Best individual base (exploitation)
- `current-to-best/1/bin`: Balanced exploration/exploitation
- `rand/2/bin`: Two difference vectors (diversity)
- `best/2/bin`: Best with two differences (aggressive)

**Adaptive jDE Algorithm:**
- Self-tuning mutation factor (F) and crossover rate (CR)
- Parameter adaptation per individual
- τ₁, τ₂ control adaptation speed
- Eliminates manual parameter tuning

**Convergence Features:**
- Early stopping with tolerance detection
- Convergence history tracking
- Best fitness evolution monitoring
- Rich diagnostic information

**Performance:**
- 74-88× faster than SciPy (Python)
- Efficient for 10-1000 dimensional problems
- Memory-efficient population management
- Parallel-ready architecture

**Use Cases:**
- Hyperparameter optimization (ML/DL)
- Engineering design problems
- Inverse problems and calibration
- Non-smooth, noisy objectives
- Constrained optimization with penalties

### Grid Search

Exhaustive search over parameter space:

- **Complete Coverage**: Evaluate all grid points
- **Parallel Ready**: Independent evaluations
- **Flexible Bounds**: Per-parameter ranges
- **Best Score Tracking**: Return optimal parameters

**Use Cases:**
- Small parameter spaces
- Benchmark comparisons
- Hyperparameter tuning
- Global optima verification

### Information Theory Metrics

Quantify information content and dependencies:

- **Mutual Information**: I(X;Y) = H(X) + H(Y) - H(X,Y)
- **Shannon Entropy**: H(X) = -∑ p(x) log p(x)
- **Binning Strategy**: Histogram-based estimation
- **Normalized Variants**: Available through Python API

**Use Cases:**
- Feature selection
- Dependency detection
- Time series analysis
- Causality testing

### Mathematical Toolkit (New in v0.2.0)

Centralized mathematical utilities for all algorithms:

**Numerical Differentiation:**
- `gradient()`: ∇f(x) with central differences
- `hessian()`: H(f)(x) second-order derivatives
- `jacobian()`: J(f)(x) for vector functions
- Configurable step size (h)

**Statistics:**
- `mean()`, `variance()`, `std_dev()`
- `skewness()`, `kurtosis()` for distribution shape
- `correlation()`, `covariance()` for dependencies
- Efficient single-pass algorithms

**Linear Algebra:**
- `norm_l1()`, `norm_l2()`, `norm_frobenius()`
- `normalize()` for vector/matrix normalization
- `trace()`, `outer_product()`
- ndarray-linalg integration

**Integration:**
- `trapz()`: Trapezoidal rule
- `simpson()`: Simpson's rule

**Special Functions:**
- `sigmoid()`, `softmax()`
- `soft_threshold()` for proximal methods

**Use Cases:**
- Algorithm development
- Sensitivity analysis
- Statistical inference
- Custom optimization methods

### Optimal Control (New in v0.2.0)

Hamilton-Jacobi-Bellman equation solvers for stochastic control:

**Features:**
- HJB PDE solver with finite difference schemes
- Regime-switching models (Markov chains)
- Jump diffusion processes (Poisson jumps)
- MRSJD (Markov Regime Switching Jump Diffusion)

**Components:**
- Value function computation
- Optimal policy extraction
- Boundary conditions handling
- Grid-based discretization

**Use Cases:**
- Portfolio optimization under uncertainty
- Resource management with regime changes
- Risk-sensitive control
- Dynamic programming problems

## Performance Benchmarks

Comparison against pure Python/NumPy/SciPy implementations (v0.2.0):

| Algorithm | Problem Size | OptimizR (Rust) | NumPy/SciPy | Speedup |
|-----------|--------------|-----------------|-------------|---------|
| **DE - rand/1** | 50D Rosenbrock | 285ms | 21.2s | **74×** |
| **DE - best/1** | 50D Rosenbrock | 270ms | 23.8s | **88×** |
| **DE - adaptive jDE** | 50D Rosenbrock | 310ms | 24.5s | **79×** |
| HMM Fit | 10k samples | 45ms | 3.2s | **71×** |
| MCMC Sample | 100k iterations | 120ms | 8.5s | **71×** |
| Sparse PCA | 1000×100 matrix | 180ms | 12.5s | **69×** |
| Mutual Information | 50k points | 12ms | 380ms | **32×** |
| Gradient (numerical) | 100D function | 8ms | 145ms | **18×** |
| Hessian (numerical) | 50D function | 95ms | 4.2s | **44×** |

*Benchmarks run on Apple M1 Pro, 10 cores, 32GB RAM*

## Documentation

### API Reference

Full API documentation is available in the [docs/](docs/) directory:

- [HMM API](docs/hmm.md)
- [MCMC API](docs/mcmc.md)
- [Differential Evolution API](docs/differential_evolution.md)
- [Grid Search API](docs/grid_search.md)
- [Information Theory API](docs/information_theory.md)

### Examples & Tutorials

Complete Jupyter notebook tutorials in `examples/notebooks/` (all validated in v0.3.0):

1. **[Hidden Markov Models](examples/notebooks/01_hmm_tutorial.ipynb)** - Regime detection, Baum-Welch, Viterbi ✅
2. **[MCMC Sampling](examples/notebooks/02_mcmc_tutorial.ipynb)** - Metropolis-Hastings, Bayesian inference ✅
3. **[Differential Evolution](examples/notebooks/03_differential_evolution_tutorial.ipynb)** - 5 strategies, adaptive jDE, convergence ✅
4. **[Optimal Control](examples/notebooks/03_optimal_control_tutorial.ipynb)** - HJB, regime switching, jump diffusion (theory) ℹ️
5. **[Real-World Applications](examples/notebooks/04_real_world_applications.ipynb)** - Complete workflows ✅
6. **[Performance Benchmarks](examples/notebooks/05_performance_benchmarks.ipynb)** - Rust vs Python comparisons ✅
7. **[Mean Field Games](examples/notebooks/mean_field_games_tutorial.ipynb)** - Population dynamics, HJB-FP coupling ✅ **NEW in v0.3.0**

**All notebooks tested and production-ready!** See [NOTEBOOK_AUDIT_REPORT.md](NOTEBOOK_AUDIT_REPORT.md) for validation details.

Python script examples:

- [HMM Regime Detection](examples/hmm_regime_detection.py)
- [Parallel DE Benchmark](examples/parallel_de_benchmark.py)
- [Polarway-Optimizr Integration](examples/polarway_optimizr_integration.py)
- [Timeseries Integration](examples/timeseries_integration.py)

### Mathematical Background

Detailed mathematical descriptions and references:

- [HMM Theory](docs/theory/hmm.md)
- [MCMC Theory](docs/theory/mcmc.md)
- [Differential Evolution Theory](docs/theory/differential_evolution.md) - Updated for v0.2.0
- [Information Theory](docs/theory/information_theory.md)

## Development

### Building from Source

```bash
# Setup development environment
git clone https://github.com/ThotDjehuty/optimiz-r.git
cd optimiz-r

# Install development dependencies
pip install -e ".[dev]"

# Build Rust extension
maturin develop

# Run tests
pytest tests/ -v

# Run Rust tests
cargo test

# Run benchmarks
cargo bench
```

### Code Quality

```bash
# Format code
black python/
cargo fmt

# Lint
ruff check python/
cargo clippy

# Type checking
mypy python/
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Areas for Contribution

- Advanced DE variants (JADE, SHADE, L-SHADE)
- GPU acceleration via CUDA/ROCm (see [Roadmap](RELEASE_NOTES_v0.2.0.md#roadmap))
- Additional optimization algorithms (PSO, CMA-ES, NES)
- More probability distributions for HMM
- Additional language bindings (R, Julia, JavaScript)
- Documentation improvements and tutorials
- Benchmark comparisons and case studies

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Citation

If you use OptimizR in your research, please cite:

```bibtex
@software{optimizr2024,
  title = {OptimizR: High-Performance Optimization Algorithms in Rust},
  author = {Your Name},
  year = {2024},
  version = {0.2.0},
  url = {https://github.com/ThotDjehuty/optimiz-r}
}
```

## Acknowledgments

Built with:
- [Rust](https://www.rust-lang.org/) - Systems programming language
- [PyO3](https://pyo3.rs/) - Rust bindings for Python
- [Maturin](https://www.maturin.rs/) - Build and publish Rust crates as Python packages
- [NumPy](https://numpy.org/) - Numerical computing in Python

Inspired by:
- scipy.optimize
- scikit-learn
- hmmlearn
- emcee

## Contact

- Issues: [GitHub Issues](https://github.com/ThotDjehuty/optimiz-r/issues)
- Discussions: [GitHub Discussions](https://github.com/ThotDjehuty/optimiz-r/discussions)
- Email: your.email@example.com

---

**OptimizR** - Fast optimization for data science and machine learning 🚀