Samplers

QUBODrivers includes three 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.

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

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)

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.

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)

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 NumberOfReads independent states in the model domain, evaluates their objective values with QUBOTools, and returns all sampled states.

Attributes

RandomSeed, "seed": Random seed to initialize the random number generator.
NumberOfReads, "num_reads": Number of random states sampled per run.
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.

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.

Project	Source Code
DWave.jl	DWave
DWaveNeal.jl	DWaveNeal
IsingSolvers.jl	GreedyDescent
	ILP
	MCMCRandom
QuantumAnnealingInterface.jl	QuantumAnnealingInterface
CIMOptimizer.jl	CIMOptimizer