{ } JustinGeoSci

Core & Utilities

The process-independent layer the physical modules build on: shared data structures, physical constants, and the exception hierarchy.

core — Core Data Structures

Shared containers not tied to one process: EnergyBalance and AtmosphericState, both accepting scalars or NumPy arrays.

EnergyBalance

EnergyBalance(net_radiation: 'float | np.ndarray', sensible_heat: 'float | np.ndarray', latent_heat: 'float | np.ndarray', ground_heat: 'float | np.ndarray' = 0.0) -> None

Container for surface energy-balance components and derived diagnostics.

>>> from atmoflux.core import EnergyBalance
>>> eb = EnergyBalance(net_radiation=400.0, sensible_heat=150.0,
...                    latent_heat=200.0, ground_heat=50.0)
>>> eb.residual
0.0
>>> round(eb.bowen_ratio, 2)
0.75
>>> eb
EnergyBalance(Rn=400.0, H=150.0, LE=200.0, G=50.0, residual=0.0)

AtmosphericState

AtmosphericState(temperature: 'float | np.ndarray', pressure: 'float | np.ndarray', wind_speed: 'float | np.ndarray', relative_humidity: 'float | np.ndarray | None' = None) -> None

Container bundling the primary atmospheric state variables.

>>> from atmoflux.core import AtmosphericState
>>> state = AtmosphericState(temperature=20.0, pressure=101.325,
...                          wind_speed=3.0, relative_humidity=55.0)
>>> state.temperature
20.0
>>> state
AtmosphericState(T=20.0°C, P=101.3kPa, U=3.0m/s, RH=55.0%)

constants — Constants

The single source of truth for physical and derived constants used across atmoflux. All pressures are in kPa.

Constant Value Meaning
CP_AIR 1005.0 Units: J/(kg·K) (Standard in atmospheric science and meteorology calculations)
LV 2450000.0 Units: J/kg
PC 0.066 Units: kPa/K
R_AIR 287.05287 Units: J/(kg·K)
R_VAPOR 461.52332 Units: J/(kg·K)
RMW 0.622 Units: Dimensionless factor used in humidity calculations
SVP_A 0.61078 Units: A = kPa, B= dimensionless, C = degrees Celsius
SVP_B 17.27
SVP_C 237.3
STEFAN_BOLTZMANN 5.670374419e-08 Units: W/(m²·K⁴)
SOLAR_CONSTANT 1361.6 Units: W/m²
KARMAN 0.4 Units: dimensionless
G 9.80665 Units: m/s²
P0 101.325 Units: kPa
RHO_WATER 1000.0 Units: kg/m³
RHO_AIR_STD 1.225 Units: kg/m³
MU_AIR 1.789e-05 Units: Pa·s
MFP_AIR 6.63e-08 Units: m
SOLAR_DECLINATION_MAX 23.45 Units: degrees
ANGSTROM_A 0.25 Units: dimensionless
ANGSTROM_B 0.5
PRIESTLEY_TAYLOR_ALPHA 1.26 Units: dimensionless
DRY_ADIABATIC_LAPSE_RATE 0.009757860696517412 Units: K/m
T0_STANDARD 288.15 Units: K
LAPSE_RATE_STANDARD 0.0065 Units: K/m

exceptions — Exceptions

The exception hierarchy. Every error derives from a single base class, so one except clause catches any package-specific failure.

AtmofluxError

AtmofluxError(...)

Base exception for errors raised by atmoflux.

>>> from atmoflux.exceptions import AtmofluxError, InvalidUnitError
>>> try:
...     raise InvalidUnitError("bad unit")
... except AtmofluxError as exc:
...     print(type(exc).__name__)
InvalidUnitError

InvalidUnitError

InvalidUnitError(...)

Raised when an unrecognized or unsupported unit string is supplied.

>>> from atmoflux.exceptions import InvalidUnitError
>>> raise InvalidUnitError("Temp unit must be one of {'C', 'F', 'K'}")
Traceback (most recent call last):
    ...
atmoflux.exceptions.InvalidUnitError: Temp unit must be one of {'C', 'F', 'K'}

OutOfRangeError

OutOfRangeError(...)

Raised when a value falls outside its physically valid range.

ValidationError

ValidationError(...)

Raised when an input fails type or value validation.