ProgramSet

class braket.program_sets.program_set.ProgramSet(programs, shots_per_executable=None)[source]

Bases: object

A set of programs to be run together on a device.

Parameters:

programs (list[CircuitBinding | Circuit] | CircuitBinding) – A list of circuit bindings or circuits to execute. It is also possible to provide a single circuit binding. Note: circuits cannot have result types.
shots_per_executable (int | None) – The number of shots to run each executable; this will be used to enforce the total shots on task creation. If not provided, the only validation at task creation will be divisibility by number of executables.

to_ir(*, gate_definitions=None)[source]

Serializes the program set into a form that can run on a Braket device.

Parameters:: gate_definitions (Mapping[tuple[Gate, QubitSet], PulseSequence] | None) – The calibration data for the device. default: None.
Return type:: ProgramSet
Returns:: braket.ir.openqasm.ProgramSet – The serialized program set.

property entries: list[CircuitBinding | Circuit]

The circuit bindings or circuits in this program set

Type:: list[CircuitBinding | Circuit]

property total_executables: int

The total number of executables in this program set

Type:: int

property shots_per_executable: int | None

The number of shots to run each executable in this program set

Type:: int

property total_shots: int

The total number of shots across all executables in this program set, if shots_per_executable was provided.

Type:: int

enumerate_executables()[source]

Yield (binding_index, parameter_set_index, observable_index) tuples in order, one per executable.

The iteration order is: iterate over self.entries; within each entry, iterate over parameter set indices; within each parameter set index, iterate over observable indices. The total number of yields is self.total_executables.

For Circuit``s and ``CircuitBinding``s with no input sets, ``parameter_set_index is 0. For entries with no observables, observable_index is 0. For CircuitBinding``s with a ``Sum Hamiltonian, observable_index ranges over the summands.

This ordering is used by split to build its index map and by ProgramSetQuantumTaskResult.merge to merge results back into the original shape.

Yields:: tuple[int, int, int] – (binding_index, parameter_set_index, observable_index).

split(max_executables)[source]

Split this program set into program sets of at most max_executables executables, alongside a map that records the position in the original program set of each executable in each of the generated program sets.

When a single parameter set index of a CircuitBinding would by itself exceed max_executables due to its observable list or Sum Hamiltonian being larger than the budget, the observable list is split into chunks of at most max_executables entries (Sum summands are sliced with coefficients preserved). Observable splitting is only performed when necessary; otherwise the full observable list or Sum is kept intact.

The indices in the list of positions take values in the range [0, total_executables - 1].

Parameters:: max_executables (int) – The maximum number of executables per program set. Must be positive.
Return type:: tuple[list[ProgramSet], list[list[int]]]
Returns:: tuple[list[ProgramSet], list[list[int]]] – (program_sets, index_map). index_map[k][j] is the index of the executable that the j-th executable of program_sets[k] represents. If this program set already fits within max_executables, the returned program-set list is [self] and the index_map is [[0, 1, ..., total_executables - 1]].
Raises:: ValueError – If max_executables is not positive.

Examples

>>> ps = ProgramSet([
...     CircuitBinding(c1, inputs1, obs1),  # 100 param sets, 4 observables
...     CircuitBinding(c2, inputs2, obs2),  # 50 param sets, 2 observables
... ])
>>> subs, index_map = ps.split(120)
>>> [s.total_executables for s in subs]
[120, 120, 120, 120, 20]
>>> sum(len(m) for m in index_map) == ps.total_executables
True

static zip(circuits, *, input_sets=None, observables=None, shots_per_executable=None)[source]

Constructs a batch of circuits from a list of circuits and optionally an input set and/or observable for each; alternatively, a single CircuitBinding can be provided and paired with corresponding observables.

Parameters:

circuits (Sequence[Circuit] | CircuitBinding) – The parametrized circuit with parameters or set of fixed circuits to run with multiple observables.
input_sets (Sequence[Mapping[str, float]] | None) – The inputs to the circuit; must match number of circuits if provided. Must be empty if circuits is a CircuitBinding.
observables (Sequence[Observable | None] | None) – A set of observables to measure with the circuits; must match number of circuits if provided.
shots_per_executable (int | None) – The number of shots to run each executable; this will be used to enforce the total shots on task creation. If not provided, the only validation at task creation will be divisibility by number of executables.

Return type:

ProgramSet

Returns:

ProgramSet – a program set consisting of matching sets of circuits, inputs and observables.

static product(circuits, observables, shots_per_executable=None)[source]

Constructs a program set from the Cartesian product of the given observables with the given circuits or bindings.

If an entry of the list is a single circuit, then the resulting program will consist of that circuit and all the observables; if an entry is a circuit binding, then the result program will be the Cartesian product of the binding’s input values and observables.

Parameters:

circuits (Sequence[Circuit | CircuitBinding]) – The parametrized circuit with parameters or set of fixed circuits to run with multiple observables.
observables (Sum | Sequence[Observable]) – A set of observables to measure with the circuits.
shots_per_executable (int | None) – The number of shots to run each executable; this will be used to enforce the total shots on task creation. If not provided, the only validation at task creation will be divisibility by number of executables.

Return type:

ProgramSet

Returns:

ProgramSet – a program set consisting of Cartesian products of the given observables with the given circuits or bindings.