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

pytcl/coordinate_systems/rotations/rotations.py

@@ -135,6 +135,12 @@ def roty(angle: float) -> NDArray[np.floating]:
     -------
     R : ndarray
         3x3 rotation matrix.
+
+    Examples
+    --------
+    >>> R = roty(np.pi/2)  # 90 degree rotation about y
+    >>> R @ [1, 0, 0]  # x-axis maps to -z-axis
+    array([ 0.,  0., -1.])
     """
     c = np.cos(angle)
     s = np.sin(angle)
@@ -154,6 +160,12 @@ def rotz(angle: float) -> NDArray[np.floating]:
     -------
     R : ndarray
         3x3 rotation matrix.
+
+    Examples
+    --------
+    >>> R = rotz(np.pi/2)  # 90 degree rotation about z
+    >>> R @ [1, 0, 0]  # x-axis maps to y-axis
+    array([0., 1., 0.])
     """
     c = np.cos(angle)
     s = np.sin(angle)
@@ -225,6 +237,13 @@ def rotmat2euler(
     angles : ndarray
         Three Euler angles in radians.
 
+    Examples
+    --------
+    >>> R = rotz(np.radians(45)) @ roty(np.radians(30)) @ rotx(np.radians(15))
+    >>> angles = rotmat2euler(R, 'ZYX')
+    >>> np.degrees(angles)
+    array([45., 30., 15.])
+
     Notes
     -----
     May have singularities (gimbal lock) at certain angles.
@@ -298,6 +317,13 @@ def axisangle2rotmat(
     R : ndarray
         3x3 rotation matrix.
 
+    Examples
+    --------
+    >>> axis = [0, 0, 1]  # Z-axis
+    >>> R = axisangle2rotmat(axis, np.pi/2)  # 90 deg about Z
+    >>> R @ [1, 0, 0]  # x-axis maps to y-axis
+    array([0., 1., 0.])
+
     Notes
     -----
     Uses Rodrigues' rotation formula.
@@ -340,6 +366,15 @@ def rotmat2axisangle(
         Unit vector rotation axis.
     angle : float
         Rotation angle in radians [0, π].
+
+    Examples
+    --------
+    >>> R = rotz(np.pi/2)  # 90 deg about Z
+    >>> axis, angle = rotmat2axisangle(R)
+    >>> axis  # Z-axis
+    array([0., 0., 1.])
+    >>> np.degrees(angle)
+    90.0
     """
     R = np.asarray(R, dtype=np.float64)
 
@@ -417,6 +452,12 @@ def rotmat2quat(R: ArrayLike) -> NDArray[np.floating]:
     q : ndarray
         Quaternion [qw, qx, qy, qz] (scalar-first, positive qw).
 
+    Examples
+    --------
+    >>> R = np.eye(3)  # Identity rotation
+    >>> rotmat2quat(R)
+    array([1., 0., 0., 0.])
+
     Notes
     -----
     Uses Shepperd's method for numerical stability.
@@ -477,6 +518,25 @@ def euler2quat(
     -------
     q : ndarray
         Quaternion [qw, qx, qy, qz].
+
+    Examples
+    --------
+    Convert yaw-pitch-roll angles to quaternion:
+
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems.rotations import euler2quat
+    >>> # 45° yaw, 30° pitch, 0° roll
+    >>> angles = np.radians([45, 30, 0])
+    >>> q = euler2quat(angles, sequence='ZYX')
+    >>> q.shape
+    (4,)
+    >>> np.abs(q[0]) > 0.5  # scalar part should be significant
+    True
+
+    See Also
+    --------
+    quat2euler : Inverse conversion.
+    euler2rotmat : Convert to rotation matrix instead.
     """
     R = euler2rotmat(angles, sequence)
     return rotmat2quat(R)
@@ -500,6 +560,13 @@ def quat2euler(
     -------
     angles : ndarray
         Three Euler angles in radians.
+
+    Examples
+    --------
+    >>> q = [1, 0, 0, 0]  # Identity quaternion
+    >>> angles = quat2euler(q, 'ZYX')
+    >>> np.allclose(angles, [0, 0, 0])
+    True
     """
     R = quat2rotmat(q)
     return rotmat2euler(R, sequence)
@@ -525,6 +592,26 @@ def quat_multiply(q1: ArrayLike, q2: ArrayLike) -> NDArray[np.floating]:
     -----
     Quaternion multiplication represents composition of rotations.
     q1 * q2 applies q2 first, then q1.
+
+    Examples
+    --------
+    Combine two rotations using quaternion multiplication:
+
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems.rotations import quat_multiply, euler2quat
+    >>> # 90° rotation about Z, then 45° about X
+    >>> q_z90 = euler2quat(np.radians([90, 0, 0]), 'ZYX')
+    >>> q_x45 = euler2quat(np.radians([0, 0, 45]), 'ZYX')
+    >>> q_combined = quat_multiply(q_z90, q_x45)
+    >>> q_combined.shape
+    (4,)
+    >>> np.isclose(np.linalg.norm(q_combined), 1.0)  # unit quaternion
+    True
+
+    See Also
+    --------
+    quat_inverse : Compute quaternion inverse.
+    quat_rotate : Rotate a vector by a quaternion.
     """
     q1 = np.asarray(q1, dtype=np.float64)
     q2 = np.asarray(q2, dtype=np.float64)
@@ -556,6 +643,11 @@ def quat_conjugate(q: ArrayLike) -> NDArray[np.floating]:
     -------
     q_conj : ndarray
         Conjugate quaternion [qw, -qx, -qy, -qz].
+
+    Examples
+    --------
+    >>> quat_conjugate([0.707, 0.707, 0, 0])
+    array([ 0.707, -0.707, -0.   , -0.   ])
     """
     q = np.asarray(q, dtype=np.float64)
     return np.array([q[0], -q[1], -q[2], -q[3]], dtype=np.float64)
@@ -575,6 +667,13 @@ def quat_inverse(q: ArrayLike) -> NDArray[np.floating]:
     q_inv : ndarray
         Inverse quaternion.
 
+    Examples
+    --------
+    >>> q = euler2quat(np.radians([45, 0, 0]), 'ZYX')
+    >>> q_inv = quat_inverse(q)
+    >>> quat_multiply(q, q_inv)  # Should be identity
+    array([1., 0., 0., 0.])
+
     Notes
     -----
     For unit quaternions, inverse equals conjugate.
@@ -599,6 +698,15 @@ def quat_rotate(q: ArrayLike, v: ArrayLike) -> NDArray[np.floating]:
     v_rot : ndarray
         Rotated vector.
 
+    Examples
+    --------
+    >>> # 90 degree rotation about z-axis
+    >>> q = euler2quat(np.radians([90, 0, 0]), 'ZYX')
+    >>> v = np.array([1.0, 0.0, 0.0])
+    >>> v_rot = quat_rotate(q, v)
+    >>> v_rot  # x-axis becomes y-axis
+    array([0., 1., 0.])
+
     Notes
     -----
     Computes q * v * q^(-1) where v is treated as a pure quaternion.
@@ -632,6 +740,15 @@ def slerp(
     -------
     q : ndarray
         Interpolated quaternion.
+
+    Examples
+    --------
+    >>> q1 = np.array([1, 0, 0, 0])  # identity
+    >>> q2 = euler2quat(np.radians([90, 0, 0]), 'ZYX')  # 90 deg about z
+    >>> q_mid = slerp(q1, q2, 0.5)  # halfway = 45 deg
+    >>> angles = quat2euler(q_mid, 'ZYX')
+    >>> np.degrees(angles[0])  # yaw should be ~45
+    45.0...
     """
     q1 = np.asarray(q1, dtype=np.float64)
     q2 = np.asarray(q2, dtype=np.float64)
@@ -674,6 +791,13 @@ def rodrigues2rotmat(rvec: ArrayLike) -> NDArray[np.floating]:
     R : ndarray
         3x3 rotation matrix.
 
+    Examples
+    --------
+    >>> rvec = [0, 0, np.pi/2]  # 90 deg about Z
+    >>> R = rodrigues2rotmat(rvec)
+    >>> R @ [1, 0, 0]  # x-axis maps to y-axis
+    array([0., 1., 0.])
+
     Notes
     -----
     The Rodrigues vector encodes both the rotation axis and angle:
@@ -702,6 +826,13 @@ def rotmat2rodrigues(R: ArrayLike) -> NDArray[np.floating]:
     -------
     rvec : ndarray
         Rodrigues vector (axis * angle).
+
+    Examples
+    --------
+    >>> R = rotz(np.pi/2)  # 90 deg about Z
+    >>> rvec = rotmat2rodrigues(R)
+    >>> np.linalg.norm(rvec)  # magnitude is the angle
+    1.5707...
     """
     axis, angle = rotmat2axisangle(R)
     return axis * angle
@@ -726,6 +857,14 @@ def dcm_rate(
     R_dot : ndarray
         Time derivative of R.
 
+    Examples
+    --------
+    >>> R = np.eye(3)
+    >>> omega = [0, 0, 1]  # 1 rad/s about Z
+    >>> R_dot = dcm_rate(R, omega)
+    >>> R_dot[0, 1]  # Off-diagonal elements show rotation
+    -1.0
+
     Notes
     -----
     R_dot = R @ skew(omega)
@@ -756,6 +895,14 @@ def is_rotation_matrix(R: ArrayLike, tol: float = 1e-6) -> bool:
     -------
     valid : bool
         True if R is a valid rotation matrix.
+
+    Examples
+    --------
+    >>> R = rotx(np.pi/4)
+    >>> is_rotation_matrix(R)
+    True
+    >>> is_rotation_matrix(np.eye(3) * 2)  # not orthonormal
+    False
     """
     R = np.asarray(R, dtype=np.float64)
 

pytcl/core/__init__.py

@@ -7,6 +7,7 @@ This module provides foundational functionality used throughout the library:
 - Array manipulation helpers compatible with MATLAB conventions
 - Custom exception hierarchy for consistent error handling
 - Optional dependency management
+- Module maturity classification system
 """
 
 from pytcl.core.array_utils import (
@@ -45,6 +46,14 @@ from pytcl.core.exceptions import (
     UninitializedError,
     ValidationError,
 )
+from pytcl.core.maturity import (
+    MaturityLevel,
+    get_maturity,
+    get_maturity_summary,
+    get_modules_by_maturity,
+    is_production_ready,
+    is_stable,
+)
 from pytcl.core.optional_deps import (
     LazyModule,
     check_dependencies,
@@ -125,4 +134,11 @@ __all__ = [
     "requires",
     "check_dependencies",
     "LazyModule",
+    # Maturity classification
+    "MaturityLevel",
+    "get_maturity",
+    "get_modules_by_maturity",
+    "get_maturity_summary",
+    "is_stable",
+    "is_production_ready",
 ]

pytcl/core/maturity.py

@@ -0,0 +1,346 @@
+"""
+Module maturity classification system for the Tracker Component Library.
+
+This module provides a standardized way to indicate the production-readiness
+and stability of different modules within pyTCL. The maturity levels help
+users understand which APIs are stable and which may change.
+
+Maturity Levels
+---------------
+STABLE (3)
+    Production-ready. Thoroughly tested, well-documented, and API is frozen.
+    Breaking changes only in major version bumps.
+
+MATURE (2)
+    Ready for production use. Good test coverage and documentation.
+    Minor API adjustments possible in minor versions.
+
+EXPERIMENTAL (1)
+    Functional but may change. Limited testing or documentation.
+    API may change in any release.
+
+DEPRECATED (0)
+    Scheduled for removal. Use the recommended replacement.
+
+Examples
+--------
+Check the maturity level of a module:
+
+>>> from pytcl.core.maturity import get_maturity, MaturityLevel
+>>> level = get_maturity("pytcl.dynamic_estimation.kalman.linear")
+>>> level == MaturityLevel.STABLE
+True
+
+List all stable modules:
+
+>>> from pytcl.core.maturity import get_modules_by_maturity, MaturityLevel
+>>> stable_modules = get_modules_by_maturity(MaturityLevel.STABLE)
+
+See Also
+--------
+pytcl.core.optional_deps : Optional dependency management.
+"""
+
+from enum import IntEnum
+from typing import Dict, List
+
+
+class MaturityLevel(IntEnum):
+    """Maturity level classification for modules.
+
+    Attributes
+    ----------
+    DEPRECATED : int
+        Level 0. Scheduled for removal.
+    EXPERIMENTAL : int
+        Level 1. Functional but unstable API.
+    MATURE : int
+        Level 2. Production-ready with possible minor changes.
+    STABLE : int
+        Level 3. Production-ready with frozen API.
+    """
+
+    DEPRECATED = 0
+    EXPERIMENTAL = 1
+    MATURE = 2
+    STABLE = 3
+
+
+# Module maturity classifications
+# Keys are module paths relative to pytcl (e.g., "dynamic_estimation.kalman.linear")
+MODULE_MATURITY: Dict[str, MaturityLevel] = {
+    # =========================================================================
+    # STABLE (3) - Production-ready, frozen API
+    # =========================================================================
+    # Core
+    "core.constants": MaturityLevel.STABLE,
+    "core.exceptions": MaturityLevel.STABLE,
+    "core.validation": MaturityLevel.STABLE,
+    "core.array_utils": MaturityLevel.STABLE,
+    "core.optional_deps": MaturityLevel.STABLE,
+    # Kalman Filters
+    "dynamic_estimation.kalman.linear": MaturityLevel.STABLE,
+    "dynamic_estimation.kalman.extended": MaturityLevel.STABLE,
+    "dynamic_estimation.kalman.unscented": MaturityLevel.STABLE,
+    "dynamic_estimation.kalman.types": MaturityLevel.STABLE,
+    "dynamic_estimation.kalman.matrix_utils": MaturityLevel.STABLE,
+    # Motion Models
+    "dynamic_models.constant_velocity": MaturityLevel.STABLE,
+    "dynamic_models.constant_acceleration": MaturityLevel.STABLE,
+    "dynamic_models.coordinated_turn": MaturityLevel.STABLE,
+    "dynamic_models.singer": MaturityLevel.STABLE,
+    "dynamic_models.process_noise.constant_velocity": MaturityLevel.STABLE,
+    "dynamic_models.process_noise.constant_acceleration": MaturityLevel.STABLE,
+    # Coordinate Systems
+    "coordinate_systems.conversions.geodetic": MaturityLevel.STABLE,
+    "coordinate_systems.conversions.spherical": MaturityLevel.STABLE,
+    "coordinate_systems.rotations.rotations": MaturityLevel.STABLE,
+    "coordinate_systems.rotations.quaternions": MaturityLevel.STABLE,
+    # Assignment Algorithms
+    "assignment_algorithms.hungarian": MaturityLevel.STABLE,
+    "assignment_algorithms.auction": MaturityLevel.STABLE,
+    "assignment_algorithms.gating": MaturityLevel.STABLE,
+    # Containers
+    "containers.kd_tree": MaturityLevel.STABLE,
+    "containers.base": MaturityLevel.STABLE,
+    # Mathematical Functions
+    "mathematical_functions.special": MaturityLevel.STABLE,
+    # =========================================================================
+    # MATURE (2) - Production-ready, minor changes possible
+    # =========================================================================
+    # Kalman Filters
+    "dynamic_estimation.kalman.square_root": MaturityLevel.MATURE,
+    "dynamic_estimation.kalman.ud_filter": MaturityLevel.MATURE,
+    "dynamic_estimation.kalman.sr_ukf": MaturityLevel.MATURE,
+    "dynamic_estimation.kalman.cubature": MaturityLevel.MATURE,
+    "dynamic_estimation.kalman.constrained": MaturityLevel.MATURE,
+    "dynamic_estimation.information_filter": MaturityLevel.MATURE,
+    "dynamic_estimation.imm": MaturityLevel.MATURE,
+    "dynamic_estimation.h_infinity": MaturityLevel.MATURE,
+    # Particle Filters
+    "dynamic_estimation.particle_filters.bootstrap": MaturityLevel.MATURE,
+    "dynamic_estimation.particle_filters.resampling": MaturityLevel.MATURE,
+    # Smoothers
+    "dynamic_estimation.smoothers.rts": MaturityLevel.MATURE,
+    "dynamic_estimation.smoothers.fixed_lag": MaturityLevel.MATURE,
+    # Motion Models
+    "dynamic_models.process_noise.coordinated_turn": MaturityLevel.MATURE,
+    "dynamic_models.process_noise.singer": MaturityLevel.MATURE,
+    # Assignment Algorithms
+    "assignment_algorithms.jpda": MaturityLevel.MATURE,
+    "assignment_algorithms.mht": MaturityLevel.MATURE,
+    "assignment_algorithms.murty": MaturityLevel.MATURE,
+    "assignment_algorithms.assignment_3d": MaturityLevel.MATURE,
+    # Containers
+    "containers.ball_tree": MaturityLevel.MATURE,
+    "containers.rtree": MaturityLevel.MATURE,
+    "containers.vptree": MaturityLevel.MATURE,
+    "containers.covertree": MaturityLevel.MATURE,
+    "containers.track_list": MaturityLevel.MATURE,
+    "containers.measurement_set": MaturityLevel.MATURE,
+    "containers.cluster_set": MaturityLevel.MATURE,
+    # Navigation
+    "navigation.ins.strapdown": MaturityLevel.MATURE,
+    "navigation.ins.error_model": MaturityLevel.MATURE,
+    "navigation.gnss.positioning": MaturityLevel.MATURE,
+    "navigation.geodesy": MaturityLevel.MATURE,
+    "navigation.great_circle": MaturityLevel.MATURE,
+    # Coordinate Systems
+    "coordinate_systems.jacobians.jacobians": MaturityLevel.MATURE,
+    "coordinate_systems.projections.utm": MaturityLevel.MATURE,
+    "coordinate_systems.projections.mercator": MaturityLevel.MATURE,
+    # Mathematical Functions
+    "mathematical_functions.signal_processing.filters": MaturityLevel.MATURE,
+    "mathematical_functions.signal_processing.detection": MaturityLevel.MATURE,
+    "mathematical_functions.transforms.fft": MaturityLevel.MATURE,
+    "mathematical_functions.transforms.wavelets": MaturityLevel.MATURE,
+    # Static Estimation
+    "static_estimation.least_squares": MaturityLevel.MATURE,
+    "static_estimation.robust": MaturityLevel.MATURE,
+    "static_estimation.ransac": MaturityLevel.MATURE,
+    # Astronomical
+    "astronomical.orbital_mechanics": MaturityLevel.MATURE,
+    "astronomical.ephemerides": MaturityLevel.MATURE,
+    "astronomical.reference_frames": MaturityLevel.MATURE,
+    # =========================================================================
+    # EXPERIMENTAL (1) - Functional but API may change
+    # =========================================================================
+    # Advanced Filters
+    "dynamic_estimation.kalman.gaussian_sum": MaturityLevel.EXPERIMENTAL,
+    "dynamic_estimation.kalman.rao_blackwellized": MaturityLevel.EXPERIMENTAL,
+    # Geophysical Models
+    "geophysical.gravity.egm": MaturityLevel.EXPERIMENTAL,
+    "geophysical.magnetism.wmm": MaturityLevel.EXPERIMENTAL,
+    "geophysical.tides": MaturityLevel.EXPERIMENTAL,
+    # Terrain
+    "terrain.dem": MaturityLevel.EXPERIMENTAL,
+    "terrain.loaders": MaturityLevel.EXPERIMENTAL,
+    "terrain.analysis": MaturityLevel.EXPERIMENTAL,
+    # Relativity
+    "astronomical.relativity": MaturityLevel.EXPERIMENTAL,
+    "astronomical.satellite.sgp4": MaturityLevel.EXPERIMENTAL,
+}
+
+
+def get_maturity(module_path: str) -> MaturityLevel:
+    """
+    Get the maturity level of a module.
+
+    Parameters
+    ----------
+    module_path : str
+        Module path relative to pytcl (e.g., "dynamic_estimation.kalman.linear")
+        or full path (e.g., "pytcl.dynamic_estimation.kalman.linear").
+
+    Returns
+    -------
+    MaturityLevel
+        The module's maturity level. Returns EXPERIMENTAL if not classified.
+
+    Examples
+    --------
+    >>> get_maturity("dynamic_estimation.kalman.linear")
+    <MaturityLevel.STABLE: 3>
+    >>> get_maturity("pytcl.core.constants")
+    <MaturityLevel.STABLE: 3>
+    """
+    # Strip pytcl. prefix if present
+    if module_path.startswith("pytcl."):
+        module_path = module_path[6:]
+
+    return MODULE_MATURITY.get(module_path, MaturityLevel.EXPERIMENTAL)
+
+
+def get_modules_by_maturity(level: MaturityLevel) -> List[str]:
+    """
+    Get all modules at a specific maturity level.
+
+    Parameters
+    ----------
+    level : MaturityLevel
+        The maturity level to filter by.
+
+    Returns
+    -------
+    list of str
+        Module paths at the specified maturity level.
+
+    Examples
+    --------
+    >>> stable = get_modules_by_maturity(MaturityLevel.STABLE)
+    >>> "core.constants" in stable
+    True
+    """
+    return [path for path, mat in MODULE_MATURITY.items() if mat == level]
+
+
+def get_maturity_summary() -> Dict[MaturityLevel, int]:
+    """
+    Get a summary count of modules at each maturity level.
+
+    Returns
+    -------
+    dict
+        Mapping from MaturityLevel to count of modules.
+
+    Examples
+    --------
+    >>> summary = get_maturity_summary()
+    >>> summary[MaturityLevel.STABLE] > 0
+    True
+    """
+    summary = {level: 0 for level in MaturityLevel}
+    for level in MODULE_MATURITY.values():
+        summary[level] += 1
+    return summary
+
+
+def is_stable(module_path: str) -> bool:
+    """
+    Check if a module is stable (production-ready with frozen API).
+
+    Parameters
+    ----------
+    module_path : str
+        Module path to check.
+
+    Returns
+    -------
+    bool
+        True if the module is stable.
+
+    Examples
+    --------
+    >>> is_stable("dynamic_estimation.kalman.linear")
+    True
+    >>> is_stable("terrain.dem")
+    False
+    """
+    return get_maturity(module_path) == MaturityLevel.STABLE
+
+
+def is_production_ready(module_path: str) -> bool:
+    """
+    Check if a module is production-ready (STABLE or MATURE).
+
+    Parameters
+    ----------
+    module_path : str
+        Module path to check.
+
+    Returns
+    -------
+    bool
+        True if the module is STABLE or MATURE.
+
+    Examples
+    --------
+    >>> is_production_ready("dynamic_estimation.kalman.linear")
+    True
+    >>> is_production_ready("dynamic_estimation.imm")
+    True
+    >>> is_production_ready("terrain.dem")
+    False
+    """
+    level = get_maturity(module_path)
+    return level >= MaturityLevel.MATURE
+
+
+def format_maturity_badge(level: MaturityLevel) -> str:
+    """
+    Get a formatted badge string for a maturity level.
+
+    Parameters
+    ----------
+    level : MaturityLevel
+        The maturity level.
+
+    Returns
+    -------
+    str
+        A badge string suitable for documentation.
+
+    Examples
+    --------
+    >>> format_maturity_badge(MaturityLevel.STABLE)
+    '|stable|'
+    """
+    badges = {
+        MaturityLevel.STABLE: "|stable|",
+        MaturityLevel.MATURE: "|mature|",
+        MaturityLevel.EXPERIMENTAL: "|experimental|",
+        MaturityLevel.DEPRECATED: "|deprecated|",
+    }
+    return badges.get(level, "|unknown|")
+
+
+__all__ = [
+    "MaturityLevel",
+    "MODULE_MATURITY",
+    "get_maturity",
+    "get_modules_by_maturity",
+    "get_maturity_summary",
+    "is_stable",
+    "is_production_ready",
+    "format_maturity_badge",
+]

pytcl/dynamic_estimation/gaussian_sum_filter.py

@@ -363,6 +363,33 @@ def gaussian_sum_filter_predict(
     -------
     components_new : list[GaussianComponent]
         Predicted components.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.dynamic_estimation.gaussian_sum_filter import GaussianComponent
+    >>> # Two-component mixture for position-velocity state
+    >>> comp1 = GaussianComponent(
+    ...     x=np.array([0.0, 1.0]),  # moving right
+    ...     P=np.eye(2) * 0.5,
+    ...     w=0.5
+    ... )
+    >>> comp2 = GaussianComponent(
+    ...     x=np.array([0.0, -1.0]),  # moving left
+    ...     P=np.eye(2) * 0.5,
+    ...     w=0.5
+    ... )
+    >>> components = [comp1, comp2]
+    >>> # Constant velocity dynamics
+    >>> dt = 0.1
+    >>> f = lambda x: np.array([x[0] + x[1] * dt, x[1]])
+    >>> F = np.array([[1, dt], [0, 1]])
+    >>> Q = np.eye(2) * 0.01
+    >>> predicted = gaussian_sum_filter_predict(components, f, F, Q)
+    >>> len(predicted)
+    2
+    >>> predicted[0].w  # weights unchanged in prediction
+    0.5
     """
     F = np.asarray(F, dtype=np.float64)
     Q = np.asarray(Q, dtype=np.float64)
@@ -401,6 +428,34 @@ def gaussian_sum_filter_update(
     -------
     components_new : list[GaussianComponent]
         Updated components with adapted weights.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.dynamic_estimation.gaussian_sum_filter import GaussianComponent
+    >>> # Two-component mixture
+    >>> comp1 = GaussianComponent(
+    ...     x=np.array([1.0, 0.5]),
+    ...     P=np.eye(2) * 0.5,
+    ...     w=0.5
+    ... )
+    >>> comp2 = GaussianComponent(
+    ...     x=np.array([3.0, 0.5]),
+    ...     P=np.eye(2) * 0.5,
+    ...     w=0.5
+    ... )
+    >>> components = [comp1, comp2]
+    >>> # Position measurement near component 1
+    >>> z = np.array([1.1])
+    >>> h = lambda x: np.array([x[0]])
+    >>> H = np.array([[1, 0]])
+    >>> R = np.array([[0.1]])
+    >>> updated = gaussian_sum_filter_update(components, z, h, H, R)
+    >>> len(updated)
+    2
+    >>> # Component 1 should have higher weight (closer to measurement)
+    >>> updated[0].w > updated[1].w
+    True
     """
     z = np.asarray(z, dtype=np.float64)
     H = np.asarray(H, dtype=np.float64)