Installing Firedrake ¶

Supported systems ¶

A native installation of Firedrake is officially supported on Ubuntu and ARM Macs (Intel Macs are no longer supported) though it should be installable on any Linux distribution. Windows users are encouraged to use WSL or one of Firedrake’s alternative installation mechanisms.

Installing Firedrake using pip ¶

A native installation of Firedrake is accomplished in 3 steps:

Install system dependencies
Install PETSc
Install Firedrake

If you encounter any problems then please refer to our list of common installation issues or consider getting in touch.

Prerequisites ¶

On Linux the only prerequisite needed to install Firedrake is a suitable version of Python (3.10 or greater). On macOS it is important that homebrew is installed and that the homebrew-installed Python is used instead of the system one.

firedrake-configure ¶

To simplify the installation process, Firedrake provides a utility script called firedrake-configure. This script can be downloaded by executing:

$ curl -O https://raw.githubusercontent.com/firedrakeproject/firedrake/master/scripts/firedrake-configure

Unlike the now deprecated firedrake-install script, firedrake-configure does not install Firedrake for you. It is simply a helper script that emits the configuration options that Firedrake needs for the various steps needed during installation.

To improve robustness, firedrake-configure is intentionally kept extremely minimal and simple. This means that if you want to install Firedrake in a non-standard way (for instance with a custom installation of PETSc, HDF5 or MPI) then it is your responsibility to modify the output from firedrake-configure as necessary. This is described in more detail in Customising Firedrake.

Installing system dependencies ¶

If on Ubuntu or macOS, system dependencies can be installed with firedrake-configure. On Ubuntu run:

$ sudo apt install $(python3 firedrake-configure --show-system-packages)

which will install the following packages:

bison build-essential cmake flex gfortran git libopenblas-dev libopenmpi-dev ninja-build pkg-config python3-dev python3-pip libfftw3-dev libfftw3-mpi-dev libhwloc-dev libhdf5-mpi-dev

If on macOS you should instead run:

$ brew install $(python3 firedrake-configure --show-system-packages)

which will install the following packages:

autoconf automake boost cmake gcc libtool make ninja openblas openmpi pkg-config python hwloc hdf5-mpi

If you do not have one of these systems then these dependencies will need to be installed manually.

Installing PETSc ¶

For Firedrake to work as expected, it is important that a specific version of PETSc is installed with a specific set of external packages. To install PETSc you need to do the following steps:

Clone the PETSc repository, checking out the right version:

$ git clone --depth 1 --branch $(python3 firedrake-configure --show-petsc-version) https://gitlab.com/petsc/petsc.git
$ cd petsc

Run PETSc configure, passing in the flags generated by firedrake-configure:

$ python3 ../firedrake-configure --show-petsc-configure-options | xargs -L1 ./configure

Compile PETSc by running the make command prompted by configure. This will look something like:
```
make PETSC_DIR=/path/to/petsc PETSC_ARCH=arch-firedrake-default all
```
Test the installation (optional) and return to the parent directory:
```
$ make check
$ cd ..
```

If you are using one of the officially supported distributions then these configure options will include paths to system packages so PETSc can correctly find and link against them. If you are not then you should pass the --no-package-manager flag to obtain a set of configure options where firedrake-configure pessimistically assumes that no external packages are available, and hence need to be downloaded and compiled from source:

$ python3 ../firedrake-configure --no-package-manager --show-petsc-configure-options | xargs -L1 ./configure

For the default build, running firedrake-configure with --no-package-manager will produce the flags:

--with-c2html=0 --with-debugging=0 --with-fortran-bindings=0 --with-shared-libraries=1 --with-strict-petscerrorcode PETSC_ARCH=arch-firedrake-default --COPTFLAGS='-O3 -march=native -mtune=native' --CXXOPTFLAGS='-O3 -march=native -mtune=native' --FOPTFLAGS='-O3 -march=native -mtune=native' --download-bison --download-fftw --download-hdf5 --download-hwloc --download-metis --download-mumps --download-netcdf --download-pnetcdf --download-ptscotch --download-scalapack --download-suitesparse --download-superlu_dist --download-zlib --download-hypre

Installing Firedrake ¶

Now that the right system packages are installed and PETSc is built we can now install Firedrake. To do this perform the following steps:

