Compound Zones: Setting Entry and Exit Time Penalties

Certain delivery or pickup areas, like large industrial parks, gated communities, or restricted city centers, require additional time simply to enter or exit the area, regardless of the specific stop location within it. These "compound zones" might involve navigating security gates, internal road networks, or specific traffic patterns. This model is supported by SWAT APIs using a compound_zones parameter to add these time penalties.

Compound zones significantly enhance the modeling of vehicle routing problems by incorporating a fixed, aggregate service time for all orders within a specified geographical area. This aggregate service time, applied in addition to the individual service times for each individual order, accurately reflects real-world scenarios where vehicles require a substantial amount of time at a location regardless of the number of individual pickups or drop-offs. A prime example of this is the docking time needed at a warehouse or distribution center. Instead of simply summing the individual service times for each package picked up or dropped off, the compound zone model accounts for the overhead associated with entering, operating within, and exiting the zone. This overhead might include time spent navigating the facility, interacting with personnel, or performing necessary logistical tasks before and after individual order processing. The fixed service time associated with the compound zone provides a more realistic and comprehensive representation of the total time commitment required at that location, leading to more accurate and efficient route optimization. This feature is particularly valuable when dealing with complex logistics networks where fixed operational constraints, such as loading dock availability or mandated security procedures, significantly impact overall vehicle routing efficiency.

Compound Zone Penalties:

Compound zone penalties define a fixed time cost incurred when a vehicle's route transitions into or out of a designated zone. Enter and exit time required for a compound zone are applied to the travel time required to reach out the drop off or pickup location.

• Entry Time: A time penalty added when a vehicle arrives at the first stop (or order) within a specific zone sequence, having come from outside that zone.
• Exit Time: A time penalty added after the vehicle completes service at the last (or order) within that specific zone sequence, before proceeding to a destination outside the zone.

These penalties apply once per contiguous sequence of stops within the zone. If a vehicle enters a zone, visits multiple stops inside, and then leaves, it incurs one entry penalty and one exit penalty for that sequence.

Examples:

• Gated Community: A driver might spend 5 minutes waiting/clearing security at the entrance (entry time) and 3 minutes navigating back to the main road upon leaving (exit time).
• Large Industrial Park: Navigating the internal road network to reach the first delivery point might take 10 minutes (entry time), and leaving the park from the final pickup point takes another 8 minutes (exit time).
• Restricted Downtown Area: Entering a pedestrian-priority or low-emission zone might involve specific access procedures taking 5 minutes (entry time), with similar time needed to exit.
• Docking time for a vehicle: Time required to dock or undock a vehicle before or after load operations can occur.

Conceptual Example:

A delivery company has stops within a large campus (Zone A) and outside it.

• Stop 1: Outside Zone A
• Stop 2: Inside Zone A
• Stop 3: Inside Zone A
• Stop 4: Outside Zone A

A possible route sequence: Depot -> Stop 1 -> Enter Zone A (Add Entry Time Penalty) -> Stop 2 -> Stop 3 -> Exit Zone A (Add Exit Time Penalty) -> Stop 4 -> Depot.

The entry penalty is added before arriving at Stop 2, and the exit penalty is added after departing from Stop 3.

Implementation

Compound zones and their associated entry/exit times are configured within the model_parameters.compound_zones section of the API request. Nodes (stops) are associated with a zone by assigning them a specific group.

compound_zones is an array where each object defines:

• group: The identifier linking nodes to this specific compound zone.
• entry_time: The time penalty (in seconds) added when entering the zone.
• exit_time: The time penalty (in seconds) added when exiting the zone.

Nodes intended to be part of a compound zone must include the corresponding group identifier in their groups list.

Instead of using groups it is also possible to explicitly set node_uids to be assigned to a compound zone for a more granular control in cases groups are used for other settings like

"model_parameters": {
  "compound_zones": [
    {
      "groups": ["IndustrialParkA","IndustrialParkB"],
      "enter_time": 600, // 10 minutes
      "exit_time": 480   // 8 minutes
    },
    {
      "node_uids": ["45188b13-e91d-4d41-95fa-9cde22767231"],
      "enter_time": 300, // 5 minutes
      "exit_time": 180   // 3 minutes
    }
  ]
},
"nodes": [
  {
    "uid": "stop1_park",
    "groups": ["IndustrialParkA", "priority_deliveries"],
    "lat": ..., "lon": ..., "service_time": 300, ...
  },
  {
    "uid": "stop2_park",
    "groups": ["IndustrialParkA"],
    "lat": ..., "lon": ..., "service_time": 450, ...
  },
  {
    "uid": "stop3_gated",
    "groups": ["GatedCommunityX"],
    "lat": ..., "lon": ..., "service_time": 200, ...
  },
  {
    "uid": "45188b13-e91d-4d41-95fa-9cde22767231",
    "groups": ["priority_deliveries"],
    "lat": ..., "lon": ..., "service_time": 150, ...
  }
]

