earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/seismology/tests/test_physics.py

@@ -0,0 +1,100 @@
+"""Physical identities, limits and dynamic checks for earthsciencekit.seismology."""
+
+import numpy as np
+import pytest
+
+from earthsciencekit.seismology.systems.interfaces import reflection_coefficient, 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 local_magnitude, moment_from_magnitude, moment_magnitude, simulate_oscillator
+from earthsciencekit.seismology.systems.waves import love_wave_angular_frequency, poisson_ratio, rayleigh_wave_speed, ricker_wavelet
+
+
+def test_seismic_oscillator_analytic():
+    frequency, Q = 1.0, 10.0
+    time = np.linspace(0, 2, 101)
+    result = simulate_oscillator(frequency, Q, time)
+    omega = 2 * np.pi * frequency
+    damping = omega / (2 * Q)
+    wd = np.sqrt(omega**2 - damping**2)
+    expected = np.exp(-damping * time) * (np.cos(wd * time) + damping / wd * np.sin(wd * time))
+    np.testing.assert_allclose(result.values[:, 0], expected, atol=3e-8)
+    energy = result.values[:, 1] ** 2 + omega**2 * result.values[:, 0] ** 2
+    assert np.all(np.diff(energy) <= 1e-8)
+    with pytest.raises(ValueError):
+        simulate_oscillator([1, 2], Q, time)
+
+
+def test_wave_interface_energy_balance():
+    z1, z2 = 2.0, 6.0
+    r = reflection_coefficient(z1, z2)
+    t = transmission_coefficient(z1, z2)
+    assert np.isclose(r * r + (z1 / z2) * t * t, 1)
+    assert np.isclose(moment_magnitude(moment_from_magnitude(7)), 7)
+    np.testing.assert_allclose(ricker_wavelet([-1, 0, 1], 2), ricker_wavelet([1, 0, -1], 2))
+
+
+def test_rayleigh_speed_solves_rayleigh_secular_equation():
+    vs = 1.0
+    vp = np.array([1.2, np.sqrt(3), 3.0, 10.0])
+    c = rayleigh_wave_speed(vp, vs)
+    assert np.all(c < vs)
+    np.testing.assert_allclose((2 - c**2 / vs**2) ** 2, 4 * np.sqrt(1 - c**2 / vp**2) * np.sqrt(1 - c**2 / vs**2), atol=1e-12)
+    # Viktorov's approximation (0.862 + 1.14 nu) / (1 + nu) holds to about 0.3% for nu >= 0.25.
+    nu = poisson_ratio(vp[1:], vs)
+    np.testing.assert_allclose(c[1:], (0.862 + 1.14 * nu) / (1 + nu), rtol=3e-3)
+
+
+def test_head_wave_crosses_direct_wave_and_starts_at_reflection():
+    h, v1, v2 = 30e3, 6e3, 8e3
+    x_cross = crossover_distance(h, v1, v2)
+    assert np.isclose(head_wave_travel_time(x_cross, h, v1, v2), travel_time(x_cross, v1))
+    x_crit = 2 * h * np.tan(critical_angle(v1, v2))
+    assert np.isclose(head_wave_travel_time(x_crit, h, v1, v2), np.hypot(x_crit, 2 * h) / v1)
+    x = np.array([2e5, 3e5])
+    assert np.isclose(np.diff(head_wave_travel_time(x, h, v1, v2))[0], 1e5 / v2)
+
+
+def test_love_dispersion_root_and_limits():
+    h, b1, b2, m1, m2 = 35e3, 3.5e3, 4.5e3, 3.4e10, 6.7e10
+    c = np.linspace(3.6e3, 4.4e3, 9)
+    omega = love_wave_angular_frequency(c, h, b1, b2, m1, m2)
+    k = omega / c
+    s1, s2 = np.sqrt(c**2 / b1**2 - 1), np.sqrt(1 - c**2 / b2**2)
+    np.testing.assert_allclose(np.tan(k * h * s1), m2 * s2 / (m1 * s1))
+    assert np.all(np.diff(omega) < 0)
+    assert love_wave_angular_frequency(b2 * (1 - 1e-12), h, b1, b2, m1, m2) < 1e-5
+    assert love_wave_angular_frequency(b1 * (1 + 1e-12), h, b1, b2, m1, m2) > 1e3
+
+
+def test_ray_parameter_is_snell_on_a_sphere():
+    r, v_above, v_below = 3.48e6, 13e3, 8e3
+    above = np.deg2rad(50.0)
+    p = ray_parameter(r, v_above, above)
+    below = np.arcsin(p * v_below / r)
+    assert np.isclose(ray_parameter(r, v_below, below), p)
+    # A straight ray in a uniform shell keeps r sin(i) fixed, hence the same p at every radius.
+    impact = r * np.sin(above)
+    for radius in [r, 4e6, 6.371e6]:
+        assert np.isclose(ray_parameter(radius, v_above, np.arcsin(impact / radius)), p)
+
+
+def test_local_magnitude_is_logarithmic_in_amplitude():
+    assert np.isclose(local_magnitude(1e-6, 1e5), 0)
+    np.testing.assert_allclose(np.diff(local_magnitude([1e-4, 1e-3, 1e-2], 3e5)), 1)
+    assert local_magnitude(1e-3, 3e5) > local_magnitude(1e-3, 1e5)
+
+
+def test_vertical_travel_time_profiles():
+    depth = np.linspace(0, 1e5, 11)
+    np.testing.assert_allclose(vertical_travel_time(depth, np.full(11, 5e3)), travel_time(depth, 5e3))
+    v0, gradient = 5e3, 0.02
+    np.testing.assert_allclose(vertical_travel_time(depth, v0 + gradient * depth), np.log1p(gradient * depth / v0) / gradient)
+    jump = vertical_travel_time([0, 1e4, 1e4, 2e4], [5e3, 5e3, 8e3, 8e3])
+    np.testing.assert_allclose(jump, [0, 2, 2, 2 + 1.25])

