A Python toolkit for large-scale atmospheric and climate dynamics research.
puffins provides functions for computing physical quantities, analyzing climate data, and creating publication-ready visualizations. Built on xarray, it is designed for use in Jupyter notebooks for both interactive exploration and generating figures for papers and presentations.
Note: This is a personal research tool. You are welcome to use it, but I cannot provide support or guarantee correctness. Use at your own risk.
Physical constants for Earth, Mars, Saturn, Titan, and Venus. Numerical differentiation, integration, interpolation, and solvers. Standardized coordinate and dimension names for consistent xarray workflows.
Coriolis parameter, absolute angular momentum, vorticity, Rossby number, thermodynamic quantities, tropopause diagnostics, and vertical coordinate transformations.
Hadley cell and meridional overturning circulation diagnostics (streamfunction, cell strength and extent), gradient wind balance, equal-area coordinates, Empirical Orthogonal Functions, and column budget adjustment via spherical harmonic wind inversion.
Implementations of classic models from the literature: Held & Hou (1980), Lindzen & Hou (1988), Plumb & Hou (1992), the Kuo-Eliassen equation, and Hide's theorem.
Matplotlib helpers with custom styling, sine-latitude and standard latitude axis formatting, and integration with faceted for multi-panel plots.
import puffins
# Coriolis parameter at 30°N
f = puffins.dynamics.coriolis_param(30)
# Same calculation for Mars
f_mars = puffins.dynamics.coriolis_param(
30, rot_rate=puffins.constants.ROT_RATE_MARS
)
# Meridional mass streamfunction from v-wind and pressure thickness
psi = puffins.had_cell.merid_streamfunc(v, dp)
# Held-Hou 1980 Hadley cell edge latitude
phi_h = puffins.held_hou_1980.hc_edge_hh80(therm_ross_num=0.1)Functions accept planet-specific parameters (gravity, radius, rotation rate) so the same code works across planetary atmospheres.
Full documentation, including the API reference, is at puffins.readthedocs.io.
pip install puffinsTo work on puffins itself, clone the repository and install in editable mode:
git clone https://github.com/spencerahill/puffins.git
cd puffins
pip install -e .puffins requires Python 3.10+ and the following packages (installed automatically):
The spherical-harmonics wind inversion in budget_adj additionally
requires windspharm, which is
optional (the fortran extra) and on modern setups must be installed
via conda: conda install -c conda-forge windspharm.
puffins is developed continuously, so a development clone may be checked out to any branch at any moment. Science projects should not import from a clone that is also used for development. The intended arrangement:
- Maintain a second, consumer-only clone (e.g.
puffins-main) that stays permanently onmasterand is only ever updated viagit pull. Install it into each project's environment in editable mode (pip install -e /path/to/puffins-main, adding--no-depswhen the environment already provides puffins' dependencies, e.g. from conda). Every project then imports pushed, CI-testedmaster, and a singlepullupdates all of them at once. - If a project needs an unmerged branch, give that project its own temporary clone or git worktree pinned to that branch, install that copy into the project's environment only, and delete it once the branch merges.
- To freeze an analysis (e.g., when a paper is submitted), replace
the editable install with one pinned to a commit or tag:
pip install git+https://github.com/spencerahill/puffins@<sha-or-tag>. The setuptools-scm version string records the exact commit.
Earlier versions of puffins instead switched a single shared clone
between branches from the top of each notebook
(nb_utils.setup_puffins() and the set-proj-puff-branch script);
those utilities have been removed.
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.