Attributes

API

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

Standard sampler attributes

Generated optimizers created with QUBODrivers.@setup support QUBODrivers.FinalNumberOfReads() and the raw key "final_num_reads".

Use "num_reads" for reads spent during a sampler's internal search, optimization, or objective evaluations. Use "final_num_reads" for reads used to build the returned SampleSet. If "final_num_reads" is unset, the effective final read count defaults to "num_reads" when the sampler supports that attribute.

Built-in samplers that do not have a separate final sampling phase document the attribute as ignored and report their fixed returned read count in metadata.

Generated optimizers also support QUBODrivers.Preprocess() and the raw key "preprocess" (default :none). Setting it to :strong, :weak, :dominance, :elimination, :relations, :mixed, or :identity runs QUBOPreprocessing.jl before sample, passes the reduced model to the sampler, reconstructs full-dimensional samples afterward, and records reduction statistics in metadata["preprocess"] and metadata["time"]["preprocess"].

Generated optimizers also support QUBODrivers.PostSampleCallback() and the raw key "post_sample_callback". The callback receives a copied SampleSet and the sampler context after raw sampling. Metadata-only annotations are allowed by default. To emit changed sample states, values, reads, sense, or domain, set QUBODrivers.PostSampleTransform() or raw "post_sample_transform" to true and return the transformed SampleSet. Replacement SampleSets should carry over or intentionally rebuild raw backend metadata. Objective annotations should follow QUBOTools' "objectives" metadata convention, and reformulation-specific projection or repair data should come from ToQUBO/QUBOTools metadata rather than from QUBODrivers.

An advanced example

module SuperSampler

import QUBODrivers
import QUBODrivers: QUBOTools
import MathOptInterface as MOI

QUBODrivers.@setup Optimizer begin
    name    = "Super Sampler"
    version = v"1.0.2"
    attributes = begin
        NumberOfReads["num_reads"]::Integer  = 100_000
        SuperAttribute["super_attr"]::String = "super"
    end
end

function MOI.set(sampler::Optimizer, attr::raw_attr"", value)
    if !(value isa Integer)
        error("'num_reads' must be an integer")
    else
        QUBODrivers.set_raw_attr!(sampler, attr, value)
    end

    return nothing
end

function MOI.set(sampler::Optimizer, attr::raw_attr"super_attr", value)
    if !(value isa AbstractString)
        error("'super_attr' must be a string")
    elseif !(value ∈ ("super", "ultra", "mega"))
        error("'super_attr' must be one of the following: 'super', 'ultra', 'mega'")
    else
        QUBODrivers.set_raw_attr!(sampler, attr, value)
    end

    return nothing
end

end # SuperSampler module