nrl-tracker 1.1.2__tar.gz → 1.2.0__tar.gz

{nrl_tracker-1.1.2/nrl_tracker.egg-info → nrl_tracker-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.1.2
+Version: 1.2.0
 Summary: Python port of the U.S. Naval Research Laboratory's Tracker Component Library for target tracking algorithms
 Author: Original: David F. Crouse, Naval Research Laboratory
 Maintainer: Python Port Contributors

{nrl_tracker-1.1.2 → nrl_tracker-1.2.0/nrl_tracker.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.1.2
+Version: 1.2.0
 Summary: Python port of the U.S. Naval Research Laboratory's Tracker Component Library for target tracking algorithms
 Author: Original: David F. Crouse, Naval Research Laboratory
 Maintainer: Python Port Contributors

{nrl_tracker-1.1.2 → nrl_tracker-1.2.0}/nrl_tracker.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ pytcl/clustering/gaussian_mixture.py
 pytcl/clustering/hierarchical.py
 pytcl/clustering/kmeans.py
 pytcl/containers/__init__.py
+pytcl/containers/base.py
 pytcl/containers/cluster_set.py
 pytcl/containers/covertree.py
 pytcl/containers/kd_tree.py
@@ -184,6 +185,7 @@ tests/test_relativity.py
 tests/test_rhumb.py
 tests/test_signal_processing.py
 tests/test_smoothers.py
+tests/test_spatial_containers_parametrized.py
 tests/test_spatial_structures.py
 tests/test_special_functions_phase12.py
 tests/test_static_estimation.py
@@ -195,4 +197,5 @@ tests/test_tracking_containers.py
 tests/test_transforms.py
 tests/test_v030_comprehensive.py
 tests/test_v030_features.py
+tests/test_validation.py
 tests/unit/test_core.py

{nrl_tracker-1.1.2 → nrl_tracker-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nrl-tracker"
-version = "1.1.2"
+version = "1.2.0"
 description = "Python port of the U.S. Naval Research Laboratory's Tracker Component Library for target tracking algorithms"
 readme = "README.md"
 authors = [

{nrl_tracker-1.1.2 → nrl_tracker-1.2.0}/pytcl/__init__.py

@@ -20,7 +20,7 @@ References
        no. 5, pp. 18-27, May 2017.
 """
 
-__version__ = "1.1.2"
+__version__ = "1.2.0"
 __author__ = "Python Port Contributors"
 __original_author__ = "David F. Crouse, Naval Research Laboratory"
 

{nrl_tracker-1.1.2 → nrl_tracker-1.2.0}/pytcl/astronomical/reference_frames.py

@@ -21,6 +21,8 @@ References
        A&A, 2003.
 """
 
+import logging
+from functools import lru_cache
 from typing import Tuple
 
 import numpy as np
@@ -28,6 +30,22 @@ from numpy.typing import NDArray
 
 from pytcl.astronomical.time_systems import JD_J2000
 
+# Module logger
+_logger = logging.getLogger("pytcl.astronomical.reference_frames")
+
+# Cache configuration
+_CACHE_JD_DECIMALS = 6  # ~86ms precision for JD quantization
+_CACHE_MAXSIZE = 128  # Max cached epochs
+
+
+def _quantize_jd(jd: float) -> float:
+    """Quantize Julian date for cache key compatibility.
+
+    Rounds to _CACHE_JD_DECIMALS decimal places (~86ms precision).
+    This enables cache hits for nearly identical epochs.
+    """
+    return round(jd, _CACHE_JD_DECIMALS)
+
 
 def julian_centuries_j2000(jd: float) -> float:
     """
@@ -78,6 +96,37 @@ def precession_angles_iau76(T: float) -> Tuple[float, float, float]:
     )
 
 
+@lru_cache(maxsize=_CACHE_MAXSIZE)
+def _precession_matrix_cached(jd_quantized: float) -> tuple:
+    """Cached precession matrix computation (internal).
+
+    Returns tuple of tuples for hashability.
+    """
+    T = julian_centuries_j2000(jd_quantized)
+    zeta, theta, z = precession_angles_iau76(T)
+
+    cos_zeta = np.cos(zeta)
+    sin_zeta = np.sin(zeta)
+    cos_theta = np.cos(theta)
+    sin_theta = np.sin(theta)
+    cos_z = np.cos(z)
+    sin_z = np.sin(z)
+
+    return (
+        (
+            cos_zeta * cos_theta * cos_z - sin_zeta * sin_z,
+            -sin_zeta * cos_theta * cos_z - cos_zeta * sin_z,
+            -sin_theta * cos_z,
+        ),
+        (
+            cos_zeta * cos_theta * sin_z + sin_zeta * cos_z,
+            -sin_zeta * cos_theta * sin_z + cos_zeta * cos_z,
+            -sin_theta * sin_z,
+        ),
+        (cos_zeta * sin_theta, -sin_zeta * sin_theta, cos_theta),
+    )
+
+
 def precession_matrix_iau76(jd: float) -> NDArray[np.floating]:
     """
     Compute IAU 1976 precession matrix from J2000 to date.
@@ -92,34 +141,15 @@ def precession_matrix_iau76(jd: float) -> NDArray[np.floating]:
     P : ndarray
         Precession rotation matrix (3x3).
         Transforms from J2000 (GCRF) to mean of date.
-    """
-    T = julian_centuries_j2000(jd)
-    zeta, theta, z = precession_angles_iau76(T)
 
-    cos_zeta = np.cos(zeta)
-    sin_zeta = np.sin(zeta)
-    cos_theta = np.cos(theta)
-    sin_theta = np.sin(theta)
-    cos_z = np.cos(z)
-    sin_z = np.sin(z)
-
-    P = np.array(
-        [
-            [
-                cos_zeta * cos_theta * cos_z - sin_zeta * sin_z,
-                -sin_zeta * cos_theta * cos_z - cos_zeta * sin_z,
-                -sin_theta * cos_z,
-            ],
-            [
-                cos_zeta * cos_theta * sin_z + sin_zeta * cos_z,
-                -sin_zeta * cos_theta * sin_z + cos_zeta * cos_z,
-                -sin_theta * sin_z,
-            ],
-            [cos_zeta * sin_theta, -sin_zeta * sin_theta, cos_theta],
-        ]
-    )
-
-    return P
+    Notes
+    -----
+    Results are cached for repeated queries at the same epoch.
+    Cache key is quantized to ~86ms precision.
+    """
+    jd_q = _quantize_jd(jd)
+    cached = _precession_matrix_cached(jd_q)
+    return np.array(cached)
 
 
 def nutation_angles_iau80(jd: float) -> Tuple[float, float]:
@@ -203,6 +233,38 @@ def mean_obliquity_iau80(jd: float) -> float:
     return eps0_arcsec * np.pi / (180 * 3600)
 
 
+@lru_cache(maxsize=_CACHE_MAXSIZE)
+def _nutation_matrix_cached(jd_quantized: float) -> tuple:
+    """Cached nutation matrix computation (internal).
+
+    Returns tuple of tuples for hashability.
+    """
+    dpsi, deps = nutation_angles_iau80(jd_quantized)
+    eps0 = mean_obliquity_iau80(jd_quantized)
+    eps = eps0 + deps
+
+    cos_eps0 = np.cos(eps0)
+    sin_eps0 = np.sin(eps0)
+    cos_eps = np.cos(eps)
+    sin_eps = np.sin(eps)
+    cos_dpsi = np.cos(dpsi)
+    sin_dpsi = np.sin(dpsi)
+
+    return (
+        (cos_dpsi, -sin_dpsi * cos_eps0, -sin_dpsi * sin_eps0),
+        (
+            sin_dpsi * cos_eps,
+            cos_dpsi * cos_eps0 * cos_eps + sin_eps0 * sin_eps,
+            cos_dpsi * sin_eps0 * cos_eps - cos_eps0 * sin_eps,
+        ),
+        (
+            sin_dpsi * sin_eps,
+            cos_dpsi * cos_eps0 * sin_eps - sin_eps0 * cos_eps,
+            cos_dpsi * sin_eps0 * sin_eps + cos_eps0 * cos_eps,
+        ),
+    )
+
+
 def nutation_matrix(jd: float) -> NDArray[np.floating]:
     """
     Compute nutation matrix.
@@ -217,35 +279,15 @@ def nutation_matrix(jd: float) -> NDArray[np.floating]:
     N : ndarray
         Nutation rotation matrix (3x3).
         Transforms from mean of date to true of date.
-    """
-    dpsi, deps = nutation_angles_iau80(jd)
-    eps0 = mean_obliquity_iau80(jd)
-    eps = eps0 + deps
 
-    cos_eps0 = np.cos(eps0)
-    sin_eps0 = np.sin(eps0)
-    cos_eps = np.cos(eps)
-    sin_eps = np.sin(eps)
-    cos_dpsi = np.cos(dpsi)
-    sin_dpsi = np.sin(dpsi)
-
-    N = np.array(
-        [
-            [cos_dpsi, -sin_dpsi * cos_eps0, -sin_dpsi * sin_eps0],
-            [
-                sin_dpsi * cos_eps,
-                cos_dpsi * cos_eps0 * cos_eps + sin_eps0 * sin_eps,
-                cos_dpsi * sin_eps0 * cos_eps - cos_eps0 * sin_eps,
-            ],
-            [
-                sin_dpsi * sin_eps,
-                cos_dpsi * cos_eps0 * sin_eps - sin_eps0 * cos_eps,
-                cos_dpsi * sin_eps0 * sin_eps + cos_eps0 * cos_eps,
-            ],
-        ]
-    )
-
-    return N
+    Notes
+    -----
+    Results are cached for repeated queries at the same epoch.
+    Cache key is quantized to ~86ms precision.
+    """
+    jd_q = _quantize_jd(jd)
+    cached = _nutation_matrix_cached(jd_q)
+    return np.array(cached)
 
 
 def earth_rotation_angle(jd_ut1: float) -> float:
@@ -647,6 +689,33 @@ def equatorial_to_ecliptic(
     return R @ r_eq
 
 
+def clear_transformation_cache() -> None:
+    """Clear cached transformation matrices.
+
+    Call this function to clear all cached precession and nutation
+    matrices. Useful when memory is constrained or after processing
+    a batch of observations at different epochs.
+    """
+    _precession_matrix_cached.cache_clear()
+    _nutation_matrix_cached.cache_clear()
+    _logger.debug("Transformation matrix cache cleared")
+
+
+def get_cache_info() -> dict:
+    """Get cache statistics for transformation matrices.
+
+    Returns
+    -------
+    dict
+        Dictionary with 'precession' and 'nutation' keys, each containing
+        CacheInfo namedtuple with hits, misses, maxsize, currsize.
+    """
+    return {
+        "precession": _precession_matrix_cached.cache_info(),
+        "nutation": _nutation_matrix_cached.cache_info(),
+    }
+
+
 __all__ = [
     # Time utilities
     "julian_centuries_j2000",
@@ -674,4 +743,7 @@ __all__ = [
     # Ecliptic/equatorial
     "ecliptic_to_equatorial",
     "equatorial_to_ecliptic",
+    # Cache management
+    "clear_transformation_cache",
+    "get_cache_info",
 ]

{nrl_tracker-1.1.2 → nrl_tracker-1.2.0}/pytcl/containers/__init__.py

@@ -3,8 +3,27 @@ Containers module.
 
 This module provides spatial data structures for efficient
 nearest neighbor queries, spatial indexing, and tracking containers.
+
+Spatial Index Hierarchy
+-----------------------
+All spatial index structures inherit from BaseSpatialIndex which defines
+a common interface for k-nearest neighbor and radius queries:
+
+    BaseSpatialIndex (abstract)
+    ├── KDTree - K-dimensional tree (Euclidean space)
+    ├── BallTree - Ball tree variant of KD-tree
+    ├── RTree - Rectangle tree for bounding boxes
+    └── MetricSpatialIndex (abstract)
+        ├── VPTree - Vantage point tree (any metric)
+        └── CoverTree - Cover tree (any metric)
 """
 
+from pytcl.containers.base import (
+    BaseSpatialIndex,
+    MetricSpatialIndex,
+    SpatialQueryResult,
+    validate_query_input,
+)
 from pytcl.containers.cluster_set import (
     ClusterSet,
     ClusterStats,
@@ -33,6 +52,11 @@ from pytcl.containers.track_list import TrackList, TrackListStats, TrackQuery
 from pytcl.containers.vptree import VPNode, VPTree, VPTreeResult
 
 __all__ = [
+    # Base classes
+    "BaseSpatialIndex",
+    "MetricSpatialIndex",
+    "SpatialQueryResult",
+    "validate_query_input",
     # K-D Tree
     "KDNode",
     "NearestNeighborResult",

nrl_tracker-1.2.0/pytcl/containers/base.py

@@ -0,0 +1,219 @@
+"""
+Base classes for spatial data structures.
+
+This module provides abstract base classes that define the common interface
+for spatial indexing data structures like KD-trees, VP-trees, R-trees, and
+Cover trees.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Callable, List, NamedTuple, Optional
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+# Module logger
+_logger = logging.getLogger("pytcl.containers")
+
+
+class SpatialQueryResult(NamedTuple):
+    """Result of a spatial query.
+
+    Attributes
+    ----------
+    indices : ndarray
+        Indices of matching points in the original data.
+    distances : ndarray
+        Distances to matching points.
+    """
+
+    indices: NDArray[np.intp]
+    distances: NDArray[np.floating]
+
+
+class BaseSpatialIndex(ABC):
+    """
+    Abstract base class for spatial indexing data structures.
+
+    All spatial index implementations (KDTree, VPTree, RTree, CoverTree)
+    should inherit from this class and implement the required methods.
+
+    This provides a consistent interface for:
+    - Building the index from point data
+    - k-nearest neighbor queries
+    - Range/radius queries
+    - Dimension and size introspection
+
+    Parameters
+    ----------
+    data : array_like
+        Data points of shape (n_samples, n_features).
+
+    Attributes
+    ----------
+    data : ndarray
+        The indexed data points.
+    n_samples : int
+        Number of data points.
+    n_features : int
+        Dimensionality of data points.
+    """
+
+    def __init__(self, data: ArrayLike):
+        self.data = np.asarray(data, dtype=np.float64)
+
+        if self.data.ndim != 2:
+            raise ValueError(
+                f"Data must be 2-dimensional (n_samples, n_features), "
+                f"got shape {self.data.shape}"
+            )
+
+        self.n_samples, self.n_features = self.data.shape
+        _logger.debug(
+            "%s initialized with %d points in %d dimensions",
+            self.__class__.__name__,
+            self.n_samples,
+            self.n_features,
+        )
+
+    @abstractmethod
+    def query(
+        self,
+        X: ArrayLike,
+        k: int = 1,
+    ) -> SpatialQueryResult:
+        """
+        Query the index for k nearest neighbors.
+
+        Parameters
+        ----------
+        X : array_like
+            Query points of shape (n_queries, n_features) or (n_features,).
+        k : int, optional
+            Number of nearest neighbors to return. Default is 1.
+
+        Returns
+        -------
+        result : SpatialQueryResult
+            Named tuple with indices and distances of k nearest neighbors
+            for each query point.
+        """
+        pass
+
+    @abstractmethod
+    def query_radius(
+        self,
+        X: ArrayLike,
+        r: float,
+    ) -> List[List[int]]:
+        """
+        Query the index for all points within radius r.
+
+        Parameters
+        ----------
+        X : array_like
+            Query points of shape (n_queries, n_features) or (n_features,).
+        r : float
+            Search radius.
+
+        Returns
+        -------
+        indices : list of list of int
+            For each query point, a list of indices of data points
+            within distance r.
+        """
+        pass
+
+    def __len__(self) -> int:
+        """Return number of indexed points."""
+        return self.n_samples
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"n_samples={self.n_samples}, n_features={self.n_features})"
+        )
+
+
+class MetricSpatialIndex(BaseSpatialIndex):
+    """
+    Base class for metric space spatial indices.
+
+    Extends BaseSpatialIndex with support for custom distance metrics.
+    Used by VP-trees and Cover trees which can work with any metric.
+
+    Parameters
+    ----------
+    data : array_like
+        Data points of shape (n_samples, n_features).
+    metric : callable, optional
+        Distance function with signature metric(x, y) -> float.
+        Default is Euclidean distance.
+    """
+
+    def __init__(
+        self,
+        data: ArrayLike,
+        metric: Optional[Callable[[NDArray, NDArray], float]] = None,
+    ):
+        super().__init__(data)
+
+        if metric is None:
+            self.metric = self._euclidean_distance
+        else:
+            self.metric = metric
+
+    @staticmethod
+    def _euclidean_distance(x: NDArray, y: NDArray) -> float:
+        """Default Euclidean distance metric."""
+        return float(np.sqrt(np.sum((x - y) ** 2)))
+
+
+def validate_query_input(
+    X: ArrayLike,
+    n_features: int,
+) -> NDArray[np.floating]:
+    """
+    Validate and reshape query input.
+
+    Parameters
+    ----------
+    X : array_like
+        Query points.
+    n_features : int
+        Expected number of features.
+
+    Returns
+    -------
+    X : ndarray
+        Validated query array of shape (n_queries, n_features).
+
+    Raises
+    ------
+    ValueError
+        If query has wrong number of features.
+    """
+    X = np.asarray(X, dtype=np.float64)
+
+    if X.ndim == 1:
+        X = X.reshape(1, -1)
+
+    if X.shape[1] != n_features:
+        _logger.warning(
+            "Query feature mismatch: got %d, expected %d", X.shape[1], n_features
+        )
+        raise ValueError(f"Query has {X.shape[1]} features, expected {n_features}")
+
+    _logger.debug(
+        "Validated query input: %d queries, %d features", X.shape[0], X.shape[1]
+    )
+    return X
+
+
+__all__ = [
+    "SpatialQueryResult",
+    "BaseSpatialIndex",
+    "MetricSpatialIndex",
+    "validate_query_input",
+]

{nrl_tracker-1.1.2 → nrl_tracker-1.2.0}/pytcl/containers/covertree.py

@@ -11,11 +11,17 @@ References
        neighbor," ICML 2006.
 """
 
+import logging
 from typing import Callable, List, NamedTuple, Optional, Set, Tuple
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
+from pytcl.containers.base import MetricSpatialIndex, validate_query_input
+
+# Module logger
+_logger = logging.getLogger("pytcl.containers.covertree")
+
 
 class CoverTreeResult(NamedTuple):
     """Result of Cover tree query.
@@ -60,7 +66,7 @@ class CoverTreeNode:
         self.children[level].append(child)
 
 
-class CoverTree:
+class CoverTree(MetricSpatialIndex):
     """
     Cover Tree for metric space nearest neighbor search.
 
@@ -93,6 +99,11 @@ class CoverTree:
 
     The implementation uses a simplified version of the original
     algorithm for clarity.
+
+    See Also
+    --------
+    MetricSpatialIndex : Abstract base class for metric-based spatial indices.
+    VPTree : Alternative metric space index using vantage points.
     """
 
     def __init__(
@@ -101,19 +112,9 @@ class CoverTree:
         metric: Optional[Callable[[NDArray, NDArray], float]] = None,
         base: float = 2.0,
     ):
-        self.data = np.asarray(data, dtype=np.float64)
-
-        if self.data.ndim != 2:
-            raise ValueError("Data must be 2-dimensional")
-
-        self.n_samples, self.n_features = self.data.shape
+        super().__init__(data, metric)
         self.base = base
 
-        if metric is None:
-            self.metric = self._euclidean_distance
-        else:
-            self.metric = metric
-
         # Compute distance cache for small datasets
         self._distance_cache: dict[Tuple[int, int], float] = {}
 
@@ -124,10 +125,12 @@ class CoverTree:
 
         if self.n_samples > 0:
             self._build_tree()
-
-    def _euclidean_distance(self, x: NDArray, y: NDArray) -> float:
-        """Default Euclidean distance metric."""
-        return float(np.sqrt(np.sum((x - y) ** 2)))
+            _logger.debug(
+                "CoverTree built with base=%.1f, levels=%d to %d",
+                base,
+                self.min_level,
+                self.max_level,
+            )
 
     def _distance(self, i: int, j: int) -> float:
         """Get distance between points i and j (with caching)."""
@@ -245,11 +248,7 @@ class CoverTree:
         result : CoverTreeResult
             Indices and distances of k nearest neighbors.
         """
-        X = np.asarray(X, dtype=np.float64)
-
-        if X.ndim == 1:
-            X = X.reshape(1, -1)
-
+        X = validate_query_input(X, self.n_features)
         n_queries = X.shape[0]
 
         all_indices = np.zeros((n_queries, k), dtype=np.intp)
@@ -368,11 +367,7 @@ class CoverTree:
         indices : list of lists
             For each query, list of indices within radius.
         """
-        X = np.asarray(X, dtype=np.float64)
-
-        if X.ndim == 1:
-            X = X.reshape(1, -1)
-
+        X = validate_query_input(X, self.n_features)
         n_queries = X.shape[0]
         results: List[List[int]] = []