qoqo_for_braket

Qoqo interface to the AWS braket service.

Classes

`BraketBackend`([device, aws_session, ...])	Qoqo backend execution qoqo objects on AWS braket.
`QueuedCircuitRun`(session, task, metadata)	Queued Result of the circuit.
`QueuedHybridRun`(session, job, metadata, ...)	Queued Result of the running a QuantumProgram with a hybrid job.
`QueuedProgramRun`(measurement, queued_circuits)	Queued Result of the measurement.

class qoqo_for_braket.BraketBackend(device: str | None = None, aws_session: AwsSession | None = None, verbatim_mode: bool = False, batch_mode: bool = False, use_hybrid_jobs: bool = True, virtual_z_replacement: bool | None = None)[source]

Qoqo backend execution qoqo objects on AWS braket.

Parameters:

device -- The AWS device the circuit should run on. provided as aws arn or for local devices starting with "local:" as for the braket QuantumJob
aws_session -- An optional braket AwsSession. If set to None AwsSession will be created automatically.
verbatim_mode -- Only use native gates for real devices and block recompilation by devices
batch_mode -- Run circuits in batch mode when running measurements. Does not work when circuits define different numbers of shots.

Initialise the BraketBackend class.

Parameters:

device -- Optional ARN of the Braket device to use. If none is provided, the default LocalSimulator will be used.
aws_session -- Optional AwsSession to use. If none is provided, a new one will be created
verbatim_mode -- Whether to use verbatim boxes to avoid recompilation
batch_mode -- Run circuits in batch mode when running measurements. Does not work when circuits define different numbers of shots.
use_hybrid_jobs -- Uses hybrid jobs to run measurements and register measurements.
virtual_z_replacement -- On platforms where the RotateXY gate is available and the natural two-qubit gate is diagonal in the Z-basis, it is possible to replace RotateZ gates by virtual changes (rotations) of the qubit basis in the XY-Plane. This is what we implement here. Setting this to True/False will enable the virtual Z replacement with/without the final rotation at the end of the circuit. Leaving this to its default (None) won't use the virtual Z replacement.

__create_device() → LocalSimulator | AwsDevice

Creates the device and returns it.

Returns:: The instanciated device (either an AwsDevice or a LocalSimulator)
Raises:: ValueError -- Device specified isn't allowed. You can allow it by calling the allow_use_actual_hardware function, but please be aware that this may incur significant monetary charges.

__init__(device: str | None = None, aws_session: AwsSession | None = None, verbatim_mode: bool = False, batch_mode: bool = False, use_hybrid_jobs: bool = True, virtual_z_replacement: bool | None = None) → None[source]

Initialise the BraketBackend class.

Parameters:

device -- Optional ARN of the Braket device to use. If none is provided, the default LocalSimulator will be used.
aws_session -- Optional AwsSession to use. If none is provided, a new one will be created
verbatim_mode -- Whether to use verbatim boxes to avoid recompilation
batch_mode -- Run circuits in batch mode when running measurements. Does not work when circuits define different numbers of shots.
use_hybrid_jobs -- Uses hybrid jobs to run measurements and register measurements.
virtual_z_replacement -- On platforms where the RotateXY gate is available and the natural two-qubit gate is diagonal in the Z-basis, it is possible to replace RotateZ gates by virtual changes (rotations) of the qubit basis in the XY-Plane. This is what we implement here. Setting this to True/False will enable the virtual Z replacement with/without the final rotation at the end of the circuit. Leaving this to its default (None) won't use the virtual Z replacement.

__weakref__: list of weak references to the object

_prepare_circuit_for_run(circuit: Circuit) → Tuple[Circuit, int, str, Circuit][source]

Prepares a braket circuit for running on braket.

Parameters:: circuit (Circuit) -- The qoqo Circuit that should be run.
Returns:: The braket circuit, the number of shots, the readout and the InputBit circuit.
Return type:: (BraketCircuit, int, str, Circuit)

_run_circuit(circuit: Circuit) → Tuple[AwsQuantumTask, Dict[str, Any], Circuit][source]

Simulate a Circuit on a AWS backend.

