As a developer, you can use OptaWeb Vehicle Routing to optimize your vehicle fleet deliveries. In this guide, you will create and run a sample OptaWeb Vehicle Routing application.

1. Introduction

1.1. What is OptaWeb Vehicle Routing?

The main purpose of many types of businesses is to transport various types of cargo. The goal of these businesses is to deliver a piece of cargo from the loading point to a destination and use its vehicle fleet in the most efficient way. This type of optimization problem is referred to as the vehicle routing problem (VRP) and has many variations.

OptaPlanner can solve many of these vehicle routing variations and provides solution examples. OptaPlanner enables developers to focus on modeling business rules and requirements instead of learning constraint programming theory. OptaWeb Vehicle Routing expands OptaPlanner’s vehicle routing capabilities by providing a reference implementation that answers questions such as these:

  • Where do I get the distances and travel times?

  • How do I visualize the solution on a map?

  • How do I build an application that runs in the cloud?

2. Quickstart

You can get up and running with OptaWeb Vehicle Routing in just a few steps.

2.1. Download routing data

The routing engine requires geographical data to calculate the time it takes vehicles to travel between locations. You must download and store OSM (OpenStreetMap) data files on the local file system before you run OptaWeb Vehicle Routing.

Note
 The OSM data files are typically between 100 MB to 1 GB and take time to download so it is a good idea to download the files before building or starting the OptaWeb Vehicle Routing application.
Procedure

  1. Open http://download.geofabrik.de/ in a web browser.

  2. Click a region in the Sub Region list, for example Europe. The sub region’s page opens.

  3. In the Sub Regions table, download the OSM file (.osm.pbf) for a country, for example Belgium.

2.2. Create the OptaWeb Vehicle Routing data directory structure

OptaWeb Vehicle Routing reads and writes several types of data on the file system. It reads OSM (OpenStreetMap) files from the openstreetmap directory, writes a road network graph to the graphhopper directory, and persists user data in a directory called db. Create a new directory dedicated to storing all of these data to make it easier to upgrade to a newer version of OptaWeb Vehicle Routing in the future and continue working with the data you created previously.

Procedure

  1. Create the openstreetmap directory in your user account home directory, for example:

    $HOME/.vrp
└── openstreetmap

  2. Move all of your downloaded OSM files (files with the extension .osm.pbf) to the openstreetmap directory.

The rest of the directory structure will be created by the OptaWeb Vehicle Routing application when it runs for the first time. After that, your directory structure will look similar to the following example:

$HOME/.vrp
├── db
│   └── vrp.mv.db
├── graphhopper
│   └── belgium-latest
└── openstreetmap
    └── belgium-latest.osm.pbf

2.3. Verify the Java version

Java SE 8 or higher must be installed on your system before you can use OptaWeb Vehicle Routing. It is recommended that you install JDK. However, if you have a binary distribution of OptaWeb Vehicle Routing, you only need the Java SE Runtime Environment (JRE). But if you want to build OptaWeb Vehicle Routing from source, your system must have the Java SE Development Kit (JDK).

Procedure:

  1. To verify the current Java installation, enter the following command:

    java -version

  2. If necessary, install OpenJDK 8.

    • To install OpenJDK 8 on Fedora, enter the following command:

      sudo dnf install java-1.8.0-openjdk-devel

    • To install OpenJDK on other platforms, follow instructions at https://openjdk.java.net/install/.

2.4. Download OptaWeb Vehicle Routing

Download the OptaWeb Vehicle Routing distribution archive, available from the OptaPlanner website, to quickly evaluate OptaWeb Vehicle Routing without having to set up build tools.

Prerequisites

  • Java 8 or higher is installed.

Note
 If you want to modify OptaWeb Vehicle Routing and build it yourself or contribute to upstream, see the Development chapter.
Procedure

  1. Go to https://www.optaplanner.org/download/download.html and click the OptaWeb Vehicle Routing tab.

  2. Click Download OptaWeb Vehicle Routing <version>.

    OptaPlanner download page at www.optaplanner.org
    Figure 1. OptaPlanner download page

  3. Extract the downloaded distribution ZIP file. The archive contains source files and a binary build of OptaWeb Vehicle Routing as well as the OptaWeb Vehicle Routing documentation.

    Content of the OptaWeb Vehicle Routing distribution archive
    Figure 2. Content of the OptaWeb Vehicle Routing distribution archive

2.5. Run OptaWeb Vehicle Routing

After you download OptaWeb Vehicle Routing, use the run.sh script to run it.

Prerequisites

  • Internet access is available. When OptaWeb Vehicle Routing runs it uses third-party public services such as OpenStreetMap to display map tiles and provide search results.

  • Java 8 or higher is installed.

  • A directory called openstreetmap with at least one OSM file exists.

  • A country code to use in search queries is identified.

Procedure

Enter the following command, where <DATA_DIR> is the parent of the openstreetmap directory, <COUNTRY> is the country that you downloaded data for, and <CODE> is the code for that country:

./bin/run.sh <DATA_DIR> <COUNTRY>-latest.osm.pbf <CODE>

For example, if you want to run OptaWeb Vehicle Routing with Belgium and you downloaded the belgium-latest.osm.pbf file from the Geofabrik website and saved it as ~/.vrp/openstreetmap/belgium-latest.osm.pbf, enter the following command:

./bin/run.sh ~/.vrp/ belgium-latest.osm.pbf BE

2.6. Using air distance mode

OptaWeb Vehicle Routing can work in air distance mode that calculates travel times based on the distance between two coordinates. Use this mode in situations where you need to get OptaWeb Vehicle Routing up and running as quickly as possible and do not want to use an OSM (OpenStreetMap) file. Air distance mode is only useful if you need to smoke-test OptaWeb Vehicle Routing and you do not need accurate travel times.

Prerequisites

  • Java 8 or higher is installed.

  • OptaWeb Vehicle Routing distribution archive is downloaded and extracted.

Procedure

  1. Enter the run.sh script without arguments to start OptaWeb Vehicle Routing in air distance mode:

    ./bin/run.sh

  2. When prompted, confirm that you want to start OptaWeb Vehicle Routing in air distance mode.

2.7. Building OptaWeb Vehicle Routing

If you do not have an executable distribution of OptaWeb Vehicle Routing, for example you have just cloned the Git repository from https://github.com/kiegroup/optaweb-vehicle-routing, you must build OptaWeb Vehicle Routing before you can run it.

Prerequisites

  • You have cloned the OptaWeb Git repository.

Procedure

  1. To build OptaWeb Vehicle Routing, change directory to the root of the project with the mvnw script file:

    cd optaweb-vehicle-routing

  2. Build with Maven:

    ./mvnw clean install -DskipTests

For more information about building OptaWeb Vehicle Routing, see the Development chapter.