Overview
The explanation endpoint helps you understand why the VRP solver made specific routing decisions. It provides:- Detailed breakdown of constraint violations and their impact on the solution score
- Alternative routing scenarios for each job
- Insights into why certain solutions are infeasible
Use explanations to debug infeasible solutions, optimize route quality, and provide transparency to end-users about routing decisions.
Basic Explanation
Every VRP solution includes a score that reflects the quality of the routing plan. The explanation endpoint breaks down this score by constraint.Request a Simple Explanation
After solving a VRP problem, retrieve the explanation using:cURL
Understanding the Response
Score Breakdown
Alternative Positions Analysis
Enable alternative position analysis to explore what-if scenarios for job routing. This feature evaluates all possible positions for each job and explains why certain placements were rejected.Enable Alternative Analysis
Setoptions.explanation.enabled to true in your solve request:
Limiting the Cost of Alternatives
Alternative generation runs after the solver has finished, and its cost grows with the size of the unassigned set: the number of alternatives per job equals the number of served jobs plus empty shifts. On a large, heavily unassigned instance an unbounded explanation can take minutes and serialize to gigabytes, so three limits apply by default.Request with Explanation Limits
Generate alternatives only for jobs that could not be served, instead of for every job.
Wall-clock budget for generating alternatives. Checked between candidate positions, so a single job
cannot consume the whole budget.
0 to disable that limit. Doing so is not supported on large instances.
Detecting a Truncated Explanation
When a limit is hit, the explanation is still returned, and both the explanation and the solution carry a warning. Read it before treating a list of alternatives, or aunservedReasons map, as exhaustive.
Truncated Explanation
explanationTruncation. This matters most for
unservedReasons: it is derived from the alternatives, and an unserved job that was not analysed still
gets an entry there, with an empty reason list that is indistinguishable from “nothing blocked it”.
TIME_LIMIT_EXCEEDED, JOB_LIMIT_EXCEEDED or ALTERNATIVES_CAPPED. The first two mean the sweep stopped
early; the third means every job was analysed but some alternative lists were trimmed.How many jobs were examined, out of
totalJobs. A job with no viable insertion position is counted here
but produces no entry in alternatives.The
truncation and explanationTruncation fields are absent when the explanation is complete, so an
empty result for a job only means “nothing found” when they are not set.Alternative Position Response
The explanation now includes alternative positions for each job:Alternatives Analysis
Practical Example
Let’s analyze a routing scenario with time window constraints:1
Define the problem
Create a VRP request with two jobs and tight time windows:
VRP Request
2
Analyze the solution
The solver finds a feasible solution where job1 (with the tighter time window) is served first:
Solution
3
Review alternatives
The explanation reveals why job2 cannot be served first:
Alternative Analysis
Job1’s narrow time window (09:00-09:20) would be violated if job2 were served first, making this alternative infeasible.
Common Constraint Types
Understanding constraint violations helps you improve your routing solutions:Hard Constraints (Must be satisfied)
Hard Constraints (Must be satisfied)
- TIME_WINDOW_CONFLICT: Job served outside its time window
- SHIFT_END_CONFLICT: Route extends beyond worker shift
- ALLOWED_RESOURCES: Job assigned to unauthorized resource
- TAG_HARD: Required skills/equipment missing
- TRIP_CAPACITY: Vehicle capacity exceeded
Soft Constraints (Optimization goals)
Soft Constraints (Optimization goals)
- TRAVEL_TIME: Total travel time minimization
- WAIT_TIME: Idle time between jobs
- RESOURCE_USAGE: Number of resources utilized
- FAIR_WORK: Workload distribution balance
- PREFERRED_RESOURCE_CONFLICT: Preference violations
Best Practices
Debug Infeasible Solutions
Start by examining hard constraint violations to identify why no feasible solution exists.
Optimize Soft Constraints
Once feasible, focus on reducing soft constraint violations to improve solution quality.
Use Alternatives Wisely
Enable alternatives only when investigating specific routing decisions to manage processing time.
Next Steps
- Explore constraint configuration to customize routing behavior
- Learn about scoring optimization to balance multiple objectives
- Review performance tuning for large-scale routing problems