examples/hybrid_jobs/0_Creating_your_first_Hybrid_Job/0_Creating_your_first_Hybrid_Job.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating your first Hybrid Job\n",
    "\n",
    "\n",
    "This tutorial provides an introduction to running hybrid quantum-classical algorithms using\n",
    "PennyLane on Amazon Braket . With Amazon Braket, you gain access to both real quantum devices and\n",
    "scalable classical compute, enabling you to push the boundaries of your algorithm.\n",
    "\n",
    "In this tutorial, we'll walk through how to create your first hybrid quantum-classical algorithms on AWS.\n",
    "With a single line of code, we'll see how to scale from PennyLane simulators on your laptop to running full-scale experiments on AWS that leverage both powerful classical compute and quantum devices.\n",
    "You'll gain understanding of the hybrid jobs queue, including QPU priority queuing, and learn how to scale classical resources for resource-intensive tasks. \n",
    "We hope these tools will empower you to start experimenting today with hybrid quantum algorithms!\n",
    "\n",
    "\n",
    "\n",
    "## Amazon Braket Hybrid Jobs\n",
    "\n",
    "Amazon Braket Hybrid Jobs offers a way for you to run hybrid quantum-classical algorithms that\n",
    "require both classical resources and quantum processing units (QPUs). Hybrid Jobs is designed to\n",
    "spin up the requested classical compute, run your algorithm, and release the instances after\n",
    "completion so you only pay for what you use. This workflow is ideal for long-running iterative\n",
    "algorithms involving both classical and quantum resources. Simply package up your code into a single\n",
    "function, create a hybrid job with a single line of code, and Braket will schedule it to run as soon\n",
    "as possible without interruption.\n",
    "\n",
    "Hybrid jobs have a separate queue from quantum tasks, so once your algorithm starts running, it will\n",
    "not be interrupted by variations in the quantum task queue. This helps your long-running algorithms\n",
    "run efficiently and predictably. Any quantum tasks created from a running hybrid job will be run\n",
    "before any other quantum tasks in the queue. This is particularly beneficial for iterative hybrid\n",
    "algorithms where subsequent tasks depend on the outcomes of prior quantum tasks. Examples of such\n",
    "algorithms include the Quantum Approximate Optimization Algorithm (QAOA), Variational Quantum\n",
    "Eigensolver (VQE), or Quantum Machine Learning (QML). You can also monitor your algorithm's progress in near-real\n",
    "time, enabling you to keep track of costs, budget, or custom metrics such as training loss or\n",
    "expectation values.\n",
    "\n",
    "Importantly, on specific QPUs, running your algorithm in Hybrid Jobs benefits from [parametric compilation](https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-parametric-compilation.html). \n",
    "This reduces the overhead associated with the computationally expensive compilation step by compiling a circuit only once and not for every iteration in your hybrid algorithm. \n",
    "This reduces the total runtime for many variational algorithms by up to 10x.\n",
    "For long-running hybrid jobs, Braket automatically uses the updated calibration data from the hardware provider when compiling your circuit to ensure the highest quality results.\n",
    "\n",
    "## Getting started with PennyLane\n",
    "\n",
    "\n",
    "Let’s setup an algorithm that makes use of both classical and quantum resources. We adapt the [PennyLane qubit rotation tutorial](https://pennylane.ai/qml/demos/tutorial_qubit_rotation).\n",
    "\n",
    "First, we define a quantum simulator to run the algorithm on. In this example, we will use the Braket local simulator before moving onto a QPU."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pennylane as qml\n",
    "from pennylane import numpy as np\n",
    "\n",
    "device = qml.device(\"braket.local.qubit\", wires=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we define a circuit with two rotation gates and measure the expectation value in the $Z$-basis"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "@qml.qnode(device)\n",
    "def circuit(params):\n",
    "    qml.RX(params[0], wires=0)\n",
    "    qml.RY(params[1], wires=0)\n",
    "    return qml.expval(qml.PauliZ(0))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we create a classical-quantum loop that uses gradient descent to minimize the expectation value.\n",
    "\n",
    "We add the ``log_metric`` function from Braket to record the training progress (see [metrics\n",
    "documentation](https://amazon-braket-sdk-python.readthedocs.io/en/stable/_apidoc/braket.jobs.metrics.html)).\n",
    "When running on AWS, ``log_metric`` records the metrics in [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/), which is accessible\n",
    "through the Braket console page or the Braket SDK. When running locally on your laptop,\n",
    "``log_metric`` prints the iteration numbers.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from braket.jobs.metrics import log_metric\n",
    "\n",
    "\n",
    "def qubit_rotation(num_steps=10, stepsize=0.5):\n",
    "    opt = qml.GradientDescentOptimizer(stepsize=stepsize)\n",
    "    params = np.array([0.5, 0.75])\n",
    "\n",
    "    for i in range(num_steps):\n",
    "        # update the circuit parameters\n",
    "        params = opt.step(circuit, params)\n",
    "        expval = circuit(params)\n",
    "\n",
    "        log_metric(metric_name=\"expval\", iteration_number=i, value=expval)\n",
    "\n",
    "    return params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To run the entire algorithm, we call the `qubit_rotation`` function to see that it runs correctly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Metrics - timestamp=1700084056.91118; expval=0.38894534132396147; iteration_number=0;\n",
      "Metrics - timestamp=1700084056.9852457; expval=0.12290715413453956; iteration_number=1;\n",
      "Metrics - timestamp=1700084057.0590365; expval=-0.09181374013482171; iteration_number=2;\n",
      "Metrics - timestamp=1700084057.128326; expval=-0.2936094099948542; iteration_number=3;\n",
      "Metrics - timestamp=1700084057.1863492; expval=-0.5344079938678078; iteration_number=4;\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "tensor([0.67679672, 2.32609342], requires_grad=True)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "qubit_rotation(5, stepsize=0.5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great! We see the expectation value change with each iteration number and the final parameters were returned as a list. Now, instead of running on our laptop, let’s submit this same function to be run on AWS."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running as a hybrid job\n",
    "\n",
    "You can execute long-running algorithms asynchronously with Amazon Braket Hybrid Jobs, \n",
    "which fully manages the classical infrastructure so you can focus on the algorithm. For example, you\n",
    "can train a larger circuit, or increase the number of iterations. Note that each hybrid job has\n",
    "at least a one minute startup time since it creates a containerized environment on Amazon EC2. So\n",
    "for very short workloads, such as a single circuit or a batch of circuits, it may suffice for you to\n",
    "use quantum tasks.\n",
    "\n",
    "We now show how you can go from running your local Python function to running it as a hybrid job.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>Note:</b> Only Python 3.10 is supported by default. For other versions, you may use hybrid job scripts, or specify a custom container image from Amazon Elastic Container Registry (ECR) (see \n",
    "<a href=\"https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-byoc.html\">containers documentation</a>).\n",
    "</div>\n",
    "\n",
    "\n",
    "The first step to creating a hybrid job is to annotate which function you want to run with the\n",
    "`@hybrid_job` decorator. Then you create the job by invoking the function as you would for normal\n",
    "Python functions. However, the decorated function returns the hybrid job handle rather than the\n",
    "result of the function. To retrieve the results after it has been completed, use `job.result()`.\n",
    "\n",
    "For algorithms that do not need priority queueing or scheduling for on-demand QPUs, you may specify the device as `local:<provider>/<simulator>` or simply `None`. For example, when using a simulator that runs on the same classical host alongside the rest of your algorithm, such as the PennyLane Lightning CPU/GPU simulators, you may set `device=\"local:pennylane/lightning.qubit\"`.  \n",
    "\n",
    "\n",
    "The required device argument in the `@hybrid_job` decorator specifies the QPU that the hybrid job\n",
    "will have priority access to.\n",
    "The device string you give is accessible in the hybrid job instance as the environment variable ``\"AMZN_BRAKET_DEVICE_ARN\"``.\n",
    "In the following code, we annotate the `qubit_rotation` function from above.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "from braket.jobs import hybrid_job, save_job_result\n",
    "\n",
    "\n",
    "@hybrid_job(device=\"local:braket/default\")\n",
    "def qubit_rotation_hybrid_job(num_steps=1, stepsize=0.5):\n",
    "    device = qml.device(\"braket.local.qubit\", wires=1)\n",
    "\n",
    "    @qml.qnode(device)\n",
    "    def circuit(params):\n",
    "        qml.RX(params[0], wires=0)\n",
    "        qml.RY(params[1], wires=0)\n",
    "        return qml.expval(qml.PauliZ(0))\n",
    "\n",
    "    opt = qml.GradientDescentOptimizer(stepsize=stepsize)\n",
    "    params = np.array([0.5, 0.75])\n",
    "\n",
    "    for i in range(num_steps):\n",
    "        # update the circuit parameters\n",
    "        params = opt.step(circuit, params)\n",
    "        expval = circuit(params)\n",
    "\n",
    "        log_metric(metric_name=\"expval\", iteration_number=i, value=expval)\n",
    "\n",
    "    return params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "AwsQuantumJob('arn':'arn:aws:braket:us-west-2:318845237731:job/qubit-rotation-hybrid-job-1700084057462')\n"
     ]
    }
   ],
   "source": [
    "job = qubit_rotation_hybrid_job(num_steps=10, stepsize=0.5)\n",
    "print(job)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The hybrid job automatically captures the function arguments as [hyperparameters](https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-hyperparameters.html).\n",
    "In this case, we set `num_steps = 10` and `stepsize = 0.5` as the hyperparameters."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can check the status with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'QUEUED'"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "job.state()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the hybrid job starts, it will change the status to `RUNNING`. We can also check the hybrid job status in the Braket console.\n",
    "\n",
    "We can monitor the metrics in near-real time in the [Braket console page](https://console.aws.amazon.com/braket/) as shown below. \n",
    "\n",
    "![Training to minimize an expectation value.](console_figures/expval.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After the hybrid job completes, we can get the results with `job.result()`. For this example, it should take approximately 2 minutes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'result': tensor([0.03642036, 3.10081929], requires_grad=True)}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "job.result()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Any objects in the return statement are automatically captured by Braket. Note that the objects returned by the function must be a tuple with each element being serializable as text. \n",
    "\n",
    "Additionally, we can plot the metrics recording during the algorithm. Below we show the expectation value decreases with each iteration as expected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'timestamp': [1700084189.268808, 1700084189.3246114, 1700084189.3840628, 1700084189.1557567, 1700084189.2123241, 1700084188.8748374, 1700084188.9313, 1700084188.9881024, 1700084189.0439024, 1700084189.099711], 'expval': [-0.9771543186187628, -0.9940804663947356, -0.9985062848699056, -0.7715298984378987, -0.9193547392516985, 0.38894534132396147, 0.12290715413453956, -0.09181374013482171, -0.2936094099948542, -0.5344079938678078], 'iteration_number': [7.0, 8.0, 9.0, 5.0, 6.0, 0.0, 1.0, 2.0, 3.0, 4.0]}\n"
     ]
    }
   ],
   "source": [
    "# May need to wait a bit before metrics show up\n",
    "# If metrics aren't there, try again after 5 seconds\n",
    "import time\n",
    "\n",
    "time.sleep(10)\n",
    "print(job.metrics())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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5ntMnz592LlzJ7Nnz2bz5s10796de+65hw0bNpRQahHxStHdof0sCKruuj2oBrT9Epo8DzYf+P0z+KEZHF1hTU4R8YwFFbdv307Dhg1Zs2YNsbGxAMybN4+uXbty4MABoqKicj2uQoUKvPfee9x///3ObZUrV+aVV15hwIABBXpvLagoIkXmyP5rFtlhc0xQeHvzjBHAsZ/N65Kl7zGvZN/oWWg8Cuy+1mYWKSPK1IKKiYmJhIaGOksQQHx8PHa7nVWrVuV5XJs2bZgxYwbHjx/H4XDwxRdfcObMGTp16pTnMWfPniUtLc3lJiJSJHYfiOwEMb3Mn+dLEECV66DrRoi531x7aMvz8FMHOLXborAi3skjilBycjIREREu23x9fQkLCyM5OTnP47788kvOnTtH5cqV8ff35+GHH+abb76hXr16eR6TkJBASEiI8xYdHe22zyEi4qJcMLT5D7T5DMqFwLFEmNsc9nxqdTIRr2FpERoxYgQ2my3f244dO4r8+qNGjeLEiRP89NNPrF27luHDh3PPPfeweXNeq77CyJEjSU1Ndd72799f5PcXESmQmF7QdROEt4Osk5B4vwZSi5QQS8cIHT16lD/++CPfferUqcOnn37K448/zp9//uncnpWVRUBAADNnzuTOO+/McVxSUhL16tVjy5YtNGrUyLk9Pj6eevXqMXny5AJl1BghESkxjizYmgBbxoKRDeVjzCvah7e1OpmIxyno329LR+WFh4cTHh5+yf1at27NiRMnWLduHS1atABg4cKFOBwOWrVqlesxGRkZANjtrie9fHx8cDgcl5lcRKQY2H2hySioGg8re5sDqX/qAI1GQeNnNZBapBh4xBihBg0acNNNN/HQQw+xevVqVqxYwaBBg7j33nudM8YOHjxI/fr1Wb16NQD169enXr16PPzww6xevZqkpCTeeOMN5s+fT7du3Sz8NCIilxDe+qKB1GP/Gki9x+pkImWORxQhgOnTp1O/fn3i4uLo2rUr7dq144MPPnA+f+7cOXbu3Ok8E1SuXDnmzp1LeHg4t912G02bNuU///kP06ZNo2vXrlZ9DBGRgnEZSB3810DqZhpILeJmHrGOkJU0RkhELHdqLyT+48LCi7Xug5bvgl+IpbFESrMytY6QiIhXqxADcYsvWpG6uVakFnEDFSEREU9wfiB1/DIoXxvS95rjhn4ZY842E5EiURESEfEkuQ6k7qiB1CJFpCIkIuJpcgykXml+VbZnutXJRDyOipCIiKeK6QU3bzIXXDyXZg6o1orUIoWiIiQi4smcA6nHXjSQeqW1uUQ8hIqQiIins/tCk+cuGkjdXgOpRQpARUhEpKzQQGqRQlMREhEpSzSQWqRQVIRERMqi3AZSr/yHBlKLXERFSESkrLp4IPXe6RpILXIRFSERkbJMA6lF8qUiJCLiDZwDqf9x0UDqvVYnE7GUipCIiLcoFwxtPoE20/82kLqZBlKLV1MREhHxNjH3aSC1yF9UhEREvJFzIPUYsNk1kFq8loqQiIi3svtCk9F/DaSO+WsgdQfYPFYDqcVrqAiJiHi78DZw88a/BlJnw+YxrgOpHdmQshj2fm7+dGRbFlXE3XytDiAiIqWAX4g5kDrqZljzyIWB1HUehP2zIOPAhX2DakCLiRDd3bq8Im6iM0IiInJBzH3m2aEqbcyB1DsnuJYggIyDsKwH7P/aioQibqUiJCIirirUhs4LzSn2uTLMH+uG6Wsy8XgqQiIiktMfieYZoTwZkLEfji4rsUgixUFFSEREcjp9uGD7/fwAbBxpDqLOzizORCLFQoOlRUQkp8BqBdsv/XfY9rJ5860AkZ0h6iao1gUq1CnejCJuoCIkIiI5hbc3Z4dlHMQ5JsiFzSxLzV6G5B/N25kjcHC2eQOoeIVZiKrdBJGdwLd8CX4AkYKxGYaR2/+Fy1/S0tIICQkhNTWV4OC8Bg6KiJRB+782Z4cBrmXIZv5oP+vCFHrDAX9uhMP/g8PzzBWqjb8tymj3M8vV+bNFIY3BZiuBDyHeqqB/v1WELkFFSES82v6vYd3Qi9YRioYWE/JfR+hcGiQvvFCM0ve6Ph8YdeFsUdV48A8rjvTixVSE3ERFSES8niPbnB12+rD5dVh4e7D7FPx4w4CTu8xSdGgeHFkM2acvPG+zQ9i1ZjGKugnCWhbu9UVyoSLkJipCIiJuln0Gjiy7cLYodavr836VoOoNf50x6gJB1a3JKR5NRchNVIRERIpZxoG/StH/4PB8OHfC9fmQxhfGFoW3Bx9/S2KKZ1ERchMVIRGREuTIgj/WmGeKDv8P/liNy0BtnyBzBlq1v4pRxSs06FpypSLkJipCIiIWOvsHJP90oRhdvNBj+doXxhZFdoZyFfN+rcsd6yQeRUXITVSERERKCcOAE5v/NkV/GTjOXXje5gvhbS+cLarUzByIDXnMfqsBLSbmP/tNPJaKkJuoCImIlFLnTpkz0M7PRjv1m+vzAZFQ9Ubwrww7J5JzYchc1kOSMkNFyE1UhEREPMTJpAuDrlMWQFZ6AQ6ymWeGbt+jr8nKGBUhN1EREhHxQNmZcGwF/DYFfv/80vsHREH5mhAQDv7hF3663K9i3rf6UiEa61QgBf37rWuNiYhI2ePjB5HXw+nkghWhM4fMW4FeOzDvspTbtnLB7pvZVpbGOpWSQucxRejFF1/k+++/Z+PGjfj5+XHixIlLHmMYBqNHj2bKlCmcOHGCtm3b8t5773HFFVcUf2AREbFeYLWC7XfNW1C+Bpw9CmeOwtljf7t/9MJ9x1lzVeyMfeatIOzlLpxRKkiB8g+7MMj775zXfrvoi5yMg+Z2TxrrVIoKnccUoczMTO6++25at27NRx99VKBjXn31Vd566y2mTZtG7dq1GTVqFF26dGHbtm0EBAQUc2IREbFceHvzD2zGQXIOlgbnGKEr/3npsxGGAVmnXAvSxUXp4m1Z6ebMttOHzFtB2OzgV9n1Kzm/yn+d2crtMxjm51g7GKq0AZ8A8yK39nLmTLrSts5SKSt0HjdGaOrUqQwbNuySZ4QMwyAqKorHH3+cJ554AoDU1FQiIyOZOnUq9957b4HeT2OEREQ8nPMPL7j+8S2BWWNZp/M+u5Rbgbp4VW13sJczi5GtnPmVoa3chW15/XTZN5/9cvuZ3zE2H/Pf4uyRPMK6b/C6148R2rNnD8nJycTHxzu3hYSE0KpVKxITE/MsQmfPnuXs2bPOx2lpacWeVUREilF0d7Ps5PpVzITiPfvgGwi+0VA+umD7O86Zxenis0spi+HA10XL4Dh3Yb2lc/nvaj0DMvabY4ciO5XIO5bZIpScnAxAZGSky/bIyEjnc7lJSEhg7NixxZpNRERKWHR3qH5HqRicmy97OTPbxWObQpsUrAh1XgDh7cCRCcY5c/accc587Pj7z9y2/e1nrsfk8Rr5vs9FP8/+kc/ZoL+5eAXxYmRpERoxYgSvvPJKvvts376d+vXrl1AiGDlyJMOHD3c+TktLIzq6gE1eRERKL7tPiZ1lcLuCjnWK6Gh+Th+/kk5YMCmLYcH1l96voIPc3cDSIvT444/zwAMP5LtPnTp1ivTaVatWBSAlJYVq1S78QlNSUmjevHmex/n7++Pvrysbi4hIKWL3MWdULeuBObYpl7FOLSaUvjNcFytooQtvX2KRLC1C4eHhhIeHF8tr165dm6pVq7JgwQJn8UlLS2PVqlU88sgjxfKeIiIixcbKsU7uUgoLnceMEdq3bx/Hjx9n3759ZGdns3HjRgDq1atHhQoVAKhfvz4JCQnceeed2Gw2hg0bxgsvvMAVV1zhnD4fFRVFt27drPsgIiIiReUpY53yU8oKnccUoeeee45p06Y5H1999dUALFq0iE6dOgGwc+dOUlNTnfs89dRTpKenM3DgQE6cOEG7du2YN2+e1hASERHP5cljnc4rRYXO49YRKmlaR0hERMTzFPTvdy5reIuIiIh4BxUhERER8VoqQiIiIuK1VIRERETEa6kIiYiIiNdSERIRERGvpSIkIiIiXktFSERERLyWipCIiIh4LY+5xIZVzi+8nZaWZnESERERKajzf7cvdQENFaFLOHnyJADR0dEWJxEREZHCOnnyJCEhIXk+r2uNXYLD4eDQoUNUrFgRm83mttdNS0sjOjqa/fv36xpmpYT+TUoX/XuULvr3KF3073FphmFw8uRJoqKisNvzHgmkM0KXYLfbqVGjRrG9fnBwsP6PuJTRv0npon+P0kX/HqWL/j3yl9+ZoPM0WFpERES8loqQiIiIeC0VIYv4+/szevRo/P39rY4if9G/Semif4/SRf8epYv+PdxHg6VFRETEa+mMkIiIiHgtFSERERHxWipCIiIi4rVUhERERMRrqQhZ5J133iEmJoaAgABatWrF6tWrrY7klRISEmjZsiUVK1YkIiKCbt26sXPnTqtjyV9efvllbDYbw4YNszqKVzt48CD/+Mc/qFy5MoGBgTRp0oS1a9daHcsrZWdnM2rUKGrXrk1gYCB169Zl3Lhxl7yeluRNRcgCM2bMYPjw4YwePZr169fTrFkzunTpwpEjR6yO5nWWLFnCo48+ys8//8z8+fM5d+4cN954I+np6VZH83pr1qzh/fffp2nTplZH8Wp//vknbdu2pVy5cvzwww9s27aNN954g0qVKlkdzSu98sorvPfee0yaNInt27fzyiuv8Oqrr/L2229bHc1jafq8BVq1akXLli2ZNGkSYF7PLDo6msGDBzNixAiL03m3o0ePEhERwZIlS+jQoYPVcbzWqVOnuOaaa3j33Xd54YUXaN68ORMmTLA6llcaMWIEK1asYNmyZVZHEeDWW28lMjKSjz76yLntrrvuIjAwkE8//dTCZJ5LZ4RKWGZmJuvWrSM+Pt65zW63Ex8fT2JiooXJBCA1NRWAsLAwi5N4t0cffZRbbrnF5f9PxBqzZ88mNjaWu+++m4iICK6++mqmTJlidSyv1aZNGxYsWMCuXbsA2LRpE8uXL+fmm2+2OJnn0kVXS9ixY8fIzs4mMjLSZXtkZCQ7duywKJWAeWZu2LBhtG3blsaNG1sdx2t98cUXrF+/njVr1lgdRYDdu3fz3nvvMXz4cJ5++mnWrFnDkCFD8PPzo2/fvlbH8zojRowgLS2N+vXr4+PjQ3Z2Ni+++CK9e/e2OprHUhES+cujjz7Kli1bWL58udVRvNb+/fsZOnQo8+fPJyAgwOo4gvkfCLGxsbz00ksAXH311WzZsoXJkyerCFngyy+/ZPr06Xz22Wc0atSIjRs3MmzYMKKiovTvUUQqQiWsSpUq+Pj4kJKS4rI9JSWFqlWrWpRKBg0axJw5c1i6dCk1atSwOo7XWrduHUeOHOGaa65xbsvOzmbp0qVMmjSJs2fP4uPjY2FC71OtWjUaNmzosq1BgwZ89dVXFiXybk8++SQjRozg3nvvBaBJkyb8/vvvJCQkqAgVkcYIlTA/Pz9atGjBggULnNscDgcLFiygdevWFibzToZhMGjQIL755hsWLlxI7dq1rY7k1eLi4ti8eTMbN2503mJjY+nduzcbN25UCbJA27ZtcywpsWvXLmrVqmVRIu+WkZGB3e76p9vHxweHw2FRIs+nM0IWGD58OH379iU2NpZrr72WCRMmkJ6eTr9+/ayO5nUeffRRPvvsM7777jsqVqxIcnIyACEhIQQGBlqczvtUrFgxx/is8uXLU7lyZY3bsshjjz1GmzZteOmll7jnnntYvXo1H3zwAR988IHV0bzSbbfdxosvvkjNmjVp1KgRGzZs4M033+TBBx+0OprH0vR5i0yaNInXXnuN5ORkmjdvzltvvUWrVq2sjuV1bDZbrts//vhjHnjggZINI7nq1KmTps9bbM6cOYwcOZJff/2V2rVrM3z4cB566CGrY3mlkydPMmrUKL755huOHDlCVFQUvXr14rnnnsPPz8/qeB5JRUhERES8lsYIiYiIiNdSERIRERGvpSIkIiIiXktFSERERLyWipCIiIh4LRUhERER8VoqQiIiIuK1VIREJFedOnVi2LBhVsfIwWaz8e2331odo9iMGTOG5s2bWx1DxGuoCIlIrr7++mvGjRvnfBwTE1OiqzvnVQgOHz7MzTffXGI5RKRs07XGRCRXYWFhxfK6mZmZl3UpgKpVq7oxjfc4d+4c5cqVszqGSKmjM0Iikqu/fzXWqVMnfv/9dx577DFsNpvLNdqWL19O+/btCQwMJDo6miFDhpCenu58PiYmhnHjxtGnTx+Cg4MZOHAgAP/617+48sorCQoKok6dOowaNYpz584BMHXqVMaOHcumTZuc7zd16lQg51djmzdvpnPnzgQGBlK5cmUGDhzIqVOnnM8/8MADdOvWjddff51q1apRuXJlHn30Ued75eb82ahPPvmEmJgYQkJCuPfeezl58qTL57r4DFnz5s0ZM2aM87HNZuP999/n1ltvJSgoiAYNGpCYmMhvv/1Gp06dKF++PG3atCEpKSlHhvfff5/o6GiCgoK45557SE1NdXn+ww8/pEGDBgQEBFC/fn3effdd53N79+7FZrMxY8YMOnbsSEBAANOnT8/z84p4MxUhEbmkr7/+mho1avD8889z+PBhDh8+DEBSUhI33XQTd911F7/88gszZsxg+fLlDBo0yOX4119/nWbNmrFhwwZGjRoFmFeanzp1Ktu2bWPixIlMmTKF8ePHA9CzZ08ef/xxGjVq5Hy/nj175siVnp5Oly5dqFSpEmvWrGHmzJn89NNPOd5/0aJFJCUlsWjRIqZNm8bUqVOdxSovSUlJfPvtt8yZM4c5c+awZMkSXn755UL/7s6XwI0bN1K/fn3uu+8+Hn74YUaOHMnatWsxDCNH3t9++40vv/yS//73v8ybN48NGzbwz3/+0/n89OnTee6553jxxRfZvn07L730EqNGjWLatGkurzNixAiGDh3K9u3b6dKlS6Gzi3gFQ0QkFx07djSGDh3qfFyrVi1j/PjxLvv079/fGDhwoMu2ZcuWGXa73Th9+rTzuG7dul3y/V577TWjRYsWzsejR482mjVrlmM/wPjmm28MwzCMDz74wKhUqZJx6tQp5/Pff/+9YbfbjeTkZMMwDKNv375GrVq1jKysLOc+d999t9GzZ888s4wePdoICgoy0tLSnNuefPJJo1WrVs7Huf0+mjVrZowePdol67PPPut8nJiYaADGRx995Nz2+eefGwEBAS7v7ePjYxw4cMC57YcffjDsdrtx+PBhwzAMo27dusZnn33m8t7jxo0zWrdubRiGYezZs8cAjAkTJuT5GUXEpDFCIlJkmzZt4pdffnH52sUwDBwOB3v27KFBgwYAxMbG5jh2xowZvPXWWyQlJXHq1CmysrIIDg4u1Ptv376dZs2aUb58eee2tm3b4nA42LlzJ5GRkQA0atQIHx8f5z7VqlVj8+bN+b52TEwMFStWdDnmyJEjhcoH0LRpU+f983maNGnisu3MmTOkpaU5P3/NmjWpXr26c5/WrVs7P1PFihVJSkqif//+PPTQQ859srKyCAkJcXnv3H7vIuJKRUhEiuzUqVM8/PDDDBkyJMdzNWvWdN7/e1EBSExMpHfv3owdO5YuXboQEhLCF198wRtvvFEsOS8eJGyz2XA4HJd1jN1uxzAMl31yG3f099c5P7Yqt22XynPe+fFPU6ZMoVWrVi7P/b3sQc7fu4jkpCIkIgXi5+dHdna2y7ZrrrmGbdu2Ua9evUK91sqVK6lVqxbPPPOMc9vvv/9+yfe7WIMGDZg6dSrp6enOP/orVqzAbrdz1VVXFSpTYYWHhzvHSgGkpaWxZ88et7z2vn37OHToEFFRUQD8/PPPzs8UGRlJVFQUu3fvpnfv3m55PxFvpsHSIlIgMTExLF26lIMHD3Ls2DHAnPm1cuVKBg0axMaNG/n111/57rvvcgz+vdgVV1zBvn37+OKLL0hKSuKtt97im2++yfF+e/bsYePGjRw7doyzZ8/meJ3evXsTEBBA37592bJlC4sWLWLw4MHcf//9zq+hikvnzp355JNPWLZsGZs3b6Zv3745zsgU1fnPtGnTJpYtW8aQIUO45557nEsHjB07loSEBN566y127drF5s2b+fjjj3nzzTfd8v4i3kRFSEQK5Pnnn2fv3r3UrVuX8PBwwBz/smTJEnbt2kX79u25+uqree6555xnMvJy++2389hjjzFo0CCaN2/OypUrnbPJzrvrrru46aabuP766wkPD+fzzz/P8TpBQUH873//4/jx47Rs2ZIePXoQFxfHpEmT3PfB8zBy5Eg6duzIrbfeyi233EK3bt2oW7euW167Xr16dO/ena5du3LjjTfStGlTl+nxAwYM4MMPP+Tjjz+mSZMmdOzYkalTp1K7dm23vL+IN7EZF3/JLSIiIuIldEZIREREvJaKkIiIiHgtFSERERHxWipCIiIi4rVUhERERMRrqQiJiIiI11IREhEREa+lIiQiIiJeS0VIREREvJaKkIiIiHgtFSERERHxWipCIiIi4rX+H0HDQ1UntDG8AAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import pandas as pd\n",
    "\n",
    "df = pd.DataFrame(job.metrics())\n",
    "df.sort_values(by=[\"iteration_number\"], inplace=True)\n",
    "\n",
    "plt.plot(df[\"iteration_number\"], df[\"expval\"], \"-o\", color=\"orange\")\n",
    "plt.xlabel(\"iteration number\")\n",
    "plt.ylabel(\"expectation value\")\n",
    "plt.title(\"Simulator results\")\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running on a QPU with priority\n",
    "\n",
    "The next step is to see how well the qubit rotation works on a real QPU. We\n",
    "create a hybrid job with the Rigetti device as the priority QPU. We also increase the number of\n",
    "steps to 10.\n",
    "\n",
    "Using hybrid jobs for iterative algorithms is very beneficial because you retain priority access to the\n",
    "target QPU. So once your quantum tasks are created in the hybrid job, they run ahead of other tasks\n",
    "waiting in the *quantum task queue*. This means your\n",
    "algorithm will not be interrupted by other quantum tasks, so it will run more efficiently and\n",
    "predictably. Quantum tasks submitted as part of a hybrid job have priority, and are aggregated in the *priority task queue*.\n",
    "\n",
    "Hybrid jobs have their own *hybrid jobs queue* so that only a single\n",
    "hybrid job can run on a QPU at a time. Each QPU has its own hybrid jobs queue. Note that this is a different queue from the quantum tasks. For a single quantum circuit, or a batch of circuit, it’s\n",
    "recommended to create quantum tasks instead of hybrid jobs. For more information on quantum tasks and hybrid jobs queue see the [Amazon Braket documentation](https://docs.aws.amazon.com/braket/latest/developerguide/braket-task-when.html).\n",
    "\n",
    "To get QPU priority, you must ensure that the device ARN used within the function matches that\n",
    "specified in the decorator. For convenience, you can use the helper function ``get_device_arn()`` to\n",
    "automatically capture the device ARN declared in ``@hybrid_job``.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>Note:</b> Only hybrid jobs running on AWS receive priority. Hybrid jobs running <a href=\"https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-local-mode.html\">locally</a>, or with a mismatched device ARN do not get priority task queueing. \n",
    "</div>\n",
    "\n",
    "In the previous example, we declared the local simulator outside the decorated function scope.\n",
    "However, for AWS devices such as QPUs or on-demand simulators, the device must be declared within the function scope. \n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>Note:</b> AWS devices must be declared within the body of the decorated function.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "from braket.devices import Devices\n",
    "\n",
    "\n",
    "device_arn = Devices.Rigetti.AspenM3\n",
    "\n",
    "\n",
    "@hybrid_job(device=device_arn)  # set priority QPU\n",
    "def qpu_qubit_rotation_hybrid_job(num_steps=10, stepsize=0.5):\n",
    "    # AWS devices must be declared within the decorated function.\n",
    "    device = qml.device(\n",
    "        \"braket.aws.qubit\",\n",
    "        device_arn=device_arn.value,  # Make sure the device ARN matches the hybrid job device ARN\n",
    "        wires=2,\n",
    "        shots=1_000,\n",
    "    )\n",
    "\n",
    "    @qml.qnode(device)\n",
    "    def circuit(params):\n",
    "        qml.RX(params[0], wires=0)\n",
    "        qml.RY(params[1], wires=0)\n",
    "        return qml.expval(qml.PauliZ(0))\n",
    "\n",
    "    opt = qml.GradientDescentOptimizer(stepsize=stepsize)\n",
    "    params = np.array([0.5, 0.75])\n",
    "\n",
    "    for i in range(num_steps):\n",
    "        # update the circuit parameters\n",
    "        params = opt.step(circuit, params)\n",
    "        expval = circuit(params)\n",
    "\n",
    "        log_metric(metric_name=\"expval\", iteration_number=i, value=expval)\n",
    "\n",
    "    return params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get a sense of how long we will wait before the hybrid job runs, we can check the hybrid job\n",
    "queue depth with `AwsDevice(device_arn).queue_depth().jobs`. We can also check if the device is\n",
    "currently available with `AwsDevice(device_arn).is_available()`.\n",
    "\n",
    "You can check the queue depth on the devices page of the [Amazon Braket Console](https://console.aws.amazon.com/braket/home). Below, we show the devices page for Rigetti Aspen-M-3.\n",
    "\n",
    "![Rigetti Aspen-M-3 showing the queue depths.](console_figures/queue_viz.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "When there are no other hybrid jobs in the queue ahead of you, and the device is available, the hybrid job will start running.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>Note:</b> Running the following cell will only run once the QPU is available. This may take a long time and will result in usage fees charged to your AWS account. Only run the cell if you are comfortable with the potential wait-time and costs. We recommend monitoring the Billing & Cost Management Dashboard on the AWS console.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "AwsQuantumJob('arn':'arn:aws:braket:us-west-2:318845237731:job/qpu-qubit-rotation-hybrid-job-1700084458165')\n"
     ]
    }
   ],
   "source": [
    "qpu_job = qpu_qubit_rotation_hybrid_job(num_steps=10, stepsize=0.5)\n",
    "print(qpu_job)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we wait for the algorithm to complete and download the result. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'result': tensor([0.0205, 3.1065], requires_grad=True)}"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "qpu_job.result()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we plot the expectation value per iteration number below. We see that on a real QPU, the data is not as smooth as the simulator, but the minimum still is detected correctly!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'timestamp': [1700084730.969484, 1700084698.0504165, 1700084679.9848497, 1700084664.1287766, 1700084648.2972944, 1700084632.2871127, 1700084616.684862], 'expval': [-0.972, -0.784, -0.548, -0.36, -0.07, 0.11, 0.388], 'iteration_number': [7.0, 5.0, 4.0, 3.0, 2.0, 1.0, 0.0]}\n"
     ]
    }
   ],
   "source": [
    "# May need to wait a bit before metrics show up\n",
    "# If metrics aren't there, try again after 5 seconds\n",
    "import time\n",
    "\n",
    "time.sleep(10)\n",
    "print(qpu_job.metrics())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "df = pd.DataFrame(qpu_job.metrics())\n",
    "df.sort_values(by=[\"iteration_number\"], inplace=True)\n",
    "\n",
    "plt.plot(df[\"iteration_number\"], df[\"expval\"], \"-o\", color=\"teal\")\n",
    "plt.xlabel(\"iteration number\")\n",
    "plt.ylabel(\"expectation value\")\n",
    "plt.title(\"QPU results\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>Note:</b> Charges shown are estimates based on your Amazon Braket simulator and quantum processing unit (QPU) task usage. \n",
    "    Estimated charges shown may differ from your actual charges. \n",
    "    Estimated charges do not factor in any discounts or credits, and you may experience additional charges based on your use of other services such as Amazon Elastic Compute Cloud (Amazon EC2)\n",
    "    Estimated cost to run this example is $39 USD.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "In this tutorial, we showed how to migrate from local Python functions to running algorithms on simulators and QPUs on Amazon Braket.\n",
    "We adapted the simple example of rotating a qubit using gradient descent, running this on both a\n",
    "local simulator and a real QPU. \n",
    "Using Amazon Braket Hybrid Jobs allowed us to run algorithms asynchronously, scale classical compute using AWS, and obtain priority access to the selected QPU for the duration of our algorithm."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "conda_braket",
   "language": "python",
   "name": "conda_braket"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}