earthsciencekit/seismology/visualizers/__init__.py

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

@@ -0,0 +1,181 @@
+"""Independent identities, conservation checks and failure contracts."""
+
+from types import SimpleNamespace
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+import pytest
+
+from earthsciencekit import __version__, atmosphere, oceanography, seismology
+from earthsciencekit._validation import model, quantity, require, time_grid
+from earthsciencekit.integrators import integrate_ode
+from earthsciencekit.results import TimeSeries
+from earthsciencekit.units import available_units, convert
+from earthsciencekit.visualizers import animate_series, plot_series
+
+
+def test_version():
+    assert __version__ == "0.2.0"
+
+
+def test_bounds_and_scalar_array_contract():
+    np.testing.assert_array_equal(quantity("x", [0, 1], lower=0, upper=1), [0, 1])
+    assert quantity("x", 1).ndim == 0
+    for kwargs, value in [
+        ({"lower": 0}, -1),
+        ({"lower": 0, "strict_lower": True}, 0),
+        ({"upper": 1}, 2),
+        ({"upper": 1, "strict_upper": True}, 1),
+    ]:
+        with pytest.raises(ValueError):
+            quantity("x", value, **kwargs)
+    with pytest.raises(ValueError):
+        require([True, False], "invalid")
+    require([True, True], "valid")
+
+
+def test_arithmetic_rejection():
+    with pytest.raises(ValueError, match="arithmetic"):
+        seismology.moment_from_magnitude(1000)
+
+    @model
+    def nonfinite():
+        return float("inf")
+
+    with pytest.raises(ValueError, match="nonfinite"):
+        nonfinite()
+
+
+@pytest.mark.parametrize("bad", [[], [1], [0, 0], [1, 0], [-1, 1], [[0, 1]], [0, np.nan]])
+def test_time_grid_bad(bad):
+    with pytest.raises(ValueError):
+        time_grid(bad)
+
+
+def test_units():
+    assert convert(1, "km", "m") == 1000
+    assert convert(0, "degC", "K") == 273.15
+    assert convert(273.15, "K", "degC") == 0
+    assert convert(1, "Sv", "m^3/s") == 1e6
+    assert convert(1, "year", "day") == 365.25
+    assert convert(1, "Ga", "Ma") == 1000 and convert(1, "kyr", "year") == 1000 and convert(1, "GPa", "MPa") == 1000
+    np.testing.assert_allclose(convert(convert([1, 5], "cm/year", "m/s"), "m/s", "cm/year"), [1, 5])
+    assert convert(180, "degree", "rad") == np.pi
+    assert np.isclose(convert(1, "mGal", "m/s^2"), 1e-5) and np.isclose(convert(5e4, "nT", "T"), 5e-5)
+    units = available_units()
+    units.pop("K")
+    assert "K" in available_units()
+    for source, target, value in [("m", "K", 1), ("bad", "m", 1), ([], "m", 1), ("K", "K", -1)]:
+        with pytest.raises(ValueError):
+            convert(value, source, target)
+
+
+def test_result_copy_summary_and_plots(tmp_path):
+    time = np.array([0.0, 1.0, 2.0])
+    values = np.array([[1.0, 2.0], [0.0, 3.0], [-1.0, 4.0]])
+    result = TimeSeries(time, values, ("a", "b"), ("m", "K"))
+    time[0] = -100
+    values[0, 0] = 999
+    assert result.time[0] == 0 and result.values[0, 0] == 1
+    assert not result.time.flags.writeable and not result.values.flags.writeable
+    assert result.summary()["a"] == {"minimum": -1.0, "maximum": 1.0, "final": -1.0, "unit": "m"}
+    figure, axes = result.plot()
+    assert len(axes) == 2 and axes[0].get_ylabel() == "a [m]"
+    plt.close(figure)
+    animation = result.animate(interval=15)
+    animation.save(tmp_path / "history.gif", writer="pillow")
+    assert (tmp_path / "history.gif").stat().st_size > 100
+    plt.close(animation._fig)
+    with pytest.raises(ValueError):
+        plot_series([1])
+    with pytest.raises(ValueError):
+        animate_series(result, interval=0)
+    with pytest.raises(ValueError):
+        animate_series(result, interval=[1, 2])
+
+
+@pytest.mark.parametrize(
+    "time, values, names, units",
+    [
+        ([0], [[1]], ("x",), ("m",)),
+        ([0, 0], [[1], [2]], ("x",), ("m",)),
+        ([0, 1], [1, 2], ("x",), ("m",)),
+        ([0, 1], [[1]], ("x",), ("m",)),
+        ([0, 1], [[1], [2]], (), ()),
+        ([0, 1], [[1], [2]], ("",), ("m",)),
+        ([0, 1], [[1, 2], [3, 4]], ("x", "x"), ("m", "m")),
+    ],
+)
+def test_result_rejects_bad_shape_and_labels(time, values, names, units):
+    with pytest.raises(ValueError):
+        TimeSeries(time, values, names, units)
+
+
+def test_ode_reference_and_defaults():
+    time = np.linspace(0, 3, 40)
+    result = integrate_ode(lambda t, y: -y, [2], time)
+    np.testing.assert_allclose(result.values[:, 0], 2 * np.exp(-time), rtol=3e-8)
+    assert result.names == ("x0",) and result.units == ("1",)
+    reference = integrate_ode(lambda t, y: [y[1], -y[0]], [1, 0], time, names=("position", "velocity"), units=("m", "m/s"), method="DOP853")
+    np.testing.assert_allclose(reference.values[:, 0], np.cos(time), atol=2e-8)
+    np.testing.assert_allclose(np.sum(reference.values**2, axis=1), 1, atol=4e-8)
+
+
+@pytest.mark.parametrize(
+    "kwargs", [{"rtol": 0}, {"atol": np.nan}, {"atol": [1, 2]}, {"method": "BAD"}, {"names": ["a", "b"]}, {"units": [""]}]
+)
+def test_ode_invalid_options(kwargs):
+    with pytest.raises(ValueError):
+        integrate_ode(lambda t, y: y, [1], [0, 1], **kwargs)
+
+
+def test_ode_failures(monkeypatch):
+    for rhs, initial, time in [
+        (0, [1], [0, 1]),
+        (lambda t, y: y, [[1]], [0, 1]),
+        (lambda t, y: y, [1], [0]),
+        (lambda t, y: y, [1], [1, 0]),
+        (lambda t, y: [1, 2], [1], [0, 1]),
+        (lambda t, y: [np.nan], [1], [0, 1]),
+    ]:
+        with pytest.raises(ValueError):
+            integrate_ode(rhs, initial, time)
+    monkeypatch.setattr("earthsciencekit.integrators.solve_ivp", lambda *a, **k: SimpleNamespace(success=False, message="test failure"))
+    with pytest.raises(ValueError, match="test failure"):
+        integrate_ode(lambda t, y: -y, [1], [0, 1])
+
+
+def test_humidity_and_wave_limits():
+    ratio = atmosphere.mixing_ratio(1000, 100000)
+    humidity = atmosphere.specific_humidity(ratio)
+    assert np.isclose(humidity / (1 - humidity), ratio)
+    assert atmosphere.coriolis_parameter(-np.pi / 4) < 0 < atmosphere.coriolis_parameter(np.pi / 4)
+    k, h, g = 1e-6, 10.0, 9.81
+    omega = oceanography.wave_angular_frequency(k, h, g)
+    assert np.isclose(omega / k, oceanography.shallow_wave_speed(h, g), rtol=1e-9)
+    k, h = 1.0, 100.0
+    omega = oceanography.wave_angular_frequency(k, h, g)
+    assert np.isclose(omega / k, oceanography.deep_wave_speed(2 * np.pi / k, g))
+
+
+def test_dynamic_overflow_is_normalized():
+    with pytest.raises(ValueError, match="arithmetic"):
+        seismology.simulate_oscillator(1e308, 10, [0, 1])
+
+
+@pytest.mark.parametrize("name", ["plate_tectonics", "seismology", "atmosphere", "climate", "oceanography", "geophysics", "volcanology"])
+def test_domain_family_layout(name):
+    import importlib
+    import inspect
+
+    domain = importlib.import_module(f"earthsciencekit.{name}")
+    core = importlib.import_module(f"earthsciencekit.{name}.core")
+    plots = importlib.import_module(f"earthsciencekit.{name}.visualizers")
+    assert core.TimeSeries is TimeSeries
+    assert plots.plot_series is plot_series and plots.animate_series is animate_series
+    for public in domain.__all__:
+        function = getattr(domain, public)
+        assert inspect.getmodule(function).__name__.startswith(f"earthsciencekit.{name}.systems."), public

