Search Parameters

All three solvers in PyQBPP — EasySolver, ExhaustiveSolver, and ABS3Solver — accept search parameters through search(). Parameters are passed as keyword arguments. Values can be strings, integers, or floats — they are automatically converted to strings before being passed to the backend.

Passing Parameters

Pass keyword arguments directly to search():

sol = solver.search(time_limit=10, target_energy=0)

Values can be mixed — strings, integers, and floats:

sol = solver.search(time_limit=2.5, target_energy="0")

When you need to build parameters programmatically, create a dict and pass it with **:

params = {}
params["time_limit"] = 10
params["target_energy"] = 0
sol = solver.search(**params)

No special Params object is needed — keyword arguments are all that is required. Internally, PyQBPP converts each value to a string and passes the key-value pairs to the solver.

Common Parameters

The following parameters are shared by all three solvers:

Parameter	Type	Description
target_energy	int	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	int (0/1)	Print newly obtained best solutions to stdout. Default: 0.
topk_sols	int	Keep up to N top-k solutions during the search.
best_energy_sols	int	Maximum number of best-energy solutions to keep. 0 = unlimited count.

EasySolver Parameters

Parameter	Type	Description	Default
time_limit	float	Time limit in seconds. 0 for no limit.	10.0
target_energy	int	Target energy.	(none)
enable_default_callback	int (0/1)	Print progress.	0
topk_sols	int	Top-k solutions to keep.	(disabled)
best_energy_sols	int	Best-energy solutions to keep.	(disabled)
thread_count	int	Number of CPU threads used for the search.	(auto)
seed	int	Random seed (for reproducible runs).	(random)
hint	Sol	A hint solution, used as the starting point of the search (see Passing a hint solution). None means no hint.	(none)

Example:

solver = qbpp.EasySolver(f)
sol = solver.search(time_limit=5, target_energy=0)

ExhaustiveSolver Parameters

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

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

Example:

solver = qbpp.ExhaustiveSolver(f)
sol = solver.search(target_energy=0)

Multiple solutions can be collected by combining parameters:

sol = solver.search(best_energy_sols=0, target_energy=0)
for s in sol.sols:
    print(s.energy)

ABS3Solver Parameters

Parameter	Type	Description	Default
time_limit	float	Time limit in seconds.	10.0
target_energy	int	Target energy.	(none)
enable_default_callback	int (0/1)	Print progress.	0
topk_sols	int	Top-k solutions to keep.	(disabled)
best_energy_sols	int	Keep optimal solutions (value = max count, 0 = unlimited).	(disabled)
cpu_enable	int (0/1)	Enable/disable CPU solver.	1
seed	int	Random seed (for reproducible runs).	(random)
hint	Sol	A hint solution, used as the starting point of the search (see Passing a hint solution). None means no hint.	(none)
cpu_thread_count	int	Number of CPU threads.	(auto)
block_count	int	Number of GPU blocks.	(auto)
thread_count	int	Number of GPU threads per block.	(auto)

Example:

solver = qbpp.ABS3Solver(f)
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 raises RuntimeError.
• An invalid value raises ValueError: a string 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 (the bools 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).
• None (except hint=None) or a value that is neither a number nor a string (such as a list) raises TypeError.