Samplers
QUBODrivers includes four utility samplers. They are intentionally simple: their main role is to exercise the interface, provide small-instance baselines, and make examples runnable without external services or fixed solver choices.
| Sampler | Purpose | Main result behavior |
|---|---|---|
ExactSampler.Optimizer | Exhaustive enumeration for small models | returns every state |
RandomSampler.Optimizer | Random baseline and smoke tests | returns num_reads random states |
IdentitySampler.Optimizer | Warm-start and conversion checks | returns the provided start state |
MIPSampler.Optimizer | Exact MIP-backed baseline using a user-supplied MOI optimizer | returns at most one best incumbent and preserves MIP objective bounds |
Exact Sampler
Use ExactSampler to validate small problem formulations or compare another sampler against a known complete set of states. The cost grows exponentially with the number of variables.
using JuMP
using QUBODrivers
model = Model(ExactSampler.Optimizer)
@variable(model, x[1:2], Bin)
@objective(model, Min, -x[1] - 2x[2] + 3x[1] * x[2])
optimize!(model)
result_count(model)4QUBODrivers.ExactSampler.Optimizer — Type
ExactSampler.Optimizer{T}This sampler performs an exhaustive search over all $2^{n}$ possible states. It is useful as a correctness oracle for small QUBO and Ising models.
Due to the exponentially large number of visited states, this sampler is intended only for small instances.
ExactSampler ignores QUBODrivers.FinalNumberOfReads; it always returns the full exhaustive sample set. A completed solve exposes MOI.OPTIMAL through MOI.TerminationStatus(). Post-sample transformations do not retain that certificate; annotation-only callbacks preserve it.
Random Sampler
Use RandomSampler as a cheap stochastic baseline. Set "num_reads" to control how many states are sampled and "seed" for reproducible examples.
using JuMP
using QUBODrivers
model = Model(RandomSampler.Optimizer)
set_optimizer_attribute(model, "num_reads", 4)
set_optimizer_attribute(model, "seed", 1)
@variable(model, x[1:3], Bin)
@objective(model, Min, x[1] + x[2] - x[3])
optimize!(model)
result_count(model)3QUBODrivers.RandomSampler.Optimizer — Type
RandomSampler.Optimizer{T}Sampler that evaluates uniformly random states.
RandomSampler is a lightweight baseline for smoke tests, examples, and benchmark harnesses. It samples independent states in the model domain, evaluates their objective values with QUBOTools, and returns the final sampled states.
Attributes
QUBODrivers.RandomSeed,"seed": Random seed to initialize the random number generator.NumberOfReads,"num_reads": Default final read count.QUBODrivers.FinalNumberOfReads,"final_num_reads": Number of random states emitted in the returned sample set. If unset, this defaults toNumberOfReads.RandomGenerator,"rng": Random Number Generator instance.
Identity Sampler
Use IdentitySampler when the requested result is the warm-start vector itself. It is useful in tests for objective evaluation, fixed variable handling, and model conversion.
using QUBODrivers
MOI = QUBODrivers.MOI
model = MOI.instantiate(IdentitySampler.Optimizer; with_bridge_type = Float64)
x, _ = MOI.add_constrained_variables(model, fill(MOI.ZeroOne(), 3))
for (xi, start) in zip(x, [1.0, 0.0, 1.0])
MOI.set(model, MOI.VariablePrimalStart(), xi, start)
end
objective = MOI.ScalarAffineFunction{Float64}(
MOI.ScalarAffineTerm{Float64}[
MOI.ScalarAffineTerm{Float64}(1.0, x[1]),
MOI.ScalarAffineTerm{Float64}(2.0, x[2]),
MOI.ScalarAffineTerm{Float64}(3.0, x[3]),
],
0.0,
)
MOI.set(model, MOI.ObjectiveSense(), MOI.MIN_SENSE)
MOI.set(model, MOI.ObjectiveFunction{typeof(objective)}(), objective)
MOI.optimize!(model)
(
round.(Int, MOI.get.(model, MOI.VariablePrimal(1), x)),
MOI.get(model, MOI.ObjectiveValue(1)),
)([1, 0, 1], 4.0)QUBODrivers.IdentitySampler.Optimizer — Type
IdentitySampler.Optimizer{T}This sampler selects precisely the state vector provided as warm-start. Use it to check model conversion, objective evaluation, fixed variables, and warm-start plumbing without invoking a stochastic or external backend.
Every variable must have a valid MOI.VariablePrimalStart value before optimization.
IdentitySampler ignores QUBODrivers.FinalNumberOfReads; it always returns the single warm-start state.
MIP Sampler
Use MIPSampler as an exact correctness baseline for small and medium QUBO instances when you want to choose the MIP backend yourself. The sampler is implemented directly against MathOptInterface and does not depend on JuMP or on any concrete MIP solver package.
using JuMP
using QUBODrivers
using GLPK
model = Model(MIPSampler.Optimizer)
set_attribute(model, MIPSampler.MIPOptimizer(), GLPK.Optimizer)
@variable(model, x[1:3], Bin)
@objective(model, Min, x[1] + x[2] - 2x[1] * x[3])
optimize!(model)
value.(x)
objective_value(model)
objective_bound(model)When a time- or node-limited MIP solve stops early, MIPSampler preserves the backend's MOI.TerminationStatus() and MOI.ObjectiveBound() (translated to the caller's original objective sense, variable domain, scaling, constant offset, and fixed-variable conditioning) separately from any incumbent:
- Interrupted with an incumbent:
result_count(model) == 1andprimal_status(model) == MOI.FEASIBLE_POINT.objective_value(model)returns the rounded binary state's re-evaluated QUBO objective.objective_bound(model)andrelative_gap(model)return the backend-reported bound and relative gap when available, or throwMOI.GetAttributeNotAllowedif the backend did not report a finite value. - Interrupted without an incumbent:
result_count(model) == 0andprimal_status(model) == MOI.NO_SOLUTION.MIPSamplerreturns an emptySampleSet(with zero emitted reads and the consumed solve time) rather than throwing, so callers can still inspecttermination_status(model),solve_time(model), andobjective_bound(model)(when the backend reported a finite bound). Queryingobjective_value(model)orvalue.(x)throwsMOI.ResultIndexBoundsError, and queryingrelative_gap(model)throwsMOI.GetAttributeNotAllowed{MOI.RelativeGap}. - Numerical or backend failures: Unlike normal limit terminations, invalid numerical backend outputs (such as
NaNor unrepresentable bounds, inconsistentbound > incumbent, or out-of-range binary primals) and backend solve errors throw an exception fromoptimize!(model), clear any prior results (result_count(model) == 0,primal_status(model) == MOI.NO_SOLUTION), and settermination_status(model)toMOI.NUMERICAL_ERRORorMOI.OTHER_ERROR(or the backend's failure status).
using JuMP
using QUBODrivers
using QUBODrivers: QUBOTools
using GLPK
const MOI = JuMP.MOI
function solve_interrupted_qubo(stop_reason::Integer)
model = Model(MIPSampler.Optimizer)
set_silent(model)
set_attribute(
model,
MIPSampler.MIPOptimizer(),
() -> begin
opt = GLPK.Optimizer()
GLPK._set_callback(opt, cb_data -> begin
if GLPK.glp_ios_reason(cb_data.tree) == stop_reason
GLPK.glp_ios_terminate(cb_data.tree)
end
end)
return opt
end,
)
@variable(model, x[1:3], Bin)
@objective(
model,
Min,
-1.25 * (x[1] + x[2] + x[3]) + 2.0 * (x[1] * x[2] + x[2] * x[3] + x[1] * x[3]),
)
try
optimize!(model)
catch err
# Numerical validation or backend failure: prior results are cleared,
# and `termination_status(model)` reflects `MOI.NUMERICAL_ERROR` or `MOI.OTHER_ERROR`.
@warn "MIP solve failed" exception = err status = termination_status(model)
end
status = termination_status(model)
bound = try
objective_bound(model)
catch err
err isa MOI.GetAttributeNotAllowed ? nothing : rethrow()
end
raw_metadata = QUBOTools.metadata(QUBOTools.solution(unsafe_backend(model)))
if result_count(model) > 0
incumbent_val = objective_value(model)
incumbent_state = round.(Int, value.(x))
gap = try
relative_gap(model)
catch err
err isa MOI.GetAttributeNotAllowed ? nothing : rethrow()
end
return (;
status,
has_incumbent = true,
bound,
incumbent_val,
incumbent_state,
gap,
solve_time = solve_time(model),
bound_metadata = raw_metadata["bound"],
)
else
# Primal-free limit termination (`primal_status(model) == MOI.NO_SOLUTION`) or failed solve:
# `objective_value(model)` and `value.(x)` throw `MOI.ResultIndexBoundsError`, and
# `relative_gap(model)` throws `MOI.GetAttributeNotAllowed`, while `bound` and timing remain available.
return (;
status,
has_incumbent = false,
bound,
incumbent_val = nothing,
incumbent_state = nothing,
gap = nothing,
solve_time = solve_time(model),
bound_metadata = get(raw_metadata, "bound", nothing),
)
end
end
# 1. Interrupted at root branching before an integer incumbent is found (bound-only result):
bound_only = solve_interrupted_qubo(GLPK.GLP_IBRANCH)
# bound_only.status == MOI.INTERRUPTED, bound_only.has_incumbent == false, bound_only.bound == -1.875
# 2. Interrupted when the first integer incumbent is found (incumbent + bound result):
with_incumbent = solve_interrupted_qubo(GLPK.GLP_IBINGO)
# with_incumbent.status == MOI.INTERRUPTED, with_incumbent.has_incumbent == true,
# with_incumbent.incumbent_val == -1.25, with_incumbent.bound == -1.25Bounds and relative gaps exposed by MIPSampler are backend-reported, tolerance-dependent quantities for the supplied QUBO/Ising model (possibly conditioned on fixed variables), not independently verified exact-arithmetic certificates. A bound on a penalized QUBO relaxation is not automatically a bound on an original constrained formulation.
Internally, MIPSampler linearizes binary products with auxiliary variables and the standard Fortet/McCormick inequalities. The reformulation is a baseline route, not a replacement for specialized large-scale QUBO heuristics. For a broader discussion of efficient binary polynomial reformulations, see Elloumi, Sourour, and Verchere, "Efficient linear reformulations for binary polynomial optimization problems", Computers & Operations Research 155 (2023), 106240.
QUBODrivers.MIPSampler.Optimizer — Type
MIPSampler.Optimizer{T}MOI-native exact baseline that linearizes a QUBO into a binary mixed-integer linear model and solves it with a user-supplied MOI optimizer.
MIPSampler does not depend on any concrete MIP solver. Set MIPOptimizer to a compatible optimizer factory, such as HiGHS.Optimizer, GLPK.Optimizer, or MOI.OptimizerWithAttributes(HiGHS.Optimizer, MOI.Silent() => true).
The sampler introduces one binary auxiliary variable for each off-diagonal quadratic term and enforces the product relation with the standard Fortet/McCormick inequalities. This follows the usual linear reformulation route for binary polynomial optimization; see also Elloumi, Sourour, and Verchere, "Efficient linear reformulations for binary polynomial optimization problems", Computers & Operations Research 155 (2023), 106240.
At most one best incumbent sample is returned, with its binary state rounded and independently re-evaluated on the full QUBO objective. MIPSampler ignores QUBODrivers.FinalNumberOfReads.
Objective Bounds, Gaps, and Limit Terminations
- Objective bounds and gaps (
MOI.ObjectiveBound,MOI.RelativeGap): When the MIP backend reports a finite objective bound,MIPSamplertranslates it back to the caller's original objective sense (MOI.MIN_SENSEorMOI.MAX_SENSE), variable domain (MOI.ZeroOneorQUBODrivers.Spin), scaling, constant offset, and fixed-variable (MOI.EqualTo) conditioning, and exposes it viaMOI.ObjectiveBound()as well asmetadata["objective_bound"]andmetadata["bound"]. If no finite objective bound is available for the current solve state,MOI.get(model, MOI.ObjectiveBound())throwsMOI.GetAttributeNotAllowed{MOI.ObjectiveBound}. - Scope: The bound applies to the supplied QUBO/Ising objective, possibly conditioned on any fixed variables in the model. A bound on a penalized QUBO relaxation is not automatically a valid bound on an original constrained problem unless the penalty parameter has been independently certified.
- Numerical provenance: Bounds and relative gaps are backend-reported, tolerance-dependent quantities, not exact-arithmetic certificates. Do not treat them as exact proofs in certified preprocessing without a separate verification layer, and do not infer global optimality from a small observed gap when
MOI.TerminationStatus()is notMOI.OPTIMAL. Effective gap tolerances inmetadata["bound"]are recorded only when confirmed by backend readback or attribute forwarding; requested sampler settings are stored separately underrequested_relative_gap_toleranceandrequested_absolute_gap_tolerance. - Relative gap: When an incumbent and a bound are both present and the backend reports a finite
MOI.RelativeGap(),MIPSamplerexposes that solver-dependent value throughMOI.RelativeGap()andmetadata["relative_gap"](labeled"backend_solver_dependent"inmetadata["bound"]["relative_gap_definition"]). It is not interchangeable with a gap recomputed from the rounded incumbent, and when no finite gap is available (including primal-free results or backends that returnNaN/Inf),MOI.get(model, MOI.RelativeGap())throwsMOI.GetAttributeNotAllowed{MOI.RelativeGap}. - Primal-free limit terminations vs. failures: If the backend stops on a normal limit or interruption (
MOI.TIME_LIMIT,MOI.NODE_LIMIT,MOI.ITERATION_LIMIT,MOI.SOLUTION_LIMIT,MOI.MEMORY_LIMIT,MOI.OBJECTIVE_LIMIT,MOI.NORM_LIMIT,MOI.OTHER_LIMIT, orMOI.INTERRUPTED) without a feasible incumbent,MIPSamplerreturns an emptySampleSet(MOI.ResultCount() == 0,MOI.PrimalStatus() == MOI.NO_SOLUTION) while preservingMOI.TerminationStatus(),MOI.ObjectiveBound()(when available), and solve timing metadata. Conversely, numerical validation failures (NaNor unrepresentable bounds/objectives/gaps, inconsistentbound > incumbent, invalid primal values) and backend solve errors throw an exception fromMOI.optimize!, clear any prior results (MOI.ResultCount() == 0,MOI.PrimalStatus() == MOI.NO_SOLUTION), and setMOI.TerminationStatus()toMOI.NUMERICAL_ERRORorMOI.OTHER_ERROR(or the backend's failure status).
Attributes
MIPOptimizer,"mip_optimizer": MOI-compatible optimizer factory used to solve the generated binary MIP.
QUBODrivers.MIPSampler.MIPOptimizer — Type
MIPOptimizer()Optimizer attribute that stores the MOI-compatible MIP backend factory used by MIPSampler.Optimizer.
External Sampler Packages
Several JuliaQUBO packages implement the same sampler interface for external libraries, heuristics, or services. Their source can be useful when building a new wrapper.
This table is the reviewed source of truth for public external sampler packages. When a new JuliaQUBO or SECQUOIA driver package is ready for users, open a QUBODrivers documentation PR that adds its package URL, solver type, and source file path.
| Project | Solver | Source Code |
|---|---|---|
| DWave.jl | DWave.Optimizer | src/sampler.jl |
| DWave.jl | DWave.Neal.Optimizer | src/neal/sampler.jl |
| DWave.jl | DWave.Tabu.Optimizer | src/tabu/sampler.jl |
| DWave.jl | DWave.Greedy.Optimizer | src/greedy/sampler.jl |
| DWave.jl | DWave.Random.Optimizer | src/random/sampler.jl |
| QiskitOpt.jl | QiskitOpt.QAOA.Optimizer | src/QAOA.jl |
| QiskitOpt.jl | QiskitOpt.VQE.Optimizer | src/VQE.jl |
| PySA.jl | PySA.Optimizer | src/PySA.jl |
| MQLib.jl | MQLib.Optimizer | src/MQLib.jl |
| QUBODecomposition.jl | QUBODecomposition.Optimizer | src/optimizer.jl |
| CIMOptimizer.jl | CIMOptimizer.Optimizer | src/CIMOptimizer.jl |
| QuantumAnnealingInterface.jl | QuantumAnnealingInterface.Optimizer | src/QuantumAnnealingInterface.jl |
QUBODecomposition
QUBODecomposition is a standalone composite optimizer configured with a user-supplied child optimizer factory and an explicit free logical-variable budget, max_variables, including isolated variables. It dispatches fitting models whole, solves fitting disconnected components, and uses conditioned serial neighborhood sweeps for oversized connected components under the default :components_then_sweeps strategy. Sweeps return heuristic incumbents; exact child solves do not certify a coupled global optimum. Strict :whole_model and :components strategies reject oversized nonconstant inputs or components.
As of October 8, 2026, the package is under development, with no published release or General registration verified. Use its canonical development manual for source-based installation, configuration, algorithms and released ToQUBO 0.7.1 integration. See also Public composition pattern, Composite accounting, and Composite conformance evidence. QUBODrivers does not depend on this external package.
Optional External Sampler Designs
Before a new provider or hardware-SDK sampler package has a standalone repository, its public driver contract, model/sample mapping, and executable credential-free conformance prototype are maintained in QUBODrivers.jl without adding vendor SDK dependencies to core packages:
- Optional CUDA-Q QAOA Sampler Design (
CUDAQOpt.jldesign contract andexamples/cudaq_qaoa_prototype.jlreference prototype, tracked underJuliaQUBO/QUBODrivers.jl#88). - Optional TKET / Quantinuum Nexus Sampler Design (
TKETOpt.jldesign contract andexamples/tket_nexus_prototype.jlreference prototype, tracked underJuliaQUBO/QUBODrivers.jl#89).