earthsciencekit/tests/test_relations.py

@@ -0,0 +1,36 @@
+"""Cross-parameter relations that simple scalar bounds cannot establish."""
+
+import pytest
+
+from earthsciencekit import atmosphere as a
+from earthsciencekit import climate as c
+from earthsciencekit import plate_tectonics as p
+from earthsciencekit import seismology as s
+
+
+@pytest.mark.parametrize(
+    "function,args",
+    [
+        (p.plate_speed, [1, 1, 4]),
+        (p.subduction_travel_time, [1, 1, 0]),
+        (p.airy_root, [1, 3, 2]),
+        (p.halfspace_temperature, [1, 1, 1, 300, 200]),
+        (p.halfspace_heat_flux, [1, 1, 1, 300, 200]),
+        (p.ocean_depth, [1, 2500, 1000, 1000, 1, 1, 300, 1300]),
+        (p.ocean_depth, [1, 2500, 2, 1, 1, 1, 300, 200]),
+        (s.poisson_ratio, [1, 1]),
+        (s.critical_angle, [2, 1]),
+        (s.rayleigh_wave_speed, [1, 1]),
+        (s.head_wave_travel_time, [4, 1, 2, 1]),
+        (s.head_wave_travel_time, [1, 1, 1, 2]),
+        (s.crossover_distance, [1, 2, 2]),
+        (s.love_wave_angular_frequency, [1, 1, 1, 2, 1, 1]),
+        (s.love_wave_angular_frequency, [2, 1, 1, 2, 1, 1]),
+        (a.mixing_ratio, [1000, 100]),
+        (a.two_layer_temperature, [0, 288, 0.0065, 50000]),
+        (c.ice_albedo, [273, 0.2, 0.6, 273, 5]),
+    ],
+)
+def test_cross_parameter_rejections(function, args):
+    with pytest.raises(ValueError):
+        function(*args)

