Compiling PIPS-IPM++

Note that at this point we support installation on Linux systems only.

Dependencies

PIPS-IPM++ requires one or several solvers for linear equations systems. Currently supported are HSL MA57, MUMPS, Pardiso from Intel MKL, and Panua-Pardiso. Best performance can be expected with Panua-Pardiso. PIPS-IPM++ development current focuses on using HSL MA57. Pardiso from Intel MKL and MUMPS are available for free (please check the license conditions), while MA57 is free for academic users only.

Building PIPS-IPM++ requires CMake, a C/C++ compiler, MPI (e.g., MPICH or OpenMPI) and Blas/Lapack. To read compressed GDX files, also ZLib is required. When using MA57, it is preferred to also have METIS available. In addition, git should be used to retrieve the source code of PIPS-IPM++ and its submodules GDX and GoogleTest.

Necessary and optional packages for a build of PIPS-IPM++ with MUMPS can be installed via

dnf install git cmake mpich-devel gcc gcc-c++ gcc-gfortran lapack-devel zlib-devel MUMPS-mpich-devel

on a RedHat based system, and via

apt-get install git cmake libmpich-dev gcc g++ gfortran liblapack-dev zlib1g-dev libmumps-dev pkgconf

an a Debian based system.

Retrieve source code

Check out PIPS-IPM++, including the GDX and GoogleTest submodules, via

git clone --recurse-submodules https://gitlab.com/pips-ipmpp/pips-ipmpp.git

Optional: Obtain MA57

PIPS-IPM++ can compile MA57 from source, if the source code has been provided. To do so, obtain a tarball from https://www.hsl.rl.ac.uk/catalogue/ma57.html and place it in directory ThirdPartyLibs/MA57. Then unpack the tarball, e.g., tar xzf ma57-3.10.0.tar.gz.

MA57 can make use of METIS 4 or 5 for matrix ordering. The build system will look for a METIS installation if MA57 source code has been provided. On a RedHat based system, METIS can be installed via

dnf install metis-devel

On a Debian based system, use

apt-get install libmetis-dev

Note that a METIS installation that uses 32bit integers is required. Cmake variables METIS_LIBRARY and METIS_INCLUDE_DIR can be used to point to a METIS installation in a non-default path.

Alternatively, one may use prebuild HSL libs or compile the source with the help of the COIN-OR ThirdParty-HSL project and use cmake variable MA57_LIBRARY to point the build system to the MA57 library.

Note that if PIPS-IPM++ is built without MA57 libraries, it can still load a library with MA57 at runtime.

Optional: Obtain MA27 and MC30

Similar instructions as for MA57 apply for building MA27, though in this case METIS is not used. Optionally, MC30 may be used by MA27, if available. The MA27 and MC30 interfaces of PIPS-IPM++ have not been tested for a while and may be removed in the future.

Optional: Obtain Panua-Pardiso

Obtain a license and download a library that is appropriate for your system from https://panua.ch/pardiso/. Then place the library libpardiso.so into the folder ThirdPartyLibs/PARDISO/src.

Either copy the license (in a file named pardiso.lic) into your home directory or alternatively into the directory from which PIPS-IPM++ will be run, or (recommended) set the environment variable PARDISO_LIC_PATH to the folder where the pardiso.lic file can be found (see also the PARDISO user guide).

Compile PIPS-IPM++

First, the build needs to be configured in a build directory via cmake, e.g.,

cd /path/to/pips-ipmpp
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release

If a debug version of PIPS-IPM++ should be build, use -DCMAKE_BUILD_TYPE=Debug instead.

There are 3 ways (priority as follows) to provide Blas/Lapack libraries to cmake:

1. Pass the variable MATH_LIBS with all necessary linker information for a custom Blas/Lapack installation to cmake (use -DMATH_LIBS=...).
2. Define the environment variable MKLROOT to make PIPS-IPM++ use the Intel MKL libraries. This environment variable can and should be set correctly by one of the scripts provided by Intel with each of its installations of MKL.
3. Let cmake try to find Blas and Lapack automatically in the system, e.g., by using -llapack -lblas. The cmake output shows the finally chosen Lapack/Blas libraries.

Eventually, compile PIPS-IPM++ by issuing

make

The build directory should now contain an executable called pipsipmCallbackExample. Run this executable to check whether everything seems to be working:

./pipsipmCallbackExample

In addition, executables gmschk and gmspips should be available. See PIPS-IPM++ Input: Format and Generation on how to use gmschk to generate input for gmspips and see Running PIPS-IPM++ on how to call gmspips.

Expert Compile Options

Enabling Sanitizers

Calling cmake with -DWITH_MEMORY_SANITIZER=ON enables address and undefined behavior sanitizers for the build. Likely, this should be used together with -DCMAKE_BUILD_TYPE=Debug. Note that cmake will suggest a setting for environment variable LSAN_OPTIONS, which should be used when running PIPS-IPM++ with sanitizers enabled.

The execution of PIPS-IPM++ with sanitizers enabled may fail with an illegal instruction signal for some reason or another. For instance, having address space layout randomization (ASLR) enabled on the system can be problematic. One may disable it for a call to gmspips via

setarch x86_64 -R ./gmspips ....

Or disable this security feature for the whole system via

echo 0 | sudo tee /proc/sys/kernel/randomize_va_space

Or tweak it via

sudo sysctl -w vm.mmap_rnd_bits=28

Another source of problems can be the memory interceptor of modern OpenMPI versions. One can disable this OpenMPI feature by setting environment variable

OMPI_MCA_memory=^patcher

Test Suites

PIPS-IPM++ comes with two test suites, one build on Google Test, the other on CTest. To enable these testsuites, call cmake with -DWITH_MAKETEST=ON.

The quick Google Test Suite can be called via ./PIPS-IPM/Test/IntegrationTests/pipsTest, but one may also run it through MPI, e.g., mpiexec -n 2 ./PIPS-IPM/Test/IntegrationTests/pipsTest. Pass argument VERBOSE to enable more output.

The CTest suite can be called via make test or ctest --output-on-failure -j4.