FAQ

This document contains a list of some frequently asked questions about SWAT APIs.

Optimization and Integration API

This section contains questions and answers related to the Optimization API and Integration API

What are the different responses for GET /api/v1/node_scheduler/{job_id}/status? What are the responses when calculations are still running, and when there is an error?

Answer

The endpoint offers three statuses pertaining to the asynchronous job in the status field:

• PENDING: Indicates that the calculation is in progress.
• FAILED: Signifies that the calculation failed.
• SUCCESS: Signifies that the calculation succeeded.

Consumers are expected to periodically poll this endpoint (approximately every 5 seconds) and wait until the PENDING state transitions to either SUCCESS or FAILED. They can then retrieve the results using the endpoint .

What should be set for the calculation time for Solver Parameter time_limit_ms? What is the unit for this parameter?

Answer

The unit is milliseconds. The recommended calculation time varies based on the number of vehicles and orders, as well as their complexity. Typically, the calculation time should fall within a range of 2 to 60 minutes, depending on the scale of the problem and the desired quality of the solution (longer calculation times generally yield better results).

How do you set a service time where regardless of the number of orders picked up or dropped off, the service time remains the same?

Answer

To specify fixed service time for a group of nodes, you can use compound_zones in the Model Parameters object. Compound zones

is a list of zones that among other properties have enter_time and exit_time needed to enter or exist that zone which are specified in seconds.

To set the same fixed operating time at the loading port, use the following settings for the node object in the request body where uid is set to loading port 1 or loading port 2:

{
  "compound_zones": [
    {
      "node_uids": ["loading port 1", "loading port 2"],
      "exit_time": 300
    }
  ]
}

The following diagram represents time parameters applied to a node

. The compound zone time is not directly reflected in vehicle node assignments (compared to slack) since it's added to travel time to ensure optimization of routes based on minimal time required to enter\exist a zone (compare to service time which is a fixed time constraint for a node).

What is the model for the demand and capacity between nodes and vehicles? If there are multiple dimensions, how do I set them up?

Answer

Demand refers to the quantity of goods or services that needs to be delivered to a particular customer or location. Capacity refers to the maximum amount of goods, services, or people that a vehicle can carry. Vehicle capacity acts as a limit on the amount of demand that can be satisfied by a single vehicle. A vehicle cannot carry more than its capacity, so the total demand assigned to a route must always be less than or equal to the vehicle's capacity.
Demand drives the need for vehicles and routes. The total demand across all customers determines the number of vehicles required and how those vehicles are routed to efficiently meet the demand.

VRP algorithms must carefully balance capacity and demand to create feasible and efficient solutions. The goal is to assign customers to vehicles and routes in a way that respects capacity constraints while minimizing travel distance, time, and cost.

Node types pickup have a positive demand, while dropoff have a negative demand when constructing the booking. Demand type is an arbitrary string, the demand type for at least one vehicle has to match capacity type for at least one node. Otherwise, this demand type will never be assigned to a vehicle. We recommend maintaining consistency in the dimensions for nodes and vehicles. If a node has an additional dimension not present in the vehicle, the booking cannot be assigned to that vehicle.

"node":
{
  "demand": {
      "goods": 1,  // Node expects 1 piece of goods delivered
      "human": -1  // Node expects 1 human picked up
  }
}

"vehicle":
{
  "capacity":{
    "goods":10, // Vehicle can carry 10 pieces of good
    "human":20, // Vehicle can carry 20 human beings
    "rat":30 // Vehicle can carry 30 rats
  }
}

How can I prioritize delivery by 3 PM whenever possible?

Answer

Delivery windows are controlled by node open_time_ts and close_time_ts. In this example, the drop off node can have close_time_ts set to 3pm. Since by default time window is a strict constraint, this may result in some bookings not being assigned. Alternatively, prioritization can be achieved by using allow_vehicle_late flag and pushing forward close_time_ts.

How do I ensure that unloading times are respected at a drop off point for multiple orders at the same location (unload prior to scheduled depature)?

Answer

The answer assumed some arbitrary timestamps as examples.

The problem statement can be formulated like stated below:

• All orders need to be unloaded before 12pm
• All orders need to be unloaded at the same location
• Each order requires some unload time (for example 5 min, 10min and 15 min for Order 1, 2 and 3)
• Location can accept order between 11am and 12pm

If orders cannot be aggregated, the node.close_time_ts can be adjusted to 12pm - Order 3 Service Time (in this example, specifically 11:45 pm) to ensure sufficient unloading time for the last order. Order 3 is selected for adjustment since it has the longest service time. This would provide enough time to unload Order 3, and since the node is closing at 12 pm, no other orders will be accepted later. As a result, the unloading of Order 1 and Order 2 will be scheduled before Order 3. Please note that the exact sequence will vary depending on the specific lengths of the time windows. However, since it's the same location, it's unlikely to be critically important for operational purposes from a route optimization perspective.

How can I retrieve all nodes/waypoints for a vehicle after the route has been optimized?

Answer

There are multiple ways to retrieve nodes for a vehicle, depending on the desired outcome.

• To retrieve assigned nodes for a single vehicle (sequence of points vehicle is planned to visit) please use /api/v2/vehicle/{vehicle_id}/assigned_nodes
• To retrieve completed nodes for a single vehicle please use /api/v2/vehicle/{vehicle_id}/completed_nodes
• To retrieve completed and assigned nodes for all vehicles in a simulation please use /api/v2/node?simulation={{simulation_id}}&status__in=completed,assigned

How does node grouping work for API /api/v2/vehicle/{vehicle_id}/nodes_grouped?

Answer

Please consider the following example:

• node_grouping_threshold : 5 minutes
• node A: 7:00
• node B: 7:05
• node C: 7:07, 5 min service time
• node D: 7:16, 5 min service time
• node E: 7:27 Assuming that all four nodes are located in the same place, the query will generate a single group for nodes A through D. Grouping logic respects service time required for a node, this is why node D will end up in the same group. If another node, E, with a timestamp of 7:23 is added since (7:27-7:26)>(5 min+5 min service time), node E will be assigned to a different group.

To which object are the vehicle and driver assigned? How can I find which vehicle the booking is assigned to?

Details

Answer

There is an implicit relationship between booking, vehicle, and driver. A vehicle and a driver are assigned to a node, not a booking. In this case, the node represents a physical location where the vehicle will need to go. Each booking must have at least two nodes associated with it: a drop-off node and a pickup node. . In a case of a simple scenario when the items or people are not moved between vehicles while enroute, all nodes for the bookings will have the same driver and vehicle assigned to it.

What is the difference between booking states fail_to_board and fail_to_deliver?

Details

Answer

A booking will be marked as fail_to_board is the driver didn't manage to do a pick up at the first node of the booking, therefore there is nothing to be delivered. In that case, this booking isn't considered in the following execution plan. However, if the driver could deliver goods, the booking state will be set to fail_to_deliver which means that the goods are still in the vehicle and constraints related to the goods have to be met (such as demand and groups).

What does max_slack parameter mean?

Details

Answer

The max_slack parameter for a node specifies the maximum amount of slack allowed at that node. It can be set to 0 if the goal is to eliminate slack at that node. Use this parameter carefully because requiring zero slack where it's needed to satisfy other constraints (such as node time windows) will prevent assignments for that node. Configuring this value also affects how driver breaks are allocated.

What happen to the nodes when a booking was marked as fail_to_board or fail_to_deliver?

Details

Answer

When a booking cannot be picked up, it can be marked as fail_to_board and is simply ignored in subsequent calculations (since there are no goods or passengers in the vehicle picked up, so there is nothing to drop off). However, fail_to_deliver is more complicated since there are still goods remaining in the vehicle, and capacity constraints need to be accommodated for that. The booking/nodes are still assigned to the vehicle in that case (while fail_to_board bookings are unassigned from vehicles). The driver can send node_status at the same time as the planner does the re-optimization.

Provide examples for using conditions in filter expressions and/or labels

Answer

The following example represent a few options for using vehicle labels or in filtering expressions following JSON form of Django querystrings.

Examples

'1' AND '2' AND '3'

{"and": ["1", "2", "3"]}

'1' OR '2' OR '3'

{"or": ["1", "2", "3"]}

'1' AND ('2' OR '3') AND NOT ('4' AND '5')