earthsciencekit/units/__init__.py

@@ -0,0 +1,66 @@
+"""Small explicit unit conversions; raw model arguments carry no unit metadata."""
+
+from earthsciencekit._validation import model, quantity, require
+from earthsciencekit.constants import SECONDS_PER_YEAR
+
+# scale and offset convert each unit to its SI base; temperature offsets are exact.
+_UNITS = {
+    "m": ("length", 1, 0),
+    "km": ("length", 1000, 0),
+    "cm": ("length", 0.01, 0),
+    "s": ("time", 1, 0),
+    "day": ("time", 86400, 0),
+    "year": ("time", SECONDS_PER_YEAR, 0),
+    "kyr": ("time", 1e3 * SECONDS_PER_YEAR, 0),
+    "Ma": ("time", 1e6 * SECONDS_PER_YEAR, 0),
+    "Ga": ("time", 1e9 * SECONDS_PER_YEAR, 0),
+    "Pa": ("pressure", 1, 0),
+    "hPa": ("pressure", 100, 0),
+    "MPa": ("pressure", 1e6, 0),
+    "GPa": ("pressure", 1e9, 0),
+    "K": ("temperature", 1, 0),
+    "degC": ("temperature", 1, 273.15),
+    "m/s": ("speed", 1, 0),
+    "cm/year": ("speed", 0.01 / SECONDS_PER_YEAR, 0),
+    "m/s^2": ("acceleration", 1, 0),
+    "mGal": ("acceleration", 1e-5, 0),
+    "T": ("magnetic field", 1, 0),
+    "nT": ("magnetic field", 1e-9, 0),
+    "rad": ("angle", 1, 0),
+    "degree": ("angle", 0.017453292519943295, 0),
+    "m^3/s": ("volume flow", 1, 0),
+    "Sv": ("volume flow", 1e6, 0),
+}
+
+
+@model
+def convert(value, source, target):
+    """Convert a finite scalar or array between listed compatible units.
+
+    Parameters
+    ----------
+    value : float or array_like
+        Quantity in source units. Temperature conversions require nonnegative kelvin.
+    source, target : str
+        Exact case-sensitive unit labels from available_units().
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Quantity in target units. Unknown units or incompatible dimensions fail.
+    """
+    value = quantity("value", value)
+    require(isinstance(source, str) and isinstance(target, str), "unit labels must be strings")
+    require(source in _UNITS and target in _UNITS, "unsupported unit label")
+    dimension, scale, offset = _UNITS[source]
+    target_dimension, target_scale, target_offset = _UNITS[target]
+    require(dimension == target_dimension, "incompatible unit dimensions")
+    base = value * scale + offset
+    if dimension == "temperature":
+        require(base >= 0, "temperature is below absolute zero")
+    return (base - target_offset) / target_scale
+
+
+def available_units():
+    """Return a new mapping of supported unit labels to dimension names."""
+    return {name: spec[0] for name, spec in _UNITS.items()}

