SUMMA Installation

We have successfully installed SUMMA on a number of Unix-like (*nix) operating systems, including Linux and Darwin (Mac OS X). Since we do a lot of our development on OS X, we have a separate page on how to install the necessary tools and libraries on that platform. If you do not want to deal with installing programs and libraries and just want to run SUMMA, then we also have a SUMMA release that uses Docker. Details can be found on our SUMMA using Docker page. If you plan to use Docker, then you can skip the rest of this page.

Dependencies

To compile SUMMA, you will need:

  • a Fortran compiler. We have successfully used the intel Fortran compiler (ifort, version 17.x) and the GNU Fortran compiler (gfortran, version 6 or higher), the latter of which is freely available. Since we do not use any compiler-specific extensions, you should be able to compile SUMMA with other Fortran compilers as well.

    If you do not have a Fortran compiler, you can install gfortran for free. The easiest way is to use a package manager. Note that gfortran is installed as part of the gcc compiler suite.

  • the NetCDF libraries. NetCDF or the Network Common Data Format is a set of software libraries and self-describing, machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data. They are widely used in the hydrometeorological community and eventually almost all SUMMA I/O will use NetCDF. Most *nix package managers include a NetCDF port. Note that you need to ensure that:

    • You have NetCDF version 4.x;
    • The NetCDF libraries are compiled with the same compiler as you plan to use for compiling SUMMA; and
    • You have the NetCDF Fortran library installed (libnetcdff.*) and not just the C-version.

  • the LAPACK (Linear Algebra PACKage) library provides a series of routines for linear algebra operations, including matrix solvers. How to install the library depends on your *nix variant and is not covered here. For example, on OS X you will get all the necessary LAPACK routines by installing the ATLAS software (again, this is easiest using a package manager; note that ATLAS can take many hours to build the first time when you install it).

  • the ATLAS (Automatically Tuned Linear Algebra Software) library. Note that this is required on OS X using the gfortran compiler to be able to use LAPACK. It's not clear that this is used on other *nix machines.

  • a copy of the SUMMA source code from this repo. You have a number of options:

    • If you just want to use the latest stable release of SUMMA, then simply look for the latest release;
    • If you want the latest and greatest (and potentially erroneous), download a copy of the development branch (or clone it);
    • If you may want to do SUMMA development, then fork the repo on github and start editing your own copy.

    Note that you will not be able to contribute to the main SUMMA repo directly. If you are seriously interested in contributing, spend a little time learning git. It will be useful anyway. For more information about working with the SUMMA code, please see the following documents:

Compilation

To compile SUMMA there are two methods, each of which is described in detail below. The first method uses a Makefile and is the traditional way to compile SUMMA. The second method uses CMake and enables parallelization for faster builds.

Makefile

