earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/oceanography/tests/test_physics.py

@@ -0,0 +1,102 @@
+"""Physical identities, limits and dynamic checks for earthsciencekit.oceanography."""
+
+import numpy as np
+import pytest
+
+from earthsciencekit.oceanography.systems.circulation import (
+    ekman_spiral_velocity,
+    ekman_transport,
+    simulate_thermohaline_boxes,
+    stommel_streamfunction,
+    sverdrup_transport,
+    thermohaline_forcing,
+)
+from earthsciencekit.oceanography.systems.hydrography import abyssal_temperature, linear_density, simplified_seawater_density
+from earthsciencekit.oceanography.systems.inertial import simulate_inertial_current
+from earthsciencekit.oceanography.systems.waves import gerstner_orbit_radius
+
+
+def test_inertial_current_direction_and_damping():
+    f, damping = 0.1, 0.01
+    time = np.linspace(0, 60, 101)
+    result = simulate_inertial_current(f, time, damping=damping)
+    np.testing.assert_allclose(result.values[:, 0], np.exp(-damping * time) * np.cos(f * time), atol=3e-8)
+    np.testing.assert_allclose(result.values[:, 1], -np.exp(-damping * time) * np.sin(f * time), atol=3e-8)
+    undamped = simulate_inertial_current(f, time)
+    np.testing.assert_allclose(np.sum(undamped.values**2, axis=1), 1, atol=3e-8)
+    southern = simulate_inertial_current(-f, time)
+    assert southern.values[1, 1] > 0 > undamped.values[1, 1]
+    for coriolis in [0, [f, f]]:
+        with pytest.raises(ValueError):
+            simulate_inertial_current(coriolis, time)
+
+
+def test_linear_density_rejects_invalid_reference_linearization():
+    with pytest.raises(ValueError):
+        linear_density(1000, 1e5, 0, 0.001, 0.001)
+
+
+def test_ekman_spiral_integrates_to_ekman_transport():
+    depth = np.linspace(0, 1000, 100001)
+    for coriolis in [1e-4, -1e-4]:
+        velocity = ekman_spiral_velocity(depth, 0.1, 1025, 0.05, coriolis)
+        assert np.isclose(np.trapezoid(velocity[:, 0], depth), 0, atol=1e-6)
+        assert np.isclose(np.trapezoid(velocity[:, 1], depth), ekman_transport(0.1, 1025, coriolis), rtol=1e-6)
+        assert np.isclose(abs(np.arctan2(velocity[0, 1], velocity[0, 0])), np.pi / 4)
+
+
+def test_stommel_interior_is_sverdrup_and_beta_free_gyre_is_symmetric():
+    width, length, tau, rho, beta, friction = 6e6, 5e6, 0.1, 1025, 2e-11, 1e-7
+    x = np.array([0.3, 0.5, 0.8]) * width
+    psi = stommel_streamfunction(x, length / 2, tau, width, length, rho, beta, friction)
+    curl = -tau * np.pi / length
+    np.testing.assert_allclose(psi, -sverdrup_transport(curl, rho, beta) * (width - x), rtol=0.02)
+    symmetric = stommel_streamfunction([0.2 * width, 0.8 * width], length / 3, tau, width, length, rho, 0, friction)
+    assert np.isclose(symmetric[0], symmetric[1])
+    edges = stommel_streamfunction([0, width, width / 2], [length / 2, length / 2, 0], tau, width, length, rho, beta, friction)
+    np.testing.assert_allclose(edges, 0, atol=1e-6 * psi[0])
+
+
+def test_thermohaline_boxes_reach_both_steady_states():
+    thermal, haline, forcing, volume = 3e7, 6e6, 3e7, 1e16
+    time = np.linspace(0, 3e10, 61)
+    for initial, sign in [(0.0, 1), (8.0, -1)]:
+        result = simulate_thermohaline_boxes(thermal, haline, forcing, volume, time, initial_salinity_difference=initial)
+        flow = result.values[-1, 1]
+        assert np.sign(flow) == sign
+        assert np.isclose(thermohaline_forcing(flow, thermal, haline), forcing, rtol=1e-6)
+        np.testing.assert_allclose(result.values[:, 1], thermal - haline * result.values[:, 0])
+    flows = np.linspace(0, thermal, 1001)
+    assert np.isclose(thermohaline_forcing(flows, thermal, haline).max(), thermal**2 / (4 * haline))
+    for bad in [[thermal, thermal], 0]:
+        with pytest.raises(ValueError):
+            simulate_thermohaline_boxes(bad, haline, forcing, volume, time)
+
+
+def test_abyssal_profile_solves_advection_diffusion():
+    z = np.linspace(0, 4000, 4001)
+    temperature = abyssal_temperature(z, 274, 284, 4000, 1e-4, 1e-7)
+    gradient, curvature = np.gradient(temperature, z), np.gradient(np.gradient(temperature, z), z)
+    np.testing.assert_allclose(1e-7 * gradient[5:-5], 1e-4 * curvature[5:-5], rtol=1e-4)
+    linear = abyssal_temperature(z, 274, 284, 4000, 1e-4, 1e-12)
+    np.testing.assert_allclose(linear, 274 + 10 * z / 4000, atol=1e-3)
+
+
+def test_simplified_density_cabbeling_and_linear_limit():
+    from scipy.optimize import brentq
+
+    cold = (275.15, 34.6)
+    rho_cold = simplified_seawater_density(*cold, 0)
+    warm = (293.15, brentq(lambda s: simplified_seawater_density(293.15, s, 0) - rho_cold, 30, 45, xtol=1e-14))
+    mixed = simplified_seawater_density((cold[0] + warm[0]) / 2, (cold[1] + warm[1]) / 2, 0)
+    assert mixed > rho_cold
+    small = np.array([1e-4, -1e-4])
+    nonlinear = simplified_seawater_density(283.15 + small, 35 + small[::-1], 0)
+    linear = linear_density(1026, small, small[::-1], 0.16550 / 1026, 0.76554 / 1026)
+    np.testing.assert_allclose(nonlinear, linear, atol=1e-8)
+
+
+def test_gerstner_orbits_decay_one_wavelength_down():
+    k = 2 * np.pi / 100
+    ratio = gerstner_orbit_radius(100, 1.0, k) / gerstner_orbit_radius(0, 1.0, k)
+    assert np.isclose(ratio, np.exp(-2 * np.pi))

