planetmodel 1.3.2__tar.gz → 1.4.0__tar.gz

{planetmodel-1.3.2 → planetmodel-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: planetmodel
-Version: 1.3.2
+Version: 1.4.0
 Summary: Spherically layered planetary models: reference bodies, fields, mappings and meshes
 License-Expression: BSD-3-Clause
 License-File: LICENSE
@@ -154,9 +154,11 @@ print(mesh.nodal(nd, "rho").shape)      # density at every mesh node
 
 ## Where to go next
 
-- `examples/tutorials/`: twelve walkthroughs, from a skeleton to random
-  fields, deck files and a laterally varying model in a model file, each
-  a `# %%` script that runs headless.
+- `examples/tutorials/`: fifteen walkthroughs, from a skeleton to random
+  fields, deck files, a laterally varying model in a model file, pictures,
+  published models and sensitivity kernels, each a `# %%` script that
+  runs headless and opens as a notebook, in Google Colab from the badges
+  in `examples/README.md`.
 - `docs/source/formats/`: the model file and the manifest beside every
   mesh, described for the codes that read them (also on Read the Docs).
 - `CONTRIBUTING.md`: the development setup, the hooks, the test

{planetmodel-1.3.2 → planetmodel-1.4.0}/README.md

@@ -118,9 +118,11 @@ print(mesh.nodal(nd, "rho").shape)      # density at every mesh node
 
 ## Where to go next
 
-- `examples/tutorials/`: twelve walkthroughs, from a skeleton to random
-  fields, deck files and a laterally varying model in a model file, each
-  a `# %%` script that runs headless.
+- `examples/tutorials/`: fifteen walkthroughs, from a skeleton to random
+  fields, deck files, a laterally varying model in a model file, pictures,
+  published models and sensitivity kernels, each a `# %%` script that
+  runs headless and opens as a notebook, in Google Colab from the badges
+  in `examples/README.md`.
 - `docs/source/formats/`: the model file and the manifest beside every
   mesh, described for the codes that read them (also on Read the Docs).
 - `CONTRIBUTING.md`: the development setup, the hooks, the test

{planetmodel-1.3.2 → planetmodel-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "planetmodel"
-version = "1.3.2"
+version = "1.4.0"
 description = "Spherically layered planetary models: reference bodies, fields, mappings and meshes"
 keywords = ["geophysics", "seismology", "planetary models", "PREM", "spectral elements", "meshing"]
 classifiers = [

{planetmodel-1.3.2 → planetmodel-1.4.0}/src/planetmodel/__init__.py

@@ -129,7 +129,7 @@ from .units import EARTH_MEAN_DENSITY, G_SI, Dimensions, Scales
 from .vocabulary import CONSTANTS, VOCABULARY, Constant, FieldSpec
 from . import testing  # noqa: F401
 
-__version__ = "1.3.2"
+__version__ = "1.4.0"
 
 __all__ = [
     "Skeleton",

{planetmodel-1.3.2 → planetmodel-1.4.0}/src/planetmodel/harmonics.py

@@ -39,6 +39,16 @@ with the Condon-Shortley phase; the real ones here are
 and that is the whole of the conversion.  ducc0 is imported where a
 transform is made, so that `import planetmodel` does not load it.
 
+**Many shells at once.**  A consumer holding a field on radial nodes
+times a grid -- a hundred shells, one band -- crosses into ducc0 once
+per shell.  `ShellTransform` instead tabulates the basis on one
+Gauss-Legendre grid's meridian, once per grid, and carries every shell
+together through two matrix products each way, agreeing with
+`synthesise_grid` and `analyse_grid` to rounding.  Its table is
+(lmax + 1)^3 numbers, so the grid transforms remain the route for a
+single field, a grid of another kind, or degrees where the table would
+not fit.
+
 **Other conventions.**  Published coefficients come in other
 normalisations and with or without the Condon-Shortley phase;
 `from_convention` gives the library's coefficients from them and
@@ -75,8 +85,8 @@ if TYPE_CHECKING:
     from .sampling import AngularGrid
 
 __all__ = ["real_harmonics", "synthesise", "synthesise_gradient", "synthesise_grid",
-           "analyse_grid", "packing", "from_convention", "to_convention",
-           "NORMALIZATIONS", "POINT_EPSILON"]
+           "analyse_grid", "ShellTransform", "packing", "from_convention",
+           "to_convention", "NORMALIZATIONS", "POINT_EPSILON"]
 
 #: The relative accuracy asked of ducc0's synthesis at arbitrary points.
 POINT_EPSILON = 1e-13
@@ -393,3 +403,102 @@ def real_harmonics(lmax: int, theta: ArrayLike, phi: ArrayLike) -> np.ndarray:
                     lam * (root2 * np.sin(angle))[None]])
     out[1, :, 0] = 0.0
     return out.reshape((2, lmax + 1, lmax + 1) + theta.shape)
+
+
+# -- many shells at once ----------------------------------------------------------
+
+class ShellTransform:
+    """Synthesis and analysis on one Gauss-Legendre grid, for any number
+    of radial shells at once.
+
+    The transform is separable: the basis on the prime meridian -- the
+    normalised Legendre functions, tabulated once through
+    `real_harmonics` -- contracts the degrees of every shell in one
+    matrix product, and the longitudes in a second; nothing loops over
+    shells.  Construction costs the table, (lmax + 1)^3 numbers; each
+    call after that is the matmuls.
+
+    The grid is the minimal Gauss-Legendre one of its band,
+    `gauss_legendre(lmax)`: lmax + 1 colatitudes and 2 lmax + 1
+    longitudes, from any phi0.  Any other grid is refused.  On it,
+    `synthesise` and `analyse` agree with `synthesise_grid` and
+    `analyse_grid` to rounding: exact for a field band-limited to the
+    grid's degree, a projection otherwise.
+    """
+
+    def __init__(self, grid: AngularGrid) -> None:
+        """Tabulate the basis on the meridian of `grid`."""
+        if (getattr(grid, "kind", None) != "gauss_legendre" or grid.lmax is None
+                or grid.weights is None):
+            raise ValueError(
+                f"ShellTransform tabulates the basis of a Gauss-Legendre grid "
+                f"and integrates with its weights; got a "
+                f"{getattr(grid, 'kind', None)!r} grid")
+        _rings(grid)            # the nodes are genuinely the kind's own
+        lmax = int(grid.lmax)
+        if grid.ntheta != lmax + 1 or grid.nphi != 2 * lmax + 1:
+            raise ValueError(
+                f"ShellTransform takes the minimal Gauss-Legendre grid of its "
+                f"band, gauss_legendre({lmax}): {lmax + 1} colatitudes and "
+                f"{2 * lmax + 1} longitudes, not {grid.ntheta} x {grid.nphi}")
+        self._lmax = lmax
+        # The basis on the prime meridian: the cosine harmonics there are the
+        # normalised Legendre functions, and the sine ones share them.
+        meridian = real_harmonics(lmax, grid.colatitudes, 0.0)[0]
+        # (order, colatitude, degree), so that a matmul contracts the degree.
+        self._legendre = np.ascontiguousarray(meridian.transpose(1, 2, 0))
+        # (order, degree, colatitude), the quadrature weights folded in.
+        self._weighted = np.ascontiguousarray(
+            (meridian * grid.weights).transpose(1, 0, 2))
+        angle = np.arange(lmax + 1)[:, None] * grid.longitudes[None, :]
+        self._cosines = np.cos(angle)                      # (order, longitude)
+        self._sines = np.sin(angle)
+        self._cell = 2.0 * np.pi / grid.nphi
+
+    @property
+    def lmax(self) -> int:
+        """The grid's band: the degree the table holds."""
+        return self._lmax
+
+    def synthesise(self, coefficients: ArrayLike) -> np.ndarray:
+        """Values on every shell from coefficient functions.
+
+        `coefficients` has shape (2, lmax + 1, lmax + 1, shells), a
+        coefficient array with one radial axis; the result has shape
+        (shells, ntheta, nphi), the layout of a sample.
+        """
+        c = np.asarray(coefficients, dtype=float)
+        n = self._lmax + 1
+        if c.ndim != 4 or c.shape[:3] != (2, n, n):
+            raise ValueError(f"coefficients must have shape (2, {n}, {n}, "
+                             f"shells), got {c.shape}")
+        shells = c.shape[3]
+        # (order, degree, shells) -> (order, colatitude, shells)
+        even = np.matmul(self._legendre, c[0].transpose(1, 0, 2))
+        odd = np.matmul(self._legendre, c[1].transpose(1, 0, 2))
+        # (longitude, colatitude * shells)
+        flat = self._cosines.T @ even.reshape(n, -1)
+        flat += self._sines.T @ odd.reshape(n, -1)
+        return np.ascontiguousarray(flat.reshape(-1, n, shells).transpose(2, 1, 0))
+
+    def analyse(self, values: ArrayLike) -> np.ndarray:
+        """Coefficient functions from values on every shell, by the grid's
+        own quadrature.
+
+        `values` has shape (shells, ntheta, nphi); the result has shape
+        (2, lmax + 1, lmax + 1, shells), zero where no harmonic is.
+        """
+        v = np.asarray(values, dtype=float)
+        n = self._lmax + 1
+        if v.ndim != 3 or v.shape[1:] != (n, 2 * self._lmax + 1):
+            raise ValueError(f"values must have shape (shells, {n}, "
+                             f"{2 * self._lmax + 1}), got {v.shape}")
+        shells = v.shape[0]
+        flat = v.transpose(2, 1, 0).reshape(v.shape[2], -1)  # (longitude, ...)
+        out = np.empty((2, n, n, shells))
+        for part, waves in enumerate((self._cosines, self._sines)):
+            fourier = (self._cell * waves) @ flat   # (order, colatitude * shells)
+            fourier = fourier.reshape(n, n, shells)
+            # (order, degree, colatitude) @ (order, colatitude, shells)
+            out[part] = np.matmul(self._weighted, fourier).transpose(1, 0, 2)
+        return out

{planetmodel-1.3.2 → planetmodel-1.4.0}/src/planetmodel/plotting/__init__.py

@@ -10,7 +10,11 @@ the figure to the caller.  Nothing here is particular to the Earth.
 upward, a step at every interface (`profiles`); `section` draws a
 great-circle section as a wedge of the annulus or a disc, or in the
 body's deformed shape (`sections`); `sphere_map` draws a sphere slice on
-cartopy's projections (`maps`, the `maps` extra); `spectrum`,
+cartopy's projections (`maps`, the `maps` extra); `cutaway` draws the
+body with a wedge cut from it, the field on the faces of the cut and
+the surface as the field, a plain colour, Natural Earth's land and sea
+or its shaded relief, with coastlines (`cutaways`, cartopy where the
+Earth's surface is drawn); `spectrum`,
 `correlation` and `correlation_total` draw spectra and correlations by
 degree and radius (`spectra`); `write_vtk` writes a model as VTK files
 for ParaView (`vtk`, no extra needed); `style` holds the look they
@@ -20,6 +24,7 @@ divided by its largest value with `normalised=True`, on maps and
 sections alike.  matplotlib is not imported here: the axes are the caller's,
 made with the `plot` extra, and cartopy only where a map is drawn.
 """
+from .cutaways import COASTLINE_STYLE, LAND, LIGHT, SEA, cutaway
 from .maps import cell_edges, sphere_map
 from .profiles import profile, radial_profile
 from .sections import section
@@ -28,6 +33,6 @@ from .style import BOUNDARY_STYLE, DIVERGING, SEQUENTIAL, colour_extend, colour_
 from .vtk import write_vtk
 
 __all__ = ["profile", "radial_profile", "section", "sphere_map", "cell_edges",
-           "spectrum", "correlation", "correlation_total", "write_vtk",
-           "BOUNDARY_STYLE", "DIVERGING", "SEQUENTIAL", "colour_scale",
-           "colour_extend"]
+           "cutaway", "spectrum", "correlation", "correlation_total", "write_vtk",
+           "BOUNDARY_STYLE", "DIVERGING", "SEQUENTIAL", "LIGHT", "LAND", "SEA",
+           "COASTLINE_STYLE", "colour_scale", "colour_extend"]

planetmodel-1.4.0/src/planetmodel/plotting/cutaways.py

@@ -0,0 +1,270 @@
+"""Cutaways: the body with a wedge cut from it, or discs through it, the
+field on the faces.
+
+`cutaway` draws a `slices.CutawaySlice`, of `slices.cutaway` or of
+`slices.discs`, on plain matplotlib axes as one image, the pixels of the
+slice's orthographic view coloured by what each looks at: the faces of
+the cut, or the discs, always show the field; the sphere left standing
+in a cut shows the field or a plain colour (`inner=`);
+and the surface shows the field (`surface="field"`), a plain colour, the
+land and the sea in two colours from Natural Earth's land polygons
+(`"land"`), Natural Earth's shaded relief, the raster cartopy ships
+(`"image"`), or any image of the whole surface given as an array (rows
+from the north pole to the south, columns from 180 degrees west
+eastward, RGB or RGBA).  Plain colours and images are shaded by the
+light of `LIGHT`, so that the sphere reads as one; the field's colours
+are never shaded.  `coastlines=True` draws Natural Earth's coastlines
+where they are seen, through `CutawaySlice.visible`, and
+`interfaces=True` the model's interfaces as faint arcs on the faces
+(`style.BOUNDARY_STYLE`); a slice showing a sphere within the body
+wears its dressing and coastlines on that sphere, the faces running
+past it.  The edge of the body is antialiased by the
+slice's coverage, a pixel of the edge whose centre misses the body
+taking the colour of its nearest neighbour that sees it.  The colour
+scale is `style.colour_scale`'s over every pixel that shows the field,
+chosen with `diverging=` and `clip=` as a map's is; `normalised=True`
+draws the slice divided by its largest absolute value.  cartopy (the
+`maps` extra) is imported where land, relief or coastlines are drawn,
+and only then.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ..frames import cartesian_points, from_geographic, geographic
+from ..slices import CutawaySlice, normalised as _normalised
+from .style import BOUNDARY_STYLE, colour_extend, colour_scale
+
+__all__ = ["cutaway", "LIGHT", "LAND", "SEA", "COASTLINE_STYLE"]
+
+#: The direction the light comes from, in the picture's frame (right, up,
+#: toward the viewer), for shading plain colours and images.
+LIGHT = (-0.3, 0.5, 1.0)
+
+#: The depth of the shading: a plain colour is multiplied by 1 - SHADE at
+#: a grazing surface and by 1 where the light falls square on it.
+_SHADE = 0.45
+
+#: The colours of the land and the sea of `surface="land"`.
+LAND = "#d8ceb1"
+SEA = "#c9dcea"
+
+#: The style of a coastline.
+COASTLINE_STYLE = {"color": "0.15", "lw": 0.5}
+
+#: The points along each interface arc drawn on a face.
+_ARC_POINTS = 181
+
+
+def _rgb(colour: Any) -> np.ndarray:
+    """A matplotlib colour as RGBA floats."""
+    from matplotlib.colors import to_rgba
+    return np.asarray(to_rgba(colour), dtype=float)
+
+
+def _shading(slice_: CutawaySlice, points: np.ndarray, normals: np.ndarray
+             ) -> np.ndarray:
+    """The factor (...,) a plain colour at `points` is multiplied by for
+    the light of `LIGHT` on a surface of outward `normals`."""
+    light = np.asarray(LIGHT, dtype=float) @ slice_.view
+    light /= np.linalg.norm(light)
+    cos = np.clip(normals @ light, 0.0, 1.0)
+    return 1.0 - _SHADE * (1.0 - cos)
+
+
+def _sample_image(image: np.ndarray, theta: np.ndarray, phi: np.ndarray
+                  ) -> np.ndarray:
+    """The pixels of an image of the whole surface, rows from the north
+    pole, columns from 180 degrees west, nearest to (theta, phi)."""
+    lat, lon = geographic(theta, phi)
+    rows, cols = image.shape[:2]
+    i = np.clip(((90.0 - lat) / 180.0 * rows).astype(int), 0, rows - 1)
+    j = np.clip(((lon + 180.0) % 360.0 / 360.0 * cols).astype(int), 0, cols - 1)
+    out = image[i, j]
+    if out.shape[-1] == 3:
+        out = np.concatenate([out, np.ones(out.shape[:-1] + (1,))], axis=-1)
+    return out
+
+
+def _natural_earth_image() -> np.ndarray:
+    """Natural Earth's shaded relief, the raster cartopy ships, as floats."""
+    import os
+    import cartopy
+    from matplotlib.image import imread
+    path = os.path.join(cartopy.config["repo_data_dir"], "raster", "natural_earth",
+                        "50-natural-earth-1-downsampled.png")
+    return np.asarray(imread(path), dtype=float)
+
+
+def _on_land(theta: np.ndarray, phi: np.ndarray) -> np.ndarray:
+    """Whether points lie on Natural Earth's land, at 110 m."""
+    import shapely
+    from cartopy.feature import NaturalEarthFeature
+    lat, lon = geographic(theta, phi)
+    lon = (lon + 180.0) % 360.0 - 180.0
+    out = np.zeros(lat.shape, dtype=bool)
+    for geometry in NaturalEarthFeature("physical", "land", "110m").geometries():
+        shapely.prepare(geometry)
+        out |= shapely.contains_xy(geometry, lon, lat)
+    return out
+
+
+def _coastlines(slice_: CutawaySlice, scale: float) -> tuple[np.ndarray, np.ndarray]:
+    """Natural Earth's coastlines at 110 m in the picture, the runs that
+    are seen separated by NaN."""
+    from cartopy.feature import NaturalEarthFeature
+    xs, ys = [], []
+    for geometry in NaturalEarthFeature("physical", "coastline",
+                                        "110m").geometries():
+        lines = getattr(geometry, "geoms", [geometry])
+        for line in lines:
+            lon, lat = np.asarray(line.coords, dtype=float).T
+            theta, phi = from_geographic(lat, lon)
+            X = cartesian_points(slice_.outer, theta, phi)
+            seen = slice_.visible(X)
+            if not np.any(seen):
+                continue
+            x, y = slice_.project(X)
+            xs.append(np.where(seen, x * scale, np.nan))
+            ys.append(np.where(seen, y * scale, np.nan))
+            xs.append([np.nan])
+            ys.append([np.nan])
+    if not xs:
+        return np.array([]), np.array([])
+    return np.concatenate(xs), np.concatenate(ys)
+
+
+def _interface_arcs(slice_: CutawaySlice, scale: float
+                    ) -> tuple[np.ndarray, np.ndarray]:
+    """The model's interfaces between the cut's radii as arcs on the two
+    faces, in the picture, the runs that are seen separated by NaN."""
+    xs, ys = [], []
+    for radius in slice_.boundaries:
+        if not slice_.inner < radius < slice_.top:
+            continue
+        for centre, a, b, start, end in slice_.arcs:
+            s = np.linspace(start, end, _ARC_POINTS)[:, None]
+            X = radius * (centre + a * np.cos(s) + b * np.sin(s))
+            seen = slice_.visible(X)
+            if not np.any(seen):
+                continue
+            x, y = slice_.project(X)
+            xs += [np.where(seen, x * scale, np.nan), [np.nan]]
+            ys += [np.where(seen, y * scale, np.nan), [np.nan]]
+    if not xs:
+        return np.array([]), np.array([])
+    return np.concatenate(xs), np.concatenate(ys)
+
+
+def _surface_colours(slice_: CutawaySlice, surface: Any, hit: np.ndarray
+                     ) -> np.ndarray | None:
+    """The RGBA of the surface pixels `hit`, or None for the field."""
+    if isinstance(surface, str) and surface == "field":
+        return None
+    X = slice_.reference[hit]
+    r = np.linalg.norm(X, axis=-1)
+    theta = np.arccos(np.clip(X[:, 2] / r, -1.0, 1.0))
+    phi = np.arctan2(X[:, 1], X[:, 0])
+    if isinstance(surface, str) and surface == "image":
+        rgba = _sample_image(_natural_earth_image(), theta, phi)
+    elif isinstance(surface, str) and surface == "land":
+        rgba = np.where(_on_land(theta, phi)[:, None], _rgb(LAND), _rgb(SEA))
+    elif isinstance(surface, np.ndarray) and surface.ndim == 3:
+        image = surface.astype(float)
+        if surface.dtype.kind in "ui":
+            image = image / 255.0
+        if image.shape[2] not in (3, 4):
+            raise ValueError("an image of the surface has RGB or RGBA pixels, "
+                             f"got shape {surface.shape}")
+        rgba = _sample_image(image, theta, phi)
+    else:
+        try:
+            rgba = np.broadcast_to(_rgb(surface), (X.shape[0], 4)).copy()
+        except ValueError:
+            raise ValueError("surface is 'field', 'image', 'land', an RGB(A) "
+                             f"image of the surface or a colour, got {surface!r}"
+                             ) from None
+    rgba = np.array(rgba, dtype=float)
+    rgba[:, :3] *= _shading(slice_, X, X / r[:, None])[:, None]
+    return rgba
+
+
+def cutaway(ax: Any, slice_: CutawaySlice, *, surface: Any = "field",
+            inner: Any = "field", coastlines: bool = False,
+            interfaces: bool = True, scale: float = 1.0, cmap: str | None = None,
+            vmin: float | None = None, vmax: float | None = None,
+            diverging: bool = False, clip: float | None = None,
+            normalised: bool = False, colorbar: bool = False, **style: Any) -> Any:
+    """Draw a cutaway on plain axes by the rules of the module docstring.
+
+    `surface` is `"field"`, `"image"`, `"land"`, an RGB(A) image of the
+    whole surface, or a colour; `inner` `"field"` or a colour for the
+    sphere left standing in the cut; `coastlines` draws the coastlines;
+    `interfaces` the interfaces as faint arcs on the faces; positions
+    are multiplied by `scale`; `cmap`, `vmin` and `vmax` override the
+    colour scale, `diverging` and `clip` choose it, `normalised` divides
+    by the largest absolute value; `colorbar` adds a colour bar labelled
+    with what the slice shows, with arrows at the ends the values run
+    beyond; `style` goes to `imshow`.  Returns the image drawn.
+    """
+    from matplotlib.cm import ScalarMappable
+    from matplotlib.colors import Normalize
+    import matplotlib.pyplot as plt
+    if (getattr(ax, "projection", None) is not None
+            or getattr(ax, "name", "") == "polar"):
+        raise ValueError("a cutaway is drawn on plain axes")
+    if normalised:
+        slice_ = _normalised(slice_)
+    field = slice_.face > 0
+    if not (isinstance(surface, str) and surface == "field"):
+        field &= ~slice_.mask("surface")
+    if not (isinstance(inner, str) and inner == "field") and "inner" in slice_.faces:
+        field &= ~slice_.mask("inner")
+    values = slice_.values[field]
+    cmap, lo, hi = colour_scale([values], slice_.shown, cmap=cmap, vmin=vmin,
+                                vmax=vmax, diverging=diverging, clip=clip)
+    norm = Normalize(lo, hi)
+    colours = plt.get_cmap(cmap)
+    n = slice_.n
+    rgba = np.zeros((n, n, 4))
+    rgba[field] = colours(norm(values))
+    top = _surface_colours(slice_, surface, slice_.mask("surface"))
+    if top is not None:
+        rgba[slice_.mask("surface")] = top
+    if not (isinstance(inner, str) and inner == "field") and "inner" in slice_.faces:
+        core = slice_.mask("inner")
+        X = slice_.reference[core]
+        r = np.linalg.norm(X, axis=-1)
+        plain = np.broadcast_to(_rgb(inner), (X.shape[0], 4)).copy()
+        plain[:, :3] *= _shading(slice_, X, X / r[:, None])[:, None]
+        rgba[core] = plain
+    # a pixel of the edge whose centre misses the body takes the colour of its
+    # nearest neighbour that sees it, at its coverage
+    seen = slice_.face > 0
+    partial = ~seen & (slice_.coverage > 0.0)
+    if np.any(partial):
+        from scipy.ndimage import distance_transform_edt
+        _, (rows, cols) = distance_transform_edt(~seen, return_indices=True)
+        rgba[partial] = rgba[rows[partial], cols[partial]]
+    rgba[..., 3] *= slice_.coverage
+    e = slice_.extent * scale
+    image = ax.imshow(rgba, extent=(-e, e, -e, e), origin="upper",
+                      interpolation="antialiased", **style)
+    if interfaces:
+        x, y = _interface_arcs(slice_, scale)
+        if x.size:
+            ax.plot(x, y, **BOUNDARY_STYLE)
+    if coastlines:
+        x, y = _coastlines(slice_, scale)
+        if x.size:
+            ax.plot(x, y, **COASTLINE_STYLE)
+    ax.set_aspect("equal")
+    ax.set_xlim(-e, e)
+    ax.set_ylim(-e, e)
+    ax.set_axis_off()
+    if colorbar:
+        ax.figure.colorbar(ScalarMappable(norm=norm, cmap=cmap), ax=ax,
+                           label=slice_.label, extend=colour_extend([values], lo, hi))
+    return image

{planetmodel-1.3.2 → planetmodel-1.4.0}/src/planetmodel/randomfield/basis.py

@@ -224,6 +224,48 @@ class SpectralBasis:
         Phi = self._modes[self.restriction.nodes]
         return (Phi ** 2) @ self.theta ** (-float(power))
 
+    def pointwise_variance_of(self, covariance: ArrayLike) -> np.ndarray:
+        """diag(Phi C Phi^T) at the physical nodes: the variance there of
+        a field of this degree whose coefficients have the covariance C,
+        a matrix (nmodes, nmodes).  `pointwise_variance(power)` is the
+        case C = diag(theta^-power)."""
+        C = np.asarray(covariance, dtype=float)
+        n = self.nmodes
+        if C.shape != (n, n):
+            raise ValueError(f"the covariance is a matrix of shape ({n}, {n}), "
+                             f"got {C.shape}")
+        Phi = self._modes[self.restriction.nodes]
+        return np.einsum("ij,ij->i", Phi @ C, Phi)
+
+    def galerkin(self, family: RadialOperatorFamily) -> np.ndarray:
+        """The matrix (nmodes, nmodes) of `family`'s member of this basis's
+        degree in the kept modes: Phi^T K'_l Phi, the bilinear form of A'_l
+        (u^T K'_l v, with K'_l its banded pencil) between pairs of the
+        M-orthonormal modes, so that for this basis's own family it is
+        diag(theta), and in general the Galerkin block of A'_l on the
+        span of the modes.  `family` must be on this basis's mesh with
+        the same weight.  The product is symmetrised explicitly,
+        (B + B^T) / 2, which removes its rounding asymmetry."""
+        own = self.family
+        if not isinstance(family, RadialOperatorFamily):
+            raise TypeError("family must be a RadialOperatorFamily")
+        if family.weight != own.weight:
+            raise ValueError(f"the family's weight is {family.weight!r}; this "
+                             f"basis's is {own.weight!r}")
+        mesh, other = own.mesh, family.mesh
+        if other is not mesh and (
+                other.nglob != mesh.nglob or other.ngll != mesh.ngll
+                or not np.array_equal(other.rglob, mesh.rglob)):
+            raise ValueError(f"the family's mesh ({other.nspec} elements of "
+                             f"{other.ngll} nodes on [{other.rglob[0]:g}, "
+                             f"{other.rglob[-1]:g}]) is not this basis's "
+                             f"({mesh.nspec} elements of {mesh.ngll} nodes on "
+                             f"[{mesh.rglob[0]:g}, {mesh.rglob[-1]:g}])")
+        l = self.degree
+        mass = family.mass(l)
+        B = self._Phi.T @ (mass[:, None] * family.apply(l, self._Phi))
+        return 0.5 * (B + B.T)
+
     def white_noise(self, *, rng: Any = None, size: int | None = None) -> np.ndarray:
         """Coefficients of white noise of the space, independent standard
         normals of shape (nmodes,) or (nmodes, size), column j of a batch

{planetmodel-1.3.2 → planetmodel-1.4.0}/src/planetmodel/randomfield/operator.py

@@ -24,7 +24,10 @@ LAPACK's banded symmetric drivers, with select-by-value for spectral
 truncation.  Since A_l = M + K_l with K_l >= 0, every eigenvalue
 satisfies theta >= 1, so negative fractional powers of the family are
 uniformly well behaved.  Eigenvectors are M-orthonormal
-(Phi^T M Phi = I), so A_l^s = Phi Theta^s Phi^T M on nodal vectors and
+(Phi^T M Phi = I) and of a fixed sign, the first component above
+`SIGN_RTOL` of the largest positive, so that the same eigenfunction
+discretised on two meshes has one sign; A_l^s = Phi Theta^s Phi^T M on
+nodal vectors and
 <f, A_l^s g> with the L^2(w dr) pairing is the H^s inner product of the
 Sobolev scale built on A.  White noise of the space is M^-1/2 z with
 z standard normal, whose covariance is M^-1.
@@ -59,7 +62,11 @@ from scipy.linalg import eig_banded, eigvals_banded, solveh_banded
 
 from ..mesh1d import Mesh1D
 
-__all__ = ["RadialOperatorFamily", "Coefficient", "Robin", "WEIGHTS"]
+__all__ = ["RadialOperatorFamily", "Coefficient", "Robin", "WEIGHTS", "SIGN_RTOL"]
+
+#: The size, relative to an eigenvector's largest component, from which a
+#: component counts as nonzero when the vector's sign is fixed.
+SIGN_RTOL = 1e-8
 
 #: The measures a family may carry: "r2" for r^2 dr, the radial part of the
 #: volume element of an annulus or ball, and "one" for plain dr on an interval.
@@ -93,6 +100,16 @@ def _nodal_coefficient(mesh: Mesh1D, c: Coefficient) -> np.ndarray:
     return out
 
 
+def _signed(Phi: np.ndarray) -> np.ndarray:
+    """The columns of Phi, each with its first component larger in size
+    than `SIGN_RTOL` of its largest made positive."""
+    size = np.abs(Phi)
+    big = size > SIGN_RTOL * size.max(axis=0, keepdims=True)
+    first = np.argmax(big, axis=0)
+    lead = Phi[first, np.arange(Phi.shape[1])]
+    return Phi * np.where(lead < 0.0, -1.0, 1.0)
+
+
 def _parse_robin(robin: Robin) -> tuple[float, float]:
     """(gamma_inner, gamma_outer) from None, one number, or a pair with
     None entries meaning Neumann."""
@@ -309,7 +326,10 @@ class RadialOperatorFamily:
         """Eigenpairs (theta, Phi) of A_l Phi = M Phi Theta, cached.
 
         Phi has the active-dof eigenvectors in its columns, ascending in
-        theta and M-orthonormal.  With `theta_max`, only the eigenvalues
+        theta, M-orthonormal and each of a fixed sign: its first component
+        above `SIGN_RTOL` of its largest is positive, so that the same
+        eigenfunction on two meshes has the same sign (LAPACK's is
+        arbitrary).  With `theta_max`, only the eigenvalues
         theta <= theta_max are computed; with `count`, the `count`
         smallest, selected by index so that none is lost to the rounding
         of a bound.  The cache keeps the widest range requested so far
@@ -334,7 +354,7 @@ class RadialOperatorFamily:
                     theta, Y = eig_banded(S, lower=False, select="i",
                                           select_range=(0, count - 1))
                     have = float(theta[-1])
-                self._pairs[l] = (theta, s[:, None] * Y, have)
+                self._pairs[l] = (theta, _signed(s[:, None] * Y), have)
             theta, Phi, _ = self._pairs[l]
             return theta[:count], Phi[:, :count]
         want = np.inf if theta_max is None else float(theta_max)
@@ -348,7 +368,7 @@ class RadialOperatorFamily:
             else:
                 theta, Y = eig_banded(S, lower=False, select="v",
                                       select_range=(0.0, want))
-            Phi = s[:, None] * Y
+            Phi = _signed(s[:, None] * Y)
             self._pairs[l] = (theta, Phi, want)
         theta, Phi, have = self._pairs[l]
         if want < have: