core.yml

# Main Firedrake CI workflow

on:
  workflow_call:
    inputs:
      source_ref:
        description: The input Git ref to checkout
        type: string
        required: true
      target_branch:
        description: The target branch (usually 'master' or 'release')
        type: string
        required: true
      run_tests:
        description: Whether to run the test suite
        type: boolean
        default: true
      test_macos:
        description: Whether to test using macOS
        type: boolean
        default: false
      deploy_website:
        description: Whether to deploy the website
        type: boolean
        default: false
      upload_pypi:
        description: Whether to upload an sdist to PyPI
        type: boolean
        default: false
      upload_testpypi:
        description: Whether to upload an sdist to TestPyPI
        type: boolean
        default: false

  workflow_dispatch:
    inputs:
      source_ref:
        description: The input Git ref to checkout
        type: string
        required: true
      target_branch:
        description: The target branch (usually 'master' or 'release')
        type: string
        required: true
      run_tests:
        description: Whether to run the test suite
        type: boolean
        default: true
      test_macos:
        description: Whether to test using macOS
        type: boolean
        default: false
      deploy_website:
        description: Whether to deploy the website
        type: boolean
        default: false
      upload_pypi:
        description: Whether to upload an sdist to PyPI
        type: boolean
        default: false
      upload_testpypi:
        description: Whether to upload an sdist to TestPyPI
        type: boolean
        default: false

