nrl-tracker 1.9.2__py3-none-any.whl → 1.11.0__py3-none-any.whl

{nrl_tracker-1.9.2.dist-info → nrl_tracker-1.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.9.2
+Version: 1.11.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
@@ -41,6 +41,8 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
 Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
+Requires-Dist: nbval>=0.10.0; extra == "dev"
 Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
@@ -51,9 +53,15 @@ Requires-Dist: sphinx>=6.0.0; extra == "dev"
 Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "dev"
 Requires-Dist: myst-parser>=1.0.0; extra == "dev"
 Requires-Dist: nbsphinx>=0.9.0; extra == "dev"
+Requires-Dist: jupyter>=1.0.0; extra == "dev"
+Requires-Dist: ipykernel>=6.0.0; extra == "dev"
 Provides-Extra: geodesy
 Requires-Dist: pyproj>=3.4.0; extra == "geodesy"
 Requires-Dist: geographiclib>=2.0; extra == "geodesy"
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=12.0.0; extra == "gpu"
+Provides-Extra: gpu-apple
+Requires-Dist: mlx>=0.5.0; extra == "gpu-apple"
 Provides-Extra: optimization
 Requires-Dist: cvxpy>=1.3.0; extra == "optimization"
 Provides-Extra: signal
@@ -63,17 +71,17 @@ Requires-Dist: plotly>=5.15.0; extra == "visualization"
 
 # Tracker Component Library (Python)
 
-[![PyPI version](https://img.shields.io/badge/pypi-v1.9.2-blue.svg)](https://pypi.org/project/nrl-tracker/)
+[![PyPI version](https://img.shields.io/badge/pypi-v1.11.0-blue.svg)](https://pypi.org/project/nrl-tracker/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: Public Domain](https://img.shields.io/badge/License-Public%20Domain-brightgreen.svg)](https://en.wikipedia.org/wiki/Public_domain)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Tests](https://img.shields.io/badge/tests-2133%20passing-success.svg)](https://github.com/nedonatelli/TCL)
+[![Tests](https://img.shields.io/badge/tests-2894%20passing-success.svg)](https://github.com/nedonatelli/TCL)
 [![MATLAB Parity](https://img.shields.io/badge/MATLAB%20Parity-100%25-brightgreen.svg)](docs/gap_analysis.rst)
 [![Type Checking](https://img.shields.io/badge/mypy--strict-passing-brightgreen.svg)](mypy.ini)
 
 A Python port of the [U.S. Naval Research Laboratory's Tracker Component Library](https://github.com/USNavalResearchLaboratory/TrackerComponentLibrary), a comprehensive collection of algorithms for target tracking, estimation, coordinate systems, and related mathematical functions.
 
-**1,070+ functions** | **153 modules** | **2,133 tests** | **100% MATLAB parity**
+**1,070+ functions** | **153 modules** | **2,894 tests** | **100% MATLAB parity**
 
 ## Overview
 
@@ -90,6 +98,7 @@ The Tracker Component Library provides building blocks for developing target tra
 - **Navigation**: Geodetic calculations, INS mechanization, GNSS utilities, INS/GNSS integration
 - **Geophysical Models**: Gravity (WGS84, EGM96/2008), magnetism (WMM, IGRF), atmosphere, tides, terrain
 - **Signal Processing**: Digital filters, matched filtering, CFAR detection, transforms (FFT, STFT, wavelets)
+- **GPU Acceleration**: CuPy (NVIDIA CUDA) and MLX (Apple Silicon) backends for batch Kalman filtering and particle filters
 
 ## Installation
 
@@ -111,6 +120,12 @@ pip install nrl-tracker[geodesy]
 # For visualization
 pip install nrl-tracker[visualization]
 
+# For GPU acceleration (NVIDIA CUDA)
+pip install nrl-tracker[gpu]
+
+# For GPU acceleration (Apple Silicon M1/M2/M3)
+pip install nrl-tracker[gpu-apple]
+
 # For development
 pip install nrl-tracker[dev]
 
@@ -183,6 +198,35 @@ assignment, total_cost = hungarian(cost_matrix)
 print(f"Optimal assignment: {assignment}, Total cost: {total_cost}")
 ```
 
+### GPU Acceleration
+
+The library supports GPU acceleration for batch processing of multiple tracks:
+
+```python
+from pytcl.gpu import is_gpu_available, get_backend, to_gpu, to_cpu
+
+# Check GPU availability (auto-detects CUDA or Apple Silicon)
+if is_gpu_available():
+    print(f"GPU available, using {get_backend()} backend")
+
+    # Transfer data to GPU
+    x_gpu = to_gpu(states)  # (n_tracks, state_dim)
+    P_gpu = to_gpu(covariances)  # (n_tracks, state_dim, state_dim)
+
+    # Use batch Kalman filter operations
+    from pytcl.gpu import batch_kf_predict
+    x_pred, P_pred = batch_kf_predict(x_gpu, P_gpu, F, Q)
+
+    # Transfer results back to CPU
+    x_pred_cpu = to_cpu(x_pred)
+```
+
+**Supported backends:**
+- **NVIDIA CUDA**: Via CuPy (`pip install nrl-tracker[gpu]`)
+- **Apple Silicon**: Via MLX (`pip install nrl-tracker[gpu-apple]`)
+
+The backend is automatically selected based on your platform.
+
 ## Module Structure
 
 ```
@@ -202,6 +246,7 @@ pytcl/
 ├── gravity/                 # Gravity models
 ├── magnetism/               # Magnetic field models
 ├── terrain/                 # Terrain elevation models
+├── gpu/                     # GPU acceleration (CuPy/MLX)
 └── misc/                    # Utilities, visualization
 ```
 

{nrl_tracker-1.9.2.dist-info → nrl_tracker-1.11.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-pytcl/__init__.py,sha256=7ROietZU-pUiPRpioyeMjjZ6XybbmjRs1qRR_KoXioQ,2030
+pytcl/__init__.py,sha256=5Px9PB57Sz5vZZ88WtlCY5q1z5VlW8Qjn33GLO5VitI,2032
 pytcl/logging_config.py,sha256=UJaYufQgNuIjpsOMTPo3ewz1XCHPk8a08jTHyP7uoI4,8956
 pytcl/assignment_algorithms/__init__.py,sha256=kUWhmyLhZcs5GiUQA5_v7KA3qETGsvqV6wU8r7paO-k,2976
 pytcl/assignment_algorithms/data_association.py,sha256=tsRxWJZk9aAPmE99BKXGouEpFfZrjPjb4HXvgxFUHhU,11405
 pytcl/assignment_algorithms/dijkstra_min_cost.py,sha256=z-Wk1HXRNKieBsRFqR8_UB8QvG5QkK3evazr8wzTpl0,5429
 pytcl/assignment_algorithms/gating.py,sha256=JaRaFcFqjfdsTbbTP6k_GY2zemDSR02l5yInWHpb05Y,11439
 pytcl/assignment_algorithms/jpda.py,sha256=rOY_v1vesL6EJySwD0kRDTfe7wHoDFLITg_lJLM-bX4,21731
-pytcl/assignment_algorithms/nd_assignment.py,sha256=qYTFZryqfnHXz1I1Kg2vTvEJIYla4JknedhKPXphdiQ,13269
+pytcl/assignment_algorithms/nd_assignment.py,sha256=bcSNm3xSEjAg8gFb_TLQovpsLjNwvI5OOlh2y8XG4M0,24571
 pytcl/assignment_algorithms/network_flow.py,sha256=pPD63Z0-HOBv5XIqKUedt1KzTkcs0KG41DNojFZocDI,14459
 pytcl/assignment_algorithms/network_simplex.py,sha256=Qi10PsIYcTc6MZ-9GPl6ivaLaGA9F5-B7ltBbmasRNM,5566
 pytcl/assignment_algorithms/three_dimensional/__init__.py,sha256=1Q40OUlUQoo7YKEucwdrSNo3D4A0Zibvkr8z4TpueBg,526
@@ -46,7 +46,7 @@ pytcl/coordinate_systems/conversions/__init__.py,sha256=PkNevB78vBw0BkalydJBbQO9
 pytcl/coordinate_systems/conversions/geodetic.py,sha256=CarrTBW9rTC-CZ4E4YGxA8QjlpauuXJ2ZScnzc4QvK8,25001
 pytcl/coordinate_systems/conversions/spherical.py,sha256=GwuS1k0aUQ3AG1zZJouioMjxSIuEPRZMk-arvUCTh2k,11563
 pytcl/coordinate_systems/jacobians/__init__.py,sha256=CRGB8GzvGT_sr4Ynm51S7gSX8grqt1pO1Pq1MWmHPTs,890
-pytcl/coordinate_systems/jacobians/jacobians.py,sha256=0gpbelZPN4HDtvS1ymc3RIhOfxCVTKpRc-jDJXdM6pQ,11747
+pytcl/coordinate_systems/jacobians/jacobians.py,sha256=IkEwyseGM1LeI2-cQEqzGD-lCplK-PVCHup7Bh3QPl4,12947
 pytcl/coordinate_systems/projections/__init__.py,sha256=TmBiffO5cmazAhsfPIVBaaqnravVSO3JxjGb0MXkucc,2404
 pytcl/coordinate_systems/projections/projections.py,sha256=y_kwcu_zp0HHiKR-wp3v3AvRcY61bleDi1SxwbrnWB0,33179
 pytcl/coordinate_systems/rotations/__init__.py,sha256=nqAz4iJd2hEOX_r7Tz4cE524sShyxdbtcQ5m56RrDLg,1047
@@ -56,7 +56,7 @@ pytcl/core/array_utils.py,sha256=SsgEiAoRCWxAVKq1aa5-nPdOi-2AB6XNObu0IaGClUk,139
 pytcl/core/constants.py,sha256=cwkCjzCU7zG2ZsFcbqwslN632v7Lw50L85s-5q892mo,9988
 pytcl/core/exceptions.py,sha256=6ImMiwL86BdmTt-Rc8fXLXxKUGQ-PcQQyxIvKKzw-n0,24324
 pytcl/core/maturity.py,sha256=Sut19NfH1-6f3Qd2QSC6OAqvDcVHJDwf5-F_-oEAMJA,11596
-pytcl/core/optional_deps.py,sha256=Xe7BG18SWsmzBD3zGa440U_QWKkfATBKhUfLOxhXZuU,15799
+pytcl/core/optional_deps.py,sha256=a3UK_DM2s0XQE4Lwp0agq9L0qjupl_d8o4csCYbi440,16396
 pytcl/core/validation.py,sha256=4ay21cZVAil8udymwej7QnVQfNyjzi_5A8O1y-d-Lyw,23492
 pytcl/dynamic_estimation/__init__.py,sha256=zxmkZIXVfHPv5AHYpQV5nwsI0PA3m-Vw7W0gkJE7j98,5191
 pytcl/dynamic_estimation/gaussian_sum_filter.py,sha256=3Ks5-sGo3IF9p_dsIzk5u2zaXS2ZAkJFAg1mdxo8vj8,15343
@@ -70,7 +70,7 @@ pytcl/dynamic_estimation/kalman/constrained.py,sha256=Zidzz6_9OvwUyQppEltdmYTMvE
 pytcl/dynamic_estimation/kalman/extended.py,sha256=Yxc4Ve2aBtrkoelfMTFmzcXZefVZM0p0Z_a9n2IM1gQ,12032
 pytcl/dynamic_estimation/kalman/h_infinity.py,sha256=rtbYiryJbxzko-CIdNJSHuWXU2wI9T52YGBYq3o92sE,16563
 pytcl/dynamic_estimation/kalman/linear.py,sha256=gLFoCHjWtNHus_Nh4fTu67n_Xiv9QFVAuO5vO8MJICo,14673
-pytcl/dynamic_estimation/kalman/matrix_utils.py,sha256=couRVm0VKbhj9ctHcI-wcq8rj2MOapaSRVGuVdze3fQ,12426
+pytcl/dynamic_estimation/kalman/matrix_utils.py,sha256=mcBKgYP3yl57SbyU7h92aDjytV3zQhhY6RBgm0RP-rc,14924
 pytcl/dynamic_estimation/kalman/square_root.py,sha256=RlDepNt7eJ1qbQkZElqfhcX2oJET09P9Q_P8Bv7LcJo,8199
 pytcl/dynamic_estimation/kalman/sr_ukf.py,sha256=Vys5uC58HSZSTLc9xfmWCjw_XnZZfD4MpFBXBX0OVzU,8912
 pytcl/dynamic_estimation/kalman/types.py,sha256=5sMEWAvd9kkE3EG9daYcG8uV70MBx_awC5u6KJkmiZw,2202
@@ -90,11 +90,18 @@ pytcl/dynamic_models/process_noise/__init__.py,sha256=ZRYgV40qmBkPwU3yTbIMvxorr4
 pytcl/dynamic_models/process_noise/coordinated_turn.py,sha256=0PciDXtXHjgQdaYf7qpQqIZ7qoMV4uO_kE7wjpiBe64,6483
 pytcl/dynamic_models/process_noise/polynomial.py,sha256=w5ZW5Ouw6QpVtev_mnuCmZoj6_O6ovb2L_ENKDhHYIc,7742
 pytcl/dynamic_models/process_noise/singer.py,sha256=ozAdzH4s0wGlBaxajdyZvSnK8_CumgsUZDKeMW-TxDs,5735
+pytcl/gpu/__init__.py,sha256=aESvpn4Sa48xrQ4SIPb0j8uBt9bgiVHK_BgCXRLNY3o,4278
+pytcl/gpu/ekf.py,sha256=KPaojhYrti9F74C71_Pgc22HKDJeBSUkyrA7Iis9-L4,12575
+pytcl/gpu/kalman.py,sha256=8swMqLsnXjdl9-0vOg6wEqxtVHQRHcV4bXjHL8RwUmk,16417
+pytcl/gpu/matrix_utils.py,sha256=x2SBjN6f21YUeOOKThBtmIPyBnAXhTCvWteTxJZlSs0,12601
+pytcl/gpu/particle_filter.py,sha256=gqPt2ROFCkP-maFIlC8n7Td-ZNDZAN-42Ahen6TOfz8,17259
+pytcl/gpu/ukf.py,sha256=83tclGEAs4LWxocvUHSk7JIoUHozQnqusxM1qk_iedk,13273
+pytcl/gpu/utils.py,sha256=cedaW4evKeGCykFXI2QL_Ns8dU1yjL42MmYXf2gfGsw,14812
 pytcl/gravity/__init__.py,sha256=5xNdQSrrkt7-1-JPOYqR38CqvNJ7qKlPyMK36DGm6-I,3693
-pytcl/gravity/clenshaw.py,sha256=O7yYfjHMigR1RQHR_gZe3UuMIe_WsGrXFSLzn7PLfIE,16985
+pytcl/gravity/clenshaw.py,sha256=zhEtIxUY6Uj8EMv7ucO3JMBqauA5shFKbUW0HO2hUfI,17240
 pytcl/gravity/egm.py,sha256=LAeNbaQ7eZakk0ciwLec0_8q41MrBFouVLpDsETis6o,19683
 pytcl/gravity/models.py,sha256=WqBwaOhQdGMx7MsYGYYNbwQLj8rgV-I_VhKZLFvmfso,11990
-pytcl/gravity/spherical_harmonics.py,sha256=bRUFVLgPQEJ8M5a_cJrJ-d5s5xTCmOs4fwRvdYaACuw,18522
+pytcl/gravity/spherical_harmonics.py,sha256=SbCIlfNuJBwQ1nIJKo0DzgeEfW7RD_QnyKI0VhDSiGQ,18686
 pytcl/gravity/tides.py,sha256=NjsiXSiI7f-0qGr7G7YJVpIOVGzDxagz2S2vf_aRq68,28681
 pytcl/magnetism/__init__.py,sha256=pBASOzCPHNnYqUH_XDEblhGtjz50vY9uW2KS25A0zQQ,2701
 pytcl/magnetism/emm.py,sha256=iIdxSL0uGGIf8nfA-c_SmHvg9_J7HwRA2-qbQIUW6IE,22380
@@ -165,8 +172,8 @@ pytcl/trackers/mht.py,sha256=osEOXMaCeTt1eVn_E08dLRhEvBroVmf8b81zO5Zp1lU,20720
 pytcl/trackers/multi_target.py,sha256=RDITa0xnbgtVYAMj5XXp4lljo5lZ2zAAc02KZlOjxbQ,10526
 pytcl/trackers/single_target.py,sha256=Yy3FwaNTArMWcaod-0HVeiioNV4xLWxNDn_7ZPVqQYs,6562
 pytcl/transponders/__init__.py,sha256=5fL4u3lKCYgPLo5uFeuZbtRZkJPABntuKYGUvVgMMEI,41
-nrl_tracker-1.9.2.dist-info/LICENSE,sha256=rB5G4WppIIUzMOYr2N6uyYlNJ00hRJqE5tie6BMvYuE,1612
-nrl_tracker-1.9.2.dist-info/METADATA,sha256=HPSMMmbYsxCQpku97YqiIiaTut7fd0LOxLUBKCoMV-Y,12452
-nrl_tracker-1.9.2.dist-info/WHEEL,sha256=pL8R0wFFS65tNSRnaOVrsw9EOkOqxLrlUPenUYnJKNo,91
-nrl_tracker-1.9.2.dist-info/top_level.txt,sha256=17megxcrTPBWwPZTh6jTkwTKxX7No-ZqRpyvElnnO-s,6
-nrl_tracker-1.9.2.dist-info/RECORD,,
+nrl_tracker-1.11.0.dist-info/LICENSE,sha256=rB5G4WppIIUzMOYr2N6uyYlNJ00hRJqE5tie6BMvYuE,1612
+nrl_tracker-1.11.0.dist-info/METADATA,sha256=XU3LUdmSB3WwEn-r_0iaov-Ve80tFzJrbPHTibngc88,14038
+nrl_tracker-1.11.0.dist-info/WHEEL,sha256=pL8R0wFFS65tNSRnaOVrsw9EOkOqxLrlUPenUYnJKNo,91
+nrl_tracker-1.11.0.dist-info/top_level.txt,sha256=17megxcrTPBWwPZTh6jTkwTKxX7No-ZqRpyvElnnO-s,6
+nrl_tracker-1.11.0.dist-info/RECORD,,

pytcl/__init__.py

@@ -6,8 +6,8 @@ systems, dynamic models, estimation algorithms, and mathematical functions.
 
 This is a Python port of the U.S. Naval Research Laboratory's Tracker Component
 Library originally written in MATLAB.
-**Current Version:** 1.9.2 (January 4, 2026)
-**Status:** Production-ready, 2,133 tests passing, 76% line coverage
+**Current Version:** 1.11.0 (January 5, 2026)
+**Status:** Production-ready, 2,894 tests passing, 76% line coverage
 Examples
 --------
 >>> import pytcl as pytcl
@@ -21,7 +21,7 @@ References
        no. 5, pp. 18-27, May 2017.
 """
 
-__version__ = "1.9.2"
+__version__ = "1.11.0"
 __author__ = "Python Port Contributors"
 __original_author__ = "David F. Crouse, Naval Research Laboratory"
 

pytcl/assignment_algorithms/nd_assignment.py

@@ -9,6 +9,11 @@ enabling more complex assignment scenarios such as:
 The module provides a unified interface for solving high-dimensional
 assignment problems using generalized relaxation methods.
 
+Performance Notes
+-----------------
+For sparse cost tensors (mostly invalid assignments), use SparseCostTensor
+to reduce memory usage by up to 50% and improve performance on large problems.
+
 References
 ----------
 .. [1] Poore, A. B., "Multidimensional Assignment Problem and Data
@@ -18,7 +23,7 @@ References
        Drug Discovery," Perspectives in Drug Discovery and Design, 2003.
 """
 
-from typing import NamedTuple, Optional, Tuple
+from typing import List, NamedTuple, Optional, Tuple, Union
 
 import numpy as np
 from numpy.typing import NDArray
@@ -442,3 +447,356 @@ def detect_dimension_conflicts(
             return True
 
     return False
+
+
+class SparseCostTensor:
+    """
+    Sparse representation of N-dimensional cost tensor.
+
+    For assignment problems where most entries represent invalid
+    assignments (infinite cost), storing only valid entries reduces
+    memory by 50% or more and speeds up greedy algorithms.
+
+    Attributes
+    ----------
+    dims : tuple
+        Shape of the full tensor (n1, n2, ..., nk).
+    indices : ndarray
+        Array of shape (n_valid, n_dims) with valid entry indices.
+    costs : ndarray
+        Array of shape (n_valid,) with costs for valid entries.
+    default_cost : float
+        Cost for entries not explicitly stored (default: inf).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Create sparse tensor for 10x10x10 problem with 50 valid entries
+    >>> dims = (10, 10, 10)
+    >>> valid_indices = np.random.randint(0, 10, size=(50, 3))
+    >>> valid_costs = np.random.rand(50)
+    >>> sparse = SparseCostTensor(dims, valid_indices, valid_costs)
+    >>> sparse.n_valid
+    50
+    >>> sparse.sparsity  # Fraction of valid entries
+    0.05
+
+    >>> # Convert from dense tensor with inf for invalid
+    >>> dense = np.full((5, 5, 5), np.inf)
+    >>> dense[0, 0, 0] = 1.0
+    >>> dense[1, 1, 1] = 2.0
+    >>> sparse = SparseCostTensor.from_dense(dense)
+    >>> sparse.n_valid
+    2
+    """
+
+    def __init__(
+        self,
+        dims: Tuple[int, ...],
+        indices: NDArray[np.intp],
+        costs: NDArray[np.float64],
+        default_cost: float = np.inf,
+    ):
+        """
+        Initialize sparse cost tensor.
+
+        Parameters
+        ----------
+        dims : tuple
+            Shape of the full tensor.
+        indices : ndarray
+            Valid entry indices, shape (n_valid, n_dims).
+        costs : ndarray
+            Costs for valid entries, shape (n_valid,).
+        default_cost : float
+            Cost for invalid (unstored) entries.
+        """
+        self.dims = dims
+        self.indices = np.asarray(indices, dtype=np.intp)
+        self.costs = np.asarray(costs, dtype=np.float64)
+        self.default_cost = default_cost
+
+        # Build lookup for O(1) cost retrieval
+        self._cost_map: dict[Tuple[int, ...], float] = {}
+        for i in range(len(self.costs)):
+            key = tuple(self.indices[i])
+            self._cost_map[key] = self.costs[i]
+
+    @property
+    def n_dims(self) -> int:
+        """Number of dimensions."""
+        return len(self.dims)
+
+    @property
+    def n_valid(self) -> int:
+        """Number of valid (finite cost) entries."""
+        return len(self.costs)
+
+    @property
+    def sparsity(self) -> float:
+        """Fraction of tensor that is valid (0 to 1)."""
+        total_size = int(np.prod(self.dims))
+        return self.n_valid / total_size if total_size > 0 else 0.0
+
+    @property
+    def memory_savings(self) -> float:
+        """Estimated memory savings vs dense representation (0 to 1)."""
+        dense_size = np.prod(self.dims) * 8  # 8 bytes per float64
+        sparse_size = self.n_valid * (8 + self.n_dims * 8)  # cost + indices
+        return max(0, 1 - sparse_size / dense_size) if dense_size > 0 else 0.0
+
+    def get_cost(self, index: Tuple[int, ...]) -> float:
+        """Get cost for a specific index tuple."""
+        return self._cost_map.get(index, self.default_cost)
+
+    def to_dense(self) -> NDArray[np.float64]:
+        """
+        Convert to dense tensor representation.
+
+        Returns
+        -------
+        dense : ndarray
+            Full tensor with default_cost for unstored entries.
+
+        Notes
+        -----
+        May use significant memory for large tensors.
+        """
+        dense = np.full(self.dims, self.default_cost, dtype=np.float64)
+        for i in range(len(self.costs)):
+            dense[tuple(self.indices[i])] = self.costs[i]
+        return dense
+
+    @classmethod
+    def from_dense(
+        cls,
+        dense: NDArray[np.float64],
+        threshold: float = 1e10,
+    ) -> "SparseCostTensor":
+        """
+        Create sparse tensor from dense array.
+
+        Parameters
+        ----------
+        dense : ndarray
+            Dense cost tensor.
+        threshold : float
+            Entries above this value are considered invalid.
+            Default 1e10 (catches np.inf and large values).
+
+        Returns
+        -------
+        SparseCostTensor
+            Sparse representation.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> dense = np.array([[[1, np.inf], [np.inf, 2]],
+        ...                   [[np.inf, 3], [4, np.inf]]])
+        >>> sparse = SparseCostTensor.from_dense(dense)
+        >>> sparse.n_valid
+        4
+        """
+        valid_mask = dense < threshold
+        indices = np.array(np.where(valid_mask)).T
+        costs = dense[valid_mask]
+        return cls(dense.shape, indices, costs, default_cost=np.inf)
+
+
+def greedy_assignment_nd_sparse(
+    sparse_cost: SparseCostTensor,
+    max_assignments: Optional[int] = None,
+) -> AssignmentNDResult:
+    """
+    Greedy solver for sparse N-dimensional assignment.
+
+    Selects minimum-cost tuples from valid entries only, which is much
+    faster than dense greedy when sparsity < 0.5.
+
+    Parameters
+    ----------
+    sparse_cost : SparseCostTensor
+        Sparse cost tensor with valid entries only.
+    max_assignments : int, optional
+        Maximum number of assignments (default: min(dimensions)).
+
+    Returns
+    -------
+    AssignmentNDResult
+        Assignments, total cost, and algorithm info.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Create sparse problem
+    >>> dims = (10, 10, 10)
+    >>> # Only 20 valid assignments out of 1000
+    >>> indices = np.array([[i, i, i] for i in range(10)] +
+    ...                    [[i, (i+1)%10, (i+2)%10] for i in range(10)])
+    >>> costs = np.random.rand(20)
+    >>> sparse = SparseCostTensor(dims, indices, costs)
+    >>> result = greedy_assignment_nd_sparse(sparse)
+    >>> result.converged
+    True
+
+    Notes
+    -----
+    Time complexity is O(n_valid * log(n_valid)) vs O(total_size * log(total_size))
+    for dense greedy. For a 10x10x10 tensor with 50 valid entries, this is
+    50*log(50) vs 1000*log(1000), about 20x faster.
+    """
+    dims = sparse_cost.dims
+    n_dims = sparse_cost.n_dims
+
+    if max_assignments is None:
+        max_assignments = min(dims)
+
+    # Sort valid entries by cost
+    sorted_indices = np.argsort(sparse_cost.costs)
+
+    assignments: List[Tuple[int, ...]] = []
+    used_indices: List[set[int]] = [set() for _ in range(n_dims)]
+    total_cost = 0.0
+
+    for sorted_idx in sorted_indices:
+        if len(assignments) >= max_assignments:
+            break
+
+        multi_idx = tuple(sparse_cost.indices[sorted_idx])
+
+        # Check if any dimension index is already used
+        conflict = False
+        for d, idx in enumerate(multi_idx):
+            if idx in used_indices[d]:
+                conflict = True
+                break
+
+        if not conflict:
+            assignments.append(multi_idx)
+            total_cost += sparse_cost.costs[sorted_idx]
+            for d, idx in enumerate(multi_idx):
+                used_indices[d].add(idx)
+
+    assignments_array = np.array(assignments, dtype=np.intp)
+    if assignments_array.size == 0:
+        assignments_array = np.empty((0, n_dims), dtype=np.intp)
+
+    return AssignmentNDResult(
+        assignments=assignments_array,
+        cost=total_cost,
+        converged=True,
+        n_iterations=1,
+        gap=0.0,
+    )
+
+
+def assignment_nd(
+    cost: Union[NDArray[np.float64], SparseCostTensor],
+    method: str = "auto",
+    max_assignments: Optional[int] = None,
+    max_iterations: int = 100,
+    tolerance: float = 1e-6,
+    epsilon: float = 0.01,
+    verbose: bool = False,
+) -> AssignmentNDResult:
+    """
+    Unified interface for N-dimensional assignment.
+
+    Automatically selects between dense and sparse algorithms based on
+    input type and sparsity.
+
+    Parameters
+    ----------
+    cost : ndarray or SparseCostTensor
+        Cost tensor (dense) or sparse cost representation.
+    method : str
+        Algorithm to use: 'auto', 'greedy', 'relaxation', 'auction'.
+        'auto' selects greedy for sparse, relaxation for dense.
+    max_assignments : int, optional
+        Maximum number of assignments for greedy methods.
+    max_iterations : int
+        Maximum iterations for iterative methods.
+    tolerance : float
+        Convergence tolerance for relaxation.
+    epsilon : float
+        Price increment for auction algorithm.
+    verbose : bool
+        Print progress information.
+
+    Returns
+    -------
+    AssignmentNDResult
+        Assignment solution.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Dense usage
+    >>> cost = np.random.rand(4, 4, 4)
+    >>> result = assignment_nd(cost, method='greedy')
+    >>> result.converged
+    True
+
+    >>> # Sparse usage (more efficient for large sparse problems)
+    >>> dense = np.full((20, 20, 20), np.inf)
+    >>> for i in range(20):
+    ...     dense[i, i, i] = np.random.rand()
+    >>> sparse = SparseCostTensor.from_dense(dense)
+    >>> result = assignment_nd(sparse, method='auto')
+    >>> result.converged
+    True
+
+    See Also
+    --------
+    greedy_assignment_nd : Dense greedy algorithm.
+    greedy_assignment_nd_sparse : Sparse greedy algorithm.
+    relaxation_assignment_nd : Lagrangian relaxation.
+    auction_assignment_nd : Auction algorithm.
+    """
+    if isinstance(cost, SparseCostTensor):
+        # Sparse input - use sparse algorithm
+        if method in ("auto", "greedy"):
+            return greedy_assignment_nd_sparse(cost, max_assignments)
+        else:
+            # Convert to dense for other methods
+            dense = cost.to_dense()
+            if method == "relaxation":
+                return relaxation_assignment_nd(
+                    dense, max_iterations, tolerance, verbose
+                )
+            elif method == "auction":
+                return auction_assignment_nd(
+                    dense, max_iterations, epsilon=epsilon, verbose=verbose
+                )
+            else:
+                raise ValueError(f"Unknown method: {method}")
+    else:
+        # Dense input
+        cost = np.asarray(cost, dtype=np.float64)
+        if method == "auto":
+            # Use relaxation for better solutions on dense
+            return relaxation_assignment_nd(cost, max_iterations, tolerance, verbose)
+        elif method == "greedy":
+            return greedy_assignment_nd(cost, max_assignments)
+        elif method == "relaxation":
+            return relaxation_assignment_nd(cost, max_iterations, tolerance, verbose)
+        elif method == "auction":
+            return auction_assignment_nd(
+                cost, max_iterations, epsilon=epsilon, verbose=verbose
+            )
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+
+__all__ = [
+    "AssignmentNDResult",
+    "SparseCostTensor",
+    "validate_cost_tensor",
+    "greedy_assignment_nd",
+    "greedy_assignment_nd_sparse",
+    "relaxation_assignment_nd",
+    "auction_assignment_nd",
+    "detect_dimension_conflicts",
+    "assignment_nd",
+]