Package google.research.optimization.v1

Index

• Optimization (interface)
• DesignShippingNetworkRequest (message)
• DesignShippingNetworkResponse (message)
• SolveMathOptModelRequest (message)
• SolveMathOptModelResponse (message)
• SolveShiftGenerationRequest (message)
• SolveShiftGenerationResponse (message)
• SolveShiftSchedulingRequest (message)
• SolveShiftSchedulingResponse (message)

Optimization

A One Platform API exposing a set of optimization solvers for high-level operations research problems. MOE:begin_strip

DesignShippingNetwork

rpc DesignShippingNetwork(DesignShippingNetworkRequest) returns (DesignShippingNetworkResponse) Solves the liner shipping network design and scheduling problem (LSNDSP) from the given DesignShippingNetworkRequest. The LSNDSP is a complex optimization problem that seeks to find the optimal design and scheduling of a liner shipping network. The goal is to minimize the total cost of operating the network, while meeting as much of the cargo demand between ports as possible. The LSNDSP can be broken down into two main subproblems: network design and scheduling. The network design subproblem determines the set of ports to be served by the network, the number of vessels to be deployed on each route, and the routes that the vessels will take. The scheduling subproblem determines the sailing schedules for the vessels, taking into account the time it takes to sail between ports, the time it takes to load and unload cargo, and the demand for cargo transportation between ports. In simple words, the LSNDSP is the problem of deciding which ports to serve, how many ships to use, and how to schedule the ships so that the cost of operating the network is minimized while maximizing the revenue for fulfilling cargo demand. A challenging subcomponent of the LSNDSP is the cargo routing, which determines which demands to meet and which routes to assign to cargo in order to maximize revenue.

SolveMathOptModel
rpc SolveMathOptModel(SolveMathOptModelRequest) returns (SolveMathOptModelResponse) Solves the input model and returns the result at once. Use this when you don't need callbacks, incrementality and don't need to track the progress of a solve.

SolveShiftGeneration
rpc SolveShiftGeneration(SolveShiftGenerationRequest) returns (SolveShiftGenerationResponse) Solves a shift generation problem from the given SolveShiftGenerationRequest by generating shifts from given shift templates in order to cover the employee demand.

SolveShiftScheduling
rpc SolveShiftScheduling(SolveShiftSchedulingRequest) returns (SolveShiftSchedulingResponse) Solves a fixed shift scheduling problem from the given SolveShiftSchedulingRequest by assigning employees to shifts such that employees' scheduling preferences are maximized and scheduling constraint violations are minimized.

DesignShippingNetworkRequest

The request holds an instance of the LSNDSP and must contain a set of ports, a set of leg candidates, a set of vessel classes and a set of commodity demands to fulfill.

Fields
request_id	string Problem or request ID.
solver_parameters	SolverParameters Parameters for the solver.
ports[]	Port List of possible ports to be called in vessel services. The request must only contain port IDs that are in this list.
leg_candidates[]	LegCandidate List of potential leg candidates to be added to vessel services. The request must only contain leg candidate IDs that are in this list.
vessel_classes[]	VesselClass List of vessel classes to perform vessel services. Note that all vessels from the same class are completely interchangeable. The request must only contain vessel class IDs that are in this list.
commodity_demands[]	CommodityDemand List of potential commodity (i.e. container) demands to be fulfilled by vessel services.
vessel_services[]	VesselService A network of valid vessel services (typically the current state of the network) can be provided to be used as a starting point for the optimization.

DesignShippingNetworkResponse

The response holds the solution to the LSNDSP instance passed in the request. It contains a valid network of vessel services and commodity demand paths. The total commodity demand going through each leg cannot exceed the vessel class capacity serving this leg. Note that having no vessel services with no fulfilled demand is always a feasible solution to the liner shipping network design and scheduling problem.

