API Reference

This page collects the public QUBODrivers API used by solver users and sampler authors. QUBOTools provides the lower-level model and sample containers; this package documents the MOI-facing sampler layer built on top of them.

Package

QUBODrivers — Module
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.
source

Sampler Interface

QUBODrivers.AbstractSampler — Type
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.

source
QUBODrivers.sample — Function
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.

source
QUBODrivers.set_model! — Function
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.

source

Setup and Attributes

QUBODrivers.@setup — Macro
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.

source
QUBODrivers.SamplerAttribute — Type
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.

source
QUBODrivers.RandomSeed — Type
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.

source
QUBODrivers.random_seed — Function
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.

source
QUBODrivers.FinalNumberOfReads — Type
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.

source
QUBODrivers.final_number_of_reads — Function
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.

source
QUBODrivers.AutoConfigure — Type
AutoConfigure()

Generic opt-in sampler optimizer attribute enabling problem-size-dependent parameter scaling (n = QUBOTools.dimension(sampler)).

The raw optimizer attribute key is "auto_configure", and the default value is false so existing solver behavior is unchanged unless explicitly enabled. Samplers that implement size-based scaling advertise support via supports_auto_configure, respect any explicitly user-set solver attributes over auto-scaled values (verifiable via has_explicit_raw_attr), clamp scaled parameters to explicit finite bounds, and log the chosen scaling details under metadata["auto_configure"].

source
QUBODrivers.auto_configure — Function
auto_configure(sampler)::Bool

Return whether automatic problem-size parameter scaling (AutoConfigure) is enabled on sampler. Samplers that do not support the attribute default to false.

source
QUBODrivers.has_explicit_raw_attr — Function
has_explicit_raw_attr(sampler, key::Union{Symbol,AbstractString})::Bool

Return true when the raw optimizer attribute key has been explicitly set by the caller on sampler (with a non-nothing value), and false when the attribute is still at its default value. Drivers implementing AutoConfigure use this check to preserve user override precedence.

source
QUBODrivers.Preprocess — Type
Preprocess()

Generic opt-in sampler optimizer attribute enabling automatic polynomial-time QUBO/Ising model reduction and exact sample reconstruction via QUBOPreprocessing.jl.

The raw optimizer attribute key is "preprocess", and the default value is :none (preprocessing disabled). Supported values (normalized to Symbol on assignment) are:

  • :none (or false, nothing): disable preprocessing (default);
  • :strong (or true, :all): run the full strong ground-state-preserving polynomial-time reduction pipeline (integerize_scale=true, dominance, degree-1/2/3 variable elimination, equivalent/opposite variable relations, star-triangle degree-3 reduction, roof duality/autarky, submodular cut, max-cut, and two-literal probing);
  • :weak: run the full weak optimum-preserving polynomial-time reduction pipeline (allowing weak ties in dominance, relations, submodular cut, and max-cut);
  • :dominance, :elimination, :relations, :mixed, or :identity: run the corresponding QUBOPreprocessing.preprocess rule schedule.

When enabled (preprocess_rules(sampler) !== :none), MOI.optimize! automatically reduces the sampler's model prior to calling sample, solves the reduced model on the surviving active variables, reconstructs all returned samples back to the full $n$-variable space via QUBOPreprocessing.reconstruct, and records preprocessing telemetry under metadata["preprocess"] and metadata["time"]["preprocess"].

source
QUBODrivers.preprocess_rules — Function
preprocess_rules(sampler)::Symbol

Return the normalized Preprocess rule mode configured on sampler (:none, :strong, :weak, :dominance, :elimination, :relations, :mixed, or :identity). Samplers that do not support the attribute default to :none.

source
QUBODrivers.PostSampleCallback — Type
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.

source
QUBODrivers.PostSampleTransform — Type
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.

source
QUBODrivers.post_sample_callback — Function
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.

source
QUBODrivers.post_sample_transform — Function
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.

source
QUBODrivers.total_time — Function
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.

source
QUBODrivers.effective_time — Function
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.

source
QUBODrivers.validate_metadata — Function
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.

source
QUBODrivers.enforces_time_limit — Function
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.

source
QUBODrivers.supported_domains — Function
supported_domains(sampler_or_type)

Return the collection of variable domains supported by a sampler optimizer.

Defaults to Set{Symbol}([:bool, :spin]) so existing binary and spin samplers remain unchanged. Samplers that natively accept contiguous bounded integer variables (MOI.Integer with finite bounds) or explicit finite integer value sets (VariableEncodingSet) may extend this method to include :int and/or :set, for example:

QUBODrivers.supported_domains(::Type{<:Optimizer}) = Set([:bool, :spin, :int, :set])
source
QUBODrivers.supports_domain — Function
supports_domain(sampler_or_type, domain)::Bool

Return whether sampler_or_type advertises support for domain (:bool / QUBOTools.BoolDomain, :spin / QUBOTools.SpinDomain, :int, or :set).

source
QUBODrivers.VariableEncodingSet — Type
VariableEncodingSet()

MOI variable attribute specifying an explicit finite integer value set (x_i ∈ U_i ⊆ ℤ) for variable x_i, shared with ToQUBO.Attributes.VariableEncodingSet().

When set on a variable in a model handed to a sampler that supports the :set domain (supports_domain(sampler, :set) == true), the variable's finite domain is Vector{Int}(U_i).

source
QUBODrivers.variable_domain — Function
variable_domain(sampler::AbstractSampler, vi::MOI.VariableIndex)::Vector{Int}

Return the ordered finite integer domain U_i ⊆ ℤ for variable vi.

source
QUBODrivers.variable_domains — Function
variable_domains(sampler::AbstractSampler)::Vector{Vector{Int}}

Return the ordered finite integer domains [U_1, …, U_n] for all free variables of sampler in QUBOTools.variables(sampler) order.

source
QUBODrivers.variable_bounds — Function
variable_bounds(sampler::AbstractSampler, vi::MOI.VariableIndex)::Tuple{Int,Int}

Return the (lower, upper) integer bounds (minimum(U_i), maximum(U_i)) for variable vi.

source
variable_bounds(sampler::AbstractSampler)::Vector{Tuple{Int,Int}}

Return the (lower, upper) integer bounds for all free variables of sampler in QUBOTools.variables(sampler) order.

source
QUBODrivers.variable_num_levels — Function
variable_num_levels(sampler::AbstractSampler, vi::MOI.VariableIndex)::Int

Return the number of discrete levels length(U_i) in the finite domain of variable vi.

source
variable_num_levels(sampler::AbstractSampler)::Vector{Int}

Return the number of discrete levels for each free variable of sampler in QUBOTools.variables(sampler) order.

source
QUBODrivers.levels_to_values — Function
levels_to_values(sampler::AbstractSampler, vi::MOI.VariableIndex, level::Integer)::Int
levels_to_values(sampler::AbstractSampler, levels::AbstractVector{<:Integer})::Vector{Int}

Map zero-based level indices k_i ∈ 0:(d_i - 1) to variable domain values U_i[k_i + 1].

source
QUBODrivers.values_to_levels — Function
values_to_levels(sampler::AbstractSampler, vi::MOI.VariableIndex, value::Real)::Int
values_to_levels(sampler::AbstractSampler, values::AbstractVector{<:Real})::Vector{Int}

Invert variable domain values v_i ∈ U_i back to zero-based level indices k_i ∈ 0:(d_i - 1).

source
QUBODrivers.supports_polynomial_objective — Function
supports_polynomial_objective(sampler_or_type)::Bool

Return whether a sampler opts into receiving general polynomial objectives (including higher-order HUBO/PUBO objectives expressed via MOI.ScalarNonlinearFunction or ScalarPolynomialFunction).

Defaults to false so quadratic QUBO/Ising samplers remain on the standard quadratic lowering path and reject degree >= 3 objectives as before.

source
QUBODrivers.polynomial_objective — Function
polynomial_objective(
    sampler::AbstractSampler{T};
    sense::Union{Symbol,QUBOTools.Sense,Nothing} = nothing,
    domain::Union{Symbol,QUBOTools.Domain,Nothing} = nothing,
    shift::Bool = false,
)::MP.AbstractPolynomial{T} where {T}