The routing engine automatically identifies sequences of nodes belonging to the same compound zone group within a vehicle's route. When a vehicle travels from a node not in group X to a node in group X, the entry_time for group X is added to the travel time before arriving at the first node in that group X sequence. When a vehicle travels from a node in group X to a node not in group X, the exit_time for group X is added to the travel time after departing the last node in that group X sequence.

Configuration via Integration API

When using the Integration API, compound zones can be defined implicitly by configuring calculation_params on operations_location objects. The system automatically converts these settings into compound zones for the routing engine, grouping all nodes (orders) associated with that location.

Example calculation_params JSON:

{
  "exit_time": {
    "fixed": 300
  },
  "enter_time": {
    "fixed": 300
  },
  "coefficients": {},
  "service_time": {
    "fixed": null
  },
  "cumulative_limitation": null
}

In this configuration:

• enter_time.fixed: Sets a fixed entry time (in seconds).
• exit_time.fixed: Sets a fixed exit time (in seconds).

When these parameters are set, the system creates a compound zone containing all nodes assigned to that operations_location_id.

Edge Case: Duplicate Locations

If you define multiple operations_location entries that share the same physical coordinates (latitude/longitude) but have different IDs, the system treats them as separate compound zones.

Scenario:

• Location A (Coords: X, Y) has exit_time = 300s.
• Location B (Coords: X, Y) has enter_time = 300s.
• Route: Stop at Location A -> Stop at Location B.

Even though the travel distance is effectively zero, the solver sees a transition between two distinct compound zones:

1. Vehicle exits Location A's Zone (Apply Exit Penalty).
2. Vehicle enters Location B's Zone (Apply Entry Penalty).

Total Penalty: Exit Time (A) + Entry Time (B).

This results in a double penalty application. To avoid this, ensure that orders at the same physical place share the same operations_location_id, or account for this cumulative effect in your time settings.

Group vs. Individual Location Application

When using the Operations Locations model, you can define compound zones at two levels: the Operations Location Group level and the individual Operations Location level. It is crucial to understand how these settings interact.

Group-Level Application

When enter_time or exit_time are configured on an OperationsLocationGroup, the system treats all locations belonging to that group as a single compound zone unit.

• Behavior: The penalty is applied only when the vehicle enters or exits the entire group of locations.
• Use Case: A large industrial estate (the group) containing multiple specific loading docks (the locations). You incur an entry penalty when entering the estate, visit multiple docks without further entry/exit penalties, and incur an exit penalty only when leaving the estate.

Location-Level Application

When enter_time or exit_time are configured on an individual OperationsLocation, a compound zone is created specifically for that location.

• Behavior: The penalty is applied when the vehicle enters or exits that specific location.
• Use Case: A specific secure facility that requires a check-in procedure every time, even if coming from a nearby location.

Nested Application (Simultaneous Configuration)

If enter_time or exit_time are defined at both the Group level and the Individual Location level, the system applies both sets of limitations cumulatively. This results in a "nested" compound zone structure.

Example Scenario:

• Group G has enter_time = 10 minutes (Campus Gate).
• Location L1 (in Group G) has enter_time = 5 minutes (Building Security).
• Route: Outside -> Location L1.

Resulting Penalty:

1. Vehicle enters Group G's Zone: +10 minutes.
2. Vehicle enters Location L1's Zone: +5 minutes. Total Entry Penalty: 15 minutes.

note

This cumulative behavior allows for modeling complex hierarchies, such as a secure campus (Group) containing individual high-security buildings (Locations). However, be careful to avoid unintentional double penalties if you only intended to override the group setting.

Special Cases and Considerations

Travel time includes entry and exit penalties. This can affect feasibility if a vehicle's arrival at a zone's first stop, including the entry penalty, falls outside the stop's time window. The penalties are not shown separately in the optimization results; they're implicitly added to the travel time between stops.

Related Constraints

• Fixed Location Service Time: Using compound zones (specifically exit_time) to model a fixed service duration (e.g., docking time) at a location, independent of the number of orders. This is a common application of the compound zone concept.