Difference between revisions of "How to Build GridPACK"

Revision as of 15:41, 3 April 2018

Overview

This section will provide a brief overview of how to configure and build GridPACK. More detail can be found by looking at builds of GridPACK on specific systems by following the links in the Examples section at the bottom of this page. These provide complete scripts for building GridPACK and its associated libraries. We strongly recommend that you find an example that is similar to the system you are planning on building on and examine the scripts for that system before attempting to build GridPACK. Users will need to make sure that they have a compiler on their system (we have used GNU and Intel compilers to build GridPACK), an MPI library and CMake (version 2.8.8 or greater).

If new to building GridPACK, it's usually best to start from a working example. Below, are detailed descriptions of building GridPACK on some specific platforms that contain scripts for building GridPACK and its associated libraries.

• Mac OS X (Yosemite) with MacPorts
• Red Hat Enterprise Linux 5
• CentOS 6
• Ubuntu Linux
• Debian Linux
• PNNL PIC Cluster (Linux cluster with Infiniband)
• Native Windows Port

Prerequisite Software

Currently, GridPACK builds on Linux/UNIX sytems. Other operating systems are not supported at this time.

Building GridPACK is relatively complicated, primarily because it depends on several third-party software packages. These need to be built and installed prior to building GridPACK. Refer to the list of required software for what is needed. Detailed information on building these packages on different platforms is available on the links listed below for building GridPACK on different platforms.

GridPACK requires the MPI, Global Arrays, Boost, PETSc and Parmetis libraries to build. The Parmetis libraries can usually be downloaded and built when configuring and building PETSc and this is the preferred way of obtaining Parmetis. If necessary, Parmetis can be downloaded and built separately.

Some version of MPI is already available on most clusters, but users may need to build their own copy of MPI if running on a workstation. Several versions of MPI, including OpenMPI, MPICH and MVAPICH are available for free. There are also commercial implementations, such as Intel MPI, that can also be used.

In general, it is a good idea to build Boost, Global Arrays and PETSc yourself. This guarantees that all libraries are using the same compiler and version of MPI. Compilers that have been used to build GridPACK include the GNU and Intel compilers.

Configuration

Configuration is the most complicated part of the process. CMake is used to configure GridPACK for building. CMake is usually available on most Linux systems but older versions of Linux may have a version of Cmake that is too old to build GridPACK. GridPACK requires version 2.8.8 or newer. If the installed version of CMake is too old, users will need to download CMake and build it themselves. The version of CMake can be found by typing

 cmake -version

The configure process insures that required software is available and usable. CMake expects to configure GridPACK in a directory other than the one containing the source code. Typically, one makes an empty directory, called build, say, and executes

 cmake [options] gridpack/source/directory

where options are used to locate required software and set compiler options. The shell script example_configuration.sh shows some examples of configuration options for a few systems. If you don't get the configure right the first time, then you should make sure that you get rid of all the files that CMake created when you tried configuring previously. This can be done by typing

 rm -rf CMake*

in your build directory. This will remove all CMake-related configuration files from your build directory so that the new build is not corrupted by the previous build. If you are using a script to configure GridPACK, then you should include this line at the start of the script.

To guarantee that CMake finds the correct C and C++ compilers, you should define the environment variables CC and CXX (if you are trying to build the Fortran interface, you should define FC and F77 as well). In addition, it may also be necessary to define CFLAGS = "-pthread" etc. depending on how some of the other libraries were built. Using C-shell, the environment variables are

 setenv CC gcc
 setenv CFLAGS "-pthread"
 setenv CXX g++
 setenv CXXFLAGS "-pthread"
 setenv FC gfortran
 setenv FCFLAGS "-pthread"
 setenv F77 gfortran
 setenv F77FLAGS "-pthread"

A complete configuration line for GridPACK is

 cmake -Wdev \
     -D BOOST_ROOT:STRING='$HOME/software_new/boost_1_55_0' \
     -D PETSC_DIR:STRING='$HOME/software_new/petsc-3.6.0' \
     -D PETSC_ARCH:STRING='linux-openmpi-gnu-cxx' \
     -D PARMETIS_DIR:STRING= \
       '$HOME/software_new/petsc-3.6.0/linux-openmpi-gnu-cxx/lib' \
     -D GA_DIR:STRING='$HOME/software_new/ga-5-4-ib' \
     -D USE_PROGRESS_RANKS:BOOL=FALSE \
     -D GA_EXTRA_LIBS='-lrt -libverbs' \
     -D MPI_CXX_COMPILER:STRING='mpicxx' \
     -D MPI_C_COMPILER:STRING='mpicc' \
     -D MPIEXEC:STRING='mpiexec' \
     -D CMAKE_INSTALL_PREFIX:PATH='$GRIDPACK/src/build/install' \
     -D CMAKE_BUILD_TYPE:STRING='RELWITHDEBINFO' \
     -D MPIEXEC_MAX_NUMPROCS:STRING="2" \
     -D CMAKE_VERBOSE_MAKEFILE:STRING=TRUE \
     ..

This example assumes that the build directory is immediately below the GRIDPACK/src directory. More information on the CMake options is available on the required software page as well as the GridPACK overview document (see the section on configuring and building GridPACK). Additional examples can also be found in the pages describing builds on different platforms.

Building

Once configured, GridPACK is built with

 make

which will take some time. (The make command should be available by default on most Linux platforms.) If building on a multi-core system, building can go faster if multiple cores are use, e.g.,

 make -j 8

will use 8 simultaneous processes to build GridPACK. It is possible that you may run into problems building with multiple cores since some dependencies may get out of order. If the build stops, then try continuing using only 1 core.

Running Tests

After a successful build, GridPACK unit tests can be run with

 make test

which will produce a list of tests and whether they passed or failed.