Update examples and docs

.gitignore

@@ -188,4 +188,6 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 .idea/
-/docs/source/
+
+# Dataset cached at runtime by the introductory notebook
+mcycle.csv

AGENTS.md

@@ -63,17 +63,17 @@ ruff format ptgp/ tests/
 python scripts/joint_graph_analysis.py        # op-count tables per model, with/without ptgp rewrites
 python scripts/inplace_audit.py               # which linalg ops are inplace and why others aren't
 
-# execute the demo notebook in place
+# execute the introduction notebook in place
 python -m jupyter nbconvert --to notebook --execute --inplace \
-    notebooks/demo.ipynb --ExecutePreprocessor.kernel_name=ptgp
+    notebooks/introduction/introduction.ipynb --ExecutePreprocessor.kernel_name=ptgp
 
 # install the bundled agent-skill docs into a Claude Code skill dir (optional)
 python scripts/install_claude_skills.py --project .   # ./.claude/skills/
 python scripts/install_claude_skills.py --user        # ~/.claude/skills/
 ```
 
 The reference usage example for all three models is
-[`notebooks/demo.ipynb`](notebooks/demo.ipynb).
+[`notebooks/introduction/introduction.ipynb`](notebooks/introduction/introduction.ipynb).
 
 ## Where things live
 

README.md

@@ -54,7 +54,7 @@ with pm.Model() as model:
 mean, var = pg.predict(svgp, np.linspace(-3, 3, 100)[:, None], fit)
 ```
 
-`pg.fit` picks a default objective from the gp type (`Unapproximated` → `marginal_log_likelihood`, `VFE` → `collapsed_elbo`, `SVGP` → `elbo`) and returns a `FitResult` that `pg.predict` consumes. For stochastic mini-batch training, staged VFE, or per-group learning rates, drop down to `pg.optim.compile_training_step` / `pg.optim.compile_scipy_objective` — see [`notebooks/demo.ipynb`](notebooks/demo.ipynb):
+`pg.fit` picks a default objective from the gp type (`Unapproximated` → `marginal_log_likelihood`, `VFE` → `collapsed_elbo`, `SVGP` → `elbo`) and returns a `FitResult` that `pg.predict` consumes. For stochastic mini-batch training, staged VFE, or per-group learning rates, drop down to `pg.optim.compile_training_step` / `pg.optim.compile_scipy_objective` — see [`notebooks/introduction/introduction.ipynb`](notebooks/introduction/introduction.ipynb):
 
 ```python
 X_var = pt.matrix("X")
@@ -73,7 +73,7 @@ predict_fn = pg.optim.compile_predict(
 mean, var = predict_fn(np.linspace(-3, 3, 100)[:, None])
 ```
 
-Training uses MAP by default: the PyMC log-prior is added to the objective. Pass `include_prior=False` for pure ELBO. For exact GPs and VFE, use `compile_scipy_objective` with L-BFGS-B instead. See [`notebooks/demo.ipynb`](notebooks/demo.ipynb) for end-to-end examples covering all three models.
+Training uses MAP by default: the PyMC log-prior is added to the objective. Pass `include_prior=False` for pure ELBO. For exact GPs and VFE, use `compile_scipy_objective` with L-BFGS-B instead. See [`notebooks/introduction/introduction.ipynb`](notebooks/introduction/introduction.ipynb) for end-to-end examples covering all three models.
 
 ## How it works
 

conda_envs/environment-docs.yaml

@@ -28,7 +28,7 @@ dependencies:
     - sphinx-notfound-page
     - sphinx-autobuild
     - jupyter-sphinx
-    - sphinxcontrib-bibtex
+    - pybtex  # .bib parsing for the simplebib extension (docs/sphinxext/simplebib.py)
     - pip
     - pip:
         - git+https://github.com/pymc-devs/pytensor@main

docs/.gitignore

@@ -14,6 +14,7 @@ source/api/**/classmethods/
 # Notebook gallery artifacts written by docs/sphinxext/generate_gallery.py
 source/examples/gallery.rst
 source/examples/examples/
+source/examples/introduction/
 source/examples/introductory/
 source/examples/advanced/
 source/examples/case_study/

docs/source/_static/custom.css

@@ -0,0 +1,34 @@
+/* Per-page citations (simplebib): superscript [n] markers linking down to a
+   numbered reference list, with a subtle back-reference arrow on each entry. */
+
+a.simplebib-cite {
+    vertical-align: super;
+    font-size: 0.7em;
+    line-height: 0;
+    padding: 0 0.1em;
+    font-weight: 500;
+    white-space: nowrap;
+    text-decoration: none;
+}
+
+a.simplebib-cite:hover {
+    text-decoration: underline;
+}
+
+a.simplebib-backref {
+    margin-left: 0.4em;
+    text-decoration: none;
+    opacity: 0.6;
+}
+
+a.simplebib-backref:hover {
+    opacity: 1;
+}
+
+.simplebib-references {
+    margin-top: 0.5em;
+}
+
+.simplebib-references .simplebib-reference {
+    margin-bottom: 0.4em;
+}

