PySLFP: Python Sea Level Fingerprints
pyslfp computes how sea level changes when mass is redistributed at the
Earth's surface, on a spherically symmetric, self-gravitating, rotating Earth.
It solves the sea level equation with the deformation of the solid Earth,
gravitational self-consistency between ice, oceans and solid Earth, and
rotational feedbacks, for two descriptions of the solid Earth:
- Elastic, for sea level fingerprints: the instantaneous pattern of sea level change produced, for example, by the melting of an ice sheet.
- Viscoelastic, for glacial isostatic adjustment (GIA): sea level, deformation and rotation evolving through an ice history on an Earth with a mantle viscosity, with fixed or migrating shorelines.
Around these it provides:
- Love numbers computed for any spherically layered model described by planetmodel, including the generalised numbers the adjoint theory needs; a table for PREM is used by default.
- Sensitivity kernels by adjoint methods: for elastic fingerprints, and for a viscoelastic evolution with respect to the ice history, the initial sea level and the mantle viscosity.
- The fingerprint and the viscoelastic response to an ice history as linear
operators between Hilbert spaces, with observation models for tide gauges,
satellite altimetry, GRACE and GNSS, for Bayesian inversions built on
pygeoinf. - Ice histories (ICE-5G, ICE-6G and ICE-7G), regional masks, and plotting on map projections.
The theory follows Al-Attar et al. (2024) for fingerprints and their kernels. Viscoelastic loading uses the internal-variable formulation of Al-Attar & Tromp (2014), and its adjoints and sensitivity kernels the adjoint theory of glacial isostatic adjustment of Crawford et al. (2018), extended to rotational feedbacks by Yu et al. (2025). Documentation is at pyslfp.readthedocs.io.
Installation
pyslfp requires Python 3.12 or later and is available from PyPI:
pip install pyslfp
Plotting works out of the box. plt.show() needs matplotlib to have an
interactive backend, which on a Python built with tkinter, the usual case, it
already has. Where tkinter is absent, or if you would rather use Qt:
pip install "pyslfp[interactive]"
For development, clone the repository and use Poetry:
poetry install # runtime dependencies only
poetry install --with dev # adds pytest, sphinx, ruff, jupyter and the hooks
See CONTRIBUTING.md for the git hooks, the documentation build and the release process.
A sea level fingerprint
The following melts ten per cent of the West Antarctic Ice Sheet and plots the resulting sea level change. It is a condensed form of the first tutorial.
import matplotlib.pyplot as plt
import pyslfp as sl
# PREM Earth model with present-day ICE-7G as the background state.
sle = sl.LinearSeaLevelEquation.from_defaults(lmax=256)
# The load associated with a 10% loss of West Antarctic ice.
direct_load = sle.state.west_antarctic_load(fraction=0.1)
# Sea level change, vertical displacement, potential change, and the angular
# velocity change (polar wander and length of day).
relative_sea_level_change, displacement, potential_change, angular_velocity_change = (
sle.solve_sea_level_equation(direct_load)
)
# Plot the sea level change in metres, masked to the oceans.
metre = sle.state.model.parameters.length_scale
fig, ax = sl.create_map_figure(figsize=(12, 6))
sl.plot(
relative_sea_level_change * sle.state.ocean_projection() * metre,
ax=ax,
colorbar_kwargs={"label": "Sea level change (m)"},
)
plt.show()
LinearSeaLevelEquation holds the shoreline fixed, the usual assumption for
present-day and near-future problems. The engine beneath it,
SeaLevelEquation, also solves the nonlinear equation with migrating
shorelines, and the generalised equation that adjoint calculations need.
A glacial isostatic adjustment run
The following runs the last deglaciation, ICE-7G from 26 ka to the present, on PREM with a Maxwell mantle of viscosity 10²¹ Pa s beneath an elastic lithosphere. It is a condensed form of the seventh tutorial, and takes about half a minute.
import numpy as np
import pyslfp as sl
from pyslfp.ice import IceNG
from pyslfp.viscoelastic import (
SeaLevelEvolution,
ViscoelasticOperator,
prem_maxwell,
viscoelastic_earth,
)
lmax = 64
# PREM with a Maxwell mantle of 10^21 Pa s, its top 77 km left elastic,
# made into the Earth model and the rheology in the library's units.
model = prem_maxwell(upper_mantle=1.0e21, lower_mantle=1.0e21)
earth_model, rheology = viscoelastic_earth(model, lmax)
operator = ViscoelasticOperator(rheology, lmax)
# The background state that ICE-7G records at 26 ka.
ice_model = IceNG(length_scale=earth_model.parameters.length_scale)
state = sl.EarthState.from_ice_model(ice_model, 26.0, earth_model)
# Half-kiloyear steps to the present; each snapshot holds the response,
# whose fields (sea level change, displacement, potential change) are
# read by name, with the angular velocity change beside them.
evolution = SeaLevelEvolution(operator, state)
snapshots, _ = evolution.run_ice_history(np.arange(26.0, -0.1, -0.5), ice_model)
present = snapshots[-1].response.field("relative_sea_level_change")
run_ice_history takes shorelines="migrating" to let the shorelines move,
and final_sea_level= to choose the initial sea level so that the run reaches
a given present-day sea level, as an ice history without its own sea level
needs. SeaLevelEvolution computes sensitivity kernels of any objective built
from the snapshots, by adjoint_ice_history and
continuous_adjoint_ice_history.
Units
Calculations are carried out in a single non-dimensional frame, planetmodel's
Scales.geophysical at the Earth's mean radius, in which the radius, the mean
density and the gravitational constant are one. Results are returned in these
units and converted to SI through the scales held by
state.model.parameters: length_scale for sea level and displacement,
parameters.scales.factor(...) for anything else. Ice histories are dated in
kiloyears before present. See the
units page.
Documentation
- Theory and methods: the sea level equation, Love numbers and their conventions, rotational feedback, viscoelastic loading and the adjoint kernels.
- Numerics and performance: discretisation, convergence, cost, and the use of threads and processes.
- The API reference.
- The theory note,
docs/theory/pyslfp_theory.pdf, with the full derivations.
Tutorials
The tutorials are scripts under tutorials/scripts, written in cells (# %%) so
that they run from the command line or cell by cell in an editor. Each has a
notebook generated from it in tutorials/notebooks, which can be run locally or
in Google Colab. They read the real datasets, so the first run downloads them.
Data
The package needs a number of external datasets: a table of Love numbers for PREM, the ICE-NG ice histories, ETOPO 2022 topography, the GLOSS tide gauge network, the Randolph Glacier Inventory, and shapefiles for the regional definitions. They are not distributed with the package, but downloaded from Zenodo on first use and cached locally, so the first call that needs a dataset pauses while it is fetched. Datasets are fetched individually, so only what is used is downloaded.
The cache lives in ~/.pyslfp_data unless the PYSLFP_DATA environment
variable says otherwise, which is useful on shared machines and in CI. The cache
is only checked for presence, so a dataset that has changed on Zenodo is not
fetched again by itself: pyslfp.data.ensure_data("LOVE_NUMBERS", refresh=True)
deletes the cached copy and downloads it afresh, and
LoveNumbers.default(refresh=True) does the same for the Love number table.
Performance
The spherical harmonic transforms dominate the cost of a sea level
calculation; they use the multi-threaded ducc0 backend, with the thread count
read from OMP_NUM_THREADS when Python starts (all cores if it is unset). When
running many independent solves in worker processes, set OMP_NUM_THREADS=1
before starting Python so that the workers share the cores rather than
oversubscribe them; pyslfp.set_num_threads(n) changes the count in the
current process. The
numerics page gives
costs and the details.
Package layout
| Module | Contents |
|---|---|
core/ |
The shared engine: EarthModelParameters and EarthModel (physical constants, scales, the spherical harmonic discretisation and the Love numbers), EarthState (ice thickness and sea level, the ocean function, projections and ready-made loads), SeaLevelEquation, the linear, generalised, adjoint and nonlinear solvers, GRDResponse, the response to a load as one spectral object with its Hilbert space, and FieldHistorySpace, the space of fields through time, a pygeoinf tensor product. The load and response spaces, the operators both drivers share (the centrifugal potential, the geocentric sea level) and the spatial projections and averages as pygeoinf operators. Also the regional masks (IMBIE Antarctic basins, Mouginot Greenland basins, IHO seas, HydroBASINS catchments, AR6 and GTN-G regions, Natural Earth oceans), the landlocked depressions and the labelling of water bodies, and the thread control for the transforms and BLAS. |
elastic/ |
LinearSeaLevelEquation, the fingerprint driver, and FingerPrintOperator, the fingerprint and its adjoint as a pygeoinf operator. |
viscoelastic/ |
Rheology, ViscoelasticOperator (the radial time stepping), SeaLevelEvolution (the coupled evolution and its adjoints), the kernel and measurement types, decay-time functionals and calibrate_initial_sea_level, SeaLevelEvolutionOperator, the evolution as a pygeoinf operator on the ice history, the initial sea level and the log viscosity (LogViscositySpace), with its derivative and second derivative by the discrete or the continuous method, and IceHistoryOperator, its linear case under frozen shorelines, whose adjoint gives the Sobolev kernels. |
love_numbers/ |
LoveNumbers and the radial spectral-element solver that computes them from any planetmodel model. |
observations/ |
Tide gauges, satellite altimetry, GRACE and GNSS: the observation models, each an observable from the model space with its sampling at stations, points or coefficients and its noise; the networks' data; and the frame of GNSS solutions, as Helmert parameters or frame-invariant data. |
ice/ |
The ice model interfaces, IceNG for the ICE-5G, ICE-6G and ICE-7G histories, AnalyticalIceModel for testing, and export to planetmodel surface histories. |
models/ |
Model spaces for inversions: named load components (ice sheets, glaciers, land water, firn, sterodynamic sea level, ocean density), ModelSetup, which assembles them with their loads, observables and constraints, HistorySetup, the same through time on a tensor product with a time space, and the operators from the components' fields to their loads. |
plotting/ |
Plotting of pyshtools.SHGrid fields on Cartopy projections, and radial profiles (viscosities, kernels) on a material's mesh. |
data/ |
Location and retrieval of the external datasets. |
Tests
poetry run pytest # the fast suite, which is the default
poetry run pytest -m slow # only the slow tests
poetry run pytest -m "" # everything
The slow tests read the real datasets, so the first run of them downloads several hundred megabytes, and include running every tutorial script.
Dependencies
pyslfp is built on numpy and scipy, with pyshtools and ducc0 for
spherical harmonic transforms and grids, pygeoinf for the Hilbert space and
inference machinery, planetmodel for the Earth models and radial meshes,
matplotlib and Cartopy for plotting, regionmask with cf-xarray for the
regional masks, and threadpoolctl for thread control.
The only optional dependency is pyqt6, under the interactive extra described
above. Nothing in the library imports it; it exists so that matplotlib has a Qt
backend to fall back on.
Citation
If you use pyslfp in published work, please cite:
-
Al-Attar, D., Syvret, F., Crawford, O., Mitrovica, J.X. and Lloyd, A.J., 2024. Reciprocity and sensitivity kernels for sea level fingerprints. Geophysical Journal International, 236(1), pp.362–378.
-
D.A. Heathcote, T.Holland, A.M. Mag, M.E. Tamisiea, S. Coulson, S. Dangendorf, A.J. Lloyd, A. Mashayek, J.X. Mitrovica, D. Al-Attar, 2026. A scalable Bayesian framework for modern sea-level inference. arXiv, 2608.22336, https://arxiv.org/abs/2608.22336.
The datasets that pyslfp downloads (the ice histories, topography, tide
gauge network, glacier inventory and regional definitions) are the work of
others and are
redistributed here only for convenience. If you use them, please cite their
original sources, which are recorded on the
Zenodo record.
License
BSD-3-Clause. See LICENSE.
Metadata
Release files for pyslfp 4.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyslfp-4.0.0.tar.gz | 234.6 kB | Without provenance | Details for pyslfp-4.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyslfp-4.0.0-py3-none-any.whl | Python 3 | none | any | Details for pyslfp-4.0.0-py3-none-any.whl |
Total release size: 492.6 kB
Release files / pyslfp-4.0.0.tar.gz
| Download URL | pyslfp-4.0.0.tar.gz |
|---|---|
| Size | 234.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08ed8305daad346c272fd7d43683d790722ea9151b1884adcf8b53b992b9733e
|
|
BLAKE2b-256 checksum How to use checksums |
755915f31196054de5c632d7f08ac0babf1a51732e296345bfaf36acadeb12e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.12.15 Linux/7.0.0-1017-azure
|
Release files / pyslfp-4.0.0-py3-none-any.whl
| Download URL | pyslfp-4.0.0-py3-none-any.whl |
|---|---|
| Size | 258.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dba1e51e61a5b7cd86244aea99dc328568ab28fdd081bef660e4d2f3ec4ead1a
|
|
BLAKE2b-256 checksum How to use checksums |
0471d9d964fde6207a6bc9ca3006933ec0db51bf439a0535742e25dbf78d8d58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.12.15 Linux/7.0.0-1017-azure
|
Security for pyslfp 4.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.