Back to ObtainingAndRunningFastDownward.

LP solver support

Some configurations of the search component of Fast Downward, such as optimal cost partitioning for landmark heuristics, require a linear programming (LP) solver and will complain if the planner has not been built with support for such a solver. Setting up LP support requires three steps, explained below:

1. Installing one or more LP solvers.
2. Installing the Open Solver Interface.
3. Building Fast Downward with LP support.

Step 1. Installing one or more LP solvers

Fast Downward uses a generic interface (see next step) for accessing LP solvers and hence can be used together with different LP solvers. Currently, four LP solvers are supported: CPLEX, SoPlex, Gurobi, and COIN-LP. You can install one, two or all solvers without causing conflicts. The solver used by the planner is selected by command-line arguments, not at compile time. We recommend using CPLEX or SoPlex, which in our experiments have led to better performance than COIN-LP. See issue752 for a discussion of their relative performance. We have no experience with Gurobi, but others recommend it over CPLEX. (If you have data comparing these two within Fast Downward, we would be very interested in hearing about it.)

The following instructions are for Linux/macOS only.

Installing one or more LP solvers: CPLEX

IBM offers a free academic license that includes access to CPLEX. Once you are registered, you find the software under Technology -> Data Science. Choose the right version and switch to HTTP download unless you have the IBM download manager installed. If you have problems using their website with Firefox, try Chrome instead. Execute the downloaded binary and follow the guided installation. If you want to install in a global location, you have to execute the installer as root.

After the installation, set the following environment variable (adapt the path if you installed another version or did not install in the default location):

export DOWNWARD_CPLEX_ROOT=/opt/ibm/ILOG/CPLEX_Studio129/cplex

Starting with version 12.7 CPLEX no longer supports 32-bit builds. If you need 32-bit builds with LP support, you need access to a CPLEX 12.6 installer. However, CPLEX 12.6 is not compatible with recent OSI versions. If you get segmentation faults with 32-bit CPLEX builds, try to build one of the sample programs that come with CPLEX to see if it is installed correctly.

If you don't want to permanently modify your environment, you can also set these variables directly when calling CMake, or in src/build.py. The variables need to be set for when installing the Open Solver Interface (Step 2.) and when building Fast Downward's search component (Step 3.).

Installing CPLEX on Windows

Please install CPLEX into a directory without spaces. (We assume this is C:\cplex. Usually you will install ILOG Studio, which contains more than just CPLEX, so the paths below use C:\cplex\cplex to point to the CPLEX part of it.) For a silent installation, please consult: https://www.ibm.com/support/knowledgecenter/SSSA5P_12.9.0/ilog.odms.studio.help/Optimization_Studio/topics/td_silent_install.html

Important Note: Setting up environment variables might require using / instead of the more Windows-common \ to work correctly.

Installing one or more LP solvers: SoPlex

SoPlex is available under a free academic license on the SoPlex homepage. Please use version 3.1.1 as OSI is currently not compatible with version 4+ of SoPlex. After downloading the sourcecode, you can install it as follows (adapt the path if you install another version or want to use another location):

sudo apt install libgmp3-dev # The library is optional but important for SoPlex's performance
export DOWNWARD_SOPLEX_ROOT=/opt/soplex-3.1.1
tar xvzf soplex-3.1.1.tgz
cd soplex-3.1.1
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX="$DOWNWARD_SOPLEX_ROOT" ..
make
make install

After installation, permanently set the environment variable DOWNWARD_SOPLEX_ROOT to the value you used in installation.

Installing SoPlex on the grid in Basel

When installing SoPlex on the grid, the GMP library has to be loaded from a module. The following set of modules is compatible.

module purge
module load GCC/8.2.0-2.31.1
module load CMake/3.9.5-GCC-8.2.0-2.31.1
module load GMP/6.1.2-GCCcore-8.2.0.lua

Because the library is loaded from a module, it is not in a default directory, so change the CMake call to

cmake -DCMAKE_INSTALL_PREFIX="$DOWNWARD_SOPLEX_ROOT" -DGMP_DIR="$EBROOTGMP" ..

