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

# Performance Optimization Guide

> Maximize VRP solver performance and understand factors affecting solution speed

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

```mermaid theme={null}
mindmap
  root((VRP Performance))
    Problem Complexity
      Number of jobs
      Number of vehicles
      Constraint types
      Geographic spread
    Configuration
      Time limit
      Constraint weights
      Options/features
      Distance matrix
    Hardware
      CPU cores
      Memory
      Network latency
      Disk I/O
```

### Performance Scaling

The solver's time complexity increases with:

<Tabs>
  <Tab title="Linear Factors">
    * Number of jobs (O(n))
    * Number of resources
    * Number of time windows
    * Basic constraints
  </Tab>

  <Tab title="Quadratic Factors">
    * Distance calculations (O(n²))
    * Job relations
    * Complex constraints
    * Alternative assignments
  </Tab>

  <Tab title="Exponential Factors">
    * Optimal solution search
    * Complex interdependencies
    * Multi-objective optimization
    * Large solution spaces
  </Tab>
</Tabs>

## Problem Size Guidelines

### Small Problems (\< 100 jobs)

<CodeGroup>
  ```json Configuration theme={null}
  {
    "options": {
      "solveTime": 10  // 10 seconds usually sufficient
    }
  }
  ```

  ```json Performance theme={null}
  {
    "typicalSolveTime": "5-10 seconds",
    "expectedQuality": "Near-optimal",
    "resourceUsage": "Minimal"
  }
  ```
</CodeGroup>

### Medium Problems (100-500 jobs)

<CodeGroup>
  ```json Configuration theme={null}
  {
    "options": {
      "solveTime": 60,  // 1 minute
      "constructionHeuristic": "FIRST_FIT"
    }
  }
  ```

  ```json Performance theme={null}
  {
    "typicalSolveTime": "30-60 seconds",
    "expectedQuality": "Very good",
    "resourceUsage": "Moderate"
  }
  ```
</CodeGroup>

### Large Problems (500-2000 jobs)

<CodeGroup>
  ```json Configuration theme={null}
  {
    "options": {
      "solveTime": 300,  // 5 minutes
      "constructionHeuristic": "CHEAPEST_INSERTION",
      "localSearchType": "TABU_SEARCH"
    }
  }
  ```

  ```json Performance theme={null}
  {
    "typicalSolveTime": "3-5 minutes",
    "expectedQuality": "Good feasible solutions",
    "resourceUsage": "Significant"
  }
  ```
</CodeGroup>

### Very Large Problems (> 2000 jobs)

<CodeGroup>
  ```json Configuration theme={null}
  {
    "options": {
      "solveTime": 600,  // 10 minutes
      "partialPlanning": true,
      "nearbySelection": {
        "enabled": true,
        "maxDistance": 50000  // 50km
      }
    }
  }
  ```

  ```json Performance theme={null}
  {
    "typicalSolveTime": "5-10 minutes",
    "expectedQuality": "Feasible solutions",
    "resourceUsage": "High",
    "recommendation": "Consider problem decomposition"
  }
  ```
</CodeGroup>

## Configuration for Performance

### Essential Options

<ParamField body="solveTime" type="integer" default="120">
  Maximum solve time in seconds. Balance between quality and speed.
</ParamField>

<ParamField body="constructionHeuristic" type="string" default="AUTO">
  Initial solution strategy. Options:

  * `FIRST_FIT`: Fastest, lower quality
  * `CHEAPEST_INSERTION`: Balanced
  * `AUTO`: Solver chooses based on problem
</ParamField>

<ParamField body="localSearchType" type="string" default="AUTO">
  Optimization algorithm:

  * `LATE_ACCEPTANCE`: Good for tight time windows
  * `TABU_SEARCH`: Good for complex constraints
  * `AUTO`: Adaptive selection
</ParamField>

### Performance-Oriented Settings

