docs/how_tos/create_custom_quantum_feature_map.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5e8bcc91",
   "metadata": {},
   "source": [
    "## How To Create Custom Quantum Feature Maps\n",
    "\n",
    "In machine learning, a feature map represents a transformation of data into a higher-dimensional space. However, this can be an expensive computation. Instead, kernel functions can be used to implicitly encode this transformation through the pairwise inner products of data samples. Kernels are a similarity measure over the dataset and are a key component of many machine learning models, for example, support vector machines. A quantum computer can be used to encode classical data into the quantum state space. We call this a quantum feature map. \n",
    "\n",
    "In this guide, we will show how to create a custom quantum feature map with trainable parameters, which may be used as input to Qiskit machine learning algorithms such as `QSVC` and `QuantumKernelTrainer`. We will follow four basic steps:\n",
    "\n",
    "1. Import required Qiskit packages\n",
    "2. Design the circuit for the quantum feature map\n",
    "3. Build the circuit with Qiskit\n",
    "4. Implement the feature map as a `QuantumCircuit` child class"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d5ea8d0",
   "metadata": {},
   "source": [
    "### Import Required Packages\n",
    "\n",
    "To create a quantum feature map with trainable parameters in Qiskit, there are two basic guidelines.<br>\n",
    "The quantum feature map should:\n",
    " - Be an extension of Qiskit's `QuantumCircuit` class\n",
    " - Contain some number of trainable user parameters, `θ`, in addition to parameters designated to input data, `x`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "30b8780c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import List, Callable, Union\n",
    "\n",
    "from qiskit import QuantumCircuit\n",
    "from qiskit.circuit import ParameterVector\n",
    "\n",
    "# To visualize circuit creation process\n",
    "from qiskit.visualization import circuit_drawer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c1ab45bd",
   "metadata": {},
   "source": [
    "### Design the Circuit\n",
    "Similarly to classical feature engineering, creating a quantum feature map is a process that strongly depends on the learning problem at hand. In general, we cannot suggest an optimal feature map with no prior knowledge of the learning problem. Instead, we will focus on the basic steps to create a circuit using the Qiskit API. To illustrate, we will build a version of the [covariant feature map](https://github.com/IBM-Quantum-prototypes/quantum-kernel-training/blob/main/qkt/feature_maps/covariant_feature_map.py), which is tailored to a dataset with a particular structure. Check out [this guide](https://github.com/IBM-Quantum-prototypes/quantum-kernel-training/blob/main/docs/background/qkernels_and_data_w_group_structure.ipynb) for more information on covariant quantum kernels.\n",
    "\n",
    "For this example, the feature map will be built from a circuit containing trainable parameters `θ` followed by a circuit encoding the input data `x`. The trainable parameter of the $i$th qubit corresponds to a rotation around the $y$-axis by an angle `θ[i]`. We follow this by an entanglement layer of controlled-$z$ gates. Finally, we encode two features `x[i], x[i+1]` per qubit using consecutive rotations around the $x$ and $z$ axes.   "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ab67ffb",
   "metadata": {},
   "source": [
    "### Build the Circuit with Qiskit\n",
    "\n",
    "First, we instantiate a `QuantumCircuit`  and create the circuit layer with trainable parameters `θ[i]`. Here, we will assume we are given a dataset with 12 features and we encode two features per qubit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "3541597f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     ┌──────────┐\n",
      "q_0: ┤ Ry(θ[0]) ├\n",
      "     ├──────────┤\n",
      "q_1: ┤ Ry(θ[1]) ├\n",
      "     ├──────────┤\n",
      "q_2: ┤ Ry(θ[2]) ├\n",
      "     ├──────────┤\n",
      "q_3: ┤ Ry(θ[3]) ├\n",
      "     ├──────────┤\n",
      "q_4: ┤ Ry(θ[4]) ├\n",
      "     ├──────────┤\n",
      "q_5: ┤ Ry(θ[5]) ├\n",
      "     └──────────┘\n"
     ]
    }
   ],
   "source": [
    "# For a dataset with 12 features; and 2 features per qubit\n",
    "FEATURE_DIMENSION = 12\n",
    "NUM_QUBITS = int(FEATURE_DIMENSION / 2)\n",
    "\n",
    "# Qiskit feature maps should generally be QuantumCircuits or extensions of QuantumCircuit\n",
    "feature_map = QuantumCircuit(NUM_QUBITS)\n",
    "user_params = ParameterVector(\"θ\", NUM_QUBITS)\n",
    "\n",
    "# Create circuit layer with trainable parameters\n",
    "for i in range(NUM_QUBITS):\n",
    "    feature_map.ry(user_params[i], feature_map.qubits[i])\n",
    "\n",
    "print(circuit_drawer(feature_map))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb0063cc",
   "metadata": {},
   "source": [
    "Next, we will define an entanglement scheme (a linear map of controlled-$z$ gates) and create the entanglement layer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "cb7a416b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     ┌──────────┐                ░ \n",
      "q_0: ┤ Ry(θ[0]) ├─■──────────────░─\n",
      "     ├──────────┤ │              ░ \n",
      "q_1: ┤ Ry(θ[1]) ├─■──■───────────░─\n",
      "     ├──────────┤    │           ░ \n",
      "q_2: ┤ Ry(θ[2]) ├────■──■────────░─\n",
      "     ├──────────┤       │        ░ \n",
      "q_3: ┤ Ry(θ[3]) ├───────■──■─────░─\n",
      "     ├──────────┤          │     ░ \n",
      "q_4: ┤ Ry(θ[4]) ├──────────■──■──░─\n",
      "     ├──────────┤             │  ░ \n",
      "q_5: ┤ Ry(θ[5]) ├─────────────■──░─\n",
      "     └──────────┘                ░ \n"
     ]
    }
   ],
   "source": [
    "# Linear entanglement\n",
    "entanglement = [\n",
    "        [i, i+1]\n",
    "        for i in range(NUM_QUBITS - 1)\n",
    "    ]\n",
    "\n",
    "for source, target in entanglement:\n",
    "    feature_map.cz(feature_map.qubits[source], feature_map.qubits[target])\n",
    "\n",
    "feature_map.barrier()\n",
    "\n",
    "print(circuit_drawer(feature_map))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3282cd2",
   "metadata": {},
   "source": [
    "Finally, we encode two features `x[i], x[i+1]` per qubit using a layer of single-qubit rotations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "30ca4b94",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     ┌──────────┐                ░  ┌──────────┐ ┌──────────┐\n",
      "q_0: ┤ Ry(θ[0]) ├─■──────────────░──┤ Rz(x[1]) ├─┤ Rx(x[0]) ├\n",
      "     ├──────────┤ │              ░  ├──────────┤ ├──────────┤\n",
      "q_1: ┤ Ry(θ[1]) ├─■──■───────────░──┤ Rz(x[3]) ├─┤ Rx(x[2]) ├\n",
      "     ├──────────┤    │           ░  ├──────────┤ ├──────────┤\n",
      "q_2: ┤ Ry(θ[2]) ├────■──■────────░──┤ Rz(x[5]) ├─┤ Rx(x[4]) ├\n",
      "     ├──────────┤       │        ░  ├──────────┤ ├──────────┤\n",
      "q_3: ┤ Ry(θ[3]) ├───────■──■─────░──┤ Rz(x[7]) ├─┤ Rx(x[6]) ├\n",
      "     ├──────────┤          │     ░  ├──────────┤ ├──────────┤\n",
      "q_4: ┤ Ry(θ[4]) ├──────────■──■──░──┤ Rz(x[9]) ├─┤ Rx(x[8]) ├\n",
      "     ├──────────┤             │  ░ ┌┴──────────┤┌┴──────────┤\n",
      "q_5: ┤ Ry(θ[5]) ├─────────────■──░─┤ Rz(x[11]) ├┤ Rx(x[10]) ├\n",
      "     └──────────┘                ░ └───────────┘└───────────┘\n"
     ]
    }
   ],
   "source": [
    "input_params = ParameterVector(\"x\", FEATURE_DIMENSION)\n",
    "for i in range(NUM_QUBITS):\n",
    "    feature_map.rz(input_params[2 * i + 1], feature_map.qubits[i])\n",
    "    feature_map.rx(input_params[2 * i], feature_map.qubits[i])\n",
    "\n",
    "print(circuit_drawer(feature_map))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc67d1fe",
   "metadata": {},
   "source": [
    "### Implement the Feature Map as a `QuantumCircuit` Child Class\n",
    "\n",
    "Most Qiskit algorithms that take feature maps as input require the feature map be a class extension of a `QuantumCircuit`. While there are many ways to do this, we suggest the following approach illustrated with `ExampleFeatureMap` that extends `QuantumCircuit`:\n",
    "\n",
    "The feature map circuit is created upon instantiation such that\n",
    " - Parameters such as feature dimension and entanglement scheme should be specified during initialization\n",
    " - In the initialization, `QuantumCircuit.__init__()` is called before the feature map circuit is generated, which ensures all `QuantumCircuit` class fields (e.g. `QuantumCircuit.qubits`) are properly initialized\n",
    " - After the `QuantumCircuit` constructor has been called, a class method `_generate_feature_map` generates the feature map circuit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "58db2d0b",
   "metadata": {},
   "outputs": [],
   "source": [
    "class ExampleFeatureMap(QuantumCircuit):\n",
    "    \"\"\"The Example Feature Map circuit\"\"\"\n",
    "\n",
    "    def __init__(\n",
    "        self,\n",
    "        feature_dimension: int,\n",
    "        entanglement: Union[str, List[List[int]], Callable[[int], List[int]]] = None,\n",
    "        name: str = \"ExampleFeatureMap\",\n",
    "\n",
    "    ) -> None:\n",
    "        \"\"\"Create a new Example Feature Map circuit.\n",
    "        Args:\n",
    "            feature_dimension: The number of features\n",
    "            entanglement: Entanglement scheme to be used in second layer\n",
    "            name: Name of QuantumCircuit object\n",
    "\n",
    "        Raises:\n",
    "            ValueError: ExampleFeatureMap requires an even number of input features\n",
    "        \"\"\"\n",
    "        if (feature_dimension % 2) != 0:\n",
    "            raise ValueError(\n",
    "                \"\"\"\n",
    "            Example feature map requires an even number of input features.\n",
    "                \"\"\"\n",
    "            )\n",
    "        self.feature_dimension = feature_dimension\n",
    "        self.entanglement = entanglement\n",
    "        self.user_parameters = None\n",
    "\n",
    "        # Call the QuantumCircuit initialization\n",
    "        num_qubits = feature_dimension / 2\n",
    "        super().__init__(\n",
    "            num_qubits,\n",
    "            name=name,\n",
    "        )\n",
    "\n",
    "        # Build the feature map circuit\n",
    "        self._generate_feature_map()\n",
    "\n",
    "    def _generate_feature_map(self):\n",
    "        # If no entanglement scheme specified, use linear entanglement\n",
    "        if self.entanglement is None:\n",
    "            self.entanglement = [\n",
    "                [i, i+1]\n",
    "                for i in range(self.num_qubits - 1)\n",
    "            ]\n",
    "\n",
    "        # Vector of data parameters\n",
    "        input_params = ParameterVector(\"x\", self.feature_dimension)\n",
    "\n",
    "        user_params = ParameterVector(\"θ\", self.num_qubits)\n",
    "        # Create an initial rotation layer of trainable parameters\n",
    "        for i in range(self.num_qubits):\n",
    "            self.ry(user_params[i], self.qubits[i])\n",
    "\n",
    "        self.user_parameters = user_params\n",
    "\n",
    "        # Create the entanglement layer\n",
    "        for source, target in self.entanglement:\n",
    "            self.cz(self.qubits[source], self.qubits[target])\n",
    "\n",
    "        self.barrier()\n",
    "\n",
    "        # Create a circuit representation of the data group\n",
    "        for i in range(self.num_qubits):\n",
    "            self.rz(input_params[2 * i + 1], self.qubits[i])\n",
    "            self.rx(input_params[2 * i], self.qubits[i])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ecccb4aa",
   "metadata": {},
   "source": [
    "### Instantiate and Inspect the Example Feature Map\n",
    "\n",
    "Finally, we will instantiate and inspect an `ExampleFeatureMap` object. We will use `feature_dimension=10` and the default linear entanglement, which should produce a 5-qubit feature map circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "91ba4f34",
   "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: ┤ Ry(θ[0]) ├─■───────────░─┤ Rz(x[1]) ├┤ Rx(x[0]) ├\n",
       "     ├──────────┤ │           ░ ├──────────┤├──────────┤\n",
       "q_1: ┤ Ry(θ[1]) ├─■──■────────░─┤ Rz(x[3]) ├┤ Rx(x[2]) ├\n",
       "     ├──────────┤    │        ░ ├──────────┤├──────────┤\n",
       "q_2: ┤ Ry(θ[2]) ├────■──■─────░─┤ Rz(x[5]) ├┤ Rx(x[4]) ├\n",
       "     ├──────────┤       │     ░ ├──────────┤├──────────┤\n",
       "q_3: ┤ Ry(θ[3]) ├───────■──■──░─┤ Rz(x[7]) ├┤ Rx(x[6]) ├\n",
       "     ├──────────┤          │  ░ ├──────────┤├──────────┤\n",
       "q_4: ┤ Ry(θ[4]) ├──────────■──░─┤ Rz(x[9]) ├┤ Rx(x[8]) ├\n",
       "     └──────────┘             ░ └──────────┘└──────────┘</pre>"
      ],
      "text/plain": [
       "     ┌──────────┐             ░ ┌──────────┐┌──────────┐\n",
       "q_0: ┤ Ry(θ[0]) ├─■───────────░─┤ Rz(x[1]) ├┤ Rx(x[0]) ├\n",
       "     ├──────────┤ │           ░ ├──────────┤├──────────┤\n",
       "q_1: ┤ Ry(θ[1]) ├─■──■────────░─┤ Rz(x[3]) ├┤ Rx(x[2]) ├\n",
       "     ├──────────┤    │        ░ ├──────────┤├──────────┤\n",
       "q_2: ┤ Ry(θ[2]) ├────■──■─────░─┤ Rz(x[5]) ├┤ Rx(x[4]) ├\n",
       "     ├──────────┤       │     ░ ├──────────┤├──────────┤\n",
       "q_3: ┤ Ry(θ[3]) ├───────■──■──░─┤ Rz(x[7]) ├┤ Rx(x[6]) ├\n",
       "     ├──────────┤          │  ░ ├──────────┤├──────────┤\n",
       "q_4: ┤ Ry(θ[4]) ├──────────■──░─┤ Rz(x[9]) ├┤ Rx(x[8]) ├\n",
       "     └──────────┘             ░ └──────────┘└──────────┘"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "feature_map = ExampleFeatureMap(feature_dimension=10)\n",
    "circuit_drawer(feature_map)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "b37d69e1",
   "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:44:49 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
}