Create a DOLFIN to DOLFINx "cheat sheet"

[mscroggs]

Highlighting specific changes related to DOLFIN to DOLFINx conversion.

An MPI communication cheat sheet would be helpful too.

These were suggested at the FEniCS2022 conference

[juliusgh]

I am not sure in which format the DOLFIN to DOLFINx cheat sheet should be created. To help myself, I created a cheat sheet as a Markdown document that contains examples for the most important operations with the DOLFINx Python/C++ API and the DOLFIN Python/C++ API, and thereby highlights the main differences.

dolfin-dolfinx-cheatsheet.md

Maybe it can be helpful as a starting point, if there isn't something already.

[jorgensd]

@juliusgh the cheat-sheet is a good starting point for people transitioning. However, I think you need to add some context to the different sub-sections, (and maybe motivation), as it is crucial for a new user to understand the why of things.

Imports

DOLFINx does no longer use wildcard imports. Some of the reasons for this are for instance listed at: https://rules.sonarsource.com/python/RSPEC-2208

Meshes

I would stress the fact that not all of the entries in mesh.create_unit_square and mesh.create_rectangle is required (they have defaults for cell type).

Dirichlet conditions

In legacy DOLFIN, the use of Expression hides a lot of information, such as assumptions of the underlying finite element space. Secondly, DirichletBC has an optional argument to chose the method of discovering degrees of freedom: https://bitbucket.org/fenics-project/dolfin/src/bd54183ed40f3597fe1187499c79c54eb4759f6d/python/dolfin/fem/dirichletbc.py#lines-119:124 As this is really messy (and hides logic from the user), this has been replaced by sending in the degrees of freedom directly in DOLFINx, and the user can choose what method they want to use for discovering dofs, locate_dofs_topological, locate_dofs_geometrical, or any custom dof locator.

Variational problem

Here, you reply on x= ufl.SpatialCoordinate(mesh) in DOLFINx, which you can use in legacy DOLFIN as well (as x=SpatialCoordinate(mesh)). Note that using an expression will do something fundamentally different than a spatial coordinate. An expression is interpolated into the appropriate space (given either by the argument degree, or element), then evaluated at quadrature points. A spatial coordinate expression is just evaluated at a quadrature point, no interpolation into any space required.

Assemble matrix and rhs vector

Note that the input to A is not a ufl.form but a dolfinx.fem.Form, which means that code has been generated or fetched from cache. This means repeated assembly does not search through cache, which assemble_system will do at every call (which can get costly if you have compiled a lot of forms and have to search through the cache). It also means that if you re-assign variables after calling fem.form is clearly not going to be taken into account in the dolfinx.fem.form. Thus it clearly separates when JIT compilation happens.

[juliusgh]

Hi @jorgensd, many thanks for your detailed feedback! Originally, I wrote the cheat sheet just for myself and wanted to keep it as short as possible to have a kind of compact lookup table for migrating code from DOLFIN to DOLFINx. Therefore, my goal in the first place was not to cover all eventualities and explain why it works.

However, I agree with you and will expand the cheat sheet based on your feedback. I have already addressed some points and will do the rest later. My code examples for DOLFIN are based on the old DOLFIN demos and therefore probably do not correspond to good practices from today's point of view so far, but I will try to improve that.

I will host it in a personal repository for now until it is clear if and how the cheat sheet could become a part of DOLFINx: https://github.com/juliusgh/dolfinx-demos/blob/main/dolfin-dolfinx-cheatsheet.md