an encyclopedia of finite element definitions

Contributing to DefElement

Making suggestions

Reporting mistakes

If you find a mistake in the DefElement database, please report it on the issue tracker using the Mistake report template.

Suggesting new elements

If you want to suggest a new element to be added to DefElement, suggest it on the issue tracker using the New element template.

Suggesting improvements

If you want to suggest a new featute or improvement to DefElement, suggest it on the issue tracker using the Suggest an improvement template.

Discussion ideas for new features

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.

Contributing directly

Submitting a pull request

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.

Defining an element

Elements in the DefElement database are defined using a yaml file in the elements/ folder. The entries in this yaml file are:

NameRequiredDescription
nameThe name of the element (ascii).
html‑nameThe name of the element, including HTML special characters.
reference‑elementsThe reference element(s) that this finite element can be defined on.
alt‑namesAlternative (HTML) names of the element.
short‑namesAbbreviated names of the element.
variantsVariants of this element.
complexesAny discretiations of complexes that this element is part of.
dofsDescription of the DOFs of this element.
ndofsThe number of DOFs the element has and the A-numbers of the OEIS sequence(s) giving the number of DOFs.
entity‑ndofsThe number of DOFs the element has per subentity type and the A-numbers of the OEIS sequence(s) giving the number of DOFs.
polynomial‑setThe polynomial set of this element. This can use sets defined in the file /data/polysets. Other sets can be given by writing [LaTeX definition of set]. Unions of multiple sets can be given, separated by && .
mixedIf this element is a mixed element, the subelements that it contains.
mappingThe mapping used to push/pull values foward/back from/to the reference element.
sobolevThe Sobolev space the element lives in.
min‑orderThe minimum order of the element
max‑orderThe maximum order of the element
examplesReference elements and orders to be included in the examples section of the entry.
notesNotes about the element.
referencesReferences to where the element is defined.
categoriesCategories the element belongs to. Categories are defined in the file /data/categories.
implementationsStrings/enum entries/etc to create this element in supported implementations.

Testing your contribution

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

Adding an implementation

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.

Style guide

When contributing to DefElement, you should follow the DefElement style guide.

Adding yourself to the contributors list

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.

Code of conduct

We expect all our contributors to follow our code of conduct. Any unacceptable behaviour can be reported to Matthew (defelement@mscroggs.co.uk).