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‑order | The minimum order of the element | |
max‑order | The maximum order of the element | |
examples | Reference elements and orders 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 first add details of the library to the file /data/implementations. You must include three key pieces of information about the library: its name, url, and a bash command to install it. These three pieces of information are filed under an id for your library.
Once this has been done, you should next add the library to defelement/implementations.py. At the end of this file, there are three dictionaries, mapping the id of a library to a function. You should add functions to these that do the following:
Once these steps are done, you can start adding implementation details for your library to the implementation field of elements in the elements folder.
When contributing to DefElement, you should follow the DefElement style guide.
Once you have contributed to DefElement, you should add your name and some information about yourself to the contributors page. To do this, you should add info about yourself to the file data/contributors. If you wish to include a picture of yourself, add a square-shaped image to the pictures/ folder.
We expect all our contributors to follow our code of conduct. Any unacceptable behaviour can be reported to Matthew (defelement@mscroggs.co.uk).