Create a virtual environment:
```
$ python3 -m venv venv-firedrake
$ . venv-firedrake/bin/activate
```
This is optional but strongly recommended to avoid polluting your system Python environment.
Set any necessary environment variables. This can be achieved using firedrake-configure:
```
$ export $(python3 firedrake-configure --show-env)
```
Which at a minimum will set the following variables:
```
CC=mpicc CXX=mpicxx PETSC_DIR=/path/to/petsc PETSC_ARCH=arch-firedrake-{default,complex} HDF5_MPI=ON
```
Note

This command will only work if you have the right starting directory. Specifically it is assumed that PETSc was cloned into a subdirectory of the current working directory (i.e. <cwd>/petsc). If you have exactly followed the instructions up to this point this should already be the case.
Install Firedrake:
```
$ pip cache remove petsc4py
$ pip install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[check]"
```
Note

Though not strictly necessary to install Firedrake’s optional dependencies with [check] it is recommended because it allows you to check that the install was successful (see below).
Firedrake is now installed and ready for use!

Warning

Until Firedrake has versioned releases (slated for April/May 2025), firedrake-zenodo will only work with editable installations of Firedrake and its components. To install Firedrake in editable mode you should follow the instructions below.

Checking the installation ¶

We recommend that you run some simple tests after installation to check that Firedrake is fully functional. To do this, after the installation run:

$ firedrake-check

This command will run a few of the unit tests, which exercise a good chunk of the functionality of the library. These tests should take a minute or less. If they fail to run for any reason, please check out our list of commonly encountered installation issues or consider getting in touch.

Note that for you to be able to run the tests you need to have installed Firedrake with its optional test dependencies by specifying the [check] dependency group as shown above.

Updating Firedrake ¶

Updating Firedrake involves following the same steps as above when installing Firedrake. First, use firedrake-configure to set the right environment variables and then run:

$ pip install --upgrade git+https://github.com/firedrakeproject/firedrake.git

Updating PETSc ¶

To update PETSc you simply need to run:

$ cd /path/to/petsc
$ git pull
$ make

Note that this will only recompile PETSc’s source code, not that of the external packages, and so should be relatively quick. If your PETSc is sufficiently out-of-date you may also need to rebuild the external packages by running:

$ make reconfigure

Common installation issues ¶

No such file or directory: ‘/tmp/…/petsc/conf/petscvariables’¶

If you encounter the error:

FileNotFoundError: [Errno 2] No such file or directory: '/tmp/.../petsc/conf/petscvariables'

when running the pip install instruction this is usually a sign that the environment variable PETSC_DIR is not set correctly. You can check this by making sure that you can run the following command without error:

$ ls $PETSC_DIR

If this raises an error then you should re-export the variable:

$ export PETSC_DIR=/path/to/petsc

and try the pip install again.

Missing symbols post install ¶

If the installation completes but then you get errors regarding missing symbols when you import Firedrake this is usually a sign that one of the Python bindings packages used by Firedrake (h5py, mpi4py, petsc4py, slepc4py) is linked against the wrong compiled library. This is usually caused by issues with caching.

To resolve the problem you should first remove any existing cached packages:

$ pip uninstall -y h5py mpi4py petsc4py slepc4py
$ pip cache remove h5py
$ pip cache remove mpi4py
$ pip cache remove petsc4py
$ pip cache remove slepc4py

before re-running the instruction to install Firedrake.

Developer install ¶

By default Firedrake is installed just like any other Python package into your environment. If you want to be able to edit Firedrake itself then an editable installation is needed. To install Firedrake in editable mode you should follow the same steps as for a non-editable install but replace the final pip install command with:

$ git clone <firedrake url>
$ pip install --no-binary h5py --editable './firedrake[dev]'

where <firedrake url> is https://github.com/firedrakeproject/firedrake.git or git@github.com:firedrakeproject/firedrake.git as preferred.

The same process applies for Firedrake’s dependencies. For example, to install FIAT in editable mode you should run:

$ git clone <fiat url>
$ pip install --editable ./fiat

Note that editable versions of Firedrake’s dependencies should be installed after Firedrake is installed. Otherwise installing Firedrake will overwrite whatever packages you just installed.

Customising Firedrake ¶

Prepared configurations ¶

firedrake-configure provides a number of different possible configurations (termed ‘ARCHs’) that specify how PETSc is configured and which external packages are built. The currently supported ARCHs are:

default: the default installation, suitable for most users
complex: an installation where PETSc is configured using complex numbers

