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

# Period Rules

> Define operational constraints for resource work periods

## Overview

Period rules enable you to set operational constraints that apply across all shifts for a resource. These rules ensure compliance with regulations, safety requirements, and operational policies by limiting or requiring specific work patterns.

<Info>
  Period rules are particularly useful for implementing driver regulations, union agreements, and safety policies that span multiple shifts.
</Info>

## Available Rule Types

### Drive Time Rules

Control the amount of time resources spend driving:

<ParamField body="maxDriveTime" type="integer">
  Maximum driving time in seconds allowed during the period
</ParamField>

<ParamField body="minDriveTime" type="integer">
  Minimum driving time in seconds required during the period
</ParamField>

### Work Time Rules

Manage total working hours:

<ParamField body="maxWorkTime" type="integer">
  Maximum total work time in seconds (includes driving and service time)
</ParamField>

<ParamField body="minWorkTime" type="integer">
  Minimum total work time in seconds required
</ParamField>

<Warning>
  Use minimum drive time rules cautiously. They may force the solver to create longer routes than necessary to meet the minimum requirement.
</Warning>

## Implementation Example

This example demonstrates how a maximum drive time rule affects route planning:

<Tabs>
  <Tab title="Request">
    ```json theme={null}
    {
      "resources": [
        {
          "name": "R-1",
          "start": {
            "latitude": 50.923554431590595,
            "longitude": 4.890691212789399
          },
          "shifts": [
            {
              "from": "2023-01-13T08:00:00",
              "to": "2023-01-13T22:00:00"
            }
          ],
          "rules": [
            {
              "maxDriveTime": 10000  // ~2.78 hours max driving
            }
          ]
        }
      ],
      "jobs": [
        {
          "name": "JOB-1",
          "location": {
            "latitude": 50.54963315022148,
            "longitude": 4.848855475505483
          },
          "duration": 3600
        },
        {
          "name": "JOB-2",
          "location": {
            "latitude": 50.65910297910443600,
            "longitude": 4.007987934186738
          },
          "duration": 3600
        },
        // Jobs 3-10 with various locations...
      ],
      "options": {
        "partialPlanning": true
      }
    }
    ```
  </Tab>

  <Tab title="Solution">
    ```json theme={null}
    {
      "score": {
        "hardScore": 0,
        "mediumScore": -25200,
        "softScore": -6924,
        "feasible": true
      },
      "trips": [
        {
          "visits": [
            {
              "arrival": "2023-01-13T08:44:54",
              "job": "JOB-6",
              "location": "50.89633806889935;4.45161298168845"
            },
            {
              "arrival": "2023-01-13T10:21:25",
              "job": "JOB-5",
              "location": "50.94837893617721;4.001604640663746"
            },
            {
              "arrival": "2023-01-13T11:55:17",
              "job": "JOB-10",
              "location": "50.78868282668716;4.167956383823208"
            }
          ],
          "resource": "R-1",
          "date": "2023-01-13",
          "departureTime": "2023-01-13T08:00:00",
          "travelTime": 6917,     // Under 10000 second limit
          "workTime": 17717,
          "serviceTime": 10800
        }
      ],
      "unserved": [
        "JOB-1", "JOB-2", "JOB-3", "JOB-4", 
        "JOB-7", "JOB-8", "JOB-9"
      ],
      "status": "SOLVED"
    }
    ```
  </Tab>

  <Tab title="Analysis">
    The solver assigned only 3 jobs to respect the 10,000-second (2.78 hour) maximum drive time rule:

    * **Total drive time**: 6,917 seconds (well under limit)
    * **Jobs completed**: 3 out of 10
    * **Unserved jobs**: 7 (would exceed drive time if included)

    The constraint forced a trade-off between service coverage and compliance with driving regulations.
  </Tab>
</Tabs>

## Common Rule Patterns

### Standard Driver Regulations

European driving regulations:

```json theme={null}
{
  "rules": [
    {
      "maxDriveTime": 32400,    // 9 hours daily driving
      "maxWorkTime": 50400       // 14 hours total work
    }
  ]
}
```

### Minimum Utilization Requirements

Ensure resources meet minimum productivity:

```json theme={null}
{
  "rules": [
    {
      "minWorkTime": 21600,      // Minimum 6 hours work
      "maxWorkTime": 36000       // Maximum 10 hours work
    }
  ]
}
```

### Combined Rules

Multiple rules work together:

