nrl-tracker 0.22.5__py3-none-any.whl → 1.7.5__py3-none-any.whl

pytcl/mathematical_functions/transforms/stft.py

@@ -22,7 +22,7 @@ References
        Speech, and Signal Processing, 32(2), 236-243.
 """
 
-from typing import NamedTuple, Optional, Union
+from typing import Any, NamedTuple, Optional, Union
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
@@ -77,7 +77,7 @@ class Spectrogram(NamedTuple):
 
 
 def get_window(
-    window: Union[str, tuple, ArrayLike],
+    window: Union[str, tuple[str, Any], ArrayLike],
     length: int,
     fftbins: bool = True,
 ) -> NDArray[np.floating]:
@@ -174,7 +174,7 @@ def window_bandwidth(
 def stft(
     x: ArrayLike,
     fs: float = 1.0,
-    window: Union[str, tuple, ArrayLike] = "hann",
+    window: Union[str, tuple[str, Any], ArrayLike] = "hann",
     nperseg: int = 256,
     noverlap: Optional[int] = None,
     nfft: Optional[int] = None,
@@ -264,13 +264,13 @@ def stft(
 def istft(
     Zxx: ArrayLike,
     fs: float = 1.0,
-    window: Union[str, tuple, ArrayLike] = "hann",
+    window: Union[str, tuple[str, Any], ArrayLike] = "hann",
     nperseg: Optional[int] = None,
     noverlap: Optional[int] = None,
     nfft: Optional[int] = None,
     input_onesided: bool = True,
     boundary: bool = True,
-) -> tuple:
+) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
     """
     Compute the inverse Short-Time Fourier Transform.
 
@@ -351,7 +351,7 @@ def istft(
 def spectrogram(
     x: ArrayLike,
     fs: float = 1.0,
-    window: Union[str, tuple, ArrayLike] = "hann",
+    window: Union[str, tuple[str, Any], ArrayLike] = "hann",
     nperseg: int = 256,
     noverlap: Optional[int] = None,
     nfft: Optional[int] = None,
@@ -436,11 +436,11 @@ def spectrogram(
 def reassigned_spectrogram(
     x: ArrayLike,
     fs: float = 1.0,
-    window: Union[str, tuple, ArrayLike] = "hann",
+    window: Union[str, tuple[str, Any], ArrayLike] = "hann",
     nperseg: int = 256,
     noverlap: Optional[int] = None,
     nfft: Optional[int] = None,
-) -> tuple:
+) -> tuple[NDArray[np.floating], NDArray[np.floating], NDArray[np.floating]]:
     """
     Compute reassigned spectrogram for improved time-frequency resolution.
 
@@ -538,7 +538,7 @@ def mel_spectrogram(
     window: str = "hann",
     nperseg: int = 2048,
     noverlap: Optional[int] = None,
-) -> tuple:
+) -> tuple[NDArray[np.floating], NDArray[np.floating], NDArray[np.floating]]:
     """
     Compute mel-scaled spectrogram.
 
@@ -611,15 +611,15 @@ def mel_spectrogram(
     # Mel frequency centers
     mel_freqs = _mel_frequencies(n_mels, fmin, fmax)
 
-    return mel_freqs, spec_result.times, mel_spec
+    return (mel_freqs, spec_result.times, mel_spec)
 
 
-def _hz_to_mel(hz: Union[float, ArrayLike]) -> Union[float, NDArray]:
+def _hz_to_mel(hz: Union[float, ArrayLike]) -> Union[float, NDArray[np.floating]]:
     """Convert frequency in Hz to mel scale."""
     return 2595.0 * np.log10(1.0 + np.asarray(hz) / 700.0)
 
 
-def _mel_to_hz(mel: Union[float, ArrayLike]) -> Union[float, NDArray]:
+def _mel_to_hz(mel: Union[float, ArrayLike]) -> Union[float, NDArray[np.floating]]:
     """Convert mel scale to frequency in Hz."""
     return 700.0 * (10.0 ** (np.asarray(mel) / 2595.0) - 1.0)
 

pytcl/mathematical_functions/transforms/wavelets.py

@@ -20,7 +20,7 @@ References
 .. [2] Daubechies, I. (1992). Ten Lectures on Wavelets. SIAM.
 """
 
-from typing import Callable, List, NamedTuple, Optional, Union
+from typing import Any, Callable, List, NamedTuple, Optional, Union
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
@@ -262,7 +262,7 @@ def gaussian_wavelet(
 def cwt(
     signal: ArrayLike,
     scales: ArrayLike,
-    wavelet: Union[str, Callable[[int], NDArray]] = "morlet",
+    wavelet: Union[str, Callable[[int], NDArray[np.floating]]] = "morlet",
     fs: float = 1.0,
     method: str = "fft",
 ) -> CWTResult:
@@ -312,16 +312,16 @@ def cwt(
     n = len(signal)
 
     # Determine wavelet function
-    def _morlet_default(M: int) -> NDArray:
+    def _morlet_default(M: int) -> NDArray[np.floating]:
         return morlet_wavelet(M, w=5.0)
 
-    def _ricker_default(M: int) -> NDArray:
+    def _ricker_default(M: int) -> NDArray[np.floating]:
         return ricker_wavelet(M, a=1.0)
 
-    def _gaussian1_default(M: int) -> NDArray:
+    def _gaussian1_default(M: int) -> NDArray[np.floating]:
         return gaussian_wavelet(M, order=1)
 
-    def _gaussian2_default(M: int) -> NDArray:
+    def _gaussian2_default(M: int) -> NDArray[np.floating]:
         return gaussian_wavelet(M, order=2)
 
     if callable(wavelet):
@@ -596,7 +596,7 @@ def dwt_single_level(
     signal: ArrayLike,
     wavelet: str = "db4",
     mode: str = "symmetric",
-) -> tuple:
+) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
     """
     Compute single-level DWT decomposition.
 
@@ -673,7 +673,7 @@ def wpt(
     wavelet: str = "db4",
     level: Optional[int] = None,
     mode: str = "symmetric",
-) -> dict:
+) -> dict[str, NDArray[np.floating]]:
     """
     Compute the Wavelet Packet Transform.
 
@@ -748,7 +748,7 @@ def available_wavelets() -> List[str]:
     return pywt.wavelist()
 
 
-def wavelet_info(wavelet: str) -> dict:
+def wavelet_info(wavelet: str) -> dict[str, Any]:
     """
     Get information about a wavelet.
 

pytcl/navigation/geodesy.py

@@ -8,11 +8,20 @@ This module provides geodetic utilities including:
 - Earth ellipsoid parameters
 """
 
-from typing import NamedTuple, Tuple
+import logging
+from functools import lru_cache
+from typing import Any, NamedTuple, Tuple
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
+# Module logger
+_logger = logging.getLogger("pytcl.navigation.geodesy")
+
+# Cache configuration for Vincenty geodetic calculations
+_VINCENTY_CACHE_DECIMALS = 10  # ~0.01mm precision
+_VINCENTY_CACHE_MAXSIZE = 128  # Max cached coordinate pairs
+
 
 class Ellipsoid(NamedTuple):
     """
@@ -51,6 +60,198 @@ GRS80 = Ellipsoid(a=6378137.0, f=1.0 / 298.257222101)
 SPHERE = Ellipsoid(a=6371000.0, f=0.0)
 
 
+def _quantize_geodetic(val: float) -> float:
+    """Quantize geodetic coordinate for cache key compatibility."""
+    return round(val, _VINCENTY_CACHE_DECIMALS)
+
+
+@lru_cache(maxsize=_VINCENTY_CACHE_MAXSIZE)
+def _inverse_geodetic_cached(
+    lat1_q: float,
+    lon1_q: float,
+    lat2_q: float,
+    lon2_q: float,
+    a: float,
+    f: float,
+) -> Tuple[float, float, float]:
+    """Cached Vincenty inverse geodetic computation (internal).
+
+    Returns (distance, azimuth1, azimuth2).
+    """
+    b = a * (1 - f)
+
+    # Reduced latitudes
+    U1 = np.arctan((1 - f) * np.tan(lat1_q))
+    U2 = np.arctan((1 - f) * np.tan(lat2_q))
+    sin_U1, cos_U1 = np.sin(U1), np.cos(U1)
+    sin_U2, cos_U2 = np.sin(U2), np.cos(U2)
+
+    L = lon2_q - lon1_q
+    lam = L
+
+    for _ in range(100):
+        sin_lam = np.sin(lam)
+        cos_lam = np.cos(lam)
+
+        sin_sigma = np.sqrt(
+            (cos_U2 * sin_lam) ** 2 + (cos_U1 * sin_U2 - sin_U1 * cos_U2 * cos_lam) ** 2
+        )
+
+        if sin_sigma == 0:
+            # Coincident points
+            return 0.0, 0.0, 0.0
+
+        cos_sigma = sin_U1 * sin_U2 + cos_U1 * cos_U2 * cos_lam
+        sigma = np.arctan2(sin_sigma, cos_sigma)
+
+        sin_alpha = cos_U1 * cos_U2 * sin_lam / sin_sigma
+        cos2_alpha = 1 - sin_alpha**2
+
+        if cos2_alpha == 0:
+            cos_2sigma_m = 0
+        else:
+            cos_2sigma_m = cos_sigma - 2 * sin_U1 * sin_U2 / cos2_alpha
+
+        C = f / 16 * cos2_alpha * (4 + f * (4 - 3 * cos2_alpha))
+
+        lam_new = L + (1 - C) * f * sin_alpha * (
+            sigma
+            + C
+            * sin_sigma
+            * (cos_2sigma_m + C * cos_sigma * (-1 + 2 * cos_2sigma_m**2))
+        )
+
+        if abs(lam_new - lam) < 1e-12:
+            break
+        lam = lam_new
+
+    u2 = cos2_alpha * (a**2 - b**2) / b**2
+    A = 1 + u2 / 16384 * (4096 + u2 * (-768 + u2 * (320 - 175 * u2)))
+    B = u2 / 1024 * (256 + u2 * (-128 + u2 * (74 - 47 * u2)))
+
+    delta_sigma = (
+        B
+        * sin_sigma
+        * (
+            cos_2sigma_m
+            + B
+            / 4
+            * (
+                cos_sigma * (-1 + 2 * cos_2sigma_m**2)
+                - B
+                / 6
+                * cos_2sigma_m
+                * (-3 + 4 * sin_sigma**2)
+                * (-3 + 4 * cos_2sigma_m**2)
+            )
+        )
+    )
+
+    distance = b * A * (sigma - delta_sigma)
+
+    # Azimuths
+    azimuth1 = np.arctan2(cos_U2 * sin_lam, cos_U1 * sin_U2 - sin_U1 * cos_U2 * cos_lam)
+    azimuth2 = np.arctan2(
+        cos_U1 * sin_lam, -sin_U1 * cos_U2 + cos_U1 * sin_U2 * cos_lam
+    )
+
+    return float(distance), float(azimuth1), float(azimuth2)
+
+
+@lru_cache(maxsize=_VINCENTY_CACHE_MAXSIZE)
+def _direct_geodetic_cached(
+    lat1_q: float,
+    lon1_q: float,
+    azimuth_q: float,
+    distance_q: float,
+    a: float,
+    f: float,
+) -> Tuple[float, float, float]:
+    """Cached Vincenty direct geodetic computation (internal).
+
+    Returns (lat2, lon2, azimuth2).
+    """
+    b = a * (1 - f)
+
+    sin_alpha1 = np.sin(azimuth_q)
+    cos_alpha1 = np.cos(azimuth_q)
+
+    # Reduced latitude
+    tan_U1 = (1 - f) * np.tan(lat1_q)
+    cos_U1 = 1.0 / np.sqrt(1 + tan_U1**2)
+    sin_U1 = tan_U1 * cos_U1
+
+    sigma1 = np.arctan2(tan_U1, cos_alpha1)
+    sin_alpha = cos_U1 * sin_alpha1
+    cos2_alpha = 1 - sin_alpha**2
+
+    u2 = cos2_alpha * (a**2 - b**2) / b**2
+    A = 1 + u2 / 16384 * (4096 + u2 * (-768 + u2 * (320 - 175 * u2)))
+    B = u2 / 1024 * (256 + u2 * (-128 + u2 * (74 - 47 * u2)))
+
+    sigma = distance_q / (b * A)
+
+    for _ in range(100):
+        cos_2sigma_m = np.cos(2 * sigma1 + sigma)
+        sin_sigma = np.sin(sigma)
+        cos_sigma = np.cos(sigma)
+
+        delta_sigma = (
+            B
+            * sin_sigma
+            * (
+                cos_2sigma_m
+                + B
+                / 4
+                * (
+                    cos_sigma * (-1 + 2 * cos_2sigma_m**2)
+                    - B
+                    / 6
+                    * cos_2sigma_m
+                    * (-3 + 4 * sin_sigma**2)
+                    * (-3 + 4 * cos_2sigma_m**2)
+                )
+            )
+        )
+
+        sigma_new = distance_q / (b * A) + delta_sigma
+        if abs(sigma_new - sigma) < 1e-12:
+            break
+        sigma = sigma_new
+
+    cos_2sigma_m = np.cos(2 * sigma1 + sigma)
+    sin_sigma = np.sin(sigma)
+    cos_sigma = np.cos(sigma)
+
+    sin_U2 = sin_U1 * cos_sigma + cos_U1 * sin_sigma * cos_alpha1
+    lat2 = np.arctan2(
+        sin_U2,
+        (1 - f)
+        * np.sqrt(
+            sin_alpha**2 + (sin_U1 * sin_sigma - cos_U1 * cos_sigma * cos_alpha1) ** 2
+        ),
+    )
+
+    lam = np.arctan2(
+        sin_sigma * sin_alpha1, cos_U1 * cos_sigma - sin_U1 * sin_sigma * cos_alpha1
+    )
+
+    C = f / 16 * cos2_alpha * (4 + f * (4 - 3 * cos2_alpha))
+    L = lam - (1 - C) * f * sin_alpha * (
+        sigma
+        + C * sin_sigma * (cos_2sigma_m + C * cos_sigma * (-1 + 2 * cos_2sigma_m**2))
+    )
+
+    lon2 = lon1_q + L
+
+    # Back azimuth
+    azimuth2 = np.arctan2(
+        sin_alpha, -sin_U1 * sin_sigma + cos_U1 * cos_sigma * cos_alpha1
+    )
+
+    return float(lat2), float(lon2), float(azimuth2)
+
+
 def geodetic_to_ecef(
     lat: ArrayLike,
     lon: ArrayLike,
@@ -372,6 +573,7 @@ def direct_geodetic(
     Solve the direct geodetic problem (Vincenty).
 
     Given a starting point, azimuth, and distance, find the destination point.
+    Results are cached for repeated queries with the same parameters.
 
     Parameters
     ----------
@@ -400,88 +602,15 @@ def direct_geodetic(
     .. [1] Vincenty, T., "Direct and Inverse Solutions of Geodesics on the
            Ellipsoid with Application of Nested Equations", Survey Review, 1975.
     """
-    a = ellipsoid.a
-    f = ellipsoid.f
-    b = ellipsoid.b
-
-    sin_alpha1 = np.sin(azimuth)
-    cos_alpha1 = np.cos(azimuth)
-
-    # Reduced latitude
-    tan_U1 = (1 - f) * np.tan(lat1)
-    cos_U1 = 1.0 / np.sqrt(1 + tan_U1**2)
-    sin_U1 = tan_U1 * cos_U1
-
-    sigma1 = np.arctan2(tan_U1, cos_alpha1)
-    sin_alpha = cos_U1 * sin_alpha1
-    cos2_alpha = 1 - sin_alpha**2
-
-    u2 = cos2_alpha * (a**2 - b**2) / b**2
-    A = 1 + u2 / 16384 * (4096 + u2 * (-768 + u2 * (320 - 175 * u2)))
-    B = u2 / 1024 * (256 + u2 * (-128 + u2 * (74 - 47 * u2)))
-
-    sigma = distance / (b * A)
-
-    for _ in range(100):
-        cos_2sigma_m = np.cos(2 * sigma1 + sigma)
-        sin_sigma = np.sin(sigma)
-        cos_sigma = np.cos(sigma)
-
-        delta_sigma = (
-            B
-            * sin_sigma
-            * (
-                cos_2sigma_m
-                + B
-                / 4
-                * (
-                    cos_sigma * (-1 + 2 * cos_2sigma_m**2)
-                    - B
-                    / 6
-                    * cos_2sigma_m
-                    * (-3 + 4 * sin_sigma**2)
-                    * (-3 + 4 * cos_2sigma_m**2)
-                )
-            )
-        )
-
-        sigma_new = distance / (b * A) + delta_sigma
-        if abs(sigma_new - sigma) < 1e-12:
-            break
-        sigma = sigma_new
-
-    cos_2sigma_m = np.cos(2 * sigma1 + sigma)
-    sin_sigma = np.sin(sigma)
-    cos_sigma = np.cos(sigma)
-
-    sin_U2 = sin_U1 * cos_sigma + cos_U1 * sin_sigma * cos_alpha1
-    lat2 = np.arctan2(
-        sin_U2,
-        (1 - f)
-        * np.sqrt(
-            sin_alpha**2 + (sin_U1 * sin_sigma - cos_U1 * cos_sigma * cos_alpha1) ** 2
-        ),
+    return _direct_geodetic_cached(
+        _quantize_geodetic(lat1),
+        _quantize_geodetic(lon1),
+        _quantize_geodetic(azimuth),
+        round(distance, 3),  # 1mm precision for distance
+        ellipsoid.a,
+        ellipsoid.f,
     )
 
-    lam = np.arctan2(
-        sin_sigma * sin_alpha1, cos_U1 * cos_sigma - sin_U1 * sin_sigma * cos_alpha1
-    )
-
-    C = f / 16 * cos2_alpha * (4 + f * (4 - 3 * cos2_alpha))
-    L = lam - (1 - C) * f * sin_alpha * (
-        sigma
-        + C * sin_sigma * (cos_2sigma_m + C * cos_sigma * (-1 + 2 * cos_2sigma_m**2))
-    )
-
-    lon2 = lon1 + L
-
-    # Back azimuth
-    azimuth2 = np.arctan2(
-        sin_alpha, -sin_U1 * sin_sigma + cos_U1 * cos_sigma * cos_alpha1
-    )
-
-    return float(lat2), float(lon2), float(azimuth2)
-
 
 def inverse_geodetic(
     lat1: float,
@@ -494,6 +623,7 @@ def inverse_geodetic(
     Solve the inverse geodetic problem (Vincenty).
 
     Given two points, find the distance and azimuths between them.
+    Results are cached for repeated queries with the same coordinates.
 
     Parameters
     ----------
@@ -526,87 +656,15 @@ def inverse_geodetic(
     .. [1] Vincenty, T., "Direct and Inverse Solutions of Geodesics on the
            Ellipsoid with Application of Nested Equations", Survey Review, 1975.
     """
-    a = ellipsoid.a
-    f = ellipsoid.f
-    b = ellipsoid.b
-
-    # Reduced latitudes
-    U1 = np.arctan((1 - f) * np.tan(lat1))
-    U2 = np.arctan((1 - f) * np.tan(lat2))
-    sin_U1, cos_U1 = np.sin(U1), np.cos(U1)
-    sin_U2, cos_U2 = np.sin(U2), np.cos(U2)
-
-    L = lon2 - lon1
-    lam = L
-
-    for _ in range(100):
-        sin_lam = np.sin(lam)
-        cos_lam = np.cos(lam)
-
-        sin_sigma = np.sqrt(
-            (cos_U2 * sin_lam) ** 2 + (cos_U1 * sin_U2 - sin_U1 * cos_U2 * cos_lam) ** 2
-        )
-
-        if sin_sigma == 0:
-            # Coincident points
-            return 0.0, 0.0, 0.0
-
-        cos_sigma = sin_U1 * sin_U2 + cos_U1 * cos_U2 * cos_lam
-        sigma = np.arctan2(sin_sigma, cos_sigma)
-
-        sin_alpha = cos_U1 * cos_U2 * sin_lam / sin_sigma
-        cos2_alpha = 1 - sin_alpha**2
-
-        if cos2_alpha == 0:
-            cos_2sigma_m = 0
-        else:
-            cos_2sigma_m = cos_sigma - 2 * sin_U1 * sin_U2 / cos2_alpha
-
-        C = f / 16 * cos2_alpha * (4 + f * (4 - 3 * cos2_alpha))
-
-        lam_new = L + (1 - C) * f * sin_alpha * (
-            sigma
-            + C
-            * sin_sigma
-            * (cos_2sigma_m + C * cos_sigma * (-1 + 2 * cos_2sigma_m**2))
-        )
-
-        if abs(lam_new - lam) < 1e-12:
-            break
-        lam = lam_new
-
-    u2 = cos2_alpha * (a**2 - b**2) / b**2
-    A = 1 + u2 / 16384 * (4096 + u2 * (-768 + u2 * (320 - 175 * u2)))
-    B = u2 / 1024 * (256 + u2 * (-128 + u2 * (74 - 47 * u2)))
-
-    delta_sigma = (
-        B
-        * sin_sigma
-        * (
-            cos_2sigma_m
-            + B
-            / 4
-            * (
-                cos_sigma * (-1 + 2 * cos_2sigma_m**2)
-                - B
-                / 6
-                * cos_2sigma_m
-                * (-3 + 4 * sin_sigma**2)
-                * (-3 + 4 * cos_2sigma_m**2)
-            )
-        )
+    return _inverse_geodetic_cached(
+        _quantize_geodetic(lat1),
+        _quantize_geodetic(lon1),
+        _quantize_geodetic(lat2),
+        _quantize_geodetic(lon2),
+        ellipsoid.a,
+        ellipsoid.f,
     )
 
-    distance = b * A * (sigma - delta_sigma)
-
-    # Azimuths
-    azimuth1 = np.arctan2(cos_U2 * sin_lam, cos_U1 * sin_U2 - sin_U1 * cos_U2 * cos_lam)
-    azimuth2 = np.arctan2(
-        cos_U1 * sin_lam, -sin_U1 * cos_U2 + cos_U1 * sin_U2 * cos_lam
-    )
-
-    return float(distance), float(azimuth1), float(azimuth2)
-
 
 def haversine_distance(
     lat1: float,
@@ -646,6 +704,31 @@ def haversine_distance(
     return radius * c
 
 
+def clear_geodesy_cache() -> None:
+    """Clear all geodesy computation caches.
+
+    This can be useful to free memory after processing large datasets
+    or when cache statistics are being monitored.
+    """
+    _inverse_geodetic_cached.cache_clear()
+    _direct_geodetic_cached.cache_clear()
+    _logger.debug("Geodesy caches cleared")
+
+
+def get_geodesy_cache_info() -> dict[str, Any]:
+    """Get cache statistics for geodesy computations.
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary with cache statistics for inverse and direct geodetic caches.
+    """
+    return {
+        "inverse_geodetic": _inverse_geodetic_cached.cache_info()._asdict(),
+        "direct_geodetic": _direct_geodetic_cached.cache_info()._asdict(),
+    }
+
+
 __all__ = [
     # Ellipsoids
     "Ellipsoid",
@@ -663,4 +746,7 @@ __all__ = [
     "direct_geodetic",
     "inverse_geodetic",
     "haversine_distance",
+    # Cache management
+    "clear_geodesy_cache",
+    "get_geodesy_cache_info",
 ]