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

# Advanced Time Features

> Fine-tune scheduling with time rounding, padding, and dynamic routing features

# Advanced Time Features

Beyond basic time windows and scheduling, the VRP solver offers advanced time features for precise control over arrival times, service scheduling, and multi-day optimization. This guide covers snapUnit, job padding, overtime management, and time-dependent routing.

## Time Snapping (snapUnit)

Round arrival times to specific intervals for cleaner schedules:

```json theme={null}
{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "delivery-1",
      "duration": 1800
    }
  ],
  "options": {
    "snapUnit": 900  // 15-minute intervals
  }
}
```

### How snapUnit Works

<Info>
  **Snap Behavior**: Arrival times are rounded UP to the nearest snapUnit interval.

  * Actual arrival: 9:03 → Snapped to: 9:15
  * Actual arrival: 9:15 → Stays at: 9:15
  * Actual arrival: 9:16 → Snapped to: 9:30
</Info>

### Common snapUnit Values

<Tabs>
  <Tab title="5 Minutes">
    ```json theme={null}
    {
      "options": {
        "snapUnit": 300  // Professional services
      }
    }
    ```

    For businesses with flexible scheduling
  </Tab>

  <Tab title="15 Minutes">
    ```json theme={null}
    {
      "options": {
        "snapUnit": 900  // Standard appointments
      }
    }
    ```

    Most common for service industries
  </Tab>

  <Tab title="30 Minutes">
    ```json theme={null}
    {
      "options": {
        "snapUnit": 1800  // Block scheduling
      }
    }
    ```

    For longer appointments or deliveries
  </Tab>

  <Tab title="1 Hour">
    ```json theme={null}
    {
      "options": {
        "snapUnit": 3600  // Hourly slots
      }
    }
    ```

    Simple scheduling for low-precision needs
  </Tab>
</Tabs>

### Impact on Routes

<Steps>
  <Step title="Calculate Natural Arrival">
    Solver determines optimal arrival time
  </Step>

  <Step title="Apply Snap Rounding">
    Round up to next snapUnit interval
  </Step>

  <Step title="Add Wait Time">
    Driver waits if arrived before snapped time
  </Step>

  <Step title="Start Service">
    Begin job at snapped arrival time
  </Step>
</Steps>

## Job Padding

Add buffer time before and after jobs:

```json theme={null}
{
  "resources": [
    {
      "name": "technician-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "complex-installation",
      "duration": 3600,  // 1 hour service
      "padding": 300,    // 5 minutes before AND after
      "location": {
        "latitude": 51.0543,
        "longitude": 3.7174
      }
    }
  ]
}
```

### Padding Use Cases

<AccordionGroup>
  <Accordion title="Setup/Teardown Time">
    ```json theme={null}
    {
      "name": "equipment-service",
      "duration": 1800,  // 30 min service
      "padding": 600     // 10 min setup/cleanup
    }
    ```

    Total time blocked: 50 minutes
  </Accordion>

  <Accordion title="Customer Preparation">
    ```json theme={null}
    {
      "name": "home-delivery",
      "duration": 300,   // 5 min delivery
      "padding": 180     // 3 min for customer to answer
    }
    ```

    Ensures customer readiness
  </Accordion>

  <Accordion title="Safety Buffer">
    ```json theme={null}
    {
      "name": "medical-appointment",
      "duration": 2700,  // 45 min appointment
      "padding": 900     // 15 min safety margin
    }
    ```

    Prevents appointment overruns
  </Accordion>
</AccordionGroup>

### Padding vs snapUnit Interaction

<Warning>
  **Important**: Padding is applied AFTER snap calculations.

  Example with snapUnit=900 (15 min) and padding=300 (5 min):

  1. Natural arrival: 9:03
  2. Snapped arrival: 9:15
  3. Actual service start: 9:20 (after padding)
  4. Service end: 10:20
  5. Ready for next job: 10:25 (after padding)
</Warning>

## Advanced Overtime Management

