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.,

  > 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.,

  > MPICC=mpiicc pip install --no-binary :all: mpi4py
  

For example, one can install these two packages as follows:

> 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

     > python -m venv /path/to/new/virtual/environment
     

  2. Activate the virtual environment

     > source /path/to/new/virtual/environment/bin/activate
     

  3. (Optional) update your virtual environment using pip

     > pip install -U setuptools pip wheel
     

     or using easy_install

     > easy_install -U setuptools pip wheel
     

     —

     NOTES

     • CMake is now available as a wheel and can be installed using pip

       > 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:

   {
        "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

   > env SETUP_FILE=path/to/setup_file pip install . --verbose
   

   For installation in development mode it is recommended to use

   > 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:

   > 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:

   > 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.

   > 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:

  export KMP_INIT_AT_FORK=false
  export MKL_THREADING_LAYER=TBB