docs(optimizr): add logo and fix rtd deps

docs/source/api/differential_evolution.md

@@ -0,0 +1,27 @@
+# API: differential_evolution
+
+```python
+from optimizr import differential_evolution
+
+best_x, best_fx = differential_evolution(
+    objective_fn,
+    bounds,
+    popsize=15,
+    maxiter=1000,
+    f=None,
+    cr=None,
+    strategy="rand1",
+    seed=None,
+    tol=1e-6,
+    atol=1e-8,
+    track_history=False,
+    parallel=False,
+    adaptive=False,
+    constraint_penalty=1000.0,
+)
+```
+
+- `objective_fn`: callable `f(x: np.ndarray) -> float`
+- `bounds`: list of `(min, max)` tuples
+- Strategies: `rand1`, `best1`, `currenttobest1`, `rand2`, `best2`
+- Returns `(best_x: np.ndarray, best_fx: float)`

docs/source/api/grid_search.md

@@ -0,0 +1,14 @@
+# API: grid_search
+
+```python
+from optimizr import grid_search
+
+best_params, best_score = grid_search(
+    objective_fn,
+    param_grid,
+)
+```
+
+- `objective_fn`: callable receiving a dict of parameters and returning a scalar loss
+- `param_grid`: dict of name -> list of values to enumerate
+- Returns `(best_params: dict, best_score: float)`

docs/source/api/hmm.md

@@ -0,0 +1,16 @@
+# API: HMM
+
+```python
+from optimizr import HMM
+
+model = HMM(n_states=2)
+model.fit(X, n_iterations=100, tolerance=1e-6)
+states = model.predict(X)
+logp = model.score(X)
+```
+
+Parameters
+- `n_states`: number of hidden regimes
+- `fit(X, n_iterations=100, tolerance=1e-6)`: train with Baum-Welch
+- `predict(X)`: Viterbi decoding → `np.ndarray`
+- `score(X)`: log-likelihood

docs/source/api/mcmc.md

@@ -0,0 +1,21 @@
+# API: mcmc_sample
+
+```python
+from optimizr import mcmc_sample
+
+samples = mcmc_sample(
+    log_likelihood_fn,
+    data,
+    initial_params,
+    param_bounds,
+    n_samples=10000,
+    burn_in=1000,
+    proposal_std=0.1,
+)
+```
+
+- `log_likelihood_fn(params, data) -> float`
+- `data`: np.ndarray passed through to the likelihood
+- `initial_params`: np.ndarray starting point
+- `param_bounds`: list of `(min, max)` tuples
+- Returns `samples: np.ndarray` of shape `(n_samples, n_params)`

docs/source/api/optimal_control.md

@@ -0,0 +1,23 @@
+# API: Optimal Control / Kalman
+
+Control utilities are exposed through the Rust extension (`optimizr._core`).
+
+```python
+from optimizr import maths_toolkit
+
+if maths_toolkit is None:
+    raise RuntimeError("Rust backend missing; reinstall with `pip install .`.")
+
+# 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)
+```
+
+Parameters
+- `F`: state transition matrix (list of lists)
+- `H`: observation matrix
+- `Q`: process noise covariance
+- `R`: observation noise covariance
+
+Also see the Mean Field Games API in `mean_field_games.md`.

docs/source/api/risk_metrics.md

@@ -0,0 +1,19 @@
+# API: Risk Metrics
+
+```python
+from optimizr import (
+    hurst_exponent_py,
+    compute_risk_metrics_py,
+    estimate_half_life_py,
+    bootstrap_returns_py,
+)
+
+h = hurst_exponent_py(returns)
+hl = estimate_half_life_py(returns)
+metrics = compute_risk_metrics_py(returns.tolist())
+boot = bootstrap_returns_py(returns, n_samples=1000)
+```
+
+- `returns`: 1D NumPy array of returns
+- `compute_risk_metrics_py` returns a dict with volatility, Sharpe, and drawdown estimates
+- `bootstrap_returns_py` resamples the series for uncertainty estimation

docs/source/api/sparse.md

@@ -0,0 +1,26 @@
+# API: Sparse Optimization
+
+## sparse_pca_py
+```python
+from optimizr import sparse_pca_py
+
+components = sparse_pca_py(
+    X,
+    n_components=3,
+    l1_ratio=0.2,
+)
+```
+- `X`: 2D NumPy array
+- Returns component matrix `(n_components, n_features)`
+
+## box_tao_decomposition_py
+```python
+from optimizr import box_tao_decomposition_py
+solution = box_tao_decomposition_py(X)
+```
+
+## elastic_net_py
+```python
+from optimizr import elastic_net_py
+coeffs = elastic_net_py(X, y, l1_ratio=0.3, alpha=0.01)
+```