Skip to main content

Driver breaks

Both the SWAT Optimization API and Integration API support driver breaks, allowing dynamic allocation to align with operational needs or legal requirements. For example, Route Optimization can incorporate the length of required breaks after specific driving durations into its execution plan while respecting other set constraints. Two main use cases apply, which can be used in a mutually exclusive manner when simulating the addition of driver breaks to optimization:

  • Single driver break for a vehicle trip
  • Multiple driver breaks for a vehicle trip

Parameters discussed below can be configured via both the Optimization (Stateless) API payload, where they are applied directly to a vehicle object api, and the Integration (Stateful) API, where they are set on the Vehicle resource, for example during bulk vehicle upload via /api/v2/microservices/bulk/task api.

{
  "agent_id": "78e07d0f-abbc-4c7d-921e-54ba7bab1041",
  "capacity": {
      "goods": 13
  },
  "characteristics": {},
  "lat": 1.3309909478620003,
  "lon": 103.86845911685897,
  // Single and multi break case
  "dynamic_break_duration": 3600,

  //  Single break case
  "dynamic_break_min_path_duration": 120,
  "dynamic_break_start_time": "2019-08-24T14:15:22Z",
  "dynamic_break_end_time": "2019-08-24T14:15:22Z",

  // Multi break case
  "dynamic_break_avg_time_between_breaks": 360,
  "dynamic_break_max_latency": 0,
  "max_pickup_locations": 10
}
tip

The planned driver break is ultimately added to the node's slack and is regarded as standard slack (waiting time) at a node for route optimization purposes.

Setting dynamic_break_avg_time_between_breaks to a specific value determines whether to use single or multiple driver break mode. When this value is unset, single driver break is applied. Otherwise, multiple breaks mode is applied. Driver breaks are applied at the node level, not the booking level.

Driver breaks are permitted only at nodes

assigned to the vehicle. The time allocated for driver breaks is added to the node's slack time. The break node is selected from one of the nodes in the path with the greatest slack. The break node cannot be the first or the last in the path. If slacks are identical, the break node is selected to be as close as possible to the middle of the path in prebook_cvrptw mode or to have minimal possible demand in prebook mode.

warning

Driver break is a hard constraint. If a requirement to have an allocated driver break is in force, some bookings may be refused if they are no longer meeting additional time constraints assumed by the driver break.

Single break​

Single break scenario assumes that there is only one or no break allowed for a single vehicle trip (optimization run) for a vehicle. Driver break is managed by four parameters:

  • dynamic_break_duration in seconds
  • dynamic_break_min_path_duration in seconds
  • dynamic_break_start_time as date\time stamp
  • dynamic_break_end_time as date\time stamp

Conditions for adding a break​

A break will be added if either one of these conditions is met:

  1. The path duration (combined vehicle travel time, nodes' slack time, and nodes' service time) exceeds dynamic_break_min_path_duration.
  2. dynamic_break_min_path_duration is not set, but dynamic_break_duration is set.

If the vehicle path has only a single node, no driver break will be added.

Break placement​

The solver will try to place the break at the midway point of the total trip duration & bias toward nodes with long slack time.

If dynamic_break_end_time is set, the solver will try to add a break before dynamic_break_end_time - dynamic_break_duration.

info

The exact start time of the break is determined by the solver. The solver ensures that the full break duration fits within the constraints. For example, if both dynamic_break_start_time and dynamic_break_end_time are specified, the break will start no earlier than dynamic_break_start_time and end no later than dynamic_break_end_time.

Scenarios​

Possible permutationsUsecase
Only dynamic_break_durationMandatory Wellness Break: A standard break assigned to every trip to ensure driver well-being, regardless of trip duration.
dynamic_break_duration with dynamic_break_start_timeScheduled Lunch: A meal break that follows a schedule, such as "Lunch cannot be taken before 11:30 AM", ensuring coverage during morning peaks.
dynamic_break_duration with dynamic_break_end_timePre-Peak Rest: A break that must be completed before a critical time window, like finishing a rest period before the 5:00 PM evening rush hour begins.
dynamic_break_duration with dynamic_break_min_path_duration & dynamic_break_start_timeLate Shift Rest: A break conditioned on a long shift (e.g., > 6 hours) that is pushed to the latter half of the day (e.g., starts after 2:00 PM). Note: The break is placed after the start time even if the minimum path duration is met earlier.
dynamic_break_duration with dynamic_break_min_path_duration & dynamic_break_end_timeWindow-Constrained Long Haul: A break for long trips that must occur within a specific service window, such as using a rest facility before it closes. Note: The end time constraint is respected even if it forces the break before the minimum path duration is fully met.

The dynamic_break_start_time and dynamic_break_end_time parameters define a time window within which the driver break can be scheduled. It's possible to specify only the maximum or minimum time boundary, in which case only that constraint will be enforced.

Multiple breaks​