earthsciencekit/oceanography/visualizers/__init__.py

@@ -0,0 +1,9 @@
+"""Plots for earthsciencekit.oceanography.
+
+The dynamic models return a TimeSeries, whose ``plot`` and ``animate`` methods
+call these package-wide helpers.
+"""
+
+from earthsciencekit.visualizers import animate_series, plot_series
+
+__all__ = ["plot_series", "animate_series"]

earthsciencekit/plate_tectonics/__init__.py

@@ -0,0 +1,59 @@
+"""Inspectable plate tectonics models; SI units unless stated otherwise."""
+
+from earthsciencekit.plate_tectonics.systems.boundaries import (
+    convergence_rate,
+    fault_slip_rate,
+    full_spreading_rate,
+    slab_pull_force,
+    spreading_age,
+    subduction_travel_time,
+)
+from earthsciencekit.plate_tectonics.systems.cooling import (
+    diffuse_temperature,
+    halfspace_heat_flux,
+    halfspace_temperature,
+    mantle_rayleigh_number,
+    ocean_depth,
+)
+from earthsciencekit.plate_tectonics.systems.isostasy import (
+    airy_root,
+    flexural_deflection,
+    flexural_parameter,
+    flexural_rigidity,
+)
+from earthsciencekit.plate_tectonics.systems.kinematics import (
+    angular_speed,
+    compose_euler_vectors,
+    euler_velocity_x,
+    euler_velocity_y,
+    euler_velocity_z,
+    hotspot_age,
+    plate_displacement,
+    plate_speed,
+)
+
+__all__ = [
+    "angular_speed",
+    "plate_speed",
+    "euler_velocity_x",
+    "euler_velocity_y",
+    "euler_velocity_z",
+    "plate_displacement",
+    "spreading_age",
+    "full_spreading_rate",
+    "convergence_rate",
+    "fault_slip_rate",
+    "subduction_travel_time",
+    "slab_pull_force",
+    "airy_root",
+    "flexural_rigidity",
+    "flexural_parameter",
+    "halfspace_temperature",
+    "halfspace_heat_flux",
+    "mantle_rayleigh_number",
+    "flexural_deflection",
+    "hotspot_age",
+    "ocean_depth",
+    "compose_euler_vectors",
+    "diffuse_temperature",
+]

