Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,9 @@ With the same number of points, adaptive sampling resolves features that a homog
<!-- --8<-- [end:summary] -->

<p align="center">
<img src="https://raw.githubusercontent.com/python-adaptive/adaptive/main/docs/_static/readme/learner1d.gif" width="43%" alt="Learner1D: homogeneous grid versus adaptive sampling of a sharp peak">
<img src="https://raw.githubusercontent.com/python-adaptive/adaptive/main/docs/_static/readme/learner2d.gif" width="36%" alt="Learner2D: homogeneous grid versus adaptive triangulation of a ring">
<img src="https://raw.githubusercontent.com/python-adaptive/adaptive/main/docs/_static/readme/learnerND.gif" width="19%" alt="LearnerND: sampled points concentrate on a spherical shell">
<img src="https://adaptive.readthedocs.io/en/latest/_static/readme/learner1d.gif" width="43%" alt="Learner1D: homogeneous grid versus adaptive sampling of a sharp peak">
<img src="https://adaptive.readthedocs.io/en/latest/_static/readme/learner2d.gif" width="36%" alt="Learner2D: homogeneous grid versus adaptive triangulation of a ring">
<img src="https://adaptive.readthedocs.io/en/latest/_static/readme/learnerND.gif" width="19%" alt="LearnerND: sampled points concentrate on a spherical shell">
</p>

## Example
Expand Down Expand Up @@ -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

Expand Down
3 changes: 3 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Binary file removed docs/_static/logo_docs.webm
Binary file not shown.
Binary file removed docs/_static/readme/learner1d.gif
Binary file not shown.
Binary file removed docs/_static/readme/learner2d.gif
Binary file not shown.
Binary file removed docs/_static/readme/learnerND.gif
Binary file not shown.
56 changes: 40 additions & 16 deletions docs/make_animations.py
Original file line number Diff line number Diff line change
@@ -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]
"""
Expand All @@ -13,6 +15,7 @@
import sys
import tempfile
from collections.abc import Callable
from concurrent.futures import ProcessPoolExecutor
from pathlib import Path

import matplotlib
Expand All @@ -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"
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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__":
Expand Down
6 changes: 5 additions & 1 deletion readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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/"
Loading