Overview#

Atmoflux groups physically related calculations into focused modules, organized into four areas: the atmospheric state, the radiation that drives surface exchange, the surface fluxes and energy balance, and the shared core utilities. Use the left sidebar to move between groups and modules, and the right panel to jump within a page.

Every public function validates its inputs and raises a descriptive subclass of AtmofluxError, so a single except AtmofluxError clause catches any package-specific failure. Functions accept NumPy arrays as well as scalars, broadcasting elementwise.

Conventions & units#

A few conventions hold throughout the package:

• Pressure and vapor pressure are always in kilopascals (kPa).
• Temperature functions take a unit of "C", "F", or "K"; internal physics runs in kelvin and results return in the requested unit.
• Energy-balance sign convention: net radiation is positive downward (into the surface); turbulent and storage fluxes are positive away from it, so a perfectly closed budget has a residual of zero.
• Examples use the >>> REPL prompt; unprompted lines are output.

Citation#

If you use atmoflux in academic work, please cite the software using the DOI provided below. Each release is archived via Zenodo and assigned a permanent DOI to ensure reproducibility.

https://doi.org/10.5281/zenodo.20470203

The recommended citation format is available in CITATION.cff and via the “Cite this repository” button on GitHub.

Installation#

Requirements

• Python ≥ 3.9 (developed and tested in 3.12)
• NumPy ≥ 1.26 is the only runtime dependency

Keeping the dependency footprint minimal is a deliberate design goal; NumPy is the sole external requirement.

From PyPI

pip install atmoflux

From source

Clone the repository and install from the project root. Use an editable install if you intend to modify the code:

git clone https://github.com/Telluris-Labs/atmoflux.git
cd atmoflux

pip install .       # regular installation
pip install -e .    # editable (development) installation

Quick start#

Compute net all-wave radiation at a surface, then bundle the surface fluxes into an EnergyBalance container that derives the closure residual and Bowen ratio.

>>> from atmoflux.radiative import net_radiation
>>> from atmoflux.balance import energy_balance
>>> rn = net_radiation(sw_down=800.0, lw_down=350.0, albedo=0.2, temp_surface=288.0)
>>> round(rn, 2)
599.89
>>> eb = energy_balance(rn, sensible_heat=150.0, latent_heat=200.0, ground_heat=50.0)
>>> round(eb.residual, 2)
199.89
>>> round(eb.bowen_ratio, 2)
0.75

From here, head into a group on the left — for example Evaporation & hydrology — for the full function set, equation provenance, and examples.