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

pytcl/gravity/spherical_harmonics.py

@@ -11,11 +11,69 @@ References
 .. [2] O. Montenbruck and E. Gill, "Satellite Orbits," Springer, 2000.
 """
 
-from typing import Optional, Tuple
+import logging
+from functools import lru_cache
+from typing import Any, Optional, Tuple
 
 import numpy as np
 from numpy.typing import NDArray
 
+# Module logger
+_logger = logging.getLogger("pytcl.gravity.spherical_harmonics")
+
+# Cache configuration for Legendre polynomials
+_LEGENDRE_CACHE_DECIMALS = 8  # Precision for x quantization
+_LEGENDRE_CACHE_MAXSIZE = 64  # Max cached (n_max, m_max, x) combinations
+
+
+def _quantize_x(x: float) -> float:
+    """Quantize x value for cache key compatibility."""
+    return round(x, _LEGENDRE_CACHE_DECIMALS)
+
+
+@lru_cache(maxsize=_LEGENDRE_CACHE_MAXSIZE)
+def _associated_legendre_cached(
+    n_max: int,
+    m_max: int,
+    x_quantized: float,
+    normalized: bool,
+) -> tuple[tuple[np.ndarray[Any, Any], ...], ...]:
+    """Cached Legendre polynomial computation (internal).
+
+    Returns tuple of tuples for hashability.
+    """
+    P = np.zeros((n_max + 1, m_max + 1))
+    u = np.sqrt(1 - x_quantized * x_quantized)
+
+    P[0, 0] = 1.0
+
+    for m in range(1, m_max + 1):
+        if normalized:
+            P[m, m] = u * np.sqrt((2 * m + 1) / (2 * m)) * P[m - 1, m - 1]
+        else:
+            P[m, m] = (2 * m - 1) * u * P[m - 1, m - 1]
+
+    for m in range(m_max):
+        if m + 1 <= n_max:
+            if normalized:
+                P[m + 1, m] = x_quantized * np.sqrt(2 * m + 3) * P[m, m]
+            else:
+                P[m + 1, m] = x_quantized * (2 * m + 1) * P[m, m]
+
+    for m in range(m_max + 1):
+        for n in range(m + 2, n_max + 1):
+            if normalized:
+                a_nm = np.sqrt((4 * n * n - 1) / (n * n - m * m))
+                b_nm = np.sqrt(((n - 1) ** 2 - m * m) / (4 * (n - 1) ** 2 - 1))
+                P[n, m] = a_nm * (x_quantized * P[n - 1, m] - b_nm * P[n - 2, m])
+            else:
+                P[n, m] = (
+                    (2 * n - 1) * x_quantized * P[n - 1, m] - (n + m - 1) * P[n - 2, m]
+                ) / (n - m)
+
+    # Convert to tuple of tuples for hashability
+    return tuple(tuple(row) for row in P)
+
 
 def associated_legendre(
     n_max: int,
@@ -53,6 +111,9 @@ def associated_legendre(
 
         \\int_{-1}^{1} [\\bar{P}_n^m(x)]^2 dx = \\frac{2}{2n+1}
 
+    Results are cached for repeated queries with the same parameters.
+    Cache key quantizes x to 8 decimal places (~1e-8 precision).
+
     Examples
     --------
     >>> P = associated_legendre(2, 2, 0.5)
@@ -63,42 +124,10 @@ def associated_legendre(
     if not -1 <= x <= 1:
         raise ValueError("x must be in [-1, 1]")
 
-    P = np.zeros((n_max + 1, m_max + 1))
-
-    # Compute sqrt(1 - x^2) = sin(theta) for colatitude
-    u = np.sqrt(1 - x * x)
-
-    # Seed values
-    P[0, 0] = 1.0
-
-    # Sectoral recursion: P_m^m from P_{m-1}^{m-1}
-    for m in range(1, m_max + 1):
-        if normalized:
-            P[m, m] = u * np.sqrt((2 * m + 1) / (2 * m)) * P[m - 1, m - 1]
-        else:
-            P[m, m] = (2 * m - 1) * u * P[m - 1, m - 1]
-
-    # Compute P_{m+1}^m from P_m^m
-    for m in range(m_max):
-        if m + 1 <= n_max:
-            if normalized:
-                P[m + 1, m] = x * np.sqrt(2 * m + 3) * P[m, m]
-            else:
-                P[m + 1, m] = x * (2 * m + 1) * P[m, m]
-
-    # General recursion: P_n^m from P_{n-1}^m and P_{n-2}^m
-    for m in range(m_max + 1):
-        for n in range(m + 2, n_max + 1):
-            if normalized:
-                a_nm = np.sqrt((4 * n * n - 1) / (n * n - m * m))
-                b_nm = np.sqrt(((n - 1) ** 2 - m * m) / (4 * (n - 1) ** 2 - 1))
-                P[n, m] = a_nm * (x * P[n - 1, m] - b_nm * P[n - 2, m])
-            else:
-                P[n, m] = (
-                    (2 * n - 1) * x * P[n - 1, m] - (n + m - 1) * P[n - 2, m]
-                ) / (n - m)
-
-    return P
+    # Use cached computation
+    x_q = _quantize_x(x)
+    cached = _associated_legendre_cached(n_max, m_max, x_q, normalized)
+    return np.array(cached)
 
 
 def associated_legendre_derivative(
@@ -230,6 +259,14 @@ def spherical_harmonic_sum(
     if n_max is None:
         n_max = C.shape[0] - 1
 
+    _logger.debug(
+        "spherical_harmonic_sum: lat=%.4f, lon=%.4f, r=%.1f, n_max=%d",
+        lat,
+        lon,
+        r,
+        n_max,
+    )
+
     # Colatitude for Legendre polynomials
     colat = np.pi / 2 - lat
     cos_colat = np.cos(colat)
@@ -495,6 +532,28 @@ def associated_legendre_scaled(
     return P_scaled, scale_exp
 
 
+def clear_legendre_cache() -> None:
+    """Clear cached Legendre polynomial results.
+
+    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.
+    """
+    _associated_legendre_cached.cache_clear()
+    _logger.debug("Legendre polynomial cache cleared")
+
+
+def get_legendre_cache_info() -> Any:
+    """Get cache statistics for Legendre polynomials.
+
+    Returns
+    -------
+    CacheInfo
+        Named tuple with hits, misses, maxsize, currsize.
+    """
+    return _associated_legendre_cached.cache_info()
+
+
 __all__ = [
     "associated_legendre",
     "associated_legendre_derivative",
@@ -502,4 +561,6 @@ __all__ = [
     "gravity_acceleration",
     "legendre_scaling_factors",
     "associated_legendre_scaled",
+    "clear_legendre_cache",
+    "get_legendre_cache_info",
 ]

pytcl/gravity/tides.py

@@ -77,9 +77,9 @@ class OceanTideLoading(NamedTuple):
         Names of tidal constituents.
     """
 
