EarthScienceKit

Inspectable Earth-system computations for learning and teaching.

EarthScienceKit 0.2.0 follows the MathematicsKit family structure with seven subpackages and 171 domain models: 162 algebraic equations and nine sampled dynamic models. Every model documents its units, input bounds and applicability. NumPy and SciPy supply mature numerical foundations.

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. Seven history pages connect at least fifteen dated breakthroughs each to the APIs; seven 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 .
MPLBACKEND=Agg python -m sphinx -E -W --keep-going -b html docs/source docs/_build/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.