Skip to content

Results are limited to QUBO Solver v0.7.2

Product news
You are reading QUBO Solver v0.7.2, an older version of this documentation. Go to the latest version (v0.10.0)

Heuristic Drive

HeuristicDriveShaper constructs a fixed, closed-form analog drive directly from the diagonal of the QUBO matrix, without running any classical pulse optimization loop.

Compared with OptimizedDriveShaper, it is lighter and faster: it builds the drive analytically from the problem structure and the hardware limits. It is especially useful when the diagonal coefficients carry meaningful site-dependent bias information.

The shaper returns:

  • a generated Drive, ready to be simulated by the solver;
  • an empty QUBOSolution placeholder. The actual bitstrings, probabilities, and costs are produced later, when the quantum simulation is executed.

The shaper first normalizes the QUBO matrix: Qeff=QQoffdiag,maxQ_{\mathrm{eff}} = \frac{Q}{Q_{\mathrm{offdiag, max}}} where Qoffdiag,maxQ_{\mathrm{offdiag, max}} is the maximal off-diagonal coefficient of QQ, and extracts its diagonal: qi=(Qeff)ii.q_i = (Q_{\mathrm{eff}})_{ii}.

It then defines target final local detunings from these diagonal terms: di=−qi2,d_i = -\frac{q_i}{2}, Intuitively, the diagonal coefficients act as local biases, and the shaper translates them into a final detuning landscape.


When a Detuning Map Modulator (DMM) is available, the shaper encodes the final local targets exactly in the intended operating regime.

Let dmin⁡=min⁡idi,dmax⁡=max⁡idi.d_{\min} = \min_i d_i, \qquad d_{\max} = \max_i d_i.

The final detuning is decomposed into:

  • a global detuning δg(T)=dmax⁡\delta_g(T) = d_{\max},
  • a DMM detuning amplitude δdmm(T)=−(dmax⁡−dmin⁡)≤0\delta_{\mathrm{dmm}}(T) = -(d_{\max} - d_{\min}) \le 0,
  • and site-dependent weights wi=dmax⁡−didmax⁡−dmin⁡∈[0,1]w_i = \frac{d_{\max} - d_i}{d_{\max} - d_{\min}} \in [0,1].

This gives the final local detuning δi(T)=δg(T)+δdmm(T) wi=di.\delta_i(T) = \delta_g(T) + \delta_{\mathrm{dmm}}(T)\, w_i = d_i.

This sign convention is important: in this stack, DMM waveforms must be non-positive, so the DMM contribution is encoded as a negative quantity.

If the DMM spread is negligible, or if no effective DMM range is available, the DMM contribution is omitted.

If dmm=False, only a global detuning can be applied. In that case the shaper cannot realize each did_i individually, so it uses a single global final value: δg(T)=meani(di),\delta_g(T) = \mathrm{mean}_i(d_i), and no weighted detunings are declared.


How Ωmax⁡\Omega_{\max} is chosen

Section titled “How Ωmax⁡\Omega_{\max}Ωmax​ is chosen”

The plateau amplitude is derived from the detuning energy scale: Ωmax⁡(raw)=κmax⁡i∣di∣.\Omega_{\max}^{(\mathrm{raw})} = \kappa \max_i |d_i|.

The current fallback default is:

  • heuristic_kappa = 0.25

The shaper uses the full sequence duration allowed by the device and constructs simple interpolated waveforms.

The amplitude follows a flat-top profile: Ω(t)=[ε, Ωmax⁡, Ωmax⁡, ε]\Omega(t) = [\varepsilon,\ \Omega_{\max},\ \Omega_{\max},\ \varepsilon] with a very small ε>0\varepsilon > 0 at the endpoints rather than a strict zero.

The global detuning starts from the most negative hardware-allowed value and then ramps to the final encoded value: δg(t)=[δ0, δ0, δg(T), δg(T)],δ0=−∣δmax⁡∣.\delta_g(t) = [\delta_0,\ \delta_0,\ \delta_g(T),\ \delta_g(T)], \qquad \delta_0 = -|\delta_{\max}|.

This creates a simple three-stage pattern:

  1. initial negative detuning,
  2. drive-on plateau,
  3. sweep toward the encoded final bias.

When DMM is active and the final DMM amplitude is strictly negative, the shaper declares a weighted detuning map through constant_weighted_dmm(...), using the weights wiw_i and final detuning δdmm(T)\delta_{\mathrm{dmm}}(T).


Hardware bounds are enforced at compilation-time by QoolQit (TODO: link reference)


The register should be normalized to have a minimal inter-atomic distance equal to 1 (plus a margin, e.g. 1.001). This can be done using the parameter min_distance from EmbeddingConfig.


Field Type Description
drive_shaping_method DriveType \| str Must be set to DriveType.HEURISTIC or "heuristic"
dmm bool Enables site-dependent final detuning through weighted DMM detunings
heuristic_kappa float Proportionality factor used to derive Ωmax⁡\Omega_{\max} from the detuning scale; current fallback default: 0.25

These parameters are provided through DriveShapingConfig and read at drive generation time.


  • The method uses only the diagonal of the normalized QUBO matrix. Off-diagonal couplings are not used directly to shape the schedule.
  • With DMM enabled, the final local targets are encoded analytically through the global detuning plus a weighted negative DMM correction.
  • Without DMM, the method can only apply a single global final detuning, so the site-dependent targets are approximated by their mean.

import torch
from qubosolver import QUBOInstance
from qubosolver.config import SolverConfig, DriveShapingConfig
from qubosolver.solver import QuboSolver
from qubosolver.qubo_types import DriveType
Q = torch.tensor([
[-1.0, 0.5, 0.2],
[0.5, -2.0, 0.3],
[0.2, 0.3, -3.0],
])
instance = QUBOInstance(Q)
config = SolverConfig(
use_quantum=True,
drive_shaping=DriveShapingConfig(
drive_shaping_method=DriveType.HEURISTIC,
dmm=True,
heuristic_kappa=0.25,
),
)
solver = QuboSolver(instance, config)
solution = solver.solve()
print(solution)