Package types (1.1.0)

API documentation for optimization_v1.types package.

Classes

AggregatedMetrics

Aggregated metrics for ShipmentRoute (resp. for OptimizeToursResponse over all Transition and/or Visit (resp. over all ShipmentRoute) elements.

AsyncModelMetadata

The long running operation metadata for async model related methods.

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.

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).

CapacityQuantity

Deprecated: Use [Shipment.Load][], [Vehicle.LoadLimit][] and [ShipmentRoute.VehicleLoad][] instead.

CapacityQuantityInterval

Deprecated: Use [Vehicle.LoadLimit.Interval][] instead.

DataFormat

Data formats for input and output files.

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.

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.

InputConfig

The desired input location information.

.. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields

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.

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.

OptimizeToursValidationError

Describes an error encountered when validating an OptimizeToursRequest.

OutputConfig

The desired output location.

.. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields

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).

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

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 | | | | || || | | | | | | || --++-----------------------------------------------------------------++-->

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.

ShipmentTypeRequirement

Specifies requirements between shipments based on their shipment_type. The specifics of the requirement are defined by the requirement mode.

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.

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 and 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).

Waypoint

Encapsulates a waypoint. Waypoints mark arrival and departure locations of VisitRequests, and start and end locations of Vehicles.

This message has oneof_ fields (mutually exclusive fields). For each oneof, at most one member field can be set at the same time. Setting any member of the oneof automatically clears all other members.

.. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields