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, IdentitySampler, and MIPSampler;
• 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. It then validates the benchmarking metadata schema and emits a warning, not an error, for missing or malformed fields.

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.

RandomSeed()

Generic sampler optimizer attribute for a reproducibility seed.

The raw optimizer attribute key is "seed", and the default value is nothing. Generated optimizers support this typed attribute when the driver declares the raw "seed" attribute in its QUBODrivers.@setup block. When a seed is set, QUBODrivers records it under metadata["seeds"]["sampler"] in the emitted SampleSet.

random_seed(sampler)

Return the configured sampler seed, or nothing when the sampler does not support the standard seed attribute or no seed is configured.

FinalNumberOfReads()

Generic sampler optimizer attribute for the number of reads used to build the final emitted SampleSet.

NumberOfReads remains the convention for reads used by a sampler's internal search, optimization, or objective evaluations. FinalNumberOfReads separates the number of reads returned to users from those internal evaluations. If the final read count is unset (nothing), the effective final read count defaults to the sampler's raw "num_reads" attribute when that attribute is supported.

Generated optimizers created by QUBODrivers.@setup support this attribute and the raw "final_num_reads" key.

final_number_of_reads(sampler)

Return the effective final read count for sampler.

This is equivalent to MOI.get(sampler, FinalNumberOfReads()) for samplers generated by QUBODrivers.@setup. If "final_num_reads" is unset, the returned value falls back to raw "num_reads" when supported; otherwise it is nothing.

PostSampleCallback()

Generic sampler optimizer attribute for a callback applied after backend sampling and before the final SampleSet is attached to the optimizer.

The raw optimizer attribute key is "post_sample_callback". The callback is called as callback(sampleset, sampler), where sampleset is a copy of the raw backend output and sampler is the optimizer/model context. The callback may mutate the copied sample-set metadata and return nothing, or return a SampleSet to replace the emitted samples. Replacing or changing sample states, values, reads, sense, or domain requires PostSampleTransform to be set to true.

PostSampleTransform()

Generic sampler optimizer attribute controlling whether PostSampleCallback may transform emitted samples.

The raw optimizer attribute key is "post_sample_transform", and the default value is false. When set to true, a post-sample callback may return a replacement SampleSet. QUBODrivers records callback metadata and preserves the raw samples in the emitted solution metadata.

post_sample_callback(sampler)

Return the configured post-sample callback for sampler, or nothing when no callback is configured or the sampler does not support the generic callback attribute.

post_sample_transform(sampler)::Bool

Return whether the configured post-sample callback may transform emitted sample states, values, reads, sense, or domain. Samplers that do not support the generic transform attribute default to false.

total_time(sampleset_or_sampler)

Return metadata["time"]["total"], the wall-clock seconds measured around the QUBODrivers sampling pipeline, or nothing when it is not available.

effective_time(sampleset_or_sampler)

Return metadata["time"]["effective"], the backend solve/sampling seconds reported by the driver, or nothing when it is not available.

validate_metadata(sampleset::SampleSet)
validate_metadata(metadata::AbstractDict)

Return a list of benchmarking metadata schema violations.

The validator is intentionally non-throwing so driver authors can use it while migrating metadata. MOI.optimize! calls it after QUBODrivers stamps framework metadata and emits a warning when the returned list is not empty.

supports_seed(sampler_or_type)::Bool

Return whether a sampler advertises support for the standard RandomSeed attribute.

honors_final_reads(sampler_or_type)::Bool

Return whether a sampler uses FinalNumberOfReads to control the number of samples emitted in the final SampleSet.

enforces_time_limit(sampler_or_type)::Bool

Return whether a sampler enforces MOI.TimeLimitSec() as part of its own sampling contract. The default is conservative because many wrappers only store or forward the attribute.

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.

ExactSampler ignores QUBODrivers.FinalNumberOfReads; it always returns the full exhaustive sample set.

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.

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.

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.

Only one best incumbent sample is returned. MIPSampler ignores QUBODrivers.FinalNumberOfReads.

Attributes

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

MIPOptimizer()

Optimizer attribute that stores the MOI-compatible MIP backend factory used by MIPSampler.Optimizer.

test(optimizer::Type{S}; examples::Bool=true, kwargs...) where {S<:AbstractSampler}
test(config!::Function, optimizer::Type{S}; examples::Bool=true, kwargs...) 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 conformance checks are enabled by default. Pass benchmark_conformance=false to disable all benchmark conformance checks, or disable individual groups with metadata_conformance=false, timing_sanity=false, determinism=false, reads_semantics=false, time_limit_acceptance=false, or termination_status=false. The default determinism=:auto runs seed determinism only for samplers whose supports_seed trait is true.

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.