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
}
There are no attributes defined on the location, only the position and the unique identifier.

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
  }
}
In this example, an arrival attribute is provided which is applicable to all vehicles requiring that vehicles may only arrive at the Guinness Storehouse between 08:00 and 12:00. Vehicles entering this location will incur 30 minutes of time. The 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
This is useful for modelling depot visits where a fixed “gate time” is incurred regardless of the number of orders collected or delivered. This attribute would be applicable to all vehicles specified in the model.

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
}
It should be noted that the location time is incurred on a dimension in addition to the task quantities specified in the task attributes. This allows the effects of visiting a location to be modelled separately to the effect of performing a particular task at the location. In this particular example, a task is considered feasible if the vehicle arrives within the specified arrival windows. If the task needs to be completed by either 12:00 or 17:00 then the departureWindow could have been specified, or the end-time of the arrivalWindows adjusted. Lastly the window on the task can be specified in addition to the location window to provide fine-grained control of multiple tasks windows independently of the location.

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
}
This example illustrates an attribute which defines that the vehicle 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.
“Location” was last updated: April 5, 2024