"""Plotting helpers (require matplotlib, installed via ``numgrids[plot]``)."""
from __future__ import annotations
from collections.abc import Callable
from pathlib import Path
from typing import TYPE_CHECKING
import numpy as np
from numpy.typing import NDArray
from numgrids.interpol import Interpolator
if TYPE_CHECKING:
from matplotlib.animation import FuncAnimation
from numgrids.grids import Grid
def require_matplotlib():
"""Import and return ``matplotlib.pyplot`` with a helpful error message."""
try:
import matplotlib.pyplot as plt
except ImportError as e: # pragma: no cover - depends on environment
raise ImportError(
"Plotting requires matplotlib. Install it with `pip install numgrids[plot]`."
) from e
return plt
def _label(grid: Grid, i: int) -> str:
name = grid.axes[i].name
return f"${name}$" if name else f"axis-{i}"
class _Mesh2D:
"""Geometry of a 2D color plot of a field: the mesh and the values on it.
Shared by :func:`plot_field` and :func:`animate_field`, so that both
draw the same picture.
"""
def __init__(self, grid: Grid, fixed: dict | None = None, cartesian: bool = True) -> None:
# Reduce to 2D
keep = list(range(grid.ndims))
index = [slice(None)] * grid.ndims
if grid.ndims > 2:
if fixed is None:
fixed = {i: grid.shape[i] // 2 for i in range(2, grid.ndims)}
fixed = {grid.axis_index(k): v for k, v in fixed.items()}
if len(fixed) != grid.ndims - 2:
raise ValueError(f"Fix exactly {grid.ndims - 2} axes via `fixed`, got {len(fixed)}.")
for i, idx in fixed.items():
index[i] = idx
keep.remove(i)
self.grid = grid
self.index = tuple(index)
i0, i1 = self.axes = tuple(keep)
use_cartesian = cartesian and grid.ndims == 2
if use_cartesian:
try:
cart = grid.cartesian_coords
except NotImplementedError:
cart = ()
# e.g. a 2D surface embedded in 3D space cannot be drawn flat
use_cartesian = len(cart) == 2
if use_cartesian:
X, Y = cart
if not use_cartesian:
X, Y = grid.meshed_coords[i0][self.index], grid.meshed_coords[i1][self.index]
self.cartesian = use_cartesian
# A radial axis through the origin has no point at r = 0: add the center
# (value from spectral interpolation) so that disks are drawn without a hole.
from numgrids.axes import RadialAxis
self._center = use_cartesian and isinstance(grid.axes[i0], RadialAxis)
if self._center:
X = np.vstack([np.zeros((1, X.shape[1])), X])
Y = np.vstack([np.zeros((1, Y.shape[1])), Y])
# Close periodic axes so that there is no gap in the plot.
self._periodic = [local for local, i in enumerate(self.axes) if grid.axes[i].periodic]
for local in self._periodic:
axis = grid.axes[self.axes[local]]
if use_cartesian:
X = np.concatenate([X, np.take(X, [0], axis=local)], axis=local)
Y = np.concatenate([Y, np.take(Y, [0], axis=local)], axis=local)
else:
X = np.concatenate([X, np.take(X, [0], axis=local) + (axis.period if local == 0 else 0)],
axis=local)
Y = np.concatenate([Y, np.take(Y, [0], axis=local) + (axis.period if local == 1 else 0)],
axis=local)
self.X, self.Y = X, Y
def values(self, f: NDArray) -> NDArray:
"""The values of a (real) field of grid shape on the mesh."""
grid = self.grid
F = f[self.index]
if self._center:
phi = grid.axes[self.axes[1]].coords[0]
center = float(np.real(grid.interpolate(f, (0.0, phi), method="spectral")))
F = np.vstack([np.full((1, F.shape[1]), center), F])
for local in self._periodic:
F = np.concatenate([F, np.take(F, [0], axis=local)], axis=local)
return F
def label_axes(self, ax) -> None:
if self.cartesian:
ax.set_aspect("equal")
ax.set_xlabel("$x$")
ax.set_ylabel("$y$")
else:
ax.set_xlabel(_label(self.grid, self.axes[0]))
ax.set_ylabel(_label(self.grid, self.axes[1]))
[docs]
def plot_field(
grid: Grid,
f: NDArray,
ax=None,
fixed: dict | None = None,
cartesian: bool = True,
colorbar: bool = True,
**kwargs,
):
"""Plot a meshed function on a grid.
* **1D grids**: line plot of *f* over the coordinate.
* **2D grids**: color plot (``pcolormesh``). Curvilinear grids with a
Cartesian mapping (e.g. :class:`~numgrids.PolarGrid`) are drawn in
Cartesian space, with periodic axes closed seamlessly.
* **Higher dimensions**: a 2D slice; all but two axes are fixed via
*fixed* (default: the middle index of the trailing axes).
Parameters
----------
grid : Grid
The grid.
f : NDArray
Meshed function values of shape ``grid.shape`` (real part is
plotted for complex arrays).
ax : matplotlib.axes.Axes, optional
Axes to draw into; a new figure is created if omitted.
fixed : dict, optional
For grids with more than two dimensions: ``{axis: index}`` for the
axes to fix (axis given by index or name). Exactly ``ndims - 2``
axes must be fixed.
cartesian : bool
Draw curvilinear 2D grids in Cartesian space (default ``True``).
colorbar : bool
Add a colorbar for 2D plots (default ``True``).
**kwargs
Passed on to ``ax.plot`` (1D) or ``ax.pcolormesh`` (2D).
Returns
-------
matplotlib.axes.Axes
"""
plt = require_matplotlib()
f = np.real(grid._check_field(f))
geometry = _Mesh2D(grid, fixed, cartesian) if grid.ndims > 1 else None
if ax is None:
_, ax = plt.subplots()
if geometry is None:
ax.plot(grid.coords, f, **kwargs)
ax.set_xlabel(_label(grid, 0))
return ax
kwargs.setdefault("shading", "gouraud")
mesh = ax.pcolormesh(geometry.X, geometry.Y, geometry.values(f), **kwargs)
if colorbar:
ax.figure.colorbar(mesh, ax=ax)
geometry.label_axes(ax)
return ax
# -- animations ---------------------------------------------------------------
_PARTS: dict[str, Callable[[NDArray], NDArray]] = {
"real": np.real,
"imag": np.imag,
"abs": np.abs,
"abs2": lambda f: np.abs(f) ** 2,
}
def _time_format(t: NDArray) -> str:
"""A format with fixed width that resolves the time steps (the title should not jitter)."""
largest = float(np.max(np.abs(t))) if t.size else 0.0
steps = np.abs(np.diff(t))
steps = steps[steps > 0]
if not np.isfinite(largest) or (largest != 0 and not 1e-3 <= largest < 1e6):
return "{:.3e}"
decimals = 2 if not steps.size else int(np.clip(np.ceil(-np.log10(steps.min())) + 1, 0, 6))
return f"{{:.{decimals}f}}"
[docs]
def animate_field(
grid: Grid,
frames: NDArray,
t: NDArray | None = None,
ax=None,
fixed: dict | None = None,
cartesian: bool = True,
colorbar: bool = True,
part: str | Callable[[NDArray], NDArray] = "real",
interval: float | None = None,
fps: float | None = None,
vmin: float | None = None,
vmax: float | None = None,
ylim: tuple[float, float] | None = None,
title: str | None = None,
repeat: bool = True,
save: str | Path | None = None,
**kwargs,
) -> FuncAnimation:
"""Animate a time-dependent field on a grid.
The frames are drawn like :func:`plot_field` draws a single field: a
line for 1D grids, a color plot for 2D grids (in Cartesian space for
curvilinear grids) and a 2D slice for higher dimensions. The axis
limits (1D) and the color scale (2D) are the same in all frames; by
default they cover the values of all frames.
Parameters
----------
grid : Grid
The grid.
frames : NDArray
The field at successive times, shape ``(nt, *grid.shape)``, e.g.
the attribute ``u`` of an :class:`~numgrids.EvolutionResult`.
t : array_like, optional
The times of the frames, shape ``(nt,)``. They are shown in the
title as ``t = ...``.
ax : matplotlib.axes.Axes, optional
Axes to draw into; a new figure is created if omitted.
fixed : dict, optional
The slice to show for grids with more than two dimensions, see
:func:`plot_field`.
cartesian : bool
Draw curvilinear 2D grids in Cartesian space (default ``True``).
colorbar : bool
Add a colorbar for 2D plots (default ``True``).
part : str or callable
What to show of the values: ``"real"`` (default), ``"imag"``,
``"abs"`` or ``"abs2"`` (the squared modulus), or a function that
is applied to the frames. Only matters for complex fields.
interval : float, optional
Delay between frames in milliseconds (default 50).
fps : float, optional
Frames per second, as an alternative to *interval*.
vmin, vmax : float, optional
Limits of the color scale (2D) or of the vertical axis (1D).
Default: the smallest and largest value of all frames.
ylim : (float, float), optional
Limits of the vertical axis for 1D grids, in place of *vmin* and
*vmax*.
title : str, optional
Title of the plot; the time is appended to it.
repeat : bool
Start again after the last frame (default ``True``).
save : str or Path, optional
Also save the animation to this file, see :func:`save_animation`.
**kwargs
Passed on to ``ax.plot`` (1D) or ``ax.pcolormesh`` (2D), e.g. ``cmap``.
Returns
-------
matplotlib.animation.FuncAnimation
Keep a reference to it: the animation stops when it is garbage
collected. In a notebook, show it with
``HTML(anim.to_jshtml())``.
Examples
--------
>>> import numpy as np
>>> from numgrids import Grid, periodic
>>> grid = Grid(x=periodic(64))
>>> t = np.linspace(0, 2 * np.pi, 40)
>>> frames = np.sin(grid.coords[None, :] - t[:, None]) # a travelling wave
>>> anim = grid.animate(frames, t) # doctest: +SKIP
>>> anim.save("wave.gif") # doctest: +SKIP
"""
plt = require_matplotlib()
from matplotlib.animation import FuncAnimation
if isinstance(frames, tuple):
raise TypeError(
"Got a tuple of fields (a coupled system). Animate one of them, e.g. frames[0], "
"or use the `field` argument of EvolutionResult.animate."
)
frames = np.asarray(frames)
if frames.ndim != grid.ndims + 1 or frames.shape[1:] != grid.shape or not len(frames):
raise ValueError(
f"`frames` has shape {frames.shape}, expected (nt, *grid.shape) with grid shape {grid.shape}."
)
nt = len(frames)
if t is not None:
t = np.asarray(t, dtype=float)
if t.shape != (nt,):
raise ValueError(f"Expected {nt} time values (one per frame), got an array of shape {t.shape}.")
if callable(part):
select = part
elif part in _PARTS:
select = _PARTS[part]
else:
raise ValueError(f"Unknown part {part!r}. Use one of {sorted(_PARTS)} or a function.")
if interval is not None and fps is not None:
raise ValueError("Give either `interval` or `fps`, not both.")
if fps is not None:
interval = 1000.0 / fps
elif interval is None:
interval = 50.0
geometry = _Mesh2D(grid, fixed, cartesian) if grid.ndims > 1 else None
if ax is None:
_, ax = plt.subplots()
def frame(k: int) -> NDArray:
return np.asarray(select(frames[k]), dtype=float)
def limits(values: NDArray) -> tuple[float, float]:
low = float(np.nanmin(values)) if vmin is None else vmin
high = float(np.nanmax(values)) if vmax is None else vmax
return low, high
if geometry is None:
(line,) = ax.plot(grid.coords, frame(0), **kwargs)
ax.set_xlabel(_label(grid, 0))
if ylim is None:
low, high = limits(np.asarray(select(frames), dtype=float))
margin = 0.05 * (high - low) or 0.5
# a little room around the curve, but not beyond limits that were asked for
ylim = (low - margin * (vmin is None), high + margin * (vmax is None))
ax.set_ylim(*ylim)
def draw(values: NDArray):
line.set_ydata(values)
return line
else:
kwargs.setdefault("shading", "gouraud")
if "norm" not in kwargs:
shown = np.asarray(select(frames[(slice(None),) + geometry.index]), dtype=float)
kwargs["vmin"], kwargs["vmax"] = limits(shown)
mesh = ax.pcolormesh(geometry.X, geometry.Y, geometry.values(frame(0)), **kwargs)
if colorbar:
ax.figure.colorbar(mesh, ax=ax)
geometry.label_axes(ax)
def draw(values: NDArray):
# Only the colors change: the mesh itself is built once.
mesh.set_array(geometry.values(values))
return mesh
stamp = None if t is None else _time_format(t)
def update(k: int):
artists = [draw(frame(k))]
if stamp is not None:
time = "t = " + stamp.format(t[k])
artists.append(ax.set_title(time if title is None else f"{title}, {time}"))
return artists
if title is not None:
ax.set_title(title)
anim = FuncAnimation(ax.figure, update, frames=nt, interval=interval, repeat=repeat, blit=False)
if save is not None:
save_animation(anim, save)
return anim
[docs]
def save_animation(anim: FuncAnimation, path: str | Path, fps: float | None = None, writer=None, **kwargs) -> Path:
"""Save an animation to a file, choosing the writer from the file name.
* ``.gif``: written with Pillow (installed together with matplotlib).
* ``.html``: a self-contained page with playback controls (the output
of ``anim.to_jshtml()``); needs no additional software.
* anything else (e.g. ``.mp4``): the default movie writer of
matplotlib, usually `ffmpeg <https://ffmpeg.org>`_, which has to be
installed separately.
Parameters
----------
anim : matplotlib.animation.Animation
The animation, e.g. from :func:`animate_field`.
path : str or Path
Destination file.
fps : float, optional
Frames per second of the file. Defaults to the speed of the
animation.
writer : str or matplotlib.animation.AbstractMovieWriter, optional
The writer to use instead of the one chosen from the file name.
**kwargs
Passed on to ``anim.save`` (e.g. ``dpi``).
Returns
-------
Path
The path of the file written.
Raises
------
RuntimeError
If the writer is not available on this system.
"""
require_matplotlib()
import matplotlib
from matplotlib import animation
path = Path(path)
suffix = path.suffix.lower()
if writer is None and suffix in (".html", ".htm"):
path.write_text(anim.to_jshtml(fps=fps), encoding="utf-8")
return path
if writer is None:
writer = "pillow" if suffix == ".gif" else matplotlib.rcParams["animation.writer"]
if isinstance(writer, str) and not animation.writers.is_available(writer):
raise RuntimeError(
f"Cannot save '{path.name}': the matplotlib movie writer '{writer}' is not available on this "
"system. Install it, or save the animation as a GIF ('.gif', needs Pillow) or as a "
"self-contained HTML page ('.html')."
)
anim.save(str(path), writer=writer, fps=fps, **kwargs)
return path
class Plotter:
"""Plotting utility for visualizing meshed functions on a grid.
Wraps matplotlib to provide quick line plots of interpolated
function values along user-specified coordinate slices.
"""
def __init__(self, grid: Grid) -> None:
"""Create a plotter for the given grid.
Parameters
----------
grid : Grid
The grid on which the data lives.
"""
self.grid = grid
self.fig = None
self.ax = None
def plot(self, f: NDArray, *coords) -> None:
"""Plot interpolated function values along a coordinate path.
The values are plotted against the first coordinate that is given
as an array.
Parameters
----------
f : NDArray
Meshed function values on the grid.
*coords
Coordinate arrays or scalar values defining the path to plot.
At least one coordinate must be an array; scalar coordinates
are broadcast to match.
"""
plt = require_matplotlib()
num_points = None
param = None
for i, c in enumerate(coords):
if hasattr(c, "__len__"):
num_points = len(c)
param = i
break
if num_points is None:
raise ValueError("At least one coordinate must be an array.")
parsed_coords = []
for c in coords:
if hasattr(c, "__len__"):
parsed_coords.append(c)
else:
parsed_coords.append([c] * num_points)
coords = parsed_coords
if self.fig is None:
self.fig = plt.figure()
self.ax = self.fig.subplots(1, 1)
inter = Interpolator(self.grid, f)
points = np.array(coords).T
values = inter(points)
self.ax.plot(np.asarray(coords[param]), values)
self.ax.set_xlabel(_label(self.grid, param))
def show(self) -> None:
"""Display the current plot."""
if self.fig is not None:
self.fig.show()