earthsciencekit 0.2.0__py3-none-any.whl

earthsciencekit/geophysics/systems/figure.py

@@ -0,0 +1,292 @@
+"""Figure of the Earth: rotational flattening, normal gravity, J2 from satellite orbits and the geoid.
+
+SI units unless stated otherwise; latitude, inclination and spherical distance in radians.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+
+__all__ = [
+    "centrifugal_ratio",
+    "homogeneous_flattening",
+    "clairaut_gravity",
+    "normal_gravity",
+    "flattening_from_j2",
+    "nodal_precession_rate",
+    "stokes_function",
+    "degree_geoid_height",
+]
+
+# GRS80 Somigliana constants: equatorial normal gravity, k = (b gamma_p) / (a gamma_e) - 1 and the first eccentricity squared.
+_GAMMA_E = 9.7803267715
+_SOMIGLIANA_K = 0.001931851353
+_E2 = 0.00669438002290
+
+
+@model
+def centrifugal_ratio(angular_speed, radius, gravity):
+    """Ratio of centrifugal to gravitational acceleration at the equator.
+
+    Rotation flattens a planet in proportion to how strongly it competes with gravity.
+
+    Parameters
+    ----------
+    angular_speed : float or array_like
+        rad/s; constraint: nonnegative.
+    radius : float or array_like
+        m; constraint: positive. Equatorial radius.
+    gravity : float or array_like
+        m/s^2; constraint: positive. Equatorial gravity.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    The geodetic ``m`` uses ``GM / (a b)`` in place of gravity; the two differ at the 0.5% level.
+    Equation: ``angular_speed**2 * radius / gravity``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    angular_speed = quantity("angular_speed", angular_speed, lower=0)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return angular_speed**2 * radius / gravity
+
+
+@model
+def homogeneous_flattening(centrifugal_ratio):
+    """Flattening of a slowly rotating homogeneous fluid planet.
+
+    A uniform self-gravitating fluid in rotation settles into an oblate spheroid.
+
+    Parameters
+    ----------
+    centrifugal_ratio : float or array_like
+        1; constraint: 0 <= value <= 0.1.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]: ``(a - c) / a``.
+
+    Notes
+    -----
+    First order in rotation (Maclaurin spheroid). A centrally condensed Earth is less flattened than this.
+    Equation: ``5 * centrifugal_ratio / 4``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    centrifugal_ratio = quantity("centrifugal_ratio", centrifugal_ratio, lower=0, upper=0.1)
+    return 5 * centrifugal_ratio / 4
+
+
+@model
+def clairaut_gravity(latitude, equatorial_gravity, flattening, centrifugal_ratio):
+    """Gravity on a rotating spheroid from Clairaut's theorem.
+
+    The increase of gravity toward the poles measures the flattening without any surveying.
+
+    Parameters
+    ----------
+    latitude : float or array_like
+        rad; constraint: -pi/2 <= latitude <= pi/2. Geodetic latitude.
+    equatorial_gravity : float or array_like
+        m/s^2; constraint: positive.
+    flattening : float or array_like
+        1; constraint: 0 <= value < 1.
+    centrifugal_ratio : float or array_like
+        1; constraint: nonnegative.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s^2]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    First order in flattening and rotation for a spheroid in hydrostatic equilibrium; the sin^4 term is omitted.
+    Equation: ``equatorial_gravity * (1 + (5 * centrifugal_ratio / 2 - flattening) * np.sin(latitude) ** 2)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    latitude = quantity("latitude", latitude, lower=-np.pi / 2, upper=np.pi / 2)
+    equatorial_gravity = quantity("equatorial_gravity", equatorial_gravity, lower=0, strict_lower=True)
+    flattening = quantity("flattening", flattening, lower=0, upper=1, strict_upper=True)
+    centrifugal_ratio = quantity("centrifugal_ratio", centrifugal_ratio, lower=0)
+    return equatorial_gravity * (1 + (5 * centrifugal_ratio / 2 - flattening) * np.sin(latitude) ** 2)
+
+
+@model
+def normal_gravity(latitude):
+    """Normal gravity on the GRS80 ellipsoid.
+
+    The reference field that gravity anomalies are measured against.
+
+    Parameters
+    ----------
+    latitude : float or array_like
+        rad; constraint: -pi/2 <= latitude <= pi/2. Geodetic latitude.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s^2]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Somigliana's closed form on the ellipsoid surface with the GRS80 constants
+    ``gamma_e = 9.7803267715``, ``k = 0.001931851353`` and ``e2 = 0.00669438002290``; exact for the level ellipsoid.
+    Equation: ``gamma_e * (1 + k * np.sin(latitude) ** 2) / np.sqrt(1 - e2 * np.sin(latitude) ** 2)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    latitude = quantity("latitude", latitude, lower=-np.pi / 2, upper=np.pi / 2)
+    sine_squared = np.sin(latitude) ** 2
+    return _GAMMA_E * (1 + _SOMIGLIANA_K * sine_squared) / np.sqrt(1 - _E2 * sine_squared)
+
+
+@model
+def flattening_from_j2(j2, centrifugal_ratio):
+    """Flattening of a hydrostatic Earth from its J2.
+
+    The oblateness term of the gravity field and the rotation fix the shape of the level surface.
+
+    Parameters
+    ----------
+    j2 : float or array_like
+        1; constraint: real. Unnormalized second zonal harmonic ``-C20``.
+    centrifugal_ratio : float or array_like
+        1; constraint: nonnegative.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    First order in flattening (Clairaut's relation for the external field); second-order terms change ``1/f`` by
+    about 0.1%.
+    Equation: ``3 * j2 / 2 + centrifugal_ratio / 2``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    j2 = quantity("j2", j2)
+    centrifugal_ratio = quantity("centrifugal_ratio", centrifugal_ratio, lower=0)
+    return 3 * j2 / 2 + centrifugal_ratio / 2
+
+
+@model
+def nodal_precession_rate(semi_major_axis, eccentricity, inclination, j2, radius, gravitational_parameter):
+    """Secular regression of a satellite orbit's node.
+
+    The equatorial bulge torques an inclined orbit, so the node drifts at a rate that measures J2.
+
+    Parameters
+    ----------
+    semi_major_axis : float or array_like
+        m; constraint: positive.
+    eccentricity : float or array_like
+        1; constraint: 0 <= value < 1.
+    inclination : float or array_like
+        rad; constraint: 0 <= inclination <= pi.
+    j2 : float or array_like
+        1; constraint: real.
+    radius : float or array_like
+        m; constraint: positive. Equatorial reference radius of J2.
+    gravitational_parameter : float or array_like
+        m^3/s^2; constraint: positive. ``G M`` of the Earth.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [rad/s]: negative (westward) for prograde orbits and positive J2.
+
+    Notes
+    -----
+    First-order secular J2 perturbation, without drag or higher harmonics; perigee must clear the reference radius.
+    Equation: ``-1.5 * n * j2 * (radius / semi_major_axis) ** 2 * np.cos(inclination) / (1 - eccentricity**2) ** 2``
+    with mean motion ``n = np.sqrt(gravitational_parameter / semi_major_axis**3)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    semi_major_axis = quantity("semi_major_axis", semi_major_axis, lower=0, strict_lower=True)
+    eccentricity = quantity("eccentricity", eccentricity, lower=0, upper=1, strict_upper=True)
+    inclination = quantity("inclination", inclination, lower=0, upper=np.pi)
+    j2 = quantity("j2", j2)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    gravitational_parameter = quantity("gravitational_parameter", gravitational_parameter, lower=0, strict_lower=True)
+    require(semi_major_axis * (1 - eccentricity) > radius, "perigee must lie above the reference radius")
+    mean_motion = np.sqrt(gravitational_parameter / semi_major_axis**3)
+    return -1.5 * mean_motion * j2 * (radius / semi_major_axis) ** 2 * np.cos(inclination) / (1 - eccentricity**2) ** 2
+
+
+@model
+def stokes_function(spherical_distance):
+    """Stokes's kernel for the geoid.
+
+    Weighting gravity anomalies over the whole globe by spherical distance gives the geoid height.
+
+    Parameters
+    ----------
+    spherical_distance : float or array_like
+        rad; constraint: 0 < value <= pi.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Spherical approximation with no masses outside the geoid; singular as ``2 / psi`` at zero distance. Its Legendre
+    expansion is ``sum((2 n + 1) / (n - 1) P_n(cos psi), n >= 2)``, so the geoid is
+    ``radius / (4 pi gravity) * integral(anomaly * S dsigma)``.
+    Equation: ``1 / s - 6 * s + 1 - 5 * np.cos(psi) - 3 * np.cos(psi) * np.log(s + s**2)`` with ``s = np.sin(psi / 2)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    psi = quantity("spherical_distance", spherical_distance, lower=0, upper=np.pi, strict_lower=True)
+    s = np.sin(psi / 2)
+    return 1 / s - 6 * s + 1 - 5 * np.cos(psi) - 3 * np.cos(psi) * np.log(s + s**2)
+
+
+@model
+def degree_geoid_height(anomaly_coefficient, degree, radius, gravity):
+    """Geoid height of one spherical-harmonic degree of the gravity anomaly.
+
+    Stokes's integral divides each degree of the anomaly by ``n - 1``, so long wavelengths dominate the geoid.
+
+    Parameters
+    ----------
+    anomaly_coefficient : float or array_like
+        m/s^2; constraint: real. Coefficient of the degree-``n`` surface harmonic of the gravity anomaly.
+    degree : float or array_like
+        1; constraint: integer >= 2.
+    radius : float or array_like
+        m; constraint: positive.
+    gravity : float or array_like
+        m/s^2; constraint: positive. Mean normal gravity.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m]: coefficient of the same surface harmonic in the geoid height.
+
+    Notes
+    -----
+    Spherical approximation of Stokes's formula; degrees 0 and 1 are excluded by construction.
+    Equation: ``radius * anomaly_coefficient / ((degree - 1) * gravity)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    anomaly_coefficient = quantity("anomaly_coefficient", anomaly_coefficient)
+    degree = quantity("degree", degree, lower=2)
+    require(degree == np.round(degree), "degree must be an integer")
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    return radius * anomaly_coefficient / ((degree - 1) * gravity)

earthsciencekit/geophysics/systems/gravity.py

@@ -0,0 +1,235 @@
+"""Gravity: buried masses, the Bouguer and free-air reductions and the weighing of the Earth.
+
+SI units unless stated otherwise.
+"""
+
+import numpy as np
+
+from earthsciencekit._validation import model, quantity, require
+from earthsciencekit.constants import G
+
+__all__ = [
+    "sphere_gravity",
+    "bouguer_correction",
+    "free_air_correction",
+    "bouguer_anomaly",
+    "torsion_balance_gravitational_constant",
+    "earth_mean_density",
+]
+
+
+@model
+def sphere_gravity(x, depth, radius, density_contrast):
+    """Gravitational attraction of a uniform sphere.
+
+    A compact body with excess density pulls a plumb line sideways and adds to gravity above it.
+
+    Parameters
+    ----------
+    x : float or array_like
+        m; constraint: real. Horizontal distance of the observer from the point above the centre.
+    depth : float or array_like
+        m; constraint: real. Depth of the centre below the observer, positive downward.
+    radius : float or array_like
+        m; constraint: positive.
+    density_contrast : float or array_like
+        kg/m^3; constraint: real. Density minus that of the surroundings.
+
+    Returns
+    -------
+    ndarray, shape (..., 2)
+        Model value [m/s^2]: the horizontal component, positive toward increasing ``x``, and the downward component.
+
+    Notes
+    -----
+    The observer must lie outside the sphere, where it attracts as a point mass ``M = 4/3 pi radius**3 density_contrast``.
+    The horizontal component always points toward the centre for positive contrast.
+    Equation: ``G * M * [-x, depth] / (x**2 + depth**2) ** 1.5``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    x = quantity("x", x)
+    depth = quantity("depth", depth)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    density_contrast = quantity("density_contrast", density_contrast)
+    distance_squared = x**2 + depth**2
+    require(distance_squared >= radius**2, "the observer must lie outside the sphere")
+    mass = 4 / 3 * np.pi * radius**3 * density_contrast
+    scale = G * mass / distance_squared**1.5
+    return np.stack(np.broadcast_arrays(-scale * x, scale * depth), axis=-1)
+
+
+@model
+def bouguer_correction(density, thickness):
+    """Attraction of an infinite horizontal slab.
+
+    Rock between the station and the reference level adds gravity that does not depend on the slab's extent.
+
+    Parameters
+    ----------
+    density : float or array_like
+        kg/m^3; constraint: positive.
+    thickness : float or array_like
+        m; constraint: real. Signed station height above the reference level.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s^2]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Flat, uniform, laterally infinite slab; no terrain or curvature correction. About 0.112 mGal per metre at
+    2670 kg/m^3.
+    Equation: ``2 * np.pi * G * density * thickness``.
+    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)
+    thickness = quantity("thickness", thickness)
+    return 2 * np.pi * G * density * thickness
+
+
+@model
+def free_air_correction(height, gravity, radius):
+    """Free-air gravity correction.
+
+    Gravity falls off with distance from the Earth's centre, about 0.3086 mGal per metre at the surface.
+
+    Parameters
+    ----------
+    height : float or array_like
+        m; constraint: real. Station height above the reference surface.
+    gravity : float or array_like
+        m/s^2; constraint: positive. Gravity on the reference surface.
+    radius : float or array_like
+        m; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s^2]: the amount to add to gravity observed at ``height``.
+
+    Notes
+    -----
+    First order in height / radius for a spherical point-mass Earth; no rock between station and reference.
+    Equation: ``2 * gravity * height / radius``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    height = quantity("height", height)
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    return 2 * gravity * height / radius
+
+
+@model
+def bouguer_anomaly(observed_gravity, normal_gravity, height, density, radius):
+    """Simple Bouguer gravity anomaly.
+
+    Removing latitude, height and the rock slab under a station leaves the attraction of buried density contrasts.
+
+    Parameters
+    ----------
+    observed_gravity : float or array_like
+        m/s^2; constraint: positive.
+    normal_gravity : float or array_like
+        m/s^2; constraint: positive. Normal gravity on the reference surface at the station's latitude.
+    height : float or array_like
+        m; constraint: real. Station height above the reference surface.
+    density : float or array_like
+        kg/m^3; constraint: positive. Reduction density of the slab.
+    radius : float or array_like
+        m; constraint: positive.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m/s^2]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Free-air and infinite-slab reductions only, without terrain correction. The free-air anomaly is the same
+    expression without the slab term.
+    Equation: ``observed_gravity - normal_gravity + 2 * normal_gravity * height / radius - 2 * np.pi * G * density * height``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    observed_gravity = quantity("observed_gravity", observed_gravity, lower=0, strict_lower=True)
+    normal_gravity = quantity("normal_gravity", normal_gravity, lower=0, strict_lower=True)
+    height = quantity("height", height)
+    density = quantity("density", density, lower=0, strict_lower=True)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    return observed_gravity - normal_gravity + 2 * normal_gravity * height / radius - 2 * np.pi * G * density * height
+
+
+@model
+def torsion_balance_gravitational_constant(arm_length, separation, deflection, attracting_mass, period):
+    """Gravitational constant from a torsion balance.
+
+    The twist of a suspended rod between large masses, timed by its free swing, measures G.
+
+    Parameters
+    ----------
+    arm_length : float or array_like
+        m; constraint: positive. Distance between the two small balls.
+    separation : float or array_like
+        m; constraint: positive. Centre distance between each small ball and its large ball.
+    deflection : float or array_like
+        rad; constraint: positive. Equilibrium twist of the rod.
+    attracting_mass : float or array_like
+        kg; constraint: positive. Mass of each large ball.
+    period : float or array_like
+        s; constraint: positive. Free oscillation period of the rod.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [m^3/(kg s^2)]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Point masses, a massless rod and attraction by the near large ball only; the small mass cancels.
+    Equation: ``2 * np.pi**2 * arm_length * separation**2 * deflection / (attracting_mass * period**2)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    arm_length = quantity("arm_length", arm_length, lower=0, strict_lower=True)
+    separation = quantity("separation", separation, lower=0, strict_lower=True)
+    deflection = quantity("deflection", deflection, lower=0, strict_lower=True)
+    attracting_mass = quantity("attracting_mass", attracting_mass, lower=0, strict_lower=True)
+    period = quantity("period", period, lower=0, strict_lower=True)
+    return 2 * np.pi**2 * arm_length * separation**2 * deflection / (attracting_mass * period**2)
+
+
+@model
+def earth_mean_density(gravity, radius, gravitational_constant=G):
+    """Mean density of the Earth.
+
+    Surface gravity and the gravitational constant together weigh the Earth.
+
+    Parameters
+    ----------
+    gravity : float or array_like
+        m/s^2; constraint: positive.
+    radius : float or array_like
+        m; constraint: positive.
+    gravitational_constant : float or array_like
+        m^3/(kg s^2); constraint: positive. Defaults to :data:`earthsciencekit.constants.G`.
+
+    Returns
+    -------
+    numpy scalar or ndarray
+        Model value [kg/m^3]. Scalar input returns a NumPy scalar; arrays broadcast.
+
+    Notes
+    -----
+    Spherically symmetric, nonrotating Earth, so ``gravity = G M / radius**2``.
+    Equation: ``3 * gravity / (4 * np.pi * gravitational_constant * radius)``.
+    Invalid, empty, nonreal or nonfinite inputs raise ValueError.
+    NumPy broadcasting applies; singular and overflowing outputs raise ValueError.
+    """
+    gravity = quantity("gravity", gravity, lower=0, strict_lower=True)
+    radius = quantity("radius", radius, lower=0, strict_lower=True)
+    gravitational_constant = quantity("gravitational_constant", gravitational_constant, lower=0, strict_lower=True)
+    return 3 * gravity / (4 * np.pi * gravitational_constant * radius)