Fields
request_id	string The ID of the request that this response is associated with.
vessel_services[]	VesselService Network of vessel services. For each vessel class, the total number of vessels used cannot exceed the available number of vessels for this class.
commodity_demand_paths[]	CommodityDemandPath List of all commodity demand paths through which positive commodity demand are shipped. Note that some commodity demand IDs might not be included if no demand is shipped. Alternatively, a commodity demand can be partially fulfilled. For each commodity demand, the total fulfilled quantity cannot exceed the total demand. Finally, commodity_demand_paths depend on vessel_services (see CommodityDemandPath definition).

SolveMathOptModelRequest

Request for a unary remote solve in MathOpt.

Fields
solver_type	SolverTypeProto Optional. Solver type to numerically solve the problem. Note that if a solver does not support a specific feature in the model, the optimization procedure won't be successful.
model	ModelProto Required. A mathematical representation of the optimization problem to solve.
parameters	SolveParametersProto Optional. Parameters to control a single solve. The enable_output parameter is handled specifically. For solvers that support messages callbacks, setting it to true will have the server register a message callback. The resulting messages will be returned in SolveMathOptModelResponse.messages. For other solvers, setting enable_output to true will result in an error.
model_parameters	ModelSolveParametersProto Optional. Parameters to control a single solve that are specific to the input model (see SolveParametersProto for model independent parameters).

SolveMathOptModelResponse

Response for a unary remote solve in MathOpt.

Fields
result	SolveResultProto Description of the output of solving the model in the request.
messages[]	string If SolveParametersProto.enable_output has been used, this will contain log messages for solvers that support message callbacks.

SolveShiftGenerationRequest

Request for solving the Shift Generation problem. Rules for generating shifts are outlined in each ShiftTemplate. Multiple shifts in the response can be generated from a single ShiftTemplate. The shifts generated and selected by the solver must adhere to the rules outlined in the ShiftTemplate and cover the specified employee demand.

Fields
solver_config	SolverConfig Optional. Parameters for the solver.
shift_templates[]	ShiftTemplate Required. Set of shift templates specifying rules for generating shifts.
employee_demands[]	EmployeeDemand Required. Total employee demand that the shifts generated by shift_templates need to cover. The DateTime intervals specified in each EmployeeDemand must be disjoint and may be nonadjacent.

SolveShiftGenerationResponse

Response for the Shift Generation problem. If the solution_status returned is SOLVED, then a set of valid shifts generated by the solver are returned in employee_schedules. For a valid shift schedule, the following properties hold:

1. Each shift generated in employee_schedules adheres to the rules specified in the corresponding ShiftTemplate.
2. Each event selected in each shift adheres to the rules specified in the corresponding ShiftTemplate.Event.
3. The total number of employees assigned to the set of shifts generated from the same ShiftTemplate does not exceed maximum_employee_count of that template.
4. The set of assigned employees cover the demand at every given interval.

Fields
solution_status	ShiftGenerationSolutionStatus Status of the returned solution. If solution_status is not SOLVED, employee_schedules will be empty.
employee_schedules[]	EmployeeSchedule Set of shifts generated by the solver along with the number of employees assigned to each schedule.

SolveShiftSchedulingRequest

Request for the workforce scheduling API. At a minimum, the request specifies a set of employees, a set of shifts, a set of possible roles that an employee can perform, and a set of coverage requirements. The coverage requirements specify, over a time window, the number of employees needed to fulfill each role. Employees assigned to a shift are also assigned to one (and only one) role for that shift, and employees cannot be assigned to two overlapping shifts. See the SolveShiftSchedulingResponse below for more details on what makes a shift assignment valid.

Additional scheduling constraints can be specified for each employee to further constrain the problem. All scheduling constraints and coverage requirements are given a priority level (MANDATORY, HIGH, MEDIUM, LOW). All constraints with priority level PRIORITY_MANDATORY must be satisfied by the solver. Constraints with any other priority can be violated by the solver, but these violations are minimized in the priority order. See the Priority enum for more details on how the priority levels for each constraint are handled.

