MAiNGO
Obtaining, Building, and Executing MAiNGO

Obtaining MAiNGO

To obtain MAiNGO, we strongly recommend using Git (Git Bash on Windows) and following the instructions below, in particular because we use submodules for dependencies. It is possible to download MAiNGO as a zipped folder, but when doing so all dependencies need to be downloaded separately.

To obtain MAiNGO via Git, first clone the MAiNGO repository via

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

where <directory> is the target directory (default name is maingo).

Next, navigate to this directory and initialize the submodules by executing

git submodule init

If you want to switch between HTTPS (default) and SSH protocols for obtaining the submodules, simply execute the shell scripts (Linux/MacOS only) ./switchToSsh or ./switchToHttps 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 web interface. If you are having HTTPS authentication problems on Windows, 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.

To actually download the 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. A note for user more familiar with Git: the git submodule update is executed 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 -j 1

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 and the dependencies by running git stash in the corresponding repository. Then, update the MAiNGO repository with the git pull and git submodule update commands. Finally, you can retrieve your changes via git stash pop.

Required Software

Building MAiNGO requires the following non-standard programs that are not provided when obtaining MAiNGO:

  • CMake 3.15 or later
  • Visual Studio 2017 or 2019 (Windows), or some other C++ compiler that supports C++17 (Linux & MacOS)
  • A Fortran Compiler (Linux & MacOS only; for Windows, we supply pre-compiled versions of all Fortran dependencies)

CPLEX 12.8 or 12.9 and Knitro 11.0.1 are optional subsolvers that are also not provided with MAiNGO. They are not required for using MAiNGO, but they can improve computational performance. CMake will automatically detect whether you have CPLEX/Knitro installed on your system 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.

All other third-party software that MAiNGO depends on comes with the MAiNGO git in the form of submodules. Unless you feel the need to modify the folder structure or switch to other versions (in which case we would appreciate you reporting your experience to us), there is nothing you need to do.

Generating and Compiling the Project

MAiNGO uses CMake for setting up the required Visual Studio project (for Windows) or Makefile (for Linux or MacOS). There are a few options for this setup that can be changed via the following CMake variables (details for how to actually do this on Windows, Linux, or MacOS follow below):

  • MAiNGO_build_parser (default: true): Whether to build an executable called MAiNGO (or MAiNGO.exe on Windows) containing the parser for reading problems in ALE syntax from .txt files. Uses the main file examples/mainAleParser.cpp.
  • MAiNGO_build_python_interface (default: false): Whether to build the Python bindings for the C++ API of MAiNGO. If set to true, this will create a Python package called pymaingo that allows using MAiNGO from Python. Check the CMake output to make sure that the correct version of Python was found. You can influence the Python version using the CMake variables PYBIND11_PYTHON_VERSION or PYTHON_EXECUTABLE as described here.
  • MAiNGO_build_standalone (default: false): Whether to build an executable called MAiNGOcpp (or MAiNGOcpp.exe on Windows) for solving problems via the C++ API. Uses the main file examples/mainCppApi.cpp.
  • MAiNGO_build_test (default: false): Whether to build the test cases for MAiNGO (and potentially pymaingo).
  • MAiNGO_use_cplex (default: true): Whether to use CPLEX if it is available on your system. Can be set to false to prevent the use of CPLEX even if it is installed, which can be useful if the compiled version is to be used on another machine that may not have CPLEX.
  • MAiNGO_use_knitro (default: true): Whether to use Knitro if it is available on your system. Can be set to false to prevent the use of Knitro even if it is installed, which can be useful if the compiled version is to be used on another machine that may not have Knitro.
  • MAiNGO_use_melon (default: true): Whether to use the MeLOn toolbox containing various machine learning models for use in the optimization problem.
  • MAiNGO_use_mpi (default: false): Whether to build the parallel version of MAiNGO. Requires an MPI library to be installed on your system.

A note for users seeking to include MAiNGO in their own code: 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. However, when including it into your code you will need to add all dependencies (i.e., all folders within the dep folder in the MAiNGO repository) in your own CMakeLists.txt using add_subdirectory. Please see also section Embedding MAiNGO in your Application.

Windows

On Windows, only Microsoft Visual Studio 2017 and 2019 are supported. We supply pre-compiled versions for all Fortran libraries, so no Fortran compiler (or runtime) should be needed. To generate the Visual Studio project and compile MAiNGO, you need to complete the following steps:

  1. 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
  2. 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; analogous for Visual Studio 16 2019). Make sure that you use default native compilers. Press Finish and wait for the configuration to complete. If at the end you get a message saying Configuring done, everything worked fine.
    CMakeGenerator.PNG
  3. If desired, you can now change the values of the CMake variables explained above. We recommend changing only those CMake variables that are prefixed with MAiNGO_.
  4. Press the Generate button. You should get a message saying Generating done.
  5. Press the Open Project button (or open the MAiNGO.sln file (with Visual Studio 2017 or 2019) that was created by CMake in the build directory you specified). Make sure to set the build type to Release, since this will result in MAiNGO being significantly faster.
    VS_Release.PNG
  6. Compile MAiNGO by clicking Build->Build solution. This will create executables called MAiNGO.exe and/or MAiNGOcpp.exe as well as a pymaingo folder in the Release directory within your build directory, depending on which CMake variables you have enabled (cf. above). MAiNGO.exe is the version that expects text-based input via ALE, while MAiNGOcpp.exe is the version that uses the C++ API and has a problem (e.g., the example problem compiled into it).
  7. If you would like to debug MAiNGO, you need to set MAiNGO as the starting project first. This is done by right clicking on MAiNGO within your project explorer of Visual Studio and setting it to be the starting project. If you get an error message saying that ALL_BUILD cannot be used as starting project, you did not set MAiNGO as starting project.

Linux and MacOS

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

  • gcc 9.2, and 10.1 (Linux and MacOS)
  • Intel C++ and Fortran Compiler 16.0.8, 17.0.7, 18.0.3, and 19.1 (Linux) - only works if building without the parser (MAiNGO_build_parser=false) and without the MeLOn toolbox (MAiNGO_build_melon=false) 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 MacOS, 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.

mkdir build
cd build

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

cmake ..

You can change the CMake variables explained above by adding -D<name_of_cmake_variable>=<value> after the cmake command. 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.

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). You can, e.g., Shift + Right click on the appropriate folder and select Command Prompt or Power Shell. Depending on which version of MAiNGO you have selected via the CMake variables (cf. section Generating and Compiling the Project), you can run MAiNGO as follows:

If you have built the parser version of MAiNGO (i.e., with MAiNGO_build_parser=true), simply type

  • on Windows: MAiNGO <yourProblem>
  • on Linux / MacOS: ./MAiNGO <yourProblem>

which starts MAiNGO for the problem defined in the <yourProblem> file, e.g., MAiNGO C:/MAiNGO/examples/01_BasicExample/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. For details on how to write your own problem file, pleases refer to section Modeling with ALE. You can also execute MAiNGO with specific settings by calling

  • on Windows: MAiNGO <yourProblem> <yourSettings>
  • on Linux / MacOS: ./MAiNGO <yourProblem> <yourSettings>

where <yourSettings> describes a path to your settings file, e.g., MAiNGO C:/MAiNGO/examples/01_BasicExample/problem.txt C:/MAiNGO/examples/MAiNGOSettings.txt. You can find an exemplary MAiNGO settings file in examples/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 Linux / MacOS: ./MAiNGOcpp <yourSettings>

which starts MAiNGO for the problem defined in the header file included in examples/mainCppApi.cpp (by default, this is examples/01_BasicExample/problem.h. For details on how to write your own problem via the C++ API, please refer to secion Modeling via C++ or Python.

If you are using the Python interface, MAiNGO is invoked by Python, see for example examples/01_BasicExample/examplePythonInterface.py.