Skip to content

Show a square grid in the Learner2D README GIF, render the animations on Read the Docs - #503

Merged
basnijholt merged 2 commits into
mainfrom
t3/readme-square-grid-gif
Nov 12, 2026
Merged

basnijholt merged 2 commits into
mainfrom
t3/readme-square-grid-gif

Conversation

@basnijholt

@basnijholt basnijholt commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Summary

Square grid as the homogeneous baseline

The "Homogeneous" panel of the Learner2D animation was a Learner2D run with uniform_loss. That produces an irregular triangulation of roughly equal-sized triangles, not a grid, which made the comparison confusing.

The panel now shows the function evaluated on a k × k square grid, with the grid lines drawn so the grid is obvious.

  • New _square_grid() helper in docs/make_animations.py shades the grid with pcolormesh(shading="gouraud") and draws white grid lines (same style as the triangle edges on the adaptive side).
  • The animation steps through k = 2..40, so both panels always use exactly k² points (4 to 1600). The caption reads e.g. "1600 points (40 × 40 grid)" and the panel title is "Homogeneous grid".

Animations are no longer version controlled

The three README GIFs and logo_docs.webm are build artifacts of docs/make_animations.py, and every refresh added megabytes to the history (this GIF alone grows from 0.81 MB to 1.36 MB, since the whole grid changes every frame).

  • Removed them from git and added them to docs/.gitignore.
  • readthedocs.yml installs ffmpeg (apt_packages) and Chrome for kaleido (plotly_get_chrome -y), and runs make_animations.py in the background while build_notebooks.py runs. ... & build_notebooks.py && wait $! fails the build if either fails.
  • make_animations.py renders each animation in its own process, so the slow LearnerND render (~143 s locally) overlaps the others.
  • The README now loads the GIFs from https://adaptive.readthedocs.io/en/latest/_static/readme/, like it already does for the logo. No release links to the old raw.githubusercontent.com/.../main URLs (the last release, v1.5.2, predates them).

Trade-offs: the README images now depend on the latest Read the Docs build (a failed build keeps serving the previous one), and a local zensical serve shows the animations only after running make_animations.py once (noted in the README).

Preview of the new GIF from this PR's docs build: https://adaptive--503.org.readthedocs.build/en/503/_static/readme/learner2d.gif

Test plan

  • pre-commit run passes on the changed files (ruff, ruff-format, mypy)
  • Inspected the first, middle and last frames of the new Learner2D GIF
  • Replayed the readthedocs.yml install and build commands in readthedocs/build:ubuntu-24.04-2026.10.21 with --cpus 2: Chrome finds all its libraries, all four animations land in _site/_static/, and the combined animations + notebooks step took 682 s (whole build ≈ 745 s)
  • Read the Docs PR build passes (1007 s; the animations + notebooks step took 860 s, versus 385–583 s for the notebooks alone in earlier builds) and serves all four files under /en/503/_static/

…E GIF

The "Homogeneous" panel used a Learner2D with uniform_loss, which gives an
irregular triangulation rather than a grid. It now evaluates the function on
a k × k square grid, draws the grid lines, and steps through k = 2..40 so both
panels always use exactly k² points.
The GIFs and the animated logo are build artifacts of docs/make_animations.py,
and every refresh added megabytes to the history. The Read the Docs build now
renders them (ffmpeg from apt, Chrome for kaleido from plotly_get_chrome), in
parallel with the notebooks, and the README links to the copies on
adaptive.readthedocs.io, like it already does for the logo.

make_animations.py renders each animation in its own process, so the slow
LearnerND render overlaps the others.
@basnijholt basnijholt changed the title Show a square grid as the homogeneous baseline in the Learner2D README GIF Show a square grid in the Learner2D README GIF, render the animations on Read the Docs Nov 12, 2026
@basnijholt
basnijholt merged commit 48de651 into main Nov 12, 2026
18 checks passed
@basnijholt
basnijholt deleted the t3/readme-square-grid-gif branch November 12, 2026 20:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant