Merge some docstrings from module-components and the api (#303)

This picks off most of the very easy docstrings, include the wrapper functions that just forward to a multivector method.

A couple of methods in printer.py got proper `sphinx.ext.napoleon` docstrings, and a few others got docstrings for the first time.

Author: eric-wieser

doc/module-components.rst

@@ -466,106 +466,60 @@ If we can instantiate multivectors we can use all the multivector class function
 Basic Multivector Functions
 ---------------------------
 
-.. function:: com(A,B)
+.. automethod:: galgebra.ga.Ga.com
    :noindex:
 
-   Calculate commutator of multivectors :math:`A` and :math:`B`. Returns :math:`(AB-BA)/2`.
-
-   Additionally, commutator and anti-commutator operators are defined by
-
-   .. math::
-
-      $\begin{aligned}
-                  \texttt{A >> B} \equiv & {\displaystyle\frac{AB - BA}{2}} \\
-                  \texttt{A << B} \equiv & {\displaystyle\frac{AB + BA}{2}}.
-          \end{aligned}
-
-.. function:: cross(v1,v2)
+.. autofunction:: galgebra.mv.cross
    :noindex:
 
-   If ``v1`` and ``v2`` are 3-dimensional Euclidean vectors the vector cross product is returned, :math:`v_{1}\times v_{2} = -I{\lp {v_{1}{\wedge}v_{2}} \rp }`.
-
-.. function:: printer.def_prec(gd,op_ord='<>|,^,*')
+.. autofunction:: galgebra.printer.def_prec
    :noindex:
 
-   This is used with the ``GAeval()`` function to evaluate a string representing a multivector expression with a revised operator precedence. ``def_prec()`` redefines the operator precedence for multivectors. ``def_prec()`` must be called in the main program an the argument ``gd`` must be ``globals()``. The argument ``op_ord`` defines the order of operator precedence from high to low with groups of equal precedence separated by commas. the default precedence ``op_ord='<>|,^,\*'`` is that used by
-   Hestenes (:cite:`Hestenes`,p7,:cite:`Doran`,p38).
-
-.. function:: dual(A,mode='I+')
+.. autofunction:: galgebra.mv.dual
    :noindex:
 
-   Return the dual of the multivector ``A``. The default operation is :math:`AI`. For other modes see member function ``Mv.dual(mode)``
-
-.. function:: even(A)
+.. autofunction:: galgebra.mv.even
    :noindex:
 
-   Return even part of :math:`A`.
-
-.. function:: exp(A,hint='-')
+.. autofunction:: galgebra.mv.exp
    :noindex:
 
-   If :math:`A` is a multivector then ``A.exp(hint)`` is returned. If :math:`A` is a *sympy* expression the *sympy* expression :math:`e^{A}` is returned (see ``sympy.exp(A)`` member function).
-
-.. function:: printer.GAeval(s,pstr=False)
+.. autofunction:: galgebra.printer.GAeval
    :noindex:
 
-   Returns multivector expression for string ``s`` with operator precedence for string ``s`` defined by inputs to function ``def_prec()``. if ``pstr=True`` ``s`` and ``s`` with parenthesis added to enforce operator precedence are printed.
-
-.. function:: grade(A,r=0)
+.. autofunction:: galgebra.mv.grade
    :noindex:
 
-   If :math:`A` is a multivector :math:`{\left < {A} \right >}_{r}` is returned.
-
-.. function:: inv(A)
+.. autofunction:: galgebra.mv.inv
    :noindex:
 
-   If :math:`A` is a multivector and :math:`AA^{{\dagger}}` is a non-zero scalar then :math:`A^{-1} = A^{{\dagger}}/(AA^{{\dagger}})` is returned otherwise an exception is returned.
-
-.. function:: Nga(x,prec=5)
+.. autofunction:: galgebra.mv.Nga
    :noindex:
 
-   If ``x`` is a multivector with coefficients that contain floating point numbers, ``Nga()`` rounds all these numbers to a precision of ``prec`` and returns the rounded multivector.
-
-.. function:: norm(A,hint='-')
+.. autofunction:: galgebra.mv.norm
    :noindex:
 
-   If :math:`A` is a multivector and :math:`AA^{{\dagger}}` is a number (not a scalar function) then :math:`\sqrt{{\left |{AA^{{\dagger}}}\right |}}` is returned. If :math:`AA^{{\dagger}}` is a scalar *sympy* expression, but not a number, and ``hint='-'`` then return :math:`\sqrt{-AA^{{\dagger}}}` otherwise return :math:`\sqrt{AA^{{\dagger}}}`.
-
-.. function:: norm2(A)
+.. autofunction:: galgebra.mv.norm2
    :noindex:
 
-   If :math:`A` is a multivector and :math:`AA^{{\dagger}}` is a scalar return :math:`{\left |{AA^{{\dagger}}}\right |}`.
-
-.. function:: odd(A)
+.. autofunction:: galgebra.mv.odd
    :noindex:
 
-   Return odd part of :math:`A`.
-
-.. function:: proj(B,A)
+.. autofunction:: galgebra.mv.proj
    :noindex:
 
-   Project blade ``A`` on blade ``B`` returning :math:`{\lp {A\rfloor B} \rp }B^{-1}`.
-
-.. function:: ReciprocalFrame(basis,mode='norm')
+.. automethod:: galgebra.ga.Ga.ReciprocalFrame(basis,mode='norm')
    :noindex:
 
-   If ``basis`` is a list/tuple of vectors, ``ReciprocalFrame()`` returns a tuple of reciprocal vectors. If ``mode=norm`` the vectors are normalized. If ``mode`` is anything other than ``norm`` the vectors are unnormalized and the normalization coefficient is added to the end of the tuple. One must divide by this coefficient to normalize the vectors.
-
-.. function:: refl(B,A)
+.. autofunction:: galgebra.mv.refl(B,A)
    :noindex:
 
-   Reflect multivector :math:`A` in blade :math:`B`. If :math:`s` is grade of :math:`B` returns :math:`\sum_{r}(-1)^{s(r+1)}B{\left < {A} \right >}_{r}B^{-1}`.
-
-.. function:: rev(A)
+.. autofunction:: galgebra.mv.rev(A)
    :noindex:
 
-   If :math:`A` is a multivector return :math:`A^{{\dagger}}`.
-
-.. function:: rot(itheta,A,hint='-')
+.. autofunction:: galgebra.mv.rot(itheta,A,hint='-')
    :noindex:
 
-   If ``A`` is a multivector return ``A.rotate_multivector(itheta,hint)`` where ``itheta`` is the bi-vector blade defining the rotation. For the use of ``hint`` see the member function ``Mv.rotate_multivector(self,itheta,hint)``.
-
 .. _makeMVD:
 
 Multivector Derivatives

galgebra/ga.py

@@ -361,6 +361,18 @@ def dual_mode(mode='I+'):
 
     @staticmethod
     def com(A, B):
+        r"""
+        Calculate commutator of multivectors :math:`A` and :math:`B`. Returns :math:`(AB-BA)/2`.
+
+        Additionally, commutator and anti-commutator operators are defined by
+
+        .. math::
+
+            \begin{aligned}
+                \texttt{A >> B} \equiv & {\displaystyle\frac{AB - BA}{2}} \\
+                \texttt{A << B} \equiv & {\displaystyle\frac{AB + BA}{2}}.
+            \end{aligned}
+        """
         return half * (A * B - B * A)
 
     @staticmethod
@@ -1965,6 +1977,14 @@ def connection(self, rbase, key_base, mode, left):
         return C
 
     def ReciprocalFrame(self, basis, mode='norm'):
+        """
+        If ``basis`` is a list/tuple of vectors, ``ReciprocalFrame()`` returns a tuple of reciprocal vectors.
+
+        If ``mode=norm`` the vectors are normalized.
+        If ``mode`` is anything other than ``norm`` the vectors are unnormalized
+        and the normalization coefficient is added to the end of the tuple.
+        One must divide by this coefficient to normalize the vectors.
+        """
         dim = len(basis)
 
         indexes = tuple(range(dim))

galgebra/mv.py

@@ -1828,6 +1828,13 @@ def _eval_derivative_n_times(self, x, n):
 
 
 def Nga(x, prec=5):
+    """
+    Like :func:`sympy.N`, but also works on multivectors
+
+    For multivectors with coefficients that contain floating point numbers, this
+    rounds all these numbers to a precision of ``prec`` and returns the rounded
+    multivector.
+    """
     if isinstance(x, Mv):
         return Mv(Nsympy(x.obj, prec), ga=x.Ga)
     else:
@@ -1905,94 +1912,123 @@ def correlation(u, v, dec=3):  # Compute the correlation coefficient of vectors
 
 
 def cross(v1, v2):
+    r"""
+    If ``v1`` and ``v2`` are 3-dimensional Euclidean vectors, compute the vector
+    cross product :math:`v_{1}\times v_{2} = -I{\lp {v_{1}{\wedge}v_{2}} \rp }`.
+    """
     if v1.is_vector() and v2.is_vector() and v1.Ga == v2.Ga and v1.Ga.n == 3:
         return -v1.Ga.I() * (v1 ^ v2)
     else:
         raise ValueError(str(v1) + ' and ' + str(v2) + ' not compatible for cross product.')
 
 
 def dual(A):
+    """ Equivalent to :meth:`Mv.dual` """
     if isinstance(A, Mv):
         return A.dual()
     else:
         raise ValueError('A not a multivector in dual(A)')
 
 
 def even(A):
+    """ Equivalent to :meth:`Mv.even` """
     if not isinstance(A, Mv):
         raise ValueError('A = ' + str(A) + ' not a multivector in even(A).')
     return A.even()
 
 
 def odd(A):
+    """ Equivalent to :meth:`Mv.odd` """
     if not isinstance(A, Mv):
         raise ValueError('A = ' + str(A) + ' not a multivector in even(A).')
     return A.odd()
 
 
 def exp(A, hint='-'):
+    """
+    If ``A`` is a multivector then ``A.exp(hint)`` is returned.
+    If ``A`` is a *sympy* expression the *sympy* expression :math:`e^{A}` is returned (see :func:`sympy.exp`).
+    """
     if isinstance(A, Mv):
         return A.exp(hint)
     else:
         return sympy_exp(A)
 
 
 def grade(A, r=0):
+    """ Equivalent to :meth:`Mv.grade` """
     if isinstance(A, Mv):
         return A.grade(r)
     else:
         raise ValueError('A not a multivector in grade(A, r)')
 
 
 def inv(A):
+    """ Equivalent to :meth:`Mv.inv` """
     if not isinstance(A, Mv):
         raise ValueError('A = ' + str(A) + ' not a multivector in inv(A).')
     return A.inv()
 
 
 def norm(A, hint='+'):
+    """ Equivalent to :meth:`Mv.norm` """
     if isinstance(A, Mv):
         return A.norm(hint=hint)
     else:
         raise ValueError('A not a multivector in norm(A)')
 
 
 def norm2(A):
+    """ Equivalent to :meth:`Mv.norm2` """
     if isinstance(A, Mv):
         return A.norm2()
     else:
         raise ValueError('A not a multivector in norm(A)')
 
 
-def proj(B, A):  # Project on the blade B the multivector A
+def proj(B, A):
+    """ Equivalent to :meth:`Mv.project_in_blade` """
     if isinstance(A, Mv):
         return A.project_in_blade(B)
     else:
         raise ValueError('A not a multivector in proj(B, A)')
 
 
-def rot(itheta, A, hint='-'):  # Rotate by the 2-blade itheta the multivector A
+def rot(itheta, A, hint='-'):
+    """
+    Equivalent to ``A.rotate_multivector(itheta, hint)`` where ``itheta`` is the bi-vector blade defining the rotation.
+    For the use of ``hint`` see the method :meth:`Mv.rotate_multivector`.
+    """
     if isinstance(A, Mv):
         return A.rotate_multivector(itheta, hint)
     else:
         raise ValueError('A not a multivector in rotate(A, itheta)')
 
 
-def refl(B, A):  # Project on the blade B the multivector A
+def refl(B, A):
+    r"""
+    Reflect multivector :math:`A` in blade :math:`B`.
+
+    If :math:`s` is grade of :math:`B` returns :math:`\sum_{r}(-1)^{s(r+1)}B{\left < {A} \right >}_{r}B^{-1}`.
+
+    Equivalent to :meth:`Mv.reflect_in_blade`
+    """
     if isinstance(A, Mv):
         return A.reflect_in_blade(B)
     else:
         raise ValueError('A not a multivector in reflect(B, A)')
 
 
 def rev(A):
+    """ Equivalent to :meth:`Mv.rev` """
     if isinstance(A, Mv):
         return A.rev()
     else:
         raise ValueError('A not a multivector in rev(A)')
 
 
 def scalar(A):
+    """ Equivalent to :meth:`Mv.scalar` """
     if not isinstance(A, Mv):
         raise ValueError('A = ' + str(A) + ' not a multivector in inv(A).')
     return A.scalar()

galgebra/printer.py

@@ -1195,7 +1195,18 @@ def Print_Function():
        '*': r'(([A-Za-z0-9\_\#]+)[\*]{1}([A-Za-z0-9\_\#]+)([\*]{1}([A-Za-z0-9\_\#]+))*)'}
 
 
