Advanced Constraints

Beyond basic routing constraints, the VRP solver supports sophisticated business rules for compliance, safety, and operational requirements. This guide covers advanced constraints including driving limits, tag matching, vehicle restrictions, and adherence penalties.

Drive Time Constraints

Maximum Continuous Drive Time

Enforce legal or safety limits on continuous driving:

{
  "resources": [
    {
      "name": "driver-1",
      "maxDriveTimeInSeconds": 14400,  // 4 hours max continuous driving
      "shifts": [{
        "from": "2024-03-15T06:00:00Z",
        "to": "2024-03-15T18:00:00Z",
        "breaks": [{
          "type": "DRIVING",  // Resets drive time counter
          "duration": 2700,   // 45-minute break
          "after": 14400      // After 4 hours driving
        }]
      }]
    }
  ],
  "jobs": [
    {
      "name": "delivery-1",
      "duration": 1800
    }
  ]
}

maxDriveTimeInSeconds

integer

Maximum seconds of continuous driving before a break is required

Legal Compliance: Many jurisdictions have mandatory driving time limits. Examples:

EU: 4.5 hours continuous driving max
US DOT: Complex hours-of-service rules
Always verify local regulations

Drive Time Ordering

Ensure jobs are visited in chronological order based on actual drive times:

{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T18:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "morning-appointment",
      "windows": [{"from": "2024-03-15T09:00:00Z", "to": "2024-03-15T10:00:00Z"}]
    },
    {
      "name": "afternoon-appointment", 
      "windows": [{"from": "2024-03-15T14:00:00Z", "to": "2024-03-15T15:00:00Z"}]
    }
  ],
  "options": {
    "constraints": {
      "driveTimeOrder": true
    }
  }
}

Drive Time Ordering prevents the solver from scheduling later appointments before earlier ones on the same route, even if it might be more efficient.

Tag-Based Constraints

Hard Tag Matching

Enforce strict requirements for skills, certifications, or equipment:

{
  "jobs": [
    {
      "name": "hazmat-delivery",
      "tags": [
        {"name": "hazmat-certified", "hard": true},
        {"name": "truck-required", "hard": true}
      ]
    }
  ],
  "resources": [
    {
      "name": "certified-driver",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }],
      "tags": ["hazmat-certified", "truck-required", "experienced"]
    },
    {
      "name": "regular-driver",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }],
      "tags": ["truck-required"]
    }
  ]
}

Soft Tag Preferences

Create preferences without hard requirements:

{
  "jobs": [
    {
      "name": "vip-service",
      "tags": [
        {"name": "premium-service", "needed": false, "preferred": true},
        {"name": "experienced", "needed": false, "preferred": true}
      ]
    }
  ],
  "resources": [
    {
      "name": "premium-driver",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }],
      "tags": ["premium-service", "experienced"]
    }
  ],
  "weights": {
    "tagViolationWeight": 10  // Global multiplier for tag mismatches
  }
}

Tag Matching Rules

Hard Tags Must Match

Job with hard tag → Resource must have same hard tag

Soft Tags Create Preference

Mismatched soft tags incur penalties based on weight

Resource Tags Don't Restrict

Resources can have tags that jobs don’t require

Weight Calculation

Penalty = tagWeight × tagViolationWeight × mismatchCount

Vehicle Restrictions

Disallowed Vehicles

Explicitly prevent certain resources from servicing specific jobs:

{
  "resources": [
    {
      "name": "employee-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    },
    {
      "name": "contractor-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "competitor-location",
      "disallowedResources": ["contractor-1", "contractor-2"],
      "allowedResources": ["employee-1", "employee-2", "employee-3"]
    }
  ]
}

Restriction Priority:

disallowedResources - Never assign these (hard constraint)
allowedResources - Only assign from this list (hard constraint)
preferredResources - Try these first (soft constraint)

Complex Restriction Example

{
  "jobs": [
    {
      "name": "secure-facility",
      "tags": [
        {"name": "security-clearance", "hard": true}
      ],
      "disallowedResources": ["temp-driver-1", "temp-driver-2"],
      "allowedResources": ["secure-driver-1", "secure-driver-2"]
    }
  ],
  "resources": [
    {
      "name": "secure-driver-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }],
      "tags": ["security-clearance"]
    }
  ]
}

Overtime Constraints

Overtime Penalties

Configure penalties for work beyond regular hours:

{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z",        // Regular hours
        "overtimeEnd": "2024-03-15T20:00:00Z" // Can work until 8 PM
      }],
      "hourlyCost": 25      // Regular rate
    }
  ],
  "jobs": [
    {
      "name": "late-delivery",
      "duration": 1800
    }
  ],
  "weights": {
    "overtimeWeight": 100  // Strong penalty for overtime
  }
}

