NDD DimensionDimension

Overview

Dimensions represent the measurable quantities in a model: time, distance, capacity, mass, weight, volume and so on. In the NDD model, the dimension configuration also defines the planning horizon through the weekLength and periodLength fields, which determine how many days are being planned across and how weeks are structured within that period.

Applicable models

• NDD ndd-cmibu6krtqja

DimensionConfiguration

The DimensionConfiguration provides a way of specifying the collection of dimensions desired for a particular model, the units for distance and time, and the shape of the planning period.

Schema definition

message DimensionConfiguration {
  optional InternalDimension timeConfig = 1;
  optional InternalDimension distanceConfig = 2;
  repeated CapacityDimension capacityDimensions = 3;
  required int32 weekLength = 4;
  required int32 periodLength = 5;
}

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, or volume. Capacitated dimensions are considered independent of one another. Can be omitted if there are no capacity constraints.

weekLength

The length of the working week. This is typically 5, 6 or 7. The week length must be a factor of the periodLength.

periodLength

The total number of days over which the model is being planned. Must be a multiple of the weekLength. Typical examples are a week length of 5 with a period length of 5 (weekly cycle), 10 (bi-weekly), or 20 (monthly). A week length of 6 would correspond to period lengths of 6, 12, or 24.

Examples

A monthly planning cycle (4 weeks) for a Monday-to-Friday operation, measuring time in minutes and distance in kilometres with a single capacity dimension:

timeConfig {
  id: "time"
  measurementUnit: MINUTES
  slackMax: 86400
  tardyMax: 0
}
distanceConfig {
  id: "distance"
  measurementUnit: KILOMETRES
  slackMax: 0
  tardyMax: 0
}
capacityDimensions {
  id: "weight"
  units: "kg"
  slackMax: 0
  tardyMax: 0
}
weekLength: 5
periodLength: 20

Notes

• The periodLength must be a multiple of the weekLength, otherwise an error will be returned.
• The weekLength and periodLength should be consistent with the profiles defined on each job.

InternalDimension

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

Schema definition

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

Fields

id

A unique identifier for this dimension.

measurementUnit

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

slackMax

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 waiting time that may be incurred in order to meet a window on that dimension. Earlyness in the context of a time dimension results in waiting time. In the context of distance or capacity, this is typically set to zero. The slack amount is added to the dimension when required and may be costed at a higher rate to discourage its use.

tardyMax

The maximum amount of dimensional quantity by which a task may exceed a window constraint. In the context of time, this represents how late a delivery may be (a “soft” window). In the context of capacity, this represents an overloading ability. The tardy quantity adjusts feasibility checks to permit exceeding a window on a dimension but is costed at an additional rate.

Examples

A typical time dimension configuration permitting earlyness but not lateness:

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

A distance dimension with no slack or tardiness:

id: "distance"
measurementUnit: KILOMETRES
slackMax: 0
tardyMax: 0

Notes

• The slackMax and tardyMax values must be positive (or zero).

InternalDimension.eMeasurementUnit

Defines the measurement unit used for an internal dimension.

Schema definition

enum eMeasurementUnit {
  SECONDS = 0;     // timeConfig
  MINUTES = 1;     // timeConfig
  HOURS = 2;       // timeConfig
  DAYS = 3;        // timeConfig
  KILOMETRES = 4;  // distanceConfig
  MILES = 5;       // distanceConfig
}

Notes

• A time measurement unit may only be used with a time configuration. Similarly for distance measurement units. A mismatch will result in an error.

CapacityDimension

The CapacityDimension defines a dimension which is capacitated (i.e. has 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 for this dimension.

units

A field describing the units (e.g. “kg”, “litres”). This field is not used computationally but makes models more human-readable.

slackMax

The maximum amount of dimensional quantity that may be added. For capacity dimensions this is typically zero, as quantity may not be added to the dimension to make a route feasible.

tardyMax

The maximum amount by which a vehicle’s capacity may be exceeded. This represents an overloading ability, costed at an additional rate to discourage overloading where it can be avoided.

Examples

id: "weight"
units: "kg"
slackMax: 0
tardyMax: 0

Notes

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