FEniCSx is an open-source multi-platform computing environment to solve partial differential equations using the finite element method. FEniCSx supports parallel computing with Python and C++ interface. FEniCSx is comprised of the libraries UFL, Basix, FFCx, and DOLFINx which are the build blocks of it. To learn more about FEniCSx: https://fenicsproject.org.
The FEniCS project originally started in 2003 and was known as FEniCS. In 2020, the developers released a new version of the library and renamed FEniCS as FEniCSx. The latest stable version of legacy FEniCS was released in April 2019 and it's barely updated. But many tutorials and legacy codes are perhaps written in legacy FEniCS. So you may want to install a version of it. We will demonstrate installing both versions on multiple different platforms here.
Both FEniCSx and FEniCS are available on Linux, macOS, and Windows. You can download and install it in different ways. Check out the options here for FEniCSx: https://github.com/FEniCS/dolfinx and here for legacy FEniCS: https://fenicsproject.org/download/archive/. For both versions, our preferred approach is to install them via Anaconda.
This step in only applicable if you are using Windows. You will have to set up Windows Subsystem for Linux (WSL) to use Anaconda based installation of FEniCSx and legacy FEniCS. WSL is a virtual Linux environment within Windows which allows you to use Linux command line tools and GUI applications (GUI is natively supported on Windows 11). If you are on macOS or Linux, you can skip this step. If you are on Windows and already have installed WSL, it still might be interesting to download the recommended applications/ tools, such as VS Code.
Microsoft Windows already comes with Windows PowerShell 5.1, but the modern edition of PowerShell 7 is more powerful and available on different operating systems. To learn more about this, check this: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows.
winget tool on default PowerShell 5.1 and new PowerShell 7.X.Y to be installed. $ winget search Microsoft.PowerShell .preview version. Now install the stable release of PowerShell using the following command: $ winget install --id Microsoft.Powershell --source winget Windows Terminal is a command line tool, available on Microsoft Store (https://apps.microsoft.com/store/apps). You can manage multiple command line environments such as Windows PowerShell 5.1, PowerShell 7.X.Y, CMD, WSL, etc. using a single application. Check out more about it here: https://learn.microsoft.com/en-us/windows/terminal/install. You can customize your command line applications using Terminal.
The current stable version for Windows Subsystem for Linux is WSL2 and this is the default installation.
$ wsl --list --online $ wsl --install -d Ubuntu $ sudo apt update && sudo apt upgrade
$ sudo apt install xvfb libgl1-mesa-glx $ explorer.exe . If this is the first time you are using Python, then seat back, it is going to get confusing like this xkcd comic. Even if you are experienced in Python, you might find this interesting (https://xkcd.com/1987/).
Most of the Python based libraries and packages often depend on other libraries and packages (called dependencies). Installing the right version of those packages and maintaining them is often a complex task even for experienced developers. So, we will use a popular Python distribution, Anaconda, to manage all the Python based libraries and relevant dependencies. Anaconda uses conda package manager and works well with pip (Python’s default package manager). Installation of Anaconda comes with popular Python packages such as NumPy, SciPy, Matplotlib, and <insert hundred other packages here>. It also comes with Jupyter Notebook and Spyder IDE. Anaconda also has a minimalist version, called Miniconda, which is light weight because it only includes the conda manager and a few packages. We strongly recommend installing Anaconda
xcode command line tools to enable basic development libraries and features. On macOS terminal, type: (base) $ xcode-select --install $ wget https://repo.anaconda.com/archive/Anaconda3-2023.03-Linux-x86_64.sh Anaconda3-2023.03-Linux-x86_644 is the latest version of Anaconda available at the time this guide is being written. Check the available versions here: https://repo.anaconda.com/archive. Replace it wish the version you downloaded for installation.$ bash Anaconda3-2022.10-Linux-x86_64.sh (base) $
As of March 2023, the latest stable release of dolfinx available via Anaconda is 0.6. If you build FEniCSx from the source, you can perhaps install 0.7.
dolfinx library, we will install mpich, pyvista, matplotlib, and cycler. Parallel processing library mpich allows different multi-processor operations within FEniCSx and the other three packages are used for quick visualization. Standard installation of Anaconda already comes with these three packages but we will still need to install them inside the FEniCSx environment. (base) $ conda create -n fenicsx
(base) $ conda activate fenicsx
(fenicsx) $ conda install -c conda-forge fenics-dolfinx mpich pyvista matplotlib cycler pyvista supports plotting higher order unstructured mesh.matplotlib lacks support for higher order unstructured mesh. So, it is recommended to use pyvista for quick visualization. But you can use matplotlib for regular plotting.(fenicsx) $ conda deactivate
(base) $ conda remove -n fenicsx --all
(base) $ conda clean --all A lots of the tutorials, examples, and published codes are still written in legacy FEniCS. So, you may want to install the legacy version in case you want to run codes written in legacy FEniCS.
pyvista here. Necessary visualization can be done using matplotlib. (base) $ conda create -n fenics
(base) $ conda activate fenics
(fenics) $ conda install -c conda-forge fenics matplotlib cycler (fenics) $ conda deactivate
(base) $ conda remove -n fenics --all
(base) $ conda clean --all apt package manager. Albeit the installation process being simple and lightweight, FEniCSx version available via apt is often not the latest version. So, we do not recommend installing this way. $ sudo add-apt-repository ppa:fenics-packages/fenics
$ sudo apt update
$ sudo apt install fenicsx apt on Ubuntu, follow the procedures below: $ sudo apt remove fenicsx
$ sudo apt remove --auto-remove fenicsx
$ sudo apt purge fenicsx
$ sudo apt purge --auto-remove fenicsx fenics instead of fenicsx in the command line for installing and uninstalling legacy FEniCS.Visual Studio Code is a cross-platform code editor from Microsoft. You can install different extensions within VS Code to enable features for code development such as remote SSH, debugging, compiling, etc. If you have another favorite IDE (e.g., Spyder or PyCharm) or code editor (e.g., Sublime text, Atom, Notepad++) you like to use, you can configure it yourself.
$ code . $ code filename.ext Vim extension pack as well but exit at your own risk.
We will now demonstrate how to run a simple FEniCSx example code here using VS Code. If you open Ubuntu or macOS terminal now, you will see the (base) environment is active.
(fenicsx) environment before running the code. (base) $ conda activate fenicsx (fenicsx) $ (base) environment is active by default. You will have to activate (fenicsx) environment using the above command. Create a directory called fenicsx-code in your WSL home directory and navigate to it:(fenicsx) $ mkdir fenicsx-code
(fenicsx) $ cd fenicsx-code (fenicsx) $ code . poisson.py. This code solves a simple 2D Poisson problem. Technical details of this code is described here: https://jsdokken.com/dolfinx-tutorial/chapter1/fundamentals. import os
import numpy
import ufl
import dolfinx
from dolfinx import mesh, fem, io, plot
from mpi4py import MPI
from petsc4py import PETSc
import pyvista as pv
# clears the terminal and prints dolfinx version
os.system('clear')
# prints dolfinx version
print(f"DOLFINx version: {dolfinx.__version__}")
# no of elements in each direction
NElem = 8
# create a unit square with 8x8 elements with quad elements and use first order shape function
domain = mesh.create_unit_square(MPI.COMM_WORLD,NElem,NElem,mesh.CellType.quadrilateral)
V = fem.FunctionSpace(domain,("CG",1))
## define trial and test functions
u = ufl.TrialFunction(V)
v = ufl.TestFunction(V)
# source term of the poisson equation
f = fem.Constant(domain, PETSc.ScalarType(-6))
## applying boundary conditions
uD = fem.Function(V)
uD.interpolate(lambda x: 1 + x[0]**2 + 2 * x[1]**2)
tdim = domain.topology.dim
fdim = tdim-1
domain.topology.create_connectivity(fdim, tdim)
boundary_facets = mesh.exterior_facet_indices(domain.topology)
boundary_dofs = fem.locate_dofs_topological(V, fdim, boundary_facets)
bc = fem.dirichletbc(uD, boundary_dofs)
# bilinear form
a = ufl.dot(ufl.grad(u), ufl.grad(v)) * ufl.dx
L = f * v * ufl.dx
# set PETSc solver options
sol_opts = {"ksp_type": "preonly", "pc_type": "lu"}
# formulate the problem
problem = fem.petsc.LinearProblem(a, L, bcs=[bc], petsc_options=sol_opts)
# solve the problem
uh = problem.solve()
## error calculation
V2 = fem.FunctionSpace(domain, ("CG", 2))
uex = fem.Function(V2)
uex.interpolate(lambda x: 1 + x[0]**2 + 2 * x[1]**2)
L2_error = fem.form(ufl.inner(uh-uex, uh-uex) * ufl.dx)
error_local = fem.assemble_scalar(L2_error)
error_L2 = numpy.sqrt(domain.comm.allreduce(error_local, op=MPI.SUM))
error_max = numpy.max(numpy.abs(uD.x.array-uh.x.array))
# print the error
if domain.comm.rank == 0:
print(f"Error_L2 : {error_L2:.2e}")
print(f"Error_max : {error_max:.2e}")
# writing output files in xdmf format
with io.XDMFFile(domain.comm, "output.xdmf", "w") as xdmf:
xdmf.write_mesh(domain)
xdmf.write_function(uh)
# 2D contour plots of the mesh and result using pyvista
#pv.start_xvfb() # Uncomment the line on WSL
pv.off_screen = True
topology, cell_types, geometry = plot.create_vtk_mesh(domain, tdim)
grid = pv.UnstructuredGrid(topology, cell_types, geometry)
plotter = pv.Plotter()
plotter.add_mesh(grid,show_edges=True)
plotter.view_xy()
plotter.save_graphic('mesh.pdf')
u_topology, u_cell_types, u_geometry = plot.create_vtk_mesh(V)
u_grid = pv.UnstructuredGrid(u_topology, u_cell_types, u_geometry)
u_grid.point_data["u"] = uh.x.array.real
u_grid.set_active_scalars("u")
u_plotter = pv.Plotter()
u_plotter.add_mesh(u_grid,show_edges=True)
u_plotter.view_xy()
u_plotter.save_graphic('contour.pdf')
(fenicsx) $ python3 poisson.py .h5 and .xdmf files with the results and save the mesh and contour plot of the primary variable .pdf files in the working directory.If this is the first time you are setting up Python and Anaconda on macOS or WSL, you may need to follow a few more steps for smooth operation. If you have done used Anaconda + VS Code combination before, you might find some of these steps redundant.
(fenicsx) $ conda install -c anaconda ipykernel ipywidgets
(fenicsx) $ pip install trame
trame and ipywidgets are needed for Jupyter backend rendering within VS Code Jupyter notebook. For interactive running, we will need to install ipykernel.(fenicsx) $ pip install --upgrade gmsh
(fenicsx) $ pip install pygmsh
(fenicsx) $ pip install meshio fenicsx environment as your default environment. We will now get the directory for our fenicsx environment within Anaconda: (fenicsx) $ conda info --envs fenicsx environment. Open VS Code from macOS or Ubuntu terminal using: (fenicsx) $ code . /Users/username/opt/anaconda3/envs/ fenicsx/bin/python (copied directory for fenicsx) as the Default Interpreter Path. /home/username/anaconda3/envs/fenicsx/bin/python (copied directory for fenicsx) as the Default Interpreter Path. .png format with plotter.screenshot() function on WSL, you have to configure the remote display option. Open your bash profile: (fenicsx) $ code ~/.bashrc .bashrc file: export DISPLAY=:99.0
export PYVISTA_OFF_SCREEN=true
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
sleep 1 (fenicsx) environment is no longer active. If you want this environment to be active at the terminal start-up then open the .bashrc or .zshrc file using VS Code and add the following line: $ conda activate fenicsx (fenicsx) environment is always active. If you want to return to the (base) conda environment, then type: (fenicsx) $ conda deactivate (base) $ q to exit the plot window instead of clicking on X icon. PyVista will not show the plot unless X-11 server is configured somehow. It can save the plot as .pdf, .eps, .svg, .tex, .ps file using save_graphic() function or as .png file as plotter.screenshot() function. This might not be an issue on Windows 11 as WSL natively supports X-11 forwarding (not tested yet). .png file with show_edges=True option. Best is to use the save_graphic() function and save it .pdf, .eps, .svg, .tex, .ps file. Since FEniCSx was released very recently, there aren't many tutorial or resources available based on FEniCSx. Please check the first two web resources which demonstrates some wonderful problems using FEniCSx. On the other hand, legacy FEniCS has numerous hands-on tutorials, books, and lecture series available. Fortunately, most of the concepts and APIs are similar between FEniCS and FEniCSx, so it shouldn't be hard to use those resources. In addition, FEniCSx developers are active in responding questions and concerns.