Getting started

Installation

QpiAI Opt supports CPython 3.10–3.14 on Linux, macOS, and Windows.

python -m pip install qpiai-opt

The base install can solve LP, MILP, continuous QP, QUBO, HUBO, and Ising problems locally. Optional integrations are installed separately:

python -m pip install "qpiai-opt[quantum]"
python -m pip install "qpiai-opt[ommx]"
python -m pip install "qpiai-opt[all]"

The quantum extra installs the pinned qpiai-quantum==0.3.0 integration; ommx installs the OMMX bridge; all installs both. Gate-based optimization requires QCloud authentication. Obtain a free QCloud API key at QpiAI QCloud. Installing the extra does not change default solve routing. Optional packages follow their own wheel support. See package support.

Build a first model

Create variables, a model, an objective, and constraints. Variables are instances: use Continuous("x", 0, 10), not the Continuous class itself.

from qpiai_opt.opt_modeller import Continuous, Model

x = Continuous("x", 0, 4)
y = Continuous("y", 0, 3)

model = Model("production")
model.maximize(3 * x + 2 * y + 5)
model.add_constraint(x + y <= 5, label="capacity")

Inspect before solving

summary() is for people. classify() and inspect() return deterministic programmatic descriptions.

from qpiai_opt.opt_solvers import classify, inspect

human_summary = model.summary()
problem_class = classify(model)  # "LP"
report = inspect(model)
inspection_valid = report["valid"]

human_summary contains the objective, domains, and named constraints. inspection_valid is True for this valid small LP.

Solve locally

Local execution is the default and cannot consume platform credits. Register for a free Opt API key at QpiAI Opt and supply it through Client; each solve verifies it online before computing locally. The code below reads the key explicitly from the application's QPIAI_OPT_API_KEY environment variable. A disconnected or rejected verification stops execution. Inspection and modelling do not need credentials.

import os

from qpiai_opt.opt_solvers import Client, solve

client = Client(api_key=os.environ["QPIAI_OPT_API_KEY"])

result = solve(model, client=client)
result.problem_class  # "LP"
result.execution_mode  # "local"
result.status  # "optimal"
result.objective  # 19.0, including the source constant and MAX sense
result.solution  # {"x": 4.0, "y": 1.0}
result.compute_time_s  # default runtime unit
result.runtime("ms")  # explicit millisecond view
result.runtime("us")  # explicit microsecond view

info = result.info()
info.method  # "linear-programming"
info.termination  # "optimal"
info.guarantee  # "global_optimum"

Results identify the problem class and execution mode, with None job/problem IDs for local execution. Durations are stored in seconds; runtime() provides millisecond and microsecond views. The solve_info field serializes the method and guarantee returned by info(). See the result contract for all fields and timing definitions.

Running a job on platform

Supplying credentials alone does not submit work. Choosing platform mode does.

import os

from qpiai_opt.opt_solvers import Client, solve

client = Client(api_key=os.environ["QPIAI_OPT_API_KEY"])
platform_result = solve(model, mode="platform", client=client)

Selecting platform mode with an authenticated client authorizes submission. Continue with local and platform routing, then the completed result contract.