PIPS-IPM++ Solver and Tools
a parallel interior-point method for doubly bordered block diagonal linear programs
Compiling PIPS-IPM++

Note that at this point we support installation on Linux systems only. We also got it running on one macOS system with OpenMPI, but do not regularly test on this platform.

Dependencies

PIPS-IPM++ requires one or several solvers for linear equations systems. Currently supported are HSL MA57, MUMPS, and Panua-Pardiso. Best performance can be expected with Panua-Pardiso. PIPS-IPM++ development current focuses on using HSL MA57. MUMPS is 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 (see also option HSLLIB).

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.

On macOS, it may be necessary to specify additional flags to have cmake find an OpenMP installation, e.g.,

-DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp -I/path/to/openmp/include"
-DOpenMP_CXX_LIB_NAMES=omp
-DOpenMP_omp_LIBRARY="/path/to/openmp/lib/libomp.a"

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.

Optionally, the PIPS-IPM++ library, C++ API header files, and gmschk and gmspips executables can be installed by issuing

make install

The will install into the directory specified by cmake option CMAKE_INSTALL_PREFIX, or /usr/local if not set. Having environment variable DESTDIR set when calling make install will prefix the install prefix by the DESTDIR.

The callback example PIPS-IPM/Drivers/CallbackExample/callbackExample.cpp can be compiled using the installed header files and library only.

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.