braket.aws.aws_quantum_task_batch module

class braket.aws.aws_quantum_task_batch.AwsQuantumTaskBatch(aws_session: AwsSession, device_arn: str, task_specifications: Circuit | Problem | OpenQasmProgram | BlackbirdProgram | AnalogHamiltonianSimulation | list[Circuit | Problem | OpenQasmProgram | BlackbirdProgram | AnalogHamiltonianSimulation], s3_destination_folder: AwsSession.S3DestinationFolder, shots: int, max_parallel: int, max_workers: int = 100, poll_timeout_seconds: float = 432000, poll_interval_seconds: float = 1, inputs: dict[str, float] | list[dict[str, float]] | None = None, gate_definitions: dict[tuple[Gate, QubitSet], PulseSequence] | list[dict[tuple[Gate, QubitSet], PulseSequence]] | None = None, reservation_arn: str | None = None, *aws_quantum_task_args: Any, **aws_quantum_task_kwargs: Any)[source]

Bases: QuantumTaskBatch

Executes a batch of quantum tasks in parallel.

Using this class can yield vast speedups over executing quantum tasks sequentially, and is particularly useful for computations that can be parallelized, such as calculating quantum gradients or statistics of terms in a Hamiltonian.

Note: there is no benefit to using this method with QPUs outside of their execution windows, since results will not be available until the window opens.

Creates a batch of quantum tasks.

Parameters:

  • aws_session (AwsSession) – AwsSession to connect to AWS with.

  • device_arn (str) – The ARN of the quantum device.

  • task_specifications (Union[Union[Circuit,Problem,OpenQasmProgram,BlackbirdProgram,AnalogHamiltonianSimulation],list[Union[Circuit,Problem,OpenQasmProgram,BlackbirdProgram,AnalogHamiltonianSimulation]]]) – # noqa Single instance or list of circuits, annealing problems, pulse sequences, or photonics program as specification of quantum task to run on device.

  • s3_destination_folder (AwsSession.S3DestinationFolder) – NamedTuple, with bucket for index 0 and key for index 1, that specifies the Amazon S3 bucket and folder to store quantum task results in.

  • shots (int) – The number of times to run the quantum task on the device. If the device is a simulator, this implies the state is sampled N times, where N = shots. shots=0 is only available on simulators and means that the simulator will compute the exact results based on the quantum task specification.

  • max_parallel (int) – The maximum number of quantum tasks to run on AWS in parallel. Batch creation will fail if this value is greater than the maximum allowed concurrent quantum tasks on the device.

  • max_workers (int) – The maximum number of thread pool workers. Default: 100

  • poll_timeout_seconds (float) – The polling timeout for AwsQuantumTask.result(), in seconds. Default: 5 days.

  • poll_interval_seconds (float) – The polling interval for results in seconds. Default: 1 second.

  • inputs (Union[dict[str, float], list[dict[str, float]]] | None) – Inputs to be passed along with the IR. If the IR supports inputs, the inputs will be updated with this value. Default: {}.

  • gate_definitions (Union[dict[tuple[Gate, QubitSet], PulseSequence], list[dict[tuple[Gate, QubitSet], PulseSequence]]] | None) – # noqa: E501 User-defined gate calibration. The calibration is defined for a particular Gate on a particular QubitSet and is represented by a PulseSequence. Default: None.

  • reservation_arn (str | None) – The reservation ARN provided by Braket Direct to reserve exclusive usage for the device to run the quantum task on. Note: If you are creating tasks in a job that itself was created reservation ARN, those tasks do not need to be created with the reservation ARN. Default: None.

  • *aws_quantum_task_args (Any) – Arbitrary args for QuantumTask.

  • **aws_quantum_task_kwargs (Any) – Arbitrary kwargs for QuantumTask.,

MAX_CONNECTIONS_DEFAULT = 100
MAX_RETRIES = 3
results(fail_unsuccessful: bool = False, max_retries: int = 3, use_cached_value: bool = True) → list[AwsQuantumTask][source]

Retrieves the result of every quantum task in the batch.

Polling for results happens in parallel; this method returns when all quantum tasks have reached a terminal state. The result of this method is cached.

Parameters:

  • fail_unsuccessful (bool) – If set to True, this method will fail if any quantum task in the batch fails to return a result even after max_retries retries.

  • max_retries (int) – Maximum number of times to retry any failed quantum tasks, i.e. any quantum tasks in the FAILED or CANCELLED state or that didn’t complete within the timeout. Default: 3.

  • use_cached_value (bool) – If False, will refetch the results from S3, even when results have already been cached. Default: True.

Returns:

list[AwsQuantumTask] – The results of all of the quantum tasks in the batch. FAILED, CANCELLED, or timed out quantum tasks will have a result of None

retry_unsuccessful_tasks() → bool[source]

Retries any quantum tasks in the batch without valid results.

This method should only be called after results() has been called at least once. The method will generate new quantum tasks for any failed quantum tasks, so self.task and self.results() may return different values after a call to this method.

Returns:

bool – Whether or not all retried quantum tasks completed successfully.

property tasks: list[AwsQuantumTask]

The quantum tasks in this batch, as a list of AwsQuantumTask objects

Type:

list[AwsQuantumTask]

property size: int

The number of quantum tasks in the batch

Type:

int

property unfinished: set[str]

Gets all the IDs of all the quantum tasks in the batch that have yet to complete.

Returns:

set[str] – The IDs of all the quantum tasks in the batch that have yet to complete.

property unsuccessful: set[str]

The IDs of all the FAILED, CANCELLED, or timed out quantum tasks in the batch.

Type:

set[str]