Add constants page to documentation

- Add table of geodetic constants in docstring. - Add constants page to documentation. - Fix input parameters in class EKF of attitude estimator. - Change estimate_all() method to private method _compute_all() in class EKF. - Add typing hints to methods - Add build folder of docs to gitignore. - Fix docstrings in attitude estimators. - Remove redundant operations in attitude estimation of class Tilt. - Remove needs_sphinx in conf file of docs.
Mayitzin · Aug 14, 2020 · 020054f · 020054f
1 parent 90d8365
commit 020054f
Show file tree

Hide file tree

Showing 19 changed files with 257 additions and 175 deletions.
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,4 @@ dist/*
 
 # Documentation
 doctest/*
+docs/build/
diff --git a/ahrs/common/constants.py b/ahrs/common/constants.py
@@ -1,43 +1,129 @@
 # -*- coding: utf-8 -*-
 """
-Common constants used in AHRS and Geodesy
-=========================================
+Constants
+=========
 
-- Constants are defined in SI Units (second, metre, kilogram) unless otherwise
-  noted, or when constants are unitless.
+Common constants used in AHRS and Geodesy. The constants are defined in SI
+Units (second, metre, kilogram) unless otherwise noted, or when constants are
+unitless.
+
+**Basic Trigonometry**
+
+===========  ==================  =====================
+Name         Description         Value
+===========  ==================  =====================
+``M_PI``     Pi                  ``3.141592653589793``
+``DEG2RAD``  Degrees to Radians  ``0.017453292519943``
+``RAD2DEG``  Radians to Degrees  ``57.29577951308232``
+===========  ==================  =====================
+
+**Geodesy**
+
+The following constants are set as defined in the latest report of the World
+Geodetic System 1984 [WGS84]_. The CODATA constants are differentiated with a
+suffix of their origin indicating their epoch as of [CODATA2014]_ or [CODATA2018]_.
+
+====================================  ==============================================  =============
+Name                                  Description                                     Value
+====================================  ==============================================  =============
+``DYNAMIC_ELLIPTICITY``               Dynamic Ellipticity                             ``3.2737949e-3``
+``EARTH_ATMOSPHERE_MASS``             Mass of Atmosphere including water vapor        ``5.148e18``
+``EARTH_AUTHALIC_RADIUS``             Earth's Radius of equal area sphere             ``6371007.1810``
+``EARTH_AXIS_RATIO``                  Earth's Axis ratio                              ``9.96647189335e-1``
+``EARTH_C20_DYN``                     Earth's Dynamic 2nd Degree Zonal Harmonic       ``-4.84165143790815e-4``
+``EARTH_C22_DYN``                     Earth's Dynamic 2nd Degree Sectorial Harmonic   ``2.43938357328313e-6``
+``EARTH_C20_GEO``                     Earth's Geographic 2nd Degree Zonal Harmonic    ``-4.84166774985e-4``
+``EARTH_EQUATOR_RADIUS``              Earth's Semi-major axis (Equatorial Radius)     ``6378137.0``
+``EARTH_EQUIVOLUMETRIC_RADIUS``       Earth's Radius of equal volume sphere           ``6371000.79``
+``EARTH_FIRST_ECCENTRICITY``          Earth's First Eccentricity                      ``8.1819190842622e-2``
+``EARTH_FIRST_ECCENTRICITY_2``        Earth's First Eccentricity Squared              ``6.6943799901414e-3``
+``EARTH_FLATTENING_INV``              Earth's Flattening Factor                       ``298.257223563``
+``EARTH_FLATTENING``                  Earth's Flattening Factor (reduced)             ``1/298.257223563``
+``EARTH_GM``                          Earth's Gravitational Constant (GM)             ``3.986004418e14``
+``EARTH_GM_1``                        Earth's GM without Atmosphere                   ``3.986000982e14``
+``EARTH_GM_2``                        Earth Atmosphere's Gravitational Constant       ``3.4359e8``
+``EARTH_GM_GPSNAV``                   Earth's GM for GPS Navigation                   ``3.9860050e14``
+``EARTH_J2``                          Earth's Dynamic Form Factor                     ``1.08263e-3``
+``EARTH_LINEAR_ECCENTRICITY``         Earth's Linear Eccentricity                     ``5.2185400842339e5``
+``EARTH_MEAN_RADIUS``                 Earth's Arithmetic Mean radius                  ``6371200.0``
+``EARTH_MEAN_AXIAL_RADIUS``           Earth's Mean Radius of the three semi-axes      ``6371008.7714``
+``EARTH_MASS``                        Earth's Mass (Atmosphere inclulded)             ``5.9721864e24``
+``EARTH_POLAR_CURVATURE_RADIUS``      Earth's Polar Radius of Curvature               ``6_399_593.6258``
+``EARTH_POLAR_RADIUS``                Earth's Semi-minor axis (Polar Radius)          ``6356752.3142``
+``EARTH_ROTATION``                    Earth's Rotation rate                           ``7.292115e-5``
+``EARTH_SECOND_ECCENTRICITY``         Earth's Second Eccentricity                     ``8.2094437949696e-2``
+``EARTH_SECOND_ECCENTRICITY_2``       Earth's Second Eccentricity Squared             ``6.739496742276486e-3``
+``EARTH_SIDEREAL_DAY``                Earth's duration of sidereal day                ``86164.09053083288``
+``EQUATORIAL_NORMAL_GRAVITY``         Earth's Normal Gravity at the Equator           ``9.7803253359``
+``LIGHT_SPEED``                       Velocity of light in vacuum                     ``2.99792458e8``
+``MEAN_NORMAL_GRAVITY``               Earth's Mean Normal Gravity                     ``9.7976432223``
+``NORMAL_GRAVITY_FORMULA``            Constant for Normal Gravity Formula             ``3.449786506841e-3``
+``NORMAL_GRAVITY_POTENTIAL``          Earth's Normal Gravity Potential                ``6.26368517146``
+``POLAR_NORMAL_GRAVITY``              Earth's Normal Gravity at the Pole              ``9.8321849379``
+``SOMIGLIANA_GRAVITY``                Constant for Somigliana's Formula               ``1.931852652458e-3``
+``UNIVERSAL_GRAVITATION_CODATA2014``  Universal Gravitation defined in CODATA2014     ``6.67408e-11``
+``UNIVERSAL_GRAVITATION_CODATA2018``  Universal Gravitation defined in CODATA2018     ``6.67430e-11``
+``UNIVERSAL_GRAVITATION_WGS84``       Universal Gravitation defined in WGS84          ``6.67428e-11``
+====================================  ==============================================  =============
+
+Although, hard defined, most of these values can be also obtained with the
+class ``WGS`` of this package, which builds the World's Geodetic System
+defined in [WGS84]_.
+
+The elemental defining parameters (equatorial radius, flattening, gravitational
+constant and rotational velocity) are set, by default, to that of Earth's. All
+other parameters are derived from these. Just to compare:
+
+.. code:: python
+
+    >>> ahrs.EARTH_EQUATOR_RADIUS
+    6378137.0
+    >>> ahrs.EARTH_POLAR_RADIUS
+    6356752.3142
+    >>> ahrs.EARTH_FIRST_ECCENTRICITY_2
+    0.0066943799901414
+    >>> wgs = ahrs.utils.WGS()  # Default model is Earth's
+    >>> wgs.a
+    6378137.0
+    >>> wgs.b
+    6356752.314245179
+    >>> wgs.first_eccentricity_squared
+    0.0066943799901413165
 
 References
 ----------
-.. [1] World Geodetic System 1984. Its Definition and Relationships with Local
-       Geodetic Systems. National Geospatial-Intelligence Agency (NGA)
-       Standarization Document. 2014.
-       (ftp://ftp.nga.mil/pub2/gandg/website/wgs84/NGA.STND.0036_1.0.0_WGS84.pdf)
-.. [2] F. Chambat. Mean radius, mass, and inertia for reference Earth models.
-       Physics of the Earth and Planetary Interiors Vol 124 (2001) p237–253.
-.. [3] Archinal, B.A. et al. 2018. "Report of the IAU/IAG Working Group on
-       cartographic coordinates and rotational elements: 2015" Celestial Mech.
-       Dyn. Astr. 130:22.
-       (https://link.springer.com/epdf/10.1007/s10569-017-9805-5)
-.. [4] 2018 CODATA Recommended Values of the Fundamental Constants of Physics
-       and Chemistry. NIST. June 2019.
-       (https://physics.nist.gov/cuu/pdf/wallet_2018.pdf)
-.. [5] 2014 CODATA Recommended Values of the Fundamental Constants of Physics
-       and Chemistry. NIST. August 2015.
-       (https://physics.nist.gov/cuu/pdf/wallet_2014.pdf)
-.. [6] Ryan S. Park. Planets and Pluto: Physical Characteristics. NASA Jet
-       Propulsion Laboratory. California Institute of Technology. 29th May 2020.
-       (https://ssd.jpl.nasa.gov/?planet_phys_par)
-.. [7] David R. Williams. Planetary Fact Sheet - Metric. NASA Goddard Space
-       Flight Center. 21st October 2019.
-       (https://nssdc.gsfc.nasa.gov/planetary/factsheet/)
+.. [WGS84] World Geodetic System 1984. Its Definition and Relationships with
+    Local Geodetic Systems. National Geospatial-Intelligence Agency (NGA)
+    Standarization Document. 2014.
+    (ftp://ftp.nga.mil/pub2/gandg/website/wgs84/NGA.STND.0036_1.0.0_WGS84.pdf)
+.. [Chambat] F. Chambat. Mean radius, mass, and inertia for reference Earth
+    models. Physics of the Earth and Planetary Interiors Vol 124 (2001)
+    p237–253.
+.. [Archinal] Archinal, B.A. et al. 2018. "Report of the IAU/IAG Working Group
+    on cartographic coordinates and rotational elements: 2015" Celestial Mech.
+    Dyn. Astr. 130:22.
+    (https://astropedia.astrogeology.usgs.gov/download/Docs/WGCCRE/WGCCRE2015reprint.pdf)
+.. [CODATA2018] 2018 CODATA Recommended Values of the Fundamental Constants of
+    Physics and Chemistry. NIST. June 2019.
+    (https://physics.nist.gov/cuu/pdf/wallet_2018.pdf)
+.. [CODATA2014] 2014 CODATA Recommended Values of the Fundamental Constants of
+    Physics and Chemistry. NIST. August 2015.
+    (https://physics.nist.gov/cuu/pdf/wallet_2014.pdf)
+.. [Park] Ryan S. Park. Planets and Pluto: Physical Characteristics. NASA Jet
+    Propulsion Laboratory. California Institute of Technology. 29th May 2020.
+    (https://ssd.jpl.nasa.gov/?planet_phys_par)
+.. [Williams] David R. Williams. Planetary Fact Sheet - Metric. NASA Goddard
+    Space Flight Center. 21st October 2019.
+    (https://nssdc.gsfc.nasa.gov/planetary/factsheet/)
 
 """
-import numpy as np
+
+import cmath
 
 # TRIGONOMETRY
-M_PI = np.pi
-DEG2RAD = np.pi/180.0
-RAD2DEG = 180.0/np.pi
+M_PI = cmath.pi
+DEG2RAD = M_PI/180
+RAD2DEG = 180/M_PI
 
 ##### Geodetic constants as defined in WORLD GEODETIC SYSTEM 1984 (rev. 2014)
 # Defining parameters
@@ -67,7 +153,7 @@
 EARTH_MEAN_RADIUS = 6_371_200.0                 # Earth's Arithmetic Mean radius [m] ((2*EQUATOR_RADIUS + POLAR_RADIUS) / 3)
 EARTH_MEAN_AXIAL_RADIUS = 6_371_008.7714        # Mean Radius of the Three Semi-axes [m]
 EARTH_AUTHALIC_RADIUS = 6_371_007.1810          # Radius of equal area sphere [m]
-EARTH_EQUIVOLUMETRIC_RADIUS = 6_371_000.79      # Tadius of equal volume sphere [m] ((EQUATOR_RADIUS^2 * POLAR_RADIUS)^(1/3))
+EARTH_EQUIVOLUMETRIC_RADIUS = 6_371_000.79      # Radius of equal volume sphere [m] ((EQUATOR_RADIUS^2 * POLAR_RADIUS)^(1/3))
 EARTH_C20_DYN = -4.84165143790815e-4            # Earth's Dynamic Second Degree Zonal Harmonic (C_2,0 dyn)
 EARTH_C22_DYN = 2.43938357328313e-6             # Earth's Dynamic Second Degree Sectorial Harmonic (C_2,2 dyn)
 EARTH_C20_GEO = -4.84166774985e-4               # Earth's Geographic Second Degree Zonal Harmonic

diff --git a/ahrs/filters/angular.py b/ahrs/filters/angular.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-Quaternion from angular rate
-============================
+Attitude from angular rate
+==========================
 
 Attitude quaternion obtained via angular rate measurements.
 
@@ -19,7 +19,8 @@
 from ..common.orientation import q_prod
 
 class AngularRate:
-    """Quaternion Estimation based on angular velocity
+    """
+    Quaternion Estimation based on angular velocity
 
     Parameters
     ----------
@@ -64,7 +65,7 @@ def update(self, q: np.ndarray, gyr: np.ndarray):
         q : numpy.ndarray
             A-priori quaternion.
         gyr : numpy.ndarray, default: None
-            N-by-3 array with measurements of angular velocity in rad/s
+            Array with triaxial measurements of angular velocity in rad/s
 
         Returns
         -------

diff --git a/ahrs/filters/aqua.py b/ahrs/filters/aqua.py
@@ -41,10 +41,10 @@
 
 def slerp_I(q: np.ndarray, ratio: float, t: float) -> np.ndarray:
     """
-    Quaternion Interpolation with Identity
+    Interpolation with identity quaternion
 
-    Interpolate a given quaternion with identity quaternion
-    :math:`\\mathbf{q}=\\begin{bmatrix}1 & 0 & 0 & 0\\end{bmatrix}` to
+    Interpolate a given quaternion with the identity quaternion
+    :math:`\\mathbf{q}_I=\\begin{pmatrix}1 & 0 & 0 & 0\\end{pmatrix}` to
     scale it to closest versor.
 
     The interpolation can be with either LERP (Linear) or SLERP (Spherical
@@ -62,7 +62,6 @@ def slerp_I(q: np.ndarray, ratio: float, t: float) -> np.ndarray:
     For LERP, a simple equation is implemented:
 
     .. math::
-
         \\hat{\\mathbf{q}} = (1-\\alpha)\\mathbf{q}_I + \\alpha\\Delta \\mathbf{q}
 
     where :math:`\\alpha\\in [0, 1]` is the gain characterizing the cut-off
@@ -85,7 +84,8 @@ def slerp_I(q: np.ndarray, ratio: float, t: float) -> np.ndarray:
     ratio : float
         Gain characterizing the cut-off frequency of the filter.
     t : float
-        Threshold deciding interpolation method. LERP when q_w>t or SLERP
+        Threshold deciding interpolation method. LERP when qw>t, otherwise
+        SLERP.
 
     Returns
     -------
@@ -120,6 +120,7 @@ def adaptive_gain(a: float, a_norm: float, t1: float = 0.1, t2: float = 0.2, g:
 
     The gain factor is constant and equal to 1 when the magnitude of the
     nongravitational acceleration is not high enough to overcome gravity.
+
     If nongravitational acceleration rises and :math:`e_m` exceeds the
     first threshold, the gain factor :math:`f` decreases linearly with the
     increase of the magnitude until reaching zero at the second threshold
@@ -295,11 +296,12 @@ def init_q(self, acc: np.ndarray, mag: np.ndarray = None) -> np.ndarray:
         return q_acc
 
     def updateIMU(self, q: np.ndarray, gyr: np.ndarray, acc: np.ndarray) -> np.ndarray:
-        """Quaternion Estimation with a IMU architecture.
+        """
+        Quaternion Estimation with a IMU architecture.
 
-        The estimation is made in two steps: a _prediction_ is done with the
+        The estimation is made in two steps: a *prediction* is done with the
         angular rate (gyroscope) to integrate and estimate the current
-        orientation; then a _correction_ step uses the measured accelerometer
+        orientation; then a *correction* step uses the measured accelerometer
         to infer the expected gravity vector and use it to correct the
         predicted quaternion.
 
@@ -342,11 +344,12 @@ def updateIMU(self, q: np.ndarray, gyr: np.ndarray, acc: np.ndarray) -> np.ndarr
         return q_prime/np.linalg.norm(q_prime)
 
     def updateMARG(self, q: np.ndarray, gyr: np.ndarray, acc: np.ndarray, mag: np.ndarray) -> np.ndarray:
-        """Quaternion Estimation with a MARG architecture.
+        """
+        Quaternion Estimation with a MARG architecture.
 
-        The estimation is made in two steps: a _prediction_ is done with the
+        The estimation is made in two steps: a *prediction* is done with the
         angular rate (gyroscope) to integrate and estimate the current
-        orientation; then a _correction_ step uses the measured accelerometer
+        orientation; then a *correction* step uses the measured accelerometer
         and magnetic field to infer the expected geodetic values. Its
         divergence is used to correct the predicted quaternion.
 
@@ -365,7 +368,7 @@ def updateMARG(self, q: np.ndarray, gyr: np.ndarray, acc: np.ndarray, mag: np.nd
         acc : numpy.ndarray
             Sample of tri-axial Accelerometer in m/s^2
         mag : numpy.ndarray
-            Sample of tri-axial Magnetometer in T
+            Sample of tri-axial Magnetometer in mT
 
         Returns
         -------

diff --git a/ahrs/filters/davenport.py b/ahrs/filters/davenport.py
@@ -3,11 +3,11 @@
 Davenport's q-Method
 ====================
 
-Attitude estimation as proposed by Paul Davenport [Davenport]_.
+Paul Davenport's q-method to estimate attitude as proposed in [Davenport1968]_.
 
 References
 ----------
-.. [Davenport] Paul B. Davenport. A Vector Approach to the Algebra of Rotations
+.. [Davenport1968] Paul B. Davenport. A Vector Approach to the Algebra of Rotations
     with Applications. NASA Technical Note D-4696. August 1968.
     (https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19680021122.pdf)