{"and": [{"or: ["2", "3"]}, {"not": {"and": ["4", "5"]}}]}

Uploaded vehicles but they do not show up in the list of vehicles?

Details

Answer

Vehicles without a project_id or project value (or where these values are set to null) will not be visible. The SWAT model uses projects for authorization; even vehicles in a simulation will be inaccessible if they aren't associated with a project.

Despite everything is set correctly, my orders are being rejected (getting no offers)

Details

Answer

A few settings at the low solver level can be used to fix this problem. This typically occurs when the solver fails to find an initial feasible solution at the very beginning, often due to inappropriate heuristics selected for large VRP problems (1000+ nodes). To address this, try tweaking the FSS parameter (e.g., use values like 3, 16, 17, 8), disabling the use_local_search_metaheuristic setting, and increasing the lambda coefficient to 0.95. This can be done at a simulation level as well.

I'm trying to do live insertion of orders during live operations and I'm getting all bookings (including those that are already assigned) rejected. Why this is happening?

Details

Answer

See detailed explanation of logic behind this and way to remedy here

How to i include or exclude vehicles from calculation without deleting them?

Details

Answer

A vehicle model has a flag in_use that can be used to enable or disable vehicles for optimization purposes while retaining them visible in SWAT Routes, or Driver App. This would allow manual assignments to the vehicles which is handy for floating (or overflow) vehicles, or spare fleet that should be only used when there are no other vehicles left for planning.

Of course, here is the FAQ formatted for Docusaurus.

Are the start_time and end_time for vehicles strict constraints?

Details

Answer

Yes, the start_time and end_time properties for vehicles are strict constraints. The solver will not schedule any activity for a vehicle outside of this time window.

How can I model a vehicle's operating hours, like 8:00 AM to 3:00 PM?

Details

Answer

There are two primary ways to model this:

1. For vehicles with partial routes: Define the operating hours using the open_time_ts and close_time_ts on the start and end nodes of the partial_route.
2. For vehicles without partial routes: Use the vehicle-level start_time and end_time fields to specify the vehicle's working time.

My vehicle starts its route at its start_time and waits a long time before the first drop-off. How can I make the vehicle start the pickup closer to the drop-off time window to minimize this waiting time (slack)?

Details

Answer

There are three main approaches to minimize the slack time between a pickup and dropoff:

1. Set a trip_cost:

   • How: Apply a small trip_cost (e.g., 0.01 - 0.1) to the nodes.
   • Effect: This encourages the solver to minimize the travel time between pickup and dropoff, effectively reducing slack.
   • Compatibility: This approach is expected to work correctly with dynamic_breaks.
   • Downside: It may decrease solver performance.

2. Set max_slack to 0:

   • How: Set max_slack: 0 on the pickup nodes.
   • Effect: This forces the slack time at that node to be zero, making it a hard constraint.
   • Requirement: For this to work without causing rejections, all time windows in the request must overlap. If a pickup time window and a dropoff time window do not overlap, the booking will be rejected.
   • Compatibility: This method does not work correctly with dynamic_breaks. The break may still be added even if the path duration is shorter than the dynamic_break_min_path_duration.

3. Use finalization_type: 'max':

   • How: Set finalization_type: 'max' on the pickup nodes.
   • Effect: This pushes the pickup to occur as late as possible within its time window.
   • Warning: This setting can have a cascading "lazy" effect, causing the solver to schedule all subsequent nodes as late as possible, which might be an undesirable side effect.
   • Compatibility: This method also does not work correctly with dynamic_breaks.

Recommendation: The most robust method, especially when dynamic_breaks are needed, is to use a small trip_cost.

If I set finalization_type: 'max' on just one pickup node, does it affect other nodes in the route?

Details

Answer

Yes. Setting finalization_type: max on even a single node can influence the scheduling for all subsequent nodes in that vehicle's route, causing them to be scheduled as late as possible.

I'm using max_slack: 0 on pickup nodes to reduce waiting time, but now dynamic breaks are not being assigned. Why?

Details

Answer

This is a known conflict. Setting max_slack: 0 creates a hard constraint that is incompatible with the logic for inserting dynamic_breaks. The solver cannot satisfy both the zero slack requirement and the rules for break insertion simultaneously. If dynamic breaks are a requirement, you should use the trip_cost method instead of max_slack: 0.

What happens if I set max_slack: 0 on a vehicle's start-location node?

Details

Answer

Setting max_slack: 0 on a vehicle's assigned start-location node (in a partial route) is a valid way to ensure the vehicle departs immediately at the start of its journey without any initial slack. This is a hard constraint.

Is slack time considered in the solver's objective function for optimization?

Details

Answer

No, not by default. Slack time is generally a byproduct of the routing solution after node assignments are made. To make the solver actively minimize slack as part of its optimization goal, you must use parameters like trip_cost or slack_cost.

If I use trip_cost, how does it affect routes with different driving and idle times?

Details

Answer

Using trip_cost makes the solver try to minimize the total travel time for each individual order. This travel time is the full duration from an order's pickup to its dropoff, which includes any slack (idle) time that occurs between the two events. Therefore, the solver will favor solutions that reduce this total time for each order, effectively minimizing the time a booking spends in the vehicle.

In cvrptw mode, why doesn't my vehicle start its route from the depot?

Details

Answer

In prebook_cvrptw mode, the solver requires an explicit starting point for each vehicle to ensure it follows the depot -> dropoff -> dropoff schema. If a vehicle's partial_route is not set, the solver may start the route from any available node, not necessarily the depot.

To fix this, you must define a partial_route for the vehicle that contains the uid of the depot node (which is typically a node of type point). For example: "partial_route": ["node-depot-uid"]. Nodes included into partial_route or partial_route_end are considered as auto assigned to the vehicle.