Capacity Management

The VRP solver provides comprehensive capacity management features to handle real-world loading constraints. From simple weight limits to complex multi-dimensional capacity tracking, this guide covers all capacity-related features.

Overview

Capacity management ensures that vehicles don’t exceed their loading limits while optimizing resource utilization. The solver supports:

Multi-dimensional capacity (weight, volume, pallets, etc.)
Dynamic capacity tracking for pickup/delivery operations
Capacity utilization optimization
Soft capacity constraints with violations

Basic Capacity Configuration

Single-Dimension Capacity

The simplest form uses a single capacity value:

{
  "resources": [
    {
      "name": "delivery-truck",
      "capacity": [1000],
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "delivery-1",
      "location": {"latitude": 52.520, "longitude": 13.405},
      "load": [150],
      "duration": 600
    },
    {
      "name": "delivery-2", 
      "location": {"latitude": 52.523, "longitude": 13.401},
      "load": [200],
      "duration": 600
    }
  ]
}

Keep the dimension order identical across jobs and resources. If a resource has capacity: [1000, 50], job loads should look like load: [weight, volume]. A job load that is shorter than the resource capacity is treated as 0 in the missing dimensions. Loads and capacities are integers, so pick a unit that does not need decimals (grams, litres, items).

Multi-Dimensional Capacity

Handle multiple capacity constraints simultaneously:

{
  "resources": [
    {
      "name": "delivery-van",
      "capacity": [2000, 15, 24],  // [weight_kg, volume_m3, pallet_positions]
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "furniture-delivery",
      "location": {"latitude": 52.520, "longitude": 13.405},
      "load": [300, 4, 2],  // 300kg, 4m³, 2 pallet positions
      "duration": 1800
    },
    {
      "name": "appliance-delivery",
      "location": {"latitude": 52.523, "longitude": 13.401},
      "load": [150, 2, 1],  // 150kg, 2m³, 1 pallet position
      "duration": 900
    }
  ]
}

The solver tracks all capacity dimensions independently. A vehicle can only accept a job if ALL capacity dimensions have sufficient remaining space.

Dimension Limit: A resource capacity supports a maximum of 5 dimensions. If you need to track more than 5 different capacity types, consider combining related dimensions.

Pickup and Delivery Capacity

For pickup and delivery operations, capacity changes dynamically during the route:

{
  "resources": [
    {
      "name": "courier-1",
      "capacity": [500],
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z",
        "start": {"latitude": 52.520, "longitude": 13.405},
        "end": {"latitude": 52.520, "longitude": 13.405}
      }]
    }
  ],
  "jobs": [
    {
      "name": "pickup-order-123",
      "location": {"latitude": 52.523, "longitude": 13.401},
      "load": [50],  // Positive load = pickup (adds to vehicle)
      "duration": 300
    },
    {
      "name": "delivery-order-123",
      "location": {"latitude": 52.517, "longitude": 13.388},
      "load": [50],  // Same load = delivery (removes from vehicle)
      "duration": 300
    }
  ],
  "relations": [
    {
      "type": "PICKUP_AND_DELIVERY",
      "jobs": ["pickup-order-123", "delivery-order-123"]
    }
  ]
}

Capacity Flow Example

Initial State

Vehicle starts empty: 0 / 500 kg

After Pickup

Load increases: 50 / 500 kg

After Delivery

Load decreases: 0 / 500 kg

Dynamic Capacity Tracking for PDP

Pickup and Delivery Problems (PDP) require sophisticated capacity tracking as vehicle loads change throughout the route:

Real-Time Capacity Updates

Track Current Load

The solver keeps track of the running load of each vehicle in every dimension as it moves along the route. Pickups add to the load and deliveries remove from it.

Validate Each Stop

Before adding a job, the solver checks:

Can the vehicle handle the pickup load?
Will future deliveries free enough space?
Does the route respect capacity at all times?

Optimize Load Sequence

The solver may reorder stops to manage capacity:

Group pickups early when possible
Schedule deliveries to free space for later pickups
Balance load throughout the route

Complex PDP Example

Here’s a real-world scenario with multiple pickups and deliveries:

{
  "resources": [{
    "name": "courier-van",
    "capacity": [1000, 12],  // 1000kg, 12m³
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T18:00:00Z"
    }]
  }],
  "jobs": [
    // Morning pickups from suppliers
    {
      "name": "pickup-supplier-a",
      "location": {"latitude": 52.520, "longitude": 13.405},
      "load": [200, 3],
      "duration": 900,
      "windows": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T10:00:00Z"}]
    },
    {
      "name": "pickup-supplier-b",
      "location": {"latitude": 52.525, "longitude": 13.410},
      "load": [300, 4],
      "duration": 900,
      "windows": [{"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T10:00:00Z"}]
    },
    
    // Midday deliveries to customers
    {
      "name": "deliver-customer-1",
      "location": {"latitude": 52.515, "longitude": 13.400},
      "load": [200, 3],
      "duration": 600,
      "windows": [{"from": "2024-03-15T11:00:00Z", "to": "2024-03-15T13:00:00Z"}]
    },
    
    // Afternoon mixed operations
    {
      "name": "pickup-return-1",
      "location": {"latitude": 52.510, "longitude": 13.395},
      "load": [100, 1],
      "duration": 600,
      "windows": [{"from": "2024-03-15T14:00:00Z", "to": "2024-03-15T16:00:00Z"}]
    },
    {
      "name": "deliver-customer-2",
      "location": {"latitude": 52.530, "longitude": 13.415},
      "load": [300, 4],
      "duration": 600,
      "windows": [{"from": "2024-03-15T15:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    },
    {
        "name": "deliver-warehouse",
        "location": {"latitude": 52.210, "longitude": 13.195},
         "load": [100, 1],
         "duration": 300
    }
  ],
    "relations": [
        {
         "type": "PICKUP_AND_DELIVERY",
          "jobs": ["pickup-supplier-a", "deliver-customer-1"]
     },
     {
         "type": "PICKUP_AND_DELIVERY",
          "jobs": ["pickup-supplier-b", "deliver-customer-2"]
     },
     {
        "type": "PICKUP_AND_DELIVERY",
        "jobs": ["pickup-return-1", "deliver-warehouse"]
     }
    ]
}

Capacity Timeline Visualization

Along one possible route for the example above, the load changes like this (times are illustrative):

Time     | Stop                 | Action   | Load Change | Current Load | Remaining
---------|---------------------|----------|-------------|--------------|------------
00    | Start               | -        | -           | [0, 0]       | [1000, 12]
30    | pickup-supplier-a   | PICKUP   | +[200, 3]   | [200, 3]     | [800, 9]
15    | pickup-supplier-b   | PICKUP   | +[300, 4]   | [500, 7]     | [500, 5]
30    | deliver-customer-1  | DELIVERY | -[200, 3]   | [300, 4]     | [700, 8]
30    | pickup-return-1     | PICKUP   | +[100, 1]   | [400, 5]     | [600, 7]
00    | deliver-customer-2  | DELIVERY | -[300, 4]   | [100, 1]     | [900, 11]
00    | deliver-warehouse   | DELIVERY | -[100, 1]   | [0, 0]       | [1000, 12]

The solver ensures that at no point does the current load exceed the vehicle’s capacity in any dimension.

Common Use Cases

1. Last-Mile Delivery

Standard parcel delivery with weight and volume constraints:

{
  "resources": [{
    "name": "delivery-van",
    "capacity": [1000],  // 1000 kg
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T18:00:00Z"
    }]
  }],
  "jobs": [
    {"name": "parcel-1", "load": [5]},
    {"name": "parcel-2", "load": [3]},
    {"name": "parcel-3", "load": [8]}
  ]
}

{
  "resources": [{
    "name": "delivery-van",
    "capacity": [1000, 8000],  // 1000 kg, 8000 litres
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T18:00:00Z"
    }]
  }],
  "jobs": [
    {"name": "parcel-1", "load": [5, 100]},
    {"name": "parcel-2", "load": [3, 50]},
    {"name": "parcel-3", "load": [8, 200]}
  ]
}

2. Waste Collection

Vehicles that fill up and need to visit disposal sites:

{
  "resources": [{
    "name": "garbage-truck",
    "capacity": [10000],  // 10 tons
    "shifts": [{
      "from": "2024-03-15T06:00:00Z",
      "to": "2024-03-15T14:00:00Z"
    }]
  }],
  "jobs": [
    // Collection points (pickups)
    {"name": "bin-1", "load": [200], "duration": 800},
    {"name": "bin-2", "load": [150], "duration": 600},
    {"name": "bin-3", "load": [300], "duration": 1200},
    // Disposal site (delivery)
    {"name": "disposal-site-bin-1", "load": [200], "duration": 1800},
    {"name": "disposal-site-bin-2", "load": [150], "duration": 1800},
    {"name": "disposal-site-bin-3", "load": [300], "duration": 1800}
  ],
  "relations": [
     {
        "type": "PICKUP_AND_DELIVERY",
        "jobs": ["bin-1", "disposal-site-bin-1"]
     },
     {
        "type": "PICKUP_AND_DELIVERY",
        "jobs": ["bin-2", "disposal-site-bin-2"]
     },
     {
        "type": "PICKUP_AND_DELIVERY",
        "jobs": ["bin-3", "disposal-site-bin-3"]
     }
  ]
}

3. Mixed Fleet Optimization

Different vehicle types with varying capacities:

{
  "resources": [
    {
      "name": "bike-courier",
      "capacity": [20, 500],  // 20kg, 500 litres
      "category": "BIKE",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    },
    {
      "name": "cargo-van",
      "capacity": [1000, 8000],  // 1000kg, 8000 litres
      "category": "CAR",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    },
    {
      "name": "truck",
      "capacity": [5000, 40000],  // 5 tons, 40000 litres
      "category": "TRUCK",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    }
  ],
  "jobs": [
    {"name": "small-parcel", "load": [15, 300]},
    {"name": "large-parcel", "load": [500, 5000]},
    {"name": "bulk-delivery", "load": [3000, 25000]}
  ]
}

Best Practices

Capacity Planning Guidelines:

Reserve Buffer: Keep 10-15% capacity buffer for unexpected additions
Dimension Selection: Only use dimensions that actually constrain your operations
Load Accuracy: Ensure load estimates include packaging and handling equipment
Mixed Units: Keep units consistent (all kg or all lbs, not mixed)

Handling Overloading

When capacity constraints make problems infeasible:

Keep Partial Planning Enabled

partialPlanning is true by default, so jobs that do not fit are left unserved instead of making the whole problem fail. To list the reasons per job, also enable the explanation:

{
  "options": {
    "partialPlanning": true,
    "explanation": {"enabled": true}
  }
}

Check Unserved Jobs

Review unserved for jobs that couldn’t be assigned. With options.explanation.enabled, unservedReasons lists the constraints that blocked each job. TRIP_CAPACITY indicates a capacity conflict:

{
  "unserved": ["heavy-delivery-5", "bulky-item-3"],
  "unservedReasons": {
    "heavy-delivery-5": ["TRIP_CAPACITY"],
    "bulky-item-3": ["TRIP_CAPACITY"]
  }
}

Add Resources or Adjust Loads

Either add more vehicles or review if load estimates are accurate.

Performance Considerations

Resources support at most 5 capacity dimensions. Only include dimensions that actually constrain your operations.

Optimization Tips

Simplify When Possible: If volume rarely constrains, use weight only
Round Values: Round loads to reasonable precision (1kg vs 1.234kg)
Group Similar Items: Combine small items into single jobs when feasible

Capacity in Response

Capacity is enforced during planning. The response lists each trip’s visits in order, together with the jobs that could not be served:

{
  "trips": [
    {
      "resource": "delivery-van",
      "visits": [
        {"job": "delivery-1", "arrival": "2024-03-15T09:15:00Z", "serviceTime": 600},
        {"job": "delivery-2", "arrival": "2024-03-15T09:45:00Z", "serviceTime": 600}
      ]
    }
  ],
  "unserved": []
}

Pickup and Delivery - Complex paired job handling
Vehicle Types - Different capacity per vehicle type
Job Relations - Capacity-aware job sequencing

Platform

VRP API

Fill API

Capacity Management

Capacity Management

Overview

Basic Capacity Configuration

Single-Dimension Capacity

Multi-Dimensional Capacity

Pickup and Delivery Capacity

Capacity Flow Example

Dynamic Capacity Tracking for PDP

Real-Time Capacity Updates

Complex PDP Example

Capacity Timeline Visualization

Common Use Cases

1. Last-Mile Delivery

2. Waste Collection

3. Mixed Fleet Optimization

Best Practices

Handling Overloading

Performance Considerations

Optimization Tips

Capacity in Response

​Capacity Management

​Overview

​Basic Capacity Configuration

​Single-Dimension Capacity

​Multi-Dimensional Capacity

​Pickup and Delivery Capacity

​Capacity Flow Example

​Dynamic Capacity Tracking for PDP

​Real-Time Capacity Updates

​Complex PDP Example

​Capacity Timeline Visualization

​Common Use Cases

​1. Last-Mile Delivery

​2. Waste Collection

​3. Mixed Fleet Optimization

​Best Practices

​Handling Overloading

​Performance Considerations

​Optimization Tips

​Capacity in Response

​Related Features

Capacity Management

Overview

Basic Capacity Configuration

Single-Dimension Capacity

Multi-Dimensional Capacity

Pickup and Delivery Capacity

Capacity Flow Example

Dynamic Capacity Tracking for PDP

Real-Time Capacity Updates

Complex PDP Example

Capacity Timeline Visualization

Common Use Cases

1. Last-Mile Delivery

2. Waste Collection

3. Mixed Fleet Optimization

Best Practices

Handling Overloading

Performance Considerations

Optimization Tips

Capacity in Response

Related Features