-    amplitude: NDArray
-    phase: NDArray
-    constituents: Tuple[str, ...]
+    amplitude: NDArray[np.floating]
+    phase: NDArray[np.floating]
+    constituents: tuple[str, ...]
 
 
 # Love and Shida numbers for degree 2 (IERS 2010)
@@ -593,9 +593,9 @@ def solid_earth_tide_gravity(
 
 def ocean_tide_loading_displacement(
     mjd: float,
-    amplitude: NDArray,
-    phase: NDArray,
-    constituents: Tuple[str, ...] = ("M2", "S2", "N2", "K2", "K1", "O1", "P1", "Q1"),
+    amplitude: NDArray[np.floating],
+    phase: NDArray[np.floating],
+    constituents: tuple[str, ...] = ("M2", "S2", "N2", "K2", "K1", "O1", "P1", "Q1"),
 ) -> TidalDisplacement:
     """
     Compute ocean tide loading displacement.

pytcl/logging_config.py

@@ -0,0 +1,328 @@
+"""
+Hierarchical logging configuration for pyTCL.
+
+Provides:
+- Hierarchical loggers (pytcl.estimation, pytcl.assignment, etc.)
+- Performance instrumentation decorators
+- Context managers for timing critical sections
+- Configurable output formats and levels
+
+Usage
+-----
+>>> from pytcl.logging_config import get_logger, timed, TimingContext
+>>> logger = get_logger(__name__)
+>>> logger.debug("Processing measurement batch")
+
+>>> @timed(logger, "kf_predict")
+... def kf_predict(x, P, F, Q):
+...     ...
+
+>>> with TimingContext(logger, "update_loop"):
+...     for _ in range(100):
+...         do_update()
+"""
+
+import functools
+import logging
+import time
+from contextlib import contextmanager
+from typing import Any, Callable, Generator, Optional, TypeVar
+
+# Type variable for decorated functions
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+# =============================================================================
+# Logger Configuration
+# =============================================================================
+
+# Root logger for pytcl namespace
+PYTCL_LOGGER = "pytcl"
+
+# Sub-loggers for major components
+LOGGER_HIERARCHY = {
+    "pytcl.estimation": "Dynamic estimation algorithms (Kalman, IMM, particle)",
+    "pytcl.assignment": "Assignment and data association (gating, JPDA, MHT)",
+    "pytcl.signal": "Signal processing functions (CFAR, matched filter)",
+    "pytcl.coordinate": "Coordinate system operations (rotations, conversions)",
+    "pytcl.containers": "Data containers and structures (TrackList, KDTree)",
+    "pytcl.math": "Mathematical functions (special functions, transforms)",
+    "pytcl.perf": "Performance instrumentation and timing",
+}
+
+# Default format strings
+FORMATS = {
+    "detailed": (
+        "%(asctime)s - %(name)s - %(levelname)s - "
+        "%(funcName)s:%(lineno)d - %(message)s"
+    ),
+    "simple": "%(name)s - %(levelname)s - %(message)s",
+    "performance": "%(asctime)s - PERF - %(name)s - %(message)s",
+    "minimal": "%(levelname)s: %(message)s",
+}
+
+
+def configure_logging(
+    level: int = logging.WARNING,
+    format_style: str = "simple",
+    handler: Optional[logging.Handler] = None,
+) -> logging.Logger:
+    """
+    Configure the pytcl logging hierarchy.
+
+    Parameters
+    ----------
+    level : int
+        Logging level (e.g., logging.DEBUG, logging.INFO).
+    format_style : str
+        One of 'detailed', 'simple', 'performance', 'minimal'.
+    handler : logging.Handler, optional
+        Custom handler. If None, uses StreamHandler.
+
+    Returns
+    -------
+    logging.Logger
+        The root pytcl logger.
+
+    Examples
+    --------
+    >>> import logging
+    >>> from pytcl.logging_config import configure_logging
+    >>> configure_logging(level=logging.DEBUG, format_style="detailed")
+    """
+    root = logging.getLogger(PYTCL_LOGGER)
+    root.setLevel(level)
+
+    # Clear existing handlers
+    root.handlers.clear()
+
+    # Create handler if not provided
+    if handler is None:
+        handler = logging.StreamHandler()
+
+    # Set format
+    fmt = FORMATS.get(format_style, FORMATS["simple"])
+    formatter = logging.Formatter(fmt)
+    handler.setFormatter(formatter)
+    handler.setLevel(level)
+
+    root.addHandler(handler)
+
+    return root
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger in the pytcl hierarchy.
+
+    Parameters
+    ----------
+    name : str
+        Logger name. If starts with 'pytcl.', used as-is.
+        Otherwise, 'pytcl.' is prepended.
+
+    Returns
+    -------
+    logging.Logger
+        Logger instance.
+
+    Examples
+    --------
+    >>> logger = get_logger("dynamic_estimation.kalman")
+    >>> logger.name
+    'pytcl.dynamic_estimation.kalman'
+    """
+    if not name.startswith(PYTCL_LOGGER):
+        name = f"{PYTCL_LOGGER}.{name}"
+    return logging.getLogger(name)
+
+
+# =============================================================================
+# Performance Instrumentation
+# =============================================================================
+
+# Performance logger
+_perf_logger = logging.getLogger(f"{PYTCL_LOGGER}.perf")
+
+
+def timed(
+    logger: Optional[logging.Logger] = None,
+    name: Optional[str] = None,
+    level: int = logging.DEBUG,
+) -> Callable[[F], F]:
+    """
+    Decorator to time function execution.
+
+    Parameters
+    ----------
+    logger : logging.Logger, optional
+        Logger to use. Defaults to pytcl.perf.
+    name : str, optional
+        Name to use in log message. Defaults to function name.
+    level : int
+        Logging level. Default is DEBUG.
+
+    Returns
+    -------
+    callable
+        Decorated function.
+
+    Examples
+    --------
+    >>> @timed(logger, "kf_predict")
+    ... def kf_predict(x, P, F, Q):
+    ...     return do_prediction(x, P, F, Q)
+    """
+
+    def decorator(func: F) -> F:
+        log = logger or _perf_logger
+        func_name = name or func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start = time.perf_counter()
+            try:
+                result = func(*args, **kwargs)
+                elapsed = (time.perf_counter() - start) * 1000
+                log.log(level, "%s completed in %.3fms", func_name, elapsed)
+                return result
+            except Exception as e:
+                elapsed = (time.perf_counter() - start) * 1000
+                log.log(level, "%s failed after %.3fms: %s", func_name, elapsed, e)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+@contextmanager
+def TimingContext(
+    logger: Optional[logging.Logger] = None,
+    name: str = "operation",
+    level: int = logging.DEBUG,
+) -> Generator[None, None, None]:
+    """
+    Context manager for timing code blocks.
+
+    Parameters
+    ----------
+    logger : logging.Logger, optional
+        Logger to use. Defaults to pytcl.perf.
+    name : str
+        Name for the operation being timed.
+    level : int
+        Logging level.
+
+    Yields
+    ------
+    dict
+        Dictionary that will contain 'elapsed_ms' after context exits.
+
+    Examples
+    --------
+    >>> with TimingContext(logger, "update_loop") as timing:
+    ...     for _ in range(100):
+    ...         do_update()
+    >>> print(f"Elapsed: {timing['elapsed_ms']:.2f}ms")
+    """
+    log = logger or _perf_logger
+    timing: dict[str, float] = {"elapsed_ms": 0.0}
+    start = time.perf_counter()
+    try:
+        yield timing
+    finally:
+        timing["elapsed_ms"] = (time.perf_counter() - start) * 1000
+        log.log(level, "%s completed in %.3fms", name, timing["elapsed_ms"])
+
+
+class PerformanceTracker:
+    """
+    Track cumulative performance statistics.
+
+    Useful for tracking performance across many iterations without
+    logging each one individually.
+
+    Parameters
+    ----------
+    name : str
+        Name for the tracked operation.
+    logger : logging.Logger, optional
+        Logger to use. Defaults to pytcl.perf.
+
+    Examples
+    --------
+    >>> tracker = PerformanceTracker("filter_cycles")
+    >>> for _ in range(1000):
+    ...     with tracker.track():
+    ...         do_filter_step()
+    >>> tracker.log_summary()
+    """
+
+    def __init__(self, name: str, logger: Optional[logging.Logger] = None):
+        self.name = name
+        self.logger = logger or _perf_logger
+        self.count = 0
+        self.total_ms = 0.0
+        self.min_ms = float("inf")
+        self.max_ms = 0.0
+
+    @contextmanager
+    def track(self) -> Generator[None, None, None]:
+        """Track a single operation."""
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            elapsed = (time.perf_counter() - start) * 1000
+            self.count += 1
+            self.total_ms += elapsed
+            self.min_ms = min(self.min_ms, elapsed)
+            self.max_ms = max(self.max_ms, elapsed)
+
+    @property
+    def mean_ms(self) -> float:
+        """Get mean execution time."""
+        return self.total_ms / self.count if self.count > 0 else 0.0
+
+    def log_summary(self, level: int = logging.INFO) -> None:
+        """Log performance summary."""
+        if self.count == 0:
+            self.logger.log(level, "%s: no data", self.name)
+            return
+
+        self.logger.log(
+            level,
+            "%s: count=%d, mean=%.3fms, min=%.3fms, max=%.3fms, total=%.1fms",
+            self.name,
+            self.count,
+            self.mean_ms,
+            self.min_ms,
+            self.max_ms,
+            self.total_ms,
+        )
+
+    def reset(self) -> None:
+        """Reset statistics."""
+        self.count = 0
+        self.total_ms = 0.0
+        self.min_ms = float("inf")
+        self.max_ms = 0.0
+
+    def __repr__(self) -> str:
+        return (
+            f"PerformanceTracker(name={self.name!r}, count={self.count}, "
+            f"mean_ms={self.mean_ms:.3f})"
+        )
+
+
+__all__ = [
+    "configure_logging",
+    "get_logger",
+    "timed",
+    "TimingContext",
+    "PerformanceTracker",
+    "PYTCL_LOGGER",
+    "LOGGER_HIERARCHY",
+    "FORMATS",
+]

pytcl/magnetism/__init__.py

@@ -45,7 +45,10 @@ from pytcl.magnetism.wmm import (
     WMM2020,
     MagneticCoefficients,
     MagneticResult,
+    clear_magnetic_cache,
+    configure_magnetic_cache,
     create_wmm2020_coefficients,
+    get_magnetic_cache_info,
     magnetic_declination,
     magnetic_field_intensity,
     magnetic_field_spherical,
@@ -66,6 +69,10 @@ __all__ = [
     "magnetic_declination",
     "magnetic_inclination",
     "magnetic_field_intensity",
+    # Cache management
+    "get_magnetic_cache_info",
+    "clear_magnetic_cache",
+    "configure_magnetic_cache",
     # IGRF
     "IGRF13",
     "create_igrf13_coefficients",

pytcl/magnetism/emm.py

@@ -24,7 +24,7 @@ References
 import os
 from functools import lru_cache
 from pathlib import Path
-from typing import Dict, NamedTuple, Optional, Tuple
+from typing import Any, NamedTuple, Optional, Tuple
 
 import numpy as np
 from numpy.typing import NDArray
@@ -32,7 +32,7 @@ from numpy.typing import NDArray
 from .wmm import MagneticResult
 
 # Model parameters
-EMM_PARAMETERS: Dict[str, Dict] = {
+EMM_PARAMETERS: dict[str, dict[str, Any]] = {
     "EMM2017": {
         "n_max": 790,
         "epoch": 2017.0,
@@ -119,7 +119,14 @@ def _ensure_data_dir() -> Path:
 def parse_emm_file(
     filepath: Path,
     n_max: Optional[int] = None,
-) -> Tuple[NDArray, NDArray, NDArray, NDArray, float, int]:
+) -> tuple[
+    NDArray[np.floating],
+    NDArray[np.floating],
+    NDArray[np.floating],
+    NDArray[np.floating],
+    float,
+    int,
+]:
     """Parse an EMM/WMMHR coefficient file.
 
     The file format is similar to WMM but with more coefficients: