Performance Optimization Guide

The VRP solver’s performance depends on multiple factors including problem size, constraint complexity, and configuration choices. This guide helps you understand and optimize solver performance for your specific use cases.

Performance Fundamentals

What Affects Solve Time?

Performance Scaling

The solver’s time complexity increases with:

Linear Factors
Quadratic Factors
Exponential Factors

Number of jobs (O(n))
Number of resources
Number of time windows
Basic constraints

Problem Size Guidelines

Small Problems (< 100 jobs)

POST /v2/vrp/solve?millis=10000

{
  "typicalSolveTime": "5-10 seconds",
  "expectedQuality": "Near-optimal",
  "resourceUsage": "Minimal"
}

Medium Problems (100-500 jobs)

POST /v2/vrp/solve?millis=60000

{
  "typicalSolveTime": "30-60 seconds",
  "expectedQuality": "Very good",
  "resourceUsage": "Moderate"
}

Large Problems (500-2000 jobs)

POST /v2/vrp/solve?millis=300000

{
  "typicalSolveTime": "3-5 minutes",
  "expectedQuality": "Good feasible solutions",
  "resourceUsage": "Significant"
}

Very Large Problems (> 2000 jobs)

POST /v2/vrp/solve?millis=600000

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

{
  "typicalSolveTime": "5-10 minutes",
  "expectedQuality": "Feasible solutions",
  "resourceUsage": "High",
  "recommendation": "Consider problem decomposition"
}

Configuration for Performance

Essential Options

integer

Maximum solve time in milliseconds, passed as a query parameter on POST /v2/vrp/solve (and the /suggest and sync-solve endpoints) — not a body field. Balance between quality and speed.

The solver doesn’t expose separate construction-heuristic or local-search algorithm selection options — solve strategy is managed internally based on the problem.

Performance-Oriented Settings

Speed Priority
Quality Priority
Balanced

Request

POST /v2/vrp/solve?millis=30000

Body

{
  "options": {
    "partialPlanning": true,
    "explanation": {
      "enabled": false  // Disable for speed
    }
  }
}

Fast solutions with reasonable quality.

Request

POST /v2/vrp/solve?millis=300000

More solve time gives the solver more iterations to improve the solution.

Request

POST /v2/vrp/solve?millis=120000

Good trade-off for most use cases.

Distance Matrix Performance

Distance calculations significantly impact performance:

Matrix Types by Speed

Euclidean (Fastest)

{
  "options": {
    "euclidian": true
  }
}

No external API calls
Instant calculation
Lower accuracy

Routing Engine (Slower, most accurate)

{
  "options": {
    "euclidian": false,
    "routingEngine": "OSM"
  }
}

Calls an external routing engine (OSM, TOMTOM, GOOGLE, or ANYMAP)
Real road distances and travel times
Most accurate

Pre-computed Custom Matrices (No calculation)

{
  "customDistanceMatrices": {
    "profileMatrices": {
      "CAR": { "9": "matrix-car-midday-456" }
    },
    "matrixServiceUrl": "https://custom-matrix-service.com/api"
  }
}

Skips on-the-fly distance calculation entirely
Best for stable location sets or multi-profile/time-sliced scenarios

Distance Matrix Optimization

Caching Strategy:

Prefer customDistanceMatrices.profileMatrices for stable location sets, so distances are pre-computed once instead of recalculated per request
Use options.euclidian: true for a fast approximation when road accuracy isn’t required
Limit unique locations

Constraint Impact on Performance

Low Impact Constraints

Basic time windows
Simple capacity checks
Fixed assignments
Priority values

Medium Impact Constraints

Multiple time windows
Multi-dimensional capacity
Skill/tag matching
Soft time preferences

High Impact Constraints

Complex job relations
Many-to-many dependencies
Dynamic time calculations
Alternative evaluations

Performance Tips:

Minimize hard constraints
Avoid unnecessary job relations
Use reasonable time window widths
Limit alternative calculations

Hardware Requirements

Minimum Requirements

CPU: 2 cores
Memory: 4GB RAM
Network: 10 Mbps
Storage: 1GB free

Recommended Specifications

Small Fleet (< 10 vehicles)
Medium Fleet (10-50 vehicles)
Large Fleet (> 50 vehicles)

CPU: 4 cores
Memory: 8GB RAM
Network: 50 Mbps
Storage: 5GB free

Performance Monitoring

The solver doesn’t expose internal solve telemetry (score-calculation counts, move-evaluation counts, time-to-first-feasible, or memory usage) through the API — there’s no built-in solve-performance endpoint. The response only reports the outcome of the solve; use these fields to gauge solution quality after the fact:

{
  "score": { "hard": 0, "soft": -12345, "feasible": true },
  "totalTravelTimeInSeconds": 3600,
  "totalTravelDistanceInMeters": 30000,
  "totalServiceTimeInSeconds": 600,
  "totalWaitTimeInSeconds": 0,
  "occupancy": 0.47,
  "workloadFairness": 0.95
}

To compare configurations, measure wall-clock time from request to response externally and compare the resulting score across runs.

Optimization Strategies

1. Problem Decomposition

For very large problems, consider:

Geographic Clustering

Divide by regions or zones

Temporal Splitting

Separate by time periods

Resource Grouping

Partition by vehicle types

Priority Batching

Process high-priority first

2. Incremental Solving

{
  "jobs": ["high-priority-jobs"]
}

{
  "jobs": [
    {"name": "high-priority-job-1", "initialResource": "vehicle-1", "initialArrival": "2024-03-15T09:00:00Z"},
    {"name": "new-job-1"}
  ]
}

Send POST /v2/vrp/solve?millis=60000 for phase 1, then POST /v2/vrp/solve?millis=120000 for phase 2. There’s no separate warmStart/solutionId field — warm-start the solver from a previous solution by setting each already-placed job’s initialResource (and optionally initialArrival/initialDepot) to what it resolved to last time.

3. Parallel Processing

When possible, run multiple scenarios:

const scenarios = [
  {weight: "minimize-vehicles"},
  {weight: "minimize-travel"},
  {weight: "balance-workload"}
];

const results = await Promise.all(
  scenarios.map(s => solveVRP(jobs, resources, s))
);

// Select best result based on business criteria
const best = selectOptimal(results);

4. Feature Toggling

Disable non-essential features for speed:

Maximum Speed
Balanced
Full Features

{
  "options": {
    "explanation": {"enabled": false},
    "traffic": 1.0
  }
}

{
  "options": {
    "explanation": {"enabled": false},
    "traffic": 1.1
  }
}

{
  "options": {
    "explanation": {"enabled": true},
    "traffic": 1.1,
    "polylines": true
  }
}

Common Performance Issues

Issue: Slow Initial Solutions

Symptoms

Long time to first feasible solution
Many jobs unassigned initially
Poor construction heuristic performance

Solutions

Relax hard constraints temporarily
Enable partial planning
Reduce initial problem size

Issue: Plateau in Optimization

Symptoms

Score stops improving
Move count remains high
No better solutions found

Solutions

Increase solve time (raise the millis query parameter)
Adjust weight balance
Add solution diversity

Issue: Memory Exhaustion

Symptoms

Out of memory errors
Slow garbage collection
System thrashing

Solutions

Reduce problem size
Disable explanation
Use geographic filtering

Best Practices

Performance Optimization Checklist:

Start Simple: Begin with minimal constraints and features
Measure Baseline: Record initial performance metrics
Profile Problems: Identify specific bottlenecks
Iterative Tuning: Make one change at a time
Cache Aggressively: Reuse distance calculations
Right-size Time: Don’t over-allocate solve time
Monitor Production: Track real-world performance
Document Settings: Record what works for your use case

Performance Benchmarks

Typical performance for well-configured problems:

Jobs	Vehicles	Constraints	Time	Quality
50	5	Basic	5s	Optimal
200	20	Moderate	30s	Near-optimal
500	50	Complex	120s	Very good
1000	100	Complex	300s	Good
2000	200	Moderate	600s	Feasible

Actual performance varies based on geographic distribution, constraint complexity, and hardware. Use these as rough guidelines only.

Constraint System

Understand constraint impact

Solution Quality

Balance speed vs quality

Cost Optimization

Optimize operational costs

Advanced Constraints

Complex constraint features

​Performance Optimization Guide

​Performance Fundamentals

​What Affects Solve Time?

​Performance Scaling

​Problem Size Guidelines

​Small Problems (< 100 jobs)

​Medium Problems (100-500 jobs)

​Large Problems (500-2000 jobs)

​Very Large Problems (> 2000 jobs)

​Configuration for Performance

​Essential Options

​Performance-Oriented Settings

​Distance Matrix Performance

​Matrix Types by Speed

​Distance Matrix Optimization

​Constraint Impact on Performance

​Low Impact Constraints

​Medium Impact Constraints

​High Impact Constraints

​Hardware Requirements

​Minimum Requirements

​Recommended Specifications

​Performance Monitoring

​Optimization Strategies

​1. Problem Decomposition

​2. Incremental Solving

​3. Parallel Processing

​4. Feature Toggling

​Common Performance Issues

​Issue: Slow Initial Solutions

​Issue: Plateau in Optimization

​Issue: Memory Exhaustion

​Best Practices

​Performance Benchmarks

​Related Topics

Constraint System

Solution Quality

Cost Optimization

Advanced Constraints

Performance Optimization Guide

Performance Fundamentals

What Affects Solve Time?

Performance Scaling

Problem Size Guidelines

Small Problems (< 100 jobs)

Medium Problems (100-500 jobs)

Large Problems (500-2000 jobs)

Very Large Problems (> 2000 jobs)

Configuration for Performance

Essential Options

Performance-Oriented Settings

Distance Matrix Performance

Matrix Types by Speed

Distance Matrix Optimization

Constraint Impact on Performance

Low Impact Constraints

Medium Impact Constraints

High Impact Constraints

Hardware Requirements

Minimum Requirements

Recommended Specifications

Performance Monitoring

Optimization Strategies

1. Problem Decomposition

2. Incremental Solving

3. Parallel Processing

4. Feature Toggling

Common Performance Issues

Issue: Slow Initial Solutions

Issue: Plateau in Optimization

Issue: Memory Exhaustion

Best Practices

Performance Benchmarks

Related Topics