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. |
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:
Item | Type | Use |
format | method | This method should take an implementation string and a set of parameters as inputs and return the implementation information for the library, as it will be displayed on each element's page. |
example | method | This method should take a DefElement Element object as an input and return a block of Python (as a string) that creates all the examples of that element using the library. |
verify | method (optional) | This method should take a DefElement Element object, an example, and a set of points as inputs and returns the element for that example tabulated at the set of points and the number of DOFs associated with each sub-entity as a tuple of tuples. The shape of the first output is (number of points, value size, number of basis functions). These functions are used to verify that the implementation spans the same space as Symfem. |
id | variable | The unique identifier for your library. This will be used in .def files. |
name | variable | The name of your library. |
install | variable | Code snippet to install you library (preferably using pip3) |
url | variable | URL where the source code of your library is avaliable (eg a GitHub link). |
verification | variable (optional) | Should be set to True if the verification function is implemented. |