Strategy configuration¶

A strategy is represented by qbalance.StrategySpec. It is immutable and combines compilation, suppression, mitigation, cutting, and runtime knobs.

Fields¶

Field	Type	Default	Notes
`optimization_level`	`int`	`1`	Qiskit preset optimization level, `0..3`.
`layout_method`	`str	None`	`None`
`routing_method`	`str	None`	`None`
`translation_method`	`str	None`	`None`
`seed_transpiler`	`int	None`	`0`
`pauli_twirling`	`bool`	`False`	Applies best-effort Pauli twirling before compilation.
`num_twirls`	`int`	`1`	Must be at least `1`.
`dynamical_decoupling`	`bool`	`False`	Adds a DD pass manager after compilation when supported.
`dd_sequence`	`str`	`"XY4"`	DD sequence name such as `"XY4"`, `"XX"`, or `"YY"`.
`measurement_twirling`	`bool`	`False`	Applies measurement bit flips and records a flip map for untwirling counts.
`seed_suppression`	`int	None`	`0`
`mthree`	`bool`	`False`	Enables M3 mitigation during execution workflows.
`zne`	`bool`	`False`	Enables zero-noise extrapolation during execution workflows.
`zne_factors`	`tuple[float, ...]`	`(1.0, 2.0, 3.0)`	Must be finite, sorted, include `1.0`, and be `>= 1.0` when `zne=True`.
`zne_degree`	`int`	`1`	Must be non-negative generally and `1 <= degree < len(zne_factors)` when `zne=True`.
`cutting`	`bool`	`False`	Enables best-effort circuit cutting before compilation.
`max_subcircuit_qubits`	`int	None`	`None`
`resilience_level`	`int	None`	`None`

Boolean values are rejected for integer-like fields even though Python treats bool as a subclass of int.

Default candidate generation¶

qbalance.search.default_candidate_strategies(max_candidates=24, seed=0) builds a deterministic candidate pool that includes:

optimization-level sweeps,
SABRE routing/layout combinations,
qbalance noise-aware layout candidates,
Pauli twirling, dynamical decoupling, and measurement-twirling variants,
optional M3/ZNE mitigation candidates,
an optional cutting candidate.

The first candidate is stable and the remaining candidates are shuffled deterministically by seed.

Explicit strategy sets¶

Use explicit strategies when you need a reproducible curated search space:

from qbalance import StrategySpec, Workload, load_data

strategies = [
    StrategySpec(optimization_level=1, routing_method="sabre"),
    StrategySpec(
        optimization_level=2,
        layout_method="qbalance_noise_aware",
        routing_method="sabre",
    ),
]

balanced = (
    Workload.from_dataset(load_data("tiny"))
    .set_target("fake:generic:5")
    .adjust(strategies=strategies)
)

Workload.adjust(strategies=...) accepts any iterable of StrategySpec objects or mapping objects. Inputs are validated and duplicate strategies are removed while preserving first-seen order.

Strategy JSON formats¶

qbalance.load_strategy_specs(path) accepts these JSON shapes:

Single strategy object¶

{"optimization_level": 1, "routing_method": "sabre"}

List of strategy objects¶

[
  {"optimization_level": 1, "routing_method": "sabre"},
  {"optimization_level": 2, "measurement_twirling": true}
]

Wrapped list¶

{
  "strategies": [
    {"optimization_level": 1, "routing_method": "sabre"},
    {"optimization_level": 2, "measurement_twirling": true}
  ]
}

Saved qbalance outputs¶

The loader can also extract strategies from saved balanced workload result files containing selections and from matrix JSON files containing results with strategy entries. This makes it possible to reuse selected or benchmarked strategies in later runs.