{

  "cells": [

    {

      "cell_type": "code",

      "execution_count": 3,

      "metadata": {

        "id": "0GKevPuPa5L_"

      },

      "outputs": [],

      "source": [

        "# This cell is added by sphinx-gallery\n",

        "# It can be customized to whatever you like\n",

        "%matplotlib inline\n",

        "# !pip install pennylane\n",

        "# !pip install covalent"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "2OVQzmEGa5MA"

      },

      "source": [

        "Quantum detection of time series anomalies\n",

        "==========================================\n",

        "\n",

        "::: {.meta}\n",

        ":property=\\\"og:description\\\": Learn how to quantumly detect anomalous\n",

        "behaviour in time series data with the help of Covalent.\n",

        ":property=\\\"og:image\\\":\n",

        "<https://pennylane.ai/qml/_images/thumbnail_tutorial_univariate_qvr.jpg>\n",

        ":::\n",

        "\n",

        "::: {.related}\n",

        "tutorial\\_qaoa\\_intro Intro to QAOA\n",

        ":::\n",

        "\n",

        "*Authors: Jack Stephen Baker, Santosh Kumar Radha --- Posted: 7 February\n",

        "2023.*\n",

        "\n",

        "Systems producing observable characteristics which evolve with time are\n",

        "almost everywhere we look. The temperature changes as day turns to\n",

        "night, stock markets fluctuate and the bacteria colony living in the\n",

        "coffee cup to your right, which you *promised* you would clean\n",

        "yesterday, is slowly growing (seriously, clean it). In many situations,\n",

        "it is important to know when these systems start behaving abnormally.\n",

        "For example, if the pressure inside a nuclear fission reactor starts\n",

        "violently fluctuating, you may wish to be alerted of that. The task of\n",

        "identifying such temporally abnormal behaviour is known as time series\n",

        "anomaly detection and is well known in machine learning circles.\n",

        "\n",

        "In this tutorial, we take a stab at time series anomaly detection using\n",

        "the *Quantum Variational Rewinding* algorithm, or QVR, proposed by\n",

        "[Baker, Horowitz, Radha et. al (2022)](https://arxiv.org/abs/2210.16438)\n",

        "--- a quantum machine learning algorithm for gate model quantum\n",

        "computers. QVR leverages the power of unitary time evolution/devolution\n",

        "operators to learn a model of *normal* behaviour for time series data.\n",

        "Given a new (i.e., unseen in training) time series, the normal model\n",

        "produces a value that, beyond a threshold, defines anomalous behaviour.\n",

        "In this tutorial, we'll be showing you how all of this works, combining\n",

        "elements from [Covalent](https://www.covalent.xyz/),\n",

        "[Pennylane](https://pennylane.ai/) and [PyTorch](https://pytorch.org/).\n",

        "\n",

        "Before getting into the technical details of the algorithm, let\\'s get a\n",

        "high-level overview with the help of the cartoon below.\n"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "fAi-GyNpa5MB"

      },

      "source": [

        "![](../demonstrations/univariate_qvr/cartoon_pennylane.png){.align-center\n",

        "width=\"70.0%\"}\n",

        "\n",

        "Going left-to-right, a time series is sampled at three points in time,\n",

        "corresponding to different stages in the life cycle of a butterfly: a\n",

        "catepillar, a chrysalis and a butterfly. This information is then\n",

        "encoded into quantum states and passed to a time machine which time\n",

        "devolves the states as generated by a learnt Hamiltonian operator (in\n",

        "practice, there is a distribution of such operators). After the devolved\n",

        "state is measured, the time series is recognized as normal if the\n",

        "average measurement is smaller than a given threshold and anomalous if\n",

        "the threshold is exceeded. In the first case, the time series is\n",

        "considered rewindable, correctly recovering the initial condition for\n",

        "the life cycle of a butterfly: eggs on a leaf. In the second case, the\n",

        "output is unrecognizable.\n",

        "\n",

        "This will all make more sense once we delve into the math a little.\n",

        "Let\\'s do it!\n"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "q6D1SN3Ga5MB"

      },

      "source": [

        "Background\n",

        "==========\n",

        "\n",

        "To begin, let's quickly recount the data that QVR handles: time series.\n",

        "A general time series $\\boldsymbol{y}$ can be described as a sequence of\n",

        "$p$-many observations of a process/system arranged in chronological\n",

        "order, where $p$ is a positive integer:\n",

        "\n",

        "$$\\boldsymbol{y} := (\\boldsymbol{y}_t: t \\in T), \\quad T := (t_l: l \\in \\mathbb{Z}^{+}_{\\leq p}).$$\n",

        "\n",

        "In the simple and didactic case treated in this tutorial,\n",

        "$\\boldsymbol{y}$ is univariate (i.e, is a one-dimensional time series),\n",

        "so bold-face for $\\boldsymbol{y}$ is dropped from this point onwards.\n",

        "Also, we take $y_t \\in \\mathbb{R}$ and $t_l \\in \\mathbb{R}_{>0}$.\n",

        "\n",

        "The goal of QVR and many other (classical) machine learning algorithms\n",

        "for time series anomaly detection is to determine a suitable *anomaly\n",

        "score* function $a_{X}$, where $X$ is a training dataset of *normal*\n",

        "time series instances $x \\in X$ ($x$ is defined analogously to $y$ in\n",

        "the above), from which the anomaly score function was learnt. When\n",

        "passed a general time series $y$, this function produces a real number:\n",

        "$a_X(y) \\in \\mathbb{R}$. The goal is to have $a_X(x) \\approx 0$, for all\n",

        "$x \\in X$. Then, for an unseen time series $y$ and a threshold\n",

        "$\\zeta \\in \\mathbb{R}$, the series is said to be anomalous should\n",

        "$a_X(y) > \\zeta,$ and normal otherwise. We show a strategy for setting\n",

        "$\\zeta$ later in this tutorial.\n",

        "\n",

        "The first step for doing all of this *quantumly* is to generate a\n",

        "sequence $\\mathcal{S} := (|x_{t} \\rangle: t \\in T)$ of $n$-qubit quantum\n",

        "states corresponding to a classical time series instance in the training\n",

        "set. Now, we suppose that each $|x_t \\rangle$ is a quantum state evolved\n",

        "to a time $t$, as generated by an *unknown embedding Hamiltonian* $H_E$.\n",

        "That is, each element of $\\mathcal{S}$ is defined by\n",

        "$|x_t \\rangle = e^{-iH_E(x_t)}|0\\rangle^{\\otimes n} = U(x_t)|0\\rangle^{\\otimes n}$\n",

        "for an embedding unitary operator $U(x_t)$ implementing a quantum\n",

        "feature map (see the [Pennylane embedding\n",

        "templates](https://docs.pennylane.ai/en/stable/introduction/templates.html#embedding-templates)\n",

        "for efficient quantum circuits for doing so). Next, we operate on each\n",

        "$|x_t\\rangle$ with a parameterized\n",

        "$e^{-iH(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})t}$ operator to prepare\n",

        "the states\n",

        "\n",

        "$$|x_t, \\boldsymbol{\\alpha}, \\boldsymbol{\\gamma}\\rangle := e^{-iH(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})t}|x_t\\rangle,$$\n",

        "\n",

        "where we write $e^{-iH(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})t}$ as\n",

        "an eigendecomposition\n",

        "\n",

        "$$V_t(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma}) := W^{\\dagger}(\\boldsymbol{\\alpha})D(\\boldsymbol{\\gamma}, t)W(\\boldsymbol{\\alpha}) = e^{-iH(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})t}.$$\n",

        "\n",

        "Here, the unitary matrix of eigenvectors $W(\\boldsymbol{\\alpha})$ is\n",

        "parametrized by $\\boldsymbol{\\alpha}$ and the unitary diagonalization\n",

        "$D(\\boldsymbol{\\gamma}, t)$ is parametrized by $\\boldsymbol{\\gamma}.$\n",

        "Both can be implemented efficiently using parameterized quantum\n",

        "circuits. The above equality with\n",

        "$e^{-iH(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})t}$ is a consequence of\n",

        "Stone's theorem for strongly continuous one-parameter unitary groups.\n",

        "\n",

        "We now ask the question: *What condition is required for*\n",

        "$|x_t, \\boldsymbol{\\alpha}, \\boldsymbol{\\gamma} \\rangle = |0 \\rangle^{\\otimes n}$\n",

        "*for all time?* To answer this, we impose\n",

        "$P(|0\\rangle^{\\otimes n}) = |\\langle 0|^{\\otimes n}|x_t, \\boldsymbol{\\alpha}, \\boldsymbol{\\gamma} \\rangle|^2 = 1.$\n",

        "Playing with the algebra a little, we find that the following condition\n",

        "must be satisfied for all $t$:\n",

        "\n",

        "$$\\langle 0|^{\\otimes n}e^{-iH(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})t}e^{-iH_E(x_t)}|0\\rangle^{\\otimes n} = 1 \\iff  H(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})t = -H_E(x_t).$$\n",

        "\n",

        "In other words, for the above to be true, the parameterized unitary\n",

        "operator $V_t(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma})$ should be able\n",

        "to reverse or *rewind* $|x_t\\rangle$ to its initial state\n",

        "$|0\\rangle^{\\otimes n}$ before the embedding unitary operator $U(x_t)$\n",

        "was applied.\n",

        "\n",

        "We are nearly there! Because it is reasonable to expect that a single\n",

        "Hamiltonian will not be able to successfully rewind every $x \\in X$ (in\n",

        "fact, this is impossible to do if each $x$ is unique, which is usually\n",

        "true), we consider the average effect of many Hamiltonians generated by\n",

        "drawing $\\boldsymbol{\\gamma}$ from a normal distribution\n",

        "$\\mathcal{N}(\\mu, \\sigma)$ with mean $\\mu$ and standard deviation\n",

        "$\\sigma$:\n",

        "\n",

        "$$F(\\boldsymbol{\\phi}, x_t) := \\mathop{\\mathbb{E}_{\\boldsymbol{\\gamma} \\sim \\mathcal{N}(\\mu, \\sigma)}}\\left[\\langle 0|^{\\otimes n} |x_t, \\boldsymbol{\\alpha}, \\boldsymbol{\\gamma}\\rangle  \\right], \\quad \\boldsymbol{\\phi} = [\\boldsymbol{\\alpha}, \\mu, \\sigma].$$\n",

        "\n",

        "The goal is for the function $F$ defined above to be as close to $1$ as\n",

        "possible, for all $x \\in X$ and $t \\in T.$ With this in mind, we can\n",

        "define the loss function to minimize as the mean square error\n",

        "regularized by a penalty function $P_{\\tau}(\\sigma)$ with a single\n",

        "hyperparameter $\\tau$:\n",

        "\n",

        "$$\\mathcal{L(\\boldsymbol{\\phi})} = \\frac{1}{2|X||T|}\\sum_{x \\in X} \\sum_{t \\in T}[1 - F(\\boldsymbol{\\phi}, x_t)]^2 + P_{\\tau}(\\sigma).$$\n",

        "\n",

        "We will show the exact form of $P_{\\tau}(\\sigma)$ later. The general\n",

        "purpose of the penalty function is to penalize large values of $\\sigma$\n",

        "(justification for this is given in the Supplement of). After\n",

        "approximately finding the argument $\\boldsymbol{\\phi}^{\\star}$ that\n",

        "minimizes the loss function (found using a classical optimization\n",

        "routine), we finally arrive at a definition for our anomaly score\n",

        "function $a_X(y)$\n",

        "\n",

        "$$a_X(y) = \\frac{1}{|T|}\\sum_{t \\in T}[1 - F(\\boldsymbol{\\phi}^{\\star}, y_t)]^2.$$\n",

        "\n",

        "It may now be apparent that we have implemented a clustering algorithm!\n",

        "That is, our model $F$ was trained such that normal time series\n",

        "$x \\in X$ produce $F(\\boldsymbol{\\phi}^{\\star}, x_t)$ clustered about a\n",

        "center at $1$. Given a new time series $y$, should\n",

        "$F(\\boldsymbol{\\phi}^{\\star}, y_t)$ venture far from the normal center\n",

        "at $1$, we are observing anomalous behaviour!\n",

        "\n",

        "Take the time now to have another look at the cartoon at the start of\n",

        "this tutorial. Hopefully things should start making sense now.\n",

        "\n",

        "Now with our algorithm defined, let's stitch this all together: enter\n",

        "[Covalent](https://www.covalent.xyz/).\n"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "0Ecv2jQ7a5MB"

      },

      "source": [

        "Covalent: heterogeneous workflow orchestration\n",

        "==============================================\n",

        "\n",

        "Presently, many QML algorithms are *heterogeneous* in nature. This means\n",

        "that they require computational resources from both classical and\n",

        "quantum computing. Covalent is a tool that can be used to manage their\n",

        "interaction by sending different tasks to different computational\n",

        "resources and stitching them together as a workflow. While you will be\n",

        "introduced to other concepts in Covalent throughout this tutorial, we\n",

        "define two key components to begin with.\n",

        "\n",

        "1.  **Electrons**. Decorate regular Python functions with `@ct.electron`\n",

        "    to desginate a *task*. These are the atoms of a computation.\n",

        "\n",

        "2.  **Lattices**. Decorate a regular Python function with `@ct.lattice`\n",

        "    to designate a *workflow*. These contain electrons stitched together\n",

        "    to do something useful.\n",

        "\n",

        "    Different electrons can be run remotely on different hardware and\n",

        "    multiple computational paridigms (classical, quantum, etc.: see the\n",

        "    [Covalent\n",

        "    executors](https://covalent.readthedocs.io/en/stable/plugins.html)).\n",

        "    In this tutorial, however, to keep things simple, tasks are run on a\n",

        "    local Dask cluster, which provides (among other things)\n",

        "    auto-parallelization.\n",

        "\n",

        "![\\| A schematic demonstrating the different platforms Covalent can\n",

        "interact\n",

        "with.](../demonstrations/univariate_qvr/covalent_platform.png){.align-center\n",

        "width=\"70.0%\"}\n",

        "\n",

        "Now is a good time to import Covalent and launch the Covalent server!\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 4,

      "metadata": {

        "id": "HxukqHJ4a5MC"

      },

      "outputs": [],

      "source": [

        "import covalent as ct\n",

        "import os\n",

        "import time\n",

        "\n",

        "# Set up Covalent server\n",

        "os.environ[\"COVALENT_SERVER_IFACE_ANY\"] = \"1\"\n",

        "os.system(\"covalent start\")\n",

        "# If you run into any out-of-memory issues with Dask when running this notebook,\n",

        "# Try reducing the number of workers and making a specific memory request. I.e.:\n",

        "# os.system(\"covalent start -m \"2GiB\" -n 2\")\n",

        "# try covalent –help for more info\n",

        "time.sleep(2)  # give the Dask cluster some time to launch"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "hWn7V9Cba5MC"

      },

      "source": [

        "Generating univariate synthetic time series\n",

        "===========================================\n",

        "\n",

        "In this tutorial, we shall deal with a simple and didactic example.\n",

        "Normal time series instances are chosen to be noisy low-amplitude\n",

        "signals normally distributed about the origin. In our case,\n",

        "$x_t \\sim \\mathcal{N}(0, 0.1)$. Series we deem to be anomalous are the\n",

        "same but with randomly inserted spikes with random durations and\n",

        "amplitudes.\n",

        "\n",

        "Let's make a `@ct.electron` to generate each of these synthetic time\n",

        "series sets. For this, we\\'ll need to import Torch. We\\'ll also set the\n",

        "default tensor type and pick a random seed for the whole tutorial for\n",

        "reproducibility.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 5,

      "metadata": {

        "id": "EMKwGXA8a5MC",

        "colab": {

          "base_uri": "https://localhost:8080/",

          "height": 0

        },

        "outputId": "e24f79a4-d37b-48c1-bdbf-6ee154ec33e8"

      },

      "outputs": [

        {

          "output_type": "stream",

          "name": "stderr",

          "text": [

            "/usr/local/lib/python3.10/dist-packages/torch/__init__.py:614: UserWarning: torch.set_default_tensor_type() is deprecated as of PyTorch 2.1, please use torch.set_default_dtype() and torch.set_default_device() as alternatives. (Triggered internally at ../torch/csrc/tensor/python_tensor.cpp:451.)\n",

            "  _C._set_default_tensor_type(t)\n"

          ]

        }

      ],

      "source": [

        "import torch\n",

        "\n",

        "# Seed Torch for reproducibility and set default tensor type\n",

        "GLOBAL_SEED = 1989\n",

        "torch.manual_seed(GLOBAL_SEED)\n",

        "torch.set_default_tensor_type(torch.DoubleTensor)\n",

        "\n",

        "\n",

        "@ct.electron\n",

        "def generate_normal_time_series_set(\n",

        "    p: int, num_series: int, noise_amp: float, t_init: float, t_end: float, seed: int = GLOBAL_SEED\n",

        ") -> tuple:\n",

        "    \"\"\"Generate a normal time series data set where each of the p elements\n",

        "    is drawn from a normal distribution x_t ~ N(0, noise_amp).\n",

        "    \"\"\"\n",

        "    torch.manual_seed(seed)\n",

        "    X = torch.normal(0, noise_amp, (num_series, p))\n",

        "    T = torch.linspace(t_init, t_end, p)\n",

        "    return X, T\n",

        "\n",

        "\n",

        "@ct.electron\n",

        "def generate_anomalous_time_series_set(\n",

        "    p: int,\n",

        "    num_series: int,\n",

        "    noise_amp: float,\n",

        "    spike_amp: float,\n",

        "    max_duration: int,\n",

        "    t_init: float,\n",

        "    t_end: float,\n",

        "    seed: int = GLOBAL_SEED,\n",

        ") -> tuple:\n",

        "    \"\"\"Generate an anomalous time series data set where the p elements of each sequence are\n",

        "    from a normal distribution x_t ~ N(0, noise_amp). Then,\n",

        "    anomalous spikes of random amplitudes and durations are inserted.\n",

        "    \"\"\"\n",

        "    torch.manual_seed(seed)\n",

        "    Y = torch.normal(0, noise_amp, (num_series, p))\n",

        "    for y in Y:\n",

        "        # 5–10 spikes allowed\n",

        "        spike_num = torch.randint(low=5, high=10, size=())\n",

        "        durations = torch.randint(low=1, high=max_duration, size=(spike_num,))\n",

        "        spike_start_idxs = torch.randperm(p - max_duration)[:spike_num]\n",

        "        for start_idx, duration in zip(spike_start_idxs, durations):\n",

        "            y[start_idx : start_idx + duration] += torch.normal(0.0, spike_amp, (duration,))\n",

        "    T = torch.linspace(t_init, t_end, p)\n",

        "    return Y, T"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "Ag9HApCFa5MC"

      },

      "source": [

        "Let\\'s do a quick sanity check and plot a couple of these series.\n",

        "Despite the above function\\'s `@ct.electron` decorators, these can still\n",

        "be used as normal Python functions without using the Covalent server.\n",

        "This is useful for quick checks like this:\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 6,

      "metadata": {

        "colab": {

          "base_uri": "https://localhost:8080/",

          "height": 449

        },

        "id": "JMcxr3jga5MC",

        "outputId": "018c3ace-18d5-4690-b21d-21e939646dd0"

      },

      "outputs": [

        {

          "output_type": "display_data",

          "data": {

            "text/plain": [

              "<Figure size 640x480 with 1 Axes>"

            ],

            "image/png": "iVBORw0KGgoAAAANSUhEUgAAAkYAAAGwCAYAAABM/qr1AAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMSwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/bCgiHAAAACXBIWXMAAA9hAAAPYQGoP6dpAACZbElEQVR4nOzdd3iUVfbA8e+09EZIQgIEQif0XgWRXsTeUQSxiw3dVfa3KqzrYsGuqy6KvaNYUJEIUqT33ltoSQjpfTIzvz/emUlC2tRMyfk8D08mU965eZlkztx7zrkqk8lkQgghhBBCoPb0AIQQQgghvIUERkIIIYQQZhIYCSGEEEKYSWAkhBBCCGEmgZEQQgghhJkERkIIIYQQZhIYCSGEEEKYaT09AF9jNBo5e/Ys4eHhqFQqTw9HCCGEEDYwmUzk5+fTvHlz1Ora54UkMLLT2bNnSUxM9PQwhBBCCOGAU6dO0bJly1pvl8DITuHh4YByYiMiIlx2XL1ez7Jlyxg7diw6nc5lx/UXcn7qJuenbnJ+6ibnp3ZyburmS+cnLy+PxMRE6/t4bSQwspNl+SwiIsLlgVFISAgRERFe/+LyBDk/dZPzUzc5P3WT81M7OTd188XzU18ajCRfCyGEEEKYSWAkhBBCCGEmgZEQQgghhJnkGAkhhPBbBoMBvV7v8OP1ej1arZaSkhIMBoMLR+YfvOn86HQ6NBqN08eRwEgIIYTfMZlMpKWlkZOT4/Rx4uPjOXXqlPSuq4G3nZ+oqCji4+OdGosERkIIIfyOJSiKi4sjJCTE4TdKo9FIQUEBYWFhdTYFbKy85fyYTCaKiorIyMgAICEhweFjSWAkhBDCrxgMBmtQ1LRpU6eOZTQaKSsrIygoSAKjGnjT+QkODgYgIyODuLg4h5fV5H9ZCCGEX7HkFIWEhHh4JKKhWf7Pnckrk8BICCGEX/KGnBfRsFzxfy6BkRBCCCGEmQRGQgghhBBmEhgJIYQQwmF//fUXGo3G6dYI3kICIyFcxWQCfbGnRyGE8GHTpk1DpVLx/PPPV7n+hx9+kJypBiKBkRCu8s1UmN8JCs57eiRCCB8WFBTECy+8QHZ2tsuOWVZW5rJj+TsJjIRwleOroTQX0vd4eiRCiEpMJhNFZeUO/ysuMzj8WJPJZPd4R48eTXx8PPPmzav1Pt999x1du3YlMDCQpKQkXn755Sq3JyUl8eyzzzJ16lQiIiK4++67+eijj4iKimLJkiV06tSJkJAQrrvuOoqKivj4449JSkqiSZMmPPTQQ1W29/j000/p168f4eHhxMfHc8stt1gbKfojafAohCvoS6AkR7lcnOXRoQghqirWG+jy9O8eee59/xpHSIB9b7UajYb//Oc/3HLLLTz00EO0bNmyyu1bt27lhhtuYM6cOdx4442sW7eO+++/n6ZNmzJt2jTr/ebPn8/TTz/NM888A8CaNWsoKirijTfe4KuvviI/P59rrrmGq6++mqioKH799VeOHTvGtddey9ChQ7nxxhsBpSfQs88+S6dOncjIyGDWrFlMmzaNX3/91bmT46UkMBLCFQrSKy4XSWAkhHDO1VdfTa9evXjmmWf44IMPqtz2yiuvMGrUKJ566ikAOnbsyL59+3jppZeqBEYjR47kscces36/Zs0a9Ho977zzDu3atQPguuuu49NPPyU9PZ2wsDC6dOnCZZddxp9//mkNjO644w7rMdq2bcsbb7xB//79KSgo8MsmmhIYCeEKBZWmlSUwEsKrBOs07PvXOIceazQayc/LJzwi3KEtL4J1ju/2/sILLzBy5Egef/zxKtfv37+fK6+8ssp1Q4cO5bXXXsNgMFi3wujXr1+1Y4aEhFiDIoBmzZqRlJREWFhYlesqL5Vt3bqVOXPmsHPnTrKzszEajQCkpqbSuXNnh38+byWBkRCuUJBWcVmW0oTwKiqVyu7lLAuj0Uh5gIaQAG2D7wU2fPhwxo0bx+zZs6vMBNkqNDS02nU6na7K9yqVqsbrLMFPYWEh48aNY9y4cXz++efExsaSmprKuHHj/DahWwIjIVyhylLaBc+NQwjhV55//nl69epFp06drNclJyezdu3aKvdbu3YtHTt2dHjj1NocOHCACxcu8Pzzz5OYmAjAli1bXPoc3kaq0oRwhXzJMRJCuF737t2ZMmUKb7zxhvW6xx57jOXLl/Pss89y6NAhPv74Y956661qS26u0KpVKwICAnjzzTc5duwYP/30E88++6zLn8ebSGAkhCvIjJEQwk3+9a9/WZe2APr06cM333zDV199Rbdu3Xj66af517/+5dByW31iY2P56KOP+Pbbb+nSpQvPP/888+fPd/nzeBNZShPCFSoHRpJjJIRw0EcffVTtuqSkJEpLS6tcd+2113LttdfW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ZYunh+U0CYy8wNdff82sWbN45pln2LZtGz179mTcuHFkZGR4emgeV1hYSM+ePXn77bc9PRSvtGrVKh544AE2bNhASkoKer2esWPHUlhY6OmheVzLli15/vnn2bp1K1u2bGHkyJFceeWV7N2719ND8zqbN2/mvffeo0ePHp4eilfp2rUr586ds/7766+/PD0kr5Gdnc3QoUPR6XT89ttv7Nu3j5dffpkmTZp4emhOk3J9LzBw4ED69+/PW2+9BSj7sSUmJvLggw/y5JNPenh03kOlUrF48WKuuuoqTw/Fa50/f564uDhWrVrF8OHDPT0crxMdHc1LL73EjBkzPD0Ur1FQUECfPn3473//y7///W969erFa6+95ulhedycOXP44Ycf2LFjh6eH4pWefPJJ1q5dy5o1azw9FJeTGSMPKysrY+vWrYwePdp6nVqtZvTo0axfv96DIxO+KDc3F1ACAFHBYDDw1VdfUVhYyODBgz09HK/ywAMPMGnSpCp/g4Ti8OHDNG/enLZt2zJlyhRSU1M9PSSv8dNPP9GvXz+uv/564uLi6N27NwsWLPD0sFxCAiMPy8zMxGAw0KxZsyrXN2vWjLS0NA+NSvgio9HII488wtChQ+nWrZunh+MVdu/eTVhYGIGBgdx7770sXryYLl26eHpYXuOrr75i27ZtzJs3z9ND8ToDBw7ko48+YunSpbzzzjscP36cYcOGkZ+f7+mheYVjx47xzjvv0KFDB37//Xfuu+8+HnroIT7++GNPD81pWk8PQAjhGg888AB79uyRPIhKOnXqxI4dO8jNzWXRokXcfvvtrFq1SoIj4NSpUzz88MOkpKQQFBTk6eF4nQkTJlgv9+jRg4EDB9K6dWu++eYbWYpF+SDWr18//vOf/wDQu3dv9uzZw7vvvsvtt9/u4dE5R2aMPCwmJgaNRkN6enqV69PT04mPj/fQqISvmTlzJkuWLOHPP/+kZcuWnh6O1wgICKB9+/b07duXefPm0bNnT15//XVPD8srbN26lYyMDPr06YNWq0Wr1bJq1SreeOMNtFotBoPB00P0KlFRUXTs2JEjR454eiheISEhodoHjOTkZL9YbpTAyMMCAgLo27cvy5cvt15nNBpZvny55EKIeplMJmbOnMnixYtZsWIFbdq08fSQvJrRaKS0tNTTw/AKo0aNYvfu3ezYseP/27tfkNbCOA7jXziXIypjoBxwCOcsiiyOBQ0KpgWrQwxTq8E/rJgEg1mwnSKWdTFp0aimZVEmBpNFnFHfW34IF2+7F38nPB84ZenL0rOzd2dfV71e18rKinq9nqIo8p5YKIPBQA8PD6pUKt5TCmF2dvbbo0Hu7u6UZZnTov+Hr9IKYGdnR+12W/V6XY1GQ4eHh3p/f9fa2pr3NHeDweCPT2j9fl+9Xk9jY2NK09RxWTFsbGyo2+3q9PRUpVLp61xauVzW8PCw8zpfu7u7ajabStNUb29v6na7urq60vn5ufe0QiiVSt/Ooo2Ojmp8fJwzapI6nY4WFxeVZZmen5+1t7enKIq0vLzsPa0Qtre3NTMzo4ODAy0tLen29lZ5nivPc+9p/y6gEI6OjkKapiGO49BoNML19bX3pEK4vLwMkr5d7Xbbe1oh/O29kRSOj4+9p7lbX18PWZaFOI5DkiRhYWEhXFxceM8qtLm5ubC5uek9oxBarVaoVCohjuMwOTkZWq1WuL+/955VKGdnZ6FWq4WhoaEwNTUV8jz3nvRf8BwjAAAAwxkjAAAAQxgBAAAYwggAAMAQRgAAAIYwAgAAMIQRAACAIYwAAAAMYQQAAGAIIwAAAEMYAYCZn5/X1taW9wwAjggjAAAAw3+lAYCk1dVVnZyc/PFav99XtVr1GQTABWEEAJJeX1/VbDZVq9W0v78vSUqSRFEUOS8D8JN+eQ8AgCIol8uK41gjIyOamJjwngPACWeMAAAADGEEAABgCCMAMHEc6+Pjw3sGAEeEEQCYarWqm5sbPT4+6uXlRZ+fn96TAPwwwggATKfTURRFmp6eVpIkenp68p4E4Ifxc30AAADDHSMAAABDGAEAABjCCAAAwBBGAAAAhjACAAAwhBEAAIAhjAAAAAxhBAAAYAgjAAAAQxgBAAAYwggAAMD8BgKNCRAb0OZrAAAAAElFTkSuQmCC\n"

          },

          "metadata": {}

        }

      ],

      "source": [

        "import matplotlib.pyplot as plt\n",

        "\n",

        "X_norm, T_norm = generate_normal_time_series_set(25, 25, 0.1, 0.1, 2 * torch.pi)\n",

        "Y_anom, T_anom = generate_anomalous_time_series_set(25, 25, 0.1, 0.4, 5, 0, 2 * torch.pi)\n",

        "\n",

        "plt.figure()\n",

        "plt.plot(T_norm, X_norm[0], label=\"Normal\")\n",

        "plt.plot(T_anom, Y_anom[1], label=\"Anomalous\")\n",

        "plt.ylabel(\"$y(t)$\")\n",

        "plt.xlabel(\"t\")\n",

        "plt.grid()\n",

        "leg = plt.legend()"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "y_u4k0J1a5MC"

      },

      "source": [

        "Taking a look at the above, the generated series are what we wanted. We\n",

        "have a simple human-parsable notion of what it is for a time series to\n",

        "be anomalous (big spikes). Of course, we don\\'t need a complicated\n",

        "algorithm to be able to detect such anomalies but this is just a\n",

        "didactic example remember!\n",

        "\n",

        "Like many machine learning algorithms, training is done in mini-batches.\n",

        "Examining the form of the loss function\n",

        "$\\mathcal{L}(\\boldsymbol{\\phi})$, we can see that time series are\n",

        "atomized. In other words, each term in the mean square error is for a\n",

        "given $x_t$ and not measured against the entire series $x$. This allows\n",

        "us to break down the training set $X$ into time-series-independent\n",

        "chunks. Here's an electron to do that:\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 7,

      "metadata": {

        "id": "uAho8PSLa5MC"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def make_atomized_training_set(X: torch.Tensor, T: torch.Tensor) -> list:\n",

        "    \"\"\"Convert input time series data provided in a two-dimensional tensor format\n",

        "    to atomized tuple chunks: (xt, t).\n",

        "    \"\"\"\n",

        "    X_flat = torch.flatten(X)\n",

        "    T_flat = T.repeat(X.size()[0])\n",

        "    atomized = [(xt, t) for xt, t in zip(X_flat, T_flat)]\n",

        "    return atomized"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "yaG5czXla5MD"

      },

      "source": [

        "We now wish to pass this to a cycled `torch.utils.data.DataLoader`.\n",

        "However, this object is not\n",

        "[pickleable](https://docs.python.org/3/library/pickle.html#:~:text=%E2%80%9CPickling%E2%80%9D%20is%20the%20process%20whereby,back%20into%20an%20object%20hierarchy.),\n",

        "which is a requirement of electrons in Covalent. We therefore use the\n",

        "below helper class to create a pickleable version.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 8,

      "metadata": {

        "id": "aN270Z0pa5MD"

      },

      "outputs": [],

      "source": [

        "from collections.abc import Iterator\n",

        "\n",

        "\n",

        "class DataGetter:\n",

        "    \"\"\"A pickleable mock-up of a Python iterator on a torch.utils.Dataloader.\n",

        "    Provide a dataset X and the resulting object O will allow you to use next(O).\n",

        "    \"\"\"\n",

        "\n",

        "    def __init__(self, X: torch.Tensor, batch_size: int, seed: int = GLOBAL_SEED) -> None:\n",

        "        \"\"\"Calls the _init_data method on intialization of a DataGetter object.\"\"\"\n",

        "        torch.manual_seed(seed)\n",

        "        self.X = X\n",

        "        self.batch_size = batch_size\n",

        "        self.data = []\n",

        "        self._init_data(\n",

        "            iter(torch.utils.data.DataLoader(self.X, batch_size=self.batch_size, shuffle=True))\n",

        "        )\n",

        "\n",

        "    def _init_data(self, iterator: Iterator) -> None:\n",

        "        \"\"\"Load all of the iterator into a list.\"\"\"\n",

        "        x = next(iterator, None)\n",

        "        while x is not None:\n",

        "            self.data.append(x)\n",

        "            x = next(iterator, None)\n",

        "\n",

        "    def __next__(self) -> tuple:\n",

        "        \"\"\"Analogous behaviour to the native Python next() but calling the\n",

        "        .pop() of the data attribute.\n",

        "        \"\"\"\n",

        "        try:\n",

        "            return self.data.pop()\n",

        "        except IndexError:  # Caught when the data set runs out of elements\n",

        "            self._init_data(\n",

        "                iter(torch.utils.data.DataLoader(self.X, batch_size=self.batch_size, shuffle=True))\n",

        "            )\n",

        "            return self.data.pop()"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "tP_VGMbLa5MD"

      },

      "source": [

        "We call an instance of the above in an electron\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 9,

      "metadata": {

        "id": "ORHpMJ-qa5MD"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def get_training_cycler(Xtr: torch.Tensor, batch_size: int, seed: int = GLOBAL_SEED) -> DataGetter:\n",

        "    \"\"\"Get an instance of the DataGetter class defined above, which behaves analogously to\n",

        "    next(iterator) but is pickleable.\n",

        "    \"\"\"\n",

        "    return DataGetter(Xtr, batch_size, seed)"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "c67taJ9ba5MD"

      },

      "source": [

        "We now have the means to create synthetic data and cycle through a\n",

        "training set. Next, we need to build our loss function\n",

        "$\\mathcal{L}(\\boldsymbol{\\phi})$ from electrons with the help of\n",

        "`PennyLane`.\n"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "hov7fVBZa5MD"

      },

      "source": [

        "Building the loss function\n",

        "==========================\n",

        "\n",

        "Core to building the loss function is the quantum circuit implementing\n",

        "$V_t(\\boldsymbol{\\alpha}, \\boldsymbol{\\gamma}) := W^{\\dagger}(\\boldsymbol{\\alpha})D(\\boldsymbol{\\gamma}, t)W(\\boldsymbol{\\alpha})$.\n",

        "While there are existing templates in `PennyLane` for implementing\n",

        "$W(\\boldsymbol{\\alpha})$, we use a custom circuit to implement\n",

        "$D(\\boldsymbol{\\gamma}, t)$. Following the approach taken in (also\n",

        "explained in and the appendix of), we create the electron:\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 10,

      "metadata": {

        "id": "PtRU27Jca5MD"

      },

      "outputs": [],

      "source": [

        "import pennylane as qml\n",

        "from itertools import combinations\n",

        "\n",

        "\n",

        "@ct.electron\n",

        "def D(gamma: torch.Tensor, n_qubits: int, k: int = None, get_probs: bool = False) -> None:\n",

        "    \"\"\"Generates an n_qubit quantum circuit according to a k-local Walsh operator\n",

        "    expansion. Here, k-local means that 1 <= k <= n of the n qubits can interact.\n",

        "    See <https://doi.org/10.1088/1367-2630/16/3/033040> for more\n",

        "    details. Optionally return probabilities of bit strings.\n",

        "    \"\"\"\n",

        "    if k is None:\n",

        "        k = n_qubits\n",

        "    cnt = 0\n",

        "    for i in range(1, k + 1):\n",

        "        for comb in combinations(range(n_qubits), i):\n",

        "            if len(comb) == 1:\n",

        "                qml.RZ(gamma[cnt], wires=[comb[0]])\n",

        "                cnt += 1\n",

        "            elif len(comb) > 1:\n",

        "                cnots = [comb[i : i + 2] for i in range(len(comb) - 1)]\n",

        "                for j in cnots:\n",

        "                    qml.CNOT(wires=j)\n",

        "                qml.RZ(gamma[cnt], wires=[comb[-1]])\n",

        "                cnt += 1\n",

        "                for j in cnots[::-1]:\n",

        "                    qml.CNOT(wires=j)\n",

        "    if get_probs:\n",

        "        return qml.probs(wires=range(n_qubits))"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "tkaI_FJra5MD"

      },

      "source": [

        "While the above may seem a little complicated, since we only use a\n",

        "single qubit in this tutorial, the resulting circuit is merely a single\n",

        "$R_z(\\theta)$ gate.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 11,

      "metadata": {

        "colab": {

          "base_uri": "https://localhost:8080/",

          "height": 237

        },

        "id": "uUbcEi6Wa5MD",

        "outputId": "0e967bcd-0874-494e-a1cd-1eb540a6f499"

      },

      "outputs": [

        {

          "output_type": "display_data",

          "data": {

            "text/plain": [

              "<Figure size 400x200 with 1 Axes>"

            ],

            "image/png": "iVBORw0KGgoAAAANSUhEUgAAAaMAAADcCAYAAADdls5UAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMSwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/bCgiHAAAACXBIWXMAAA9hAAAPYQGoP6dpAAAa+klEQVR4nO3de1xT9/0/8FdINOLdotJ6+RIEtK2tFG+1KqjbFN06OqXi5bFHVztjrbMrG7ZMJ17mHq1OrHXO7qH48L6tK4XNta4ibiheaZV6Q5wExVZXtegKkiDXz+8PH+TnSQKEkOSTE17Px4NHez45OeeT84bzMsnnfI5GCCFAREQkUYDsDhARETGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCQdw4iIiKRjGBERkXQMIyIiko5hRERE0jGMiIhIOoYRERFJxzAiIiLpGEZERCSdTnYHiLyhqqoKV65cQVFREUwmE0pLS3H//n1UVVXJ7pqCXq9Hhw4d0LNnT4SHhyMiIgIDBgyAXq+X3TW3Yj3IFsOI/FJtbS0OHz6M9PR0ZGVl4dq1axBCyO6WSzQaDUJCQhAbG4vp06dj3Lhx0OnU9afLelBzNEKtvxFEDphMJqxbtw4ZGRn45ptvZHfHI3r16oX4+HgsWrQIYWFhsrvTJNaDnCaI/IDZbBYpKSmiffv2AkCb+NHr9SIlJUWYzWbZh98O60EtxXdGpHoHDhzAvHnzcO3atWbXDQ4ORnh4OPr374+OHTuiffv2CAjwjXE89fX1qK6uhsViwVdffQWTyYRbt241+zyDwYDNmzdj0qRJXuhl8/ytHufPn8fXX3+NmpoaVdZDNWSnIVFrZGZmCp1O1+i/VocNGyZWr14tTp06JcrKymR3t8XKysrEqVOnxOrVq8XQoUMbfZ06nU5kZmbK7q5f1aOurk4kJycLANZjq7Z6qAnDiFSrsROfVqsViYmJori4WHYX3c5kMonExESh1Wp97gToT/WwWCzixRdftL6Gr7/+2uF6vlwPtWEYkSplZWU5PPHFxMSI8+fPy+6ex50/f17ExMQ4PAFmZWV5vT/+VI+bN2+KkSNHWl+DwWBo9jm+Vg81YhiR6pjNZhESEmL3h280GkVdXZ3s7nlNXV2dMBqNdsfBYDAIi8XitX74Uz0uXLhg91pmzZrl1HN9pR5qxTAi1UlJSfGLE587NHYCXLZsmdf64C/1yM7OFl27drV7Lb///e+d3oYv1EOtGEakKkVFRUKv19t9FKS2E5871dXViejoaLthxiaTyeP79pd6pKWlNTrw4vPPP2/RtmTWQ818YwwlkZPWrVunmDJGq9Vi06ZNPjMcWIaAgABs2rQJWq3W2lZVVYXU1FSP71vt9aivr0dycjKMRiNqa2vtHg8MDERkZGSLtimzHmqmjt8YIjyYUiYjI0PR9vrrr+Opp56S1CPf8fTTT+P1119XtGVmZjo8wbqL2utRWVmJhIQE/O53v2t0neHDh6Ndu3Yt3raMeqgdw4hU4/Dhw3ZTytj+wbdlCxcuVCzfvn0bubm5Htufmutx69YtjB8/3i5MbT333HMu78Pb9VA7hhGpRnp6umJ52LBhGDBggKTe+J6wsDAMHTpU0WZ7zNxJrfUoKCjAs88+i88++0zR7uijxdaEkbfroXYMI1KNrKwsxfL06dMl9cR32R4T22PmTmqsR3Z2NkaPHm03VVG3bt0cfqczatSoVu3Pm/VQO4YRqUJVVZXdCeR73/uepN74rokTJyqWr1275pF7BKmxHmlpaZgyZQrKy8sV7QaDAcePH0fHjh3t2h999NFW7dNb9fAHDCNShStXrtjd/2bgwIGSeuO7IiIiFMv19fW4evWq2/ejpno0jJibN28e6urqFI89++yzOHnyJJ588kmcOHFC8VhrPqJr4K16+AOGEalCUVGRYjk4OBhdunSR1Bvf1bVrV/Tu3VvRZnvs3EEt9bBYLE2OmNu9ezeCg4MBwCNh5K16+AOGEamCyWRSLIeHh0vqie+z/de4J05+aqnH3bt3UVlZ2ejjAwcOxJQpU1BaWorLly8rHnNHGAHeqYc/YBiRKpSWliqW+/fvL6knvq9fv36K5Tt37rh9H2qpR79+/fDJJ59g7969MBgMDtfZv38/evXqpWhz5WLXpvrwME/Uwx8wjEgV7t+/r1i2/bLZU0pKSqDRaBQ/7dq1Q9++fZGQkIBTp04BAN577z1oNBrMmTOn0W0dOnQIAQEBGDFihEcvfrQ9NrbHzh1k1cMZdXV1iu+GNBoN4uLicPHiRSxbtsypbbh6sasj3qiHP9DJ7gCRM2xHILVv396r+w8LC8OPf/xjAIDZbMbp06eRnp6Ov//97zh48CDeeOMN7N27Fzt27MC0adPwwx/+UPH8iooKzJkzB3q9Hrt27YJO57k/Pb1er1j2xMlPdj2qq6tx9uxZxU9BQQHu3buHmpoaAEC7du3QpUsXDB48GJGRkYiMjMT//d//ObV9d31EB3inHv6AYUSq5O25z8LDw7FixQpF2+rVq7F48WKkpKTg8OHD2LFjB4YMGQKj0YiCggIEBQVZ101KSkJJSQnWr1+PJ554wqN9lTEvnLf2eebMGWzbtg1/+tOfcPfu3SbXrampwd27d3HkyBEcOXKkRftxZxipZZ4+2XiUiFz005/+FABw+vRpAEBISAjee+893Lp1C6+99pp1vaysLGzZsgUTJkzAG2+8IaWvalZbW4vNmzcjKioKUVFR2LhxY7NB1BI/+MEP7N69tPZiV2o5hhFRKz38kducOXMQFxeH9PR0/OUvf8G3336LuXPnomvXrti+fTs0Go3EnqrPiRMnMHz4cMyfPx9nzpzxyD727duH0NBQ67shd1zsSi3Hj+mIXLR161YAwNixYxXtW7ZswfHjx/Gzn/0MMTExuH79OrZt24aQkBAZ3VSlO3fu4Fe/+pX1GDdm4MCB1u+DIiMj0bdvX+u7nKqqKty4cQNnz57FqlWrmpz54NKlSwAezJigllnH/Q3DiMgJJpPJ+p1RwwCGnJwcBAcHY+3atYp1g4ODsXnzZsTHx2Pv3r2Ii4trcpQdKZ05cwbPP/88bty44fDx/v374+WXX8ZPfvIThIWFNbmtqKgoBAUFYenSpU7tOzs7GxcvXsRLL72EZ555pqVdp1ZgGBE5obi4GCtXrlS0Pfroozhy5IjDCz6nTZuGkSNH4rPPPsPq1au91U3V279/P1588UWYzWa7x5566imsXbsWEydOVNy4rilCCIwePdquff369Xj88cfx5ptv4sKFC4rHbty4gbFjx+Kjjz7C5MmTXXsh1GL8zojICbGxsRBCQAiB27dvY+3atbh9+zbi4uJQUVHh8DmBgYGK/1LTPv74Y8TFxdkFUadOnZCamor8/HxMnjzZ6SACgF//+tcO2xMTEzF58mTk5+cjNTUVnTp1UjxuNpvxwgsv4OOPP275CyGXMIyIWqhXr15YtGgRlixZgsLCQqc/AqLGHTt2DPHx8dZrhBpER0ejsLAQSUlJLb4I9d69e3jnnXfs2gsLC63/365dOyQlJaGwsNDuu7/q6mrEx8fj2LFjLdovuYZhROSiJUuWoE+fPnj//fdRUlIiuzuq9b///Q+zZ8+2C6JZs2YhOzvb5amGHH2fFBUVhccff9yuvX///jh48CBmzZqlaK+pqcHs2bPx7bffutQHcl6bCKPPP/8c3//+99G9e3d06tQJo0aNwocffii7W6RygYGBSE5ORk1NDVatWiW7O6okhIDRaMSXX36paH/llVewe/duu+t/nHXixAm7W6IDwMmTJxt9jl6vx+7du/HKK68o2r/88ksYjUa7W2aQe/l9GOXk5GDMmDE4evQoEhISMH/+fNy8eRMzZszAunXrZHePVG7evHno06cPdu3aheLiYtndUZ20tDRkZGQo2saPH48tW7a06LuhhzU2aGHDhg3NTluk1WqxZcsWjBs3TtH+0UcfNTvMnFrHr8OotrYWRqMRAQEByM3NxZYtW7Bu3TqcPXsWAwcOxJIlS+zuVknUEh06dMDixYtRW1trN9qOmmaxWLB48WJF2yOPPII9e/a4HERA44MWfv7znzv1fK1Wiz179uCRRx5RtC9evBgWi8XlflHT/DqM/v3vf6O4uBizZ89WXDPQrVs3LFmyBNXV1di5c6e8DpLPMxgMEEJg//79ja6zcOFCCCGwa9cuRfuhQ4cghGj01gVt3Y4dO+ym9dm+fTv69u3r8jadGbTgjH79+mHbtm2Ktjt37vB84UF+HUaHDh0CAEyaNMnusdjYWADA4cOHvdklIsKD2zy8++67irYpU6YgLi6uVdttyaCF5rzwwguYMmWKou3dd9+1u3U5uYdfh1HDHRVt77QIPLhgsXPnzrzrIpEEe/futfuObdGiRa3apiuDFpqTlJSkWDaZTPjHP/7h8vaocX49A0NZWRmABx/LOdK1a1frOmohhGiTn1vbDvsl59XU1Dic0aC122wN29GsUVFRmDBhgsvba82ghaZ85zvfwTPPPKOYpPWvf/0rpk6d6vI2yTG/DiN/ZLFY0LlzZ9ndIBVJS0tDWlqa7G4o2L5bmTdvXqtmNG/toIXGaDQazJs3DwsWLLC25eXltWqb5Jhff0zX8I6osXc/5eXljb5rIiLPuHnzpt0oVtvZD1rCXYMWGmPbt5KSEty6dcst26b/z6/fGTV8V1RUVIRhw4YpHrt58yYqKiowcuRIGV1zWceOHRudC82f/eIXv/C5f92rhdFoxPr16926zdbUw/adRZcuXVp191t3Dlpw5Mknn0Tnzp0Vf3d5eXmtHmxBSn4dRuPGjcM777yDAwcOYObMmYrHsrKyrOuoiUajsZvUsS1o6bxkDYQQGD58OIKCgnDgwAE398rzli5dig0bNsBkMiE4ONilbbRr187tvzOu1gMAzp49q1geMWKEy9cVeWLQgi2tVosRI0YgJyfH2nbmzBmGkZv59cd03/3udzFgwAD8+c9/VnwBWVZWhrfffhvt27fHSy+9JK+D5HG7du1Cfn4+fvOb31jbiouLsWLFCsTFxaFv377QaDStuhbo8uXLSEhIQM+ePREYGIjIyEj88Y9/bHT6mPLycvzyl79ESEgI9Ho9DAYD3nzzTYfveJOSkhAQEIDly5e73D9fc+/ePcWyq3PPeWrQgiO2fWyLn054ml+/M9LpdNi6dStiY2MRExODmTNnokuXLsjIyMC1a9eQmprKCxL9WH19PVasWIHo6GiMGjXK2n7kyBGsXLkSWq0WTzzxBG7evOnyPi5evIjRo0ejsrISCQkJ6NOnD/bt24cFCxbg4sWL2Lhxo2J9s9mMcePG4cyZM5g0aRJmzZqFL774AqmpqTh8+DByc3PRoUMH6/o9evTA3LlzsWHDBixevNgv7hYbGRmJmTNnorKyEpWVlXj66add2o6nBi04MmTIEEyaNAmBgYHWf3CQm4k2IC8vT0yePFl07dpVBAYGipEjR4oPPvhAdreoBRYsWCAAWH8WLFjQ7HM++eQTAUCkpaUp2ouLi8WJEyeExWIRQgih1+tFSEiIS/2KiYkRAMQ///lPa1tVVZWIjo4WAMTx48cV6y9btkwAEMnJyYr25ORkAUC8/fbbdvvIz88XAMTSpUud6pMrx6qlvLGPppSXlyv23/BTWFjo1X44Q/axUgu//piuwciRI/Hpp5+irKwMFosFeXl5mDFjhuxukYdt374dGo0G8fHxivYBAwZg1KhRrb7p3eXLl5Gbm4sJEyYortRv3769dRbvh7/kF0Jg69at6Ny5M1JSUhTbSklJQefOnR1OxhkVFYXw8HDs2LGjVf31J54etEDe1ybCiNoeIQRycnIwaNAg9OjRwyP7aGq6qbFjx6JTp06K6aaKiorw3//+F2PGjLEbUNCpUyeMGTMGV65cwVdffWW3veeeew7Xr1/H5cuX3fsiVMgbgxbI+xhG5JcKCwtx9+5duyH97tTUdFNarRahoaEoKSlBbW1ts+s/3O5oiqrhw4cDQJu/66jw4qAF8i6GEfml69evA4DLw6Gd4cx0U/X19dbRY86s//B6D2t4HQ2vq63y5qAF8i6GEfmlO3fuAAC6d+8utyNu0nBvndLSUsk9kcfTMy2QXAwj8ksNgxPu37/vsX04M92URqNBly5dnF7/4fUeVllZCeDBDBxtFQct+DeGEfmlXr16AYDdzdvcqanveOrq6nD16lWEhoZCp9M1u/7D7Y6+U2p4HQ2vq63hoAX/xzAivzR48GAEBATgP//5j8f20TCVlKNpho4ePWq9wLVBREQE+vTpg2PHjtnd0sFsNuPYsWMIDQ11OCNBw+tw9QJRNeOghbaBYUR+qXv37hgyZAhOnTqF+vr6Vm/v0qVLuHTpkqJt0KBBiImJQU5ODj799FNre3V1tfU6orlz51rbNRoN5s6di4qKCut1SA1WrVqFiooKGI1Gh/vPy8uDTqdzeFL2dxy00Db49XRA1LZNnToVy5cvx8mTJxUn8dLSUsVdRWtqalBaWoqXX37Z2paamoqePXtalxtmlRY28829//77GDNmDH70ox9hxowZeOyxx7Bv3z4UFBRg4cKFduHx1ltvYe/evVizZg2++OILDB06FPn5+Thw4ABGjBiBxMREu9dRUVGBkydPYuLEiW1uklwOWmg7GEbkt+bOnYtVq1Zhz549ilCoqKjAzp07FeuazWZF24oVKxRh1JjBgwcjLy8PS5cuxb59+2A2mzFw4EBs2rQJr732mt36DRfCrlixAhkZGcjJycFjjz2GpKQkLF++3OGsEBkZGaisrMSrr77akpfvFzhooe1gGJEqOfPRW58+fTBz5kx88MEHWLNmjXVUm8FgaHRG7cY0tf6gQYOQnp7u9La6deuG9evXO32Poa1btyIiIgLPP/+8U+u742PJlvLEPi9duuQXgxZk1EON+J0RqYJer1csV1dXO/W83/72t6isrLSbPVst/vWvf+Ho0aNYs2aN0/f8qaqqUiw/PAu4u7haD2cJIRx+ZKnGQQveqIc/YBiRKtj+AVssFqeeFxISgp07d1rfFalNWVkZUlNTMXXqVKefY3tsPHHyc7Uezrp9+7bdSMgePXqoctCCN+rhD/gxHamC7fc3jiYTbUxCQoK7u+M106ZNa/FzbKcMCgoKcld3rFpTD2cEBwfj4sWLWL16NdasWQOdTodz5865dR/e4o16+AO+MyJVCA8PVyybTCZJPfF9thfVNjYxa2t4ox6BgYFYuXIlCgoKsGvXLvTr18/t+/AGb9TDH/CdEamC7R/wrVu3UF5ebp1clB4oLy/H7du3FW2eOPl5sx5hYWEOR9Wpgbfq4Q/4zohUYcCAAdBoNIq2xqbVactsj0lAQABCQ0Pdvh/Wwzneqoc/YBiRKuj1eoSEhCjaDh48KKk3vis7O1uxHBISYjfyzR1YD+d4qx7+gGFEqhEbG6tYbsm1PW2F7TGxPWbuxHo0z5v1UDuGEanG9OnTFcunT5/GlStXJPXG9xQXFyM/P1/RZnvM3In1aJq366F2DCNSjXHjxtndQkGtF7N6wh/+8AfFcu/evRETE+Ox/bEeTfN2PdSOYUSqodPpEB8fr2jbuHEjLly4IKlHvuP8+fN2QTBt2jTrvZQ8gfVonIx6qJ1GtHSSLiKJiouLMXjwYMUUKw23cQgIaJv/tqqvr8f48eNx5MgRa5ter0dBQYHHh0SzHvZk1kPN2uZvC6lWWFgY3nrrLUVbbm4u5s+f3yYnpKyvr8f8+fMVJz4ASE5O9sqJj/VQkl0PVRNEKmM2m0VISIgAoPgxGo2irq5Odve8pq6uThiNRrvjYDAYhMVi8Vo/WI8HfKUeasUwIlXKysoSOp3O7g8/OjpanDt3Tnb3PO7cuXMiOjra7vXrdDqRlZXl9f6wHr5VDzViGJFqZWZmOjwBarVakZiYKEwmk+wuup3JZBKJiYlCq9U6PPFlZmZK6xvr4Vv1UBsOYCBV+9vf/oaEhATU1tY6fHzo0KGYPn06Jk6ciIiICNXNZVdeXo6ioiJkZ2cjPT3d7rqVBjqdDh9++GGLbjXhCazHA75SDzVhGJHqHThwAK+++ipKSkqaXbd3796IiIhAv3790LFjR+j1ep8Z9VVfX4+qqipYLBZcv34dRUVFdpNsOmIwGLB582ZMmjTJC71sHuvhW/VQDblvzIjcw2KxiGXLlgm9Xm/3cYm//uj1erFs2TKf/HKc9aCW4jsj8ivFxcVITU1FRkYGvvnmG9nd8YjevXtj2rRpWLRokc8PF2Y9yFkMI/JLtbW1yM3NRXp6OrKyslBSUgK1/qprNBoYDAbExsZi+vTpiImJUd2V/KwHNYdhRG1CVVUVrl69iqKiIhQVFeHOnTu4f/8+7t+/L7trCh06dECHDh0QFBSEiIgIREREIDQ01O9uO8B6kC2GERERSecbw1aIiKhNYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISDqGERERSccwIiIi6RhGREQkHcOIiIikYxgREZF0DCMiIpKOYURERNIxjIiISLr/BxCn8tHBLwreAAAAAElFTkSuQmCC\n"

          },

          "metadata": {}

        }

      ],

      "source": [

        "n_qubits = 2\n",

        "dev = qml.device(\"default.qubit\", wires=n_qubits, shots=None)\n",

        "D_one_qubit = qml.qnode(dev)(D)\n",

        "_ = qml.draw_mpl(D_one_qubit, decimals=2)(torch.tensor([1, 0]), 1, 1, True)"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "IDWWmn_7a5MD"

      },

      "source": [

        "You may find the general function for $D$\\` useful in case you want to\n",

        "experiment with more qubits and your own (possibly multi-dimensional)\n",

        "data after this tutorial.\n",

        "\n",

        "Next, we define a circuit to calculate the probability of certain bit\n",

        "strings being measured in the computational basis. In our simple\n",

        "example, we work only with one qubit and use the `default.qubit` local\n",

        "quantum circuit simulator.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 12,

      "metadata": {

        "id": "IbWRykxxa5MD"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "@qml.qnode(dev, interface=\"torch\", diff_method=\"backprop\")\n",

        "def get_probs(\n",

        "    xt: torch.Tensor,\n",

        "    t: float,\n",

        "    alpha: torch.Tensor,\n",

        "    gamma: torch.Tensor,\n",

        "    k: int,\n",

        "    U: callable,\n",

        "    W: callable,\n",

        "    D: callable,\n",

        "    n_qubits: int,\n",

        ") -> torch.Tensor:\n",

        "    \"\"\"Measure the probabilities for measuring each bitstring after applying a\n",

        "    circuit of the form W†DWU to the |0⟩^(⊗n) state. This\n",

        "    function is defined for individual sequence elements xt.\n",

        "    \"\"\"\n",

        "    U(xt, wires=range(n_qubits))\n",

        "    W(alpha, wires=range(n_qubits))\n",

        "    D(gamma * t, n_qubits, k)\n",

        "    qml.adjoint(W)(alpha, wires=range(n_qubits))\n",

        "    return qml.probs(range(n_qubits))"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "8UEO-z-Qa5MD"

      },

      "source": [

        "To take the projector $|0\\rangle^{\\otimes n} \\langle 0 |^{\\otimes n}$,\n",

        "we consider only the probability of measuring the bit string of all\n",

        "zeroes, which is the 0th element of the probabilities (bit strings are\n",

        "returned in lexicographic order).\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 13,

      "metadata": {

        "id": "1u3xoE3Sa5MD"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def get_callable_projector_func(\n",

        "    k: int, U: callable, W: callable, D: callable, n_qubits: int, probs_func: callable\n",

        ") -> callable:\n",

        "    \"\"\"Using get_probs() above, take only the probability of measuring the\n",

        "    bitstring of all zeroes (i.e, take the projector\n",

        "    |0⟩^(⊗n)⟨0|^(⊗n)) on the time devolved state.\n",

        "    \"\"\"\n",

        "    callable_proj = lambda xt, t, alpha, gamma: probs_func(\n",

        "        xt, t, alpha, gamma, k, U, W, D, n_qubits\n",

        "    )[0]\n",

        "    return callable_proj"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "7CASnQNva5MD"

      },

      "source": [

        "We now have the necessary ingredients to build\n",

        "$F(\\boldsymbol{\\phi}, x_t)$.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 14,

      "metadata": {

        "id": "Un_xjqcxa5MD"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def F(\n",

        "    callable_proj: callable,\n",

        "    xt: torch.Tensor,\n",

        "    t: float,\n",

        "    alpha: torch.Tensor,\n",

        "    mu: torch.Tensor,\n",

        "    sigma: torch.Tensor,\n",

        "    gamma_length: int,\n",

        "    n_samples: int,\n",

        ") -> torch.Tensor:\n",

        "    \"\"\"Take the classical expecation value of of the projector on zero sampling\n",

        "    the parameters of D from normal distributions. The expecation value is estimated\n",

        "    with an average over n_samples.\n",

        "    \"\"\"\n",

        "    # length of gamma should not exceed 2^n - 1\n",

        "    gammas = sigma.abs() * torch.randn((n_samples, gamma_length)) + mu\n",

        "    expectation = torch.empty(n_samples)\n",

        "    for i, gamma in enumerate(gammas):\n",

        "        expectation[i] = callable_proj(xt, t, alpha, gamma)\n",

        "    return expectation.mean()"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "KkaRe8d9a5MD"

      },

      "source": [

        "We now return to the matter of the penalty function $P_{\\tau}$. We\n",

        "choose\n",

        "\n",

        "$$P_{\\tau}(\\sigma) := \\frac{1}{\\pi} \\arctan(2 \\pi \\tau |\\sigma|).$$\n",

        "\n",

        "As an electron, we have\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 15,

      "metadata": {

        "id": "MijWXiBLa5ME"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def callable_arctan_penalty(tau: float) -> callable:\n",

        "    \"\"\"Create a callable arctan function with a single hyperparameter\n",

        "    tau to penalize large entries of sigma.\n",

        "    \"\"\"\n",

        "    prefac = 1 / (torch.pi)\n",

        "    callable_pen = lambda sigma: prefac * torch.arctan(2 * torch.pi * tau * sigma.abs()).mean()\n",

        "    return callable_pen"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "Mrh5wkIRa5ME"

      },

      "source": [

        "The above is a sigmoidal function chosen because it comes with the\n",

        "useful property of being bounded. The prefactor of $1/\\pi$ is chosen\n",

        "such that the final loss $\\mathcal{L}(\\boldsymbol{\\phi})$ is defined in\n",

        "the range (0, 1), as defined in the below electron.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 16,

      "metadata": {

        "id": "veCMIMuwa5ME"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def get_loss(\n",

        "    callable_proj: callable,\n",

        "    batch: torch.Tensor,\n",

        "    alpha: torch.Tensor,\n",

        "    mu: torch.Tensor,\n",

        "    sigma: torch.Tensor,\n",

        "    gamma_length: int,\n",

        "    n_samples: int,\n",

        "    callable_penalty: callable,\n",

        ") -> torch.Tensor:\n",

        "    \"\"\"Evaluate the loss function ℒ, defined in the background section\n",

        "    for a certain set of parameters.\n",

        "    \"\"\"\n",

        "    X_batch, T_batch = batch\n",

        "    loss = torch.empty(X_batch.size()[0])\n",

        "    for i in range(X_batch.size()[0]):\n",

        "        # unsqueeze required for tensor to have the correct dimension for PennyLane templates\n",

        "        loss[i] = (\n",

        "            1\n",

        "            - F(\n",

        "                callable_proj,\n",

        "                X_batch[i].unsqueeze(0),\n",

        "                T_batch[i].unsqueeze(0),\n",

        "                alpha,\n",

        "                mu,\n",

        "                sigma,\n",

        "                gamma_length,\n",

        "                n_samples,\n",

        "            )\n",

        "        ).square()\n",

        "    return 0.5 * loss.mean() + callable_penalty(sigma)"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "ZxOb7d5ga5ME"

      },

      "source": [

        "Training the normal model\n",

        "=========================\n",

        "\n",

        "Now equipped with a loss function, we need to minimize it with a\n",

        "classical optimization routine. To start this optimization, however, we\n",

        "need some initial parameters. We can generate them with the below\n",

        "electron.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 17,

      "metadata": {

        "id": "ZiirtuMva5ME"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def get_initial_parameters(\n",

        "    W: callable, W_layers: int, n_qubits: int, seed: int = GLOBAL_SEED\n",

        ") -> dict:\n",

        "    \"\"\"Randomly generate initial parameters. We need initial parameters for the\n",

        "    variational circuit ansatz implementing W(alpha) and the standard deviation\n",

        "    and mean (sigma and mu) for the normal distribution we sample gamma from.\n",

        "    \"\"\"\n",

        "    torch.manual_seed(seed)\n",

        "    init_alpha = torch.rand(W.shape(W_layers, n_qubits))\n",

        "    init_mu = torch.rand(1)\n",

        "    # Best to start sigma small and expand if needed\n",

        "    init_sigma = torch.rand(1)\n",

        "    init_params = {\n",

        "        \"alpha\": (2 * torch.pi * init_alpha).clone().detach().requires_grad_(True),\n",

        "        \"mu\": (2 * torch.pi * init_mu).clone().detach().requires_grad_(True),\n",

        "        \"sigma\": (0.1 * init_sigma + 0.05).clone().detach().requires_grad_(True),\n",

        "    }\n",

        "    return init_params"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "wfYxh6Fja5ME"

      },

      "source": [

        "Using the `PyTorch` interface to `PennyLane`, we define our final\n",

        "electron before running the training workflow.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 18,

      "metadata": {

        "id": "zt2IVHlWa5ME"

      },

      "outputs": [],

      "source": [

        "@ct.electron\n",

        "def train_model_gradients(\n",

        "    lr: float,\n",

        "    init_params: dict,\n",

        "    pytorch_optimizer: callable,\n",

        "    cycler: DataGetter,\n",

        "    n_samples: int,\n",

        "    callable_penalty: callable,\n",

        "    batch_iterations: int,\n",

        "    callable_proj: callable,\n",

        "    gamma_length: int,\n",

        "    seed=GLOBAL_SEED,\n",

        "    print_intermediate=False,\n",

        ") -> dict:\n",

        "    \"\"\"Train the QVR model (minimize the loss function) with respect to the\n",

        "    variational parameters using gradient-based training. You need to pass a\n",

        "    PyTorch optimizer and a learning rate (lr).\n",

        "    \"\"\"\n",

        "    torch.manual_seed(seed)\n",

        "    opt = pytorch_optimizer(init_params.values(), lr=lr)\n",

        "    alpha = init_params[\"alpha\"]\n",

        "    mu = init_params[\"mu\"]\n",

        "    sigma = init_params[\"sigma\"]\n",

        "\n",

        "    def closure():\n",

        "        opt.zero_grad()\n",

        "        loss = get_loss(\n",

        "            callable_proj, next(cycler), alpha, mu, sigma, gamma_length, n_samples, callable_penalty\n",

        "        )\n",

        "        loss.backward()\n",

        "        return loss\n",

        "\n",

        "    loss_history = []\n",

        "    for i in range(batch_iterations):\n",

        "        loss = opt.step(closure)\n",

        "        loss_history.append(loss.item())\n",

        "        if batch_iterations % 10 == 0 and print_intermediate:\n",

        "            print(f\"Iteration number {i}\\n Current loss {loss.item()}\\n\")\n",

        "\n",

        "    results_dict = {\n",

        "        \"opt_params\": {\n",

        "            \"alpha\": opt.param_groups[0][\"params\"][0],\n",

        "            \"mu\": opt.param_groups[0][\"params\"][1],\n",

        "            \"sigma\": opt.param_groups[0][\"params\"][2],\n",

        "        },\n",

        "        \"loss_history\": loss_history,\n",

        "    }\n",

        "    return results_dict"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "Nio1PhXga5ME"

      },

      "source": [

        "Now, enter our first `@ct.lattice`. This combines the above electrons,\n",

        "eventually returning the optimal parameters $\\boldsymbol{\\phi}^{\\star}$\n",

        "and the loss with batch iterations.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 19,

      "metadata": {

        "id": "K95eoEaLa5ME"

      },

      "outputs": [],

      "source": [

        "@ct.lattice\n",

        "def training_workflow(\n",

        "    U: callable,\n",

        "    W: callable,\n",

        "    D: callable,\n",

        "    n_qubits: int,\n",

        "    k: int,\n",

        "    probs_func: callable,\n",

        "    W_layers: int,\n",

        "    gamma_length: int,\n",

        "    n_samples: int,\n",

        "    p: int,\n",

        "    num_series: int,\n",

        "    noise_amp: float,\n",

        "    t_init: float,\n",

        "    t_end: float,\n",

        "    batch_size: int,\n",

        "    tau: float,\n",

        "    pytorch_optimizer: callable,\n",

        "    lr: float,\n",

        "    batch_iterations: int,\n",

        "):\n",

        "    \"\"\"\n",

        "    Combine all of the previously defined electrons to do an entire training workflow,\n",

        "    including (1) generating synthetic data, (2) packaging it into training cyclers\n",

        "    (3) preparing the quantum functions and (4) optimizing the loss function with\n",

        "    gradient based optimization. You can find definitions for all of the arguments\n",

        "    by looking at the electrons and text cells above.\n",

        "    \"\"\"\n",

        "\n",

        "    X, T = generate_normal_time_series_set(p, num_series, noise_amp, t_init, t_end)\n",

        "    Xtr = make_atomized_training_set(X, T)\n",

        "    cycler = get_training_cycler(Xtr, batch_size)\n",

        "    init_params = get_initial_parameters(W, W_layers, n_qubits)\n",

        "    callable_penalty = callable_arctan_penalty(tau)\n",

        "    callable_proj = get_callable_projector_func(k, U, W, D, n_qubits, probs_func)\n",

        "    results_dict = train_model_gradients(\n",

        "        lr,\n",

        "        init_params,\n",

        "        pytorch_optimizer,\n",

        "        cycler,\n",

        "        n_samples,\n",

        "        callable_penalty,\n",

        "        batch_iterations,\n",

        "        callable_proj,\n",

        "        gamma_length,\n",

        "        print_intermediate=False,\n",

        "    )\n",

        "    return results_dict"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "_cVnbMBQa5ME"

      },

      "source": [

        "Before running this workflow, we define all of the input parameters.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 20,

      "metadata": {

        "id": "zrgDBKbCa5ME"

      },

      "outputs": [],

      "source": [

        "general_options = {\n",

        "    \"U\": qml.AngleEmbedding,\n",

        "    \"W\": qml.StronglyEntanglingLayers,\n",

        "    \"D\": D,\n",

        "    \"n_qubits\": 1,\n",

        "    \"probs_func\": get_probs,\n",

        "    \"gamma_length\": 1,\n",

        "    \"n_samples\": 10,\n",

        "    \"p\": 25,\n",

        "    \"num_series\": 25,\n",

        "    \"noise_amp\": 0.1,\n",

        "    \"t_init\": 0.1,\n",

        "    \"t_end\": 2 * torch.pi,\n",

        "    \"k\": 1,\n",

        "}\n",

        "\n",

        "training_options = {\n",

        "    \"batch_size\": 10,\n",

        "    \"tau\": 5,\n",

        "    \"pytorch_optimizer\": torch.optim.Adam,\n",

        "    \"lr\": 0.01,\n",

        "    \"batch_iterations\": 100,\n",

        "    \"W_layers\": 2,\n",

        "}\n",

        "\n",

        "training_options.update(general_options)"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "lOYhgeYRa5MF"

      },

      "source": [

        "We can now dispatch the lattice to the Covalent server.\n"

      ]

    },

    {

      "cell_type": "code",

      "execution_count": 21,

      "metadata": {

        "id": "-QCVzIZya5MF"

      },

      "outputs": [],

      "source": [

        "tr_dispatch_id = ct.dispatch(training_workflow)(**training_options)"

      ]

    },

    {

      "cell_type": "markdown",

      "metadata": {

        "id": "BRxajqpva5MF"

      },

      "source": [

        "If you are running the notebook version of this tutorial, if you\n",

        "navigate to <http://localhost:48008/> you can view the workflow on the\n",

        "Covalent GUI. It will look like the screenshot below, showing nicely how\n",

        "all of the electrons defined above interact with each other in the\n",

        "workflow. You can also track the progress of the calculation here.\n",

        "\n",

        "![A screenshot of the Covalent GUI for the training\n",

        "workflow.](../demonstrations/univariate_qvr/covalent_tutorial_screenshot.png){.align-center\n",

        "width=\"85.0%\"}\n"

      ]

    },