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
• Github Actions 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+).
• BLAS: for multiplying dense matrices, if they emerge in the calculation.

The following optional software can greatly enhance the NTPoly experience:

• 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)

# Library Files
set(TOOLCHAIN_LIBS "-lblas")

# Release suggestions
set(CXX_TOOLCHAINFLAGS_RELEASE "-O3 -openmp -lgomp -fPIC")
set(F_TOOLCHAINFLAGS_RELEASE "-O3 -cpp -openmp -fPIC")

# Debug suggestions
set(CXX_TOOLCHAINFLAGS_DEBUG "-O0 -openmp -fPIC")
set(F_TOOLCHAINFLAGS_DEBUG "-O0 -cpp -fPIC")

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. It is necessary to also pass the -fPIC flag because we will link with python using shared libraries.

MacBook Pro with clang and gfortran

Here is the mac versions

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

# Library Files
set(TOOLCHAIN_LIBS "-framework Accelerate -lgomp")

# Release Suggestions
set(CXX_TOOLCHAINFLAGS_RELEASE "-O3 -openmp")
set(F_TOOLCHAINFLAGS_RELEASE "-O3 -cpp -fopenmp")

# Debug suggestions
set(CXX_TOOLCHAINFLAGS_DEBUG "-O0")
set(F_TOOLCHAINFLAGS_DEBUG
  "-fbounds-check -O0 -fexternal-blas -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. Thus you need to manually specify the executable of python, and then I have a CMake script hat determines the parameters.

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(CMAKE_Fortran_MODDIR_FLAG "-M")

set(TOOLCHAIN_LIBS "")

# Release Suggestions
set(CXX_TOOLCHAINFLAGS_RELEASE
    "-Kfast,-Kparallel,openmp,optmsg=2 --linkfortran")
set(F_TOOLCHAINFLAGS_RELEASE "-Kfast,-Kparallel,openmp,optmsg=2 -Cpp")

# Debug Suggestions
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.

Github Actions Build

As a last resort of compilation help, I think the Github actions build can be instructive. You can read the .github/workflows/ci.yml file to see in detail what steps are performed to compile NTPoly from scratch on Ubuntu.

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