```json theme={null}
{
  "rules": [
    {
      "maxDriveTime": 25200,     // Max 7 hours driving
      "minDriveTime": 7200,      // Min 2 hours driving
      "maxWorkTime": 36000,      // Max 10 hours total
      "minWorkTime": 14400       // Min 4 hours total
    }
  ]
}
```

## Rule Scope and Application

### Period Definition

Rules apply to the entire planning period, not individual shifts:

```json theme={null}
{
  "shifts": [
    {"from": "2023-01-13T08:00:00", "to": "2023-01-13T12:00:00"},
    {"from": "2023-01-13T13:00:00", "to": "2023-01-13T17:00:00"}
  ],
  "rules": [
    {
      "maxDriveTime": 18000  // Applies across BOTH shifts
    }
  ]
}
```

### Multi-Day Planning

For multi-day scenarios, rules apply per day:

```json theme={null}
{
  "shifts": [
    {"from": "2023-01-13T08:00:00", "to": "2023-01-13T17:00:00"},
    {"from": "2023-01-14T08:00:00", "to": "2023-01-14T17:00:00"}
  ],
  "rules": [
    {
      "maxDriveTime": 25200  // Resets each day
    }
  ]
}
```

## Best Practices

<Steps>
  <Step title="Start with regulatory requirements">
    Implement legally required limits first (e.g., DOT hours of service, EU driving time regulations).
  </Step>

  <Step title="Add operational constraints">
    Layer in company policies and union agreements after regulatory compliance.
  </Step>

  <Step title="Test with partial planning">
    Enable `partialPlanning: true` when rules might prevent full job assignment.
  </Step>

  <Step title="Monitor rule impact">
    Use the explanation API to understand how rules affect job assignments.
  </Step>

  <Step title="Balance min/max rules">
    Avoid overly restrictive combinations that create infeasible scenarios.
  </Step>
</Steps>

## Troubleshooting

### Too Many Unassigned Jobs

If rules cause excessive unassigned jobs:

<Accordion title="Solution strategies">
  1. **Review rule strictness**: Are limits realistic for your operation?
  2. **Add more resources**: Distribute work across more vehicles
  3. **Adjust job locations**: Cluster jobs to reduce travel
  4. **Extend shift times**: Provide more working hours within rules
  5. **Use soft constraints**: Consider making some rules soft with penalties
</Accordion>

### Inefficient Routes

When minimum rules force unnecessary travel:

<Tip>
  Replace minimum drive time rules with minimum job count or revenue targets to achieve utilization goals without forcing inefficient routing.
</Tip>

## Advanced Scenarios

### Time-Based Rule Variations

While not directly supported, you can simulate time-based variations using multiple resources:

```json theme={null}
{
  "resources": [
    {
      "name": "Driver-Morning",
      "shifts": [{"from": "06:00", "to": "14:00"}],
      "rules": [{"maxDriveTime": 25200}]  // 7 hours
    },
    {
      "name": "Driver-Evening", 
      "shifts": [{"from": "14:00", "to": "22:00"}],
      "rules": [{"maxDriveTime": 21600}]  // 6 hours (different limit)
    }
  ]
}
```

### Combining with Other Constraints

Rules work alongside other VRP features:

```json theme={null}
{
  "resources": [{
    "name": "R-1",
    "rules": [{"maxDriveTime": 28800}],
    "breaks": [
      {
        "type": "DRIVE",
        "duration": 2700,        // 45-min break
        "afterDriveTime": 16200  // After 4.5 hours driving
      }
    ],
    "maxDistance": 300000        // 300km daily limit
  }]
}
```

## Performance Impact

<Note>
  Period rules are evaluated continuously during optimization. Complex rule combinations may increase solve time, especially with tight constraints that limit feasible solutions.
</Note>

Consider:

* Fewer, simpler rules perform better than many complex rules
* Hard rules that severely limit options increase computation time
* Partial planning helps when rules make full assignment impossible

## Related Features

<CardGroup cols={2}>
  <Card title="Breaks" icon="pause" href="/guides/vrp/features/break-management">
    Configure mandatory rest periods within shifts
  </Card>

  <Card title="Shift Management" icon="calendar-days" href="/guides/vrp/features/resource-management">
    Define when resources are available to work
  </Card>

  <Card title="Resource Constraints" icon="shield" href="/guides/vrp/features/resource-management">
    Set capacity, skills, and regional limitations
  </Card>

  <Card title="Weights" icon="balance-scale" href="/guides/vrp/features/cost-optimization">
    Fine-tune how rules impact optimization
  </Card>
</CardGroup>