Explanation

The explanation endpoint returns the score and the constraints that are violated in the current solution. It can give the insights into why a solve was like it is.

Name	Type	Description
`score`	Score	Score
`conflicts`	Conflict	Conflicts
`unresolved`	Unresolved	Unresolved constraints
`alternatives`	map of job name to [Alternative]	Alternative assignments per job when explanation is enabled (optional)
`truncation`	Truncation	Present only when a limit in `options.explanation` cut the alternatives short (optional)

Example:

explanation

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -6924,
    "feasible": true
  },
  "unresolved": [
    {
      "constraint": "JOB_DAY_INDEX",
      "score": "-7soft"
    },
    {
      "constraint": "TRAVEL_TIME",
      "score": "-6917soft"
    },
    {
      "constraint": "UNUSED_RESOURCES",
      "score": "-25200medium"
    }
  ]
}

Truncation

Absent when the explanation is complete. When present, the alternatives map is partial - and so is the unservedReasons map on the solution, which carries the same object as explanationTruncation.

Name	Type	Description
`reason`	string	`TIME_LIMIT_EXCEEDED`, `JOB_LIMIT_EXCEEDED` or `ALTERNATIVES_CAPPED`
`message`	string	Human readable summary of what was skipped
`analysedJobs`	integer	Number of jobs that were examined (a job with no viable position yields no entry)
`totalJobs`	integer	Number of jobs that were eligible for an explanation
`cappedJobs`	integer	Number of analysed jobs whose alternative list was trimmed
`limitMillis`	integer	The wall-clock budget that applied, in milliseconds
`maxAlternativesPerJob`	integer	The per-job alternative cap that applied

Unresolved

Name	Type	Description
`constraint`	string	Routing constraint name
`score`	string	score of this constraint

Conflict

Name	Type	Description
`constraint`	RoutingConstraint	Routing constraint name
`score`	string	score of this constraint
`job`	string	job name in this conflict
`resource`	string	resource name in this conflict
`tag`	string	tag name in this conflict

Alternative

The alternatives field is a map keyed by job name; each value is a list of assignments (Alternative) showing where else that job could go and what it would cost.

Name	Type	Description
`job`	string	Job name
`resource`	string	Resource name
`suggestedArrival`	string (ISO 8601)	Suggested arrival date-time
`latestArrival`	string (ISO 8601)	Latest arrival date-time
`executedAfter`	string	Name of the job executed right before this one
`suggestedInitialArrival`	string (ISO 8601)	Suggested initial arrival date-time (optional)
`score`	Score	Score of this alternative assignment
`violations`	[Unresolved]	Constraints violated by this alternative assignment (optional)

Constraint

The following constraints can appear in the explanation response:

Name	Description	Impact
`TRIP_CAPACITY`	Vehicle capacity exceeded for a trip	hard
`RESOURCE_CAPACITY`	Resource capacity exceeded	hard
`RESOURCE_CAPACITY2`	Secondary resource capacity exceeded	hard
`TRAVEL_TIME`	Travel time optimization	soft
`TYPE_REQUIREMENT`	Job type requirements not met by resource	hard
`TAG_SOFT`	Soft tag preference not satisfied	soft
`TAG_HARD`	Hard tag requirement not satisfied	hard
`TYPE_REQUIREMENT_SOFT`	Soft type requirement not satisfied	soft
`END_LOCATION_TRAVEL_TIME`	Travel time from last job to end location	soft
`TIME_WINDOW_CONFLICT`	Job scheduled outside its time window	hard
`SHIFT_END_CONFLICT`	Job extends beyond resource shift end time	hard
`OVERTIME_END_CONFLICT`	Job extends beyond overtime limit	hard
`RESOURCE_USAGE`	Resource usage optimization	medium
`URGENCY`	Urgent job scheduling priority	soft
`PREFERRED_RESOURCE_CONFLICT`	Job not assigned to preferred resource	soft
`ALLOWED_RESOURCES`	Job assigned to non-allowed resource	hard
`DISALLOWED_RESOURCES`	Job assigned to disallowed resource	hard
`REGION_TIME`	Regional time constraint violation	soft
`FAIR_WORK`	Work distribution fairness across resources	soft
`UNSERVED_JOBS`	Jobs that could not be scheduled	medium
`RESOURCE_ACTIVATION`	Resource activation cost	medium
`OPEN_DAYS`	Resource scheduled on non-working day	hard
`JOB_PRECEDENCE`	Job precedence order violated	hard
`JOB_DAY_INDEX`	Job not scheduled on required day	soft
`DATE_TIME_WINDOW_CONFLICT`	Job scheduled outside date/time window	hard
`DATE_TIME_WINDOW_CONFLICT_SOFT`	Soft date/time window preference not met	soft
`LINKED_JOB_CONFLICT`	Linked jobs constraint violation	hard
`PLANNED_RESOURCE`	Job not assigned to planned resource	soft
`PLANNED_ARRIVAL`	Job arrival time differs from planned	soft
`PLANNED_DATE`	Job scheduled on different date than planned	soft
`WORKING_TIME`	Total working time constraint	soft
`HARD_JOBS`	Hard job requirement not satisfied	hard
`MAX_DRIVE_TIME`	Maximum drive time per resource exceeded	hard
`MAX_DRIVE_TIME_JOB`	Maximum drive time per job exceeded	hard
`FAIR_TOTAL_WORK`	Total work fairness across resources	soft
`RESOURCE_PERIOD_MAX_SERVICE_TIME`	Maximum service time per period exceeded	hard
`RESOURCE_PERIOD_MAX_DRIVE_TIME`	Maximum drive time per period exceeded	hard
`RESOURCE_PERIOD_MAX_WORK_TIME`	Maximum work time per period exceeded	hard
`RESOURCE_PERIOD_MIN_SERVICE_TIME`	Minimum service time per period not met	soft
`RESOURCE_PERIOD_MIN_DRIVE_TIME`	Minimum drive time per period not met	soft
`RESOURCE_PERIOD_MIN_WORK_TIME`	Minimum work time per period not met	soft
`MINIMISE_TRIP_USAGE`	Trip usage minimization	soft
`DELIVERY_NOT_ON_SAME_VEHICLE`	Pickup and delivery not on same vehicle	hard
`DELIVERY_BEFORE_PICKUP`	Delivery scheduled before pickup	hard
`SAME_TRIP`	Jobs must be on same trip	hard
`SEQUENCE`	Job sequence constraint	hard
`SAME_TIME`	Jobs must be at same time	hard
`NEIGHBOR`	Jobs must be neighbors in sequence	hard
`DIRECT_SEQUENCE`	Jobs must be in direct sequence	hard
`SAME_RESOURCE`	Jobs must be assigned to same resource	hard
`WAIT_TIME`	Wait time optimization	soft
`DRIVE_TIME`	Drive time optimization	soft

Explains the conflicts of a certain routing solution and the unresolved constraints.

score

object

required

Score of the solution.

Show child attributes

conflicts

object

Conflicts in the solution

object[]
object

Show child attributes

Example:

{
  "constraint": "TIME_WINDOW_CONFLICT",
  "score": "-1000",
  "job": "Job-1",
  "resource": "vehicle-1"
}

unresolved

object

Unresolved constraints in the solution

object[]
object

Show child attributes

Example:

{
  "constraint": "TRAVEL_TIME",
  "score": "-1500"
}

alternatives

object | null

When options.explanation.enabled is set to true, this field will contain the alternatives for the solution.The key is the job name and the value is the list of assignments. Each assignment contains the resource, the date, and the score. In this way, you can check the impact of the alternative on the score.

Show child attributes

Example:

{
  "Job-1": [
    {
      "job": "Job-1",
      "resource": "vehicle-2",
      "suggestedArrival": "2023-01-13T09:30:00Z",
      "latestArrival": "2023-01-13T10:00:00Z",
      "executedAfter": "Job-0",
      "score": {
        "hard": 0,
        "soft": -1500,
        "feasible": true
      }
    }
  ]
}

Platform

VRP API

Fill API

Truncation

Unresolved

Conflict

Alternative

Constraint

​Truncation

​Unresolved

​Conflict

​Alternative

​Constraint

Truncation

Unresolved

Conflict

Alternative

Constraint