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 | Program | str] | CircuitBinding | Program) – A list of circuit bindings, circuits, OpenQASM programs, or OpenQASM strings to execute. It is also possible to provide a single circuit binding or OpenQASM program. OpenQASM program input values must be equal-length lists. 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.

Raises:

ValueError – If a circuit has result types, or if an OpenQASM program’s inputs are not equal-length lists.

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 | Program | str]

The entries in this program set.

Type:: list[CircuitBinding | Circuit | Program | str]

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, OpenQASM strings, OpenQASM ``Program``s with no inputs, 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. OpenQASM Program input lists are sliced into contiguous chunks when necessary.

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 (Observable | PauliString | str | Sum) – Sequence[Observable | PauliString | str]): A single observable, Pauli string, Pauli word, or a sequence 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.
observables (Observable | PauliString | str | Sum | Sequence[Observable | PauliString | str])

Return type:

ProgramSet

Returns:

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