QUBO solver API reference

Import this surface from qpiai_opt.opt_solvers.qubo. The QUBO solver guide defines request fields, result semantics, lifecycle behavior, and failures. See the QUBO modelling guide for model construction and representation conventions.

from qpiai_opt.opt_solvers.qubo import QUBOSolver

Class: QUBOSolver

QUBOSolver(api_key: 'Optional[str]' = None, url: 'Optional[str]' = None, *, client: 'Optional[Client]' = None, experiment_id: 'Optional[str]' = None, experiment_name: 'Optional[str]' = None, compute_resource_id: 'Optional[str]' = None) -> 'None'

Solve QUBO problems through QpiAI Platform. Supply a Client or an api_key from your application's secret store; construction performs no HTTP request. url is the platform API root when constructing a client. When a client is supplied, an additional key or URL must match it or construction raises ValueError; another client type raises TypeError. Experiment ID/name and compute-resource ID establish solver defaults; call-level selections take precedence. Identifier and URL validation follows Client.

Public class attribute: DEFAULT_URL = "https://opt-server.qpiai.tech/api".

Methods and properties

Method: submit

submit(problem: 'Union[QUBOProblem, Dict]', timeout: 'float' = 1200.0, *, name: 'Optional[str]' = None, experiment_id: 'Optional[str]' = None, experiment_name: 'Optional[str]' = None, compute_resource_id: 'Optional[str]' = None) -> 'JobSubmissionResponse'

Validate a QUBOProblem or its Python field dictionary, create one problem record, and submit one potentially paid job without waiting. timeout is a positive finite per-request connection/read timeout, defaulting to 1200 seconds. name=None generates a UTC-labelled problem name; experiment ID/name override solver/client defaults and a supplied ID takes precedence. compute_resource_id=None uses the solver default or automatic platform selection. Return JobSubmissionResponse with normalized status and identifiers.

An empty normalized QUBO raises ValueError before HTTP. Invalid request fields raise pydantic.ValidationError; invalid identifiers/timing raise ValueError. Transport and platform failures propagate. A definitive non-transient 4xx submission rejection triggers best-effort deletion of the newly created problem. Ambiguous outcomes retain it for reconciliation; see submission failures.

Method: solve

solve(problem: Union[QUBOProblem, dict], *, poll_interval: float = 5.0, timeout: float = 5400.0, request_timeout: float | None = None, **submit_options) -> SolveResult

Submit once, wait for completion, retrieve output, and return a source-aware SolveResult. Pass the documented timing options by keyword. submit_options accepts name, experiment_id, experiment_name, and compute_resource_id; unknown arguments raise TypeError. poll_interval and timeout must be positive finite values; request_timeout=None uses the client's timeout. The blocking timing contract distinguishes the waiting budget from request timeouts. Failure, cancellation, and wait expiry raise JobFailedError, JobCancelledError, and TimeoutError; a timeout does not cancel the job.

Method: get_status

get_status(job_id: 'str', timeout: 'float' = 60.0) -> 'JobStatusResponse'

Return JobStatusResponse after reading one job. job_id follows the client's path-ID rules; timeout is a positive finite per-request timeout. Completed jobs include a parsed result and may require a storage download; other states contain no result. Cached source metadata is used when present. Result validation/restoration can fail even after the job reaches completed.

Method: get_result

get_result(job_id: 'str', timeout: 'float' = 60.0, *, problem: 'Optional[Union[QUBOProblem, Dict]]' = None) -> 'SolveResult'

Read the job and return its parsed SolveResult; a state other than completed raises RuntimeError. timeout is a positive finite per-request timeout. Optional problem accepts a QUBOProblem or field dictionary and takes precedence over solver-instance metadata, restoring source sense, offset, names, and model decoding. Pass the original problem when retrieving from another process; without it or cached metadata, the reported minimizing matrix objective cannot be restored to source coordinates. A mismatched source problem or malformed service result can raise RuntimeError, ValueError, or pydantic.ValidationError.

Method: get_solution

get_solution(job_id: 'Optional[str]' = None, result: 'Optional[SolveResult]' = None) -> 'List[int]'

Supply exactly one job_id or QUBO SolveResult; neither or both raises ValueError, and a different result type raises TypeError. A job ID calls get_result() with its default timeout; an existing result avoids HTTP. Return its list[int] solution in QUBO index order.

Method: health

health() -> 'bool'

Delegate to Client.health(): perform an authenticated account request with a five-second timeout and return bool. Request/API failure returns False; no problem or job is created.

Class: QUBOProblem

