Installing Firedrake ¶

Supported systems ¶

A native installation of Firedrake is officially supported on Ubuntu and macOS 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

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

Prepared configurations ¶

firedrake-configure provides a number of different possible configurations (termed ‘ARCH’s) 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-system-packages --arch complex

If --arch is not specified then default is used.

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

Note

Not all the system dependencies declared by firedrake-configure have to be installed at this stage. Some (e.g. HDF5, hwloc) can also be installed from source by PETSc during the configure step by passing additional flags (e.g. --download-hdf5, --download-hwloc).

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 ARCH, 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

Customising the PETSc installation ¶

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

Append additional options when configure is invoked. For example, to compile PETSc with 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:

$ python3 ../firedrake-configure --show-petsc-configure-options > my_configure_options.txt
<edit my_configure_options.txt>
$ ./configure $(cat my_configure_options.txt)

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)
```
At a minimum this will set the following variables:
```
CC=mpicc CXX=mpicxx PETSC_DIR=/path/to/petsc PETSC_ARCH=arch-firedrake-{default,complex} HDF5_MPI=ON
```
Note

If you are installing

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 install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[test]"
```
Note

Though not strictly necessary to install Firedrake’s optional test dependencies with [test] 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.

Note

During the installation Firedrake will compile and install petsc4py. If you have previously installed petsc4py on your computer with a different PETSc then pip will erroneously reuse the existing petsc4py which is linked against the wrong library. To avoid this you need to run the command:

pip cache remove petsc4py

Equivalent commands may also be necessary for mpi4py and h5py if you are changing the MPI and/or HDF5 libraries in use.

Note

If you are using an MPI installed into a nonstandard location it may be necessary to set some additional environment variables before installation including:

MPICC to the location of mpicc
MPI_HOME to the base directory of the MPI installation (e.g. /usr or /opt/mpich)

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 see the section below on how to get help.

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 [test] dependency group as shown above.

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 run:

$ git clone https://github.com/firedrakeproject/firedrake.git
$ pip install --no-binary h5py --editable './firedrake[dev]'

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

$ git clone https://github.com/firedrakeproject/fiat.git
$ pip install --editable ./fiat

Note

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

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 petsc
$ git pull
$ make

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

Alternative installation methods ¶

As well as being installable through pip, Firedrake also provides Docker containers and Jupyter notebooks running on Google Colab.

Having trouble?¶

If you struggling to install Firedrake for any reason please get in touch either on our Slack channel or create a GitHub discussion.

To make debugging easier please make sure to share as much information as you can including:

The operating system you are using
The command you ran and the error that was produced
Any install logs that are produced (e.g. if PETSc configure fails please make sure to share the configure.log file)