11 Commits

Author SHA1 Message Date
ThotDjehuty 49be6c7bf7 docs(diagrams): add 4 remaining SVG figures for §8 HMM + §10 geometry
- fig_hmm_regime: 3-state Bull/Neutral/Bear HMM state machine + emission table
- fig_viterbi_trellis: Viterbi trellis K=3 T=4 with MAP path highlighted
- fig_std_vs_nat_gradient: standard vs natural gradient property comparison panels
- fig_lie_group_hierarchy: GL/SL/O/SO/Sp/H Lie group tree with finance annotations

All 27 SVGs regenerated; mathematical_foundations.md now 0 remaining ASCII blocks.
_fix_diagrams3.py added for reproducibility.
2026-03-07 13:39:43 +01:00
ThotDjehuty 5d06f0ab57 docs: replace all ASCII/Unicode diagram blocks with matplotlib SVG figures
Replace 23 ASCII/Unicode text diagram code-blocks in mathematical_foundations.md
with professionally rendered matplotlib SVG figures.

Changes:
- Add docs/source/_gen_diagrams.py: Python script generating all 23 SVG figures
  with consistent styling (white bg, blue/orange/green/red palette, scipy/numpy/
  matplotlib Agg backend)
- Add docs/source/_static/diagrams/*.svg: 23 rendered SVG figures covering:
  §1 DE/random-walk/BM/GBM, §2 Ito/Picard/FP/EM/OU, §3 Poisson/Merton/Levy,
  §6 Kalman, §7 MCMC, §9 KL/Fisher, §10 curvatures/natural-gradient
- Update mathematical_foundations.md: all ASCII art code-blocks replaced with
  MyST {figure} directives pointing to the generated SVGs
- Sphinx build: clean success, all 23 SVGs copied to build, 1 pre-existing warning

Resolves: user request for professional publication-quality figures instead of
  ASCII/Unicode art (which was too low-level for publication)
2026-03-07 11:29:14 +01:00
ThotDjehuty e80d717aa7 docs: upgrade all ASCII diagrams to Unicode box-drawing art
Replace ~20 ASCII diagrams across §1–§10 with polished Unicode art:
- Proper axes: ╰──→ ▲ ╌ with tick marks and labels
- Curves: ╭─╮ ╰─╯ ╲ ╱ for smooth paths and bells
- Steps: ─── ┐ └ for Poisson staircase
- Fills: ▓ ░ · ◦ ● for density and scatter plots
- Tables: ┌┬─┤├┼┘ Unicode box drawing for HMM state machine
- Remove duplicate BM fan + GBM diagrams (were repeated verbatim)
- Consistent 44-char width, title banners with ┄ separators
2026-03-07 10:38:38 +01:00
ThotDjehuty d24b8b1036 docs: enrich mathematical_foundations SDE sections + transparent logo 2026-03-07 09:44:08 +01:00
ThotDjehuty b41618c627 docs(theory): enrich Section 4 optimal control with 4 worked examples
- Add HJB/PMP/HJBI comparison overview table
- Add Merton 1969 portfolio allocation example (log-utility, constant fraction)
- Add Almgren-Chriss inventory liquidation example (LQR + TWAP-like schedule)
- Add PMP costate derivation for Merton problem
- Add American option as viscosity example (variational inequality, smooth-pasting)
- Explain jump integral term intuition in HJBI
- Add shooting method pseudocode for PMP
- Mirror all enrichments in LaTeX .tex source
- Regenerate PDF (13 pages, cross-refs resolved)
2026-03-06 20:22:35 +01:00
ThotDjehuty 7a964fd9ee fix(docs): convert mathematical_foundations.md to correct MyST Markdown syntax
Replace all RST directives with MyST equivalents so equations and
admonitions render correctly on ReadTheDocs:

- :math:`...` inline roles -> $...$ (dollarmath extension)
- .. math:: blocks -> $$...$$ display math
- .. admonition:: -> ::::{admonition} ... :::: colon-fence blocks
- .. list-table:: -> standard Markdown pipe tables
- ``code`` -> `code` backticks
- double-colon code blocks -> fenced ``` blocks

Build: clean (no new warnings).
2026-03-06 19:31:04 +01:00
ThotDjehuty 48220de0ce docs(theory): enrich mathematical foundations with 10 sections
Sections added/expanded:
- DE: operator table, jDE self-adaptive rules, convergence theorem
- Stochastic Processes: 4-axiom BM, Ito calculus+lemma, SDE table, OU MLE
- Jump Processes: Poisson, Merton formula, Levy-Khintchine theorem+table, SDE generator
- Optimal Control: HJB boxed PDE, LQR Riccati, PMP costate theorem, HJBI jumps, viscosity solutions
- Mean Field Games: HJB+KFP system, fixed-point pseudocode, Lasry-Lions convergence
- Kalman Filtering: predict/update recursion, KL-minimization view, Kalman-Bucy Riccati
- MCMC: MH accept-reject, optimal step h~2.38/sqrt(d), MALA+Langevin SDE
- HMM: full Baum-Welch E/M (alpha/beta/gamma/xi), Viterbi max-product
- Information Theory: Shannon entropy, KL+Gibbs, Fisher info+Cramer-Rao, mRMR, natural gradient preview
- Differential Geometry: Riemannian manifold+geodesic+Christoffel, Fisher-Rao metric,
  Amari natural gradient, dually-flat exp families, Lie groups, symplectic geometry+PMP, sectional curvature
- Quick Reference table (15 rows), 11 full references
- Sphinx build clean (1 unrelated chardet warning only)
2026-03-06 19:14:43 +01:00
ThotDjehuty b10263b4f2 docs: Rebrand OptimizR to Optimiz-rs throughout documentation
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).
2026-02-17 10:09:15 +01:00
Melvin Alvarez 7a9ab20b89 docs: add mfg tutorial and enrich theory 2026-02-09 17:27:35 +01:00
Melvin Alvarez 6e3367c396 docs: deepen theory and benchmarks 2026-02-09 17:09:27 +01:00
Melvin Alvarez 43af949904 docs(optimizr): add logo and fix rtd deps 2026-02-09 16:15:41 +01:00