Classes
AggregatedMetrics
Aggregated metrics for [ShipmentRoute][google.cloud.optimization.v1.ShipmentRoute] (resp. for [OptimizeToursResponse][google.cloud.optimization.v1.OptimizeToursResponse] over all [Transition][google.cloud.optimization.v1.ShipmentRoute.Transition] and/or [Visit][google.cloud.optimization.v1.ShipmentRoute.Visit] (resp. over all [ShipmentRoute][google.cloud.optimization.v1.ShipmentRoute]) elements.
AsyncModelMetadata
The long running operation metadata for async model related methods.
AsyncModelMetadata.Types
Container for nested types declared in the AsyncModelMetadata message type.
BatchOptimizeToursRequest
Request to batch optimize tours as an asynchronous operation.
Each input file should contain one OptimizeToursRequest
, and each output
file will contain one OptimizeToursResponse
. The request contains
information to read/write and parse the files. All the input and output files
should be under the same project.
BatchOptimizeToursRequest.Types
Container for nested types declared in the BatchOptimizeToursRequest message type.
BatchOptimizeToursRequest.Types.AsyncModelConfig
Information for solving one optimization model asynchronously.
BatchOptimizeToursResponse
Response to a BatchOptimizeToursRequest
. This is returned in
the LRO Operation after the operation is complete.
BreakRule
Rules to generate time breaks for a vehicle (e.g. lunch breaks). A break is a contiguous period of time during which the vehicle remains idle at its current position and cannot perform any visit. A break may occur:
- during the travel between two visits (which includes the time right before or right after a visit, but not in the middle of a visit), in which case it extends the corresponding transit time between the visits,
- or before the vehicle start (the vehicle may not start in the middle of a break), in which case it does not affect the vehicle start time.
- or after the vehicle end (ditto, with the vehicle end time).
BreakRule.Types
Container for nested types declared in the BreakRule message type.
BreakRule.Types.BreakRequest
The sequence of breaks (i.e. their number and order) that apply to each
vehicle must be known beforehand. The repeated BreakRequest
s define
that sequence, in the order in which they must occur. Their time windows
(earliest_start_time
/ latest_start_time
) may overlap, but they must
be compatible with the order (this is checked).
BreakRule.Types.FrequencyConstraint
One may further constrain the frequency and duration of the breaks
specified above, by enforcing a minimum break frequency, such as
"There must be a break of at least 1 hour every 12 hours". Assuming that
this can be interpreted as "Within any sliding time window of 12h, there
must be at least one break of at least one hour", that example would
translate to the following FrequencyConstraint
:
{
min_break_duration { seconds: 3600 } # 1 hour.
max_inter_break_duration { seconds: 39600 } # 11 hours (12 - 1 = 11).
}
The timing and duration of the breaks in the solution will respect all
such constraints, in addition to the time windows and minimum durations
already specified in the BreakRequest
.
A FrequencyConstraint
may in practice apply to non-consecutive breaks.
For example, the following schedule honors the "1h every 12h" example:
04:00 vehicle start
.. performing travel and visits ..
09:00 1 hour break
10:00 end of the break
.. performing travel and visits ..
12:00 20-min lunch break
12:20 end of the break
.. performing travel and visits ..
21:00 1 hour break
22:00 end of the break
.. performing travel and visits ..
23:59 vehicle end
CapacityQuantity
Deprecated: Use [Vehicle.LoadLimit.Interval][google.cloud.optimization.v1.Vehicle.LoadLimit.Interval] instead.
CapacityQuantityInterval
Deprecated: Use [Vehicle.LoadLimit.Interval][google.cloud.optimization.v1.Vehicle.LoadLimit.Interval] instead.
DistanceLimit
A limit defining a maximum distance which can be traveled. It can be either hard or soft.
If a soft limit is defined, both soft_max_meters
and
cost_per_kilometer_above_soft_max
must be defined and be nonnegative.
FleetRouting
A service for optimizing vehicle tours.
Validity of certain types of fields:
google.protobuf.Timestamp
- Times are in Unix time: seconds since 1970-01-01T00:00:00+00:00.
- seconds must be in [0, 253402300799], i.e. in [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00].
- nanos must be unset or set to 0.
google.protobuf.Duration
- seconds must be in [0, 253402300799], i.e. in [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00].
- nanos must be unset or set to 0.
google.type.LatLng
- latitude must be in [-90.0, 90.0].
- longitude must be in [-180.0, 180.0].
- at least one of latitude and longitude must be non-zero.
FleetRouting.FleetRoutingBase
Base class for server-side implementations of FleetRouting
FleetRouting.FleetRoutingClient
Client for FleetRouting
FleetRoutingClient
FleetRouting client wrapper, for convenient use.
FleetRoutingClientBuilder
Builder class for FleetRoutingClient to provide simple configuration of credentials, endpoint etc.
FleetRoutingClientImpl
FleetRouting client wrapper implementation, for convenient use.
FleetRoutingSettings
Settings for FleetRoutingClient instances.
GcsDestination
The Google Cloud Storage location where the output file will be written to.
GcsSource
The Google Cloud Storage location where the input file will be read from.
InjectedSolutionConstraint
Solution injected in the request including information about which visits must be constrained and how they must be constrained.
InjectedSolutionConstraint.Types
Container for nested types declared in the InjectedSolutionConstraint message type.
InjectedSolutionConstraint.Types.ConstraintRelaxation
For a group of vehicles, specifies at what threshold(s) constraints on
visits will be relaxed and to which level. Shipments listed in
the skipped_shipment
field are constrained to be skipped; i.e., they
cannot be performed.
InjectedSolutionConstraint.Types.ConstraintRelaxation.Types
Container for nested types declared in the ConstraintRelaxation message type.
InjectedSolutionConstraint.Types.ConstraintRelaxation.Types.Relaxation
If relaxations
is empty, the start time and sequence of all visits
on routes
are fully constrained and no new visits may be inserted or
added to those routes. Also, a vehicle's start and end time in
routes
is fully constrained, unless the vehicle is empty (i.e., has no
visits and has used_if_route_is_empty
set to false in the model).
relaxations(i).level
specifies the constraint relaxation level applied
to a visit #j that satisfies:
route.visits(j).start_time >= relaxations(i).threshold_time
ANDj + 1 >= relaxations(i).threshold_visit_count
Similarly, the vehicle start is relaxed to relaxations(i).level
if it
satisfies:
vehicle_start_time >= relaxations(i).threshold_time
ANDrelaxations(i).threshold_visit_count == 0
and the vehicle end is relaxed torelaxations(i).level
if it satisfies:vehicle_end_time >= relaxations(i).threshold_time
ANDroute.visits_size() + 1 >= relaxations(i).threshold_visit_count
To apply a relaxation level if a visit meets the threshold_visit_count
OR the threshold_time
add two relaxations
with the same level
:
one with only threshold_visit_count
set and the other with only
threshold_time
set. If a visit satisfies the conditions of multiple
relaxations
, the most relaxed level applies. As a result, from the
vehicle start through the route visits in order to the vehicle end, the
relaxation level becomes more relaxed: i.e., the relaxation level is
non-decreasing as the route progresses.
The timing and sequence of route visits that do not satisfy the
threshold conditions of any relaxations
are fully constrained
and no visits may be inserted into these sequences. Also, if a
vehicle start or end does not satisfy the conditions of any
relaxation the time is fixed, unless the vehicle is empty.
InjectedSolutionConstraint.Types.ConstraintRelaxation.Types.Relaxation.Types
Container for nested types declared in the Relaxation message type.
InputConfig
The desired input location information.
Location
Encapsulates a location (a geographic point, and an optional heading).
OptimizeToursRequest
Request to be given to a tour optimization solver which defines the shipment model to solve as well as optimization parameters.
OptimizeToursRequest.Types
Container for nested types declared in the OptimizeToursRequest message type.
OptimizeToursResponse
Response after solving a tour optimization problem containing the routes followed by each vehicle, the shipments which have been skipped and the overall cost of the solution.
OptimizeToursResponse.Types
Container for nested types declared in the OptimizeToursResponse message type.
OptimizeToursResponse.Types.Metrics
Overall metrics, aggregated over all routes.
OptimizeToursValidationError
Describes an error encountered when validating an OptimizeToursRequest
.
OptimizeToursValidationError.Types
Container for nested types declared in the OptimizeToursValidationError message type.
OptimizeToursValidationError.Types.FieldReference
Specifies a context for the validation error. A FieldReference
always
refers to a given field in this file and follows the same hierarchical
structure. For example, we may specify element #2 of start_time_windows
of vehicle #5 using:
name: "vehicles" index: 5 sub_field { name: "end_time_windows" index: 2 }
We however omit top-level entities such as OptimizeToursRequest
or
ShipmentModel
to avoid crowding the message.
OutputConfig
The desired output location.
RouteModifiers
Encapsulates a set of optional conditions to satisfy when calculating
vehicle routes. This is similar to RouteModifiers
in the Google Maps
Platform API; see:
https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteModifiers.
Shipment
The shipment of a single item, from one of its pickups to one of its deliveries. For the shipment to be considered as performed, a unique vehicle must visit one of its pickup locations (and decrease its spare capacities accordingly), then visit one of its delivery locations later on (and therefore re-increase its spare capacities accordingly).
Shipment.Types
Container for nested types declared in the Shipment message type.
Shipment.Types.Load
When performing a visit, a predefined amount may be added to the vehicle load if it's a pickup, or subtracted if it's a delivery. This message defines such amount. See [load_demands][google.cloud.optimization.v1.Shipment.load_demands].
Shipment.Types.VisitRequest
Request for a visit which can be done by a vehicle: it has a geo-location (or two, see below), opening and closing times represented by time windows, and a service duration time (time spent by the vehicle once it has arrived to pickup or drop off goods).
ShipmentModel
A shipment model contains a set of shipments which must be performed by a set of vehicles, while minimizing the overall cost, which is the sum of:
- the cost of routing the vehicles (sum of cost per total time, cost per travel time, and fixed cost over all vehicles).
- the unperformed shipment penalties.
- the cost of the global duration of the shipments
ShipmentModel.Types
Container for nested types declared in the ShipmentModel message type.
ShipmentModel.Types.BreakRule
Deprecated: Use top level [BreakRule][google.cloud.optimization.v1.ShipmentModel.BreakRule] instead. Rules to generate time breaks for a vehicle (e.g. lunch breaks). A break is a contiguous period of time during which the vehicle remains idle at its current position and cannot perform any visit. A break may occur:
- during the travel between two visits (which includes the time right before or right after a visit, but not in the middle of a visit), in which case it extends the corresponding transit time between the visits
- before the vehicle start (the vehicle may not start in the middle of a break), in which case it does not affect the vehicle start time.
- after the vehicle end (ditto, with the vehicle end time).
ShipmentModel.Types.BreakRule.Types
Container for nested types declared in the BreakRule message type.
ShipmentModel.Types.BreakRule.Types.BreakRequest
The sequence of breaks (i.e. their number and order) that apply to each
vehicle must be known beforehand. The repeated BreakRequest
s define
that sequence, in the order in which they must occur. Their time windows
(earliest_start_time
/ latest_start_time
) may overlap, but they must
be compatible with the order (this is checked).
ShipmentModel.Types.BreakRule.Types.FrequencyConstraint
One may further constrain the frequency and duration of the breaks
specified above, by enforcing a minimum break frequency, such as
"There must be a break of at least 1 hour every 12 hours". Assuming that
this can be interpreted as "Within any sliding time window of 12h, there
must be at least one break of at least one hour", that example would
translate to the following FrequencyConstraint
:
{
min_break_duration { seconds: 3600 } # 1 hour.
max_inter_break_duration { seconds: 39600 } # 11 hours (12 - 1 = 11).
}
The timing and duration of the breaks in the solution will respect all
such constraints, in addition to the time windows and minimum durations
already specified in the BreakRequest
.
A FrequencyConstraint
may in practice apply to non-consecutive breaks.
For example, the following schedule honors the "1h every 12h" example:
04:00 vehicle start
.. performing travel and visits ..
09:00 1 hour break
10:00 end of the break
.. performing travel and visits ..
12:00 20-min lunch break
12:20 end of the break
.. performing travel and visits ..
21:00 1 hour break
22:00 end of the break
.. performing travel and visits ..
23:59 vehicle end
ShipmentModel.Types.DurationDistanceMatrix
Specifies a duration and distance matrix from visit and vehicle start locations to visit and vehicle end locations.
ShipmentModel.Types.DurationDistanceMatrix.Types
Container for nested types declared in the DurationDistanceMatrix message type.
ShipmentModel.Types.DurationDistanceMatrix.Types.Row
Specifies a row of the duration and distance matrix.
ShipmentModel.Types.PrecedenceRule
A precedence rule between two events (each event is the pickup or the
delivery of a shipment): the "second" event has to start at least
offset_duration
after "first" has started.
Several precedences can refer to the same (or related) events, e.g., "pickup of B happens after delivery of A" and "pickup of C happens after pickup of B".
Furthermore, precedences only apply when both shipments are performed and are otherwise ignored.
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 a Visit
:
---+-------------------------------------+-----------------------------+-->
| 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:
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 | | | | ||
|| | | | | | | ||
--++-----------------------------------------------------------------++-->
ShipmentRoute.Types
Container for nested types declared in the ShipmentRoute message type.
ShipmentRoute.Types.Break
Data representing the execution of a break.
ShipmentRoute.Types.Delay
Deprecated: Use [ShipmentRoute.Transition.delay_duration][google.cloud.optimization.v1.ShipmentRoute.Transition.delay_duration] instead. Time interval spent on the route resulting from a [TransitionAttributes.delay][google.cloud.optimization.v1.TransitionAttributes.delay].
ShipmentRoute.Types.EncodedPolyline
The encoded representation of a polyline. More information on polyline encoding can be found here: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.
ShipmentRoute.Types.Transition
Transition between two events on the route. See the description of [ShipmentRoute][google.cloud.optimization.v1.ShipmentRoute].
If the vehicle does not have a start_location
and/or end_location
, the
corresponding travel metrics are 0.
ShipmentRoute.Types.TravelStep
Deprecated: Use
[ShipmentRoute.Transition][google.cloud.optimization.v1.ShipmentRoute.Transition]
instead. Travel between each visit along the route: from the vehicle's
start_location
to the first visit's arrival_location
, then from the
first visit's departure_location
to the second visit's
arrival_location
, and so on until the vehicle's end_location
. This
accounts only for the actual travel between visits, not counting the
waiting time, the time spent performing a visit, nor the distance covered
during a visit.
Invariant: travel_steps_size() == visits_size() + 1
.
If the vehicle does not have a start_ and/or end_location, the corresponding travel metrics are 0 and/or empty.
ShipmentRoute.Types.VehicleLoad
Reports the actual load of the vehicle at some point along the route, for a given type (see [Transition.vehicle_loads][google.cloud.optimization.v1.ShipmentRoute.Transition.vehicle_loads]).
ShipmentRoute.Types.Visit
A visit performed during a route. This visit corresponds to a pickup or a
delivery of a Shipment
.
ShipmentTypeIncompatibility
Specifies incompatibilties between shipments depending on their shipment_type. The appearance of incompatible shipments on the same route is restricted based on the incompatibility mode.
ShipmentTypeIncompatibility.Types
Container for nested types declared in the ShipmentTypeIncompatibility message type.
ShipmentTypeRequirement
Specifies requirements between shipments based on their shipment_type. The specifics of the requirement are defined by the requirement mode.
ShipmentTypeRequirement.Types
Container for nested types declared in the ShipmentTypeRequirement message type.
SkippedShipment
Specifies details of unperformed shipments in a solution. For trivial cases and/or if we are able to identify the cause for skipping, we report the reason here.
SkippedShipment.Types
Container for nested types declared in the SkippedShipment message type.
SkippedShipment.Types.Reason
If we can explain why the shipment was skipped, reasons will be listed
here. If the reason is not the same for all vehicles, reason
will have
more than 1 element. A skipped shipment cannot have duplicate reasons,
i.e. where all fields are the same except for example_vehicle_index
.
Example:
reasons {
code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
example_vehicle_index: 1
example_exceeded_capacity_type: "Apples"
}
reasons {
code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
example_vehicle_index: 3
example_exceeded_capacity_type: "Pears"
}
reasons {
code: CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT
example_vehicle_index: 1
}
The skipped shipment is incompatible with all vehicles. The reasons may be different for all vehicles but at least one vehicle's "Apples" capacity would be exceeded (including vehicle 1), at least one vehicle's "Pears" capacity would be exceeded (including vehicle 3) and at least one vehicle's distance limit would be exceeded (including vehicle 1).
SkippedShipment.Types.Reason.Types
Container for nested types declared in the Reason message type.
TimeWindow
Time windows constrain the time of an event, such as the arrival time at a visit, or the start and end time of a vehicle.
Hard time window bounds, start_time
and end_time
, enforce the earliest
and latest time of the event, such that start_time <= event_time <=
end_time
. The soft time window lower bound, soft_start_time
, expresses a
preference for the event to happen at or after soft_start_time
by incurring
a cost proportional to how long before soft_start_time the event occurs. The
soft time window upper bound, soft_end_time
, expresses a preference for the
event to happen at or before soft_end_time
by incurring a cost proportional
to how long after soft_end_time
the event occurs. start_time
, end_time
,
soft_start_time
and soft_end_time
should be within the global time limits
(see
[ShipmentModel.global_start_time][google.cloud.optimization.v1.ShipmentModel.global_start_time]
and
[ShipmentModel.global_end_time][google.cloud.optimization.v1.ShipmentModel.global_end_time])
and should respect:
0 <= `start_time` <= `soft_start_time` <= `end_time` and
0 <= `start_time` <= `soft_end_time` <= `end_time`.
TransitionAttributes
Specifies attributes of transitions between two consecutive visits on a
route. Several TransitionAttributes
may apply to the same transition: in
that case, all extra costs add up and the strictest constraint or limit
applies (following natural "AND" semantics).
Vehicle
Models a vehicle in a shipment problem. Solving a shipment problem will
build a route starting from start_location
and ending at end_location
for this vehicle. A route is a sequence of visits (see ShipmentRoute
).
Vehicle.Types
Container for nested types declared in the Vehicle message type.
Vehicle.Types.DurationLimit
A limit defining a maximum duration of the route of a vehicle. It can be either hard or soft.
When a soft limit field is defined, both the soft max threshold and its associated cost must be defined together.
Vehicle.Types.LoadLimit
Defines a load limit applying to a vehicle, e.g. "this truck may only carry up to 3500 kg". See [load_limits][google.cloud.optimization.v1.Vehicle.load_limits].
Vehicle.Types.LoadLimit.Types
Container for nested types declared in the LoadLimit message type.
Vehicle.Types.LoadLimit.Types.Interval
Interval of acceptable load amounts.
Waypoint
Encapsulates a waypoint. Waypoints mark arrival and departure locations of VisitRequests, and start and end locations of Vehicles.
Enums
AsyncModelMetadata.Types.State
Possible states of the operation.
DataFormat
Data formats for input and output files.
InjectedSolutionConstraint.Types.ConstraintRelaxation.Types.Relaxation.Types.Level
Expresses the different constraint relaxation levels, which are applied for a visit and those that follow when it satisfies the threshold conditions.
The enumeration below is in order of increasing relaxation.
InputConfig.SourceOneofCase
Enum of possible cases for the "source" oneof.
OptimizeToursRequest.Types.SearchMode
Mode defining the behavior of the search, trading off latency versus solution quality. In all modes, the global request deadline is enforced.
OptimizeToursRequest.Types.SolvingMode
Defines how the solver should handle the request. In all modes but
VALIDATE_ONLY
, if the request is invalid, you will receive an
INVALID_REQUEST
error. See
[max_validation_errors][google.cloud.optimization.v1.OptimizeToursRequest.max_validation_errors]
to cap the number of errors returned.
OptimizeToursValidationError.Types.FieldReference.IndexOrKeyOneofCase
Enum of possible cases for the "index_or_key" oneof.
OutputConfig.DestinationOneofCase
Enum of possible cases for the "destination" oneof.
ShipmentTypeIncompatibility.Types.IncompatibilityMode
Modes defining how the appearance of incompatible shipments are restricted on the same route.
ShipmentTypeRequirement.Types.RequirementMode
Modes defining the appearance of dependent shipments on a route.
SkippedShipment.Types.Reason.Types.Code
Code identifying the reason type. The order here is meaningless. In particular, it gives no indication of whether a given reason will appear before another in the solution, if both apply.
Vehicle.Types.TravelMode
Travel modes which can be used by vehicles.
These should be a subset of the Google Maps Platform Routes Preferred API travel modes, see: https://developers.google.com/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode.
Vehicle.Types.UnloadingPolicy
Policy on how a vehicle can be unloaded. Applies only to shipments having both a pickup and a delivery.
Other shipments are free to occur anywhere on the route independent of
unloading_policy
.
Waypoint.LocationTypeOneofCase
Enum of possible cases for the "location_type" oneof.