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

pytcl/containers/kd_tree.py

@@ -14,12 +14,17 @@ References
 """
 
 import logging
-from typing import List, NamedTuple, Optional, Tuple
+from typing import List, Optional, Tuple
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-from pytcl.containers.base import BaseSpatialIndex, validate_query_input
+from pytcl.containers.base import NearestNeighborResult  # Backward compatibility alias
+from pytcl.containers.base import (
+    BaseSpatialIndex,
+    NeighborResult,
+    validate_query_input,
+)
 
 # Module logger
 _logger = logging.getLogger("pytcl.containers.kd_tree")
@@ -57,21 +62,6 @@ class KDNode:
         self.right: Optional["KDNode"] = None
 
 
-class NearestNeighborResult(NamedTuple):
-    """Result of nearest neighbor query.
-
-    Attributes
-    ----------
-    indices : ndarray
-        Indices of nearest neighbors.
-    distances : ndarray
-        Distances to nearest neighbors.
-    """
-
-    indices: NDArray[np.intp]
-    distances: NDArray[np.floating]
-
-
 class KDTree(BaseSpatialIndex):
     """
     K-D Tree for efficient spatial queries.
@@ -157,7 +147,7 @@ class KDTree(BaseSpatialIndex):
         self,
         X: ArrayLike,
         k: int = 1,
-    ) -> NearestNeighborResult:
+    ) -> NeighborResult:
         """
         Query the tree for k nearest neighbors.
 
@@ -170,7 +160,7 @@ class KDTree(BaseSpatialIndex):
 
         Returns
         -------
-        result : NearestNeighborResult
+        result : NeighborResult
             Indices and distances of k nearest neighbors for each query.
 
         Examples
@@ -195,7 +185,7 @@ class KDTree(BaseSpatialIndex):
                 all_indices[i, :n_found] = indices
                 all_distances[i, :n_found] = distances
 
-        return NearestNeighborResult(indices=all_indices, distances=all_distances)
+        return NeighborResult(indices=all_indices, distances=all_distances)
 
     def _query_single(
         self,
@@ -308,27 +298,7 @@ class KDTree(BaseSpatialIndex):
         _search(self.root)
         return indices
 
-    def query_ball_point(
-        self,
-        X: ArrayLike,
-        r: float,
-    ) -> List[List[int]]:
-        """
-        Alias for query_radius (scipy compatibility).
-
-        Parameters
-        ----------
-        X : array_like
-            Query points.
-        r : float
-            Query radius.
-
-        Returns
-        -------
-        indices : list of lists
-            Indices of points within radius.
-        """
-        return self.query_radius(X, r)
+    # query_ball_point inherited from BaseSpatialIndex
 
 
 class BallTree(BaseSpatialIndex):
@@ -444,7 +414,7 @@ class BallTree(BaseSpatialIndex):
         self,
         X: ArrayLike,
         k: int = 1,
-    ) -> NearestNeighborResult:
+    ) -> NeighborResult:
         """
         Query the tree for k nearest neighbors.
 
@@ -457,7 +427,7 @@ class BallTree(BaseSpatialIndex):
 
         Returns
         -------
-        result : NearestNeighborResult
+        result : NeighborResult
             Indices and distances of k nearest neighbors.
         """
         X = validate_query_input(X, self.n_features)
@@ -473,7 +443,9 @@ class BallTree(BaseSpatialIndex):
                 all_indices[i, :n_found] = indices
                 all_distances[i, :n_found] = distances
 
-        return NearestNeighborResult(indices=all_indices, distances=all_distances)
+        return NeighborResult(indices=all_indices, distances=all_distances)
+
+    # query_ball_point inherited from BaseSpatialIndex
 
     def query_radius(
         self,
@@ -606,7 +578,8 @@ class BallTree(BaseSpatialIndex):
 
 __all__ = [
     "KDNode",
-    "NearestNeighborResult",
+    "NeighborResult",
+    "NearestNeighborResult",  # Backward compatibility alias
     "KDTree",
     "BallTree",
 ]

pytcl/containers/rtree.py

@@ -19,7 +19,11 @@ from typing import List, NamedTuple, Optional, Tuple
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-from pytcl.containers.base import SpatialQueryResult, validate_query_input
+from pytcl.containers.base import SpatialQueryResult  # Backward compatibility alias
+from pytcl.containers.base import (
+    NeighborResult,
+    validate_query_input,
+)
 
 # Module logger
 _logger = logging.getLogger("pytcl.containers.rtree")
@@ -418,7 +422,7 @@ class RTree:
         self,
         X: ArrayLike,
         k: int = 1,
-    ) -> SpatialQueryResult:
+    ) -> NeighborResult:
         """
         Query the tree for k nearest neighbors.
 
