Implementing a Sampler

This walkthrough builds a minimal sampler that works through the same public interfaces used by package wrappers. It uses exhaustive search so the example is self-contained; a production wrapper can replace that inner loop with a call to an external library, service, or device.

Minimal module

A QUBODrivers sampler needs an optimizer type and a QUBODrivers.sample method. The QUBODrivers.@setup macro creates the optimizer type, standard MOI methods, and attribute storage.

module DemoSampler

import QUBODrivers
import QUBODrivers: MOI, QUBOTools, Sample, SampleSet

QUBODrivers.@setup Optimizer begin
    name    = "Demo Sampler"
    version = v"0.1.0"
    attributes = begin
        NumberOfReads["num_reads"]::Integer = 1
    end
end

function QUBODrivers.sample(sampler::Optimizer{T}) where {T}
    n, linear, quadratic, scale, offset = QUBOTools.qubo(
        sampler,
        :dict;
        sense = :min,
    )

    num_reads = MOI.get(sampler, NumberOfReads())
    final_reads = MOI.get(sampler, QUBODrivers.FinalNumberOfReads())
    if num_reads < 1
        error("'num_reads' must be a positive integer")
    end
    if final_reads < 1
        error("'final_num_reads' must be a positive integer")
    end

    best_state = Vector{Int}()
    best_value = nothing

    for state in Iterators.product(ntuple(_ -> (0, 1), n)...)
        candidate_state = collect(state)
        candidate_value = QUBOTools.value(
            candidate_state,
            linear,
            quadratic,
            scale,
            offset,
        )

        if isnothing(best_value) || candidate_value < best_value
            best_state = candidate_state
            best_value = candidate_value
        end
    end

    samples = [
        Sample{T,Int}(copy(best_state), best_value)
        for _ in 1:final_reads
    ]

    metadata = Dict{String,Any}(
        "origin"    => "Demo Sampler",
        "algorithm" => Dict{String,Any}("name" => "Demo Sampler"),
        "backend"   => Dict{String,Any}("name" => "Demo Sampler", "version" => v"0.1.0"),
        "execution" => Dict{String,Any}("mode" => "exhaustive_search"),
        "optimizer" => Dict{String,Any}("iterations" => nothing, "evaluations" => final_reads),
        "reads"     => Dict{String,Any}(
            "number_of_reads"       => final_reads,
            "final_number_of_reads" => final_reads,
        ),
        "seeds"     => Dict{String,Any}(),
        "time"      => Dict{String,Any}("effective" => 0.0),
        "status"    => "optimal",
    )

    return SampleSet{T}(samples, metadata; sense = :min, domain = :bool)
end

end

nothing

Use it from JuMP

The generated Optimizer type is an MOI.AbstractOptimizer, so it can be passed directly to JuMP.Model.

using JuMP

model = Model(DemoSampler.Optimizer)
set_optimizer_attribute(model, "num_reads", 2)

@variable(model, x[1:2], Bin)
@objective(model, Min, -x[1] - 2x[2] + 3x[1] * x[2])

optimize!(model)

(objective_value(model), round.(Int, value.(x)), result_count(model))
(-2.0, [0, 1], 1)

Implementation checklist

When adapting the example for a real sampler:

  • choose the QUBOTools representation that matches the backend, such as QUBOTools.qubo(sampler, :dict; sense = :min) or QUBOTools.ising(sampler, :dense; sense = :max);
  • read user-facing options through MOI attributes generated by @setup;
  • use QUBODrivers.FinalNumberOfReads() for the returned sample count when a backend has separate search and final sampling phases;
  • convert backend outputs into Sample{T,Int} entries;
  • return a SampleSet{T} with the correct sense and domain;
  • include useful metadata such as timing, backend status, and backend version;
  • leave generic post-sampling annotation or repair to QUBODrivers.PostSampleCallback() when users need a configurable hook;
  • use QUBOTools objective metadata and ToQUBO reformulation metadata for objective bookkeeping, original-variable projection, and encoding-specific auxiliary handling;
  • run QUBODrivers.test(YourSampler.Optimizer) in the package test suite.

The built-in RandomSampler and ExactSampler implementations are compact references for these same steps.

Polynomial Objectives (HUBO / PUBO)

Samplers that natively accept higher-order polynomial objectives (such as HUBO or PUBO solvers) can opt into QUBODrivers' polynomial objective bridge by specializing QUBODrivers.supports_polynomial_objective:

QUBODrivers.supports_polynomial_objective(::Type{<:Optimizer}) = true

When enabled, the sampler accepts MOI.ScalarNonlinearFunction and QUBODrivers.ScalarPolynomialFunction objectives in addition to linear and quadratic MOI objectives. Inside QUBODrivers.sample, call QUBODrivers.polynomial_objective to retrieve a MultivariatePolynomials.AbstractPolynomial{T} over the free variables in QUBOTools.variables(sampler) order (or QUBODrivers.polynomial_function to retrieve the MOI QUBODrivers.ScalarPolynomialFunction wrapper), with fixed variables substituted and constant offsets preserved. Non-polynomial operators (such as sin, division / by zero or a non-constant expression, or non-integer/negative ^) throw QUBODrivers.InvalidNLExpression. Samplers that do not opt in keep supports_polynomial_objective == false and remain on the quadratic QUBO/Ising lowering path.

Package a sampler interface

Once the sampler module works, package it like a normal Julia interface package. The smallest useful repository usually has src/, test/, Project.toml, and GitHub automation for tests and releases. Prefer this checklist over a generated template: QUBODrivers interfaces vary from single-file wrappers to multi-module hardware clients and Python-backed packages.

