Reference documentation and code samples for the Google Cloud Optimization V1 Client class ShipmentRoute.
A vehicle's route can be decomposed, along the time axis, like this (we assume there are n visits):
| | | | | T[2], | | |
| Transition | Visit #0 | | | V[2], | | |
| #0 | aka | T[1] | V[1] | ... | V[n-1] | T[n] |
| aka T[0] | V[0] | | | V[n-2],| | |
| | | | | T[n-1] | | |
^ ^ ^ ^ ^ ^ ^ ^
vehicle V[0].start V[0].end V[1]. V[1]. V[n]. V[n]. vehicle
start (arrival) (departure) start end start end end
Note that we make a difference between:
"punctual events", such as the vehicle start and end and each visit's start and end (aka arrival and departure). They happen at a given second.
"time intervals", such as the visits themselves, and the transition between visits. Though time intervals can sometimes have zero duration, i.e. start and end at the same second, they often have a positive duration. Invariants:
- If there are n visits, there are n+1 transitions.
- A visit is always surrounded by a transition before it (same index) and a transition after it (index + 1).
- The vehicle start is always followed by transition #0.
- The vehicle end is always preceded by transition #n.
Zooming in, here is what happens during a
Transition
and aVisit
:php ---+-------------------------------------+-----------------------------+--> | TRANSITION[i] | VISIT[i] | | | | | * TRAVEL: the vehicle moves from | PERFORM the visit: | | VISIT[i-1].departure_location to | | | VISIT[i].arrival_location, which | * Spend some time: | | takes a given travel duration | the "visit duration". | | and distance | | | | * Load or unload | | * BREAKS: the driver may have | some quantities from the | | breaks (e.g. lunch break). | vehicle: the "demand". | | | | | * WAIT: the driver/vehicle does | | | nothing. This can happen for | | | many reasons, for example when | | | the vehicle reaches the next | | | event's destination before the | | | start of its time window | | | | | | * DELAY: *right before* the next | | | arrival. E.g. the vehicle and/or | | | driver spends time unloading. | | | | | ---+-------------------------------------+-----------------------------+--> ^ ^ ^ V[i-1].end V[i].start V[i].end
Lastly, here is how the TRAVEL, BREAKS, DELAY and WAIT can be arranged during a transition. - They don't overlap.
- The DELAY is unique and must be a contiguous period of time right before the next visit (or vehicle end). Thus, it suffice to know the delay duration to know its start and end time.
- The BREAKS are contiguous, non-overlapping periods of time. The response specifies the start time and duration of each break.
- TRAVEL and WAIT are "preemptable": they can be interrupted several times
during this transition. Clients can assume that travel happens "as soon as
possible" and that "wait" fills the remaining time.
A (complex) example:
php TRANSITION[i] --++-----+-----------------------------------------------------------++--> || | | | | | | || || T | B | T | | B | | D || || r | r | r | W | r | W | e || || a | e | a | a | e | a | l || || v | a | v | i | a | i | a || || e | k | e | t | k | t | y || || l | | l | | | | || || | | | | | | || --++-----------------------------------------------------------------++-->
Generated from protobuf message google.cloud.optimization.v1.ShipmentRoute
Namespace
Google \ Cloud \ Optimization \ V1Methods
__construct
Constructor.
Parameters | |
---|---|
Name | Description |
data |
array
Optional. Data for populating the Message object. |
↳ vehicle_index |
int
Vehicle performing the route, identified by its index in the source |
↳ vehicle_label |
string
Label of the vehicle performing this route, equal to |
↳ vehicle_start_time |
Google\Protobuf\Timestamp
Time at which the vehicle starts its route. |
↳ vehicle_end_time |
Google\Protobuf\Timestamp
Time at which the vehicle finishes its route. |
↳ visits |
array<Google\Cloud\Optimization\V1\ShipmentRoute\Visit>
Ordered sequence of visits representing a route. visits[i] is the i-th visit in the route. If this field is empty, the vehicle is considered as unused. |
↳ transitions |
array<Google\Cloud\Optimization\V1\ShipmentRoute\Transition>
Ordered list of transitions for the route. |
↳ has_traffic_infeasibilities |
bool
When OptimizeToursRequest.consider_road_traffic, is set to true, this field indicates that inconsistencies in route timings are predicted using traffic-based travel duration estimates. There may be insufficient time to complete traffic-adjusted travel, delays, and breaks between visits, before the first visit, or after the last visit, while still satisfying the visit and vehicle time windows. For example, |
↳ route_polyline |
Google\Cloud\Optimization\V1\ShipmentRoute\EncodedPolyline
The encoded polyline representation of the route. This field is only populated if OptimizeToursRequest.populate_polylines is set to true. |
↳ breaks |
array<Google\Cloud\Optimization\V1\ShipmentRoute\PBBreak>
Breaks scheduled for the vehicle performing this route. The |
↳ metrics |
Google\Cloud\Optimization\V1\AggregatedMetrics
Duration, distance and load metrics for this route. The fields of AggregatedMetrics are summed over all ShipmentRoute.transitions or ShipmentRoute.visits, depending on the context. |
↳ route_costs |
array|Google\Protobuf\Internal\MapField
Cost of the route, broken down by cost-related request fields. The keys are proto paths, relative to the input OptimizeToursRequest, e.g. "model.shipments.pickups.cost", and the values are the total cost generated by the corresponding cost field, aggregated over the whole route. In other words, costs["model.shipments.pickups.cost"] is the sum of all pickup costs over the route. All costs defined in the model are reported in detail here with the exception of costs related to TransitionAttributes that are only reported in an aggregated way as of 2022/01. |
↳ route_total_cost |
float
Total cost of the route. The sum of all costs in the cost map. |
↳ end_loads |
array<Google\Cloud\Optimization\V1\CapacityQuantity>
Deprecated: Use Transition.vehicle_loads instead. Vehicle loads upon arrival at its end location, for each type specified in Vehicle.capacities, |
↳ travel_steps |
array<Google\Cloud\Optimization\V1\ShipmentRoute\TravelStep>
Deprecated: Use ShipmentRoute.transitions instead. Ordered list of travel steps for the route. |
↳ vehicle_detour |
Google\Protobuf\Duration
Deprecated: No longer used. This field will only be populated at the ShipmentRoute.Visit level. This field is the extra detour time due to the shipments visited on the route. It is equal to |
↳ delay_before_vehicle_end |
Google\Cloud\Optimization\V1\ShipmentRoute\Delay
Deprecated: Delay occurring before the vehicle end. See TransitionAttributes.delay. |
getVehicleIndex
Vehicle performing the route, identified by its index in the source
ShipmentModel
.
Returns | |
---|---|
Type | Description |
int |
setVehicleIndex
Vehicle performing the route, identified by its index in the source
ShipmentModel
.
Parameter | |
---|---|
Name | Description |
var |
int
|
Returns | |
---|---|
Type | Description |
$this |
getVehicleLabel
Label of the vehicle performing this route, equal to
ShipmentModel.vehicles(vehicle_index).label
, if specified.
Returns | |
---|---|
Type | Description |
string |
setVehicleLabel
Label of the vehicle performing this route, equal to
ShipmentModel.vehicles(vehicle_index).label
, if specified.
Parameter | |
---|---|
Name | Description |
var |
string
|
Returns | |
---|---|
Type | Description |
$this |
getVehicleStartTime
Time at which the vehicle starts its route.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Timestamp|null |
hasVehicleStartTime
clearVehicleStartTime
setVehicleStartTime
Time at which the vehicle starts its route.
Parameter | |
---|---|
Name | Description |
var |
Google\Protobuf\Timestamp
|
Returns | |
---|---|
Type | Description |
$this |
getVehicleEndTime
Time at which the vehicle finishes its route.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Timestamp|null |
hasVehicleEndTime
clearVehicleEndTime
setVehicleEndTime
Time at which the vehicle finishes its route.
Parameter | |
---|---|
Name | Description |
var |
Google\Protobuf\Timestamp
|
Returns | |
---|---|
Type | Description |
$this |
getVisits
Ordered sequence of visits representing a route.
visits[i] is the i-th visit in the route. If this field is empty, the vehicle is considered as unused.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Internal\RepeatedField |
setVisits
Ordered sequence of visits representing a route.
visits[i] is the i-th visit in the route. If this field is empty, the vehicle is considered as unused.
Parameter | |
---|---|
Name | Description |
var |
array<Google\Cloud\Optimization\V1\ShipmentRoute\Visit>
|
Returns | |
---|---|
Type | Description |
$this |
getTransitions
Ordered list of transitions for the route.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Internal\RepeatedField |
setTransitions
Ordered list of transitions for the route.
Parameter | |
---|---|
Name | Description |
var |
array<Google\Cloud\Optimization\V1\ShipmentRoute\Transition>
|
Returns | |
---|---|
Type | Description |
$this |
getHasTrafficInfeasibilities
When OptimizeToursRequest.consider_road_traffic, is set to true, this field indicates that inconsistencies in route timings are predicted using traffic-based travel duration estimates. There may be insufficient time to complete traffic-adjusted travel, delays, and breaks between visits, before the first visit, or after the last visit, while still satisfying the visit and vehicle time windows. For example,
start_time(previous_visit) + duration(previous_visit) +
travel_duration(previous_visit, next_visit) > start_time(next_visit)
Arrival at next_visit will likely happen later than its current
time window due the increased estimate of travel time
travel_duration(previous_visit, next_visit)
due to traffic. Also, a break
may be forced to overlap with a visit due to an increase in travel time
estimates and visit or break time window restrictions.
Returns | |
---|---|
Type | Description |
bool |
setHasTrafficInfeasibilities
When OptimizeToursRequest.consider_road_traffic, is set to true, this field indicates that inconsistencies in route timings are predicted using traffic-based travel duration estimates. There may be insufficient time to complete traffic-adjusted travel, delays, and breaks between visits, before the first visit, or after the last visit, while still satisfying the visit and vehicle time windows. For example,
start_time(previous_visit) + duration(previous_visit) +
travel_duration(previous_visit, next_visit) > start_time(next_visit)
Arrival at next_visit will likely happen later than its current
time window due the increased estimate of travel time
travel_duration(previous_visit, next_visit)
due to traffic. Also, a break
may be forced to overlap with a visit due to an increase in travel time
estimates and visit or break time window restrictions.
Parameter | |
---|---|
Name | Description |
var |
bool
|
Returns | |
---|---|
Type | Description |
$this |
getRoutePolyline
The encoded polyline representation of the route.
This field is only populated if OptimizeToursRequest.populate_polylines is set to true.
Returns | |
---|---|
Type | Description |
Google\Cloud\Optimization\V1\ShipmentRoute\EncodedPolyline|null |
hasRoutePolyline
clearRoutePolyline
setRoutePolyline
The encoded polyline representation of the route.
This field is only populated if OptimizeToursRequest.populate_polylines is set to true.
Parameter | |
---|---|
Name | Description |
var |
Google\Cloud\Optimization\V1\ShipmentRoute\EncodedPolyline
|
Returns | |
---|---|
Type | Description |
$this |
getBreaks
Breaks scheduled for the vehicle performing this route.
The breaks
sequence represents time intervals, each starting at the
corresponding start_time
and lasting duration
seconds.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Internal\RepeatedField |
setBreaks
Breaks scheduled for the vehicle performing this route.
The breaks
sequence represents time intervals, each starting at the
corresponding start_time
and lasting duration
seconds.
Parameter | |
---|---|
Name | Description |
var |
array<Google\Cloud\Optimization\V1\ShipmentRoute\PBBreak>
|
Returns | |
---|---|
Type | Description |
$this |
getMetrics
Duration, distance and load metrics for this route. The fields of AggregatedMetrics are summed over all ShipmentRoute.transitions or ShipmentRoute.visits, depending on the context.
Returns | |
---|---|
Type | Description |
Google\Cloud\Optimization\V1\AggregatedMetrics|null |
hasMetrics
clearMetrics
setMetrics
Duration, distance and load metrics for this route. The fields of AggregatedMetrics are summed over all ShipmentRoute.transitions or ShipmentRoute.visits, depending on the context.
Parameter | |
---|---|
Name | Description |
var |
Google\Cloud\Optimization\V1\AggregatedMetrics
|
Returns | |
---|---|
Type | Description |
$this |
getRouteCosts
Cost of the route, broken down by cost-related request fields.
The keys are proto paths, relative to the input OptimizeToursRequest, e.g. "model.shipments.pickups.cost", and the values are the total cost generated by the corresponding cost field, aggregated over the whole route. In other words, costs["model.shipments.pickups.cost"] is the sum of all pickup costs over the route. All costs defined in the model are reported in detail here with the exception of costs related to TransitionAttributes that are only reported in an aggregated way as of 2022/01.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Internal\MapField |
setRouteCosts
Cost of the route, broken down by cost-related request fields.
The keys are proto paths, relative to the input OptimizeToursRequest, e.g. "model.shipments.pickups.cost", and the values are the total cost generated by the corresponding cost field, aggregated over the whole route. In other words, costs["model.shipments.pickups.cost"] is the sum of all pickup costs over the route. All costs defined in the model are reported in detail here with the exception of costs related to TransitionAttributes that are only reported in an aggregated way as of 2022/01.
Parameter | |
---|---|
Name | Description |
var |
array|Google\Protobuf\Internal\MapField
|
Returns | |
---|---|
Type | Description |
$this |
getRouteTotalCost
Total cost of the route. The sum of all costs in the cost map.
Returns | |
---|---|
Type | Description |
float |
setRouteTotalCost
Total cost of the route. The sum of all costs in the cost map.
Parameter | |
---|---|
Name | Description |
var |
float
|
Returns | |
---|---|
Type | Description |
$this |
getEndLoads
Deprecated: Use
Transition.vehicle_loads
instead. Vehicle loads upon arrival at its end location, for each type
specified in
Vehicle.capacities,
start_load_intervals
, end_load_intervals
or demands. Exception: we omit
loads for quantity types unconstrained by intervals and that don't have any
non-zero demand on the route.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Internal\RepeatedField |
setEndLoads
Deprecated: Use
Transition.vehicle_loads
instead. Vehicle loads upon arrival at its end location, for each type
specified in
Vehicle.capacities,
start_load_intervals
, end_load_intervals
or demands. Exception: we omit
loads for quantity types unconstrained by intervals and that don't have any
non-zero demand on the route.
Parameter | |
---|---|
Name | Description |
var |
array<Google\Cloud\Optimization\V1\CapacityQuantity>
|
Returns | |
---|---|
Type | Description |
$this |
getTravelSteps
Deprecated: Use ShipmentRoute.transitions instead. Ordered list of travel steps for the route.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Internal\RepeatedField |
setTravelSteps
Deprecated: Use ShipmentRoute.transitions instead. Ordered list of travel steps for the route.
Parameter | |
---|---|
Name | Description |
var |
array<Google\Cloud\Optimization\V1\ShipmentRoute\TravelStep>
|
Returns | |
---|---|
Type | Description |
$this |
getVehicleDetour
Deprecated: No longer used.
This field will only be populated at the
ShipmentRoute.Visit
level.
This field is the extra detour time due to the shipments visited on the
route.
It is equal to vehicle_end_time
- vehicle_start_time
- travel duration
from the vehicle's start_location to its end_location
.
Returns | |
---|---|
Type | Description |
Google\Protobuf\Duration|null |
hasVehicleDetour
clearVehicleDetour
setVehicleDetour
Deprecated: No longer used.
This field will only be populated at the
ShipmentRoute.Visit
level.
This field is the extra detour time due to the shipments visited on the
route.
It is equal to vehicle_end_time
- vehicle_start_time
- travel duration
from the vehicle's start_location to its end_location
.
Parameter | |
---|---|
Name | Description |
var |
Google\Protobuf\Duration
|
Returns | |
---|---|
Type | Description |
$this |
getDelayBeforeVehicleEnd
Deprecated: Delay occurring before the vehicle end. See TransitionAttributes.delay.
Returns | |
---|---|
Type | Description |
Google\Cloud\Optimization\V1\ShipmentRoute\Delay|null |
hasDelayBeforeVehicleEnd
clearDelayBeforeVehicleEnd
setDelayBeforeVehicleEnd
Deprecated: Delay occurring before the vehicle end. See TransitionAttributes.delay.
Parameter | |
---|---|
Name | Description |
var |
Google\Cloud\Optimization\V1\ShipmentRoute\Delay
|
Returns | |
---|---|
Type | Description |
$this |