{ "cells": [ { "cell_type": "markdown", "metadata": { "id": "2kWo-GNlwpT6" }, "source": [ "##### Copyright 2021 The TensorFlow Authors." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "5w2rucWZwpUA" }, "outputs": [], "source": [ "#@title Licensed under the Apache License, Version 2.0 (the \"License\");\n", "# you may not use this file except in compliance with the License.\n", "# You may obtain a copy of the License at\n", "#\n", "# https://www.apache.org/licenses/LICENSE-2.0\n", "#\n", "# Unless required by applicable law or agreed to in writing, software\n", "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", "# See the License for the specific language governing permissions and\n", "# limitations under the License." ] }, { "cell_type": "markdown", "metadata": { "id": "GHebkma_wpUC" }, "source": [ "# Parametrized Quantum Circuits for Reinforcement Learning" ] }, { "cell_type": "markdown", "metadata": { "id": "xQf8eEUewpUD" }, "source": [ "\n", " \n", " \n", " \n", " \n", "
\n", " View on TensorFlow.org\n", " \n", " Run in Google Colab\n", " \n", " View source on GitHub\n", " \n", " Download notebook\n", "
" ] }, { "cell_type": "markdown", "metadata": { "id": "8NJTIUX_wpUE" }, "source": [ "Quantum computers have been shown to provide computational advantages in certain problem areas. The field of quantum reinforcement learning (QRL) aims to harness this boost by designing RL agents that rely on quantum models of computation.\n", "\n", "In this tutorial, you will implement two reinforcement learning algorithms based on parametrized/variational quantum circuits (PQCs or VQCs), namely a policy-gradient and a deep Q-learning implementation. These algorithms were introduced by [[1] Jerbi et al.](https://arxiv.org/abs/2103.05577) and [[2] Skolik et al.](https://arxiv.org/abs/2103.15084), respectively." ] }, { "cell_type": "markdown", "metadata": { "id": "bYkcUIu4wpUF" }, "source": [ "You will implement a PQC with data re-uploading in TFQ, and use it as:\n", "1. an RL policy trained with a policy-gradient method,\n", "2. a Q-function approximator trained with deep Q-learning,\n", "\n", "each solving [CartPole-v1](http://gym.openai.com/envs/CartPole-v1/), a benchmarking task from OpenAI Gym. Note that, as showcased in [[1]](https://arxiv.org/abs/2103.05577) and [[2]](https://arxiv.org/abs/2103.15084), these agents can also be used to solve other task-environment from OpenAI Gym, such as [FrozenLake-v0](http://gym.openai.com/envs/FrozenLake-v0/), [MountainCar-v0](http://gym.openai.com/envs/MountainCar-v0/) or [Acrobot-v1](http://gym.openai.com/envs/Acrobot-v1/)." ] }, { "cell_type": "markdown", "metadata": { "id": "gw0D-uwmwpUF" }, "source": [ "Features of this implementation:\n", "- you will learn how to use a `tfq.layers.ControlledPQC` to implement a PQC with data re-uploading, appearing in many applications of QML. This implementation also naturally allows using trainable scaling parameters at the input of the PQC, to increase its expressivity,\n", "- you will learn how to implement observables with trainable weights at the output of a PQC, to allow a flexible range of output values,\n", "- you will learn how a `tf.keras.Model` can be trained with non-trivial ML loss functions, i.e., that are not compatible with `model.compile` and `model.fit`, using a `tf.GradientTape`." ] }, { "cell_type": "markdown", "metadata": { "id": "kLSoeBdTwpUF" }, "source": [ "## Setup" ] }, { "cell_type": "markdown", "metadata": { "id": "pgTTkiY0wpUG" }, "source": [ "Install TensorFlow:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "bPTH8ScrwpUG" }, "outputs": [], "source": [ "!pip install tensorflow==2.15.0" ] }, { "cell_type": "markdown", "metadata": { "id": "jlbSE9jXwpUH" }, "source": [ "Install TensorFlow Quantum:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "MZeJimx6wpUI" }, "outputs": [], "source": [ "!pip install tensorflow-quantum==0.7.3" ] }, { "cell_type": "markdown", "metadata": { "id": "xLEu0I6qwpUI" }, "source": [ "Install Gym:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "id": "6A2JRKhMwpUJ" }, "outputs": [], "source": [ "!pip install gym==0.18.0" ] }, { "cell_type": "markdown", "metadata": { "id": "Id8vB7FiwpUJ" }, "source": [ "Now import TensorFlow and the module dependencies:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "colab": {}, "colab_type": "code", "id": "4Ql5PW-ACO0J" }, "outputs": [], "source": [ "# Update package resources to account for version changes.\n", "import importlib, pkg_resources\n", "importlib.reload(pkg_resources)" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "id": "RIIYRJ79wpUK" }, "outputs": [], "source": [ "import tensorflow as tf\n", "import tensorflow_quantum as tfq\n", "\n", "import gym, cirq, sympy\n", "import numpy as np\n", "from functools import reduce\n", "from collections import deque, defaultdict\n", "import matplotlib.pyplot as plt\n", "from cirq.contrib.svg import SVGCircuit\n", "tf.get_logger().setLevel('ERROR')" ] }, { "cell_type": "markdown", "metadata": { "id": "jxWGru_NwpUK" }, "source": [ "## 1. Build a PQC with data re-uploading" ] }, { "cell_type": "markdown", "metadata": { "id": "85woLQQswpUL" }, "source": [ "At the core of both RL algorithms you are implementing is a PQC that takes as input the agent's state $s$ in the environment (i.e., a numpy array) and outputs a vector of expectation values. These expectation values are then post-processed, either to produce an agent's policy $\\pi(a|s)$ or approximate Q-values $Q(s,a)$. In this way, the PQCs are playing an analog role to that of deep neural networks in modern deep RL algorithms.\n", "\n", "A popular way to encode an input vector in a PQC is through the use of single-qubit rotations, where rotation angles are controlled by the components of this input vector. In order to get a [highly-expressive model](https://arxiv.org/abs/2008.08605), these single-qubit encodings are not performed only once in the PQC, but in several \"[re-uploadings](https://quantum-journal.org/papers/q-2020-02-06-226/)\", interlayed with variational gates. The layout of such a PQC is depicted below:\n", "\n", "" ] }, { "cell_type": "markdown", "metadata": { "id": "vxw3Rz0awpUL" }, "source": [ "As discussed in [[1]](https://arxiv.org/abs/2103.05577) and [[2]](https://arxiv.org/abs/2103.15084), a way to further enhance the expressivity and trainability of data re-uploading PQCs is to use trainable input-scaling parameters $\\boldsymbol{\\lambda}$ for each encoding gate of the PQC, and trainable observable weights $\\boldsymbol{w}$ at its output." ] }, { "cell_type": "markdown", "metadata": { "id": "rNSjI-OywpUM" }, "source": [ "### 1.1 Cirq circuit for ControlledPQC" ] }, { "cell_type": "markdown", "metadata": { "id": "OCYrUUwswpUM" }, "source": [ "The first step is to implement in Cirq the quantum circuit to be used as the PQC. For this, start by defining basic unitaries to be applied in the circuits, namely an arbitrary single-qubit rotation and an entangling layer of CZ gates:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "id": "X4P5EORYwpUM" }, "outputs": [], "source": [ "def one_qubit_rotation(qubit, symbols):\n", " \"\"\"\n", " Returns Cirq gates that apply a rotation of the bloch sphere about the X,\n", " Y and Z axis, specified by the values in `symbols`.\n", " \"\"\"\n", " return [cirq.rx(symbols[0])(qubit),\n", " cirq.ry(symbols[1])(qubit),\n", " cirq.rz(symbols[2])(qubit)]\n", "\n", "def entangling_layer(qubits):\n", " \"\"\"\n", " Returns a layer of CZ entangling gates on `qubits` (arranged in a circular topology).\n", " \"\"\"\n", " cz_ops = [cirq.CZ(q0, q1) for q0, q1 in zip(qubits, qubits[1:])]\n", " cz_ops += ([cirq.CZ(qubits[0], qubits[-1])] if len(qubits) != 2 else [])\n", " return cz_ops" ] }, { "cell_type": "markdown", "metadata": { "id": "cTgpkm6iwpUM" }, "source": [ "Now, use these functions to generate the Cirq circuit:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "id": "PEicpzq9wpUN" }, "outputs": [], "source": [ "def generate_circuit(qubits, n_layers):\n", " \"\"\"Prepares a data re-uploading circuit on `qubits` with `n_layers` layers.\"\"\"\n", " # Number of qubits\n", " n_qubits = len(qubits)\n", " \n", " # Sympy symbols for variational angles\n", " params = sympy.symbols(f'theta(0:{3*(n_layers+1)*n_qubits})')\n", " params = np.asarray(params).reshape((n_layers + 1, n_qubits, 3))\n", " \n", " # Sympy symbols for encoding angles\n", " inputs = sympy.symbols(f'x(0:{n_layers})'+f'_(0:{n_qubits})')\n", " inputs = np.asarray(inputs).reshape((n_layers, n_qubits))\n", " \n", " # Define circuit\n", " circuit = cirq.Circuit()\n", " for l in range(n_layers):\n", " # Variational layer\n", " circuit += cirq.Circuit(one_qubit_rotation(q, params[l, i]) for i, q in enumerate(qubits))\n", " circuit += entangling_layer(qubits)\n", " # Encoding layer\n", " circuit += cirq.Circuit(cirq.rx(inputs[l, i])(q) for i, q in enumerate(qubits))\n", "\n", " # Last varitional layer\n", " circuit += cirq.Circuit(one_qubit_rotation(q, params[n_layers, i]) for i,q in enumerate(qubits))\n", " \n", " return circuit, list(params.flat), list(inputs.flat)" ] }, { "cell_type": "markdown", "metadata": { "id": "ZL8MvT21wpUN" }, "source": [ "Check that this produces a circuit that is alternating between variational and encoding layers." ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "colab": { "base_uri": "https://localhost:8080/", "height": 188 }, "id": "M4LFL2bQwpUO", "outputId": "e446c0c0-f844-4d63-9f29-d01f8aeed411" }, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "findfont: Font family ['Arial'] not found. Falling back to DejaVu Sans.\n" ] }, { "data": { "image/svg+xml": "(0, 0): (0, 1): (0, 2): Rx(theta0)Rx(theta3)Rx(theta6)Ry(theta1)Ry(theta4)Ry(theta7)Rz(theta2)Rz(theta5)Rz(theta8)Rx(x0_0)Rx(x0_1)Rx(x0_2)Rx(theta9)Rx(theta12)Rx(theta15)Ry(theta10)Ry(theta13)Ry(theta16)Rz(theta11)Rz(theta14)Rz(theta17)", "text/plain": [ "" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "n_qubits, n_layers = 3, 1\n", "qubits = cirq.GridQubit.rect(1, n_qubits)\n", "circuit, _, _ = generate_circuit(qubits, n_layers)\n", "SVGCircuit(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "-RrFUkT3wpUP" }, "source": [ "### 1.2 ReUploadingPQC layer using ControlledPQC\n", "\n", "To construct the re-uploading PQC from the figure above, you can create a custom Keras layer. This layer will manage the trainable parameters (variational angles $\\boldsymbol{\\theta}$ and input-scaling parameters $\\boldsymbol{\\lambda}$) and resolve the input values (input state $s$) into the appropriate symbols in the circuit." ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "id": "7XJvWgQ4wpUP" }, "outputs": [], "source": [ "class ReUploadingPQC(tf.keras.layers.Layer):\n", " \"\"\"\n", " Performs the transformation (s_1, ..., s_d) -> (theta_1, ..., theta_N, lmbd[1][1]s_1, ..., lmbd[1][M]s_1,\n", " ......., lmbd[d][1]s_d, ..., lmbd[d][M]s_d) for d=input_dim, N=theta_dim and M=n_layers.\n", " An activation function from tf.keras.activations, specified by `activation` ('linear' by default) is\n", " then applied to all lmbd[i][j]s_i.\n", " All angles are finally permuted to follow the alphabetical order of their symbol names, as processed\n", " by the ControlledPQC.\n", " \"\"\"\n", "\n", " def __init__(self, qubits, n_layers, observables, activation=\"linear\", name=\"re-uploading_PQC\"):\n", " super(ReUploadingPQC, self).__init__(name=name)\n", " self.n_layers = n_layers\n", " self.n_qubits = len(qubits)\n", "\n", " circuit, theta_symbols, input_symbols = generate_circuit(qubits, n_layers)\n", "\n", " theta_init = tf.random_uniform_initializer(minval=0.0, maxval=np.pi)\n", " self.theta = tf.Variable(\n", " initial_value=theta_init(shape=(1, len(theta_symbols)), dtype=\"float32\"),\n", " trainable=True, name=\"thetas\"\n", " )\n", " \n", " lmbd_init = tf.ones(shape=(self.n_qubits * self.n_layers,))\n", " self.lmbd = tf.Variable(\n", " initial_value=lmbd_init, dtype=\"float32\", trainable=True, name=\"lambdas\"\n", " )\n", " \n", " # Define explicit symbol order.\n", " symbols = [str(symb) for symb in theta_symbols + input_symbols]\n", " self.indices = tf.constant([symbols.index(a) for a in sorted(symbols)])\n", " \n", " self.activation = activation\n", " self.empty_circuit = tfq.convert_to_tensor([cirq.Circuit()])\n", " self.computation_layer = tfq.layers.ControlledPQC(circuit, observables) \n", "\n", " def call(self, inputs):\n", " # inputs[0] = encoding data for the state.\n", " batch_dim = tf.gather(tf.shape(inputs[0]), 0)\n", " tiled_up_circuits = tf.repeat(self.empty_circuit, repeats=batch_dim)\n", " tiled_up_thetas = tf.tile(self.theta, multiples=[batch_dim, 1])\n", " tiled_up_inputs = tf.tile(inputs[0], multiples=[1, self.n_layers])\n", " scaled_inputs = tf.einsum(\"i,ji->ji\", self.lmbd, tiled_up_inputs)\n", " squashed_inputs = tf.keras.layers.Activation(self.activation)(scaled_inputs)\n", "\n", " joined_vars = tf.concat([tiled_up_thetas, squashed_inputs], axis=1)\n", " joined_vars = tf.gather(joined_vars, self.indices, axis=1)\n", " \n", " return self.computation_layer([tiled_up_circuits, joined_vars])" ] }, { "cell_type": "markdown", "metadata": { "id": "_u3QBKbvwpUP" }, "source": [ "## 2. Policy-gradient RL with PQC policies" ] }, { "cell_type": "markdown", "metadata": { "id": "4deMRl86wpUP" }, "source": [ "In this section, you will implement the policy-gradient algorithm presented in [1]. For this, you will start by constructing, out of the PQC that was just defined, the `softmax-VQC` policy (where VQC stands for variational quantum circuit):\n", "$$ \\pi_\\theta(a|s) = \\frac{e^{\\beta \\langle O_a \\rangle_{s,\\theta}}}{\\sum_{a'} e^{\\beta \\langle O_{a'} \\rangle_{s,\\theta}}} $$\n", "where $\\langle O_a \\rangle_{s,\\theta}$ are expectation values of observables $O_a$ (one per action) measured at the output of the PQC, and $\\beta$ is a tunable inverse-temperature parameter. " ] }, { "cell_type": "markdown", "metadata": { "id": "Wb7zQF5AwpUQ" }, "source": [ "You can adopt the same observables used in [1] for CartPole, namely a global $Z_0Z_1Z_2Z_3$ Pauli product acting on all qubits, weighted by an action-specific weight for each action. To implement the weighting of the Pauli product, you can use an extra `tf.keras.layers.Layer` that stores the action-specific weights and applies them multiplicatively on the expectation value $\\langle Z_0Z_1Z_2Z_3 \\rangle_{s,\\theta}$." ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "id": "kPLHsGRewpUQ" }, "outputs": [], "source": [ "class Alternating(tf.keras.layers.Layer):\n", " def __init__(self, output_dim):\n", " super(Alternating, self).__init__()\n", " self.w = tf.Variable(\n", " initial_value=tf.constant([[(-1.)**i for i in range(output_dim)]]), dtype=\"float32\",\n", " trainable=True, name=\"obs-weights\")\n", "\n", " def call(self, inputs):\n", " return tf.matmul(inputs, self.w)" ] }, { "cell_type": "markdown", "metadata": { "id": "HdyTMNPTwpUQ" }, "source": [ "Prepare the definition of your PQC:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "id": "l3yZCMhywpUQ" }, "outputs": [], "source": [ "n_qubits = 4 # Dimension of the state vectors in CartPole\n", "n_layers = 5 # Number of layers in the PQC\n", "n_actions = 2 # Number of actions in CartPole\n", "\n", "qubits = cirq.GridQubit.rect(1, n_qubits)" ] }, { "cell_type": "markdown", "metadata": { "id": "NMGNUCmOwpUR" }, "source": [ "and its observables:" ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "id": "qMAc2_--wpUR" }, "outputs": [], "source": [ "ops = [cirq.Z(q) for q in qubits]\n", "observables = [reduce((lambda x, y: x * y), ops)] # Z_0*Z_1*Z_2*Z_3" ] }, { "cell_type": "markdown", "metadata": { "id": "px9D6vE8wpUR" }, "source": [ "With this, define a `tf.keras.Model` that applies, sequentially, the `ReUploadingPQC` layer previously defined, followed by a post-processing layer that computes the weighted observables using `Alternating`, which are then fed into a `tf.keras.layers.Softmax` layer that outputs the `softmax-VQC` policy of the agent." ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "id": "-ivAvce6wpUR" }, "outputs": [], "source": [ "def generate_model_policy(qubits, n_layers, n_actions, beta, observables):\n", " \"\"\"Generates a Keras model for a data re-uploading PQC policy.\"\"\"\n", "\n", " input_tensor = tf.keras.Input(shape=(len(qubits), ), dtype=tf.dtypes.float32, name='input')\n", " re_uploading_pqc = ReUploadingPQC(qubits, n_layers, observables)([input_tensor])\n", " process = tf.keras.Sequential([\n", " Alternating(n_actions),\n", " tf.keras.layers.Lambda(lambda x: x * beta),\n", " tf.keras.layers.Softmax()\n", " ], name=\"observables-policy\")\n", " policy = process(re_uploading_pqc)\n", " model = tf.keras.Model(inputs=[input_tensor], outputs=policy)\n", "\n", " return model\n", "\n", "model = generate_model_policy(qubits, n_layers, n_actions, 1.0, observables)" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "colab": { "base_uri": "https://localhost:8080/", "height": 232 }, "id": "ANysIOrswpUS", "outputId": "131f0db1-8525-4cfa-a6c5-2b0c8573bdb1" }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "" ] }, "execution_count": 10, "metadata": { "tags": [] }, "output_type": "execute_result" } ], "source": [ "tf.keras.utils.plot_model(model, show_shapes=True, dpi=70)" ] }, { "cell_type": "markdown", "metadata": { "id": "Ec-s2ECYwpUS" }, "source": [ "You can now train the PQC policy on CartPole-v1, using, e.g., the basic `REINFORCE` algorithm (see Alg. 1 in [1]). Pay attention to the following points:\n", "1. Because scaling parameters, variational angles and observables weights are trained with different learning rates, it is convenient to define 3 separate optimizers with their own learning rates, each updating one of these groups of parameters.\n", "2. The loss function in policy-gradient RL is\n", " $$ \\mathcal{L}(\\theta) = -\\frac{1}{|\\mathcal{B}|}\\sum_{s_0,a_0,r_1,s_1,a_1, \\ldots \\in \\mathcal{B}} \\left(\\sum_{t=0}^{H-1} \\log(\\pi_\\theta(a_t|s_t)) \\sum_{t'=1}^{H-t} \\gamma^{t'} r_{t+t'} \\right)$$\n", "for a batch $\\mathcal{B}$ of episodes $(s_0,a_0,r_1,s_1,a_1, \\ldots)$ of interactions in the environment following the policy $\\pi_\\theta$. This is different from a supervised learning loss with fixed target values that the model should fit, which make it impossible to use a simple function call like `model.fit` to train the policy. Instead, using a `tf.GradientTape` allows to keep track of the computations involving the PQC (i.e., policy sampling) and store their contributions to the loss during the interaction. After running a batch of episodes, you can then apply backpropagation on these computations to get the gradients of the loss with respect to the PQC parameters and use the optimizers to update the policy-model." ] }, { "cell_type": "markdown", "metadata": { "id": "LHS7UlTHwpUS" }, "source": [ "Start by defining a function that gathers episodes of interaction with the environment:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "id": "dYepv83JwpUT" }, "outputs": [], "source": [ "def gather_episodes(state_bounds, n_actions, model, n_episodes, env_name):\n", " \"\"\"Interact with environment in batched fashion.\"\"\"\n", "\n", " trajectories = [defaultdict(list) for _ in range(n_episodes)]\n", " envs = [gym.make(env_name) for _ in range(n_episodes)]\n", "\n", " done = [False for _ in range(n_episodes)]\n", " states = [e.reset() for e in envs]\n", "\n", " while not all(done):\n", " unfinished_ids = [i for i in range(n_episodes) if not done[i]]\n", " normalized_states = [s/state_bounds for i, s in enumerate(states) if not done[i]]\n", "\n", " for i, state in zip(unfinished_ids, normalized_states):\n", " trajectories[i]['states'].append(state)\n", "\n", " # Compute policy for all unfinished envs in parallel\n", " states = tf.convert_to_tensor(normalized_states)\n", " action_probs = model([states])\n", "\n", " # Store action and transition all environments to the next state\n", " states = [None for i in range(n_episodes)]\n", " for i, policy in zip(unfinished_ids, action_probs.numpy()):\n", " action = np.random.choice(n_actions, p=policy)\n", " states[i], reward, done[i], _ = envs[i].step(action)\n", " trajectories[i]['actions'].append(action)\n", " trajectories[i]['rewards'].append(reward)\n", "\n", " return trajectories" ] }, { "cell_type": "markdown", "metadata": { "id": "TJRGD1g1wpUT" }, "source": [ "and a function that computes discounted returns $\\sum_{t'=1}^{H-t} \\gamma^{t'} r_{t+t'}$ out of the rewards $r_t$ collected in an episode:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "id": "KGDLrNN1wpUT" }, "outputs": [], "source": [ "def compute_returns(rewards_history, gamma):\n", " \"\"\"Compute discounted returns with discount factor `gamma`.\"\"\"\n", " returns = []\n", " discounted_sum = 0\n", " for r in rewards_history[::-1]:\n", " discounted_sum = r + gamma * discounted_sum\n", " returns.insert(0, discounted_sum)\n", "\n", " # Normalize them for faster and more stable learning\n", " returns = np.array(returns)\n", " returns = (returns - np.mean(returns)) / (np.std(returns) + 1e-8)\n", " returns = returns.tolist()\n", " \n", " return returns" ] }, { "cell_type": "markdown", "metadata": { "id": "xkuUMdskwpUT" }, "source": [ "Define the hyperparameters:" ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "id": "QUuSU1LRwpUU" }, "outputs": [], "source": [ "state_bounds = np.array([2.4, 2.5, 0.21, 2.5])\n", "gamma = 1\n", "batch_size = 10\n", "n_episodes = 1000" ] }, { "cell_type": "markdown", "metadata": { "id": "PM8uFSLMwpUU" }, "source": [ "Prepare the optimizers:" ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "id": "2fxGvCKpwpUU" }, "outputs": [], "source": [ "optimizer_in = tf.keras.optimizers.Adam(learning_rate=0.1, amsgrad=True)\n", "optimizer_var = tf.keras.optimizers.Adam(learning_rate=0.01, amsgrad=True)\n", "optimizer_out = tf.keras.optimizers.Adam(learning_rate=0.1, amsgrad=True)\n", "\n", "# Assign the model parameters to each optimizer\n", "w_in, w_var, w_out = 1, 0, 2" ] }, { "cell_type": "markdown", "metadata": { "id": "JbVHz19-wpUU" }, "source": [ "Implement a function that updates the policy using states, actions and returns:" ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "id": "zLfbu8Q2wpUV" }, "outputs": [], "source": [ "@tf.function\n", "def reinforce_update(states, actions, returns, model):\n", " states = tf.convert_to_tensor(states)\n", " actions = tf.convert_to_tensor(actions)\n", " returns = tf.convert_to_tensor(returns)\n", "\n", " with tf.GradientTape() as tape:\n", " tape.watch(model.trainable_variables)\n", " logits = model(states)\n", " p_actions = tf.gather_nd(logits, actions)\n", " log_probs = tf.math.log(p_actions)\n", " loss = tf.math.reduce_sum(-log_probs * returns) / batch_size\n", " grads = tape.gradient(loss, model.trainable_variables)\n", " for optimizer, w in zip([optimizer_in, optimizer_var, optimizer_out], [w_in, w_var, w_out]):\n", " optimizer.apply_gradients([(grads[w], model.trainable_variables[w])])" ] }, { "cell_type": "markdown", "metadata": { "id": "rrPlDlqLwpUV" }, "source": [ "Now implement the main training loop of the agent." ] }, { "cell_type": "markdown", "metadata": { "id": "95Foz1XewpUV" }, "source": [ "Note: This agent may need to simulate several million quantum circuits and can take as much as ~20 minutes to finish training." ] }, { "cell_type": "code", "execution_count": 16, "metadata": { "colab": { "base_uri": "https://localhost:8080/" }, "id": "cYSDSNGlwpUW", "outputId": "ae603811-b930-4484-a002-d26c4673fa06" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Finished episode 10 Average rewards: 22.3\n", "Finished episode 20 Average rewards: 27.4\n", "Finished episode 30 Average rewards: 24.7\n", "Finished episode 40 Average rewards: 21.2\n", "Finished episode 50 Average rewards: 33.9\n", "Finished episode 60 Average rewards: 31.3\n", "Finished episode 70 Average rewards: 37.3\n", "Finished episode 80 Average rewards: 34.4\n", "Finished episode 90 Average rewards: 58.4\n", "Finished episode 100 Average rewards: 33.2\n", "Finished episode 110 Average rewards: 67.9\n", "Finished episode 120 Average rewards: 63.9\n", "Finished episode 130 Average rewards: 83.5\n", "Finished episode 140 Average rewards: 88.0\n", "Finished episode 150 Average rewards: 142.9\n", "Finished episode 160 Average rewards: 204.7\n", "Finished episode 170 Average rewards: 138.1\n", "Finished episode 180 Average rewards: 183.0\n", "Finished episode 190 Average rewards: 196.0\n", "Finished episode 200 Average rewards: 302.0\n", "Finished episode 210 Average rewards: 374.4\n", "Finished episode 220 Average rewards: 329.1\n", "Finished episode 230 Average rewards: 307.8\n", "Finished episode 240 Average rewards: 359.6\n", "Finished episode 250 Average rewards: 400.7\n", "Finished episode 260 Average rewards: 414.4\n", "Finished episode 270 Average rewards: 394.9\n", "Finished episode 280 Average rewards: 470.7\n", "Finished episode 290 Average rewards: 459.7\n", "Finished episode 300 Average rewards: 428.7\n", "Finished episode 310 Average rewards: 500.0\n" ] } ], "source": [ "env_name = \"CartPole-v1\"\n", "\n", "# Start training the agent\n", "episode_reward_history = []\n", "for batch in range(n_episodes // batch_size):\n", " # Gather episodes\n", " episodes = gather_episodes(state_bounds, n_actions, model, batch_size, env_name)\n", " \n", " # Group states, actions and returns in numpy arrays\n", " states = np.concatenate([ep['states'] for ep in episodes])\n", " actions = np.concatenate([ep['actions'] for ep in episodes])\n", " rewards = [ep['rewards'] for ep in episodes]\n", " returns = np.concatenate([compute_returns(ep_rwds, gamma) for ep_rwds in rewards])\n", " returns = np.array(returns, dtype=np.float32)\n", "\n", " id_action_pairs = np.array([[i, a] for i, a in enumerate(actions)])\n", " \n", " # Update model parameters.\n", " reinforce_update(states, id_action_pairs, returns, model)\n", "\n", " # Store collected rewards\n", " for ep_rwds in rewards:\n", " episode_reward_history.append(np.sum(ep_rwds))\n", " \n", " avg_rewards = np.mean(episode_reward_history[-10:])\n", "\n", " print('Finished episode', (batch + 1) * batch_size,\n", " 'Average rewards: ', avg_rewards)\n", " \n", " if avg_rewards >= 500.0:\n", " break" ] }, { "cell_type": "markdown", "metadata": { "id": "8E7Be2SqwpUW" }, "source": [ "Plot the learning history of the agent:" ] }, { "cell_type": "code", "execution_count": 17, "metadata": { "colab": { "base_uri": "https://localhost:8080/", "height": 334 }, "id": "51RzNBZqwpUX", "outputId": "36b2eae1-7113-4d21-f39e-7d1bab291401", "scrolled": true }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "
" ] }, "metadata": { "needs_background": "light", "tags": [] }, "output_type": "display_data" } ], "source": [ "plt.figure(figsize=(10,5))\n", "plt.plot(episode_reward_history)\n", "plt.xlabel('Epsiode')\n", "plt.ylabel('Collected rewards')\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": { "id": "Qfdf4DBkwpUX" }, "source": [ "Congratulations, you have trained a quantum policy gradient model on Cartpole! The plot above shows the rewards collected by the agent per episode throughout its interaction with the environment. You should see that after a few hundred episodes, the performance of the agent gets close to optimal, i.e., 500 rewards per episode. " ] }, { "cell_type": "markdown", "metadata": { "id": "YtaBfoERwpUX" }, "source": [ "You can now visualize the performance of your agent using `env.render()` in a sample episode (uncomment/run the following cell only if your notebook has access to a display):" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "-VpROTJ1wpUX" }, "outputs": [], "source": [ "# from PIL import Image\n", "\n", "# env = gym.make('CartPole-v1')\n", "# state = env.reset()\n", "# frames = []\n", "# for t in range(500):\n", "# im = Image.fromarray(env.render(mode='rgb_array'))\n", "# frames.append(im)\n", "# policy = model([tf.convert_to_tensor([state/state_bounds])])\n", "# action = np.random.choice(n_actions, p=policy.numpy()[0])\n", "# state, _, done, _ = env.step(action)\n", "# if done:\n", "# break\n", "# env.close()\n", "# frames[1].save('./images/gym_CartPole.gif',\n", "# save_all=True, append_images=frames[2:], optimize=False, duration=40, loop=0)" ] }, { "cell_type": "markdown", "metadata": { "id": "i0iA0nubwpUX" }, "source": [ "" ] }, { "cell_type": "markdown", "metadata": { "id": "iAO1TBxqwpUX" }, "source": [ "## 3. Deep Q-learning with PQC Q-function approximators" ] }, { "cell_type": "markdown", "metadata": { "id": "9uEimdpHwpUY" }, "source": [ "In this section, you will move to the implementation of the deep Q-learning algorithm presented in [2]. As opposed to a policy-gradient approach, the deep Q-learning method uses a PQC to approximate the Q-function of the agent. That is, the PQC defines a function approximator:\n", "$$ Q_\\theta(s,a) = \\langle O_a \\rangle_{s,\\theta} $$\n", "where $\\langle O_a \\rangle_{s,\\theta}$ are expectation values of observables $O_a$ (one per action) measured at the ouput of the PQC.\n", "\n", "These Q-values are updated using a loss function derived from Q-learning:\n", "$$ \\mathcal{L}(\\theta) = \\frac{1}{|\\mathcal{B}|}\\sum_{s,a,r,s' \\in \\mathcal{B}} \\left(Q_\\theta(s,a) - [r +\\max_{a'} Q_{\\theta'}(s',a')]\\right)^2$$\n", "for a batch $\\mathcal{B}$ of $1$-step interactions $(s,a,r,s')$ with the environment, sampled from the replay memory, and parameters $\\theta'$ specifying the target PQC (i.e., a copy of the main PQC, whose parameters are sporadically copied from the main PQC throughout learning)." ] }, { "cell_type": "markdown", "metadata": { "id": "nTyRzuDYwpUY" }, "source": [ "You can adopt the same observables used in [2] for CartPole, namely a $Z_0Z_1$ Pauli product for action $0$ and a $Z_2Z_3$ Pauli product for action $1$. Both observables are re-scaled so their expectation values are in $[0,1]$ and weighted by an action-specific weight. To implement the re-scaling and weighting of the Pauli products, you can define again an extra `tf.keras.layers.Layer` that stores the action-specific weights and applies them multiplicatively on the expectation values $\\left(1+\\langle Z_0Z_1 \\rangle_{s,\\theta}\\right)/2$ and $\\left(1+\\langle Z_2Z_3 \\rangle_{s,\\theta}\\right)/2$." ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "id": "MX5l96qywpUY" }, "outputs": [], "source": [ "class Rescaling(tf.keras.layers.Layer):\n", " def __init__(self, input_dim):\n", " super(Rescaling, self).__init__()\n", " self.input_dim = input_dim\n", " self.w = tf.Variable(\n", " initial_value=tf.ones(shape=(1,input_dim)), dtype=\"float32\",\n", " trainable=True, name=\"obs-weights\")\n", "\n", " def call(self, inputs):\n", " return tf.math.multiply((inputs+1)/2, tf.repeat(self.w,repeats=tf.shape(inputs)[0],axis=0))" ] }, { "cell_type": "markdown", "metadata": { "id": "oesnEQa7wpUY" }, "source": [ "Prepare the definition of your PQC and its observables:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "id": "cpV0PxZqwpUY" }, "outputs": [], "source": [ "n_qubits = 4 # Dimension of the state vectors in CartPole\n", "n_layers = 5 # Number of layers in the PQC\n", "n_actions = 2 # Number of actions in CartPole\n", "\n", "qubits = cirq.GridQubit.rect(1, n_qubits)\n", "ops = [cirq.Z(q) for q in qubits]\n", "observables = [ops[0]*ops[1], ops[2]*ops[3]] # Z_0*Z_1 for action 0 and Z_2*Z_3 for action 1" ] }, { "cell_type": "markdown", "metadata": { "id": "JLMvQBXFwpUZ" }, "source": [ "Define a `tf.keras.Model` that, similarly to the PQC-policy model, constructs a Q-function approximator that is used to generate the main and target models of our Q-learning agent." ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "id": "PBGM6RHIwpUZ" }, "outputs": [], "source": [ "def generate_model_Qlearning(qubits, n_layers, n_actions, observables, target):\n", " \"\"\"Generates a Keras model for a data re-uploading PQC Q-function approximator.\"\"\"\n", "\n", " input_tensor = tf.keras.Input(shape=(len(qubits), ), dtype=tf.dtypes.float32, name='input')\n", " re_uploading_pqc = ReUploadingPQC(qubits, n_layers, observables, activation='tanh')([input_tensor])\n", " process = tf.keras.Sequential([Rescaling(len(observables))], name=target*\"Target\"+\"Q-values\")\n", " Q_values = process(re_uploading_pqc)\n", " model = tf.keras.Model(inputs=[input_tensor], outputs=Q_values)\n", "\n", " return model\n", "\n", "model = generate_model_Qlearning(qubits, n_layers, n_actions, observables, False)\n", "model_target = generate_model_Qlearning(qubits, n_layers, n_actions, observables, True)\n", "\n", "model_target.set_weights(model.get_weights())" ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "colab": { "base_uri": "https://localhost:8080/", "height": 232 }, "id": "57TxgIN5wpUZ", "outputId": "da6a3aee-1722-40b3-fae5-2972d8c2ed88" }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "" ] }, "execution_count": 9, "metadata": { "tags": [] }, "output_type": "execute_result" } ], "source": [ "tf.keras.utils.plot_model(model, show_shapes=True, dpi=70)" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "colab": { "base_uri": "https://localhost:8080/", "height": 232 }, "id": "jHp42R4twpUa", "outputId": "69a20e50-fde4-4634-897b-01edaeab420a" }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "" ] }, "execution_count": 10, "metadata": { "tags": [] }, "output_type": "execute_result" } ], "source": [ "tf.keras.utils.plot_model(model_target, show_shapes=True, dpi=70)" ] }, { "cell_type": "markdown", "metadata": { "id": "vricJOvXwpUa" }, "source": [ "You can now implement the deep Q-learning algorithm and test it on the CartPole-v1 environment. For the policy of the agent, you can use an $\\varepsilon$-greedy policy:\n", "$$ \\pi(a|s) =\n", "\\begin{cases}\n", "\\delta_{a,\\text{argmax}_{a'} Q_\\theta(s,a')}\\quad \\text{w.p.}\\quad 1 - \\varepsilon\\\\\n", "\\frac{1}{\\text{num_actions}}\\quad \\quad \\quad \\quad \\text{w.p.}\\quad \\varepsilon\n", "\\end{cases} $$\n", "where $\\varepsilon$ is multiplicatively decayed at each episode of interaction." ] }, { "cell_type": "markdown", "metadata": { "id": "sMteuedswpUb" }, "source": [ "Start by defining a function that performs an interaction step in the environment:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "id": "0L9cV26PwpUb" }, "outputs": [], "source": [ "def interact_env(state, model, epsilon, n_actions, env):\n", " # Preprocess state\n", " state_array = np.array(state) \n", " state = tf.convert_to_tensor([state_array])\n", "\n", " # Sample action\n", " coin = np.random.random()\n", " if coin > epsilon:\n", " q_vals = model([state])\n", " action = int(tf.argmax(q_vals[0]).numpy())\n", " else:\n", " action = np.random.choice(n_actions)\n", "\n", " # Apply sampled action in the environment, receive reward and next state\n", " next_state, reward, done, _ = env.step(action)\n", " \n", " interaction = {'state': state_array, 'action': action, 'next_state': next_state.copy(),\n", " 'reward': reward, 'done':np.float32(done)}\n", " \n", " return interaction" ] }, { "cell_type": "markdown", "metadata": { "id": "oDiw3iJywpUb" }, "source": [ "and a function that updates the Q-function using a batch of interactions:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "id": "RR2DjesVwpUb" }, "outputs": [], "source": [ "@tf.function\n", "def Q_learning_update(states, actions, rewards, next_states, done, model, gamma, n_actions):\n", " states = tf.convert_to_tensor(states)\n", " actions = tf.convert_to_tensor(actions)\n", " rewards = tf.convert_to_tensor(rewards)\n", " next_states = tf.convert_to_tensor(next_states)\n", " done = tf.convert_to_tensor(done)\n", "\n", " # Compute their target q_values and the masks on sampled actions\n", " future_rewards = model_target([next_states])\n", " target_q_values = rewards + (gamma * tf.reduce_max(future_rewards, axis=1)\n", " * (1.0 - done))\n", " masks = tf.one_hot(actions, n_actions)\n", "\n", " # Train the model on the states and target Q-values\n", " with tf.GradientTape() as tape:\n", " tape.watch(model.trainable_variables)\n", " q_values = model([states])\n", " q_values_masked = tf.reduce_sum(tf.multiply(q_values, masks), axis=1)\n", " loss = tf.keras.losses.Huber()(target_q_values, q_values_masked)\n", "\n", " # Backpropagation\n", " grads = tape.gradient(loss, model.trainable_variables)\n", " for optimizer, w in zip([optimizer_in, optimizer_var, optimizer_out], [w_in, w_var, w_out]):\n", " optimizer.apply_gradients([(grads[w], model.trainable_variables[w])])" ] }, { "cell_type": "markdown", "metadata": { "id": "tfXHhqaPwpUb" }, "source": [ "Define the hyperparameters:" ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "id": "SQ937aYPwpUc" }, "outputs": [], "source": [ "gamma = 0.99\n", "n_episodes = 2000\n", "\n", "# Define replay memory\n", "max_memory_length = 10000 # Maximum replay length\n", "replay_memory = deque(maxlen=max_memory_length)\n", "\n", "epsilon = 1.0 # Epsilon greedy parameter\n", "epsilon_min = 0.01 # Minimum epsilon greedy parameter\n", "decay_epsilon = 0.99 # Decay rate of epsilon greedy parameter\n", "batch_size = 16\n", "steps_per_update = 10 # Train the model every x steps\n", "steps_per_target_update = 30 # Update the target model every x steps" ] }, { "cell_type": "markdown", "metadata": { "id": "AHsHnuHmwpUc" }, "source": [ "Prepare the optimizers:" ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "id": "713nl3oUwpUc" }, "outputs": [], "source": [ "optimizer_in = tf.keras.optimizers.Adam(learning_rate=0.001, amsgrad=True)\n", "optimizer_var = tf.keras.optimizers.Adam(learning_rate=0.001, amsgrad=True)\n", "optimizer_out = tf.keras.optimizers.Adam(learning_rate=0.1, amsgrad=True)\n", "\n", "# Assign the model parameters to each optimizer\n", "w_in, w_var, w_out = 1, 0, 2" ] }, { "cell_type": "markdown", "metadata": { "id": "AwE0buDowpUd" }, "source": [ "Now implement the main training loop of the agent." ] }, { "cell_type": "markdown", "metadata": { "id": "TjjTamvywpUd" }, "source": [ "Note: This agent may need to simulate several million quantum circuits and can take as much as ~40 minutes to finish training." ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "colab": { "base_uri": "https://localhost:8080/" }, "id": "er9fXHH_wpUd", "outputId": "b165066b-c239-4bf0-b444-7c710640241c", "scrolled": true }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Episode 10/2000, average last 10 rewards 22.1\n", "Episode 20/2000, average last 10 rewards 27.9\n", "Episode 30/2000, average last 10 rewards 31.5\n", "Episode 40/2000, average last 10 rewards 23.3\n", "Episode 50/2000, average last 10 rewards 25.4\n", "Episode 60/2000, average last 10 rewards 19.7\n", "Episode 70/2000, average last 10 rewards 12.5\n", "Episode 80/2000, average last 10 rewards 11.7\n", "Episode 90/2000, average last 10 rewards 14.9\n", "Episode 100/2000, average last 10 rewards 15.3\n", "Episode 110/2000, average last 10 rewards 14.6\n", "Episode 120/2000, average last 10 rewards 20.4\n", "Episode 130/2000, average last 10 rewards 14.2\n", "Episode 140/2000, average last 10 rewards 21.6\n", "Episode 150/2000, average last 10 rewards 30.4\n", "Episode 160/2000, average last 10 rewards 27.6\n", "Episode 170/2000, average last 10 rewards 18.5\n", "Episode 180/2000, average last 10 rewards 30.6\n", "Episode 190/2000, average last 10 rewards 12.2\n", "Episode 200/2000, average last 10 rewards 27.2\n", "Episode 210/2000, average last 10 rewards 27.2\n", "Episode 220/2000, average last 10 rewards 15.3\n", "Episode 230/2000, average last 10 rewards 128.4\n", "Episode 240/2000, average last 10 rewards 68.3\n", "Episode 250/2000, average last 10 rewards 44.0\n", "Episode 260/2000, average last 10 rewards 119.8\n", "Episode 270/2000, average last 10 rewards 135.3\n", "Episode 280/2000, average last 10 rewards 90.6\n", "Episode 290/2000, average last 10 rewards 120.9\n", "Episode 300/2000, average last 10 rewards 125.3\n", "Episode 310/2000, average last 10 rewards 141.7\n", "Episode 320/2000, average last 10 rewards 144.7\n", "Episode 330/2000, average last 10 rewards 165.7\n", "Episode 340/2000, average last 10 rewards 26.1\n", "Episode 350/2000, average last 10 rewards 9.7\n", "Episode 360/2000, average last 10 rewards 9.6\n", "Episode 370/2000, average last 10 rewards 9.7\n", "Episode 380/2000, average last 10 rewards 9.4\n", "Episode 390/2000, average last 10 rewards 11.3\n", "Episode 400/2000, average last 10 rewards 11.6\n", "Episode 410/2000, average last 10 rewards 165.4\n", "Episode 420/2000, average last 10 rewards 170.5\n", "Episode 430/2000, average last 10 rewards 25.1\n", "Episode 440/2000, average last 10 rewards 74.1\n", "Episode 450/2000, average last 10 rewards 214.7\n", "Episode 460/2000, average last 10 rewards 139.1\n", "Episode 470/2000, average last 10 rewards 265.1\n", "Episode 480/2000, average last 10 rewards 296.7\n", "Episode 490/2000, average last 10 rewards 101.7\n", "Episode 500/2000, average last 10 rewards 146.6\n", "Episode 510/2000, average last 10 rewards 325.6\n", "Episode 520/2000, average last 10 rewards 45.9\n", "Episode 530/2000, average last 10 rewards 263.5\n", "Episode 540/2000, average last 10 rewards 223.3\n", "Episode 550/2000, average last 10 rewards 73.1\n", "Episode 560/2000, average last 10 rewards 115.0\n", "Episode 570/2000, average last 10 rewards 148.3\n", "Episode 580/2000, average last 10 rewards 41.6\n", "Episode 590/2000, average last 10 rewards 266.7\n", "Episode 600/2000, average last 10 rewards 275.2\n", "Episode 610/2000, average last 10 rewards 253.9\n", "Episode 620/2000, average last 10 rewards 282.2\n", "Episode 630/2000, average last 10 rewards 348.3\n", "Episode 640/2000, average last 10 rewards 162.2\n", "Episode 650/2000, average last 10 rewards 276.0\n", "Episode 660/2000, average last 10 rewards 234.6\n", "Episode 670/2000, average last 10 rewards 187.4\n", "Episode 680/2000, average last 10 rewards 285.0\n", "Episode 690/2000, average last 10 rewards 362.8\n", "Episode 700/2000, average last 10 rewards 316.0\n", "Episode 710/2000, average last 10 rewards 436.0\n", "Episode 720/2000, average last 10 rewards 366.1\n", "Episode 730/2000, average last 10 rewards 305.0\n", "Episode 740/2000, average last 10 rewards 273.2\n", "Episode 750/2000, average last 10 rewards 236.8\n", "Episode 760/2000, average last 10 rewards 260.2\n", "Episode 770/2000, average last 10 rewards 443.9\n", "Episode 780/2000, average last 10 rewards 494.2\n", "Episode 790/2000, average last 10 rewards 333.1\n", "Episode 800/2000, average last 10 rewards 367.1\n", "Episode 810/2000, average last 10 rewards 317.8\n", "Episode 820/2000, average last 10 rewards 396.6\n", "Episode 830/2000, average last 10 rewards 494.1\n", "Episode 840/2000, average last 10 rewards 500.0\n" ] } ], "source": [ "env = gym.make(\"CartPole-v1\")\n", " \n", "episode_reward_history = []\n", "step_count = 0\n", "for episode in range(n_episodes):\n", " episode_reward = 0\n", " state = env.reset()\n", " \n", " while True:\n", " # Interact with env\n", " interaction = interact_env(state, model, epsilon, n_actions, env)\n", " \n", " # Store interaction in the replay memory\n", " replay_memory.append(interaction)\n", " \n", " state = interaction['next_state']\n", " episode_reward += interaction['reward']\n", " step_count += 1\n", " \n", " # Update model\n", " if step_count % steps_per_update == 0:\n", " # Sample a batch of interactions and update Q_function\n", " training_batch = np.random.choice(replay_memory, size=batch_size)\n", " Q_learning_update(np.asarray([x['state'] for x in training_batch]),\n", " np.asarray([x['action'] for x in training_batch]),\n", " np.asarray([x['reward'] for x in training_batch], dtype=np.float32),\n", " np.asarray([x['next_state'] for x in training_batch]),\n", " np.asarray([x['done'] for x in training_batch], dtype=np.float32),\n", " model, gamma, n_actions)\n", " \n", " # Update target model\n", " if step_count % steps_per_target_update == 0:\n", " model_target.set_weights(model.get_weights())\n", " \n", " # Check if the episode is finished\n", " if interaction['done']:\n", " break\n", "\n", " # Decay epsilon\n", " epsilon = max(epsilon * decay_epsilon, epsilon_min)\n", " episode_reward_history.append(episode_reward)\n", " if (episode+1)%10 == 0:\n", " avg_rewards = np.mean(episode_reward_history[-10:])\n", " print(\"Episode {}/{}, average last 10 rewards {}\".format(\n", " episode+1, n_episodes, avg_rewards))\n", " if avg_rewards >= 500.0:\n", " break" ] }, { "cell_type": "markdown", "metadata": { "id": "BG8BWOSYwpUd" }, "source": [ "Plot the learning history of the agent:" ] }, { "cell_type": "code", "execution_count": 17, "metadata": { "colab": { "base_uri": "https://localhost:8080/", "height": 334 }, "id": "sSRMtk-swpUe", "outputId": "a2a4c5a8-92cf-495a-da9d-6be0e8f673a2" }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "
" ] }, "metadata": { "needs_background": "light", "tags": [] }, "output_type": "display_data" } ], "source": [ "plt.figure(figsize=(10,5))\n", "plt.plot(episode_reward_history)\n", "plt.xlabel('Epsiode')\n", "plt.ylabel('Collected rewards')\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": { "id": "f_7rJf0iwpUe" }, "source": [ "Similarly to the plot above, you should see that after ~1000 episodes, the performance of the agent gets close to optimal, i.e., 500 rewards per episode. Learning takes longer for Q-learning agents since the Q-function is a \"richer\" function to be learned than the policy." ] }, { "cell_type": "markdown", "metadata": { "id": "X8X49f8owpUe" }, "source": [ "## 4. Exercise\n", "\n", "Now that you have trained two different types of models, try experimenting with different environments (and different numbers of qubits and layers). You could also try combining the PQC models of the last two sections into an [actor-critic agent](https://lilianweng.github.io/lil-log/2018/04/08/policy-gradient-algorithms.html#actor-critic)." ] } ], "metadata": { "colab": { "collapsed_sections": [ "jxWGru_NwpUK", "_u3QBKbvwpUP", "X8X49f8owpUe" ], "name": "quantum_reinforcement_learning.ipynb", "provenance": [] }, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "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.9 (main, Dec 7 2022, 13:47:07) [GCC 12.2.0]" }, "vscode": { "interpreter": { "hash": "916dbcbb3f70747c44a77c7bcd40155683ae19c65e1c03b4aa3499c5328201f1" } } }, "nbformat": 4, "nbformat_minor": 1 }