earthsciencekit/plate_tectonics/core/__init__.py

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

earthsciencekit/plate_tectonics/core/base.py

@@ -0,0 +1,10 @@
+"""Result containers for earthsciencekit.plate_tectonics.
+
+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/plate_tectonics/systems/__init__.py

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

earthsciencekit/plate_tectonics/systems/boundaries.py

@@ -0,0 +1,201 @@
+"""Plate boundaries: spreading ridges, transform and convergent margins, subducting slabs and slab pull.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+
+__all__ = [
+    "spreading_age",
+    "full_spreading_rate",
+    "convergence_rate",
+    "fault_slip_rate",
+    "subduction_travel_time",
+    "slab_pull_force",
+]
+
+
+@model
+def spreading_age(distance, half_spreading_rate):
+    """Magnetic-stripe spreading clock.
+
+    Symmetric ocean-floor ages link ridge spreading to plate creation.
+
+    Parameters
+    ----------
+    distance : float or array_like
+        m; constraint: nonnegative.
+    half_spreading_rate : float or array_like
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Distance on one side and half-spreading rate; changes in rate are omitted.
+    Equation: ``distance / half_spreading_rate``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    distance = quantity("distance", distance, lower=0)
+    half_spreading_rate = quantity("half_spreading_rate", half_spreading_rate, lower=0, strict_lower=True)
+    return distance / half_spreading_rate
+
+
+@model
+def full_spreading_rate(half_spreading_rate):
+    """Symmetric full spreading rate.
+
+    Opposite plate velocities combine into ridge opening speed.
+
+    Parameters
+    ----------
+    half_spreading_rate : float or array_like
+        m/s; constraint: nonnegative.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Symmetric spreading; asymmetric velocities require their own relative-vector calculation.
+    Equation: ``2 * half_spreading_rate``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    half_spreading_rate = quantity("half_spreading_rate", half_spreading_rate, lower=0)
+    return 2 * half_spreading_rate
+
+
+@model
+def convergence_rate(relative_speed, obliquity):
+    """Signed plate-boundary convergence.
+
+    Resolving relative motion normal to a boundary separates convergence and shear.
+
+    Parameters
+    ----------
+    relative_speed : float or array_like
+        m/s; constraint: nonnegative.
+    obliquity : float or array_like
+        rad; constraint: width.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Positive normal component denotes convergence; negative denotes divergence.
+    Equation: ``relative_speed * np.cos(obliquity)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    relative_speed = quantity("relative_speed", relative_speed, lower=0)
+    obliquity = quantity("obliquity", obliquity, lower=0, upper=2 * np.pi)
+    return relative_speed * np.cos(obliquity)
+
+
+@model
+def fault_slip_rate(relative_speed, obliquity):
+    """Tangential boundary slip rate.
+
+    The tangential motion component connects oblique convergence to strike slip.
+
+    Parameters
+    ----------
+    relative_speed : float or array_like
+        m/s; constraint: nonnegative.
+    obliquity : float or array_like
+        rad; constraint: width.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Supplied obliquity is oriented from the positive convergence normal.
+    Equation: ``relative_speed * np.sin(obliquity)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    relative_speed = quantity("relative_speed", relative_speed, lower=0)
+    obliquity = quantity("obliquity", obliquity, lower=0, upper=2 * np.pi)
+    return relative_speed * np.sin(obliquity)
+
+
+@model
+def subduction_travel_time(vertical_depth, slab_speed, dip):
+    """Slab path travel time.
+
+    Slab dip changes the path length required to reach a specified depth.
+
+    Parameters
+    ----------
+    vertical_depth : float or array_like
+        m; constraint: nonnegative.
+    slab_speed : float or array_like
+        m/s; constraint: positive.
+    dip : float or array_like
+        rad; constraint: inclination.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Straight slab at constant speed; zero dip cannot reach depth and is rejected.
+    Equation: ``vertical_depth / (slab_speed * np.sin(dip))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    vertical_depth = quantity("vertical_depth", vertical_depth, lower=0)
+    slab_speed = quantity("slab_speed", slab_speed, lower=0, strict_lower=True)
+    dip = quantity("dip", dip, lower=0, upper=np.pi / 2)
+    require(dip > 0, "slab dip must be positive")
+    return vertical_depth / (slab_speed * np.sin(dip))
+
+
+@model
+def slab_pull_force(density_excess, slab_volume, gravity):
+    """Slab negative-buoyancy force.
+
+    A cold slab can drive motion through its excess weight.
+
+    Parameters
+    ----------
+    density_excess : float or array_like
+        kg/m^3; constraint: nonnegative.
+    slab_volume : float or array_like
+        m^3; constraint: nonnegative.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Simple buoyancy force magnitude; drag, phase changes and mantle flow are excluded.
+    Equation: ``density_excess * slab_volume * gravity``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    density_excess = quantity("density_excess", density_excess, lower=0)
+    slab_volume = quantity("slab_volume", slab_volume, lower=0)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return density_excess * slab_volume * gravity

