ThotDjehuty
0a349f7391
Notebooks 07 (topology), 08 (volterra), 10 (bsde) and 14 (mckean_vlasov)
now follow the same pedagogical template as the optimal-control tutorial:
- Theorem / proof markdown PRE-cells stating the equation pivot, with
derivations inspired by the latex coursework on path integrals,
Volterra-Malliavin and math-physics-finance lectures.
- Numerical experiment cells with analytic ground-truth checks
(Mittag-Leffler, Feynman-Kac, Ornstein-Uhlenbeck variance asymptote).
- Markdown POST-cells stating the expected result, how to read each
figure, and the conclusion linking back to the API.
- Concrete real-world applications:
* 07 topology -> physics: persistent H1 detects the hole of a thin
annulus vs a filled disk.
* 08 volterra -> sub-diffusion fractional Fokker-Planck moments.
* 10 bsde -> heat equation expectation as a linear BSDE.
* 14 mckean_vlasov -> opinion dynamics on a population.
All cells executed end-to-end with the rhftlab kernel; outputs (figures,
prints, ground-truth errors) are embedded as proof of work.
Includes the deterministic builder script _build_enriched_v2.py used to
regenerate the four notebooks.
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)