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
JSON representation 
{
  "shipments": [
    {
      object (Shipment)
    }
  ],
  "vehicles": [
    {
      object (Vehicle)
    }
  ],
  "globalStartTime": string,
  "globalEndTime": string,
  "globalDurationCostPerHour": number,
  "durationDistanceMatrices": [
    {
      object (DurationDistanceMatrix)
    }
  ],
  "durationDistanceMatrixSrcTags": [
    string
  ],
  "durationDistanceMatrixDstTags": [
    string
  ],
  "transitionAttributes": [
    {
      object (TransitionAttributes)
    }
  ],
  "shipmentTypeIncompatibilities": [
    {
      object (ShipmentTypeIncompatibility)
    }
  ],
  "shipmentTypeRequirements": [
    {
      object (ShipmentTypeRequirement)
    }
  ],
  "precedenceRules": [
    {
      object (PrecedenceRule)
    }
  ],
  "breakRules": [
    {
      object (BreakRule)
    }
  ],
  "maxActiveVehicles": integer
}
Fields
shipments[]

object (Shipment)

Set of shipments which must be performed in the model.
vehicles[]

object (Vehicle)

Set of vehicles which can be used to perform visits.
globalStartTime

string (Timestamp format)

Global start and end time of the model: no times outside of this range can be considered valid.

The model's time span must be less than a year, i.e. the globalEndTime and the globalStartTime must be within 31536000 seconds of each other.

When using cost_per_*hour fields, you might want to set this window to a smaller interval to increase performance (eg. if you model a single day, you should set the global time limits to that day). If unset, 00:00:00 UTC, January 1, 1970 (i.e. seconds: 0, nanos: 0) is used as default.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
globalEndTime

string (Timestamp format)

If unset, 00:00:00 UTC, January 1, 1971 (i.e. seconds: 31536000, nanos: 0) is used as default.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
globalDurationCostPerHour

number

The "global duration" of the overall plan is the difference between the earliest effective start time and the latest effective end time of all vehicles. Users can assign a cost per hour to that quantity to try and optimize for earliest job completion, for example. This cost must be in the same unit as Shipment.penalty_cost.
durationDistanceMatrices[]

object (DurationDistanceMatrix)

Specifies duration and distance matrices used in the model. If this field is empty, Google Maps or geodesic distances will be used instead, depending on the value of the useGeodesicDistances field. If it is not empty, useGeodesicDistances cannot be true and neither durationDistanceMatrixSrcTags nor durationDistanceMatrixDstTags can be empty.

Usage examples:

  • There are two locations: locA and locB.
  • 1 vehicle starting its route at locA and ending it at locA.
  • 1 pickup visit request at locB.
model {
  vehicles { startTags: "locA"  endTags: "locA" }
  shipments { pickups { tags: "locB" } }
  durationDistanceMatrixSrcTags: "locA"
  durationDistanceMatrixSrcTags: "locB"
  durationDistanceMatrixDstTags: "locA"
  durationDistanceMatrixDstTags: "locB"
  durationDistanceMatrices {
    rows {  # from: locA
      durations { seconds: 0 }   meters: 0    # to: locA
      durations { seconds: 100 } meters: 1000 # to: locB
    }
    rows {  # from: locB
      durations { seconds: 102 } meters: 990 # to: locA
      durations { seconds: 0 }   meters: 0   # to: locB
    }
  }
}
  • There are three locations: locA, locB and locC.
  • 1 vehicle starting its route at locA and ending it at locB, using matrix "fast".
  • 1 vehicle starting its route at locB and ending it at locB, using matrix "slow".
  • 1 vehicle starting its route at locB and ending it at locB, using matrix "fast".
  • 1 pickup visit request at locC.
model {
  vehicles { startTags: "locA" endTags: "locB" startTags: "fast" }
  vehicles { startTags: "locB" endTags: "locB" startTags: "slow" }
  vehicles { startTags: "locB" endTags: "locB" startTags: "fast" }
  shipments { pickups { tags: "locC" } }
  durationDistanceMatrixSrcTags: "locA"
  durationDistanceMatrixSrcTags: "locB"
  durationDistanceMatrixSrcTags: "locC"
  durationDistanceMatrixDstTags: "locB"
  durationDistanceMatrixDstTags: "locC"
  durationDistanceMatrices {
    vehicleStartTag: "fast"
    rows {  # from: locA
      durations { seconds: 1000 } meters: 2000 # to: locB
      durations { seconds: 600 }  meters: 1000 # to: locC
    }
    rows {  # from: locB
      durations { seconds: 0 }   meters: 0    # to: locB
      durations { seconds: 700 } meters: 1200 # to: locC
    }
    rows {  # from: locC
      durations { seconds: 702 } meters: 1190 # to: locB
      durations { seconds: 0 }   meters: 0    # to: locC
    }
  }
  durationDistanceMatrices {
    vehicleStartTag: "slow"
    rows {  # from: locA
      durations { seconds: 1800 } meters: 2001 # to: locB
      durations { seconds: 900 }  meters: 1002 # to: locC
    }
    rows {  # from: locB
      durations { seconds: 0 }    meters: 0    # to: locB
      durations { seconds: 1000 } meters: 1202 # to: locC
    }
    rows {  # from: locC
      durations { seconds: 1001 } meters: 1195 # to: locB
      durations { seconds: 0 }    meters: 0    # to: locC
    }
  }
}
durationDistanceMatrixSrcTags[]

