MAiNGO
Installing and Executing MAiNGO

Obtaining MAiNGO

In order to obtain MAiNGO, we strongly recommend using Git (Git Bash on Windows). It is possible to download MAiNGO as a .zip folder, but we strongly recommend to use Git and follow the given instructions (in particular because we use submodules for dependencies, which need to be downloaded separately when not using Git). First you need to clone the MAiNGO repository. This is done by

git clone https://git.rwth-aachen.de/avt.svt/public/maingo.git <directory>

where <directory> is the name of the directory where you can find all MAiNGO files after cloning (default name is maingo). After the cloning is done, simply navigate to the directory. In the cloned MAiNGO directory execute

git submodule init

If nothing happens, you are not in the cloned MAiNGO directory and have to navigate to there first. For Windows users, we recommend the usage of HTTPS protocols for Git and SSH protocols for Linux and Mac OS users to avoid multiple username and password inputs. If you want to switch from HTTPS to SSH, simply execute the shell script ./switchToSsh or ./switchToHttps for switchting from SSH to HTTPS and back after executing the git submodule init command. For more info on SSH keys, see the Git documentation on SSH authentication which can be found under Help -> SSH authentication in your GitLab. If you are having HTTPS authentication problems on Windows, please make sure that your cedential manager has the correct settings. The Windows credential manager can be found at Control Panel -> User Accounts -> Manage your credentials.

In order to proceed and update all submodules of MAiNGO, execute

git submodule update -j 1

in the MAiNGO directory. You can determine whether the above worked properly by checking if each dependency folder in the dep/ folder is non-empty. In the case that the above DID NOT work properly, execute the following in the MAiNGO directory

git submodule foreach git checkout master
git submodule foreach git pull

A note for user more familiar with Git: the git submodule update is exectued without the –recursive option. This avoids instantiating any indirect dependencies; in the repository design of MAiNGO, all dependencies (including indirect ones) are present in the dep folder. It is also executed using only one process -j 1 to avoid input failures.

Updating MAiNGO

If you want to update to the latest MAiNGO version, use the following git commands

git pull
git submodule update

If you changed any of the source files in MAiNGO or any dependency found in the dep/ folder, you should restore the original state of MAiNGO by first saving a copy of the files you changed (or using git stash) and then executing

git checkout .

in the MAiNGO repository and/or in any dependency repository you edited. Then, update the MAiNGO repository with the pull and submodule update commands. Finally, you can replace the files of interest by your saved copies (or retrieve them via git stash pop).

Required Software

Building MAiNGO requires the following non-standard programs that are not in the Git repository:

  • CMake 3.8 or later
  • Visual Studio 2017 (Windows only)
  • A Fortran Compiler (Linux and Mac OS)

CPLEX 12.8 and Knitro 11.1 are optional subsolvers that are not required for using MAiNGO, but it is strongly recommended to use CPLEX to achieve best computational results. CMake will automatically detect whether you have CPLEX/Knitro or not. If you installed CPLEX or Knitro in a non-default path, it may be neccessary to adapt the paths in the corresponding CMakeLists.txt files at dep/knitro and dep/cplex. A note on CPLEX versions: We experienced problems trying to include CPLEX 12.7 into MAiNGO, since there appears to be a bug in the API related to scaling of variables and equations when modifying a model causing failure of MAiNGO for many problems. CPLEX 12.5 mostly worked for us, but did give a couple of weird bugs where problems were not updated properly. When using CPLEX 12.5, you need to go back to Visual Studio 2010 as well (this may result in multiple changes in the CMakeLists.txt files).

All other third-party software that MAiNGO depends on comes with the MAiNGO Git. Unless you feel the need to modify the folder structure or switch to other versions (in which case we would appreciate you contacting the MAiNGO team as well), there is nothing you need to do.

Generating and Compiling the Project

MAiNGO uses modern target-oriented cmake commands. The CMakeLists.txt in the root directory is the sole entry point both for building MAiNGO as a standalone solver or including it into your project.

Windows

On Windows, only Microsoft Visual C++ 2017 is supported. We supply pre-compiled versions for all Fortran libraries, so no Fortran compiler (or runtime) should be needed.

First, start CMake and navigate or type the path to your MAiNGO directory (this is the one where the Readme.md is) and select your build directory.

CMakeHead.PNG

