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

pytcl/astronomical/orbital_mechanics.py

@@ -157,6 +157,12 @@ def mean_to_hyperbolic_anomaly(
     -------
     H : float
         Hyperbolic anomaly (radians).
+
+    Examples
+    --------
+    >>> H = mean_to_hyperbolic_anomaly(1.0, 1.5)
+    >>> abs(1.5 * np.sinh(H) - H - 1.0) < 1e-10
+    True
     """
     if e <= 1:
         raise ValueError(f"Eccentricity must be > 1 for hyperbolic orbits, got {e}")
@@ -196,6 +202,12 @@ def eccentric_to_true_anomaly(E: float, e: float) -> float:
     -------
     nu : float
         True anomaly (radians), in [0, 2*pi).
+
+    Examples
+    --------
+    >>> nu = eccentric_to_true_anomaly(np.pi/4, 0.5)
+    >>> 0 <= nu < 2 * np.pi
+    True
     """
     # Use half-angle formula for numerical stability
     nu = 2 * np.arctan2(np.sqrt(1 + e) * np.sin(E / 2), np.sqrt(1 - e) * np.cos(E / 2))
@@ -217,6 +229,12 @@ def true_to_eccentric_anomaly(nu: float, e: float) -> float:
     -------
     E : float
         Eccentric anomaly (radians), in [0, 2*pi).
+
+    Examples
+    --------
+    >>> E = true_to_eccentric_anomaly(np.pi/3, 0.5)
+    >>> 0 <= E < 2 * np.pi
+    True
     """
     E = 2 * np.arctan2(np.sqrt(1 - e) * np.sin(nu / 2), np.sqrt(1 + e) * np.cos(nu / 2))
     return E % (2 * np.pi)
@@ -237,6 +255,12 @@ def hyperbolic_to_true_anomaly(H: float, e: float) -> float:
     -------
     nu : float
         True anomaly (radians).
+
+    Examples
+    --------
+    >>> nu = hyperbolic_to_true_anomaly(0.5, 1.5)
+    >>> isinstance(nu, float)
+    True
     """
     nu = 2 * np.arctan(np.sqrt((e + 1) / (e - 1)) * np.tanh(H / 2))
     return nu
@@ -277,6 +301,12 @@ def eccentric_to_mean_anomaly(E: float, e: float) -> float:
     -------
     M : float
         Mean anomaly (radians).
+
+    Examples
+    --------
+    >>> M = eccentric_to_mean_anomaly(np.pi/4, 0.5)
+    >>> 0 <= M < 2 * np.pi
+    True
     """
     M = E - e * np.sin(E)
     return M % (2 * np.pi)
@@ -297,6 +327,12 @@ def mean_to_true_anomaly(M: float, e: float) -> float:
     -------
     nu : float
         True anomaly (radians).
+
+    Examples
+    --------
+    >>> nu = mean_to_true_anomaly(np.pi/4, 0.1)
+    >>> 0 <= nu < 2 * np.pi
+    True
     """
     if e < 1:
         E = mean_to_eccentric_anomaly(M, e)
@@ -514,6 +550,12 @@ def orbital_period(a: float, mu: float = GM_EARTH) -> float:
     -------
     T : float
         Orbital period (seconds).
+
+    Examples
+    --------
+    >>> T = orbital_period(7000)  # LEO satellite
+    >>> T / 60  # Convert to minutes  # doctest: +SKIP
+    97.8...
     """
     if a <= 0:
         raise ValueError("Semi-major axis must be positive for elliptic orbits")
@@ -535,6 +577,13 @@ def mean_motion(a: float, mu: float = GM_EARTH) -> float:
     -------
     n : float
         Mean motion (radians/second).
+
+    Examples
+    --------
+    >>> n = mean_motion(42164)  # GEO orbit
+    >>> revs_per_day = n * 86400 / (2 * np.pi)
+    >>> abs(revs_per_day - 1.0) < 0.01  # Approximately 1 rev/day
+    True
     """
     return np.sqrt(mu / abs(a) ** 3)
 
@@ -607,6 +656,15 @@ def kepler_propagate_state(
     -------
     new_state : StateVector
         Propagated state vector.
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])
+    >>> state = StateVector(r=r, v=v)
+    >>> new_state = kepler_propagate_state(state, 3600)
+    >>> np.linalg.norm(new_state.r) > 0
+    True
     """
     elements = state_to_orbital_elements(state, mu)
     new_elements = kepler_propagate(elements, dt, mu)
@@ -630,6 +688,12 @@ def vis_viva(r: float, a: float, mu: float = GM_EARTH) -> float:
     -------
     v : float
         Orbital velocity (km/s).
+
+    Examples
+    --------
+    >>> v = vis_viva(7000, 7000)  # Circular orbit
+    >>> abs(v - circular_velocity(7000)) < 0.01
+    True
     """
     return np.sqrt(mu * (2 / r - 1 / a))
 