<Tabs>
  <Tab title="Speed Priority">
    ```json theme={null}
    {
      "options": {
        "solveTime": 30,
        "constructionHeuristic": "FIRST_FIT",
        "partialPlanning": true,
        "explanation": {
          "enabled": false  // Disable for speed
        }
      }
    }
    ```

    Fast solutions with reasonable quality.
  </Tab>

  <Tab title="Quality Priority">
    ```json theme={null}
    {
      "options": {
        "solveTime": 300,
        "constructionHeuristic": "CHEAPEST_INSERTION",
        "localSearchType": "TABU_SEARCH",
        "moveThreadCount": 4
      }
    }
    ```

    Better solutions with more computation.
  </Tab>

  <Tab title="Balanced">
    ```json theme={null}
    {
      "options": {
        "solveTime": 120,
        "constructionHeuristic": "AUTO",
        "localSearchType": "AUTO"
      }
    }
    ```

    Good trade-off for most use cases.
  </Tab>
</Tabs>

## Distance Matrix Performance

Distance calculations significantly impact performance:

### Matrix Types by Speed

<Steps>
  <Step title="Euclidean (Fastest)">
    ```json theme={null}
    {
      "distanceUnit": "meter",
      "distanceCalculation": "EUCLIDEAN"
    }
    ```

    * No external API calls
    * Instant calculation
    * Lower accuracy
  </Step>

  <Step title="Haversine (Fast)">
    ```json theme={null}
    {
      "distanceUnit": "meter",
      "distanceCalculation": "HAVERSINE"
    }
    ```

    * No external API calls
    * Quick calculation
    * Good for aerial distance
  </Step>

  <Step title="Road Distance (Slower)">
    ```json theme={null}
    {
      "distanceMatrixType": "osm",
      "distanceMatrix": {
        "profile": "car"
      }
    }
    ```

    * External API calls
    * Caching helps
    * Most accurate
  </Step>
</Steps>

### Distance Matrix Optimization

<Tip>
  **Caching Strategy**:

  1. Pre-calculate frequently used distances
  2. Store in request for reuse
  3. Use `matrixId` for persistent caching
  4. Limit unique locations
</Tip>

<CodeGroup>
  ```json With Caching theme={null}
  {
    "distanceMatrix": {
      "matrixId": "city-center-matrix-v2",
      "cache": true,
      "profile": "car"
    }
  }
  ```

  ```json Pre-calculated theme={null}
  {
    "distanceMatrix": {
      "distances": [[0, 1000, 2000], [1000, 0, 1500], [2000, 1500, 0]],
      "durations": [[0, 120, 240], [120, 0, 180], [240, 180, 0]]
    }
  }
  ```
</CodeGroup>

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

<Warning>
  **Performance Tips**:

  * Minimize hard constraints
  * Avoid unnecessary job relations
  * Use reasonable time window widths
  * Limit alternative calculations
</Warning>

## Hardware Requirements

### Minimum Requirements

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

### Recommended Specifications

<Tabs>
  <Tab title="Small Fleet (< 10 vehicles)">
    * **CPU**: 4 cores
    * **Memory**: 8GB RAM
    * **Network**: 50 Mbps
    * **Storage**: 5GB free
  </Tab>

  <Tab title="Medium Fleet (10-50 vehicles)">
    * **CPU**: 8 cores
    * **Memory**: 16GB RAM
    * **Network**: 100 Mbps
    * **Storage**: 10GB free
  </Tab>

  <Tab title="Large Fleet (> 50 vehicles)">
    * **CPU**: 16+ cores
    * **Memory**: 32GB+ RAM
    * **Network**: 1 Gbps
    * **Storage**: 20GB+ free
  </Tab>
</Tabs>

## Performance Monitoring

### Key Metrics to Track

```json theme={null}
{
  "performance": {
    "solveTimeInMillis": 45230,
    "scoreCalculationCount": 125000,
    "moveEvaluationCount": 89000,
    "bestScoreTime": 38500,
    "timeToFirstFeasible": 12300,
    "memoryUsageMB": 1250
  }
}
```

### Performance Indicators

| Metric                 | Good             | Warning    | Critical    |
| ---------------------- | ---------------- | ---------- | ----------- |
| Time to First Feasible | \< 20% of limit  | 20-50%     | > 50%       |
| Score Improvement Rate | > 1%/sec         | 0.1-1%/sec | \< 0.1%/sec |
| Memory Usage           | \< 50% available | 50-80%     | > 80%       |
| Move Evaluations/sec   | > 1000           | 100-1000   | \< 100      |

## Optimization Strategies

### 1. Problem Decomposition

For very large problems, consider:

<Steps>
  <Step title="Geographic Clustering">
    Divide by regions or zones
  </Step>

  <Step title="Temporal Splitting">
    Separate by time periods
  </Step>

  <Step title="Resource Grouping">
    Partition by vehicle types
  </Step>

  <Step title="Priority Batching">
    Process high-priority first
  </Step>
</Steps>

### 2. Incremental Solving

<CodeGroup>
  ```json Phase 1: Core Jobs theme={null}
  {
    "jobs": ["high-priority-jobs"],
    "options": {"solveTime": 60}
  }
  ```

  ```json Phase 2: Additional Jobs theme={null}
  {
    "jobs": ["all-jobs"],
    "warmStart": {"solutionId": "phase1-solution"},
    "options": {"solveTime": 120}
  }
  ```
</CodeGroup>

### 3. Parallel Processing

When possible, run multiple scenarios:

```javascript theme={null}
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:

<Tabs>
  <Tab title="Maximum Speed">
    ```json theme={null}
    {
      "options": {
        "explanation": {"enabled": false},
        "alternativeStop": {"enabled": false},
        "traffic": {"enabled": false},
        "nearbySelection": {"enabled": true}
      }
    }
    ```
  </Tab>

  <Tab title="Balanced">
    ```json theme={null}
    {
      "options": {
        "explanation": {"enabled": false},
        "alternativeStop": {"enabled": true},
        "traffic": {"enabled": true, "lightweight": true}
      }
    }
    ```
  </Tab>

  <Tab title="Full Features">
    ```json theme={null}
    {
      "options": {
        "explanation": {"enabled": true},
        "alternativeStop": {"enabled": true},
        "traffic": {"enabled": true},
        "historicalTraffic": {"enabled": true}
      }
    }
    ```
  </Tab>
</Tabs>

## Common Performance Issues

### Issue: Slow Initial Solutions

<AccordionGroup>
  <Accordion title="Symptoms">
    * Long time to first feasible solution
    * Many jobs unassigned initially
    * Poor construction heuristic performance
  </Accordion>

  <Accordion title="Solutions">
    1. Relax hard constraints temporarily
    2. Use `FIRST_FIT` construction
    3. Enable partial planning
    4. Reduce initial problem size
  </Accordion>
</AccordionGroup>

### Issue: Plateau in Optimization

<AccordionGroup>
  <Accordion title="Symptoms">
    * Score stops improving
    * Move count remains high
    * No better solutions found
  </Accordion>

  <Accordion title="Solutions">
    1. Increase solve time
    2. Adjust weight balance
    3. Try different local search
    4. Add solution diversity
  </Accordion>
</AccordionGroup>

### Issue: Memory Exhaustion

<AccordionGroup>
  <Accordion title="Symptoms">
    * Out of memory errors
    * Slow garbage collection
    * System thrashing
  </Accordion>

  <Accordion title="Solutions">
    1. Reduce problem size
    2. Disable explanation
    3. Limit move thread count
    4. Use geographic filtering
  </Accordion>
</AccordionGroup>

## Best Practices

<Check>
  **Performance Optimization Checklist**:

  1. **Start Simple**: Begin with minimal constraints and features
  2. **Measure Baseline**: Record initial performance metrics
  3. **Profile Problems**: Identify specific bottlenecks
  4. **Iterative Tuning**: Make one change at a time
  5. **Cache Aggressively**: Reuse distance calculations
  6. **Right-size Time**: Don't over-allocate solve time
  7. **Monitor Production**: Track real-world performance
  8. **Document Settings**: Record what works for your use case
</Check>

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

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

## Related Topics

<CardGroup cols={2}>
  <Card title="Constraint System" icon="link" href="/guides/vrp/concepts/constraint-system">
    Understand constraint impact
  </Card>

  <Card title="Solution Quality" icon="chart-line" href="/guides/vrp/concepts/solution-quality">
    Balance speed vs quality
  </Card>

  <Card title="Cost Optimization" icon="route" href="/guides/vrp/features/cost-optimization">
    Optimize operational costs
  </Card>

  <Card title="Advanced Constraints" icon="wrench" href="/guides/vrp/features/advanced-constraints">
    Complex constraint features
  </Card>
</CardGroup>