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.
| Option | Default and validation |
|---|---|
child_optimizer | nothing; required fresh empty child factory; zero arguments, or a ComponentJob argument with an explicit executor |
component_executor | nothing preserves serial defaults; an AbstractComponentExecutor opts into independent component execution, requires strategy=:components |
absolute_deadline_sec | nothing; finite nonnegative absolute monotonic seconds (time_ns()/1e9), excludes Bool; shares the caller's deadline across preparation, execution, validation and commit; see timing |
max_variables | nothing; 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_groups | nothing; owned vector of disjoint nonempty free-index groups for strategy=:coarse; group count, rather than represented originals, fits capacity; see coarse proposals |
sample_pool | nothing; explicit owned labelled original-domain pool for :sample_fixing; hard limits 256 rows / 65,536 cells; see sample fixing |
fixing_threshold | 1.0; finite Float64 threshold in (1/2,1], excludes Bool; strict majority of distinct states |
max_fixings | 256; integer in 0:256, excludes Bool; stop fixing sooner once the residual fits |
max_pool_size | 256; integer in 1:256, excludes Bool; may lower the supplied row cap |
separator | Int[]; 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_pruning | false; Bool; opt into exact-rational termwise pruning before residual dispatch in :separator mode |
max_separator_size | 8; 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_plan | nothing; for selection=:partition, an owned vector of index vectors or callback (indices, adjacency, max_variables) -> blocks; see partition sweeps |
batch_size | 8; integer in 1:64, excludes Bool; maximum overlapping neighborhoods per frozen transaction |
repair | true; Bool; set false for voting alone |
max_child_calls | 1000; nonnegative Int-sized integer excluding Bool; across all component, neighborhood and separator calls |
max_candidate_evaluations | 100000; 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_sweeps | 20; nonnegative Int-sized integer excluding Bool; whole-invocation sweep cap |
stagnation_sweeps | 2; positive Int-sized integer excluding Bool; stop after this many complete sweeps without improvement |
child_time_limit_sec | nothing or finite nonnegative seconds, excludes Bool |
seed | nothing 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.