QUBOProblem(*, problem_type: Literal['QUBO'] = 'QUBO', num_variables: typing.Annotated[int, Strict(strict=True), Ge(ge=0)], matrix_format: Literal['symmetric', 'upper'] = 'symmetric', max_evaluations: typing.Annotated[int, Strict(strict=True), Gt(gt=0)] = 10000, sense: Literal['MIN', 'MAX'] = 'MIN', offset: float = 0.0, variable_names: Optional[Tuple[str, ...]] = None, qubo_dict: Dict[Tuple[int, int], float]) -> None

Validated QUBO problem for local or explicit platform execution. Its field contracts define count, coefficients, names, offset, direction, and platform evaluation budget. Unknown fields are forbidden. Boolean coefficients, offsets, counts, and indices are rejected. Upper input is converted immediately to symmetric half-coefficient storage; malformed mirrors, indices, names, or coefficient scale raise pydantic.ValidationError. Sense and problem marker are case-insensitive without whitespace stripping; matrix formats also strip whitespace and accept the documented aliases.

Fields: problem_type, num_variables, matrix_format, max_evaluations, sense, offset, variable_names, qubo_dict.

Methods and properties

Method: from_model

from_model(model, *, max_evaluations=10000, **compile_options)

Return QUBOProblem by compiling an algebraic Model and deep-copying its source/decoding state. The compiler's minimizing representation is converted into source coordinates, including MAX sense and offset. max_evaluations is the platform evaluation budget; compile_options accepts the public QUBO compilation controls except matrix_format, which this factory fixes to symmetric storage. The source model's compiled state is committed on success and restored on failure. Later model edits do not change this problem's snapshot. A different input type raises TypeError; compilation and request validation errors propagate.

Class: SolveResult

SolveResult(*, problem_class: Literal['QUBO'] = 'QUBO', execution_mode: Literal['local', 'platform'] = 'platform', job_id: str | None = None, problem_id: str | None = None, solver_time_s: typing.Annotated[float | None, Ge(ge=0)] = None, compute_time_s: typing.Annotated[float | None, Ge(ge=0)] = None, solve_info: qpiai_opt.opt_solvers.result_base.SolveInfo | None = None, num_nodes: typing.Annotated[int, Strict(strict=True), Ge(ge=0)], objective: float, variable_assignment: Dict[str, Union[int, float]], solution: List[int]) -> None

Completed QUBO result shared by local and platform execution. num_nodes is a strict nonnegative integer and solution must be a list/tuple of that length containing values equal to zero or one; construction normalizes bits to Python integers. objective is finite and non-Boolean. variable_assignment maps nonempty string names to finite non-Boolean numeric values, which may be decoded nonbinary source values. These validations do not independently prove feasibility or objective consistency. Unknown fields are forbidden; malformed data raise pydantic.ValidationError. See the common result contract for identity, timing, serialization, and guarantee semantics.

Fields: problem_class, execution_mode, job_id, problem_id, solver_time_s, compute_time_s, solve_info, num_nodes, objective, variable_assignment, solution.

Methods and properties

Method: runtime

runtime(unit: 'str' = 's', *, kind: 'str' = 'compute') -> 'float | None'

Return the compute or solver duration in seconds, milliseconds, or microseconds. kind="compute" is the default; unknown durations return None.

Method: info

info() -> 'SolveInfo'

Return the common provider, method, termination, feasibility, proof, guarantee, source-objective, transformation, and settings view.

Class: JobSubmissionResponse

JobSubmissionResponse(*, job_id: str, status: Literal['pending', 'running', 'completed', 'failed', 'cancelled', 'unknown'], message: str, problem_id: Optional[str] = None) -> None

Submission record. job_id, message, and a non-null problem_id are stripped nonempty strings. Status is stripped/lowercased and must be one of the six listed lifecycle literals. The record confirms submission rather than a mathematical solution; unknown fields or invalid values raise pydantic.ValidationError.

Fields: job_id, status, message, problem_id.

Class: JobStatusResponse

JobStatusResponse(*, job_id: str, status: Literal['pending', 'running', 'completed', 'failed', 'cancelled', 'unknown'], result: Optional[qpiai_opt.opt_solvers.qubo.models.SolveResult] = None, error: Optional[str] = None, submitted_at: Optional[str] = None, completed_at: Optional[str] = None, compute_time_s: Optional[float] = None, solver_time_s: Optional[float] = None) -> None

Lifecycle record. Job ID and non-null timestamp strings are stripped and nonempty; timestamps are strings rather than parsed datetime objects. Status is stripped/lowercased to a listed literal. A completed record must contain SolveResult; every other state must omit it or use None. error is optional text. Durations are optional finite nonnegative non-Boolean seconds. Unknown fields, invalid timing/text, or inconsistent result/state combinations raise pydantic.ValidationError.

Fields: job_id, status, result, error, submitted_at, completed_at, compute_time_s, solver_time_s.