Heuristic Drive

Heuristic Drive Shaper

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.

Principle

The shaper first normalizes the QUBO matrix: $Q_{\mathrm{eff}} = \frac{Q}{\lVert Q \rVert}$ and extracts its diagonal: $q_i = (Q_{\mathrm{eff}})_{ii}.$

It then defines target final local detunings from these diagonal terms: $d_i = -\alpha q_i,$ where $\alpha > 0$ is chosen automatically so that the resulting schedule remains compatible with the hardware bounds.

Intuitively, the diagonal coefficients act as local biases, and the shaper translates them into a final detuning landscape.

Final Detuning Encoding

With DMM enabled

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

Let $d_{\min} = \min_i d_i, \qquad d_{\max} = \max_i d_i.$

The final detuning is decomposed into:

a global detuning $\delta_g(T) = d_{\max}$,
a DMM detuning amplitude $\delta_{\mathrm{dmm}}(T) = -(d_{\max} - d_{\min}) \le 0$,
and site-dependent weights $w_i = \frac{d_{\max} - d_i}{d_{\max} - d_{\min}} \in [0,1]$.

This gives the final local detuning $\delta_i(T) = \delta_g(T) + \delta_{\mathrm{dmm}}(T)\, w_i = d_i.$

This sign convention is important: in this stack, WeightedDetuning 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.

Without DMM

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

How $\alpha$ is chosen

The shaper computes a conservative upper bound $\alpha_{\max}$ from the active hardware constraints, then applies a safety factor.

Let $q_{\min} = \min_i q_i, \qquad q_{\max} = \max_i q_i, \qquad q_{\mathrm{abs}} = \max_i |q_i|.$

The effective encoding must satisfy:

the global detuning bound,
the DMM detuning bound (when DMM is used),
the Rabi amplitude bound, since the amplitude scale is derived from the detuning scale.

The implementation therefore uses: $\alpha_{\max} = \min\!\left( \frac{\delta_{g,\max}}{q_{\mathrm{abs}}}, \; \frac{\delta_{\mathrm{dmm},\max}}{q_{\max}-q_{\min}}, \; \frac{\Omega_{\mathrm{hw},\max}}{\kappa\, q_{\mathrm{abs}}} \right),$ where only meaningful terms are included:

the DMM term is used only when DMM is enabled and $q_{\max} > q_{\min}$,
the amplitude term is used only when $\kappa > 0$,
degenerate zero-denominator cases are ignored safely.

The final value is then: $\alpha = \mathtt{heuristic\_alpha\_safety} \times \alpha_{\max}.$

In the current implementation, the fallback default is:

heuristic_alpha_safety = 0.6

If no valid upper bound can be formed, the code falls back to a very small positive value for $\alpha$.

How $\Omega_{\max}$ is chosen

The plateau amplitude is derived from the detuning energy scale: $\Omega_{\max}^{(\mathrm{raw})} = \kappa \max_i |d_i|.$

This value is then clamped to the hardware amplitude constraints of the global Rydberg channel. In particular, the implementation:

enforces the channel lower bound through min_avg_amp,
keeps a small safety margin below the hard upper limit (0.99 * max_amp).

The current fallback default is:

heuristic_kappa = 0.25

Schedule Shape

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

Amplitude

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

Global detuning

The global detuning starts from the most negative hardware-allowed value and then ramps to the final encoded value: $\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:

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

DMM weighted detuning

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

Hardware Bounds Used

The shaper reads the following hardware limits from the device:

global detuning bound from the global Rydberg channel (max_abs_detuning);
global amplitude bound from the same channel (max_amp);
minimum average amplitude from min_avg_amp;
DMM bound from the DMM channel bottom_detuning when available.

If no explicit DMM bound is found, the code falls back to the global detuning bound.

Configuration Parameters

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_alpha_safety`	`float`	Safety factor applied to $\alpha_{\max}$; current fallback default: `0.6`
`heuristic_kappa`	`float`	Proportionality factor used to derive $\Omega_{\max}$ from the detuning scale; current fallback default: `0.25`

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

Notes and Limitations

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.
Final values are still clipped to hardware-compatible ranges when needed.

Example

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_alpha_safety=0.6,
        heuristic_kappa=0.25,
    ),
)

solver = QuboSolver(instance, config)
solution = solver.solve()

print(solution)