Compilation Help

Contents

• Overview
• Dependencies
• Toolchain Examples
  • Linux Cluster With Intel Compilers
  • MacBook Pro with clang and gfortran
  • The K Computer
• Linking Your Own Code with NTPoly
  • Linking Fortran Code
  • Linking C++ Code
  • Linking Python Code
  • Linking Using CMake
• Travis CI Build

Overview

On this page we go into detail about the compilation procedure for NTPoly.

Dependencies

Building NTPoly requires the following software:

• A Fortran Compiler.
• An MPI Installation (MPI-3 Standard+).
• CMake (Version 3.2+).

The following optional software can greatly enhance the NTPoly experience:

• BLAS: for multiplying dense matrices, if they emerge in the calculation.
• A C++ Compiler for building C++ bindings.
• Doxygen: for building documentation.
• Python (Version 2.7+): for testing.
• MPI4PY: for testing.
• SciPy: for testing.
• NumPy: for testing.
• SWIG (Version 3.0+): for building the Python bindings.

CMake is used for the build system. SWIG is used to expose an interface to languages other than Fortran, C, and C++. Python is used for testing NTPoly. SWIG exposesis required to run the python tests, so it is definitely encouraged.

Toolchain Examples

Here we will go into detail about building for a few sample systems.

Linux Cluster With Intel Compilers

Our group maintains a cluster that uses the intel compilers. Here is a look at the configuration options.

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_Fortran_COMPILER mpiifort)
set(CMAKE_C_COMPILER mpiicc)
set(CMAKE_CXX_COMPILER mpiicpc)

set(CXX_TOOLCHAINFLAGS_RELEASE "-O3 -qopenmp -lgomp -fPIC")
set(F_TOOLCHAINFLAGS_RELEASE "-O3 -fpp -qopenmp -fPIC")
set(CXX_TOOLCHAINFLAGS_DEBUG "-O0 -qopenmp -lgomp -fPIC")
set(F_TOOLCHAINFLAGS_DEBUG "-check bounds -O0 -fpp -qopenmp -fPIC -DPURE=")

Fortunately, in this case things aren't so difficult. We specify that it's a linux machine. We specify the MPI wrappers for C, C++, and Fortran. After the compilers are set, we set the compiler options. Here we have some debugging settings like -check bounds and -O0. -fpp is needed to use the Fortran preprocessor, and -qopenmp for openmp parallelization.

MacBook Pro with clang and gfortran

This isn't pretty. Here we go.

set(CMAKE_SYSTEM_NAME Darwin)
set(CMAKE_C_COMPILER mpicc)
set(CMAKE_Fortran_COMPILER mpif90)
set(CMAKE_CXX_COMPILER mpicxx)

set(PYTHON_EXECUTABLE python2)
execute_process(
COMMAND ${PYTHON_EXECUTABLE} -c
"
from distutils.sysconfig import get_python_lib
path=get_python_lib(standard_lib=True)+\"/../../Python\"
print(path)"
OUTPUT_VARIABLE PYTHON_LIBRARIES OUTPUT_STRIP_TRAILING_WHITESPACE)

set(CXX_TOOLCHAINFLAGS_RELEASE "-O3 -openmp -framework Accelerate -lgomp")
set(F_TOOLCHAINFLAGS_RELEASE "-O3 -cpp -fopenmp")
set(CXX_TOOLCHAINFLAGS_DEBUG "-O0 -framework Accelerate")
set(F_TOOLCHAINFLAGS_DEBUG
    "-fbounds-check -O0 -fexternal-blas -framework Accelerate -cpp -Wall -DPURE=")

Unfortunately, the flavor of python that comes with the Mac doesn't have all the features we want. The solution is to install a newer version using the brew package manager. However, CMake gets very confused by all these versions of python sitting around, so we have to manually specify a lot. Here we run a small script using your python executable to hunt down those parameters.

The flags are similar to the Intel case.

The K Computer

Now for the K computer.

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_C_COMPILER mpifccpx)
set(CMAKE_Fortran_COMPILER mpifrtpx)
set(CMAKE_CXX_COMPILER mpiFCCpx)
set(CXX_TOOLCHAINFLAGS_RELEASE
    "-Kfast,-Kparallel,openmp,optmsg=2 --linkfortran")
set(F_TOOLCHAINFLAGS_RELEASE "-Kfast,-Kparallel,openmp,optmsg=2 -Cpp")
set(CXX_TOOLCHAINFLAGS_DEBUG "--linkfortran")
set(F_TOOLCHAINFLAGS_DEBUG "-Cpp")

The compiler wrappers are supplied by Fujitsu. In this case, we show optimized flags such as -Kfast. -Cpp is for the preprocessor, and --linkfortran is necessary to call Fortran from C++. I had to install my own version of python locally.

Linking Your Own Code with NTPoly

Most of the linking details are hidden by CMake, so here we will explicitly discuss how to manually link your code with NTPoly. These details are also discussed in the ReadMe files in the Examples directory.

Linking Fortran Code

Linking against a Fortran code is the simplest case. After NTPoly has been compiled, the compiled module files are stored in Build/include, and the compiled object files are stored in a library in Build/lib. Thus, you should add the include line -I/path/to/Build/include and the link directory line -L/path/to/Build/lib. The Fortran library is libNTPoly.a, so link against it with -lNTPoly. NTPoly also requires openmp, so be sure to use the appropriate compiler flags.

Linking C++ Code

For a C++ code, you need both a C++ and Fortran compilers. First, compile your code to object files using the C++ compiler. The necessary header files can be included with -I/path/to/Source/CPlusPlus -I/path/to/Source/C.

Next, you need to link your code against NTPoly. To link, we recommend using a Fortrancompiler. The library files are all located in /path/to/Build/lib , and you need to link against all the library files in that directory. The following link line should work -L/path/to/Build/lib -lNTPolyCPP -lNTPolyWrapper -lNTPoly.

Since we are linking C++ code with a Fortran compiler, the basic C++ libraries need to be manually linked. For gfortran -lstdc++ should suffice. For the Intel compiler, you need to use -cxxlib -nofor_main.

As with Fortran code, openmp is a requirement, so be sure to pass the appropriate compiler flags.

Linking Python Code

The only necessary step for linking your python code is to set the environment variable PYTHONPATH to include /path/to/Build/python.

If you encounter difficulties with python, check to make sure there aren't multiple versions of python on your computer. Sometimes SWIG will generate python code that is compatible with the wrong version. You can look at the MacBook pro compilation section of this page to learn how to specify which python version NTPoly is linked against.

Linking Using CMake

It is also possible to link against NTPoly from a cmake based project using the find_package feature. The details of this kind of linking are provided in the CMakeLinkage example.

Travis CI Build

As a last resort of compilation help, I think the Travis CI build can be instructive. You can read the .travis.yml file to see in detail what steps are performed to compile NTPoly from scratch on Ubuntu Trusty Tahr.

Using aptitude, we install gfortran, the python development environment, doxygen, and cmake. Depending on your version of Linux, you might also be able to install openmpi and swig using aptitude, but we install from source because we need to use newer versions than are in the Trusty Tahr repositories.

We also install scipy, numpy, and mpi4py using pip. From there, we can follow the basic installation instructions using the Linux.cmake toolchain file.