earthsciencekit/plate_tectonics/systems/cooling.py

@@ -0,0 +1,238 @@
+"""Cooling and convection: half-space cooling, heat flux, ocean depth, mantle Rayleigh number and periodic diffusion.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+from scipy.special import erf
+
+from earthsciencekit._validation import model, quantity, require, safe_arithmetic
+
+__all__ = [
+    "halfspace_temperature",
+    "halfspace_heat_flux",
+    "mantle_rayleigh_number",
+    "ocean_depth",
+    "diffuse_temperature",
+]
+
+
+@model
+def halfspace_temperature(depth, age, diffusivity, surface_temperature, mantle_temperature):
+    """Cooling oceanic lithosphere.
+
+    Oceanic plates cool as their age and distance from a ridge increase.
+
+    Parameters
+    ----------
+    depth : float or array_like
+        m; constraint: nonnegative.
+    age : float or array_like
+        s; constraint: positive.
+    diffusivity : float or array_like
+        m^2/s; constraint: positive.
+    surface_temperature : float or array_like
+        K; constraint: positive.
+    mantle_temperature : float or array_like
+        K; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Semi-infinite conduction with fixed surface temperature; no hydrothermal or advective heat transfer.
+    Equation: ``surface_temperature + (mantle_temperature - surface_temperature) * erf(depth / (2 * np.sqrt(diffusivity * age)))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    depth = quantity("depth", depth, lower=0)
+    age = quantity("age", age, lower=0, strict_lower=True)
+    diffusivity = quantity("diffusivity", diffusivity, lower=0, strict_lower=True)
+    surface_temperature = quantity("surface_temperature", surface_temperature, lower=0, strict_lower=True)
+    mantle_temperature = quantity("mantle_temperature", mantle_temperature, lower=0, strict_lower=True)
+    require(mantle_temperature >= surface_temperature, "mantle must be at least as warm as surface")
+    return surface_temperature + (mantle_temperature - surface_temperature) * erf(depth / (2 * np.sqrt(diffusivity * age)))
+
+
+@model
+def halfspace_heat_flux(age, diffusivity, conductivity, surface_temperature, mantle_temperature):
+    """Cooling-plate surface heat flux.
+
+    Surface heat flux decreases as an oceanic plate cools.
+
+    Parameters
+    ----------
+    age : float or array_like
+        s; constraint: positive.
+    diffusivity : float or array_like
+        m^2/s; constraint: positive.
+    conductivity : float or array_like
+        W/(m K); constraint: positive.
+    surface_temperature : float or array_like
+        K; constraint: positive.
+    mantle_temperature : float or array_like
+        K; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Positive upward flux; semi-infinite conductive model excludes the zero-age singularity.
+    Equation: ``conductivity * (mantle_temperature - surface_temperature) / np.sqrt(np.pi * diffusivity * age)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    age = quantity("age", age, lower=0, strict_lower=True)
+    diffusivity = quantity("diffusivity", diffusivity, lower=0, strict_lower=True)
+    conductivity = quantity("conductivity", conductivity, lower=0, strict_lower=True)
+    surface_temperature = quantity("surface_temperature", surface_temperature, lower=0, strict_lower=True)
+    mantle_temperature = quantity("mantle_temperature", mantle_temperature, lower=0, strict_lower=True)
+    require(mantle_temperature >= surface_temperature, "mantle must be at least as warm as surface")
+    return conductivity * (mantle_temperature - surface_temperature) / np.sqrt(np.pi * diffusivity * age)
+
+
+@model
+def ocean_depth(age, ridge_depth, mantle_density, water_density, thermal_expansivity, diffusivity, surface_temperature, mantle_temperature):
+    """Ocean depth of a cooling half-space.
+
+    Thermal contraction of the cooling plate makes the sea floor deepen with the square root of its age.
+
+    Parameters
+    ----------
+    age : float or array_like
+        s; constraint: nonnegative.
+    ridge_depth : float or array_like
+        m; constraint: nonnegative.
+    mantle_density : float or array_like
+        kg/m^3; constraint: positive.
+    water_density : float or array_like
+        kg/m^3; constraint: positive.
+    thermal_expansivity : float or array_like
+        1/K; constraint: positive.
+    diffusivity : float or array_like
+        m^2/s; constraint: positive.
+    surface_temperature : float or array_like
+        K; constraint: positive.
+    mantle_temperature : float or array_like
+        K; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Isostatic half-space cooling, depth positive downward; it overestimates depth on sea floor older than about 70 million years.
+    Equation: ``ridge_depth + 2 * mantle_density * thermal_expansivity * (mantle_temperature - surface_temperature)
+    / (mantle_density - water_density) * np.sqrt(diffusivity * age / np.pi)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    age = quantity("age", age, lower=0)
+    ridge_depth = quantity("ridge_depth", ridge_depth, lower=0)
+    mantle_density = quantity("mantle_density", mantle_density, lower=0, strict_lower=True)
+    water_density = quantity("water_density", water_density, lower=0, strict_lower=True)
+    thermal_expansivity = quantity("thermal_expansivity", thermal_expansivity, lower=0, strict_lower=True)
+    diffusivity = quantity("diffusivity", diffusivity, lower=0, strict_lower=True)
+    surface_temperature = quantity("surface_temperature", surface_temperature, lower=0, strict_lower=True)
+    mantle_temperature = quantity("mantle_temperature", mantle_temperature, lower=0, strict_lower=True)
+    require(mantle_density > water_density, "mantle must be denser than water")
+    require(mantle_temperature >= surface_temperature, "mantle must be at least as warm as surface")
+    subsidence = 2 * mantle_density * thermal_expansivity * (mantle_temperature - surface_temperature) / (mantle_density - water_density)
+    return ridge_depth + subsidence * np.sqrt(diffusivity * age / np.pi)
+
+
+@model
+def mantle_rayleigh_number(thermal_expansivity, density, gravity, temperature_difference, thickness, diffusivity, viscosity):
+    """Rayleigh number of a convecting mantle layer.
+
+    Buoyancy against viscous and thermal diffusion decides whether the mantle convects.
+
+    Parameters
+    ----------
+    thermal_expansivity : float or array_like
+        1/K; constraint: positive.
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+    temperature_difference : float or array_like
+        K; constraint: nonnegative.
+    thickness : float or array_like
+        m; constraint: positive.
+    diffusivity : float or array_like
+        m^2/s; constraint: positive.
+    viscosity : float or array_like
+        Pa s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Layer heated from below with uniform properties; convection starts above about 657.5 (free slip) or 1708 (rigid walls).
+    Equation: ``thermal_expansivity * density * gravity * temperature_difference * thickness**3 / (diffusivity * viscosity)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    thermal_expansivity = quantity("thermal_expansivity", thermal_expansivity, lower=0, strict_lower=True)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    temperature_difference = quantity("temperature_difference", temperature_difference, lower=0)
+    thickness = quantity("thickness", thickness, lower=0, strict_lower=True)
+    diffusivity = quantity("diffusivity", diffusivity, lower=0, strict_lower=True)
+    viscosity = quantity("viscosity", viscosity, lower=0, strict_lower=True)
+    return thermal_expansivity * density * gravity * temperature_difference * thickness**3 / (diffusivity * viscosity)
+
+
+@safe_arithmetic
+def diffuse_temperature(initial, time, diffusivity, spacing):
+    """Evolve a periodic one-dimensional conductive temperature grid.
+
+    Parameters
+    ----------
+    initial : array_like, shape (m,), m >= 3
+        Positive temperatures [K] on an equally spaced periodic grid.
+    time : array_like
+        Strictly increasing nonnegative output times [s]. Initial state belongs
+        to the first supplied time; values need not start at zero.
+    diffusivity : float
+        Positive scalar thermal diffusivity [m^2/s].
+    spacing : float
+        Positive scalar grid spacing [m].
+
+    Returns
+    -------
+    TimeSeries
+        Temperature at each grid point [K]. Columns are labeled cell_0, ... .
+
+    Notes
+    -----
+    The centered discrete Laplacian is diagonalized with a real FFT. Time
+    evolution of that discrete system is exact to floating-point accuracy.
+    Periodicity conserves mean temperature. Spatial discretization error remains;
+    this is not the fixed-surface half-space cooling boundary condition.
+    """
+    from earthsciencekit._validation import time_grid
+    from earthsciencekit.plate_tectonics.core.base import TimeSeries
+
+    initial = quantity("initial", initial, lower=0, strict_lower=True)
+    require(initial.ndim == 1 and initial.size >= 3, "at least three temperature cells are required")
+    time = time_grid(time)
+    diffusivity = quantity("diffusivity", diffusivity, lower=0, strict_lower=True)
+    spacing = quantity("spacing", spacing, lower=0, strict_lower=True)
+    require(diffusivity.ndim == spacing.ndim == 0, "diffusivity and spacing must be scalars")
+    with np.errstate(over="raise", divide="raise", invalid="raise"):
+        eigenvalues = -4 * diffusivity * np.sin(np.pi * np.fft.rfftfreq(initial.size)) ** 2 / spacing**2
+        spectra = np.fft.rfft(initial)[None, :] * np.exp((time - time[0])[:, None] * eigenvalues)
+        values = np.fft.irfft(spectra, n=initial.size, axis=1)
+    return TimeSeries(time, values, tuple(f"cell_{i}" for i in range(initial.size)), ("K",) * initial.size)