Installation instructions

This page contains installation instructions for both Java and Python users. It also contains information about installing additional optimization software for solving (mixed-integer) linear programs.

Java users: import Maven project in Eclipse

The toolbox comes as an Apache Maven project for Eclipse. In order to get started it is required to perform the following steps:

1. Install Eclipse and the Maven plugin (Help -> Install New Software)
2. Clone the repository in your Eclipse workspace
3. Create a new project with the same name as the directory created in step 2
4. Convert the project to a Maven project (right click on the project -> Configure -> Convert to Maven Project)
5. If you get compilation errors: make sure that the compiler compliance level has been set correctly in the project settings

Java users: generating executable jar files

The Eclipse project can be used to create executable jar files for the example code and the server. This can be done by executing the package command of Maven, which builds the project and stores the executable jar files in the target directory. Example command for linux: mvn package. The following files are created:

• Server.jar: executable which runs the server that is required for Python users
• TestCMDP.jar: executable which runs the example code for MDPs
• TestCPOMDP.jar: executable which runs the example code for POMDPs
• ToyExamples.jar: executable which runs the example with user-defined domains

The jar files are also available as part of the release of the toolbox.

Python users: starting server and running code

When using Python it is required to run the java toolbox as a server. This can be done in two different ways:

• Execute the start_server script in the server directory of the repository. Prior to executing the script you have to move Server.jar to this directory. The Server.jar file can be generated as described above, or it can be downloaded from the release page. More information can be found in the README file in this directory.
• After importing the project in Eclipse, you can start the server by executing the executables.Server class. In the program arguments you have to provide the following arguments: port, lpsolver, verbose, clientdir. port is the port where the server waits for a connection. By default the Python client tries to connect to port 8080, so it is recommended to use that port. lpsolver is the name of the LP solver to use (gurobi, lpsolve or simplex). verbose indicates whether algorithms should print output (true or false). clientdir is the full path of the client directory

More information about installing the LP solvers can be found in the next section.

Running the Python code is straightforward. After starting the server (see above) the Python files can be executed directly. Example for Linux: python3 TestCMDP.py

Java and Python users: install optimization software

The toolbox requires a (mixed-integer) linear programming solver for the execution of several algorithms. The toolbox provides a built-in LP solver which is suitable to get started without additional optimization software. For better performance it is recommended to install a separate solver. For this purpose the toolbox provides support for Gurobi and LPSolve. Below we provide an overview of the steps that need to be taken to install additional optimization software.

Built-in LP solver (experimental)

For the built-in LP solver it is not required to install additional software. When starting the server it is sufficient to define 'simplex' as the LP solver. When running examples directly in the java source, it is sufficient to instantiate an LPSolverSimplex object as the LPSolver. The built-in solver does not provide support for integer programming, and therefore it is not possible to use the deterministic preallocation algorithm combined with this solver. Since the built-in LP solver is relatively unstable, we strongly recommend to install either Gurobi or LPSolve.

Gurobi

For the commercial optimization software Gurobi we refer to the official documentation. For Linux and Mac users it may be necessary to set the environment variables GUROBI_HOME, PATH and LD_LIBRARY_PATH in either the terminal, or the Eclipse run configuration. We refer to the quick start guide for more details. If you want to work with the Eclipse project, then it is required to move the jar file provided in the Gurobi installation directory to the lib directory of your Eclipse project. Furthermore, the path to this jar file should be set in the CONFIG file. If you want to run the server, then we refer to the server README for additional details.

LPSolve

If you want to use LPSolve in your java project in Eclipse, then it is necessary to install the software based on the official documentation. If you just run the server based on the jar file provided, then it is possible to use the LPSolve version that we included already. By default it uses the 32 bits version. If you want to use the 64 bits version, then it is required to modify the run script prior to executing it using a text editor. The architecture should match the architecture of your Java installation, rather than the operating system. Unfortunately, Mac users need to compile LPSolve from source, for which a README is provided in the server/mac/lpsolve_src directory. More information can be found in the README file in the server directory.