gavindiaz/optimiz-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(v2.0.0-alpha.6): convert all inline $...$ to :math: role in v2 RST pages

Browse Source 
RST does not parse dollar-math (the dollarmath MyST extension applies
only to .md files), so every inline LaTeX expression was rendered as
raw text on Read the Docs — with backslashes silently stripped by the
RST escape mechanism (e.g. \bar s shown as 'bar s', \mathbb{E} shown
as 'mathbb{E}'). The eight v2.0 algorithm pages now use the proper
:math: role for inline math (224 expressions converted), so MathJax
renders every symbol correctly.

Affected pages: bsde, pde, stochastic_control, quadratic_impact_control,
mckean_vlasov, agent_based, robust_drift, generative_calibration_hooks.
This commit is contained in:
ThotDjehuty
2026-05-12 17:10:06 +02:00
parent 73ec6c02cb
commit ece0b31d9e
8 changed files with 143 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/algorithms/agent_based.rst
+17 -17
View File
@@ -10,53 +10,53 @@ update rule
\qquad \bar s^k \;=\; \frac1N \sum_{j=1}^N s^k_j,
\qquad \xi^k_i \sim \mathcal{N}(0, \sigma^2),
with $\alpha \in (0, 1]$ the *averaging weight* and $\sigma$ the noise scale. This is the
with :math:`\alpha \in (0, 1]` the *averaging weight* and :math:`\sigma` the noise scale. This is the
DeGroot–Friedkin–Johnsen baseline of opinion dynamics, and the *complete-graph* limit of the
Hegselmann–Krause and Vicsek flocking models.
Mathematical background
-----------------------
**Mean conservation.** Averaging the update over $i$ gives
$\bar s^{k+1} = \bar s^k + \bar\xi^k$ with $\mathbb{E}[\bar\xi^k] = 0$, so the empirical mean
**Mean conservation.** Averaging the update over :math:`i` gives
:math:`\bar s^{k+1} = \bar s^k + \bar\xi^k` with :math:`\mathbb{E}[\bar\xi^k] = 0`, so the empirical mean
is a *martingale* and is exactly preserved in expectation:
.. math::
\mathbb{E}[\bar s^k] \;=\; \bar s^0 \quad \text{for all } k \ge 0.
In the noiseless case $\sigma = 0$ the mean is preserved *path-by-path*.
In the noiseless case :math:`\sigma = 0` the mean is preserved *path-by-path*.
**Geometric contraction of the spread.** Define the deviation $d^k_i := s^k_i - \bar s^k$.
**Geometric contraction of the spread.** Define the deviation :math:`d^k_i := s^k_i - \bar s^k`.
The update implies
.. math::
d^{k+1}_i \;=\; (1 - \alpha)\, d^k_i \;+\; \bigl(\xi^k_i - \bar\xi^k\bigr) ,
so in the absence of noise $\| d^k \|_\infty \le (1 - \alpha)^k \| d^0 \|_\infty$ — the spread
*contracts geometrically* with rate $1 - \alpha$. The companion notebook plots
$\max_i s^k_i - \min_i s^k_i$ on a log scale across $\alpha \in \{0.05, \dots, 1\}$ and
so in the absence of noise :math:`\| d^k \|_\infty \le (1 - \alpha)^k \| d^0 \|_\infty` — the spread
*contracts geometrically* with rate :math:`1 - \alpha`. The companion notebook plots
:math:`\max_i s^k_i - \min_i s^k_i` on a log scale across :math:`\alpha \in \{0.05, \dots, 1\}` and
recovers exactly this slope.
**Stationary variance with noise.** Treating the deviation as an AR(1) process with input
variance $\sigma^2 (1 - 1/N)$, the steady-state variance of any single agent's deviation is
variance :math:`\sigma^2 (1 - 1/N)`, the steady-state variance of any single agent's deviation is
.. math::
\mathrm{Var}_\infty(d_i) \;=\; \frac{\sigma^2 (1 - 1/N)}{1 - (1 - \alpha)^2}
\;\xrightarrow[\alpha \to 0]{}\; \frac{\sigma^2}{2\alpha}\,(1 - 1/N).
**Continuous-time limit (linear Vlasov).** Sending $\alpha = \theta\, \Delta t$,
$\xi^k_i = \sigma \sqrt{\Delta t}\, W^i_k$ and $\Delta t \to 0$ recovers the McKean–Vlasov SDE
$dX^i_t = \theta(\bar X_t - X^i_t)\, dt + \sigma\, dW^i_t$ of :doc:`mckean_vlasov` — the
**Continuous-time limit (linear Vlasov).** Sending :math:`\alpha = \theta\, \Delta t`,
:math:`\xi^k_i = \sigma \sqrt{\Delta t}\, W^i_k` and :math:`\Delta t \to 0` recovers the McKean–Vlasov SDE
:math:`dX^i_t = \theta(\bar X_t - X^i_t)\, dt + \sigma\, dW^i_t` of :doc:`mckean_vlasov` — the
discrete consensus update is the prototype of mean-field interaction.
**Spectral interpretation.** On a general weighted graph the update reads
$s^{k+1} = (I - \alpha L)\, s^k + \xi^k$, where $L$ is the normalised Laplacian. The
complete-graph case shipped here has $L = I - \tfrac1N \mathbf{1}\mathbf{1}^\top$ with
eigenvalue $1$ on the orthogonal complement of $\mathbf{1}$, hence the contraction rate
$1 - \alpha$ above. Replacing $\mathbf{1}\mathbf{1}^\top / N$ by an arbitrary stochastic
:math:`s^{k+1} = (I - \alpha L)\, s^k + \xi^k`, where :math:`L` is the normalised Laplacian. The
complete-graph case shipped here has :math:`L = I - \tfrac1N \mathbf{1}\mathbf{1}^\top` with
eigenvalue :math:`1` on the orthogonal complement of :math:`\mathbf{1}`, hence the contraction rate
:math:`1 - \alpha` above. Replacing :math:`\mathbf{1}\mathbf{1}^\top / N` by an arbitrary stochastic
matrix produces the full DeGroot model and is a one-liner extension on the Rust side.
Why it matters
@@ -66,7 +66,7 @@ Why it matters
(Bayesian persuasion, social media echo chambers, voting-system stability).
* **Distributed estimation & federated learning.** Average-consensus protocols for sensor
networks, gossip algorithms, federated averaging — all reduce to the same contraction
argument with explicit convergence rate $1 - \alpha$.
argument with explicit convergence rate :math:`1 - \alpha`.
* **Coupled-oscillator physics.** Linear approximation of the Kuramoto / Vicsek models near
the synchronised regime; direct comparison with the McKean–Vlasov continuous limit.
docs/source/algorithms/bsde.rst
+30 -30
View File
@@ -1,16 +1,16 @@
BSDE — θ-scheme and deep-BSDE bridge
====================================
A **backward stochastic differential equation** (BSDE) on $[0, T]$ is the inverse-time problem
A **backward stochastic differential equation** (BSDE) on :math:`[0, T]` is the inverse-time problem
.. math::
Y_t \;=\; \xi \;+\; \int_t^T f(s, Y_s, Z_s)\, ds \;-\; \int_t^T Z_s\, dW_s,
\qquad Y_T = \xi,
where $\xi \in L^2(\mathcal{F}_T)$ is the *terminal condition*, $f$ is the *driver* and the
unknowns are an adapted pair $(Y, Z) \in \mathcal{S}^2 \times \mathcal{H}^2$. The auxiliary
process $Z$ is a *non-anticipative hedge*: it makes the equation adapted despite the terminal
where :math:`\xi \in L^2(\mathcal{F}_T)` is the *terminal condition*, :math:`f` is the *driver* and the
unknowns are an adapted pair :math:`(Y, Z) \in \mathcal{S}^2 \times \mathcal{H}^2`. The auxiliary
process :math:`Z` is a *non-anticipative hedge*: it makes the equation adapted despite the terminal
constraint.
The primitive `linear_bsde_constant_coeffs` solves the constant-coefficient linear case
@@ -20,19 +20,19 @@ The primitive `linear_bsde_constant_coeffs` solves the constant-coefficient line
-dY_t \;=\; (a\, Y_t + b\, Z_t + c)\, dt \;-\; Z_t\, dW_t,
\qquad Y_T = \xi,
by a **Crank–Nicolson θ-scheme** (θ = 0.5 → second-order in $\Delta t$).
by a **Crank–Nicolson θ-scheme** (θ = 0.5 → second-order in :math:`\Delta t`).
Mathematical background
-----------------------
**Pardoux–Peng theorem (1990).** If $f$ is uniformly Lipschitz in $(y, z)$ and
$\mathbb{E}\!\int_0^T f(s, 0, 0)^2\, ds < \infty$, then the BSDE admits a unique solution
$(Y, Z) \in \mathcal{S}^2 \times \mathcal{H}^2$. The proof is a Banach–Picard fixed point on
$\Phi : (Y, Z) \mapsto (Y', Z')$ with
$Y'_t = \mathbb{E}\bigl[\xi + \int_t^T f(s, Y_s, Z_s)\, ds \bigm| \mathcal{F}_t\bigr]$ and $Z'$
**Pardoux–Peng theorem (1990).** If :math:`f` is uniformly Lipschitz in :math:`(y, z)` and
:math:`\mathbb{E}\!\int_0^T f(s, 0, 0)^2\, ds < \infty`, then the BSDE admits a unique solution
:math:`(Y, Z) \in \mathcal{S}^2 \times \mathcal{H}^2`. The proof is a Banach–Picard fixed point on
:math:`\Phi : (Y, Z) \mapsto (Y', Z')` with
:math:`Y'_t = \mathbb{E}\bigl[\xi + \int_t^T f(s, Y_s, Z_s)\, ds \bigm| \mathcal{F}_t\bigr]` and :math:`Z'`
obtained by the martingale representation theorem.
**Closed-form for the linear case.** For $a, b, c$ deterministic the solution is the
**Closed-form for the linear case.** For :math:`a, b, c` deterministic the solution is the
conditional expectation under a Girsanov-shifted measure:
.. math::
@@ -41,12 +41,12 @@ conditional expectation under a Girsanov-shifted measure:
\;+\; \int_t^T c(s)\, e^{\int_t^s a(r)\, dr}\, ds
\,\Big|\, \mathcal{F}_t \right],
with the Girsanov density $\frac{d\mathbb{Q}}{d\mathbb{P}} = \mathcal{E}\bigl(\int_0^\cdot b(s)\,dW_s\bigr)$.
When $b = c = 0$, $a \equiv -\rho$ and $\xi = 1$ this collapses to the analytic ground truth
$Y_t = e^{-\rho(T-t)}$ used by the convergence test.
with the Girsanov density :math:`\frac{d\mathbb{Q}}{d\mathbb{P}} = \mathcal{E}\bigl(\int_0^\cdot b(s)\,dW_s\bigr)`.
When :math:`b = c = 0`, :math:`a \equiv -\rho` and :math:`\xi = 1` this collapses to the analytic ground truth
:math:`Y_t = e^{-\rho(T-t)}` used by the convergence test.
**Feynman–Kac bridge.** Setting $f(s, y, z) = -r y$ and $\xi = g(X_T)$ for a forward SDE $X$
recovers the discounted-payoff PDE: $Y_t = e^{-r(T-t)} \mathbb{E}[g(X_T) \mid \mathcal{F}_t]$.
**Feynman–Kac bridge.** Setting :math:`f(s, y, z) = -r y` and :math:`\xi = g(X_T)` for a forward SDE :math:`X`
recovers the discounted-payoff PDE: :math:`Y_t = e^{-r(T-t)} \mathbb{E}[g(X_T) \mid \mathcal{F}_t]`.
More generally, the markovian BSDE
.. math::
@@ -54,10 +54,10 @@ More generally, the markovian BSDE
Y_t = g(X_T) + \int_t^T f(s, X_s, Y_s, Z_s)\, ds - \int_t^T Z_s\, dW_s,
is the probabilistic representation of the semilinear PDE
$\partial_t u + \mathcal{L}u + f(t, x, u, \sigma^\top \nabla u) = 0$, $u(T, x) = g(x)$, with
$Y_t = u(t, X_t)$ and $Z_t = \sigma^\top(t, X_t)\nabla u(t, X_t)$.
:math:`\partial_t u + \mathcal{L}u + f(t, x, u, \sigma^\top \nabla u) = 0`, :math:`u(T, x) = g(x)`, with
:math:`Y_t = u(t, X_t)` and :math:`Z_t = \sigma^\top(t, X_t)\nabla u(t, X_t)`.
**Crank–Nicolson θ-scheme.** On a uniform grid $0 = t_0 < \cdots < t_N = T$ the scheme reads
**Crank–Nicolson θ-scheme.** On a uniform grid :math:`0 = t_0 < \cdots < t_N = T` the scheme reads
.. math::
@@ -65,28 +65,28 @@ $Y_t = u(t, X_t)$ and $Z_t = \sigma^\top(t, X_t)\nabla u(t, X_t)$.
\;+\; \Delta t\,\bigl(\theta\, f(t_i, Y^N_{t_i}, Z^N_{t_i})
+ (1-\theta)\, f(t_{i+1}, Y^N_{t_{i+1}}, Z^N_{t_{i+1}})\bigr),
with $Z^N_{t_i} = \Delta t^{-1}\,\mathbb{E}\bigl[Y^N_{t_{i+1}}(W_{t_{i+1}} - W_{t_i})\bigm|\mathcal{F}_{t_i}\bigr]$
(discrete Clark–Ocone identity). For $\theta = 1/2$ the global truncation error is
$\sup_i \mathbb{E}|Y_{t_i} - Y^N_{t_i}|^2 = O(\Delta t^2)$ — the second-order rate verified
with :math:`Z^N_{t_i} = \Delta t^{-1}\,\mathbb{E}\bigl[Y^N_{t_{i+1}}(W_{t_{i+1}} - W_{t_i})\bigm|\mathcal{F}_{t_i}\bigr]`
(discrete Clark–Ocone identity). For :math:`\theta = 1/2` the global truncation error is
:math:`\sup_i \mathbb{E}|Y_{t_i} - Y^N_{t_i}|^2 = O(\Delta t^2)` — the second-order rate verified
empirically by the convergence cell of the companion notebook.
**Deep-BSDE bridge (E–Han–Jentzen, 2017).** In high dimension the conditional expectation
is intractable; one parametrises $Z_{t_i} = \zeta^i_\theta(X_{t_i})$ by a neural network and
minimises $\mathbb{E}\bigl[(Y^\theta_T - \xi)^2\bigr]$ over $(Y_0, \theta)$. The trait
is intractable; one parametrises :math:`Z_{t_i} = \zeta^i_\theta(X_{t_i})` by a neural network and
minimises :math:`\mathbb{E}\bigl[(Y^\theta_T - \xi)^2\bigr]` over :math:`(Y_0, \theta)`. The trait
`ConditionalExpectation` and the struct `DeepBsdeBridge` expose the same θ-scheme step so the
user can plug in any regression / neural-network conditional-expectation oracle.
Why it matters
--------------
* **Pricing & hedging in incomplete markets.** $Y_t$ is the super-replication price of the
contingent claim $\xi$ and $Z_t$ is the instantaneous hedge ratio. Constraints (transaction
costs, portfolio caps, recursive utilities) are absorbed into the driver $f$.
* **Pricing & hedging in incomplete markets.** :math:`Y_t` is the super-replication price of the
contingent claim :math:`\xi` and :math:`Z_t` is the instantaneous hedge ratio. Constraints (transaction
costs, portfolio caps, recursive utilities) are absorbed into the driver :math:`f`.
* **Stochastic control.** Forward–backward SDEs are the probabilistic counterpart of the
Hamilton–Jacobi–Bellman PDE; deep-BSDE solves HJB up to $d \sim 100$ state variables, well
Hamilton–Jacobi–Bellman PDE; deep-BSDE solves HJB up to :math:`d \sim 100` state variables, well
beyond grid-based PDE solvers.
* **Risk-sensitive optimisation.** Quadratic-driver BSDE
$-dY = \tfrac1{2\eta}|Z|^2 dt - Z\, dW$ encodes exponential utility hedging (Kramkov–Schachermayer 1999).
:math:`-dY = \tfrac1{2\eta}|Z|^2 dt - Z\, dW` encodes exponential utility hedging (Kramkov–Schachermayer 1999).
.. note::
📓 **Companion notebook** — `view on GitHub <https://github.com/ThotDjehuty/optimiz-rs/blob/main/examples/notebooks/10_bsde.ipynb>`_
@@ -108,7 +108,7 @@ Generic CPU-only Crank–Nicolson scheme for linear backward stochastic differen
Exponential ground-truth check
------------------------------
With $a(t) \equiv -\rho$, $b = c = 0$ and $Y_T = 1$ the analytic deterministic solution is $Y_t = e^{-\rho (T-t)}$.
With :math:`a(t) \equiv -\rho`, :math:`b = c = 0` and :math:`Y_T = 1` the analytic deterministic solution is :math:`Y_t = e^{-\rho (T-t)}`.
.. code-block:: python
docs/source/algorithms/generative_calibration_hooks.rst
+15 -15
View File
@@ -8,9 +8,9 @@ function of every generative-calibration loop in `optimiz-rs`.
Mathematical background
-----------------------
**Definition.** For a positive-definite kernel $k : \mathbb{R}^d \times \mathbb{R}^d \to \mathbb{R}$
with reproducing-kernel Hilbert space (RKHS) $\mathcal{H}_k$, the *kernel mean embedding* of a
probability measure $P$ is $\mu_P := \mathbb{E}_{X \sim P}[k(X, \cdot)] \in \mathcal{H}_k$.
**Definition.** For a positive-definite kernel :math:`k : \mathbb{R}^d \times \mathbb{R}^d \to \mathbb{R}`
with reproducing-kernel Hilbert space (RKHS) :math:`\mathcal{H}_k`, the *kernel mean embedding* of a
probability measure :math:`P` is :math:`\mu_P := \mathbb{E}_{X \sim P}[k(X, \cdot)] \in \mathcal{H}_k`.
The **squared MMD** is the RKHS distance between embeddings:
.. math::
@@ -18,10 +18,10 @@ The **squared MMD** is the RKHS distance between embeddings:
\mathrm{MMD}^2(P, Q) \;:=\; \| \mu_P - \mu_Q \|_{\mathcal{H}_k}^2
\;=\; \mathbb{E}\,[k(X, X')] \;-\; 2\, \mathbb{E}\,[k(X, Y)] \;+\; \mathbb{E}\,[k(Y, Y')] ,
where $X, X' \sim P$ and $Y, Y' \sim Q$ are independent. When $k$ is *characteristic*
(e.g. Gaussian RBF), $\mathrm{MMD}(P, Q) = 0 \iff P = Q$.
where :math:`X, X' \sim P` and :math:`Y, Y' \sim Q` are independent. When :math:`k` is *characteristic*
(e.g. Gaussian RBF), :math:`\mathrm{MMD}(P, Q) = 0 \iff P = Q`.
**U-statistic estimator.** Given i.i.d. samples $\{x_i\}_{i=1}^n$ and $\{y_j\}_{j=1}^m$, the
**U-statistic estimator.** Given i.i.d. samples :math:`\{x_i\}_{i=1}^n` and :math:`\{y_j\}_{j=1}^m`, the
unbiased estimator is
.. math::
@@ -31,21 +31,21 @@ unbiased estimator is
\;-\; \frac{2}{n m}\!\sum_{i, j} k(x_i, y_j)
\;+\; \frac{1}{m(m-1)}\!\sum_{j \ne j'} k(y_j, y_{j'}) .
It is unbiased, computable in $O((n + m)^2)$ for $d = 1$ (the case implemented), and asymptotically
It is unbiased, computable in :math:`O((n + m)^2)` for :math:`d = 1` (the case implemented), and asymptotically
normal under the alternative. Self-distance is **exactly zero**.
**Kernel.** The shipped routine uses the Gaussian RBF
$k_\sigma(x, y) = \exp\!\bigl(-(x - y)^2 / (2\sigma^2)\bigr)$ with bandwidth $\sigma$. Standard
:math:`k_\sigma(x, y) = \exp\!\bigl(-(x - y)^2 / (2\sigma^2)\bigr)` with bandwidth :math:`\sigma`. Standard
reproducing-kernel theory shows that this kernel is *characteristic*, hence MMD metrises weak
convergence on bounded subsets.
**Closed forms for two notable cases.**
* **Pure translation, equal samples.** If $Q$ is the law of $X + \Delta$ with $X \sim P$ on
$\mathbb{R}$ and $P = \delta$ atomic, the squared MMD is $2 - 2 e^{-\Delta^2 / (2\sigma^2)}$ —
smooth, monotone in $|\Delta|$, asymptote $2$ as $\Delta \to \infty$. This is the analytic
* **Pure translation, equal samples.** If :math:`Q` is the law of :math:`X + \Delta` with :math:`X \sim P` on
:math:`\mathbb{R}` and :math:`P = \delta` atomic, the squared MMD is :math:`2 - 2 e^{-\Delta^2 / (2\sigma^2)}` —
smooth, monotone in :math:`|\Delta|`, asymptote :math:`2` as :math:`\Delta \to \infty`. This is the analytic
ground-truth verified by the *bandwidth dependence* cell of the companion notebook.
* **Two Gaussians.** For $P = \mathcal{N}(\mu_1, \sigma_1^2)$ and $Q = \mathcal{N}(\mu_2, \sigma_2^2)$,
* **Two Gaussians.** For :math:`P = \mathcal{N}(\mu_1, \sigma_1^2)` and :math:`Q = \mathcal{N}(\mu_2, \sigma_2^2)`,
.. math::
@@ -57,8 +57,8 @@ convergence on bounded subsets.
giving an exact reference for unit tests.
**Statistical guarantee.** Gretton et al. (2012, Thm. 12) give the deviation bound
$\Pr\!\bigl(\widehat{\mathrm{MMD}}^2 - \mathrm{MMD}^2 > \varepsilon\bigr) \le \exp\bigl(-\varepsilon^2 nm / (8 K^2 (n + m))\bigr)$
for $|k| \le K$. Hence MMD detects fixed alternatives at the optimal $n^{-1/2}$ rate.
:math:`\Pr\!\bigl(\widehat{\mathrm{MMD}}^2 - \mathrm{MMD}^2 > \varepsilon\bigr) \le \exp\bigl(-\varepsilon^2 nm / (8 K^2 (n + m))\bigr)`
for :math:`|k| \le K`. Hence MMD detects fixed alternatives at the optimal :math:`n^{-1/2}` rate.
**Connection with Wasserstein.** Both metrise weak convergence, but MMD is *quadratic in the
sample size* (no transport plan to solve) and admits unbiased low-variance gradient estimators —
@@ -69,7 +69,7 @@ Why it matters
--------------
* **Generative calibration.** Train an implicit sampler (neural SDE, copula generator, GAN-like
architecture) by minimising $\widehat{\mathrm{MMD}}^2$ between the simulator output and the
architecture) by minimising :math:`\widehat{\mathrm{MMD}}^2` between the simulator output and the
target distribution. The trait `GenerativeSampler` plus `calibration_step` is the abstract
glue.
* **Two-sample testing.** Distribution drift detection in streaming data, A/B-test signal
docs/source/algorithms/mckean_vlasov.rst
+13 -13
View File
@@ -9,7 +9,7 @@ on the *law* of the solution itself:
dX_t \;=\; b\bigl(t, X_t, \mathcal{L}(X_t)\bigr)\, dt \;+\; \sigma\bigl(t, X_t, \mathcal{L}(X_t)\bigr)\, dW_t,
\qquad X_0 \sim \mu_0 .
It is the formal $N \to \infty$ limit of an exchangeable system of $N$ interacting diffusions
It is the formal :math:`N \to \infty` limit of an exchangeable system of :math:`N` interacting diffusions
.. math::
@@ -23,22 +23,22 @@ The primitive shipped here, `mean_reverting_mckean_vlasov`, simulates the canoni
dX_t \;=\; \theta\bigl(\bar X_t - X_t\bigr)\, dt \;+\; \sigma\, dW_t,
\qquad \bar X_t = \mathbb{E}[X_t],
with the symmetric Euler particle scheme $X^{i,N}_{k+1} = X^{i,N}_k + \theta(\bar X^N_k - X^{i,N}_k)\Delta t + \sigma\sqrt{\Delta t}\,\xi^i_k$.
with the symmetric Euler particle scheme :math:`X^{i,N}_{k+1} = X^{i,N}_k + \theta(\bar X^N_k - X^{i,N}_k)\Delta t + \sigma\sqrt{\Delta t}\,\xi^i_k`.
Mathematical background
-----------------------
**Sznitman's propagation of chaos (1991).** Under standard Lipschitz assumptions on $b, \sigma$ in
$(x, \mu)$ (the $\mu$ argument equipped with the Wasserstein distance $W_2$), the empirical
measure $\mu^N_t = \tfrac1N \sum_i \delta_{X^{i,N}_t}$ converges weakly to the deterministic flow
$\mathcal{L}(X_t)$, and any fixed sub-system of $k$ particles becomes asymptotically independent:
**Sznitman's propagation of chaos (1991).** Under standard Lipschitz assumptions on :math:`b, \sigma` in
:math:`(x, \mu)` (the :math:`\mu` argument equipped with the Wasserstein distance :math:`W_2`), the empirical
measure :math:`\mu^N_t = \tfrac1N \sum_i \delta_{X^{i,N}_t}` converges weakly to the deterministic flow
:math:`\mathcal{L}(X_t)`, and any fixed sub-system of :math:`k` particles becomes asymptotically independent:
.. math::
\sup_{0 \le t \le T} \, \mathbb{E}\bigl[\,W_2^2\!\bigl(\mu^N_t,\, \mathcal{L}(X_t)\bigr)\bigr]
\;\le\; \frac{C(T)}{N^{2/(d+4)}} .
**Density flow (nonlinear Fokker–Planck).** The marginal density $\rho_t = \mathrm{law}(X_t)$
**Density flow (nonlinear Fokker–Planck).** The marginal density :math:`\rho_t = \mathrm{law}(X_t)`
satisfies the *nonlinear* PDE
.. math::
@@ -47,8 +47,8 @@ satisfies the *nonlinear* PDE
\;=\; \tfrac12\, \nabla^2\!:\!\bigl(\sigma\sigma^\top(t, x, \rho_t)\, \rho_t\bigr).
**Closed-form for the mean-reverting case.** Taking expectation of the SDE gives
$\dot{\bar X}_t = 0$, so the population mean is *exactly preserved*: $\bar X_t \equiv \bar X_0$.
The deviation $\widetilde X^i_t := X^{i,N}_t - \bar X_0$ then solves a standard Ornstein–Uhlenbeck
:math:`\dot{\bar X}_t = 0`, so the population mean is *exactly preserved*: :math:`\bar X_t \equiv \bar X_0`.
The deviation :math:`\widetilde X^i_t := X^{i,N}_t - \bar X_0` then solves a standard Ornstein–Uhlenbeck
SDE, so each marginal is Gaussian with
.. math::
@@ -61,21 +61,21 @@ SDE, so each marginal is Gaussian with
The companion notebook checks both the mean conservation and the variance asymptote.
**Connection with mean-field BSDEs.** Coupling the McKean–Vlasov forward SDE with a backward
equation $-dY_t = f(t, X_t, Y_t, Z_t, \mathcal{L}(X_t, Y_t))\, dt - Z_t\, dW_t$ produces the
equation :math:`-dY_t = f(t, X_t, Y_t, Z_t, \mathcal{L}(X_t, Y_t))\, dt - Z_t\, dW_t` produces the
*mean-field BSDE* of Carmona–Delarue (2018), itself the probabilistic representation of the
HJB side of mean-field games (cf. :doc:`stochastic_control`).
Why it matters
--------------
* **Mean-field games.** At the Nash equilibrium of a symmetric $N$-player game, each player's
state follows a McKean–Vlasov SDE in which the population law $\mu_t$ is the consistent
* **Mean-field games.** At the Nash equilibrium of a symmetric :math:`N`-player game, each player's
state follows a McKean–Vlasov SDE in which the population law :math:`\mu_t` is the consistent
fixed point of every player's best response. This is the master tool of Lasry–Lions theory
for systemic-risk modelling, optimal execution and price formation.
* **Statistical physics.** Vlasov, Boltzmann, and granular-media equations all arise as
density flows of mean-field particle systems; the same Euler scheme estimates their solutions.
* **Generative modelling.** Stein-variational gradient descent and score-based diffusion can
be analysed as McKean–Vlasov gradient flows on $W_2$.
be analysed as McKean–Vlasov gradient flows on :math:`W_2`.
.. note::
📓 **Companion notebook** — `view on GitHub <https://github.com/ThotDjehuty/optimiz-rs/blob/main/examples/notebooks/14_mckean_vlasov.ipynb>`_
docs/source/algorithms/pde.rst
+19 -19
View File
@@ -10,7 +10,7 @@ Mathematical background
-----------------------
**Fokker–Planck (Kolmogorov forward).** For a 1-D Itô diffusion
$dX_t = \mu(t, x)\, dt + \sigma(t, x)\, dW_t$, the marginal density $\rho(t, x)$ of $X_t$
:math:`dX_t = \mu(t, x)\, dt + \sigma(t, x)\, dW_t`, the marginal density :math:`\rho(t, x)` of :math:`X_t`
satisfies the parabolic PDE
.. math::
@@ -19,15 +19,15 @@ satisfies the parabolic PDE
\;=\; \tfrac12\, \partial^2_{xx}\!\bigl(\sigma^2(t,x)\, \rho\bigr),
\qquad \rho(0, \cdot) = \rho_0 .
For the *pure-diffusion* test ($\mu \equiv 0$, $\sigma^2 \equiv 1$, $\rho_0 = \mathcal{N}(0, 1)$)
the analytic Gaussian heat kernel gives $\rho(t, x) = \frac{1}{\sqrt{2\pi(1+t)}}\exp\!\bigl(-\frac{x^2}{2(1+t)}\bigr)$,
so the variance grows linearly: $\mathrm{Var}(X_t) = 1 + t$. The conservative
For the *pure-diffusion* test (:math:`\mu \equiv 0`, :math:`\sigma^2 \equiv 1`, :math:`\rho_0 = \mathcal{N}(0, 1)`)
the analytic Gaussian heat kernel gives :math:`\rho(t, x) = \frac{1}{\sqrt{2\pi(1+t)}}\exp\!\bigl(-\frac{x^2}{2(1+t)}\bigr)`,
so the variance grows linearly: :math:`\mathrm{Var}(X_t) = 1 + t`. The conservative
Lax–Wendroff / centred-flux scheme implemented by `fokker_planck_constant` preserves total mass
(checked in the notebook to machine precision).
**Hamilton–Jacobi–Bellman.** Consider the controlled diffusion
$dX_t = \mu(X_t, \alpha_t)\, dt + \sigma(X_t)\, dW_t$ and the value function
$v(t, x) = \sup_\alpha \mathbb{E}_{t,x}\!\bigl[\int_t^T r(X_s, \alpha_s)\, ds + g(X_T)\bigr]$.
:math:`dX_t = \mu(X_t, \alpha_t)\, dt + \sigma(X_t)\, dW_t` and the value function
:math:`v(t, x) = \sup_\alpha \mathbb{E}_{t,x}\!\bigl[\int_t^T r(X_s, \alpha_s)\, ds + g(X_T)\bigr]`.
Dynamic programming produces
.. math::
@@ -41,24 +41,24 @@ Dynamic programming produces
heat-only relaxation case (:math:`H \equiv 0`, :math:`\sigma^2 > 0`) preserves a constant value while a
quadratic terminal :math:`g(x) = \tfrac12 \lVert x \rVert^2` smooths into a Gaussian-shaped value surface.
**Elliptic Poisson with zero Dirichlet boundary.** On the unit square $\Omega = (0,1)^2$,
**Elliptic Poisson with zero Dirichlet boundary.** On the unit square :math:`\Omega = (0,1)^2`,
.. math::
-\Delta u(x, y) = f(x, y) \text{ in } \Omega, \qquad u\!\restriction_{\partial\Omega} = 0 .
The Laplace eigenfunctions $\phi_{m,n}(x, y) = \sin(m\pi x)\sin(n\pi y)$ form an
orthonormal basis with eigenvalues $\lambda_{m,n} = (m^2 + n^2)\pi^2$, so for
$f = 2\pi^2 \sin(\pi x)\sin(\pi y)$ the *exact* solution is
$u(x, y) = \sin(\pi x)\sin(\pi y)$. `poisson_2d_zero_boundary` solves the 5-point stencil by
The Laplace eigenfunctions :math:`\phi_{m,n}(x, y) = \sin(m\pi x)\sin(n\pi y)` form an
orthonormal basis with eigenvalues :math:`\lambda_{m,n} = (m^2 + n^2)\pi^2`, so for
:math:`f = 2\pi^2 \sin(\pi x)\sin(\pi y)` the *exact* solution is
:math:`u(x, y) = \sin(\pi x)\sin(\pi y)`. `poisson_2d_zero_boundary` solves the 5-point stencil by
**Successive Over-Relaxation** with optimal relaxation parameter
$\omega^* = 2 / (1 + \sin(\pi h))$ for grid spacing $h = 1/(N-1)$, achieving spectral radius
$\rho \sim 1 - 2\pi h$ — i.e. $O(h^{-1})$ iterations to reach a fixed tolerance, against
$O(h^{-2})$ for plain Gauss–Seidel.
:math:`\omega^* = 2 / (1 + \sin(\pi h))` for grid spacing :math:`h = 1/(N-1)`, achieving spectral radius
:math:`\rho \sim 1 - 2\pi h` — i.e. :math:`O(h^{-1})` iterations to reach a fixed tolerance, against
:math:`O(h^{-2})` for plain Gauss–Seidel.
**Probabilistic representation (Feynman–Kac).** Both the parabolic HJB and the elliptic
Poisson PDE admit stochastic representations: $u(x) = \mathbb{E}_x\!\bigl[\int_0^{\tau_\Omega} f(X_s)\, ds\bigr]$
for the latter, where $\tau_\Omega$ is the first exit time of the diffusion from $\Omega$.
Poisson PDE admit stochastic representations: :math:`u(x) = \mathbb{E}_x\!\bigl[\int_0^{\tau_\Omega} f(X_s)\, ds\bigr]`
for the latter, where :math:`\tau_\Omega` is the first exit time of the diffusion from :math:`\Omega`.
This links the PDE solvers above to the BSDE primitives of :doc:`bsde`.
Why it matters
@@ -95,7 +95,7 @@ Fokker–Planck, HJB, Poisson.
Pure-diffusion Fokker–Planck
----------------------------
$\partial_t m = \tfrac12 \partial_{xx} m$ with Gaussian initial density should remain centred and approximately Gaussian.
:math:`\partial_t m = \tfrac12 \partial_{xx} m` with Gaussian initial density should remain centred and approximately Gaussian.
.. code-block:: python
@@ -140,7 +140,7 @@ $\partial_t m = \tfrac12 \partial_{xx} m$ with Gaussian initial density should r
2-D Poisson eigenfunction
-------------------------
$-\Delta u = 2\pi^2 \sin(\pi x)\sin(\pi y)$ on the unit square with zero Dirichlet boundary admits the exact solution $u(x,y) = \sin(\pi x)\sin(\pi y)$.
:math:`-\Delta u = 2\pi^2 \sin(\pi x)\sin(\pi y)` on the unit square with zero Dirichlet boundary admits the exact solution :math:`u(x,y) = \sin(\pi x)\sin(\pi y)`.
.. code-block:: python
@@ -183,7 +183,7 @@ $-\Delta u = 2\pi^2 \sin(\pi x)\sin(\pi y)$ on the unit square with zero Dirichl
2-D HJB with quadratic terminal
-------------------------------
Heat-only relaxation ($H = 0$, σ² > 0) preserves a constant value, while a quadratic terminal $g(x) = ½(x²+y²)$ smooths.
Heat-only relaxation (:math:`H = 0`, σ² > 0) preserves a constant value, while a quadratic terminal :math:`g(x) = ½(x²+y²)` smooths.
.. code-block:: python
docs/source/algorithms/quadratic_impact_control.rst
+18 -18
View File
@@ -7,7 +7,7 @@ problem with running quadratic *impact* penalty.
Mathematical background
-----------------------
Let $A_t$ be a controlled scalar state driven by an additive control $u_t$ and Gaussian noise.
Let :math:`A_t` be a controlled scalar state driven by an additive control :math:`u_t` and Gaussian noise.
The controller minimises the *finite-horizon quadratic objective*
.. math::
@@ -16,11 +16,11 @@ The controller minimises the *finite-horizon quadratic objective*
\;+\; \tfrac{\phi}{2}\, A_t^2 \,\bigr)\, dt
\;+\; \tfrac{A_T}{2}\, A_T^2 \,\right] ,
where $\gamma > 0$ is the **impact / control cost**, $\phi \ge 0$ the **running risk weight**
and $A_T$ the **terminal penalty** (over-loaded notation: $A_T$ here is the *coefficient*).
where :math:`\gamma > 0` is the **impact / control cost**, :math:`\phi \ge 0` the **running risk weight**
and :math:`A_T` the **terminal penalty** (over-loaded notation: :math:`A_T` here is the *coefficient*).
**Hamilton–Jacobi–Bellman.** With value function $v(t, A) = \tfrac12 h(t)\, A^2 + c(t)$, the
HJB equation collapses to a scalar Riccati ODE on $h$:
**Hamilton–Jacobi–Bellman.** With value function :math:`v(t, A) = \tfrac12 h(t)\, A^2 + c(t)`, the
HJB equation collapses to a scalar Riccati ODE on :math:`h`:
.. math::
@@ -34,15 +34,15 @@ The optimal feedback is the linear law
u^*(t, A) \;=\; -\, \frac{h(t)}{\gamma}\, A \;\equiv\; -\, k(t)\, A,
with *feedback gain* $k(t) = h(t) / \gamma$. This is the structure returned by the primitive.
with *feedback gain* :math:`k(t) = h(t) / \gamma`. This is the structure returned by the primitive.
**Closed-form solutions.**
* **Symmetric fixed point** $\gamma = \phi = A_T = 1$: $h(t) \equiv 1$ is the unique solution
(RHS vanishes), so the feedback gain is constant $k \equiv 1$. The notebook checks this
* **Symmetric fixed point** :math:`\gamma = \phi = A_T = 1`: :math:`h(t) \equiv 1` is the unique solution
(RHS vanishes), so the feedback gain is constant :math:`k \equiv 1`. The notebook checks this
to machine precision.
* **Generic $\phi > 0$.** Writing $\bar h = \sqrt{\gamma \phi}$ for the steady-state and
$\rho = \sqrt{\phi / \gamma}$, the Riccati ODE has the closed-form (separation of variables /
* **Generic :math:`\phi > 0`.** Writing :math:`\bar h = \sqrt{\gamma \phi}` for the steady-state and
:math:`\rho = \sqrt{\phi / \gamma}`, the Riccati ODE has the closed-form (separation of variables /
Bernoulli substitution)
.. math::
@@ -50,19 +50,19 @@ with *feedback gain* $k(t) = h(t) / \gamma$. This is the structure returned by
h(t) \;=\; \bar h\, \frac{(\bar h + A_T)\, e^{2\rho(T-t)} \;-\; (\bar h - A_T)}
{(\bar h + A_T)\, e^{2\rho(T-t)} \;+\; (\bar h - A_T)} .
In the limit $T - t \to \infty$ the trajectory relaxes to the stationary value $\bar h = \sqrt{\gamma\phi}$.
* **Free of running risk** $\phi = 0$. Then $h'(t) = h(t)^2/\gamma$ integrates explicitly to
In the limit :math:`T - t \to \infty` the trajectory relaxes to the stationary value :math:`\bar h = \sqrt{\gamma\phi}`.
* **Free of running risk** :math:`\phi = 0`. Then :math:`h'(t) = h(t)^2/\gamma` integrates explicitly to
.. math::
h(t) \;=\; \frac{A_T}{1 + (A_T / \gamma)(T - t)} ,
recovering the Pontryagin LQR closed form $P(0) = 1/2$ of :doc:`stochastic_control`.
recovering the Pontryagin LQR closed form :math:`P(0) = 1/2` of :doc:`stochastic_control`.
**Connection with mean-field games.** Coupling this single-agent control with an interacting
population — the running cost depending on the *average* control $\bar u_t$ — yields the
population — the running cost depending on the *average* control :math:`\bar u_t` — yields the
Almgren–Chriss MFG (Lasry–Lions 2007); at the Nash equilibrium the optimal trajectory is the
uniform schedule $\dot A^*_t = -A_0 / T$ (cf. Sec. 3 of Carmona–Delarue 2018, Vol. I).
uniform schedule :math:`\dot A^*_t = -A_0 / T` (cf. Sec. 3 of Carmona–Delarue 2018, Vol. I).
Why it matters
--------------
@@ -71,7 +71,7 @@ Why it matters
Riccati ODE; the closed form means *real-time* feedback re-computation.
* **Stochastic regulators.** Temperature stabilisation, attitude control, queueing-network
smoothing all map to a quadratic-impact problem with a single state.
* **Building block for higher-dimensional MPC.** Vector generalisations of $h(t)$ are matrix
* **Building block for higher-dimensional MPC.** Vector generalisations of :math:`h(t)` are matrix
Riccati ODEs; this scalar primitive is the verification kernel against which the matrix
solver in :doc:`matrix_riccati` is tested.
@@ -93,7 +93,7 @@ Why it matters
Riccati fixed-point check
-------------------------
$h'(t) = h(t)^2/γ - φ$ with $h(T) = A$. When $γ = φ = A = 1$ the right-hand side is $h^2 - 1 = 0$ at $h = 1$, so `h ≡ 1`.
:math:`h'(t) = h(t)^2/γ - φ` with :math:`h(T) = A`. When :math:`γ = φ = A = 1` the right-hand side is :math:`h^2 - 1 = 0` at :math:`h = 1`, so `h ≡ 1`.
.. code-block:: python
@@ -134,7 +134,7 @@ $h'(t) = h(t)^2/γ - φ$ with $h(T) = A$. When $γ = φ = A = 1$ the right-hand
Sensitivity to the terminal weight
----------------------------------
Vary $A$, fix $γ = 1$, $φ = 0.25$, $T = 1$.
Vary :math:`A`, fix :math:`γ = 1`, :math:`φ = 0.25`, :math:`T = 1`.
.. code-block:: python
docs/source/algorithms/robust_drift.rst
+16 -16
View File
@@ -8,16 +8,16 @@ Heavy-tail-resistant maximum-likelihood estimator for the discrete Ornstein–Uh
x_{k+1} \;=\; x_k \;+\; (a + b\, x_k)\, \Delta t \;+\; \sigma\, \sqrt{\Delta t}\, \varepsilon_k,
\qquad \varepsilon_k \sim_{\text{i.i.d.}} P_\varepsilon ,
where $P_\varepsilon$ is *contaminated*: a fraction $1 - \eta$ of standard Gaussian innovations
plus a fraction $\eta$ of large outliers (jumps, fat tails, recording errors).
where :math:`P_\varepsilon` is *contaminated*: a fraction :math:`1 - \eta` of standard Gaussian innovations
plus a fraction :math:`\eta` of large outliers (jumps, fat tails, recording errors).
Mathematical background
-----------------------
**Naive OLS.** Setting $y_k := (x_{k+1} - x_k)/\Delta t$, the model is the linear regression
$y_k = a + b\, x_k + \sigma\, \Delta t^{-1/2}\, \varepsilon_k$. Ordinary least-squares
minimises $\sum_k (y_k - a - b x_k)^2$ but its breakdown point is $0$: a single outlier with
$|\varepsilon_k| \gg 1$ moves the estimate arbitrarily far.
**Naive OLS.** Setting :math:`y_k := (x_{k+1} - x_k)/\Delta t`, the model is the linear regression
:math:`y_k = a + b\, x_k + \sigma\, \Delta t^{-1/2}\, \varepsilon_k`. Ordinary least-squares
minimises :math:`\sum_k (y_k - a - b x_k)^2` but its breakdown point is :math:`0`: a single outlier with
:math:`|\varepsilon_k| \gg 1` moves the estimate arbitrarily far.
**Huber loss & IRLS.** Huber (1964) replaces the quadratic loss by the *piecewise* loss
@@ -30,7 +30,7 @@ $|\varepsilon_k| \gg 1$ moves the estimate arbitrarily far.
\end{cases}
which is *quadratic in the bulk* and *linear in the tails*. The first-order condition
$\sum_k \psi_\delta(r_k)\, \nabla_{a,b}\, r_k = 0$ with $\psi_\delta = \rho_\delta'$ rewrites
:math:`\sum_k \psi_\delta(r_k)\, \nabla_{a,b}\, r_k = 0` with :math:`\psi_\delta = \rho_\delta'` rewrites
as a weighted least-squares problem with weights
.. math::
@@ -45,16 +45,16 @@ so the **Iteratively Reweighted Least-Squares** algorithm reads
\qquad w^{(t+1)}_k = \min\!\bigl(1, \delta / |r^{(t+1)}_k|\bigr).
The sequence converges geometrically when the design matrix is well-conditioned
(Holland–Welsch 1977). `robust_drift` returns the limit pair $(\widehat a, \widehat b)$ and
(Holland–Welsch 1977). `robust_drift` returns the limit pair :math:`(\widehat a, \widehat b)` and
the number of iterations.
**Choice of the cut-off.** The default $\delta = 1.345 \cdot \hat\sigma$ delivers $95\%$
**Choice of the cut-off.** The default :math:`\delta = 1.345 \cdot \hat\sigma` delivers :math:`95\%`
asymptotic efficiency under Gaussian innovations while keeping the influence function bounded;
it is the Huber–Hampel value used as the standard reference in robust statistics.
**Closed-form one-step (debiased OLS).** When the contamination is symmetric and the
innovations have finite variance $\sigma^2_\varepsilon$, the *consistent* one-step estimate at
the ordinary least-squares solution $(\hat a^0, \hat b^0)$ reads
innovations have finite variance :math:`\sigma^2_\varepsilon`, the *consistent* one-step estimate at
the ordinary least-squares solution :math:`(\hat a^0, \hat b^0)` reads
.. math::
@@ -63,12 +63,12 @@ the ordinary least-squares solution $(\hat a^0, \hat b^0)$ reads
\binom{\hat a^0}{\hat b^0}
\;+\; \bigl(X^\top W X\bigr)^{-1}\, X^\top \psi_\delta(r^0),
where $X$ is the $(N - 1) \times 2$ design matrix and $W = \mathrm{diag}(w_k)$. Bahadur
linearisation shows $\widehat\theta - \theta^\star = O_P(N^{-1/2})$ even in the contaminated
model, with asymptotic variance $\sigma^2_\psi / I^2_\psi$ (Huber, *Robust Statistics*, 2004,
where :math:`X` is the :math:`(N - 1) \times 2` design matrix and :math:`W = \mathrm{diag}(w_k)`. Bahadur
linearisation shows :math:`\widehat\theta - \theta^\star = O_P(N^{-1/2})` even in the contaminated
model, with asymptotic variance :math:`\sigma^2_\psi / I^2_\psi` (Huber, *Robust Statistics*, 2004,
Thm. 7.7).
**Connection with Malliavin calculus.** The driver $a + b\, x$ is exactly the linearised
**Connection with Malliavin calculus.** The driver :math:`a + b\, x` is exactly the linearised
drift of the Ornstein–Uhlenbeck process used in the Greeks formulae of
:doc:`stochastic_control` and the Vasicek interest-rate model; robust calibration is the
pre-requisite for any Monte-Carlo Greeks computation under noisy historical data.
@@ -79,7 +79,7 @@ Why it matters
* **Heavy-tailed historical data.** Crypto returns, electricity prices, plasma confinement
signals, and bio-medical recordings all contain spikes that destroy OLS but leave Huber
estimates within statistical noise.
* **Online & streaming estimation.** IRLS with $\sim 10$ iterations is real-time on streaming
* **Online & streaming estimation.** IRLS with :math:`\sim 10` iterations is real-time on streaming
windows and exposes a stable derivative for downstream control loops.
* **Robust risk management.** Replacing raw OLS by IRLS in any volatility / mean-reversion
estimator dramatically reduces *parameter risk* in stress periods.
docs/source/algorithms/stochastic_control.rst
+15 -15
View File
@@ -9,9 +9,9 @@ intensity controller** for jump processes.
Mathematical background
-----------------------
**1. Optimal switching as a Snell envelope.** Let $(Y^i_k)_{k, i}$ be the running rewards in
mode $i \in \{1, \dots, M\}$ and $c_{ij}$ the cost of switching from $i$ to $j$. The value
function $V_k(i)$ satisfies the backward dynamic-programming recursion
**1. Optimal switching as a Snell envelope.** Let :math:`(Y^i_k)_{k, i}` be the running rewards in
mode :math:`i \in \{1, \dots, M\}` and :math:`c_{ij}` the cost of switching from :math:`i` to :math:`j`. The value
function :math:`V_k(i)` satisfies the backward dynamic-programming recursion
.. math::
@@ -20,22 +20,22 @@ function $V_k(i)$ satisfies the backward dynamic-programming recursion
V_k(i) \;=\; Y^i_k \;+\; \max_{j}\!\bigl( V_{k+1}(j) - c_{ij}\bigr).
This is the *multi-mode Snell envelope* of El Karoui–Quenez (1995). When switching is free
($c_{ij} = 0$) and only mode 1 pays a unit reward at every period, $V_k(i) = N - k$ for
$i \neq 1$ and $V_k(1) = N - k + 1$ — reproduced exactly by `optimal_switching_dp`.
(:math:`c_{ij} = 0`) and only mode 1 pays a unit reward at every period, :math:`V_k(i) = N - k` for
:math:`i \neq 1` and :math:`V_k(1) = N - k + 1` — reproduced exactly by `optimal_switching_dp`.
**2. Pontryagin–Bismut maximum principle (LQR).** For the controlled SDE
$dX_t = (a X_t + b u_t)\, dt + \sigma\, dW_t$ with quadratic cost
$J(u) = \mathbb{E}\!\bigl[\int_0^T (q X_t^2 + r u_t^2)\, dt + s_T X_T^2\bigr]$, the
adjoint variable $P_t$ solves the **matrix Riccati ODE**
:math:`dX_t = (a X_t + b u_t)\, dt + \sigma\, dW_t` with quadratic cost
:math:`J(u) = \mathbb{E}\!\bigl[\int_0^T (q X_t^2 + r u_t^2)\, dt + s_T X_T^2\bigr]`, the
adjoint variable :math:`P_t` solves the **matrix Riccati ODE**
.. math::
\dot P_t \;+\; 2 a\, P_t \;-\; \frac{b^2}{r}\, P_t^2 \;+\; q \;=\; 0,
\qquad P_T = s_T,
and the optimal feedback is $u^*_t = -(b/r)\, P_t\, X_t$. In the canonical case
$a = q = 0$, $b = r = s_T = 1$, $T = 1$ the ODE simplifies to
$\dot P_t = P_t^2$, whose closed-form solution is
and the optimal feedback is :math:`u^*_t = -(b/r)\, P_t\, X_t`. In the canonical case
:math:`a = q = 0`, :math:`b = r = s_T = 1`, :math:`T = 1` the ODE simplifies to
:math:`\dot P_t = P_t^2`, whose closed-form solution is
.. math::
@@ -43,8 +43,8 @@ $\dot P_t = P_t^2$, whose closed-form solution is
\qquad
P(0) = \tfrac12 .
The primitive `pontryagin_lqr` reproduces this with relative error below $10^{-3}$ for
$N = 2000$ steps (the symmetric Strang splitting is second-order in $\Delta t$).
The primitive `pontryagin_lqr` reproduces this with relative error below :math:`10^{-3}` for
:math:`N = 2000` steps (the symmetric Strang splitting is second-order in :math:`\Delta t`).
**3. Two-sided intensity control.** For a jump-controller the agent picks the rates
:math:`\lambda_\pm \ge 0` at which up/down events fire. With *affine premia*
@@ -72,7 +72,7 @@ Why it matters
* **Optimal switching** powers production-mode selection (start/stop a power plant), regime
changes in algorithmic strategies, and American-style option pricing (Carmona–Touzi 2008).
* **Pontryagin LQR** is the linearised core of every continuous-control problem: target
tracking, Kalman-LQG, ground-up RL, robust $H_\infty$ design.
tracking, Kalman-LQG, ground-up RL, robust :math:`H_\infty` design.
* **Two-sided intensity control** is the closed-form heart of optimal market making
(Avellaneda–Stoikov 2008, Cartea–Jaimungal–Penalva 2015) and limit-order placement.
@@ -136,7 +136,7 @@ Two modes; only mode 1 pays a unit reward. Free switching should give `V_0(0) =
Pontryagin 1-D LQR
------------------
Closed-form Riccati for $a=q=0$, $b=r=s_T=1$, $T=1$ is $P(t) = 1/(1 + (T - t))$, hence $P(0) = 0.5$.
Closed-form Riccati for :math:`a=q=0`, :math:`b=r=s_T=1`, :math:`T=1` is :math:`P(t) = 1/(1 + (T - t))`, hence :math:`P(0) = 0.5`.
.. code-block:: python