Overtime Behavior

{
  "resources": [{
    "name": "driver-1",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T17:00:00Z",
      "overtimeEnd": "2024-03-15T20:00:00Z"  // Allowed but penalized
    }]
  }],
  "jobs": [{
    "name": "job-1"
  }],
  "weights": {
    "overtimeWeight": 50
  }
}

Work past regular hours incurs penalties

Planning Adherence

Maintaining Planned Schedules

Penalize deviations from existing plans:

{
  "jobs": [
    {
      "name": "scheduled-maintenance",
      "plannedArrival": "2024-03-15T14:00:00Z",
      "plannedResource": "technician-1",
      "windows": [{
        "from": "2024-03-15T13:00:00Z",
        "to": "2024-03-15T15:00:00Z"
      }]
    }
  ],
  "resources": [
    {
      "name": "technician-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "weights": {
    "plannedWeight": 50,         // Arrival time adherence
    "plannedResourceWeight": 100  // Resource assignment adherence
  }
}

Adherence Calculation

Planned Arrival Penalty = |actual_arrival - planned_arrival| × plannedWeightResource Change Penalty = (resource_changed ? 1 : 0) × plannedResourceWeight

Use Cases for Planning Adherence

Customer Communications

When customers have been notified of arrival times, minimize changes to maintain trust.

Incremental Optimization

Re-optimize routes while keeping most assignments stable.

Partial Replanning

Add new jobs while minimizing disruption to existing schedule.

Constraint Interactions

Constraint Priority Hierarchy

Hard Constraints (Absolute)

Time windows (hard)
Capacity limits
Disallowed resources
Hard tags
Shift boundaries (without overtime)

Soft Constraints (Weighted)

Soft time windows
Overtime penalties
Tag preferences
Planning adherence
Preferred resources

Optimization Objectives

Minimize total cost
Minimize travel time
Balance workload
Maximize urgency satisfaction

Complex Constraint Example

{
  "jobs": [
    {
      "name": "complex-service",
      // Hard constraints
      "tags": [
        {"name": "certified", "needed": true},
        {"name": "heavy-equipment", "needed": true},
        {"name": "premium-service", "needed": false, "preferred": true}
      ],
      "disallowedResources": ["junior-tech-1", "junior-tech-2"],
      "windows": [{
        "from": "2024-03-15T09:00:00Z", "to": "2024-03-15T17:00:00Z"
      }],
      
      // Soft constraints
      "plannedArrival": "2024-03-15T14:00:00Z",
      "urgency": 80
    }
  ],
  "resources": [
    {
      "name": "senior-tech-1",
      "tags": ["certified", "heavy-equipment", "premium-service"],
      "maxDriveTimeInSeconds": 14400,
      "shifts": [{
        "from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z",
        "overtimeEnd": "2024-03-15T19:00:00Z"
      }]
    }
  ],
  "weights": {
    "overtimeWeight": 100,
    "plannedWeight": 50,
    "tagViolationWeight": 10,
    "urgencyWeight": 20
  }
}

Performance Considerations

Constraint Complexity Impact:Low Impact:

Basic tag matching
Disallowed resources
Simple overtime penalties

Medium Impact:

Many soft constraints
Complex tag hierarchies
Planning adherence with many jobs

High Impact:

Drive time ordering
Many overlapping soft constraints
Complex overtime structures

Optimization Tips

Use Hard Constraints Sparingly: Each hard constraint reduces solution space
Balance Weights: Keep soft constraint weights in reasonable ratios
Test Incrementally: Add constraints one at a time to identify conflicts
Monitor Infeasibility: Too many constraints can make problems unsolvable

Troubleshooting

Common Issues

Jobs Not Assigned Due to Constraints

Symptoms: High unassigned job countCheck:

Tag requirements vs available resources
Disallowed resource lists
Time window compatibility
Capacity constraints

Solutions:

Review tag assignments
Verify resource capabilities
Consider soft constraints instead of hard
Enable partial planning

Unexpected Constraint Violations

Symptoms: Soft constraints violated despite high weightsCheck:

Competing constraint weights
Hard constraint conflicts
Resource availability

Solutions:

Increase specific constraint weights
Review weight ratios
Check for conflicting requirements
Add more resources

Poor Solution Quality

Symptoms: Valid but inefficient routesCheck:

Too many hard constraints
Conflicting soft constraints
Insufficient optimization time

Solutions:

Convert some hard constraints to soft
Adjust weight balance
Increase solve time limit
Simplify constraint model

Debugging Constraints

Use the explanation endpoint to understand constraint impacts:

GET /v2/vrp/jobs/{jobId}/explanation

Response includes:

Active constraints for each assignment
Constraint violations and penalties
Why certain assignments weren’t made

Best Practices

Start Simple

Begin with essential constraints only:

Basic time windows
Required capacities
Critical tags

Add Incrementally

Layer in advanced constraints:

Soft preferences
Overtime rules
Planning adherence

Monitor Impact

Track key metrics:

Constraint violation counts
Solution quality scores
Computation time
Unassigned job reasons

Document Rules

Maintain clear documentation:

Business reason for each constraint
Weight selection rationale
Expected behavior
Fallback strategies

Tag & Ranking

Advanced tag matching and preferences

Time Windows

Time-based constraints

Period Rules

Long-term resource constraints

Cost Optimization

How constraints affect costs

Platform

VRP API

Advanced Constraints

Advanced Constraints

Drive Time Constraints

Maximum Continuous Drive Time

Drive Time Ordering

Tag-Based Constraints

Hard Tag Matching

Soft Tag Preferences

Tag Matching Rules

Vehicle Restrictions

Disallowed Vehicles

Complex Restriction Example

Overtime Constraints

Overtime Penalties

Overtime Behavior

Planning Adherence

Maintaining Planned Schedules

Adherence Calculation

Use Cases for Planning Adherence

Constraint Interactions

Constraint Priority Hierarchy

Complex Constraint Example

Performance Considerations

Optimization Tips

Troubleshooting

Common Issues

Debugging Constraints

Best Practices

Tag & Ranking

Time Windows

Period Rules

Cost Optimization

Platform

VRP API

​Advanced Constraints

​Drive Time Constraints

​Maximum Continuous Drive Time

​Drive Time Ordering

​Tag-Based Constraints

​Hard Tag Matching

​Soft Tag Preferences

​Tag Matching Rules

​Vehicle Restrictions

​Disallowed Vehicles

​Complex Restriction Example

​Overtime Constraints

​Overtime Penalties

​Overtime Behavior

​Planning Adherence

​Maintaining Planned Schedules

​Adherence Calculation

​Use Cases for Planning Adherence

​Constraint Interactions

​Constraint Priority Hierarchy

​Complex Constraint Example

​Performance Considerations

​Optimization Tips

​Troubleshooting

​Common Issues

​Debugging Constraints

​Best Practices

​Related Features

Tag & Ranking

Time Windows

Period Rules

Cost Optimization

Advanced Constraints

Drive Time Constraints

Maximum Continuous Drive Time

Drive Time Ordering

Tag-Based Constraints

Hard Tag Matching

Soft Tag Preferences

Tag Matching Rules

Vehicle Restrictions

Disallowed Vehicles

Complex Restriction Example

Overtime Constraints

Overtime Penalties

Overtime Behavior

Planning Adherence

Maintaining Planned Schedules

Adherence Calculation

Use Cases for Planning Adherence

Constraint Interactions

Constraint Priority Hierarchy

Complex Constraint Example

Performance Considerations

Optimization Tips

Troubleshooting

Common Issues

Debugging Constraints

Best Practices

Related Features