nrl-tracker 1.11.0__py3-none-any.whl → 1.12.0__py3-none-any.whl

pytcl/coordinate_systems/conversions/geodetic.py

@@ -257,6 +257,27 @@ def geodetic2enu(
     enu : ndarray
         Local ENU coordinates [east, north, up] in meters.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems import geodetic2enu
+    >>> # Reference point: San Francisco Airport (-122.375°, 37.615°)
+    >>> lat_ref = np.radians(37.615)
+    >>> lon_ref = np.radians(-122.375)
+    >>> alt_ref = 0
+    >>> # Target point: 2 km north, 1 km east of reference
+    >>> # Approximate location using small offsets
+    >>> lat_target = lat_ref + np.radians(0.01)
+    >>> lon_target = lon_ref + np.radians(0.01)
+    >>> alt_target = 100  # 100 m elevation
+    >>> enu = geodetic2enu(lat_target, lon_target, alt_target,
+    ...                      lat_ref, lon_ref, alt_ref)
+    >>> # ENU coordinates should show positive north and east offsets
+    >>> enu[0] > 0 and enu[1] > 0  # East > 0, North > 0
+    True
+    >>> enu[2] > 100  # Up should be approximately the altitude difference
+    True
+
     See Also
     --------
     enu2geodetic : Inverse conversion.
@@ -509,6 +530,25 @@ def ned2ecef(
     ecef : ndarray
         ECEF coordinates [x, y, z] in meters.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems import ned2ecef, geodetic2ecef
+    >>> # Reference point: Kennedy Space Center (28.5°N, 80.65°W)
+    >>> lat_ref = np.radians(28.5)
+    >>> lon_ref = np.radians(-80.65)
+    >>> # NED offset from reference: 5 km north, 3 km east, 1 km down
+    >>> ned = np.array([5000.0, 3000.0, 1000.0])
+    >>> # Convert to ECEF coordinates
+    >>> ecef = ned2ecef(ned, lat_ref, lon_ref)
+    >>> ecef.shape
+    (3,)
+    >>> # Verify roundtrip conversion
+    >>> from pytcl.coordinate_systems import ecef2ned
+    >>> ned_back = ecef2ned(ecef, lat_ref, lon_ref)
+    >>> np.allclose(ned, ned_back, atol=0.1)  # Allow small numerical error
+    True
+
     See Also
     --------
     ecef2ned : Inverse conversion.
@@ -825,6 +865,24 @@ def sez2geodetic(
     alt : ndarray
         Altitude in meters.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.coordinate_systems import sez2geodetic, geodetic2sez
+    >>> # Observer location: Arecibo Observatory (18.3°N, 66.75°W)
+    >>> lat_ref = np.radians(18.3)
+    >>> lon_ref = np.radians(-66.75)
+    >>> alt_ref = 500  # m
+    >>> # Observed satellite: 30 km south, 20 km east, 35 km zenith
+    >>> sez = np.array([-30000.0, 20000.0, 35000.0])
+    >>> # Convert to geodetic coordinates
+    >>> lat, lon, alt = sez2geodetic(sez, lat_ref, lon_ref, alt_ref)
+    >>> # Verify roundtrip conversion
+    >>> from pytcl.coordinate_systems import geodetic2sez
+    >>> sez_back = geodetic2sez(lat, lon, alt, lat_ref, lon_ref, alt_ref)
+    >>> np.allclose(sez, sez_back, atol=1.0)  # Allow ~1m numerical error
+    True
+
     See Also
     --------
     geodetic2sez : Forward conversion.

pytcl/core/array_utils.py

@@ -269,6 +269,16 @@ def unvec(
     -------
     NDArray
         Matrix with specified shape.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.core.array_utils import unvec
+    >>> v = np.array([1, 2, 3, 4, 5, 6])
+    >>> M = unvec(v, (2, 3))
+    >>> M
+    array([[1, 3, 5],
+           [2, 4, 6]])
     """
     v = np.asarray(v).flatten()
     return v.reshape(shape, order=order)
@@ -362,6 +372,16 @@ def unskew(S: ArrayLike) -> NDArray[np.floating[Any]]:
     -------
     NDArray
         3-element vector.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.core.array_utils import unskew, skew_symmetric
+    >>> v = np.array([1, 2, 3])
+    >>> S = skew_symmetric(v)
+    >>> v_recovered = unskew(S)
+    >>> np.allclose(v, v_recovered)
+    True
     """
     S = np.asarray(S, dtype=np.float64)
     if S.shape != (3, 3):
@@ -503,6 +523,20 @@ def meshgrid_ij(
     -------
     tuple of NDArray
         Coordinate matrices.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.core.array_utils import meshgrid_ij
+    >>> x = np.array([1, 2, 3])
+    >>> y = np.array([4, 5])
+    >>> X, Y = meshgrid_ij(x, y)
+    >>> X
+    array([[1, 2, 3],
+           [1, 2, 3]])
+    >>> Y
+    array([[4, 4, 4],
+           [5, 5, 5]])
     """
     return np.meshgrid(*xi, indexing=indexing)
 
@@ -563,6 +597,15 @@ def nearest_positive_definite(A: ArrayLike) -> NDArray[np.floating[Any]]:
     -------
     NDArray
         Nearest positive definite matrix.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.core.array_utils import nearest_positive_definite
+    >>> A = np.array([[1, -2], [-2, 1]])  # Not PD
+    >>> A_pd = nearest_positive_definite(A)
+    >>> np.all(np.linalg.eigvalsh(A_pd) > 0)
+    True
     """
     A = np.asarray(A, dtype=np.float64)
 
@@ -614,6 +657,15 @@ def safe_cholesky(
     ------
     np.linalg.LinAlgError
         If Cholesky decomposition fails after all attempts.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.core.array_utils import safe_cholesky
+    >>> A = np.array([[4, 2], [2, 3]])  # PD matrix
+    >>> L = safe_cholesky(A)
+    >>> np.allclose(L @ L.T, A)
+    True
     """
     A = np.asarray(A, dtype=np.float64)
 

pytcl/gpu/ekf.py

@@ -155,6 +155,30 @@ def batch_ekf_predict(
     result : BatchEKFPrediction
         Predicted states and covariances.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.ekf import batch_ekf_predict
+    >>> # Nonlinear dynamics: coordinated turn
+    >>> def f_turn(x):
+    ...     w = 0.01  # Turn rate
+    ...     return np.array([x[0] + np.cos(w)*x[2],
+    ...                      x[1] + np.sin(w)*x[3],
+    ...                      x[2], x[3]])
+    >>> def F_jacobian(x):
+    ...     w = 0.01
+    ...     return np.array([[1, 0, np.cos(w), 0],
+    ...                      [0, 1, np.sin(w), 0],
+    ...                      [0, 0, 1, 0],
+    ...                      [0, 0, 0, 1]])
+    >>> n_tracks = 30
+    >>> x = np.random.randn(n_tracks, 4) * 0.1
+    >>> P = np.tile(np.eye(4) * 0.01, (n_tracks, 1, 1))
+    >>> Q = np.eye(4) * 0.001
+    >>> result = batch_ekf_predict(x, P, f_turn, F_jacobian, Q)
+    >>> result.x.shape
+    (30, 4)
+
     Notes
     -----
     The nonlinear dynamics are applied on CPU (Python function), then
@@ -238,6 +262,28 @@ def batch_ekf_update(
     -------
     result : BatchEKFUpdate
         Update results including states, covariances, and statistics.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.ekf import batch_ekf_update
+    >>> # Polar measurement from Cartesian state
+    >>> def h_polar(x):
+    ...     r = np.sqrt(x[0]**2 + x[1]**2)
+    ...     theta = np.arctan2(x[1], x[0])
+    ...     return np.array([r, theta])
+    >>> def H_jacobian(x):
+    ...     r = np.sqrt(x[0]**2 + x[1]**2)
+    ...     return np.array([[x[0]/r, x[1]/r],
+    ...                      [-x[1]/r**2, x[0]/r**2]])
+    >>> n_tracks = 20
+    >>> x = np.random.randn(n_tracks, 2)
+    >>> P = np.tile(np.eye(2), (n_tracks, 1, 1))
+    >>> z = np.random.randn(n_tracks, 2) * [100, 0.1]  # r, theta
+    >>> R = np.diag([10.0, 0.01])
+    >>> result = batch_ekf_update(x, P, z, h_polar, H_jacobian, R)
+    >>> result.x.shape
+    (20, 2)
     """
     cp = import_optional("cupy", extra="gpu", feature="GPU Extended Kalman filter")
 

pytcl/gpu/kalman.py

@@ -353,6 +353,22 @@ def batch_kf_predict_update(
     -------
     result : BatchKalmanUpdate
         Named tuple with updated states, covariances, and statistics.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.kalman import batch_kf_predict_update
+    >>> n_tracks = 50
+    >>> x = np.random.randn(n_tracks, 2)
+    >>> P = np.tile(np.eye(2), (n_tracks, 1, 1))
+    >>> z = np.random.randn(n_tracks, 2)  # Measurements
+    >>> F = np.array([[1, 0.1], [0, 1]])  # Constant velocity
+    >>> Q = np.eye(2) * 0.01
+    >>> H = np.eye(2)
+    >>> R = np.eye(2) * 0.1
+    >>> result = batch_kf_predict_update(x, P, z, F, Q, H, R)
+    >>> result.x.shape
+    (50, 2)
     """
     pred = batch_kf_predict(x, P, F, Q, B, u)
     return batch_kf_update(pred.x, pred.P, z, H, R)

pytcl/gpu/matrix_utils.py

@@ -393,6 +393,16 @@ class MemoryPool:
         -------
         stats : dict
             Dictionary with 'used', 'total', and 'free' bytes.
+
+        Examples
+        --------
+        >>> from pytcl.gpu.matrix_utils import get_memory_pool
+        >>> pool = get_memory_pool()
+        >>> stats = pool.get_stats()
+        >>> stats.keys()
+        dict_keys(['used', 'total', 'free', 'device_total'])
+        >>> stats['used'] >= 0
+        True
         """
         if self._pool is None:
             return {"used": 0, "total": 0, "free": 0}
@@ -409,7 +419,19 @@ class MemoryPool:
         }
 
     def free_all(self) -> None:
-        """Free all cached memory blocks."""
+        """
+        Free all cached memory blocks.
+
+        Clears the memory pool cache, which can help free up GPU memory
+        when operations are complete.
+
+        Examples
+        --------
+        >>> from pytcl.gpu.matrix_utils import get_memory_pool
+        >>> pool = get_memory_pool()
+        >>> # After allocations
+        >>> pool.free_all()  # Clear cached blocks
+        """
         if self._pool is not None:
             self._pool.free_all_blocks()
         if self._pinned_pool is not None:
@@ -423,6 +445,15 @@ class MemoryPool:
         ----------
         limit : int or None
             Maximum bytes to allocate. None for no limit.
+
+        Examples
+        --------
+        >>> from pytcl.gpu.matrix_utils import get_memory_pool
+        >>> pool = get_memory_pool()
+        >>> # Limit to 2 GB
+        >>> pool.set_limit(2 * 1024**3)
+        >>> # Reset to unlimited
+        >>> pool.set_limit(None)
         """
         if self._pool is not None:
             if limit is None:
@@ -471,6 +502,18 @@ def get_memory_pool() -> MemoryPool:
     -------
     pool : MemoryPool
         Global memory pool instance.
+
+    Examples
+    --------
+    >>> from pytcl.gpu.matrix_utils import get_memory_pool
+    >>> pool = get_memory_pool()
+    >>> # Get current memory stats
+    >>> stats = pool.get_stats()
+    >>> print(f"Used: {stats['used']} bytes")
+    >>> # Set memory limit
+    >>> pool.set_limit(1024**3)  # 1 GB limit
+    >>> # Free cached blocks
+    >>> pool.free_all()
     """
     global _memory_pool
     if _memory_pool is None:

pytcl/gpu/particle_filter.py

@@ -79,6 +79,17 @@ def gpu_effective_sample_size(weights: ArrayLike) -> float:
     -------
     ess : float
         Effective sample size.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.particle_filter import gpu_effective_sample_size
+    >>> weights = np.array([0.1, 0.2, 0.3, 0.4])
+    >>> ess = gpu_effective_sample_size(weights)
+    >>> ess > 0
+    True
+    >>> ess <= len(weights)
+    True
     """
     cp = import_optional("cupy", extra="gpu", feature="GPU particle filter")
     w = ensure_gpu_array(weights, dtype=cp.float64)
@@ -151,6 +162,17 @@ def gpu_resample_multinomial(weights: ArrayLike) -> NDArray[np.intp]:
     indices : ndarray
         Resampled particle indices, shape (n_particles,).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.particle_filter import gpu_resample_multinomial
+    >>> weights = np.array([0.1, 0.4, 0.5])
+    >>> indices = gpu_resample_multinomial(weights)
+    >>> indices.shape
+    (3,)
+    >>> np.all(indices < 3)
+    True
+
     Notes
     -----
     Multinomial resampling has higher variance than systematic resampling
@@ -230,6 +252,17 @@ def gpu_normalize_weights(
         Normalized weights, shape (n_particles,).
     log_likelihood : float
         Log of the normalization constant.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.particle_filter import gpu_normalize_weights
+    >>> log_w = np.array([-1.0, -0.5, -2.0])
+    >>> weights, log_likelihood = gpu_normalize_weights(log_w)
+    >>> np.allclose(weights.sum(), 1.0)
+    True
+    >>> log_likelihood < 0
+    True
     """
     cp = import_optional("cupy", extra="gpu", feature="GPU particle filter")
 

pytcl/gpu/ukf.py

@@ -209,6 +209,21 @@ def batch_ukf_predict(
     -------
     result : BatchUKFPrediction
         Predicted states and covariances.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.ukf import batch_ukf_predict
+    >>> # Nonlinear dynamics example
+    >>> def f_dynamics(x):
+    ...     return np.array([x[0] + 0.1*x[1], x[1] * 0.99])
+    >>> n_tracks = 50
+    >>> x = np.random.randn(n_tracks, 2)
+    >>> P = np.tile(np.eye(2) * 0.01, (n_tracks, 1, 1))
+    >>> Q = np.eye(2) * 0.001
+    >>> result = batch_ukf_predict(x, P, f_dynamics, Q)
+    >>> result.x.shape
+    (50, 2)
     """
     cp = import_optional("cupy", extra="gpu", feature="GPU Unscented Kalman filter")
 
@@ -290,6 +305,22 @@ def batch_ukf_update(
     -------
     result : BatchUKFUpdate
         Update results.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.ukf import batch_ukf_update
+    >>> # Nonlinear measurement example
+    >>> def h_measurement(x):
+    ...     return np.sqrt(x[0]**2 + x[1]**2)  # Range-only
+    >>> n_tracks = 40
+    >>> x = np.random.randn(n_tracks, 2)
+    >>> P = np.tile(np.eye(2), (n_tracks, 1, 1))
+    >>> z = np.random.randn(n_tracks, 1) * 10 + 100
+    >>> R = np.array([[1.0]])
+    >>> result = batch_ukf_update(x, P, z, h_measurement, R)
+    >>> result.x.shape
+    (40, 2)
     """
     cp = import_optional("cupy", extra="gpu", feature="GPU Unscented Kalman filter")
 

pytcl/gpu/utils.py

@@ -115,6 +115,12 @@ def is_cupy_available() -> bool:
     -------
     bool
         True if CuPy acceleration is available.
+
+    Examples
+    --------
+    >>> from pytcl.gpu.utils import is_cupy_available
+    >>> if is_cupy_available():
+    ...     print("CUDA GPU available")
     """
     if not is_available("cupy"):
         _logger.debug("CuPy not installed")
@@ -430,6 +436,15 @@ def ensure_gpu_array(
     -------
     GPUArray
         Array on GPU with specified dtype (cupy.ndarray or mlx.array).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.gpu.utils import ensure_gpu_array, is_gpu_available
+    >>> x = np.array([1, 2, 3])
+    >>> if is_gpu_available():
+    ...     x_gpu = ensure_gpu_array(x, dtype=np.float32)
+    ...     print(x_gpu.dtype)
     """
     gpu_arr = to_gpu(arr, backend=backend)
 

pytcl/magnetism/igrf.py

@@ -53,6 +53,14 @@ def create_igrf13_coefficients() -> MagneticCoefficients:
     coeffs : MagneticCoefficients
         IGRF-13 spherical harmonic coefficients.
 
+    Examples
+    --------
+    >>> coeffs = create_igrf13_coefficients()
+    >>> coeffs.epoch
+    2020.0
+    >>> coeffs.n_max
+    13
+
     Notes
     -----
     IGRF-13 is valid from 1900.0 to 2025.0. This function returns
@@ -483,6 +491,18 @@ def igrf_declination(
     -------
     D : float
         Declination in radians.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.magnetism import igrf_declination
+    >>> # Declination at Denver (40°N, 105°W)
+    >>> lat = np.radians(40)
+    >>> lon = np.radians(-105)
+    >>> D = igrf_declination(lat, lon, 1.6, 2023.0)
+    >>> # Eastern US has westerly declination (~10-20° W)
+    >>> -0.35 < D < 0  # West is negative
+    True
     """
     return igrf(lat, lon, h, year).D
 
@@ -511,6 +531,19 @@ def igrf_inclination(
     -------
     I : float
         Inclination in radians.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.magnetism import igrf_inclination
+    >>> # Inclination comparison: equator vs pole
+    >>> I_eq = igrf_inclination(0, 0, 0, 2023.0)  # Equator
+    >>> I_pole = igrf_inclination(np.radians(85), 0, 0, 2023.0)  # Near pole
+    >>> # At equator, inclination is ~0; at poles it's ~90 degrees
+    >>> abs(I_eq) < 0.2  # ~11 degrees
+    True
+    >>> abs(I_pole) > 1.4  # ~80 degrees
+    True
     """
     return igrf(lat, lon, h, year).I
 
@@ -533,6 +566,16 @@ def dipole_moment(coeffs: MagneticCoefficients = IGRF13) -> float:
     -----
     The dipole moment is computed from the n=1 Gauss coefficients:
     M = a^3 * sqrt(g10^2 + g11^2 + h11^2)
+
+    Examples
+    --------
+    >>> from pytcl.magnetism import dipole_moment, IGRF13
+    >>> # Compute Earth's dipole moment from IGRF-13
+    >>> M = dipole_moment(IGRF13)
+    >>> # Earth's dipole moment is approximately 7.9 × 10^22 A·m²
+    >>> # In nT·km³ units, this is about 7.9 × 10^15
+    >>> 7e15 < M < 8.5e15
+    True
     """
     a = 6371.2  # Reference radius in km
     g10 = coeffs.g[1, 0]
@@ -565,6 +608,18 @@ def dipole_axis(
     -----
     The geomagnetic pole is where the centered dipole axis
     intersects the Earth's surface.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.magnetism import dipole_axis, IGRF13
+    >>> # Compute geomagnetic pole location
+    >>> lat, lon = dipole_axis(IGRF13)
+    >>> # Geomagnetic north pole is around 80°N, 72°W
+    >>> 70 < np.degrees(lat) < 85
+    True
+    >>> -100 < np.degrees(lon) < -60
+    True
     """
     g10 = coeffs.g[1, 0]
     g11 = coeffs.g[1, 1]
@@ -611,6 +666,23 @@ def magnetic_north_pole(
     -----
     This uses an iterative search starting from the dipole pole.
     The magnetic pole moves over time.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.magnetism import magnetic_north_pole, dipole_axis
+    >>> # Magnetic north pole location (2023)
+    >>> lat, lon = magnetic_north_pole(2023.0)
+    >>> # Should be in Canadian Arctic, around 80-85°N
+    >>> 75 < np.degrees(lat) < 90
+    True
+    >>> -150 < np.degrees(lon) < -60
+    True
+    >>> # Compare with geomagnetic pole
+    >>> geo_lat, geo_lon = dipole_axis()
+    >>> # Magnetic pole differs from geomagnetic pole
+    >>> abs(lat - geo_lat) > 0.01  # Different locations
+    True
     """
     # Start from dipole pole
     lat, lon = dipole_axis(coeffs)

pytcl/magnetism/wmm.py

@@ -103,6 +103,14 @@ def create_wmm2020_coefficients() -> MagneticCoefficients:
     coeffs : MagneticCoefficients
         WMM2020 spherical harmonic coefficients.
 
+    Examples
+    --------
+    >>> coeffs = create_wmm2020_coefficients()
+    >>> coeffs.epoch
+    2020.0
+    >>> coeffs.n_max
+    12
+
     Notes
     -----
     These are the official WMM2020 coefficients valid from 2020.0 to 2025.0.
@@ -727,6 +735,19 @@ def magnetic_field_spherical(
     to a configurable precision before caching to improve hit rates for
     nearby queries. Use `get_magnetic_cache_info()` to check cache
     statistics and `clear_magnetic_cache()` to free memory.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.magnetism import magnetic_field_spherical
+    >>> # Compute at Earth's surface (40°N, 105°W, sea level)
+    >>> lat = np.radians(40)
+    >>> lon = np.radians(-105)
+    >>> r = 6371.2  # Earth mean radius in km
+    >>> B_r, B_theta, B_phi = magnetic_field_spherical(lat, lon, r, 2023.0)
+    >>> # All components should be on order of tens to tens of thousands of nT
+    >>> 20000 < (B_r**2 + B_theta**2 + B_phi**2)**0.5 < 70000
+    True
     """
     if use_cache:
         # Quantize inputs for cache key
@@ -892,6 +913,21 @@ def magnetic_inclination(
         Magnetic inclination in radians.
         Positive = field points into Earth (Northern hemisphere).
         Negative = field points out of Earth (Southern hemisphere).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.magnetism import magnetic_inclination
+    >>> # Inclination at 40°N, 105°W (Denver)
+    >>> lat = np.radians(40)
+    >>> lon = np.radians(-105)
+    >>> I = magnetic_inclination(lat, lon, 1.6, 2023.0)
+    >>> # Northern hemisphere: inclination should be positive
+    >>> I > 0
+    True
+    >>> # Typical values in US are 50-70 degrees
+    >>> 0.8 < I < 1.3  # ~46-74 degrees
+    True
     """
     result = wmm(lat, lon, h, year, coeffs)
     return result.I
@@ -924,6 +960,22 @@ def magnetic_field_intensity(
     -------
     F : float
         Total magnetic field intensity in nT.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.magnetism import magnetic_field_intensity
+    >>> # Field intensity at magnetic equator vs pole
+    >>> F_eq = magnetic_field_intensity(0, 0, 0, 2023.0)  # Equator
+    >>> F_pole = magnetic_field_intensity(np.radians(80), 0, 0, 2023.0)  # Near pole
+    >>> # Field is stronger at poles
+    >>> F_pole > F_eq
+    True
+    >>> # Typical Earth field is 25,000 to 65,000 nT
+    >>> 25000 < F_eq < 35000  # Equatorial field is weaker
+    True
+    >>> 55000 < F_pole < 65000  # Polar field is stronger
+    True
     """
     result = wmm(lat, lon, h, year, coeffs)
     return result.F

pytcl/mathematical_functions/basic_matrix/decompositions.py

@@ -210,6 +210,13 @@ def pinv_truncated(
     A_pinv : ndarray
         Pseudo-inverse of A with shape (n, m).
 
+    Examples
+    --------
+    >>> A = np.array([[1, 2], [3, 4], [5, 6]])
+    >>> A_pinv = pinv_truncated(A)
+    >>> np.allclose(A @ A_pinv @ A, A)
+    True
+
     See Also
     --------
     numpy.linalg.pinv : Standard pseudo-inverse.