> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Solutions with Explanations

> Learn how to analyze VRP solutions and explore alternative routing options using the explanation endpoint

## 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

<Info>
  Use explanations to debug infeasible solutions, optimize route quality, and provide transparency to end-users about routing decisions.
</Info>

## 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:

```bash cURL theme={null}
curl -X GET 'https://api.solvice.io/v2/vrp/jobs/{job_id}/explanation' \
    -H 'Authorization: YOUR_API_KEY'
```

### Understanding the Response

```json Score Breakdown theme={null}
{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -40,
    "feasible": true
  },
  "unresolved": [
    {
      "constraint": "TRAVEL_TIME",
      "score": "-40soft"
    }
  ]
}
```

<ResponseField name="score" type="object" required>
  Overall solution quality metrics.

  <Expandable title="Score components">
    <ResponseField name="hardScore" type="integer">
      Violations of hard constraints. Must be 0 for feasible solutions.
    </ResponseField>

    <ResponseField name="softScore" type="integer">
      Violations of soft constraints. Lower (more negative) values indicate worse solutions.
    </ResponseField>

    <ResponseField name="feasible" type="boolean">
      Whether the solution satisfies all hard constraints.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="unresolved" type="array">
  List of constraints contributing to the score.

  <Expandable title="Constraint details">
    <ResponseField name="constraint" type="string">
      Type of constraint (e.g., TRAVEL\_TIME, TIME\_WINDOW\_CONFLICT).
    </ResponseField>

    <ResponseField name="score" type="string">
      Impact on the solution score (e.g., "-40soft").
    </ResponseField>
  </Expandable>
</ResponseField>

## 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 `explanationOptions.enabled` to `true` in your solve request:

<CodeGroup>
  ```json Request with Alternatives theme={null}
  {
    "resources": [...],
    "jobs": [...],
    "options": {
      "explanationOptions": {
        "enabled": true
      }
    }
  }
  ```
</CodeGroup>

<Warning>
  Computing alternatives increases processing time. Only enable when you need detailed routing analysis.
</Warning>

### Alternative Position Response

The explanation now includes alternative positions for each job:

```json Alternatives Analysis theme={null}
{
  "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:

<ParamField body="suggestedArrival" type="timestamp" required>
  Proposed arrival time at the job location.
</ParamField>

<ParamField body="latestArrival" type="timestamp" required>
  Latest possible arrival time while maintaining schedule feasibility.
</ParamField>

<ParamField body="executedAfter" type="string" required>
  Identifier of the preceding job or trip start in this scenario.
</ParamField>

<ParamField body="violations" type="array">
  List of constraints violated in this alternative scenario.
</ParamField>

## Practical Example

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

<Steps>
  <Step title="Define the problem">
    Create a VRP request with two jobs and tight time windows:

    ```json VRP Request theme={null}
    {
      "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
          }]
        }
      ]
    }
    ```
  </Step>

  <Step title="Analyze the solution">
    The solver finds a feasible solution where job1 (with the tighter time window) is served first:

    ```json Solution theme={null}
    {
      "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"
          }
        ]
      }]
    }
    ```
  </Step>

  <Step title="Review alternatives">
    The explanation reveals why job2 cannot be served first:

    ```json Alternative Analysis theme={null}
    {
      "alternatives": {
        "job2": [{
          "suggestedArrival": "2023-01-01T09:00:34",
          "violations": [{
            "constraint": "DATE_TIME_WINDOW_CONFLICT",
            "score": "-639hard"
          }]
        }]
      }
    }
    ```

    <Note>
      Job1's narrow time window (09:00-09:20) would be violated if job2 were served first, making this alternative infeasible.
    </Note>
  </Step>
</Steps>

## Common Constraint Types

Understanding constraint violations helps you improve your routing solutions:

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Best Practices

<Cards>
  <Card title="Debug Infeasible Solutions" icon="bug">
    Start by examining hard constraint violations to identify why no feasible solution exists.
  </Card>

  <Card title="Optimize Soft Constraints" icon="chart-line">
    Once feasible, focus on reducing soft constraint violations to improve solution quality.
  </Card>

  <Card title="Use Alternatives Wisely" icon="route">
    Enable alternatives only when investigating specific routing decisions to manage processing time.
  </Card>
</Cards>

## Next Steps

* Explore [constraint configuration](/guides/vrp/concepts/constraint-system) to customize routing behavior
* Learn about [scoring optimization](/guides/vrp/concepts/scoring-explanation) to balance multiple objectives
* Review [performance tuning](/guides/vrp/concepts/performance-guide) for large-scale routing problems