docs/source/api/kernels.rst

@@ -28,6 +28,7 @@ Non-stationary
 .. autosummary::
     :toctree: generated/
 
+    Linear
     Gibbs
     RandomWalk
     WarpedInput

docs/source/api/optim.rst

@@ -3,6 +3,16 @@ Optimization
 
 .. currentmodule:: ptgp.optim
 
+High-level API
+--------------
+
+.. autosummary::
+    :toctree: generated/
+
+    fit
+    predict
+    FitResult
+
 Training compilers
 ------------------
 

docs/source/conf.py

@@ -48,16 +48,15 @@
     "sphinx_sitemap",
     "notfound.extension",
     "jupyter_sphinx",
-    "sphinxcontrib.bibtex",
+    "simplebib",
     "generate_gallery",
     "generate_kernel_gallery",
 ]
 
-# Bibliographic citations: drop new entries into docs/source/references.bib
-# and cite from prose with `{cite:t}` (textual) or `{cite:p}` (parenthetical).
-bibtex_bibfiles = ["references.bib"]
-bibtex_default_style = "unsrt"
-bibtex_reference_style = "author_year"
+# Bibliographic citations: drop new entries into docs/source/references.bib and
+# cite from prose with `{cite:t}` / `{cite:p}`. Each page renders its own numbered
+# reference list via `{bibliography}` (see docs/sphinxext/simplebib.py).
+simplebib_bibfiles = ["references.bib"]
 
 # Use the document path as prefix for autosectionlabel anchors so the same
 # section title in two files doesn't collide.
