![]() |
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
where <directory> is the target directory (default name is maingo).
Next, navigate to this directory and initialize the submodules by executing
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
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.
If you want to update to the latest MAiNGO version, use the following git commands:
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
.
Building MAiNGO requires the following non-standard programs that are not provided when obtaining MAiNGO:
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.
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.
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:
Configuring done
, everything worked fine. MAiNGO_
.Generating done
.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. 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).ALL_BUILD
cannot be used as starting project, you did not set MAiNGO as starting project.On Linux and MacOS, the following compiler configurations have been tested:
MAiNGO_build_parser=false
) and without the MeLOn toolbox (MAiNGO_build_melon=false
) because of missing C++17 features in Intel compilersOn 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
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.
Then simply execute cmake using the CMakeLists.txt from the MAiNGO directory by
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
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.
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
MAiNGO <yourProblem>
./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
MAiNGO <yourProblem> <yourSettings>
./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
MAiNGOcpp <yourSettings>
./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
.