Installing one or more LP solvers: Gurobi

We have no experience with installing Gurobi. On Linux, Gurobi is only available for 64-bit.

After the installation, set the following environment variables:

export DOWNWARD_GUROBI_ROOT=/path/to/gurobi

If you don't want to permanently modify your environment, you can also set these variables directly when calling CMake, or in src/build.py. The variables need to be set for when installing the Open Solver Interface (Step 2.) and when building Fast Downward's search component (Step 3.).

Installing one or more LP solvers: COIN-LP

COIN-LP is no longer bundled with OSI starting from version 0.104.0 and needs to be installed separately. Installation should be possible with

sudo apt-get install clp

but we have no experience with this. We recommend against using it in serious experiments unless you have established that it offers comparable performance to CPLEX in your setting.

Step 2. Installing the Open Solver Interface

The Open Solver Interface (OSI) provides a common interface to different LP solvers. OSI must be compiled after installing the LP solver(s) in Step 1. If you install a solver later, repeat the installation steps of OSI. We assume in the following that CPLEX and SoPlex are installed and the environment variables DOWNWARD_CPLEX_ROOT and DOWNWARD_SOPLEX_ROOT are set up correctly.

These instructions apply to COIN/OSI 0.107.9, newer versions from http://www.coin-or.org/download/source/Osi/ should work, too. If you experience problems, please let us know.

Installing the Open Solver Interface on Linux

The way we install OSI depends on zlib, so make sure to install it first with

sudo apt install zlib1g-dev

Run the following commands. If you have chosen not to install CPLEX or SoPlex, omit the options related to the corresponding solver from the call to ./configure (options for solvers that are not installed can lead to very cryptic error messages). If you installed other solvers like CLP or Gurobi, also add the corresponding options for them. You may have to include the path to shared libraries in LDFLAGS, i.e. LDFLAGS="-L$DOWNWARD_CPLEX_ROOT/lib -L/usr/lib/gcc/i686-linux-gnu/4.8". If there are other problems, see the troubleshooting section.

   1 wget http://www.coin-or.org/download/source/Osi/Osi-0.107.9.tgz
   2 tar xvzf Osi-0.107.9.tgz
   3 cd Osi-0.107.9
   4 
   5 export DOWNWARD_COIN_ROOT=/opt/coin/Osi-0.107.9
   6 
   7 
   8 ./configure CC="gcc"  CFLAGS="-pthread -Wno-long-long" \
   9             CXX="g++" CXXFLAGS="-pthread -Wno-long-long" \
  10             LDFLAGS="-L$DOWNWARD_CPLEX_ROOT/lib/x86-64_linux/static_pic \
  11                      -L$DOWNWARD_SOPLEX_ROOT/lib" \
  12             --without-lapack --enable-static=no \
  13             --prefix="$DOWNWARD_COIN_ROOT" \
  14             --disable-bzlib \
  15             --with-soplex-incdir=$DOWNWARD_SOPLEX_ROOT/include \
  16             --with-soplex-lib="-lsoplex" \
  17             --with-cplex-incdir=$DOWNWARD_CPLEX_ROOT/include/ilcplex \
  18             --with-cplex-lib="-lcplex -lm -ldl" # -ldl is only needed for CPLEX >= 12.8
  19 
  20 make
  21 make install
  22 cd ..
  23 rm -rf Osi-0.107.9
  24 rm Osi-0.107.9.tgz

After installation, permanently set the environment variable DOWNWARD_COIN_ROOT to the value you used in installation.

If you don't want to permanently modify your environment, you can also set these variables directly when calling CMake, or in src/build.py. The variables need to be set for when installing the Open Solver Interface (Step 2.) and when building Fast Downward's search component (Step 3.).

Installing the Open Solver Interface on macOS

Follow the Linux instructions above with the following change:

• Building CoinUtils can create both static and dynamic libraries and there have been reported problems with both.

  • To use static libraries, replace --enable-static=no with --enable-static=yes and delete the dynamic libraries from $(DOWNWARD_COIN_ROOT)/lib/ after building CoinUtils.

  • or

  • To use dynamic libraries, keep using --enable-static=no and change the Fast Downward CMakefile to look for dynamic (*.dylib) instead of static (*.a) libraries of libOsiCpx, libOsiGrb, and libOsiClp.

