You are viewing Nextmv legacy docs. ⚡️ Go to latest docs ⚡️

Features

Penalties

You will learn the basics of using penalties on cloud.

Penalties are mechanisms for discouraging undesirable behavior in returned solutions. For example, your business operations may place value on vehicles not arriving late to stops. Or, perhaps, it’s unacceptable to not service a stop by unassigning it from a route. Penalty application is usually dependent upon other input settings (e.g., target_times and hard_windows) and can be represented with different value types (e.g., a multiplier vs. arbitrary time in seconds). Penalties contribute to the overall value function of a solution.

Earliness penalties and lateness penalties

Earliness and lateness penalties are costs applied to the value function when vehicles arrive at stops too early or too late. These penalties are useful for discouraging behavior such as hot food being delivered too late or ride sharing vehicles arriving too early for an airport pickup.

Earliness and lateness penalties are multipliers applied to every second a vehicle services a stop before or after a defined target time. Target times must be defined in the input schema in order for these penalties to be applied. For example, if a vehicle services a stop 60 seconds after a target time and the lateness penalty is set to 10, 600 seconds are added to the value function.

These penalties are defined at the stops level of the input schema, either in the defaults section or on a stop-by-stop basis.

{
  "defaults": {
    "vehicles": {
      "shift_start": "2021-10-17T09:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    { "id": "vehicle-1" }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": { "lon": -96.8445, "lat": 32.9787 },
      // No penalty for lateness
      "lateness_penalty": 0,
      "target_time": "2021-10-17T09:05:00-06:00"
    },
    {
      "id": "location-2",
      "position": { "lon": -96.8694, "lat": 32.9965 },
      // Low penalty for lateness
      "lateness_penalty": 100,
      "target_time": "2021-10-17T09:05:00-06:00"
    },
    {
      "id": "location-3",
      "position": { "lon": -96.8152, "lat": 33.0203 },
      // High penalty for lateness
      "lateness_penalty": 1000,
      "target_time": "2021-10-17T09:05:00-06:00"
    }
  ]
}
Copy

Unassigned penalties

The unassigned penalty represents the severity of not assigning a stop to a vehicle. These penalties are useful for discouraging stops being dropped from routes. Nextmv solvers will attempt to assign every stop to a vehicle. In some cases, however, it may not be possible to assign a stop (e.g., if no vehicles in a fleet have sufficient capacity or compatibility for the stop). To achieve the desired behavior of discouraging but allowing for unassignment if necessary, a sufficiently large penalty value should be used, where 'sufficiently large' can be defined as larger than the maximum cost of servicing the particular stop.

The unassigned penalty is represented by an arbitrary amount of time measured in seconds. A stop is unassigned if adding it to a vehicle’s route violates a defined constraint (e.g., capacity, hard_windows, shift_start, shift_end, and compatibility_attributes).

This penalty is defined at the stops level of the input schema, either in the defaults section or on a stop-by-stop basis.

If no penalty value is defined in the input file, the unassigned penalty will be autoconfigured. Any unassigned penalties added to the input file (in the defaults section or per stop) override the autoconfigured value.

{
  "defaults": {
    "vehicles": {
      "shift_start": "2021-08-24T09:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    { 
      "id": "vehicle-1",
      // Only two stops allowed (we prefer to service the ones with higher
      // penalty)
      "max_stops": 2
    }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": { "lon": -96.7103, "lat": 33.2058 },
      // High penalty -> high priority stop
      "unassigned_penalty": 2000000000
    },
    {
      "id": "location-2",
      "position": { "lon": -96.7264, "lat": 33.2101 },
      // Lower penalty -> low priority stop
      "unassigned_penalty": 1000000000
    },
    {
      "id": "location-3",
      "position": { "lon": -96.7161, "lat": 33.2042 },
      // High penalty -> high priority stop
      "unassigned_penalty": 2000000000
    }
  ]
}
Copy

Page last updated

Go to on-page nav menu