Documentation (#200)

* document finite_element.py

* document functionals.py

* document geometry.py

* doucment mappings.py

* Document moments.py

* document plotting.py

* document elements/tnt.py

* document elements/q

* document elements/kmv

* document element/guzman_neilan

* document elements/dual

* document functions

* document polynomials

* document polynomials.py

* .

Author: mscroggs

symfem/elements/dual.py

@@ -53,17 +53,32 @@ def __init__(
     def get_polynomial_basis(
         self, reshape: bool = True
     ) -> typing.List[AnyFunction]:
-        """Get the symbolic polynomial basis for the element."""
+        """Get the symbolic polynomial basis for the element.
+
+        Returns:
+            The polynomial basis
+        """
         raise ValueError("Polynomial basis not supported for barycentric dual elements.")
 
     def get_dual_matrix(self) -> sympy.matrices.dense.MutableDenseMatrix:
-        """Get the dual matrix."""
+        """Get the dual matrix.
+
+        Returns:
+            The dual matrix
+        """
         raise ValueError("Dual matrix not supported for barycentric dual elements.")
 
     def get_basis_functions(
         self, use_tensor_factorisation: bool = False
     ) -> typing.List[AnyFunction]:
-        """Get the basis functions of the element."""
+        """Get the basis functions of the element.
+
+        Args:
+            use_tensor_factorisation: Should a tensor factorisation be used?
+
+        Returns:
+            The basis functions
+        """
         assert not use_tensor_factorisation
 
         if self._basis_functions is None:
@@ -102,7 +117,15 @@ def get_basis_functions(
         return self._basis_functions
 
     def entity_dofs(self, entity_dim: int, entity_number: int) -> typing.List[int]:
-        """Get the numbers of the DOFs associated with the given entity."""
+        """Get the numbers of the DOFs associated with the given entity.
+
+        Args:
+            entity_dim: The dimension of the entity
+            entity_number: The number of the entity
+
+        Returns:
+            The numbers of the DOFs associated with the entity
+        """
         out = []
         for i, e in enumerate(self.dof_entities):
             if e == (entity_dim, entity_number):
@@ -115,14 +138,30 @@ def map_to_cell(
         forward_map: typing.Optional[PointType] = None,
         inverse_map: typing.Optional[PointType] = None
     ) -> typing.List[AnyFunction]:
-        """Map the basis onto a cell using the appropriate mapping for the element."""
+        """Map the basis onto a cell using the appropriate mapping for the element.
+
+        Args:
+            vertices_in: The vertices of the cell
+            basis: The basis functions
+            forward_map: The map from the reference to the cell
+            inverse_map: The map to the reference from the cell
+
+        Returns:
+            The basis functions mapped to the cell
+        """
         raise NotImplementedError()
 
     def plot_dof_diagram(
         self, filename: typing.Union[str, typing.List[str]],
         plot_options: typing.Dict[str, typing.Any] = {}, **kwargs: typing.Any
     ):
-        """Plot a diagram showing the DOFs of the element."""
+        """Plot a diagram showing the DOFs of the element.
+
+        Args:
+            filename: The file name
+            plot_options: Options for the plot
+            kwargs: Keyword arguments
+        """
         img = Picture(**kwargs)
 
         for entities in self.reference.z_ordered_entities():

symfem/elements/guzman_neilan.py

@@ -87,7 +87,15 @@ def __init__(self, reference: Reference, order: int):
     def _make_polyset_triangle(
         self, reference: Reference, order: int
     ) -> typing.List[FunctionInput]:
-        """Make the polyset for a triangle."""
+        """Make the polyset for a triangle.
+
+        Args:
+            reference: The reference cell
+            order: The polynomial order
+
+        Returns:
+            The polynomial set
+        """
         assert order == 1
 
         from ._guzman_neilan_triangle import coeffs
@@ -123,7 +131,15 @@ def _make_polyset_triangle(
     def _make_polyset_tetrahedron(
         self, reference: Reference, order: int
     ) -> typing.List[FunctionInput]:
-        """Make the polyset for a tetrahedron."""
+        """Make the polyset for a tetrahedron.
+
+        Args:
+            reference: The reference cell
+            order: The polynomial order
+
+        Returns:
+            The polynomial set
+        """
         assert order in [1, 2]
         from ._guzman_neilan_tetrahedron import coeffs
 
@@ -167,7 +183,18 @@ def make_piecewise_lagrange(
     sub_cells: typing.List[SetOfPoints], cell_name, order: int, zero_on_boundary: bool = False,
     zero_at_centre: bool = False
 ) -> typing.List[PiecewiseFunction]:
-    """Make the basis functions of a piecewise Lagrange space."""
+    """Make the basis functions of a piecewise Lagrange space.
+
+    Args:
+        sub_cells: A list of vertices of sub cells
+        cell_name: The cell type of the sub cells
+        order: The polynomial order
+        zero_in_boundary: Should the functions be zero on the boundary?
+        zero_at_centre: Should the functions be zero at the centre?
+
+    Returns:
+        The basis functions
+    """
     from symfem import create_reference
     lagrange_space = VectorLagrange(create_reference(cell_name), order)
     lagrange_bases: typing.List[typing.List[VectorFunction]] = []

symfem/elements/kmv.py

@@ -17,7 +17,15 @@
 
 
 def kmv_tri_polyset(m: int, mf: int) -> typing.List[FunctionInput]:
-    """Create the polynomial set for a KMV space on a triangle."""
+    """Create the polynomial set for a KMV space on a triangle.
+
+    Args:
+        m: The parameter m
+        mf: The parameter mf
+
+    Returns:
+        The polynomial set
+    """
     poly: typing.List[FunctionInput] = []
     poly += polynomial_set_1d(2, m)
 
@@ -29,7 +37,16 @@ def kmv_tri_polyset(m: int, mf: int) -> typing.List[FunctionInput]:
 
 
 def kmv_tet_polyset(m: int, mf: int, mi: int) -> typing.List[FunctionInput]:
-    """Create the polynomial set for a KMV space on a tetrahedron."""
+    """Create the polynomial set for a KMV space on a tetrahedron.
+
+    Args:
+        m: The parameter m
+        mf: The parameter mf
+        mi: The parameter mi
+
+    Returns:
+        The polynomial set
+    """
     poly: typing.List[FunctionInput] = []
     poly += polynomial_set_1d(3, m)
 

symfem/elements/q.py

@@ -57,7 +57,11 @@ def __init__(self, reference: Reference, order: int, variant: str = "equispaced"
     def get_tensor_factorisation(
         self
     ) -> typing.List[typing.Tuple[str, typing.List[FiniteElement], typing.List[int]]]:
-        """Get the representation of the element as a tensor product."""
+        """Get the representation of the element as a tensor product.
+
+        Returns:
+            The tensor factorisation
+        """
         from symfem import create_element
         interval_q = create_element("interval", "Lagrange", self.order)
 

symfem/elements/tnt.py

@@ -21,7 +21,15 @@
 
 
 def p(k: int, v: sympy.core.symbol.Symbol) -> ScalarFunction:
-    """Return the kth Legendre polynomial."""
+    """Return the kth Legendre polynomial.
+
+    Args:
+        k: k
+        v: The variable to use
+
+    Returns:
+        The kth Legendre polynomial
+    """
     return orthogonal_basis("interval", k, 0, [v])[0][-1]
 
 
@@ -30,6 +38,13 @@ def b(k: int, v: sympy.core.symbol.Symbol) -> ScalarFunction:
 
     This function is defined on page 4 (606) of
     https://doi.org/10.1090/S0025-5718-2013-02729-9 (Cockburn, Qiu, 2013).
+
+    Args:
+        k: k
+        v: The variable to use
+
+    Returns:
+        The function B_k
     """
     if k == 1:
         return ScalarFunction(0)