an encyclopedia of finite element definitions
If you find a mistake in the DefElement database, please report it on the issue tracker using the Mistake report template.
If you want to suggest a new element to be added to DefElement, suggest it on the issue tracker using the New element template.
If you want to suggest a new featute or improvement to DefElement, suggest it on the issue tracker using the Suggest an improvement template.
You can use GitHub's Discussions to discuss ideas you have for features (that perhaps aren't fully formed enough yet to make an issue) or to discuss other people's ideas. You're welcome to also use the Discussions to just chat to other members of the community.
If you want to directly submit changes to DefElement, you can do this by forking the DefElement GitHub repository, making changes, then submitting a pull request. If you want to contribute, but are unsure where to start, have a look at the issue tracker for issues labelled "good first issue".
The functional information and examples on the element pages are generated using Symfem, a symbolic finite element definition library. Before adding an element to DefElement, it should first be implemented in Symfem.
Elements in the DefElement database are defined using a yaml file in the elements/ folder. The entries in this yaml file are:
| Name | Required | Description |
| name | The name of the element (ascii). | |
| html‑name | The name of the element, including HTML special characters. | |
| reference‑elements | The reference element(s) that this finite element can be defined on. | |
| alt‑names | Alternative (HTML) names of the element. | |
| short‑names | Abbreviated names of the element. | |
| variants | Variants of this element. | |
| complexes | Any discretiations of complexes that this element is part of. | |
| dofs | Description of the DOFs of this element. | |
| ndofs | The number of DOFs the element has and the A-numbers of the OEIS sequence(s) giving the number of DOFs. | |
| entity‑ndofs | The number of DOFs the element has per subentity type and the A-numbers of the OEIS sequence(s) giving the number of DOFs. | |
| polynomial‑set | The polynomial set of this element. This can use sets defined in the file /data/polysets. Other sets can be given by writing | |
| mixed | If this element is a mixed element, the subelements that it contains. | |
| mapping | The mapping used to push/pull values foward/back from/to the reference element. | |
| sobolev | The Sobolev space the element lives in. | |
| min‑degree | The minimum degree of the element | |
| max‑degree | The maximum degree of the element | |
| polynomial-subdegree | The degree of the highest degree complete polynomial space that is a subspace of this element's polynomial space | |
| polynomial-superdegree | The degree of the lowest degree complete polynomial space that is a superspace of this element's polynomial space | |
| lagrange-subdegree | The degree of the highest degree Lagrange space that is a subspace of this element's polynomial space | |
| lagrange-superdegree | The degree of the lowest degree Lagrange space that is a superspace of this element's polynomial space | |
| degree | Degree that is use to index this element, should be polynomial-subdegree, polynomial-superdegree, lagrange-subdegree, lagrange-superdegree | |
| examples | Reference elements and degrees to be included in the examples section of the entry. | |
| notes | Notes about the element. | |
| references | References to where the element is defined. | |
| categories | Categories the element belongs to. Categories are defined in the file /data/categories. | |
| implementations | Strings/enum entries/etc to create this element in supported implementations. |
In the implementations fields, parameters can be passed to the implementation using syntax like this:
``yaml implementations: libraryname: String param_name1=param_value1 param_name2=param_value2
There are a few special parameters (written in ALL CAPS) that can be used here:
| Parameter | Purpose |
| DEGREES | A list of degrees for which this element is defined in this implementation, eg 1,2,4:8 denotes that degrees 1 and 2 and 4 to 8 (including 4 but not including 8) are supported. Note that if DEGREEMAP is set, the degrees used here should correspond to the DefElement convention, not the degree after the degree map is applied. |
| DEGREEMAP | A map to apply to the degree used on DefElement to obtain the degree used by this library. The value here will be parsed using Sympy, with the variable k equal to the degree (using DefElement's convention). |
When you open a pull request, a series of tests and style checks will run via GitHub Actions.
(You may have to wait for manual approval for these to run.)
These tests and checks must pass before the pull request can be merged.
If the tests and checks fail, you can click on them on the pull request page to see where the failure is happening.
The style checks will check that the Python scripts that generate DefElement pass flake8 checks.
If you've changed these scripts, you can run these checks locally by running:
python3 -m flake8 defelement build.py test
Before you can run the tests or do a test build, you'll need to install DefElement's requirements:
python3 -m pip install -r requirements.txt
The DefElement tests can be run using:
python3 -m pytest test/
To test that DefElement successfully builds, you can pass --test auto to the build.py script.
This will build the website including examples for a small set of elements, and will take much less time
then building the full website.
python3 build.py _test_html --test auto --processes 4
If you've updated an element, then you can test this element by replacing auto with the filename of the element you have edited.
If you've updated multiple elements, you can use multiple filenames separated by commas. For example:
python3 build.py _test_html --test dpc --processes 4 python3 build.py _test_html --test lagrange,vector-lagrange --processes 4
To add a library to the implementations section of DefElement, you must add a file containing to the folder
/defelement/implementations.
This file should define a class that is a subclass of Implementation.
This class should include: