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(delta_h=1/6)Functions accept planet-specific parameters (gravity, radius, rotation rate) so the same code works across planetary atmospheres.
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.9+ and the following packages (installed automatically):
- xarray
- numpy
- scipy
- matplotlib
- windspharm
- eofs
- faceted
- statsmodels
- scikit-learn
- pymannkendall
- gitpython
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.