docs: Add comprehensive documentation improvement roadmap

- 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
2026-02-17 19:59:56 +01:00
parent 78442d9e69
commit 5f0c8b0d67
1 changed files with 226 additions and 0 deletions
@@ -0,0 +1,226 @@
 # Documentation Improvements Needed
 **Date:** 2026-02-17  
 **Version:** v1.0.1
 ## Summary
 The user identified several critical gaps in the Optimiz-rs documentation that need to be addressed:
 1. **Optimal Control Page (`docs/source/algorithms/optimal_control.md`)**
   - Needs much more detail on HJB equations
   - Needs explanation of viscosity solutions
   - Needs to introduce what's actually in the code/module
   - Needs more mathematical foundations
 2. **HMM API Page (`docs/source/api/hmm.md`)**
   - Currently almost empty (only ~16 lines)
   - Needs explanation of what algorithms are implemented
   - Needs details on how they work  
   - Needs guidance on when/how to use them
 3. **General Documentation**
   - Make more concise and detailed throughout
   - Better balance of theory and practice
 ## Required Enhancements
 ### 1. Optimal Control Documentation
 #### Mathematical Foundations Needed:
 - **HJB Equation:** Full derivation and intuition
  - General form for stochastic processes
  - Specialization to Ornstein-Uhlenbeck process
  - Connection to optimal stopping/switching problems
 - **Viscosity Solutions:** Detailed explanation
  - Why classical solutions don't exist (kinks at boundaries)
  - Definition of viscosity solutions
  - Numerical approximation via upwind schemes
  - Monotonicity and convergence properties
 - **Finite Difference Methods:**
  - Grid discretization approach
  - Upwind vs central differences
  - Policy iteration algorithm
  - Convergence criteria
 #### Implementation Details Needed:
 - **What's Actually in the Module:**
  - HJB solver for OU process (src/optimal_control/hjb_solver.rs)
  - Viscosity solution solver (src/optimal_control/viscosity.rs)
  - Regime switching (src/optimal_control/regime_switching.rs)
  - Jump diffusion (src/optimal_control/jump_diffusion.rs)
  - MRSJD - Multi-Regime Switching Jump Diffusion (src/optimal_control/mrsjd.rs)
  - OU parameter estimation (src/optimal_control/ou_estimator.rs)
  - Kalman filters: Linear, EKF, UKF (src/optimal_control/kalman_filter.rs)
  - Backtesting framework (src/optimal_control/backtest.rs)
 #### Usage Guidance Needed:
 - When to use each algorithm
 - Parameter tuning guidelines
 - Diagnostic plots and convergence monitoring
 - Integration with other modules (HMM, Mean Field Games)
 - Real-world trading examples
 ### 2. HMM API Documentation
 #### Algorithms to Document:
 - **Forward Algorithm:** Compute P(O|λ) efficiently
  - Forward variable α_t(i)
  - Recursive computation
  - Numerical stability (scaling)
 - **Backward Algorithm:** Alternative for completeness
  - Backward variable β_t(i)
  - Use in Baum-Welch
 - **Viterbi Algorithm:** Most likely state sequence
  - Dynamic programming approach
  - Backtracking for path recovery
 - **Baum-Welch (EM) Algorithm:** Parameter learning
  - E-step: compute γ_t(i) and ξ_t(i,j)
  - M-step: update π, A, B parameters
  - Convergence properties
 #### API Methods to Explain:
 - **`HMM(n_states)`:** Constructor
  - When to use 2 vs 3+ states
  - Initialization strategy
 - **`fit(X, n_iterations, tolerance)`:** Training
  - What data X should look like
  - How many iterations needed
  - Convergence diagnostics
  - Multiple random restarts
 - **`predict(X)`:** Viterbi decoding
  - Returns most likely state sequence
  - Use cases: regime detection, trading signals
 - **`score(X)`:** Log-likelihood
  - Model comparison
  - Convergence monitoring
  - Anomaly detection
 #### Usage Examples Needed:
 - **Regime Detection:**
  - Market regimes (bull/bear)
  - Volatility regimes (high/low)
  - Integration with optimal control
 - **Parameter Estimation Per Regime:**
  - Combine with OU parameter estimation
  - Regime-specific HJB solving
 - **Model Selection:**
  - BIC/AIC for choosing number of states
  - Cross-validation approaches
 - **Numerical Best Practices:**
  - Data requirements (minimum samples)
  - Handling outliers
  - Initialization sensitivity
  - Convergence diagnostics
 ### 3. API Reference Page (`docs/source/api/optimal_control.md`)
 Currently 117 lines but needs:
 - Complete function signatures
 - Parameter descriptions with types
 - Return value specifications
 - Detailed examples for each function
 - Error handling documentation
 ## Implementation Plan
 ### Phase 1: Mathematical Foundations (High Priority)
 1. Expand optimal_control.md with HJB equation derivations
 2. Add viscosity solutions section with theory and numerics
 3. Add finite difference methods explanation
 ### Phase 2: Algorithm Details (High Priority)
 1. HMM API documentation expansion
 2. Detail each algorithm (forward, backward, Viterbi, Baum-Welch)
 3. Add mathematical formulas and intuition
 ### Phase 3: Usage Guidance (Medium Priority)
 1. Add "When to Use" sections for each algorithm
 2. Parameter tuning guidelines
 3. Diagnostic procedures
 4. Integration examples
 ### Phase 4: API Reference (Medium Priority)
 1. Complete function signatures
 2. Parameter and return types
 3. Error documentation
 4. Cross-references
 ### Phase 5: Examples and Tutorials (Low Priority)
 1. Jupyter notebooks for common use cases
 2. End-to-end workflows
 3. Performance benchmarking examples
 ## Technical Notes
 ### Current Implementation Status:
 **Optimal Control Module (`src/optimal_control/`):**
 - ✅ HJB solver (hjb_solver.rs)
 - ✅ Viscosity solutions (viscosity.rs)
 -  ✅ Regime switching (regime_switching.rs)
 - ✅ Jump diffusion (jump_diffusion.rs)
 - ✅ MRSJD (mrsjd.rs)
 - ✅ OU estimation (ou_estimator.rs)
 - ✅ Kalman filters (kalman_filter.rs, kalman_py_bindings.rs)
 - ✅ Backtesting (backtest.rs)
 **HMM Module (`src/hmm/`):**
 - ✅ Gaussian emissions (emission.rs)
 - ✅ Forward-Backward algorithm (model.rs)
 - ✅ Viterbi decoding (viterbi.rs)
 - ✅ Baum-Welch training (model.rs)
 - ✅ Python bindings (python_bindings.rs)
 ### Documentation Files to Update:
 1. `docs/source/algorithms/optimal_control.md` (currently 94 lines → target: 500+ lines)
 2. `docs/source/api/hmm.md` (currently 16 lines → target: 300+ lines)
 3. `docs/source/api/optimal_control.md` (currently 117 lines → target: 400+ lines)  
 4. `docs/source/algorithms/hmm.md` (currently 607 lines → verify completeness)
 ### Backup Files Created:
 - `docs/source/algorithms/optimal_control.md.backup`
 - `docs/source/api/hmm.md.backup`
 - `docs/source/api/optimal_control.md.backup`
 ## Next Steps
 1. **Immediate:** Write comprehensive optimal_control mathematical foundations
 2. **Immediate:** Expand HMM API documentation with algorithm details
 3. **Soon:** Add usage examples and integration guides
 4. **Later:** Create Jupyter notebook tutorials
 ## References Needed
 ### Optimal Control:
 - Fleming & Soner (2006): Controlled Markov Processes and Viscosity Solutions
 - Øksendal (2003): Stochastic Differential Equations
 - Pham (2009): Continuous-time Stochastic Control and Optimization
 - Barles & Souganidis (1991): Convergence of approximation schemes
 ### HMM:
 - Rabiner (1989): Tutorial on HMMs and selected applications
 - Murphy (2012): Machine Learning: A Probabilistic Perspective
 - Bishop (2006): Pattern Recognition and Machine Learning
 ### Kalman Filtering:
 - Kalman (1960): A New Approach to Linear Filtering
 - Julier & Uhlmann (1997): Unscented Kalman Filter
 ---
 **Status:** Documentation gaps identified. Implementation in progress.
 **Priority:** High - These are critical for user onboarding and proper usage.