QUBO and Ising Solvers
unitarylab.library.qubocore provides eight CPU heuristic solvers. They all minimize the Ising energy
Convert QUBO problems to this convention first. Definitions of cross terms and constant terms can differ across tools, so verify an energy value on a small problem after conversion.
Minimal example
import numpy as np
from unitarylab.library import qubocore
J = np.array([
[0.0, 1.0, -0.5],
[1.0, 0.0, 0.25],
[-0.5, 0.25, 0.0],
])
h = np.array([0.1, 0.0, -0.2])
result = qubocore.bsb_minimize(J, h, n_steps=100, n_agents=4, seed=7)
print(result)All solvers accept NumPy-compatible real-valued inputs and return dictionaries. Common fields are:
| Field | Shape | Description |
|---|---|---|
spins | (N,) | Spin configuration with the lowest energy |
energy | Scalar | Ising energy corresponding to spins |
all_spins | (n_agents, N) | Candidate configurations retained for each agent |
all_energies | (n_agents,) | Energy of each candidate configuration |
n_steps | Scalar | Number of iterations used for this solve |
Method-specific diagnostic fields are not part of the common result contract; use the fields listed above for portable access.
Solvers and parameters
| Entry | Method | Main method-specific parameters |
|---|---|---|
bsb_minimize | Ballistic Simulated Bifurcation | n_steps=1000, dt=1.0, c0=None, a0=1.0 |
dsb_minimize | Discrete Simulated Bifurcation | n_steps=1000, dt=1.0, c0=None, a0=1.0 |
asb_minimize | Adiabatic Simulated Bifurcation | n_steps=1000, dt=0.5, xi0=None, a0=1.0 |
simcim_minimize | SimCIM | dt=0.01, momentum=0.9, epsilon=0.05, sigma=0.03, v_start=0, v_end=2, x_sat=1 |
cim_minimize | Coherent Ising machine | p=2, A_s=1, epsilon=0.1, n_steps=3000, dt=0.01 |
oim_minimize | Oscillator Ising machine | K_c=None, K_s_final=5, K_s_schedule="linear", integrator="rk4", sigma=0 |
phia_minimize | Parallel heat-bath inspired annealing | n_steps=200, L=30, eps=0.01, gamma=5, beta_init=0.1, beta_final=15 |
gahmc_minimize | Generalized-acceptance HMC | total_trajectory_length=100, beta=10, n_samples=500 |
In addition to the listed parameters, all methods accept J, optional h, n_agents, and seed; defaults for n_agents differ by method. seed=None uses the system random source; an integer seed makes experiments reproducible. asb_minimize() does not support local field h.
Input constraints
Jmust be a real square matrix.hmust be a one-dimensional real vector of matching length; complex inputs raiseTypeError.- Numeric parameters must be finite; step counts, agent counts, and sample counts must be integers.
- If
c0,xi0, orK_cisNone, the solver calibrates it automatically; explicit values must be positive. K_s_scheduleandintegratoraccept only their supported string options.- Heuristic methods do not guarantee a global optimum. Increase
n_agents, try multiple seeds, and recompute candidate energies using the common energy formula.
Choosing a method
Compare multiple solvers with their default parameters, then adjust step and agent counts for the problem size. Methods with normalize_j=True normalize the coupling matrix internally; use the original values to recompute final energies when comparing methods.