Skip to main content

PySLFP: Python Sea Level Fingerprints

PyPI version Release Documentation License: BSD-3-Clause

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

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.

Tutorial Contents Colab
01_first_fingerprint Everything at its default: the fingerprint of a West Antarctic melt. Open In Colab
02_physics The scales, the Earth model, a state from an analytic ice model, a load of one's own, the linear and non-linear solutions. Open In Colab
03_love_numbers The shipped table, computing Love numbers from PREM, the identities, the radial solutions, files, and the complex numbers of a viscoelastic body. Open In Colab
04_operators The fingerprint as an operator, composition, adjoints and sensitivity kernels, polar wander and length of day, Sobolev spaces and tide gauges. Open In Colab
05_inversion A Bayesian inversion of synthetic GLOSS tide gauge data for ice thickness change. Open In Colab
06_forward_gia A first forward GIA run: a melting ice cap on a viscoelastic PREM, and postglacial rebound. Open In Colab
07_ice7g_deglaciation ICE-7G from 26 ka to the present: uplift rates, the sea level curve and a Hudson Bay emergence record. Open In Colab
08_gia_kernels Ice-history sensitivity kernels by the discrete and continuous adjoints. Open In Colab
09_decay_time_viscosity The decay time of postglacial emergence and its viscosity kernel. Open In Colab
10_initial_sea_level Calibrating the initial sea level of a thickness-only history against the present day, by the classical update and the adjoint gradient. Open In Colab

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.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyslfp 4.1.0
File Size Uploaded Provenance Actions
pyslfp-4.1.0.tar.gz 239.2 kB Without provenance Details for pyslfp-4.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyslfp 4.1.0
File Interpreter ABI Platform Actions
pyslfp-4.1.0-py3-none-any.whl Python 3 none any Details for pyslfp-4.1.0-py3-none-any.whl

Total release size: 501.7 kB

Release files / pyslfp-4.1.0.tar.gz

Download URL pyslfp-4.1.0.tar.gz
Size 239.2 kB
Tags Source
SHA-256 checksum
How to use checksums
90729a9d1d97ca8b4afac2f92a436333b5275b713e2d95b492e372c27fcaa129
BLAKE2b-256 checksum
How to use checksums
5bea293d8b57c7eee6d87d10ab2a4ad2de19919b47c19e46db1d3b006053c6b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.12.16 Linux/7.0.0-1019-azure

Release files / pyslfp-4.1.0-py3-none-any.whl

Download URL pyslfp-4.1.0-py3-none-any.whl
Size 262.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f31bb1724c1d83b3a5f71cde0b6ec2977e149190e804809fcf008536981d79f0
BLAKE2b-256 checksum
How to use checksums
ebbb08fcd7d5925436402355ca88ee2b033ed932445f293117517c331990e2a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.12.16 Linux/7.0.0-1019-azure

Security for pyslfp 4.1.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.

Release history Release notifications | RSS feed

This release

4.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page