Installation of version 0.103.0 has been reported to fail on macOS due to a bug in the CoinUtils configure script. (See issue295.) If you run into this problem, try downloading the patched file attached to this page, make it executable, and replace the file Osi-0.103.0/CoinUtils/configure with it:

    cp Dowloads/coinutils-configure.patched Osi-0.103.0/CoinUtils/configure
    chmod +x Osi-0.103.0/CoinUtils/configure

Installing the Open Solver Interface on Windows

We managed to install OSI natively with support for CPLEX on Windows using the following steps:

1. We assume CPLEX is installed in C:\cplex and

2. Open the command line and execute vcvarsall.bat x64 of Visual Studio (see ObtainingAndRunningFastDownward#Compiling_on_Windows)

3. Download the zlib source code (https://www.zlib.net/). We use the current (Jan 2021) version 1.2.11. We assume your unpacked directory is called zlib_sources. Next compile it and set up the include and lib directories within zlib\. Let the variable ZLIB_ROOT point to zlib\.

   •    1     mkdir zlib
        2     mv zlib_sources zlib\include
        3     cd zlib\include
        4     nmake /f win32/Makefile.msc
        5     mkdir ..\lib
        6     move zdll.lib ..\lib\zdll.lib
        7     move zlib.lib ..\lib\zlib.lib
        8     move zlib1.dll ..\lib\zlib1.dll
     

4. Download OSI (we use 0.107.9, newer versions should work but are untested). We assume your unpacked directory is called osi. On Windows, we have to create two directories for the libraries, one for the debug and one for the release mode. First, we create the include directories:

   •    1     mkdir osi_release\include
        2     cd osi
        3     copy CoinUtils\src\*.hpp ..\osi_release\include
        4     copy CoinUtils\src\*.h ..\osi_release\include
        5     copy Osi\src\Osi\*.hpp ..\osi_release\include
        6     copy Osi\src\Osi\*.h ..\osi_release\include
        7     copy Osi\src\OsiCpx\*.hpp ..\osi_release\include
        8     copy Osi\src\OsiCpx\*.h ..\osi_release\include
        9     Xcopy /E /I ..\osi_release\include ..\osi_debug\include
     

5. To statically link the LP solvers, we have to compile the libraries with static linking. At the time being (Jan 2021), setting this parameter required the Visual Studio GUI. We wrote our own script which workes without a GUI. For easier access, we create a variable to call the script.

   •    1     set SET_RUNTIME_LIBRARY=python PATH\TO\REPOSITORY\github\workflows\misc\set-visual-studio-static-runtime-libraries.py
     

6. Next, we compile libOsi. We use devenv to update the Visual Studio project file for your Visual Studio version.

   •    1     mkdir ..\osi_release\lib
        2     mkdir ..\osi_debug\lib
        3 
        4     cd Osi\MSVisualStudio\v10\
        5     devenv Osi.sln /Upgrade
        6     cd libOsi\
        7     %SET_RUNTIME_LIBRARY% libOsi.vcxproj libOsi.vcxproj
        8     msbuild libOsi.vcxproj /p:Configuration=Release /p:Platform=x64 /p:DefaultWindowsSDKVersion=%WindowsSDKVersion% /p:OutDir=lib
        9     move lib\* ..\..\..\..\..\osi_release\lib\
       10     msbuild libOsi.vcxproj /p:Configuration=Debug /p:Platform=x64 /p:DefaultWindowsSDKVersion=%WindowsSDKVersion% /p:OutDir=lib
       11     move lib\* ..\..\..\..\..\osi_debug\lib\
       12 
     

7. To use CPLEX with Osi, we compile the binding library. There is no Visual Studio project for this, thus, we compile it manually.

   •    1     cd ..\..\..\src\OsiCpx
        2     cl /EHsc OsiCpxSolverInterface.cpp /I ..\Osi /I ..\..\..\CoinUtils\src /I "%DOWNWARD_CPLEX_ROOT%\include\ilcplex" /c
        3     lib OsiCpxSolverInterface.obj
        4     move OsiCpxSolverInterface.lib ..\..\..\..\osi_release\lib\libOsiCpx.lib
        5     cl /EHsc OsiCpxSolverInterface.cpp /I ..\Osi /I ..\..\..\CoinUtils\src /I "%DOWNWARD_CPLEX_ROOT%\include\ilcplex" /c /MTd
        6     lib OsiCpxSolverInterface.obj
        7     move OsiCpxSolverInterface.lib ..\..\..\..\osi_debug\lib\libOsiCpx.lib
     

8. At last, we compile libCoinUtils.

   •    1     cd ..\..\..\CoinUtils\MSVisualStudio\v10
        2     devenv CoinUtils.sln /Upgrade
        3     cd libCoinUtils
        4     %SET_RUNTIME_LIBRARY% libCoinUtils.vcxproj libCoinUtils.vcxproj
        5     msbuild libCoinUtils.vcxproj /p:Configuration=Release /p:Platform=x64 /p:DefaultWindowsSDKVersion=%WindowsSDKVersion% /p:OutDir=lib
        6     move lib\* ..\..\..\..\..\osi_release\lib\
        7     msbuild libCoinUtils.vcxproj /p:Configuration=Debug /p:Platform=x64 /p:DefaultWindowsSDKVersion=%WindowsSDKVersion% /p:OutDir=lib
        8     move lib\* ..\..\..\..\..\osi_debug\lib\
        9 
     

9. Finally, set the DOWNWARD_COIN_ROOT_RELEASE and DOWNWARD_COIN_ROOT_DEBUG variables to point to osi_release and osi_debug.

Step 3. Building Fast Downward with LP support

Once OSI is installed, you can build Fast Downward's search component with LP support by calling ./build.py. Remove your previous build first:

rm -rf builds

Fast Downward automatically includes an LP Solver in the build, if it is needed, and the solver and the necessary OSI adapter are detected on the system. If you want to explicitly build without the LP solver that is installed on your system, disable the LP solver plugin (with -DPLUGIN_LP_SOLVER_ENABLED=FALSE) and all plug-ins that require it, such as POTENTIAL_HEURISTICS (see ObtainingAndRunningFastDownward#Manual_Builds ).

Troubleshooting

The LP-related libraries have a number of dependencies which might not be installed on your system. If for some reason one of the above steps fails, we would appreciate if you could attempt to troubleshoot it yourself.

If the configure step of COIN/OSI fails with the error Cannot find symbol(s) CPXgetstat with CPX, check the path to the CPLEX lib directory. Depending on your CPLEX installation, the libraries might be stored in a different place, e.g., in $DOWNWARD_CPLEX_ROOT/lib/x86-64_sles10_4.1/static_pic. Check that the directory exists and contains the file libcplex.a. In some cases with the same error message, the library dl has to be added (see this question on stackoverflow). If the configure step fails for another reason, have a look at their troubleshooting page or their page of current issues.

If you get warnings about unresolved references with CPLEX, visit their help pages.

If Fast Downward gives you compilation errors mentioning the isnan function, you are likely affected by an OSI/compiler incompatibility (see http://issues.fast-downward.org/issue681). In this case try the following:

1. Add export DOWNWARD_USE_ISNAN_WORKAROUND=1 to your ~/.bashrc file (or other shell configuration file).

2. Make sure the changed shell configuration takes effect by logging out and then logging in again.

3. In the main directory of the repository, delete all cmake build artifacts with rm -r builds.

4. Rebuild.

If you compiled Fast Downward on Windows (especially on GitHub Actions) and cannot execute the binary in a new command line, then it might be unable to find a dynamically linked library. Use dumpbin /dependents PATH\TO\DOWNWARD\BINARY to list all required libraries and ensure that they can be found in your PATH variable.

If after troubleshooting you can get the LP package to work, please do let us know of your problem and its solution so that we can improve these instructions. If you still cannot get it to work, we may be able to provide some help, but note that the LP solvers and OSI library are external packages not developed by us.