The default number of shots for the simulation is 100. Any kind of Measurement instruction only works as intended if it is the last instruction in the Circuit. Currently only one simulation is performed, meaning different measurements on different registers are not supported.

Parameters:: circuit (Circuit) -- the Circuit to simulate.
Returns:: (AwsQuantumTask, {readout, output_registers, output_lengths}, input_bit_circuit)
Raises:: ValueError -- Circuit contains multiple ways to set the number of measurements

_run_circuits_batch(circuits: List[Circuit]) → Tuple[AwsQuantumTaskBatch, List[Dict[str, Any]], Circuit][source]

Run a list of Circuits on a AWS backend in batch mode.

The default number of shots for the simulation is 100. Any kind of Measurement instruction only works as intended if it is the last instruction in the Circuit. Currently only one simulation is performed, meaning different measurements on different registers are not supported.

Parameters:: circuits (List[Circuit]) -- the Circuits to simulate.
Returns:: (AwsQuantumTaskBatch, {readout, output_registers}, input_bit_circuit)
Raises:: ValueError -- Circuit contains multiple ways to set the number of measurements

_run_measurement_registers_hybrid(measurement: Any, wait_until_complete: bool = True) → AwsQuantumJob[source]

Run all circuits of a measurement with the AWS Braket backend using hybrid jobs.

Using hybrid jobs allows us to naturally group the circuits from a measurement.

Parameters:

measurement -- The measurement that is run.
wait_until_complete -- Whether to wait for the job to complete. Should be False when using queued runs.

Returns:

AwsQuantumJob

_set_up_registers(circuit: Circuit) → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]], Dict[str, int], Dict[str, int], Dict[str, int]][source]

Sets up the output registers for a circuit running on braket.

Parameters:

circuit (Circuit) -- The qoqo Circuit for which to prepare the registers.

Returns:

(Dict[str, List[List[bool]]], Dict[str, List[List[float]]],

Dict[str, List[List[complex]]]): The output bit register, float: register and complex register.

allow_use_actual_hardware() → None[source]: Allow the use of actual hardware - will cost money.

change_max_circuit_length(length: int) → None[source]

Change the maximum circuit length allowed.

Parameters:: length -- new maximum allowed length of circuit

change_max_shots(shots: int) → None[source]

Change the maximum number of shots allowed.

Parameters:: shots -- new maximum allowed number of shots

disallow_use_actual_hardware() → None[source]: Disallow the use of actual hardware.

force_ionq_verbatim() → None[source]: Force the use of ionq verbatim. Mostly used for testing purposes.

force_iqm_verbatim() → None[source]: Force the use of iqm verbatim. Mostly used for testing purposes.

force_oqc_verbatim() → None[source]: Force the use of oqc verbatim. Mostly used for testing purposes.

force_rigetti_verbatim() → None[source]: Force the use of rigetti verbatim. Mostly used for testing purposes.

get_virtual_z_replacement() → bool | None[source]

Return the virtual Z replacement mode.

Returns:: The virtual Z replacement mode (True or False)

run_circuit(circuit: Circuit) → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]][source]

Simulate a Circuit on a AWS backend.

The default number of shots for the simulation is 100. Any kind of Measurement instruction only works as intended if it is the last instruction in the Circuit. Currently only one simulation is performed, meaning different measurements on different registers are not supported.

Parameters:

circuit (Circuit) -- the Circuit to simulate.

Returns:

Tuple[Dict[str, List[List[bool]]],: Dict[str, List[List[float]]], Dict[str, List[List[complex]]]]: bit, float and complex registers dictionaries.

run_circuit_queued(circuit: Circuit) → QueuedCircuitRun[source]

Run a Circuit on a AWS backend and return a queued Job Result.

The default number of shots for the simulation is 100. Any kind of Measurement instruction only works as intended if it are the last instructions in the Circuit. Currently only one simulation is performed, meaning different measurements on different registers are not supported.

Parameters:: circuit (Circuit) -- the Circuit to simulate.
Returns:: QueuedCircuitRun

run_circuits_batch(circuits: List[Circuit]) → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]][source]

Run a list of Circuits on a AWS backend in batch mode.

The default number of shots for the simulation is 100. Any kind of Measurement instruction only works as intended if it is the last instruction in the Circuit. Currently only one simulation is performed, meaning different measurements on different registers are not supported.

