earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/climate/tests/test_physics.py

@@ -0,0 +1,16 @@
+"""Physical identities, limits and dynamic checks for earthsciencekit.climate."""
+
+import numpy as np
+import pytest
+
+from earthsciencekit.climate.systems.response import simulate_one_box, step_temperature
+
+
+def test_one_box_exact_solution_and_nonzero_start():
+    time = np.linspace(10, 20, 51)
+    result = simulate_one_box(4, 2, 2, time, initial_anomaly=-1)
+    np.testing.assert_allclose(result.values[:, 0], 2 - 3 * np.exp(-(time - time[0])), atol=2e-8)
+    zero = simulate_one_box(4, 2, 2, time)
+    np.testing.assert_allclose(zero.values[:, 0], step_temperature(4, 2, 2, time - time[0]), atol=2e-8)
+    with pytest.raises(ValueError):
+        simulate_one_box(4, [2, 3], 2, time)

earthsciencekit/climate/visualizers/__init__.py

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

@@ -0,0 +1,23 @@
+"""Explicit reference constants, not an evolving observational dataset.
+
+SI units apply. Earth angular speed and material properties are educational
+reference values. EPSILON_WATER is the ratio of dry-air to vapor gas constants.
+"""
+
+G = 6.67430e-11  # m^3 kg^-1 s^-2
+MU0 = 1.2566370614359173e-6  # H/m, conventional nonmagnetic approximation
+R_GAS = 8.31446261815324  # J/(mol K)
+AVOGADRO = 6.02214076e23  # 1/mol
+R_DRY_AIR = 287.05  # J/(kg K)
+CP_DRY_AIR = 1004.0  # J/(kg K)
+R_VAPOR = 461.5  # J/(kg K)
+EPSILON_WATER = R_DRY_AIR / R_VAPOR
+OMEGA_EARTH = 7.2921150e-5  # rad/s
+SIGMA_SB = 5.670374419e-8  # W/(m^2 K^4)
+GRAVITY = 9.80665  # m/s^2, standard gravity
+EARTH_RADIUS = 6371008.8  # m, mean radius reference
+SECONDS_PER_YEAR = 365.25 * 86400  # s, Julian year
+LAMBDA_U238 = 1.55125e-10 / SECONDS_PER_YEAR  # 1/s, Jaffey et al. (1971)
+LAMBDA_U235 = 9.8485e-10 / SECONDS_PER_YEAR  # 1/s, Jaffey et al. (1971)
+U238_U235 = 137.88  # 1, present-day atomic ratio, Steiger and Jaeger (1977)
+LIBBY_MEAN_LIFE = 8033 * SECONDS_PER_YEAR  # s, conventional radiocarbon mean life (5568-year half-life)

earthsciencekit/geophysics/__init__.py

