Sorted Circuit Parameters.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Sorted circuit parameters\n",
    "\n",
    "Two main changes:\n",
    "\n",
    "* Circuit parameters are returned in a fixed order (sorted by insertion)\n",
    "* Circuit parameters can be assigned by a list of values (instead of a dict only)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Let's start with a simple parameterized circuit..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "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: ┤ H ├┤ RZ(a) ├──■───────────\n",
       "     ├───┤├───────┤┌─┴─┐┌───────┐\n",
       "q_1: ┤ H ├┤ RX(b) ├┤ X ├┤ RY(c) ├\n",
       "     └───┘└───────┘└───┘└───────┘</pre>"
      ],
      "text/plain": [
       "     ┌───┐┌───────┐              \n",
       "q_0: ┤ H ├┤ RZ(a) ├──■───────────\n",
       "     ├───┤├───────┤┌─┴─┐┌───────┐\n",
       "q_1: ┤ H ├┤ RX(b) ├┤ X ├┤ RY(c) ├\n",
       "     └───┘└───────┘└───┘└───────┘"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector\n",
    "\n",
    "a, b, c = [Parameter(name) for name in 'abc']\n",
    "circuit = QuantumCircuit(2)\n",
    "circuit.h([0, 1])\n",
    "circuit.rz(a, 0)\n",
    "circuit.rx(b, 1)\n",
    "circuit.cx(0, 1)\n",
    "circuit.ry(c, 1)\n",
    "\n",
    "circuit.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Instead of a set of unordered parameters, the return type is now a ``ParameterView``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParameterView([Parameter(a), Parameter(b), Parameter(c)])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "circuit.parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "This is similar to the ``KeysView`` object of a dictionary, except it allows indexing. This allows to treat numeric parameter-arrays and symbolic parameter-arrays more similarly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a\n",
      "[Parameter(b), Parameter(c)]\n"
     ]
    }
   ],
   "source": [
    "print(circuit.parameters[0])\n",
    "print(circuit.parameters[1:])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "An order allows us to assign parameter values by an array instead of a `{parameter: value}` dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "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: ┤ H ├┤ RZ(1) ├──■───────────\n",
       "     ├───┤├───────┤┌─┴─┐┌───────┐\n",
       "q_1: ┤ H ├┤ RX(2) ├┤ X ├┤ RY(3) ├\n",
       "     └───┘└───────┘└───┘└───────┘</pre>"
      ],
      "text/plain": [
       "     ┌───┐┌───────┐              \n",
       "q_0: ┤ H ├┤ RZ(1) ├──■───────────\n",
       "     ├───┤├───────┤┌─┴─┐┌───────┐\n",
       "q_1: ┤ H ├┤ RX(2) ├┤ X ├┤ RY(3) ├\n",
       "     └───┘└───────┘└───┘└───────┘"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "values = [1, 2, 3]\n",
    "circuit.assign_parameters(values).draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Partial binding still requires to pass the dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# values = [1, 2]\n",
    "# circuit.assign_parameters(values).draw()  # error mismatching dims"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "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: ┤ H ├┤ RZ(1) ├──■───────────\n",
       "     ├───┤├───────┤┌─┴─┐┌───────┐\n",
       "q_1: ┤ H ├┤ RX(2) ├┤ X ├┤ RY(c) ├\n",
       "     └───┘└───────┘└───┘└───────┘</pre>"
      ],
      "text/plain": [
       "     ┌───┐┌───────┐              \n",
       "q_0: ┤ H ├┤ RZ(1) ├──■───────────\n",
       "     ├───┤├───────┤┌─┴─┐┌───────┐\n",
       "q_1: ┤ H ├┤ RX(2) ├┤ X ├┤ RY(c) ├\n",
       "     └───┘└───────┘└───┘└───────┘"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "circuit.assign_parameters({a: 1, b: 2}).draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Anonymous binding in action\n",
    "\n",
    "Anonymous binding (aka binding with an array) is especially useful if circuits are passed around or constructed for you (e.g. from the circuit library)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "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: ───┤ H ├─────■───────────────■───────────────■───────────────■──┤ H ├\n",
       "     ┌──┴───┴──┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐└───┘\n",
       "q_1: ┤ P(p[0]) ├┤ X ├┤ P(p[1]) ├┤ X ├┤ P(p[2]) ├┤ X ├┤ P(p[3]) ├┤ X ├─────\n",
       "     └─────────┘└───┘└─────────┘└───┘└─────────┘└───┘└─────────┘└───┘     </pre>"
      ],
      "text/plain": [
       "        ┌───┐                                                        ┌───┐\n",
       "q_0: ───┤ H ├─────■───────────────■───────────────■───────────────■──┤ H ├\n",
       "     ┌──┴───┴──┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐└───┘\n",
       "q_1: ┤ P(p[0]) ├┤ X ├┤ P(p[1]) ├┤ X ├┤ P(p[2]) ├┤ X ├┤ P(p[3]) ├┤ X ├─────\n",
       "     └─────────┘└───┘└─────────┘└───┘└─────────┘└───┘└─────────┘└───┘     "
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def secret_circuit():\n",
    "    params = ParameterVector('p', 4)\n",
    "    circuit = QuantumCircuit(2)\n",
    "    circuit.h(0)\n",
    "    for param in params:\n",
    "        circuit.p(param, 1)\n",
    "        circuit.cx(0, 1)\n",
    "    circuit.h(0)\n",
    "    \n",
    "    return circuit\n",
    "\n",
    "circuit = secret_circuit()\n",
    "circuit.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Let's try to assign some values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "values = np.arange(circuit.num_parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "We previously had to pass a dictionary of values. But how do we create this dictionary?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Attempt 1: Just call `list(circuit.parameters)` and use that."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "param_dict = dict(zip(list(circuit.parameters), values))  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Problem: Not consistent! Every time you run this script the values are mapped in a different order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Attempt 2: Impose some order and sort the parameters manually."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "sorted_params = sorted(circuit.parameters, key=lambda p: p.name)\n",
    "param_dict = dict(zip(sorted_params, values))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Works, but is this really intuitive sorting? "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0: theta[0]\n",
      "1: theta[10]\n",
      "2: theta[1]\n",
      "3: theta[2]\n",
      "4: theta[3]\n",
      "5: theta[4]\n",
      "6: theta[5]\n",
      "7: theta[6]\n",
      "8: theta[7]\n",
      "9: theta[8]\n",
      "10: theta[9]\n"
     ]
    }
   ],
   "source": [
    "params = ParameterVector('theta', 11)\n",
    "sorted_params = sorted(params, key=lambda p: p.name)\n",
    "for i, sorted_param in enumerate(sorted_params):\n",
    "    print(f'{i}: {sorted_param}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Note\n",
    "\n",
    "All our built-in algorithms handling parameters currently do the above to ensure reproducibility. But the cost is that the assignment can be non-intuitive."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Now, we already have an order and can just do."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<qiskit.circuit.quantumcircuit.QuantumCircuit at 0x7fa349840090>"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "circuit.assign_parameters(values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### A less standard example\n",
    "\n",
    "Imagine a user playing with their own circuit or a researcher plugging circuits together!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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sWVNrCzQdfXHSL1yS98xi9GU+bH9r84GYDiZicqjabtOCgpBUlBIseVf2jQdOSlpek5ZqCL7DQAIW/13sdvypOqXLCSRaC2+1zxAcd03F6Lumwv1lOb55jxwqk7br9l5CGp2HlLmfAuXJvD66smjKK3cfctc1piyEhEREWlD3N4ziNt7psz5yuzcogKNoTDGzETlKW+7BoAjby/RUxrNxGR9llT9koWkcsjcGxjNa3va6ShIJRlaHqnwfTB8/BsRERGRJg7e7kb3ulJllvq1qXoz1u3aGPchmrCQVA7FB+9KHUG0KS2kTkCl4d+FiIiIyLi1DxwldYQKM8bMROUx1u3aWHOXhQOFEBERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCwkERERERERERGRKCZSBzB0qp82QoiJk+S1Ze4NoPjgXdHLfx0GRD7SXZ6K8rQDprSQOgURUSFD20dSSTxuPD/YHw0b+2JJZ2dvwINrMXp/XQdvd7QPHFWpdaXKDFQtN5EmxrpdG+M+RBMWksohxMRBCLsudQxRIh8Bl+5LnYKIyDBxH0lkONgfydg8uBaDlGDj+EzwmDFmJiqPsW7Xxpq7LLy1jYiIiIiIiIiIRGEhiYiIiIiIiIiIROGtbUREVCUhkfdx4FQiLlxLLZrW84P9aO1VC51a1cHL3erBzFQhYUKiihEEAUHnkxF0/g4uhj/Zrvt/dAhtmzmi+4su8HvBGTKZTMKUJSXfy8ZfR2Jx4fqTzF3e2YMWTWqinbcjBr7UEA525hImJKq48Og07P0vAReu3yua1mP0PrTyckBHXye84lcPFub8SEPGQxAEnL5yF0fOJhU7d+o34SDaNKsFvxdc8FJ7V8jlhnWMufcgB38djcP5sHu4Hp1WNP2DeSfwgndtDOzRAHVqWUoXkPSKe10iIqqUf4NvY96aSzh95W6JeUfOJuHI2STgF8CpliU+GtEMn73rA3MzFpTIcAmCgA1/38CX668iKq7kSNB7/0vA3v8SsGDtZXi52+Hz93zwzoCmkheUbsanY+b/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\n",
      "text/plain": [
       "<Figure size 1531.4x204.68 with 1 Axes>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit.circuit.library import ZZFeatureMap, EfficientSU2\n",
    "\n",
    "phase = Parameter('phase')\n",
    "ansatz = ZZFeatureMap(3, reps=1)\n",
    "ansatz.p(phase, 0)\n",
    "ansatz.compose(EfficientSU2(3, reps=1), inplace=True)\n",
    "ansatz.draw(output='mpl', style='iqx')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Optimization\n",
    "\n",
    "This direct assignment of arrays is especially valuable in optimization, since classical subroutines always handle parameters as arrays of values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 387.597x204.68 with 1 Axes>"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit.circuit.library import PauliTwoDesign\n",
    "from qiskit.opflow import Z, I, CircuitSampler, StateFn\n",
    "\n",
    "observable = Z ^ Z ^ I\n",
    "ansatz = PauliTwoDesign(3, reps=1)\n",
    "ansatz.draw(output='mpl', style='iqx')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "def cost_function(values):\n",
    "    bound = ansatz.assign_parameters(values)\n",
    "    expectation_value = ~StateFn(observable) @ StateFn(bound)\n",
    "    return expectation_value.eval().real"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.0"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cost_function(np.zeros(6))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.optimize import minimize\n",
    "\n",
    "initial_guess = np.random.random(ansatz.num_parameters)\n",
    "maxiter = 100\n",
    "\n",
    "# runs too long for this tutorial ;)\n",
    "# minimize(cost_function, initial_guess, method='bfgs', options={'maxiter': maxiter})  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our built-in optimization algorithms (VQE, QAOA) can now also use this order instead of sort parameters by name and stay consistent with the users input."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Composing\n",
    "\n",
    "When composing circuits, the parameters are composed in the same order as the circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "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: ───┤ H ├─────■───────────────■───────────────■───────────────■──┤ H ├»\n",
       "     ┌──┴───┴──┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐└───┘»\n",
       "q_1: ┤ P(p[0]) ├┤ X ├┤ P(p[1]) ├┤ X ├┤ P(p[2]) ├┤ X ├┤ P(p[3]) ├┤ X ├─────»\n",
       "     └─────────┘└───┘└─────────┘└───┘└─────────┘└───┘└─────────┘└───┘     »\n",
       "«     ┌─────────┐┌─────────┐\n",
       "«q_0: ┤0        ├┤0        ├\n",
       "«     │  RXX(x) ││  RYY(y) │\n",
       "«q_1: ┤1        ├┤1        ├\n",
       "«     └─────────┘└─────────┘</pre>"
      ],
      "text/plain": [
       "        ┌───┐                                                        ┌───┐»\n",
       "q_0: ───┤ H ├─────■───────────────■───────────────■───────────────■──┤ H ├»\n",
       "     ┌──┴───┴──┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐┌─────────┐┌─┴─┐└───┘»\n",
       "q_1: ┤ P(p[0]) ├┤ X ├┤ P(p[1]) ├┤ X ├┤ P(p[2]) ├┤ X ├┤ P(p[3]) ├┤ X ├─────»\n",
       "     └─────────┘└───┘└─────────┘└───┘└─────────┘└───┘└─────────┘└───┘     »\n",
       "«     ┌─────────┐┌─────────┐\n",
       "«q_0: ┤0        ├┤0        ├\n",
       "«     │  RXX(x) ││  RYY(y) │\n",
       "«q_1: ┤1        ├┤1        ├\n",
       "«     └─────────┘└─────────┘"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x, y = Parameter('x'), Parameter('y')\n",
    "\n",
    "other = QuantumCircuit(2)\n",
    "other.rxx(x, 0, 1)\n",
    "other.ryy(y, 0, 1)\n",
    "\n",
    "composed = circuit.compose(other)\n",
    "composed.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Circuit + Other returns ```[a b c] [x y]```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParameterView([Parameter(p[0]), Parameter(p[1]), Parameter(p[2]), Parameter(p[3]), Parameter(x), Parameter(y)])"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "composed.parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other + Circuit returns ``[x y] [a b c]`` (using the ``front`` keyword here)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParameterView([Parameter(x), Parameter(y), Parameter(p[0]), Parameter(p[1]), Parameter(p[2]), Parameter(p[3])])"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "circuit.compose(other, front=True).parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Appending"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ParameterView([Parameter(x), Parameter(y)])\n"
     ]
    }
   ],
   "source": [
    "first = QuantumCircuit(1)\n",
    "first.p(x, 0)\n",
    "\n",
    "second = QuantumCircuit(1)\n",
    "second.rz(y, 0)\n",
    "\n",
    "first.append(second, [0])\n",
    "print(first.parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tensoring\n",
    "\n",
    "TODO could argue for both orders.\n",
    "\n",
    "When tensoring, the parameters of the top circuit are coming first. (status quo)\n",
    "\n",
    "When tensoring, the parameters of the leftmost object in the tensorproduct are coming first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParameterView([Parameter(x), Parameter(y), Parameter(p[0]), Parameter(p[1]), Parameter(p[2]), Parameter(p[3])])"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "circuit.tensor(other).parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Conversion to DAG and back"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ParameterView([Parameter(x), Parameter(y)])\n",
      "     ┌──────┐\n",
      "q_0: ┤ P(y) ├\n",
      "     ├──────┤\n",
      "q_1: ┤ P(x) ├\n",
      "     └──────┘\n"
     ]
    }
   ],
   "source": [
    "x, y = Parameter('x'), Parameter('y')\n",
    "circuit = QuantumCircuit(2)\n",
    "circuit.p(x, 1)\n",
    "circuit.p(y, 0)\n",
    "print(circuit.parameters)\n",
    "print(circuit.draw())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "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: ┤ P(y) ├\n",
       "     ├──────┤\n",
       "q_1: ┤ P(x) ├\n",
       "     └──────┘</pre>"
      ],
      "text/plain": [
       "     ┌──────┐\n",
       "q_0: ┤ P(y) ├\n",
       "     ├──────┤\n",
       "q_1: ┤ P(x) ├\n",
       "     └──────┘"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit.converters import circuit_to_dag, dag_to_circuit\n",
    "\n",
    "dag = circuit_to_dag(circuit)\n",
    "circuit2 = dag_to_circuit(dag)\n",
    "\n",
    "circuit2.draw()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParameterView([Parameter(y), Parameter(x)])"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "circuit2.parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Transpiling"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qiskit import transpile"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParameterView([Parameter(p[0]), Parameter(p[1]), Parameter(p[2]), Parameter(p[3]), Parameter(x), Parameter(y)])"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled = transpile(composed, basis_gates=['u', 'cx'], optimization_level=0)\n",
    "transpiled.parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParameterView([Parameter(p[0]), Parameter(p[1]), Parameter(p[2]), Parameter(p[3]), Parameter(x), Parameter(y)])"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled = transpile(composed, basis_gates=['u', 'cx'], optimization_level=3)\n",
    "transpiled.parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "     ┌──────┐┌───────────┐\n",
      "q_0: ┤ P(x) ├┤ P(-1.0*x) ├\n",
      "     └──────┘└───────────┘\n",
      "ParameterView([Parameter(x)])\n"
     ]
    }
   ],
   "source": [
    "x = Parameter('x')\n",
    "circuit = QuantumCircuit(1)\n",
    "circuit.p(x, 0)\n",
    "circuit.p(-x, 0)\n",
    "\n",
    "transpiled = transpile(circuit, basis_gates=['p', 'cx'], optimization_level=3)\n",
    "print(transpiled)\n",
    "print(transpiled.parameters)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}