string

Tags defining the sources of the duration and distance matrices; durationDistanceMatrices(i).rows(j) defines durations and distances from visits with tag durationDistanceMatrixSrcTags(j) to other visits in matrix i.

Tags correspond to VisitRequest.tags or Vehicle.start_tags. A given VisitRequest or Vehicle must match exactly one tag in this field. Note that a Vehicle's source, destination and matrix tags may be the same; similarly a VisitRequest's source and destination tags may be the same. All tags must be different and cannot be empty strings. If this field is not empty, then durationDistanceMatrices must not be empty.
durationDistanceMatrixDstTags[]

string

Tags defining the destinations of the duration and distance matrices; durationDistanceMatrices(i).rows(j).durations(k) (resp. durationDistanceMatrices(i).rows(j).meters(k)) defines the duration (resp. the distance) of the travel from visits with tag durationDistanceMatrixSrcTags(j) to visits with tag durationDistanceMatrixDstTags(k) in matrix i.

Tags correspond to VisitRequest.tags or Vehicle.start_tags. A given VisitRequest or Vehicle must match exactly one tag in this field. Note that a Vehicle's source, destination and matrix tags may be the same; similarly a VisitRequest's source and destination tags may be the same. All tags must be different and cannot be empty strings. If this field is not empty, then durationDistanceMatrices must not be empty.
transitionAttributes[]

object (TransitionAttributes)

Transition attributes added to the model.
shipmentTypeIncompatibilities[]

object (ShipmentTypeIncompatibility)

Sets of incompatible shipment_types (see ShipmentTypeIncompatibility).
shipmentTypeRequirements[]

object (ShipmentTypeRequirement)

Sets of shipmentType requirements (see ShipmentTypeRequirement).
precedenceRules[]

object (PrecedenceRule)

Set of precedence rules which must be enforced in the model.
breakRules[]
(deprecated)

object (BreakRule)

Deprecated: No longer used. Set of break rules used in the model. Each vehicle specifies the BreakRule that applies to it via the Vehicle.break_rule_indices field (which must be a singleton).
maxActiveVehicles

integer

Constrains the maximum number of active vehicles. A vehicle is active if its route performs at least one shipment. This can be used to limit the number of routes in the case where there are fewer drivers than vehicles and that the fleet of vehicles is heterogeneous. The optimization will then select the best subset of vehicles to use. Must be strictly positive.

DurationDistanceMatrix

Specifies a duration and distance matrix from visit and vehicle start locations to visit and vehicle end locations.

JSON representation 
{
  "rows": [
    {
      object (Row)
    }
  ],
  "vehicleStartTag": string
}
Fields
rows[]

object (Row)

Specifies the rows of the duration and distance matrix. It must have as many elements as ShipmentModel.duration_distance_matrix_src_tags.
vehicleStartTag

string

Tag defining to which vehicles this duration and distance matrix applies. If empty, this applies to all vehicles, and there can only be a single matrix.

Each vehicle start must match exactly one matrix, i.e. exactly one of their startTags field must match the vehicleStartTag of a matrix (and of that matrix only).

All matrices must have a different vehicleStartTag.

Row

Specifies a row of the duration and distance matrix.

JSON representation 
{
  "durations": [
    string
  ],
  "meters": [
    number
  ]
}
Fields
durations[]

string (Duration format)

Duration values for a given row. It must have as many elements as ShipmentModel.duration_distance_matrix_dst_tags.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
meters[]

number

Distance values for a given row. If no costs or constraints refer to distances in the model, this can be left empty; otherwise it must have as many elements as durations.

BreakRule

Deprecated: Use top level 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).
JSON representation 
{
  "breakRequests": [
    {
      object (BreakRequest)
    }
  ],
  "frequencyConstraints": [
    {
      object (FrequencyConstraint)
    }
  ]
}
Fields
breakRequests[]

object (BreakRequest)

Sequence of breaks. See the BreakRequest message.
frequencyConstraints[]

object (FrequencyConstraint)

Several FrequencyConstraint may apply. They must all be satisfied by the BreakRequests of this BreakRule. See FrequencyConstraint.

BreakRequest

The sequence of breaks (i.e. their number and order) that apply to each vehicle must be known beforehand. The repeated BreakRequests define that sequence, in the order in which they must occur. Their time windows (earliestStartTime / latestStartTime) may overlap, but they must be compatible with the order (this is checked).

JSON representation 
{
  "earliestStartTime": string,
  "latestStartTime": string,
  "minDuration": string
}
Fields
earliestStartTime

string (Timestamp format)

Required. Lower bound (inclusive) on the start of the break.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
latestStartTime

string (Timestamp format)

Required. Upper bound (inclusive) on the start of the break.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
minDuration

string (Duration format)

Required. Minimum duration of the break. Must be positive.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

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:

{
   minBreakDuration { seconds: 3600 }         # 1 hour.
   maxInterBreakDuration { 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
JSON representation 
{
  "minBreakDuration": string,
  "maxInterBreakDuration": string
}
Fields
minBreakDuration

string (Duration format)

Required. Minimum break duration for this constraint. Nonnegative. See description of FrequencyConstraint.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
maxInterBreakDuration

string (Duration format)

Required. Maximum allowed span of any interval of time in the route that does not include at least partially a break of duration >= minBreakDuration. Must be positive.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".