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‑degreeThe minimum degree of the element
max‑degreeThe maximum degree of the element
polynomial-subdegreeThe degree of the highest degree complete polynomial space that is a subspace of this element's polynomial space
polynomial-superdegreeThe degree of the lowest degree complete polynomial space that is a superspace of this element's polynomial space
lagrange-subdegreeThe degree of the highest degree Lagrange space that is a subspace of this element's polynomial space
lagrange-superdegreeThe degree of the lowest degree Lagrange space that is a superspace of this element's polynomial space
degreeDegree that is use to index this element, should be polynomial-subdegree, polynomial-superdegree, lagrange-subdegree, lagrange-superdegree
examplesReference elements and degrees 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 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:

ItemTypeUse
formatmethodThis 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.
examplemethodThis 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.
verifymethod (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.
idvariableThe unique identifier for your library. This will be used in .def files.
namevariableThe name of your library.
installvariableCode snippet to install you library (preferably using pip3)
urlvariableURL where the source code of your library is avaliable (eg a GitHub link).
verificationvariable (optional)Should be set to True if the verification function is implemented.

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).