qrunch.hybrid_jobs

The Hybrid jobs module makes it easy to get started running real quantum hardware through AWS hybrid jobs.

AWS hybrid jobs run your python user script on standard EC2 instances, and forwards calls automatically to the chosen quantum device. Convenience methods like save_job_result from the bracket SDK can be used in the user script, to save results that can be retrieved on successful job executions.

An example of a user script could be the following simple example, which samples a circuit directly through the backend, retrieves the result and saves it to the local folder ‘/home/test’. For the example to work two prerequisites are required:

  • The user must have a fully configured AWS cli installed.

  • The user must have docker installed and running.

from pathlib import Path

from braket.devices import Devices

from qrunch.hybrid_jobs.hybrid_job_runner import HybridJobRunner
from qrunch.quantum.backends.amazon.local_braket import LocalBraketBackend, LocalBraketBackendMethods
from qrunch.quantum.circuits.circuit import Circuit
from qrunch.quantum.gates import XGate


def my_script() -> None:
    simple_circuit = Circuit(4)
    simple_circuit.extend([XGate(0), XGate(2)])

    backend = LocalBraketBackend(LocalBraketBackendMethods.STATE_VECTOR)

    job = backend.run(simple_circuit, shots=1000)

    result = job.result()

    measurement = result.measurements[0]

    HybridRunner.save_result(measurement.to_binary_dict())


if __name__ == "__main__":
    hybrid_runner = HybridRunner(
        result_folder=Path.home() / "test",
        device=Devices.Amazon.SV1,
        repository_name="qrunch",
        region="us-west-2",
    )
    hybrid_runner.run_hybrid_job(my_script)

Notice that since a local backend is used no calls to actual hardware is made, but the script can still be executed, as a hybrid job, effectively running the script on an EC2 instance. However, this is a cheap way to test and get familiar with the AWS Hybrid Job ecosystem. The above example is a minimal example, but entire python modules can be used as input script. For more details see the AWS Braket and Hybrid jobs documentation.

Note that the function my_script() is the actual user script that will run on Amazon Braket Hybrid Job. The only things that are needed in order to run this as desired is:

  1. The desired output of the script should be saved using the HybridRunner.save_result() method, instead of returning it from the function.

  2. The HybridRunner class is initialized with the desired quantum device (or simulator), and related settings. The class is in charge of pushing the given docker image to the AWS Elastic Container Repository (ECR), of the region of the Quantum Device that will be used. If None (default) is given, a default Docker image is created.

  3. A hybrid job is created and the function is run by passing it as an argument to the :py:meth: HybridRunner.run_hybrid_job method.

To ease the process of creating a docker image that can run hybrid jobs (including the Kvantify Qrunch) and uploading it to ECR, we have created the HybridJobDockerImage.Builder builder class.

Modules

docker_image

Logic for creating a docker file that can be used to run a hybrid job on.

hybrid_job_runner

Module containing logic for conveniently running jobs as Amazon Braket Hybris Job.