VROOM Documentation

The actual start time of a task must fall within its time_windows.

Timing Behavior:

• If a vehicle arrives before a window starts, it may wait.
• setup and service times occur immediately after the start time and can extend past the window end.

Window Formats:

• Relative values: e.g., [0, 14400] (a 4-hour window from the start of the planning horizon). Output arrival times will be relative to the horizon start.
• Absolute values: Real timestamps. Output arrival times will be interpreted as timestamps.

If no time_window is provided, the task can be performed at any time permitted by other constraints.

VROOM operates in two distinct modes depending on your objective:

1. Default VRP: The standard mode. It takes a vehicle routing problem description and outputs a set of routes that satisfy all provided constraints.
2. Plan mode: Activated using the -c flag. This mode is used to determine the best ETAs for an existing, expected route. It takes the same input format but includes a description of the expected route for each vehicle via the steps key. In this mode, all input constraints are treated as soft constraints. The output aims to match the expected route while minimizing timing violations and reporting any constraint breaches.

To model capacity constraints (e.g., weight, volume, item count), use arrays of amounts across different objects. A vehicle is only allowed to serve a task if the resulting load at every step remains below the vehicle's capacity for every metric.

Key fields:

• capacity (on vehicle)
• delivery (on job)
• pickup (on job)
• amount (on shipment)

Assumptions:

• For job objects, delivery amounts are assumed to be loaded at the vehicle start.
• For job objects, pickup amounts are assumed to be brought back at the vehicle end.

Tip: When using multiple metrics, place the most limiting/important metrics first in the arrays.

If the time required to complete a task varies by vehicle type, use service_per_type and setup_per_type in the task definition.

For a vehicle with type: t, the actual time used is:

1. task.service_per_type[t] (if provided).
2. task.service (fallback if t is not a key in service_per_type).

Vroom models Vehicle Routing Problems (VRP) using three primary abstractions:

1. Vehicles: Represent the resources available for routing. They can have capacities (on arbitrary metrics), skills, working hours, and driver breaks. Vehicles can have specific start and end locations/times, or support 'open trip optimization' where only the start or end is defined.
2. Jobs: Represent single-location tasks. These can be pickups or deliveries with specific amounts (on arbitrary metrics), service time windows, service durations, skills, and priority levels.
3. Shipments: Represent pickup-and-delivery tasks where the pickup and delivery must occur within the same route.

Vroom solves multiple problem types simultaneously, including TSP, CVRP, VRPTW, MDHVRPTW, and PDPTW.

Use skills to ensure only qualified vehicles serve specific tasks.

Logic:

• A job j is eligible for vehicle v if and only if j.skills is a subset of v.skills (i.e., the vehicle possesses all required skills for the job).
• A task without skills can be served by any vehicle.
• A vehicle without skills can only serve tasks that require no skills.

To model a problem with no skill requirements, you can simply omit the skills key (it defaults to an empty array).

Vehicles can be configured with start and end locations. At least one must be present.

• If end is omitted: The route stops at the last visited task (determined by optimization).
• If start is omitted: The route starts at the first visited task (determined by optimization).
• For a round trip: Specify both start and end with the same coordinates.

Note: If using custom matrices, follow the same logic as tasks: use location_index instead of location.

Task Priorities

Set a priority value for tasks to influence unassigned tasks. Higher priority values make the optimizer more likely to include those tasks in the solution.

Setup Times

Use setup to model the time required to get started at a location.

• Total action time at a new location = setup + service.
• Total action time at a previously visited location = service only.

When defining job, pickup, or delivery objects, how you specify location depends on whether you are using custom matrices:

Using Custom Matrices

If you provide custom matrices in the input, you must use indices instead of coordinates:

• location_index is mandatory.
• location is optional (can be included to retrieve coordinates in the response).

Using Default Routing (No Custom Matrices)

If no custom matrices are provided, VROOM will query the routing engine:

• location is mandatory.
• location_index is ignored.

Vroom works out-of-the-box with several open-source routing engines to provide distance and time matrices:

• OSRM (Open Source Routing Machine)
• Openrouteservice
• Valhalla

Additionally, Vroom can utilize a custom cost matrix computed from any other external source.

The steps array allows you to define specific route orderings.

In Plan Mode

steps describes the exact route ordering that will be generated. Optional service_* keys in vehicle_step act as hard timing constraints.

In Solving Mode (Default VRP)

steps is used to force the search to start from a user-defined solution. This follows a single search path rather than running concurrent searches.

• Only steps with type=job, pickup, or delivery are used for ordering.
• service_* keys are ignored.
• Warning: If the provided steps violate any constraints, an error is raised.

To run Vroom, you have two primary paths:

1. Build from source: Follow the instructions in the project wiki.
2. Docker: Use vroom-docker for a pre-configured environment.

If you need to interact with Vroom via HTTP, use vroom-express, which is a simple wrapper already bundled in the vroom-docker setup.