Analyzing Unscheduled Orders

This sample describes how to analyze the reason, why an order remains unscheduled by the xTour service.

Benefits

• Users learn how to use and integrate the operations of xTour that analyze unscheduled orders.

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

• Session Storage
• Unscheduled Orders

Programming Guide

This example provides information on how to analyze unscheduled orders to find out why they remained unplanned or if the orders are unplannable.

After passing a PlanToursRequest to the planTours operation of the xTour service, a number of orders may remain unplanned. As preparation for the analysis of the unscheduled orders, the plan must be stored using the field storeRequest in the PlanToursRequest. The analysis itself depends on whether the orders are unplanned or unplannable.

Analyze unplanned orders

For an unplanned order whose id is in orderIdsNotPlanned, but not in orderIdsNotPlannable, we can simply send an InsertionPositionsForOrdersQuery. The field orderIds contains the id of the order to analyze. Note that only one order can be analyzed at a time. If you leave targetVehicleIds empty, then all possible insertion positions for all vehicles are proposed. As we expect all insertion positions to be violated, returnViolatedTours has to be set to true.

The resulting proposals contain MoveOrdersActions and AddTripActions. Each proposal only contains the changed tour. The corresponding TourViolationReport contains the violations occurring when inserting the order at the given position. We can use this report to find out what prevented the order from being scheduled. As the order is unplanned but not unplannable, an additional vehicle would always be a feasible way to schedule the order.

The following sample contains a simple way of aggregating the violations in the proposals to find out whether the planning horizon or the opening intervals are the reason for an order being unplanned. You can modify the initial plan by changing useShortPlanningHorizon:

• Set useShortPlanningHorizon to true, so that an order cannot be planned because of the planning horizon being too short.
• Set useShortPlanningHorizon to false, so that an order cannot be planned because of an opening interval being too short.

Analyze unplannable orders

Contrary to the previous part, unplannable orders cannot be served using additional vehicles. For a reasonable analysis, we need a plan without tours, so that we can find out the reason for the order being unplannable even if the vehicles do not serve any other order.

In the following sample, the request contains an order with a 20-hours service time. Even a completely empty vehicle cannot serve the order, because the planning horizon only has a length of 8 hours. After planning, the id of the unplannable order is in orderIdsNotPlannable. In function createSingleOrderPlan a plan is created which only contains the unplannable order. Function analyzeUnplannableOrders then runs an InsertionPositionsForOrdersQuery like before. Only one AddTripAction per vehicle is created. We again have a look at the TourViolationReport to find out the reason for the order to be unplannable, which in this example is the planning horizon being too short.

Limiting the resulting number of proposals of an InsertionPositionsForOrdersQuery

Running an InsertionPositionsForOrdersQuery yields all possible insertion positions for the given order. While the number of AddTripActions is limited by the number of vehicles and existing trips, many more MoveOrdersActions may be proposed, depending on the size of the plan.

Therefore, you can limit the number of MoveOrdersActions using the field maximumNumberOfMoveOrdersActions so that at most the given number of nearest insertion positions are returned.

Additionally, you can limit the proposed MoveOrdersActions using maximumDistanceOfAdjacentStops to a certain area around the customer site of the given order (or in case of a depot-depot transport to an area around both depot sites). Only stops in this area may be used as neighboring stops for the insertion.