docs/how_tos/train_kernels_using_qiskit_feature_maps.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "94433c6b",
   "metadata": {},
   "source": [
    "## How To Build Trainable Feature Maps from the Qiskit Circuit Library\n",
    "\n",
    "In this guide, we will show how to build trainable feature maps from existing circuits in the Qiskit circuit library. Each approach will involve reassigning some parameters originally reserved for input data to instead be trainable parameters.\n",
    "\n",
    "To build a trainable feature map, we require the following:\n",
    "\n",
    "1. A circuit containing parameterized gates\n",
    "2. A partition of circuit parameters into two sets: input parameters (encode the data) and user (trainable) parameters\n",
    "3. After partitioning parameters, the dimensionality of the input data must equal the number of input parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44f0eed9",
   "metadata": {},
   "source": [
    "### Option 1: Partition the Parameters of a Single Circuit\n",
    "\n",
    "The main distinction between a feature map and a _parameterized_ feature map is the presence of parameters not associated to our input data. In other words, a feature map contains input parameters (encoding the dataset), and a parameterized feature map contains both input parameters as well as user parameters (which are trainable). \n",
    "\n",
    "One way to generate a parameterized feature map from an existing Qiskit feature map is to reassign some of the input parameters to be user parameters instead. If you go down this path, take care to ensure that you retain enough input parameters to match the dimensionality of your data. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "93c4fce5",
   "metadata": {},
   "outputs": [],
   "source": [
    "#pylint: disable=protected-access\n",
    "from qiskit.circuit.library import ZZFeatureMap\n",
    "from qiskit.circuit import ParameterVector"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33574058",
   "metadata": {},
   "source": [
    "Let's start with a two-qubit feature map from the Qiskit circuit library. By default, this is not parametrized and contains two input parameters `x[0]` and `x[1]` encoding the components of each data sample."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "3b2afbfc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">     ┌──────────────────────────┐\n",
       "q_0: ┤0                         ├\n",
       "     │  ZZFeatureMap(x[0],x[1]) │\n",
       "q_1: ┤1                         ├\n",
       "     └──────────────────────────┘</pre>"
      ],
      "text/plain": [
       "     ┌──────────────────────────┐\n",
       "q_0: ┤0                         ├\n",
       "     │  ZZFeatureMap(x[0],x[1]) │\n",
       "q_1: ┤1                         ├\n",
       "     └──────────────────────────┘"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Define a (non-parameterized) feature map from the Qiskit circuit library\n",
    "fm = ZZFeatureMap(2)\n",
    "input_params = fm.parameters\n",
    "fm.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03597a47",
   "metadata": {},
   "source": [
    "Let's partition the input parameters into two sets such that the second one is reassigned to be a user (trainable) parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "221650c1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "input_params: [ParameterVectorElement(x[0])]\n",
      "user_params: [ParameterVectorElement(x[1])]\n"
     ]
    }
   ],
   "source": [
    "# split params into two disjoint sets\n",
    "input_params = fm.parameters[::2]\n",
    "user_params = fm.parameters[1::2]\n",
    "print(\"input_params:\", input_params)\n",
    "print(\"user_params:\", user_params)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98b08751",
   "metadata": {},
   "source": [
    "For clarity, we will manually reassign the feature map parameters such that the new parameters are properly named. (Renaming is not strictly required in this example; however, in the example below it will be necessary to prevent name collisions.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "4263ce77",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "input_params: x, ['x[0]']\n",
      "user_params: θ, ['θ[0]']\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">     ┌──────────────────────────┐\n",
       "q_0: ┤0                         ├\n",
       "     │  ZZFeatureMap(x[0],θ[0]) │\n",
       "q_1: ┤1                         ├\n",
       "     └──────────────────────────┘</pre>"
      ],
      "text/plain": [
       "     ┌──────────────────────────┐\n",
       "q_0: ┤0                         ├\n",
       "     │  ZZFeatureMap(x[0],θ[0]) │\n",
       "q_1: ┤1                         ├\n",
       "     └──────────────────────────┘"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# define new parameter vectors for the input and user parameters\n",
    "new_input_params = ParameterVector('x', len(input_params))\n",
    "new_user_params = ParameterVector('θ', len(user_params))\n",
    "\n",
    "# resassign the origin feature map parameters\n",
    "param_reassignments = {}\n",
    "for i, p in enumerate(input_params):\n",
    "    param_reassignments[p] = new_input_params[i]\n",
    "for i, p in enumerate(user_params):\n",
    "    param_reassignments[p] = new_user_params[i]\n",
    "\n",
    "fm.assign_parameters(param_reassignments, inplace=True)\n",
    "\n",
    "input_params = new_input_params\n",
    "user_params = new_user_params\n",
    "\n",
    "print(\"input_params:\", input_params)\n",
    "print(\"user_params:\", user_params)\n",
    "fm.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eaa7fe1b",
   "metadata": {},
   "source": [
    "### Option 2: Compose Multiple Circuits\n",
    "\n",
    "We can build a parameterized feature map out of existing Qiskit library circuits by composing them to form a larger composite circuit. However, if two circuits have (different) parameters that share the same name, qiskit will not allow us to compose them. \n",
    "\n",
    "To resolve this issue, we will simply rename our user parameters to prevent name collisions. As a nice side effect, our parameter names will also be more accurate and helpful. Again, note that our parameter names are automatically updated in our feature map circuit.\n",
    "\n",
    "*Note: although both options we show in this guide use two qubits, Option 2 results in a feature map that accepts two-dimensional data while Option 1 results in a feature map for one-dimensional data.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "3429cb60",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "input_params: [ParameterVectorElement(x[0]), ParameterVectorElement(x[1])]\n",
      "user_params: θ, ['θ[0]', 'θ[1]']\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">     ┌──────────────────────────┐┌──────────────────────────┐\n",
       "q_0: ┤0                         ├┤0                         ├\n",
       "     │  ZZFeatureMap(θ[0],θ[1]) ││  ZZFeatureMap(x[0],x[1]) │\n",
       "q_1: ┤1                         ├┤1                         ├\n",
       "     └──────────────────────────┘└──────────────────────────┘</pre>"
      ],
      "text/plain": [
       "     ┌──────────────────────────┐┌──────────────────────────┐\n",
       "q_0: ┤0                         ├┤0                         ├\n",
       "     │  ZZFeatureMap(θ[0],θ[1]) ││  ZZFeatureMap(x[0],x[1]) │\n",
       "q_1: ┤1                         ├┤1                         ├\n",
       "     └──────────────────────────┘└──────────────────────────┘"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Define two circuits\n",
    "circ1 = ZZFeatureMap(2)\n",
    "circ2 = ZZFeatureMap(2)\n",
    "input_params = circ1.parameters\n",
    "user_params = ParameterVector('θ', 2)\n",
    "\n",
    "# Reassign new parameters to circ2 so there are no name collisions\n",
    "circ2.assign_parameters(user_params, inplace=True)\n",
    "\n",
    "# Compose to build a parameterized feature map\n",
    "fm = circ2.compose(circ1)\n",
    "print(\"input_params:\", list(input_params))\n",
    "print(\"user_params:\", user_params)\n",
    "fm.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92bb6724",
   "metadata": {},
   "source": [
    "###  Option 3: Build from Scratch\n",
    "\n",
    "As a user, you are free to define your own trainable feature map and we encourage you to do so! This is a growing area of research, and understanding what makes a good trainable feature map is an important next step toward realizing practical quantum machine learning. \n",
    "\n",
    "In our [guide on creating custom quantum feature maps](https://github.com/IBM-Quantum-prototypes/quantum-kernel-training/blob/main/docs/how_tos/create_custom_quantum_feature_map.ipynb) we give an example of a trainable feature map tailored to classifying datasets with a particular group structure. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f4f17839",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<h3>Version Information</h3><table><tr><th>Qiskit Software</th><th>Version</th></tr><tr><td><code>qiskit-terra</code></td><td>0.20.0</td></tr><tr><td><code>qiskit-aer</code></td><td>0.9.1</td></tr><tr><td><code>qiskit-ignis</code></td><td>0.7.0</td></tr><tr><td><code>qiskit-ibmq-provider</code></td><td>0.18.1</td></tr><tr><td><code>qiskit</code></td><td>0.33.0</td></tr><tr><td><code>qiskit-machine-learning</code></td><td>0.3.0</td></tr><tr><th>System information</th></tr><tr><td>Python version</td><td>3.8.10</td></tr><tr><td>Python compiler</td><td>Clang 10.0.0 </td></tr><tr><td>Python build</td><td>default, May 19 2021 11:01:55</td></tr><tr><td>OS</td><td>Darwin</td></tr><tr><td>CPUs</td><td>8</td></tr><tr><td>Memory (Gb)</td><td>32.0</td></tr><tr><td colspan='2'>Fri Dec 10 16:45:08 2021 CST</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div style='width: 100%; background-color:#d5d9e0;padding-left: 10px; padding-bottom: 10px; padding-right: 10px; padding-top: 5px'><h3>This code is a part of Qiskit</h3><p>&copy; Copyright IBM 2017, 2021.</p><p>This code is licensed under the Apache License, Version 2.0. You may<br>obtain a copy of this license in the LICENSE.txt file in the root directory<br> of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.<p>Any modifications or derivative works of this code must retain this<br>copyright notice, and modified files need to carry a notice indicating<br>that they have been altered from the originals.</p></div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import qiskit.tools.jupyter\n",
    "%qiskit_version_table\n",
    "%qiskit_copyright"
   ]
  }
 ],
 "metadata": {
  "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.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}