IVR LocationLocation
Overview
Locations are used to model where things happen. This is useful when there are multiple tasks which occur at the same location and there are concepts which need to be modelled at a location level. Typical examples of this are modelling the depot as a location, and having times for entering the depot (regardless of how many tasks are picked up or dropped off). Another example is to create location times which incentivises customer orders which are at the same location to be grouped together.
Applicable models
- IVR7
ivr7-kt461v8eoaif
- IVR8
ivr8-yni1c9k2swof
Location
The Location
defines a unique location which is visited by vehicles.
Schema definition
message Location {
required string id = 1;
optional Geocode geocode = 2;
repeated Attribute attributes = 3;
}
Fields
- id
- The unique identifier for this location. If duplicate locations are provide in a model payload, the request is rejected.
- geocode
- The position of the location in either longitude/latitude (for earth/network routing) or x-y space (planar routing)
- attributes
- An optional list of attributes which should be applied to this location. The location attributes may specify vehicle-specific attributes, or attributes which are applicable on arrival at or departure from a particular location.
Examples
This example illustrates a minimal location definition:
id: "The Oval Bar Dublin"
geocode {
longitude: -6.26029587
latitude: 53.348465
}
A more complete example of a location definition might be:
id: "Guinness Storehouse"
geocode {
longitude: -6.28681087
latitude: 53.3416138
}
attributes {
dimensionId: "time"
quantity: 30
arrivalWindows {
start: 480
end: 720
}
}
attributes {
dimensionId: "time"
vehicleId: "vehicle_1"
quantity: 45
arrivalWindows {
start: 480
end: 720
}
}
vehicleArrivalAttribute
indicates that vehicle_1
will require 45 minutes to enter the location, but with the same window. If the quantity on the vehicleArrivalAttribute
had been omitted, the quantity of 30 minutes would have been used from the arrivalAttributes. The intersection of arrival windows on the vehicleArrivalAttribute
for a specified dimension will be applicable to vehicle_1
. In this instance, the windows correspond and the intersection of arrival and vehiclearrival windows is simply the arrival window, however, this may have restricted the arrival window further. If an infeasible window is produced, an error is reported by the API.
Notes
- It’s typical to either use the arrival and departure attributes, or use the vehicleArrival and vehicleDeparture attributes. This recommendation is made merely to ensure the expected results are achieved.
- In the hierarchy of attributes and vehicle attributes, the attributes apply generally with quantities being overridden by the vehicleAttributes and the intersection of windows being taken when specified by the vehicleAttributes.
- If a quantity is specified on both an arrival and departure attribute, both values are used, the first before the task and the second before moving to a new location.
- If the location is unchanged between tasks, location attribute quantities and windows are not applied. If attributes should be applied between successive tasks, attributes can be applied at the task level.
Location Attribute
The location attribute defines a quantity and/or multiple dimension windows for a particular location. These attributes are either applied on arrival, departure or both arrival and departure at the associated location. Location attributes may also be specific to particular vehicles specified by the vehicle identifier.
Schema Definition
message Attribute {
required string dimensionId = 1;
optional string vehicleId = 2;
optional float quantity = 3;
repeated Window arrivalWindows = 4;
repeated Window departureWindows = 5;
}
Fields
- dimensionId
- The dimension to which this attribute should be applied.
- vehicleId
- The vehicle to which this attribute should be applied. When omitted, this attribute will be applied to all vehicles specified in the model
- quantity
- The amount to be added to the associated dimension when changing location (default of zero).
- arrivalWindows
- An optional list of window objects which are applicable for this location (and perhaps vehicle) and dimension combination. Windows specified in this list are applicable to vehicles when arriving at a particular location.
- departureWindows
- An optional list of window objects which are applicable for this location (and perhaps vehicle) and dimension combination. Windows specified in this list are applicable to vehicles when departing from a particular location.
Examples
An example of a location which incurs a fixed time of 30 minutes each time the location is visited from a different location:
dimensionId: "time"
quantity: 30
An example of a customer time window which can only be serviced from 08:00 to 12:00 or 14:00 to 17:00 with a 15 minute duration for visiting the customer to perform orders (the time dimension in this context is measured in minutes):
dimensionId: "time"
quantity: 15
arrivalWindows {
start: 480
end: 720
}
arrivalWindows {
start: 840
end: 1020
}
An example of an attribute that would be applicable to a location where a capacity window is applicable (capacity is being measured in kilograms):
dimensionId: "capacity"
vehicleId: "flatdeck-1"
arrivalWindows {
start: 1000
end: 8000
}
departureWindows {
start: 2000
end: 8000
}
flatdeck-1
have a minimum of 1 tonne on the vehicle before entering the site, and a maximum of 8 tonnes. In addition, the vehicle load on departure should be between 2 and 8 tonnes. This is commonplace where a particular vehicle mass may be required to navigate road conditions. This example illustrates modelling the arrival and departure separately for a particular vehicle.
Notes
- Attributes can be applicable to multiple contexts, such as on arrival at a particular location, departure, or both.
- Attributes can also be applied to any dimension. Examples of this include capacity constraints for a location - which is indicative of a road restriction.
- Attributes which do not specify a vehicle are then applied to all vehicles. We recommend modelling either each vehicle-specific attribute or a single time independently of vehicles to avoid the case where a mixture of these approaches is employed.