earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/plate_tectonics/tests/test_physics.py

@@ -0,0 +1,94 @@
+"""Physical identities, limits and dynamic checks for earthsciencekit.plate_tectonics."""
+
+import numpy as np
+import pytest
+
+from earthsciencekit.plate_tectonics.systems.cooling import diffuse_temperature, halfspace_heat_flux, mantle_rayleigh_number, ocean_depth
+from earthsciencekit.plate_tectonics.systems.isostasy import flexural_deflection, flexural_parameter
+from earthsciencekit.plate_tectonics.systems.kinematics import (
+    angular_speed,
+    compose_euler_vectors,
+    euler_velocity_x,
+    euler_velocity_y,
+    euler_velocity_z,
+    hotspot_age,
+    plate_speed,
+)
+
+
+def test_periodic_diffusion_conservation_and_eigenmode():
+    n, spacing, diffusivity = 16, 2.0, 0.1
+    initial = 300 + 10 * np.cos(2 * np.pi * np.arange(n) / n)
+    time = np.linspace(10, 110, 31)
+    result = diffuse_temperature(initial, time, diffusivity, spacing)
+    np.testing.assert_allclose(result.values.mean(axis=1), 300, atol=1e-12)
+    rate = 4 * diffusivity * np.sin(np.pi / n) ** 2 / spacing**2
+    expected = 300 + (initial - 300)[None, :] * np.exp(-rate * (time - time[0]))[:, None]
+    np.testing.assert_allclose(result.values, expected, atol=1e-12)
+    assert result.values.min() >= initial.min() and result.values.max() <= initial.max()
+    for initial, diffusion, spacing in [([300, 310], 1, 1), ([[300] * 3], 1, 1), ([300] * 3, [1, 2], 1), ([300] * 3, 0, 1)]:
+        with pytest.raises(ValueError):
+            diffuse_temperature(initial, [0, 1], diffusion, spacing)
+
+
+def test_plate_rotation_tangent_and_speed():
+    omega = np.array([1.0, 2.0, 3.0]) * 1e-9
+    r = np.array([3.0, 4.0, 5.0]) * 1e6
+    v = np.array(
+        [
+            euler_velocity_x(omega[1], omega[2], r[1], r[2]),
+            euler_velocity_y(omega[2], omega[0], r[2], r[0]),
+            euler_velocity_z(omega[0], omega[1], r[0], r[1]),
+        ]
+    )
+    np.testing.assert_allclose(v, np.cross(omega, r))
+    assert abs(np.dot(v, r)) < 1e-10
+    distance = np.arccos(np.dot(omega, r) / (np.linalg.norm(omega) * np.linalg.norm(r)))
+    assert np.isclose(plate_speed(np.linalg.norm(omega), np.linalg.norm(r), distance), np.linalg.norm(v))
+
+
+def test_flexure_balances_load_and_places_bulge():
+    rigidity, contrast, gravity, load = 1e23, 2300.0, 9.8, 2e12
+    alpha = flexural_parameter(rigidity, contrast, gravity)
+    x = np.linspace(-25 * alpha, 25 * alpha, 200001)
+    w = flexural_deflection(x, load, rigidity, contrast, gravity)
+    assert np.isclose(np.trapezoid(contrast * gravity * w, x), load, rtol=1e-6)
+    w0 = flexural_deflection(0, load, rigidity, contrast, gravity)
+    assert np.isclose(flexural_deflection(3 * np.pi * alpha / 4, load, rigidity, contrast, gravity), 0, atol=1e-12 * w0)
+    assert np.isclose(flexural_deflection(np.pi * alpha, load, rigidity, contrast, gravity), -np.exp(-np.pi) * w0)
+
+
+def test_ocean_depth_matches_heat_flux_and_parsons_sclater():
+    year = 365.25 * 86400
+    age = np.array([1, 4, 25]) * 1e6 * year
+    depth = ocean_depth(age, 2500, 3300, 1000, 3e-5, 1e-6, 273, 1553)
+    np.testing.assert_allclose((depth - 2500) / np.sqrt(age / (1e6 * year)), 350, rtol=0.01)
+    np.testing.assert_allclose(np.diff(depth - 2500) / (depth - 2500)[:-1], [1, 1.5])
+    # Subsidence is the thermal contraction of the heat lost since the ridge: alpha * int(q dt) / (c_p (rho_m - rho_w)).
+    flux = halfspace_heat_flux(age, 1e-6, 3.3, 273, 1553)
+    heat_capacity = 3.3 / (3300 * 1e-6)
+    np.testing.assert_allclose(depth - 2500, 3e-5 * 2 * flux * age / (heat_capacity * (3300 - 1000)))
+
+
+def test_euler_circuit_closes_and_velocities_add():
+    omega_ab = np.array([1.0, -2.0, 0.5]) * 1e-9
+    omega_bc = np.array([-0.3, 0.8, 2.0]) * 1e-9
+    omega_ac = compose_euler_vectors(omega_ab, omega_bc)
+    np.testing.assert_allclose(compose_euler_vectors(omega_ac, -omega_ac), 0)
+    r = np.array([3.0, 4.0, 5.0]) * 1e6
+    np.testing.assert_allclose(np.cross(omega_ac, r), np.cross(omega_ab, r) + np.cross(omega_bc, r))
+
+
+def test_hotspot_age_is_rotation_angle_over_rate():
+    omega, radius, colatitude = 2e-15, 6.371e6, np.array([0.3, 1.0, 2.5])
+    angle = 0.2
+    ages = hotspot_age(angle * radius * np.sin(colatitude), omega, radius, colatitude)
+    np.testing.assert_allclose(ages, angle / omega)
+    assert np.isclose(angular_speed(angle, ages[0]), omega)
+
+
+def test_mantle_rayleigh_number_cubic_in_thickness():
+    args = (3e-5, 4000, 9.8, 2500, 1e6, 1e-6, 1e21)
+    ratio = mantle_rayleigh_number(*args[:4], 2 * args[4], *args[5:]) / mantle_rayleigh_number(*args)
+    assert np.isclose(ratio, 8)
+    assert mantle_rayleigh_number(3e-5, 4000, 9.8, 0, 1e6, 1e-6, 1e21) == 0

