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

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.

pytcl/mathematical_functions/special_functions/gamma_functions.py

@@ -95,6 +95,11 @@ def gammainc(a: ArrayLike, x: ArrayLike) -> NDArray[np.floating]:
     -----
     This is the CDF of the gamma distribution.
 
+    Examples
+    --------
+    >>> gammainc(1, 1)  # 1 - exp(-1)
+    0.632...
+
     See Also
     --------
     scipy.special.gammainc : Regularized lower incomplete gamma function.
@@ -121,6 +126,11 @@ def gammaincc(a: ArrayLike, x: ArrayLike) -> NDArray[np.floating]:
     Q : ndarray
         Values of the regularized upper incomplete gamma function.
 
+    Examples
+    --------
+    >>> gammaincc(1, 1)  # exp(-1)
+    0.367...
+
     See Also
     --------
     scipy.special.gammaincc : Regularized upper incomplete gamma function.
@@ -146,6 +156,11 @@ def gammaincinv(a: ArrayLike, y: ArrayLike) -> NDArray[np.floating]:
     x : ndarray
         Values where P(a, x) = y.
 
+    Examples
+    --------
+    >>> gammaincinv(1, 0.5)  # Median of exponential distribution
+    0.693...
+
     See Also
     --------
     scipy.special.gammaincinv : Inverse of lower incomplete gamma.
@@ -169,6 +184,11 @@ def digamma(x: ArrayLike) -> NDArray[np.floating]:
     ψ : ndarray
         Values of the digamma function.
 
+    Examples
+    --------
+    >>> digamma(1)  # -γ (negative Euler-Mascheroni constant)
+    -0.577...
+
     See Also
     --------
     scipy.special.digamma : Digamma function.
@@ -195,6 +215,13 @@ def polygamma(n: int, x: ArrayLike) -> NDArray[np.floating]:
     ψn : ndarray
         Values of the n-th polygamma function.
 
+    Examples
+    --------
+    >>> polygamma(0, 1)  # Digamma at 1 = -γ
+    -0.577...
+    >>> polygamma(1, 1)  # Trigamma at 1 = π²/6
+    1.644...
+
     See Also
     --------
     scipy.special.polygamma : Polygamma function.
@@ -252,6 +279,12 @@ def betaln(a: ArrayLike, b: ArrayLike) -> NDArray[np.floating]:
     lnB : ndarray
         Values of ln(B(a, b)).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> betaln(100, 100)  # More stable than log(beta(100, 100))
+    -137.74...
+
     See Also
     --------
     scipy.special.betaln : Log of beta function.
@@ -284,6 +317,11 @@ def betainc(a: ArrayLike, b: ArrayLike, x: ArrayLike) -> NDArray[np.floating]:
     -----
     This is the CDF of the beta distribution.
 
+    Examples
+    --------
+    >>> betainc(1, 1, 0.5)  # Uniform distribution CDF at 0.5
+    0.5
+
     See Also
     --------
     scipy.special.betainc : Regularized incomplete beta function.
@@ -311,6 +349,11 @@ def betaincinv(a: ArrayLike, b: ArrayLike, y: ArrayLike) -> NDArray[np.floating]
     x : ndarray
         Values where I_x(a, b) = y.
 
+    Examples
+    --------
+    >>> betaincinv(1, 1, 0.5)  # Median of uniform distribution
+    0.5
+
     See Also
     --------
     scipy.special.betaincinv : Inverse of incomplete beta function.

pytcl/mathematical_functions/special_functions/lambert_w.py

@@ -170,6 +170,11 @@ def wright_omega(z: ArrayLike) -> NDArray[np.complexfloating]:
 
     It is entire (analytic everywhere) unlike the Lambert W function.
 
+    Examples
+    --------
+    >>> wright_omega(0)  # Omega constant
+    (0.5671...+0j)
+
     References
     ----------
     .. [1] Wright, E.M. (1959). "Solution of the equation z*exp(z) = a".

pytcl/mathematical_functions/special_functions/marcum_q.py