@@ -649,6 +713,15 @@ def specific_angular_momentum(
     -------
     h : ndarray
         Specific angular momentum vector (km^2/s).
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])
+    >>> state = StateVector(r=r, v=v)
+    >>> h = specific_angular_momentum(state)
+    >>> h[2]  # Angular momentum in z-direction
+    52500.0
     """
     return np.cross(state.r, state.v)
 
@@ -672,6 +745,15 @@ def specific_orbital_energy(
     energy : float
         Specific orbital energy (km^2/s^2).
         Negative for bound orbits, positive for escape trajectories.
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])
+    >>> state = StateVector(r=r, v=v)
+    >>> energy = specific_orbital_energy(state)
+    >>> energy < 0  # Bound orbit
+    True
     """
     r_mag = np.linalg.norm(state.r)
     v_mag = np.linalg.norm(state.v)
@@ -692,6 +774,15 @@ def flight_path_angle(state: StateVector) -> float:
     gamma : float
         Flight path angle (radians).
         Positive when climbing, negative when descending.
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])  # Tangential velocity
+    >>> state = StateVector(r=r, v=v)
+    >>> gamma = flight_path_angle(state)
+    >>> abs(gamma) < 0.01  # Nearly zero for circular motion
+    True
     """
     r = np.asarray(state.r)
     v = np.asarray(state.v)
@@ -720,6 +811,12 @@ def periapsis_radius(a: float, e: float) -> float:
     -------
     r_p : float
         Periapsis radius (km).
+
+    Examples
+    --------
+    >>> r_p = periapsis_radius(10000, 0.3)
+    >>> r_p
+    7000.0
     """
     return a * (1 - e)
 
@@ -739,6 +836,12 @@ def apoapsis_radius(a: float, e: float) -> float:
     -------
     r_a : float
         Apoapsis radius (km). Infinite for parabolic/hyperbolic orbits.
+
+    Examples
+    --------
+    >>> r_a = apoapsis_radius(10000, 0.3)
+    >>> r_a
+    13000.0
     """
     if e >= 1:
         return np.inf
@@ -769,6 +872,13 @@ def time_since_periapsis(
     -------
     t : float
         Time since periapsis (seconds).
+
+    Examples
+    --------
+    >>> t = time_since_periapsis(np.pi, 7000, 0.1)  # At apoapsis
+    >>> T = orbital_period(7000)
+    >>> abs(t - T/2) < 1  # Approximately half the period
+    True
     """
     M = true_to_mean_anomaly(nu, e)
     n = mean_motion(a, mu)
@@ -792,6 +902,15 @@ def orbit_radius(nu: float, a: float, e: float) -> float:
     -------
     r : float
         Orbital radius (km).
+
+    Examples
+    --------
+    >>> r = orbit_radius(0, 10000, 0.3)  # At periapsis
+    >>> r
+    7000.0
+    >>> r = orbit_radius(np.pi, 10000, 0.3)  # At apoapsis
+    >>> r
+    13000.0
     """
     p = a * (1 - e * e)
     return p / (1 + e * np.cos(nu))
@@ -812,6 +931,12 @@ def escape_velocity(r: float, mu: float = GM_EARTH) -> float:
     -------
     v_esc : float
         Escape velocity (km/s).
+
+    Examples
+    --------
+    >>> v_esc = escape_velocity(6378 + 400)  # At ISS altitude
+    >>> 10 < v_esc < 12  # About 11 km/s
+    True
     """
     return np.sqrt(2 * mu / r)
 
@@ -831,6 +956,12 @@ def circular_velocity(r: float, mu: float = GM_EARTH) -> float:
     -------
     v_circ : float
         Circular velocity (km/s).
