diff --git a/docs/source/algorithms/grid_search.md b/docs/source/algorithms/grid_search.md index 8c8b768..e9985b3 100644 --- a/docs/source/algorithms/grid_search.md +++ b/docs/source/algorithms/grid_search.md @@ -306,6 +306,20 @@ plt.title('Grid Search: Loss Surface') plt.savefig('grid_search_heatmap.png', dpi=150) ``` +**Output:** + +Produces a 2D heatmap showing the loss landscape across different hyperparameter combinations: +- **X-axis**: Dropout rate values +- **Y-axis**: Learning rate values +- **Color intensity**: Loss values (darker = lower loss = better performance) + +This visualization helps identify optimal parameter regions and understand parameter interactions. + +📓 **Real-World Examples**: See [04_real_world_applications.ipynb](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/04_real_world_applications.ipynb) for grid search applied to: +- Neural network hyperparameter tuning +- Portfolio optimization +- Trading strategy parameter selection + --- ## Combining with Other Methods diff --git a/docs/source/algorithms/hmm.md b/docs/source/algorithms/hmm.md index 9a18c38..91ba6de 100644 --- a/docs/source/algorithms/hmm.md +++ b/docs/source/algorithms/hmm.md @@ -448,6 +448,14 @@ plt.tight_layout() plt.savefig('hmm_states.png', dpi=150) ``` +**Output:** + +This visualization creates a two-panel plot: +- **Top panel**: Returns time series showing price movements +- **Bottom panel**: Decoded state sequence highlighting regime transitions (e.g., Bull/Bear markets) + +For complete examples with regime detection on real market data, see the [HMM Tutorial notebook](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/01_hmm_tutorial.ipynb). + ### Transition Diagram ```python @@ -469,6 +477,19 @@ plt.title('HMM Transition Diagram') plt.savefig('hmm_transitions.png', dpi=150) ``` +**Output:** + +Generates a directed graph visualization showing: +- **Nodes**: Hidden states (e.g., State 0, State 1) +- **Edges**: Transition probabilities between states (labeled with probability values) +- Only transitions with probability > 0.01 are shown for clarity + +📓 **Full Tutorial**: Explore [01_hmm_tutorial.ipynb](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/01_hmm_tutorial.ipynb) for hands-on examples including: +- Multi-state regime detection +- Volatility clustering analysis +- Mean-reversion regime identification +- Viterbi decoding in financial time series + --- ## Applications diff --git a/docs/source/algorithms/mean_field_games.md b/docs/source/algorithms/mean_field_games.md index 2f30132..d90c869 100644 --- a/docs/source/algorithms/mean_field_games.md +++ b/docs/source/algorithms/mean_field_games.md @@ -237,6 +237,14 @@ plt.tight_layout() plt.savefig('mfg_heatmaps.png', dpi=150) ``` +**Output:** + +This code generates two side-by-side heatmaps: +- **Left plot**: Population density `m(x,t)` evolution over space and time +- **Right plot**: Value function `u(x,t)` showing optimal value at each position and time + +For interactive visualization with complete outputs, see the [Mean Field Games Tutorial notebook](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb) on GitHub. + ### Time Slices ```python @@ -256,6 +264,12 @@ plt.grid(True, alpha=0.3) plt.savefig('mfg_time_slices.png', dpi=150) ``` +**Output:** + +This produces a line plot showing population density profiles at 5 different time points (t=0.0, 0.25, 0.5, 0.75, 1.0), illustrating how the population distribution evolves from initial to terminal conditions. + +📓 **Complete Examples**: See the [Mean Field Games Tutorial](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb) for interactive visualizations with real numerical solutions. + --- ## Performance @@ -351,7 +365,7 @@ Good choices for `m0`: ## Notebook Tutorial For a complete walkthrough with validated outputs and visualizations, see the -Mean Field Games Tutorial notebook at `examples/notebooks/mean_field_games_tutorial.ipynb`. +[Mean Field Games Tutorial notebook](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb) on GitHub. The notebook demonstrates: @@ -361,4 +375,4 @@ The notebook demonstrates: - Interpreting convergence diagnostics - Comparing congestion levels -Audit documentation is available at `docs/MFG_TUTORIAL_COMPLETE.md`. +Audit documentation is available at [`docs/MFG_TUTORIAL_COMPLETE.md`](https://github.com/ThotDjehuty/optimiz-r/blob/main/docs/MFG_TUTORIAL_COMPLETE.md). diff --git a/docs/source/api/optimal_control.md b/docs/source/api/optimal_control.md index 534d5ed..cb1e772 100644 --- a/docs/source/api/optimal_control.md +++ b/docs/source/api/optimal_control.md @@ -114,4 +114,4 @@ log_likelihoods = result.get_log_likelihoods() **Conceptual picture:** Kalman filtering = prediction (dynamics prior) + correction (measurement residual). EKF linearizes $f, h$; UKF propagates sigma points for better nonlinear fidelity. RTS smoothing runs backward in time to refine all past states. -See `examples/notebooks/03_optimal_control_tutorial.ipynb` for end-to-end usage combining HJB thresholds, OU estimation, and filtering. +See [`examples/notebooks/03_optimal_control_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/03_optimal_control_tutorial.ipynb) for end-to-end usage combining HJB thresholds, OU estimation, and filtering. diff --git a/docs/source/benchmarks.md b/docs/source/benchmarks.md index 8f2e541..9afe105 100644 --- a/docs/source/benchmarks.md +++ b/docs/source/benchmarks.md @@ -11,8 +11,8 @@ These results come from the Rust backends (release build) versus SciPy’s `diff **How to reproduce** -- Run `examples/notebooks/05_performance_benchmarks.ipynb` (validated in CI) to regenerate figures and raw CSV metrics. -- Or from the repo root, run `make benchmark` for the Rust-side microbenchmarks (no Python overhead). +- Run [`examples/notebooks/05_performance_benchmarks.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/05_performance_benchmarks.ipynb) (validated in CI) to regenerate figures and raw CSV metrics. +- Or from the [repo root](https://github.com/ThotDjehuty/optimiz-r), run `make benchmark` for the Rust-side microbenchmarks (no Python overhead). - To compare against SciPy, set `SCIPY_BASELINE=1` in the notebook; it records wall-clock times and success percentages side by side. **What the notebook plots** diff --git a/docs/source/examples.md b/docs/source/examples.md index 601b14d..0dff798 100644 --- a/docs/source/examples.md +++ b/docs/source/examples.md @@ -108,15 +108,17 @@ print("Half-life:", estimate_half_life_py(returns)) ## Notebooks -- Differential Evolution: `examples/notebooks/03_differential_evolution_tutorial.ipynb` -- Mean Field Games: `examples/notebooks/mean_field_games_tutorial.ipynb` -- HMM: `examples/notebooks/01_hmm_tutorial.ipynb` -- MCMC: `examples/notebooks/02_mcmc_tutorial.ipynb` -- Optimal Control & Kalman: `examples/notebooks/03_optimal_control_tutorial.ipynb` -- Performance benchmarks: `examples/notebooks/05_performance_benchmarks.ipynb` +Explore interactive tutorials on GitHub: + +- **Differential Evolution**: [`03_differential_evolution_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/03_differential_evolution_tutorial.ipynb) +- **Mean Field Games**: [`mean_field_games_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb) +- **HMM**: [`01_hmm_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/01_hmm_tutorial.ipynb) +- **MCMC**: [`02_mcmc_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/02_mcmc_tutorial.ipynb) +- **Optimal Control & Kalman**: [`03_optimal_control_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/03_optimal_control_tutorial.ipynb) +- **Performance Benchmarks**: [`05_performance_benchmarks.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/05_performance_benchmarks.ipynb) ## Contribute Examples -1. Fork the repository and add notebooks under `examples/notebooks/` +1. Fork the [repository](https://github.com/ThotDjehuty/optimiz-r) and add notebooks under `examples/notebooks/` 2. Keep dependencies minimal (NumPy/Matplotlib preferred) 3. Ensure the notebook runs end-to-end before submitting a PR diff --git a/docs/source/mfg_tutorial.md b/docs/source/mfg_tutorial.md index 7b8bdc1..40c31a8 100644 --- a/docs/source/mfg_tutorial.md +++ b/docs/source/mfg_tutorial.md @@ -1,6 +1,6 @@ # Mean Field Games Tutorial (Production) -This page summarizes the full MFG tutorial notebook (`examples/notebooks/mean_field_games_tutorial.ipynb`) and the accompanying audit in `docs/MFG_TUTORIAL_COMPLETE.md`. +This page summarizes the full MFG tutorial notebook ([`mean_field_games_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb)) and the accompanying audit in [`docs/MFG_TUTORIAL_COMPLETE.md`](https://github.com/ThotDjehuty/optimiz-r/blob/main/docs/MFG_TUTORIAL_COMPLETE.md). ## What the notebook demonstrates