Next, use the Configure button to choose Visual Studio 15 2017 Win64 as generator (or Visual Studio 15 2017 as generator and x64 as optional platform for generator in the newer versions of CMake). Make sure that you use default native compilers. Press Finish and then Generate the project.

CMakeGenerator.PNG

After the generation is complete, start Visual Studio 15 2017 and make sure you compile MAiNGO in Release mode to get the best performance.

VS_Release.PNG

Linux and Mac OS

On Linux and Mac OS, the following compiler configurations have been tested:

  • gcc 6.3, 8.2, and 9.2 (Linux and MacOS)
  • Intel C++ and Fortran Compiler 16.0.8, 17.0.7, 18.0.3, and 19.0.1 (Linux) - only works if building without the parser (MAiNGO_build_parser=false, cf. below) because of missing C++17 features in Intel compilers
  • Clang 7.0, 8.0, 9.0 (Linux) and clang-1001.0.46.4 (MacOS) with gfortran - only works if not using CPLEX (CPLEX seems to be incompatible with Clang)

On Linux, the Fortran parts are usually not an issue thanks to gcc/gfortran. On Mac OS, you may need to install gfortran separately. If you use gfortran and get a linker error when compiling the code stating that a library was not found for -lgfortran, execute

export LIBRARY_PATH=<pathToFolderContainingYourLibgfortran.a>

This may, for example, be /opt/local/lib/<yourGccVersion>. You can try to locate libgfortran.a by calling locate gfortran.

We recommend to create a build folder in the MAiNGO directory first and then navigate to it (you can create the build folder anywhere else on you machine).

mkdir build
cd build

Then simply execute cmake using the CMakeLists.txt from the MAiNGO directory by

cmake ..

To compile the code execute

make

You can add the option -j n to compile using n cores of your machine, e.g., execute make -j 4 to compile using 4 cores.

CMake Variables

You can change specific CMake flags by removing or adding a checkmark at the desired option on Windows or by adding -D<name_of_cmake_variable> after the cmake command on Linux and Mac OS. We recommend changing only those CMake variables only that are prefixed with MAiNGO_:

  • MAiNGO_build_parser (default: true): Whether to build an executable containing the parser for reading problems in ALE syntax from .txt files; uses the main file exampleAleParser/mainAleParser.cpp.
  • MAiNGO_build_standalone (default: false): Whether to build an executable for solving problems via the C++ API; uses the main file exampleCppApi/mainCppApi.cpp.
  • MAiNGO_use_filib (default: true): Whether to use FILIB++ for interval extensions, which is strongly recommended. If turned off, the non-validated intervals extensions from MC++ are used.
  • MAiNGO_use_mpi (default: false): Whether to build the parallel version of MAiNGO. Requires an MPI library to be installed on your system.

Executing MAiNGO

To execute MAiNGO, open a terminal window in the build folder where the MAiNGO executable is. On Windows this is in the Release or Debug folder (depending on what you have built). In order to not having to navigate to the build folder on Windows, you can, e.g., Shift + Right click on the appropriate folder and select Command Prompt or Power Shell. If you have built the parser version of MAiNGO (i.e., with MAiNGO_build_parser=true), simply type
on Windows: MAiNGO <yourProblem>
on Unix: ./MAiNGO <yourProblem>

which starts MAiNGO for the problem defined in the <yourProblem> file, e.g., MAiNGO C:/MAiNGO/exampleAleParser/problem.txt. If you get an error message stating that the problem file has not been found, please check the path to your problem file. If you want to modify your problem refer to section Modeling in MAiNGO. You can also execute MAiNGO with specific settings by calling
on Windows: MAiNGO <yourProblem> <yourSettings>
on Unix: ./MAiNGO <yourProblem> <yourSettings>

where <yourSettings> describes a path to your settings file, e.g., MAiNGO C:/MAiNGO/exampleAleParser/problem.txt C:/MAiNGO/exampleAleParser/MAiNGOSettings.txt. You can find an exemplary MAiNGO settings file in exampleAleParser/MAiNGOSettings.txt or exampleCppApi/MAiNGOSettings.txt. If you have built the standalone version in which the model is specified via the C++ API (i.e., with MAiNGO_build_standalone=true), type
on Windows: MAiNGOcpp <yourSettings>
on Unix: ./MAiNGOcpp <yourSettings>