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.
RST does not parse dollar-math (the dollarmath MyST extension applies
only to .md files), so every inline LaTeX expression was rendered as
raw text on Read the Docs — with backslashes silently stripped by the
RST escape mechanism (e.g. \bar s shown as 'bar s', \mathbb{E} shown
as 'mathbb{E}'). The eight v2.0 algorithm pages now use the proper
:math: role for inline math (224 expressions converted), so MathJax
renders every symbol correctly.
Affected pages: bsde, pde, stochastic_control, quadratic_impact_control,
mckean_vlasov, agent_based, robust_drift, generative_calibration_hooks.
Each of the eight v2.0 algorithm pages (bsde, pde, stochastic_control,
quadratic_impact_control, mckean_vlasov, agent_based, robust_drift,
generative_calibration_hooks) gains:
- A dedicated 'Mathematical background' section with the central theorem
(Pardoux-Peng, Sznitman propagation of chaos, Pontryagin-Bismut,
Huber-IRLS, Gretton MMD, Kolmogorov forward, etc.), key derivations
and the analytic closed-form solution that the unit tests target.
- An 'Applications' / 'Why it matters' paragraph listing concrete
research and engineering use-cases so newcomers grasp the value of
each primitive.
- A repaired companion-notebook block: the broken relative path
'../../examples/notebooks/...ipynb' (which 404s on RTD) is replaced
by an explicit GitHub blob (view) + raw (download) URL pair.
Sphinx now builds the full doc set with zero new warnings.
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.
RTD builds were failing because openblas-build 0.10.16 (transitively pulled by
ndarray-linalg via openblas-src) requires ureq tls feature flags it does not
enable. Cargo.lock is gitignored so RTD always resolves fresh and hits the
broken upstream version.
Building the Rust extension on RTD is unnecessary: the Sphinx pages do not
use autodoc against the Python module, and all inline plots under doc samples
are pre-rendered PNGs committed to docs/source/_static/auto/ by the local
scripts/inject_doc_plots.py author-time pipeline.
This commit makes the RTD job render-only: install docs/requirements.txt and
run Sphinx. No Rust toolchain, no maturin, no OpenBLAS.
Add scripts/inject_doc_plots.py that scans every .md and .rst page under
docs/source/, executes each Python code-block in an isolated namespace
with a non-interactive matplotlib backend, captures every figure
produced, and inserts an inline image directive immediately after the
code-block. Markers AUTO-PLOT-BEGIN/END make the injection idempotent
on re-runs. Blocks that fail to execute or produce no figure are left
untouched.
Add a transparent __getattr__ fallback in python/optimizr/__init__.py
that forwards any unresolved top-level attribute to the compiled _core
extension. This lets all v1.x and v2.0 doc samples that use
'from optimizr import X' (estimate_ou_params_py, linear_bsde_constant_coeffs,
mmd_gaussian, ...) execute as written.
Augment the OU Parameter Estimation example
(docs/source/algorithms/optimal_control.md) with a two-panel
visualization (simulated path plus empirical/theoretical autocorrelation).
Net effect: 14 doc pages now display matplotlib plots inline directly
under the code that produced them -- including the OU page, point
processes, Grid Search, HMM, MCMC, plus the 8 v2.0 RST pages.
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.
Optimal Control: 94 to 610 lines with HJB theory, viscosity solutions, finite differences
HMM API: 16 to 571 lines with complete API reference and usage examples
- Identifies critical gaps in optimal control mathematical foundations
- Details needed HMM API expansion (currently only 16 lines)
- Lists all implemented algorithms requiring documentation
- Provides phased implementation plan with priorities
- References academic sources for mathematical content
User feedback: 'make it a lot more concise and detailed' + needs HJB equation theory, viscosity solutions, algorithm details
- Replace all OptimizR references with Optimiz-rs in README
- Fix logo URL to use GitHub raw link (displays on PyPI)
- Bump version to 1.0.1 for metadata update
- Published to PyPI: https://pypi.org/project/optimiz-rs/1.0.1/
Changes:
- README.md: 7 instances of OptimizR → Optimiz-rs
- README.md: Logo URL now uses raw.githubusercontent.com
- pyproject.toml: version 1.0.0 → 1.0.1
- Cargo.toml: version 1.0.0 → 1.0.1
Updated Branding in ReadTheDocs:
- ✅ All 'OptimizR' → 'Optimiz-rs' (17 files)
- ✅ Project name in conf.py
- ✅ HTML title and short title
- ✅ All algorithm documentation
- ✅ Getting started guide
- ✅ Installation guide
- ✅ Theory/mathematical foundations
- ✅ Archive documentation
Documentation now consistently uses the new 'optimiz-rs' branding that
matches both PyPI and crates.io package names.
Note: Python module name 'optimizr' in import statements intentionally
unchanged (that's the actual module name).
- Updated Cargo.toml: name = 'optimiz-rs'
- Maintains lib name as 'optimizr' for code compatibility
- Achieves naming consistency with PyPI (optimiz-rs)
Both registries now use the same base name:
- crates.io: optimiz-rs
- PyPI: optimiz-rs
Logo Updates:
- ✅ New logo: logo_optimizrs.png (1024x1536 PNG)
- ✅ README.md: Updated logo reference
- ✅ docs/source/conf.py: Updated html_logo and html_favicon
- ✅ Removed old logos: logo_optimizr_valid.png, logo_optimizr_valid.jpeg
- ✅ Copied from: business/logo/logo_optimizrs.png
The logo now reflects the new optimiz-rs package name across:
- GitHub README
- ReadTheDocs documentation
- Sphinx HTML output
- favicon
All documentation will automatically use the updated branding.
Publication Details:
- ✅ Package name: optimiz-rs (cleaner than optimizr-rs)
- ✅ PyPI URL: https://pypi.org/project/optimiz-rs/1.0.0/
- ✅ Installation tested: pip install optimiz-rs works perfectly
- ✅ Functionality verified: imports and DE algorithm working
Updated Documentation:
- README.md: Updated installation instructions
- RELEASE_NOTES_v1.0.0.md: Removed '(publishing in progress)'
- FINAL_RELEASE_STATUS.md: Updated to 100% complete status
Both Registries Now Live:
- crates.io: https://crates.io/crates/optimizr
- PyPI: https://pypi.org/project/optimiz-rs/
v1.0.0 is now 100% published and ready for the world! 🚀
- Shorter, cleaner package name
- Updated pyproject.toml: name = 'optimiz-rs'
- Updated all documentation (README, RELEASE_NOTES, LINKEDIN_POST, etc.)
- Rebuilt wheel: optimiz_rs-1.0.0-cp38-abi3-macosx_10_12_x86_64.whl
- Tested: Python import and DE algorithm working correctly
Package verified and ready for PyPI publication.
crates.io:
- Successfully published optimizr v1.0.0
- Available at: https://crates.io/crates/optimizr
PyPI Preparation:
- Renamed package to optimizr-rs (avoid name conflict)
- Updated pyproject.toml with new name
- Built wheel: optimizr_rs-1.0.0-cp38-abi3-macosx_10_12_x86_64.whl
- Ready for upload (need API token)
Documentation Updates:
- Updated RELEASE_NOTES with crates.io link
- Updated README.md installation instructions
- Updated LINKEDIN_POST.md with correct package names
- Created PYPI_PUBLISHING.md with token instructions
Next: Get PyPI API token and run twine upload
Details publication blockers:
- crates.io: Email verification required
- PyPI: Package name conflict (optimizr already exists at v1.4.7)
Recommendations:
- Use optimizr-rs for PyPI (clear Rust variant naming)
- Verify email at crates.io/settings/profile
Current status: 99% ready, just need user actions
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.
- Step-by-step crates.io setup and publication
- Step-by-step PyPI setup and publication
- GitHub Actions automation template
- Post-publication checklist
- Marketing & announcement strategy
- Success metrics and tracking
- Known issues and limitations
Guide includes all commands needed to complete publication
after credentials are configured.
- First stable release announcement
- Complete feature list and performance benchmarks
- Breaking changes documentation
- Migration guide from v0.3.0
- Roadmap for v1.1.0, v1.2.0, v2.0.0
- Publication details for crates.io and PyPI
- Add python-bindings feature to maturin build configuration
- Ensures PyO3 extension module is built correctly for PyPI
- Fixes PyInit__core symbol warning during wheel build
This is required because we removed python-bindings from default features
to fix cargo publish linking issues. Maturin now explicitly enables it.
ThotDjehuty