concurrency:
  # Cancel running jobs if new commits are pushed
  group: >
    ${{ github.workflow }}-
    ${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  test_linux:
    name: Build and test Firedrake (Linux)
    strategy:
      # We want to know all of the tests which fail, so don't kill real if
      # complex fails and vice-versa
      fail-fast: false
      matrix:
        arch: [default, complex]
    runs-on: [self-hosted, Linux]
    container:
      image: ubuntu:latest
    outputs:
      sdist_conclusion: ${{ steps.report_sdist.outputs.conclusion }}
      docs_conclusion: ${{ steps.report_docs.outputs.conclusion }}
    env:
      OMPI_ALLOW_RUN_AS_ROOT: 1
      OMPI_ALLOW_RUN_AS_ROOT_CONFIRM: 1
      OMP_NUM_THREADS: 1
      OPENBLAS_NUM_THREADS: 1
      FIREDRAKE_CI: 1
      PYOP2_CI_TESTS: 1
      PYOP2_SPMD_STRICT: 1
      EXTRA_PYTEST_ARGS: --splitting-algorithm least_duration --timeout=600 --timeout-method=thread -o faulthandler_timeout=660
      PYTEST_MPI_MAX_NPROCS: 8
    steps:
      - name: Fix HOME
        # For unknown reasons GitHub actions overwrite HOME to /github/home
        # which will break everything unless fixed
        # (https://github.com/actions/runner/issues/863)
        run: echo "HOME=/root" >> "$GITHUB_ENV"

      - name: Pre-run cleanup
        # Make sure the current directory is empty
        run: find . -delete

      # Use a different mirror to fetch apt packages from to get around
      # temporary outage.
      # (https://askubuntu.com/questions/1549622/problem-with-archive-ubuntu-com-most-of-the-servers-are-not-responding)
      # The mirror was chosen from https://launchpad.net/ubuntu/+archivemirrors.
      - name: Configure apt
        run: |
          sed -i 's|http://archive.ubuntu.com/ubuntu|http://www.mirrorservice.org/sites/archive.ubuntu.com/ubuntu/|g' /etc/apt/sources.list.d/ubuntu.sources
          apt-get update

      # Git is needed for actions/checkout and Python for firedrake-configure
      - name: Install system dependencies (1)
        run: apt-get -y install git python3

      - uses: actions/checkout@v4
        with:
          path: firedrake-repo
          ref: ${{ inputs.source_ref }}

      - name: Validate single source of truth
        run: ./firedrake-repo/scripts/check-config

      # Raise an error if any 'TODO RELEASE' comments remain
      - name: Check no 'TODO RELEASE' comments (release only)
        if: inputs.target_branch == 'release'
        working-directory: firedrake-repo
        run: |
          if [ -z "$( grep -r --exclude-dir='.*' 'TODO RELEASE' )" ]; then
            exit 0
          else
            exit 1
          fi

      - name: Install system dependencies (2)
        run: |
          apt-get -y install \
            $(python3 ./firedrake-repo/scripts/firedrake-configure --arch ${{ matrix.arch }} --show-system-packages)
          apt-get -y install python3-venv
          : # Dependencies needed to run the test suite
          apt-get -y install parallel

      - name: Install PETSc
        run: |
          if [ ${{ inputs.target_branch }} = 'release' ]; then
            git clone --depth 1 \
              --branch $(python3 ./firedrake-repo/scripts/firedrake-configure --show-petsc-version) \
              https://gitlab.com/petsc/petsc.git
          else
            git clone --depth 1 https://gitlab.com/petsc/petsc.git
          fi
          cd petsc
          python3 ../firedrake-repo/scripts/firedrake-configure \
            --arch ${{ matrix.arch }} --show-petsc-configure-options | \
            xargs -L1 ./configure --with-make-np=8 --download-slepc
          make PETSC_DIR=/__w/firedrake/firedrake/petsc PETSC_ARCH=arch-firedrake-${{ matrix.arch }}
          make check
          {
            echo "PETSC_DIR=/__w/firedrake/firedrake/petsc"
            echo "PETSC_ARCH=arch-firedrake-${{ matrix.arch }}"
            echo "SLEPC_DIR=/__w/firedrake/firedrake/petsc/arch-firedrake-${{ matrix.arch }}"
          } >> "$GITHUB_ENV"

      - name: Install Firedrake
        id: install
        run: |
          export $(python3 ./firedrake-repo/scripts/firedrake-configure --arch "${{ matrix.arch }}" --show-env)
          python3 -m venv venv
          . venv/bin/activate

          : # Force a rebuild of petsc4py as the cached one will not link to the fresh
          : # install of PETSc.
          pip cache remove petsc4py
          pip cache remove slepc4py

          if [ ${{ inputs.target_branch }} = 'release' ]; then
            EXTRA_BUILD_ARGS=''
            EXTRA_PIP_FLAGS=''
          else
            : # Install build dependencies
            pip install "$PETSC_DIR"/src/binding/petsc4py
            pip install -r ./firedrake-repo/requirements-build.txt

            : # Install runtime dependencies that have been removed from the pyproject.toml
            : # because they rely on non-PyPI versions of petsc4py.
            pip install --no-build-isolation --no-deps \
              "$PETSC_DIR"/"$PETSC_ARCH"/externalpackages/git.slepc/src/binding/slepc4py
            pip install --no-deps ngsPETSc netgen-mesher netgen-occt

            : # We have to pass '--no-build-isolation' to use a custom petsc4py
            EXTRA_BUILD_ARGS='--no-isolation'
            EXTRA_PIP_FLAGS='--no-build-isolation'
          fi

          : # Install from an sdist so we can make sure that it is not ill-formed
          pip install build
          python -m build ./firedrake-repo --sdist "$EXTRA_BUILD_ARGS"

          pip install --verbose $EXTRA_PIP_FLAGS \
            --no-binary h5py \
            --extra-index-url https://download.pytorch.org/whl/cpu \
            "$(echo ./firedrake-repo/dist/firedrake-*.tar.gz)[ci,docs]"
          : # TODO: Remove before merge
          pip install --verbose --editable git+https://github.com/dolfin-adjoint/pyadjoint.git@dham/abstract_reduced_functional#egg=pyadjoint-ad

          firedrake-clean
          pip list

      - name: Upload sdist (default ARCH only)
        if: matrix.arch == 'default'
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: firedrake-repo/dist/*

      - name: Report sdist build status
        id: report_sdist
        run: echo "conclusion=success" >> "$GITHUB_OUTPUT"

      - name: Run firedrake-check
        run: |
          . venv/bin/activate
          firedrake-check
        timeout-minutes: 5

      - name: Run TSFC tests
        # Run even if earlier tests failed
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          : # Use pytest-xdist here so we can have a single collated output (not possible
          : # for parallel tests)
          firedrake-run-split-tests 1 1 -n 8 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/tsfc
        timeout-minutes: 60

      - name: Run PyOP2 tests
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          : # Use pytest-xdist here so we can have a single collated output (not possible
          : # for parallel tests)
          firedrake-run-split-tests 1 1 -n 8 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/pyop2
          firedrake-run-split-tests 2 4 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/pyop2
          firedrake-run-split-tests 3 2 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/pyop2
          firedrake-run-split-tests 4 2 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/pyop2
        timeout-minutes: 15


      - name: Run Firedrake tests (nprocs = 1)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          : # Use pytest-xdist here so we can have a single collated output (not possible
          : # for parallel tests)
          firedrake-run-split-tests 1 1 -n 8 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 60

      - name: Run tests (nprocs = 2)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          firedrake-run-split-tests 2 4 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 30

      - name: Run tests (nprocs = 3)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          firedrake-run-split-tests 3 2 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 60

      - name: Run tests (nprocs = 4)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          firedrake-run-split-tests 4 2 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 15

      - name: Run tests (nprocs = 5)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          firedrake-run-split-tests 5 1 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 15

      - name: Run tests (nprocs = 6)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          firedrake-run-split-tests 6 1 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 15

      - name: Run tests (nprocs = 7)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          firedrake-run-split-tests 7 1 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 15

      - name: Run tests (nprocs = 8)
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        run: |
          . venv/bin/activate
          firedrake-run-split-tests 8 1 "$EXTRA_PYTEST_ARGS" firedrake-repo/tests/firedrake
        timeout-minutes: 15

      - name: Run Gusto smoke tests
        # Only test Gusto in real mode
        if: |
          inputs.run_tests &&
          (success() || steps.install.conclusion == 'success') &&
          matrix.arch == 'default'
        run: |
          . venv/bin/activate
          git clone --depth 1 https://github.com/firedrakeproject/gusto.git gusto-repo
          pip install --verbose ./gusto-repo
          python -m pytest -n 8 --verbose \
            gusto-repo/integration-tests/balance/test_saturated_balance.py \
            gusto-repo/integration-tests/equations/test_thermal_sw.py \
            gusto-repo/integration-tests/transport/test_embedded_dg_advection.py
        timeout-minutes: 10

      - name: Run Thetis smoke tests
        if: |
          inputs.run_tests &&
          (success() || steps.install.conclusion == 'success') &&
          matrix.arch == 'default'
        run: |
          . venv/bin/activate
          git clone --depth 1 https://github.com/thetisproject/thetis.git thetis-repo
          pip install --verbose ./thetis-repo
          python -m pytest -n 8 --verbose thetis-repo/test_adjoint/test_swe_adjoint.py
        timeout-minutes: 10

      - name: Run spyro smoke tests
        if: |
          inputs.run_tests &&
          (success() || steps.install.conclusion == 'success') &&
          matrix.arch == 'default'
        run: |
          . venv/bin/activate
          git clone --depth 1 https://github.com/NDF-Poli-USP/spyro.git spyro-repo
          pip install --verbose ./spyro-repo
          mpiexec -n 6 python -m pytest spyro-repo/test_integration/ -m parallel[6]
        timeout-minutes: 5

      - name: Run G-ADOPT smoke tests
        if: |
          inputs.run_tests &&
          (success() || steps.install.conclusion == 'success') &&
          matrix.arch == 'default'
        run: |
          . venv/bin/activate
          git clone --depth 1 https://github.com/g-adopt/g-adopt.git g-adopt-repo
          pip install --verbose ./g-adopt-repo
          make -C g-adopt-repo/demos/mantle_convection/base_case check
        timeout-minutes: 5

      - name: Upload log files
        uses: actions/upload-artifact@v4
        if: inputs.run_tests && (success() || steps.install.conclusion == 'success')
        with:
          name: firedrake-logs-${{ matrix.arch }}
          path: pytest_*.log

      - name: Install system dependencies (3)
        if: (success() || steps.install.conclusion == 'success') && matrix.arch == 'default'
        run: apt-get -y install inkscape texlive-full

      - name: Check bibtex
        if: (success() || steps.install.conclusion == 'success') && matrix.arch == 'default'
        run: |
          . venv/bin/activate
          make -C firedrake-repo/docs validate-bibtex

      - name: Check documentation links
        if: (success() || steps.install.conclusion == 'success') && matrix.arch == 'default'
        run: |
          . venv/bin/activate
          make -C firedrake-repo/docs linkcheck

      - name: Build documentation
        if: (success() || steps.install.conclusion == 'success') && matrix.arch == 'default'
        id: build_docs
        run: |
          . venv/bin/activate
          cd firedrake-repo/docs
          make SPHINXOPTS="-t ${{ inputs.target_branch }}" html
          make latex
          make latexpdf
          # : Copy manual to HTML tree
          cp build/latex/Firedrake.pdf build/html/_static/manual.pdf

      - name: Upload documentation
        uses: actions/upload-pages-artifact@v3
        id: upload_docs
        if: (success() || steps.build_docs.conclusion == 'success') && matrix.arch == 'default'
        with:
          name: github-pages
          path: firedrake-repo/docs/build/html
          retention-days: 1

      - name: Report docs build status
        id: report_docs
        if: success() || steps.upload_docs.conclusion == 'success'
        run: echo "conclusion=success" >> "$GITHUB_OUTPUT"

      # Some files are automatically generated when we install or build the
      # docs (e.g. AUTHORS.rst). These files are committed to the repository
      # so uncommitted changes at this point reflect changes in the automatically
      # generated files that ought to be committed.
      - name: Check no untracked files
        if: always()
        working-directory: firedrake-repo
        run: |
          if [ -z "$( git status --porcelain )" ]; then
            exit 0
          else
            echo Error: there are untracked files in the repository
            echo The output from 'git status' is:
            git status
            exit 1
          fi

      - name: Post-run cleanup
        if: always()
        run: find . -delete

  test_macos:
    name: Build and test Firedrake (macOS)
    runs-on: [self-hosted, macOS]
    if: inputs.test_macos
    env:
      FIREDRAKE_CI: 1
      OMP_NUM_THREADS: 1
      OPENBLAS_NUM_THREADS: 1
    steps:
      - name: Add homebrew to PATH
        # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-system-path
        run: echo "/opt/homebrew/bin" >> "$GITHUB_PATH"

      - name: Pre-run cleanup
        # Make sure the current directory is empty
        run: find . -delete

      - uses: actions/checkout@v4
        with:
          path: firedrake-repo
          ref: ${{ inputs.source_ref }}

      - name: Install system dependencies
        run: |
          brew install $(python3 ./firedrake-repo/scripts/firedrake-configure --arch default --show-system-packages)

      - name: Install PETSc
        run: |
          if [ ${{ inputs.target_branch }} = 'release' ]; then
            git clone --depth 1 \
              --branch $(python3 ./firedrake-repo/scripts/firedrake-configure --show-petsc-version) \
              https://gitlab.com/petsc/petsc.git
          else
            git clone --depth 1 https://gitlab.com/petsc/petsc.git
          fi
          cd petsc
          python3 ../firedrake-repo/scripts/firedrake-configure \
            --arch default --show-petsc-configure-options | \
            xargs -L1 ./configure --with-make-np=4
          make
          make check
          {
            echo "PETSC_DIR=/Users/github/actions-runner/_work/firedrake/firedrake/petsc"
            echo "PETSC_ARCH=arch-firedrake-default"
            echo "SLEPC_DIR=/Users/github/actions-runner/_work/firedrake/firedrake/petsc/arch-firedrake-default"
          } >> "$GITHUB_ENV"

      - name: Install Firedrake
        id: install
        run: |
          export $(python3 ./firedrake-repo/scripts/firedrake-configure --arch default --show-env)
          python3 -m venv venv
          . venv/bin/activate

          : # Force a rebuild of petsc4py as the cached one will not link to the fresh
          : # install of PETSc. A similar trick may be needed for compiled dependencies
          : # like h5py or mpi4py if changing HDF5/MPI libraries.
          pip cache remove petsc4py

          : # Hotfix for petsc4py build, see https://gitlab.com/petsc/petsc/-/issues/1759
          echo 'Cython<3.1' > constraints.txt
          export PIP_CONSTRAINT=constraints.txt

          if [ ${{ inputs.target_branch }} = 'release' ]; then
            EXTRA_PIP_FLAGS=''
          else
            : # Install build dependencies
            pip install "$PETSC_DIR"/src/binding/petsc4py
            pip install -r ./firedrake-repo/requirements-build.txt

            : # We have to pass '--no-build-isolation' to use a custom petsc4py
            EXTRA_PIP_FLAGS='--no-build-isolation'
          fi

          pip install --verbose $EXTRA_PIP_FLAGS \
            --no-binary h5py \
            './firedrake-repo[check]'

          firedrake-clean
          pip list

      - name: Run smoke tests
        run: |
          . venv/bin/activate
          firedrake-check
        timeout-minutes: 10

      - name: Post-run cleanup
        if: always()
        run: |
          find . -delete

  lint:
    name: Lint codebase
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.source_ref }}
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Setup flake8 annotations
        uses: rbialon/flake8-annotations@v1
      - name: Install linting packages
        run: pip install flake8 pylint
      - name: Lint codebase
        run: make lint GITHUB_ACTIONS_FORMATTING=1

  deploy_website:
    name: Deploy GitHub pages (optional)
    needs: test_linux
    # Only deploy the website for master here, the release branch is managed
    # by https://github.com/firedrakeproject/firedrakeproject.github.io
    if: |
      always() &&
      inputs.deploy_website &&
      inputs.target_branch == 'master' &&
      needs.test_linux.outputs.docs_conclusion == 'success'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: http://firedrakeproject.github.io/firedrake
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

  upload_pypi:
    name: Upload to PyPI (optional)
    needs: test_linux
    if: |
      always() &&
      inputs.upload_pypi &&
      inputs.target_branch == 'release' &&
      needs.test_linux.outputs.sdist_conclusion == 'success'
    runs-on: ubuntu-latest
    environment:
      name: pypi
    permissions:
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist
      - name: Push to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

  upload_testpypi:
    name: Upload to TestPyPI (optional)
    needs: test_linux
    if: |
      always() &&
      inputs.upload_testpypi &&
      inputs.target_branch == 'release' &&
      needs.test_linux.outputs.sdist_conclusion == 'success'
    runs-on: ubuntu-latest
    environment:
      name: testpypi
    permissions:
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist
      - name: Push to TestPyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          repository-url: https://test.pypi.org/legacy/