Skip to content

Building and Testing MAPL as a standalone

Jump to bottom
Ben Auer edited this page Jul 1, 2022 · 40 revisions

Introduction

MAPL can be built by itself as long as you have the dependencies. If you are inside the NASA HPC ecosystem on NAS or NCCS computer clusters it is really simple since the SI Team maintains the dependencies needed.

Building at NAS or NCCS

If you have an account as NAS or NCCS it is really, really simple to build MAPL (we promise) since we maintain all the dependencies. There is no need to read beyond this section. You will need "mepo" in your path, ask the SI team if you don't know what that means. Once you have mepo in your path, it is as simple as this.

git clone [email protected]:GEOS-ESM/MAPL.git
cd MAPL
mepo clone
source ESMA_env/g5_modules
mkdir build
cd build
cmake ../ -DBASEDIR=$BASEDIR/Linux -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install
make -j4 install

Once you do this, you will have an install directory with libraries and executables created by MAPL. The instructions above will build the "Release" build which enables optimization flags and turns off some error checking like going past array bounds. We highly recommend for any development work to use the "Debug" built which turns off optimization flags and turns on error checking such as making sure arrays do not go out of bounds and uninitialized variables will be set to signaling NANs. To turn on the "Debug" built you simple replace -DCMAKE_BUILD_TYPE=Release with -DCMAKE_BUILD_TYPE=Debug in the cmake command when you build. Note you can even have multiple installations. Just build twice and point to a different installation directory in each!

As a side note, if you can do the above you can build the full GEOSgcm or GEOSadas in the same manner, you just clone a different repo to start. We would recommend that you do that rather than use the parallel_build scripts in those repos. As you can see, building by hand is not hard and you will actually understand what is going on!

Building Outside of NASA HPC systems

If you are not inside a NASA HPC system, it is more exciting, as you will have to build the dependencies yourself. If you are on a Linux system with a C and Fortran compiler with MPI, you could try build our GMAO baselibs. Assuming you have the compiler/mpi stack, in theory baselibs should build easily and that is detailed below. On macOS, you can also build baselibs but it may be a little more exciting.

Dependencies

MAPL has the following dependencies (really the easiest way to get the dependencies is to build our Baselibs):

  • MPI with Fortran interfaces
  • ESMF
    • NetCDF
      • HDF
  • NetCDF-Fortran
    • NetCDF
      • HDF
  • FLAP
  • ESMA_cmake
  • ecbuild
  • gFTL (support for generic programming, part of GFE)
  • gFTL-shared (common containers, part of GFE)
  • YafYAML (Fortran YAML library, part of GFE)

Testing

  • pFUnit (Unit testing framework)
    • fArgParse (command line processing for testing framework)
    • gFTL
    • gFTL-shared

Note 1: The one dependency that could be eliminated here is FLAP. It is only used in drivers for MAPL, and not in the unit tests. We also expect to replace FLAP with fArgParse in the future, which adds no complexity as it is already being used by the testing framework.

Note 2: We are assuming that MPI is available in the desired computing environment and offer no instructions for building and installing MPI.

Baselibs All-in-One

Baselibs can be obtained here: https://github.com/GEOS-ESM/ESMA-Baselibs

Before building make sure you have these environment variables set for you chosen compilers:

Compilers:

$ export FC=...
$ export CC=...
$ export CXX=...

Then, be certain that the MPI wrappers (mpif90/mpifort/..., mpicc, mpicxx) are in your path.

Building baselibs with GNUmake

In theory if the above is true you can build baselibs like so with GNUmake. For the sake of this example I will assume you want to build baselibs v6.2.13 and note that I am assuming it is Intel MPI you are using if you have a different flavour of MPI you will need specify that.

mkdir ESMA-Baselibs-6.2.13
cd ESMA-Baselibs-6.2.13
git clone --recurse-submodules -b v6.2.13 https://github.com/GEOS-ESM/ESMA-Baselibs.git src
cd src
make download
make -j30 install ESMF_COMM=intelmpi BUILD=ESSENTIALS CONFIG_SETUP=ifort_2021.3.0-intelmpi_2021.3.0

Once baselibs is built, you would need to point the g5_modules in your MAPL clone to the correct baselibs and make sure any modules you need are loaded on your system. From there you would build as detailed in the beginning of the document.

Anything beyond this point is not for the faint of heart..., it's really much easier if you just build our baselibs. You have been warned and the following instructions have not been tested or may be incomplete.

Building with CMAKE

In theory someone put here you can build baselibs with CMAKE, but I have not tried that. YMMV To build a needed-libraries-only version of Baselibs, you can do the following:

$ git clone https://github.com/mathomp4/ESMA-Baselibs-MAPL.git Baselibs
$ cd Baselibs
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_Fortran_COMPILER=<...> -DCMAKE_CC_COMPILER=<...> -DCMAKE_CXX_COMPILER=<...>
           -DMPI_Fortran_COMPILER=<...> -DMPI_C_COMPILER=<...> -DMPI_CXX_COMPILER=<...>
$ make -jN install

This will build everything including ESMF (branch: master). The system will attempt to autodetect ESMF_COMPILER and ESMF_COMM, though you can pass them in. The system will also try and create an installation directory parallel to build with a name built from ESMF_COMM and ESMF_COMPILER, though this can be overridden with -DCMAKE_INSTALL_PREFIX=<path>.

Note 1: The cmake step above must be done on a machine with internet access as it downloads/clones the needed libraries.

Note 2: On many systems, the paths to the compilers and MPI wrappers will be automatically determined by the environment.

Build MAPL

  1. Clone MAPL 
    $ git clone -b develop [email protected]:GEOS-ESM/MAPL.git
  2. Create a build directory 
    $ mkdir <build-dir>
$ cd <build-dir>
  3. Configure cmake 
    $ cmake -DCMAKE_PREFIX_PATH=<install-dir> -DESMF= -DNETCDF=
  4. Build and run unit tests 
    $ make -j 
$ make -j tests
$ ctest -V

Note 1: These changes currently only work on the develop branch of MAPL. Soon the master branch will be updated.

Note 2: The cmake step above must be done on a machine with internet access as it downloads/clones the needed libraries.

Note 3: The make tests step must be done after the regular make step. This is because some dependencies are not correctly captured in the pFUnit macro used to define the tests.

Clone this wiki locally