Python Async gRPC 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.

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, 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().

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)#

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.

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 waits indefinitely. 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).

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#