Package google.research.optimization.v1.networkdesign

  • This documentation details the message types used to define and solve liner shipping network design problems.

  • These messages encompass information about ports, vessels, services, commodity demands, and solver parameters.

  • CommodityDemandPath outlines the specific route and vessel service legs used to fulfill a commodity demand.

  • VesselService defines a sequence of legs that a vessel class follows on a weekly schedule, while respecting port stay constraints.

  • SolverParameters are used to configure the solver's behavior, such as the maximum time limit for finding a solution.

Index

CommodityDemand

Commodity demand, i.e., a potential demand to be fulfilled by a shipper.

Fields
id

string

Unique ID assigned to this commodity demand.
origin_port_id

string

ID of the origin port.
destination_port_id

string

ID of the destination port.
container_count

int64

Maximum number of containers to be fulfilled.
freight_rate

double

Freight rate per container (which could include a penalty for unfulfilled demand). It should remove the cost of loading and discharging per container at origin and destination.
maximum_transit_duration

Duration

Maximum transit duration (if set, should be stricly positive). Transit time is defined from the time when the first vessel serving this demand leaves the origin port to the time when the last vessel serving this demand arrives at the destination port.

CommodityDemandPath

The different services and ports that a fraction of a given commodity demand is taking. Indices used below are based on the order of vessel services in the response and the order of service legs in individual vessel services.

Fields
commodity_demand_id

string

Commodity demand ID fulfilled.
container_count

int64

Number of containers going through this path. For each commodity demand, the total fulfilled quantity cannot exceed the total demand.
vessel_service_leg_ids[]

VesselServiceLegId

List of vessel service leg IDs taken through this path. For a valid commodity demand path, the following properties hold: 1. First leg's departure_port_id must match origin_port_id of the commodity demand. 2. Last leg's destination_port_id must match destination_port_id of the commodity demand. 3. Consecutive legs' arrival_port_id and departure_port_id must match. 4. If provided for this commodity demand, the maximum transit time should be greater or equal than the total duration of the path.

VesselServiceLegId

Single vessel service leg used in a commodity demand path. For instance, consider that there are two vessel services. The first is made of three legs (indexed 0, 1 and 2) and the second two (indexed 0 and 1). In addition, the first leg of the first service arrives at the departure port of the second leg of the second service. A commodity path consisting of the three following vessel service leg ids: {vessel_service_index: 0, vessel_service_leg_index: 2} {vessel_service_index: 0, vessel_service_leg_index: 0} {vessel_service_index: 1, vessel_service_leg_index: 1} means that containers take 2 consecutive legs from the first vessel service (note that 2 and 0 are consecutive since each service is a cycle), then transships to vessel service 1 for a single leg.

Fields
vessel_service_index

int32

Index of the vessel service.
vessel_service_leg_index

int32

Index of the leg from the vessel service indexed by vessel_service_index.
vessel_service_id

string

Optional. The ID of the vessel service. This is set if and only if the service was part of the input request.

Duration

A duration (port stay/transshipment, demand transit) is defined on an hourly granularity and must be positive.

Fields
hours

int64

Number of hours defining the duration.

LegCandidate

Vessel service leg candidate. There can be multiple leg candidates between the same two ports, e.g. representing different ocean routes and/or vessel velocities. However, there can only be one leg candidate between two ports with a given duration.

Fields
id

string

Unique ID assigned to this leg candidate.
departure_port_id

string

ID of the departure port.
arrival_port_id

string

ID of the arrival port.
duration

Duration

Duration of the leg.
vessel_class_costs

map<string, double>

Cost for assigning this leg candidate to a certain vessel class. This can include vessel operating cost, bunker cost, charter cost. A vessel class can only sail though this leg candidate if it has an entry in this map.

Port

Port, e.g. a terminal or all terminals of a port.

Fields
id

string

Unique ID assigned to this port.
minimum_port_stay_duration

Duration

Minimum duration of stay for a port call. Most studies assume constant as ports typically assign more cranes to larger vessels with high move counts, as they take up more space.
minimum_transshipment_duration

Duration

Minimum duration of a transshipment at a given port, including duration to unload a container and reload it onto another vessel.
transshipment_cost

double

Cost of transshipping a container. It will usually be lower than the sum of loading and discharging because transshipping does not require customs paperwork at the port.
vessel_class_costs