Parameters:

circuits (List[Circuit]) -- the Circuit to simulate.

Returns:

Tuple[Dict[str, List[List[bool]]],: Dict[str, List[List[float]]], Dict[str, List[List[complex]]]]: bit, float and complex registers dictionaries.

run_measurement(measurement: Any) → Dict[str, float] | None[source]

Run a circuit with the AWS Braket backend.

Parameters:: measurement -- The measurement that is run.
Returns:: Optional[Dict[str, float]]

run_measurement_queued(measurement: Any) → QueuedProgramRun[source]

Run a qoqo measurement on a AWS backend and return a queued Job Result.

The default number of shots for the simulation is 100. Any kind of Measurement instruction only works as intended if it are the last instructions in the Circuit. Currently only one simulation is performed, meaning different measurements on different registers are not supported.

Parameters:: measurement (qoqo.measurement) -- the measurement to simulate.
Returns:: QueuedProgramRun

run_measurement_registers(measurement: Any) → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]][source]

Run all circuits of a measurement with the AWS Braket backend.

Parameters:

measurement -- The measurement that is run.

Returns:

Tuple[Dict[str, List[List[bool]]],: Dict[str, List[List[float]]], Dict[str, List[List[complex]]]]

run_measurement_registers_hybrid(measurement: Any) → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]] | Dict[str, float][source]

Run all circuits of a measurement with the AWS Braket backend using hybrid jobs.

Using hybrid jobs allows us to naturally group the circuits from a measurement.

Parameters:

measurement -- The measurement that is run.

Returns:

Union[

Tuple[: Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]],

], Dict[str, float],

]

run_measurement_registers_hybrid_queued(measurement: Any) → QueuedHybridRun[source]

Run all circuits of a measurement with the AWS Braket backend using hybrid jobs.

Using hybrid jobs allows us to naturally group the circuits from a measurement.

Parameters:: measurement -- The measurement that is run.
Returns:: QueuedHybridRun

run_program(program: QuantumProgram, params_values: List[float] | List[List[float]]) → List[Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]] | Dict[str, float]] | None[source]

Run a qoqo quantum program on a AWS backend multiple times.

It can handle QuantumProgram instances containing any kind of measurement. The list of lists of parameters will be used to call program.run(self, params) or program.run_registers(self, params) as many times as the number of sublists. The return type will change accordingly.

If no parameters values are provided, a normal call program.run(self, []) call will be executed.

Parameters:

program (QuantumProgram) -- the qoqo quantum program to run.
params_values (Union[List[float], List[List[float]]]) -- the parameters values to pass
program. (to the quantum)

Returns:

Optional[

List[

Union[

Tuple[: Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]],

], Dict[str, float],

]

]: list of dictionaries (or tuples of dictionaries) containing the

run results.

run_program_queued(program: QuantumProgram, params_values: List[List[float]], hybrid: bool = False) → List[QueuedProgramRun | QueuedHybridRun][source]

Run a qoqo quantum program on a AWS backend multiple times return a list of queued Jobs.

This effectively performs the same operations as run_program but returns queued results.

The hybrid parameter can specify whether to run the program in hybrid mode or not.

Parameters:

program (QuantumProgram) -- the qoqo quantum program to run.
params_values (List[List[float]]) -- the parameters values to pass to the quantum program.
hybrid (bool) -- whether to run the program in hybrid mode.

Raises:

ValueError -- incorrect length of params_values compared to program's input parameter names.

Returns:

List[Union[QueuedProgramRun, QueuedHybridRun]]

set_virtual_z_replacement(replacement: bool) → None[source]

Set the virtual Z replacement mode.

On platforms where the RotateXY gate is available and the natural two-qubit gate is diagonal in the Z-basis, it is possible to replace RotateZ gates by virtual changes (rotations) of the qubit basis in the XY-Plane. This is what we implement here. Setting this to True/False will enable the virtual Z replacement with/without the final rotation at the end of the circuit. Leaving this to its default (None) won't use the virtual Z replacement.

Parameters:: replacement (Optional[bool]) -- The virtual Z replacement mode.

class qoqo_for_braket.QueuedCircuitRun(session: AwsSession, task: QuantumTask | None, metadata: Dict[Any, Any])[source]