Multiple break scenario assumes that there could be multiple, one or no breaks allocated to a vehicle for a single trip (optimization run). Driver break is managed by three parameters in this case:

  • dynamic_break_avg_time_between_breaks in seconds
  • dynamic_break_duration in seconds
  • dynamic_break_max_latency in seconds

The dynamic_break_duration parameter specifies the duration of the breaks that should be scheduled. Each planned break will have the same duration.

The dynamic_break_avg_time_between_breaks parameter governs the maximum average time a vehicle can drive without a break. It encompasses the cumulative vehicle travel time, node slack time, and node service time in its computation. There is no prescribed minimum interval between breaks, thereby allowing for multiple consecutive breaks at the same node.

Using dynamic_break_max_latency, a driver's break constraint can be transformed into a more flexible constraint that tolerates tardiness. This value specifies the maximum allowable delay for the break.

Interpreting results​

Optimization (Stateless) API​

In the Optimization (Stateless) API, drivers' break schedules can be found within the vehicle assignments list, which enumerates all nodes assigned to a vehicle api.

warning

A booking requires association with two nodes (pickup and drop-off). Due to route optimization, a vehicle may perform multiple pickups and drop-offs. Consequently, vehicle route assignment is handled at the node level. The Optimization (Stateless) API provides a sequential list of nodes assigned to the vehicle, not bookings.

The following example showcases two breaks assigned at a single node. The response indicates dynamic_break as true and details the total break duration in dynamic_break_time (e.g., 7200 seconds for two 1-hour breaks). The break_start_ts provides a list specifying the exact start timestamps for each break. The value denoted by slack signifies the overall waiting time at that particular node, which in this instance incorporates the total dynamic_break_time plus any remaining standard node slack.

{
  "booking_uid": "some_booking", // Booking UID this node belongs to
  "dynamic_break": true,
  "dynamic_break_time": 7200,
  "break_start_ts": [
    "2022-08-01T15:30:00.000000+00:00",
    "2022-08-01T17:30:00.000000+00:00"
  ],
  "lat": 30.0,
  "location_code": null,
  "location_name": null,
  "lon": 130.0,
  "matrix_timestamp": null,
  "node_type": "pickup",
  "scheduled_cumulative_distance": 0,
  "scheduled_ts": "2022-08-01T14:34:18.600504+00:00",
  "service_time": 0,
  "slack": 18349.5,
  "stop_id": "warehouse",
  "uid": "some_uid" // This node's UID
}

If dynamic_break is set to null or false, no break is scheduled at that node.

Integration (Stateful) API​

In the Integration (Stateful) API, drivers' break schedules are returned within the break_info property of the Node object (e.g., when retrieving routes or simulation results).

Instead of flat fields like dynamic_break and break_start_ts, the stateful API groups all break segments under break_info.driver_break_list. Each entry in this list specifies the exact start_time and duration of the break applied at this node. Standard waiting time is still accounted for separately on the node, but the break details are explicitly segregated here for easier parsing.

{
  "uid": "some_node_uid",
  "node_type": "pickup",
  "break_info": {
    "driver_break_list": [
      {
        "start_time": "2022-08-01T15:30:00Z",
        "duration": 3600
      },
      {
        "start_time": "2022-08-01T17:30:00Z",
        "duration": 3600
      }
    ]
  },
  "close_time_offset": 18349
}

If no break is scheduled at a node, the break_info property will be null or contain an empty driver_break_list.

warning

Because the exact start times of the driver breaks are calculated as a post-processing step rather than being exhaustively embedded inside the core routing engine solver, there can occasionally be edge cases in highly constrained scenarios. The main solver correctly reserves the necessary time block continuously as node slack and guarantees the minimum breaks can fit within the route. However, the exact granular break placement timestamps within that slack are resolved sequentially after the macro route is generated, which can occasionally cause alignment discrepancies or suboptimal exact timestamps if multiple rigid constraints overlap tightly.

FAQ​

Some common use cases are explained below

Q: How do I model a situation where a driver has to take a 30-minute break when a trip exceeds 4 hours, assuming there's only one driver break during the trip?
A: The vehicle assigned to the driver must have the following parameters configured. If the planned vehicle path is less than four hours, no breaks will be scheduled. Additionally, breaks can be allocated at any point along the path (attached to a node) because start and end-time constraints are not set.

{
// ...
"dynamic_break_duration": 1800,
"dynamic_break_min_path_duration": 14400
// ...
}

Q: Can you provide examples of scenarios involving multiple driver breaks with varying slack and service times, given that the break duration (dynamic_break_duration) is set to 30 minutes and the time between breaks (dynamic_break_avg_time_between_breaks) is set to 4 hours?
A: Please see the following time diagrams

Scenario 1: Travel 5h​

Scenario 2: Slack 5h + Travel 5h​

Scenario 3: Slack 2h + Travel 3h​

Scenario 4: Service 1h + Slack 1h + Travel 3h​

Scenario 5: Multi-stop​

Playground​

You can try out the Driver Break concept using the playground below. The example defines a vehicle with a dynamic_break_duration of 3600 seconds (1 hour).

Loading...