ThotDjehuty
cce31055c1
Add scripts/inject_doc_plots.py that scans every .md and .rst page under docs/source/, executes each Python code-block in an isolated namespace with a non-interactive matplotlib backend, captures every figure produced, and inserts an inline image directive immediately after the code-block. Markers AUTO-PLOT-BEGIN/END make the injection idempotent on re-runs. Blocks that fail to execute or produce no figure are left untouched. Add a transparent __getattr__ fallback in python/optimizr/__init__.py that forwards any unresolved top-level attribute to the compiled _core extension. This lets all v1.x and v2.0 doc samples that use 'from optimizr import X' (estimate_ou_params_py, linear_bsde_constant_coeffs, mmd_gaussian, ...) execute as written. Augment the OU Parameter Estimation example (docs/source/algorithms/optimal_control.md) with a two-panel visualization (simulated path plus empirical/theoretical autocorrelation). Net effect: 14 doc pages now display matplotlib plots inline directly under the code that produced them -- including the OU page, point processes, Grid Search, HMM, MCMC, plus the 8 v2.0 RST pages.
87 lines
2.6 KiB
ReStructuredText
87 lines
2.6 KiB
ReStructuredText
Generative calibration — Gaussian MMD loss
|
||
==========================================
|
||
|
||
Maximum-Mean-Discrepancy distance with Gaussian kernel (`mmd_gaussian`). Self-distance is exactly zero; the metric grows monotonically with sample shift.
|
||
|
||
.. note:: Companion executed notebook: `17_generative_calibration.ipynb <../../examples/notebooks/17_generative_calibration.ipynb>`_
|
||
|
||
17 — MMD calibration loss
|
||
=========================
|
||
|
||
.. code-block:: python
|
||
|
||
import numpy as np
|
||
import matplotlib.pyplot as plt
|
||
from optimizr import _core as opt
|
||
plt.rcParams['figure.figsize'] = (7, 4)
|
||
plt.rcParams['figure.dpi'] = 110
|
||
|
||
.. code-block:: python
|
||
|
||
x = np.linspace(0.0, 5.0, 80)
|
||
shifts = np.linspace(0.0, 6.0, 40)
|
||
d = [opt.mmd_gaussian(x.tolist(), (x + s).tolist(), 1.0) for s in shifts]
|
||
print('MMD self =', d[0])
|
||
print('MMD at shift 6.0 =', d[-1])
|
||
|
||
.. code-block:: python
|
||
|
||
fig, ax = plt.subplots()
|
||
ax.plot(shifts, d, lw=2)
|
||
ax.set_xlabel('translation Δ'); ax.set_ylabel('MMD(P, P + Δ)')
|
||
ax.set_title('Gaussian-kernel MMD vs translation (σ = 1)')
|
||
ax.grid(alpha=0.3); fig.tight_layout(); plt.show()
|
||
|
||
|
||
|
||
|
||
|
||
.. AUTO-PLOT-BEGIN
|
||
.. image:: ../_static/auto/algorithms__generative_calibration_hooks/block_03_fig_01.png
|
||
:align: center
|
||
:width: 80%
|
||
|
||
.. AUTO-PLOT-END
|
||
.. image:: ../_static/v2/generative_calibration_hooks/plot_01.png
|
||
:align: center
|
||
:width: 80%
|
||
|
||
Bandwidth dependence
|
||
--------------------
|
||
|
||
.. code-block:: python
|
||
|
||
fig, ax = plt.subplots()
|
||
for sigma in [0.25, 0.5, 1.0, 2.0]:
|
||
d = [opt.mmd_gaussian(x.tolist(), (x + s).tolist(), sigma) for s in shifts]
|
||
ax.plot(shifts, d, label=f'σ = {sigma:g}')
|
||
ax.set_xlabel('translation Δ'); ax.set_ylabel('MMD'); ax.legend(); ax.grid(alpha=0.3)
|
||
ax.set_title('MMD as a function of kernel bandwidth')
|
||
fig.tight_layout(); plt.show()
|
||
|
||
|
||
|
||
|
||
|
||
.. AUTO-PLOT-BEGIN
|
||
.. image:: ../_static/auto/algorithms__generative_calibration_hooks/block_04_fig_01.png
|
||
:align: center
|
||
:width: 80%
|
||
|
||
.. AUTO-PLOT-END
|
||
.. image:: ../_static/v2/generative_calibration_hooks/plot_02.png
|
||
:align: center
|
||
:width: 80%
|
||
|
||
**Verified:** `MMD(x, x) = 0`; metric is strictly monotonic in shift.
|
||
|
||
API
|
||
---
|
||
|
||
.. code-block:: rust
|
||
|
||
pub fn mmd_distance(x: &[f64], y: &[f64], loss: &MmdLoss) -> Result<f64>;
|
||
pub fn calibration_step<S: GenerativeSampler>(sampler: &mut S, target: &[f64], loss: &MmdLoss, lr: f64) -> Result<f64>;
|
||
pub trait GenerativeSampler { fn sample(&self, n: usize, seed: u64) -> Vec<f64>; fn parameters(&self) -> Vec<f64>; fn perturb(&mut self, deltas: &[f64]); }
|
||
pub struct MmdLoss { pub sigma: f64 }
|