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

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.

pytcl/mathematical_functions/special_functions/error_functions.py

@@ -107,6 +107,13 @@ def erfcx(x: ArrayLike) -> NDArray[np.floating]:
     This function is useful when erfc(x) underflows but the scaled
     version remains representable.
 
+    Examples
+    --------
+    >>> erfcx(0)
+    1.0
+    >>> erfcx(10)  # Remains finite even when erfc(10) underflows
+    0.056...
+
     See Also
     --------
     scipy.special.erfcx : Scaled complementary error function.
@@ -130,6 +137,13 @@ def erfi(x: ArrayLike) -> NDArray[np.floating]:
     y : ndarray
         Values of erfi(x).
 
+    Examples
+    --------
+    >>> erfi(0)
+    0.0
+    >>> erfi(1)
+    1.650...
+
     See Also
     --------
     scipy.special.erfi : Imaginary error function.
@@ -183,6 +197,13 @@ def erfcinv(y: ArrayLike) -> NDArray[np.floating]:
     x : ndarray
         Inverse complementary error function values.
 
+    Examples
+    --------
+    >>> erfcinv(1)
+    0.0
+    >>> erfc(erfcinv(0.5))
+    0.5
+
     See Also
     --------
     scipy.special.erfcinv : Inverse complementary error function.
@@ -211,6 +232,13 @@ def dawsn(x: ArrayLike) -> NDArray[np.floating]:
     Dawson's integral is related to the imaginary error function by:
     F(x) = (√π/2) * exp(-x²) * erfi(x)
 
+    Examples
+    --------
+    >>> dawsn(0)
+    0.0
+    >>> dawsn(1)
+    0.538...
+
     See Also
     --------
     scipy.special.dawsn : Dawson's integral.
@@ -238,6 +266,14 @@ def fresnel(x: ArrayLike) -> tuple[np.ndarray[Any, Any], np.ndarray[Any, Any]]:
     C : ndarray
         Fresnel cosine integral.
 
+    Examples
+    --------
+    >>> S, C = fresnel(1)
+    >>> S
+    0.438...
+    >>> C
+    0.779...
+
     See Also
     --------
     scipy.special.fresnel : Fresnel integrals.
@@ -266,6 +302,14 @@ def wofz(z: ArrayLike) -> NDArray[np.complexfloating]:
     -----
     This function is useful in spectral line modeling and plasma physics.
 
+    Examples
+    --------
+    >>> w = wofz(0)
+    >>> w.real
+    1.0
+    >>> w.imag
+    0.0
+
     See Also
     --------
     scipy.special.wofz : Faddeeva function.
@@ -294,6 +338,11 @@ def voigt_profile(x: ArrayLike, sigma: float, gamma: float) -> NDArray[np.floati
     V : ndarray
         Voigt profile values (normalized to unit area).
 
+    Examples
+    --------
+    >>> voigt_profile(0, 1, 0)  # Pure Gaussian at x=0
+    0.398...
+
     See Also
     --------
     scipy.special.voigt_profile : Voigt profile.