nrl-tracker 1.11.0__tar.gz → 1.12.0__tar.gz

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0}/CONTRIBUTING.md

@@ -148,8 +148,8 @@ from scipy.io import loadmat
 import numpy as np
 
 data = loadmat('cart2sphere_reference.mat')
-np.savez('cart2sphere_reference.npz', 
-         input=data['input'], 
+np.savez('cart2sphere_reference.npz',
+         input=data['input'],
          expected=data['output'])
 ```
 
@@ -176,10 +176,10 @@ When porting a function from the original MATLAB library:
    Notes
    -----
    This is a port of Cart2Sphere.m from the MATLAB Tracker Component Library.
-   
+
    References
    ----------
-   .. [1] Original implementation: 
+   .. [1] Original implementation:
           https://github.com/USNavalResearchLaboratory/TrackerComponentLibrary
    ```
 
@@ -204,13 +204,13 @@ When porting a function from the original MATLAB library:
    ```bash
    # Format code
    black .
-   
+
    # Lint
    flake8 pytcl tests
-   
+
    # Type check
    mypy pytcl
-   
+
    # Run tests
    pytest
    ```

{nrl_tracker-1.11.0/nrl_tracker.egg-info → nrl_tracker-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.11.0
+Version: 1.12.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
@@ -71,17 +71,17 @@ Requires-Dist: nrl-tracker[astronomy,dev,geodesy,optimization,signal,visualizati
 
 # Tracker Component Library (Python)
 
-[![PyPI version](https://img.shields.io/badge/pypi-v1.11.0-blue.svg)](https://pypi.org/project/nrl-tracker/)
+[![PyPI version](https://img.shields.io/badge/pypi-v1.11.1-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-2894%20passing-success.svg)](https://github.com/nedonatelli/TCL)
+[![Tests](https://img.shields.io/badge/tests-3280%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,894 tests** | **100% MATLAB parity**
+**1,070+ functions** | **153 modules** | **3,280 tests** | **100% MATLAB parity**
 
 ## Overview
 

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0}/README.md

@@ -1,16 +1,16 @@
 # Tracker Component Library (Python)
 
-[![PyPI version](https://img.shields.io/badge/pypi-v1.11.0-blue.svg)](https://pypi.org/project/nrl-tracker/)
+[![PyPI version](https://img.shields.io/badge/pypi-v1.11.1-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-2894%20passing-success.svg)](https://github.com/nedonatelli/TCL)
+[![Tests](https://img.shields.io/badge/tests-3280%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,894 tests** | **100% MATLAB parity**
+**1,070+ functions** | **153 modules** | **3,280 tests** | **100% MATLAB parity**
 
 ## Overview
 

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0/nrl_tracker.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.11.0
+Version: 1.12.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
@@ -71,17 +71,17 @@ Requires-Dist: nrl-tracker[astronomy,dev,geodesy,optimization,signal,visualizati
 
 # Tracker Component Library (Python)
 
-[![PyPI version](https://img.shields.io/badge/pypi-v1.11.0-blue.svg)](https://pypi.org/project/nrl-tracker/)
+[![PyPI version](https://img.shields.io/badge/pypi-v1.11.1-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-2894%20passing-success.svg)](https://github.com/nedonatelli/TCL)
+[![Tests](https://img.shields.io/badge/tests-3280%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,894 tests** | **100% MATLAB parity**
+**1,070+ functions** | **153 modules** | **3,280 tests** | **100% MATLAB parity**
 
 ## Overview
 

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0}/nrl_tracker.egg-info/SOURCES.txt

@@ -195,8 +195,12 @@ tests/test_coordinate_systems.py
 tests/test_coverage_boost.py
 tests/test_coverage_boost_2.py
 tests/test_debye.py
+tests/test_debye_comprehensive.py
+tests/test_detection_comprehensive.py
+tests/test_distributions_comprehensive.py
 tests/test_dynamic_models.py
 tests/test_egm.py
+tests/test_egm_comprehensive.py
 tests/test_elliptic.py
 tests/test_emm.py
 tests/test_ephemerides.py
@@ -209,21 +213,28 @@ tests/test_geometry.py
 tests/test_geophysical.py
 tests/test_gpu.py
 tests/test_gpu_utils.py
+tests/test_gpu_utils_comprehensive.py
 tests/test_great_circle.py
 tests/test_h_infinity.py
 tests/test_hypergeometric.py
+tests/test_hypergeometric_comprehensive.py
+tests/test_hypergeometric_stft_targeted.py
 tests/test_ins.py
 tests/test_ins_gnss.py
 tests/test_ionosphere.py
 tests/test_jpda.py
 tests/test_kalman_filters.py
+tests/test_lambert_comprehensive.py
 tests/test_marcum_q.py
 tests/test_matched_filter.py
 tests/test_mathematical_functions.py
+tests/test_maturity_comprehensive.py
 tests/test_maximum_likelihood.py
+tests/test_metrics_plotting_comprehensive.py
 tests/test_mht.py
 tests/test_nd_assignment.py
 tests/test_network_flow.py
+tests/test_network_flow_comprehensive.py
 tests/test_nrlmsise00.py
 tests/test_optional_deps.py
 tests/test_performance_evaluation.py
@@ -244,6 +255,7 @@ tests/test_special_functions.py
 tests/test_special_orbits.py
 tests/test_square_root_filters.py
 tests/test_static_estimation.py
+tests/test_stft_comprehensive.py
 tests/test_terrain.py
 tests/test_terrain_loaders.py
 tests/test_tides.py

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nrl-tracker"
-version = "1.11.0"
+version = "1.12.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.11.0 → nrl_tracker-1.12.0}/pytcl/__init__.py

@@ -6,7 +6,7 @@ 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.11.0 (January 5, 2026)
+**Current Version:** 1.12.0 (January 5, 2026)
 **Status:** Production-ready, 2,894 tests passing, 76% line coverage
 Examples
 --------
@@ -21,7 +21,7 @@ References
        no. 5, pp. 18-27, May 2017.
 """
 
-__version__ = "1.11.0"
+__version__ = "1.12.0"
 __author__ = "Python Port Contributors"
 __original_author__ = "David F. Crouse, Naval Research Laboratory"
 

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0}/pytcl/assignment_algorithms/network_flow.py

@@ -179,13 +179,19 @@ def min_cost_flow_successive_shortest_paths(
     max_iterations: int = 1000,
 ) -> MinCostFlowResult:
     """
-    Solve min-cost flow using successive shortest paths.
+    Solve min-cost flow using successive shortest paths with cost scaling.
 
     Algorithm:
-    1. While there is excess supply:
-       - Find shortest path from a supply node to a demand node
-       - Push maximum feasible flow along path
-       - Update supplies and residual capacities
+    1. Initialize potentials using Bellman-Ford
+    2. While there is excess supply:
+       - Find shortest path using reduced costs (Dijkstra with potentials)
+       - Push unit flow along path
+       - Update node potentials
+       - Recompute shortest paths to maintain optimality
+
+    This is the standard min-cost flow algorithm that guarantees optimality
+    and convergence. It uses Dijkstra's algorithm with potentials, which
+    maintains the dual feasibility (reduced cost property).
 
     Parameters
     ----------
@@ -217,100 +223,163 @@ def min_cost_flow_successive_shortest_paths(
 
     Notes
     -----
-    This is a simplified implementation using Bellman-Ford for shortest
-    paths. Production code would use more efficient implementations.
+    This implementation uses successive shortest paths with potentials.
+    The algorithm is guaranteed to find the optimal solution for any
+    feasible min-cost flow problem.
+
+    For rectangular assignment problems (m < n or m > n), all m units
+    of flow must be satisfied. The algorithm ensures this by finding
+    augmenting paths until all supply is routed.
     """
     n_nodes = len(supplies)
     n_edges = len(edges)
 
-    # Build adjacency lists for residual graph
-    graph: list[list[tuple[int, int, float]]] = [[] for _ in range(n_nodes)]
+    # Initialize flow and residual capacity
     flow = np.zeros(n_edges)
     residual_capacity = np.array([e.capacity for e in edges])
 
+    # Initialize node potentials using Bellman-Ford from a dummy source
+    # This ensures all potentials are finite and maintains dual feasibility
+    potential = np.zeros(n_nodes)
+
+    # Build adjacency list representation
+    # Each entry: (to_node, edge_idx, is_reverse, cost)
+    graph: list[list[tuple[int, int, int, float]]] = [[] for _ in range(n_nodes)]
+
     for edge_idx, edge in enumerate(edges):
-        graph[edge.from_node].append((edge.to_node, edge_idx, edge.cost))
-        # Add reverse edge with negative cost
-        graph[edge.to_node].append((edge.from_node, edge_idx, -edge.cost))
+        # Forward edge
+        graph[edge.from_node].append((edge.to_node, edge_idx, 0, edge.cost))
+        # Reverse edge (for flow cancellation)
+        graph[edge.to_node].append((edge.from_node, edge_idx, 1, -edge.cost))
 
     current_supplies = supplies.copy()
     iteration = 0
 
+    # Main algorithm loop
     while iteration < max_iterations:
-        # Find a node with excess supply
-        excess_node = None
+        # Find excess and deficit nodes
+        excess_node = -1
+        deficit_node = -1
+
         for node in range(n_nodes):
             if current_supplies[node] > 1e-10:
                 excess_node = node
                 break
 
-        if excess_node is None:
-            break
+        if excess_node < 0:
+            break  # No more excess nodes
 
-        # Find a node with deficit
-        deficit_node = None
         for node in range(n_nodes):
             if current_supplies[node] < -1e-10:
                 deficit_node = node
                 break
 
-        if deficit_node is None:
-            break
+        if deficit_node < 0:
+            break  # No deficit nodes
 
-        # Find shortest path using Bellman-Ford relaxation
+        # Find shortest path using Dijkstra with potentials
+        # Reduced cost: c_reduced(u,v) = c(u,v) + π(u) - π(v)
         dist = np.full(n_nodes, np.inf)
         dist[excess_node] = 0.0
         parent = np.full(n_nodes, -1, dtype=int)
         parent_edge = np.full(n_nodes, -1, dtype=int)
+        parent_reverse = np.full(n_nodes, 0, dtype=int)
+        visited = np.zeros(n_nodes, dtype=bool)
+
+        # Dijkstra's algorithm
+        for _ in range(n_nodes):
+            # Find unvisited node with minimum distance
+            u = -1
+            min_dist = np.inf
+            for node in range(n_nodes):
+                if not visited[node] and dist[node] < min_dist:
+                    u = node
+                    min_dist = dist[node]
+
+            if u < 0 or dist[u] == np.inf:
+                break
+
+            visited[u] = True
 
-        for _ in range(n_nodes - 1):
-            for u in range(n_nodes):
-                if dist[u] == np.inf:
-                    continue
-                for v, edge_idx, cost in graph[u]:
-                    if residual_capacity[edge_idx] > 1e-10:
-                        new_dist = dist[u] + cost
-                        if new_dist < dist[v]:
-                            dist[v] = new_dist
-                            parent[v] = u
-                            parent_edge[v] = edge_idx
-
-        if dist[deficit_node] == np.inf:
+            # Relax edges from u
+            for v, eidx, is_rev, cost in graph[u]:
+                if residual_capacity[eidx] > 1e-10:
+                    # Compute reduced cost
+                    reduced_cost = cost + potential[u] - potential[v]
+                    new_dist = dist[u] + reduced_cost
+
+                    if new_dist < dist[v] - 1e-10:
+                        dist[v] = new_dist
+                        parent[v] = u
+                        parent_edge[v] = eidx
+                        parent_reverse[v] = is_rev
+
+        if dist[deficit_node] >= np.inf:
             # No path found
             break
 
-        # Extract path and find bottleneck capacity
+        # Update potentials to maintain dual feasibility
+        for node in range(n_nodes):
+            if dist[node] < np.inf:
+                potential[node] += dist[node]
+
+        # Extract path by backtracking
         path_edges = []
+        path_reverse_flags = []
         node = deficit_node
-        while parent[node] != -1:
+        path_length = 0
+        visited_set = set()
+
+        while parent[node] >= 0:
+            if path_length >= n_nodes:
+                break  # Safety check
+            if node in visited_set:
+                break  # Cycle detected
+
+            visited_set.add(node)
             path_edges.append(parent_edge[node])
+            path_reverse_flags.append(parent_reverse[node])
             node = parent[node]
+            path_length += 1
+
+        if not path_edges:
+            iteration += 1
+            continue
 
         path_edges.reverse()
+        path_reverse_flags.reverse()
 
-        # Find minimum capacity along path
+        # Find bottleneck capacity
         min_flow = min(residual_capacity[e] for e in path_edges)
         min_flow = min(
-            min_flow, current_supplies[excess_node], -current_supplies[deficit_node]
+            min_flow,
+            current_supplies[excess_node],
+            -current_supplies[deficit_node],
         )
 
         # Push flow along path
-        total_cost = 0.0
-        for edge_idx in path_edges:
-            flow[edge_idx] += min_flow
-            residual_capacity[edge_idx] -= min_flow
-            total_cost += min_flow * edges[edge_idx].cost
+        for edge_idx, is_reverse in zip(path_edges, path_reverse_flags):
+            if is_reverse == 0:
+                # Forward edge: increase flow
+                flow[edge_idx] += min_flow
+                residual_capacity[edge_idx] -= min_flow
+            else:
+                # Reverse edge: decrease flow (cancel)
+                flow[edge_idx] -= min_flow
+                residual_capacity[edge_idx] += min_flow
 
         current_supplies[excess_node] -= min_flow
         current_supplies[deficit_node] += min_flow
 
         iteration += 1
 
-    # Compute total cost
-    total_cost = float(np.sum(flow[i] * edges[i].cost for i in range(n_edges)))
+    # Compute total cost: include all flows (including negative which cancel)
+    total_cost = 0.0
+    for i, edge in enumerate(edges):
+        total_cost += flow[i] * edge.cost
 
     # Determine status
-    if np.allclose(current_supplies, 0):
+    if np.allclose(current_supplies, 0, atol=1e-6):
         status = FlowStatus.OPTIMAL
     elif iteration >= max_iterations:
         status = FlowStatus.TIMEOUT
@@ -409,6 +478,14 @@ def assignment_from_flow_solution(
     """
     Extract assignment from flow network solution.
 
+    A valid flow solution for assignment should have:
+    - Exactly 1 unit of flow from each worker to some task
+    - Exactly 1 unit of flow to each task from some worker
+    - No negative flows on worker->task edges (those are cancellations)
+
+    This function extracts the actual assignment by identifying which
+    worker->task edges carry the net positive flow.
+
     Parameters
     ----------
     flow : ndarray
@@ -427,24 +504,59 @@ def assignment_from_flow_solution(
     """
     m, n = cost_matrix_shape
     assignment = []
+    cost = 0.0
+
+    # Build source node (node 0) and sink node (node m+n+1) indices
+    source = 0
+    sink = m + n + 1
+
+    # For a valid assignment solution:
+    # - Count flow out of source to each worker
+    # - Count flow into sink from each task
+    worker_outflow = np.zeros(m)
+    task_inflow = np.zeros(n)
+
+    # Collect all worker->task edges and their flows
+    worker_task_edges = []
 
     for edge_idx, edge in enumerate(edges):
-        # Worker-to-task edges: from_node in [1, m], to_node in [m+1, m+n]
-        if 1 <= edge.from_node <= m and m + 1 <= edge.to_node <= m + n:
-            if flow[edge_idx] > 0.5:  # Flow > 0 (allowing for numerical tolerance)
-                worker_idx = edge.from_node - 1
-                task_idx = edge.to_node - m - 1
-                assignment.append([worker_idx, task_idx])
+        # Worker edges: from source (0) to worker nodes (1..m)
+        if edge.from_node == source and 1 <= edge.to_node <= m:
+            worker_id = edge.to_node - 1
+            worker_outflow[worker_id] += flow[edge_idx]
 
-    assignment = np.array(assignment, dtype=np.intp)
-    cost = 0.0
-    if len(assignment) > 0:
-        cost = float(
-            np.sum(
-                flow[edge_idx] * edges[edge_idx].cost for edge_idx in range(len(edges))
-            )
-        )
+        # Task edges: from task nodes (m+1..m+n) to sink
+        if m + 1 <= edge.from_node <= m + n and edge.to_node == sink:
+            task_id = edge.from_node - (m + 1)
+            task_inflow[task_id] += flow[edge_idx]
 
+        # Worker-to-task edges
+        if 1 <= edge.from_node <= m and m + 1 <= edge.to_node <= m + n:
+            worker_id = edge.from_node - 1
+            task_id = edge.to_node - (m + 1)
+            if flow[edge_idx] > 0.5:  # Positive flow means this edge is used
+                worker_task_edges.append(
+                    {
+                        "worker": worker_id,
+                        "task": task_id,
+                        "flow": flow[edge_idx],
+                        "cost": edge.cost,
+                        "edge_idx": edge_idx,
+                    }
+                )
+
+    # For assignment problems, each worker should have exactly 1 outgoing flow
+    # and each task should have exactly 1 incoming flow
+    # Extract the assignment from worker->task edges with positive flow
+    for edge_info in worker_task_edges:
+        assignment.append([edge_info["worker"], edge_info["task"]])
+        cost += edge_info["flow"] * edge_info["cost"]
+
+    assignment = (
+        np.array(assignment, dtype=np.intp)
+        if assignment
+        else np.empty((0, 2), dtype=np.intp)
+    )
     return assignment, cost
 
 

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0}/pytcl/astronomical/time_systems.py

@@ -269,6 +269,13 @@ def mjd_to_jd(mjd: float) -> float:
     float
         Julian Date.
 
+    Examples
+    --------
+    >>> mjd = 44239.0  # 1980-01-01
+    >>> jd = mjd_to_jd(mjd)
+    >>> jd
+    2444239.5
+
     Notes
     -----
     MJD = JD - 2400000.5
@@ -289,6 +296,13 @@ def jd_to_mjd(jd: float) -> float:
     -------
     float
         Modified Julian Date.
+
+    Examples
+    --------
+    >>> jd = 2444239.5  # 1980-01-01
+    >>> mjd = jd_to_mjd(jd)
+    >>> mjd
+    44239.0
     """
     return jd - MJD_OFFSET
 
@@ -328,6 +342,13 @@ def jd_to_unix(jd: float) -> float:
     -------
     float
         Unix timestamp.
+
+    Examples
+    --------
+    >>> jd = 2440587.5  # 1970-01-01 00:00:00 UTC
+    >>> unix_to_jd = jd_to_unix(jd)
+    >>> unix_to_jd
+    0.0
     """
     return (jd - JD_UNIX_EPOCH) * 86400.0
 

{nrl_tracker-1.11.0 → nrl_tracker-1.12.0}/pytcl/containers/cluster_set.py

@@ -94,6 +94,23 @@ def compute_cluster_centroid(
     -------
     centroid : ndarray
         Centroid position [x, y].
+
+    Examples
+    --------
+    >>> from pytcl.trackers.multi_target import Track
+    >>> import numpy as np
+    >>> # Create sample tracks with [x, vx, y, vy] state vectors
+    >>> track1 = Track(state=np.array([0.0, 1.0, 0.0, 1.0]))
+    >>> track2 = Track(state=np.array([2.0, 1.0, 2.0, 1.0]))
+    >>> track3 = Track(state=np.array([4.0, 1.0, 4.0, 1.0]))
+    >>> tracks = [track1, track2, track3]
+    >>> centroid = compute_cluster_centroid(tracks)
+    >>> centroid
+    array([2., 2.])
+
+    See Also
+    --------
+    compute_cluster_covariance : Compute covariance of track positions.
     """
     track_list = list(tracks)
     if len(track_list) == 0:
@@ -122,6 +139,25 @@ def compute_cluster_covariance(
     -------
     covariance : ndarray
         Position covariance matrix (2x2).
+
+    Examples
+    --------
+    >>> from pytcl.trackers.multi_target import Track
+    >>> import numpy as np
+    >>> # Create collinear tracks (high variance along x-axis)
+    >>> track1 = Track(state=np.array([0.0, 1.0, 0.0, 0.0]))
+    >>> track2 = Track(state=np.array([1.0, 1.0, 0.0, 0.0]))
+    >>> track3 = Track(state=np.array([2.0, 1.0, 0.0, 0.0]))
+    >>> tracks = [track1, track2, track3]
+    >>> cov = compute_cluster_covariance(tracks)
+    >>> cov.shape
+    (2, 2)
+    >>> cov[0, 0] > cov[1, 1]  # More spread in x than y
+    True
+
+    See Also
+    --------
+    compute_cluster_centroid : Compute centroid of track positions.
     """
     track_list = list(tracks)
     if len(track_list) < 2: