.. _installation: Installation ============ **GreenALM** is installed as a Python package using either *setup.py* or *pip* (preferred option). Although one can provide *pip* with a list of dependencies (option `-r requirements.txt`) it is recommended to install most of the required packages before the installation of GreenALM. Dependencies ************ * cmake >= 3.15 * python >= 3.7 * numpy >=1.16.0 <=1.19.8 * scipy * f90wrap >= 0.2.1 \* * LAPACK (preferably MKL) * mpi4py (only for the MPI-enabled build) \* Supported compilers: * ifort, icc >= 19.1 * gfortran, gcc >= 8.x MPI library: * Any library that fully supports MPI 3.0 standard. * Fortran 2008 bindings (`mpi_f08`) must be compiled with the same compiler as the one used for the **GreenALM** library. Current version of the package was tested only with IntelMPI and OpenMPI. **\*Important note**: Packages *f90wrap* and *mpi4py* are source distributions, which must be built consistently with the whole **GreenALM** package. * *f90wrap*: must be built with the same version of *numpy* as the one used in **GreenALM**. It might also be necessary to specify the Fortran compiler by setting variable `F90`, e.g., .. code-block:: console > F90=ifort pip install --no-binary :all: f90wrap In some cases, it seems to be necessary that *f90wrap* is built with the same Fortran compiler as the one used for *numpy*. * *mpi4py*: must be built with the same MPI library as the one used in **GreenALM** The compiler (MPI wrapper) is specified by the variable `MPICC`, e.g., .. code-block:: console > MPICC=mpiicc pip install --no-binary :all: mpi4py For example, one can install these two packages as follows: .. code-block:: console > env MPICC=path/to/mpi_c_compiler F90=path/to/fortran_compiler pip install -r requirements.txt where *requirements.txt* file can be replaced by *requirements-dev.txt* adjusted for development purposes. Python environments ******************* The recommended way of installing the **GreenALM** package is to use either native virtual environments of Python or anaconda environments. * Installation using a virtual environment 1. Set up a virtual environment by executing the *venv* command .. code-block:: console > python -m venv /path/to/new/virtual/environment 2. Activate the virtual environment .. code-block:: console > source /path/to/new/virtual/environment/bin/activate 3. (Optional) update your virtual environment using *pip* .. code-block:: console > pip install -U setuptools pip wheel or using *easy_install* .. code-block:: console > easy_install -U setuptools pip wheel --- **NOTES** - *CMake* is now available as a wheel and can be installed using *pip* .. code-block:: console > pip install cmake * Installation using an Anaconda environment - Installation using Anaconda environment is similar to that above but often problems arise because variables CC, FC, LDFLAGS, etc. are modified by Anaconda, which might lead to build failures. Installation into the virtual environment ***************************************** After all of the required packages are installed and the environment is updated: 1. Navigate to the folder where **GreenALM** was downloaded and create a setup file *SETUP_FILE*, which is a JSON file containing CMake-style definitions. The following options can be defined there: - `CMAKE`: path to cmake executable with version >= 3.16.0 - `CMAKE_C_COMPILER`: path to the C compiler - `CMAKE_Fortran_COMPILER`: path to the Fortan compiler - `WITH_MPI`: \[boolean, default: *True*\] whether MPI should be enabled - `WITH_MPI_DEBUG`: \[boolean, default: *False*\] needed for MPI debugging - `BUILD_TESTING`: \[boolean, default: *True*\] whether to build unit tests - `CMAKE_BUILD_TYPE`: Release/Debug - `LAPACK_LIBRARY`: path to LAPACK library - `BLAS_LIBRARY`: \[optional\] path to BLAS library - `WITH_MKL_SEARCH`: \[boolean, optional\] whether to allow CMake to search for MKL libraries An example of the setup file: .. code-block:: json { "CMAKE": "/home/fmoitzi/cmake_install/bin/cmake", "CMAKE_C_COMPILER": "gcc-8", "CMAKE_Fortran_COMPILER": "mpif90.openmpi", "WITH_MPI": true, "BUILD_TESTING": true, "CMAKE_BUILD_TYPE": "Debug", "LAPACK_LIBRARY": "/home/fmoitzi/intel/oneapi/mkl/2021.1.1/lib/intel64/libmkl_rt.so.1", "Fortran_FLAGS": [ "-O2", "-g", "-fcheck=all", "-Wextra", "-fbacktrace" ], "PARALLEL_MAKE": true } 2. Install the package using *pip* .. code-block:: console > env SETUP_FILE=path/to/setup_file pip install . --verbose For installation in development mode it is recommended to use .. code-block:: console > env SETUP_FILE=path/to/setup_file pip install -e . --verbose This will create a link to the Python source files inside a *site_packages* directory of your current virtual environment. It is also possible to control whether *cmake* or *make* should be executed before installation: .. code-block:: console > env SETUP_FILE=path/to/setup_file RUN_CMAKE=False RUN_BUILD=False pip install -e . --verbose - `RUN_CMAKE` is set to *True* by default. If *False* CMake will not be invoked. - `RUN_BUILD` is set to *True* by default. If *False* CMake will not run the build. --- **NOTE** Old *pip* versions copy source files to a temporary directory before the build. To avoid this unnecessary step one can specify `--use-feature=in-tree-build`. The build directory can be modified using option `-b`: .. code-block:: console > env SETUP_FILE=path/to/setup_file pip install -e path/to/build_directory . --verbose --- 3. Configure tests Python and Fortran tests can be run with *pytest*. Fortran tests can also be executed using *ctest* which must be called inside the build directory. Configuration file *pytest.ini* allows one to specify which Fortran tests must be discovered by *pytest*. .. code-block:: console > pytest src/test/python > pytest build/*/tests --- **NOTE** Currently MPI tests cannot be executed using *pytest* because of an unpleasant interaction between `mpi4py` and `subprocess`. One has to run these tests using *ctest*. --- Known installation issues ************************* * Depending on the environment setup *f2py* might fail to compile the wrapper because of the missing `-shared` flag. It can be passed to the build system using environment variable `LDFLAGS`. * Another possible reason for the failure of *f2py* is the mismatch in versions of `numpy` currently installed and the one used to build `f90wrap`. * If the code was build with MKL and multiple tests are failing, this might be related to a known issue of Intel OpenMP used inside MKL. As a workaround one could try to set either of the two variables: .. code-block:: console export KMP_INIT_AT_FORK=false export MKL_THREADING_LAYER=TBB