earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/__init__.py

@@ -0,0 +1,6 @@
+"""Educational Earth-system computations with explicit units and model limits."""
+
+from . import atmosphere, climate, geophysics, oceanography, plate_tectonics, seismology, volcanology
+
+__version__ = "0.2.0"
+__all__ = ["plate_tectonics", "seismology", "atmosphere", "climate", "oceanography", "volcanology", "geophysics"]

earthsciencekit/_validation.py

@@ -0,0 +1,62 @@
+"""Central contracts for real, finite, nonempty numerical quantities."""
+
+from functools import wraps
+
+import numpy as np
+
+
+def quantity(name, value, *, lower=None, upper=None, strict_lower=False, strict_upper=False):
+    """Return a floating NumPy quantity after validating physical bounds."""
+    array = np.asarray(value)
+    if array.dtype.kind not in "iuf" or not array.size or not np.all(np.isfinite(array)):
+        raise ValueError(f"{name} must contain finite real numbers, excluding booleans")
+    array = array.astype(float)
+    if lower is not None:
+        require(array > lower if strict_lower else array >= lower, f"{name} violates its lower bound")
+    if upper is not None:
+        require(array < upper if strict_upper else array <= upper, f"{name} violates its upper bound")
+    return array
+
+
+def require(condition, message):
+    """Reject any violated relation, including array-valued physical constraints."""
+    if not np.all(condition):
+        raise ValueError(message)
+
+
+def model(function):
+    """Preserve signatures and turn arithmetic singularities into ValueError."""
+
+    @wraps(function)
+    def wrapped(*args, **kwargs):
+        try:
+            with np.errstate(over="raise", divide="raise", invalid="raise"):
+                result = function(*args, **kwargs)
+        except FloatingPointError as error:
+            raise ValueError(f"{function.__name__}: singular or overflowing arithmetic") from error
+        require(np.all(np.isfinite(result)), f"{function.__name__}: nonfinite result")
+        return result
+
+    return wrapped
+
+
+def time_grid(value):
+    """Validate a nonnegative strictly increasing vector of sampled seconds."""
+    time = quantity("time", value, lower=0)
+    require(time.ndim == 1 and time.size >= 2, "time must be a vector with at least two samples")
+    require(np.all(np.diff(time) > 0), "time must strictly increase")
+    return time
+
+
+def safe_arithmetic(function):
+    """Translate floating arithmetic failures in structured numerical models."""
+
+    @wraps(function)
+    def wrapped(*args, **kwargs):
+        try:
+            with np.errstate(over="raise", divide="raise", invalid="raise"):
+                return function(*args, **kwargs)
+        except FloatingPointError as error:
+            raise ValueError(f"{function.__name__}: singular or overflowing arithmetic") from error
+
+    return wrapped

earthsciencekit/atmosphere/__init__.py

@@ -0,0 +1,57 @@
+"""Inspectable atmosphere models; SI units unless stated otherwise."""
+
+from earthsciencekit.atmosphere.systems.dynamics import (
+    coriolis_parameter,
+    geostrophic_speed,
+    rossby_number,
+    rossby_wave_speed,
+    simulate_barotropic_vorticity,
+)
+from earthsciencekit.atmosphere.systems.hydrostatics import (
+    barometer_column_height,
+    barometric_pressure,
+    dry_air_density,
+    scale_height,
+    surface_pressure_tendency,
+    two_layer_temperature,
+)
+from earthsciencekit.atmosphere.systems.moisture import (
+    mixing_ratio,
+    relative_humidity,
+    saturation_vapor_pressure,
+    specific_humidity,
+    virtual_temperature,
+)
+from earthsciencekit.atmosphere.systems.thermodynamics import (
+    brunt_vaisala_squared,
+    dry_adiabatic_lapse_rate,
+    potential_temperature,
+    richardson_number,
+    simulate_dry_ascent,
+    temperature_from_potential,
+)
+
+__all__ = [
+    "dry_air_density",
+    "scale_height",
+    "barometric_pressure",
+    "potential_temperature",
+    "temperature_from_potential",
+    "dry_adiabatic_lapse_rate",
+    "saturation_vapor_pressure",
+    "mixing_ratio",
+    "specific_humidity",
+    "virtual_temperature",
+    "relative_humidity",
+    "coriolis_parameter",
+    "brunt_vaisala_squared",
+    "geostrophic_speed",
+    "rossby_number",
+    "barometer_column_height",
+    "two_layer_temperature",
+    "richardson_number",
+    "surface_pressure_tendency",
+    "rossby_wave_speed",
+    "simulate_dry_ascent",
+    "simulate_barotropic_vorticity",
+]