Use src/library/drivers/ExactSampler.jl as the canonical copy-from skeleton for the optimizer declaration, the QUBODrivers.sample method, and metadata shape. Then compare against real interfaces such as DWave.jl and JuliQAOAOpt.jl for package layouts that include external backends.

Project.toml

A standalone interface package should depend on QUBODrivers, QUBOTools, and MathOptInterface. Add backend-specific dependencies only when the sampler calls them directly.

name = "MySampler"
uuid = "00000000-0000-0000-0000-000000000000"
authors = ["Your Name <you@example.com>"]
version = "0.1.0"

[deps]
MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
QUBODrivers = "a3f166f7-2cd3-47b6-9e1e-6fbfe0449eb0"
QUBOTools = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"

[compat]
MathOptInterface = "1"
QUBODrivers = "0.6"
QUBOTools = "0.10, 0.11, 0.12, 0.13, 0.14"
julia = "1.10"

Keep [compat] bounds explicit. They define what users and CI can install, and they are also what registry review checks before accepting a release.

Replace the placeholder uuid with a real value generated in Julia, for example using UUIDs; uuid4().

Tests

Put the public interface checks in test/runtests.jl. The QUBODrivers.test extension loads when both QUBODrivers and Julia's Test standard library are available.

using Test
using MySampler
using QUBODrivers

@testset "MySampler" begin
    QUBODrivers.test(MySampler.Optimizer)
end

For samplers that need deterministic options or credentials-free operation, pass a setup function or disable example problems as shown in Test Suite. Keep backend integration tests separate when they require secrets, paid hardware, or long runtimes.

Public composition pattern

A composite sampler can implement QUBODrivers.sample and the public QUBODrivers.set_model! hook, using @setup for its optimizer or for model storage. Read the backing model through QUBOTools.backend and public model queries. Keep decomposition policy in the standalone package.

Accept a zero-argument factory that constructs a fresh, empty child optimizer for each call. Configure child-specific attributes inside that factory through MOI.set, MOI.RawOptimizerAttribute, or MOI.OptimizerWithAttributes; use MOI.instantiate when a wrapper needs bridges. Check support for the domain, objective and attributes required by the child contract.

using QUBODrivers
import MathOptInterface as MOI

child_factory = () -> QUBODrivers.ExactSampler.Optimizer()
child = child_factory()
(child isa MOI.AbstractOptimizer, MOI.is_empty(child))
(true, true)

Copy each child problem with MOI.copy_to and retain its returned index map for MOI.VariablePrimal queries. Explicitly include isolated variables. Reconstruct complete global assignments, including fixed variables, and independently evaluate the original model objective with its sense, domain, scale and offset. Child-reported objectives alone cannot validate reconstruction. For ToQUBO, this original model is the compiled QUBO; source feasibility and source objective evaluation remain a separate compiler/user responsibility.

Use public MOI.ResultCount, MOI.PrimalStatus, MOI.TerminationStatus, and result queries to validate a child before committing its candidates. A raw metadata status string is diagnostic, not a certificate. A completed exhaustive ExactSampler solve exposes public OPTIMAL; failed solves and transformed post-sample results do not retain that certificate. QUBODrivers 0.6.5 and earlier returned LOCALLY_SOLVED despite exhaustive completion; this was a public-status defect, not an intended algorithm limitation. Consumers using that release must retain its observed status until adopting a version containing the fix. Independent component certificates require valid public OPTIMAL results for every component; exact neighborhood solves in coupled sweeps do not prove a global optimum. Preserve limits, interruptions and failures conservatively, exposing only validated results and clearing stale results/proofs on a new invocation.

QUBODecomposition's public implementation demonstrates this pattern using released QUBODrivers 0.6.5 and QUBOTools 0.16.2 interfaces. No new upstream hook, schema or routing trait is needed for this consumer. Its whole-model example and serial example show factory/budget configuration. See Composite accounting for metadata and Composite conformance evidence for the audited tests.

Continuous integration and maintenance

Use CI to exercise the package on the Julia versions in [compat]. A typical GitHub Actions workflow checks out the repository, installs Julia with julia-actions/setup-julia, enables julia-actions/cache, runs julia-actions/julia-buildpkg, and runs julia-actions/julia-runtest.

Add Dependabot for the package environments that exist in the repository. Common entries are:

  • the root Julia package environment at /;
  • /docs if the package builds Documenter docs;
  • /test if tests use a separate test environment;
  • GitHub Actions updates at /.

If the package is registered and should publish Git tags automatically, add TagBot with JuliaRegistries/TagBot. Registration is optional for sampler interfaces, and TagBot is only useful once releases are driven by registry events.

Installation and registration

Unregistered sampler packages can be installed directly from their repository URL. This is the default fallback path while an interface is private, experimental, or too specialized for registration.

import Pkg
Pkg.add(url = "https://github.com/Owner/MySampler.jl")

When the package is stable enough for wider use, register it with Julia's General registry using Registrator. Before registering, confirm the package has a unique UUID, an incremented version, explicit [compat] bounds, passing CI, and documentation that points users back to this QUBODrivers interface guide.

Registering the package with QUBODrivers docs

If the sampler package is public and current in the JuliaQUBO or SECQUOIA organizations, open a QUBODrivers documentation PR that adds it to the external sampler table in docs/src/manual/3-samplers.md. That table is maintained as the reviewed source of truth rather than generated from GitHub search.

Include:

  • the package repository URL;
  • the public solver type, such as Package.Optimizer or Package.Submodule.Optimizer;
  • the source file path that defines the optimizer;
  • a note when the package is deprecated, renamed, experimental, private, or a compatibility shim.

For documentation-only registration PRs, run:

julia --project=docs/ docs/make.jl --skip-deploy