ThotDjehuty
d8682f61e5
PyO3 abi3 bindings for the 13 v2.0.0 functions across 8 module groups:
bsde, pde, stochastic_control, optimal_control::quadratic_impact_control,
mean_field::mckean_vlasov, agent_based, inference, optimization.
8 executed companion notebooks under examples/notebooks/10_bsde.ipynb …
17_generative_calibration.ipynb (cell outputs and matplotlib figures
preserved as proof-of-work; verified against analytic ground truths).
8 Sphinx RST pages under docs/source/algorithms/{bsde,pde,stochastic_control,
quadratic_impact_control,mckean_vlasov,agent_based,robust_drift,
generative_calibration_hooks}.rst with .. math:: derivations and inline
.. image:: directives placed immediately after each .. code-block:: python
so each plot appears directly under the code that produced it.
18 PNG plot assets under docs/source/_static/v2/<group>/.
index.rst extended with a new 'v2.0 Generic Stochastic Control & PDE'
toctree caption.
Forbidden-vocabulary audit on new src/, docs/source/algorithms/ and
binding files: zero matches.
All previously stable APIs untouched; v2.0.0 is additive at the binding
level — no v1.x function signature was changed.
OptimizR Tutorial Notebooks
This directory contains comprehensive Jupyter notebook tutorials demonstrating OptimizR's capabilities.
✅ Production-Ready Tutorials (6/8 - 75%)
These notebooks are fully functional and execute successfully with outputs:
1. Hidden Markov Models - 01_hmm_tutorial.ipynb (388 KB)
Level: Beginner
Topics: Baum-Welch algorithm, Viterbi decoding, regime detection
Use Cases: Market regime detection, financial time series
2. MCMC Sampling - 02_mcmc_tutorial.ipynb (446 KB)
Level: Intermediate
Topics: Metropolis-Hastings, Bayesian inference, parameter estimation
Use Cases: Statistical modeling, uncertainty quantification
3. Differential Evolution - 03_differential_evolution_tutorial.ipynb (1.3 MB)
Level: Intermediate
Topics: Global optimization, adaptive jDE, 5 DE strategies
Use Cases: Non-convex optimization, hyperparameter tuning
4. Optimal Control - 03_optimal_control_tutorial.ipynb (487 KB)
Level: Advanced
Topics: HJB equations, regime-switching, jump diffusion
Use Cases: Algorithmic trading, portfolio optimization
5. Kalman Filter Sensor Fusion - 04_kalman_filter_sensor_fusion.ipynb (1.2 MB)
Level: Intermediate Topics: State estimation, sensor fusion, microstructure noise
Use Cases: High-frequency trading, signal processing
6. Real-World Applications - 04_real_world_applications.ipynb (1.1 MB)
Level: Intermediate
Topics: Portfolio optimization, regime detection, crypto markets
Use Cases: Quantitative finance, risk management
📚 Advanced Research Tutorials (2/8)
These notebooks demonstrate cutting-edge algorithms but may encounter numerical challenges:
7. Performance Benchmarks - 05_performance_benchmarks.ipynb (33 KB)
Status: ⚠️ Kernel crashes during heavy benchmarking
Cause: Memory limits with large-scale HMM benchmarking (50k+ observations)
Note: Demonstrates 50-100× speedup comparisons, partial execution available
8. Mean Field Games - mean_field_games_tutorial.ipynb (690 KB)
Status: ⚠️ Python implementation has numerical instability
Cause: Explicit finite difference scheme on coarse grid (known MFG challenge)
Note: Demonstrates Rust implementation's superior stability over pure Python
🚀 Getting Started
Prerequisites
# Install OptimizR
pip install optimizr
# Additional dependencies for notebooks
pip install jupyter matplotlib seaborn pandas sklearn
Running Notebooks
# Start Jupyter
cd examples/notebooks
jupyter notebook
# Or use JupyterLab
jupyter lab
With Docker
# From repository root
docker-compose up dev
# Access at http://localhost:8888
📊 What You'll Learn
- Optimization: Global optimization with differential evolution (jDE, multiple strategies)
- Statistical Inference: MCMC sampling, Bayesian parameter estimation
- Time Series: HMM regime detection, Kalman filtering, state estimation
- Control Theory: Optimal control, HJB equations, regime-switching models
- Mean Field Games: Population dynamics, agent modeling (advanced)
- Performance: Rust vs Python benchmarking, 50-100× speedup demonstrations
🎯 Tutorial Progression
Recommended Order for Beginners:
- Start with
01_hmm_tutorial.ipynb(regime detection) - Try
03_differential_evolution_tutorial.ipynb(optimization basics) - Explore
04_real_world_applications.ipynb(practical finance examples) - Advanced:
02_mcmc_tutorial.ipynb(Bayesian inference) - Expert:
03_optimal_control_tutorial.ipynb(HJB/control theory)
📈 Performance Highlights
From the tutorials, you'll see:
- HMM: 20-50× faster than hmmlearn (Python/Cython)
- MCMC: 10-30× faster than pure Python implementations
- Differential Evolution: 5-10× faster than scipy.optimize
- Memory: 90-95% reduction vs NumPy for large-scale problems
🐛 Known Issues
-
Performance Benchmarks - Heavy benchmarking (>50k observations) may exhaust kernel memory. Reduce sample sizes if needed.
-
Mean Field Games - Python PDE solver has numerical instability on coarse grids (academic research limitation, not a bug). Rust implementation demonstrates superior stability.
💡 Tips
- Memory: Clear notebook outputs before committing (
Cell > All Output > Clear) - Performance: Use
%timeitfor micro-benchmarks,time.perf_counter()for larger tests - Reproducibility: Set random seeds (
np.random.seed(42)) for consistent results - Visualization: All plots use seaborn styling for publication-quality figures
🤝 Contributing
Found an issue or want to add a tutorial? See CONTRIBUTING.md
📚 Documentation
Full API documentation: https://optimiz-r.readthedocs.io
📄 License
MIT License - see LICENSE for details
Last Updated: v1.0.0 (February 2026)
Tutorial Success Rate: 75% (6/8 fully functional)
Required Python: 3.8+
Required Rust: 1.70+ (for building from source)