Once you have all the above, you can compile SUMMA using the following steps for using the Makefile:

  1. Navigate to your local copy of the SUMMA directory and go to the build subdirectory;

  2. Specify a number of environment variables that are used by the build process. You will need to set the following:

    • F_MASTER : This is the parent directory of the build directory.

      Example: Given the following directory structure: ```

             summa/  
       ├── build  
       ├── ci  
       ├── COPYING  
       ├── Dockerfile  
       ├── docs  
       ├── header.license  
       ├── LICENSE.txt  
       ├── mkdocs.yml  
       ├── readme.md -> docs/index.md  
       └── utils  
       ```

      export F_MASTER=/summa

    • FC : Define the compiler family. This is only used to determine the compiler flags. If your compiler is not included, you will need to add the relevant section to the Makefile.

      Example: export FC=gfortran

    • FC_EXE : This is the actual compiler executable that is invoked.

      Example: export FC_EXE=gfortran

    • INCLUDES: This is the path to the NetCDF and LAPACK include files. This is typically /usr/include or /usr/local/include.

      Example: export INCLUDES='-I/usr/include -I/usr/local/inclde -I<other paths>

    • LIBRARIES: This is the path to the NetCDF and LAPACK libraries, typically /usr/lib. The following command will help you determine the correct paths: find / -type f \( -name "libblas*.so*" -o -name "libnetcdf*.so*" \).

      Example: export LIBRARIES='-L/usr/lib -lnetcdff -L/usr/lib/x86_64-linux-gnu -llapack -lblas'

    If you are using the bash shell, then you would set these environment variables with export FC=gfortran for example. You may need to modify the Makefile if you are using a different Fortran compiler or your setup is different. If someone wants to contribute an actual configure script that would be great.

    • If you are compiling SUMMA using packages installed through Homebrew with gfortran, then use the following entries in Part 0 of Makefile: Date updated: May-2024 FC = gfortran FC_EXE = gfortran INCLUDES = -I/opt/homebrew/Cellar/netcdf-fortran/x.x.x/include -I/opt/homebrew/Cellar/lapack/x.x.x/include LIBRARIES = -L/opt/homebrew/Cellar/netcdf-fortran/x.x.x/lib -lnetcdff -L/opt/homebrew/Cellar/lapack/x.x.x/lib -lblas -llapack

      Note: change x.x.x with the exact version number in both the INCLUDE and LIBRARIES variables. This can be done by using ls /opt/homebrew/Cellar/netcdf-fortran/ and then using tab button to find the current version installed on your machine. Do the same for lapack. Currently, the most up-to-date netcdf-fortran version is 4.6.1 and lapack is 3.12.0.

    • If you are compiling SUMMA on the Graham cluster of the Digital Research Alliance of Canada using ifort then use the following entries in Part 0 of Makefile: Date updated:July-2020 FC = ifort FC_EXE = /cvmfs/restricted.computecanada.ca/easybuild/software/2017/Core/ifort/2019.3.199/compilers_and_libraries_2019.3.199/linux/bin/intel64/ifort INCLUDES = -I/cvmfs/soft.computecanada.ca/easybuild/software/2017/avx/Compiler/intel2016.4/netcdf-fortran/4.4.4/include LIBRARIES = -L/cvmfs/soft.computecanada.ca/easybuild/software/2017/avx/Compiler/intel2016.4/netcdf-fortran/4.4.4/lib -lnetcdff -mkl

      Note: Before compiling, load the most recent intel module. Check the available versions with: module spider intel. Then load the latest version: module load intel/2019.3. Lapack and blas libraries are loaded with library argument -mkl.

  3. Check that all variables in the Makefile are set correctly by typing make check. Inspect the variables and make sure that they make sense. If not, modify the Makefile further.

  4. Type make (if you are in the build directory). If all goes well, this will build SUMMA and move the executable summa.exe to the bin directory. You may get some warnings (depending on your compiler settings), but you should not get any errors;

  5. Pay attention to the make output. You may need to set some environment variables (LD_LIBRARY_PATH in particular) to support dynamic linking;

  6. If the code compiles successfully, then the last line of output from the make process will tell you where the SUMMA executable is installed (it goes into summa/bin). Run summa.exe in that directory (you may need to provide the full path). If all goes well, you should get a usage message that looks something like (depending on the SUMMA version):

    Usage: summa.exe -m master_file [-s fileSuffix] [-g startGRU countGRU] [-h iHRU] [-r freqRestart] [-p freqProgress] [-c]
     summa.exe          summa executable

    Running options:
     -m --master        Define path/name of master file (required)
     -s --suffix        Add fileSuffix to the output files
     -g --gru           Run a subset of countGRU GRUs starting from index startGRU
     -h --hru           Run a single HRU with index of iHRU
     -r --restart       Define frequency [y,m,d,never] to write restart files
     -p --progress      Define frequency [m,d,h,never] to print progress
     -v --version       Display version information of the current built

If you get this far then SUMMA is installed correctly and functional.

CMake

Most users will be able to compile SUMMA using the following steps, even on Digital Alliance of Canada machines (loaded modules usually automatically set the necessary CMake variables):

cd summa/build/cmake
./compile_script.sh

If the compilation is successful, you will see the help output from running summa.exe in summa/bin/ as shown in the Makefile instructions above.

If you encounter issues with dependencies, it is most likely because they are installed in a non-standard location. If this is the case, you can set the CMAKE_PREFIX_PATH variable in the compile_script.sh script to the location of the dependencies. For example, if the NetCDF libraries are installed in /home/some_user/netcdf, you would modify the compile_script.sh script as follows:

#!/bin/bash

export CMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH:/home/some_user/netcdf"

cmake -B cmake_build -S ../. 
cmake --build cmake_build --target all -j

Continue reading SUMMA configuration to learn more about how to configure SUMMA for your application. We strongly recommend that you get the test applications to help you get started.