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

- Learner1D: homogeneous grid versus adaptive sampling of a sharp peak - Learner2D: homogeneous grid versus adaptive triangulation of a ring - LearnerND: sampled points concentrate on a spherical shell + Learner1D: homogeneous grid versus adaptive sampling of a sharp peak + Learner2D: homogeneous grid versus adaptive triangulation of a ring + LearnerND: sampled points concentrate on a spherical shell

## 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/"