docs: add ReadTheDocs configuration and Sphinx documentation structure
This commit is contained in:
Melvin Alvarez
@@ -1,7 +1,7 @@
|
||||
# OptimizR Enhancement Strategy
|
||||
|
||||
**Date**: January 2, 2025
|
||||
**Context**: Post-Polaroid Phase 4, exploring integration and improvements
|
||||
**Context**: Post-Polarway Phase 4, exploring integration and improvements
|
||||
**Based On**: v0.2.0 codebase review, roadmap analysis, synergy opportunities
|
||||
|
||||
## Current State Analysis
|
||||
@@ -58,14 +58,14 @@
|
||||
- Simulated Annealing
|
||||
- Ant Colony Optimization
|
||||
|
||||
## Synergy Opportunities: Polaroid + OptimizR
|
||||
## Synergy Opportunities: Polarway + OptimizR
|
||||
|
||||
### 1. Time-Series Feature Engineering for HMM
|
||||
**Description**: Use Polaroid's time-series operations to create features for regime detection
|
||||
**Description**: Use Polarway's time-series operations to create features for regime detection
|
||||
|
||||
**Implementation**:
|
||||
```python
|
||||
# Polaroid: Fast feature creation
|
||||
# Polarway: Fast feature creation
|
||||
df = client.lag(['price'], periods=1) # Lagged prices
|
||||
df = client.pct_change(['price'], periods=1) # Returns
|
||||
df = client.diff(['price'], periods=1) # Price changes
|
||||
@@ -78,7 +78,7 @@ states = hmm.predict(returns)
|
||||
```
|
||||
|
||||
**Value**:
|
||||
- Polaroid provides fast feature engineering (50-200× faster for large datasets)
|
||||
- Polarway provides fast feature engineering (50-200× faster for large datasets)
|
||||
- OptimizR provides statistical inference (HMM regime detection)
|
||||
- Combined: Real-time regime switching for trading strategies
|
||||
|
||||
@@ -87,7 +87,7 @@ states = hmm.predict(returns)
|
||||
|
||||
**Implementation**:
|
||||
```python
|
||||
# Polaroid: Efficient return calculation
|
||||
# Polarway: Efficient return calculation
|
||||
df = client.pct_change(['price'], periods=1)
|
||||
returns = df['price_pct_change'].to_numpy()
|
||||
|
||||
@@ -98,7 +98,7 @@ risk_metrics = compute_risk_metrics(returns) # Comprehensive suite
|
||||
```
|
||||
|
||||
**Value**:
|
||||
- Fast preprocessing (Polaroid) + sophisticated analysis (OptimizR)
|
||||
- Fast preprocessing (Polarway) + sophisticated analysis (OptimizR)
|
||||
- Useful for pairs trading, mean-reversion strategies
|
||||
- Real-time risk monitoring
|
||||
|
||||
@@ -107,7 +107,7 @@ risk_metrics = compute_risk_metrics(returns) # Comprehensive suite
|
||||
|
||||
**Implementation**:
|
||||
```python
|
||||
# Polaroid: Multi-asset feature creation
|
||||
# Polarway: Multi-asset feature creation
|
||||
df = client.lag(['spy_price', 'vix'], periods=[1, 5, 20])
|
||||
df = client.pct_change(['spy_price'], periods=1)
|
||||
|
||||
@@ -127,7 +127,7 @@ value_fn = solve_hjb_regime_switching(...)
|
||||
|
||||
**Implementation**:
|
||||
```python
|
||||
# Polaroid: Backtest execution (fast data ops)
|
||||
# Polarway: Backtest execution (fast data ops)
|
||||
def backtest_strategy(params):
|
||||
df = client.lag(['price'], periods=int(params[0]))
|
||||
# ... strategy logic ...
|
||||
@@ -143,7 +143,7 @@ result = differential_evolution(
|
||||
```
|
||||
|
||||
**Value**:
|
||||
- Polaroid handles heavy data processing
|
||||
- Polarway handles heavy data processing
|
||||
- OptimizR finds optimal parameters
|
||||
- 74-88× faster than SciPy DE
|
||||
|
||||
@@ -258,14 +258,14 @@ impl SHADEMemory {
|
||||
|
||||
### Priority 3: Time-Series Integration Helpers
|
||||
|
||||
**Problem**: Using Polaroid + OptimizR requires manual glue code
|
||||
**Problem**: Using Polarway + OptimizR requires manual glue code
|
||||
|
||||
**Solution**: Create helper functions for common time-series + optimization patterns
|
||||
|
||||
**Implementation Strategy**:
|
||||
1. Add `timeseries_utils` module to OptimizR
|
||||
2. Functions for common workflows
|
||||
3. Optional Polaroid integration (via feature flag)
|
||||
3. Optional Polarway integration (via feature flag)
|
||||
|
||||
**Code Outline**:
|
||||
```rust
|
||||
@@ -350,7 +350,7 @@ result = tsu.optimize_strategy_params(
|
||||
|
||||
1. **Session 1 (Current)**: Time-Series Integration Helpers (1-2 hours)
|
||||
- Low effort, immediate value
|
||||
- Makes Polaroid + OptimizR integration obvious
|
||||
- Makes Polarway + OptimizR integration obvious
|
||||
- Creates examples for documentation
|
||||
|
||||
2. **Session 2**: Enable Rust-Native Parallelization (1-2 hours)
|
||||
@@ -372,7 +372,7 @@ result = tsu.optimize_strategy_params(
|
||||
For each enhancement:
|
||||
1. **Unit tests**: Algorithm correctness (sphere function, Rosenbrock)
|
||||
2. **Benchmarks**: Performance comparison (before/after)
|
||||
3. **Integration tests**: Polaroid + OptimizR workflows
|
||||
3. **Integration tests**: Polarway + OptimizR workflows
|
||||
4. **Documentation**: Usage examples, API docs
|
||||
|
||||
## Git Commit Strategy (per MANDATORY rules)
|
||||
@@ -404,4 +404,4 @@ Each enhancement gets:
|
||||
|
||||
---
|
||||
|
||||
**Next Action**: Implement Priority 3 (Time-Series Integration Helpers) as it's lowest effort with immediate value for demonstrating Polaroid + OptimizR synergy.
|
||||
**Next Action**: Implement Priority 3 (Time-Series Integration Helpers) as it's lowest effort with immediate value for demonstrating Polarway + OptimizR synergy.
|
||||
|
||||
@@ -14,7 +14,7 @@ Completed comprehensive enhancement suite for OptimizR v0.2.0, implementing all
|
||||
2. ✅ **Rust Parallelization** (Priority 2)
|
||||
3. ✅ **SHADE Algorithm** (Priority 1)
|
||||
|
||||
Additionally created integration examples combining Polaroid + OptimizR workflows.
|
||||
Additionally created integration examples combining Polarway + OptimizR workflows.
|
||||
|
||||
---
|
||||
|
||||
@@ -41,7 +41,7 @@ Additionally created integration examples combining Polaroid + OptimizR workflow
|
||||
- All functions tested and working
|
||||
|
||||
**Impact**:
|
||||
- Enables Polaroid → OptimizR workflows
|
||||
- Enables Polarway → OptimizR workflows
|
||||
- Simplifies regime detection with HMM
|
||||
- Streamlines pairs trading analysis
|
||||
|
||||
@@ -130,12 +130,12 @@ Additionally created integration examples combining Polaroid + OptimizR workflow
|
||||
|
||||
### 4. Integration Examples (Included with parallelization)
|
||||
|
||||
**Purpose**: Demonstrate Polaroid + OptimizR workflows.
|
||||
**Purpose**: Demonstrate Polarway + OptimizR workflows.
|
||||
|
||||
**Implementation**:
|
||||
- `examples/polaroid_optimizr_integration.py` (500+ lines)
|
||||
- `examples/polarway_optimizr_integration.py` (500+ lines)
|
||||
- 4 comprehensive workflows:
|
||||
1. **Regime Detection**: Polaroid features → HMM → regime classification
|
||||
1. **Regime Detection**: Polarway features → HMM → regime classification
|
||||
2. **Strategy Optimization**: Moving average crossover with DE
|
||||
3. **Risk Analysis**: Portfolio with rolling metrics
|
||||
4. **Pairs Trading**: Complete pipeline with cointegration check
|
||||
@@ -148,11 +148,11 @@ Additionally created integration examples combining Polaroid + OptimizR workflow
|
||||
|
||||
**Impact**:
|
||||
- End-to-end examples for financial analysis
|
||||
- Demonstrates Polaroid + OptimizR synergy
|
||||
- Demonstrates Polarway + OptimizR synergy
|
||||
- Ready for production adaptation
|
||||
|
||||
**Files**:
|
||||
- `examples/polaroid_optimizr_integration.py`
|
||||
- `examples/polarway_optimizr_integration.py`
|
||||
- `examples/timeseries_integration.py`
|
||||
- `examples/parallel_de_benchmark.py`
|
||||
|
||||
@@ -223,7 +223,7 @@ All commits pushed to origin/main ✅
|
||||
|
||||
All enhancements align with OptimizR v0.3.0 roadmap:
|
||||
|
||||
- ✅ **Time-series integration**: Enable Polaroid workflows
|
||||
- ✅ **Time-series integration**: Enable Polarway workflows
|
||||
- ✅ **Parallelization**: Unlock Rayon infrastructure
|
||||
- ✅ **SHADE**: State-of-the-art adaptive DE
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
# Python dependencies for building documentation
|
||||
sphinx>=7.0.0
|
||||
furo>=2023.9.10
|
||||
myst-parser>=2.0.0
|
||||
sphinx-autodoc-typehints>=1.24.0
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user