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

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

pytcl/gravity/clenshaw.py

@@ -106,6 +106,17 @@ def clenshaw_sum_order(
         Sum of C terms weighted by Legendre functions.
     sum_S : float
         Sum of S terms weighted by Legendre functions.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> C = np.zeros((5, 5))
+    >>> S = np.zeros((5, 5))
+    >>> C[2, 0] = 1.0  # Only C20 term
+    >>> cos_theta, sin_theta = np.cos(np.pi/4), np.sin(np.pi/4)
+    >>> sum_C, sum_S = clenshaw_sum_order(0, cos_theta, sin_theta, C, S, 4)
+    >>> isinstance(sum_C, float)
+    True
     """
     # Handle edge case
     if m > n_max:
@@ -187,6 +198,18 @@ def clenshaw_sum_order_derivative(
         Derivative of sum_C with respect to theta.
     dsum_S : float
         Derivative of sum_S with respect to theta.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> C = np.zeros((5, 5))
+    >>> S = np.zeros((5, 5))
+    >>> C[2, 0] = -0.0005  # J2-like term
+    >>> cos_theta, sin_theta = np.cos(np.pi/4), np.sin(np.pi/4)
+    >>> sum_C, sum_S, dsum_C, dsum_S = clenshaw_sum_order_derivative(
+    ...     0, cos_theta, sin_theta, C, S, 4)
+    >>> len([sum_C, sum_S, dsum_C, dsum_S])
+    4
     """
     if m > n_max:
         return 0.0, 0.0, 0.0, 0.0
@@ -298,6 +321,19 @@ def clenshaw_geoid(
             \\sum_{m=0}^{n} P_n^m(\\sin\\phi) (C_{nm}\\cos m\\lambda + S_{nm}\\sin m\\lambda)
 
     The n=0 and n=1 terms are excluded as they represent the reference field.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> C = np.zeros((5, 5))
+    >>> S = np.zeros((5, 5))
+    >>> C[0, 0] = 1.0
+    >>> R = 6.378e6
+    >>> GM = 3.986e14
+    >>> gamma = 9.81
+    >>> N = clenshaw_geoid(0, 0, C, S, R, GM, gamma)
+    >>> isinstance(N, float)
+    True
     """
     if n_max is None:
         n_max = C.shape[0] - 1
@@ -381,6 +417,18 @@ def clenshaw_potential(
     -------
     float
         Gravitational potential in m^2/s^2.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> C = np.zeros((5, 5))
+    >>> S = np.zeros((5, 5))
+    >>> C[0, 0] = 1.0  # Central term only
+    >>> R = 6.378e6
+    >>> GM = 3.986e14
+    >>> V = clenshaw_potential(0, 0, R, C, S, R, GM)
+    >>> abs(V - GM/R) / (GM/R) < 0.01  # ~GM/r for central term
+    True
     """
     if n_max is None:
         n_max = C.shape[0] - 1
@@ -464,6 +512,18 @@ def clenshaw_gravity(
         Northward component of gravity disturbance in m/s^2.
     g_lon : float
         Eastward component of gravity disturbance in m/s^2.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> C = np.zeros((5, 5))
+    >>> S = np.zeros((5, 5))
+    >>> C[0, 0] = 1.0
+    >>> R = 6.378e6
+    >>> GM = 3.986e14
+    >>> g_r, g_lat, g_lon = clenshaw_gravity(0, 0, R, C, S, R, GM)
+    >>> g_r < 0  # Gravity points inward
+    True
     """
     if n_max is None:
         n_max = C.shape[0] - 1

pytcl/gravity/egm.py

@@ -131,6 +131,12 @@ def get_data_dir() -> Path:
     -------
     Path
         Path to the data directory.
+
+    Examples
+    --------
+    >>> data_dir = get_data_dir()
+    >>> str(data_dir).endswith('.pytcl/data') or 'PYTCL_DATA_DIR' in dir()
+    True
     """
     env_dir = os.environ.get("PYTCL_DATA_DIR")
     if env_dir:
@@ -242,6 +248,16 @@ def create_test_coefficients(n_max: int = 36) -> EGMCoefficients:
     -------
     EGMCoefficients
         Test coefficient set.
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> coef.n_max
+    10
+    >>> coef.C[0, 0]  # Central term
+    1.0
+    >>> abs(coef.C[2, 0]) > 0  # J2 term present
+    True
     """
     C = np.zeros((n_max + 1, n_max + 1))
     S = np.zeros((n_max + 1, n_max + 1))
@@ -496,6 +512,16 @@ def geoid_heights(
     -------
     ndarray
         Geoid heights in meters.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> lats = np.array([0.0, np.pi/4])  # Equator and 45°N
+    >>> lons = np.array([0.0, np.pi/2])  # Prime meridian and 90°E
+    >>> heights = geoid_heights(lats, lons, coefficients=coef)
+    >>> len(heights)
+    2
     """
     # Load coefficients once
     if coefficients is None:
@@ -543,6 +569,13 @@ def gravity_disturbance(
     -------
     GravityDisturbance
         Gravity disturbance components.
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> dist = gravity_disturbance(0, 0, h=0, coefficients=coef)
+    >>> isinstance(dist.magnitude, float)
+    True
     """
     if coefficients is None:
         coefficients = load_egm_coefficients(model, n_max)
@@ -613,6 +646,13 @@ def gravity_anomaly(
     -------
     float
         Gravity anomaly in m/s^2 (typically reported in mGal = 1e-5 m/s^2).
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> anomaly = gravity_anomaly(0, 0, h=0, coefficients=coef)
+    >>> isinstance(anomaly, float)
+    True
     """
     disturbance = gravity_disturbance(lat, lon, h, model, n_max, coefficients)
 
@@ -657,6 +697,13 @@ def deflection_of_vertical(
     -----
     Positive xi means the plumb line points more north than the normal.
     Positive eta means the plumb line points more east than the normal.
+
+    Examples
+    --------
+    >>> coef = create_test_coefficients(n_max=10)
+    >>> xi, eta = deflection_of_vertical(0, 0, coefficients=coef)
+    >>> isinstance(xi, float) and isinstance(eta, float)
+    True
     """
     if coefficients is None:
         coefficients = load_egm_coefficients(model, n_max)

pytcl/gravity/models.py

@@ -267,6 +267,12 @@ def gravity_j2(
     -------
     result : GravityResult
         Gravity components and magnitude.
+
+    Examples
+    --------
+    >>> result = gravity_j2(0, 0, 0)  # At equator, sea level
+    >>> abs(result.magnitude - 9.78) < 0.01
+    True
     """
     GM = constants.GM
     a = constants.a
@@ -328,6 +334,12 @@ def geoid_height_j2(
     N : float
         Geoid height (geoid - ellipsoid) in meters.
 
+    Examples
+    --------
+    >>> N = geoid_height_j2(0)  # At equator
+    >>> N > 0  # Equator bulges outward
+    True
+
     Notes
     -----
     This is a simplified model. For accurate geoid heights,
@@ -371,6 +383,12 @@ def gravitational_potential(
     -------
     U : float
         Gravitational potential (m^2/s^2).
+
+    Examples
+    --------
+    >>> U = gravitational_potential(0, 0, 6.4e6)  # Near Earth surface
+    >>> U < 0  # Potential is negative
+    True
     """
     GM = constants.GM
     a = constants.a
@@ -415,6 +433,14 @@ def free_air_anomaly(
     delta_g : float
         Free-air anomaly in m/s^2 (or mGal if multiplied by 1e5).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Observed gravity slightly higher than normal
+    >>> delta_g = free_air_anomaly(9.81, np.radians(45), 100)
+    >>> isinstance(delta_g, float)
+    True
+
     Notes
     -----
     The free-air anomaly is the difference between observed gravity
@@ -452,6 +478,14 @@ def bouguer_anomaly(
     delta_g : float
         Bouguer anomaly in m/s^2.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Bouguer anomaly at mountain location
+    >>> delta_g = bouguer_anomaly(9.81, np.radians(45), 1000)
+    >>> isinstance(delta_g, float)
+    True
+
     Notes
     -----
     The Bouguer anomaly removes the gravitational effect of the