Lateness Configuration

In typical logistics operations, strict adherence to time windows is essential. However, real-world conditions often require flexibility. In the context of the solver, "lateness" (or time window violations) does not solely mean computing an arrival after a location's closing time (close_time_ts). It also encompasses arriving before the opening time (open_time_ts), as an early arrival may force the vehicle to perform a service outside of its planned bounds. The logistics API provides granular configuration options to handle these time window violations gracefully at both the simulation level and the individual vehicle level.

Common Logistics Industry Use Cases

Time constraints rarely survive contact with live operations. Configuring lateness flexibility properly is critical for the following real-world workflows:

1. Traffic and Operational Delays (Late Arrival): A driver encounters a severe traffic jam or a previous unloading takes twice as long as expected. Instead of the solver completely rejecting downstream nodes because they suddenly violate their close_time_ts windows, enabling lateness allows the solver to calculate realistic (albeit late) ETAs and keep the route structurally valid.
2. Early Arrivals (Before Open Time): A driver makes excellent time and arrives at a distribution center before staff complete their shift turnover or open the receiving docks (open_time_ts). If time windows are strictly enforced, the solver might insert artificial wait time or reject the sequence. With lateness/earliness flexibility, the solver permits the sequence and processes the violation smoothly, reflecting how dispatchers routinely allow early operations in the real world.
3. Forced VIP Live Insertions: A dispatcher forcibly injects a high-priority "VIP" booking into a driver's live, ongoing route. This insertion might push subsequent, previously promised stops past their closing times. In a strict solver setup, the VIP insertion would be rejected to preserve downstream constraints. By selectively allowing lateness on pre-assigned nodes, the dispatcher can push the new VIP order into the route and let the solver adapt without failing.

Simulation Configuration

To enable the solver to find valid routes even when vehicles exceed node time windows, you can configure lateness parameters globally for the simulation via simulation.data.logistics_api_settings:

• allow_vehicle_late A boolean flag allowing the solver to compute routes with vehicles arriving after the node's close_time_ts. When enabled, the solver exchanges lateness for route efficiency.

• vehicle_late_penalty_coefficient When allow_vehicle_late is enabled, this coefficient dictates how heavily the optimization engine penalizes late arrivals in comparison to other cost components (like distance or travel time).

• manual_edit_allow_vehicle_late This parameter determines if a manual edit function will bypass standard time windows validations if the vehicle forces an entry that causes lateness downstream.

• max_possible_lateness Sets the upper bound for how late a vehicle can arrive at any given node. If the computed arrival time is later than the time window close plus this value, the insertion is considered invalid.

For the full list of configurable properties on the simulation object, refer to the Logistics API Settings documentation.

Vehicle Configuration

Sometimes, you need to allow a vehicle to be late strictly on the nodes already assigned to it, preventing the solver from rejecting insertions due to cumulative lateness on the ongoing route.

• allow_late_on_assigned_nodes A boolean flag available directly on the Vehicle entity. Setting this to true allows the vehicle to be late on all nodes that are pre-assigned (assigned_nodes). This prevents active nodes outside their time windows from crashing the model or blocking live insertions into the vehicle's remaining route.

  warning

  Enabling this flag only applies to time windows on pre-assigned nodes. It does not allow time window violations for the vehicle's overall start_time and end_time constraints.

Early Online Vehicles in Manual Edits

During manual edits with live vehicles, time constraints can sometimes become infeasible if a vehicle goes online before its configured start_time. This early vehicle_position conflicts with the vehicle.start_time setting. To avoid optimization failures and "no-offer" responses during booking assignments, the solver is designed to silently ignore vehicle.start_time whenever a vehicle is already live (i.e., has a vehicle_position node assigned). This ensures a seamless manual edit workflow even when vehicles arrive or go online earlier than planned.

By strategically adjusting these parameters and leveraging the system's live-vehicle handling, you ensure that the solver appropriately reflects real-world delays without collapsing the entire schedule constraints.