@@ -112,6 +112,11 @@ def marcum_q1(
     Q : ndarray
         Values of Q_1(a, b).
 
+    Examples
+    --------
+    >>> marcum_q1(2, 2)
+    0.735...
+
     See Also
     --------
     marcum_q : Generalized Marcum Q function.
@@ -274,6 +279,11 @@ def nuttall_q(
     -----
     This is the probability P(X <= b^2) for X ~ chi^2(2, a^2).
 
+    Examples
+    --------
+    >>> nuttall_q(2, 2)  # 1 - Q_1(2, 2)
+    0.264...
+
     See Also
     --------
     marcum_q : Marcum Q function.
@@ -322,6 +332,12 @@ def swerling_detection_probability(
     For Swerling 1:
         P_d = exp(-threshold / (2 + 2*n*SNR)) * (1 + n*SNR/...)
 
+    Examples
+    --------
+    >>> pd = swerling_detection_probability(10, 1e-6, n_pulses=10, swerling_case=0)
+    >>> pd > 0.9  # High probability of detection with 10 dB SNR
+    True
+
     References
     ----------
     .. [1] Swerling, P. (1960). "Probability of Detection for Fluctuating

pytcl/navigation/geodesy.py

@@ -280,8 +280,17 @@ def geodetic_to_ecef(
     Examples
     --------
     >>> import numpy as np
+    >>> # Philadelphia (40°N, 75°W) at 100m altitude
     >>> lat, lon, alt = np.radians(40.0), np.radians(-75.0), 100.0
     >>> x, y, z = geodetic_to_ecef(lat, lon, alt)
+    >>> x / 1e6  # ~1.2 million meters
+    1.24...
+    >>> # Equator at prime meridian
+    >>> x, y, z = geodetic_to_ecef(0.0, 0.0, 0.0)
+    >>> x  # Semi-major axis (equatorial radius)
+    6378137.0
+    >>> y, z
+    (0.0, 0.0)
     """
     lat = np.asarray(lat, dtype=np.float64)
     lon = np.asarray(lon, dtype=np.float64)
@@ -327,6 +336,19 @@ def ecef_to_geodetic(
     alt : ndarray
         Altitude above ellipsoid in meters.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Point on equator at prime meridian
+    >>> lat, lon, alt = ecef_to_geodetic(6378137.0, 0.0, 0.0)
+    >>> np.degrees(lat), np.degrees(lon), alt
+    (0.0, 0.0, 0.0)
+    >>> # Round-trip conversion
+    >>> x, y, z = geodetic_to_ecef(np.radians(45.0), np.radians(90.0), 1000.0)
+    >>> lat2, lon2, alt2 = ecef_to_geodetic(x, y, z)
+    >>> np.degrees(lat2), np.degrees(lon2), alt2
+    (45.0..., 90.0..., 1000.0...)
+
     Notes
     -----
     Uses Bowring's iterative algorithm for robust conversion.
@@ -409,12 +431,19 @@ def ecef_to_enu(
 
     Examples
     --------
-    >>> # Reference point
+    >>> import numpy as np
+    >>> # Reference point: Philadelphia
     >>> lat_ref, lon_ref, alt_ref = np.radians(40.0), np.radians(-75.0), 0.0
-    >>> # Target point (1 km east)
+    >>> # Target point slightly east
     >>> lat, lon, alt = np.radians(40.0), np.radians(-74.99), 0.0
     >>> x, y, z = geodetic_to_ecef(lat, lon, alt)
     >>> e, n, u = ecef_to_enu(x, y, z, lat_ref, lon_ref, alt_ref)
+    >>> e  # East displacement in meters
+    850...
+    >>> abs(n) < 10  # North displacement should be ~0
+    True
+    >>> abs(u) < 10  # Up displacement should be ~0
+    True
     """
     x = np.asarray(x, dtype=np.float64)
     y = np.asarray(y, dtype=np.float64)
@@ -471,6 +500,18 @@ def enu_to_ecef(
     -------
     x, y, z : ndarray
         ECEF coordinates in meters.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Reference point
+    >>> lat_ref, lon_ref, alt_ref = np.radians(40.0), np.radians(-75.0), 0.0
+    >>> # 1 km east, 500 m north, 100 m up
+    >>> x, y, z = enu_to_ecef(1000.0, 500.0, 100.0, lat_ref, lon_ref, alt_ref)
+    >>> # Convert back to verify
+    >>> e, n, u = ecef_to_enu(x, y, z, lat_ref, lon_ref, alt_ref)
+    >>> e, n, u
+    (1000.0..., 500.0..., 100.0...)
     """
     east = np.asarray(east, dtype=np.float64)
     north = np.asarray(north, dtype=np.float64)
@@ -522,6 +563,17 @@ def ecef_to_ned(
     -------
     north, east, down : ndarray
         NED coordinates in meters relative to reference point.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Reference point
+    >>> lat_ref, lon_ref, alt_ref = np.radians(40.0), np.radians(-75.0), 0.0
+    >>> # Target above reference
+    >>> x, y, z = geodetic_to_ecef(lat_ref, lon_ref, 1000.0)  # 1km above
+    >>> n, e, d = ecef_to_ned(x, y, z, lat_ref, lon_ref, alt_ref)
+    >>> abs(n) < 1, abs(e) < 1, d  # Should be ~0, ~0, -1000
+    (True, True, -1000.0...)
     """
     east, north, up = ecef_to_enu(x, y, z, lat_ref, lon_ref, alt_ref, ellipsoid)
     return north, east, -up
@@ -556,6 +608,17 @@ def ned_to_ecef(
     -------
     x, y, z : ndarray
         ECEF coordinates in meters.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat_ref, lon_ref, alt_ref = np.radians(40.0), np.radians(-75.0), 0.0
+    >>> # 100m north, 50m east, 10m down
+    >>> x, y, z = ned_to_ecef(100.0, 50.0, 10.0, lat_ref, lon_ref, alt_ref)
+    >>> # Verify round-trip
+    >>> n, e, d = ecef_to_ned(x, y, z, lat_ref, lon_ref, alt_ref)
+    >>> n, e, d
+    (100.0..., 50.0..., 10.0...)
     """
     return enu_to_ecef(
         east, north, -np.asarray(down), lat_ref, lon_ref, alt_ref, ellipsoid
@@ -597,6 +660,17 @@ def direct_geodetic(
     azimuth2 : float
         Back azimuth at destination in radians.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # From New York, travel 1000 km northeast
+    >>> lat1, lon1 = np.radians(40.7), np.radians(-74.0)
+    >>> azimuth = np.radians(45)  # Northeast
+    >>> distance = 1_000_000  # 1000 km
+    >>> lat2, lon2, az2 = direct_geodetic(lat1, lon1, azimuth, distance)
+    >>> np.degrees(lat2), np.degrees(lon2)  # Destination
+    (47.0..., -62.6...)
+
     References
     ----------
     .. [1] Vincenty, T., "Direct and Inverse Solutions of Geodesics on the
@@ -647,6 +721,18 @@ def inverse_geodetic(
     azimuth2 : float
         Back azimuth at destination in radians.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Distance from New York to London
+    >>> lat1, lon1 = np.radians(40.7128), np.radians(-74.0060)  # NYC
+    >>> lat2, lon2 = np.radians(51.5074), np.radians(-0.1278)   # London
+    >>> dist, az1, az2 = inverse_geodetic(lat1, lon1, lat2, lon2)
+    >>> dist / 1000  # Distance in km
+    5570...
+    >>> np.degrees(az1)  # Initial heading from NYC
+    51.2...
+
     Notes
     -----
     May fail to converge for nearly antipodal points.
@@ -690,6 +776,19 @@ def haversine_distance(
     float
         Great-circle distance in meters.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Distance from equator to 45°N along prime meridian
+    >>> lat1, lon1 = 0.0, 0.0
+    >>> lat2, lon2 = np.radians(45.0), 0.0
+    >>> dist = haversine_distance(lat1, lon1, lat2, lon2)
+    >>> dist / 1000  # ~5000 km
+    5003...
+    >>> # Same point -> 0 distance
+    >>> haversine_distance(0.0, 0.0, 0.0, 0.0)
+    0.0
+
     Notes
     -----
     This is a spherical approximation. For higher accuracy on an ellipsoid,

pytcl/navigation/great_circle.py

@@ -260,6 +260,14 @@ def great_circle_inverse(
     -------
     GreatCircleResult
         Distance and azimuths.
+
+    Examples
+    --------
+    >>> lat1, lon1 = np.radians(40.7128), np.radians(-74.0060)  # NYC
+    >>> lat2, lon2 = np.radians(51.5074), np.radians(-0.1278)   # London
+    >>> result = great_circle_inverse(lat1, lon1, lat2, lon2)
+    >>> result.distance > 5000000  # Over 5000 km
+    True
     """
     distance = great_circle_distance(lat1, lon1, lat2, lon2, radius)
     azimuth1 = great_circle_azimuth(lat1, lon1, lat2, lon2)
@@ -346,6 +354,14 @@ def great_circle_waypoints(
     -------
     lats, lons : ndarray
         Arrays of waypoint latitudes and longitudes in radians.
+
+    Examples
+    --------
+    >>> lat1, lon1 = 0.0, 0.0
+    >>> lat2, lon2 = np.pi/4, np.pi/4
+    >>> lats, lons = great_circle_waypoints(lat1, lon1, lat2, lon2, 5)
+    >>> len(lats)
+    5
     """
     fractions = np.linspace(0, 1, n_points)
     lats = np.zeros(n_points)
@@ -448,6 +464,16 @@ def cross_track_distance(
     -----
     Positive cross-track means the point is to the right of the path
     (when traveling from start to end).
+
+    Examples
+    --------
+    >>> # Point near a path from origin to northeast
+    >>> lat_pt, lon_pt = np.radians(5), np.radians(2)
+    >>> lat1, lon1 = 0.0, 0.0
+    >>> lat2, lon2 = np.radians(10), np.radians(10)
+    >>> result = cross_track_distance(lat_pt, lon_pt, lat1, lon1, lat2, lon2)
+    >>> abs(result.cross_track) < 500000  # Within 500 km
+    True
     """
     # Angular distance from start to point
     d13 = great_circle_distance(lat1, lon1, lat_point, lon_point, radius=1.0)
@@ -502,6 +528,16 @@ def great_circle_intersect(
     Great circles always intersect at two antipodal points (unless they
     are identical or parallel). The returned points are the intersections
     closest to the given points.
+
+    Examples
+    --------
+    >>> lat1, lon1 = 0.0, 0.0
+    >>> az1 = np.radians(45)  # Northeast
+    >>> lat2, lon2 = 0.0, np.radians(10)
+    >>> az2 = np.radians(315)  # Northwest
+    >>> result = great_circle_intersect(lat1, lon1, az1, lat2, lon2, az2)
+    >>> result.valid
+    True
     """
 
     # Convert to Cartesian unit vectors
@@ -595,6 +631,16 @@ def great_circle_path_intersect(
     -------
     IntersectionResult
         Intersection points and validity.
+
+    Examples
+    --------
+    >>> # Two crossing paths
+    >>> result = great_circle_path_intersect(
+    ...     0.0, 0.0, np.radians(10), np.radians(10),  # Path A
+    ...     0.0, np.radians(10), np.radians(10), 0.0    # Path B
+    ... )
+    >>> result.valid
+    True
     """
     # Get bearings from start points
     az1 = great_circle_azimuth(lat1a, lon1a, lat2a, lon2a)
@@ -783,6 +829,22 @@ def angular_distance(
     -------
     float
         Angular distance in radians.
+
+    Examples
+    --------
+    Compute angular distance between New York and London:
+
+    >>> import numpy as np
+    >>> # NYC: 40.7°N, 74.0°W; London: 51.5°N, 0.1°W
+    >>> lat1, lon1 = np.radians(40.7), np.radians(-74.0)
+    >>> lat2, lon2 = np.radians(51.5), np.radians(-0.1)
+    >>> angle = angular_distance(lat1, lon1, lat2, lon2)
+    >>> np.degrees(angle)  # about 50 degrees
+    49.9...
+
+    See Also
+    --------
+    great_circle_distance : Compute distance on sphere with given radius.
     """
     return great_circle_distance(lat1, lon1, lat2, lon2, radius=1.0)
 
@@ -809,6 +871,15 @@ def destination_point(
     -------
     WaypointResult
         Destination coordinates.
+
+    Examples
+    --------
+    >>> lat, lon = 0.0, 0.0
+    >>> bearing = np.radians(90)  # Due East
+    >>> ang_dist = np.radians(10)  # 10 degrees
+    >>> dest = destination_point(lat, lon, bearing, ang_dist)
+    >>> np.degrees(dest.lon)  # Should be ~10 degrees East
+    10.0
     """
     lat2 = np.arcsin(
         np.sin(lat) * np.cos(angular_distance)