Return the objective polynomial stored on an opted-in sampler as a MultivariatePolynomials.AbstractPolynomial{T} over the free variables in QUBOTools.variables(sampler) order, preserving constant offset and fixed variable reductions.

If sense (:min or :max) or domain (:bool or :spin) is provided, the polynomial is cast to the requested optimization sense and variable domain. When shift = true, contiguous unit-step integer domains {l_i, …, u_i} are shifted via $x_i \mapsto y_i + l_i$ to zero-based level coordinates $y_i \in \{0, \dots, u_i - l_i\}$.

Throws an ArgumentError if neither supports_polynomial_objective(sampler) nor non-binary domain support is enabled on sampler.

source
QUBODrivers.polynomial_function — Function
polynomial_function(p::MP.AbstractPolynomial{T}, variables::Vector{MOI.VariableIndex}) where {T}
polynomial_function(func::MOI.AbstractScalarFunction, ::Type{T} = Float64) where {T}
polynomial_function(sampler::AbstractSampler{T}; sense = nothing, domain = nothing) where {T}

Construct or extract a ScalarPolynomialFunction representing a scalar polynomial objective or constraint expression.

source
QUBODrivers.polynomial_type — Function
polynomial_type(::Type{MOI.VariableIndex})
polynomial_type(::Type{MOI.VariableIndex}, ::Type{T}) where {T}
polynomial_type(::Type{T} = Float64) where {T<:Number}

Return the concrete DynamicPolynomials.Polynomial type used by QUBODrivers to represent MOI polynomial functions with coefficient type T.

source
QUBODrivers.ScalarPolynomialFunction — Type
struct ScalarPolynomialFunction{T,P<:MP.AbstractPolynomial{T}} <: MOI.AbstractScalarFunction
    polynomial::P
    variables::Vector{MOI.VariableIndex}
end

Defines the polynomial function of the variables variables where the variable MultivariatePolynomials.variables(polynomial)[i] corresponds to variables[i].

source
QUBODrivers.ToPolynomialBridge — Type
ToPolynomialBridge{T}

ToPolynomialBridge implements the following reformulations:

  • $\min \{f(x)\}$ into $\min\{p(x)\}$
  • $\max \{f(x)\}$ into $\max\{p(x)\}$

where $f(x)$ is a scalar function and $p(x)$ is a polynomial.

Source node

ToPolynomialBridge supports:

  • MOI.ObjectiveFunction{F} where F is a MOI.AbstractScalarFunction for which convert(::Type{QUBODrivers.ScalarPolynomialFunction{T,P}}, ::F) is defined, such as MOI.VariableIndex, MOI.ScalarAffineFunction{T}, MOI.ScalarQuadraticFunction{T}, and MOI.ScalarNonlinearFunction.

Target nodes

ToPolynomialBridge creates:

  • One objective node: MOI.ObjectiveFunction{QUBODrivers.ScalarPolynomialFunction{T,P}}
source
QUBODrivers.InvalidNLExpression — Type
InvalidNLExpression <: Exception

Exception thrown when a nonlinear expression cannot be converted into a polynomial (for example, when it uses a non-polynomial operator such as sin, non-constant division /, or a non-integer or negative exponent in ^).

source
QUBODrivers.RawSamplerAttribute — Type
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.

source
QUBODrivers.@raw_attr_str — Macro
@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
source
QUBODrivers.get_raw_attr — Function
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.

source
QUBODrivers.set_raw_attr! — Function
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.

source
QUBODrivers.default_raw_attr — Function
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.

source

Built-In Samplers

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
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
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
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

Test and Benchmark Helpers

QUBODrivers.test — Function
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.

source
QUBODrivers.benchmark — Function
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.

source

Re-Exported Types

QUBODrivers re-exports a few commonly used QUBOTools and MOI names:

  • QUBODrivers.MOI aliases MathOptInterface;
  • QUBODrivers.Sample and QUBODrivers.SampleSet are QUBOTools sample containers returned by QUBODrivers.sample;
  • QUBODrivers.Spin, QUBODrivers.↑, and QUBODrivers.↓ are the spin domain set and values used by QUBOTools' MOI extension.