Configure flexible overtime with graduated penalties:

```json theme={null}
{
  "resources": [{
    "name": "driver-1",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T17:00:00Z",
      "overtimeEnd": "2024-03-15T20:00:00Z"
    }],
    "hourlyCost": 25
  }],
  "jobs": [{
    "name": "late-job",
    "duration": 3600
  }],
  "weights": {
    "overtimeWeight": 100
  }
}
```

### Overtime Strategies

<Tabs>
  <Tab title="Simple Overtime">
    ```json theme={null}
    {
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z",
        "overtimeEnd": "2024-03-15T19:00:00Z"
      }],
      "hourlyCost": 30
    }
    ```
  </Tab>

  <Tab title="Graduated Penalties">
    ```json theme={null}
    {
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z",
        "overtimeEnd": "2024-03-15T20:00:00Z"
      }],
      "weights": {
        "overtimeWeight": 100
      }
    }
    ```
  </Tab>

  <Tab title="Hard Cutoff">
    ```json theme={null}
    {
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z",
        "overtimeEnd": "2024-03-15T18:00:00Z"  // 1 hour max
      }],
      "weights": {
        "overtimeWeight": 1000   // Effectively prevents
      }
    }
    ```
  </Tab>
</Tabs>

## Time-Dependent Routing

Account for traffic patterns and rush hours:

```json theme={null}
{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T06:00:00Z",
        "to": "2024-03-15T19:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "morning-delivery",
      "duration": 1800,
      "windows": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T10:00:00Z"
      }]
    },
    {
      "name": "afternoon-delivery",
      "duration": 1800,
      "windows": [{
        "from": "2024-03-15T14:00:00Z",
        "to": "2024-03-15T16:00:00Z"
      }]
    }
  ],
  "options": {
    "distanceMatrixType": "OSM_ROUTE"
  }
}
```

### Traffic Pattern Modeling

<Steps>
  <Step title="Define Time Periods">
    Identify distinct traffic patterns:

    * Morning rush: 6-9 AM
    * Midday: 9 AM-4 PM
    * Evening rush: 4-7 PM
    * Night: 7 PM-6 AM
  </Step>

  <Step title="Create Period Matrices">
    Generate distance matrices for each period with realistic travel times
  </Step>

  <Step title="Configure Transitions">
    Solver automatically interpolates between periods
  </Step>

  <Step title="Validate Results">
    Check routes avoid heavy traffic when possible
  </Step>
</Steps>

## Multi-Day ASAP Optimization

Schedule jobs as early as possible across multiple days:

```json theme={null}
{
  "jobs": [
    {
      "name": "flexible-service",
      "dayIndex": 0,  // Available immediately
      "windows": [
        {"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"},
        {"from": "2024-03-16T08:00:00Z", "to": "2024-03-16T17:00:00Z"},
        {"from": "2024-03-17T08:00:00Z", "to": "2024-03-17T17:00:00Z"}
      ]
    },
    {
      "name": "scheduled-later",
      "dayIndex": 2,  // Not available until day 3
      "windows": [
        {"from": "2024-03-17T08:00:00Z", "to": "2024-03-17T17:00:00Z"},
        {"from": "2024-03-18T08:00:00Z", "to": "2024-03-18T17:00:00Z"}
      ]
    }
  ],
  "options": {
    "weights": {
      "asapWeight": 100,
      "dayIndexWeight": 50
    }
  }
}
```

### DayIndex Logic

<Info>
  **dayIndex** represents the earliest day a job can be scheduled:

  * `dayIndex: 0` → Can be scheduled on day 1
  * `dayIndex: 1` → Cannot be scheduled before day 2
  * `dayIndex: 2` → Cannot be scheduled before day 3

  Combined with `asapWeight`, this creates pressure to schedule jobs on their earliest available day.
</Info>

## Complex Time Scenario

Combining all advanced time features:

