earthsciencekit.atmosphere

Domain hub · History · Examples · API reference

Inspectable atmosphere models; SI units unless stated otherwise.

earthsciencekit.atmosphere.barometer_column_height(pressure, liquid_density, gravity)

Liquid barometer column height.

The weight of a liquid column balances the pressure of the air above it.

Parameters:

• pressure (float or array_like) – Pa; constraint: nonnegative.

• liquid_density (float or array_like) – kg/m^3; constraint: positive.

• gravity (float or array_like) – m/s^2; constraint: positive.

Returns:

Model value [m]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Incompressible liquid with a vacuum above the column; vapour pressure and capillarity are neglected. Equation: pressure / (liquid_density * gravity). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.barometric_pressure(surface_pressure, height, temperature, gravity)

Isothermal barometric profile.

Vertical pressure structure follows from hydrostatic balance and the gas law.

Parameters:

• surface_pressure (float or array_like) – Pa; constraint: positive.

• height (float or array_like) – m; constraint: real.

• temperature (float or array_like) – K; constraint: positive.

• gravity (float or array_like) – m/s^2; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Isothermal column; signed height is relative to the reference level. Equation: surface_pressure * np.exp(-gravity * height / (R_DRY_AIR * temperature)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.brunt_vaisala_squared(potential_temperature, vertical_gradient, gravity)

Dry static stability.

A potential-temperature gradient determines dry stratification stability.

Parameters:

• potential_temperature (float or array_like) – K; constraint: positive.

• vertical_gradient (float or array_like) – K/m; constraint: real.

• gravity (float or array_like) – m/s^2; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Returns signed N squared; negative values represent instability rather than an imaginary frequency. Equation: gravity * vertical_gradient / potential_temperature. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.coriolis_parameter(latitude)

Rotating-Earth Coriolis parameter.

Latitude controls rotational deflection and geophysical balance.

Parameters:

latitude (float or array_like) – rad; constraint: latitude.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Spherical rotating-Earth approximation; input is radians. Equation: 2 * OMEGA_EARTH * np.sin(latitude). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.dry_adiabatic_lapse_rate(gravity, heat_capacity)

Dry adiabatic lapse rate.

Rising dry parcels cool as they perform expansion work.

Parameters:

• gravity (float or array_like) – m/s^2; constraint: positive.

• heat_capacity (float or array_like) – J/(kg K); constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Returned positive lapse magnitude in K per metre; temperature decreases upward. Equation: gravity / heat_capacity. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.dry_air_density(pressure, temperature)

Ideal-gas atmospheric density.

An equation of state connects atmospheric pressure, temperature and density.

Parameters:

• pressure (float or array_like) – Pa; constraint: positive.

• temperature (float or array_like) – K; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Dry ideal air with fixed specific gas constant. Equation: pressure / (R_DRY_AIR * temperature). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.geostrophic_speed(pressure_gradient, density, coriolis)

Pressure-gradient geostrophic component.

Pressure gradients and rotation can balance in large-scale flow.

Parameters:

• pressure_gradient (float or array_like) – Pa/m; constraint: real.

• density (float or array_like) – kg/m^3; constraint: positive.

• coriolis (float or array_like) – 1/s; constraint: nonzero.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Signed cross-gradient component; invalid at the equator where coriolis vanishes. Equation: pressure_gradient / (density * coriolis). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.mixing_ratio(vapor_pressure, total_pressure)

Water-vapor mass mixing ratio.

Partial pressure determines water mass per unit dry-air mass.

Parameters:

• vapor_pressure (float or array_like) – Pa; constraint: nonnegative.

• total_pressure (float or array_like) – Pa; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Ideal vapor mixture; vapor pressure must be below total pressure. Equation: EPSILON_WATER * vapor_pressure / (total_pressure - vapor_pressure). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.potential_temperature(temperature, pressure, reference_pressure)

Poisson potential temperature.

Adiabatic temperature adjustment permits comparisons across pressure levels.

Parameters:

• temperature (float or array_like) – K; constraint: positive.

• pressure (float or array_like) – Pa; constraint: positive.

• reference_pressure (float or array_like) – Pa; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Dry ideal gas with constant heat capacity; not equivalent potential temperature. Equation: temperature * (reference_pressure / pressure)**(R_DRY_AIR / CP_DRY_AIR). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.relative_humidity(vapor_pressure, saturation_pressure)

Relative humidity fraction.

Humidity compares actual vapor pressure to a saturation reference.

Parameters:

• vapor_pressure (float or array_like) – Pa; constraint: nonnegative.

• saturation_pressure (float or array_like) – Pa; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Returned fraction may exceed one during supersaturation; no clipping. Equation: vapor_pressure / saturation_pressure. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.richardson_number(brunt_vaisala_squared, shear)

Gradient Richardson number.

Stratification suppresses the turbulence that vertical wind shear generates.

Parameters:

• brunt_vaisala_squared (float or array_like) – 1/s^2; constraint: real.

• shear (float or array_like) – 1/s; constraint: nonzero.

Returns:

Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Signed; stratified shear flow can become unstable only where it falls below 1/4 (Miles-Howard). Equation: brunt_vaisala_squared / shear**2. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.rossby_number(speed, length, coriolis)

Rossby dynamical scaling.

Rossby number measures inertia relative to rotational effects.

Parameters:

• speed (float or array_like) – m/s; constraint: nonnegative.

• length (float or array_like) – m; constraint: positive.

• coriolis (float or array_like) – 1/s; constraint: nonzero.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Magnitude scaling only; small values support but do not prove geostrophic balance. Equation: speed / (np.abs(coriolis) * length). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.rossby_wave_speed(zonal_wind, beta, wavenumber)

Barotropic Rossby-wave zonal phase speed.

The latitude gradient of the Coriolis parameter makes vorticity waves drift westward.

Parameters:

• zonal_wind (float or array_like) – m/s; constraint: real. Uniform background eastward wind.

• beta (float or array_like) – 1/(m s); constraint: nonnegative. Northward gradient of the Coriolis parameter.

• wavenumber (float or array_like) – rad/m; constraint: positive. Total horizontal wavenumber.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Nondivergent barotropic flow on a beta plane; positive values are eastward. Equation: zonal_wind - beta / wavenumber**2. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.saturation_vapor_pressure(temperature)

Integrated Clausius-Clapeyron approximation.

Phase equilibrium makes saturation vapor pressure strongly temperature dependent.

Parameters:

temperature (float or array_like) – K; constraint: temperature.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Liquid-water reference with constant latent heat; restricted to 180-330 K, not an ice saturation formula. Equation: 611.2 * np.exp((2.5e6 / R_VAPOR) * (1 / 273.15 - 1 / temperature)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.scale_height(temperature, gravity)

Isothermal scale height.

Hydrostatic balance predicts an exponential pressure scale.

Parameters:

• temperature (float or array_like) – K; constraint: positive.

• gravity (float or array_like) – m/s^2; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Dry isothermal atmosphere with constant gravity. Equation: R_DRY_AIR * temperature / gravity. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.simulate_barotropic_vorticity(initial_vorticity, time, beta, spacing)

Integrate the barotropic vorticity equation on a periodic beta plane.

Parameters:

• initial_vorticity (array_like, shape (ny, nx), ny, nx >= 4) – Relative vorticity [1/s] on an equally spaced doubly periodic grid, rows northward and columns eastward.

• time (array_like) – Strictly increasing nonnegative output times [s]. Initial state belongs to the first supplied time; values need not start at zero.

• beta (float) – Nonnegative scalar northward gradient of the Coriolis parameter [1/(m s)].

• spacing (float) – Positive scalar grid spacing [m], the same in both directions.

Returns:

Relative vorticity at each grid point [1/s], flattened row by row. Columns are labeled cell_<row>_<column>.

Return type:

TimeSeries

Notes

Solves d(zeta)/dt + J(psi, zeta) + beta * d(psi)/dx = 0 with laplacian(psi) = zeta. Derivatives are pseudo-spectral (FFT) with the two-thirds dealiasing rule, and integrators.integrate_ode steps in time. The domain mean of vorticity is removed and conserved; energy and enstrophy are conserved up to the time-stepping error. A single Fourier mode is an exact Rossby wave. There is no forcing, friction, divergence or sphere.

earthsciencekit.atmosphere.simulate_dry_ascent(initial_temperature, initial_pressure, vertical_speed, time)

Follow an ideal dry parcel along a hydrostatic constant-speed ascent.

Parameters:

• initial_temperature (float) – Positive scalar initial temperature [K].

• initial_pressure (float) – Positive scalar initial pressure [Pa].

• vertical_speed (float) – Finite scalar vertical velocity [m/s], positive upward.

• time (array_like) – Nonnegative strictly increasing sampled times [s].

Returns:

Parcel temperature [K] and pressure [Pa].

Return type:

TimeSeries

Notes

Dry lapse and hydrostatic pressure equations use constant standard gravity and dry-air heat capacity. Potential temperature should remain constant. The parcel is unsaturated; condensation and environmental entrainment are excluded. Reject trajectories whose predicted temperature reaches zero.

earthsciencekit.atmosphere.specific_humidity(mixing_ratio)

Specific humidity from mixing ratio.

Changing the denominator connects two moisture conventions.

Parameters:

mixing_ratio (float or array_like) – kg/kg dry air; constraint: nonnegative.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Output is water mass per total moist-air mass. Equation: mixing_ratio / (1 + mixing_ratio). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.surface_pressure_tendency(mean_divergence, surface_pressure)

Surface pressure tendency from column divergence.

Mass leaving the column through net horizontal divergence lowers the surface pressure.

Parameters:

• mean_divergence (float or array_like) – 1/s; constraint: real. Pressure-weighted column mean of the horizontal divergence.

• surface_pressure (float or array_like) – Pa; constraint: positive.

Returns:

Model value [Pa/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Hydrostatic column with no surface mass flux; divergence at one level is far larger than the column mean. Equation: -surface_pressure * mean_divergence. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.temperature_from_potential(potential_temperature, pressure, reference_pressure)

Inverse potential temperature.

Potential-temperature inversion recovers the local dry-air temperature.

Parameters:

• potential_temperature (float or array_like) – K; constraint: positive.

• pressure (float or array_like) – Pa; constraint: positive.

• reference_pressure (float or array_like) – Pa; constraint: positive.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Uses the same dry-air heat capacity and reference pressure convention. Equation: potential_temperature * (pressure / reference_pressure)**(R_DRY_AIR / CP_DRY_AIR). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.two_layer_temperature(height, surface_temperature, lapse_rate, tropopause_height)

Troposphere-stratosphere temperature profile.

Temperature falls with height up to the tropopause and stays constant above it.

Parameters:

• height (float or array_like) – m; constraint: nonnegative.

• surface_temperature (float or array_like) – K; constraint: positive.

• lapse_rate (float or array_like) – K/m; constraint: nonnegative.

• tropopause_height (float or array_like) – m; constraint: positive.

Returns:

Model value [K]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Constant-lapse troposphere under an isothermal lower stratosphere; the stratospheric warming above about 20 km is omitted. Equation: surface_temperature - lapse_rate * np.minimum(height, tropopause_height). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.atmosphere.virtual_temperature(temperature, specific_humidity)

Virtual-temperature buoyancy correction.

Moist air is less dense than dry air at the same pressure and temperature.

Parameters:

• temperature (float or array_like) – K; constraint: positive.

• specific_humidity (float or array_like) – kg/kg moist air; constraint: fraction.

Returns:

Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Ideal vapor mixture without suspended liquid or ice. Equation: temperature * (1 + (1 / EPSILON_WATER - 1) * specific_humidity). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.