|
| 1 | +# Installation |
| 2 | + |
| 3 | +- [Requirements](#requirements) |
| 4 | +- [Python setup and project download](#python-setup-and-project-download) |
| 5 | +- [Installing the library](#installing-the-library) |
| 6 | +- [Optional PETSc installation](#optional-petsc-installation) |
| 7 | +- [Uninstall](#uninstall) |
| 8 | + |
| 9 | +## Requirements |
| 10 | + |
| 11 | +Psydac requires a certain number of components to be installed on the machine: |
| 12 | + |
| 13 | +- Fortran and C compilers with OpenMP support |
| 14 | +- OpenMP library |
| 15 | +- BLAS and LAPACK libraries |
| 16 | +- MPI library |
| 17 | +- HDF5 library with MPI support |
| 18 | + |
| 19 | +The installation instructions depend on the operating system and on the packaging manager used. |
| 20 | + |
| 21 | +### Linux Debian-Ubuntu-Mint |
| 22 | + |
| 23 | +To install all requirements on a Linux Ubuntu operating system, just use APT, the Advanced Packaging Tool: |
| 24 | +```sh |
| 25 | +sudo apt update |
| 26 | +sudo apt install python3 python3-dev python3-pip |
| 27 | +sudo apt install gcc gfortran |
| 28 | +sudo apt install libblas-dev liblapack-dev |
| 29 | +sudo apt install libopenmpi-dev openmpi-bin |
| 30 | +sudo apt install libomp-dev libomp5 |
| 31 | +sudo apt install libhdf5-openmpi-dev |
| 32 | +``` |
| 33 | + |
| 34 | +### macOS |
| 35 | + |
| 36 | +To install all the requirements on a macOS operating system we recommend using [Homebrew](https://brew.sh/): |
| 37 | + |
| 38 | +```eh |
| 39 | +brew update |
| 40 | +brew install gcc |
| 41 | +brew install openblas |
| 42 | +brew install lapack |
| 43 | +brew install open-mpi |
| 44 | +brew install libomp |
| 45 | +brew install hdf5-mpi |
| 46 | +``` |
| 47 | + |
| 48 | +### Other operating systems |
| 49 | + |
| 50 | +Please see the [instructions for the pyccel library](https://github.com/pyccel/pyccel#Requirements) for further details. |
| 51 | + |
| 52 | +### High-performance computers using Environment Modules |
| 53 | + |
| 54 | +Many high-performance computers use [Environment Modules](https://modules.sourceforge.net/). |
| 55 | +On those systems one typically needs to load the correct versions (i.e. compatible with each other) of the modules `gcc`, `openmpi`, and `hdf5-mpi`, e.g. |
| 56 | + |
| 57 | +```sh |
| 58 | +module load gcc/15 |
| 59 | +module load openmpi/5.0 |
| 60 | +module load hdf5-mpi/1.14.1 |
| 61 | +``` |
| 62 | +OpenMP instructions should work out of the box. |
| 63 | +For access to BLAS and LAPACK routines there are usually different options, we refer therefore to any documentation provided by the supercomputer's maintainers. |
| 64 | + |
| 65 | +## Python setup and project download |
| 66 | + |
| 67 | +We recommend creating a clean Python virtual environment using [venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment): |
| 68 | +```sh |
| 69 | +python3 -m venv <ENV-PATH> |
| 70 | +``` |
| 71 | +where `<ENV-PATH>` is the location to create the virtual environment. |
| 72 | +(A new directory will be created at the required location.) |
| 73 | +In order to activate the environment just run the command |
| 74 | +```sh |
| 75 | +source <ENV-PATH>/bin/activate |
| 76 | +``` |
| 77 | +At this point the commands `python` and [`pip`](https://pip.pypa.io/en/stable/) will refer to the Python 3 interpreter and package manager of the virtual environment, respectively. |
| 78 | +Additionally, the command `deactivate` closes the environment. |
| 79 | +It is good practice to keep `pip` up to date with |
| 80 | +```sh |
| 81 | +pip install --upgrade pip |
| 82 | +``` |
| 83 | + |
| 84 | +One can clone the Psydac repository at any location `<ROOT-PATH>` in the filesystem which does not require administrator privileges, using either |
| 85 | +```sh |
| 86 | +git clone https://github.com/pyccel/psydac.git |
| 87 | +``` |
| 88 | +or |
| 89 | +```sh |
| 90 | +git clone [email protected]:pyccel/psydac.git |
| 91 | +``` |
| 92 | +The latter command requires a GitHub account. |
| 93 | + |
| 94 | +## Installing the library |
| 95 | + |
| 96 | +Psydac depends on several Python packages, which should be installed in the newly created virtual environment. |
| 97 | +Almost all of these dependencies will be automatically installed by `pip` at the time of installing the `psydac` package later on. |
| 98 | + |
| 99 | +The single exception is the `h5py` package, which needs to be installed in parallel mode. |
| 100 | +This means that a wheel will be built from sources and linked to the local parallel HDF5 library. |
| 101 | + |
| 102 | +To this end, we first set the environment variable `HDF5_DIR` s.t. the path `$HDF5_DIR/lib/` will correspond to the folder containing the dynamic library `libhdf5.so` (on Ubuntu/Debian) or `libhdf5.dylib` (on macOS). |
| 103 | +This path can be obtained with a command which depends on your system. |
| 104 | + |
| 105 | +- **Ubuntu/Debian**: |
| 106 | + ```sh |
| 107 | + export HDF5_DIR=$(dpkg -L libhdf5-openmpi-dev | grep "libhdf5.so" | xargs dirname) |
| 108 | + ``` |
| 109 | + |
| 110 | +- **macOS**: |
| 111 | + ```sh |
| 112 | + export HDF5_DIR=$(brew list hdf5-mpi | grep "libhdf5.dylib" | xargs dirname | xargs dirname) |
| 113 | + ``` |
| 114 | + |
| 115 | +- **High-performance computers using [Environment Modules](https://modules.sourceforge.net/)**: |
| 116 | + |
| 117 | + The correct location of the HDF5 library can be found using the `module show` command, which reveals any environment variables after the `setenv` keyword. |
| 118 | + For example, on this system both `HDF5_HOME` and `HDF5_ROOT` contain the information we need: |
| 119 | + |
| 120 | + ```sh |
| 121 | + > module show hdf5-mpi/1.14.1 |
| 122 | +
|
| 123 | + ------------------------------------------------------------------- |
| 124 | + /mpcdf/soft/SLE_15/sub/gcc_15/sub/openmpi_5_0/modules/libs/hdf5-mpi/1.14.1: |
| 125 | +
|
| 126 | + module-whatis {HDF5 library 1.14.1 with MPI support, built for openmpi_5_0_7_gcc_15_1} |
| 127 | + conflict hdf5-serial |
| 128 | + conflict hdf5-mpi |
| 129 | + setenv HDF5_HOME /mpcdf/soft/SLE_15/packages/skylake/hdf5/gcc_15-15.1.0-openmpi_5.0-5.0.7/1.14.1 |
| 130 | + setenv HDF5_ROOT /mpcdf/soft/SLE_15/packages/skylake/hdf5/gcc_15-15.1.0-openmpi_5.0-5.0.7/1.14.1 |
| 131 | + prepend-path PATH /mpcdf/soft/SLE_15/packages/skylake/hdf5/gcc_15-15.1.0-openmpi_5.0-5.0.7/1.14.1/bin |
| 132 | + ------------------------------------------------------------------- |
| 133 | + ``` |
| 134 | + |
| 135 | + Therefore it is sufficient to set |
| 136 | + |
| 137 | + ```sh |
| 138 | + export HDF5_DIR=$HDF5_HOME |
| 139 | + ``` |
| 140 | + |
| 141 | +Next, install `h5py` in parallel mode using `pip`: |
| 142 | +```sh |
| 143 | +export CC="mpicc" |
| 144 | +export HDF5_MPI="ON" |
| 145 | +
|
| 146 | +pip install h5py --no-cache-dir --no-binary h5py |
| 147 | +``` |
| 148 | + |
| 149 | +At this point the Psydac library may be installed from the cloned directory `<ROOT-PATH>/psydac` in **standard mode**, which copies the relevant files to the correct locations of the virtual environment, or in **development mode**, which only installs symbolic links to the Psydac directory. The latter mode allows one to affect the behavior of Psydac by modifying the source files. |
| 150 | + |
| 151 | +- **Standard mode**: |
| 152 | + ```bash |
| 153 | + pip install . |
| 154 | + ``` |
| 155 | + |
| 156 | +- **Development mode**: |
| 157 | + ```bash |
| 158 | + pip install --editable . |
| 159 | + ``` |
| 160 | + |
| 161 | +## Optional PETSc installation |
| 162 | + |
| 163 | +Although Psydac provides several iterative linear solvers which work with our native matrices and vectors, it is often useful to access a dedicated library like [PETSc](https://petsc.org). To this end, our matrices and vectors have the method `topetsc()`, which converts them to the corresponding `petsc4py` objects. |
| 164 | +(`petsc4py` is a Python package which provides Python bindings to PETSc.) After solving the linear system with a PETSc solver, the function `petsc_to_psydac` allows converting the solution vector back to the Psydac format. |
| 165 | +
|
| 166 | +In order to use these additional feature, PETSc and petsc4py must be installed as follows. |
| 167 | +First, we download the latest release of PETSc from its [official Git repository](https://gitlab.com/petsc/petsc): |
| 168 | +```sh |
| 169 | +git clone --depth 1 --branch v3.21.4 https://gitlab.com/petsc/petsc.git |
| 170 | +``` |
| 171 | +Next, we specify a configuration for complex numbers, and install PETSc in a local directory: |
| 172 | +```sh |
| 173 | +cd petsc |
| 174 | + |
| 175 | +export PETSC_DIR=$(pwd) |
| 176 | +export PETSC_ARCH=petsc-cmplx |
| 177 | + |
| 178 | +./configure --with-scalar-type=complex --with-fortran-bindings=0 --have-numpy=1 |
| 179 | + |
| 180 | +make all check |
| 181 | + |
| 182 | +cd - |
| 183 | +``` |
| 184 | +Finally, we install the Python package `petsc4py` which is included in the `PETSc` source distribution: |
| 185 | +```sh |
| 186 | +pip install wheel Cython numpy |
| 187 | +pip install petsc/src/binding/petsc4py |
| 188 | +``` |
| 189 | + |
| 190 | +## Uninstall |
| 191 | + |
| 192 | +- **Whichever the install mode**: |
| 193 | + ```bash |
| 194 | + pip uninstall psydac |
| 195 | + ``` |
| 196 | +- **If PETSc was installed**: |
| 197 | + ```bash |
| 198 | + pip uninstall petsc4py |
| 199 | + ``` |
| 200 | + |
| 201 | +The non-Python dependencies can be uninstalled manually using the package manager. |
| 202 | +In the case of PETSc, it is sufficient to remove the cloned source directory given that the installation has been performed locally. |
0 commit comments