earthsciencekit.oceanography#

Domain hub · History · Examples · API reference

Inspectable oceanography models; SI units unless stated otherwise.

earthsciencekit.oceanography.abyssal_temperature(height, bottom_temperature, top_temperature, column_height, diffusivity, upwelling)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.buoyancy_frequency_squared(density, upward_density_gradient, gravity)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.deep_group_speed(wavelength, gravity)[source]#

Deep-water group speed.

Wave energy travels at group speed rather than crest phase speed.

Parameters:

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Deep-water gravity waves; group speed is half phase speed. Equation: 0.5 * np.sqrt(gravity * wavelength / (2 * np.pi)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.oceanography.deep_wave_speed(wavelength, gravity)[source]#

Deep-water phase speed.

Short waves relative to depth propagate dispersively.

Parameters:

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Deep-water small-amplitude gravity waves without capillarity. Equation: np.sqrt(gravity * wavelength / (2 * np.pi)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.oceanography.ekman_spiral_velocity(depth, wind_stress, density, eddy_viscosity, coriolis)[source]#

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:

Model value [m/s]: the downwind component and the crosswind component, positive to the right of the wind.

Return type:

ndarray, shape (…, 2)

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 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.

earthsciencekit.oceanography.ekman_transport(wind_stress, density, coriolis)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.geostrophic_current(surface_slope, coriolis, gravity)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.gerstner_orbit_radius(rest_depth, amplitude, wavenumber)[source]#

Particle-orbit radius in a Gerstner trochoidal wave.

Water particles in a deep-water wave move on circles that shrink with depth.

Parameters:

  • rest_depth (float or array_like) – m; constraint: nonnegative. Depth of the particle’s orbit centre below the mean surface.

  • amplitude (float or array_like) – m; constraint: nonnegative. Orbit radius at the surface.

  • wavenumber (float or array_like) – 1/m; constraint: positive.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Exact nonlinear deep-water solution with closed orbits and no Stokes drift; the flow has vorticity. amplitude * wavenumber must not exceed 1, where the surface trochoid forms a cusp. A particle at rest position (a, b) moves to (a - r sin(k a - omega t), -b + r cos(k a - omega t)) with omega = sqrt(g k). Equation: amplitude * np.exp(-wavenumber * rest_depth). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.oceanography.hydrostatic_pressure(density, depth, gravity)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.inertial_period(coriolis)[source]#

Inertial oscillation period.

Rotation supplies a natural timescale for ocean motion.

Parameters:

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

Returns:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.internal_wave_speed(reduced_gravity, upper_depth, lower_depth)[source]#

Two-layer internal long wave.

Layer depths and buoyancy jointly set internal long-wave speed.

Parameters:

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

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Hydrostatic two-layer fluid under a rigid lid. Equation: np.sqrt(reduced_gravity * upper_depth * lower_depth / (upper_depth + lower_depth)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.oceanography.linear_density(reference_density, temperature_anomaly, salinity_anomaly, thermal_expansion, haline_contraction)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.reduced_gravity(density_difference, reference_density, gravity)[source]#

Two-layer reduced gravity.

A small density contrast slows internal waves relative to surface waves.

Parameters:

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

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Boussinesq small density contrast; output is acceleration. Equation: gravity * density_difference / reference_density. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.oceanography.rossby_radius(buoyancy_frequency, depth, coriolis)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.shallow_wave_speed(depth, gravity)[source]#

Shallow-water gravity wave.

Long surface waves respond to water depth through gravity.

Parameters:

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Wavelength much greater than depth, small amplitude, no dispersion. Equation: np.sqrt(gravity * depth). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.oceanography.simplified_seawater_density(conservative_temperature, absolute_salinity, depth)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.simulate_inertial_current(coriolis, time, *, east_speed=1.0, north_speed=0.0, damping=0.0)[source]#

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 (float) – Initial signed horizontal velocity components [m/s].

  • north_speed (float) – Initial signed horizontal velocity components [m/s].

  • damping (float) – Nonnegative scalar linear decay rate [1/s].

Returns:

Eastward and northward velocity [m/s].

Return type:

TimeSeries

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.

earthsciencekit.oceanography.simulate_thermohaline_boxes(thermal_flow, haline_coefficient, salt_forcing, volume, time, *, initial_salinity_difference=0.0)[source]#

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:

Salinity difference [g/kg] and overturning [m^3/s], positive when polar water sinks.

Return type:

TimeSeries

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 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.

earthsciencekit.oceanography.stommel_streamfunction(x, y, wind_stress, basin_width, basin_length, density, beta, friction)[source]#

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:

Model value [m^3/s]. Northward transport is the eastward derivative.

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.sverdrup_transport(wind_stress_curl, density, beta)[source]#

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:

Model value [m^2/s]: depth-integrated northward transport per unit zonal width.

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.thermohaline_forcing(flow, thermal_flow, haline_coefficient)[source]#

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:

Model value [g/kg m^3/s]: the virtual salt flux into the equatorial box.

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.tidal_elevation(time, amplitude, period, phase)[source]#

Single harmonic tide.

Harmonic constituents provide an inspectable tide representation.

Parameters:

  • time (float or array_like) – s; constraint: real.

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

  • period (float or array_like) – s; constraint: positive.

  • phase (float or array_like) – rad; constraint: real.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

One supplied constituent; not a site-specific tide prediction or navigational product. Equation: amplitude * np.cos(2 * np.pi * time / period + phase). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.oceanography.volume_transport(speed, width, depth)[source]#

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:

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

Return type:

numpy scalar or ndarray

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.

earthsciencekit.oceanography.wave_angular_frequency(wavenumber, depth, gravity)[source]#

Finite-depth dispersion relation.

The dispersion relation bridges shallow and deep gravity waves.

Parameters:

  • wavenumber (float or array_like) – 1/m; constraint: positive.

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Linear inviscid surface gravity wave, no current or surface tension. Equation: np.sqrt(gravity * wavenumber * np.tanh(wavenumber * depth)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.