gRPC Routing Client API Reference#

Import path: cuopt.grpc.routing.

Client#

class cuopt.grpc.routing.RoutingClient#

Client for solving VRP problems on a remote cuOpt gRPC server.

Methods

`cancel`(self, str job_id)	Request cancellation of a queued or running job.
`delete`(self, str job_id)	Delete a job's server-side result; raise `RoutingSolveError` on failure.
`result`(self, str job_id)	Fetch and parse the routing solution for a completed job.
`solve`(self, data_model[, settings])	Submit, wait, and return the solution (the common path).
`status`(self, str job_id)	Return the current job status without blocking.
`submit`(self, data_model[, settings])	Serialize and submit a VRP problem; return its `job_id`.
`wait`(self, str job_id, int timeout=0)	Block until the job finishes; return the terminal status int.

cancel(self, str job_id) → None#

Request cancellation of a queued or running job.

The job moves to CANCELLED. Call delete() to release its server-side state.

Parameters:

job_idstr: Id returned by submit().

Returns:

None

Raises:

RoutingSolveError: If the cancel RPC fails, including when job_id is unknown.

delete(self, str job_id)#: Delete a job’s server-side result; raise RoutingSolveError on failure.

result(self, str job_id)#

Fetch and parse the routing solution for a completed job.

Returns None if the job is still in flight (mirrors the LP client).

solve( self, data_model, settings=None, *, int timeout=0, bool delete=True, )#: Submit, wait, and return the solution (the common path).

status(self, str job_id) → JobStatus#

Return the current job status without blocking.

Parameters:

job_idstr: Id returned by submit().

Returns:

JobStatus: A JobStatus member (QUEUED, PROCESSING, COMPLETED, FAILED, CANCELLED, or NOT_FOUND).

Raises:

RoutingSolveError: If the status RPC itself fails (transport error).

submit(self, data_model, settings=None)#: Serialize and submit a VRP problem; return its job_id.

wait(self, str job_id, int timeout=0)#

Block until the job finishes; return the terminal status int.

Raises RoutingSolveError if the wait itself fails (e.g. transport error or unknown job), mirroring the LP/MILP client.

Polls job status from Python so the GIL is released between short status RPCs. timeout == 0 waits indefinitely; negative values raise RoutingSolveError. Each status poll is a unary RPC with a separate 60-second hang deadline.

Supporting Types#

class cuopt.grpc.routing.JobStatus(*values)

QUEUED = 0

PROCESSING = 1

COMPLETED = 2

FAILED = 3

CANCELLED = 4

NOT_FOUND = 5

Exceptions#

exception cuopt.grpc.routing.RoutingSolveError#

Bases: RuntimeError

A remote VRP job failed or returned no routing solution.

Settings#

settings accepts a dict or a cuopt.routing.SolverSettings. time_limit, verbose_mode (a dict may use verbose), and error_logging are forwarded to the remote solve. dump_best_results is not forwarded: the solver would write that file on the server. dump_config_file is not forwarded either. Local cuopt.routing.Solve() writes that YAML in the calling process after the solve; the remote solve does not. Any other dict key is silently ignored.

Solution Fields#

result() returns None while the job is still queued or running. Once a solution is available, it returns a dict read from the routing solution message. solve() returns that dict when the job completes, and raises RoutingSolveError otherwise. Route data is one NumPy array per field, with one entry per stop.

Key	Description
`status`	`0` success, `1` infeasible, `2` timeout, `3` empty, `4` error.
`status_message`	Solver status text, such as `Success`.
`error_message`	Set when `status` is `4`. Empty otherwise.
`solve_time`	Seconds spent in the routing solver on the server.
`vehicle_count`	Number of vehicles used.
`total_objective_value`	Overall cost.
`objective_values`	`dict` of objective id to cost.
`route`, `truck_id`, `locations`, `node_types`	Per-stop integer arrays.
`arrival_stamp`	Per-stop arrival times.
`unserviced_nodes`	Orders that cannot be served.
`accepted`	Orders accepted, for prize-collection problems.