earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/oceanography/systems/circulation.py

@@ -0,0 +1,388 @@
+"""Circulation: geostrophy, Ekman and Sverdrup transport, the Stommel gyre, the Rossby radius and thermohaline boxes.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require, safe_arithmetic
+
+__all__ = [
+    "geostrophic_current",
+    "ekman_transport",
+    "rossby_radius",
+    "volume_transport",
+    "ekman_spiral_velocity",
+    "sverdrup_transport",
+    "stommel_streamfunction",
+    "thermohaline_forcing",
+    "simulate_thermohaline_boxes",
+]
+
+
+@model
+def geostrophic_current(surface_slope, coriolis, gravity):
+    """Sea-surface geostrophic component.
+
+    Sea-surface tilt can reveal large-scale currents.
+
+    Parameters
+    ----------
+    surface_slope : float or array_like
+        1; constraint: real.
+    coriolis : float or array_like
+        1/s; constraint: nonzero.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Signed cross-slope component away from the equator; no ageostrophic velocity.
+    Equation: ``gravity * surface_slope / coriolis``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    surface_slope = quantity("surface_slope", surface_slope)
+    coriolis = quantity("coriolis", coriolis)
+    require(coriolis != 0, "coriolis must be nonzero")
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return gravity * surface_slope / coriolis
+
+
+@model
+def ekman_transport(wind_stress, density, coriolis):
+    """Cross-wind Ekman transport magnitude.
+
+    Wind stress and rotation drive vertically integrated transport.
+
+    Parameters
+    ----------
+    wind_stress : float or array_like
+        Pa; 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 [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Signed cross-wind component per unit width; direction requires a consistent vector convention.
+    Equation: ``wind_stress / (density * coriolis)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    wind_stress = quantity("wind_stress", wind_stress)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    coriolis = quantity("coriolis", coriolis)
+    require(coriolis != 0, "coriolis must be nonzero")
+    return wind_stress / (density * coriolis)
+
+
+@model
+def ekman_spiral_velocity(depth, wind_stress, density, eddy_viscosity, coriolis):
+    """Velocity profile of the Ekman spiral.
+
+    Wind stress diffused downward by friction turns and decays with depth under rotation.
+
+    Parameters
+    ----------
+    depth : float or array_like
+        m; constraint: nonnegative.
+    wind_stress : float or array_like
+        Pa; constraint: real. Signed stress along the wind axis.
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    eddy_viscosity : float or array_like
+        m^2/s; constraint: positive. Constant vertical eddy viscosity.
+    coriolis : float or array_like
+        1/s; constraint: nonzero.
+
+    Returns
+    -------
+    ndarray, shape (..., 2)
+        Model value [m/s]: the downwind component and the crosswind component, positive to the right of the wind.
+
+    Notes
+    -----
+    Steady, infinitely deep ocean with constant eddy viscosity and no pressure gradient. The surface current is 45 degrees
+    to the right of the wind in the northern hemisphere (left in the southern). The crosswind component integrated over
+    depth equals :func:`ekman_transport`; the downwind component integrates to zero.
+    Equation: ``v0 * np.exp(-s) * [np.sin(np.pi / 4 - s), np.sign(coriolis) * np.cos(np.pi / 4 - s)]``
+    with ``s = depth / d``, ``d = np.sqrt(2 * eddy_viscosity / abs(coriolis))`` and
+    ``v0 = wind_stress / (density * np.sqrt(eddy_viscosity * abs(coriolis)))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    depth = quantity("depth", depth, lower=0)
+    wind_stress = quantity("wind_stress", wind_stress)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    eddy_viscosity = quantity("eddy_viscosity", eddy_viscosity, lower=0, strict_lower=True)
+    coriolis = quantity("coriolis", coriolis)
+    require(coriolis != 0, "coriolis must be nonzero")
+    scaled = depth / np.sqrt(2 * eddy_viscosity / np.abs(coriolis))
+    surface = wind_stress / (density * np.sqrt(eddy_viscosity * np.abs(coriolis)))
+    decay = surface * np.exp(-scaled)
+    return np.stack([decay * np.sin(np.pi / 4 - scaled), np.sign(coriolis) * decay * np.cos(np.pi / 4 - scaled)], axis=-1)
+
+
+@model
+def volume_transport(speed, width, depth):
+    """Section volume transport.
+
+    Integrating velocity over a section produces volume transport.
+
+    Parameters
+    ----------
+    speed : float or array_like
+        m/s; constraint: real.
+    width : float or array_like
+        m; constraint: positive.
+    depth : float or array_like
+        m; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Uniform signed velocity and rectangular section; output m cubed per second, not Sverdrups.
+    Equation: ``speed * width * depth``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    speed = quantity("speed", speed)
+    width = quantity("width", width, lower=0, strict_lower=True)
+    depth = quantity("depth", depth, lower=0, strict_lower=True)
+    return speed * width * depth
+
+
+@model
+def sverdrup_transport(wind_stress_curl, density, beta):
+    """Sverdrup meridional transport.
+
+    Wind-stress curl drives interior flow across planetary vorticity contours.
+
+    Parameters
+    ----------
+    wind_stress_curl : float or array_like
+        Pa/m; constraint: real.
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    beta : float or array_like
+        1/(m s); constraint: positive. Northward gradient of the Coriolis parameter.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m^2/s]: depth-integrated northward transport per unit zonal width.
+
+    Notes
+    -----
+    Steady linear interior balance away from boundaries, friction and the equator's singular Ekman layer.
+    Negative curl (subtropical gyres) drives equatorward flow.
+    Equation: ``wind_stress_curl / (density * beta)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    wind_stress_curl = quantity("wind_stress_curl", wind_stress_curl)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    beta = quantity("beta", beta, lower=0, strict_lower=True)
+    return wind_stress_curl / (density * beta)
+
+
+@model
+def stommel_streamfunction(x, y, wind_stress, basin_width, basin_length, density, beta, friction):
+    """Transport streamfunction of Stommel's wind-driven gyre.
+
+    Bottom friction and the beta effect confine the return flow to a western boundary current.
+
+    Parameters
+    ----------
+    x : float or array_like
+        m; constraint: 0 <= x <= basin_width. Eastward distance from the western wall.
+    y : float or array_like
+        m; constraint: 0 <= y <= basin_length. Northward distance from the southern wall.
+    wind_stress : float or array_like
+        Pa; constraint: real. Amplitude of the zonal stress ``-wind_stress * cos(pi y / basin_length)``.
+    basin_width : float or array_like
+        m; constraint: positive.
+    basin_length : float or array_like
+        m; constraint: positive.
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    beta : float or array_like
+        1/(m s); constraint: nonnegative. Zero gives Stommel's symmetric uniform-rotation gyre.
+    friction : float or array_like
+        1/s; constraint: positive. Linear bottom-drag coefficient on the depth-integrated flow.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m^3/s]. Northward transport is the eastward derivative.
+
+    Notes
+    -----
+    Steady linear barotropic vorticity balance ``friction * laplacian(psi) + beta * dpsi/dx = curl(tau) / density`` in a
+    rectangular basin with ``psi = 0`` on the walls. Positive wind stress gives a clockwise (subtropical) gyre whose
+    western boundary layer has width ``friction / beta``.
+    Equation: ``wind_stress * basin_length / (np.pi * density * friction) * np.sin(np.pi * y / basin_length) * X``
+    with ``X = 1 + ((np.exp(m2 * L) - 1) * np.exp(m1 * (x - L)) + (np.exp(-m1 * L) - 1) * np.exp(m2 * x))
+    / (1 - np.exp((m2 - m1) * L))``, ``L = basin_width``,
+    ``m1, m2 = (-beta +/- np.sqrt(beta**2 + 4 * friction**2 * k**2)) / (2 * friction)`` and ``k = np.pi / basin_length``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    x = quantity("x", x, lower=0)
+    y = quantity("y", y, lower=0)
+    wind_stress = quantity("wind_stress", wind_stress)
+    basin_width = quantity("basin_width", basin_width, lower=0, strict_lower=True)
+    basin_length = quantity("basin_length", basin_length, lower=0, strict_lower=True)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    beta = quantity("beta", beta, lower=0)
+    friction = quantity("friction", friction, lower=0, strict_lower=True)
+    require(x <= basin_width, "x must lie inside the basin")
+    require(y <= basin_length, "y must lie inside the basin")
+    k = np.pi / basin_length
+    root = np.sqrt(beta**2 + 4 * friction**2 * k**2)
+    m1 = 2 * friction * k**2 / (beta + root)
+    m2 = -(beta + root) / (2 * friction)
+    shape = 1 + ((np.exp(m2 * basin_width) - 1) * np.exp(m1 * (x - basin_width)) + (np.exp(-m1 * basin_width) - 1) * np.exp(m2 * x)) / (
+        1 - np.exp((m2 - m1) * basin_width)
+    )
+    return wind_stress * basin_length / (np.pi * density * friction) * np.sin(np.pi * y / basin_length) * shape
+
+
+@model
+def rossby_radius(buoyancy_frequency, depth, coriolis):
+    """Baroclinic deformation scale.
+
+    Stratification and rotation set a horizontal adjustment scale.
+
+    Parameters
+    ----------
+    buoyancy_frequency : float or array_like
+        1/s; constraint: positive.
+    depth : float or array_like
+        m; constraint: positive.
+    coriolis : float or array_like
+        1/s; constraint: nonzero.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    First-mode constant-N rigid-boundary estimate N H over pi f; not a general layered solution.
+    Equation: ``buoyancy_frequency * depth / (np.pi * np.abs(coriolis))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    buoyancy_frequency = quantity("buoyancy_frequency", buoyancy_frequency, lower=0, strict_lower=True)
+    depth = quantity("depth", depth, lower=0, strict_lower=True)
+    coriolis = quantity("coriolis", coriolis)
+    require(coriolis != 0, "coriolis must be nonzero")
+    return buoyancy_frequency * depth / (np.pi * np.abs(coriolis))
+
+
+@model
+def thermohaline_forcing(flow, thermal_flow, haline_coefficient):
+    """Salt forcing that holds Stommel's two-box overturning steady.
+
+    Salt advection by the overturning must balance the freshwater-driven salinity contrast.
+
+    Parameters
+    ----------
+    flow : float or array_like
+        m^3/s; constraint: at most thermal_flow. Overturning, positive when polar water sinks.
+    thermal_flow : float or array_like
+        m^3/s; constraint: positive. Overturning the temperature contrast alone would drive.
+    haline_coefficient : float or array_like
+        m^3/s per g/kg; constraint: positive. Overturning lost per unit salinity contrast.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [g/kg m^3/s]: the virtual salt flux into the equatorial box.
+
+    Notes
+    -----
+    Temperatures held fixed by fast restoring; flow ``q = thermal_flow - haline_coefficient * dS`` and steady salt budget
+    ``abs(q) * dS = forcing``. Read as forcing against flow, the curve folds at ``q = thermal_flow / 2``: for
+    ``0 < forcing < thermal_flow**2 / (4 * haline_coefficient)`` a thermal and a haline state coexist.
+    Equation: ``np.abs(flow) * (thermal_flow - flow) / haline_coefficient``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    flow = quantity("flow", flow)
+    thermal_flow = quantity("thermal_flow", thermal_flow, lower=0, strict_lower=True)
+    haline_coefficient = quantity("haline_coefficient", haline_coefficient, lower=0, strict_lower=True)
+    require(flow <= thermal_flow, "flow above thermal_flow implies a negative salinity contrast")
+    return np.abs(flow) * (thermal_flow - flow) / haline_coefficient
+
+
+@safe_arithmetic
+def simulate_thermohaline_boxes(thermal_flow, haline_coefficient, salt_forcing, volume, time, *, initial_salinity_difference=0.0):
+    """Integrate Stommel's two-box thermohaline circulation.
+
+    Parameters
+    ----------
+    thermal_flow : float
+        Positive scalar overturning driven by the fixed temperature contrast [m^3/s].
+    haline_coefficient : float
+        Positive scalar overturning lost per unit salinity contrast [m^3/s per g/kg].
+    salt_forcing : float
+        Nonnegative scalar virtual salt flux into the equatorial box [g/kg m^3/s].
+    volume : float
+        Positive scalar volume of each box [m^3].
+    time : array_like
+        Nonnegative strictly increasing sampled times [s].
+    initial_salinity_difference : float
+        Equatorial minus polar salinity at the first time [g/kg].
+
+    Returns
+    -------
+    TimeSeries
+        Salinity difference [g/kg] and overturning [m^3/s], positive when polar water sinks.
+
+    Notes
+    -----
+    ``volume * dS/dt = salt_forcing - abs(q) * dS`` with ``q = thermal_flow - haline_coefficient * dS``.
+    Temperatures are held fixed by fast restoring. Steady states satisfy
+    :func:`thermohaline_forcing`; below the fold forcing
+    thermal_flow**2 / (4 * haline_coefficient) the initial state decides
+    between the thermal (q > 0) and haline (q < 0) regimes.
+    """
+    from earthsciencekit._validation import time_grid
+    from earthsciencekit.integrators import integrate_ode
+    from earthsciencekit.oceanography.core.base import TimeSeries
+
+    thermal_flow = quantity("thermal_flow", thermal_flow, lower=0, strict_lower=True)
+    haline_coefficient = quantity("haline_coefficient", haline_coefficient, lower=0, strict_lower=True)
+    salt_forcing = quantity("salt_forcing", salt_forcing, lower=0)
+    volume = quantity("volume", volume, lower=0, strict_lower=True)
+    initial_salinity_difference = quantity("initial_salinity_difference", initial_salinity_difference)
+    scalars = (thermal_flow, haline_coefficient, salt_forcing, volume, initial_salinity_difference)
+    require(all(v.ndim == 0 for v in scalars), "box parameters must be scalars")
+    time = time_grid(time)
+
+    def rhs(t, state):
+        flow = thermal_flow - haline_coefficient * state[0]
+        return [(salt_forcing - np.abs(flow) * state[0]) / volume]
+
+    salinity = integrate_ode(rhs, [initial_salinity_difference], time).values[:, 0]
+    values = np.column_stack([salinity, thermal_flow - haline_coefficient * salinity])
+    return TimeSeries(time, values, ("salinity_difference", "overturning"), ("g/kg", "m^3/s"))

earthsciencekit/oceanography/systems/hydrography.py

@@ -0,0 +1,212 @@
+"""Hydrography: hydrostatic pressure, equations of state, stratification and the abyssal temperature profile.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+
+__all__ = [
+    "hydrostatic_pressure",
+    "linear_density",
+    "buoyancy_frequency_squared",
+    "abyssal_temperature",
+    "simplified_seawater_density",
+]
+
+
+@model
+def hydrostatic_pressure(density, depth, gravity):
+    """Ocean hydrostatic pressure.
+
+    Water weight connects pressure and depth.
+
+    Parameters
+    ----------
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    depth : float or array_like
+        m; constraint: nonnegative.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Gauge pressure with constant density; atmospheric pressure is excluded.
+    Equation: ``density * gravity * depth``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    density = quantity("density", density, lower=0, strict_lower=True)
+    depth = quantity("depth", depth, lower=0)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return density * gravity * depth
+
+
+@model
+def linear_density(reference_density, temperature_anomaly, salinity_anomaly, thermal_expansion, haline_contraction):
+    """Linear seawater equation of state.
+
+    Temperature and salinity both change buoyancy.
+
+    Parameters
+    ----------
+    reference_density : float or array_like
+        kg/m^3; constraint: positive.
+    temperature_anomaly : float or array_like
+        K; constraint: real.
+    salinity_anomaly : float or array_like
+        g/kg; constraint: real.
+    thermal_expansion : float or array_like
+        1/K; constraint: nonnegative.
+    haline_contraction : float or array_like
+        kg/g; constraint: nonnegative.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Local linearization around a supplied reference; not TEOS-10 and no pressure dependence.
+    Equation: ``reference_density * (1 - thermal_expansion * temperature_anomaly + haline_contraction * salinity_anomaly)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    reference_density = quantity("reference_density", reference_density, lower=0, strict_lower=True)
+    temperature_anomaly = quantity("temperature_anomaly", temperature_anomaly)
+    salinity_anomaly = quantity("salinity_anomaly", salinity_anomaly)
+    thermal_expansion = quantity("thermal_expansion", thermal_expansion, lower=0)
+    haline_contraction = quantity("haline_contraction", haline_contraction, lower=0)
+    require(
+        1 - thermal_expansion * temperature_anomaly + haline_contraction * salinity_anomaly > 0, "linearization implies nonpositive density"
+    )
+    return reference_density * (1 - thermal_expansion * temperature_anomaly + haline_contraction * salinity_anomaly)
+
+
+@model
+def simplified_seawater_density(conservative_temperature, absolute_salinity, depth):
+    """Simplified nonlinear seawater density fitted to TEOS-10.
+
+    Cabbeling and thermobaricity make seawater density nonlinear in temperature, salinity and pressure.
+
+    Parameters
+    ----------
+    conservative_temperature : float or array_like
+        K; constraint: positive.
+    absolute_salinity : float or array_like
+        g/kg; constraint: nonnegative.
+    depth : float or array_like
+        m; constraint: nonnegative.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    The S-EOS of Roquet et al. (2015) with NEMO's default coefficients: ``a0 = 0.16550``, ``b0 = 0.76554``,
+    ``lambda1 = 5.9520e-2``, ``lambda2 = 7.4914e-4``, ``mu1 = 1.4970e-4``, ``mu2 = 1.1090e-5``, ``nu = 2.4341e-3``
+    and ``rho0 = 1026``, with anomalies ``t = conservative_temperature - 283.15`` and ``s = absolute_salinity - 35``.
+    It reproduces the TEOS-10 density gradients over typical ocean conditions; absolute density can be off by about
+    1 kg/m^3 and it is not TEOS-10 itself.
+    Equation: ``1026 - a0 * (1 + lambda1 * t / 2 + mu1 * depth) * t + b0 * (1 - lambda2 * s / 2 - mu2 * depth) * s - nu * t * s``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    conservative_temperature = quantity("conservative_temperature", conservative_temperature, lower=0, strict_lower=True)
+    absolute_salinity = quantity("absolute_salinity", absolute_salinity, lower=0)
+    depth = quantity("depth", depth, lower=0)
+    t = conservative_temperature - 283.15
+    s = absolute_salinity - 35
+    thermal = 0.16550 * (1 + 0.5 * 5.9520e-2 * t + 1.4970e-4 * depth) * t
+    haline = 0.76554 * (1 - 0.5 * 7.4914e-4 * s - 1.1090e-5 * depth) * s
+    return 1026 - thermal + haline - 2.4341e-3 * t * s
+
+
+@model
+def buoyancy_frequency_squared(density, upward_density_gradient, gravity):
+    """Ocean density stratification.
+
+    Vertical density gradients control internal oscillations and convection.
+
+    Parameters
+    ----------
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    upward_density_gradient : float or array_like
+        kg/m^4; constraint: real.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Coordinate increases upward; negative output denotes unstable stratification.
+    Equation: ``-gravity * upward_density_gradient / density``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    density = quantity("density", density, lower=0, strict_lower=True)
+    upward_density_gradient = quantity("upward_density_gradient", upward_density_gradient)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return -gravity * upward_density_gradient / density
+
+
+@model
+def abyssal_temperature(height, bottom_temperature, top_temperature, column_height, diffusivity, upwelling):
+    """Munk's advective-diffusive abyssal temperature profile.
+
+    Slow upwelling balanced by downward mixing of heat sets an exponential thermocline.
+
+    Parameters
+    ----------
+    height : float or array_like
+        m; constraint: 0 <= height <= column_height. Height above the bottom of the column.
+    bottom_temperature : float or array_like
+        K; constraint: positive.
+    top_temperature : float or array_like
+        K; constraint: positive.
+    column_height : float or array_like
+        m; constraint: positive.
+    diffusivity : float or array_like
+        m^2/s; constraint: positive. Vertical eddy diffusivity.
+    upwelling : float or array_like
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [K]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Steady one-dimensional balance ``upwelling * dT/dz = diffusivity * d2T/dz2`` with fixed end temperatures;
+    the scale height is ``h = diffusivity / upwelling`` (about 1 km in Munk's recipe).
+    Equation: ``bottom_temperature + (top_temperature - bottom_temperature)
+    * (np.exp((height - column_height) / h) - np.exp(-column_height / h)) / (1 - np.exp(-column_height / h))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    height = quantity("height", height, lower=0)
+    bottom_temperature = quantity("bottom_temperature", bottom_temperature, lower=0, strict_lower=True)
+    top_temperature = quantity("top_temperature", top_temperature, lower=0, strict_lower=True)
+    column_height = quantity("column_height", column_height, lower=0, strict_lower=True)
+    diffusivity = quantity("diffusivity", diffusivity, lower=0, strict_lower=True)
+    upwelling = quantity("upwelling", upwelling, lower=0, strict_lower=True)
+    require(height <= column_height, "height must lie inside the column")
+    scale = diffusivity / upwelling
+    shape = np.exp((height - column_height) / scale) * -np.expm1(-height / scale) / -np.expm1(-column_height / scale)
+    return bottom_temperature + (top_temperature - bottom_temperature) * shape

earthsciencekit/oceanography/systems/inertial.py

@@ -0,0 +1,86 @@
+"""Inertial motion: the inertial period and damped inertial currents.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require, safe_arithmetic
+
+__all__ = [
+    "inertial_period",
+    "simulate_inertial_current",
+]
+
+
+@model
+def inertial_period(coriolis):
+    """Inertial oscillation period.
+
+    Rotation supplies a natural timescale for ocean motion.
+
+    Parameters
+    ----------
+    coriolis : float or array_like
+        1/s; constraint: nonzero.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [Pa]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    No pressure gradient or friction; invalid at zero Coriolis parameter.
+    Equation: ``2 * np.pi / np.abs(coriolis)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    coriolis = quantity("coriolis", coriolis)
+    require(coriolis != 0, "coriolis must be nonzero")
+    return 2 * np.pi / np.abs(coriolis)
+
+
+@safe_arithmetic
+def simulate_inertial_current(coriolis, time, *, east_speed=1.0, north_speed=0.0, damping=0.0):
+    """Integrate rotating, optionally damped horizontal ocean currents.
+
+    Parameters
+    ----------
+    coriolis : float
+        Finite nonzero scalar Coriolis parameter [1/s], signed by hemisphere.
+    time : array_like
+        Nonnegative strictly increasing sampled times [s].
+    east_speed, north_speed : float
+        Initial signed horizontal velocity components [m/s].
+    damping : float
+        Nonnegative scalar linear decay rate [1/s].
+
+    Returns
+    -------
+    TimeSeries
+        Eastward and northward velocity [m/s].
+
+    Notes
+    -----
+    du/dt = f v - r u; dv/dt = -f u - r v. With no damping, speed is
+    conserved and northern-hemisphere motion rotates clockwise. Pressure
+    gradients and wind forcing are omitted.
+    """
+    from earthsciencekit._validation import time_grid
+    from earthsciencekit.integrators import integrate_ode
+
+    coriolis = quantity("coriolis", coriolis)
+    damping = quantity("damping", damping, lower=0)
+    east_speed = quantity("east_speed", east_speed)
+    north_speed = quantity("north_speed", north_speed)
+    require(all(v.ndim == 0 for v in (coriolis, damping, east_speed, north_speed)), "current parameters must be scalars")
+    require(coriolis != 0, "coriolis must be nonzero")
+    time = time_grid(time)
+    return integrate_ode(
+        lambda t, y: [coriolis * y[1] - damping * y[0], -coriolis * y[0] - damping * y[1]],
+        [east_speed, north_speed],
+        time,
+        names=("east_velocity", "north_velocity"),
+        units=("m/s", "m/s"),
+    )