planetmodel 1.2.1__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.1 → planetmodel-1.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "planetmodel"
-version = "1.2.1"
+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.1 → planetmodel-1.2.4}/src/planetmodel/__init__.py

@@ -89,7 +89,7 @@ from .mapping import (
 from .materials import ElasticField, elastic_moduli, is_fluid, kappa_mu, moduli
 from .mesh1d import RadialMesh
 from .mesh1d.gravity import gravity, gravity_fields, mass
-from .model import Layer, Model
+from .model import CoarseningFit, Layer, Model
 from .pushforward import PulledBackField, PushedForwardField, pull_back, push_forward
 from .rheology import (
     dispersive_moduli,
@@ -104,12 +104,13 @@ 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.1"
+__version__ = "1.2.4"
 
 __all__ = [
     "Skeleton",
     "Location",
     "CoarseningMap",
+    "CoarseningFit",
     "Geometry",
     "LayerInfo",
     "InterfaceInfo",

{planetmodel-1.2.1 → planetmodel-1.2.4}/src/planetmodel/behaviours.py

@@ -31,18 +31,18 @@ type derived from `Model` alone.  The transformations `isotropic`,
 from __future__ import annotations
 
 import functools
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Mapping, Sequence
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
 from . import materials, rheology
-from .character import SCALAR
+from .character import DENSITY, SCALAR
 from .fields import ComposedField, Field
 from .mesh1d.gravity import gravity, gravity_fields, mass
 
 if TYPE_CHECKING:
-    from .model import Model
+    from .model import CoarseningFit, Model
 
 __all__ = ["layer_method", "with_moduli", "with_velocities", "Elastic", "ConstantQ",
            "SelfGravitating", "Viscoelastic", "ELASTIC_FAMILIES", "elastic_family"]
@@ -69,6 +69,25 @@ def elastic_family(name: str) -> tuple[str, ...]:
                    f"{list(materials.ELASTIC_NAMES)}")
 
 
+def _description_family(model: Model, group: Sequence[int]) -> tuple[str, ...]:
+    """The elastic names a merged group is refit through: the first
+    description every layer of the group holds, velocities preferred
+    since their products keep the derived moduli exact polynomials."""
+    held = set.intersection(*(set(model.layer(i).names) for i in group))
+    if "rho" in held and ({"vp", "vs"} <= held or {"vpv", "vsv"} <= held):
+        return tuple(nm for nm in VELOCITY_NAMES if nm in held)
+    five = materials.MODULI_NAMES[materials.Symmetry.VTI]
+    if set(five) <= held:
+        return five
+    iso = materials.MODULI_NAMES[materials.Symmetry.ISOTROPIC]
+    if set(iso) <= held:
+        return iso
+    raise ValueError(
+        f"merged layers {list(group)} share no complete elastic description "
+        "in velocities or moduli (perhaps only 'elastic_moduli'); keep the "
+        "interface, or re-describe the layers first")
+
+
 def layer_method[T](fn: Callable[..., T]) -> Callable[..., T]:
     """`fn(layer, *args, **kwargs)` as a method `model.fn(which, *args, **kwargs)`.
 
@@ -191,6 +210,39 @@ class Elastic:
             return out
         return out.replaced(layers=layers)
 
+    def coarsened(self: Model, *, keep: Iterable[int | str] | None = None,
+                  drop: Iterable[int | str] | None = None, degree: int = 3,
+                  n: int = 64) -> tuple[Model, CoarseningFit]:
+        """`Model.coarsened` with the elastic description kept consistent.
+
+        Each merged group is refit through its base description alone,
+        rho with the velocities where every merged layer holds them
+        (the five then follow as exact polynomial products of the
+        fits), else the five Love moduli, else kappa and mu; the other
+        elastic names are dropped before the fit and derived again
+        from the fitted description, so the coarse model satisfies the
+        elastic relations exactly.  A group whose layers share no such
+        description (one speaking only through `elastic_moduli`, say)
+        is refused.  Layers left whole are untouched.
+        """
+        from .model import Model
+        _, cmap = self._coarsening(keep=keep, drop=drop)
+        layers = [dict(layer.fields) for layer in self.layers]
+        merged = [group for group in cmap.layers if len(group) > 1]
+        for group in merged:
+            family = _description_family(self, group)
+            for i in group:
+                layers[i] = {k: f for k, f in layers[i].items()
+                             if k not in materials.ELASTIC_NAMES or k in family}
+        stripped = self.replaced(layers=layers, check=False)
+        coarse, fit = Model.coarsened(stripped, keep=keep, drop=drop,
+                                      degree=degree, n=n)
+        out = [dict(layer.fields) for layer in coarse.layers]
+        for j, group in enumerate(fit.map.layers):
+            if len(group) > 1:
+                out[j] = with_velocities(with_moduli(out[j]))
+        return coarse.replaced(layers=out), fit
+
     def isotropic(self: Model) -> Model:
         """The model with every elastic description replaced by its Voigt
         average: each layer keeps rho and everything that is not an
@@ -246,9 +298,10 @@ class SelfGravitating:
     density on every layer: the reference body's, computed on each call
     and never stored, as numbers by `gravity` and `mass`, as one radial
     field per layer by `gravity_fields`, and as a copy of the model
-    holding that field under the vocabulary name `g` by `with_gravity`.
-    A density that depends on direction is refused, and the geometry's
-    mapping does not enter (see `mesh1d.gravity`)."""
+    holding that field under the vocabulary name `g` by `with_gravity`;
+    `with_stratification` attaches d rho / d Phi_0 = rho'(r) / g(r) to
+    the fluid layers.  A density that depends on direction is refused,
+    and the geometry's mapping does not enter (see `mesh1d.gravity`)."""
 
     gravity = gravity
     mass = mass
@@ -268,6 +321,48 @@ class SelfGravitating:
             layers.append({**layer.fields, name: field})
         return self.replaced(layers=layers)
 
+    def with_stratification(self: Model, *, name: str = "drho_dphi0",
+                            replace: bool = False) -> Model:
+        """The model with the stratification of its fluid layers,
+        d rho / d Phi_0 = rho'(r) / g(r), attached to each of them
+        under `name`; solid layers, and layers whose fluidity cannot
+        be read, are left alone, and a model with no fluid layer is
+        refused.  rho' is exact where the density is polynomial; the
+        field is zero where g vanishes (the centre).  A fluid layer
+        already holding `name` is refused unless `replace`."""
+        fields = gravity_fields(self)
+        layers = []
+        n_fluid = 0
+        for layer, g in zip(self.layers, fields):
+            try:
+                fluid = materials.is_fluid(layer)
+            except KeyError:
+                fluid = False
+            if not fluid:
+                layers.append(dict(layer.fields))
+                continue
+            if name in layer and not replace:
+                raise ValueError(
+                    f"layer {layer.index} ({layer.name!r}) already holds {name!r}; "
+                    "pass replace=True to replace it")
+            rho = layer["rho"]
+            if not hasattr(rho, "derivative"):
+                raise ValueError(
+                    f"layer {layer.index} ({layer.name!r}) holds a rho that "
+                    "cannot state its radial derivative, so its "
+                    "stratification cannot be formed")
+            n_fluid += 1
+            strat = ComposedField(
+                lambda d, a: np.where(a != 0.0, d, 0.0)
+                / np.where(a != 0.0, a, 1.0),
+                (rho.derivative(nu=1), g), character=DENSITY, name=name)
+            layers.append({**layer.fields, name: strat})
+        if not n_fluid:
+            raise ValueError(
+                "no fluid layer: the stratification d rho / d Phi_0 is a "
+                "property of fluids, and no layer of this model is one")
+        return self.replaced(layers=layers)
+
 
 class Viscoelastic:
     """The rheology read from the fields: a layer's viscoelasticity, the

{planetmodel-1.2.1 → planetmodel-1.2.4}/src/planetmodel/catalogue.py

@@ -21,8 +21,9 @@ velocity are isotropic and get vph = vpv, vsh = vsv and eta = 1 as
 exact constants; the fluid outer core and ocean hold no qmu; the
 elastic values are those at a reference period of 1 s.
 
-`LayeredIsotropicElastic` builds an isotropic model of constant exact
-layers from a few numbers, a fluid layer being one with vs = 0; its
+`LayeredIsotropicElastic` builds an isotropic model of exact layers
+from a few numbers per layer, a constant or the coefficients of a
+polynomial in r / scale, a fluid layer being one with vs = 0; its
 `homogeneous` classmethod is the one-layer case.
 
 `MineosModel` is the model of a mineos deck, PREM's own tabulation
@@ -199,16 +200,20 @@ class PREM(Elastic, ConstantQ, SelfGravitating, Viscoelastic, Model):
 
 
 class LayeredIsotropicElastic(Elastic, SelfGravitating, Model):
-    """An isotropic model of constant layers between `boundaries`.
+    """An isotropic model of exact polynomial layers between `boundaries`.
 
     `boundaries` are the skeleton's, centre outward (an inner radius
     above zero gives a hollow model); `rho`, `vp` and `vs` give one
-    value per layer, and a layer with vs = 0 is fluid.  `name` is the
-    model's.
+    entry per layer, a number for a constant or a sequence of ascending
+    polynomial coefficients in r / scale, and a layer with vs = 0
+    throughout is fluid.  `name` is the model's.
     """
 
-    def __init__(self, boundaries: Sequence[float], *, rho: Sequence[float],
-                 vp: Sequence[float], vs: Sequence[float],
+    def __init__(self, boundaries: Sequence[float], *,
+                 rho: Sequence[float | Sequence[float]],
+                 vp: Sequence[float | Sequence[float]],
+                 vs: Sequence[float | Sequence[float]],
+                 scale: float = 1.0,
                  layer_names: Sequence[str | None] | None = None,
                  interface_names: Sequence[str | None] | None = None,
                  scales: Scales = Scales.SI, name: str | None = None) -> None:
@@ -222,11 +227,18 @@ class LayeredIsotropicElastic(Elastic, SelfGravitating, Model):
         layers = []
         for i in range(sk.nlayers):
             iv = sk.interval(i)
-            layers.append({
-                "rho": constant_field(iv, rho[i], character=DENSITY, name="rho"),
-                "vp": constant_field(iv, vp[i], name="vp"),
-                "vs": constant_field(iv, vs[i], name="vs"),
-            })
+            fields = {}
+            for key, character in (("rho", DENSITY), ("vp", SCALAR),
+                                   ("vs", SCALAR)):
+                value = values[key][i]
+                if np.isscalar(value):
+                    fields[key] = constant_field(iv, float(value),
+                                                 character=character, name=key)
+                else:
+                    fields[key] = RadialField(
+                        iv, polynomial_layer(iv, value, scale=scale),
+                        character=character, name=key)
+            layers.append(fields)
         super().__init__(geometry, layers, scales=scales, name=name)
 
     @classmethod

{planetmodel-1.2.1 → 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.1 → 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