Update docs (#118)

* Add reference to Ciarlet

* DOI is for 2002 reprint

* add some examples to readme

* Add Nedelec demo
Add text to demos
Test snippets in readme

* Add a LAgrange test

* update demos

* Add demos to docs

* add more intro to readme

* Corrected mapping in Lagrange demo (#119)

Co-authored-by: Matthew Scroggs <[email protected]>

* Add fast test running to readme

* give reason for xfailing

Co-authored-by: Sigvald Marholm <[email protected]>

Author: mscroggs

README.md

@@ -9,10 +9,15 @@
 [![status](https://joss.theoj.org/papers/95e093272d6555489b1f941aebd6494b/status.svg)](https://joss.theoj.org/papers/95e093272d6555489b1f941aebd6494b)
 
 Symfem is a symbolic finite element definition library, that can be used to
-symbolically evaluate the basis functions of a finite element space.
+symbolically evaluate the basis functions of a finite element space. Symfem can:
+
+- Symbolically compute the basis functions of a wide range of finite element spaces
+- Symbolically compute derivatives and vector products and substitute values into functions
+- Allow the user to define their own element using the Ciarlet definition of a finite element
+- Be used to verify that the basis functions of a given space have some desired properties
 
 ## Installing Symfem
-### Installing from repo
+### Installing from sourde
 Symfem can be installed by downloading the [GitHub repo](https://github.com/mscroggs/symfem)
 and running:
 
@@ -41,10 +46,68 @@ To run the Symfem unit tests, clone the repository and run:
 python3 -m pytest test/
 ```
 
+You may instead like to run the following, as this will skip the slowest tests.
+
+```bash
+python3 -m pytest test/ --speed fast
+```
+
 ## Using Symfem
-Documentation of the latest release version of Symfem can be found on
-[Read the Docs](https://symfem.readthedocs.io/en/latest/).
+Finite elements can be created in Symfem using the `symfem.create_element()`
+function. For example, some elements are created in the following snippet:
+
+```python
+import symfem
 
+lagrange = symfem.create_element("triangle", "Lagrange", 1)
+rt = symfem.create_element("tetrahedron", "Raviart-Thomas", 2)
+nedelec = symfem.create_element("triangle", "N2curl", 1)
+qcurl = symfem.create_element("quadrilateral", "Qcurl", 2)
+```
+
+The polynomial basis of an element can be obtained by calling `get_polynomial_basis()`:
+
+```python
+import symfem
+
+lagrange = symfem.create_element("triangle", "Lagrange", 1)
+print(lagrange.get_basis_functions())
+```
+```
+[-x - y + 1, x, y]
+```
+
+Each basis function will be a [Sympy](https://www.sympy.org) symbolic expression.
+
+Derivative of these basis functions can be computed using the functions in
+[`symfem.calculus`](symfem/calculus.py). Vector-valued basis functions can
+be manipulated using the functions in [`symfem.vector`](symfem/vectors.py).
+
+The function `map_to_cell` can be used to map the basis functions of a finite element
+to a non-default cell:
+
+```python
+import symfem
+
+lagrange = symfem.create_element("triangle", "Lagrange", 1)
+print(lagrange.get_basis_functions())
+print(lagrange.map_to_cell([(0,0), (2, 0), (2, 1)]))
+```
+```
+[-x - y + 1, x, y]
+[1 - x/2, x/2 - y, y]
+```
+
+### Further documentation
+More detailed documentation of the latest release version of Symfem can be found on
+[Read the Docs](https://symfem.readthedocs.io/en/latest/). A series of example uses
+of Symfem can be found in the [`demo` folder](demo/) or viewed on
+[Read the Docs](https://symfem.readthedocs.io/en/latest/demos/index.html).
+
+Details of the definition of each element can be found on [DefElement](https://defelement.com)
+alongside Symfem snippets for creating the element.
+
+## Getting help
 You can ask questions about using Symfem by opening [an issue with the support label](https://github.com/mscroggs/symfem/issues/new?assignees=&labels=support&template=support.md&title=).
 You can view previously answered questions [here](https://github.com/mscroggs/symfem/issues?q=is%3Aclosed+label%3Asupport).
 
@@ -175,4 +238,3 @@ You can find information about how to contribute to Symfem [here](CONTRIBUTING.m
 - Buffa-Christiansen
 - dual
 - rotated Buffa-Christiansen
-

demo/custom_element.py

@@ -1,3 +1,7 @@
+"""
+This demo shows how a custom element can be created in Symfem.
+"""
+
 import symfem
 import sympy
 from symfem.finite_element import CiarletElement
@@ -40,3 +44,6 @@ def __init__(self, reference, order):
 # Create the element and print its basis functions
 element = symfem.create_element("quadrilateral", "custom quad element", 1)
 print(element.get_basis_functions())
+
+# Run the Symfem tests on the custom element
+element.test()

demo/lagrange.py

@@ -0,0 +1,42 @@
+"""
+This demo shows how Symfem can be used to verify properties of the basis functions of
+an element.
+
+The basis functions of a Lagrange element, when restricted to an edge of a cell,
+should be equal to the basis functions of a Lagrange space on that edge (or equal to 0).
+
+In this demo, we verify that this is true for an order 5 Lagrange element on a triangle.
+"""
+
+import symfem
+import sympy
+from symfem.symbolic import x, subs, symequal
+
+element = symfem.create_element("triangle", "Lagrange", 5)
+edge_element = symfem.create_element("interval", "Lagrange", 5)
+
+# Define a parameter that will go from 0 to 1 on the chosen edge
+a = sympy.Symbol("a")
+
+# Get the basis functions of the Lagrange space and substitute the parameter into the
+# functions on the edge
+basis = element.get_basis_functions()
+edge_basis = [subs(f, x[0], a) for f in edge_element.get_basis_functions()]
+
+# Get the DOFs on edge 0 (from vertex 1 (1,0) to vertex 2 (0,1))
+# (1 - a, a) is a parametrisation of this edge
+dofs = element.entity_dofs(0, 1) + element.entity_dofs(0, 2) + element.entity_dofs(1, 0)
+# Check that the basis functions on this edge are equal
+for d, edge_f in zip(dofs, edge_basis):
+    # symequal will simplify the expressions then check that they are equal
+    assert symequal(subs(basis[d], x[:2], (1 - a, a)),  edge_f)
+
+# Get the DOFs on edge 1 (from vertex 0 (0,0) to vertex 2 (0,1), parametrised (0, a))
+dofs = element.entity_dofs(0, 0) + element.entity_dofs(0, 2) + element.entity_dofs(1, 1)
+for d, edge_f in zip(dofs, edge_basis):
+    assert symequal(subs(basis[d], x[:2], (0, a)),  edge_f)
+
+# Get the DOFs on edge 2 (from vertex 0 (0,0) to vertex 1 (1,0), parametrised (a, 0))
+dofs = element.entity_dofs(0, 0) + element.entity_dofs(0, 1) + element.entity_dofs(1, 2)
+for d, edge_f in zip(dofs, edge_basis):
+    assert symequal(subs(basis[d], x[:2], (a, 0)),  edge_f)

demo/nedelec.py

@@ -0,0 +1,48 @@
+"""
+This demo shows how Symfem can be used to verify properties of the polynomial basis
+and basis functions of an element.
+
+The polynomial set of a degree k Nedelec first kind space is:
+{polynomials of degree < k} UNION {polynomials of degree k such that p DOT x = 0}.
+
+The basis functions of a Nedelec first kind that are associated with the interior of the cell
+have 0 tangential component on the facets of the cell.
+
+In this demo, we verify that these properties hold for a degree 4 Nedelec first kind
+space on a triangle.
+"""
+
+import symfem
+from symfem.polynomials import polynomial_set
+from symfem.symbolic import x, subs, symequal
+
+# In this demo, we use the function vdot to compute the dot product of two vectors.
+# The module symfem.vectors contains many functions that can be used to manipulate
+# vectors.
+from symfem.vectors import vdot
+
+element = symfem.create_element("triangle", "Nedelec1", 4)
+polys = element.get_polynomial_basis()
+
+# Check that the first 20 polynomials in the polynomial basis are
+# the polynomials of degree 3
+p3 = polynomial_set(2, 2, 3)
+assert len(p3) == 20
+for i, j in zip(p3, polys[:20]):
+    assert i == j
+
+# Check that the rest of the polynomials in the polynomial basis
+# satisfy p DOT x = 0
+for p in polys[20:]:
+    assert vdot(p, x) == 0
+
+# Get the basis functions associated with the interior of the triangle
+basis = element.get_basis_functions()
+functions = [basis[d] for d in element.entity_dofs(2, 0)]
+
+# Check that these functions have 0 tangential component on each edge
+# symequal will simplify the expressions then check that they are equal
+for f in functions:
+    assert symequal(vdot(subs(f, x[0], 1 - x[1]), (1, -1)), 0)
+    assert symequal(vdot(subs(f, x[0], 0), (0, 1)), 0)
+    assert symequal(vdot(subs(f, x[1], 0), (1, 0)), 0)

demo/stiffness_matrix.py

@@ -1,19 +1,34 @@
+"""
+This demo shows how Symfem can be used to compute a stiffness matrix.
+"""
+
 import symfem
 from symfem.vectors import vdot
 from symfem.calculus import grad
 
-matrix = [[0 for i in range(4)] for j in range(4)]
-
+# Define the vertived and triangles of the mesh
 vertices = [(0, 0), (1, 0), (0, 1), (1, 1)]
 triangles = [[0, 1, 2], [1, 3, 2]]
 
+# Create a matrix of zeros with the correct shape
+matrix = [[0 for i in range(4)] for j in range(4)]
+
+# Create a Lagrange element
 element = symfem.create_element("triangle", "Lagrange", 1)
+
 for triangle in triangles:
+    # Get the vertices of the triangle
     vs = [vertices[i] for i in triangle]
+    # Create a reference cell with these vertices: this will be used
+    # to compute the integral over the triangle
     ref = symfem.create_reference("triangle", vertices=vs)
+    # Map the basis functions to the cell
     basis = element.map_to_cell(vs)
+
     for test_i, test_f in zip(triangle, basis):
         for trial_i, trial_f in zip(triangle, basis):
+            # Compute the integral of grad(u)-dot-grad(v) for each pair of basis
+            # functions u and v
             integrand = vdot(grad(test_f, 2), grad(trial_f, 2))
             matrix[test_i][trial_i] += ref.integral(integrand)
 

docs/demos/index.rst

@@ -5,6 +5,7 @@ Symfem demos
 .. toctree::
    :titlesonly:
 
+   lagrange
+   nedelec
    stiffness_matrix
    custom_element
-

docs/demos/lagrange.rst

@@ -0,0 +1,10 @@
+###########################
+Checking a Lagrange element
+###########################
+
+This demo shows how Symfem can be used to confirm that when the basis functions of a Lagrange
+element of a triangle are restricted to an edge, then they are equal to the basis functions
+of a Lagrange element on that edge.
+
+.. literalinclude:: ../../demo/lagrange.py
+  :language: Python

docs/demos/nedelec.rst

@@ -0,0 +1,9 @@
+##########################
+Checking a Nedelec element
+##########################
+
+This demo shows how Symfem can be used to confirm that the polynomial set of a Nedelec
+first kind element are as expected.
+
+.. literalinclude:: ../../demo/nedelec.py
+  :language: Python

docs/index.rst

@@ -6,7 +6,11 @@
 Symfem
 ======
 
-Welcome to the documention of Symfem: a symbolic finite element definition library
+Welcome to the documention of Symfem: a symbolic finite element definition library.
+
+Symfem can be used to create a very wide range of finite element spaces. The basis functions
+of these spaces can be computed symbolically, allowing them to easily be further
+manipulated.
 
 *****************
 Installing Symfem
@@ -27,7 +31,7 @@ Using Symfem
 
 Finite elements
 ---------------
-Finite elements can be created in symfem using the :func:`symfem.create_element` function.
+Finite elements can be created in Symfem using the :func:`symfem.create_element` function.
 For example, some elements are created in the following snippet:
 
 .. code-block:: python
@@ -40,67 +44,69 @@ For example, some elements are created in the following snippet:
     qcurl = symfem.create_element("quadrilateral", "Qcurl", 2)
 
 `create_element` will create a :class:`symfem.finite_element.FiniteElement` object.
-From this object, the polynomial basis of the element can be obtained:
+The basis functions spanning the finite element space can be obtained, or tabulated
+at a set of points:
 
 .. code-block:: python
 
     import symfem
 
     lagrange = symfem.create_element("triangle", "Lagrange", 1)
-    print(lagrange.get_polynomial_basis())
+    print(lagrange.get_basis_functions())
+
+    points = [[0, 0], [0.5, 0], [1, 0], [0.25, 0.25]]
+    print(lagrange.tabulate_basis(points))
 
 ::
 
-    [1, x, y]
+    [-x - y + 1, x, y]
+    [[1, 0, 0], [0.500000000000000, 0.500000000000000, 0], [0, 1, 0], [0.500000000000000, 0.250000000000000, 0.250000000000000]]
 
-Each item in the polynomial basis will be a `Sympy <https://www.sympy.org>`_ symbolic expression.
+Each basis function will be a `Sympy <https://www.sympy.org>`_ symbolic expression.
 
-The functionals that define the DOFs of the finite element space can be obtained with the following
-snippet.
+The majority of the elements in Symfem are defined using Ciarlet's [Ciarlet]_ definition of
+a finite element (:class:`symfem.finite_element.CiarletElement`): these elements are using a
+polynomial set, and a set of functionals. In Symfem, the polynomial set
+of an element can be obtained by:
 
 .. code-block:: python
 
     import symfem
 
     lagrange = symfem.create_element("triangle", "Lagrange", 1)
-    print(lagrange.dofs)
+    print(lagrange.get_polynomial_basis())
 
 ::
 
-    [<symfem.functionals.PointEvaluation object at 0x{ADDRESS}>, <symfem.functionals.PointEvaluation object at 0x{ADDRESS}>, <symfem.functionals.PointEvaluation object at 0x{ADDRESS}>]
-
-Each functional will be a functional defined in :mod:`symfem.functionals`.
+    [1, x, y]
 
-The basis functions spanning the finite element space can be obtained, or tabulated
-at a set of points:
+The functionals of the finite element space can be obtained with the following snippet.
 
 .. code-block:: python
 
     import symfem
 
     lagrange = symfem.create_element("triangle", "Lagrange", 1)
-    print(lagrange.get_basis_functions())
-
-    points = [[0, 0], [0.5, 0], [1, 0], [0.25, 0.25]]
-    print(lagrange.tabulate_basis(points))
+    print(lagrange.dofs)
 
 ::
 
-    [-x - y + 1, x, y]
-    [[1, 0, 0], [0.500000000000000, 0.500000000000000, 0], [0, 1, 0], [0.500000000000000, 0.250000000000000, 0.250000000000000]]
+    [<symfem.functionals.PointEvaluation object at 0x{ADDRESS}>, <symfem.functionals.PointEvaluation object at 0x{ADDRESS}>, <symfem.functionals.PointEvaluation object at 0x{ADDRESS}>]
+
+Each functional will be a functional defined in :mod:`symfem.functionals`.
 
-Reference elements
-------------------
-Reference elements can be obtained from a :class:`symfem.finite_element.FiniteElement`:
+Reference cells
+---------------
+Reference cells can be obtained from a :class:`symfem.finite_element.FiniteElement`:
 
 .. code-block:: python
 
-    import symfem
+    import symfem   
 
     lagrange = symfem.create_element("triangle", "Lagrange", 1)
     reference = lagrange.reference
 
-Alternatively, reference elements can be created using the :func:`symfem.create_reference` function.
+Alternatively, reference cells can be created using the :func:`symfem.create_reference` function.
 For example:
 
 .. code-block:: python
@@ -115,7 +121,7 @@ For example:
 In the final example, the vertices of the reference have been provided, so a reference
 with these three vertices will be created.
 
-Various information about the reference can be accessed. The reference element's subentities
+Various information about the reference can be accessed. The reference cell's subentities
 can be obtained:
 
 .. code-block:: python
@@ -196,3 +202,5 @@ Documentation index
 
    demos/index
    docs/index
+
+.. [Ciarlet] P. G. Ciarlet, The Finite Element Method for Elliptic Problems (2002, first published 1978) [DOI: 10.1137/1.9780898719208](https://doi.org/10.1137/1.9780898719208)