nrl-tracker 1.9.1__tar.gz → 1.9.2__tar.gz

{nrl_tracker-1.9.1/nrl_tracker.egg-info → nrl_tracker-1.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.9.1
+Version: 1.9.2
 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
@@ -63,17 +63,17 @@ Requires-Dist: nrl-tracker[astronomy,dev,geodesy,optimization,signal,visualizati
 
 # Tracker Component Library (Python)
 
-[![PyPI version](https://img.shields.io/badge/pypi-v1.9.0-blue.svg)](https://pypi.org/project/nrl-tracker/)
+[![PyPI version](https://img.shields.io/badge/pypi-v1.9.2-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-1988%20passing-success.svg)](https://github.com/nedonatelli/TCL)
+[![Tests](https://img.shields.io/badge/tests-2133%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** | **1,988 tests** | **100% MATLAB parity**
+**1,070+ functions** | **153 modules** | **2,133 tests** | **100% MATLAB parity**
 
 ## Overview
 

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/README.md

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

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2/nrl_tracker.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.9.1
+Version: 1.9.2
 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
@@ -63,17 +63,17 @@ Requires-Dist: nrl-tracker[astronomy,dev,geodesy,optimization,signal,visualizati
 
 # Tracker Component Library (Python)
 
-[![PyPI version](https://img.shields.io/badge/pypi-v1.9.0-blue.svg)](https://pypi.org/project/nrl-tracker/)
+[![PyPI version](https://img.shields.io/badge/pypi-v1.9.2-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-1988%20passing-success.svg)](https://github.com/nedonatelli/TCL)
+[![Tests](https://img.shields.io/badge/tests-2133%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** | **1,988 tests** | **100% MATLAB parity**
+**1,070+ functions** | **153 modules** | **2,133 tests** | **100% MATLAB parity**
 
 ## Overview
 

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/nrl_tracker.egg-info/SOURCES.txt

@@ -65,6 +65,7 @@ pytcl/core/__init__.py
 pytcl/core/array_utils.py
 pytcl/core/constants.py
 pytcl/core/exceptions.py
+pytcl/core/maturity.py
 pytcl/core/optional_deps.py
 pytcl/core/validation.py
 pytcl/dynamic_estimation/__init__.py

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nrl-tracker"
-version = "1.9.1"
+version = "1.9.2"
 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.9.1 → nrl_tracker-1.9.2}/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.9.1 (January 4, 2026)
+**Current Version:** 1.9.2 (January 4, 2026)
 **Status:** Production-ready, 2,133 tests passing, 76% line coverage
 Examples
 --------
@@ -21,7 +21,7 @@ References
        no. 5, pp. 18-27, May 2017.
 """
 
-__version__ = "1.9.1"
+__version__ = "1.9.2"
 __author__ = "Python Port Contributors"
 __original_author__ = "David F. Crouse, Naval Research Laboratory"
 

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/pytcl/assignment_algorithms/gating.py

@@ -322,6 +322,24 @@ def compute_gate_volume(
         V = c_m * sqrt(det(S)) * gamma^(m/2)
 
     where c_m is the volume of the unit hypersphere in m dimensions.
+
+    Examples
+    --------
+    Compute gate volume for a 2D measurement with 99% gate probability:
+
+    >>> import numpy as np
+    >>> from scipy.stats import chi2
+    >>> S = np.array([[4.0, 0.0], [0.0, 1.0]])  # innovation covariance
+    >>> gate_prob = 0.99
+    >>> threshold = chi2.ppf(gate_prob, df=2)
+    >>> volume = compute_gate_volume(S, threshold)
+    >>> volume > 0
+    True
+
+    See Also
+    --------
+    ellipsoidal_gate : Test if measurement passes gate.
+    mahalanobis_distance : Compute distance used in gating.
     """
     S = np.asarray(innovation_covariance, dtype=np.float64)
     m = S.shape[0]

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/pytcl/assignment_algorithms/jpda.py

@@ -136,6 +136,22 @@ def compute_likelihood_matrix(
         Likelihood values, shape (n_tracks, n_meas).
     gated : ndarray[Any]
         Boolean gating matrix, shape (n_tracks, n_meas).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Two tracks, two measurements
+    >>> states = [np.array([0.0, 1.0]), np.array([5.0, 0.0])]
+    >>> covs = [np.eye(2) * 0.5, np.eye(2) * 0.5]
+    >>> measurements = np.array([[0.1], [5.2]])
+    >>> H = np.array([[1, 0]])
+    >>> R = np.array([[0.1]])
+    >>> L, gated = compute_likelihood_matrix(states, covs, measurements, H, R)
+    >>> L.shape
+    (2, 2)
+    >>> # Track 0 should have high likelihood for measurement 0
+    >>> L[0, 0] > L[0, 1]
+    True
     """
     n_tracks = len(track_states)
     n_meas = len(measurements)
@@ -191,6 +207,23 @@ def jpda_probabilities(
         Association probability matrix, shape (n_tracks, n_meas + 1).
         beta[i, j] = P(measurement j is from track i) for j < n_meas.
         beta[i, n_meas] = P(track i has no measurement).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Likelihood matrix: 2 tracks, 2 measurements
+    >>> # Track 0 has high likelihood for meas 0
+    >>> # Track 1 has high likelihood for meas 1
+    >>> likelihood = np.array([[0.9, 0.1],
+    ...                        [0.1, 0.8]])
+    >>> gated = np.array([[True, True],
+    ...                   [True, True]])
+    >>> beta = jpda_probabilities(likelihood, gated, detection_prob=0.9)
+    >>> beta.shape  # 2 tracks, 3 columns (2 meas + 1 miss)
+    (2, 3)
+    >>> # Track 0 most likely associated with measurement 0
+    >>> np.argmax(beta[0, :2])
+    0
     """
     n_tracks, n_meas = likelihood_matrix.shape
 
@@ -591,6 +624,29 @@ def jpda(
     -------
     result : JPDAResult
         Association probabilities and related information.
+
+    Examples
+    --------
+    Compute association probabilities for 2 tracks and 3 measurements:
+
+    >>> import numpy as np
+    >>> # Two tracks with [x, vx] state
+    >>> states = [np.array([0.0, 1.0]), np.array([10.0, -0.5])]
+    >>> covariances = [np.eye(2) * 0.5, np.eye(2) * 0.5]
+    >>> # Three position measurements
+    >>> measurements = np.array([[0.1], [9.8], [5.0]])
+    >>> H = np.array([[1, 0]])  # measure position only
+    >>> R = np.array([[0.1]])
+    >>> result = jpda(states, covariances, measurements, H, R)
+    >>> result.association_probs.shape  # (2 tracks, 4 columns: 3 meas + miss)
+    (2, 4)
+    >>> # Track 0 should have high prob for measurement 0
+    >>> result.association_probs[0, 0] > 0.5
+    True
+
+    See Also
+    --------
+    jpda_update : JPDA with state update.
     """
     # Convert inputs
     track_states = [np.asarray(x, dtype=np.float64).flatten() for x in track_states]

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/pytcl/assignment_algorithms/nd_assignment.py

@@ -67,6 +67,20 @@ def validate_cost_tensor(cost_tensor: NDArray[np.float64]) -> Tuple[int, ...]:
     ------
     ValueError
         If tensor has fewer than 2 dimensions.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> cost = np.random.rand(3, 4, 5)
+    >>> dims = validate_cost_tensor(cost)
+    >>> dims
+    (3, 4, 5)
+    >>> # 1D tensor should raise error
+    >>> try:
+    ...     validate_cost_tensor(np.array([1, 2, 3]))
+    ... except ValueError:
+    ...     print("Caught expected error")
+    Caught expected error
     """
     if cost_tensor.ndim < 2:
         raise ValueError(
@@ -98,6 +112,21 @@ def greedy_assignment_nd(
     AssignmentNDResult
         Assignments, total cost, and algorithm info.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 3D cost tensor: 3 measurements x 2 tracks x 2 hypotheses
+    >>> cost = np.array([
+    ...     [[1.0, 5.0], [3.0, 2.0]],   # meas 0
+    ...     [[4.0, 1.0], [2.0, 6.0]],   # meas 1
+    ...     [[2.0, 3.0], [5.0, 1.0]],   # meas 2
+    ... ])
+    >>> result = greedy_assignment_nd(cost)
+    >>> result.cost  # Total cost of greedy solution
+    4.0
+    >>> len(result.assignments)  # Number of assignments made
+    2
+
     Notes
     -----
     Greedy assignment is fast O(n log n) but not optimal. Used as
@@ -178,6 +207,18 @@ def relaxation_assignment_nd(
     AssignmentNDResult
         Assignments, total cost, convergence info, and optimality gap.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 3x3x3 assignment problem
+    >>> np.random.seed(42)
+    >>> cost = np.random.rand(3, 3, 3)
+    >>> result = relaxation_assignment_nd(cost, max_iterations=50)
+    >>> result.converged
+    True
+    >>> result.assignments.shape[1]  # 3D assignments
+    3
+
     Notes
     -----
     The relaxation approach:
@@ -297,6 +338,18 @@ def auction_assignment_nd(
     AssignmentNDResult
         Assignments, total cost, convergence info, gap estimate.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 4D assignment: sensors x measurements x tracks x hypotheses
+    >>> np.random.seed(123)
+    >>> cost = np.random.rand(2, 3, 3, 2) * 10
+    >>> result = auction_assignment_nd(cost, max_iterations=50, epsilon=0.1)
+    >>> len(result.assignments) > 0
+    True
+    >>> result.n_iterations <= 50
+    True
+
     Notes
     -----
     The algorithm maintains a "price" for each index and allows bidding
@@ -368,6 +421,18 @@ def detect_dimension_conflicts(
     -------
     has_conflicts : bool
         True if any index appears more than once in any dimension.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Valid assignment: no index repeated in any dimension
+    >>> assignments = np.array([[0, 0], [1, 1]])
+    >>> detect_dimension_conflicts(assignments, (3, 3))
+    False
+    >>> # Invalid: index 0 used twice in first dimension
+    >>> assignments = np.array([[0, 0], [0, 1]])
+    >>> detect_dimension_conflicts(assignments, (3, 3))
+    True
     """
     n_dims = len(dims)
 

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/pytcl/assignment_algorithms/network_flow.py

@@ -104,6 +104,20 @@ def assignment_to_flow_network(
         Positive = supply, negative = demand.
     node_names : ndarray
         Names of nodes for reference.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 2 workers, 3 tasks
+    >>> cost = np.array([[1.0, 2.0, 3.0],
+    ...                  [4.0, 5.0, 6.0]])
+    >>> edges, supplies, names = assignment_to_flow_network(cost)
+    >>> len(edges)  # source->workers + workers->tasks + tasks->sink
+    11
+    >>> supplies[0]  # source supplies 2 (num workers)
+    2.0
+    >>> names[0]
+    'source'
     """
     m, n = cost_matrix.shape
 
@@ -187,6 +201,20 @@ def min_cost_flow_successive_shortest_paths(
     MinCostFlowResult
         Solution with flow values, cost, status, and iterations.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.assignment_algorithms.network_flow import (
+    ...     FlowEdge, assignment_to_flow_network
+    ... )
+    >>> cost = np.array([[1.0, 5.0], [4.0, 2.0]])
+    >>> edges, supplies, _ = assignment_to_flow_network(cost)
+    >>> result = min_cost_flow_successive_shortest_paths(edges, supplies)
+    >>> result.status == FlowStatus.OPTIMAL
+    True
+    >>> result.cost  # Optimal is 1+2=3 (diagonal)
+    3.0
+
     Notes
     -----
     This is a simplified implementation using Bellman-Ford for shortest
@@ -445,6 +473,18 @@ def min_cost_assignment_via_flow(
     total_cost : float
         Total assignment cost.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> cost = np.array([[1.0, 5.0, 9.0],
+    ...                  [3.0, 2.0, 8.0],
+    ...                  [7.0, 6.0, 4.0]])
+    >>> assignment, total_cost = min_cost_assignment_via_flow(cost)
+    >>> total_cost  # Optimal assignment: (0,0), (1,1), (2,2) = 1+2+4 = 7
+    7.0
+    >>> len(assignment)
+    3
+
     Notes
     -----
     Phase 1B: Dijkstra-based optimization provides O(K*E log V) vs

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/pytcl/astronomical/ephemerides.py

@@ -446,6 +446,12 @@ def sun_position(
     velocity : ndarray, shape (3,)
         Sun velocity in AU/day
 
+    Examples
+    --------
+    >>> r, v = sun_position(2451545.0)  # J2000.0  # doctest: +SKIP
+    >>> np.linalg.norm(r)  # Distance from SSB  # doctest: +SKIP
+    0.00...
+
     See Also
     --------
     DEEphemeris.sun_position : Full ephemeris class with caching
@@ -473,6 +479,12 @@ def moon_position(
     velocity : ndarray, shape (3,)
         Moon velocity in AU/day
 
+    Examples
+    --------
+    >>> r, v = moon_position(2451545.0, 'earth_centered')  # doctest: +SKIP
+    >>> np.linalg.norm(r) * 149597870.7  # Distance in km  # doctest: +SKIP
+    402...
+
     See Also
     --------
     DEEphemeris.moon_position : Full ephemeris class with caching
@@ -533,5 +545,11 @@ def barycenter_position(
     velocity : ndarray, shape (3,)
         Velocity in AU/day
 
+    Examples
+    --------
+    >>> r, v = barycenter_position('mars', 2451545.0)  # doctest: +SKIP
+    >>> np.linalg.norm(r)  # Mars distance from SSB  # doctest: +SKIP
+    1.4...
+
     """
     return _get_default_ephemeris().barycenter_position(body, jd)

{nrl_tracker-1.9.1 → nrl_tracker-1.9.2}/pytcl/astronomical/orbital_mechanics.py

@@ -157,6 +157,12 @@ def mean_to_hyperbolic_anomaly(
     -------
     H : float
         Hyperbolic anomaly (radians).
+
+    Examples
+    --------
+    >>> H = mean_to_hyperbolic_anomaly(1.0, 1.5)
+    >>> abs(1.5 * np.sinh(H) - H - 1.0) < 1e-10
+    True
     """
     if e <= 1:
         raise ValueError(f"Eccentricity must be > 1 for hyperbolic orbits, got {e}")
@@ -196,6 +202,12 @@ def eccentric_to_true_anomaly(E: float, e: float) -> float:
     -------
     nu : float
         True anomaly (radians), in [0, 2*pi).
+
+    Examples
+    --------
+    >>> nu = eccentric_to_true_anomaly(np.pi/4, 0.5)
+    >>> 0 <= nu < 2 * np.pi
+    True
     """
     # Use half-angle formula for numerical stability
     nu = 2 * np.arctan2(np.sqrt(1 + e) * np.sin(E / 2), np.sqrt(1 - e) * np.cos(E / 2))
@@ -217,6 +229,12 @@ def true_to_eccentric_anomaly(nu: float, e: float) -> float:
     -------
     E : float
         Eccentric anomaly (radians), in [0, 2*pi).
+
+    Examples
+    --------
+    >>> E = true_to_eccentric_anomaly(np.pi/3, 0.5)
+    >>> 0 <= E < 2 * np.pi
+    True
     """
     E = 2 * np.arctan2(np.sqrt(1 - e) * np.sin(nu / 2), np.sqrt(1 + e) * np.cos(nu / 2))
     return E % (2 * np.pi)
@@ -237,6 +255,12 @@ def hyperbolic_to_true_anomaly(H: float, e: float) -> float:
     -------
     nu : float
         True anomaly (radians).
+
+    Examples
+    --------
+    >>> nu = hyperbolic_to_true_anomaly(0.5, 1.5)
+    >>> isinstance(nu, float)
+    True
     """
     nu = 2 * np.arctan(np.sqrt((e + 1) / (e - 1)) * np.tanh(H / 2))
     return nu
@@ -277,6 +301,12 @@ def eccentric_to_mean_anomaly(E: float, e: float) -> float:
     -------
     M : float
         Mean anomaly (radians).
+
+    Examples
+    --------
+    >>> M = eccentric_to_mean_anomaly(np.pi/4, 0.5)
+    >>> 0 <= M < 2 * np.pi
+    True
     """
     M = E - e * np.sin(E)
     return M % (2 * np.pi)
@@ -297,6 +327,12 @@ def mean_to_true_anomaly(M: float, e: float) -> float:
     -------
     nu : float
         True anomaly (radians).
+
+    Examples
+    --------
+    >>> nu = mean_to_true_anomaly(np.pi/4, 0.1)
+    >>> 0 <= nu < 2 * np.pi
+    True
     """
     if e < 1:
         E = mean_to_eccentric_anomaly(M, e)
@@ -514,6 +550,12 @@ def orbital_period(a: float, mu: float = GM_EARTH) -> float:
     -------
     T : float
         Orbital period (seconds).
+
+    Examples
+    --------
+    >>> T = orbital_period(7000)  # LEO satellite
+    >>> T / 60  # Convert to minutes  # doctest: +SKIP
+    97.8...
     """
     if a <= 0:
         raise ValueError("Semi-major axis must be positive for elliptic orbits")
@@ -535,6 +577,13 @@ def mean_motion(a: float, mu: float = GM_EARTH) -> float:
     -------
     n : float
         Mean motion (radians/second).
+
+    Examples
+    --------
+    >>> n = mean_motion(42164)  # GEO orbit
+    >>> revs_per_day = n * 86400 / (2 * np.pi)
+    >>> abs(revs_per_day - 1.0) < 0.01  # Approximately 1 rev/day
+    True
     """
     return np.sqrt(mu / abs(a) ** 3)
 
@@ -607,6 +656,15 @@ def kepler_propagate_state(
     -------
     new_state : StateVector
         Propagated state vector.
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])
+    >>> state = StateVector(r=r, v=v)
+    >>> new_state = kepler_propagate_state(state, 3600)
+    >>> np.linalg.norm(new_state.r) > 0
+    True
     """
     elements = state_to_orbital_elements(state, mu)
     new_elements = kepler_propagate(elements, dt, mu)
@@ -630,6 +688,12 @@ def vis_viva(r: float, a: float, mu: float = GM_EARTH) -> float:
     -------
     v : float
         Orbital velocity (km/s).
+
+    Examples
+    --------
+    >>> v = vis_viva(7000, 7000)  # Circular orbit
+    >>> abs(v - circular_velocity(7000)) < 0.01
+    True
     """
     return np.sqrt(mu * (2 / r - 1 / a))
 
@@ -649,6 +713,15 @@ def specific_angular_momentum(
     -------
     h : ndarray
         Specific angular momentum vector (km^2/s).
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])
+    >>> state = StateVector(r=r, v=v)
+    >>> h = specific_angular_momentum(state)
+    >>> h[2]  # Angular momentum in z-direction
+    52500.0
     """
     return np.cross(state.r, state.v)
 
@@ -672,6 +745,15 @@ def specific_orbital_energy(
     energy : float
         Specific orbital energy (km^2/s^2).
         Negative for bound orbits, positive for escape trajectories.
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])
+    >>> state = StateVector(r=r, v=v)
+    >>> energy = specific_orbital_energy(state)
+    >>> energy < 0  # Bound orbit
+    True
     """
     r_mag = np.linalg.norm(state.r)
     v_mag = np.linalg.norm(state.v)
@@ -692,6 +774,15 @@ def flight_path_angle(state: StateVector) -> float:
     gamma : float
         Flight path angle (radians).
         Positive when climbing, negative when descending.
+
+    Examples
+    --------
+    >>> r = np.array([7000.0, 0.0, 0.0])
+    >>> v = np.array([0.0, 7.5, 0.0])  # Tangential velocity
+    >>> state = StateVector(r=r, v=v)
+    >>> gamma = flight_path_angle(state)
+    >>> abs(gamma) < 0.01  # Nearly zero for circular motion
+    True
     """
     r = np.asarray(state.r)
     v = np.asarray(state.v)
@@ -720,6 +811,12 @@ def periapsis_radius(a: float, e: float) -> float:
     -------
     r_p : float
         Periapsis radius (km).
+
+    Examples
+    --------
+    >>> r_p = periapsis_radius(10000, 0.3)
+    >>> r_p
+    7000.0
     """
     return a * (1 - e)
 
@@ -739,6 +836,12 @@ def apoapsis_radius(a: float, e: float) -> float:
     -------
     r_a : float
         Apoapsis radius (km). Infinite for parabolic/hyperbolic orbits.
+
+    Examples
+    --------
+    >>> r_a = apoapsis_radius(10000, 0.3)
+    >>> r_a
+    13000.0
     """
     if e >= 1:
         return np.inf
@@ -769,6 +872,13 @@ def time_since_periapsis(
     -------
     t : float
         Time since periapsis (seconds).
+
+    Examples
+    --------
+    >>> t = time_since_periapsis(np.pi, 7000, 0.1)  # At apoapsis
+    >>> T = orbital_period(7000)
+    >>> abs(t - T/2) < 1  # Approximately half the period
+    True
     """
     M = true_to_mean_anomaly(nu, e)
     n = mean_motion(a, mu)
@@ -792,6 +902,15 @@ def orbit_radius(nu: float, a: float, e: float) -> float:
     -------
     r : float
         Orbital radius (km).
+
+    Examples
+    --------
+    >>> r = orbit_radius(0, 10000, 0.3)  # At periapsis
+    >>> r
+    7000.0
+    >>> r = orbit_radius(np.pi, 10000, 0.3)  # At apoapsis
+    >>> r
+    13000.0
     """
     p = a * (1 - e * e)
     return p / (1 + e * np.cos(nu))
@@ -812,6 +931,12 @@ def escape_velocity(r: float, mu: float = GM_EARTH) -> float:
     -------
     v_esc : float
         Escape velocity (km/s).
+
+    Examples
+    --------
+    >>> v_esc = escape_velocity(6378 + 400)  # At ISS altitude
+    >>> 10 < v_esc < 12  # About 11 km/s
+    True
     """
     return np.sqrt(2 * mu / r)
 
@@ -831,6 +956,12 @@ def circular_velocity(r: float, mu: float = GM_EARTH) -> float:
     -------
     v_circ : float
         Circular velocity (km/s).
+
+    Examples
+    --------
+    >>> v_circ = circular_velocity(6378 + 400)  # At ISS altitude
+    >>> 7 < v_circ < 8  # About 7.7 km/s
+    True
     """
     return np.sqrt(mu / r)