planetmodel 1.2.3__tar.gz → 1.2.4__tar.gz

planetmodel-1.2.4/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: planetmodel
+Version: 1.2.4
+Summary: Spherically layered planetary models: reference bodies, fields, mappings and meshes
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: geophysics,seismology,planetary models,PREM,spectral elements,meshing
+Author: David Al-Attar
+Author-email: da380@cam.ac.uk
+Requires-Python: >=3.12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Provides-Extra: harmonics
+Provides-Extra: meshing
+Provides-Extra: mfem
+Provides-Extra: netcdf
+Provides-Extra: notebook
+Provides-Extra: plot
+Requires-Dist: ducc0 (>=0.41) ; extra == "harmonics"
+Requires-Dist: gmsh (>=4.13) ; extra == "meshing"
+Requires-Dist: ipykernel (>=6.29) ; extra == "notebook"
+Requires-Dist: matplotlib (>=3.11,<4) ; extra == "plot"
+Requires-Dist: mfem (>=4.8) ; extra == "mfem"
+Requires-Dist: netCDF4 (>=1.7) ; extra == "netcdf"
+Requires-Dist: numpy (>=2.0,<3)
+Requires-Dist: pyshtools (>=4.14) ; extra == "harmonics"
+Requires-Dist: scipy (>=1.15,<2)
+Project-URL: Homepage, https://github.com/da380/planetmodel
+Project-URL: Repository, https://github.com/da380/planetmodel
+Description-Content-Type: text/markdown
+
+# planetmodel
+
+Spherically layered planetary models — a planet described as concentric
+layers with physical properties on each — and the meshes that hand such
+a model to a numerical solver.
+
+With this library you can build a model (PREM out of the box, simple
+layered models, any mineos deck file, or a model type of your own), ask
+it for its properties with the discontinuities treated honestly, deform
+it with ellipticity or surface topography, and mesh it: a
+spectral-element mesh along the radius, or a 2D or 3D finite-element
+mesh for [MFEM](https://mfem.org), refined where you need it. A
+sub-package, `planetmodel.randomfield`, draws Matérn random fields on
+balls, annuli and layers.
+
+## Design
+
+**A skeleton.** The list of boundary radii, increasing, possibly
+starting above zero for a hollow shell. It answers geometric questions
+(which layer a radius lies in, the intervals between boundaries) and
+supports surgery: refine, truncate, hollow, extend, coarsen.
+
+**A geometry.** A skeleton placed in the physical world by one
+continuous mapping from the reference (spherical) body to the physical
+one, plus names for the layers and interfaces. Ellipticity or surface
+topography is therefore a property of the whole model, stated once,
+rather than something each field has to know about. The shipped mapping
+is the radial stretch `m(X) = (r + h) e_r` driven by any callable
+`h(r, theta, phi)`; any object with `__call__`,
+`deformation_gradient` and `jacobian` serves as a mapping, and a
+geometry checks the invariants (orientation preserved, continuous,
+kinked only on boundaries) when it is built.
+
+**A field on one layer.** An interval, a name, a character (the tensor
+rank and weight that say how the values transform), and
+`evaluate(r, theta, phi, *, frame)` giving components in the local
+spherical frame or in Cartesian ones. A discontinuity is simply two
+layers: ask each side and get each side's answer. Radial fields sit on
+an algebra that is exact on polynomials — PREM's moduli `rho v^2` are
+exact polynomials, not fits — and fields may be complex-valued, which
+is what a model frozen at a frequency holds.
+
+**One model class.** A model is a geometry with named fields on every
+layer; what a name like `"rho"` means comes from the shipped vocabulary
+or from the specs the model is given. A model type (`PREM`,
+`LayeredIsotropicElastic`, `MineosModel`, or your own) derives from
+`Model` alone — there is no hierarchy of model types — and the mixins
+of `planetmodel.behaviours` add the standard derivations: the Love
+moduli beside the velocities, the elastic tensor and its Voigt average,
+gravity, and the constant-Q and Maxwell rheologies frozen at a
+frequency.
+
+**Units in one place.** The model's `Scales` say what one stored unit
+of length, mass and time is in SI, and `converted` re-expresses the
+whole model, exactly for polynomials. Nothing else names a unit: radii
+are numbers, tolerances are relative, and the meshers hand the
+geometry's numbers to gmsh unchanged.
+
+**Two meshers.** `planetmodel.mesh1d` lays Gauss–Lobatto–Legendre
+elements along the radius with every boundary an element boundary,
+evaluates a model's fields and gravity on the nodes, and samples a
+model on an angular grid.
+`planetmodel.mesh3d` meshes a geometry, full or hollow, in 2D or 3D,
+with buffer shells outside it when a far-field condition needs room;
+element sizes are controlled per interface, and refinements
+(`NearPoints`, `near_curve`, or any size function of your own) make the
+mesh finer towards a coastline, a source region or a station network
+without coarsening anything elsewhere. Every mesh comes with a JSON
+manifest saying what each attribute means, and exports to MFEM together
+with the mapping's displacement and the model's fields.
+
+**Executable contracts.** `planetmodel.testing` holds one `check_*`
+function per protocol, and the shipped implementations and your own are
+held to the same call.
+
+## Installing
+
+```
+pip install planetmodel                     # numpy and scipy only
+pip install 'planetmodel[meshing]'          # 2D and 3D meshes via gmsh
+pip install 'planetmodel[mfem]'             # export to MFEM (PyMFEM)
+pip install 'planetmodel[harmonics]'        # grid transforms via pyshtools and ducc0
+pip install 'planetmodel[plot]'             # matplotlib, for the figures
+pip install 'planetmodel[notebook]'         # ipykernel, to run tutorials cell by cell
+```
+
+Python 3.12 or later. Nothing optional is imported by `import
+planetmodel`.
+
+## A first look
+
+```python
+from planetmodel import PREM, RadialMesh, flattening, gravity
+
+m = PREM()                              # exact polynomials, SI units
+
+# Fields live on layers, so a discontinuity gives two honest answers,
+# one from each side.
+r_cmb = m.geometry.interface("cmb").radius
+print(m.layer("outer_core")["rho"](r_cmb))         # density, core side
+print(m.layer("lowermost_mantle")["rho"](r_cmb))   # density, mantle side
+print(gravity(m, [r_cmb, 6371e3]))                 # gravity at the CMB and surface
+
+# Reshape the model: non-dimensionalise it, flatten it by 1/300, and
+# lay a radial spectral-element mesh over it.
+nd = m.nondimensionalised().stretched(flattening(1 / 300, rmax=1.0))
+mesh = RadialMesh(nd, ngll=5, drmax=0.05)
+print(mesh.nodal(nd, "rho").shape)      # density at every mesh node
+```
+
+## Where to go next
+
+- `examples/tutorials/`: eleven walkthroughs, from a skeleton to random
+  fields and deck files, each a `# %%` script that runs headless.
+- `src/planetmodel/mesh3d/manifest.py`: the manifest beside every mesh,
+  its schema described from the consumer's side.
+- `CONTRIBUTING.md`: the development setup, the hooks, the test
+  selections and how a release is made.
+
+## Tests
+
+```
+poetry run pytest                                   # the fast suite
+poetry run pytest -m "not slow"                     # with gmsh and MFEM
+poetry run ruff check .
+```
+
+## Licence
+
+BSD-3
+

planetmodel-1.2.4/README.md

@@ -0,0 +1,130 @@
+# planetmodel
+
+Spherically layered planetary models — a planet described as concentric
+layers with physical properties on each — and the meshes that hand such
+a model to a numerical solver.
+
+With this library you can build a model (PREM out of the box, simple
+layered models, any mineos deck file, or a model type of your own), ask
+it for its properties with the discontinuities treated honestly, deform
+it with ellipticity or surface topography, and mesh it: a
+spectral-element mesh along the radius, or a 2D or 3D finite-element
+mesh for [MFEM](https://mfem.org), refined where you need it. A
+sub-package, `planetmodel.randomfield`, draws Matérn random fields on
+balls, annuli and layers.
+
+## Design
+
+**A skeleton.** The list of boundary radii, increasing, possibly
+starting above zero for a hollow shell. It answers geometric questions
+(which layer a radius lies in, the intervals between boundaries) and
+supports surgery: refine, truncate, hollow, extend, coarsen.
+
+**A geometry.** A skeleton placed in the physical world by one
+continuous mapping from the reference (spherical) body to the physical
+one, plus names for the layers and interfaces. Ellipticity or surface
+topography is therefore a property of the whole model, stated once,
+rather than something each field has to know about. The shipped mapping
+is the radial stretch `m(X) = (r + h) e_r` driven by any callable
+`h(r, theta, phi)`; any object with `__call__`,
+`deformation_gradient` and `jacobian` serves as a mapping, and a
+geometry checks the invariants (orientation preserved, continuous,
+kinked only on boundaries) when it is built.
+
+**A field on one layer.** An interval, a name, a character (the tensor
+rank and weight that say how the values transform), and
+`evaluate(r, theta, phi, *, frame)` giving components in the local
+spherical frame or in Cartesian ones. A discontinuity is simply two
+layers: ask each side and get each side's answer. Radial fields sit on
+an algebra that is exact on polynomials — PREM's moduli `rho v^2` are
+exact polynomials, not fits — and fields may be complex-valued, which
+is what a model frozen at a frequency holds.
+
+**One model class.** A model is a geometry with named fields on every
+layer; what a name like `"rho"` means comes from the shipped vocabulary
+or from the specs the model is given. A model type (`PREM`,
+`LayeredIsotropicElastic`, `MineosModel`, or your own) derives from
+`Model` alone — there is no hierarchy of model types — and the mixins
+of `planetmodel.behaviours` add the standard derivations: the Love
+moduli beside the velocities, the elastic tensor and its Voigt average,
+gravity, and the constant-Q and Maxwell rheologies frozen at a
+frequency.
+
+**Units in one place.** The model's `Scales` say what one stored unit
+of length, mass and time is in SI, and `converted` re-expresses the
+whole model, exactly for polynomials. Nothing else names a unit: radii
+are numbers, tolerances are relative, and the meshers hand the
+geometry's numbers to gmsh unchanged.
+
+**Two meshers.** `planetmodel.mesh1d` lays Gauss–Lobatto–Legendre
+elements along the radius with every boundary an element boundary,
+evaluates a model's fields and gravity on the nodes, and samples a
+model on an angular grid.
+`planetmodel.mesh3d` meshes a geometry, full or hollow, in 2D or 3D,
+with buffer shells outside it when a far-field condition needs room;
+element sizes are controlled per interface, and refinements
+(`NearPoints`, `near_curve`, or any size function of your own) make the
+mesh finer towards a coastline, a source region or a station network
+without coarsening anything elsewhere. Every mesh comes with a JSON
+manifest saying what each attribute means, and exports to MFEM together
+with the mapping's displacement and the model's fields.
+
+**Executable contracts.** `planetmodel.testing` holds one `check_*`
+function per protocol, and the shipped implementations and your own are
+held to the same call.
+
+## Installing
+
+```
+pip install planetmodel                     # numpy and scipy only
+pip install 'planetmodel[meshing]'          # 2D and 3D meshes via gmsh
+pip install 'planetmodel[mfem]'             # export to MFEM (PyMFEM)
+pip install 'planetmodel[harmonics]'        # grid transforms via pyshtools and ducc0
+pip install 'planetmodel[plot]'             # matplotlib, for the figures
+pip install 'planetmodel[notebook]'         # ipykernel, to run tutorials cell by cell
+```
+
+Python 3.12 or later. Nothing optional is imported by `import
+planetmodel`.
+
+## A first look
+
+```python
+from planetmodel import PREM, RadialMesh, flattening, gravity
+
+m = PREM()                              # exact polynomials, SI units
+
+# Fields live on layers, so a discontinuity gives two honest answers,
+# one from each side.
+r_cmb = m.geometry.interface("cmb").radius
+print(m.layer("outer_core")["rho"](r_cmb))         # density, core side
+print(m.layer("lowermost_mantle")["rho"](r_cmb))   # density, mantle side
+print(gravity(m, [r_cmb, 6371e3]))                 # gravity at the CMB and surface
+
+# Reshape the model: non-dimensionalise it, flatten it by 1/300, and
+# lay a radial spectral-element mesh over it.
+nd = m.nondimensionalised().stretched(flattening(1 / 300, rmax=1.0))
+mesh = RadialMesh(nd, ngll=5, drmax=0.05)
+print(mesh.nodal(nd, "rho").shape)      # density at every mesh node
+```
+
+## Where to go next
+
+- `examples/tutorials/`: eleven walkthroughs, from a skeleton to random
+  fields and deck files, each a `# %%` script that runs headless.
+- `src/planetmodel/mesh3d/manifest.py`: the manifest beside every mesh,
+  its schema described from the consumer's side.
+- `CONTRIBUTING.md`: the development setup, the hooks, the test
+  selections and how a release is made.
+
+## Tests
+
+```
+poetry run pytest                                   # the fast suite
+poetry run pytest -m "not slow"                     # with gmsh and MFEM
+poetry run ruff check .
+```
+
+## Licence
+
+BSD-3

{planetmodel-1.2.3 → planetmodel-1.2.4}/pyproject.toml

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

{planetmodel-1.2.3 → planetmodel-1.2.4}/src/planetmodel/__init__.py

@@ -104,7 +104,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.2.3"
+__version__ = "1.2.4"
 
 __all__ = [
     "Skeleton",

{planetmodel-1.2.3 → planetmodel-1.2.4}/src/planetmodel/deck.py

@@ -146,10 +146,12 @@ class Deck:
 
     @property
     def names(self) -> tuple[str, ...]:
+        """The column names, in the deck's order."""
         return tuple(self.columns)
 
     @property
     def nknots(self) -> int:
+        """The number of knots, repeated radii counted twice."""
         return self.radius.size
 
     def __getitem__(self, name: str) -> np.ndarray:
@@ -189,6 +191,7 @@ class Deck:
 
     @property
     def nlayers(self) -> int:
+        """The number of layers the repeated radii cut the deck into."""
         return len(self.layers())
 
     def __repr__(self) -> str:

{planetmodel-1.2.3 → planetmodel-1.2.4}/src/planetmodel/displacement.py

@@ -63,7 +63,9 @@ class RadialDisplacement(Protocol):
     """
 
     def __call__(self, r: ArrayLike, theta: ArrayLike, phi: ArrayLike
-                 ) -> np.ndarray: ...
+                 ) -> np.ndarray:
+        """The displacement at the broadcast coordinates."""
+        ...
 
 
 def _broadcast(r: ArrayLike, theta: ArrayLike, phi: ArrayLike
@@ -80,19 +82,23 @@ class ZeroDisplacement:
     knots: tuple[float, ...] = ()
 
     def __call__(self, r: ArrayLike, theta: ArrayLike, phi: ArrayLike) -> np.ndarray:
+        """Zeros of the broadcast shape."""
         r, _, _ = _broadcast(r, theta, phi)
         return np.zeros(r.shape)
 
     def radial_derivative(self, r: ArrayLike, theta: ArrayLike,
                           phi: ArrayLike) -> np.ndarray:
+        """dh/dr: zeros of the broadcast shape."""
         return self(r, theta, phi)
 
     def angular_gradient(self, r: ArrayLike, theta: ArrayLike, phi: ArrayLike
                          ) -> tuple[np.ndarray, np.ndarray]:
+        """(dh/dtheta, dh/dphi): zeros of the broadcast shape."""
         z = self(r, theta, phi)
         return z, z.copy()
 
     def bounds(self) -> tuple[float, float]:
+        """(min h, max h): both zero."""
         return 0.0, 0.0
 
     def __repr__(self) -> str:
@@ -125,6 +131,7 @@ class CallableDisplacement:
         self.name = name
 
     def __call__(self, r: ArrayLike, theta: ArrayLike, phi: ArrayLike) -> np.ndarray:
+        """The wrapped callable at the broadcast coordinates."""
         r, theta, phi = _broadcast(r, theta, phi)
         return np.asarray(self._fn(r, theta, phi), dtype=float)
 
@@ -235,10 +242,12 @@ class LayerLinear:
 
     @property
     def boundaries(self) -> np.ndarray:
+        """The skeleton boundaries the reliefs sit on, innermost first."""
         return self._b
 
     @property
     def reliefs(self) -> tuple[Relief | None, ...]:
+        """One relief per boundary, None where a boundary carries none."""
         return tuple(self._reliefs)
 
     def _relief(self, j: int, theta: np.ndarray, phi: np.ndarray) -> np.ndarray:
@@ -264,6 +273,7 @@ class LayerLinear:
         return r, theta, phi, lo, hi, below, above
 
     def __call__(self, r: ArrayLike, theta: ArrayLike, phi: ArrayLike) -> np.ndarray:
+        """The reliefs of the point's layer, interpolated linearly in r."""
         r, theta, phi, lo, hi, below, above = self._pieces(r, theta, phi)
         t = (r - lo) / (hi - lo)
         return (1.0 - t) * below + t * above

{planetmodel-1.2.3 → planetmodel-1.2.4}/src/planetmodel/fields.py

@@ -7,10 +7,9 @@ no units: a discontinuity is two layers asked separately, and what the
 numbers mean is the model's business.
 
 `evaluate(r, theta, phi)` broadcasts its coordinates and returns float64
-(complex128 for a complex-valued field, as a model frozen at a frequency
-holds)
-of the broadcast shape followed by the character's Voigt shape for
-ranks 2 and 4, or its component shape otherwise.  Components are given
+— complex128 for a complex-valued field, such as a model frozen at a
+frequency holds — of the broadcast shape followed by the character's
+Voigt shape for ranks 2 and 4, or its component shape otherwise.  Components are given
 in the local spherical frame (e_r, e_theta, e_phi) at the point unless
 `frame="cartesian"` asks for Cartesian ones; a rank-1 field rotates as
 R v, a Voigt rank-2 as M v and a Voigt rank-4 as M C M^T with M the Bond
@@ -78,7 +77,10 @@ class Field(Protocol):
     name: str | None
 
     def evaluate(self, r: ArrayLike, theta: ArrayLike, phi: ArrayLike, *,
-                 frame: str = "spherical") -> np.ndarray: ...
+                 frame: str = "spherical") -> np.ndarray:
+        """The components at the broadcast coordinates, in `frame`:
+        the broadcast shape followed by the character's stored shape."""
+        ...
 
 
 def _interval(interval: tuple[float, float]) -> tuple[float, float]:
@@ -116,14 +118,17 @@ class FieldBase:
 
     @property
     def interval(self) -> tuple[float, float]:
+        """The (lo, hi) span of radius the field lives on."""
         return self._interval
 
     @property
     def character(self) -> Character:
+        """The field's law under a mapping: rank, weight, Voigt or not."""
         return self._character
 
     @property
     def name(self) -> str | None:
+        """The field's name, or None for an unnamed one."""
         return self._name
 
     @property
@@ -133,6 +138,7 @@ class FieldBase:
 
     @property
     def stored_shape(self) -> tuple[int, ...]:
+        """The trailing shape of the values: `stored_shape` of the character."""
         return stored_shape(self._character)
 
     # -- the question -------------------------------------------------------
@@ -425,6 +431,7 @@ class RadialField(FieldBase):
                          name=self._name)
 
     def renamed(self, name: str | None) -> "RadialField":
+        """The same field under `name`."""
         return self._map(lambda f: f, name=name)
 
     def __repr__(self) -> str:
@@ -490,6 +497,7 @@ class AnalyticField(FieldBase):
             rtol=self._rtol)
 
     def renamed(self, name: str | None) -> "AnalyticField":
+        """The same field under `name`."""
         return AnalyticField(self._interval, self._fn, character=self._character,
                              name=name, frame=self._frame, rtol=self._rtol)
 
@@ -562,10 +570,12 @@ class ComposedField(FieldBase):
 
     @property
     def fn(self) -> Callable[..., ArrayLike]:
+        """The pointwise function applied to the sources' values."""
         return self._fn
 
     @property
     def sources(self) -> tuple[Field, ...]:
+        """The fields whose values the function is applied to."""
         return self._sources
 
     def _values(self, r: np.ndarray, theta: np.ndarray | None,
@@ -575,6 +585,7 @@ class ComposedField(FieldBase):
         return to_stored(raw, r.shape, self._character, self)
 
     def on_interval(self, lo: float, hi: float) -> "ComposedField":
+        """The same composition with every source restated on (lo, hi)."""
         return ComposedField(self._fn, [s.on_interval(lo, hi) for s in self._sources],
                              character=self._character, name=self._name)
 
@@ -587,6 +598,7 @@ class ComposedField(FieldBase):
                              character=self._character, name=self._name)
 
     def renamed(self, name: str | None) -> "ComposedField":
+        """The same field under `name`."""
         return ComposedField(self._fn, self._sources, character=self._character,
                              name=name)
 

{planetmodel-1.2.3 → planetmodel-1.2.4}/src/planetmodel/geometry.py

@@ -161,10 +161,12 @@ class Geometry:
 
     @property
     def skeleton(self) -> Skeleton:
+        """The boundary radii the geometry is built over."""
         return self._sk
 
     @property
     def mapping(self) -> Mapping:
+        """The mapping taking the reference body to the physical one."""
         return self._m
 
     @property
@@ -174,6 +176,7 @@ class Geometry:
 
     @property
     def nlayers(self) -> int:
+        """The number of layers."""
         return self._sk.nlayers
 
     @property
@@ -183,15 +186,19 @@ class Geometry:
 
     @property
     def is_hollow(self) -> bool:
+        """Whether the innermost boundary is above zero."""
         return self._sk.is_hollow
 
     @property
     def layers(self) -> tuple[LayerInfo, ...]:
+        """Index, interval and name of every layer, centre outward."""
         return tuple(LayerInfo(i, self._sk.interval(i), name=self._layer_names[i])
                      for i in range(self._sk.nlayers))
 
     @property
     def interfaces(self) -> tuple[InterfaceInfo, ...]:
+        """Index, radius, `between` and name of every interface, centre
+        outward; see the module docstring for the numbering."""
         b = self._sk.boundaries
         L = self._sk.nlayers
         faces = []

{planetmodel-1.2.3 → planetmodel-1.2.4}/src/planetmodel/layerfunction.py

@@ -78,15 +78,25 @@ class LayerFunction(Protocol):
 
     interval: tuple[float, float]
 
-    def __call__(self, r: ArrayLike) -> np.ndarray: ...
+    def __call__(self, r: ArrayLike) -> np.ndarray:
+        """The values at `r`, of its shape."""
+        ...
 
-    def derivative(self, *, nu: int = 1) -> LayerFunction: ...
+    def derivative(self, *, nu: int = 1) -> LayerFunction:
+        """The nu-th derivative as a layer function; nu=0 is the function."""
+        ...
 
-    def integrate(self, a: float, b: float) -> float | complex: ...
+    def integrate(self, a: float, b: float) -> float | complex:
+        """The signed integral from a to b."""
+        ...
 
-    def on_interval(self, lo: float, hi: float) -> LayerFunction: ...
+    def on_interval(self, lo: float, hi: float) -> LayerFunction:
+        """The same function restated on [lo, hi]."""
+        ...
 
-    def rescaled(self, *, k: float, v: float) -> LayerFunction: ...
+    def rescaled(self, *, k: float, v: float) -> LayerFunction:
+        """v f(r / k) on the interval scaled by k."""
+        ...
 
 
 #: What `as_layer_function` accepts: a layer function, a scipy `PPoly` or