@@ -155,6 +154,7 @@
 
 html_sidebars = {"**": ["sidebar-nav-bs.html", "searchbox.html"]}
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 
 # -- MyST / MyST-NB config ---------------------------------------------------
 myst_enable_extensions = [

docs/source/dev/docs.rst

@@ -62,7 +62,7 @@ commit anything under ``source/kernels/img/``, ``source/_thumbnails/``,
 ``source/examples/<category>/``, ``source/api/**/generated/``, or
 ``source/kernels/gallery.rst`` / ``source/examples/gallery.rst``.
 
-The two custom Sphinx extensions live at ``docs/sphinxext/``:
+The custom Sphinx extensions live at ``docs/sphinxext/``:
 
 * ``generate_gallery.py`` — discovers notebooks under ``notebooks/``, copies
   them into ``docs/source/examples/<category>/``, extracts thumbnails, and
@@ -71,6 +71,12 @@ The two custom Sphinx extensions live at ``docs/sphinxext/``:
   ``KERNEL_RECIPES``, emits ``kernels/gallery.rst`` with grid cards. Cards
   link to per-kernel pages when a matching ``kernels/gallery/<slug>.md``
   exists on disk.
+* ``simplebib.py`` — per-page citations. Provides the ``{cite:t}`` /
+  ``{cite:p}`` roles and the ``{bibliography}`` directive, parsing
+  ``references.bib`` with :mod:`pybtex`. Each page is self-contained: its
+  citations render as numbered ``[n]`` footnotes that link down to a numbered
+  reference list on the same page, so numbering and anchors never collide
+  across pages.
 
 Adding a new kernel to the covariance gallery
 ---------------------------------------------
@@ -145,26 +151,29 @@ Adding a citation
 -----------------
 
 Append the BibTeX entry to ``docs/source/references.bib``, then cite from
-prose with either textual or parenthetical form:
+prose with ``{cite:t}`` or ``{cite:p}`` (both render as a numbered footnote
+marker):
 
 .. code-block:: markdown
 
     The kernel ridge regression view is discussed by {cite:t}`somekey-2024`.
     This approach goes back decades {cite:p}`smith-1985`.
 
-Each page that uses citations should also include a per-page bibliography:
+End each page that cites anything with a ``{bibliography}`` directive, which
+renders the numbered reference list for that page:
 
 .. code-block:: markdown
 
+    ## References
+
     ```{bibliography}
-    :filter: docname in docnames
     ```
 
-The ``:filter: docname in docnames`` clause restricts the rendered
-bibliography to entries cited on the current page. Sphinx will emit
-"duplicate citation" warnings when the same key is rendered from multiple
-pages — these are tolerated; we prefer per-page bibliographies for
-readability.
+Citations are handled by the ``simplebib`` extension and are page-local:
+``{bibliography}`` lists only the works cited on that page, numbered in
+citation order, and the in-text markers link down to it. There is no central
+bibliography page and no cross-page numbering, so the same key can be cited on
+any number of pages without collisions.
 
 Plot helpers
 ------------

docs/source/kernels/gallery/expquad.md

@@ -11,7 +11,7 @@ kernelspec:
 
 # Exponentiated Quadratic Kernel
 
-[Stationary](../gallery_tags.rst#stationary), [Isotropic](../gallery_tags.rst#isotropic), [Smooth](../gallery_tags.rst#smooth), [Universal](../gallery_tags.rst#universal)
+{ref}`Stationary <stationary>`, {ref}`Isotropic <isotropic>`, {ref}`Smooth <smooth>`, {ref}`Universal <universal>`
 
 The exponentiated quadratic kernel — also known as the **squared exponential**, **RBF**, or **Gaussian** kernel — measures covariance with the squared Euclidean distance between inputs, decaying as a Gaussian in distance. It is the default first choice in most GP applications.
 
@@ -126,5 +126,4 @@ The three lengthscales show the kernel's effect on prior beliefs:
 The exponentiated quadratic is the canonical GP covariance and is discussed across all standard treatments; {cite:t}`rasmussen-williams-2006` Chapter 4 is the standard reference.
 
 ```{bibliography}
-:filter: docname in docnames
 ```

docs/source/kernels/gallery/linear.md

@@ -11,7 +11,7 @@ kernelspec:
 
 # Linear Kernel
 
-[Non-stationary](../gallery_tags.rst#non-stationary), [Isotropic](../gallery_tags.rst#isotropic)
+{ref}`Non-stationary <non-stationary>`, {ref}`Isotropic <isotropic>`
 
 The linear (dot-product) kernel produces sample functions that are straight lines through the center point $c$. It is the GP equivalent of Bayesian linear regression: the posterior mean is a linear function of the inputs and the posterior variance reflects uncertainty in the slope.
 
@@ -109,5 +109,4 @@ The three centers show the kernel's effect on prior beliefs:
 The linear kernel and its connection to Bayesian linear regression are discussed in {cite:t}`rasmussen-williams-2006` Chapter 2.
 
 ```{bibliography}
-:filter: docname in docnames
 ```

docs/source/kernels/gallery/matern12.md

@@ -11,7 +11,7 @@ kernelspec:
 
 # Matérn 1/2 (Exponential) Kernel
 
-[Stationary](../gallery_tags.rst#stationary), [Isotropic](../gallery_tags.rst#isotropic), [Very Rough](../gallery_tags.rst#very-rough)
+{ref}`Stationary <stationary>`, {ref}`Isotropic <isotropic>`, {ref}`Very Rough <very-rough>`
 
 The Matérn 1/2 kernel — also known as the **exponential kernel** — produces sample functions that are continuous but nowhere differentiable. The resulting GP is equivalent to an Ornstein–Uhlenbeck process: a mean-reverting random walk in continuous time. Sample paths look like noisy zig-zag trajectories rather than smooth curves.
 
@@ -121,5 +121,4 @@ print(K.shape, K.diagonal()[:3])
 The Matérn family and its smoothness-tuning role in GP modeling is discussed in {cite:t}`rasmussen-williams-2006` Chapter 4.
 
 ```{bibliography}
-:filter: docname in docnames
 ```

docs/source/kernels/gallery/matern32.md

@@ -11,7 +11,7 @@ kernelspec:
 
 # Matérn 3/2 Kernel
 
-[Stationary](../gallery_tags.rst#stationary), [Isotropic](../gallery_tags.rst#isotropic), [Rough](../gallery_tags.rst#rough)
+{ref}`Stationary <stationary>`, {ref}`Isotropic <isotropic>`, {ref}`Rough <rough>`
 
 The Matérn 3/2 kernel produces sample functions that are once mean-square differentiable but no smoother — the function itself and its first derivative exist and are continuous, but the second derivative does not. This is the right kernel when the process you are modeling has a clearly defined velocity but acceleration is a meaningless concept (e.g. abrupt regime changes, piecewise-linear-ish behavior on small scales).
 
@@ -121,5 +121,4 @@ print(K.shape, K.diagonal()[:3])
 The Matérn family and its smoothness-tuning role in GP modeling is discussed in {cite:t}`rasmussen-williams-2006` Chapter 4.
 
 ```{bibliography}
-:filter: docname in docnames
 ```

docs/source/kernels/gallery/matern52.md

@@ -11,7 +11,7 @@ kernelspec:
 
 # Matérn 5/2 Kernel
 
-[Stationary](../gallery_tags.rst#stationary), [Isotropic](../gallery_tags.rst#isotropic), [Smooth](../gallery_tags.rst#smooth)
+{ref}`Stationary <stationary>`, {ref}`Isotropic <isotropic>`, {ref}`Smooth <smooth>`
 
 The Matérn 5/2 kernel is the smoothest member of the Matérn family that is *not* infinitely differentiable. Sample functions are twice mean-square differentiable — the function and its first derivative are well-defined and continuous, but the curvature can have jumps. This is enough smoothness for most real-world processes and avoids the overconfident extrapolation that the [exponentiated quadratic](expquad.md) tends to produce when the true function is not analytic.
 
@@ -121,5 +121,4 @@ print(K.shape, K.diagonal()[:3])
 The Matérn family and its smoothness-tuning role in GP modeling is discussed in {cite:t}`rasmussen-williams-2006` Chapter 4.
 
 ```{bibliography}
-:filter: docname in docnames
 ```

docs/source/kernels/gallery/randomwalk.md

@@ -11,7 +11,7 @@ kernelspec:
 
 # Random Walk Kernel
 
-[Non-stationary](../gallery_tags.rst#non-stationary), [1-D](../gallery_tags.rst#one-d), [Rough](../gallery_tags.rst#rough)
+{ref}`Non-stationary <non-stationary>`, {ref}`1-D <one-d>`, {ref}`Rough <rough>`
 
 The random walk kernel — the covariance function of standard Brownian motion (the Wiener process) — is the textbook example of a non-stationary GP kernel. Its covariance depends not just on the distance between inputs but on their actual locations: $k(x, y) = \min(x, y)$ means that variance grows linearly with the input value, and two points are correlated only via their shared "history" from the origin.
 
@@ -99,5 +99,4 @@ Prior samples fan out from the origin; the posterior pinches around each observa
 The random walk kernel and the broader connection between GPs and stochastic processes are covered in {cite:t}`rasmussen-williams-2006` Chapter 4.
 
 ```{bibliography}
-:filter: docname in docnames
 ```

docs/source/kernels/gallery_tags.md

@@ -0,0 +1,48 @@
+---
+orphan: true
+---
+
+(gallery-tags)=
+# Kernel property tags
+
+The covariance gallery labels each kernel with the properties below. Follow a tag from any kernel page to its definition here.
+
+(stationary)=
+## Stationary
+
+The covariance $k(x, y)$ depends only on the separation $x - y$, so it is invariant to shifting both inputs by the same amount. The prior variance $k(x, x)$ is then constant across the whole input space.
+
+(non-stationary)=
+## Non-stationary
+
+The covariance depends on where the inputs sit, not just on their separation. The prior variance and correlation length can vary across the input space.
+
+(isotropic)=
+## Isotropic
+
+The covariance depends only on the distance $\lVert x - y \rVert$ between inputs, so it is invariant to rotation as well as translation. A single lengthscale controls correlation in every direction.
+
+(smooth)=
+## Smooth
+
+Sample functions are several times mean-square differentiable, giving very regular draws. The exponentiated quadratic is infinitely differentiable; the Matérn 5/2 kernel is twice differentiable.
+
+(rough)=
+## Rough
+
+Sample functions are at most once mean-square differentiable, giving visibly jagged draws. Examples are the Matérn 3/2 kernel and the random walk.
+
+(very-rough)=
+## Very Rough
+
+Sample functions are continuous but nowhere differentiable, as with the exponential (Matérn 1/2) kernel.
+
+(one-d)=
+## 1-D
+
+Defined for a single input dimension only.
+
+(universal)=
+## Universal
+
+The kernel's reproducing-kernel Hilbert space is dense in the continuous functions, so it can approximate any continuous target arbitrarily well. The exponentiated quadratic is the canonical example.

docs/source/references.bib

@@ -6,3 +6,25 @@ @book{rasmussen-williams-2006
     isbn      = {026218253X},
     url       = {http://www.gaussianprocess.org/gpml/},
 }
+
+@inproceedings{titsias-2009,
+    author    = {Titsias, Michalis K.},
+    title     = {Variational Learning of Inducing Variables in Sparse Gaussian Processes},
+    booktitle = {Proceedings of the Twelfth International Conference on Artificial Intelligence and Statistics (AISTATS)},
+    series    = {Proceedings of Machine Learning Research},
+    volume    = {5},
+    pages     = {567--574},
+    year      = {2009},
+    url       = {https://proceedings.mlr.press/v5/titsias09a.html},
+}
+
+@article{burt-2020,
+    author  = {Burt, David R. and Rasmussen, Carl Edward and van der Wilk, Mark},
+    title   = {Convergence of Sparse Variational Inference in Gaussian Processes Regression},
+    journal = {Journal of Machine Learning Research},
+    volume  = {21},
+    number  = {131},
+    pages   = {1--63},
+    year    = {2020},
+    url     = {https://jmlr.org/papers/v21/19-1015.html},
+}