@@ -0,0 +1,77 @@
+"""Inspectable geophysics models: gravity, the figure of the Earth and geomagnetism; SI units unless stated otherwise."""
+
+from earthsciencekit.geophysics.systems.deformation import (
+    equivalent_water_height,
+    love_number_h2,
+    love_number_k2,
+    tidal_gravimetric_factor,
+)
+from earthsciencekit.geophysics.systems.dynamo import (
+    magnetic_decay_time,
+    magnetic_reynolds_number,
+    rikitake_fixed_point,
+    simulate_rikitake_dynamo,
+)
+from earthsciencekit.geophysics.systems.figure import (
+    centrifugal_ratio,
+    clairaut_gravity,
+    degree_geoid_height,
+    flattening_from_j2,
+    homogeneous_flattening,
+    nodal_precession_rate,
+    normal_gravity,
+    stokes_function,
+)
+from earthsciencekit.geophysics.systems.gravity import (
+    bouguer_anomaly,
+    bouguer_correction,
+    earth_mean_density,
+    free_air_correction,
+    sphere_gravity,
+    torsion_balance_gravitational_constant,
+)
+from earthsciencekit.geophysics.systems.magnetism import (
+    block_magnetic_anomaly,
+    dipole_field,
+    dipole_inclination,
+    direction_angle,
+    field_elements,
+    gauss_dipole_moment,
+    paleolatitude,
+    virtual_geomagnetic_pole,
+    zonal_field,
+)
+
+__all__ = [
+    "sphere_gravity",
+    "bouguer_correction",
+    "free_air_correction",
+    "bouguer_anomaly",
+    "torsion_balance_gravitational_constant",
+    "earth_mean_density",
+    "centrifugal_ratio",
+    "homogeneous_flattening",
+    "clairaut_gravity",
+    "normal_gravity",
+    "flattening_from_j2",
+    "nodal_precession_rate",
+    "stokes_function",
+    "degree_geoid_height",
+    "dipole_field",
+    "dipole_inclination",
+    "paleolatitude",
+    "zonal_field",
+    "gauss_dipole_moment",
+    "field_elements",
+    "direction_angle",
+    "virtual_geomagnetic_pole",
+    "block_magnetic_anomaly",
+    "magnetic_reynolds_number",
+    "magnetic_decay_time",
+    "rikitake_fixed_point",
+    "love_number_h2",
+    "love_number_k2",
+    "tidal_gravimetric_factor",
+    "equivalent_water_height",
+    "simulate_rikitake_dynamo",
+]

earthsciencekit/geophysics/core/__init__.py

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

earthsciencekit/geophysics/core/base.py

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

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

earthsciencekit/geophysics/systems/deformation.py

@@ -0,0 +1,161 @@
+"""Deformation of the Earth: tidal Love numbers and mass change from time-variable gravity.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+
+__all__ = [
+    "love_number_h2",
+    "love_number_k2",
+    "tidal_gravimetric_factor",
+    "equivalent_water_height",
+]
+
+
+def _rigidity_ratio(rigidity, density, gravity, radius):
+    rigidity = quantity("rigidity", rigidity, lower=0)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    return 19 * rigidity / (2 * density * gravity * radius)
+
+
+@model
+def love_number_h2(rigidity, density, gravity, radius):
+    """Degree-2 displacement Love number of a homogeneous elastic Earth.
+
+    The solid Earth rises and falls with the tide by a fraction of the equilibrium tide that measures its rigidity.
+
+    Parameters
+    ----------
+    rigidity : float or array_like
+        Pa; constraint: nonnegative. Shear modulus; zero gives a fluid Earth.
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+    radius : float or array_like
+        m; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]: radial displacement over the equilibrium tide height.
+
+    Notes
+    -----
+    Uniform, incompressible, self-gravitating elastic sphere (Kelvin's solution); ``h2 = 5 k2 / 3``.
+    Equation: ``2.5 / (1 + 19 * rigidity / (2 * density * gravity * radius))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    return 2.5 / (1 + _rigidity_ratio(rigidity, density, gravity, radius))
+
+
+@model
+def love_number_k2(rigidity, density, gravity, radius):
+    """Degree-2 potential Love number of a homogeneous elastic Earth.
+
+    The tidal bulge adds its own gravitational potential, a fraction k2 of the tidal potential.
+
+    Parameters
+    ----------
+    rigidity : float or array_like
+        Pa; constraint: nonnegative. Shear modulus; zero gives a fluid Earth.
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+    radius : float or array_like
+        m; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Uniform, incompressible, self-gravitating elastic sphere (Kelvin's solution); the fluid limit is 3/2.
+    Equation: ``1.5 / (1 + 19 * rigidity / (2 * density * gravity * radius))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    return 1.5 / (1 + _rigidity_ratio(rigidity, density, gravity, radius))
+
+
+@model
+def tidal_gravimetric_factor(h2, k2):
+    """Gravimetric factor of the body tide.
+
+    A gravimeter on a yielding Earth sees the tide amplified by its uplift and reduced by the bulge's attraction.
+
+    Parameters
+    ----------
+    h2 : float or array_like
+        1; constraint: nonnegative.
+    k2 : float or array_like
+        1; constraint: nonnegative.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]: observed over rigid-Earth tidal gravity change.
+
+    Notes
+    -----
+    Degree-2 tide on a spherically symmetric elastic Earth, without ocean loading. About 1.16 for the real Earth.
+    Equation: ``1 + h2 - 1.5 * k2``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    h2 = quantity("h2", h2, lower=0)
+    k2 = quantity("k2", k2, lower=0)
+    return 1 + h2 - 1.5 * k2
+
+
+@model
+def equivalent_water_height(coefficient_change, degree, load_love_number, radius, mean_density, water_density):
+    """Water layer behind a change of one Stokes coefficient.
+
+    Monthly gravity fields from a satellite pair reveal the moving mass of water, ice and groundwater.
+
+    Parameters
+    ----------
+    coefficient_change : float or array_like
+        1; constraint: real. Change of a fully normalized Stokes coefficient of degree ``n``.
+    degree : float or array_like
+        1; constraint: integer >= 0.
+    load_love_number : float or array_like
+        1; constraint: greater than -1. Elastic yielding ``k'_n`` of the Earth under the load.
+    radius : float or array_like
+        m; constraint: positive.
+    mean_density : float or array_like
+        kg/m^3; constraint: positive. Mean density of the Earth.
+    water_density : float or array_like
+        kg/m^3; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m]: coefficient of the same fully normalized harmonic in the water thickness.
+
+    Notes
+    -----
+    Thin surface layer on an elastic Earth (Wahr et al., 1998); valid while the layer is much thinner than the
+    resolution of the truncated expansion.
+    Equation: ``radius * mean_density * (2 * degree + 1) * coefficient_change / (3 * water_density * (1 + load_love_number))``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    coefficient_change = quantity("coefficient_change", coefficient_change)
+    degree = quantity("degree", degree, lower=0)
+    require(degree == np.round(degree), "degree must be an integer")
+    load_love_number = quantity("load_love_number", load_love_number, lower=-1, strict_lower=True)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    mean_density = quantity("mean_density", mean_density, lower=0, strict_lower=True)
+    water_density = quantity("water_density", water_density, lower=0, strict_lower=True)
+    return radius * mean_density * (2 * degree + 1) * coefficient_change / (3 * water_density * (1 + load_love_number))

earthsciencekit/geophysics/systems/dynamo.py

@@ -0,0 +1,159 @@
+"""Geodynamo: magnetic diffusion, the magnetic Reynolds number and Rikitake's two-disc dynamo.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require, safe_arithmetic
+from earthsciencekit.constants import MU0
+
+__all__ = [
+    "magnetic_reynolds_number",
+    "magnetic_decay_time",
+    "rikitake_fixed_point",
+    "simulate_rikitake_dynamo",
+]
+
+
+@model
+def magnetic_reynolds_number(speed, length, conductivity):
+    """Magnetic Reynolds number.
+
+    A conducting fluid can stretch and regenerate a magnetic field only if advection beats diffusion.
+
+    Parameters
+    ----------
+    speed : float or array_like
+        m/s; constraint: nonnegative.
+    length : float or array_like
+        m; constraint: positive.
+    conductivity : float or array_like
+        S/m; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Order-of-magnitude scale; dynamos need values above a geometry-dependent threshold of order 10 to 100.
+    Equation: ``MU0 * conductivity * speed * length``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    speed = quantity("speed", speed, lower=0)
+    length = quantity("length", length, lower=0, strict_lower=True)
+    conductivity = quantity("conductivity", conductivity, lower=0, strict_lower=True)
+    return MU0 * conductivity * speed * length
+
+
+@model
+def magnetic_decay_time(radius, conductivity):
+    """Free decay time of the slowest magnetic mode of a conducting sphere.
+
+    Without a dynamo the Earth's field would die in tens of thousands of years, far less than its age.
+
+    Parameters
+    ----------
+    radius : float or array_like
+        m; constraint: positive.
+    conductivity : float or array_like
+        S/m; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [s]: e-folding time of the field of the slowest dipole mode.
+
+    Notes
+    -----
+    Uniform stationary conductor surrounded by an insulator.
+    Equation: ``MU0 * conductivity * radius**2 / np.pi**2``.
+    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)
+    conductivity = quantity("conductivity", conductivity, lower=0, strict_lower=True)
+    return MU0 * conductivity * radius**2 / np.pi**2
+
+
+@model
+def rikitake_fixed_point(mu, k):
+    """Steady state of Rikitake's two-disc dynamo.
+
+    The two coupled discs have a pair of steady states of opposite polarity, which the chaotic flow visits in turn.
+
+    Parameters
+    ----------
+    mu : float or array_like
+        1; constraint: positive. Scaled resistance.
+    k : float or array_like
+        1; constraint: positive. Sets ``A = mu * (k**2 - 1 / k**2)``.
+
+    Returns
+    -------
+    ndarray, shape (..., 3)
+        Model value [1]: the scaled currents ``x``, ``y`` and the scaled angular speed ``z`` of the positive state; the
+        other state is ``(-x, -y, z)``.
+
+    Notes
+    -----
+    Nondimensional system of :func:`simulate_rikitake_dynamo`. Both states are unstable for the usual parameters.
+    Equation: ``[k, 1 / k, mu * k**2]``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    mu = quantity("mu", mu, lower=0, strict_lower=True)
+    k = quantity("k", k, lower=0, strict_lower=True)
+    return np.stack(np.broadcast_arrays(k, 1 / k, mu * k**2), axis=-1)
+
+
+@safe_arithmetic
+def simulate_rikitake_dynamo(mu, k, time_scale, time, *, initial_state=(1.0, 0.0, 0.0)):
+    """Integrate Rikitake's coupled two-disc dynamo.
+
+    Parameters
+    ----------
+    mu : float
+        Positive scalar scaled resistance [1].
+    k : float
+        Positive scalar setting the torque asymmetry ``A = mu * (k**2 - 1 / k**2)`` [1].
+    time_scale : float
+        Positive scalar seconds per nondimensional time unit [s].
+    time : array_like
+        Nonnegative strictly increasing sampled times [s].
+    initial_state : sequence of float
+        Scaled currents ``x``, ``y`` and angular speed ``z`` at the first time [1].
+
+    Returns
+    -------
+    TimeSeries
+        The scaled currents ``x`` and ``y`` (whose sign is the polarity) and the scaled angular speed ``z`` [1].
+
+    Notes
+    -----
+    ``dx/dt = -mu * x + y * z``, ``dy/dt = -mu * y + (z - A) * x``, ``dz/dt = 1 - x * y`` in units of ``time_scale``.
+    The steady states are :func:`rikitake_fixed_point`. Trajectories oscillate about one and jump irregularly to the
+    other, reversing both currents: a chaotic analogue of geomagnetic reversals, not a model of the core.
+    """
+    from earthsciencekit._validation import time_grid
+    from earthsciencekit.geophysics.core.base import TimeSeries
+    from earthsciencekit.integrators import integrate_ode
+
+    mu = quantity("mu", mu, lower=0, strict_lower=True)
+    k = quantity("k", k, lower=0, strict_lower=True)
+    time_scale = quantity("time_scale", time_scale, lower=0, strict_lower=True)
+    initial_state = quantity("initial_state", initial_state)
+    require(all(v.ndim == 0 for v in (mu, k, time_scale)), "dynamo parameters must be scalars")
+    require(initial_state.shape == (3,), "initial_state must hold x, y and z")
+    time = time_grid(time)
+    a = mu * (k**2 - 1 / k**2)
+
+    def rhs(t, state):
+        x, y, z = state
+        return [(-mu * x + y * z) / time_scale, (-mu * y + (z - a) * x) / time_scale, (1 - x * y) / time_scale]
+
+    result = integrate_ode(rhs, initial_state, time, names=("x", "y", "z"), units=("1", "1", "1"), method="DOP853", rtol=1e-10)
+    return TimeSeries(result.time, result.values, result.names, result.units)