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
QUBODriversCommon MathOptInterface-compatible tools for QUBO and Ising samplers.
QUBODrivers provides:
- an
AbstractSampleroptimizer interface for QUBO-oriented solvers; - the
@setupmacro for declaring sampler optimizers and attributes; - built-in utility samplers in
ExactSampler,RandomSampler,IdentitySampler, andMIPSampler; - result and model plumbing through MathOptInterface and QUBOTools;
- optional
testandbenchmarkhelpers for sampler implementations.
Sampler Interface
QUBODrivers.AbstractSampler — Type
AbstractSampler{T} <: MOI.AbstractOptimizerAbstract 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.
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.
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.
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
endDeclare 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 byMOI.SolverName;version: optionalVersionNumber, 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_000NumberOfReads = 1_000NumberOfReads::Integer = 1_000NumberOfReads["num_reads"] = 1_000NumberOfReads["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
endAfter setup, implement QUBODrivers.sample for the generated optimizer.
QUBODrivers.SamplerAttribute — Type
SamplerAttributeAbstract 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.
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.
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.
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.
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.
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"].
QUBODrivers.auto_configure — Function
auto_configure(sampler)::BoolReturn whether automatic problem-size parameter scaling (AutoConfigure) is enabled on sampler. Samplers that do not support the attribute default to false.
QUBODrivers.supports_auto_configure — Function
supports_auto_configure(sampler_or_type)::BoolReturn whether a sampler implements automatic problem-size parameter scaling when AutoConfigure is set to true. Defaults to false.
QUBODrivers.has_explicit_raw_attr — Function
has_explicit_raw_attr(sampler, key::Union{Symbol,AbstractString})::BoolReturn 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.
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(orfalse,nothing): disable preprocessing (default);:strong(ortrue,: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 correspondingQUBOPreprocessing.preprocessrule 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"].
QUBODrivers.preprocess_rules — Function
preprocess_rules(sampler)::SymbolReturn 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.
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.
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.
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.
QUBODrivers.post_sample_transform — Function
post_sample_transform(sampler)::BoolReturn 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.
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.
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.
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.
QUBODrivers.supports_seed — Function
supports_seed(sampler_or_type)::BoolReturn whether a sampler advertises support for the standard RandomSeed attribute.
QUBODrivers.honors_final_reads — Function
honors_final_reads(sampler_or_type)::BoolReturn whether a sampler uses FinalNumberOfReads to control the number of samples emitted in the final SampleSet.
QUBODrivers.enforces_time_limit — Function
enforces_time_limit(sampler_or_type)::BoolReturn 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.
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])QUBODrivers.supports_domain — Function
supports_domain(sampler_or_type, domain)::BoolReturn whether sampler_or_type advertises support for domain (:bool / QUBOTools.BoolDomain, :spin / QUBOTools.SpinDomain, :int, or :set).
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).
QUBODrivers.variable_domain — Function
variable_domain(sampler::AbstractSampler, vi::MOI.VariableIndex)::Vector{Int}Return the ordered finite integer domain U_i ⊆ ℤ for variable vi.
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.
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.
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.
QUBODrivers.variable_num_levels — Function
variable_num_levels(sampler::AbstractSampler, vi::MOI.VariableIndex)::IntReturn the number of discrete levels length(U_i) in the finite domain of variable vi.
variable_num_levels(sampler::AbstractSampler)::Vector{Int}Return the number of discrete levels for each free variable of sampler in QUBOTools.variables(sampler) order.
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].
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).
QUBODrivers.supports_polynomial_objective — Function
supports_polynomial_objective(sampler_or_type)::BoolReturn 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.
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.
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.
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.
QUBODrivers.ScalarPolynomialFunction — Type
struct ScalarPolynomialFunction{T,P<:MP.AbstractPolynomial{T}} <: MOI.AbstractScalarFunction
polynomial::P
variables::Vector{MOI.VariableIndex}
endDefines the polynomial function of the variables variables where the variable MultivariatePolynomials.variables(polynomial)[i] corresponds to variables[i].
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}whereFis aMOI.AbstractScalarFunctionfor whichconvert(::Type{QUBODrivers.ScalarPolynomialFunction{T,P}}, ::F)is defined, such asMOI.VariableIndex,MOI.ScalarAffineFunction{T},MOI.ScalarQuadraticFunction{T}, andMOI.ScalarNonlinearFunction.
Target nodes
ToPolynomialBridge creates:
- One objective node:
MOI.ObjectiveFunction{QUBODrivers.ScalarPolynomialFunction{T,P}}
QUBODrivers.NLToPolynomial — Type
NLToPolynomial{T,M<:MOI.ModelLike} <: MOI.AbstractOptimizerOptimizer wrapper that rewrites nonlinear polynomial expressions into ScalarPolynomialFunction objectives and constraints.
QUBODrivers.InvalidNLExpression — Type
InvalidNLExpression <: ExceptionException 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 ^).
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.
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
endQUBODrivers.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.
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.
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.
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.
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.
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 toNumberOfReads.RandomGenerator,"rng": Random Number Generator instance.
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.
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,MIPSamplertranslates it back to the caller's original objective sense (MOI.MIN_SENSEorMOI.MAX_SENSE), variable domain (MOI.ZeroOneorQUBODrivers.Spin), scaling, constant offset, and fixed-variable (MOI.EqualTo) conditioning, and exposes it viaMOI.ObjectiveBound()as well asmetadata["objective_bound"]andmetadata["bound"]. If no finite objective bound is available for the current solve state,MOI.get(model, MOI.ObjectiveBound())throwsMOI.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 notMOI.OPTIMAL. Effective gap tolerances inmetadata["bound"]are recorded only when confirmed by backend readback or attribute forwarding; requested sampler settings are stored separately underrequested_relative_gap_toleranceandrequested_absolute_gap_tolerance. - Relative gap: When an incumbent and a bound are both present and the backend reports a finite
MOI.RelativeGap(),MIPSamplerexposes that solver-dependent value throughMOI.RelativeGap()andmetadata["relative_gap"](labeled"backend_solver_dependent"inmetadata["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 returnNaN/Inf),MOI.get(model, MOI.RelativeGap())throwsMOI.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, orMOI.INTERRUPTED) without a feasible incumbent,MIPSamplerreturns an emptySampleSet(MOI.ResultCount() == 0,MOI.PrimalStatus() == MOI.NO_SOLUTION) while preservingMOI.TerminationStatus(),MOI.ObjectiveBound()(when available), and solve timing metadata. Conversely, numerical validation failures (NaNor unrepresentable bounds/objectives/gaps, inconsistentbound > incumbent, invalid primal values) and backend solve errors throw an exception fromMOI.optimize!, clear any prior results (MOI.ResultCount() == 0,MOI.PrimalStatus() == MOI.NO_SOLUTION), and setMOI.TerminationStatus()toMOI.NUMERICAL_ERRORorMOI.OTHER_ERROR(or the backend's failure status).
Attributes
MIPOptimizer,"mip_optimizer": MOI-compatible optimizer factory used to solve the generated binary MIP.
QUBODrivers.MIPSampler.MIPOptimizer — Type
MIPOptimizer()Optimizer attribute that stores the MOI-compatible MIP backend factory used by MIPSampler.Optimizer.
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.
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.
Re-Exported Types
QUBODrivers re-exports a few commonly used QUBOTools and MOI names:
QUBODrivers.MOIaliases MathOptInterface;QUBODrivers.SampleandQUBODrivers.SampleSetare QUBOTools sample containers returned byQUBODrivers.sample;QUBODrivers.Spin,QUBODrivers.↑, andQUBODrivers.↓are the spin domain set and values used by QUBOTools' MOI extension.