earthsciencekit/atmosphere/core/__init__.py

@@ -0,0 +1,5 @@
+"""Result containers for earthsciencekit.atmosphere."""
+
+from earthsciencekit.atmosphere.core.base import TimeSeries
+
+__all__ = ["TimeSeries"]

earthsciencekit/atmosphere/core/base.py

@@ -0,0 +1,10 @@
+"""Result containers for earthsciencekit.atmosphere.
+
+Algebraic models return NumPy scalars or arrays. The sampled dynamic models
+return the package-wide immutable :class:`~earthsciencekit.results.TimeSeries`,
+which is re-exported here as this domain's result type.
+"""
+
+from earthsciencekit.results import TimeSeries
+
+__all__ = ["TimeSeries"]

earthsciencekit/atmosphere/systems/__init__.py

@@ -0,0 +1 @@
+"""Models of earthsciencekit.atmosphere, grouped by topic."""

earthsciencekit/atmosphere/systems/dynamics.py

@@ -0,0 +1,208 @@
+"""Rotating dynamics: the Coriolis parameter, geostrophy, the Rossby number, Rossby waves and barotropic vorticity.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require, safe_arithmetic
+from earthsciencekit.constants import OMEGA_EARTH
+
+__all__ = [
+    "coriolis_parameter",
+    "geostrophic_speed",
+    "rossby_number",
+    "rossby_wave_speed",
+    "simulate_barotropic_vorticity",
+]
+
+
+@model
+def coriolis_parameter(latitude):
+    """Rotating-Earth Coriolis parameter.
+
+    Latitude controls rotational deflection and geophysical balance.
+
+    Parameters
+    ----------
+    latitude : float or array_like
+        rad; constraint: latitude.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    latitude = quantity("latitude", latitude, lower=-np.pi / 2, upper=np.pi / 2)
+    return 2 * OMEGA_EARTH * np.sin(latitude)
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    pressure_gradient = quantity("pressure_gradient", pressure_gradient)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    coriolis = quantity("coriolis", coriolis)
+    require(coriolis != 0, "coriolis must be nonzero")
+    return pressure_gradient / (density * coriolis)
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    speed = quantity("speed", speed, lower=0)
+    length = quantity("length", length, lower=0, strict_lower=True)
+    coriolis = quantity("coriolis", coriolis)
+    require(coriolis != 0, "coriolis must be nonzero")
+    return speed / (np.abs(coriolis) * length)
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    zonal_wind = quantity("zonal_wind", zonal_wind)
+    beta = quantity("beta", beta, lower=0)
+    wavenumber = quantity("wavenumber", wavenumber, lower=0, strict_lower=True)
+    return zonal_wind - beta / wavenumber**2
+
+
+@safe_arithmetic
+def 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
+    -------
+    TimeSeries
+        Relative vorticity at each grid point [1/s], flattened row by row.
+        Columns are labeled cell_<row>_<column>.
+
+    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.
+    """
+    from earthsciencekit._validation import time_grid
+    from earthsciencekit.integrators import integrate_ode
+
+    zeta = quantity("initial_vorticity", initial_vorticity)
+    require(zeta.ndim == 2 and min(zeta.shape) >= 4, "initial_vorticity must be a grid of at least 4 x 4 cells")
+    time = time_grid(time)
+    beta = quantity("beta", beta, lower=0)
+    spacing = quantity("spacing", spacing, lower=0, strict_lower=True)
+    require(beta.ndim == spacing.ndim == 0, "beta and spacing must be scalars")
+    shape = zeta.shape
+    ky = 2 * np.pi * np.fft.fftfreq(shape[0], spacing)[:, None]
+    kx = 2 * np.pi * np.fft.rfftfreq(shape[1], spacing)[None, :]
+    k2 = kx**2 + ky**2
+    inverse = np.divide(-1, k2, out=np.zeros_like(k2), where=k2 > 0)
+    keep = (np.abs(ky) < 2 / 3 * np.abs(ky).max()) & (np.abs(kx) < 2 / 3 * kx.max())
+
+    def rhs(t, state):
+        spectrum = np.fft.rfft2(state.reshape(shape)) * keep
+        psi = spectrum * inverse
+        u = np.fft.irfft2(-1j * ky * psi, s=shape)
+        v = np.fft.irfft2(1j * kx * psi, s=shape)
+        zeta_x = np.fft.irfft2(1j * kx * spectrum, s=shape)
+        zeta_y = np.fft.irfft2(1j * ky * spectrum, s=shape)
+        advection = np.fft.rfft2(u * zeta_x + v * zeta_y) * keep
+        return np.fft.irfft2(-advection - beta * 1j * kx * psi, s=shape).ravel()
+
+    initial = np.fft.irfft2(np.fft.rfft2(zeta) * keep * (k2 > 0), s=shape).ravel()
+    names = tuple(f"cell_{i}_{j}" for i in range(shape[0]) for j in range(shape[1]))
+    return integrate_ode(rhs, initial, time, names=names, units=("1/s",) * initial.size)

earthsciencekit/atmosphere/systems/hydrostatics.py

@@ -0,0 +1,214 @@
+"""Hydrostatics: air density, scale height, barometric pressure, the barometer, a layered profile and pressure tendency.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+from earthsciencekit.constants import R_DRY_AIR
+
+__all__ = [
+    "dry_air_density",
+    "scale_height",
+    "barometric_pressure",
+    "barometer_column_height",
+    "two_layer_temperature",
+    "surface_pressure_tendency",
+]
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    pressure = quantity("pressure", pressure, lower=0, strict_lower=True)
+    temperature = quantity("temperature", temperature, lower=0, strict_lower=True)
+    return pressure / (R_DRY_AIR * temperature)
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    temperature = quantity("temperature", temperature, lower=0, strict_lower=True)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return R_DRY_AIR * temperature / gravity
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    surface_pressure = quantity("surface_pressure", surface_pressure, lower=0, strict_lower=True)
+    height = quantity("height", height)
+    temperature = quantity("temperature", temperature, lower=0, strict_lower=True)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return surface_pressure * np.exp(-gravity * height / (R_DRY_AIR * temperature))
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [m]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    pressure = quantity("pressure", pressure, lower=0)
+    liquid_density = quantity("liquid_density", liquid_density, lower=0, strict_lower=True)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return pressure / (liquid_density * gravity)
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [K]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    height = quantity("height", height, lower=0)
+    surface_temperature = quantity("surface_temperature", surface_temperature, lower=0, strict_lower=True)
+    lapse_rate = quantity("lapse_rate", lapse_rate, lower=0)
+    tropopause_height = quantity("tropopause_height", tropopause_height, lower=0, strict_lower=True)
+    require(surface_temperature > lapse_rate * tropopause_height, "tropopause temperature must be positive")
+    return surface_temperature - lapse_rate * np.minimum(height, tropopause_height)
+
+
+@model
+def 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
+    -------
+    numpy scalar or ndarray
+        Model value [Pa/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    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.
+    """
+    mean_divergence = quantity("mean_divergence", mean_divergence)
+    surface_pressure = quantity("surface_pressure", surface_pressure, lower=0, strict_lower=True)
+    return -surface_pressure * mean_divergence