Restricting Start and End of Tours

This sample describes how to restrict start and end of tours planned by the xTour service.

Benefits

Users learn how to use and integrate the parameters of xTour that restrict start and end time of tours.

Prerequisites

Please ensure following prerequisites are fulfilled before you start with the use case:

Installed and licensed PTV xTour service
License for as many vehicles The term vehicle describes what is being routed or planned for. Vehicles are used in route calculation, distance matrix calculation and effectively also in tour planning. In route calculation, vehicle properties like overall size, weight and speed are in focus. In tour planning, it is vehicle properties like capacity and availability. Commonly a vehicle is motorized, like a truck - including its trailer or a car. However also a bike or even a pedestrian are included in this definition. as the plan should contain

Concepts

Tours and Trips

Planning Horizon

The field planningHorizon restricts start and end time of all tours. All opening intervals that are outside of this planning horizon will not be considered for the automatic tour planning.

However it can happen that an input tour cannot be planned within the planning horizon. In this case the tourViolations of tour events outside of the planning horizon (either starting before the planning horizon or ending after it) will contain a violation of type TourViolationType.PLANNING_HORIZON. In the TourViolationReport the duration of the exceedance is stored in planningHorizonExceedance.

Operating Intervals of the Driver

Furthermore, start and end time of a specific tour can also be restricted through the operatingIntervals of the Driver. The driver is assigned to a specific vehicle and if a tour is served by that vehicle, it has to respect the driver's operating intervals. In automatic tour planning these restrictions will always be met.

However it can happen that an input tour cannot be planned within the operating intervals of the driver. In this case the tourViolations of tour events outside of the operating intervals will contain a violation of type TourViolationType.OPERATING_INTERVAL. In the TourViolationReport the duration of the exceedance is stored in operatingIntervalExceedance. A tour never starts before the operating interval start. If the planning horizon does not overlap with the driver's operating intervals, the operating intervals are considered more important because they are the more specific parameter.

Programming Guide

This example explains how the request has to look like in order to influence the start and end time of tours as mentioned in the use-case description above. If you are interested in a more detailed description of the below defined request fields, please have a look at our other integration samples, for example Planning a Round Trip.

As use-case-specific fields we first define a planningHorizon from 8 a.m. to 4 p.m. on the 13th of april 2018 as part of a PlanToursOptions object.

Then we introduce two drivers, one working from 9 a.m. to 11 a.m. on 13th of april 2018, the other one working from 1 p.m. to 3:30 p.m. on 13th of april 2018 (assuming having two vehicles with id's "vehicle_1" and "vehicle_2").

We consider two visit orders at sites restricted by opening intervals. The first order requires one hour service time and can only be executed at the site between 8 a.m. and 10 a.m. The second order can only be executed from 2 p.m. to 4 p.m. and also requires one hour service time.

We pass the request on to planTours. Once xTour has processed the request a callback is invoked which gives us access to the result of the calculation in form of a ToursResponse object.

The customer sites of the request are displayed in gray, the depot sites in orange. Since the ToursResponse only contains references to the given locations, the corresponding coordinates are taken from the request. The first tour of the result is displayed in gray, the second one in blue.

Both vehicles start their tour at the depot (orange circle) and also end it there. Since no driver can serve both orders within its operating interval and within the given opening intervals of the sites, both vehicles need to conduct a tour.

In the following image you can see the different restrictions on the tours in an overview.

Time Restrictions

In the above example, the planning horizon is set wide enough to not interfere with both tours. If you set its end more restrictive as described in the commentary next to the definition of the planning horizon, it is not possible anymore to serve the second order within its site's opening intervals, the driver's operating interval and the planning horizon. So the second order stays unplanned.

Instead you can also extend the end of the first driver's interval as described in the commentary next to the definition of the driver. As the driver is now working long enough to serve both orders, it is possible to plan only one tour leaving the second vehicle unplanned.