planetmodel 1.2.4__tar.gz → 1.3.0__tar.gz

{planetmodel-1.2.4 → planetmodel-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: planetmodel
-Version: 1.2.4
+Version: 1.3.0
 Summary: Spherically layered planetary models: reference bodies, fields, mappings and meshes
 License-Expression: BSD-3-Clause
 License-File: LICENSE
@@ -14,26 +14,32 @@ 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: maps
 Provides-Extra: meshing
 Provides-Extra: mfem
 Provides-Extra: netcdf
 Provides-Extra: notebook
 Provides-Extra: plot
-Requires-Dist: ducc0 (>=0.41) ; extra == "harmonics"
+Requires-Dist: cartopy (>=0.24,<1) ; extra == "maps"
+Requires-Dist: ducc0 (>=0.41,<1)
 Requires-Dist: gmsh (>=4.13) ; extra == "meshing"
 Requires-Dist: ipykernel (>=6.29) ; extra == "notebook"
+Requires-Dist: matplotlib (>=3.11,<4) ; extra == "maps"
 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
+# planetmodel: A library for spherical and aspherical planetary models
+
+[![CI](https://github.com/da380/planetmodel/actions/workflows/ci.yml/badge.svg)](https://github.com/da380/planetmodel/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/planetmodel.svg)](https://pypi.org/project/planetmodel/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Documentation Status](https://readthedocs.org/projects/planetmodel/badge/?version=latest)](https://planetmodel.readthedocs.io/en/latest/?badge=latest)
 
 Spherically layered planetary models — a planet described as concentric
 layers with physical properties on each — and the meshes that hand such
@@ -111,16 +117,19 @@ held to the same call.
 ## Installing
 
 ```
-pip install planetmodel                     # numpy and scipy only
+pip install planetmodel                     # numpy, scipy and ducc0
 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[netcdf]'           # the model file (netCDF4)
 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`.
+Python 3.12 or later. ducc0 does the spherical-harmonic transforms;
+it ships wheels for Linux on x86_64, macOS on Apple silicon and
+Windows, and elsewhere pip builds it from source, which needs a C++17
+compiler. `import planetmodel` loads numpy and scipy alone: ducc0 and
+every extra are imported where they are used.
 
 ## A first look
 
@@ -138,17 +147,18 @@ print(gravity(m, [r_cmb, 6371e3]))                 # gravity at the CMB and surf
 
 # 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))
+nd = m.nondimensionalised().stretched(flattening(1 / 300))
 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.
+- `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.
+- `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
   selections and how a release is made.
 

{planetmodel-1.2.4 → planetmodel-1.3.0}/README.md

@@ -1,4 +1,9 @@
-# planetmodel
+# planetmodel: A library for spherical and aspherical planetary models
+
+[![CI](https://github.com/da380/planetmodel/actions/workflows/ci.yml/badge.svg)](https://github.com/da380/planetmodel/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/planetmodel.svg)](https://pypi.org/project/planetmodel/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Documentation Status](https://readthedocs.org/projects/planetmodel/badge/?version=latest)](https://planetmodel.readthedocs.io/en/latest/?badge=latest)
 
 Spherically layered planetary models — a planet described as concentric
 layers with physical properties on each — and the meshes that hand such
@@ -76,16 +81,19 @@ held to the same call.
 ## Installing
 
 ```
-pip install planetmodel                     # numpy and scipy only
+pip install planetmodel                     # numpy, scipy and ducc0
 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[netcdf]'           # the model file (netCDF4)
 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`.
+Python 3.12 or later. ducc0 does the spherical-harmonic transforms;
+it ships wheels for Linux on x86_64, macOS on Apple silicon and
+Windows, and elsewhere pip builds it from source, which needs a C++17
+compiler. `import planetmodel` loads numpy and scipy alone: ducc0 and
+every extra are imported where they are used.
 
 ## A first look
 
@@ -103,17 +111,18 @@ print(gravity(m, [r_cmb, 6371e3]))                 # gravity at the CMB and surf
 
 # 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))
+nd = m.nondimensionalised().stretched(flattening(1 / 300))
 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.
+- `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.
+- `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
   selections and how a release is made.
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "planetmodel"
-version = "1.2.4"
+version = "1.3.0"
 description = "Spherically layered planetary models: reference bodies, fields, mappings and meshes"
 keywords = ["geophysics", "seismology", "planetary models", "PREM", "spectral elements", "meshing"]
 classifiers = [
@@ -21,6 +21,7 @@ requires-python = ">=3.12"
 dependencies = [
     "numpy>=2.0,<3",
     "scipy>=1.15,<2",
+    "ducc0>=0.41,<1",
 ]
 
 [project.urls]
@@ -32,20 +33,35 @@ meshing = ["gmsh>=4.13"]
 mfem = ["mfem>=4.8"]
 netcdf = ["netCDF4>=1.7"]
 plot = ["matplotlib>=3.11,<4"]
+maps = ["matplotlib>=3.11,<4", "cartopy>=0.24,<1"]
 notebook = ["ipykernel>=6.29"]
-harmonics = ["pyshtools (>=4.14)", "ducc0 (>=0.41)"]
 
 [dependency-groups]
 dev = [
     "pytest>=9",
+    # opens model files in the tests as CF tools do
+    "xarray>=2024.10",
     "ruff>=0.6",
     "pre-commit (>=4)",
     "pytest-cov (>=6)",
 ]
+docs = [
+    # The lower bound: the apidoc template in docs/apidoc_templates is
+    # named package.rst.jinja, the name Sphinx looks for from 7.4
+    # onwards.  The upper: Sphinx 9's autodoc evaluates PEP 695 `type`
+    # aliases, which fails on the names imported under TYPE_CHECKING.
+    "sphinx>=7.4,<9",
+    "furo>=2024.8",
+]
 
 [tool.poetry]
 packages = [{include = "planetmodel", from = "src"}]
 
+# The docs group serves Read the Docs and local documentation builds
+# (`poetry install --with docs`); a plain install leaves it out.
+[tool.poetry.group.docs]
+optional = true
+
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"
@@ -54,15 +70,24 @@ build-backend = "poetry.core.masonry.api"
 testpaths = ["tests"]
 pythonpath = ["src"]
 norecursedirs = [".*", "build", "dist"]
-# The fast suite is the default: it needs numpy and scipy alone, and the
-# `plot` and `harmonics` extras where installed.  `-m "not slow"` adds the
-# gmsh unit geometries and the MFEM exports, `-m ""` everything.
-addopts = "-m 'not gmsh and not mfem and not slow'"
+# The fast suite is the default: it needs the dependencies alone, and the
+# `plot`, `netcdf` and `maps` extras where installed.  `-m "not slow and not
+# network"` adds the gmsh unit geometries and the MFEM exports, `-m "not
+# network"` everything off the network, and `-m network` the registry check,
+# which fetches every data set.
+addopts = "-m 'not gmsh and not mfem and not slow and not network'"
+# netCDF4 1.7.4 sets an array's shape when writing a variable of two or
+# more dimensions, which numpy 2.5 deprecates; nothing of ours to change.
+filterwarnings = [
+    "ignore:Setting the shape on a NumPy array:DeprecationWarning",
+]
 markers = [
     "slow: long-running tests (minutes); deselect with -m 'not slow'",
     "gmsh: requires the optional gmsh dependency (planetmodel[meshing])",
     "mfem: requires PyMFEM (planetmodel[mfem])",
-    "harmonics: requires pyshtools (planetmodel[harmonics])",
+    "netcdf: requires netCDF4 (planetmodel[netcdf])",
+    "maps: requires cartopy (planetmodel[maps])",
+    "network: fetches published data sets from their hosts; run with -m network",
 ]
 
 [tool.ruff]

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

@@ -20,11 +20,19 @@ Modules reached by name, one level down:
   catalogue    PREM, LayeredIsotropicElastic and MineosModel, model types
   deck         tabulated models: decks, their formats, fields by interpolation
   sampling     a model on a radial mesh times an angular grid
-  harmonics    real spherical harmonics; grid transforms via pyshtools (optional)
-  plotting     radial profiles drawn one way, radius upward (matplotlib, optional)
+  lateral      values between the nodes of an angular grid: the lateral rules
+  modelfile    the model file: a model in one netCDF file (netCDF4, optional)
+  harmonics    real spherical harmonics, through ducc0
+  slices       a field on a sphere, a section or a profile; spectra and
+               correlations by degree
+  plotting     profiles, sections, maps and spectra drawn (matplotlib and
+               cartopy, optional), and VTK files for ParaView
   mesh1d       radial spectral-element meshes (GLL), nodal values, gravity
+               and hydrostatic pressure
   mesh3d       2D and 3D meshes via gmsh, and MFEM export
   randomfield  Matern random fields on balls, annuli and layers
+  datasets     published models: their entries, fetched on demand into a
+               cache, read into the library's objects
   testing      the executable contracts, `check_field` and its kin
 """
 
@@ -40,7 +48,10 @@ from .behaviours import (
 from .catalogue import PREM, LayeredIsotropicElastic, MineosModel
 from .character import DENSITY, ELASTIC, SCALAR, STRESS, VECTOR, Character, Symmetry
 from .deck import (
+    GIA,
     MINEOS,
+    ND,
+    TVEL,
     Deck,
     DeckFormat,
     Tabulated,
@@ -56,6 +67,7 @@ from .displacement import (
     flattening,
     layer_linear,
 )
+from .expansions import HarmonicField, HarmonicFunction
 from .fields import (
     AnalyticField,
     ComposedField,
@@ -64,8 +76,10 @@ from .fields import (
     RadialField,
     constant_field,
 )
+from .frames import from_geographic, geographic
 from .geometry import Geometry, InterfaceInfo, LayerInfo
-from .harmonics import analyse_grid, real_harmonics, synthesise, synthesise_grid
+from .gridded import GriddedDisplacement, GriddedField, GriddedFunction
+from .harmonics import real_harmonics, synthesise
 from .layerfunction import (
     LayerFunction,
     NumericLayer,
@@ -87,9 +101,11 @@ from .mapping import (
     validity_lattice,
 )
 from .materials import ElasticField, elastic_moduli, is_fluid, kappa_mu, moduli
+from .means import spherical_mean, spherically_averaged
 from .mesh1d import RadialMesh
-from .mesh1d.gravity import gravity, gravity_fields, mass
+from .mesh1d.gravity import gravity, gravity_fields, mass, pressure, pressure_fields
 from .model import CoarseningFit, Layer, Model
+from .perturbation import PerturbedField, perturbed, unperturbed
 from .pushforward import PulledBackField, PushedForwardField, pull_back, push_forward
 from .rheology import (
     dispersive_moduli,
@@ -98,13 +114,20 @@ from .rheology import (
     is_viscoelastic,
     reference_omega,
 )
-from .sampling import AngularGrid, Sample, equiangular, gauss_legendre, sample
+from .sampling import (
+    AngularGrid,
+    Sample,
+    driscoll_healy,
+    equiangular,
+    gauss_legendre,
+    sample,
+)
 from .skeleton import CoarseningMap, Location, Skeleton
 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.4"
+__version__ = "1.3.0"
 
 __all__ = [
     "Skeleton",
@@ -148,6 +171,16 @@ __all__ = [
     "AnalyticField",
     "ComposedField",
     "constant_field",
+    "GriddedField",
+    "GriddedFunction",
+    "GriddedDisplacement",
+    "HarmonicField",
+    "HarmonicFunction",
+    "PerturbedField",
+    "perturbed",
+    "unperturbed",
+    "spherical_mean",
+    "spherically_averaged",
     "ElasticField",
     "is_fluid",
     "moduli",
@@ -185,6 +218,9 @@ __all__ = [
     "Deck",
     "DeckFormat",
     "MINEOS",
+    "GIA",
+    "ND",
+    "TVEL",
     "read_deck",
     "write_deck",
     "deck_layers",
@@ -195,14 +231,17 @@ __all__ = [
     "Sample",
     "sample",
     "gauss_legendre",
+    "driscoll_healy",
     "equiangular",
+    "geographic",
+    "from_geographic",
     "real_harmonics",
     "synthesise",
-    "synthesise_grid",
-    "analyse_grid",
     "gravity",
     "mass",
     "gravity_fields",
+    "pressure",
+    "pressure_fields",
     "testing",
     "__version__",
 ]

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

@@ -39,22 +39,23 @@ import numpy as np
 from . import materials, rheology
 from .character import DENSITY, SCALAR
 from .fields import ComposedField, Field
-from .mesh1d.gravity import gravity, gravity_fields, mass
+from .mesh1d.gravity import gravity, gravity_fields, mass, pressure, pressure_fields
 
 if TYPE_CHECKING:
-    from .model import CoarseningFit, Model
+    from .model import CoarseningFit, Layer, Model
 
 __all__ = ["layer_method", "with_moduli", "with_velocities", "Elastic", "ConstantQ",
            "SelfGravitating", "Viscoelastic", "ELASTIC_FAMILIES", "elastic_family"]
 
 #: The velocity names an elastic description may be given in.
-VELOCITY_NAMES = ("vp", "vs", "vpv", "vph", "vsv", "vsh", "eta")
+VELOCITY_NAMES = materials.VELOCITY_NAMES
 
 #: The ways a layer describes its elastic medium, each a family of names
-#: that is complete on its own: the velocities beside rho, the isotropic
-#: moduli, the five Love moduli, and the tensor stored under
-#: `elastic_moduli`.
-ELASTIC_FAMILIES = (VELOCITY_NAMES,
+#: that is complete on its own: the isotropic and the transversely
+#: isotropic velocities beside rho, the isotropic moduli, the five Love
+#: moduli, and the tensor stored under `elastic_moduli`.
+ELASTIC_FAMILIES = (materials.VELOCITY_SETS[materials.Symmetry.ISOTROPIC],
+                    materials.VELOCITY_SETS[materials.Symmetry.VTI],
                     materials.MODULI_NAMES[materials.Symmetry.ISOTROPIC],
                     materials.MODULI_NAMES[materials.Symmetry.VTI],
                     ("elastic_moduli",))
@@ -69,6 +70,40 @@ def elastic_family(name: str) -> tuple[str, ...]:
                    f"{list(materials.ELASTIC_NAMES)}")
 
 
+#: The fields a frozen layer's complex moduli were derived from.
+_FROZEN_FROM = ("rho",) + materials.ELASTIC_NAMES + rheology.RHEOLOGY_NAMES
+
+
+def _refuse_frozen(model: Model, why: str) -> None:
+    """Refuse a change that would leave a frozen model's moduli stale."""
+    if rheology.is_frozen(model):
+        raise ValueError(
+            f"the model is frozen at omega = {float(model.constant('omega')):g} "
+            f"and {why}, so the frozen moduli would go stale; make the change "
+            "on the elastic model and freeze it again")
+
+
+def _refuse_other_symmetry(layer: Layer, name: str) -> None:
+    """Refuse a velocity of one symmetry on a layer holding velocities of
+    the other, naming what the layer holds and the way out."""
+    sets = materials.VELOCITY_SETS
+    own = next((s for s, names in sets.items() if name in names), None)
+    held = [n for s, names in sets.items() if s is not own for n in names
+            if n in layer]
+    if own is None or not held:
+        return
+    if own is materials.Symmetry.ISOTROPIC:
+        remedy = ("replace one of those, or describe the layer by vp and vs "
+                  "with isotropic() first")
+    else:
+        remedy = (f"no one velocity completes {list(sets[own])}; replace one of "
+                  "the Love moduli A, C, F, L, N instead, and the velocities are "
+                  "derived again from the five")
+    where = f"layer {layer.index}" + (f" ({layer.name!r})" if layer.name else "")
+    raise ValueError(f"{where} holds the velocities {held}, so {name!r} would "
+                     f"contradict them; {remedy}")
+
+
 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
@@ -160,18 +195,19 @@ class Elastic:
     vanishing of shear, and `isotropic()` the model re-described by its
     Voigt average, kappa and mu with the five and the velocities
     recomputed from them.  A layer holding a general anisotropic tensor
-    is refused by the three that read the five, until the general Voigt
-    average is written.
+    is refused by the three that read the five.
 
     The derived fields are kept in step by `with_field`: replacing an
     elastic field on a layer makes the family it belongs to (rho with
-    the velocities, kappa and mu, or the five) the description, drops
-    the other elastic names from that layer, and completes the
-    description again, so the five follow a new `vs` and the velocities
-    a new `L`; a field added beside the existing ones is attached as it
-    is.  A change that goes through `replaced` directly, as the
-    library's own transformations do, is the caller's to keep
-    consistent.
+    the isotropic or the transversely isotropic velocities, kappa and
+    mu, or the five) the description, drops the other elastic names from
+    that layer, and completes the description again, so the five follow
+    a new `vs` and the velocities a new `L`; a field added beside the
+    existing ones is attached as it is, and a velocity of the other
+    symmetry than the layer's is refused, as is any change to what a
+    frozen model's moduli were derived from.  A change that goes through
+    `replaced` directly, as the library's own transformations do, is the
+    caller's to keep consistent.
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -192,16 +228,30 @@ class Elastic:
 
         Replacing an elastic field makes its family the layer's
         description and derives the other elastic fields from it again;
-        a field added beside the existing ones, or a family too
-        incomplete to describe the medium, is attached as it is.
+        replacing rho on a layer holding velocities makes the velocities
+        the description, so the moduli follow the new density.  A field
+        added beside the existing ones, or a family too incomplete to
+        describe the medium, is attached as it is.  A velocity of one
+        symmetry on a layer holding velocities of the other is refused,
+        added or replaced: no single velocity completes the other set,
+        and `isotropic()` re-describes a layer by vp and vs.  On a frozen
+        model (`rheology.is_frozen`) rho, the elastic names and the
+        rheology names are refused, the frozen moduli having been derived
+        from them.
         """
         from .model import Model
+        if name in _FROZEN_FROM or rheology.is_rheology_name(name):
+            _refuse_frozen(self, f"its moduli were derived from {name!r}")
+        _refuse_other_symmetry(self.layer(which), name)
         out = Model.with_field(self, which, name, field, replace=replace)
-        if not replace or name not in materials.ELASTIC_NAMES:
-            return out
         i = self.layer(which).index
+        if name == "rho" and any(n in out.layer(i) for n in VELOCITY_NAMES):
+            keep = VELOCITY_NAMES
+        elif not replace or name not in materials.ELASTIC_NAMES:
+            return out
+        else:
+            keep = elastic_family(name)
         layers = [dict(layer.fields) for layer in out.layers]
-        keep = elastic_family(name)
         fields = {k: f for k, f in layers[i].items()
                   if k not in materials.ELASTIC_NAMES or k in keep}
         try:
@@ -223,9 +273,11 @@ class Elastic:
         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.
+        is refused, as is a frozen model.  Layers left whole are
+        untouched.
         """
         from .model import Model
+        _refuse_frozen(self, "coarsening refits the elastic description")
         _, 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]
@@ -293,12 +345,28 @@ class ConstantQ:
                                       name="elastic_moduli")
 
 
+def _with_radial(model: Model, fields: Sequence[Field], name: str,
+                 replace: bool) -> Model:
+    """The model with one field per layer attached under `name`, a layer
+    already holding it refused unless `replace`."""
+    layers = []
+    for layer, field in zip(model.layers, fields):
+        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")
+        layers.append({**layer.fields, name: field})
+    return model.replaced(layers=layers)
+
+
 class SelfGravitating:
-    """The gravity and mass of a spherically symmetric model with a radial
-    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`;
+    """The gravity, mass and pressure of a spherically symmetric model with
+    a radial density on every layer: the reference body's, computed on
+    each call and never stored, as numbers by `gravity`, `mass` and
+    `pressure`, as one radial field per layer by `gravity_fields` and
+    `pressure_fields`, and as a copy of the model holding that field
+    under the vocabulary name `g` by `with_gravity`, `pressure` by
+    `with_pressure`;
     `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`)."""
@@ -306,20 +374,21 @@ class SelfGravitating:
     gravity = gravity
     mass = mass
     gravity_fields = gravity_fields
+    pressure = pressure
+    pressure_fields = pressure_fields
 
     def with_gravity(self: Model, *, name: str = "g", replace: bool = False) -> Model:
         """The model with its gravity attached to every layer as a radial
         field under `name`, exact where the density is polynomial; a
         layer already holding `name` is refused unless `replace`."""
-        fields = gravity_fields(self)
-        layers = []
-        for layer, field in zip(self.layers, fields):
-            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")
-            layers.append({**layer.fields, name: field})
-        return self.replaced(layers=layers)
+        return _with_radial(self, gravity_fields(self), name, replace)
+
+    def with_pressure(self: Model, *, name: str = "pressure",
+                      replace: bool = False) -> Model:
+        """The model with its hydrostatic pressure attached to every layer
+        as a radial field under `name` (`mesh1d.gravity`); a layer already
+        holding `name` is refused unless `replace`."""
+        return _with_radial(self, pressure_fields(self), name, replace)
 
     def with_stratification(self: Model, *, name: str = "drho_dphi0",
                             replace: bool = False) -> Model:
@@ -373,9 +442,9 @@ class Viscoelastic:
     frozen = rheology.frozen
 
     def elastic(self: Model) -> Model:
-        """The model without its rheology fields (`RHEOLOGY_NAMES`), so
+        """The model without its rheology fields (`rheology.is_rheology_name`), so
         that every layer is elastic; a frozen model keeps its complex
         moduli, which are what its rheology became."""
         layers = [{k: f for k, f in layer.fields.items()
-                   if k not in rheology.RHEOLOGY_NAMES} for layer in self.layers]
+                   if not rheology.is_rheology_name(k)} for layer in self.layers]
         return self.replaced(layers=layers, check=False)

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

@@ -56,6 +56,10 @@ __all__ = ["PREM", "LayeredIsotropicElastic", "MineosModel", "PREM_RADIUS"]
 #: The normalisation radius a of PREM's polynomials, metres.
 PREM_RADIUS = 6371e3
 
+_PREM_CITATION = ("Dziewonski, A. M. and D. L. Anderson (1981).  Preliminary "
+                  "reference Earth model.  Phys. Earth Planet. Inter. 25, 297-356, "
+                  "doi:10.1016/0031-9201(81)90046-7")
+
 #: Table I of Dziewonski and Anderson (1981), centre outward: the radii
 #: of each region in metres and the polynomial coefficients of each
 #: column in the paper's units, ascending in x = r / a.
@@ -196,7 +200,8 @@ class PREM(Elastic, ConstantQ, SelfGravitating, Viscoelastic, Model):
                     name=name)
             layers.append(fields)
         super().__init__(geometry, layers, scales=Scales.SI,
-                         name="PREM" if ocean else "PREM (no ocean)")
+                         name="PREM" if ocean else "PREM (no ocean)",
+                         citation=(_PREM_CITATION,))
 
 
 class LayeredIsotropicElastic(Elastic, SelfGravitating, Model):
@@ -263,11 +268,12 @@ class MineosModel(Elastic, ConstantQ, SelfGravitating, Viscoelastic, Tabulated,
     becomes the constant `omega_ref` that `moduli_at` and `frozen`
     disperse about, and its title is the model's name.  The deck is
     kept as `deck`, its knots per layer as `knots` and its header as
-    `header`, so `to_deck` writes the model back out.
+    `header`, so `to_deck` writes the model back out.  The model is in
+    SI, as the deck is; `converted` gives it in other scales.
     """
 
     def __init__(self, source: str | os.PathLike[str] | Deck, *,
-                 kind: str = "cubic", scales: Scales = Scales.SI) -> None:
+                 kind: str = "cubic") -> None:
         deck = source if isinstance(source, Deck) else read_deck(source, MINEOS)
         skeleton, layers = deck_layers(deck, kind=kind)
         layer_names, interface_names = mineos_names(deck)
@@ -282,5 +288,5 @@ class MineosModel(Elastic, ConstantQ, SelfGravitating, Viscoelastic, Tabulated,
         self.deck = deck
         self.knots = deck_knots(deck)
         self.header = deck.header
-        super().__init__(geometry, layers, scales=scales, constants=constants,
+        super().__init__(geometry, layers, constants=constants,
                          name=str(deck.header.get("name", "")) or None)