OptaPlanner EOL notice - Timefold offers support

The vehicle routing problem (VRP) is a popular academic optimization problem with numerous variants.

While you can map the vehicle routing problem to real-world tasks like planning deliveries or optimizing itineraries for field service technicians, very often you have to deal with at least one additional constraint: customers' availabilities.

This post will show you how to solve the vehicle routing problem using Timefold Solver.

VRP with time windows

Let’s start by defining the problem. Same as the vanilla VRP, the task is to plan routes of N vehicles to visit M customers to minimize the driving time. The additional complexity comes from customers' availability in limited time windows. If the vehicle arrives at the destination too early, it has to wait, which is suboptimal. If it arrives too late, it’s even worse as the planned visit has to be rescheduled to some other day and all the mileage driven comes in vain.

Map with a customer’s availability

Domain model

The vehicle routing class diagram

The domain model takes advantage of the @PlanningListVariable: the Vehicle is the @PlanningEntity with a list of Customer instances to visit. The @PlanningListVariable enables the use of a few build-in shadow variables:

  • @InverseRelationShadowVariable that points from the Customer to the assigned Vehicle.

  • @PreviousElementShadowVariable and @NextElementShadowVariable that point to the previous and the next customer in the list respectively.

To calculate the arrival time at each customer, the model relies on the arrivalTime shadow variable that is updated by the ArrivalTimeUpdatingVariableListener every time the previousCustomer or the vehicle changes.


The constraints are implemented using the Constraint Streams API and you can see them in the VehicleRoutingConstraintProvider.java.

Service must be finished in time

Providing the service to the customer also takes time, expressed by the serviceDuration. Of course, the service duration counts towards the customer’s availability. This is a hard constraint.

protected Constraint serviceFinishedAfterDueTime(ConstraintFactory factory) {
    return factory.forEach(Customer.class)

Minimize travel time

This is a soft constraint that penalizes the time spent driving per every vehicle, knowing the distances between individual locations.

protected Constraint minimizeTravelTime(ConstraintFactory factory) {
    return factory.forEach(Vehicle.class)

Wait a second, where do we make sure we don’t arrive too early? The serviceFinishedAfterDueTime constraint does it for us, just indirectly. The more time vehicles spend waiting, the fewer customers they can visit without arriving too late.

Try for yourself

  1. git clone [email protected]:timefoldai/timefold-quickstarts.git

  2. cd timefold-quickstarts/use-cases/vehicle-routing

  3. mvn quarkus:dev

  4. Open a browser and navigate to http://localhost:8080

  5. Click on the solve button

If you want to try your own dataset, use the REST API. Click the Guide in the top-level menu to learn how to get started.


The vehicle routing with time windows is a more practical variation of VRP, which we might translate to domains like field service technician or last mile delivery. You can solve all these using Timefold Solver.

Continue reading

  • Red Hat: OptaPlanner End Of Life Notice (EOL)

    Timefold, led by former core OptaPlanner engineers, offers a seamless transition with extended support and accelerated innovation.

  • Newsletter 4: A big Speed Upgrade for Timefold - Our First Customer Story and AMA!

    Unlock unprecedented speed with Timefold's latest update! Essential for OptaPlanner and pre-1.8.0 users – upgrade now for instant gains

  • How fast is Java 22?

    Explore the performance of Java 22 against Java 21, this time also with GraalVM.

  • Continuous Planning Optimization with Pinning

    Discover how to make non-disruptive, feasible adjustments to your already in-progress plans with Timefold, ensuring real-time adaptability to unexpected changes.

  • Fast Planning Optimization with the Recommended Fit API

    Discover how Timefold's Recommended Fit API offers swift, feasible adjustments to your plans, ensuring real-time adaptability to unexpected changes.

  • Newsletter 3: Explainable AI for Planning Optimization

    Discover how Timefold's ScoreAnalysis API builds trust in automated planning. And don't forget to join Timefold's first AMA on Youtube Live on March 19th!

Sign up for our newsletter

And stay up to date with announcements, the latest news, events, roadmap progress & product updates from Timefold!

We care about the protection of your data. Read our Privacy Policy.