gRPC API (Reference)#

The CuOptRemoteService gRPC API is defined in Protocol Buffers under the cuopt.remote package:

Download all five as cuopt-protos.zip. They import each other by file name, so keep them in one directory.

The libcuopt-client wheel and conda package install the same five files:

  • pip: <site-packages>/libcuopt_client/share/cuopt/proto

  • conda: $CONDA_PREFIX/share/cuopt/proto

Generate stubs for your language with that directory as the include path, for example for Python:

python -m grpc_tools.protoc -I "$PROTO_DIR" --python_out=. --grpc_python_out=. \
  "$PROTO_DIR"/*.proto

The same files are in the repository under cpp/src/grpc/, cpp/src/grpc/routing/ and cpp/src/grpc/codegen/generated/. The chunked-transfer wire format is described in GRPC_INTERFACE.md.

Most users do not call these RPCs directly:

  • Remote execution — Python, C (cuOptSolve), cuopt_cli, and modeling-language integrations that call those APIs forward LP, MIP, and QP solves when CUOPT_REMOTE_HOST and CUOPT_REMOTE_PORT are set (Quick Start, Advanced Configuration).

  • gRPC linear programming client — cuopt.grpc.linear_programming.Client for LP, MIP, and QP (gRPC Linear Programming Client).

  • gRPC routing client — cuopt.grpc.routing.RoutingClient for VRP, TSP, and PDP (gRPC Routing Client).

Custom clients call CuOptRemoteService over gRPC using these definitions. This page summarizes the service for custom integrators and debugging.

Service: CuOptRemoteService#

Asynchronous Jobs#

RPC

Purpose

SubmitJob

Submit an LP, MIP, or VRP job in one message (within gRPC message size limits; VRP is unary-only today, see gRPC Routing Client).

CheckStatus

Poll job status by job_id.

GetResult

Fetch a completed result (unary, when the payload fits one message).

DeleteResult

Cancel the job if it is still queued or running, then remove all server-side state for that job_id.

CancelJob

Cancel a queued or running job.

WaitForCompletion

Block until the job finishes (status only; use GetResult for the solution).

Chunked Upload (Large Problems)#

RPC

Purpose

StartChunkedUpload

Begin a session; send problem metadata and settings (arrays follow as chunks).

SendArrayChunk

Upload one slice of a numeric array field.

FinishChunkedUpload

Finalize the upload and return job_id (same as SubmitJob).

Chunked Download (Large Results)#

RPC

Purpose

StartChunkedDownload

Begin a download session; returns scalar result fields and array descriptors.

GetResultChunk

Fetch one chunk of a result array.

FinishChunkedDownload

End the download session and release server state.

Streaming and Callbacks#

RPC

Purpose

StreamLogs

Server-streaming solver log lines for a job.

GetIncumbents

MIP incumbent solutions since a given index (only if the job was submitted with enable_incumbents; otherwise the list is empty). enable_set_incumbent registers a server-side set-solution callback that echoes the last get-incumbent into the solver (disables presolve).

Messages and Constraints#

  • Problem types — Wire categories are LP/QP, MIP, or VRP. QP is submitted as lp_request (SolveLPRequest) with quadratic fields on OptimizationProblem. VRP rides the same SubmitJob/GetResult RPCs as LP/MIP, as a vrp_request payload typed by cpp/src/grpc/routing/cuopt_routing.proto (problem) and cuopt_routing_solution.proto (result) – not a separate service. There is no CUOPT_REMOTE_HOST/CUOPT_REMOTE_PORT remote-execution path for routing; use the gRPC routing client (gRPC Routing Client) or REST for remote routing.

  • Solver settings — Carried as PDLPSolverSettings or MIPSolverSettings inside the request or chunked header, aligned with the NVIDIA cuOpt solver options documentation.

  • Errors — Transport failures use gRPC status codes. Some outcomes use Status::OK with response fields: CheckStatus reports unknown jobs as job_status=NOT_FOUND; GetResult uses transport NOT_FOUND / UNAVAILABLE (not ready) and status=ERROR_SOLVE_FAILED for failed solves; DeleteResult / CancelJob report outcomes in the response. See cuopt_remote_service.proto.

Further Reading#