Understanding Solutions with Explanations

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

curl -X GET 'https://api.solvice.io/v2/vrp/jobs/{job_id}/explanation' \
    -H 'Authorization: YOUR_API_KEY'

Understanding the Response

Score Breakdown

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -40,
    "feasible": true
  },
  "unresolved": [
    {
      "constraint": "TRAVEL_TIME",
      "score": "-40soft"
    }
  ]
}

object

required

Overall solution quality metrics.

Show Score components

integer

Violations of hard constraints. Must be 0 for feasible solutions.

integer

Violations of soft constraints. Lower (more negative) values indicate worse solutions.

boolean

Whether the solution satisfies all hard constraints.

array

List of constraints contributing to the score.

Show Constraint details

string

Type of constraint (e.g., TRAVEL_TIME, TIME_WINDOW_CONFLICT).

string

Impact on the solution score (e.g., “-40soft”).

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

Set options.explanation.enabled to true in your solve request:

{
  "resources": [...],
  "jobs": [...],
  "options": {
    "explanation": {
      "enabled": true
    }
  }
}

Computing alternatives increases processing time. Only enable when you need detailed routing analysis.

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

{
  "options": {
    "explanation": {
      "enabled": true,
      "onlyUnassigned": true,
      "maxDurationMillis": 30000,
      "maxExplainedJobs": 500,
      "maxAlternativesPerJob": 25
    }
  }
}

boolean

default:"false"

Generate alternatives only for jobs that could not be served, instead of for every job.

integer

default:"30000"

Wall-clock budget for generating alternatives. Checked between candidate positions, so a single job cannot consume the whole budget.

integer

default:"500"

Maximum number of jobs alternatives are generated for.

integer

default:"25"

Maximum number of alternative positions kept per job, best score first.

Set any of these to 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 a unservedReasons map, as exhaustive.

Truncated Explanation

{
  "score": { "hardScore": -639, "softScore": -39, "feasible": false },
  "alternatives": { "...": [] },
  "truncation": {
    "reason": "TIME_LIMIT_EXCEEDED",
    "message": "Explanation stopped after 30000 ms. Analysed 412 of 8186 jobs.",
    "analysedJobs": 412,
    "totalJobs": 8186,
    "cappedJobs": 0,
    "limitMillis": 30000
  }
}

The same object appears on the solution as 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”.

string

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.

integer

How many jobs were examined, out of totalJobs. A job with no viable insertion position is counted here but produces no entry in alternatives.

integer

How many analysed jobs had their alternative list trimmed to maxAlternativesPerJob.

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

{
  "score": {
    "hardScore": 0,
    "softScore": -40,
    "feasible": true
  },
  "alternatives": {
    "job2": [
      {
        "job": "job2",
        "resource": "worker1",
        "suggestedArrival": "2023-01-01T09:00:34",
        "latestArrival": "2023-01-01T09:00:34",
        "executedAfter": "worker12023-01-01",
        "score": {
          "hardScore": -639,
          "softScore": -39,
          "feasible": false
        },
        "violations": [
          {
            "constraint": "DATE_TIME_WINDOW_CONFLICT",
            "score": "-639hard"
          }
        ]
      }
    ]
  }
}

Each alternative position includes:

timestamp

required

Proposed arrival time at the job location.

timestamp

required

Latest possible arrival time while maintaining schedule feasibility.

string

required

Identifier of the preceding job or trip start in this scenario.

array

List of constraints violated in this alternative scenario.

Practical Example

Let’s analyze a routing scenario with time window constraints:

Define the problem

Create a VRP request with two jobs and tight time windows:

VRP Request

{
  "resources": [
    {
      "name": "worker1",
      "start": {
        "latitude": 51.056,
        "longitude": 3.7267
      },
      "shifts": [{
        "from": "2023-01-01T09:00:00",
        "to": "2023-01-01T20:00:00"
      }]
    }
  ],
  "jobs": [
    {
      "name": "job1",
      "location": {
        "latitude": 51.0541,
        "longitude": 3.7227
      },
      "duration": 1800,
      "windows": [{
        "from": "2023-01-01T09:00:00",
        "to": "2023-01-01T09:20:00",
        "hard": true
      }]
    },
    {
      "name": "job2",
      "location": {
        "latitude": 51.0538,
        "longitude": 3.7233
      },
      "duration": 1800,
      "windows": [{
        "from": "2023-01-01T09:00:00",
        "to": "2023-01-01T20:00:00",
        "hard": true
      }]
    }
  ]
}

Analyze the solution

The solver finds a feasible solution where job1 (with the tighter time window) is served first:

Solution

{
  "score": {
    "hardScore": 0,
    "softScore": -40,
    "feasible": true
  },
  "trips": [{
    "visits": [
      {
        "arrival": "2023-01-01T09:00:35",
        "job": "job1"
      },
      {
        "arrival": "2023-01-01T09:30:40",
        "job": "job2"
      }
    ]
  }]
}

Review alternatives

The explanation reveals why job2 cannot be served first:

Alternative Analysis

{
  "alternatives": {
    "job2": [{
      "suggestedArrival": "2023-01-01T09:00:34",
      "violations": [{
        "constraint": "DATE_TIME_WINDOW_CONFLICT",
        "score": "-639hard"
      }]
    }]
  }
}

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)

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)

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

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

Platform

VRP API

Fill API

Understanding Solutions with Explanations

Overview

Basic Explanation

Request a Simple Explanation

Understanding the Response

Alternative Positions Analysis

Enable Alternative Analysis

Limiting the Cost of Alternatives

Detecting a Truncated Explanation

Alternative Position Response

Practical Example

Common Constraint Types

Best Practices

Next Steps

​Overview

​Basic Explanation

​Request a Simple Explanation

​Understanding the Response

​Alternative Positions Analysis

​Enable Alternative Analysis

​Limiting the Cost of Alternatives

​Detecting a Truncated Explanation

​Alternative Position Response

​Practical Example

​Common Constraint Types

​Best Practices

​Next Steps

Overview

Basic Explanation

Request a Simple Explanation

Understanding the Response

Alternative Positions Analysis

Enable Alternative Analysis

Limiting the Cost of Alternatives

Detecting a Truncated Explanation

Alternative Position Response

Practical Example

Common Constraint Types

Best Practices

Next Steps