nrl-tracker 1.1.3__py3-none-any.whl → 1.2.0__py3-none-any.whl

pytcl/core/validation.py

@@ -472,3 +472,334 @@ def validated_array_input(
         return wrapper
 
     return decorator
+
+
+class ArraySpec:
+    """
+    Specification for array validation in @validate_inputs decorator.
+
+    Parameters
+    ----------
+    dtype : type or np.dtype, optional
+        Required dtype.
+    ndim : int or tuple of int, optional
+        Required dimensionality.
+    shape : tuple, optional
+        Required shape (None for any size).
+    min_ndim : int, optional
+        Minimum dimensions required.
+    max_ndim : int, optional
+        Maximum dimensions allowed.
+    finite : bool, optional
+        Require all finite values.
+    non_negative : bool, optional
+        Require all values >= 0.
+    positive : bool, optional
+        Require all values > 0.
+    allow_empty : bool, optional
+        Allow empty arrays. Default True.
+    square : bool, optional
+        Require square matrix.
+    symmetric : bool, optional
+        Require symmetric matrix.
+    positive_definite : bool, optional
+        Require positive definite matrix.
+
+    Examples
+    --------
+    >>> spec = ArraySpec(ndim=2, finite=True, square=True)
+    >>> @validate_inputs(matrix=spec)
+    ... def process_matrix(matrix):
+    ...     return np.linalg.inv(matrix)
+    """
+
+    def __init__(
+        self,
+        *,
+        dtype: type | np.dtype | None = None,
+        ndim: int | tuple[int, ...] | None = None,
+        shape: tuple[int | None, ...] | None = None,
+        min_ndim: int | None = None,
+        max_ndim: int | None = None,
+        finite: bool = False,
+        non_negative: bool = False,
+        positive: bool = False,
+        allow_empty: bool = True,
+        square: bool = False,
+        symmetric: bool = False,
+        positive_definite: bool = False,
+    ):
+        self.dtype = dtype
+        self.ndim = ndim
+        self.shape = shape
+        self.min_ndim = min_ndim
+        self.max_ndim = max_ndim
+        self.finite = finite
+        self.non_negative = non_negative
+        self.positive = positive
+        self.allow_empty = allow_empty
+        self.square = square
+        self.symmetric = symmetric
+        self.positive_definite = positive_definite
+
+    def validate(self, arr: ArrayLike, name: str) -> NDArray[Any]:
+        """Validate an array against this specification."""
+        result = validate_array(
+            arr,
+            name,
+            dtype=self.dtype,
+            ndim=self.ndim,
+            shape=self.shape,
+            min_ndim=self.min_ndim,
+            max_ndim=self.max_ndim,
+            finite=self.finite,
+            non_negative=self.non_negative,
+            positive=self.positive,
+            allow_empty=self.allow_empty,
+        )
+
+        if self.positive_definite:
+            result = ensure_positive_definite(result, name)
+        elif self.symmetric:
+            result = ensure_symmetric(result, name)
+        elif self.square:
+            result = ensure_square_matrix(result, name)
+
+        return result
+
+
+class ScalarSpec:
+    """
+    Specification for scalar validation in @validate_inputs decorator.
+
+    Parameters
+    ----------
+    dtype : type, optional
+        Required type (int, float, etc.).
+    min_value : float, optional
+        Minimum allowed value (inclusive).
+    max_value : float, optional
+        Maximum allowed value (inclusive).
+    finite : bool, optional
+        Require finite value.
+    positive : bool, optional
+        Require value > 0.
+    non_negative : bool, optional
+        Require value >= 0.
+
+    Examples
+    --------
+    >>> spec = ScalarSpec(dtype=int, min_value=1, max_value=10)
+    >>> @validate_inputs(k=spec)
+    ... def get_k_nearest(k, data):
+    ...     return data[:k]
+    """
+
+    def __init__(
+        self,
+        *,
+        dtype: type | None = None,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        finite: bool = False,
+        positive: bool = False,
+        non_negative: bool = False,
+    ):
+        self.dtype = dtype
+        self.min_value = min_value
+        self.max_value = max_value
+        self.finite = finite
+        self.positive = positive
+        self.non_negative = non_negative
+
+    def validate(self, value: Any, name: str) -> Any:
+        """Validate a scalar value against this specification."""
+        # Type check
+        if self.dtype is not None:
+            if not isinstance(value, self.dtype):
+                try:
+                    value = self.dtype(value)
+                except (ValueError, TypeError) as e:
+                    raise ValidationError(
+                        f"{name} must be {self.dtype.__name__}, got {type(value).__name__}"
+                    ) from e
+
+        # Convert to float for numeric checks
+        try:
+            num_value = float(value)
+        except (ValueError, TypeError):
+            if any(
+                [
+                    self.finite,
+                    self.positive,
+                    self.non_negative,
+                    self.min_value is not None,
+                    self.max_value is not None,
+                ]
+            ):
+                raise ValidationError(
+                    f"{name} must be numeric for range validation"
+                ) from None
+            return value
+
+        # Finite check
+        if self.finite and not np.isfinite(num_value):
+            raise ValidationError(f"{name} must be finite, got {value}")
+
+        # Positive check
+        if self.positive and num_value <= 0:
+            raise ValidationError(f"{name} must be positive, got {value}")
+
+        # Non-negative check
+        if self.non_negative and num_value < 0:
+            raise ValidationError(f"{name} must be non-negative, got {value}")
+
+        # Range checks
+        if self.min_value is not None and num_value < self.min_value:
+            raise ValidationError(f"{name} must be >= {self.min_value}, got {value}")
+
+        if self.max_value is not None and num_value > self.max_value:
+            raise ValidationError(f"{name} must be <= {self.max_value}, got {value}")
+
+        return value
+
+
+def validate_inputs(
+    **param_specs: ArraySpec | ScalarSpec | dict[str, Any],
+) -> Callable[[F], F]:
+    """
+    Decorator for validating multiple function parameters.
+
+    This decorator enables declarative input validation using specification
+    objects (ArraySpec, ScalarSpec) or dictionaries of validation options.
+
+    Parameters
+    ----------
+    **param_specs : ArraySpec | ScalarSpec | dict
+        Keyword arguments mapping parameter names to validation specs.
+        Each spec can be:
+        - ArraySpec: For array validation
+        - ScalarSpec: For scalar validation
+        - dict: Options passed to ArraySpec (for convenience)
+
+    Returns
+    -------
+    Callable
+        Decorated function with input validation.
+
+    Examples
+    --------
+    >>> @validate_inputs(
+    ...     x=ArraySpec(ndim=2, finite=True),
+    ...     P=ArraySpec(ndim=2, positive_definite=True),
+    ...     k=ScalarSpec(dtype=int, min_value=1),
+    ... )
+    ... def kalman_update(x, P, z, H, R, k=1):
+    ...     # x and P are guaranteed valid here
+    ...     pass
+
+    Using dict shorthand:
+
+    >>> @validate_inputs(
+    ...     state={"ndim": 1, "finite": True},
+    ...     covariance={"ndim": 2, "positive_definite": True},
+    ... )
+    ... def predict(state, covariance, dt):
+    ...     pass
+
+    Notes
+    -----
+    Validation happens in the order parameters are defined in the decorator.
+    If any validation fails, a ValidationError is raised with a descriptive
+    message identifying the parameter and the constraint violated.
+
+    See Also
+    --------
+    ArraySpec : Specification class for array validation.
+    ScalarSpec : Specification class for scalar validation.
+    validate_array : Lower-level array validation function.
+    """
+
+    def decorator(func: F) -> F:
+        import inspect
+
+        # Pre-fetch signature for efficiency
+        sig = inspect.signature(func)
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            for param_name, spec in param_specs.items():
+                if param_name not in bound.arguments:
+                    continue
+
+                value = bound.arguments[param_name]
+
+                # Convert dict to ArraySpec
+                if isinstance(spec, dict):
+                    spec = ArraySpec(**spec)
+
+                # Validate using spec
+                if isinstance(spec, (ArraySpec, ScalarSpec)):
+                    bound.arguments[param_name] = spec.validate(value, param_name)
+                else:
+                    raise TypeError(
+                        f"Invalid spec type for {param_name}: {type(spec)}. "
+                        "Use ArraySpec, ScalarSpec, or dict."
+                    )
+
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def check_compatible_shapes(
+    *shapes: tuple[int, ...],
+    names: Sequence[str] | None = None,
+    dimension: int | None = None,
+) -> None:
+    """
+    Check that array shapes are compatible for operations.
+
+    Parameters
+    ----------
+    *shapes : tuple of int
+        Shapes to check for compatibility.
+    names : sequence of str, optional
+        Names for error messages.
+    dimension : int, optional
+        If provided, only check compatibility along this dimension.
+
+    Raises
+    ------
+    ValidationError
+        If shapes are not compatible.
+
+    Examples
+    --------
+    >>> check_compatible_shapes((3, 4), (4, 5), names=["A", "B"], dimension=0)
+    # Raises: A has 3 rows but B has 4 rows
+
+    >>> check_compatible_shapes((3, 4), (4, 5), names=["A", "B"])
+    # Passes (inner dimensions compatible for matrix multiply)
+    """
+    if len(shapes) < 2:
+        return
+
+    if names is None:
+        names = [f"array_{i}" for i in range(len(shapes))]
+
+    if dimension is not None:
+        # Check specific dimension
+        dims = [s[dimension] if len(s) > dimension else None for s in shapes]
+        valid_dims = [d for d in dims if d is not None]
+        if valid_dims and not all(d == valid_dims[0] for d in valid_dims):
+            dim_strs = [f"{n}={d}" for n, d in zip(names, dims) if d is not None]
+            raise ValidationError(
+                f"Arrays have incompatible sizes along dimension {dimension}: "
+                f"{', '.join(dim_strs)}"
+            )

pytcl/gravity/egm.py

@@ -21,6 +21,7 @@ References
        https://earth-info.nga.mil/
 """
 
+import logging
 import os
 from functools import lru_cache
 from pathlib import Path
@@ -32,6 +33,9 @@ from numpy.typing import NDArray
 from .clenshaw import clenshaw_gravity, clenshaw_potential
 from .models import WGS84, normal_gravity_somigliana
 
+# Module logger
+_logger = logging.getLogger("pytcl.gravity.egm")
+
 
 class EGMCoefficients(NamedTuple):
     """Earth Gravitational Model coefficients.
@@ -317,6 +321,8 @@ def _load_coefficients_cached(
     data_dir = get_data_dir()
     filepath = data_dir / f"{model}.cof"
 
+    _logger.debug("Loading %s coefficients from %s", model, filepath)
+
     if not filepath.exists():
         raise FileNotFoundError(
             f"Coefficient file not found: {filepath}\n"
@@ -330,6 +336,13 @@ def _load_coefficients_cached(
     actual_n_max = n_max if n_max is not None else int(params["n_max_full"])
     C, S = parse_egm_file(filepath, actual_n_max)
 
+    _logger.info(
+        "Loaded %s coefficients: n_max=%d, array_size=%.1f MB",
+        model,
+        C.shape[0] - 1,
+        C.nbytes / 1024 / 1024 * 2,  # Both C and S arrays
+    )
+
     return EGMCoefficients(
         C=C,
         S=S,

pytcl/gravity/spherical_harmonics.py

@@ -11,11 +11,69 @@ References
 .. [2] O. Montenbruck and E. Gill, "Satellite Orbits," Springer, 2000.
 """
 
+import logging
+from functools import lru_cache
 from typing import 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:
+    """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():
+    """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/mathematical_functions/special_functions/hypergeometric.py

@@ -3,13 +3,84 @@ Hypergeometric functions.
 
 This module provides hypergeometric functions commonly used in
 mathematical physics, probability theory, and special function evaluation.
+
+Performance
+-----------
+The generalized hypergeometric function uses Numba JIT compilation for
+the series summation loop, providing significant speedup for the general
+case (p > 2 or q > 1).
 """
 
 import numpy as np
 import scipy.special as sp
+from numba import njit
 from numpy.typing import ArrayLike, NDArray
 
 
+@njit(cache=True, fastmath=True)
+def _hypergeometric_series(
+    a: np.ndarray,
+    b: np.ndarray,
+    z: np.ndarray,
+    max_terms: int,
+    tol: float,
+) -> np.ndarray:
+    """
+    Numba-optimized series summation for generalized hypergeometric function.
+
+    Parameters
+    ----------
+    a : ndarray
+        Numerator parameters (1D array).
+    b : ndarray
+        Denominator parameters (1D array).
+    z : ndarray
+        Argument values (1D array).
+    max_terms : int
+        Maximum number of series terms.
+    tol : float
+        Convergence tolerance.
+
+    Returns
+    -------
+    result : ndarray
+        Computed pFq values for each z.
+    """
+    n_z = len(z)
+    p = len(a)
+    q = len(b)
+
+    result = np.ones(n_z, dtype=np.float64)
+    term = np.ones(n_z, dtype=np.float64)
+
+    for k in range(1, max_terms):
+        # Compute numerator product: prod(a_i + k - 1)
+        num_factor = 1.0
+        for i in range(p):
+            num_factor *= a[i] + k - 1
+
+        # Compute denominator product: prod(b_i + k - 1) * k
+        den_factor = float(k)
+        for i in range(q):
+            den_factor *= b[i] + k - 1
+
+        # Update term and result for each z value
+        ratio = num_factor / den_factor
+        converged = True
+        for j in range(n_z):
+            term[j] = term[j] * z[j] * ratio
+            result[j] += term[j]
+
+            # Check convergence
+            if np.abs(term[j]) >= tol * np.abs(result[j]):
+                converged = False
+
+        if converged:
+            break
+
+    return result
+
+
 def hyp0f1(
     b: ArrayLike,
     z: ArrayLike,
@@ -369,6 +440,11 @@ def generalized_hypergeometric(
     - p = q + 1: |z| < 1
     - p > q + 1: diverges except for polynomial cases
 
+    Performance
+    -----------
+    Uses Numba JIT compilation for the general case (p > 2 or q > 1),
+    providing 5-10x speedup over pure Python loops.
+
     Examples
     --------
     >>> generalized_hypergeometric([1], [2], 1)  # 1F1(1; 2; 1) ~ 1.718...
@@ -389,21 +465,9 @@ def generalized_hypergeometric(
     elif p == 2 and q == 1:
         return hyp2f1(a[0], a[1], b[0], z)
 
-    # General case: series summation
-    z = np.atleast_1d(z)
-    result = np.ones_like(z, dtype=np.float64)
-    term = np.ones_like(z, dtype=np.float64)
-
-    for k in range(1, max_terms):
-        # Compute ratio term_k / term_{k-1}
-        num_factor = np.prod(a + k - 1)
-        den_factor = np.prod(b + k - 1) * k
-        term = term * z * num_factor / den_factor
-
-        result += term
-
-        if np.all(np.abs(term) < tol * np.abs(result)):
-            break
+    # General case: use Numba-optimized series summation
+    z_arr = np.atleast_1d(z)
+    result = _hypergeometric_series(a, b, z_arr, max_terms, tol)
 
     return result if result.size > 1 else result[0]