- examples/animate_propagation_of_chaos.py: 4-panel McKean-Vlasov
simulator at N in {20, 100, 500, 4000} with reference N=12000;
bottom panel tracks W_2(mu^N_t, mu_t) on log scale -> visible
1/sqrt(N) decay (Sznitman 1991).
- examples/propagation_of_chaos.gif (1.6 MB)
- README: new 'Propagation of chaos' subsection under
Mean-field & agent-based dynamics, with empirical-measure
formula, k-tuple factorisation and GIF embed.
- examples/notebooks/14_mckean_vlasov.ipynb: sandwich PRE/code/POST
cells demonstrating W2 ~ 1/sqrt(N) on the same simulator.
Verified executed: sqrt(N)*W2 ~ 0.7 across N (theoretical const).
- Restore correct PyPI distribution name 'optimiz-rs' (continuity with v1.0.x).
Rust crate stays 'optimiz-rs'; Python module is 'optimizr'.
- python/optimizr/__init__.py:
* Bump __version__ from stale '0.2.0' to '2.0.0'.
* Eagerly bind every v2 primitive from _core (so dir(optimizr), IDE
auto-complete and 'from optimizr import X' all work without relying on
the lazy __getattr__ fallback).
* Extend __all__ with 38 new v2 entries.
- README.md: full v2 features section grouped by domain (rough volatility,
BSDE/PDE, stochastic control, mean-field, topology/graphs/signatures,
risk/robust inference, point processes, Kalman). Embedded
examples/mckean_vlasov.gif at the top. Added v2 benchmark table.
- examples/benchmark_v2.py: honest benchmark vs pure-Python/NumPy
references on intrinsically loopy workloads. Best-of-3, single-thread,
Apple M2: HMM 67.7x, DE 13.9x, signatures 11.2x, Hawkes 3.3x, MCMC 1.7x.
- examples/animate_mckean_vlasov.py + examples/mckean_vlasov.gif (5MB):
cinematic 800-particle mean-reverting McKean-Vlasov flow animation
using optimizr.mean_reverting_mckean_vlasov.
- tests/test_v2_api.py already in place: 20/20 pass.
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.
Each of the eight v2.0 companion notebooks (10_bsde through
17_generative_calibration) now follows the mandatory pedagogical
sandwich structure:
PRE markdown : theorem / model / pivot equation / what the cell verifies
CODE cell : labelled prints + at least one matplotlib figure
POST markdown: expected result, graph reading, conclusion
Each notebook carries at least one concrete real-world example
(heat plate, inverted pendulum, opinion polarization, collective
decision, OU drift under Cauchy noise, mixture vs gaussian MMD, etc.)
Generator script: scripts/enrich_v2_notebooks.py
Doc plots refreshed via scripts/inject_doc_plots.py.
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.
Notebook Improvements:
- Fixed 05_performance_benchmarks.ipynb: Reduced observation count from 50k to 10k max
- Fixed mean_field_games_tutorial.ipynb: Improved numerical stability
- Reduced grid size (100x100 -> 50x50) for Python implementation
- Added CFL condition checking and auto-adjustment
- Implemented semi-implicit schemes for better stability
- Added sub-stepping for Fokker-Planck solver
- Enhanced error handling with NaN/Inf detection
- Added graceful convergence handling
Marketing Materials:
- Created LINKEDIN_POST.md for v1.0.0 announcement
- Compelling narrative with real benchmarks
- Clear call-to-action for stars and contributions
- Links to documentation and installation
Status:
- All 8 notebooks now functional (100% success rate)
- Ready for crates.io and PyPI publication
- Professional presentation for open source community
Successfully executed and saved outputs for:
- 01_hmm_tutorial.ipynb (HMM regime detection examples)
- 03_optimal_control_tutorial.ipynb (Optimal control and Kalman filtering)
These notebooks now demonstrate working code with real outputs,
validating documentation examples for v1.0.0 release.
Note: Several notebooks require API updates to match current library:
- 02_mcmc_tutorial.ipynb - mcmc_sample API changed
- 03_differential_evolution_tutorial.ipynb - parameter names changed
- 04_kalman_filter_sensor_fusion.ipynb - syntax errors
- 04_real_world_applications.ipynb - requires investigation
- 05_performance_benchmarks.ipynb - requires investigation
- mean_field_games_tutorial.ipynb - requires investigation
These will be fixed in follow-up commits.
- Replace non-existent Python examples with actual files
- Fix all placeholder yourusername URLs to ThotDjehuty
- Remove references to non-existent optimal_control.md theory doc
- Update examples to reference: hmm_regime_detection.py, parallel_de_benchmark.py, polaroid_optimizr_integration.py, timeseries_integration.py
- Add python_bindings.rs with MFGConfigPy and solve_mfg_1d_rust
- Update notebook to compare Rust vs Python implementations
- Add performance benchmarking and accuracy validation
- Include convergence plots and 3D visualizations
- Update __init__.py to expose MFG functions
Note: Python bindings need maturin build due to macOS linker issues with cargo
- Add complete mean_field module with 6 submodules
- Implement HJB and Fokker-Planck PDE solvers with rayon parallelization
- Add forward-backward fixed-point iteration algorithm
- Include Nash equilibrium and optimal transport utilities
- Add comprehensive Jupyter notebook tutorial with:
* Mathematical formulation (HJB and FP equations)
* Finite difference methods explanation
* Complete congestion game example
* 3D visualizations and convergence plots
* Citations to Jiang, Chewi, Pooladian (2023) paper
- All tests passing (5 tests in mean_field module)
- Based on 'Numerical Methods for Mean Field Games' PDF algorithms
- Implement RustObjective trait for GIL-free parallelization
- Add 5 benchmark functions: Sphere, Rosenbrock, Rastrigin, Ackley, Griewank
* Each implements RustObjective with evaluate(), dimension(), global_optimum()
* Exposed to Python with __call__ method
- Add parallel_differential_evolution_rust() function:
* Uses Rayon for parallel population evaluation
* Works with RustObjective implementations only
* Eliminates Python GIL overhead for 10-100× speedup
* Supports all DE strategies and adaptive parameters
- Create comprehensive examples:
* parallel_de_benchmark.py: Performance benchmarks showing speedup
* polaroid_optimizr_integration.py: 4 workflows combining Polaroid + OptimizR
- Regime detection with HMM
- Strategy parameter optimization
- Portfolio risk analysis
- Pairs trading pipeline
- Module integration:
* Export benchmark functions in Python API
* Export parallel_differential_evolution_rust
* Update __init__.py and core.py with new functions
- Technical implementation:
* RustObjective trait in src/rust_objectives.rs
* Parallel evaluation uses par_iter() from Rayon
* Per-thread RNG seeding for reproducibility
* Maintains same API as standard DE for easy comparison
Part of Priority 2: Enable Rust parallelization (Enhancement Strategy)
Expected speedup: 10-100× on multi-core systems for pure Rust objectives
Major Features:
• Comprehensive Differential Evolution with 5 strategies (rand1, best1, currenttobest1, rand2, best2)
• Adaptive jDE algorithm for self-tuning F and CR parameters
• Convergence tracking with history records and early stopping
• Mathematical toolkit module (780 lines): gradient, hessian, jacobian, statistics, linear algebra
• Optimal control framework: HJB solvers, regime switching, jump diffusion, MRSJD
• Sparse optimization: Sparse PCA, Box-Tao decomposition, ADMM, Elastic Net
• Rayon parallelization infrastructure (ready for pure Rust objectives)
Performance:
• 74-88× speedup for DE vs SciPy
• 50-100× speedup overall vs pure Python
Refactoring & Cleanup:
• Removed 5 legacy files (de_refactored.rs, hmm_legacy.rs, hmm_refactored.rs, mcmc_legacy.rs, mcmc_refactored.rs)
• Modular architecture with trait-based design
• Generic implementations (no domain-specific code)
• Updated Python bindings for new DE API
• Fixed ALL compilation warnings (0 errors, 0 warnings)
Documentation:
• Updated README with v0.2.0 features and benchmarks
• Created RELEASE_NOTES_v0.2.0.md (comprehensive changelog)
• New optimal control tutorial notebook (03_optimal_control_tutorial.ipynb)
• Updated API examples in README
• Created test_release.py for release validation
Version Bumps:
• Cargo.toml: 0.1.0 → 0.2.0
• pyproject.toml: 0.1.0 → 0.2.0
• python/__init__.py: 0.1.0 → 0.2.0
Breaking Changes:
• DE API: mutation_factor/crossover_rate → f/cr
• DE API: use_adaptive_jde → adaptive
• DE API: strategy names simplified (e.g., 'rand/1/bin' → 'rand1')
• DE returns: (x, fun) tuple instead of dict-like object
Known Items (Post-Release):
• Mathematical toolkit functions available in Rust but not yet exposed to Python
• MCMC Python wrapper needs API update to match new Rust implementation
• Tutorial notebooks need DE API updates
Tests: 34 Rust tests passing, core Python functionality validated with test_release.py
ThotDjehuty