From 6719252d2cdac3b9894930262cc751547eda0889 Mon Sep 17 00:00:00 2001 From: mbeach-aws <85963088+mbeach-aws@users.noreply.github.com> Date: Thu, 2 Nov 2023 13:48:07 -0400 Subject: [PATCH] Add hybrid jobs to Braket QAOA demo (#947) **Title:** Computing gradients in parallel with Amazon Braket **Summary:** Adding hybrid jobs to Braket QAOA demo. **Relevant references:** **Possible Drawbacks:** **Related GitHub Issues:** --------- Co-authored-by: Guillermo Alonso-Linaje <65235481+KetpuntoG@users.noreply.github.com> --- _static/qaoa_training.png | Bin 0 -> 19021 bytes .../braket-parallel-gradients.metadata.json | 7 +- demonstrations/braket-parallel-gradients.py | 192 +++++++++++++++++- demonstrations/braket/qaoa_training.png | Bin 0 -> 32402 bytes 4 files changed, 186 insertions(+), 13 deletions(-) create mode 100644 _static/qaoa_training.png create mode 100644 demonstrations/braket/qaoa_training.png diff --git a/_static/qaoa_training.png b/_static/qaoa_training.png new file mode 100644 index 0000000000000000000000000000000000000000..fc69b63700a111dbf253a747fa0e4be9e4d54def GIT binary patch literal 19021 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 literal 0 HcmV?d00001 diff --git a/demonstrations/braket-parallel-gradients.metadata.json b/demonstrations/braket-parallel-gradients.metadata.json index 8d8f67184d..ca034abae5 100644 --- a/demonstrations/braket-parallel-gradients.metadata.json +++ b/demonstrations/braket-parallel-gradients.metadata.json @@ -6,10 +6,13 @@ }, { "id": "maria_schuld" + }, + { + "id": "matthew_beach" } ], "dateOfPublication": "2020-12-08T00:00:00+00:00", - "dateOfLastModification": "2021-09-30T00:00:00+00:00", + "dateOfLastModification": "2023-10-30T00:00:00+00:00", "categories": [ "Devices and Performance" ], @@ -45,4 +48,4 @@ "logo": "/_static/hardware_logos/aws.png" } ] -} +} \ No newline at end of file diff --git a/demonstrations/braket-parallel-gradients.py b/demonstrations/braket-parallel-gradients.py index dc736d561d..d218d911fe 100644 --- a/demonstrations/braket-parallel-gradients.py +++ b/demonstrations/braket-parallel-gradients.py @@ -92,13 +92,9 @@ `__ for accessing Braket from Python. -Let's load the SV1 simulator in PennyLane with 25 qubits. We must specify both the ARN and -the address of the `S3 bucket `__ where results are to be stored: +Let's load the SV1 simulator in PennyLane with 25 qubits by specifying the device ARN. """ -my_bucket = "amazon-braket-Your-Bucket-Name" # the name of the bucket, keep the 'amazon-braket-' prefix and then include the bucket name -my_prefix = "Your-Folder-Name" # the name of the folder in the bucket -s3_folder = (my_bucket, my_prefix) device_arn = "arn:aws:braket:::device/quantum-simulator/amazon/sv1" @@ -114,7 +110,6 @@ "braket.aws.qubit", device_arn=device_arn, wires=n_wires, - s3_destination_folder=s3_folder, parallel=True, ) @@ -229,7 +224,10 @@ def circuit(params): d_qnode_remote(params) t_1_remote_grad = time.time() -print("Gradient calculation time on remote device (seconds):", t_1_remote_grad - t_0_remote_grad) +print( + "Gradient calculation time on remote device (seconds):", + t_1_remote_grad - t_0_remote_grad, +) ############################################################################## # .. rst-class:: sphx-glr-script-out @@ -251,7 +249,10 @@ def circuit(params): d_qnode_local(params) t_1_local_grad = time.time() -print("Gradient calculation time on local device (seconds):", t_1_local_grad - t_0_local_grad) +print( + "Gradient calculation time on local device (seconds):", + t_1_local_grad - t_0_local_grad, +) ############################################################################## # .. rst-class:: sphx-glr-script-out @@ -313,7 +314,6 @@ def circuit(params): "braket.aws.qubit", device_arn=device_arn, wires=n_wires, - s3_destination_folder=s3_folder, parallel=True, max_parallel=20, poll_timeout_seconds=30, @@ -350,7 +350,7 @@ def circuit(params, **kwargs): cost_function = qml.QNode(circuit, dev) -optimizer = qml.AdagradOptimizer(stepsize=0.1) +optimizer = qml.AdagradOptimizer(stepsize=0.01) ############################################################################## # We're now set up to train the circuit! Note, if you are training this circuit yourself, you may @@ -437,9 +437,179 @@ def circuit(params, **kwargs): # analyze the performance of this optimized circuit following a similar strategy to the # :doc:`QAOA tutorial`. Did we find a large graph cut? # +# Large-scale experiments with Hybrid Jobs +# ---------------------------------- +# We have seen how we can use PennyLane on Braket to solve graph optimization problems with QAOA. +# However, we have only used Amazon Braket for the quantum simulations, leaving the classical +# Python code to run on our laptop. +# This is great for getting started with small experiments, but for large-scale algorithms running +# them on a laptop is impractical due to potential crashes, restarts or even hardware limitations +# such as limited memory. With Amazon Braket Hybrid Jobs, you can send your entire algorithm, both +# classical and quantum parts, to run on AWS while you get a coffee! +# +# With a single line of code, we'll see how to scale from PennyLane simulators on your laptop to +# run full-scale experiments on AWS that leverage both powerful classical compute and quantum +# devices. For more details on hybrid jobs see +# :doc:`getting started with hybrid jobs `. +# +# .. warning:: +# The following demo is only compatible with Python version 3.10. +# +# In the following code, we run the same QAOA optimization as before, but this time on an +# `Amazon EC2 ml.c5.xlarge instance `__ +# instead of our laptop. We specify this with the `instance_config` for our hybrid job. +# A complete set of options is available in the `Braket documentation +# `__. +# + +from braket.jobs import InstanceConfig, hybrid_job +from braket.jobs.metrics import log_metric +from braket.tracking import Tracker + +# choose a large instance type for our experiment +large_instance = InstanceConfig(instanceType="ml.c5.xlarge") + + +@hybrid_job(device="local:pennylane/lightning.qubit", instance_config=large_instance) +def qaoa_training(n_iterations, n_layers=2): + braket_tasks_cost = Tracker().start() # track Braket quantum tasks costs + + # declare PennyLane device + dev = qml.device("lightning.qubit", wires=wires) + + @qml.qnode(dev) + def cost_function(params, **kwargs): + for i in range(wires): # Prepare an equal superposition over all qubits + qml.Hadamard(wires=i) + qml.layer(qaoa_layer, n_layers, params[0], params[1]) + return qml.expval(cost_h) + + params = 0.01 * np.random.uniform(size=[2, n_layers]) + + # run the classical-quantum iterations + for i in range(n_iterations): + params, cost_before = optimizer.step_and_cost(cost_function, params) + + log_metric(metric_name="cost", value=cost_before, iteration_number=i) + + return { + "parameters": params, + "final_cost": cost_function(params), + "braket_tasks_cost": braket_tasks_cost.qpu_tasks_cost() + + braket_tasks_cost.simulator_tasks_cost(), + } + + +############################################################################## +# Now we create a hybrid job by calling the function as usual. This returns an ``AwsQuantumJob`` +# object that contains the device ARN, region, and job name. The hybrid job will start running +# immediately since we are not using a QPU in this example. +# +# .. warning:: +# Running the the following cell will result charges to your AWS account based on Amazon EC2 +# pricing. +# + +job = qaoa_training(n_iterations=20, n_layers=2) +print(job) + +############################################################################## +# .. rst-class:: sphx-glr-script-out +# +# .. code-block:: none +# +# AwsQuantumJob('arn':'arn:aws:braket:::job/qaoa-training-1695044583') + +###################################################################### +# The hybrid job automatically captures the function arguments as hyperparameters. +# In this case, we set ``n_iterations = 20`` and ``n_layers = 2`` as the hyperparameters. +# +# We can check the status with: +# + +job.state() + +############################################################################## +# .. rst-class:: sphx-glr-script-out +# +# .. code-block:: none # +# 'QUEUED' + +############################################################################## +# The hybrid job will be scheduled to run and will appear in the "QUEUED" state. +# If the target is a QPU, the job will be queued with other jobs. +# If the target device is not a QPU, the hybrid job should start immediately. +# Note that since the algorithm code is run in a containerized environment, it takes approximately 1 +# minute to start running your algorithm. +# +# After the hybrid job is completed, we can get the results with ``job.result()``. For this example, +# it should take approximately 6 minutes. +# + +job.result() + +############################################################################## +# .. rst-class:: sphx-glr-script-out +# +# .. code-block:: none +# +# {'parameters': [[-0.2615367426048209, -0.46218141633156967], +# [0.3853200394389563, 0.2402391372931216]], +# 'final_cost': -37.76176577995996, +# 'braket_tasks_cost': 0} + + +############################################################################## +# The results included the three values from the return statement of our function. +# Additionally, we can retrieve the metrics recorded during the training with: +# + +metrics = job.metrics() + +############################################################################## +# Now that we have the metrics, we can plot the convergence of the loss function. +# We use the pandas library to load the metrics into a DataFrame, and plot the loss as a function of +# iteration number. + +import pandas as pd +import matplotlib.pyplot as plt + +plt.style.use("pennylane.drawer.plot") + +df = pd.DataFrame(metrics) + +df.sort_values(by=["iteration_number"]).plot(x="iteration_number", y="cost") + + +############################################################################## +# +# .. figure:: ../demonstrations/braket/qaoa_training.png +# :align: center +# :scale: 75% +# :alt: Convergence of cost function for QAOA training. +# :target: javascript:void(0); + +############################################################################## +# Great! The loss function gets lower with each iteration, reaching a value of approximately -36.5. +# +# Conclusion +# ---------------------------------- +# In this tutorial, we found the solution to a MaxCut problem using QAOA. We used Amazon Braket +# on-demand simulators to efficiently parallelize the parameter-shift rule for gradients. We also +# demonstrated how to scale-up experiments with your own simulator, such as PennyLane Lightning, by +# running on Amazon Braket Hybrid Jobs. In both approaches, we perform the intensive calculations on +# the cloud instead of our laptop. +# +# For more examples of how to use hybrid jobs, see the +# `Amazon Braket examples GitHub `__. +# + +############################################################################## # About the authors # ----------------- # .. include:: ../_static/authors/thomas_bromley.txt # -# .. include:: ../_static/authors/maria_schuld.txt \ No newline at end of file +# .. include:: ../_static/authors/maria_schuld.txt +# +# .. include:: ../_static/authors/matthew_beach.txt diff --git a/demonstrations/braket/qaoa_training.png b/demonstrations/braket/qaoa_training.png new file mode 100644 index 0000000000000000000000000000000000000000..085e6a37138309b04ab6e52a78e5082588eda431 GIT binary patch literal 32402 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