-def def_prec(gd, op_ord='<>|,^,*'):  # Default is Doran and Lasenby convention
+def def_prec(gd: dict, op_ord: str = '<>|,^,*') -> None:
+    """
+    This is used with the ``GAeval()`` function to evaluate a string representing a multivector expression with a revised operator precedence.
+
+    Parameters
+    ----------
+    gd :
+        The ``globals()`` dictionary to lookup variable names in.
+    op_ord :
+        The order of operator precedence from high to low with groups of equal precedence separated by commas.
+        The default precedence, ``'<>|,^,*'``, is that used by Hestenes (:cite:`Hestenes`, p7, :cite:`Doran`, p38).
+    """
     global global_dict, op_dict, op_lst
     global_dict = gd
     op_lst = op_ord.split(',')
@@ -1351,14 +1362,21 @@ def parse_line(line):
     return line
 
 
-def GAeval(s, pstr=False):
+def GAeval(s: str, pstr: bool = False):
     """
-    GAeval converts a string to a multivector expression where the
-    user can control the precedence of the of the multivector operators so
-    that one does not need to put parenthesis around every multivector
-    operation.  The default precedence used (high to low) is <,>, and | have
-    an have the highest precedence, then comes ^, and finally *.  The
-    default precedence can be changed with the def_prec function.
+    Evaluate a multivector expression string ``s``.
+
+    The operator precedence and variable values within the string are
+    controlled by :func:`def_prec`. The documentation for that function
+    describes the default precedence.
+
+    Parameters
+    ----------
+    s :
+        The string to evaluate.
+    pstr :
+        If ``True``, the values of ``s`` and ``s`` with parenthesis added to
+        enforce operator precedence are printed.
     """
 
     seval = parse_line(s)