Search Parameters

All three solvers in QUBO++ — Easy Solver, Exhaustive Solver, and ABS3 Solver — accept search parameters through search(). Parameters are key-value pairs. Values can be strings, integers, or floating-point numbers — numeric values are automatically converted to strings internally.

Passing Parameters

Pass an initializer list directly to search():

auto sol = solver.search({{"time_limit", 10}, {"target_energy", 0}});

Values can be mixed — strings, integers, and floating-point numbers:

auto sol = solver.search({{"time_limit", 2.5}, {"target_energy", "0"}});

When you need to build parameters programmatically, create a qbpp::Params object and use operator():

qbpp::Params params;
params("time_limit", 10);
params("target_energy", 0);
auto sol = solver.search(params);

Common Parameters

The following parameters are shared by all three solvers:

Parameter	Type	Description
target_energy	integer	Stop when a solution with energy ≤ this value is found. With constraints declared by cons(), every constraint must also be satisfied (see Solver support and semantics).
enable_default_callback	0/1	Print newly obtained best solutions to stdout. Default: 0.
topk_sols	integer	Keep up to N top-k solutions during the search.
best_energy_sols	0/integer	Maximum number of best-energy solutions to keep. 0 = unlimited count.

Easy Solver Parameters

Parameter	Type	Description	Default
time_limit	float	Time limit in seconds. 0 for no limit.	10.0
target_energy	integer	Target energy.	(none)
enable_default_callback	0/1	Print progress.	0
topk_sols	integer	Top-k solutions to keep.	(disabled)
best_energy_sols	0/integer	Best-energy solutions to keep.	(disabled)
thread_count	integer	Number of CPU threads used for the search.	(auto)
seed	integer	Random seed (for reproducible runs).	(random)

Example:

#include <qbpp/qbpp.hpp>
#include <qbpp/easy_solver.hpp>

auto solver = qbpp::EasySolver(f);
auto sol = solver.search({{"time_limit", 5}, {"target_energy", 0}});

Exhaustive Solver Parameters

The Exhaustive Solver does not have a time_limit parameter because it performs a complete search.

Parameter	Type	Description	Default
target_energy	integer	Target energy (for early termination).	(none)
verbose	0/1	Display search progress percentage.	0
enable_default_callback	0/1	Print progress.	0
topk_sols	integer	Top-k solutions to keep.	(disabled)
best_energy_sols	0/integer	Keep optimal solutions (value = max count, 0 = unlimited).	(disabled)
all_sols	0/1	Keep all solutions, including assignments that violate cons() constraints ($2^n$ for $n$ binary variables).	(disabled)

Example:

#include <qbpp/qbpp.hpp>
#include <qbpp/exhaustive_solver.hpp>

auto solver = qbpp::ExhaustiveSolver(f);
auto sol = solver.search({{"target_energy", 0}});

ABS3 Solver Parameters

Parameter	Type	Description	Default
time_limit	float	Time limit in seconds.	10.0
target_energy	integer	Target energy.	(none)
enable_default_callback	0/1	Print progress.	0
topk_sols	integer	Top-k solutions to keep.	(disabled)
best_energy_sols	0/integer	Keep optimal solutions (value = max count, 0 = unlimited).	(disabled)
cpu_enable	0/1	Enable/disable CPU solver.	1
seed	integer	Random seed (for reproducible runs).	(random)
cpu_thread_count	integer	Number of CPU threads.	(auto)
block_count	integer	Number of GPU blocks.	(auto)
thread_count	integer	Number of GPU threads per block.	(auto)

Example:

#include <qbpp/qbpp.hpp>
#include <qbpp/abs3_solver.hpp>

auto solver = qbpp::ABS3Solver(f);
auto sol = solver.search({{"time_limit", 10}, {"target_energy", 0}});

Automatic CPU Thread Count

When thread_count (Easy Solver) or cpu_thread_count (ABS3 Solver) is not given, the number of threads follows the number of CPUs this process may use (at least 4 for Easy Solver and ABS3 Solver). That number is the smallest of the machine’s CPU count, the CPU affinity (taskset etc.), the CPU limit of a container, and the cores allotted by a job scheduler (NCPUS of PBS, SLURM_CPUS_PER_TASK of Slurm). A job on a shared node of a supercomputer uses only the cores allotted to it. For a large model, the CPU side of ABS3 Solver limits the automatically chosen number of threads to 16 (a cpu_thread_count you give is used as is). Exhaustive Solver uses the same number of CPUs.

Error Handling

• An unknown parameter key causes a std::runtime_error.
• An invalid value causes a std::invalid_argument: a value that is not a number for a numeric parameter (such as {"time_limit", "abc"}), a value other than 0/1 for a parameter that takes 0/1 (true/false are accepted), a fraction or an out-of-range value for an integer parameter, or a negative value for time_limit, thread_count, cpu_thread_count, block_count, or topk_sols (also 0 for thread_count of Easy Solver).