@@ -137,6 +147,7 @@ class PolynomialLayer:
 
     @property
     def interval(self) -> tuple[float, float]:
+        """The (lo, hi) span of radius the function is stated on."""
         return self._interval
 
     @property
@@ -146,12 +157,15 @@ class PolynomialLayer:
 
     @property
     def degree(self) -> int:
+        """The polynomial degree of the pieces."""
         return self._p.c.shape[0] - 1
 
     def __call__(self, r: ArrayLike) -> np.ndarray:
+        """The polynomial at `r`, of its shape."""
         return as_values(self._p(np.asarray(r, dtype=float)))
 
     def derivative(self, *, nu: int = 1) -> "PolynomialLayer":
+        """The nu-th derivative, exact on the coefficients."""
         if nu < 0:
             raise ValueError("nu must be non-negative")
         if nu == 0:
@@ -324,6 +338,7 @@ class NumericLayer:
 
     @property
     def interval(self) -> tuple[float, float]:
+        """The (lo, hi) span of radius the function is stated on."""
         return self._interval
 
     @property
@@ -332,11 +347,14 @@ class NumericLayer:
         return self._fn
 
     def __call__(self, r: ArrayLike) -> np.ndarray:
+        """The callable at `r`, broadcast to its shape."""
         r = np.asarray(r, dtype=float)
         out = as_values(self._fn(r))
         return np.broadcast_to(out, r.shape).copy() if out.shape != r.shape else out
 
     def derivative(self, *, nu: int = 1) -> "NumericLayer":
+        """The nu-th derivative: the supplied one, else a central
+        difference with a step relative to the interval's width."""
         if nu < 0:
             raise ValueError("nu must be non-negative")
         if nu == 0:
@@ -371,6 +389,7 @@ class NumericLayer:
         return NumericLayer((lo, hi), self._fn, derivative=self._d, dstep=self._dstep)
 
     def rescaled(self, *, k: float, v: float) -> "NumericLayer":
+        """v f(r / k) as a closure, on the interval scaled by k."""
         k, v = float(k), float(v)
         if k <= 0.0:
             raise ValueError(f"the coordinate factor must be positive, got {k}")