gRPC Linear Programming Client API Reference#

Import path: cuopt.grpc.linear_programming.

Client#

class cuopt.grpc.linear_programming.Client(str host, int port, tls=None, *)#

Methods

cancel(self, str job_id)

Request cancellation of a running job.

delete(self, str job_id)

Cancel job_id if it is still running, then delete it on the server and release its state.

incumbents(self, str job_id[, from_index])

Return incumbent solutions collected so far (or all remaining).

join_incumbent_stream(self, str job_id[, ...])

Wait for the background incumbent-stream thread started by start_incumbent_stream().

join_log_stream(self, str job_id[, timeout])

Wait for the background log-stream thread started by start_log_stream().

logs(self, str job_id[, from_byte])

Return all solver log lines for a job that has finished.

ping(self[, timeout_seconds])

Probe cuopt_grpc_server with a short CheckStatus RPC.

result(self, str job_id[, variable_names])

Fetch the solution for a completed job, or None if not ready.

start_incumbent_stream(self, str job_id, ...)

Poll for MIP incumbent solutions on a background thread until the job completes.

start_log_stream(self, str job_id[, ...])

Stream solver logs on a background thread until the job completes.

status(self, str job_id)

Return the current JobStatus for job_id without blocking.

submit(self, problem, SolverSettings settings)

Submit a problem for solving and return its job_id.

wait(self, str job_id[, timeout])

Block until job_id reaches a terminal state and return its JobStatus.
cancel(self, str job_id)#

Request cancellation of a running job. The job moves to JobStatus.CANCELLED; call delete() to release its state.

delete(self, str job_id)#

Cancel job_id if it is still running, then delete it on the server and release its state. Joins any client-side incumbent-stream thread for this job first. Call once you no longer need the job’s result or logs.

incumbents(self, str job_id, from_index=0)#

Return incumbent solutions collected so far (or all remaining).

Works while the job is running or after it completes. Each entry is a dict with index, objective, bound, and assignment (list of floats).

join_incumbent_stream(self, str job_id, timeout=None)#

Wait for the background incumbent-stream thread started by start_incumbent_stream().

join_log_stream(self, str job_id, timeout=None)#

Wait for the background log-stream thread started by start_log_stream().

Returns a dict when a thread was started for job_id, else None. Useful keys:

  • lines — list of log line strings collected so far

  • live_lines — count of lines received from the live stream thread

  • backfilled — True if the live stream received no lines and this method then called logs() as a client-side fallback to fill lines (and re-invoke the callback). That fetch is not destructive; the server keeps the log until delete().

Other keys in the dict are internal; do not rely on them.

logs(self, str job_id, from_byte=0)#

Return all solver log lines for a job that has finished.

Raises JobNotReadyError if the job is still queued or running. For live output during the solve, use start_log_stream().

ping(self, timeout_seconds=5)#

Probe cuopt_grpc_server with a short CheckStatus RPC.

Raises GrpcError if the server does not answer before timeout_seconds (default 5). Used by the HTTP proxy health endpoints so Kubernetes can restart a combined proxy+gRPC container.

result(self, str job_id, variable_names=None)#

Fetch the solution for a completed job, or None if not ready.

LP vs MIP is determined from the server response (via grpc_client_t::get_result). Pass variable_names (column order) to key solution.get_vars() by name. Raises GrpcError if the job failed or was cancelled.

start_incumbent_stream(
self,
str job_id,
settings,
from_index=0,
poll_interval_ms=1000,
)#

Poll for MIP incumbent solutions on a background thread until the job completes.

Pass settings with GetSolutionCallback instances registered via set_mip_callback() (same as local solve).

Call join_incumbent_stream() before delete().

start_log_stream(self, str job_id, callback=print, from_byte=0)#

Stream solver logs on a background thread until the job completes.

callback is invoked as callback(line, job_complete) for each line. Return False explicitly to stop early; other return values (including None from print) keep the stream open.

Call join_log_stream() before delete() to ensure all log lines were received. To collect lines in memory:

lines = []
client.start_log_stream(job_id, lines.append)
status(self, str job_id)#

Return the current JobStatus for job_id without blocking.

submit(
self,
problem,
SolverSettings settings,
enable_incumbents=None,
enable_set_incumbent=False,
)#

Submit a problem for solving and return its job_id.

problem is a Problem or DataModel. The job runs asynchronously; use wait() or status() to track it and result() to fetch the solution. Always delete() when done.

enable_incumbents defaults to None, which enables MIP incumbent collection when settings already has MIP callbacks. Pass True or False to override (used by the HTTP proxy, which has no local callback objects).

enable_set_incumbent registers the server-side MIP set-solution callback that echoes the last get-incumbent back into the solver (legacy incumbent_set_solutions). Default False.

wait(self, str job_id, timeout=None)#

Block until job_id reaches a terminal state and return its JobStatus.

timeout is in whole seconds. None or 0 waits indefinitely. Negative values raise GrpcError. Non-None values are converted with int(timeout) (so 0.5 becomes 0 and waits indefinitely). Positive timeouts poll about once per second and raise GrpcError if the deadline expires (they do not return a non-terminal JobStatus).

The wait loop runs in Python and only calls status() for each poll, so the GIL is released between checks. Concurrent start_incumbent_stream() and start_log_stream() threads can therefore make progress during the wait. Each status() call is a unary RPC with a separate 60-second hang deadline; a hung poll can therefore outlast a short timeout.

Supporting Types#

class cuopt.grpc.linear_programming.TlsConfig(root_certs=None, client_cert=None, client_key=None)#

TLS / mTLS settings for Client.

Each PEM argument may be PEM text or a path to a PEM file. For mTLS, pass both client_cert and client_key. When root_certs is omitted, the client uses the system/default CA trust store.

Attributes

client_cert

client_key

root_certs
client_cert#
client_key#
root_certs#
class cuopt.grpc.linear_programming.JobStatus(*values)#
QUEUED = 0#
PROCESSING = 1#
COMPLETED = 2#
FAILED = 3#
CANCELLED = 4#
NOT_FOUND = 5#

Exceptions#

exception cuopt.grpc.linear_programming.GrpcError#

Bases: RuntimeError

exception cuopt.grpc.linear_programming.JobNotReadyError#

Bases: GrpcError

See Also#