docs: add ReadTheDocs configuration and Sphinx documentation structure

2026-02-08 17:16:41 +01:00
parent 68fe7fdb8e
commit c1f4c0bde7
14 changed files with 646 additions and 526 deletions
@@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../python'))
+
+# -- Project information -----------------------------------------------------
+project = 'OptimizR'
+copyright = '2026, HFThot Research Lab'
+author = 'HFThot Research Lab'
+release = '0.3.0'
+version = '0.3.0'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'myst_parser',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = 'furo'  # Modern, clean theme
+html_static_path = ['_static']
+html_title = 'OptimizR Documentation'
+html_short_title = 'OptimizR'
+html_logo = None  # Add logo if available
+
+html_theme_options = {
+    "light_css_variables": {
+        "color-brand-primary": "#f97316",
+        "color-brand-content": "#f97316",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#fb923c",
+        "color-brand-content": "#fb923c",
+    },
+}
+
+# Napoleon settings for Google/NumPy docstring parsing
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+# Intersphinx configuration
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+}
+
+# MyST parser configuration for markdown support
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+]
@@ -0,0 +1,152 @@
+# Examples
+
+This page lists all available examples and tutorials for OptimizR.
+
+## Jupyter Notebooks
+
+All notebooks are located in the [examples/](https://github.com/ThotDjehuty/optimiz-r/tree/main/examples) directory.
+
+### 1. Differential Evolution
+
+**File**: `01_differential_evolution_tutorial.ipynb`
+
+Learn how to use the Differential Evolution optimizer:
+- Basic optimization problems (Rosenbrock, Rastrigin, Ackley)
+- Strategy comparison (rand/1, best/1, current-to-best/1)
+- Parameter tuning (F, CR, population size)
+- Convergence analysis and visualization
+
+### 2. Mean Field Games
+
+**File**: `02_mean_field_games_tutorial.ipynb`
+
+Solve 1D Mean Field Games:
+- HJB-Fokker-Planck coupling
+- Agent population dynamics
+- Nash equilibrium computation
+- 3D visualization (time × space × density)
+
+### 3. Hidden Markov Models
+
+**File**: `03_hmm_tutorial.ipynb`
+
+Train and apply HMMs:
+- Baum-Welch training algorithm
+- Viterbi decoding
+- Gaussian emission models
+- Real-world applications (regime detection, speech recognition)
+
+### 4. MCMC Sampling
+
+**File**: `04_mcmc_tutorial.ipynb`
+
+Bayesian inference with Metropolis-Hastings:
+- Sampling from complex distributions
+- Adaptive proposal tuning
+- Convergence diagnostics
+- Posterior analysis
+
+### 5. Sparse Optimization
+
+**File**: `05_sparse_optimization_tutorial.ipynb`
+
+Sparse methods for high-dimensional data:
+- Sparse PCA
+- Elastic Net
+- ADMM solver
+- Feature selection
+
+### 6. Optimal Control
+
+**File**: `06_optimal_control_tutorial.ipynb`
+
+Solve HJB equations:
+- Regime-switching jump diffusions (MRSJD)
+- Optimal stopping problems
+- Dynamic programming
+- Financial applications
+
+### 7. Risk Metrics
+
+**File**: `07_risk_metrics_tutorial.ipynb`
+
+Time series analysis:
+- Hurst exponent estimation
+- Half-life calculation
+- Mean reversion testing
+- Trading signal generation
+
+## Python Scripts
+
+Quick examples for copy-paste usage:
+
+### Optimize Rosenbrock Function
+
+```python
+import numpy as np
+from optimizr import DifferentialEvolution
+
+def rosenbrock(x):
+    return sum(100.0 * (x[1:] - x[:-1]**2)**2 + (1 - x[:-1])**2)
+
+de = DifferentialEvolution(bounds=[(-5, 5)] * 10)
+result = de.optimize(rosenbrock, max_iterations=200)
+
+print(f"Minimum: {result.best_fitness}")
+```
+
+### Train HMM on Data
+
+```python
+import numpy as np
+from optimizr import HMMGaussian
+
+# Load your data
+observations = np.load("data.npy")
+
+# Train model
+hmm = HMMGaussian(n_states=3)
+hmm.fit(observations)
+
+# Predict states
+states = hmm.decode(observations)
+```
+
+### MCMC Sampling
+
+```python
+import numpy as np
+from optimizr import MetropolisHastings
+
+def log_posterior(x):
+    return -0.5 * np.sum((x - 2)**2)
+
+sampler = MetropolisHastings(log_posterior, initial_state=np.zeros(5))
+samples = sampler.sample(n_samples=10000)
+```
+
+## Running Examples
+
+To run notebooks:
+
+```bash
+cd examples/
+jupyter notebook
+```
+
+To run Python scripts:
+
+```bash
+python examples/basic_optimization.py
+```
+
+## Contribute Examples
+
+Have a cool use case? Contribute your example:
+
+1. Fork the [repository](https://github.com/ThotDjehuty/optimiz-r)
+2. Add your notebook to `examples/`
+3. Ensure it runs without errors
+4. Submit a pull request
+
+See [Contributing Guide](contributing.md) for details.
@@ -0,0 +1,127 @@
+.. OptimizR documentation master file
+
+OptimizR Documentation
+======================
+
+**High-performance optimization algorithms in Rust with Python bindings**
+
+.. image:: https://img.shields.io/badge/version-0.3.0-blue.svg
+   :target: https://github.com/ThotDjehuty/optimiz-r/releases
+   :alt: Version
+   
+.. image:: https://img.shields.io/badge/license-MIT-green.svg
+   :target: https://github.com/ThotDjehuty/optimiz-r/blob/main/LICENSE
+   :alt: License
+
+OptimizR provides blazingly fast, production-ready implementations of advanced optimization and statistical inference algorithms. Built with Rust for maximum performance and exposed to Python through PyO3, it delivers **50-100× speedup** over pure Python implementations.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+   
+   installation
+   quickstart
+   examples
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Algorithms
+   
+   algorithms/differential_evolution
+   algorithms/mean_field_games
+   algorithms/hmm
+   algorithms/mcmc
+   algorithms/sparse_optimization
+   algorithms/optimal_control
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+   
+   api/differential_evolution
+   api/mean_field_games
+   api/hmm
+   api/mcmc
+   api/sparse
+   api/optimal_control
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Advanced
+   
+   theory/mathematical_foundations
+   benchmarks
+   contributing
+   changelog
+
+Features
+--------
+
+✨ **Algorithms Included:**
+
+- **Mean Field Games**: 1D MFG solver, HJB-Fokker-Planck coupling, agent population dynamics
+- **Differential Evolution**: 5 strategies (rand/1, best/1, current-to-best/1, rand/2, best/2), adaptive jDE
+- **Optimal Control**: HJB solvers, regime switching, jump diffusion, MRSJD framework
+- **Hidden Markov Models**: Baum-Welch training, Viterbi decoding, Gaussian emissions
+- **MCMC Sampling**: Metropolis-Hastings, adaptive proposals, Bayesian inference
+- **Sparse Optimization**: Sparse PCA, Box-Tao decomposition, Elastic Net, ADMM
+- **Risk Metrics**: Hurst exponent, half-life estimation, time series analysis
+- **Information Theory**: Mutual information, Shannon entropy, feature selection
+
+🚀 **Performance:**
+
+- **50-100× faster** than pure Python implementations
+- **95% memory reduction** vs NumPy/SciPy
+- **Parallel-ready** with Rayon infrastructure
+- Production-tested on multi-dimensional problems
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    import numpy as np
+    from optimizr import DifferentialEvolution
+    
+    # Define objective function
+    def sphere(x):
+        return np.sum(x**2)
+    
+    # Optimize
+    de = DifferentialEvolution(
+        bounds=[(-5, 5)] * 10,
+        strategy="best/1/bin",
+        population_size=50
+    )
+    result = de.optimize(sphere, max_iterations=100)
+    
+    print(f"Best fitness: {result.best_fitness:.6f}")
+    print(f"Best solution: {result.best_solution}")
+
+Installation
+------------
+
+From PyPI (coming soon):
+
+.. code-block:: bash
+
+    pip install optimizr
+
+From source:
+
+.. code-block:: bash
+
+    # Clone repository
+    git clone https://github.com/ThotDjehuty/optimiz-r.git
+    cd optimiz-r
+    
+    # Build and install
+    pip install maturin
+    maturin develop --release
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
@@ -0,0 +1,111 @@
+# Installation Guide
+
+## Requirements
+
+- Python 3.8 or higher
+- Rust 1.70 or higher (for building from source)
+- pip
+
+## Install from PyPI
+
+**Coming soon**: OptimizR will be available on PyPI.
+
+```bash
+pip install optimizr
+```
+
+## Install from Source
+
+### Step 1: Clone Repository
+
+```bash
+git clone https://github.com/ThotDjehuty/optimiz-r.git
+cd optimiz-r
+```
+
+### Step 2: Install Maturin
+
+[Maturin](https://github.com/PyO3/maturin) is required to build Rust-Python bindings:
+
+```bash
+pip install maturin
+```
+
+### Step 3: Build and Install
+
+**Development mode** (editable install, useful for development):
+
+```bash
+maturin develop --release
+```
+
+**Production install** (creates wheel and installs):
+
+```bash
+maturin build --release
+pip install target/wheels/optimizr-*.whl
+```
+
+### Step 4: Verify Installation
+
+```python
+import optimizr
+print(optimizr.__version__)  # Should print "0.3.0"
+```
+
+## Platform-Specific Notes
+
+### macOS
+
+If you encounter build errors on macOS:
+
+1. Ensure Xcode Command Line Tools are installed:
+   ```bash
+   xcode-select --install
+   ```
+
+2. Install Rust via rustup:
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   ```
+
+### Windows
+
+1. Install Visual Studio Build Tools (2019 or later)
+2. Install Rust via [rustup-init.exe](https://rustup.rs/)
+3. Follow standard installation steps
+
+### Linux
+
+Requires GCC or Clang:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install build-essential
+
+# Fedora/RHEL
+sudo dnf install gcc gcc-c++
+```
+
+## Troubleshooting
+
+**Issue**: `maturin: command not found`
+
+**Solution**: Ensure pip bin directory is in PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"  # Linux/macOS
+```
+
+**Issue**: Rust compiler errors
+
+**Solution**: Update Rust to latest stable:
+```bash
+rustup update stable
+```
+
+**Issue**: ImportError when importing optimizr
+
+**Solution**: Rebuild with correct Python version:
+```bash
+maturin develop --release -i python3.10  # Replace with your Python version
+```
@@ -0,0 +1,125 @@
+# Quick Start Guide
+
+## Your First Optimization
+
+Let's optimize the classic **Rosenbrock function** using Differential Evolution:
+
+```python
+import numpy as np
+from optimizr import DifferentialEvolution
+
+# Define the Rosenbrock function
+def rosenbrock(x):
+    return sum(100.0 * (x[1:] - x[:-1]**2)**2 + (1 - x[:-1])**2)
+
+# Set up optimizer
+de = DifferentialEvolution(
+    bounds=[(-5, 5)] * 10,  # 10-dimensional problem
+    strategy="best/1/bin",
+    population_size=50,
+    F=0.8,
+    CR=0.9
+)
+
+# Run optimization
+result = de.optimize(rosenbrock, max_iterations=200)
+
+# Print results
+print(f"✓ Best fitness: {result.best_fitness:.6f}")
+print(f"✓ Best solution: {result.best_solution}")
+print(f"✓ Converged in {result.iterations} iterations")
+```
+
+**Expected output:**
+```
+✓ Best fitness: 0.000002
+✓ Best solution: [1.0, 1.0, 1.0, ..., 1.0]
+✓ Converged in 174 iterations
+```
+
+## Mean Field Games Example
+
+Solve a **1D Mean Field Game** (agent population dynamics):
+
+```python
+from optimizr import MFGSolver
+
+# Define parameters
+solver = MFGSolver(
+    nx=100,           # Spatial grid points
+    nt=50,            # Time steps
+    x_min=-5.0,       
+    x_max=5.0,
+    T=1.0,            # Terminal time
+    epsilon=0.1,      # Noise intensity
+    kappa=1.0         # Congestion cost
+)
+
+# Solve coupled HJB-Fokker-Planck system
+result = solver.solve()
+
+# Access solution
+print(f"Value function shape: {result.value_function.shape}")  # (50, 100)
+print(f"Density shape: {result.density.shape}")               # (50, 100)
+print(f"Converged: {result.converged}")
+```
+
+## Hidden Markov Model Example
+
+Train an **HMM** on observed data:
+
+```python
+import numpy as np
+from optimizr import HMMGaussian
+
+# Generate synthetic data (2 hidden states, 1D observations)
+np.random.seed(42)
+observations = np.random.randn(1000, 1)
+
+# Initialize HMM
+hmm = HMMGaussian(n_states=2, n_features=1)
+
+# Train model
+hmm.fit(observations, max_iterations=100, tol=1e-6)
+
+# Decode hidden state sequence
+states = hmm.decode(observations)
+print(f"Predicted states: {states[:20]}") # First 20 states
+```
+
+## MCMC Sampling Example
+
+Sample from a **posterior distribution**:
+
+```python
+import numpy as np
+from optimizr import MetropolisHastings
+
+# Define log-posterior (unnormalized)
+def log_posterior(x):
+    # Gaussian prior: N(0, 1)
+    prior = -0.5 * np.sum(x**2)
+    # Likelihood: N(2, 0.5)
+    likelihood = -0.5 * np.sum((x - 2)**2) / 0.25
+    return prior + likelihood
+
+# Initialize sampler
+sampler = MetropolisHastings(
+    log_prob_fn=log_posterior,
+    initial_state=np.zeros(5),
+    proposal_scale=0.5
+)
+
+# Generate samples
+samples = sampler.sample(n_samples=10000, burn_in=1000)
+
+print(f"Posterior mean: {samples.mean(axis=0)}")  # ~[1.6, 1.6, ...]
+print(f"Acceptance rate: {sampler.acceptance_rate:.2%}")
+```
+
+## Next Steps
+
+- **Explore algorithms**: See [Algorithms](algorithms/differential_evolution.md) for detailed guides
+- **API reference**: Check [API Reference](api/differential_evolution.md) for all parameters
+- **Examples**: Browse [examples/](https://github.com/ThotDjehuty/optimiz-r/tree/main/examples) for Jupyter notebooks
+- **Benchmarks**: See [Benchmarks](benchmarks.md) for performance comparisons