map<string, VesselCost>

Costs incurred when calling this port mapped by vessel class ID. A vessel class can only call this port if it has an entry in this map.

VesselCost

Vessel cost for calling and staying at this port is defined as a linear function of the stay duration (fixed_cost + hourly_cost * hours).

Fields
fixed_cost

double

Fixed cost for calling this port.
hourly_cost

double

Hourly cost for staying at this port.

ScheduleTime

A schedule time (vessel/demand departure/arrivals) is defined on a weekly frequency at a given hour.

Fields
day

int64

Day on the schedule. Day 0 is the first possible day.
hour_of_day

int32

Hour of day of the schedule time should be an integer between 0 and 23 inclusive.

SolverParameters

Parameters that control a single solve of the LSNDSP.

Fields
time_limit

Duration

Maximum time the solver should spend on the problem. This value is not a hard limit and it does not account for the communication overhead. The expected latency to solve the problem may slightly exceed this value.

VesselClass

Vessel class, i.e., a group of vessel(s) sharing the same properties. There is no way to differentiate between two vessels from the same class.

Fields
id

string

Unique ID assigned to this vessel class.
container_capacity

int64

Vessel class capacity (in containers).
vessel_count

int64

Number of vessels in this vessel class.

VesselService

Vessel service which can be used to serve commodity demands. IMPORTANT: a current assumption is that services are on a weekly frequency and port stay times cannot exceed one week. Consider the following sequence of vessel service legs: vessel_service_legs { leg_candidate_id: "0->1" origin_departure_time {} destination_arrival_time { day: 3 hour_of_day: 12 } } vessel_service_legs { leg_candidate_id: "1->0" origin_departure_time { day: 4 } destination_arrival_time { day: 6 hour_of_day: 12 } } These legs define a one-week service lines going through two ports with both port stay times of 12 hours.

Fields
id

string

Unique ID assigned to this vessel service.
vessel_class_id

string

Vessel class ID performing the service.
vessel_service_legs[]

VesselServiceLeg

For a valid vessel service, the following properties hold: 1. It cannot be empty. 2. Consecutive legs' destination_port_id and origin_port_id must match (including for the last and first legs).

VesselServiceConstraint

Defines the level of fixing for a vessel service. This can be used to control which parts of the service are fixed and which can be optimized. The enforcement of such constraint on a service implies it cannot be removed.

Fields
vessel_service_id

string

Required. The ID of the vessel service to which this constraint applies. This must correspond to the ID of a VesselService in the vessel_services field of the DesignShippingNetworkRequest.
allowed_vessel_class_ids[]

string

Optional. The list of vessel class IDs that are permitted for this service. If empty, any vessel class can be assigned.
minimum_vessel_count

int32

Optional. Minimum number of vessels (i.e. weeks) that the service must have. If not set, there is no lower bound.
maximum_vessel_count

int32

Optional. Maximum number of vessels (i.e. weeks) that the service must have. If not set, there is no upper bound. If set, must be greater than or equal to minimum_vessel_count.
port_sequence_constraint

PortSequenceConstraint

Optional. If set, the sequence of ports is fixed according to the settings within PortSequenceConstraint. The port sequence itself is taken from the corresponding VesselService in the request.

PortSequenceConstraint

Settings for fixing the port sequence and optionally the schedule.

Fields
maximum_schedule_time_deviation

Duration

Optional. Maximum allowed deviation (both earlier and later) for each arrival and departure time on the service's weekly schedule, relative to the time specified in the corresponding leg of the input VesselService. For an original weekly schedule time T (e.g., Wednesday 10:00), a maximum_schedule_time_deviation of D means the event in the optimized schedule must occur within the time interval [T - D, T + D] (modulo one week).

Example: If the original time is Wednesday 08:00 and maximum_schedule_time_deviation is { hours: 24 }, the new time must be between Tuesday 08:00 and Thursday 08:00 inclusive.

If this field is not set, the schedule is fully flexible, even though the port sequence is fixed. The deviation duration value must be non-negative and less than one week (168 hours).

VesselServiceLeg

A single leg of a vessel service.

Fields
leg_candidate_id

string

Assigned leg candidate ID.
origin_departure_time

ScheduleTime

Time of departure at the origin port on the weekly schedule.
destination_arrival_time

ScheduleTime

Time of arrival at the destination port on the weekly schedule.