nrl-tracker 1.9.1__py3-none-any.whl → 1.10.0__py3-none-any.whl

pytcl/gravity/egm.py

@@ -131,6 +131,12 @@ def get_data_dir() -> Path:
     -------
     Path
         Path to the data directory.
+
+    Examples
+    --------
+    >>> data_dir = get_data_dir()
+    >>> str(data_dir).endswith('.pytcl/data') or 'PYTCL_DATA_DIR' in dir()
+    True
     """
     env_dir = os.environ.get("PYTCL_DATA_DIR")
     if env_dir:
@@ -242,6 +248,16 @@ def create_test_coefficients(n_max: int = 36) -> EGMCoefficients:
     -------
     EGMCoefficients
         Test coefficient set.
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> coef.n_max
+    10
+    >>> coef.C[0, 0]  # Central term
+    1.0
+    >>> abs(coef.C[2, 0]) > 0  # J2 term present
+    True
     """
     C = np.zeros((n_max + 1, n_max + 1))
     S = np.zeros((n_max + 1, n_max + 1))
@@ -496,6 +512,16 @@ def geoid_heights(
     -------
     ndarray
         Geoid heights in meters.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> lats = np.array([0.0, np.pi/4])  # Equator and 45°N
+    >>> lons = np.array([0.0, np.pi/2])  # Prime meridian and 90°E
+    >>> heights = geoid_heights(lats, lons, coefficients=coef)
+    >>> len(heights)
+    2
     """
     # Load coefficients once
     if coefficients is None:
@@ -543,6 +569,13 @@ def gravity_disturbance(
     -------
     GravityDisturbance
         Gravity disturbance components.
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> dist = gravity_disturbance(0, 0, h=0, coefficients=coef)
+    >>> isinstance(dist.magnitude, float)
+    True
     """
     if coefficients is None:
         coefficients = load_egm_coefficients(model, n_max)
@@ -613,6 +646,13 @@ def gravity_anomaly(
     -------
     float
         Gravity anomaly in m/s^2 (typically reported in mGal = 1e-5 m/s^2).
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> anomaly = gravity_anomaly(0, 0, h=0, coefficients=coef)
+    >>> isinstance(anomaly, float)
+    True
     """
     disturbance = gravity_disturbance(lat, lon, h, model, n_max, coefficients)
 
@@ -657,6 +697,13 @@ def deflection_of_vertical(
     -----
     Positive xi means the plumb line points more north than the normal.
     Positive eta means the plumb line points more east than the normal.
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> xi, eta = deflection_of_vertical(0, 0, coefficients=coef)
+    >>> isinstance(xi, float) and isinstance(eta, float)
+    True
     """
     if coefficients is None:
         coefficients = load_egm_coefficients(model, n_max)

pytcl/gravity/models.py

@@ -267,6 +267,12 @@ def gravity_j2(
     -------
     result : GravityResult
         Gravity components and magnitude.
+
+    Examples
+    --------
+    >>> result = gravity_j2(0, 0, 0)  # At equator, sea level
+    >>> abs(result.magnitude - 9.78) < 0.01
+    True
     """
     GM = constants.GM
     a = constants.a
@@ -328,6 +334,12 @@ def geoid_height_j2(
     N : float
         Geoid height (geoid - ellipsoid) in meters.
 
+    Examples
+    --------
+    >>> N = geoid_height_j2(0)  # At equator
+    >>> N > 0  # Equator bulges outward
+    True
+
     Notes
     -----
     This is a simplified model. For accurate geoid heights,
@@ -371,6 +383,12 @@ def gravitational_potential(
     -------
     U : float
         Gravitational potential (m^2/s^2).
+
+    Examples
+    --------
+    >>> U = gravitational_potential(0, 0, 6.4e6)  # Near Earth surface
+    >>> U < 0  # Potential is negative
+    True
     """
     GM = constants.GM
     a = constants.a
@@ -415,6 +433,14 @@ def free_air_anomaly(
     delta_g : float
         Free-air anomaly in m/s^2 (or mGal if multiplied by 1e5).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Observed gravity slightly higher than normal
+    >>> delta_g = free_air_anomaly(9.81, np.radians(45), 100)
+    >>> isinstance(delta_g, float)
+    True
+
     Notes
     -----
     The free-air anomaly is the difference between observed gravity
@@ -452,6 +478,14 @@ def bouguer_anomaly(
     delta_g : float
         Bouguer anomaly in m/s^2.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Bouguer anomaly at mountain location
+    >>> delta_g = bouguer_anomaly(9.81, np.radians(45), 1000)
+    >>> isinstance(delta_g, float)
+    True
+
     Notes
     -----
     The Bouguer anomaly removes the gravitational effect of the

pytcl/gravity/spherical_harmonics.py

@@ -157,6 +157,16 @@ def associated_legendre_derivative(
     -------
     dP : ndarray
         Array of shape (n_max+1, m_max+1) containing dP_n^m/dx.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.cos(np.radians(45))  # cos of 45 degrees
+    >>> dP = associated_legendre_derivative(2, 2, x)
+    >>> dP.shape
+    (3, 3)
+    >>> abs(dP[0, 0]) < 1e-10  # dP_0^0/dx = 0
+    True
     """
     if P is None:
         P = associated_legendre(n_max, m_max, x, normalized)
@@ -255,6 +265,18 @@ def spherical_harmonic_sum(
         V = \\frac{GM}{r} \\sum_{n=0}^{N} \\left(\\frac{R}{r}\\right)^n
             \\sum_{m=0}^{n} \\bar{P}_n^m(\\sin\\phi)
             (C_{nm}\\cos m\\lambda + S_{nm}\\sin m\\lambda)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Simple monopole (degree 0 only)
+    >>> C = np.array([[1.0]])
+    >>> S = np.array([[0.0]])
+    >>> R = 6.378e6  # meters
+    >>> GM = 3.986e14  # m^3/s^2
+    >>> V, dV_r, dV_lat = spherical_harmonic_sum(0, 0, R, C, S, R, GM, n_max=0)
+    >>> abs(V - GM/R) / (GM/R) < 1e-10  # V = GM/r for degree 0
+    True
     """
     if n_max is None:
         n_max = C.shape[0] - 1
@@ -382,6 +404,18 @@ def gravity_acceleration(
         Northward component of gravity.
     g_lon : float
         Eastward component of gravity.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Simple monopole field
+    >>> C = np.array([[1.0]])
+    >>> S = np.array([[0.0]])
+    >>> R = 6.378e6
+    >>> GM = 3.986e14
+    >>> g_r, g_lat, g_lon = gravity_acceleration(0, 0, 0, C, S, R, GM, n_max=0)
+    >>> g_r < 0  # Gravity points inward (negative radial)
+    True
     """
     # Approximate radial distance (simplified, ignoring ellipsoid flattening)
     r = R + h
@@ -427,6 +461,18 @@ def legendre_scaling_factors(n_max: int) -> NDArray[np.floating]:
            Clenshaw summation and the recursive computation of very high
            degree and order normalised associated Legendre functions."
            Journal of Geodesy 76.5 (2002): 279-299.
+
+    Examples
+    --------
+    >>> scale = legendre_scaling_factors(100)
+    >>> len(scale)
+    101
+    >>> scale[0]  # No scaling for low degrees
+    1.0
+
+    >>> scale_high = legendre_scaling_factors(200)
+    >>> scale_high[200] < scale_high[0]  # Higher degrees scaled down
+    True
     """
     scale = np.ones(n_max + 1)
 
@@ -480,6 +526,16 @@ def associated_legendre_scaled(
 
     For normal operations (n < 150), scale_exp is all zeros and
     P_scaled equals the actual Legendre values.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.cos(np.radians(45))
+    >>> P_scaled, scale_exp = associated_legendre_scaled(10, 10, x)
+    >>> P_scaled.shape
+    (11, 11)
+    >>> all(scale_exp == 0)  # No scaling needed for n_max < 150
+    True
     """
     if m_max > n_max:
         raise ValueError("m_max must be <= n_max")
@@ -538,6 +594,15 @@ def clear_legendre_cache() -> None:
     Call this function to clear the cached associated Legendre
     polynomial arrays. Useful when memory is constrained or after
     processing a batch with different colatitude values.
+
+    Examples
+    --------
+    >>> _ = associated_legendre(10, 10, 0.5)  # Populate cache
+    >>> info = get_legendre_cache_info()
+    >>> clear_legendre_cache()
+    >>> info_after = get_legendre_cache_info()
+    >>> info_after.currsize
+    0
     """
     _associated_legendre_cached.cache_clear()
     _logger.debug("Legendre polynomial cache cleared")
@@ -550,6 +615,14 @@ def get_legendre_cache_info() -> Any:
     -------
     CacheInfo
         Named tuple with hits, misses, maxsize, currsize.
+
+    Examples
+    --------
+    >>> clear_legendre_cache()  # Start fresh
+    >>> _ = associated_legendre(5, 5, 0.5)
+    >>> info = get_legendre_cache_info()
+    >>> info.currsize >= 1  # At least one entry cached
+    True
     """
     return _associated_legendre_cached.cache_info()
 

pytcl/gravity/tides.py

@@ -142,6 +142,15 @@ def julian_centuries_j2000(mjd: float) -> float:
     -------
     T : float
         Julian centuries since J2000.0.
+
+    Examples
+    --------
+    >>> T = julian_centuries_j2000(51544.5)  # J2000.0 epoch
+    >>> abs(T) < 1e-10  # Should be zero at J2000
+    True
+    >>> T = julian_centuries_j2000(51544.5 + 36525)  # One century later
+    >>> abs(T - 1.0) < 1e-10
+    True
     """
     # J2000.0 = JD 2451545.0 = MJD 51544.5
     return (mjd - 51544.5) / 36525.0
@@ -172,6 +181,14 @@ def fundamental_arguments(T: float) -> Tuple[float, float, float, float, float]:
     Notes
     -----
     Based on IERS Conventions (2010) expressions.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> T = 0.0  # J2000.0
+    >>> l, lp, F, D, Om = fundamental_arguments(T)
+    >>> all(0 <= x < 2*np.pi for x in [l, lp, F, D, Om])  # All in [0, 2pi)
+    True
     """
     # Convert degrees to radians
     deg2rad = np.pi / 180.0
@@ -241,6 +258,15 @@ def moon_position_approximate(mjd: float) -> Tuple[float, float, float]:
     Notes
     -----
     Low-precision formula adequate for tidal computations.
+
+    Examples
+    --------
+    >>> r, lat, lon = moon_position_approximate(58000)
+    >>> 350000e3 < r < 410000e3  # Distance in km range
+    True
+    >>> import numpy as np
+    >>> -np.pi/2 <= lat <= np.pi/2  # Valid latitude
+    True
     """
     T = julian_centuries_j2000(mjd)
 
@@ -313,6 +339,14 @@ def sun_position_approximate(mjd: float) -> Tuple[float, float, float]:
     Notes
     -----
     Low-precision formula adequate for tidal computations.
+
+    Examples
+    --------
+    >>> r, lat, lon = sun_position_approximate(58000)
+    >>> 1.47e11 < r < 1.52e11  # Distance ~1 AU
+    True
+    >>> lat == 0.0  # Sun on ecliptic
+    True
     """
     T = julian_centuries_j2000(mjd)
 

pytcl/mathematical_functions/numerical_integration/quadrature.py

@@ -71,6 +71,14 @@ def gauss_hermite(
     w : ndarray
         Quadrature weights of shape (n,).
 
+    Examples
+    --------
+    >>> x, w = gauss_hermite(5)
+    >>> # Compute E[X^2] for X ~ N(0, 1) (exact = 1)
+    >>> result = np.sum(w * (np.sqrt(2) * x)**2) / np.sqrt(np.pi)
+    >>> abs(result - 1.0) < 1e-10
+    True
+
     Notes
     -----
     For computing E[f(X)] where X ~ N(μ, σ²):
@@ -105,6 +113,13 @@ def gauss_laguerre(
     w : ndarray
         Quadrature weights of shape (n,).
 
+    Examples
+    --------
+    >>> x, w = gauss_laguerre(5)
+    >>> # Integrate x * exp(-x) from 0 to inf (exact = 1)
+    >>> np.sum(w * x)
+    1.0
+
     See Also
     --------
     numpy.polynomial.laguerre.laggauss : Equivalent function.
@@ -137,6 +152,12 @@ def gauss_chebyshev(
     w : ndarray
         Quadrature weights of shape (n,).
 
+    Examples
+    --------
+    >>> x, w = gauss_chebyshev(5, kind=1)
+    >>> x.shape
+    (5,)
+
     See Also
     --------
     numpy.polynomial.chebyshev.chebgauss : Type 1 Chebyshev.
@@ -232,6 +253,13 @@ def dblquad(
     error : float
         Estimate of the absolute error.
 
+    Examples
+    --------
+    >>> # Integrate x*y over unit square
+    >>> result, error = dblquad(lambda y, x: x*y, 0, 1, lambda x: 0, lambda x: 1)
+    >>> result  # Should be 0.25
+    0.25
+
     See Also
     --------
     scipy.integrate.dblquad : Underlying implementation.
@@ -281,6 +309,18 @@ def tplquad(
     error : float
         Estimate of the absolute error.
 
+    Examples
+    --------
+    >>> # Integrate x*y*z over unit cube
+    >>> result, error = tplquad(
+    ...     lambda z, y, x: x*y*z,
+    ...     0, 1,
+    ...     lambda x: 0, lambda x: 1,
+    ...     lambda x, y: 0, lambda x, y: 1
+    ... )
+    >>> abs(result - 0.125) < 1e-6  # 1/8
+    True
+
     See Also
     --------
     scipy.integrate.tplquad : Underlying implementation.
@@ -362,6 +402,13 @@ def romberg(
     result : float
         Estimated integral value.
 
+    Examples
+    --------
+    >>> # Integrate x^2 from 0 to 1 (exact = 1/3)
+    >>> result = romberg(lambda x: x**2, 0, 1)
+    >>> abs(result - 1/3) < 1e-8
+    True
+
     Notes
     -----
     This is a native implementation that does not depend on scipy.integrate.romberg,
@@ -417,6 +464,15 @@ def simpson(
     result : float
         Estimated integral.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.linspace(0, np.pi, 101)
+    >>> y = np.sin(x)
+    >>> result = simpson(y, x)  # Should be ~2.0
+    >>> abs(result - 2.0) < 1e-5
+    True
+
     See Also
     --------
     scipy.integrate.simpson : Underlying implementation.
@@ -446,6 +502,15 @@ def trapezoid(
     result : float
         Estimated integral.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.linspace(0, 1, 11)
+    >>> y = x**2  # Integrate x^2 from 0 to 1
+    >>> result = trapezoid(y, x)
+    >>> abs(result - 1/3) < 0.01  # Approximation
+    True
+
     See Also
     --------
     scipy.integrate.trapezoid : Underlying implementation.
@@ -534,6 +599,16 @@ def spherical_cubature(
     References
     ----------
     Arasaratnam & Haykin, "Cubature Kalman Filters", IEEE TAC, 2009.
+
+    Examples
+    --------
+    >>> points, weights = spherical_cubature(3)
+    >>> points.shape  # 2*n = 6 points in 3D
+    (6, 3)
+    >>> weights.shape
+    (6,)
+    >>> np.sum(weights)  # Weights sum to 1
+    1.0
     """
     # Points at ±√n along each axis
     sqrt_n = np.sqrt(n_dim)
@@ -592,6 +667,16 @@ def unscented_transform_points(
     ----------
     Julier & Uhlmann, "Unscented Filtering and Nonlinear Estimation",
     Proc. IEEE, 2004.
+
+    Examples
+    --------
+    >>> sigma_points, wm, wc = unscented_transform_points(3)
+    >>> sigma_points.shape  # 2*n+1 = 7 points in 3D
+    (7, 3)
+    >>> wm.shape
+    (7,)
+    >>> np.abs(np.sum(wm) - 1.0) < 1e-10  # Mean weights sum to 1
+    True
     """
     if kappa is None:
         kappa = 3.0 - n_dim

pytcl/mathematical_functions/special_functions/bessel.py

@@ -72,6 +72,11 @@ def bessely(
     -----
     Y_n(x) is singular at x = 0.
 
+    Examples
+    --------
+    >>> bessely(0, 1)
+    0.088...
+
     See Also
     --------
     scipy.special.yv : Bessel function of second kind of real order.
@@ -137,6 +142,13 @@ def besselk(
     -----
     K_n(x) is singular at x = 0.
 
+    Examples
+    --------
+    >>> besselk(0, 1)
+    0.421...
+    >>> besselk(1, 2)
+    0.139...
+
     See Also
     --------
     scipy.special.kv : Modified Bessel function of second kind.
@@ -174,6 +186,14 @@ def besselh(
     H^(1)_n(x) = J_n(x) + i*Y_n(x)
     H^(2)_n(x) = J_n(x) - i*Y_n(x)
 
+    Examples
+    --------
+    >>> h = besselh(0, 1, 1)  # H^(1)_0(1)
+    >>> h.real
+    0.765...
+    >>> h.imag
+    0.088...
+
     See Also
     --------
     scipy.special.hankel1 : Hankel function of first kind.
@@ -215,6 +235,13 @@ def spherical_jn(
     -----
     j_n(x) = sqrt(pi / (2*x)) * J_{n+1/2}(x)
 
+    Examples
+    --------
+    >>> spherical_jn(0, 1)  # sin(1)/1
+    0.841...
+    >>> spherical_jn(0, 1, derivative=True)  # Derivative
+    0.301...
+
     See Also
     --------
     scipy.special.spherical_jn : Spherical Bessel function of first kind.
@@ -246,6 +273,11 @@ def spherical_yn(
     y : ndarray
         Values of y_n(x) or y_n'(x).
 
+    Examples
+    --------
+    >>> spherical_yn(0, 1)  # -cos(1)/1
+    -0.540...
+
     See Also
     --------
     scipy.special.spherical_yn : Spherical Bessel function of second kind.
@@ -277,6 +309,11 @@ def spherical_in(
     i : ndarray
         Values of i_n(x) or i_n'(x).
 
+    Examples
+    --------
+    >>> spherical_in(0, 1)  # sinh(1)/1
+    1.175...
+
     See Also
     --------
     scipy.special.spherical_in : Modified spherical Bessel function of first kind.
@@ -308,6 +345,11 @@ def spherical_kn(
     k : ndarray
         Values of k_n(x) or k_n'(x).
 
+    Examples
+    --------
+    >>> spherical_kn(0, 1)  # (pi/2) * exp(-1)
+    0.578...
+
     See Also
     --------
     scipy.special.spherical_kn : Modified spherical Bessel function of second kind.
@@ -344,6 +386,14 @@ def airy(
     Bip : ndarray
         Derivative of Airy function Bi'(x).
 
+    Examples
+    --------
+    >>> Ai, Aip, Bi, Bip = airy(0)
+    >>> Ai
+    0.355...
+    >>> Bi
+    0.614...
+
     See Also
     --------
     scipy.special.airy : Airy functions.
@@ -511,6 +561,11 @@ def struve_l(
     -------
     L : ndarray
         Values of L_n(x).
+
+    Examples
+    --------
+    >>> struve_l(0, 1)
+    0.710...
     """
     return np.asarray(sp.modstruve(n, x), dtype=np.float64)
 

pytcl/mathematical_functions/special_functions/elliptic.py

@@ -61,6 +61,11 @@ def ellipkm1(p: ArrayLike) -> NDArray[np.floating]:
     K : ndarray
         Values of K(1 - p).
 
+    Examples
+    --------
+    >>> ellipkm1(0.1)  # K(0.9)
+    2.578...
+
     See Also
     --------
     scipy.special.ellipkm1 : Elliptic integral near m = 1.
@@ -117,6 +122,12 @@ def ellipeinc(phi: ArrayLike, m: ArrayLike) -> NDArray[np.floating]:
     E : ndarray
         Values of the incomplete elliptic integral of the second kind.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> ellipeinc(np.pi/2, 0)  # Same as ellipe(0) = π/2
+    1.5707...
+
     See Also
     --------
     scipy.special.ellipeinc : Incomplete elliptic integral of second kind.
@@ -142,6 +153,12 @@ def ellipkinc(phi: ArrayLike, m: ArrayLike) -> NDArray[np.floating]:
     F : ndarray
         Values of the incomplete elliptic integral of the first kind.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> ellipkinc(np.pi/2, 0)  # Same as ellipk(0) = π/2
+    1.5707...
+
     See Also
     --------
     scipy.special.ellipkinc : Incomplete elliptic integral of first kind.
@@ -170,6 +187,11 @@ def elliprd(x: ArrayLike, y: ArrayLike, z: ArrayLike) -> NDArray[np.floating]:
     R_D : ndarray
         Values of the Carlson R_D integral.
 
+    Examples
+    --------
+    >>> elliprd(1, 2, 3)
+    0.297...
+
     See Also
     --------
     scipy.special.elliprd : Carlson R_D integral.
@@ -204,6 +226,11 @@ def elliprf(x: ArrayLike, y: ArrayLike, z: ArrayLike) -> NDArray[np.floating]:
     The complete elliptic integral of the first kind is:
     K(m) = R_F(0, 1-m, 1)
 
+    Examples
+    --------
+    >>> elliprf(1, 1, 1)  # R_F(a, a, a) = 1/sqrt(a)
+    1.0
+
     See Also
     --------
     scipy.special.elliprf : Carlson R_F integral.
@@ -236,6 +263,11 @@ def elliprg(x: ArrayLike, y: ArrayLike, z: ArrayLike) -> NDArray[np.floating]:
     The complete elliptic integral of the second kind is:
     E(m) = 2 * R_G(0, 1-m, 1)
 
+    Examples
+    --------
+    >>> elliprg(1, 1, 1)  # R_G(a, a, a) = sqrt(a)
+    1.0
+
     See Also
     --------
     scipy.special.elliprg : Carlson R_G integral.
@@ -272,6 +304,11 @@ def elliprj(
     -----
     The complete elliptic integral of the third kind can be computed using R_J.
 
+    Examples
+    --------
+    >>> elliprj(1, 2, 3, 4)
+    0.213...
+
     See Also
     --------
     scipy.special.elliprj : Carlson R_J integral.
@@ -302,6 +339,11 @@ def elliprc(x: ArrayLike, y: ArrayLike) -> NDArray[np.floating]:
     - R_C(x, y) = arctan(sqrt((x-y)/y)) / sqrt(x-y) for x > y
     - R_C(x, y) = arctanh(sqrt((y-x)/y)) / sqrt(y-x) for x < y
 
+    Examples
+    --------
+    >>> elliprc(1, 1)  # R_C(a, a) = 1/sqrt(a)
+    1.0
+
     See Also
     --------
     scipy.special.elliprc : Carlson R_C integral.