Route Sequence Locking

Route Sequence Locking is a constraint that "locks" the sequence of a certain portion of a vehicle's currently assigned route. It fixes the sequence of upcoming stops, ensuring that new insertions or rerouting do not alter the driver's immediate itinerary.

This feature is designed for dynamic dispatching scenarios, guaranteeing that drivers are not subjected to sudden re-sequencing or unexpected new stops just as they are heading to their imminent destinations.

Value in the Planning Process

In real-time operations, continuously re-optimizing a route as new orders come in can be highly disruptive to drivers on the ground. For instance, if a driver is 10 minutes away from a stop, inserting a new pickup 5 minutes away forces them to abruptly change direction.

Activating Route Sequence Locking provides significant stability by:

• Preventing immediate disruptions: Ensures the driver's immediate upcoming sequence is fixed and untouched.
• Improving driver experience: Eliminates the confusion of sudden route changes while the driver is already navigating.
• Controlled insertions: Allows new bookings to be inserted only after the protected time window or after a specific number of locations have been visited.

How Route Sequence Locking Works

The protection mechanism works by enforcing a "protection time interval" over the vehicle's timeline. Any scheduled nodes that fall strictly within this interval are locked in their current sequence. The routing engine is prohibited from inserting new stops before or between these protected nodes.

You can define and restrict this protection using two main vehicle-level parameters:

• assigned_nodes_protection_interval (seconds): The duration of the time interval during which the insertion of new nodes is inherently prohibited. The engine locks all assigned nodes whose scheduled times fall within this window.
• assigned_nodes_protection_max_locations: A strict limit on the maximum number of unique physical locations to protect. Rather than a pure time-based lock, this locks the subsequent X geographical locations. Consecutive stops sharing the exact same latitude and longitude coordinates count as a single location boundary.

ヒント

These parameters can be overridden globally across all vehicles or set per individual vehicle in the Optimization API payload to cater to different operational requirements (e.g., locking 30 minutes ahead for cars, but 1 hour ahead for trucks).

Protection Interval Mode

The baseline starting point from which the assigned_nodes_protection_interval is calculated is dictated by the global engine setting assigned_nodes_protection_interval_mode.

There are two available modes:

• current_time (Default): The protection interval begins exactly at the current time (the min_timestamp or the start of the optimization run). Any node assigned to the vehicle falling within current_time + assigned_nodes_protection_interval is locked.
• last_bound_node: The protection interval begins at the scheduled timestamp of the last bound node in the vehicle's partial route. This is useful when you want to guarantee a certain duration of unbroken route sequence continuing directly after a previously committed fixed route.

警告

If a new booking's delivery time window is extremely tight and the only efficient sequence would normally require inserting it between the vehicle's protected nodes, the order will be rejected as unroutable because the Route Sequence Locking constraint strictly prevents that insertion.

Implementation in APIs

Route Sequence Locking can be configured through both the Optimization (Stateless) API and the Integration (Stateful) API.

Optimization (Stateless) API

In the Optimization API api, the individual intervals and maximum location limits are attached natively to the vehicles objects inside the payload. The mode setting evaluating the start of the interval baseline is configured globally underneath engine_settings.

{
  "vehicles": [
    {
      "agent_id": "vehicle-1",
      "assigned_nodes_protection_interval": 1200, 
      "assigned_nodes_protection_max_locations": 3
    }
  ],
  "engine_settings": {
    "model_parameters": {
      "assigned_nodes_protection_interval_mode": "last_bound_node"
    }
  }
}

In this scenario, for vehicle-1, the engine locks a maximum of 3 unique physical locations mapping to any assigned nodes scheduled within a 20-minute (1200 seconds) window starting from the last bound node.

Integration (Stateful) API

In the Integration (Stateful) API, the parameters for assigned_nodes_protection_interval and assigned_nodes_protection_max_locations are defined directly on the Vehicle resource objects. These configurations can be passed to the backend, for example, during vehicle creation or updates via bulk uploads /api/v2/microservices/bulk/task api.

The protection mode baseline assigned_nodes_protection_interval_mode is managed continuously at the optimization engine parameter level.

Below is an example snippet representing a vehicle payload in the Integration database:

{
  "name": "driver_john",
  "assigned_nodes_protection_interval": 1800,
  "assigned_nodes_protection_max_locations": 5,
  "capacity": {
    "goods": 20
  }
}