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

pytcl/dynamic_estimation/particle_filters/bootstrap.py

@@ -48,6 +48,15 @@ def resample_multinomial(
     -------
     resampled : ndarray
         Resampled particles with uniform weights.
+
+    Examples
+    --------
+    >>> rng = np.random.default_rng(42)
+    >>> particles = np.array([[1.0], [2.0], [3.0], [4.0]])
+    >>> weights = np.array([0.1, 0.1, 0.1, 0.7])  # particle 4 dominant
+    >>> resampled = resample_multinomial(particles, weights, rng)
+    >>> resampled.shape
+    (4, 1)
     """
     if rng is None:
         rng = np.random.default_rng()
@@ -80,6 +89,15 @@ def resample_systematic(
     -------
     resampled : ndarray
         Resampled particles.
+
+    Examples
+    --------
+    >>> rng = np.random.default_rng(42)
+    >>> particles = np.array([[0.0], [1.0], [2.0], [3.0]])
+    >>> weights = np.array([0.25, 0.25, 0.25, 0.25])
+    >>> resampled = resample_systematic(particles, weights, rng)
+    >>> resampled.shape
+    (4, 1)
     """
     if rng is None:
         rng = np.random.default_rng()
@@ -145,6 +163,18 @@ def resample_residual(
     -------
     resampled : ndarray
         Resampled particles.
+
+    Examples
+    --------
+    >>> rng = np.random.default_rng(42)
+    >>> particles = np.array([[1.0], [2.0], [3.0], [4.0]])
+    >>> weights = np.array([0.1, 0.2, 0.3, 0.4])
+    >>> resampled = resample_residual(particles, weights, rng)
+    >>> resampled.shape
+    (4, 1)
+    >>> # High-weight particles are copied deterministically
+    >>> np.sum(resampled == 4.0) >= 1
+    True
     """
     if rng is None:
         rng = np.random.default_rng()
@@ -184,6 +214,17 @@ def effective_sample_size(weights: NDArray[np.floating]) -> float:
     ess : float
         Effective sample size, in range [1, N].
 
+    Examples
+    --------
+    >>> # Uniform weights -> ESS = N
+    >>> weights = np.array([0.25, 0.25, 0.25, 0.25])
+    >>> effective_sample_size(weights)
+    4.0
+    >>> # Degenerate weights -> ESS approaches 1
+    >>> weights = np.array([0.97, 0.01, 0.01, 0.01])
+    >>> effective_sample_size(weights)
+    1.06...
+
     Notes
     -----
     ESS = 1 / sum(w_i^2)
@@ -220,6 +261,29 @@ def bootstrap_pf_predict(
     -------
     particles_pred : ndarray
         Predicted particles.
+
+    Examples
+    --------
+    Predict particles through constant velocity dynamics:
+
+    >>> import numpy as np
+    >>> rng = np.random.default_rng(42)
+    >>> # 50 particles for 2D state [position, velocity]
+    >>> particles = np.column_stack([
+    ...     np.zeros(50),  # position
+    ...     np.ones(50)    # velocity = 1
+    ... ])
+    >>> dt = 0.1
+    >>> # x_next = [pos + vel*dt, vel]
+    >>> f = lambda x: np.array([x[0] + x[1] * dt, x[1]])
+    >>> # Process noise sampler
+    >>> Q_sample = lambda n, r: r.normal(0, 0.01, (n, 2))
+    >>> pred = bootstrap_pf_predict(particles, f, Q_sample, rng)
+    >>> pred.shape
+    (50, 2)
+    >>> # Positions moved forward by ~0.1
+    >>> np.mean(pred[:, 0])  # doctest: +ELLIPSIS
+    0.1...
     """
     if rng is None:
         rng = np.random.default_rng()
@@ -266,6 +330,25 @@ def bootstrap_pf_update(
         Updated normalized weights.
     log_likelihood : float
         Log marginal likelihood of measurement.
+
+    Examples
+    --------
+    Update particle weights with a position measurement:
+
+    >>> import numpy as np
+    >>> # 4 particles at different positions
+    >>> particles = np.array([[0.0], [1.0], [2.0], [3.0]])
+    >>> weights = np.ones(4) / 4  # uniform initial weights
+    >>> z = np.array([2.0])  # measured position
+    >>> # Gaussian likelihood centered on measurement
+    >>> def likelihood(z, x):
+    ...     return np.exp(-0.5 * (z[0] - x[0])**2)
+    >>> new_weights, log_lik = bootstrap_pf_update(particles, weights, z, likelihood)
+    >>> # Particle at x=2 should have highest weight
+    >>> np.argmax(new_weights)
+    2
+    >>> np.sum(new_weights)  # weights sum to 1
+    1.0
     """
     z = np.asarray(z, dtype=np.float64)
     N = len(particles)
@@ -312,6 +395,19 @@ def gaussian_likelihood(
     -------
     likelihood : float
         p(z|x) = N(z; z_pred, R).
+
+    Examples
+    --------
+    >>> z = np.array([1.0, 2.0])  # actual measurement
+    >>> z_pred = np.array([1.0, 2.0])  # perfect prediction
+    >>> R = np.eye(2) * 0.1  # measurement noise covariance
+    >>> lik = gaussian_likelihood(z, z_pred, R)
+    >>> lik > 0
+    True
+    >>> # Zero innovation -> maximum likelihood
+    >>> z_off = np.array([10.0, 10.0])
+    >>> gaussian_likelihood(z_off, z_pred, R) < lik
+    True
     """
     m = len(z)
     innovation = z - z_pred
@@ -366,6 +462,30 @@ def bootstrap_pf_step(
     -------
     state : ParticleState
         Updated particles and weights.
+
+    Examples
+    --------
+    Track a 1D random walk with position measurements:
+
+    >>> import numpy as np
+    >>> rng = np.random.default_rng(42)
+    >>> # 100 particles for 1D state
+    >>> particles = rng.normal(0, 1, (100, 1))
+    >>> weights = np.ones(100) / 100
+    >>> # Simple dynamics: x_k+1 = x_k + w
+    >>> f = lambda x: x
+    >>> h = lambda x: x  # measure position directly
+    >>> Q_sample = lambda n, r: r.normal(0, 0.1, (n, 1))
+    >>> R = np.array([[0.5]])  # measurement noise
+    >>> z = np.array([0.5])  # measurement
+    >>> state = bootstrap_pf_step(particles, weights, z, f, h, Q_sample, R, rng=rng)
+    >>> state.particles.shape
+    (100, 1)
+
+    See Also
+    --------
+    bootstrap_pf_predict : Prediction step only.
+    bootstrap_pf_update : Update step only.
     """
     if rng is None:
         rng = np.random.default_rng()
@@ -420,6 +540,13 @@ def particle_mean(
     -------
     mean : ndarray
         Weighted mean estimate.
+
+    Examples
+    --------
+    >>> particles = np.array([[0.0], [1.0], [2.0], [3.0]])
+    >>> weights = np.array([0.1, 0.2, 0.3, 0.4])
+    >>> particle_mean(particles, weights)
+    array([2.])
     """
     return np.sum(weights[:, np.newaxis] * particles, axis=0)
 
@@ -470,6 +597,14 @@ def particle_covariance(
     -------
     cov : ndarray
         Weighted covariance.
+
+    Examples
+    --------
+    >>> particles = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
+    >>> weights = np.array([0.25, 0.25, 0.25, 0.25])
+    >>> cov = particle_covariance(particles, weights)
+    >>> cov.shape
+    (2, 2)
     """
     if mean is None:
         mean = particle_mean(particles, weights)
@@ -505,6 +640,17 @@ def initialize_particles(
     -------
     state : ParticleState
         Initial particles with uniform weights.
+
+    Examples
+    --------
+    >>> rng = np.random.default_rng(42)
+    >>> x0 = np.array([0.0, 0.0])
+    >>> P0 = np.eye(2) * 0.1
+    >>> state = initialize_particles(x0, P0, N=100, rng=rng)
+    >>> state.particles.shape
+    (100, 2)
+    >>> np.allclose(state.weights, 0.01)  # uniform 1/N
+    True
     """
     if rng is None:
         rng = np.random.default_rng()

pytcl/dynamic_estimation/rbpf.py

@@ -501,6 +501,32 @@ def rbpf_predict(
     -------
     list[RBPFParticle]
         Predicted particles
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.dynamic_estimation.rbpf import RBPFParticle
+    >>> np.random.seed(42)
+    >>> # 3 particles with nonlinear bearing and linear position
+    >>> particles = [
+    ...     RBPFParticle(y=np.array([0.1]), x=np.array([0.0, 1.0]),
+    ...                  P=np.eye(2) * 0.5, w=1/3),
+    ...     RBPFParticle(y=np.array([0.0]), x=np.array([0.0, 1.0]),
+    ...                  P=np.eye(2) * 0.5, w=1/3),
+    ...     RBPFParticle(y=np.array([-0.1]), x=np.array([0.0, 1.0]),
+    ...                  P=np.eye(2) * 0.5, w=1/3),
+    ... ]
+    >>> # Nonlinear dynamics for bearing
+    >>> g = lambda y: y  # bearing stays constant
+    >>> G = np.eye(1)
+    >>> Qy = np.eye(1) * 0.01
+    >>> # Linear dynamics for position
+    >>> f = lambda x, y: np.array([x[0] + x[1] * 0.1, x[1]])
+    >>> F = np.array([[1, 0.1], [0, 1]])
+    >>> Qx = np.eye(2) * 0.01
+    >>> predicted = rbpf_predict(particles, g, G, Qy, f, F, Qx)
+    >>> len(predicted)
+    3
     """
     new_particles = []
 
@@ -553,6 +579,31 @@ def rbpf_update(
     -------
     list[RBPFParticle]
         Updated particles with adapted weights
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.dynamic_estimation.rbpf import RBPFParticle
+    >>> # 3 particles at different bearings
+    >>> particles = [
+    ...     RBPFParticle(y=np.array([0.5]), x=np.array([1.0, 0.0]),
+    ...                  P=np.eye(2) * 0.5, w=1/3),
+    ...     RBPFParticle(y=np.array([0.0]), x=np.array([1.0, 0.0]),
+    ...                  P=np.eye(2) * 0.5, w=1/3),
+    ...     RBPFParticle(y=np.array([-0.5]), x=np.array([1.0, 0.0]),
+    ...                  P=np.eye(2) * 0.5, w=1/3),
+    ... ]
+    >>> # Position measurement
+    >>> z = np.array([1.1])
+    >>> h = lambda x, y: np.array([x[0]])  # measure position
+    >>> H = np.array([[1, 0]])
+    >>> R = np.array([[0.1]])
+    >>> updated = rbpf_update(particles, z, h, H, R)
+    >>> len(updated)
+    3
+    >>> # Weights should sum to 1
+    >>> abs(sum(p.w for p in updated) - 1.0) < 1e-10
+    True
     """
     weights = np.zeros(len(particles))
     new_particles = []

pytcl/dynamic_estimation/smoothers.py

@@ -423,6 +423,25 @@ def fixed_interval_smoother(
     result : RTSResult
         Smoothed estimates over the interval.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 1D constant velocity model
+    >>> x0 = np.array([0.0, 1.0])  # [position, velocity]
+    >>> P0 = np.eye(2) * 5.0
+    >>> F = np.array([[1, 1], [0, 1]])
+    >>> Q = np.array([[0.25, 0.5], [0.5, 1.0]]) * 0.01
+    >>> H = np.array([[1, 0]])
+    >>> R = np.array([[0.5]])
+    >>> measurements = [np.array([0.9]), np.array([2.1]), np.array([3.0]),
+    ...                 np.array([4.2]), np.array([4.9])]
+    >>> result = fixed_interval_smoother(x0, P0, measurements, F, Q, H, R)
+    >>> len(result.x_smooth)
+    5
+    >>> # Smoothed estimates have lower uncertainty
+    >>> np.trace(result.P_smooth[2]) < np.trace(result.P_filt[2])
+    True
+
     See Also
     --------
     rts_smoother : Full RTS smoother with time-varying parameters.
@@ -478,6 +497,26 @@ def two_filter_smoother(
     result : RTSResult
         Smoothed estimates.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 1D position-velocity system
+    >>> x0_fwd = np.array([0.0, 1.0])
+    >>> P0_fwd = np.eye(2) * 5.0
+    >>> # Backward filter starts with diffuse (high uncertainty) prior
+    >>> x0_bwd = np.array([5.0, 1.0])  # approximate final state
+    >>> P0_bwd = np.eye(2) * 100.0     # diffuse prior
+    >>> F = np.array([[1, 1], [0, 1]])
+    >>> Q = np.eye(2) * 0.1
+    >>> H = np.array([[1, 0]])
+    >>> R = np.array([[1.0]])
+    >>> measurements = [np.array([0.8]), np.array([1.9]), np.array([3.1]),
+    ...                 np.array([4.0]), np.array([5.2])]
+    >>> result = two_filter_smoother(x0_fwd, P0_fwd, x0_bwd, P0_bwd,
+    ...                               measurements, F, Q, H, R)
+    >>> len(result.x_smooth)
+    5
+
     Notes
     -----
     The two-filter smoother runs two independent Kalman filters:
@@ -645,6 +684,25 @@ def rts_smoother_single_step(
     -------
     result : SmoothedState
         Smoothed state and covariance at current time.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # After running forward filter and getting smoothed estimate at k+1
+    >>> x_filt = np.array([1.0, 0.5])      # filtered state at k
+    >>> P_filt = np.eye(2) * 0.5           # filtered covariance at k
+    >>> x_pred_next = np.array([1.5, 0.5]) # predicted state at k+1
+    >>> P_pred_next = np.eye(2) * 0.6      # predicted covariance at k+1
+    >>> x_smooth_next = np.array([1.4, 0.6])  # smoothed state at k+1
+    >>> P_smooth_next = np.eye(2) * 0.3       # smoothed covariance at k+1
+    >>> F = np.array([[1, 1], [0, 1]])
+    >>> result = rts_smoother_single_step(x_filt, P_filt, x_pred_next,
+    ...                                    P_pred_next, x_smooth_next,
+    ...                                    P_smooth_next, F)
+    >>> result.x.shape
+    (2,)
+    >>> result.P.shape
+    (2, 2)
     """
     x_s, P_s = kf_smooth(
         x_filt, P_filt, x_pred_next, P_pred_next, x_smooth_next, P_smooth_next, F

pytcl/dynamic_models/continuous_time/dynamics.py

@@ -79,6 +79,13 @@ def drift_constant_acceleration(
     -------
     a : ndarray
         Drift vector.
+
+    Examples
+    --------
+    >>> x = np.array([0, 10, 1])  # 1D: pos=0, vel=10, acc=1
+    >>> a = drift_constant_acceleration(x, num_dims=1)
+    >>> a  # [vel, acc, 0]
+    array([10.,  1.,  0.])
     """
     x = np.asarray(x, dtype=np.float64)
     n = 3  # states per dimension
@@ -124,6 +131,13 @@ def drift_singer(
     -----
     The Singer model has acceleration following a first-order Markov process:
         da/dt = -a/tau + w(t)
+
+    Examples
+    --------
+    >>> x = np.array([0, 10, 2])  # 1D: pos=0, vel=10, acc=2
+    >>> a = drift_singer(x, tau=5.0, num_dims=1)
+    >>> a  # [vel, acc, -acc/tau]
+    array([10. ,  2. , -0.4])
     """
     x = np.asarray(x, dtype=np.float64)
     n = 3  # states per dimension
@@ -167,6 +181,14 @@ def drift_coordinated_turn_2d(
         dy/dt = vy
         dvy/dt = omega * vx
         domega/dt = 0
+
+    Examples
+    --------
+    >>> # Aircraft at origin with velocity [100, 0] and turn rate 0.1 rad/s
+    >>> x = np.array([0, 100, 0, 0, 0.1])
+    >>> a = drift_coordinated_turn_2d(x)
+    >>> a  # [vx, -omega*vy, vy, omega*vx, 0]
+    array([ 100.,   -0.,    0.,   10.,    0.])
     """
     x = np.asarray(x, dtype=np.float64)
     pos_x, vel_x, pos_y, vel_y, omega = x
@@ -209,6 +231,18 @@ def diffusion_constant_velocity(
     -------
     D : ndarray
         Diffusion matrix (noise enters through velocity derivative).
+
+    Examples
+    --------
+    >>> x = np.array([0, 1, 0, 2])  # 2D state (not used)
+    >>> D = diffusion_constant_velocity(x, sigma_a=0.5, num_dims=2)
+    >>> D.shape
+    (4, 2)
+    >>> D  # Noise enters velocity states only
+    array([[0. , 0. ],
+           [0.5, 0. ],
+           [0. , 0. ],
+           [0. , 0.5]])
     """
     n = 2 * num_dims
     D = np.zeros((n, num_dims), dtype=np.float64)
@@ -244,6 +278,17 @@ def diffusion_constant_acceleration(
     -------
     D : ndarray
         Diffusion matrix.
+
+    Examples
+    --------
+    >>> x = np.array([0, 1, 0.5])  # 1D state (not used)
+    >>> D = diffusion_constant_acceleration(x, sigma_j=0.1, num_dims=1)
+    >>> D.shape
+    (3, 1)
+    >>> D  # Noise enters acceleration state only
+    array([[0. ],
+           [0. ],
+           [0.1]])
     """
     n = 3 * num_dims
     D = np.zeros((n, num_dims), dtype=np.float64)
@@ -286,6 +331,15 @@ def diffusion_singer(
     Notes
     -----
     The diffusion coefficient for Singer is sqrt(2*sigma_m^2/tau).
+
+    Examples
+    --------
+    >>> x = np.array([0, 1, 0.5])  # 1D state (not used)
+    >>> D = diffusion_singer(x, sigma_m=1.0, tau=10.0, num_dims=1)
+    >>> D.shape
+    (3, 1)
+    >>> D[2, 0]  # sqrt(2*1^2/10) = sqrt(0.2)
+    0.4472135954999579
     """
     n = 3 * num_dims
     D = np.zeros((n, num_dims), dtype=np.float64)
@@ -355,6 +409,17 @@ def continuous_to_discrete(
     ----------
     .. [1] Van Loan, C.F., "Computing Integrals Involving the Matrix
            Exponential", IEEE Trans. Automatic Control, 1978.
+
+    Examples
+    --------
+    >>> # 1D constant velocity model
+    >>> A = np.array([[0, 1], [0, 0]])
+    >>> G = np.array([[0], [1]])
+    >>> Q_c = np.array([[1.0]])  # acceleration variance
+    >>> F, Q_d = continuous_to_discrete(A, G, Q_c, T=0.1)
+    >>> F  # State transition matrix
+    array([[1. , 0.1],
+           [0. , 1. ]])
     """
     A = np.asarray(A, dtype=np.float64)
     G = np.asarray(G, dtype=np.float64)
@@ -411,6 +476,19 @@ def discretize_lti(
         Discrete-time state transition matrix.
     G : ndarray or None
         Discrete-time input matrix (None if B is None).
+
+    Examples
+    --------
+    >>> # 1D constant velocity: dx/dt = v, dv/dt = u (control input)
+    >>> A = np.array([[0, 1], [0, 0]])
+    >>> B = np.array([[0], [1]])
+    >>> F, G = discretize_lti(A, B, T=0.1)
+    >>> F  # State transition
+    array([[1. , 0.1],
+           [0. , 1. ]])
+    >>> G  # Input matrix
+    array([[0.005],
+           [0.1  ]])
     """
     A = np.asarray(A, dtype=np.float64)
     n = A.shape[0]
@@ -454,6 +532,14 @@ def state_jacobian_cv(
     -------
     A : ndarray
         Continuous-time state matrix.
+
+    Examples
+    --------
+    >>> x = np.array([0, 1])  # 1D state (not used)
+    >>> A = state_jacobian_cv(x, num_dims=1)
+    >>> A
+    array([[0., 1.],
+           [0., 0.]])
     """
     n = 2  # states per dimension
     A_1d = np.array(
@@ -494,6 +580,15 @@ def state_jacobian_ca(
     -------
     A : ndarray
         Continuous-time state matrix.
+
+    Examples
+    --------
+    >>> x = np.array([0, 1, 0.5])  # 1D state (not used)
+    >>> A = state_jacobian_ca(x, num_dims=1)
+    >>> A
+    array([[0., 1., 0.],
+           [0., 0., 1.],
+           [0., 0., 0.]])
     """
     n = 3  # states per dimension
     A_1d = np.array(
@@ -538,6 +633,15 @@ def state_jacobian_singer(
     -------
     A : ndarray
         Continuous-time state matrix.
+
+    Examples
+    --------
+    >>> x = np.array([0, 1, 0.5])  # 1D state (not used)
+    >>> A = state_jacobian_singer(x, tau=5.0, num_dims=1)
+    >>> A
+    array([[ 0. ,  1. ,  0. ],
+           [ 0. ,  0. ,  1. ],
+           [ 0. ,  0. , -0.2]])
     """
     n = 3  # states per dimension
     A_1d = np.array(

pytcl/dynamic_models/discrete_time/coordinated_turn.py

@@ -232,6 +232,12 @@ def f_coord_turn_polar(
     - psi is heading angle
     - v is speed magnitude
     - omega is turn rate
+
+    Examples
+    --------
+    >>> F = f_coord_turn_polar(T=1.0, omega=0.1, speed=100.0)
+    >>> F.shape
+    (5, 5)
     """
     # Handle near-zero turn rate
     if np.abs(omega) < 1e-10:

pytcl/dynamic_models/discrete_time/singer.py

@@ -123,6 +123,12 @@ def f_singer_2d(T: float, tau: float) -> NDArray[np.floating]:
     F : ndarray
         State transition matrix of shape (6, 6).
 
+    Examples
+    --------
+    >>> F = f_singer_2d(T=1.0, tau=10.0)
+    >>> F.shape
+    (6, 6)
+
     See Also
     --------
     f_singer : General Singer model.
@@ -148,6 +154,12 @@ def f_singer_3d(T: float, tau: float) -> NDArray[np.floating]:
     F : ndarray
         State transition matrix of shape (9, 9).
 
+    Examples
+    --------
+    >>> F = f_singer_3d(T=1.0, tau=10.0)
+    >>> F.shape
+    (9, 9)
+
     See Also
     --------
     f_singer : General Singer model.

pytcl/dynamic_models/process_noise/coordinated_turn.py

@@ -1,5 +1,51 @@
 """
 Process noise covariance matrices for coordinated turn models.
+
+This module provides functions to construct process noise covariance matrices
+(Q matrices) for coordinated turn motion models used in target tracking.
+Coordinated turn models describe targets that maintain a constant turn rate,
+such as aircraft executing banking maneuvers.
+
+The process noise captures uncertainty in the target's motion, including:
+- Linear acceleration uncertainty along the velocity direction
+- Turn rate (angular velocity) uncertainty
+
+Available functions:
+- ``q_coord_turn_2d``: 2D coordinated turn (planar motion)
+- ``q_coord_turn_3d``: 3D coordinated turn (spatial motion)
+- ``q_coord_turn_polar``: Polar/heading-speed representation
+
+These Q matrices are designed to work with the corresponding state transition
+matrices in :mod:`pytcl.dynamic_models.coordinated_turn`.
+
+Examples
+--------
+Create process noise for a 2D coordinated turn tracker:
+
+>>> from pytcl.dynamic_models.process_noise import q_coord_turn_2d
+>>> Q = q_coord_turn_2d(T=0.1, sigma_a=2.0)  # 0.1s step, 2 m/s² accel noise
+>>> Q.shape
+(4, 4)
+
+With turn rate state estimation:
+
+>>> Q = q_coord_turn_2d(T=0.1, sigma_a=2.0, sigma_omega=0.01,
+...                     state_type='position_velocity_omega')
+>>> Q.shape
+(5, 5)
+
+See Also
+--------
+pytcl.dynamic_models.coordinated_turn : State transition matrices
+pytcl.dynamic_models.process_noise.constant_velocity : CV process noise
+pytcl.dynamic_models.process_noise.constant_acceleration : CA process noise
+
+References
+----------
+.. [1] Bar-Shalom, Y., Li, X.R., and Kirubarajan, T., "Estimation with
+       Applications to Tracking and Navigation", Wiley, 2001.
+.. [2] Blackman, S. and Popoli, R., "Design and Analysis of Modern
+       Tracking Systems", Artech House, 1999.
 """
 
 import numpy as np

pytcl/dynamic_models/process_noise/polynomial.py

@@ -229,6 +229,12 @@ def q_constant_acceleration(
     Q : ndarray
         Process noise covariance matrix.
 
+    Examples
+    --------
+    >>> Q = q_constant_acceleration(T=1.0, sigma_j=0.1, num_dims=2)
+    >>> Q.shape
+    (6, 6)
+
     See Also
     --------
     f_constant_acceleration : State transition matrix for CA model.

pytcl/dynamic_models/process_noise/singer.py

@@ -1,5 +1,57 @@
 """
 Process noise covariance matrices for Singer acceleration model.
+
+This module provides functions to construct process noise covariance matrices
+(Q matrices) for the Singer acceleration motion model. The Singer model
+treats target acceleration as a first-order Gauss-Markov process, making it
+well-suited for tracking maneuvering targets with random accelerations.
+
+The Singer model is characterized by:
+- A maneuver time constant (tau) that controls how quickly acceleration
+  correlations decay
+- An RMS maneuver level (sigma_m) that sets the expected acceleration magnitude
+- State vector [position, velocity, acceleration] per dimension
+
+The model dynamics are:
+    da/dt = -a/tau + w(t)
+
+where w(t) is white noise with spectral density 2*sigma_m²/tau.
+
+Available functions:
+- ``q_singer``: Generic N-dimensional Singer process noise
+- ``q_singer_2d``: 2D Singer model (6x6 state)
+- ``q_singer_3d``: 3D Singer model (9x9 state)
+
+These Q matrices are designed to work with the corresponding state transition
+matrices in :mod:`pytcl.dynamic_models.singer`.
+
+Examples
+--------
+Create process noise for tracking a maneuvering aircraft:
+
+>>> from pytcl.dynamic_models.process_noise import q_singer
+>>> Q = q_singer(T=1.0, tau=20.0, sigma_m=3.0)  # tau=20s, 3g maneuvers
+>>> Q.shape
+(3, 3)
+
+For 3D tracking:
+
+>>> Q = q_singer_3d(T=0.1, tau=10.0, sigma_m=2.0)
+>>> Q.shape
+(9, 9)
+
+See Also
+--------
+pytcl.dynamic_models.singer : State transition matrices
+pytcl.dynamic_models.process_noise.constant_acceleration : CA process noise
+
+References
+----------
+.. [1] Singer, R.A., "Estimating Optimal Tracking Filter Performance for
+       Manned Maneuvering Targets", IEEE Trans. Aerospace and Electronic
+       Systems, Vol. AES-6, No. 4, July 1970, pp. 473-483.
+.. [2] Bar-Shalom, Y., Li, X.R., and Kirubarajan, T., "Estimation with
+       Applications to Tracking and Navigation", Wiley, 2001, Chapter 6.
 """
 
 import numpy as np