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.

SamplerPurposeMain result behavior
ExactSampler.OptimizerExhaustive enumeration for small modelsreturns every state
RandomSampler.OptimizerRandom baseline and smoke testsreturns num_reads random states
IdentitySampler.OptimizerWarm-start and conversion checksreturns the provided start state
MIPSampler.OptimizerExact MIP-backed baseline using a user-supplied MOI optimizerreturns 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)
4
QUBODrivers.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.

Warn

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.

source

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)
3
QUBODrivers.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 to NumberOfReads.
  • RandomGenerator, "rng": Random Number Generator instance.
source

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.

source

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) == 1 and primal_status(model) == MOI.FEASIBLE_POINT. objective_value(model) returns the rounded binary state's re-evaluated QUBO objective. objective_bound(model) and relative_gap(model) return the backend-reported bound and relative gap when available, or throw MOI.GetAttributeNotAllowed if the backend did not report a finite value.
  • Interrupted without an incumbent: result_count(model) == 0 and primal_status(model) == MOI.NO_SOLUTION. MIPSampler returns an empty SampleSet (with zero emitted reads and the consumed solve time) rather than throwing, so callers can still inspect termination_status(model), solve_time(model), and objective_bound(model) (when the backend reported a finite bound). Querying objective_value(model) or value.(x) throws MOI.ResultIndexBoundsError, and querying relative_gap(model) throws MOI.GetAttributeNotAllowed{MOI.RelativeGap}.
  • Numerical or backend failures: Unlike normal limit terminations, invalid numerical backend outputs (such as NaN or unrepresentable bounds, inconsistent bound > incumbent, or out-of-range binary primals) and backend solve errors throw an exception from optimize!(model), clear any prior results (result_count(model) == 0, primal_status(model) == MOI.NO_SOLUTION), and set termination_status(model) to MOI.NUMERICAL_ERROR or MOI.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.25
Bound Scope and Numerical Provenance

Bounds 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, MIPSampler translates it back to the caller's original objective sense (MOI.MIN_SENSE or MOI.MAX_SENSE), variable domain (MOI.ZeroOne or QUBODrivers.Spin), scaling, constant offset, and fixed-variable (MOI.EqualTo) conditioning, and exposes it via MOI.ObjectiveBound() as well as metadata["objective_bound"] and metadata["bound"]. If no finite objective bound is available for the current solve state, MOI.get(model, MOI.ObjectiveBound()) throws MOI.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 not MOI.OPTIMAL. Effective gap tolerances in metadata["bound"] are recorded only when confirmed by backend readback or attribute forwarding; requested sampler settings are stored separately under requested_relative_gap_tolerance and requested_absolute_gap_tolerance.
  • Relative gap: When an incumbent and a bound are both present and the backend reports a finite MOI.RelativeGap(), MIPSampler exposes that solver-dependent value through MOI.RelativeGap() and metadata["relative_gap"] (labeled "backend_solver_dependent" in metadata["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 return NaN/Inf), MOI.get(model, MOI.RelativeGap()) throws MOI.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, or MOI.INTERRUPTED) without a feasible incumbent, MIPSampler returns an empty SampleSet (MOI.ResultCount() == 0, MOI.PrimalStatus() == MOI.NO_SOLUTION) while preserving MOI.TerminationStatus(), MOI.ObjectiveBound() (when available), and solve timing metadata. Conversely, numerical validation failures (NaN or unrepresentable bounds/objectives/gaps, inconsistent bound > incumbent, invalid primal values) and backend solve errors throw an exception from MOI.optimize!, clear any prior results (MOI.ResultCount() == 0, MOI.PrimalStatus() == MOI.NO_SOLUTION), and set MOI.TerminationStatus() to MOI.NUMERICAL_ERROR or MOI.OTHER_ERROR (or the backend's failure status).

Attributes

  • MIPOptimizer, "mip_optimizer": MOI-compatible optimizer factory used to solve the generated binary MIP.
source

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.

ProjectSolverSource Code
DWave.jlDWave.Optimizersrc/sampler.jl
DWave.jlDWave.Neal.Optimizersrc/neal/sampler.jl
DWave.jlDWave.Tabu.Optimizersrc/tabu/sampler.jl
DWave.jlDWave.Greedy.Optimizersrc/greedy/sampler.jl
DWave.jlDWave.Random.Optimizersrc/random/sampler.jl
QiskitOpt.jlQiskitOpt.QAOA.Optimizersrc/QAOA.jl
QiskitOpt.jlQiskitOpt.VQE.Optimizersrc/VQE.jl
PySA.jlPySA.Optimizersrc/PySA.jl
MQLib.jlMQLib.Optimizersrc/MQLib.jl
QUBODecomposition.jlQUBODecomposition.Optimizersrc/optimizer.jl
CIMOptimizer.jlCIMOptimizer.Optimizersrc/CIMOptimizer.jl
QuantumAnnealingInterface.jlQuantumAnnealingInterface.Optimizersrc/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: