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
    }
  ]
}

Always ensure that job loads and resource capacities have the same number of dimensions. If a resource has capacity: [1000, 50], all jobs must have loads like load: [weight, volume].

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: The solver supports a maximum of 5 capacity dimensions. If you need to track more than 5 different capacity types, consider combining related dimensions or using multiple optimization runs.

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

Active Capacity Coefficient

Solver-internal, not request-configurable: activeCapacityCoefficient and capacityDiscountCoefficient are internal tuning constants used by the solver’s workload-balance scoring. They are not fields on OnRouteWeights and cannot be set from the request — there is no weights.activeCapacityCoefficient or weights.capacityDiscountCoefficient key to send.

Internally, the solver uses these coefficients (defaults activeCapacityCoefficient = 0.7, capacityDiscountCoefficient = 0.1) when scoring how efficiently vehicle capacity is being used, to prefer fuller vehicles over partially loaded ones.

How Active Capacity Works

Concept
Automatic Heuristic Override

The active capacity coefficient encourages the solver to:

Use fewer vehicles by filling them more completely
Reduce partial loads and empty space
Consolidate deliveries when possible

Score Impact Formula (internal):

utilization_score = (used_capacity / total_capacity) * activeCapacityCoefficient

When options.minimizeResources is true and the total available capacity is at least twice the number of jobs (i.e. resources have generous spare capacity relative to demand), the solver automatically overrides activeCapacityCoefficient to 0.3 for that solve. This happens internally based on the request shape — it is not something you set, and there is no way to opt out of it via the request.

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 maintains real-time load state for each vehicle:

{
  "vehicleState": {
    "currentLoad": [300, 5],  // [weight_kg, volume_m3]
    "remainingCapacity": [700, 10],  // Available space
    "maxCapacityReached": [450, 8]  // Peak during route
  }
}

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": [150, 2],
      "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": [250, 3],
      "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

The solver tracks how capacity changes throughout the route:

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, 8],  // 1000 kg, 8 m³
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T18:00:00Z"
    }]
  }],
  "jobs": [
    {"name": "parcel-1", "load": [5, 0.1]},
    {"name": "parcel-2", "load": [3, 0.05]},
    {"name": "parcel-3", "load": [8, 0.2]}
  ]
}

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, 0.5],  // 20kg, 0.5m³
      "category": "BIKE",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    },
    {
      "name": "cargo-van",
      "capacity": [1000, 8],  // 1000kg, 8m³
      "category": "CAR",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    },
    {
      "name": "truck",
      "capacity": [5000, 40],  // 5 tons, 40m³
      "category": "TRUCK",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    }
  ],
  "jobs": [
    {"name": "small-parcel", "load": [15, 0.3]},
    {"name": "large-parcel", "load": [500, 5]},
    {"name": "bulk-delivery", "load": [3000, 25]}
  ]
}

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:

Enable Partial Planning

{
  "options": {
    "partialPlanning": true
  }
}

Check Unassigned Jobs

Review the response for jobs that couldn’t be assigned due to capacity:

{
  "unassigned": ["heavy-delivery-5", "bulky-item-3"],
  "unassignedReasons": {
    "heavy-delivery-5": ["CAPACITY_EXCEEDED"],
    "bulky-item-3": ["NO_VEHICLE_WITH_SUFFICIENT_CAPACITY"]
  }
}

Add Resources or Adjust Loads

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

Performance Considerations

Multi-dimensional capacity impact:

Each additional capacity dimension increases computation complexity
Use 1-3 dimensions for best performance
More than 5 dimensions may significantly slow solving

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

The solution includes capacity tracking information:

{
  "routes": [
    {
      "resource": "delivery-van",
      "jobs": [
        {
          "job": "delivery-1",
          "arrival": "2024-03-15T09:15:00Z",
          "departure": "2024-03-15T09:25:00Z",
          "load": [150],  // Current load after this job
          "cumulativeLoad": [150]  // Total load at this point
        },
        {
          "job": "delivery-2",
          "arrival": "2024-03-15T09:45:00Z",
          "departure": "2024-03-15T09:55:00Z",
          "load": [200],
          "cumulativeLoad": [350]  // 150 + 200
        }
      ],
      "summary": {
        "maxLoad": [350],  // Peak load during route
        "capacityUtilization": 0.35  // 35% of 1000kg capacity
      }
    }
  ]
}

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

Active Capacity Coefficient

How Active Capacity Works

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

​Active Capacity Coefficient

​How Active Capacity Works

​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

Active Capacity Coefficient

How Active Capacity Works

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