The different configurations can be selected by passing the flag --arch to firedrake-configure. For example:

$ python3 firedrake-configure --show-petsc-configure-options --arch complex

Optional dependencies ¶

SLEPc ¶

To install Firedrake with SLEPc support you should:

Pass --download-slepc when running PETSc configure (see Installing PETSc):

$ python3 ../firedrake-configure --show-petsc-configure-options | xargs -L1 ./configure --download-slepc

Set SLEPC_DIR:

$ export SLEPC_DIR=$PETSC_DIR/$PETSC_ARCH

Continue with the installation as normal but remove slepc4py from the pip cache and install Firedrake with the slepc optional dependency. For example:
```
$ pip cache remove slepc4py
$ pip install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[check,slepc]"
```

VTK ¶

To install Firedrake with VTK, it should be installed using the vtk optional dependency. For example:

$ pip install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[check,vtk]"

At present VTK wheels are not available for ARM Linux machines. Depending on your Python version you may be able to work around this by downloading and pip installing the appropriate .whl file from here.

PyTorch ¶

To install Firedrake with PyTorch, it should be installed using the torch optional dependency. For example:

$ pip install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[check,torch]" --extra-index-url https://download.pytorch.org/whl/cpu

Observe that, in addition to specifying torch, an additional argument (--extra-index-url) is needed. More information on installing PyTorch can be found here.

JAX ¶

To install Firedrake with JAX, it should be installed using the jax optional dependency. For example:

$ pip install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[check,jax]"

Netgen ¶

To install Firedrake with Netgen support, it should be installed with the netgen optional dependency. For example:

$ pip install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[check,netgen]"

Customising PETSc ¶

Since firedrake-configure only outputs a string of options it is straightforward to customise the options that are passed to PETSc configure. You can either:

Append additional options when configure is invoked. For example, to build PETSc with support for 64-bit indices you should run:
```
$ python3 ../firedrake-configure --show-petsc-configure-options | xargs -L1 ./configure --with-64-bit-indices
```

Write the output of firedrake-configure to a file than can be modified. For example:

$ python3 ../firedrake-configure --show-petsc-configure-options > my_configure_options.txt
<edit my_configure_options.txt>
$ cat my_configure_options.txt | xargs -L1 ./configure

Note

If additional options are passed to configure then care must be taken when using externally-installed system packages (i.e. --with-package=... or --with-package-{include,lib}=... are in the configure options) as they may no longer be suitable for the new configuration. It is your responsibility to either ensure that the configuration is suitable, or replace the configure option with --download-package so that PETSc will download and install the right thing.

Reconfiguring an existing PETSc ¶

If rebuilding an existing PETSc installation, rather than removing everything and starting from scratch, it can be useful to modify and run the reconfigure-ARCH.py Python script that PETSc generates. This can be found in $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf. Other example scripts can be found in $PETSC_DIR/config/examples directory.

Alternative installation methods ¶

If for some reason you are unable to install Firedrake natively using pip, Firedrake has a number of alternative mechanisms that you can use to obtain an environment to run your Firedrake code.

Docker ¶

Firedrake provides a number of different Docker images that can be found here. The main images best suited for users are:

firedrake-vanilla-default: a complete Firedrake installation with ARCH default
firedrake-vanilla-complex: a complete Firedrake installation with ARCH complex
firedrake: the firedrake-vanilla-default image with extra downstream packages installed

To use one of the containers you should run:

$ docker pull firedrakeproject/<image name>:latest

to download the most recent image (replacing <image name> with the desired image). Then you can run:

$ docker run -it firedrakeproject/<image name>:latest

to start and enter a container.

Note

The ‘full-fat’ firedrakeproject/firedrake image only exists for x86 architectures because some external packages do not provide ARM wheels. If you are using an ARM Mac (i.e. M1, M2, etc) then you are encouraged to use the firedrakeproject/firedrake-vanilla-default or firedrakeproject/firedrake-vanilla-complex images instead.

It is possible to use Microsoft VSCode inside a running container. Instructions for how to do this may be found here.

Warning

The Docker daemon runs with superuser privileges and so has the potential to damage your system, in particular if volumes are mounted between the container and host. We therefore strongly advise you to take care when using Docker. More information can be found here.

Google Colab ¶

Firedrake can also be used inside the brower using Jupyter notebooks and Google Colab. For more information please see here.