Update Firedrake installation instructions and workflow (#125)

Closes #112.

The Firedrake installation approach moved away from the
`firedrake-install` script and is now clearly separated in three
distinct steps that are described in
https://www.firedrakeproject.org/install.html and that are very easy for
users to follow. We follow their instructions almost exactly as
described, except that we pass some extra flags to PETSc's `configure`
(`--download-parmmg` etc.).

So here I removed a lot of our own installation instructions, as well as
related files that we used to aid the installation process.

Author: ddundo

.dockerignore

@@ -1,10 +1,9 @@
 name: 'Test Firedrake Installation'
 
 on:
-  # Trigger when this or any file in the install directory changes
+  # Trigger when this workflow changes in an open PR
   pull_request:
     paths:
-      - 'install/**'
       - '.github/workflows/test_firedrake_install.yml'
 
   # Trigger the workflow on the 1st day of every month at midnight
@@ -26,53 +25,54 @@ jobs:
     container:
       image: ubuntu:24.04
       options: --user root
+    env:
+      OMPI_ALLOW_RUN_AS_ROOT: 1
+      OMPI_ALLOW_RUN_AS_ROOT_CONFIRM: 1
 
     steps:
-      - name: 'Install required packages'
+      - name: Fix HOME
+        # GitHub sets HOME to /github/home (https://github.com/actions/runner/issues/863)
+        run: echo "HOME=/root" >> "$GITHUB_ENV"
+
+      - name: 'Install system dependencies'
         run: |
           apt-get update
           apt-get -y dist-upgrade
-          apt-get install -y --no-install-recommends tzdata curl vim docker.io \
-          openssh-client build-essential autoconf automake cmake gfortran git \
-          libopenblas-serial-dev libtool python3-dev python3-pip python3-tk \
-          python3-venv python3-requests zlib1g-dev libboost-dev sudo gmsh bison flex \
-          ninja-build libocct-ocaf-dev libocct-data-exchange-dev swig graphviz \
-          libcurl4-openssl-dev libxml2-dev
+          apt-get -y install curl python3 python3-pip python3-venv
+          curl -O https://raw.githubusercontent.com/firedrakeproject/firedrake/master/scripts/firedrake-configure
+          apt-get -y install $(python3 firedrake-configure --show-system-packages)
 
-      - name: 'Download necessary files'
+      - name: 'Install PETSc'
         run: |
-          curl -O https://raw.githubusercontent.com/mesh-adaptation/mesh-adaptation-docs/main/install/Makefile
-          curl -O https://raw.githubusercontent.com/mesh-adaptation/mesh-adaptation-docs/main/install/petsc_configure_options.txt
+          git clone --depth 1 --branch $(python3 firedrake-configure --show-petsc-version) https://gitlab.com/petsc/petsc.git
+          cd petsc
+          python3 ../firedrake-configure --show-petsc-configure-options | xargs -L1 ./configure --with-make-np=8 --download-eigen --download-parmetis --download-mmg --download-parmmg
+          make PETSC_DIR=$(pwd) PETSC_ARCH=arch-firedrake-default all
+          make check
 
       - name: 'Install Firedrake'
         run: |
-          yes | make install
-          cd firedrake-*/
-          echo "FIREDRAKE_ENV=$(pwd)" >> $GITHUB_ENV
-
-      - name: 'Upload firedrake-install.log as an artifact'
-        if: ${{ !cancelled() }}
-        uses: actions/upload-artifact@v4
-        with:
-          name: firedrake-install-log
-          path: firedrake-install.log
-          retention-days: 1
-          overwrite: true
+          python3 -m venv venv
+          . venv/bin/activate
+          export $(python3 firedrake-configure --show-env)
+          pip cache remove petsc4py
+          pip install --no-binary h5py --src . -e git+https://github.com/firedrakeproject/firedrake.git#egg=firedrake[check]
 
+      # Do not call `make test` here since we need --use-hwthread-cpus for nprocs=3 tests 
       - name: 'Install and test Animate'
         run: |
-          . $FIREDRAKE_ENV/bin/activate
-          cd $FIREDRAKE_ENV/src
+          . venv/bin/activate
           git clone https://github.com/mesh-adaptation/animate.git
           cd animate
           make install_dev
-          make test
+          python3 -m pytest -v -k "parallel[1] or not parallel" test
+          mpiexec -n 2 python3 -m pytest -v -m parallel[2] test
+          mpiexec -n 3 --use-hwthread-cpus python3 -m pytest -v -m parallel[3] test
 
       - name: 'Install and test Goalie'
         if: ${{ !cancelled() }}
         run: |
-          . $FIREDRAKE_ENV/bin/activate
-          cd $FIREDRAKE_ENV/src
+          . venv/bin/activate
           git clone https://github.com/mesh-adaptation/goalie.git
           cd goalie
           make install_dev
@@ -81,8 +81,7 @@ jobs:
       - name: 'Install and test Movement'
         if: ${{ !cancelled() }}
         run: |
-          . $FIREDRAKE_ENV/bin/activate
-          cd $FIREDRAKE_ENV/src
+          . venv/bin/activate
           git clone https://github.com/mesh-adaptation/movement.git
           cd movement
           make install_dev

.github/workflows/test_firedrake_install.yml

@@ -1,59 +1,36 @@
 The following installation instructions assume a Linux or Windows Subsystem for Linux (WSL) operating system.
-The mesh adaptation modules are dependent on a custom setup for Firedrake with PETSc from either a [Makefile](#default-approach) or a [Docker image](#installing-firedrake-via-docker-image).
+The mesh adaptation modules are dependent on a custom setup for Firedrake with PETSc from either a [local installation](#local-firedrake-installation) or a [pre-built Docker image](#installing-firedrake-via-docker-image).
 Once Firedrake is installed (or if you already have a working installation), see the section on [installing Animate, Goalie, or Movement](#installing-animate-goalie-or-movement).
 
-## Installing Firedrake with custom PETSc
+## Local Firedrake installation
 
-Firedrake and PETSc are required by Animate, Goalie, and Movement. Choose from the following installation approaches for these packages.
+As described on the [Firedrake installation page](https://www.firedrakeproject.org/install.html#), a native installation of Firedrake is accomplished in 3 steps:
+1. Installing systems dependencies
+2. Installing PETSc
+3. Installing Firedrake itself.
 
-### Default approach
-
-The first approach uses the default MPI packages found in the path.
-Run the following code to download and install Firedrake and PETSc using the associated Makefile and bespoke PETSc options:
-```
-curl -O https://raw.githubusercontent.com/mesh-adaptation/mesh-adaptation-docs/main/install/Makefile
-curl -O https://raw.githubusercontent.com/mesh-adaptation/mesh-adaptation-docs/main/install/petsc_configure_options.txt
-make install
-```
-
-The `make install` command accepts several optional arguments:
-* `FIREDRAKE_ENV` for setting the Firedrake virtual environment name. Defaults to `firedrake-mmmyy`, where `mmm` is the first three letters of the current month and `yy` are the last two digits of the current year.
-* `BUILD_DIR` for setting the build directory. Defaults to the current directory.
-* `PETSC_CONFIGURE_FILE` for setting the PETSc configure options. Defaults to `petsc_configure_options.txt`.
-These options may be combined, e.g.:
-```
-make install FIREDRAKE_ENV=firedrake-dev BUILD_DIR=/scratch PETSC_CONFIGURE_FILE=my_configure_file.txt
-```
-
-### Custom MPI approach
-
-The second approach allows customisation of the MPI packages by passing arguments to the associated Makefile. First, download the Makefile and bespoke PETSc options using `curl`:
-```
-curl -O https://raw.githubusercontent.com/mesh-adaptation/mesh-adaptation-docs/main/install/Makefile
-curl -O https://raw.githubusercontent.com/mesh-adaptation/mesh-adaptation-docs/main/install/petsc_configure_options.txt
-```
-When running `make install`, pass arguments for `MPICC`, `MPICXX`, `MPIF90`, and `MPIEXEC`:
+To use the mesh adaptation modules, we can install system dependencies (step 1) and Firedrake (step 3) exactly as described, but we must [customise the PETSc installation](https://www.firedrakeproject.org/install.html#id29) (step 2) to install additional packages: Eigen, ParMETIS, MMG, and ParMMG. We do that simply by passing the `--download-<PACKAGE>` flags when running PETSc `configure`:
 ```
-make install MPICC=/path/to/mpicc MPICXX=/path/to/mpicxx MPIF90=/path/to/mpif90 MPIEXEC=/path/to/mpiexec
+python3 ../firedrake-configure --show-petsc-configure-options | xargs -L1 ./configure --download-chaco --download-eigen --download-parmetis --download-mmg --download-parmmg
 ```
 
 ## Docker container approach
 
-A bespoke Firedrake Docker container exists and can be downloaded and installed as an alternative to the above:
+A bespoke Firedrake Docker image exists and can be downloaded and run as an alternative to the above:
 ```
 docker pull ghcr.io/mesh-adaptation/firedrake-parmmg:latest
-docker run --rm -it -v ${HOME}:${HOME} ghcr.io/mesh-adaptation/firedrake-parmmg:latest
+docker run -it ghcr.io/mesh-adaptation/firedrake-parmmg:latest
 ```
 
-NOTE: by installing via a Docker image with ``${HOME}`` you are giving Docker access to your home space.
+For more information on how to run docker containers, see the [official documentation](https://docs.docker.com/engine/containers/run/). For example, since all data inside a container is only accessible from inside the container, it is useful to create [filesystem mounts](https://docs.docker.com/engine/containers/run/#filesystem-mounts) to be able to access data from outside the container.
 
 ## Installing Mesh Adaptation modules
 
 The Mesh Adaptation packages can be installed through the following options, denoting the package of interest by `<PACKAGE>`.
 In both cases, make sure that you have activated the Python virtual environment that was created when you installed Firedrake.
 Ensure that you have activated the Python virtual environment associated with your Firedrake installation before following the steps below:
 ```
-source /path/to/firedrake/bin/activate
+source /path/to/venv/bin/activate
 ```
 
 ### Cloning via HTTPS
@@ -76,9 +53,6 @@ make install
 
 It is highly recommended to keep your Firedrake installation and Mesh Adaptation software stack up to date.
 **We recommend updating the full stack at least once every two months.**
-The quickest way to do this is to use the `firedrake-update` command from within an active virtual environment.
-This approach works well when there have been small changes to Firedrake and/or its associated dependencies and add-ons, but sometimes fails when there have been major changes.
-See https://www.firedrakeproject.org/download.html for details on updating Firedrake.
 
-If the `firedrake-update` approach fails then we recommend creating a whole new Firedrake installation using one of the approaches described above.
-Note that the `--venv-name` command line option for the `firedrake-install` script can be useful for differentiating between different builds.
+* To update Firedrake and PETSc, follow the [official Firedrake instructions](https://www.firedrakeproject.org/install.html#updating-firedrake) on how to do so.
+* To update Animate/Goalie/Movement, simply change directory to where each one is located (`cd /path/to/package`) and run `git pull`.