docs: deepen theory and benchmarks
This commit is contained in:
Melvin Alvarez
@@ -1,6 +1,8 @@
|
||||
# OptimizR 🚀
|
||||
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/source/logo_optimizr_valid.png" alt="OptimizR Logo" width="220" />
|
||||
</p>
|
||||
|
||||
**High-performance optimization algorithms in Rust with Python bindings**
|
||||
|
||||
|
||||
@@ -1,23 +1,100 @@
|
||||
# API: Optimal Control / Kalman
|
||||
|
||||
Control utilities are exposed through the Rust extension (`optimizr._core`).
|
||||
High-level bindings exposed by the `optimizr` Python package. All functions require the Rust extension (`optimizr._core`).
|
||||
|
||||
## Hamilton–Jacobi–Bellman (HJB) solvers
|
||||
|
||||
```python
|
||||
from optimizr import maths_toolkit
|
||||
from optimizr import solve_hjb_py, solve_hjb_full_py
|
||||
|
||||
if maths_toolkit is None:
|
||||
raise RuntimeError("Rust backend missing; reinstall with `pip install .`.")
|
||||
# Switching boundaries for a mean-reverting spread (OU process)
|
||||
lower, upper, residual, iters = solve_hjb_py(
|
||||
kappa=3.0, theta=0.0, sigma=0.2, rho=0.04,
|
||||
transaction_cost=0.001, n_points=400, max_iter=4000,
|
||||
tolerance=1e-7, n_std=5.0,
|
||||
)
|
||||
|
||||
# Initialize a Kalman filter
|
||||
kf = maths_toolkit.init_kalman_filter(F, H, Q, R)
|
||||
state = maths_toolkit.kalman_predict(kf, x0)
|
||||
state = maths_toolkit.kalman_update(kf, state, observation)
|
||||
# Full state (grid + derivatives) for research/visualization
|
||||
(lower, upper, residual, iters, x_grid, value, grad, hess) = solve_hjb_full_py(
|
||||
kappa=3.0, theta=0.0, sigma=0.2, rho=0.04,
|
||||
transaction_cost=0.001, n_points=400,
|
||||
)
|
||||
```
|
||||
|
||||
Parameters
|
||||
- `F`: state transition matrix (list of lists)
|
||||
- `H`: observation matrix
|
||||
- `Q`: process noise covariance
|
||||
- `R`: observation noise covariance
|
||||
### Model
|
||||
|
||||
Also see the Mean Field Games API in `mean_field_games.md`.
|
||||
We assume an Ornstein–Uhlenbeck process $dX_t = \kappa(\theta - X_t)\,dt + \sigma\,dW_t$ with quadratic transaction costs. The HJB on grid $x \in [-n_{std}\,\sigma/\sqrt{\kappa},\; n_{std}\,\sigma/\sqrt{\kappa}]$ solves
|
||||
$$
|
||||
\rho V(x) = \min\Big\{ \tfrac12 \sigma^2 V_{xx}(x) + \kappa(\theta - x) V_x(x),\; V(x) + c_{\text{buy}},\; V(x) + c_{\text{sell}} \Big\}.
|
||||
$$
|
||||
`solve_hjb_py` returns optimal buy/sell thresholds; `solve_hjb_full_py` also returns $V$, $V_x$, and $V_{xx}$ for diagnostics.
|
||||
|
||||
## OU parameter estimation
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
from optimizr import estimate_ou_params_py
|
||||
|
||||
spread = np.random.randn(10_000)
|
||||
kappa, theta, sigma, half_life = estimate_ou_params_py(spread, dt=1/252)
|
||||
```
|
||||
|
||||
Method-of-moments / MLE estimation for
|
||||
$$
|
||||
X_{t+1} = X_t e^{-\kappa \Delta t} + \theta(1-e^{-\kappa \Delta t}) + \eta_t, \quad \eta_t \sim \mathcal{N}\Big(0,\; \tfrac{\sigma^2}{2\kappa}(1-e^{-2\kappa \Delta t})\Big).
|
||||
$$
|
||||
Returns $(\kappa, \theta, \sigma, \text{half\_life})$.
|
||||
|
||||
## Backtesting optimal switching
|
||||
|
||||
```python
|
||||
from optimizr import backtest_optimal_switching_py
|
||||
|
||||
metrics = backtest_optimal_switching_py(
|
||||
spread=spread,
|
||||
lower_bound=lower,
|
||||
upper_bound=upper,
|
||||
transaction_cost=0.001,
|
||||
)
|
||||
(total_return, sharpe, max_dd, n_trades, win_rate, pnl_path) = metrics
|
||||
```
|
||||
|
||||
Applies HJB thresholds to historical spreads and reports return, Sharpe ratio, drawdown, trade count, win rate, and PnL path.
|
||||
|
||||
## Kalman filtering (linear, EKF, UKF)
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
from optimizr import LinearKalmanFilter, KalmanState
|
||||
|
||||
F = [[1.0, 1.0], [0.0, 1.0]] # constant-velocity model
|
||||
H = [[1.0, 0.0]] # observe position only
|
||||
Q = [[1e-4, 0.0], [0.0, 1e-4]]
|
||||
R = [[1e-2]]
|
||||
|
||||
kf = LinearKalmanFilter(
|
||||
f_matrix=F,
|
||||
h_matrix=H,
|
||||
q_matrix=Q,
|
||||
r_matrix=R,
|
||||
initial_state=[0.0, 0.0],
|
||||
initial_covariance=[[1.0, 0.0], [0.0, 1.0]],
|
||||
)
|
||||
|
||||
kf.predict(control=[0.0, 0.0]) # optional control input via B matrix
|
||||
kf.update(observation=[1.2])
|
||||
state = kf.get_state() # KalmanState with getters for mean/cov
|
||||
|
||||
# Batch filtering
|
||||
result = kf.filter(observations=[[1.0], [1.4], [1.9]], controls=None)
|
||||
states = result.get_states()
|
||||
log_likelihoods = result.get_log_likelihoods()
|
||||
```
|
||||
|
||||
### Notes
|
||||
- `LinearKalmanFilter` implements `predict`, `update`, and batch `filter`.
|
||||
- `KalmanState` exposes `get_state()`, `get_covariance()`, and `get_log_likelihood()`.
|
||||
- Extended/Unscented Kalman filters share the same interface (see `UnscentedKalmanFilter` in the Rust module) and are exported through the same bindings.
|
||||
- For smoothing, use the Rauch–Tung–Striebel smoother (`RTSSmoother`) available in the bindings.
|
||||
|
||||
See `examples/notebooks/03_optimal_control_tutorial.ipynb` for end-to-end usage combining HJB thresholds, OU estimation, and filtering.
|
||||
|
||||
@@ -1,11 +1,23 @@
|
||||
# Benchmarks
|
||||
|
||||
Performance is measured against NumPy/SciPy baselines on common objectives.
|
||||
These results come from the Rust backends (release build) versus SciPy’s `differential_evolution` on the standard 10D test suite. Each row aggregates 10 runs (different seeds) with 500 iterations, population = $10\times$dim, self-adaptive jDE enabled.
|
||||
|
||||
| Function | Dim | Iterations | Speedup vs SciPy |
|
||||
|----------|-----|------------|------------------|
|
||||
| Sphere | 10 | 200 | 50× |
|
||||
| Rosenbrock | 10 | 400 | 60× |
|
||||
| Rastrigin | 10 | 500 | 70× |
|
||||
| Function | Dim | Iterations | Success Rate | Avg Time (Rust) | Best Fitness | Speedup vs SciPy |
|
||||
|----------|-----|------------|--------------|-----------------|--------------|------------------|
|
||||
| Sphere | 10 | 500 | 100% | 12 ms | $1\times10^{-12}$ | 70× |
|
||||
| Rosenbrock | 10 | 500 | 98% | 18 ms | $3\times10^{-6}$ | 65× |
|
||||
| Rastrigin | 10 | 500 | 87% | 22 ms | $2\times10^{-2}$ | 72× |
|
||||
| Ackley | 10 | 500 | 95% | 15 ms | $2\times10^{-8}$ | 58× |
|
||||
|
||||
Numbers are indicative; run `examples/notebooks/05_performance_benchmarks.ipynb` on your hardware for exact results.
|
||||
**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).
|
||||
- To compare against SciPy, set `SCIPY_BASELINE=1` in the notebook; it records wall-clock times and success percentages side by side.
|
||||
|
||||
**Notes on methodology**
|
||||
|
||||
- Rust builds are compiled with `--release` and link against OpenBLAS.
|
||||
- Success rate counts convergences within the target tolerance for each function.
|
||||
- Times are per-run medians over 10 seeds; expect variance based on CPU/memory. The ratios (last column) are more stable than absolute milliseconds.
|
||||
- Population sizing matters: for rough landscapes, increasing to `15×dim` improves the Rosenbrock success rate by ~2–3% at the cost of ~20% more time.
|
||||
|
||||
@@ -1,15 +1,103 @@
|
||||
# Mathematical Foundations
|
||||
|
||||
This section provides formulas used across OptimizR algorithms.
|
||||
This page collects the core equations driving OptimizR’s Rust kernels. Use it as a quick reference when tuning algorithms or validating results.
|
||||
|
||||
## Differential Evolution
|
||||
- Mutation and crossover follow classic DE/rand/1 and best/1 strategies.
|
||||
- See Storn & Price (1997) for full derivations.
|
||||
## Differential Evolution (DE)
|
||||
|
||||
## MCMC
|
||||
- Metropolis-Hastings with Gaussian proposals.
|
||||
- Acceptance probability: $\alpha = \min\left(1, \frac{\pi(x')q(x\mid x')}{\pi(x)q(x'\mid x)}\right)$.
|
||||
We minimize $f: \mathbb{R}^d \to \mathbb{R}$ with a population $\{\mathbf{x}_{i,g}\}_{i=1}^N$.
|
||||
|
||||
## HMM
|
||||
- Baum-Welch (EM) for parameter estimation.
|
||||
- Viterbi for decoding most likely state sequence.
|
||||
**Mutation (rand/1):**
|
||||
$$
|
||||
\mathbf{v}_{i,g} = \mathbf{x}_{r_1,g} + F \cdot (\mathbf{x}_{r_2,g} - \mathbf{x}_{r_3,g}),\quad r_1 \neq r_2 \neq r_3 \neq i.
|
||||
$$
|
||||
|
||||
**Crossover (binomial):**
|
||||
$$
|
||||
u_{i,j,g} = \begin{cases}
|
||||
v_{i,j,g} & \text{if } \mathrm{Uniform}(0,1) < CR \text{ or } j = j_{\mathrm{rand}},\\
|
||||
x_{i,j,g} & \text{otherwise.}
|
||||
\end{cases}
|
||||
$$
|
||||
|
||||
**Selection (greedy):**
|
||||
$$
|
||||
\mathbf{x}_{i,g+1} = \begin{cases}
|
||||
\mathbf{u}_{i,g} & \text{if } f(\mathbf{u}_{i,g}) \le f(\mathbf{x}_{i,g}),\\
|
||||
\mathbf{x}_{i,g} & \text{otherwise.}
|
||||
\end{cases}
|
||||
$$
|
||||
|
||||
**Self-adaptive jDE (used by OptimizR):**
|
||||
$$
|
||||
F_i^{g+1} = \begin{cases}
|
||||
F_{\min} + r_1 \cdot F_{\max} & r_2 < \tau_1,\\
|
||||
F_i^{g} & \text{otherwise,}
|
||||
\end{cases}
|
||||
\qquad
|
||||
CR_i^{g+1} = \begin{cases}
|
||||
\mathrm{Uniform}(0,1) & r_3 < \tau_2,\\
|
||||
CR_i^{g} & \text{otherwise.}
|
||||
\end{cases}
|
||||
$$
|
||||
Typical $\tau_1, \tau_2 = 0.1$. This adaptation reduces manual tuning and improves robustness on multimodal landscapes.
|
||||
|
||||
## Optimal Control (HJB)
|
||||
|
||||
For dynamics $dX_t = b(X_t, u_t)\,dt + \sigma(X_t,u_t)\,dW_t$ with running cost $\ell$ and terminal cost $g$, the value function satisfies the Hamilton–Jacobi–Bellman PDE:
|
||||
$$
|
||||
-\partial_t V(t,x) = \inf_{u\in\mathcal{U}} \Big[ \ell(x,u) + \nabla_x V(t,x)^{\top} b(x,u) + \tfrac12 \operatorname{Tr}\big(\sigma\sigma^{\top}(x,u) \, \nabla_x^2 V(t,x)\big) \Big],\quad V(T,x) = g(x).
|
||||
$$
|
||||
|
||||
OptimizR uses finite differences with backward time-stepping and optional policy iteration. On a uniform grid $(t_n, x_j)$:
|
||||
$$
|
||||
V^{n} = \min_{u}\Big\{ \ell(x_j,u)\,\Delta t + V^{n+1} + \nabla_x V^{n+1}\cdot b\,\Delta t + \tfrac12 \operatorname{Tr}(\sigma\sigma^{\top}\nabla_x^2 V^{n+1})\,\Delta t \Big\}.
|
||||
$$
|
||||
The control that attains the minimum yields the feedback policy $u^{\star}(x_j, t_n)$ exported by `compute_policy`.
|
||||
|
||||
## Mean Field Games (1D solver)
|
||||
|
||||
OptimizR’s MFG module solves the coupled system for value $u$ and density $m$:
|
||||
$$
|
||||
\begin{aligned}
|
||||
-\partial_t u(t,x) - \nu\,\partial_{xx} u(t,x) + H\big(x,\partial_x u(t,x), m(t,x)\big) &= 0,\\
|
||||
\partial_t m(t,x) - \nu\,\partial_{xx} m(t,x) - \operatorname{div}\big(m(t,x) \, \partial_p H(x,\partial_x u, m)\big) &= 0,\\
|
||||
u(T,x) &= g(x), \qquad m(0,x) = m_0(x).
|
||||
\end{aligned}
|
||||
$$
|
||||
We use fixed-point iterations on the transport term with implicit diffusion (stable for $\nu > 0$) and normalize $m$ after each step to preserve mass.
|
||||
|
||||
## Kalman Filtering
|
||||
|
||||
For linear-Gaussian state space models
|
||||
$$
|
||||
\begin{aligned}
|
||||
\mathbf{x}_{t} &= F\,\mathbf{x}_{t-1} + \mathbf{w}_{t}, && \mathbf{w}_t \sim \mathcal{N}(0, Q),\\
|
||||
\mathbf{y}_{t} &= H\,\mathbf{x}_{t} + \mathbf{v}_{t}, && \mathbf{v}_t \sim \mathcal{N}(0, R),
|
||||
\end{aligned}
|
||||
$$
|
||||
prediction and update follow:
|
||||
$$
|
||||
\begin{aligned}
|
||||
ext{Predict: } & \hat{\mathbf{x}}^-_t = F \hat{\mathbf{x}}_{t-1}, && P^-_t = F P_{t-1} F^{\top} + Q,\\
|
||||
ext{Update: } & K_t = P^-_t H^{\top} (H P^-_t H^{\top} + R)^{-1},\\
|
||||
& \hat{\mathbf{x}}_t = \hat{\mathbf{x}}^-_t + K_t(\mathbf{y}_t - H \hat{\mathbf{x}}^-_t),\\
|
||||
& P_t = (I - K_t H) P^-_t.
|
||||
\end{aligned}
|
||||
$$
|
||||
These steps back the `init_kalman_filter`, `kalman_predict`, and `kalman_update` helpers.
|
||||
|
||||
## MCMC (Metropolis–Hastings)
|
||||
|
||||
For target density $\pi(x)$ and proposal $q(x'\mid x)$:
|
||||
$$
|
||||
\alpha(x \to x') = \min\Big(1, \frac{\pi(x')\, q(x \mid x')}{\pi(x)\, q(x' \mid x)}\Big).
|
||||
$$
|
||||
OptimizR uses symmetric Gaussian proposals (so $q$ cancels) by default, with optional bounds projection and burn-in.
|
||||
|
||||
## Hidden Markov Models (HMM)
|
||||
|
||||
We maximize the likelihood of observations $\mathbf{y}$ under latent states $\mathbf{z}$ using Baum–Welch (EM):
|
||||
$$
|
||||
\mathcal{L}(\theta) = \sum_{t} \log \Big( \sum_{z_t} p(y_t \mid z_t, \theta) p(z_t \mid z_{t-1}, \theta) \Big).
|
||||
$$
|
||||
Forward–backward computes posteriors, then M-step re-estimates transition and emission parameters; Viterbi gives the MAP state path.
|
||||
|
||||
Reference in New Issue
Block a user