diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 14637408d2..5bd8da3c7a 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -72,8 +72,11 @@ jobs: 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" >> "$GITHUB_ENV" - echo "PETSC_ARCH=arch-firedrake-${{ matrix.arch }}" >> "$GITHUB_ENV" + { + 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 diff --git a/demos/eigenvalues_QG_basinmodes/qgbasinmodes.py.rst b/demos/eigenvalues_QG_basinmodes/qgbasinmodes.py.rst index 4e957affc9..33c5b02d4a 100644 --- a/demos/eigenvalues_QG_basinmodes/qgbasinmodes.py.rst +++ b/demos/eigenvalues_QG_basinmodes/qgbasinmodes.py.rst @@ -18,10 +18,8 @@ dissipative forces. Unlike the other demo that integrated the equations forward in time, in this problem it is necessary to compute the eigenvalues and eigenfunctions for a particular differential operator. -This demo requires SLEPc and slepc4py to be installed. This is most easily -achieved by providing the optional `--slepc` flag to either `firedrake-install` -(for a new installation), or `firedrake-update` (to add SLEPc to an existing -installation). +This demo requires SLEPc and slepc4py to be installed. For instructions on how +to install them please follow `these instructions `_. Governing PDE diff --git a/demos/netgen/netgen_mesh.py.rst b/demos/netgen/netgen_mesh.py.rst index 688f150aa1..3d3235aa96 100755 --- a/demos/netgen/netgen_mesh.py.rst +++ b/demos/netgen/netgen_mesh.py.rst @@ -11,7 +11,7 @@ Finally we will show how to use mesh refinement features included in Netgen to c Installing Netgen ------------------ -This demo requires the NGSolve/Netgen suite to be installed. This is most easily achieved by providing the optional `--netgen` flag to either `firedrake-install` (for a new installation), or `firedrake-update` (to add the NGSolve/Netgen suite to an existing installation). :: +This demo requires the NGSolve/Netgen suite to be installed. This can be done by running ``pip install ngsPETSc``. :: from firedrake import * try: diff --git a/docs/source/checkpointing.rst b/docs/source/checkpointing.rst index b3ff8049fb..841674b035 100644 --- a/docs/source/checkpointing.rst +++ b/docs/source/checkpointing.rst @@ -617,9 +617,9 @@ Firedrake uses the PETSc_ HDF5 Viewer_ object to write and read state. As such, writing data is collective across processes. h5py_ is used for attribute manipulation. To this end, h5py_ *must* be linked against the same version of the HDF5 library that PETSc was built -with. The ``firedrake-install`` script automates this, however, if -you build PETSc manually, you will need to ensure that h5py_ is linked -correctly following the instructions for custom installation here_. +with. If you have a custom installation of Firedrake then it may be +necessary to manually ensure that h5py is linked correctly. +Instructions for how to do this can be found here_. .. warning:: diff --git a/docs/source/install.rst b/docs/source/install.rst index 2c76de6f1d..6f5e1bfc1a 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -15,8 +15,9 @@ Supported systems ================= A :ref:`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 +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 :ref:`alternative installation mechanisms`. @@ -52,25 +53,16 @@ To simplify the installation process, Firedrake provides a utility script called $ 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. -.. _firedrake_archs: - -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. +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 :ref:`customising`. .. _install_system_dependencies: @@ -100,12 +92,6 @@ which will install the following packages: 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`` :ref:`step` by - passing additional flags (e.g. ``--download-hdf5``, ``--download-hwloc``). - .. _install_petsc: @@ -147,31 +133,13 @@ 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 +For the default build, running ``firedrake-configure`` with ``--no-package-manager`` will produce the flags: .. literalinclude:: petsc_configure_options.txt :language: text -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 - - $ ./configure $(cat my_configure_options.txt) - - .. _install_firedrake: Installing Firedrake @@ -193,15 +161,12 @@ install Firedrake. To do this perform the following steps: $ export $(python3 firedrake-configure --show-env) - At a minimum this will set the following variables: + Which at a minimum will set the following variables: .. code-block:: text 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 @@ -211,14 +176,30 @@ install Firedrake. To do this perform the following steps: #. Install Firedrake:: - $ pip install --no-binary h5py "firedrake @ git+https://github.com/firedrakeproject/firedrake.git#[test]" + $ 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 test - dependencies with ``[test]`` it is recommended because it allows you + 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 :ref:`below`). + .. note:: + A common issue encountered with this step is the installation will fail with + an error message like: + + .. code-block:: text + + FileNotFoundError: [Errno 2] No such file or directory: '/tmp/pip-build-env-9j45p2su/normal/lib/python3.11/site-packages/petsc/lib/petsc/conf/petscvariables' + + This usually means 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 + + #. Firedrake is now installed and ready for use! .. warning:: @@ -227,26 +208,6 @@ install Firedrake. To do this perform the following steps: Firedrake and its components. To install Firedrake in editable mode you should follow the instructions :ref:`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``) - .. _firedrake_check: @@ -264,59 +225,191 @@ minute or less. If they fail to run for any reason, please see the section below on how to :ref:`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]`` +Firedrake with its optional test dependencies by specifying the ``[check]`` dependency group as shown :ref:`above`. +Updating Firedrake +------------------ + +Updating Firedrake involves following the same steps as above when +:ref:`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 + + .. _dev_install: 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:: +mode you should follow the same +:ref:`steps as for a non-editable install` but replace the +final ``pip install`` command with:: - $ git clone https://github.com/firedrakeproject/firedrake.git + $ git clone $ pip install --no-binary h5py --editable './firedrake[dev]' +where ```` 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 https://github.com/firedrakeproject/fiat.git + $ git clone $ 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. +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. -Updating Firedrake ------------------- +.. _customising: -Updating Firedrake involves following the same steps as above when -:ref:`installing Firedrake`. First, use ``firedrake-configure`` -to set the right environment variables and then run:: +Customising Firedrake +===================== - $ pip install --upgrade git+https://github.com/firedrakeproject/firedrake.git -Updating PETSc -~~~~~~~~~~~~~~ +.. _firedrake_archs: -To update PETSc you simply need to run:: +Prepared configurations +----------------------- - $ cd petsc - $ git pull - $ make +``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: -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:: +* ``default``: the default installation, suitable for most users +* ``complex``: an installation where PETSc is configured using complex numbers - $ make reconfigure +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 :ref:`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 + + $ 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_install: @@ -324,10 +417,59 @@ out-of-date you may also need to rebuild the external packages by running:: Alternative installation methods ================================ -As well as being installable through ``pip``, Firedrake also provides -`Docker containers `_ and -Jupyter notebooks running on :doc:`Google Colab`. +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/:latest + +to download the most recent image (replacing ```` with the desired +image). Then you can run:: + + $ docker run -it firedrakeproject/: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 :doc:`here`. .. _getting_help: diff --git a/pyproject.toml b/pyproject.toml index de4ec400f8..f0803671fb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -65,11 +65,47 @@ spydump = "pyop2.scripts.spydump:main" [project.optional-dependencies] -# Dependencies needed to run firedrake-check -test = [ +check = [ "mpi-pytest", "pytest", ] +dev = [ # build dependencies that are needed to run 'make' + "Cython", + "mpi-pytest", + "pybind11", + "pytest", + "setuptools", +] +docs = [ + "bibtexparser", + "matplotlib", # needed to resolve API + "numpydoc", + "pylit", + "sphinx<8.2.0", # https://github.com/firedrakeproject/firedrake/issues/4059 + "sphinx-autobuild", + "sphinx-reredirects", + "sphinxcontrib-bibtex", + "sphinxcontrib-jquery", + "sphinxcontrib-svg2pdfconverter", + "sphinxcontrib-youtube", + "vtk", # needed to resolve API +] +jax = [ + "jax", +] +netgen = [ + "ngsPETSc", +] +slepc = [ + "slepc4py==3.22.2", +] +torch = [ # requires passing '--extra-index-url' to work + "torch", +] +vtk = [ + "vtk", +] + # Dependencies needed to run the full test suite ci = [ "ipympl", # needed for notebook testing @@ -99,29 +135,6 @@ docker = [ # Used in firedrake-vanilla container "pytest-xdist", "slepc4py==3.22.2", ] -# Dependencies needed to build the docs -docs = [ - "bibtexparser", - "matplotlib", # needed to resolve API - "numpydoc", - "pylit", - "sphinx<8.2.0", # https://github.com/firedrakeproject/firedrake/issues/4059 - "sphinx-autobuild", - "sphinx-reredirects", - "sphinxcontrib-bibtex", - "sphinxcontrib-jquery", - "sphinxcontrib-svg2pdfconverter", - "sphinxcontrib-youtube", - "vtk", # needed to resolve API -] -# Developer dependencies. In particular the build dependencies that are needed to run 'make'. -dev = [ - "Cython", - "mpi-pytest", - "pybind11", - "pytest", - "setuptools", -] [build-system] requires = [