Differences between revisions 101 and 102
⇤ ← Revision 101 as of 2023-09-15 13:42:10 →
Size: 6532
Editor: RemoChristen
Comment: Replace "DOWNWARD_CPLEX_ROOT" by "cplex_DIR".
← Revision 102 as of 2023-10-12 12:21:52 → ⇥
Size: 0
Editor: GabiRoeger
Comment: Info moved to repository (and streamlined)
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
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. Running an LP configuration requires three steps, explained below:

 1. Installing one or more LP solvers.
 1. Building Fast Downward with LP support.
 1. Choosing a solver with command-line arguments.

== Step 1. Installing one or more LP solvers ==

Fast Downward uses a generic interface for accessing LP solvers and hence can be used together with different LP solvers. Currently, CPLEX and !SoPlex are supported. You can install one or both solvers without causing conflicts. Installation varies by solver and operating system.

=== Installing CPLEX on Linux/macOS ===

IBM offers a [[http://ibm.com/academic|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.
The installer is for ILOG Studio, which contains more than just CPLEX, so the variable points to the subdirectory {{{/cplex}}} of the installation.
Adapt the path if you installed another version or did not install in the default location:
{{{
export cplex_DIR=/opt/ibm/ILOG/CPLEX_Studio2211/cplex
}}}

If you don't want to permanently modify your environment, you can also set these variables directly when calling CMake. The variable needs to be set when building Fast Downward's search component (Step 2.).

=== Installing CPLEX on Windows ===

Follow the Linux instructions to acquire a license and access the Windows-version of the CPLEX installer. Please install CPLEX into a directory without spaces.
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 SoPlex on Linux/macOS ===

!SoPlex is available under the Apache License from [[https://github.com/scipopt/soplex|Github]]. To be compatible with C++-20, we require a version of !SoPlex more recent than 6.0.3. At the time of this writing, 6.0.3 is the latest release, so we have to build from the unreleased version at the tip of the main branch.

You can install !SoPlex as follows (adapt the path if you install another version or want to use another location):
{{{

git clone https://github.com/scipopt/soplex.git
sudo apt install libgmp3-dev # The library is optional but important for SoPlex's performance
export soplex_DIR=/opt/soplex-6.0.3x
export CXXFLAGS="$CXXFLAGS -Wno-use-after-free" # Ignore compiler warnings about use-after-free
cmake -S soplex -B build
cmake --build build
cmake --install build --prefix $soplex_DIR
rm -rf soplex build
}}}

After installation, permanently set the environment variable {{{soplex_DIR}}} to the value you used in installation.

/!\ '''Note:''' Once a version including Salomé's fix is released, we can update this and can recommend the [[https://soplex.zib.de/index.php#download|SoPlex homepage]] for downloads instead.

=== Installing SoPlex on the grid in Basel ===

To build !SoPlex on the grid, you should load a module with the GMP library and a compatible compiler module. The following setup should work:
{{{
module purge
module load GCC/11.3.0.lua
module load CMake/3.23.1-GCCcore-11.3.0.lua
module load Python/3.10.4-GCCcore-11.3.0.lua
module load GMP/6.2.1-GCCcore-11.3.0
}}}

Because the library is loaded from a module, it is not in a default directory, so change the CMake call to
{{{
cmake -S soplex -B build -DGMP_DIR="$EBROOTGMP"
}}}


== Step 2. Building Fast Downward with LP support ==

Once LP solvers are installed and the environment variables {{{cplex_DIR}}} and/or {{{soplex_DIR}}} are set up correctly, 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 is detected on the system. If you want to explicitly build without LP solvers that are installed on your system, use {{{./build.py release_no_lp}}}, or a [[ObtainingAndRunningFastDownward#Manual_Builds|manual build]] with the option {{{-DUSE_LP=NO}}}.


== Step 3. Choosing a solver with command-line arguments ==

Features that use an LP solver have a command-line option `lpsolver` to switch between different solver types. See [[http://issues.fast-downward.org/issue752|issue752]] and [[http://issues.fast-downward.org/issue1076|issue1076]] for a discussion of the relative performance of CPLEX and !SoPlex.

Note that !SoPlex is not a MIP solver, so using it for configurations that require integer variables will result in an error. Please use CPLEX for such cases.


== 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 you get warnings about unresolved references with CPLEX, visit their [[http://www-01.ibm.com/support/docview.wss?uid=swg21399926|help pages]].

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 are external packages not developed by us.