earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/geophysics/tests/test_physics.py

@@ -0,0 +1,171 @@
+"""Physical identities, limits and dynamic checks for earthsciencekit.geophysics."""
+
+import numpy as np
+import pytest
+from scipy.integrate import quad
+from scipy.special import eval_legendre
+
+from earthsciencekit.constants import MU0
+from earthsciencekit.geophysics.systems.deformation import equivalent_water_height, love_number_h2, love_number_k2
+from earthsciencekit.geophysics.systems.dynamo import rikitake_fixed_point, simulate_rikitake_dynamo
+from earthsciencekit.geophysics.systems.figure import (
+    centrifugal_ratio,
+    clairaut_gravity,
+    degree_geoid_height,
+    flattening_from_j2,
+    nodal_precession_rate,
+    normal_gravity,
+    stokes_function,
+)
+from earthsciencekit.geophysics.systems.gravity import bouguer_anomaly, bouguer_correction, free_air_correction, sphere_gravity
+from earthsciencekit.geophysics.systems.magnetism import (
+    block_magnetic_anomaly,
+    dipole_field,
+    dipole_inclination,
+    direction_angle,
+    field_elements,
+    paleolatitude,
+    virtual_geomagnetic_pole,
+    zonal_field,
+)
+
+
+@pytest.mark.parametrize(
+    "function,args",
+    [
+        (sphere_gravity, [0.5, 0, 1, 1000]),
+        (nodal_precession_rate, [1.5, 0.5, 0, 1e-3, 1, 1]),
+        (field_elements, [0, 0, 0]),
+        (block_magnetic_anomaly, [0, 1, 1, 1, 2, 1]),
+        (block_magnetic_anomaly, [0, -1, 1, 2, 2, 1]),
+    ],
+)
+def test_cross_parameter_rejections(function, args):
+    with pytest.raises(ValueError):
+        function(*args)
+
+
+def test_sphere_gravity_peak_and_half_width():
+    depth = 1000.0
+    field = sphere_gravity(np.array([-depth * 0.766, 0, depth * 0.766]), depth, 200, 500)
+    assert np.isclose(field[0, 1], field[1, 1] / 2, rtol=1e-3)
+    assert field[0, 0] > 0 > field[2, 0] and field[1, 0] == 0
+
+
+def test_bouguer_anomaly_recovers_buried_body_on_topography():
+    height = np.array([0.0, 250.0, 800.0])
+    radius, density, buried = 6.371e6, 2670.0, 3e-5
+    normal = normal_gravity(0.7)
+    observed = normal - free_air_correction(height, normal, radius) + bouguer_correction(density, height) + buried
+    np.testing.assert_allclose(bouguer_anomaly(observed, normal, height, density, radius), buried, rtol=1e-9)
+
+
+def test_clairaut_matches_somigliana_to_first_order():
+    latitude = np.linspace(0, np.pi / 2, 19)
+    flattening, ratio = 1 / 298.257222101, 0.00344978600308
+    np.testing.assert_allclose(clairaut_gravity(latitude, normal_gravity(0), flattening, ratio), normal_gravity(latitude), rtol=5e-5)
+
+
+def test_satellite_precession_returns_flattening():
+    gm, radius, j2 = 3.986004418e14, 6378137.0, 1.08263e-3
+    rate = nodal_precession_rate(7.3e6, 0.1, np.radians(65.3), j2, radius, gm)
+    recovered = rate / nodal_precession_rate(7.3e6, 0.1, np.radians(65.3), 1, radius, gm)
+    assert np.isclose(recovered, j2)
+    assert nodal_precession_rate(7.3e6, 0, np.pi / 2, j2, radius, gm) == pytest.approx(0, abs=1e-20)
+    ratio = centrifugal_ratio(7.292115e-5, radius, 9.7803267715)
+    assert np.isclose(1 / flattening_from_j2(j2, ratio), 298.257, rtol=2e-3)
+
+
+@pytest.mark.parametrize("degree", [2, 3, 5])
+def test_stokes_integral_of_a_zonal_anomaly(degree):
+    def integrand(psi):
+        return eval_legendre(degree, np.cos(psi)) * stokes_function(psi) * np.sin(psi)
+
+    integral = quad(integrand, 0, np.pi, limit=200)[0] / 2
+    assert np.isclose(integral * 6.371e6 / 9.8, degree_geoid_height(1, degree, 6.371e6, 9.8), rtol=1e-6)
+
+
+def test_dipole_directions_poles_and_paleolatitude():
+    latitude = np.linspace(-1.4, 1.4, 15)
+    field = dipole_field(latitude, 6.371e6, 8e22)
+    elements = field_elements(field[..., 0], 0, field[..., 1])
+    np.testing.assert_allclose(elements[..., 1], dipole_inclination(latitude))
+    np.testing.assert_allclose(paleolatitude(dipole_inclination(latitude)), latitude)
+    poles = dipole_field([np.pi / 2, 0], 6.371e6, 8e22)
+    assert np.isclose(poles[0, 1], 2 * poles[1, 0])
+    pole = virtual_geomagnetic_pole(latitude, 2.0, 0, dipole_inclination(latitude))
+    np.testing.assert_allclose(pole[..., 0], np.pi / 2)
+    reversed_pole = virtual_geomagnetic_pole(0.6, 2.0, np.pi, -dipole_inclination(0.6))
+    assert np.isclose(reversed_pole[0], -np.pi / 2)
+
+
+def test_zonal_dipole_term_is_the_axial_dipole():
+    latitude, distance, g10, a = np.linspace(-1.5, 1.5, 7), 8e6, -29404.8e-9, 6371.2e3
+    moment = -4 * np.pi * a**3 * g10 / MU0
+    np.testing.assert_allclose(zonal_field(latitude, distance, 1, g10, a), dipole_field(latitude, distance, moment), rtol=1e-12)
+    far, near = zonal_field(0.4, [2 * a, a], 3, 1e-6, a)[:, 1]
+    assert np.isclose(far / near, 2.0**-5)
+
+
+def test_vgp_of_a_tilted_dipole_recovers_its_pole():
+    pole_latitude, pole_longitude = np.radians(70), np.radians(300)
+    site_latitude, site_longitude = np.radians([10, 45, -30]), np.radians([20, 100, 250])
+    cos_p = np.sin(site_latitude) * np.sin(pole_latitude) + np.cos(site_latitude) * np.cos(pole_latitude) * np.cos(
+        pole_longitude - site_longitude
+    )
+    p = np.arccos(cos_p)
+    declination = np.arctan2(
+        np.cos(pole_latitude) * np.sin(pole_longitude - site_longitude),
+        np.cos(site_latitude) * np.sin(pole_latitude)
+        - np.sin(site_latitude) * np.cos(pole_latitude) * np.cos(pole_longitude - site_longitude),
+    )
+    inclination = np.arctan(2 / np.tan(p))
+    pole = virtual_geomagnetic_pole(site_latitude, site_longitude, declination, inclination)
+    np.testing.assert_allclose(pole, np.column_stack([np.full(3, pole_latitude), np.full(3, pole_longitude)]))
+
+
+def test_direction_angle_of_a_reversal_is_pi():
+    inclination = dipole_inclination(0.6)
+    assert np.isclose(direction_angle(0, inclination, np.pi, -inclination), np.pi)
+    assert direction_angle(0.3, 0.2, 0.3, 0.2) == 0
+
+
+def test_block_anomaly_superposes_and_cancels_for_a_layer():
+    x = np.linspace(-5e4, 5e4, 11)
+    whole = block_magnetic_anomaly(x, -1e4, 1e4, 2500, 3000, 5)
+    parts = block_magnetic_anomaly(x, -1e4, 0, 2500, 3000, 5) + block_magnetic_anomaly(x, 0, 1e4, 2500, 3000, 5)
+    np.testing.assert_allclose(whole, parts)
+    np.testing.assert_allclose(block_magnetic_anomaly(x, -1e12, 1e12, 2500, 3000, 5), 0, atol=1e-6 * np.abs(whole).max())
+    np.testing.assert_allclose(block_magnetic_anomaly(x, -1e4, 1e4, 2500, 3000, -5), -whole)
+
+
+def test_love_numbers_fluid_and_rigid_limits():
+    assert love_number_k2(0, 5500, 9.8, 6.371e6) == 1.5
+    assert love_number_h2(0, 5500, 9.8, 6.371e6) == 2.5
+    stiff = love_number_k2(1e15, 5500, 9.8, 6.371e6)
+    assert 0 < stiff < 1e-3
+    assert np.isclose(love_number_h2(1e11, 5500, 9.8, 6.371e6), 5 / 3 * love_number_k2(1e11, 5500, 9.8, 6.371e6))
+
+
+def test_equivalent_water_height_is_linear_and_rejects_noninteger_degree():
+    single = equivalent_water_height(1e-10, 10, -0.069, 6.371e6, 5514, 1000)
+    assert np.isclose(equivalent_water_height(3e-10, 10, -0.069, 6.371e6, 5514, 1000), 3 * single)
+    with pytest.raises(ValueError):
+        equivalent_water_height(1e-10, 10.5, -0.069, 6.371e6, 5514, 1000)
+
+
+def test_rikitake_fixed_point_is_steady_and_flow_reverses():
+    mu, k = 1.0, 2.0
+    time = np.linspace(0, 20, 41)
+    steady = simulate_rikitake_dynamo(mu, k, 1.0, time, initial_state=rikitake_fixed_point(mu, k))
+    np.testing.assert_allclose(steady.values, np.broadcast_to(rikitake_fixed_point(mu, k), steady.values.shape), atol=1e-7)
+    mirrored = simulate_rikitake_dynamo(mu, k, 1.0, time, initial_state=-rikitake_fixed_point(mu, k) * [1, 1, -1])
+    np.testing.assert_allclose(mirrored.values[:, :2], -steady.values[:, :2], atol=1e-7)
+    chaotic = simulate_rikitake_dynamo(mu, k, 2.0, np.linspace(0, 400, 2001))
+    assert np.count_nonzero(np.diff(np.sign(chaotic.values[:, 0]))) > 4
+    assert chaotic.names == ("x", "y", "z") and chaotic.units == ("1", "1", "1")
+    for args in [(0, k, 1.0), (mu, k, [1.0, 2.0])]:
+        with pytest.raises(ValueError):
+            simulate_rikitake_dynamo(*args, time)
+    with pytest.raises(ValueError):
+        simulate_rikitake_dynamo(mu, k, 1.0, time, initial_state=[1, 0])

earthsciencekit/geophysics/visualizers/__init__.py

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

@@ -0,0 +1,62 @@
+"""Validated access to SciPy initial-value integration."""
+
+import numpy as np
+from scipy.integrate import solve_ivp
+
+from earthsciencekit._validation import quantity, require
+from earthsciencekit.results import TimeSeries
+
+__all__ = ["integrate_ode"]
+
+
+def integrate_ode(rhs, initial, time, *, names=None, units=None, rtol=1e-8, atol=1e-10, method="RK45"):
+    """Integrate a real initial-value system and retain the requested samples.
+
+    Parameters
+    ----------
+    rhs : callable
+        ``rhs(t, state)`` returns derivatives with the same vector shape as state.
+    initial : array_like, shape (m,)
+        State at the first supplied time, in the units specified by ``units``.
+    time : array_like, shape (n,)
+        Strictly increasing output times in seconds, with at least two samples.
+    names, units : sequence of str or None
+        State labels; defaults are x0, x1, ... and dimensionless unit labels.
+    rtol, atol : float
+        Positive finite scalar solver tolerances; atol uses each state's units.
+    method : str
+        One of RK23, RK45, DOP853, Radau, BDF or LSODA.
+
+    Returns
+    -------
+    TimeSeries
+        Immutable sampled states. Numerical solver errors raise ValueError.
+
+    Notes
+    -----
+    SciPy adapts its internal steps; the output grid is not the integration step.
+    Solver tolerances do not validate a physical model or guarantee conservation.
+    """
+    require(callable(rhs), "rhs must be callable")
+    initial = quantity("initial", initial)
+    time = quantity("time", time)
+    require(initial.ndim == 1, "initial must be a nonempty state vector")
+    require(time.ndim == 1 and time.size >= 2, "time must have at least two samples")
+    require(np.all(np.diff(time) > 0), "time must strictly increase")
+    for name, value in [("rtol", rtol), ("atol", atol)]:
+        tolerance = quantity(name, value, lower=0, strict_lower=True)
+        require(tolerance.ndim == 0, "tolerances must be scalars")
+    require(method in ("RK23", "RK45", "DOP853", "Radau", "BDF", "LSODA"), "unsupported integration method")
+    names = tuple(f"x{i}" for i in range(initial.size)) if names is None else tuple(names)
+    units = tuple("1" for _ in initial) if units is None else tuple(units)
+    # Validate labels before invoking potentially expensive or stateful callbacks.
+    TimeSeries(time, np.broadcast_to(initial, (time.size, initial.size)), names, units)
+
+    def checked_rhs(t, state):
+        derivative = quantity("rhs derivative", rhs(t, state))
+        require(derivative.shape == initial.shape, "rhs must return a matching state vector")
+        return derivative
+
+    solution = solve_ivp(checked_rhs, (time[0], time[-1]), initial, t_eval=time, rtol=rtol, atol=atol, method=method)
+    require(solution.success, f"integration failed: {solution.message}")
+    return TimeSeries(solution.t, solution.y.T, names, units)