Queued Result of the circuit.

Initialise the QueuedCircuitRun class.

Parameters:

session -- Braket AwsSession to use
task -- Braket QuantumTask to query
metadata -- Additional information about the circuit

__init__(session: AwsSession, task: QuantumTask | None, metadata: Dict[Any, Any]) → None[source]

Initialise the QueuedCircuitRun class.

Parameters:

session -- Braket AwsSession to use
task -- Braket QuantumTask to query
metadata -- Additional information about the circuit

__weakref__: list of weak references to the object

static from_json(string: str) → QueuedCircuitRun[source]

Convert a json string to an instance of QueuedCircuitRun.

Parameters:: string -- json string to convert.
Returns:: converted json string
Return type:: QueuedCircuitRun

poll_result() → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]] | None[source]

Poll the result once.

Returns:

Optional[Tuple[Dict[str, List[List[bool]]],: Dict[str, List[List[float]]], Dict[str, List[List[complex]]],]]: Result if task was successful.

Raises:

RuntimeError -- job failed or cancelled

to_json() → str[source]

Convert self to a json string.

Returns:: self as a json string
Return type:: str

class qoqo_for_braket.QueuedHybridRun(session: ~braket.aws.aws_session.AwsSession, job: ~braket.jobs.quantum_job.QuantumJob, metadata: ~typing.Dict[~typing.Any, ~typing.Any], measurement: <module 'measurements'>)[source]

Queued Result of the running a QuantumProgram with a hybrid job.

Initialise the QueuedCircuitRun class.

Parameters:

session -- Braket AwsSession to use
job -- Braket QuantumJob to query
metadata -- Additional information about the circuit
measurement -- The qoqo measurement to be run

__init__(session: ~braket.aws.aws_session.AwsSession, job: ~braket.jobs.quantum_job.QuantumJob, metadata: ~typing.Dict[~typing.Any, ~typing.Any], measurement: <module 'measurements'>) → None[source]

Initialise the QueuedCircuitRun class.

Parameters:

session -- Braket AwsSession to use
job -- Braket QuantumJob to query
metadata -- Additional information about the circuit
measurement -- The qoqo measurement to be run

__weakref__: list of weak references to the object

delete_tmp_folder() → None[source]: Delete the folder created by AWS for the LocalQuantumJob.

static from_json(string: str) → QueuedHybridRun[source]

Convert a json string to an instance of QueuedHybridRun.

Parameters:: string -- json string to convert.
Returns:: converted json string
Return type:: QueuedHybridRun

poll_result() → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]] | Dict[str, float] | None[source]

Poll the result once.

Returns:

Optional[

Union[

Tuple[: Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]],

], Dict[str, float],

]

]: Result if task was successful.

Raises:

RuntimeError -- job failed or cancelled

to_json() → str[source]

Convert self to a json string.

Returns:: self as a json string
Return type:: str

class qoqo_for_braket.QueuedProgramRun(measurement: Any, queued_circuits: List[QueuedCircuitRun])[source]

Queued Result of the measurement.

Initialise the QueuedProgramRun class.

Parameters:

measurement -- the qoqo Measurement to run
queued_circuits -- the list of associated queued circuits

__init__(measurement: Any, queued_circuits: List[QueuedCircuitRun]) → None[source]

Initialise the QueuedProgramRun class.

Parameters:

measurement -- the qoqo Measurement to run
queued_circuits -- the list of associated queued circuits

__weakref__: list of weak references to the object

static from_json(string: str) → QueuedProgramRun[source]

Convert a json string to an instance of QueuedProgramRun.

Parameters:: string -- json string to convert.
Returns:: converted json string
Return type:: QueuedProgramRun

poll_result() → Tuple[Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]]] | Dict[str, float] | None[source]

Poll the result once.

Returns:

Optional[

Union[

Tuple[: Dict[str, List[List[bool]]], Dict[str, List[List[float]]], Dict[str, List[List[complex]]],

], Dict[str, float],

]

]: Result if all tasks were successful.

Raises:

RuntimeError -- job failed or cancelled

to_json() → str[source]

Convert self to a json string.

Returns:: self as a json string
Return type:: str