Vehicle Efficiency

In the context of the Stateless API, Vehicle Efficiency refers to a set of constraints designed to optimize and control how a vehicle's capacity is utilized throughout its route. These constraints allow you to enforce rules about minimum loads during a trip and maximum loads at the end of a trip.

This feature is crucial for ensuring that vehicles are not underutilized (driving empty or with very little cargo) and for enforcing specific operational flows, such as ensuring a vehicle empties its load before taking on new work.

Core Concepts

Vehicle efficiency constraints are defined per vehicle and operate on specific demand dimensions (e.g., weight, volume, passengers). There are two main types of checks:

1. Loaded Capacity Check (Minimum Load)

This check enforces that during a trip, the vehicle must carry at least a specified minimum amount of load.

• Purpose: To prevent vehicles from making trips with inefficiently small loads.
• Mechanism: The solver checks the vehicle's load after every stop. If the load is below the loaded_min_capacity threshold, it is considered a violation.

2. Unloaded Capacity Check (Maximum Load when Unloaded)

This check enforces that whenever the vehicle is considered "unloaded" (e.g., at the end of a trip, or potentially after a sequence of drop-offs depending on the solver's internal logic for "trip" segments), the vehicle must not carry more than a specified maximum amount of load.

• Purpose: To ensure vehicles return empty or with minimal residual cargo. This is often used to force a "delivery first, then pickup" workflow or simply to ensure all goods are delivered.
• Mechanism: The solver checks the vehicle's load at the end of the assigned route and potentially at intermediate points where a "trip" is considered complete (e.g., after a delivery run). If the load exceeds the unloaded_max_capacity, it is considered a violation.

Strictness and Penalties

Both checks can be configured as either Strict or Flexible.

• Strict (true): The constraint must be satisfied. If a solution violates the constraint, it is considered invalid and discarded. This is useful for mandatory business rules (e.g., "Trucks must be empty when returning to the depot").
• Flexible (false): The constraint is treated as a "soft" constraint. Violations are allowed but incur a penalty cost. The optimizer will try to minimize these penalties, effectively balancing the efficiency constraint against other costs like travel time and distance.

Configuration

To enable vehicle efficiency constraints, you add an efficiency object to the vehicle definition in your JSON payload.

Parameters

Parameter	Type	Description
demand_name	string	The name of the demand dimension to check (e.g., "units", "weight"). Must match a key in your capacity and demand objects.
loaded_min_capacity	number	The minimum required load during the trip (absolute units).
loaded_min_capacity_percentage	number	The minimum required load during the trip (percentage of total capacity, 0-100).
loaded_undercapacity_check_strict	boolean	If true, the minimum load requirement is strict.
unloaded_max_capacity	number	The maximum allowed load when unloaded (absolute units).
unloaded_max_capacity_percentage	number	The maximum allowed load when unloaded (percentage of total capacity, 0-100).
unloaded_overcapacity_check_strict	boolean	If true, the maximum end-load requirement is strict.

Using Percentages

Instead of defining absolute values (e.g., "5 units"), you can define constraints relative to the vehicle's total capacity using the _percentage parameters.

• loaded_min_capacity_percentage: Sets the minimum load as a percentage (0-100) of the vehicle's max capacity.
• unloaded_max_capacity_percentage: Sets the maximum unloaded load as a percentage (0-100) of the vehicle's max capacity.

Note: You should use either the absolute value parameter OR the percentage parameter for a given constraint, not both simultaneously for the same demand type.

Example JSON Payload

Here is an example of how to configure a vehicle to ensure it is always carrying at least 15 units during a trip. This forces the vehicle to consolidate smaller pickups (e.g., 10 units and 5 units) before proceeding to drop-offs, as a single pickup of 10 units would violate the minimum load constraint.

{
  "vehicles": [
    {
      "agent_id": "vehicle_1",
      "capacity": {
        "units": 100
      },
      "efficiency": {
        "constraints": [
          {
            "demand_name": "units",
            "loaded_min_capacity": 15,
            "loaded_undercapacity_check_strict": true,
            "unloaded_max_capacity": 0,
            "unloaded_overcapacity_check_strict": false
          }
        ]
      }
      // ... other vehicle properties
    }
  ]
}

Scenario: Ensuring Drop-offs Before Pickups

A common use case for Vehicle Efficiency is to enforce a workflow where a vehicle must complete all its deliveries (drop-offs) before it can start any new pickups. This effectively prohibits "interleaving" pickups and drop-offs if it results in carrying residual load back to the depot or mixing flows.

By setting the Unloaded Capacity Check to 0 and making it Strict, you ensure that the vehicle cannot finish its route with any items on board. In a scenario where a vehicle starts with goods to deliver, this forces the optimizer to schedule all drop-offs. If the vehicle were to pick up new items before finishing deliveries, it might end up with those new items still on board at the end of the route (depending on the destination of the new items), which this constraint would prevent.

More specifically, to strictly prohibit returning with any load (which implicitly encourages completing drop-offs), you would use:

"efficiency": {
    "constraints": [
        {
            "demand_name": "weight",
            "unloaded_max_capacity": 0,
            "unloaded_overcapacity_check_strict": true
        }
    ]
}

This configuration enforces a strict overcapacity check for the demand type weight. It defines a maximum capacity of 0 after a series of consecutive drop-offs, effectively preventing the vehicle from performing pickups until all drop-offs are completed if those pickups would result in a non-empty return.

Why is this important for planning?

1. Cost Reduction: By enforcing minimum loads (loaded_min_capacity), you avoid dispatching vehicles for trivial amounts of cargo, which saves on fuel and driver costs per unit delivered.
2. Operational Compliance: Many logistics operations have strict rules about "clean" returns (e.g., returning empty containers, or ensuring no cross-contamination). The unloaded_max_capacity constraint directly models these physical or regulatory requirements.
3. Workflow Control: It allows planners to guide the solver towards preferred operational patterns (like "deliver everything first") without manually sequencing every stop.

tip

When using Flexible constraints (strict = false), you can control the "strength" of the constraint by adjusting the penalty costs in the model_parameters (if applicable) or relying on the solver's internal default penalties to balance efficiency against other factors.

Playground

You can try out the Vehicle Efficiency concept using the playground below. In this example, the vehicle has a Loaded Efficiency constraint of 15 units. Since the pickups are 10 and 5 units respectively, the vehicle is forced to visit both pickup locations to meet the minimum load requirement before it can proceed to the drop-offs.

Loading...