The solver will try to maximize the ShiftPreference.preference values for each Employee over the given constraints. The solver will not violate a constraint in order to satisfy more preferences; it will only violate a constraint if the scheduling assignment is infeasible under the given constraints.

Note about time: All times in the problem are specified using the DateTime message. This message includes a TimeZone field. The TimeZone is assumed to be UTC unless specified otherwise by the user. DateTime messages should only be specified down to the minutes; all seconds and nanos are ignored.

Fields
request_id	string Problem or request ID.
solve_parameters	SolveParameters Parameters to control a single solve of the problem.
employees[]	Employee All available employees to be scheduled.
shifts[]	Shift All shifts to form the schedule.
coverage_requirements[]	CoverageRequirement Coverage requirements for the entire planning horizon. These specify the number of employees that must perform each role, or possess a skill, during either a time window or a list of shift IDs. All coverage requirements must be specified with either time windows or a list of shift IDs (but not both). Time windows (if given) for the coverage requirements cannot overlap for each given location. The default priority level for each of these constraints is PRIORITY_MANDATORY for the role requirements and PRIORITY_LOW for the skill requirements. See the Priority enum for more details.
role_ids[]	string List of all possible roles across the workforce. Each employee must have at least one role that they can be assigned to for a shift. A Role refers to a specific job assignment during a shift (i.e. registered nurse, executive chef, waiter, etc). When an employee is assigned to a shift, they are also assigned to a single specific role.
skill_ids[]	string List of all possible skills across the workforce. A Skill refers to any extra qualifications an employee may have that do not pertain to a specific assignable job (i.e. certifications, languages spoken, etc). This list can be empty. When an employee is assigned to a shift, they must fulfill all skills needed for that shift.
location_ids[]	string List of all possible locations for the set of shifts in the schedule. This list can be empty. Specifying different locations can be useful when, for example, a nurse manager wants to schedule many nurses across different units at a hospital or, for another example, a hotel manager wants to schedule employees across multiple hotels.
budget_requirements[]	BudgetRequirement Budget specification for the scheduling problem. The default priority level for each of these requirements is PRIORITY_LOW. See the Priority enum for more details.
assignments_hint[]	ShiftAssignment Shift assignments to use as a tentative solution (a.k.a. solution hint) to the scheduling problem. Assignment hints are ignored if the assignment contradicts a nonassignable shift or a scheduling request.

SolveShiftSchedulingResponse

Response for the workforce scheduling API. For each response, the shift_assignments will be empty if the solution_status returned is NOT_SOLVED_DEADLINE_EXCEEDED or INFEASIBLE. If the solution_status returned is OPTIMAL or FEASIBLE, then a valid shift assignment is returned in shift_assignments. For a valid shift assignment, the following properties hold:

1. Each employee ID is contained in the set of employees given in the request.
2. Each role ID assigned to the employee is contained in the set of role IDs for the given employee.
3. Each shift ID is contained in the set of shifts given in the request.
4. Each shift ID is not one of the nonassignable shift IDs for the given employee.
5. An employee will never be assigned to two overlapping shifts.
6. For the given schedule, none of the constraints or requests with priority level PRIORITY_MANDATORY are violated.

Fields
request_id	string The ID of the request that this response is associated with.
solution_status	SolutionStatus Status of the returned solution. If the solution is not FEASIBLE or OPTIMAL, other fields in this proto may be empty. If the status is NOT_SOLVED_DEADLINE_EXCEEDED, the time limit was reached without finding a feasible solution or determining if a feasible solution exists. Requests may be infeasible if the constraints of priority level MANDATORY cannot all be satisfied.
shift_assignments[]	ShiftAssignment List of all assignments. Each ShiftAssignment specifies an employee, the shift they are assigned to, and the role they are assigned to perform for that shift.
status_message	string If solution_status is not optimal, this field may contain additional information about the solver.