```json theme={null}
{
  "options": {
    "snapUnit": 900,  // 15-minute slots
    "weights": {
      "asapWeight": 80,
      "overtimeWeight": 100,
      "waitTimeWeight": 20
    }
  },
  "jobs": [
    {
      "name": "morning-appointment",
      "duration": 2700,  // 45 minutes
      "padding": 300,    // 5 min buffer
      "dayIndex": 0,
      "windows": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T12:00:00Z"
      }]
    },
    {
      "name": "afternoon-installation",
      "duration": 7200,  // 2 hours
      "padding": 600,    // 10 min setup/cleanup
      "dayIndex": 0,
      "urgency": 90,
      "windows": [{
        "from": "2024-03-15T13:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "resources": [{
    "name": "technician",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T17:00:00Z",
      "overtimeEnd": "2024-03-15T19:00:00Z"
    }]
  }]
}
```

### Expected Behavior

1. **Morning appointment**:
   * Natural arrival: 8:12
   * Snapped to: 8:15
   * Service: 8:20-9:05 (with padding)
   * Depart: 9:10

2. **Afternoon installation**:
   * Natural arrival: 13:08
   * Snapped to: 13:15
   * Service: 13:25-15:25 (with padding)
   * Depart: 15:35

## Performance Optimization

### Time Feature Impact

<Accordion title="Performance Considerations">
  **Low Impact**:

  * snapUnit with reasonable intervals (≥300s)
  * Simple padding values
  * Basic overtime configuration

  **Medium Impact**:

  * Small snapUnit values (`< 300s`)
  * Multiple time-dependent matrices
  * Complex overtime structures

  **High Impact**:

  * Very small snapUnit (60s)
  * Many time period transitions
  * Complex padding patterns
</Accordion>

### Best Practices

<Steps>
  <Step title="Choose Appropriate Precision">
    * Use 15-minute slots unless finer control needed
    * Avoid snapUnit \< 300 for large problems
  </Step>

  <Step title="Balance Features">
    * Don't combine all features unless necessary
    * Test impact of each feature separately
  </Step>

  <Step title="Monitor Wait Time">
    * Track wait time statistics
    * Adjust snapUnit if excessive waiting
  </Step>

  <Step title="Validate Time Logic">
    * Ensure padding + duration fits in windows
    * Check overtime doesn't conflict with shifts
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Excessive Wait Times">
    **Symptom**: Drivers waiting long periods

    **Causes**:

    * snapUnit too large
    * Poor alignment with job windows
    * Suboptimal route sequencing

    **Solutions**:

    * Reduce snapUnit value
    * Adjust time windows
    * Increase waitTimeWeight
  </Accordion>

  <Accordion title="Jobs Not Fitting in Windows">
    **Symptom**: Jobs unassigned due to time

    **Causes**:

    * Padding makes job too long
    * snapUnit pushes beyond window
    * Travel time underestimated

    **Solutions**:

    * Reduce padding
    * Widen time windows
    * Verify travel time accuracy
  </Accordion>

  <Accordion title="Unexpected Overtime">
    **Symptom**: Routes extending past regular hours

    **Causes**:

    * snapUnit delaying arrivals
    * Padding accumulating
    * Poor ASAP prioritization

    **Solutions**:

    * Increase overtimeWeight
    * Review time feature combinations
    * Adjust shift definitions
  </Accordion>
</AccordionGroup>

## Related Features

<CardGroup cols={2}>
  <Card title="Time Windows" icon="clock" href="/guides/vrp/features/time-scheduling-advanced">
    Core time scheduling features
  </Card>

  <Card title="Cost Optimization" icon="dollar-sign" href="/guides/vrp/features/cost-optimization">
    Overtime cost configuration
  </Card>

  <Card title="Break Management" icon="coffee" href="/guides/vrp/features/break-management">
    How breaks interact with timing
  </Card>

  <Card title="Multi-Day Planning" icon="calendar" href="/guides/vrp/features/time-scheduling-advanced">
    Extended planning horizons
  </Card>
</CardGroup>