IVR DimensionDimension

Overview

Distance, time, capacity, mass, weight, volume are all examples of measurement dimensions. Dimensions are things we measure when creating a model which either participate in the objective function (distance) or represent constraints (time or capacity).

Time and Distance are actually very similar as they are both a function of both the origin and destination. A capacity dimension (such as in the CVRP) is a function of a single node. So we can add an attribute to each task or location which corresponds to a quantity which should impact this dimension. Specifying complete distance-time matrices requires not only a lot of data, but also adds unnecessary complexity to the model. This is why we create the distance/time matrices for you, you just need to tell us how you want to name things and we’re all set.

Applicable models

• IVR7 ivr7-kt461v8eoaif
• IVR8 ivr8-yni1c9k2swof

DimensionConfiguration

The DimensionConfiguration provides a way of specifying the collection of dimensions desired for a particular model as well as the units you’re measuring in for distance and time. If you don’t need distance or time, you’re welcome to omit them in the data provided, but, if you’re using our API in this way, please give us a shout because we’d love to understand what this use case looks like.

Schema definition

message DimensionConfiguration {
  optional InternalDimension timeConfig = 1;
  optional InternalDimension distanceConfig = 2;
  repeated CapacityDimension capacityDimensions = 3;
}

Fields

timeConfig

Optional configuration for a time dimension (commonly configured)

distanceConfig

Optional configuration for a distance dimension (commonly configured)

capacityDimensions

A list of additional capacitated dimensions, such as weight, mass, volume. Capacitated dimensions are considered independent of one another in this representation. Can be omitted (left empty) if there are no capacity constraints (such as a TSP).

Examples

timeConfig {
  id: "time"
  measurementUnit: MINUTES
  slackMax: 86400
  tardyMax: 0
}
distanceConfig {
  id: "distance"
  measurementUnit: KILOMETRES
  slackMax: 0
  tardyMax: 0
}
capacityDimensions {
  id: "capacity"
  units: "kg"
  slackMax: 0
  tardyMax: 0
}

This sample would be used to configure the dimensions for a Capacitated Vehicle Routing Problem with Time Windows where the maximum earlyness for a particular time window is 24 hours (60 * 60 * 24).

InternalDimension

The InternalDimension is provided to allow us to create a distance/time matrix for you and configure your model against the road network.

Schema definition

message InternalDimension {
  enum eMeasurementUnit {
    SECONDS = 0;     // timeConfig
    MINUTES = 1;     // timeConfig
    HOURS = 2;       // timeConfig
    DAYS = 3;        // timeConfig
    KILOMETRES = 4;  // distanceConfig
    MILES = 5;       // distanceConfig
  }
  required string id = 1;                         // the name of the dimension (unique)
  required eMeasurementUnit measurementUnit = 2;  // the measurement unit (used for conversions)
  optional float slackMax = 3 [default = 0];      // the maximum slack on this dimension (a default for all tasks)
  optional float tardyMax = 4 [default = 0];      // the maximum tardiness on this dimension (a default for all tasks)
}

Fields

id

A unqiue idenfitier for this dimension.

measurementUnit

The measurement unit to be used in the model. Generated quantities for this dimension will then be in the target units.

slackMax

Slack Max is the maximum amount of the dimensional quantity that may be added while performing a task. In the context of time, this relates to the maximum amount of time that may be added to the existing cumulative value in order to meet a window or constraint on that dimension. Earlyness in the context of a time dimension results in waiting time. Often waiting time is unavoidable when there are many delivery windows. In the context of distance or capacity, the maximum slack permitted is set to zero as quantity may not be added to the dimension to make a route feasible. The slack amount is added to dimension when required and may also be costed at a higher rate (in order to discourage the use of slack).

tardyMax

Tardy Max is the maximum amount of dimensional quantity which may be deduced from a task in order to perform the task feasibly. In the context of time, this relates to the maximum amount of time a task may exceed a time window. This is sometimes referred to as a “soft” window, whereby we can be late for the window, but perhaps this is costed as being more expensive (often we would like to achieve the target windows without additional cost). In the context of distance this does not have an analogous interpretation. In the context of capacity, this may be considered an overloading ability, whereby, one may exceed the dimensional constraint on a vehicles capacity (up to the maximum tardy) but will be costed at additional amount (perhaps to discourage overloading where it can be avoided). The tardy quantity is not added to the dimension if required, but is used to adjust the feasibillity checks to permit exceeding a window on a dimension (this is to avoid travelling back in time when late for a particular window, or removing quanity from an overloaded vehicle).

Examples

A typical configuration for the time dimension which permits as much earlyness as required in order to perform all tasks.

timeConfig {
  id: "time"
  measurementUnit: MINUTES
  slackMax: 1e+06
  tardyMax: 0
}

A typical configuration for the distance dimension which ensures that distance is not created (maxSlack = 0) and is preserved exactly when moving between nodes.

distanceConfig {
  id: "distance"
  measurementUnit: KILOMETRES
  slackMax: 0
  tardyMax: 0
}

Notes

• The slackMax and tardyMax are both required to be positive values.

CapacityDimension

The CapacityDimension is provided to define a dimension which is capacitated (i.e. a maximum allowable cumulative quantity).

Schema definition

message CapacityDimension {
  required string id = 1;
  required string units = 2;
  optional float slackMax = 3 [default = 0];
  optional float tardyMax = 4 [default = 0];
}

Fields

id

A unique identifier

units

A field describing the units, can be blank. This field is not actually used for anything other than making the models more “human readable”.

slackMax

Slack Max is the maximum amount of the dimensional quantity that may be added while performing a task. In the context of capacity, the maximum slack permitted is set to zero as quantity may not be added to the dimension to make a route feasible. The slack amount is added to dimension when required and may also be costed at a higher rate (in order to discourage the use of slack).

tardyMax

Tardy Max is the maximum amount of dimensional quantity which may be deduced from a task in order to perform the task feasibly. In the context of capacity, this may be considered an overloading ability, whereby, one may exceed the dimensional constraint on a vehicle’s capacity (up to the maximum tardy) but will be costed at additional amount (perhaps to discourage overloading where it can be avoided). The tardy quantity is not added to the dimension if required, but is used to adjust the feasibillity checks to permit exceeding a window on a dimension (without removing quanity placed on an overloaded vehicle).

Examples

A typical configuration for a capacity dimension which ensures that additional slack is not created (maxSlack = 0) and is preserved exactly when moving between nodes.

capacityDimensions {
  id: "capacity"
  units: "kg"
  slackMax: 0
  tardyMax: 0
}

Notes

• Multiple capacity dimensions can be used in conjunction with one another, however, evaluations between the dimensions remain independent.
• Changes in capacity dimensions over a route are driven by the associated dimensional quantities on task attributes