API Reference

QUBODrivers

Common MathOptInterface-compatible tools for QUBO and Ising samplers.

QUBODrivers provides:

• an AbstractSampler optimizer interface for QUBO-oriented solvers;
• the @setup macro for declaring sampler optimizers and attributes;
• built-in utility samplers in ExactSampler, RandomSampler, and IdentitySampler;
• result and model plumbing through MathOptInterface and QUBOTools;
• optional test and benchmark helpers for sampler implementations.

AbstractSampler{T} <: MOI.AbstractOptimizer

Abstract supertype for QUBODrivers sampler optimizers.

Concrete sampler optimizers are usually generated with QUBODrivers.@setup. They are MathOptInterface optimizers that accept QUBO or Ising models with binary or spin variables and return one or more sampled states through standard MOI result attributes.

The type parameter T is the numeric coefficient type used by the internal QUBOTools.Model.

sample(::AbstractSampler{T})::SampleSet{T} where {T}

Run the backend sampler and return a QUBOTools.SampleSet.

Sampler packages implement this method for their optimizer type. The method should read the model from the sampler, read any MOI or raw optimizer attributes it needs, call the backend, and return a SampleSet{T} whose samples use the same sense and domain as the backend output.

MOI.optimize! calls this method and attaches the returned sample set to the optimizer. If the returned metadata does not include a "time" dictionary with a "total" entry, or does not include "status", QUBODrivers fills those fields with default values.

set_model!(sampler::AbstractSampler{T}, model::QUBOTools.Model{VI,T,Int}) where {T}

Store the QUBOTools model backing a sampler.

The @setup macro provides this method for generated optimizer types. Custom sampler types that do not use @setup must provide it so that MOI.copy_to can transfer JuMP/MOI models into the sampler before optimization.

QUBODrivers.@setup Optimizer begin
    name = "Solver Name"
    version = v"1.0.0"
    attributes = begin
        NumberOfReads["num_reads"]::Integer = 1_000
    end
end

Declare a QUBODrivers sampler optimizer type.

The macro creates a mutable Optimizer{T} <: QUBODrivers.AbstractSampler{T}, QUBOTools model storage, MOI optimizer metadata, raw attribute storage, and MOI.get/MOI.set/MOI.supports methods for declared attributes.

The setup block accepts:

• name: required solver name returned by MOI.SolverName;
• version: optional VersionNumber, defaulting to the QUBODrivers package version;
• attributes: optional block of solver attributes.

Attributes are assignments to default values. They may be typed with ::T, exposed as typed MOI attributes, exposed as raw string attributes, or exposed as both:

• "num_reads" = 1_000
• "num_reads"::Integer = 1_000
• NumberOfReads = 1_000
• NumberOfReads::Integer = 1_000
• NumberOfReads["num_reads"] = 1_000
• NumberOfReads["num_reads"]::Integer = 1_000

Example

QUBODrivers.@setup Optimizer begin
    name       = "Super Sampler"
    version    = v"1.0.2"
    attributes = begin
        NumberOfReads["num_reads"]::Integer  = 1_000
        SuperAttribute["super_attr"]         = nothing
        MegaAttribute::Union{String,Nothing} = "mega"
    end
end

After setup, implement QUBODrivers.sample for the generated optimizer.

SamplerAttribute

Abstract supertype for optimizer attributes declared by QUBODrivers samplers.

Attributes generated by QUBODrivers.@setup, such as NumberOfReads, subtype SamplerAttribute and can be used with MOI.get, MOI.set, and MOI.supports.

RawSamplerAttribute{key}

QUBODrivers raw optimizer attribute identified by a string-like key.

RawSamplerAttribute("num_reads") is the QUBODrivers counterpart of MOI.RawOptimizerAttribute("num_reads"). Generated samplers route MOI raw attributes through this type so solver-specific attributes can share the same storage and validation as typed sampler attributes.

@raw_attr_str("key")

Create a RawSamplerAttribute type for dispatch.

This macro is useful when extending validation for a particular raw attribute:

function MOI.set(sampler::Optimizer, attr::QUBODrivers.@raw_attr_str("seed"), value)
    QUBODrivers.set_raw_attr!(sampler, attr, value)
    return nothing
end

get_raw_attr(sampler, attr)

Return a raw sampler attribute value.

Generated optimizers first look in the sampler's attribute storage and then fall back to default_raw_attr. Most users access this through MOI.get(sampler, MOI.RawOptimizerAttribute(name)) or a typed attribute.

set_raw_attr!(sampler, attr, value)

Store a raw sampler attribute value.

Generated optimizers use this hook from MOI.set. Sampler implementations can specialize it, or specialize MOI.set for a RawSamplerAttribute, to validate backend-specific options before storing them.

default_raw_attr(sampler, attr)

Return the default value for a raw sampler attribute.

Methods are generated by QUBODrivers.@setup for declared attributes. Sampler implementations may add methods to customize defaults for additional raw attributes.

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.

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.

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.

test(optimizer::Type{S}; examples::Bool=true) where {S<:AbstractSampler}
test(config!::Function, optimizer::Type{S}; examples::Bool=true) where {S<:AbstractSampler}

Run QUBODrivers' interface and example test suite for a sampler implementation.

These methods are implemented by the QUBODrivers_Test_Ext package extension and become available when Test is loaded in the active environment. The core package does not depend on Test directly.

benchmark(optimizer::Type{S}; objective_sense=MOI.MIN_SENSE) where {S<:AbstractSampler}
benchmark(config!::Function, optimizer::Type{S}; objective_sense=MOI.MIN_SENSE) where {S<:AbstractSampler}
benchmark(optimizer::Type{S}, source::MOI.ModelLike) where {S<:AbstractSampler}
benchmark(config!::Function, optimizer::Type{S}, source::MOI.ModelLike) where {S<:AbstractSampler}

Run a QUBO benchmark problem with a sampler implementation.

When source is provided, benchmark the sampler on that MOI model. The no-source methods use a small built-in QUBO instance as a smoke benchmark.

The optional config! function receives the raw sampler optimizer after the source model is copied and before optimization. This is useful for setting sampler attributes such as seeds, number of reads, time limits, or warm-starts.

The return value is a named tuple with solver metadata, benchmark problem size, result count, objective values, read counts, objective-value summary statistics, the best result, MOI solve time, measured wall time around MOI.optimize!, and solver status fields.