+
+    Examples
+    --------
+    >>> v_circ = circular_velocity(6378 + 400)  # At ISS altitude
+    >>> 7 < v_circ < 8  # About 7.7 km/s
+    True
     """
     return np.sqrt(mu / r)
 

pytcl/atmosphere/ionosphere.py

@@ -222,6 +222,15 @@ def dual_frequency_tec(
     tec : ndarray
         Total Electron Content in TECU (10^16 electrons/m²).
 
+    Examples
+    --------
+    >>> # Pseudorange measurements from dual-frequency receiver
+    >>> p_l1 = 22000000.0  # L1 pseudorange in meters
+    >>> p_l2 = 22000002.5  # L2 pseudorange (slightly delayed)
+    >>> tec = dual_frequency_tec(p_l1, p_l2)
+    >>> tec > 0  # TEC should be positive
+    True
+
     Notes
     -----
     The ionospheric delay is proportional to TEC and inversely
@@ -271,6 +280,17 @@ def ionospheric_delay_from_tec(
     delay : ndarray
         Ionospheric delay in meters.
 
+    Examples
+    --------
+    >>> # Typical mid-latitude TEC of 20 TECU
+    >>> delay = ionospheric_delay_from_tec(20.0)
+    >>> delay > 0
+    True
+    >>> # Delay at L2 is larger than at L1 (lower frequency)
+    >>> delay_l2 = ionospheric_delay_from_tec(20.0, frequency=F_L2)
+    >>> delay_l2 > delay
+    True
+
     Notes
     -----
     The ionospheric delay for a signal is:
@@ -410,6 +430,18 @@ def magnetic_latitude(
     -------
     mag_lat : ndarray
         Geomagnetic latitude in radians.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # New York City (40.7°N, 74°W)
+    >>> mag_lat = magnetic_latitude(np.radians(40.7), np.radians(-74))
+    >>> np.degrees(mag_lat)  # doctest: +ELLIPSIS
+    51.4...
+    >>> # Equator at 0° longitude
+    >>> mag_lat_eq = magnetic_latitude(0.0, 0.0)
+    >>> np.abs(np.degrees(mag_lat_eq)) < 15  # Near magnetic equator
+    True
     """
     latitude = np.asarray(latitude, dtype=np.float64)
     longitude = np.asarray(longitude, dtype=np.float64)
@@ -457,6 +489,18 @@ def scintillation_index(
     s4 : ndarray
         S4 amplitude scintillation index (0-1).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Equatorial region at night (high scintillation risk)
+    >>> s4 = scintillation_index(np.radians(10), 21, kp_index=5.0)
+    >>> s4 > 0.3  # Moderate to strong scintillation
+    True
+    >>> # Mid-latitude during daytime (low scintillation)
+    >>> s4_low = scintillation_index(np.radians(45), 12, kp_index=1.0)
+    >>> s4_low < 0.2
+    True
+
     Notes
     -----
     S4 > 0.3 indicates moderate scintillation.

pytcl/atmosphere/models.py

@@ -260,6 +260,16 @@ def altitude_from_pressure(
     altitude : ndarray
         Geometric altitude in meters.
 
+    Examples
+    --------
+    >>> # Sea level pressure
+    >>> altitude_from_pressure(101325)
+    0.0
+    >>> # Pressure at approximately 5000m
+    >>> alt = altitude_from_pressure(54000)
+    >>> 4800 < alt < 5200
+    True
+
     Notes
     -----
     This is an approximate inversion of the ISA model, valid primarily
@@ -292,6 +302,15 @@ def mach_number(
     -------
     mach : ndarray
         Mach number.
+
+    Examples
+    --------
+    >>> # Aircraft at 300 m/s at sea level
+    >>> mach_number(300, 0)  # doctest: +ELLIPSIS
+    0.88...
+    >>> # Same speed at 10 km altitude (lower speed of sound)
+    >>> mach_number(300, 10000)  # doctest: +ELLIPSIS
+    1.00...
     """
     velocity = np.asarray(velocity, dtype=np.float64)
     altitude = np.asarray(altitude, dtype=np.float64)
@@ -318,6 +337,16 @@ def true_airspeed_from_mach(
     -------
     velocity : ndarray
         True airspeed in m/s.
+
+    Examples
+    --------
+    >>> # Mach 0.8 at cruise altitude (10 km)
+    >>> tas = true_airspeed_from_mach(0.8, 10000)
+    >>> 230 < tas < 250  # approximately 240 m/s
+    True
+    >>> # Supersonic at sea level
+    >>> true_airspeed_from_mach(1.0, 0)  # doctest: +ELLIPSIS
+    340.2...
     """
     mach = np.asarray(mach, dtype=np.float64)
     altitude = np.asarray(altitude, dtype=np.float64)

pytcl/clustering/dbscan.py

@@ -76,6 +76,15 @@ def compute_neighbors(
     -------
     neighbors : list of ndarray
         neighbors[i] contains indices of points within eps of point i.
+
+    Examples
+    --------
+    >>> X = np.array([[0.0, 0.0], [0.5, 0.0], [3.0, 0.0]])
+    >>> neighbors = compute_neighbors(X, eps=1.0)
+    >>> 0 in neighbors[1] and 1 in neighbors[0]  # Points 0 and 1 are neighbors
+    True
+    >>> 2 in neighbors[0]  # Point 2 is far from point 0
+    False
     """
     n_samples = X.shape[0]
 

pytcl/clustering/gaussian_mixture.py

@@ -168,6 +168,16 @@ def runnalls_merge_cost(
         cost = 0.5 * [w_m * log|P_m| - w_1 * log|P_1| - w_2 * log|P_2|]
 
     where w_m = w_1 + w_2, P_m is the moment-matched covariance.
+
+    Examples
+    --------
+    >>> c1 = GaussianComponent(0.3, np.array([0., 0.]), np.eye(2) * 0.1)
+    >>> c2 = GaussianComponent(0.2, np.array([0.1, 0.]), np.eye(2) * 0.1)  # Close
+    >>> c3 = GaussianComponent(0.2, np.array([5., 5.]), np.eye(2) * 0.1)  # Far
+    >>> cost_close = runnalls_merge_cost(c1, c2)
+    >>> cost_far = runnalls_merge_cost(c1, c3)
+    >>> cost_close < cost_far  # Closer components have lower merge cost
+    True
     """
     w1, w2 = c1.weight, c2.weight
     w_merged = w1 + w2
@@ -420,6 +430,16 @@ def west_merge_cost(
     -------
     cost : float
         Merge cost based on weighted mean separation.
+
+    Examples
+    --------
+    >>> c1 = GaussianComponent(0.3, np.array([0., 0.]), np.eye(2) * 0.1)
+    >>> c2 = GaussianComponent(0.2, np.array([0.1, 0.]), np.eye(2) * 0.1)  # Close
+    >>> c3 = GaussianComponent(0.2, np.array([5., 5.]), np.eye(2) * 0.1)  # Far
+    >>> cost_close = west_merge_cost(c1, c2)
+    >>> cost_far = west_merge_cost(c1, c3)
+    >>> cost_close < cost_far  # Closer components have lower merge cost
+    True
     """
     w1, w2 = c1.weight, c2.weight
     w_merged = w1 + w2

pytcl/clustering/hierarchical.py

@@ -106,6 +106,15 @@ def compute_distance_matrix(
     -------
     distances : ndarray
         Distance matrix, shape (n_samples, n_samples).
+
+    Examples
+    --------
+    >>> X = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]])
+    >>> D = compute_distance_matrix(X)
+    >>> D.shape
+    (3, 3)
+    >>> D[0, 1]  # Distance between points 0 and 1
+    1.0
     """
     X = np.asarray(X, dtype=np.float64)
     return _compute_distance_matrix_jit(X)
@@ -402,6 +411,16 @@ def cut_dendrogram(
     -------
     labels : ndarray
         Cluster labels, shape (n_samples,).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> rng = np.random.default_rng(42)
+    >>> X = np.vstack([rng.normal(0, 0.5, (10, 2)), rng.normal(3, 0.5, (10, 2))])
+    >>> result = agglomerative_clustering(X)
+    >>> labels = cut_dendrogram(result.linkage_matrix, n_samples=20, n_clusters=2)
+    >>> len(np.unique(labels))
+    2
     """
     linkage_matrix = np.asarray(linkage_matrix)
 
@@ -472,6 +491,16 @@ def fcluster(
     -------
     labels : ndarray
         Cluster labels (1-indexed for scipy compatibility).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> rng = np.random.default_rng(42)
+    >>> X = np.vstack([rng.normal(0, 0.5, (10, 2)), rng.normal(3, 0.5, (10, 2))])
+    >>> result = agglomerative_clustering(X)
+    >>> labels = fcluster(result.linkage_matrix, n_samples=20, t=2, criterion='maxclust')
+    >>> labels.min()  # 1-indexed
+    1
     """
     if criterion == "distance":
         labels = cut_dendrogram(linkage_matrix, n_samples, distance_threshold=t)

pytcl/clustering/kmeans.py

@@ -171,6 +171,15 @@ def update_centers(
     centers : ndarray
         Updated cluster centers, shape (n_clusters, n_features).
         Empty clusters retain their previous position (zeros).
+
+    Examples
+    --------
+    >>> X = np.array([[0, 0], [1, 0], [10, 10], [11, 10]])
+    >>> labels = np.array([0, 0, 1, 1])
+    >>> centers = update_centers(X, labels, n_clusters=2)
+    >>> centers
+    array([[ 0.5,  0. ],
+           [10.5, 10. ]])
     """
     X = np.asarray(X, dtype=np.float64)
     labels = np.asarray(labels, dtype=np.intp)

pytcl/coordinate_systems/conversions/geodetic.py

@@ -295,9 +295,25 @@ def ecef2enu(
     enu : ndarray
         Local ENU coordinates [east, north, up] in meters.
 
+    Examples
+    --------
+    Convert an aircraft position from ECEF to local ENU frame:
+
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems.conversions import ecef2enu, geodetic2ecef
+    >>> # Reference point (airport at 38.9°N, 77.0°W)
+    >>> lat_ref = np.radians(38.9)
+    >>> lon_ref = np.radians(-77.0)
+    >>> # Aircraft ECEF position
+    >>> ecef_aircraft = np.array([1130000.0, -4830000.0, 3990000.0])
+    >>> enu = ecef2enu(ecef_aircraft, lat_ref, lon_ref)
+    >>> enu.shape
+    (3,)
+
     See Also
     --------
     enu2ecef : Inverse conversion.
+    ecef2ned : Convert to NED (North-East-Down) frame.
     """
     ecef = np.asarray(ecef, dtype=np.float64)
 
@@ -355,6 +371,21 @@ def enu2ecef(
     ecef : ndarray
         ECEF coordinates [x, y, z] in meters.
 
+    Examples
+    --------
+    Convert local ENU offset to ECEF coordinates:
+
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems.conversions import enu2ecef
+    >>> # Reference point (airport at 38.9°N, 77.0°W)
+    >>> lat_ref = np.radians(38.9)
+    >>> lon_ref = np.radians(-77.0)
+    >>> # Aircraft 1km east, 2km north, 500m up
+    >>> enu = np.array([1000.0, 2000.0, 500.0])
+    >>> ecef = enu2ecef(enu, lat_ref, lon_ref)
+    >>> ecef.shape
+    (3,)
+
     See Also
     --------
     ecef2enu : Inverse conversion.
@@ -425,6 +456,21 @@ def ecef2ned(
     ned : ndarray
         Local NED coordinates [north, east, down] in meters.
 
+    Examples
+    --------
+    Convert aircraft ECEF position to local NED frame:
+
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems.conversions import ecef2ned, geodetic2ecef
+    >>> # Reference point (airport)
+    >>> lat_ref = np.radians(38.9)
+    >>> lon_ref = np.radians(-77.0)
+    >>> # Aircraft ECEF position
+    >>> ecef_aircraft = np.array([1130000.0, -4830000.0, 3990000.0])
+    >>> ned = ecef2ned(ecef_aircraft, lat_ref, lon_ref)
+    >>> ned.shape  # [north, east, down]
+    (3,)
+
     See Also
     --------
     ned2ecef : Inverse conversion.

pytcl/coordinate_systems/conversions/spherical.py

@@ -264,6 +264,16 @@ def cart2cyl(
     z : ndarray
         Height (same as Cartesian z).
 
+    Examples
+    --------
+    >>> rho, phi, z = cart2cyl([1, 1, 5])
+    >>> rho
+    1.4142135623730951
+    >>> np.degrees(phi)
+    45.0
+    >>> z
+    5.0
+
     See Also
     --------
     cyl2cart : Inverse conversion.
@@ -310,6 +320,12 @@ def cyl2cart(
     cart_points : ndarray
         Cartesian coordinates of shape (3,) or (3, n).
 
+    Examples
+    --------
+    >>> cart = cyl2cart(1.414, np.radians(45), 5.0)
+    >>> cart
+    array([1.00..., 1.00..., 5.  ])
+
     See Also
     --------
     cart2cyl : Inverse conversion.
@@ -354,6 +370,16 @@ def ruv2cart(
     cart_points : ndarray
         Cartesian coordinates.
 
+    Examples
+    --------
+    >>> # Target at 45 deg azimuth, 30 deg elevation, range 100
+    >>> az, el = np.radians(45), np.radians(30)
+    >>> u = np.cos(az) * np.cos(el)
+    >>> v = np.sin(az) * np.cos(el)
+    >>> cart = ruv2cart(100, u, v)
+    >>> cart
+    array([61.23..., 61.23..., 50.  ])
+
     Notes
     -----
     This representation is common in radar tracking systems.
@@ -396,6 +422,15 @@ def cart2ruv(
     v : ndarray
         Direction cosine along y-axis (y/r).
 
+    Examples
+    --------
+    >>> r, u, v = cart2ruv([100, 0, 0])
+    >>> r, u, v
+    (100.0, 1.0, 0.0)
+    >>> r, u, v = cart2ruv([50, 50, 50])
+    >>> r
+    86.602...
+
     See Also
     --------
     ruv2cart : Inverse conversion.