BatchConfig

class BatchConfig(mode=BatchMode.MERGED, max_batch_size=None, max_concurrent_programs=None, _sort_programs=False)[source]

Bases: object

Configuration for circuit batching in ProgramEnsemble.run().

Choosing values

The two main knobs — max_concurrent_programs and max_batch_size — work together to shape merged backend submissions:

  • max_concurrent_programs controls how many programs run at once. It sizes the executor pool and the wait-for-all barrier.

  • max_batch_size caps the number of circuits in a single merged backend call.

The default (both unset) sizes the pool to fit every program (up to 256) and waits for all to submit — one merged call. For larger ensembles or to bound the merged-call payload, set the relevant knob.

Cloud submission (e.g. QoroService) typically benefits from one large merged job to amortize HTTP round trips. Pass -1 to unleash every program concurrently:

ensemble.run(
    batch_config=BatchConfig(max_concurrent_programs=-1),
)

Local simulators benefit from smaller merges that overlap circuit construction with execution. The default settings already do this.

Variables:

  • mode – Whether to merge circuit submissions across programs. Defaults to MERGED.

  • max_batch_size – Flush-trigger threshold on the pending circuit count, not a hard cap on merged-call size. When set, the coordinator fires a flush as soon as pending circuits reach this value, and the flush includes every circuit pending at that moment — so an actual merged submission may exceed max_batch_size when programs submit multiple circuits per call. None (the default) preserves the wait-for-all barrier behavior. Setting this value also couples the executor pool size to it (when max_concurrent_programs is unset): the pool is sized to min(max_batch_size, len(programs)) so the barrier predicate can fill the batch in one wave. Only meaningful when mode is MERGED.

  • max_concurrent_programs – Maximum number of programs running concurrently. When set to a positive integer, sizes the executor pool to that value and bypasses the default ensemble-size cap, letting the wait-for-all barrier admit a single merged submission of up to this many programs. Pass -1 to size the pool to the entire ensemble — the cloud-merge recipe — without having to query len(ensemble.programs) yourself; when combined with max_batch_size the pool is capped at min(max_batch_size, len(programs)) so the barrier and batch size align (one full wave per flush, no surplus threads). None (the default) auto-sizes the pool: max(len(programs), cpu_count + 4) in barrier mode (capped at 256), or min(max_batch_size, len(programs)) when max_batch_size is set. Explicit values above 1024 emit a UserWarning; the -1 form is silent because it’s an intentional opt-in. Only meaningful when mode is MERGED.

  • _sort_programs –

    Whether to sort programs by key before merging their circuits into a single backend call. Defaults to False.

    When False (default), circuits are merged in submission-arrival order — the order in which program threads reach the flush barrier. This preserves backward-compatible behavior.

    Set to True to merge circuits in a consistent, key-sorted order regardless of thread scheduling. This ensures that position-dependent seeds (e.g. seed + circuit_index in QiskitSimulator deterministic mode) map to the same circuit on every run, making seeded experiments fully reproducible. Only meaningful when mode is MERGED.

Attributes Summary

max_batch_size

max_concurrent_programs

mode

Attributes Documentation

max_batch_size: int | None = None
max_concurrent_programs: int | None = None
mode: BatchMode = 'merged'