IVR Vehicle ClassVehicle Class

Overview

The vehicle class describes the way in which a vehicle behaves with respect to the tasks, locations associated with those tasks, and the transits, or movements, between locations. Vehicle classes can describe general behaviour for a group of vehicles, or each vehicle may belong to its own class. In addition, a vehicle class may specify the transit rules or compartment set which should be inherited by vehicles assigned to this class.

Applicable models

• IVR7 ivr7-kt461v8eoaif
• IVR8 ivr8-yni1c9k2swof

Vehicle Class

Schema definition

message VehicleClass {
  required string id = 1;               // unique identifier
  repeated Attribute attributes = 2;    // describe the movement w.r.t the dimensions
  repeated string transitRuleIds = 3;   // optional set of rules
  optional string compartmentSetId = 4; // IVR 8 only
}

Fields

id

The unique identifier for the vehicle class. Should be unique across all vehicle classes provided in a model. If duplicates are found, the payload is rejected as invalid.

attributes

Attributes that describe this instance of a vehicle class. Attributes are used to describe the way in which this vehicle class interacts with the dimensions with respect to transits (movements between locations), tasks and locations. Multiple attributes may be provided for a given dimension where the order in which attributes are provided is the order in which attributes are applied to create a particular transit matrix. See the advanced IVR examples on github for more details.

transitRuleIds

An optional list of Transit rules that are applicable to vehicles that belong to this class. All vehicles within this class will inherit this transit rule, unless a transit rule has been set at a vehicle level.

compartmentSetId

An optional compartment set associated with this vehicle class. The compartment set describes the collection of compartments that define the packing area of the vehicle. All vehicles within this class will inherit this compartment set, unless a compartment set has been set at a vehicle level.

Examples

This example illustrates a simple configuration for a vehicle against the road network. This configuration will use a typical car profile for the road network and will use road network times and distances for the movements between locations. The taskCoef and locationCoef of 1 indicate that the vehicle class should use the task and location quantities specified in the model applying a coefficient of 1.0 to all values.

id: "vc1"
attributes {
  dimensionId: "time"
  transitGeneratorId: "roadnetwork_time"
  transitCoef: 1
  taskCoef: 1
  locationCoef: 1
}
attributes {
  dimensionId: "distance"
  transitGeneratorId: "roadnetwork_distance"
  transitCoef: 1
}
transitRuleIds: "lunch-break rule"
compartmentSetId: "double-stack layout"

Vehicle Class Attribute

Schema definition

message Attribute {
  required string dimensionId = 1;
  optional string transitGeneratorId = 2;      // links to a transitGenerator object, not to be confused with transitRules
  optional float transitCoef = 3;
  optional float taskCoef = 4;
  optional float locationCoef = 5;
}

Fields

dimensionId

The dimension to which this attribute should be applied.

transitGeneratorId

The transitGeneratorId value should be specified if this vehicle class is required to use transit values when moving between locations for the specified dimension. In instances such as capacity dimensions, this field may be omitted. There are two reserved identifiers for this field, namely roadnetwork_time and roadnetwork_distance, which connect the specified dimension to either the road network time or distance matrix generators. A custom set of transits may be provided using a combination of a transit generator and the transit set object. This may be done by including all required transits for a dimension in the current model payload, or uploading the transits for a dimension separately and referencing the data-payload request ID returned. This is considered advanced usage of the API. The reason for provisioning the transit matrix separately to the model is to minimise the bandwidth required for running models which use a common set of locations. When referencing a custom transit set the scheduler will extract the subset of transit values corresponding to the locations in the current model allowing for a single “master” matrix per dimension to be uploaded. A final usage of the transit set object is to override a subset of transit values. This is common when only a subset of restrictions apply in a network, such as turn restrictions (or open-routing). In this use case, a pre-configured network may be referenced with an additional attribute referencing the attributes to be applied over the pre-configured matrix. The order of the attributes in this instance is important as it implied the order in which data should be loaded into the solver and hence the resulting set of data. See the advanced usage examples on github in R and Python for more info.

transitCoef

The coefficient (or multiplier) that should be applied to the values obtained from the transit set for this dimension. A value of 1.0 means that the values should be used as presented. A value greater than 1.0 will increase the value of the transit proportionately to the coefficient. I.e. a value of 1.5 will increase all transit values by 50%. Similarly, a value less than 1.0 will decrease the value of a transit for this vehicle class. Valid coefficient values should be greater than or equal to zero.

taskCoef

The coefficient (or multiplier) that should be applied to the task quantities specified for this dimension. A value of 1.0 will use the task quantities as provided for the dimension in the task attributes. A value greater than 1.0 will increase the quantity and a value less than 1.0 will decrease the quantity for this vehicle class. A value of zero will nullify the quantities provided on the tasks for the specified dimension. Valid coefficient values should be greater than or equal to zero.

locationCoef

The coefficient (or multiplier) that should be applied to the location quantities specified for this dimension. A value of 1.0 will use the location quantities provided for the dimension as per the location attributes. A coefficient greater than 1.0 will increase the location quantities proportionately, and a value less than 1.0 will similarly decrease the location-dimension quantity. Valid coefficient values should be greater than or equal to zero.

Examples

An example of an attribute which specifies that the internal road network time matrix should be generated for this particular vehicle class, however, the times that are served from the road network should be increased by 25%. This is usual when modelling larger vehicles which typically model significantly slower than normal vehicles in the road network.

attributes {
  dimensionId: "time"
  transitGeneratorId: "roadnetwork_time"
  transitCoef: 1.25
  taskCoef: 1
  locationCoef: 1
}

The following configuration illustrates how to reference both a custom distance and time matrix which are defined in the model transit set with the id’s my-time-matrix and my-distance-matrix.

attributes {
  dimensionId: "time"
  transitGeneratorId: "my-time-matrix"
  transitCoef: 1
  taskCoef: 1
  locationCoef: 1
}
attributes {
  dimensionId: "distance"
  transitGeneratorId: "my-distance-matrix"
  transitCoef: 1
}

The following configuration illustrates how to reference custom time and distance matrices which have been uploaded separately using the transit set and the upload endpoint. The GUIDs in these attributes were returned by an upload request and, as such, are referenceable by all models which use the same API key. If the transit set corresponding to the provided GUID cannot be retrieved, the payload is rejected by the solver.

attributes {
  dimensionId: "time"
  transitGeneratorId: "b2842bd0-8b28-453f-9f45-8bc73878e2a9"
  transitCoef: 1
  taskCoef: 1
  locationCoef: 1
}
attributes {
  dimensionId: "distance"
  transitGeneratorId: "2fc79c09-d63a-4805-b668-e8be8eb0904f"
  transitCoef: 1
}

This configuration illustrates how to combine two transit requests on the same dimension one after the other. The first is a reference to the internal road network time transits, which are generated on the fly for the model. The second attribute is a reference to a collection of transits which have been previously uploaded. This sequence of attributes will first pull through a time matrix of transits corresponding to the road network travel times between locations, and then apply the custom transits over this network where specified. The typical use case for this is to use the majority of the road network times but provide specific travel times between certain locations in the model which have other time dynamics not encapsulated by the road network.

attributes {
  dimensionId: "time"
  transitGeneratorId: "roadnetwork_time"
  transitCoef: 1
  taskCoef: 1
  locationCoef: 1
}
attributes {
  dimensionId: "time"
  transitGeneratorId: "b2842bd0-8b28-453f-9f45-8bc73878e2a9"
  transitCoef: 1
  taskCoef: 1
  locationCoef: 1
}

Notes

Two reserved identifiers apply in this section of the model to the transitGeneratorId field.

roadnetwork_time

which provides access to the internal road network to retrieve the travel times between locations.

roadnetwork_distance

which provides access to the internal road network to retrieve the distances between locations.

• It is anticipated that additional reserved terms will be introduced in the future to accommodate different resource type movements in the road network, or alternate types of networks. Drop us a mail if you have a specific requirement in this regard.