EarthScienceKit
Inspectable Earth-system computations for learning and teaching.
EarthScienceKit follows the MathematicsKit family structure with ten
subpackages and 323 domain models: 305 algebraic equations and 18 sampled
dynamic models. Release 0.3.0 has the first nine; geomorphology is unreleased. Every model documents its units, input bounds and applicability.
NumPy and SciPy supply mature numerical foundations.
| Subpackage | Models | Focus |
|---|
plate_tectonics | 27 | Euler rotation, finite rotations and their composition, spreading, subduction, isostasy, flexure, convection, hotspots, cooling |
seismology | 25 | Elastic, surface and head waves, rays and travel times in a layered Earth, interfaces, magnitudes, pulses, rebound |
atmosphere | 30 | Hydrostatics, dry and moist thermodynamics, condensation level, CAPE and CIN, humidity, stratification, rotation, Rossby waves, barotropic vorticity |
climate | 30 | Radiation, greenhouse layers, insolation, forcing, feedback, two-box response, diffusive energy balance, ice-albedo hysteresis, red noise, heat storage, carbon and sea level |
oceanography | 25 | Tides, trochoidal and dispersive waves, density, the 75-term TEOS-10 polynomial and cabbeling, dynamic method, Ekman spiral, gyres, two-box overturning, abyssal mixing |
geophysics | 33 | Gravity anomalies, normal gravity and flattening, satellite J2, Stokes's geoid, dipole and Gauss coefficients, Schmidt harmonics and field synthesis, paleomagnetic poles, reversal anomalies, Love numbers, GRACE water, Rikitake dynamo |
volcanology | 28 | Decay and radiometric ages, radiocarbon, Pb-Pb, concordia and isochron dating, Rayleigh and crystal fractionation, lattice strain, isotope thermometry, magma viscosity and ascent, diffusive bubble growth, Mogi inflation, plume and column heights, VEI |
hydrology | 45 | Water balance, Darcy and Dupuit flow, Theis and Cooper-Jacob wells, steady and transient Richards, Green-Ampt and Horton infiltration, Chézy and Manning channels, unit hydrographs, Muskingum and kinematic-wave routing, degree-day snowmelt, Penman-Monteith evaporation, Horton's stream laws, TOPMODEL |
glaciology | 43 | Glen's flow law, Forbes's viscous slab, Nye's plastic ice sheet and crevasses, Weertman sliding, shallow-ice and Vialov profiles, flowline glacier, mass balance, Stefan sea ice, glacial isostasy and Haskell rebound, ice-core dating, Herron-Langway firn and gas-age offset, positive-degree-day melt, Schoof grounding line |
geomorphology | 37 | Stokes and Ferguson-Church settling, the Shields threshold, Rouse suspension, Meyer-Peter and Müller bedload, hillslope creep and fault scarps, soil production, stream power, graded and transient river profiles, chi, Hack, Flint and Strahler, hydraulic geometry, effective discharge, blown sand and dunes, cosmogenic erosion rates |
Install and explore
python -m pip install earthsciencekit
# Or from a checkout:
python -m pip install -e '.[dev]'
import numpy as np
from earthsciencekit.climate import simulate_one_box
from earthsciencekit.units import convert
time = convert(np.linspace(0, 100, 201), "year", "s")
result = simulate_one_box(4, 1.2, 2e8, time)
print(result.summary())
figure, axes = result.plot()
animation = result.animate(interval=40)
SI units apply unless an argument explicitly states otherwise. Latitude and
angles use radians. Algebraic functions accept scalars and broadcast arrays;
finite real quantities and physical bounds are validated. Unit conversions are
explicit. Sampled histories copy their arrays, retain labels and support plots
and animation export.
Documentation and validation
The Sphinx site has Subpackages, History, Examples and API entry points,
MathematicsKit-style cards/hubs and cross-links. Ten history pages connect
at least fifteen dated breakthroughs each to the APIs; ten guides explain equations,
conventions and independent checks. One executed gallery script per breakthrough
provides figures and Python/notebook downloads.
MPLBACKEND=Agg python -m pytest --cov=earthsciencekit --cov-report=term-missing
python -m ruff check .
python -m ruff format --check .
cd docs && make html
python -m build
Coverage enforces 100% of production statements, including validators and
visualization; test files alone are omitted. This metric does not establish
physical applicability. Tests include independent analytic solutions,
conservation balances, limiting cases and invalid-input contracts. Exact release
results are in VERIFICATION.md; model limits are in docs/source/limitations.rst.
The documentation is hosted at https://cpoli.github.io/earthsciencekit/, and
notebooks/quickstart.ipynb runs in Colab from the badge above.
Contribute
See CONTRIBUTING.md. Educational models should have explicit equations, units,
assumptions, independent benchmarks and an executable example. The MIT license
is in LICENSE. Please cite this software using CITATION.cff.