earthsciencekit/oceanography/__init__.py

@@ -0,0 +1,61 @@
+"""Inspectable oceanography models; SI units unless stated otherwise."""
+
+from earthsciencekit.oceanography.systems.circulation import (
+    ekman_spiral_velocity,
+    ekman_transport,
+    geostrophic_current,
+    rossby_radius,
+    simulate_thermohaline_boxes,
+    stommel_streamfunction,
+    sverdrup_transport,
+    thermohaline_forcing,
+    volume_transport,
+)
+from earthsciencekit.oceanography.systems.hydrography import (
+    abyssal_temperature,
+    buoyancy_frequency_squared,
+    hydrostatic_pressure,
+    linear_density,
+    simplified_seawater_density,
+)
+from earthsciencekit.oceanography.systems.inertial import (
+    inertial_period,
+    simulate_inertial_current,
+)
+from earthsciencekit.oceanography.systems.waves import (
+    deep_group_speed,
+    deep_wave_speed,
+    gerstner_orbit_radius,
+    internal_wave_speed,
+    reduced_gravity,
+    shallow_wave_speed,
+    tidal_elevation,
+    wave_angular_frequency,
+)
+
+__all__ = [
+    "hydrostatic_pressure",
+    "linear_density",
+    "buoyancy_frequency_squared",
+    "geostrophic_current",
+    "ekman_transport",
+    "inertial_period",
+    "shallow_wave_speed",
+    "deep_wave_speed",
+    "wave_angular_frequency",
+    "deep_group_speed",
+    "rossby_radius",
+    "reduced_gravity",
+    "internal_wave_speed",
+    "volume_transport",
+    "tidal_elevation",
+    "gerstner_orbit_radius",
+    "ekman_spiral_velocity",
+    "sverdrup_transport",
+    "stommel_streamfunction",
+    "thermohaline_forcing",
+    "abyssal_temperature",
+    "simplified_seawater_density",
+    "simulate_inertial_current",
+    "simulate_thermohaline_boxes",
+]

earthsciencekit/oceanography/core/__init__.py

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

earthsciencekit/oceanography/core/base.py

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

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