earthsciencekit/plate_tectonics/visualizers/__init__.py

@@ -0,0 +1,9 @@
+"""Plots for earthsciencekit.plate_tectonics.
+
+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/results.py

@@ -0,0 +1,73 @@
+"""Immutable sampled histories shared by the numerical models."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ._validation import quantity, require
+
+
+@dataclass(frozen=True)
+class TimeSeries:
+    """A time grid in seconds and one or more state columns.
+
+    Parameters
+    ----------
+    time : array_like, shape (n,)
+        Finite, strictly increasing seconds; at least two samples.
+    values : array_like, shape (n, m)
+        Finite real state columns in the units given by ``units``.
+    names, units : tuple of str, length m
+        Unique state names and explicit output unit labels.
+
+    Notes
+    -----
+    Input data are copied and made read-only. Samples do not imply a continuous
+    interpolation or independently validate the governing model.
+    """
+
+    time: np.ndarray
+    values: np.ndarray
+    names: tuple[str, ...]
+    units: tuple[str, ...]
+
+    def __post_init__(self):
+        time = quantity("time", self.time)
+        values = quantity("values", self.values)
+        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")
+        require(values.ndim == 2 and values.shape[0] == time.size, "values must have shape (time, state)")
+        names, units = tuple(self.names), tuple(self.units)
+        require(len(names) == values.shape[1] == len(units), "one name and unit per state required")
+        require(all(isinstance(s, str) and s for s in names + units), "names and units must be nonempty strings")
+        require(len(set(names)) == len(names), "state names must be unique")
+        time.setflags(write=False)
+        values.setflags(write=False)
+        object.__setattr__(self, "time", time)
+        object.__setattr__(self, "values", values)
+        object.__setattr__(self, "names", names)
+        object.__setattr__(self, "units", units)
+
+    def summary(self):
+        """Return each state's minimum, maximum, final value and unit label."""
+        return {
+            name: {
+                "minimum": float(self.values[:, i].min()),
+                "maximum": float(self.values[:, i].max()),
+                "final": float(self.values[-1, i]),
+                "unit": self.units[i],
+            }
+            for i, name in enumerate(self.names)
+        }
+
+    def plot(self):
+        """Create one labeled Matplotlib axis per state; return figure and axes."""
+        from .visualizers import plot_series
+
+        return plot_series(self)
+
+    def animate(self, *, interval=40):
+        """Create a history-reveal animation; interval is milliseconds per frame."""
+        from .visualizers import animate_series
+
+        return animate_series(self, interval=interval)