@@ -433,7 +437,7 @@ class RTree:
 
         Returns
         -------
-        result : SpatialQueryResult
+        result : NeighborResult
             Indices and distances of k nearest neighbors for each query.
 
         Examples
@@ -460,7 +464,7 @@ class RTree:
                 all_indices[i, :n_found] = indices
                 all_distances[i, :n_found] = distances
 
-        return SpatialQueryResult(indices=all_indices, distances=all_distances)
+        return NeighborResult(indices=all_indices, distances=all_distances)
 
     def query_radius(
         self,
@@ -529,6 +533,36 @@ class RTree:
 
         return results
 
+    def query_ball_point(
+        self,
+        X: ArrayLike,
+        r: float,
+    ) -> List[List[int]]:
+        """
+        Query the tree for all points within radius r.
+
+        This is an alias for :meth:`query_radius` provided for compatibility
+        with scipy.spatial.KDTree.
+
+        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.
+
+        See Also
+        --------
+        query_radius : The underlying implementation.
+        """
+        return self.query_radius(X, r)
+
     def query_intersect(self, query_bbox: BoundingBox) -> RTreeResult:
         """
         Find all entries intersecting a query box.
@@ -695,10 +729,15 @@ class RTree:
 
 
 __all__ = [
+    # Result types
+    "NeighborResult",
+    "SpatialQueryResult",  # Backward compatibility alias
+    # Bounding box utilities
     "BoundingBox",
     "merge_boxes",
     "box_from_point",
     "box_from_points",
+    # R-tree components
     "RTreeNode",
     "RTreeResult",
     "RTree",

pytcl/containers/vptree.py

@@ -12,32 +12,22 @@ References
 """
 
 import logging
-from typing import Any, Callable, List, NamedTuple, Optional, Tuple
+from typing import Any, Callable, List, Optional, Tuple
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-from pytcl.containers.base import MetricSpatialIndex, validate_query_input
+from pytcl.containers.base import VPTreeResult  # Backward compatibility alias
+from pytcl.containers.base import (
+    MetricSpatialIndex,
+    NeighborResult,
+    validate_query_input,
+)
 
 # Module logger
 _logger = logging.getLogger("pytcl.containers.vptree")
 
 
-class VPTreeResult(NamedTuple):
-    """Result of VP-tree query.
-
-    Attributes
-    ----------
-    indices : ndarray
-        Indices of nearest neighbors.
-    distances : ndarray
-        Distances to nearest neighbors.
-    """
-
-    indices: NDArray[np.intp]
-    distances: NDArray[np.floating]
-
-
 class VPNode:
     """Node in a VP-tree.
 
@@ -154,7 +144,7 @@ class VPTree(MetricSpatialIndex):
         self,
         X: ArrayLike,
         k: int = 1,
-    ) -> VPTreeResult:
+    ) -> NeighborResult:
         """
         Query the tree for k nearest neighbors.
 
@@ -167,7 +157,7 @@ class VPTree(MetricSpatialIndex):
 
         Returns
         -------
-        result : VPTreeResult
+        result : NeighborResult
             Indices and distances of k nearest neighbors.
         """
         X = validate_query_input(X, self.n_features)
@@ -184,7 +174,9 @@ class VPTree(MetricSpatialIndex):
                 all_indices[i, :n_found] = indices
                 all_distances[i, :n_found] = distances
 
-        return VPTreeResult(indices=all_indices, distances=all_distances)
+        return NeighborResult(indices=all_indices, distances=all_distances)
+
+    # query_ball_point inherited from BaseSpatialIndex
 
     def _query_single(
         self,
@@ -295,7 +287,8 @@ class VPTree(MetricSpatialIndex):
 
 
 __all__ = [
-    "VPTreeResult",
+    "NeighborResult",
+    "VPTreeResult",  # Backward compatibility alias
     "VPNode",
     "VPTree",
 ]

pytcl/core/__init__.py

@@ -5,6 +5,8 @@ This module provides foundational functionality used throughout the library:
 - Physical and mathematical constants
 - Input validation utilities
 - Array manipulation helpers compatible with MATLAB conventions
+- Custom exception hierarchy for consistent error handling
+- Optional dependency management
 """
 
 from pytcl.core.array_utils import (
@@ -23,10 +25,36 @@ from pytcl.core.constants import (
     WGS84,
     PhysicalConstants,
 )
+from pytcl.core.exceptions import (
+    ComputationError,
+    ConfigurationError,
+    ConvergenceError,
+    DataError,
+    DependencyError,
+    DimensionError,
+    EmptyContainerError,
+    FormatError,
+    MethodError,
+    NumericalError,
+    ParameterError,
+    ParseError,
+    RangeError,
+    SingularMatrixError,
+    StateError,
+    TCLError,
+    UninitializedError,
+    ValidationError,
+)
+from pytcl.core.optional_deps import (
+    LazyModule,
+    check_dependencies,
+    import_optional,
+    is_available,
+    requires,
+)
 from pytcl.core.validation import (
     ArraySpec,
     ScalarSpec,
-    ValidationError,
     check_compatible_shapes,
     ensure_2d,
     ensure_column_vector,
@@ -48,8 +76,31 @@ __all__ = [
     "EARTH_ROTATION_RATE",
     "WGS84",
     "PhysicalConstants",
-    # Validation
+    # Exceptions (base)
+    "TCLError",
+    # Exceptions (validation)
     "ValidationError",
+    "DimensionError",
+    "ParameterError",
+    "RangeError",
+    # Exceptions (computation)
+    "ComputationError",
+    "ConvergenceError",
+    "NumericalError",
+    "SingularMatrixError",
+    # Exceptions (state)
+    "StateError",
+    "UninitializedError",
+    "EmptyContainerError",
+    # Exceptions (configuration)
+    "ConfigurationError",
+    "MethodError",
+    "DependencyError",
+    # Exceptions (data)
+    "DataError",
+    "FormatError",
+    "ParseError",
+    # Validation utilities
     "validate_array",
     "validate_inputs",
     "validate_same_shape",
@@ -68,4 +119,10 @@ __all__ = [
     "wrap_to_range",
     "column_vector",
     "row_vector",
+    # Optional dependencies
+    "is_available",
+    "import_optional",
+    "requires",
+    "check_dependencies",
+    "LazyModule",
 ]

pytcl/core/constants.py

@@ -317,3 +317,62 @@ c = SPEED_OF_LIGHT
 
 #: Alias for GRAVITATIONAL_CONSTANT
 G = GRAVITATIONAL_CONSTANT
+
+
+__all__ = [
+    # Universal Physical Constants
+    "SPEED_OF_LIGHT",
+    "GRAVITATIONAL_CONSTANT",
+    "PLANCK_CONSTANT",
+    "BOLTZMANN_CONSTANT",
+    "STEFAN_BOLTZMANN_CONSTANT",
+    "ELEMENTARY_CHARGE",
+    "AVOGADRO_CONSTANT",
+    "UNIVERSAL_GAS_CONSTANT",
+    "STANDARD_ATMOSPHERE",
+    "ABSOLUTE_ZERO_CELSIUS",
+    # Earth Parameters
+    "EARTH_SEMI_MAJOR_AXIS",
+    "EARTH_SEMI_MINOR_AXIS",
+    "EARTH_FLATTENING",
+    "EARTH_ECCENTRICITY_SQ",
+    "EARTH_ECCENTRICITY",
+    "EARTH_ECCENTRICITY_PRIME_SQ",
+    "EARTH_ROTATION_RATE",
+    "EARTH_GM",
+    "EARTH_GM_EGM2008",
+    "EARTH_MEAN_ANGULAR_VELOCITY",
+    "EARTH_MEAN_RADIUS",
+    "STANDARD_GRAVITY",
+    # Time Constants
+    "SECONDS_PER_DAY",
+    "SECONDS_PER_JULIAN_CENTURY",
+    "DAYS_PER_JULIAN_YEAR",
+    "DAYS_PER_JULIAN_CENTURY",
+    "J2000_EPOCH_JD",
+    "MJD_OFFSET",
+    # Mathematical Constants
+    "PI",
+    "TWO_PI",
+    "HALF_PI",
+    "DEG_TO_RAD",
+    "RAD_TO_DEG",
+    "ARCSEC_TO_RAD",
+    "RAD_TO_ARCSEC",
+    # Dataclasses
+    "EllipsoidParameters",
+    "PhysicalConstants",
+    # Ellipsoid Instances
+    "WGS84",
+    "GRS80",
+    "CLARKE1866",
+    "SPHERE_EARTH",
+    # Solar System Parameters
+    "ASTRONOMICAL_UNIT",
+    "SUN_GM",
+    "MOON_GM",
+    "EARTH_MOON_MASS_RATIO",
+    # Aliases
+    "c",
+    "G",
+]