earthsciencekit/visualizers/__init__.py

@@ -0,0 +1,45 @@
+"""Labeled figures and lightweight animations for sampled histories."""
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.animation import FuncAnimation
+
+from earthsciencekit._validation import quantity, require
+from earthsciencekit.results import TimeSeries
+
+__all__ = ["plot_series", "animate_series"]
+
+
+def plot_series(series):
+    """Plot a TimeSeries with one state and explicit unit label per axis."""
+    require(isinstance(series, TimeSeries), "series must be a TimeSeries")
+    figure, axes = plt.subplots(len(series.names), 1, squeeze=False, sharex=True)
+    axes = axes[:, 0]
+    for i, axis in enumerate(axes):
+        axis.plot(series.time, series.values[:, i])
+        axis.set_ylabel(f"{series.names[i]} [{series.units[i]}]")
+        axis.grid(alpha=0.2)
+    axes[-1].set_xlabel("time [s]")
+    figure.tight_layout()
+    return figure, axes
+
+
+def animate_series(series, *, interval=40):
+    """Reveal a sampled history progressively; return a Matplotlib animation.
+
+    Keep the returned object alive when displaying it, or call ``save`` with an
+    appropriate Matplotlib writer. Interval is positive scalar milliseconds.
+    """
+    interval = quantity("interval", interval, lower=0, strict_lower=True)
+    require(interval.ndim == 0, "interval must be a scalar")
+    figure, axes = plot_series(series)
+    lines = [axis.lines[0] for axis in axes]
+    for line in lines:
+        line.set_data([], [])
+
+    def update(frame):
+        for i, line in enumerate(lines):
+            line.set_data(series.time[: frame + 1], series.values[: frame + 1, i])
+        return lines
+
+    return FuncAnimation(figure, update, frames=np.arange(series.time.size), interval=float(interval), blit=True)

earthsciencekit/volcanology/__init__.py

@@ -0,0 +1,61 @@
+"""Inspectable volcanology and geochemistry models; SI units unless stated otherwise."""
+
+from earthsciencekit.volcanology.systems.eruptions import (
+    column_height,
+    plume_rise_height,
+    simulate_eruption_column,
+    volcanic_explosivity_index,
+)
+from earthsciencekit.volcanology.systems.geochemistry import (
+    delta_value,
+    equilibrium_crystallization_melt,
+    fractional_crystallization_melt,
+    isotope_temperature,
+    lattice_strain_partition,
+    rayleigh_fractionation,
+)
+from earthsciencekit.volcanology.systems.geochronology import (
+    concordia_ratios,
+    decay_constant,
+    isochron_fit,
+    lead_lead_age,
+    parent_fraction,
+    radiocarbon_age,
+    radiogenic_daughter,
+    radiogenic_lead_ratio,
+    radiometric_age,
+)
+from earthsciencekit.volcanology.systems.magma import (
+    arrhenius_viscosity,
+    dike_ascent_velocity,
+    mogi_displacement,
+    shaw_viscosity,
+    water_solubility,
+)
+
+__all__ = [
+    "rayleigh_fractionation",
+    "delta_value",
+    "decay_constant",
+    "parent_fraction",
+    "radiometric_age",
+    "radiogenic_daughter",
+    "fractional_crystallization_melt",
+    "equilibrium_crystallization_melt",
+    "lattice_strain_partition",
+    "isotope_temperature",
+    "radiocarbon_age",
+    "radiogenic_lead_ratio",
+    "lead_lead_age",
+    "concordia_ratios",
+    "plume_rise_height",
+    "mogi_displacement",
+    "isochron_fit",
+    "arrhenius_viscosity",
+    "shaw_viscosity",
+    "column_height",
+    "dike_ascent_velocity",
+    "water_solubility",
+    "volcanic_explosivity_index",
+    "simulate_eruption_column",
+]

earthsciencekit/volcanology/core/__init__.py

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

earthsciencekit/volcanology/core/base.py

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

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