diff --git a/README.md b/README.md
index 961d5ca3..e6ce2945 100644
--- a/README.md
+++ b/README.md
@@ -29,9 +29,9 @@ With the same number of points, adaptive sampling resolves features that a homog
-
-
-
+
+
+
## Example
@@ -175,7 +175,9 @@ uv run --group docs python docs/build_notebooks.py
uv run --group docs zensical serve # preview on http://localhost:8000
```
-The README animations are made from real learner runs with `uv run --group docs python docs/make_animations.py`, which needs `ffmpeg` and Chrome or Chromium.
+The README animations and the animated logo are made from real learner runs by `uv run --group docs python docs/make_animations.py`, which needs `ffmpeg` and Chrome or Chromium (`uv run --group docs plotly_get_chrome` installs one).
+They are not version controlled: the Read the Docs build renders them, and the README links to those copies.
+Run the script once before `zensical serve` to see them locally.
## Citing
diff --git a/docs/.gitignore b/docs/.gitignore
index 65a4396f..0cb31c39 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -5,3 +5,6 @@
*.ipynb
# Written by notebooks during execution
/notebooks/tutorial/data/
+# Rendered by docs/make_animations.py during the docs build
+/_static/readme/
+/_static/logo_docs.webm
diff --git a/docs/_static/logo_docs.webm b/docs/_static/logo_docs.webm
deleted file mode 100644
index 43f23a67..00000000
Binary files a/docs/_static/logo_docs.webm and /dev/null differ
diff --git a/docs/_static/readme/learner1d.gif b/docs/_static/readme/learner1d.gif
deleted file mode 100644
index 41c2b0b3..00000000
Binary files a/docs/_static/readme/learner1d.gif and /dev/null differ
diff --git a/docs/_static/readme/learner2d.gif b/docs/_static/readme/learner2d.gif
deleted file mode 100644
index 4988aecf..00000000
Binary files a/docs/_static/readme/learner2d.gif and /dev/null differ
diff --git a/docs/_static/readme/learnerND.gif b/docs/_static/readme/learnerND.gif
deleted file mode 100644
index df370d6c..00000000
Binary files a/docs/_static/readme/learnerND.gif and /dev/null differ
diff --git a/docs/make_animations.py b/docs/make_animations.py
index 846e2c90..0c27f87f 100644
--- a/docs/make_animations.py
+++ b/docs/make_animations.py
@@ -1,8 +1,10 @@
"""Render the README animations and the animated docs logo from real learner runs.
Writes docs/_static/readme/{learner1d,learner2d,learnerND}.gif and
-docs/_static/logo_docs.webm. Needs ffmpeg, and Chrome or Chromium for kaleido
-(set BROWSER_PATH if it is not found).
+docs/_static/logo_docs.webm, which are not version controlled: the Read the
+Docs build renders them and the README links to the copies on Read the Docs.
+Needs ffmpeg, and Chrome or Chromium for kaleido (set BROWSER_PATH if it is not
+found, or install one with ``plotly_get_chrome``).
Usage: python docs/make_animations.py [learner1d learner2d learnerND logo]
"""
@@ -13,6 +15,7 @@
import sys
import tempfile
from collections.abc import Callable
+from concurrent.futures import ProcessPoolExecutor
from pathlib import Path
import matplotlib
@@ -26,7 +29,6 @@
import adaptive # noqa: E402
from adaptive.learner.learner1D import uniform_loss # noqa: E402
-from adaptive.learner.learner2D import uniform_loss as uniform_loss_2d # noqa: E402
STATIC = Path(__file__).parent / "_static"
DARK, ACCENT, NEW = "#2c3e6b", "#21918c", "#e4572e"
@@ -147,25 +149,42 @@ def _triangles(ax, points, values, vmin, vmax, edge_color):
ax.axis("off")
+def _square_grid(ax, k, vmin, vmax):
+ """Evaluate ``ring`` on a k × k grid and draw its cells."""
+ x = np.linspace(-1, 1, k)
+ X, Y = np.meshgrid(x, x)
+ ax.pcolormesh(
+ X, Y, ring((X, Y)), shading="gouraud", cmap="viridis", vmin=vmin, vmax=vmax
+ )
+ ax.vlines(x, -1, 1, color="white", lw=0.35, alpha=0.7)
+ ax.hlines(x, -1, 1, color="white", lw=0.35, alpha=0.7)
+ ax.set_xlim(-1, 1)
+ ax.set_ylim(-1, 1)
+ ax.set_aspect("equal")
+ ax.axis("off")
+
+
def learner2d(target: Path) -> None:
- bounds = ((-1, 1), (-1, 1))
- points, values = sampled(adaptive.Learner2D(ring, bounds), npoints_goal=1600)
- uniform = adaptive.Learner2D(ring, bounds, loss_per_triangle=uniform_loss_2d)
- points_uniform, values_uniform = sampled(uniform, npoints_goal=1600)
+ sides = np.arange(2, 41) # every frame has k × k points on both sides
+ points, values = sampled(
+ adaptive.Learner2D(ring, ((-1, 1), (-1, 1))), npoints_goal=sides[-1] ** 2
+ )
vmin, vmax = values.min(), values.max()
def draw(fig, i):
- n = frames[i]
+ k = sides[i]
+ n = k**2
axes = fig.subplots(1, 2)
- _triangles(axes[0], points_uniform[:n], values_uniform[:n], vmin, vmax, "white")
+ _square_grid(axes[0], k, vmin, vmax)
_triangles(axes[1], points[:n], values[:n], vmin, vmax, "white")
- axes[0].set_title("Homogeneous")
+ axes[0].set_title("Homogeneous grid")
axes[1].set_title("Adaptive")
- fig.suptitle(f"{n} points", fontsize=12, color="#555555", y=0.05)
+ fig.suptitle(
+ f"{n} points ({k} × {k} grid)", fontsize=12, color="#555555", y=0.05
+ )
fig.subplots_adjust(left=0.02, right=0.98, top=0.9, bottom=0.1, wspace=0.05)
- frames = counts(4, len(points), 60, power=2.5)
- _render_gif(draw, len(frames), (7, 3.75), target, dpi=90)
+ _render_gif(draw, len(sides), (7, 3.75), target, dpi=90, fps=10)
def learnerND(target: Path) -> None:
@@ -264,11 +283,16 @@ def draw(fig, i):
}
+def make(name: str) -> None:
+ function, target = ANIMATIONS[name]
+ function(target)
+
+
def main(names: list[str]) -> None:
(STATIC / "readme").mkdir(exist_ok=True)
- for name in names or ANIMATIONS:
- function, target = ANIMATIONS[name]
- function(target)
+ # One process per animation, so the others render while LearnerND runs.
+ with ProcessPoolExecutor() as pool:
+ list(pool.map(make, names or ANIMATIONS))
if __name__ == "__main__":
diff --git a/readthedocs.yml b/readthedocs.yml
index ae8ef5d6..db833922 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -2,6 +2,8 @@ version: 2
build:
os: ubuntu-24.04
+ apt_packages:
+ - ffmpeg # docs/make_animations.py encodes the animations
tools:
python: "3.13"
jobs:
@@ -15,9 +17,11 @@ build:
- uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
install:
- UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --group docs
+ - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs plotly_get_chrome -y # for kaleido
build:
html:
- - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs python docs/build_notebooks.py
+ # The animations are not version controlled; render them while the notebooks run.
+ - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs python docs/make_animations.py & UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs python docs/build_notebooks.py && wait $!
- UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run --group docs zensical build --strict
- mkdir -p "${READTHEDOCS_OUTPUT}/html"
- cp -r _site/. "${READTHEDOCS_OUTPUT}/html/"