atmoflux

A Python package for atmospheric and surface flux calculation and analysis.

Overview

atmoflux is a Python library for atmospheric and surface flux calculations relevant to climate, micrometeorology, and urban environmental research. The package provides modular tools for radiative, turbulent, hydrological, aerosol, and energy balance calculations, alongside supporting utilities for atmospheric state variables and physical constants.

The atmoflux library emphasizes physically explicit formulations and transparent diagnostics, supporting process-based analysis and integration with statistical or machine learning models. All functions accept scalars or NumPy arrays, so calculations vectorize naturally over gridded or time-series data.

atmoflux is being developed alongside dissertation research focused on urban microclimates, heat stress, and land–atmosphere interactions, and is intended to evolve as a flexible research framework rather than a fixed operational model.

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.

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

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

Requirements

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

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

Installation

From PyPI (recommended)

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

import atmoflux as af

# Net all-wave radiation at a surface (W/m²)
rn = af.radiative.net_radiation(
    sw_down=800, lw_down=350, albedo=0.2, temp_surface=295
)

# Turbulent sensible heat flux via the bulk-aerodynamic method
rho = af.turbulent.air_density(temp=22, pressure=101.325)
h = af.turbulent.sensible_heat_flux(
    rho, wind_speed=3.0, temp_air=22, temp_surface=25, transfer_coeff=0.0013
)

# Assemble a surface energy balance with derived diagnostics
eb = af.balance.energy_balance(
    rn, sensible_heat=h, latent_heat=250, ground_heat=60
)
print(eb.residual)       # closure residual (W/m²)
print(eb.bowen_ratio)    # H / LE

Modules

Atmospheric state

Radiation

Surface fluxes

Core & utilities

Testing

The package ships with a pytest suite mirroring the module structure, plus doctests in every public function.

# Unit tests
pytest atmoflux/tests/

# Docstring examples
pytest --doctest-modules atmoflux/

License

Released under the MIT License. See the LICENSE file for details.