earthsciencekit/seismology/__init__.py

@@ -0,0 +1,59 @@
+"""Inspectable seismology models; SI units unless stated otherwise."""
+
+from earthsciencekit.seismology.systems.interfaces import (
+    reflection_coefficient,
+    seismic_impedance,
+    transmission_coefficient,
+)
+from earthsciencekit.seismology.systems.rays import (
+    critical_angle,
+    crossover_distance,
+    head_wave_travel_time,
+    ray_parameter,
+    travel_time,
+    vertical_travel_time,
+)
+from earthsciencekit.seismology.systems.sources import (
+    gutenberg_richter,
+    local_magnitude,
+    moment_from_magnitude,
+    moment_magnitude,
+    omori_rate,
+    seismic_moment,
+    simulate_oscillator,
+)
+from earthsciencekit.seismology.systems.waves import (
+    attenuated_amplitude,
+    love_wave_angular_frequency,
+    p_wave_speed,
+    poisson_ratio,
+    rayleigh_wave_speed,
+    ricker_wavelet,
+    s_wave_speed,
+)
+
+__all__ = [
+    "p_wave_speed",
+    "s_wave_speed",
+    "poisson_ratio",
+    "travel_time",
+    "seismic_impedance",
+    "reflection_coefficient",
+    "transmission_coefficient",
+    "critical_angle",
+    "seismic_moment",
+    "moment_magnitude",
+    "moment_from_magnitude",
+    "gutenberg_richter",
+    "omori_rate",
+    "ricker_wavelet",
+    "attenuated_amplitude",
+    "rayleigh_wave_speed",
+    "head_wave_travel_time",
+    "crossover_distance",
+    "love_wave_angular_frequency",
+    "ray_parameter",
+    "local_magnitude",
+    "vertical_travel_time",
+    "simulate_oscillator",
+]

earthsciencekit/seismology/core/__init__.py

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

earthsciencekit/seismology/core/base.py

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

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

earthsciencekit/seismology/systems/interfaces.py

@@ -0,0 +1,102 @@
+"""Interfaces: seismic impedance and normal-incidence reflection and transmission.
+
+SI units unless stated otherwise.
+"""
+
+from earthsciencekit._validation import model, quantity
+
+__all__ = [
+    "seismic_impedance",
+    "reflection_coefficient",
+    "transmission_coefficient",
+]
+
+
+@model
+def seismic_impedance(density, speed):
+    """Acoustic impedance.
+
+    Impedance contrasts control normal-incidence reflection.
+
+    Parameters
+    ----------
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    speed : float or array_like
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Scalar acoustic impedance; elastic mode conversion is excluded.
+    Equation: ``density * speed``.
+    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)
+    speed = quantity("speed", speed, lower=0, strict_lower=True)
+    return density * speed
+
+
+@model
+def reflection_coefficient(impedance1, impedance2):
+    """Normal-incidence pressure reflection.
+
+    An interface divides incident energy into reflected and transmitted waves.
+
+    Parameters
+    ----------
+    impedance1 : float or array_like
+        kg/(m^2 s); constraint: positive.
+    impedance2 : float or array_like
+        kg/(m^2 s); constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Pressure amplitude convention at normal incidence; coefficient can be negative.
+    Equation: ``(impedance2 - impedance1) / (impedance2 + impedance1)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    impedance1 = quantity("impedance1", impedance1, lower=0, strict_lower=True)
+    impedance2 = quantity("impedance2", impedance2, lower=0, strict_lower=True)
+    return (impedance2 - impedance1) / (impedance2 + impedance1)
+
+
+@model
+def transmission_coefficient(impedance1, impedance2):
+    """Normal-incidence pressure transmission.
+
+    Pressure transmission differs from transmitted energy fraction.
+
+    Parameters
+    ----------
+    impedance1 : float or array_like
+        kg/(m^2 s); constraint: positive.
+    impedance2 : float or array_like
+        kg/(m^2 s); constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Normal-incidence acoustic pressure amplitudes, not displacement amplitudes.
+    Equation: ``2 * impedance2 / (impedance2 + impedance1)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    impedance1 = quantity("impedance1", impedance1, lower=0, strict_lower=True)
+    impedance2 = quantity("impedance2", impedance2, lower=0, strict_lower=True)
+    return 2 * impedance2 / (impedance2 + impedance1)

earthsciencekit/seismology/systems/rays.py

@@ -0,0 +1,221 @@
+"""Rays and travel times: direct, head and vertical waves, crossover distance, critical angle and ray parameter.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+
+__all__ = [
+    "travel_time",
+    "critical_angle",
+    "head_wave_travel_time",
+    "crossover_distance",
+    "ray_parameter",
+    "vertical_travel_time",
+]
+
+
+@model
+def travel_time(distance, speed):
+    """Homogeneous travel time.
+
+    Arrival times connect source distance and propagation speed.
+
+    Parameters
+    ----------
+    distance : float or array_like
+        m; constraint: nonnegative.
+    speed : float or array_like
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Straight path in a homogeneous medium; not a ray tracer.
+    Equation: ``distance / speed``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    distance = quantity("distance", distance, lower=0)
+    speed = quantity("speed", speed, lower=0, strict_lower=True)
+    return distance / speed
+
+
+@model
+def critical_angle(speed1, speed2):
+    """Snell refraction critical angle.
+
+    Snell refraction explains head waves above a faster layer.
+
+    Parameters
+    ----------
+    speed1 : float or array_like
+        m/s; constraint: positive.
+    speed2 : float or array_like
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Incidence from the slower medium; second speed must exceed first.
+    Equation: ``np.arcsin(speed1 / speed2)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    speed1 = quantity("speed1", speed1, lower=0, strict_lower=True)
+    speed2 = quantity("speed2", speed2, lower=0, strict_lower=True)
+    require(speed2 > speed1, "second medium must be faster")
+    return np.arcsin(speed1 / speed2)
+
+
+@model
+def head_wave_travel_time(distance, thickness, speed1, speed2):
+    """Head-wave travel time below a single layer.
+
+    A wave critically refracted along a faster layer overtakes the direct wave at long range.
+
+    Parameters
+    ----------
+    distance : float or array_like
+        m; constraint: nonnegative, at least the critical distance.
+    thickness : float or array_like
+        m; constraint: positive.
+    speed1 : float or array_like
+        m/s; constraint: positive.
+    speed2 : float or array_like
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [s]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Flat layer of speed1 over a faster half-space of speed2, surface source and receiver.
+    The head wave exists only beyond the critical distance ``2 * thickness * tan(critical_angle)``.
+    Equation: ``distance / speed2 + 2 * thickness * np.sqrt(speed2**2 - speed1**2) / (speed1 * speed2)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    distance = quantity("distance", distance, lower=0)
+    thickness = quantity("thickness", thickness, lower=0, strict_lower=True)
+    speed1 = quantity("speed1", speed1, lower=0, strict_lower=True)
+    speed2 = quantity("speed2", speed2, lower=0, strict_lower=True)
+    require(speed2 > speed1, "second medium must be faster")
+    require(distance >= 2 * thickness * speed1 / np.sqrt(speed2**2 - speed1**2), "distance is inside the critical distance")
+    return distance / speed2 + 2 * thickness * np.sqrt(speed2**2 - speed1**2) / (speed1 * speed2)
+
+
+@model
+def crossover_distance(thickness, speed1, speed2):
+    """Head-wave crossover distance.
+
+    The range at which the refracted wave arrives first measures the depth of the layer.
+
+    Parameters
+    ----------
+    thickness : float or array_like
+        m; constraint: positive.
+    speed1 : float or array_like
+        m/s; constraint: positive.
+    speed2 : float or array_like
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Flat layer of speed1 over a faster half-space of speed2; direct and head-wave times are equal there.
+    Equation: ``2 * thickness * np.sqrt((speed2 + speed1) / (speed2 - speed1))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    thickness = quantity("thickness", thickness, lower=0, strict_lower=True)
+    speed1 = quantity("speed1", speed1, lower=0, strict_lower=True)
+    speed2 = quantity("speed2", speed2, lower=0, strict_lower=True)
+    require(speed2 > speed1, "second medium must be faster")
+    return 2 * thickness * np.sqrt((speed2 + speed1) / (speed2 - speed1))
+
+
+@model
+def ray_parameter(radius, speed, incidence_angle):
+    """Ray parameter in a spherically layered Earth.
+
+    Snell's law on a sphere keeps one quantity fixed along each ray, which fixes where it emerges.
+
+    Parameters
+    ----------
+    radius : float or array_like
+        m; constraint: positive.
+    speed : float or array_like
+        m/s; constraint: positive.
+    incidence_angle : float or array_like
+        rad; constraint: between 0 and pi/2, measured from the radial direction.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [s/rad]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Spherically symmetric isotropic Earth; the value is the same at every point of one ray.
+    Equation: ``radius * np.sin(incidence_angle) / speed``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    speed = quantity("speed", speed, lower=0, strict_lower=True)
+    incidence_angle = quantity("incidence_angle", incidence_angle, lower=0, upper=np.pi / 2)
+    return radius * np.sin(incidence_angle) / speed
+
+
+@model
+def vertical_travel_time(depth, speed):
+    """Vertical travel time through a tabulated speed profile.
+
+    Integrating slowness through a reference Earth model predicts arrival times.
+
+    Parameters
+    ----------
+    depth : array_like, shape (n,), n >= 2
+        m; constraint: nonnegative and nondecreasing. A repeated depth marks a discontinuity.
+    speed : array_like, shape (n,)
+        m/s; constraint: positive.
+
+    Returns
+    -------
+    ndarray, shape (n,)
+        Model value [s]: one-way vertical time from the first depth to each depth.
+
+    Notes
+    -----
+    Speed varies linearly in depth between tabulated points; the integral of each segment is exact.
+    Equation: ``cumsum(dz * np.log(v2 / v1) / (v2 - v1))``, which is ``dz / v1`` where ``v2 == v1``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    depth = quantity("depth", depth, lower=0)
+    speed = quantity("speed", speed, lower=0, strict_lower=True)
+    require(depth.ndim == 1 and depth.size >= 2, "depth must be a vector with at least two samples")
+    require(speed.shape == depth.shape, "speed must have the same shape as depth")
+    require(np.all(np.diff(depth) >= 0), "depth must not decrease")
+    change = np.diff(speed) / speed[:-1]
+    factor = np.ones_like(change)
+    varying = change != 0
+    factor[varying] = np.log1p(change[varying]) / change[varying]
+    return np.concatenate([[0.0], np.cumsum(np.diff(depth) / speed[:-1] * factor)])