Construction and configuration

QUBODecomposition.Optimizer uses Float64 coefficients. Runtime dependencies are QUBOTools 0.16.2, QUBODrivers 0.6.5 and MathOptInterface 1. Julia 1.10 is supported. JuMP and ToQUBO >=0.7.1 on the 0.7 compatibility line are test/example dependencies. component_executor, the component job/executor interfaces and absolute_deadline_sec require QUBODecomposition 0.1.2 or later. The exact resolved test versions are recorded in PR verification evidence and CI. The MOI 1.0.0 floor lane runs the entire runtime suite and every driver conformance group. JuMP 1 requires MOI >= 1.1.1, so its integration tests run through Pkg.test() in the other lanes.

Optimizer() is loadable without a child. Before solving, set child_optimizer and max_variables, using constructor keywords or MOI.RawOptimizerAttribute with the same names. The child factory must return a fresh empty MOI.AbstractOptimizer for every call, supporting the original homogeneous binary/spin domain, objective sense and Float64 quadratic objective. A factory may configure solver-specific attributes; the parent overrides only the per-call seed and the minimum applicable time limit. It rejects reused live optimizer instances.

OptionDefault and validation
child_optimizernothing; required fresh empty child factory; zero arguments, or a ComponentJob argument with an explicit executor
component_executornothing preserves serial defaults; an AbstractComponentExecutor opts into independent component execution, requires strategy=:components
absolute_deadline_secnothing; finite nonnegative absolute monotonic seconds (time_ns()/1e9), excludes Bool; shares the caller's deadline across preparation, execution, validation and commit; see timing
max_variablesnothing; required positive Int-sized integer, excludes Bool, including for empty models
strategy:components_then_sweeps; also :components, :whole_model, :separator, :frozen_batch, :consensus, :coarse and :sample_fixing
coarse_groupsnothing; owned vector of disjoint nonempty free-index groups for strategy=:coarse; group count, rather than represented originals, fits capacity; see coarse proposals
sample_poolnothing; explicit owned labelled original-domain pool for :sample_fixing; hard limits 256 rows / 65,536 cells; see sample fixing
fixing_threshold1.0; finite Float64 threshold in (1/2,1], excludes Bool; strict majority of distinct states
max_fixings256; integer in 0:256, excludes Bool; stop fixing sooner once the residual fits
max_pool_size256; integer in 1:256, excludes Bool; may lower the supplied row cap
separatorInt[]; either :articulation for automatic discovery or unique positive Int-sized free-variable indices, excludes Bool; checked against the current model in separator mode; setter/getter copy vectors
separator_pruningfalse; Bool; opt into exact-rational termwise pruning before residual dispatch in :separator mode
max_separator_size8; integer in 0:16, excludes Bool; separator length checked before any exponentiation or branch allocation
selection:strongest_edge; also :single_flip_gain, :bfs, :random_blocks and :partition; applies only to oversized-component sweeps
partition_plannothing; for selection=:partition, an owned vector of index vectors or callback (indices, adjacency, max_variables) -> blocks; see partition sweeps
batch_size8; integer in 1:64, excludes Bool; maximum overlapping neighborhoods per frozen transaction
repairtrue; Bool; set false for voting alone
max_child_calls1000; nonnegative Int-sized integer excluding Bool; across all component, neighborhood and separator calls
max_candidate_evaluations100000; nonnegative Int-sized integer excluding Bool; cumulative across initial evaluation, every supplied pool row, every row of every child call and direct residual evaluations
max_sweeps20; nonnegative Int-sized integer excluding Bool; whole-invocation sweep cap
stagnation_sweeps2; positive Int-sized integer excluding Bool; stop after this many complete sweeps without improvement
child_time_limit_secnothing or finite nonnegative seconds, excludes Bool
seednothing or integer in 0:2^31-2, excludes Bool

Unknown options fail explicitly. The released driver's conformance contract also exercises the legacy raw fixed_variables and moi_variables metadata slots; these are accepted as opaque user data and never alter the actual MOI copying/reconstruction state. Invalid setters clear old results and throw. Missing configuration returns INVALID_OPTION with no result. The required capacity counts every free logical variable, including isolates. MOI-fixed variables are reduced by the public driver copy hook and reconstructed through its public VariablePrimal interface. Arbitrary QUBOTools labels are preserved via QUBODrivers.set_model! and QUBOTools.backend, variable, index, state and solution. MOI variable queries apply to MOI-copied models; direct non-MOI labels use QUBOTools queries.

Automatic discovery is opt-in with strategy=:separator, separator=:articulation. Raw MOI.RawOptimizerAttribute("separator") accepts and returns that symbol; other symbols and strings are invalid. A separator option is used only by the separator strategy. Getters/configuration snapshots retain the symbol or an owned vector, and setters invalidate prior results even when rejected. Changing input, labels, capacity, mode or separator cap rebuilds discovery on the next solve.

strategy=:frozen_batch supports selection=:strongest_edge and :bfs only. Other selector combinations return INVALID_OPTION before child dispatch, including on fitting or constant inputs. These scalar options are owned by the optimizer; setting them invalidates old results. No mutable batch-plan callback or weighted voting interface is introduced.

For explicit overlapping blocks, see serial Lagrangian consensus.

separator_pruning=true and strategy=:consensus require 0.1.3 or later. See installation. Root preprocessing requires 0.1.5 or later. Pruning's certificate assumptions differ from the experimental consensus strategy, whose completion remains heuristic even with exact children, agreement or a zero gap.

The QUBODrivers floor stays 0.6.5. See the ExactSampler version contract for the corrected 0.6.6 public certificate and unchanged heuristic/limit rules.