QuantumSimCounter.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# QuantumSim - Counter\n",
    "Author: Nico Kuijpers<br>\n",
    "Date: January 2, 2025\n",
    "\n",
    "In this notebook we introduce a counter to count the number of qubits in state $|1\\rangle$. The qubits are initialized by an input string. The length of the string corresponds to the number of qubits of which the the states $|1\\rangle$ are counted. Characters 'I', 'X', and 'H' indicate which operation is to be applied upon initialization.\n",
    "\n",
    "The counter is implemented in QuantumSim. In this notebook, a generic version of the Toffoli operation is applied, which has a list of control qubits and a target qubit as parameters. \n",
    "\n",
    "The implementation of the generic Toffoli gate in QuantumSim is described in this notebook:\n",
    "\n",
    "https://github.com/nicokuijpers/QuantumSim/blob/main/QuantumSimMoreOperations.ipynb"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from quantumsim import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Count till one\n",
    "Below a function is defined to implement a basic counter circuit. The circuit has $2$ qubits. \n",
    "Depending on the input character, the first qubit is initialized with either a Pauli X, Hadamard or Identity operation. \n",
    "Next, a CNOT operation is applied with control qubit $0$ and target qubit $1$.\n",
    "Upon measurement, the second qubit will be in state $|1\\rangle$ when first qubit is also in state $|1\\rangle$, thus counting the number of ones."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "def create_counter_circuit_one(input_char:chr) -> Circuit:\n",
    "    circuit = Circuit(2)\n",
    "    \n",
    "    # Initialize input qubit\n",
    "    if input_char == 'X':\n",
    "         circuit.pauli_x(0)\n",
    "    elif input_char == 'H':\n",
    "        circuit.hadamard(0)\n",
    "    else:\n",
    "        circuit.identity(0)\n",
    "\n",
    "    # Counter\n",
    "    circuit.cnot(0,1)\n",
    "    return circuit"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below a circuit is created with input character is 'H'. With this input this, a Bell state is generated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjkAAAHECAYAAADbDzs3AAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8pXeV/AAAACXBIWXMAAA9hAAAPYQGoP6dpAABGB0lEQVR4nO3deVyU5f7/8fewLwoIKggi4VIq5IqUx93STp6UTE+WhpqnU2mZpXncUvO4V6bZQqWpUcdMSws1W0zNLRVLPS7VN81dwRIBTSBlrt8fPbx/jVjHQRC8ez0fj3k8nOu65ro/9zA3vL3va2YcxhgjAAAAm/Eo6wIAAABKAyEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAFCqvvrqK82aNausy8CfECEHv2v+/PlyOByqX79+WZdSolJTU9WwYUP5+/vLx8dHd9xxR1mXBBs4ceKEevTooapVq8rLy0thYWFatWpVqW1v8eLF8vDwkMPhkMPh0KJFi0ptW1fqtdde04ABA67a9u68807realQocJV2y7KH0LONeDBBx+Uw+FQYGCgvvzyS0nSunXr5OnpaR3IixcvLvHtdu/eXZMmTdLZs2dLfO6y8s0336hfv37q16+fvvzyS3399deaPXt2WZcFG3j88cd14MABLVy4UNu3b9e6devUunXrUtte586dtWfPHu3cuVORkZH6+eefS21bV+q2227TwIEDr9r25syZo127dmnOnDlX/Xnp3bu35s2bV2LzjR49WuPGjSux+f5svMq6APxvzz77rKKjozVmzBg9/vjj2rRpk1q0aKFvv/1WQ4cOlcPhKJWzET4+PqpWrVqJz1uWtm3bpqpVq2rQoEFlXQpsZuvWrXryySfVtm3bq7I9b29v1a1b1/p3edatWzd169btqm0vNDRUoaGh+vHHH6/aNi84dOiQDh48WGLzHT58WA6Ho8Tm+7PhTM41IDg4WNWqVdPNN9+sH3/8Ue+88448PDxUp04dhYSEKDg4WD4+PlqzZo08PT0VHBxsPfbhhx+Ww+GQt7e3tm/fLkm65ZZb5HA41L59e1WrVk0xMTFKTU1Vo0aNFBISookTJxapYd68eapXr558fX1Vq1YtTZs2TRd/t+vGjRv117/+VcHBwQoJCVGrVq308ccfu4yZNGmSy+n1devWqW3btgoICFBsbKz27Nnj9vOzadMm3X777QoODpafn5+aNGmiuXPnuoxJT0+Xt7e3evXqpePHj1s1eHh4aP78+W5v83K3K0mbN29Whw4dVKFCBYWEhKhNmza655571LNnT7fG7du3T76+vvLx8VFmZqYkacqUKdZ+LF261JrrP//5j7WPzz77rHbv3q077rhDFStWVLVq1bR69Wq3xknSkSNH1LdvX0VERCggIEANGjTQzJkzdf78eWvMAw88IIfDoXvuuUcPPfSQIiIiFBERoaeffrrI83Ls2DH16dNHlStXtuYbMGCAYmJiXMadOnVKjz32mGrUqCE/Pz/Vq1dPY8eOVV5ensu4C7VXrlxZgYGBatCggZo2bVrs/wUXFBRo7Nixql27tnx8fBQeHq4+ffro0KFDLuOSkpLkcDj0/fff66GHHrKezwsBpDjbHT16tK677jr5+voqNjZWDz/8sK677jrt3LmzWPMNHTpUderUkb+/v6pWrap+/frpzJkzLuPOnTunf/3rX4qNjZWfn59q1Kihdu3aXfJy9dSpU3XDDTfI399fkZGRateunaKjo4vMOWbMGOv5iI+P/90aL/cYWbJkiVq0aKHg4GAFBgaqefPm2rJli9vPibvWr1+vdu3aqVKlSgoKClJCQoLi4uL05ptvXnL8//re60OHDqlnz56KjIyUr6+vrrvuOj3zzDO/O/5/zed0OjV9+nTFxcXJz89PMTEx6tu3r44ePeoyLjc3Vw8++KCqV68uPz8/1apVS23atFHHjh3/cP5rmsE1YdasWaZNmzZm8eLFpkaNGiYvL88YY0yfPn1Mnz59jDHGFBYWmtTUVPPbH2tWVpbZuXOnkWRWr15tjDHmxx9/NM2aNTOxsbFm5cqV5tZbbzWSzNixY80rr7xivL29zcmTJ40xxsydO9d4enqaKlWqmNmzZ5uNGzeaCRMmGB8fHzN06FBrO5988onx9vY2Dz30kFm9erXZuHGjGT58uPHw8DAvv/yyNe7MmTNmz549JjIy0vztb38z1atXN3PnzjWfffaZGThwoNm/f79bz8tnn31mvL29ze23324++ugjs3btWvPkk08aT09PM3z4cGuc0+k03333nZkzZ46RZHbu3Gl27txpdu/ebc6dO+fWNt3Z7qpVq4yPj4+58847zYoVK8yXX35pBg4caCSZNm3auD1uzZo1RpL1PJ05c8bs2rXLREZGmrlz51rjCgoKzDfffGMSEhLMrbfeaiIiIszMmTPNmjVrzODBg81XX33l1rgjR46YatWqmfbt25u0tDSzZcsW88orr5jQ0FDz97//3dpudna2SUpKMpJM3759zYYNG8xLL71kHA6HWbp0qTXu+PHjJjo62tx4443m3XffNVu2bDEzZswwgYGBLq/f06dPm/r165smTZqYhQsXmvT0dPPmm2+amJgY07x5c5efXd26dU3nzp3N+vXrzeeff24eeOABqw53FRYWmltuucUEBweb6dOnmy+//NK8++67pn79+iY8PNwcPHjQGnvhGEtISDD9+/e3XlvHjh0r1nY7duxowsLCzIsvvmg2b95sFi5caGrVquVyDF8sJibG5ef/W3v27DG1a9c248aNM5s2bTKLFi0yVatWNUOGDHEZN2XKFBMeHm7ee+89s3nzZvPSSy+ZsLAwc/GfiQULFpiAgAAzd+5cs2XLFjNv3jwTExNjJJkDBw64jL3w+pwwYYKJiYm5ZH2X+9o3xpiOHTuae++913z00Udm/fr15m9/+5uJiooy+fn5l5x79erVRep31y+//GKCgoJMv379zKZNm8yKFStM165djSTz9NNPW+Puu+8+4+XlZSQZh8NhPD09jaenp/Hx8TELFixwmXPOnDmmadOm5vXXXzdbtmwx06dPL3KMjBo1ynh7exuHw+Eyn5eXl3n22Wdd5uvdu7cJDw83L7/8stm8ebNZtmyZadWqlalSpYrLz+Thhx82N9xwg1m+fLnZuHGjmTRpkgkICDDXXXfdFT1H5Rkh5xpxIeQYY8wtt9xiJk2aZIxxDTnG/P5BffEvyDZt2pixY8dac1eoUMGcP3/e/Pzzz0aSSU9PN8b8GnIkmTVr1rjM9+yzzxpPT09z+PBhY4wx9evXN48//niR7Q4aNMgEBwebX375xaU9JibGxMTEmEOHDrn1PFysfv36pk2bNsbpdLq0T5kyxXh4eJh9+/a5tJfELz13thsfH29uu+22Io8fNmyY6dGjh3X/csft37/fJeRc8Ht/5Nq0aWNCQkLM9u3b/3B//te4AQMGmISEBHP+/HmX9iVLlhhJZsuWLVZbnz59TKNGjVyem/bt25snnnjCuv/oo4+aiIgIk5WV5TJfWlqaiYqKsu4/88wzpnr16ubMmTMu47Zt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t26d6dKliwkMDLzi9ZHlFSHnGrBq1SrjcDiMJCPJWll//vx507hxY/PII4+4jP/0009NXFycCQgIMI0bNzaLFi0ygYGBxsPDw6xatcp07NjRmmvkyJFm2bJlxsPDw7Rt29YYY0zNmjWNl5eXmTBhgpFk/Pz8TGpqqqlVq5bx9vY2tWrVMi+++GKROt977z2TkJBgfH19TVhYmGnevLmZNm2ayy/766+/3tr2b2+/XRznrg0bNpiOHTuaihUrGl9fX9OoUSMza9YslzE7d+403t7eRbbr6elZZJFnSW7XGGM2btxobr31VhMYGGhCQkJM+/btzeLFi4s97quvvjKJiYkmICDA1KtXz6SkpJj69esbSebNN980xhiXn/Fvb506dXKZ63LHGfPrYt9OnTqZihUrmsDAQBMfH2+GDh3q8ofyn//8pzXHhfD9j3/8w2rr1auXNfbw4cMmOTnZhIWFGX9/f9OoUSMzffr0Iu+U+eGHH8zdd99tQkNDjb+/v7nhhhtM//79zddff+0yrk6dOqZbt26mXr16xt/f3wr77r5j74K8vDzz1FNPWcdD5cqVTa9evYrMd++99172c3g58vPzzahRo0xMTIzx8fExNWvWNEOGDDHHjx93GXfhXWyXur300kvWuM2bN5vExETj7+9vatSoYXr27Gnef/994+XlZXx8fKw//KNHjzYtW7Y0rVu3tp7rxo0buwQXY4yZPXu2ady4senQoYOpUqWK8fX1NXXr1jWvvvqqy7hXXnnld+sLCAhwWaR8Oa/9M2fOmL59+5pKlSqZSpUqmRYtWpglS5aYRo0aGUlWiDh+/Ljx9fW95HZ9fX3dDp/Z2dkmMjLSdO/e3dSuXdv4+vqa8PBw069fP/PTTz9dcvw999xjgoKCTGBgoElMTDSTJ092WWT/5ptvmlq1almv52HDhln/oaxZs6bLfL/88ovp37+/dZzceOON5qmnnnIJQz///LMZMmSIiY6ONj4+PiYmJsZ069bNLF261OU/cb179zYdO3Y0N910kwkKCjIVKlQwLVq0KPLGEjtxGFMKCzYAAADKGGtyAACALRFyAACALRFyAACALRFyAACALRFyAACALRFyAACALf1pv9bB6XTq2LFjqlixYpl9fDsAAHCPMUanT59WZGRkka+yuNifNuQcO3bsir4cEgAAlJ3Dhw+revXqfzjm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x4+rW7duOn36dIkXBwAAUFxuh5ygoCDl5+dbIadatWrKz8/XpEmTSrw4AACA4nI75GzatEmLFi1SgwYNrLYpU6ZowYIFJVoYAADAlXA75GRlZalatWoubdHR0crKyiqxogAAAK6U2yGnSZMmRb7C4d1331WjRo1KqiYAAIAr5va7q5577jm1a9dOmzZtUnx8vHbs2KHly5dr9erVpVEfAABAsbh9JichIUHbtm1TWFiY1q9fr6pVq2rbtm1q2rRpadQHAABQLMX6nJzatWvrhRdecGkzxlhf8wAAAFDWiv1hgJmZmSooKJAkOZ1O/eUvf9GxY8dKrDAAAIAr4XbI+fjjj9W3b19Jkr+/v9WemZlZYkUBAABcKbdDzoABAzR9+nTde++9Lu133313iRUFAABwpdxeeJybm6vbb7+9SPvChQtLpCAAAICS4HbIufvuuy/5FQ7du3d3a57CwkKNGTNGkZGRCg0N1cCBA3X+/Hmr/8yZM+ratasCAgLUqVMn5eTkFJkjJSVFYWFhio2N1apVq9zdFQAAYGNuX65asWKFDh48qNmzZyskJETSr++sOnTokFvz7Nu3T/v379fnn38ub29vdejQQbVr19agQYMkSePHj5fT6dSRI0f0yCOPaOTIkXr55Zetx+/evVujRo3SunXrtHfvXvXo0UOHDh1yWScEAAD+vNwOOWfPntX+/ftd2pxOp5o3b+7WPNdff73eeust63737t21efNma77U1FQtWrRIoaGhGjZsmNq1a6fnn39evr6+kqTU1FTdddddiouLU1xcnMaOHau0tDT16NHD3V0CAAA25PblqoyMDMXExLjcYmNjlZGRUewizp07p02bNqlZs2aSpCNHjigjI8P6gMGGDRsqLy9P33//vfWY9PR0lw8gTExMVHp6erFrAAAA9uJ2yHE4HCooKNCiRYs0Y8YMSdKGDRtc1tO446233lKNGjXk6empxx57TNKvb0f38/OzLj05HA5VqlTJJUhlZmYqNDTUuh8WFvaHQaugoEC5ubkuNwAAYF9uh5yjR4+qYcOGeuKJJzRixAidPHlSM2fO1Ouvv16sAjp27Kjnn39e+/bt08SJEyXpkp+c7HQ6XdovHnNx/8UmT56s4OBg6xYdHV2segEAwLXB7ZAzaNAgtW/fXgcPHlRISIgKCwvVs2fPIt9MfrnCw8N17733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2mX1P/XUU4qNjdXhw4e1ceNGXX/99Tp16pTVv2bNGr399ttau3atDh8+rEceeURZWVn65ZdfrDG33nqrzp07p9GjR1/yUlL37t21f/9+rV69Wj/88INq166tPXv2KCcnR5Lk4eGhdu3a6dNPP9WPP/6orl27avjw4Ze9j5fjP//5j7Zt26bt27dr79696tatm06cOGGFlJSUFC1fvlyRkZHavn27tm/frm3btqlKlSrWHBUqVNCQIUP03Xffac+ePdq2bZuWL18uSWrcuLG+/vprdenSRf/+97+tOX4bctavX6+kpCQ99thjOnz4sF599VWNHj1ab7zxhjWmT58+Gjx4sE6cOKEFCxbIx8dHZ86cKdHnArjWlI9z1QBKzIkTJxQREXHF8xQWFuq1117TE088IT8/P509e1Y7d+5UfHy8JCk/P1+JiYkKCgpSUFCQUlNTrfBxoT8yMlLVq1eXr6+vHnjgAf39739XcHCwy3Y8PT3l4VH0/1tff/211q9fr2PHjikkJESSNHPmTJ04ccIKEOfOndPBgwf1yiuv6NSpU6pcuXKRS3JXKj8/X7GxsQoPD5enp6eGDRumhx9+2Ko5ICBAVapUkaen5+8+78YYLVq0SE899ZQcDofOnTunnTt36o477pAkVa1aVf7+/goODr7kHM8++6wGDRqknj17SpLatm2rp59+Ws8995z+8Y9/WHU2btxYFSpUUPPmzbVu3ToVFhaW6HMBXGs4kwPYTOXKla94fcjRo0f117/+VYmJiVqxYoUWLVqkOnXquCxQfvrppzV79mxVrFhR1atX180336ylS5da/R06dFD9+vUVFhamqlWrqn79+ho+fLjOnj17WTXs27dP1atXtwKO9GsgWrRokaKioiRJI0aMUFpamp577jl98cUXGjx4cIkvou7du7fy8/MVFBSkiIgI3XjjjZo6daqcTudlPT4vL08dOnRQlSpVtGTJEi1btkyJiYlu1bl37169+uqr1qWsiIgIjRo1SkePHrXGpKSk6LbbblOlSpUUGxurzp07a+fOnW7vL2AnnMkBbOaWW27RI488om+++Ub16tWz2gsKCuTl5SVPT8//OcemTZtUu3ZtjR071moLCAhwGTNnzhx9+OGHqlKlirKyspSenq6uXbuqQ4cOCg8P14YNG9SoUSOlpKTo5MmTOnHihHr16qWXX35ZQ4cO/Z811KpVS4cPH1Z2drZL0Dl27JiqVasmh8Ohzz//XBMmTNAtt9wiScrMzPyf87rrww8/VN++fbVw4UKdPHlSR48eVefOndW4cWNrDZKnp6d+/vnnSz5+z549ysvL0yuvvGK1hYaGFhn3R3NUr15d999/v+677z6X9ooVK1r/XrRokQ4ePKgzZ84oJydHKSkpuv/++7V792639xmwC87kADZTu3ZtPfjgg+revbs2bdqknJwcpaWlKS4uTp9++qk1rrCwUOfPn3f594V1JjVq1NAPP/yg7du368SJE3rqqae0YsUKq1/6dTFtjx499N133ykkJET5+fny8PCw3rH1ww8/6F//+pfeffdd+fn5ydfXV/n5+fLx8bHmcDqdOn/+vJxOp8u/JalJkyZq1aqVkpOTtX//fv3444+aMmWK6tatay1erlGjhj766CPl5ORo3bp16tOnjyS51HlhXmNMkf28HN99950eeughffbZZ6pQoYI8PDz0yy+/uOxHeHi48vPztWbNGp08eVKzZ89WixYtlJOTo8jISJ09e1YrV65UVlaWZs6cqVmzZhWpoXbt2vroo4+UnZ2tr776Sg888ICmTJkiSXr44Yf12muvaf/+/apYsaJOnTql2bNna9CgQdbj33nnHT388MPKyclRUFCQzp4961Ij8KdkANjO+fPnzZgxY0xUVJQJCAgwzZs3Nx988IHVv2XLFuPp6Wkkudx69+5tjRk9erQJCQkxVatWNT169DAPPfSQkWTmzp1rjDHm3nvvNbfeequpXr268fHxMTfccINZsGCB9fjly5ebhg0bmoYNGxo/Pz9TuXJl8+CDD5qCggJjjDG5ubkmMDCwSA2+vr7m2LFjxhhjcnJyzEMPPWQiIiJMcHCwueOOO8yWLVusbXzzzTemadOmJiAgwNx4440mJSXFBAQEmJiYGGOMMUePHjV+fn5FttG6devLfi5ffvllc9NNN5m6desaHx8fU61aNTNy5EjjdDpdxs2fP99ERkYaf39/06JFC5Oammr1paSkmKpVq5pKlSqZTp06mZEjRxpJZuzYsdaY7Oxs06lTJ+Pr62uioqLMww8/bA4dOmT1z5s3z9SvX9/4+fmZmJgY069fP7N9+3arv06dOuaWW24xoaGhVg3btm277P0E7MhhjBv/pQEAALhGcLkKAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADYEiEHAADY0v8DzXag8pWRLJYAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "input_char = 'H'\n",
    "circuit = create_counter_circuit_one(input_char)\n",
    "result = QuantumUtil.measure_circuit(circuit)\n",
    "QuantumUtil.histogram_of_classical_states(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Count till three\n",
    "Below a function is defined to implement a counter circuit that is able to count till three. The circuit has $5$ qubits. \n",
    "Depending on the corresponding characters in the input string, the first $3$ qubits are initialized with either a Pauli X, Hadamard or Identity operations. \n",
    "The two remaining qubits form a binary counter with qubit $3$ the most significant bit and qubit $4$ the least significant bit.\n",
    "\n",
    "The counter is implemented as follows. \n",
    "For each of the input qubits, a Toffoli operation is applied followed by a CNOT. \n",
    "The Toffolli operation ensures that the most significant bit becomes $|1\\rangle$\n",
    "when both the input qubit and the least significant bit are $|1\\rangle$. \n",
    "The CNOT operation ensures that the least signicant bit is flipped when the input qubit is in state $|1\\rangle$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def create_counter_circuit_three(input_string:str) -> Circuit:\n",
    "    if len(input_string) != 3:\n",
    "        raise ValueError(\"Wrong length input_string\")\n",
    "    \n",
    "    n = 3 # input qubits\n",
    "    m = 2 # counter qubits\n",
    "    circuit = Circuit(n + m)\n",
    "\n",
    "    # Initialize input qubits\n",
    "    for q in range(n):\n",
    "        char = input_string[q]\n",
    "        if char == 'X':\n",
    "            circuit.pauli_x(q)\n",
    "        elif char == 'H':\n",
    "            circuit.hadamard(q)\n",
    "        else:\n",
    "            circuit.identity(q)\n",
    "        \n",
    "    # Counter\n",
    "    for q in range(n):\n",
    "        circuit.toffoli(q, n + 1, n)\n",
    "        circuit.cnot(q, n + 1)\n",
    "    return circuit"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below a circuit is created with input string \"HXX\". Depending on the state of the first qubit, the last two qubits are either 10 (decimal 2) or 11 (decimal 3). Thus, the number of ones in the first three qubits is counted."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjkAAAHECAYAAADbDzs3AAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8pXeV/AAAACXBIWXMAAA9hAAAPYQGoP6dpAABGxUlEQVR4nO3deVyU5f7/8fcAsiogKCCIhEu5kCtSprlVdvKkZFqWhpqnU2qZpnncUvO4V6bZwunoUbMy09IylxaPmlsqlnpcqm+au4ImAi6Ayly/P3p4/xrRYhAE717Px2MeD+e6rrnuzz3MDW/v+5oZhzHGCAAAwGY8SroAAACA4kDIAQAAtkTIAQAAtkTIAQAAtkTIAQAAtkTIAQAAtkTIAQAAtkTIAQAAtkTIAQAUq2+//VbTp08v6TLwJ0TIwVXNnTtXDodDtWvXLulSitScOXNUr149+fn5ydvbW/fff39JlwQbOH78uDp37qywsDB5eXkpNDRUK1euLLbtLVy4UB4eHnI4HHI4HFqwYEGxbetavf322+rTp891294DDzxgPS9ly5a9bttF6UPIuQE8+eSTcjgcCggI0DfffCNJWrt2rTw9Pa0DeeHChUW+3U6dOmn8+PE6d+5ckc9dUr7//nv17NlTPXv21DfffKPvvvtOM2bMKOmyYAP9+/fX/v37NX/+fG3btk1r165V8+bNi2177dq10+7du7Vjxw5FRkbq7Nmzxbata3Xvvfeqb9++1217M2fO1M6dOzVz5szr/rx069ZNs2fPLrL5RowYodGjRxfZfH82XiVdAP7Yyy+/rOjoaI0cOVL9+/fXxo0b1bRpU/3www8aNGiQHA5HsZyN8Pb2VqVKlYp83pK0detWhYWFqV+/fiVdCmxmy5Ytev7559WyZcvrsr0yZcqoZs2a1r9Ls44dO6pjx47XbXshISEKCQnRiRMnrts2Lzl48KAOHDhQZPMdOnRIDoejyOb7s+FMzg0gKChIlSpV0u23364TJ07ogw8+kIeHh2rUqKHg4GAFBQXJ29tbq1evlqenp4KCgqzH9urVSw6HQ2XKlNG2bdskSXfddZccDodat26tSpUqKSYmRnPmzFH9+vUVHByscePG5ath9uzZqlWrlnx8fFStWjVNnjxZl3+364YNG/SXv/xFQUFBCg4O1p133qnPP//cZcz48eNdTq+vXbtWLVu2lL+/v2JjY7V79263n5+NGzfqvvvuU1BQkHx9fdWwYUPNmjXLZUxKSorKlCmjrl276tixY1YNHh4emjt3rtvbLOh2JWnTpk265557VLZsWQUHB6tFixZ65JFH1KVLF7fG7d27Vz4+PvL29lZaWpokaeLEidZ+fPbZZ9Zc77//vrWPL7/8snbt2qX7779f5cqVU6VKlbRq1Sq3xknS4cOH1aNHD0VERMjf319169bVtGnTdPHiRWvME088IYfDoUceeURPPfWUIiIiFBERoRdffDHf83L06FF1795dFSpUsObr06ePYmJiXMadOnVKzz77rKpUqSJfX1/VqlVLo0aNUnZ2tsu4S7VXqFBBAQEBqlu3rho1alTo/wXn5uZq1KhRql69ury9vRUeHq7u3bvr4MGDLuMSExPlcDj0008/6amnnrKez0sBpDDbHTFihG666Sb5+PgoNjZWvXr10k033aQdO3YUar5BgwapRo0a8vPzU1hYmHr27KkzZ864jLtw4YL+8Y9/KDY2Vr6+vqpSpYpatWp1xcvVkyZN0i233CI/Pz9FRkaqVatWio6OzjfnyJEjrecjLi7uqjUW9BhZtGiRmjZtqqCgIAUEBKhJkybavHmz28+Ju9atW6dWrVqpfPnyCgwMVHx8vOrUqaN33nnniuP/6HuvDx48qC5duigyMlI+Pj666aab9NJLL111/B/N53Q6NWXKFNWpU0e+vr6KiYlRjx49dOTIEZdxWVlZevLJJ1W5cmX5+vqqWrVqatGihdq0afO789/QDG4I06dPNy1atDALFy40VapUMdnZ2cYYY7p37266d+9ujDEmLy/PzJkzx/z2x5qenm527NhhJJlVq1YZY4w5ceKEady4sYmNjTUrVqwwd999t5FkRo0aZd566y1TpkwZc/LkSWOMMbNmzTKenp6mYsWKZsaMGWbDhg1m7Nixxtvb2wwaNMjazhdffGHKlCljnnrqKbNq1SqzYcMGM2TIEOPh4WHefPNNa9yZM2fM7t27TWRkpPnrX/9qKleubGbNmmW++uor07dvX7Nv3z63npevvvrKlClTxtx3331m2bJlZs2aNeb55583np6eZsiQIdY4p9NpfvzxRzNz5kwjyezYscPs2LHD7Nq1y1y4cMGtbbqz3ZUrVxpvb2/zwAMPmOXLl5tvvvnG9O3b10gyLVq0cHvc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Xp4kady4cfkWQDscDpUrV04VK1bMN4enp2eR1XC54lyo5+52nU5ngeYt6Ljfq+lKCvo8/964vLw8dejQ4YrrW7y9vVW9enWXtoI8/wXZ37y8PCUkJFzxHXBeXl6qWrWqdf++++7T3r17dfz4cZ08eVLp6ekaP3682rdvb63DKihjTIkt9ryW18GVJCYmKiMjQyNHjlTNmjV1/vx5zZ49W1999ZXLuNDQUC1fvlxnzpxRamqqsrKy9PXXX2vAgAGqWbOm7rvvPkmSn5+f3nvvPU2fPl3Hjh1TVlaWtm/fbq316N27t9s1FmSfp0+frr59+2rIkCFq3bq1AgIC9PPPP+vhhx92e3vu6tGjh7p166bU1FSdOnVKaWlpGjJkiJKSkrRp0ya35kpLS1PLli11xx136I033lDlypWVnp5e4N/nl8vLy5OXl5e+/fZbeXi4nrfw8PBQVFSUdb9q1arasGGDMjIylJaWptOnT2vBggVKSkpS/fr1VadOnULVUJpxJucG9c9//lOLFi3Kt1A3ODhY0q+LOi/ZunXrNW3r5MmTWr16tUvbokWLVKZMGd1xxx0KCwtTdHS0fvjhB+t/G5duNWrUUFZW1jVt/2oqVKigmjVr6v3338/X9+6778rDw0PNmjUrse1WqFBBtWvX1ocffphv3OrVq/X6669b8xVknHTln+/x48fzLTAsao0aNdKOHTt088035/sZ5+TkuB2kW7RooS+++CLfGb4DBw7o+eeft/7oNWrUSP/3f/+nqKiofNs1xlgBW5Juvvlm7d27V+Hh4apdu7aaNWumxx57TGlpaTp16pRb9d155506ePBgvjOBmZmZ+uyzz4rtreEtWrTQoUOHtGHDBpf27OxsvfDCC26/a+fUqVPasGGD3nnnHSUlJalx48Zq2rSpyx++S4YOHapJkyapbNmyql69uho2bKh+/frJx8dH33//vTXu0mfe+Pn5qWrVqqpfv766d++umJgYl3EF4c5rf8mSJXriiSf04osvqnnz5mrUqJEaN27s1vYK49SpU7r55puVmZmpyMhI1alTR61bt9YDDzxwxf318vL63dfbhg0blJeXp8WLF6t9+/Zq2LCh7r77bvn4+Fxx/B/N16hRI128eFHp6en5jpHy5cu7fARI165d9cEHHyg4OFi33HKL4uPj1a9fPxlj9OOPP7rxrNxASuo6GQruwoULZsyYMSY+Pt7s2rXLui78xhtvGEku6wPOnTtnQkNDTceOHc2GDRvMwoULTY0aNYwk8+6775q8vDxz/Phx07hxY9OnTx+TlZVlZs2aZSIjI01qaqox5tf1O++9957Jyckx48ePN5JMWFiY+c9//mO++eYbM2HCBOPr62teeOEFa7uzZ882DofDPPPMM2b16tVm7dq15sUXXzRRUVEmNjbWGnfkyBGzY8cOExkZacaOHWtdZ87IyCjUc/PFF18YLy8vk5iYaJYvX27Wrl1rhgwZYsqUKeOyMPpqC49/+OGHfOtqinK7K1asMGXKlDEPP/ywWbFihfn6669N37598y1QLug4Y4ypVauWufPOO83XX39tPv/8c9O4cWMjyYwfP9669n/8+PErrg84fvy4y1wFHbdr1y4TEBBg7rnnHrN06VKzadMmk5ycbBo2bGjKlCljfvrpJ2OMMadOnbLWEFy67p+enm61Xfo5Hz161ERFRZn69eubhQsXmo0bN5qXX37ZhISEmCZNmlg/k9TUVBMREWEaNWpkPv74Y7N582bzzjvvmJYtWxqHw+GyzkySiYmJMW+99ZZZv369WbJkialVq5apW7eu2z/fixcvmpYtW5qQkBAzbdo0a8FuvXr1TMWKFV3WRF1t4fFv1z0U1KUFzxUrVjRvv/222bRpk3n33XdNrVq1TMWKFa01cMYYc/LkSWtbvz2edu7cab0xwel0mkqVKpnHHnvMbNq0yXz11VfmySefNJ6eniYyMtL83//9nzVf9+7djaenpxk4cKBZtmyZ2bhxo3niiSeMp6eny5qrUaNGGUmmZ8+e5tNPPzWbN282w4cPN5LMxx9/bI3LyckxO3fuNDt27DBjx441kZGRVr0///yzNa6gr/3Bgweb2NhYs3TpUrNx40YzdepUExkZaSSZ2bNnm9OnT1tj9+zZY3bs2JHveN+zZ4/bP5NL6+BuvfVWM2vWLOu1EBkZadq3b59vfP/+/U3lypXNl19+adatW2fGjBljateubf75z38aY4zZuXOn8fT0NC+99JLZsmWL+fjjj83dd99tHA6HSUxMNIcPH3aZb+rUqaZs2bLmk08+MRs3bjSvvvqqady4sfnb3/5m/Yxbt25tIiIizNtvv202b95sPv30U9O1a1dTpkwZM3r0aGuuFi1aGH9/fzN69GizYsUKs3bt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cuRIde3aVZGRkWrZsqWSk5NdHh8XF6cxY8aoWbNmCgwM1Lx58+Tr61vg7QMAAHsrcMjx9PTMd0lqxYoVGjFihO644w6XNTUFsXXr1t/tL1u2rD799NPfHfP000/r6aefdmu7AADgz6HAIWfz5s3Wvzdt2qRhw4bJz89Pb7/9turWrVssxQEAABRWgUNOgwYNtGvXLg0bNkwnT57UhAkTdOedd1r93bt31zvvvFMsRQIAALirwO+uevLJJ3XbbbepevXqGj9+vIwxWrNmjdasWaOVK1fqvffeK846AQAA3FLgMzkzZsxQixYt9N1331mfTAwAAFBaFTjktGnTRp9//vlV+/9okTAAAMD1VODLVb8XcCQpMTHxmosBAAAoKm5/4jEAAMCNgJADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsqURDzrx589SxY0dFRETk6ztz5ow6dOggf39/tW3bVpmZmfnGJCcnKzQ0VLGxsVq5cuX1KBkAANwgSizkXLx4UUuWLFHNmjWVlpaWr3/MmDFyOp06fPiwgoKCNGzYMJf+Xbt2afjw4VqzZo2mTp2qzp07Kzs7+3qVDwAASrkSCzleXl5677339Pe//z1fn9Pp1Jw5czRo0CCFhIRo8ODBmjt3rnJzc60xc+bM0YMPPqg6deooMTFRUVFRWrx48fXcBQAAUIqVyjU5hw8fVmpqqho1aiRJqlevnrKzs/XTTz9ZY1JSUqx+SUpISFBKSspV58zNzVVWVpbLDQAA2FepDDlpaWny9fWVn5+fJMnhcKh8+fJKTU11GRMSEmLdDw0Ndem/3IQJExQUFGTdoqOji28HAABAiSuVIcfhcORrczqdLu2Xj7m8/3JDhw5VZmamdTt06FDRFQwAAEodr5Iu4ErCw8OVk5Oj7Oxs+fn5yRijjIwMhYeHu4xJT0+37qenp7v0X87Hx0c+Pj7FWjcAACg9SuWZnKioKEVERGjLli2SpO3bt8vf3181atSwxsTHx1v90q9rdBISEq57rQAAoHQq0ZCTm5urc+fOSfr1c3EuXLjwa1EeHkpKStLkyZN16tQpTZo0SV26dHE5E5OUlKRFixZp9+7dWrx4sY4cOaL27duXyH4AAIDSp8RCzokTJxQYGKg6depIksqVK6fY2Firf+TIkTLGKDIyUhkZGRo3bpzL4+Pi4jRmzBg1a9ZMzz77rObNmydfX9/rug8AAKD0KrE1ORUrVnT53JvLlS1bVp9++unvzvH000/r6aefLurSAACADZTKNTkAAADXipADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABsiZADAABs6YYPOevXr1eNGjVUvnx5vfrqqyVdDgAAKCW8SrqAa3Hx4kV17txZL730kho3bqymTZuqWbNmSkhIKOnSAABACbuhz+R89dVX8vX1VZcuXVSjRg116dJFs2bNKumyAABAKXBDn8lJSUlRo0aNrPsJCQlXvWSVm5ur3Nxc635mZqYkKSsrq1hqc+aeK5Z5ATsoruPueuM4B35fcRzrl+Y0xvzh2Bs65KSlpSkkJMS6HxoaqtTU1CuOnTBhgkaPHp2vPTo6utjqA3BlQVNLugIA10NxHuunT59WUFDQ7465oUOO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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "input_string = \"HXX\"\n",
    "circuit = create_counter_circuit_three(input_string)\n",
    "result = QuantumUtil.measure_circuit(circuit)\n",
    "QuantumUtil.histogram_of_classical_states(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below all probabilities of intermediate states are shown."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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ODhY1XkATmWVnveEc6/2PKDMtiN33hOundrzgDLbjqt5Tzj3Uh8eJlV5eTkWL16M4uJiWWfEut1/8sI1aGC/HgIlqEKYw3U1mUxo1aoVli5ditjYWHTr1g07d+5EXFycQ3U6efIkHnvsMWRmZiI3NxeTJk1CXl4eGjRo4PBxsTNci51hIiIiIld5WmdYg59r7AwLhDhc1927d+PZZ59Fbm4uAGDWrFmoqKjAu+++61CdXn75ZVy7dg1/+ctfAACdO3fG7NmzkZiY6OBRyfTQDSIiIiJSJoHrMFfzErgO4FbH+deviooKu/vKyspCly5dLO/j4uKQlZXlcF1czQPsDBMRERGRA3x8fNCkSRMALQEEV/NqiYYNGyIyMhJBQUGWV2pqqt19FhQUIDQ01PI+LCwMly9fdrhOruYB/oCOiIiIiBzg5+eHc+fO4ebNmzVuJ4SARmM9xZqvr6/dbe/ezmw22yyriat5gJ1hIiIiInKQn5+fW39vFRERgRMnTljeFxUVISIiQlK+qKjI6Tyg0s7w7d8MVnf/ChEREZGnuN1fqY9zHsTExFg9aC0rK8tmJok9e/Zg3rx5mDZtGpKSkmzy2dnZVvlXXnlFWiWECuXn5wsAfPHFF1988cUXX4p55efny92FcrvKykrRtGlTsXHjRvHf//5XNG7cWBw5csRqm379+gkAon379jb5nJwcERISIk6ePCk+/fRT0ahRI1FWViapDqocGW7WrBny8/MREBAg+b4SdygpKUFkZCTy8/OdmiKFefnySq4788rOK7nuzCs7r+S6e0LeHYQQuH79Opo1ayZL+bVJp9Nhy5YtloduzJ8/32ZkeNCgQThw4ABGjBhhk+/QoQNef/11dO/eHYGBgfjoo48k38ahys6wVqtFixYt5K4GAgMDXfpgMS9fXsl1Z17ZeSXXnXll55Vcd0/IuyooKEi2smtb9+7dLfMM2zN58mRMnjy52vUzZszAjBkznC6fU6sRERERkWqxM0xEREREqsXOsAx8fX2xYMGCaufcY95z80quO/PKziu57swrO6/kuntCnjyfRoh6OE8HEREREZEDODJMRERERKrFzjARERERqRY7w0RERESkWuwMExEREZFqsTNMRERERKrFzjARERERqRY7w0RERESkWuwMExEREZFqsTMsI6PRiClTpqCioqLO83KWzby680qu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",
      "text/plain": [
       "<Figure size 900x850 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "QuantumUtil.show_all_probabilities(circuit, show_description=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Count till seven\n",
    "Below a function is defined to implement a counter circuit that is able to count till seven. The circuit has $10$ qubits. \n",
    "Depending on the corresponding characters in the input string, the first $7$ qubits are initialized with either a Pauli X, Hadamard or Identity operations. \n",
    "The three remaining qubits form a binary counter with qubit $7$ the most significant bit and qubit $9$ the least significant bit.\n",
    "\n",
    "The counter is implemented as follows. \n",
    "For each of the input qubits, a Toffoli operation is applied with three control qubits, followed by a Toffoli with two control qubits and a CNOT. \n",
    "The first Toffoli operation ensures that the most signifcan bit becomes $|1\\rangle$\n",
    "when the input qubit and the other bits are in state $|1\\rangle$.\n",
    "The second Toffolli operation ensures that the second bit becomes $|1\\rangle$\n",
    "when both the input qubit and the least significant bit are $|1\\rangle$. \n",
    "The CNOT operation ensures that the least signicant bit is flipped when the input qubit is in state $|1\\rangle$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "def create_counter_circuit_seven(input_string:str):\n",
    "    if len(input_string) != 7:\n",
    "        raise ValueError(\"Wrong length input_string\")\n",
    "    \n",
    "    n = 7 # input qubits\n",
    "    m = 3 # counter qubits\n",
    "    circuit = Circuit(n + m)\n",
    "\n",
    "    # Initialize input qubits\n",
    "    for q in range(n):\n",
    "        char = input_string[q]\n",
    "        if char == 'X':\n",
    "            circuit.pauli_x(q)\n",
    "        elif char == 'H':\n",
    "            circuit.hadamard(q)\n",
    "        else:\n",
    "            circuit.identity(q)\n",
    "\n",
    "    # Counter\n",
    "    for q in range(n):\n",
    "        circuit.generic_toffoli([q, n + 2, n + 1], n)\n",
    "        circuit.toffoli(q, n + 2, n + 1)\n",
    "        circuit.cnot(q, n + 2)\n",
    "\n",
    "    return circuit\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below a circuit is created with input string \"XXXXXXX\". With this input string, the result is $|1111111111\\rangle$. \n",
    "Thus, the number of ones in the first seven qubits is counted and the result is 111 (decimal 7).\n",
    "\n",
    "You can try other input strings and check the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAkEAAAHECAYAAAA+kf5bAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8pXeV/AAAACXBIWXMAAA9hAAAPYQGoP6dpAABG2ElEQVR4nO3deVhV1f7H8c9hHhQQFBAkxKEcSHGivFoOld0sJdObpTnk7WZ2M0szp9TKufJqNlhpatY109JCzaarZuZc6nWoboOzAgUCDoDCWb8/ety/TmBx6hxF9/v1POd5PGutvfZ3H0A+7L32OQ5jjBEAAIDN+FzoAgAAAC4EQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAA4IL74osvNGvWrAtdBmyGEIQ/ZcGCBXI4HGrQoMGFLsWj5s+fr8aNGys4OFgBAQG65ZZbLnRJuARkZWWpe/fuio6Olp+fn6KiorRq1Sqv7W/JkiXy8fGRw+GQw+HQ4sWLvbavP+vll1/W/ffff972d+utt1qvS6VKlc7bflGxEIIuEffee68cDodCQ0O1YcMGSdJnn30mX19f6wd9yZIlHt9vt27dNHHiRJ06dcrjc18oX331lfr166d+/fppw4YN+vLLLzV79uwLXRYuAQ899JD27dunRYsWafv27frss8907bXXem1/nTp10p49e7Rz507FxcXp5MmTXtvXn3XjjTdq4MCB521/c+bM0a5duzRnzpzz/rr07t1b8+bN89h8o0eP1hNPPOGx+ezE70IXAM94+umnlZCQoDFjxuihhx7Sxo0b1apVK3399dcaOnSoHA6HV85mBAQEqHr16h6f90Latm2boqOjNWjQoAtdCi4xW7du1SOPPKK2bduel/35+/urXr161r8rsq5du6pr167nbX+RkZGKjIzUjz/+eN72edaBAwe0f/9+j8138OBBORwOj81nJ5wJukSEh4erevXquvrqq/Xjjz/qzTfflI+Pj+rWrauIiAiFh4crICBAa9aska+vr8LDw61t77vvPjkcDvn7+2v79u2SpOuuu04Oh0Pt27dX9erVlZiYqPnz5yslJUURERGaMGFCqRrmzZun+vXrKzAwULVr19bUqVP168/nXb9+vf76178qPDxcERERuuaaa/TBBx+4jJk4caLL6fvPPvtMbdu2VUhIiJKSkrRnzx63X5+NGzfqpptuUnh4uIKCgtS0aVPNnTvXZcyWLVvk7++vnj176ujRo1YNPj4+WrBggdv7LO9+JWnTpk264YYbVKlSJUVERKhNmza644471KNHD7fGff/99woMDFRAQIAyMzMlSZMnT7aOY9myZdZc//73v61jfPrpp7V7927dcsstqly5sqpXr67Vq1e7NU6SDh06pL59+yo2NlYhISFq1KiRZsyYoeLiYmvMPffcI4fDoTvuuEP9+/dXbGysYmNj9fjjj5d6XY4cOaI+ffqoatWq1nz333+/EhMTXcYdO3ZMDz74oC677DIFBQWpfv36Gjt2rAoKClzGna29atWqCg0NVaNGjdSsWbM//Fd0UVGRxo4dqzp16iggIEAxMTHq06ePDhw44DIuLS1NDodD3377rfr372+9nmcDyh/Z7+jRo1WzZk0FBgYqKSlJ9913n2rWrKmdO3f+ofmGDh2qunXrKjg4WNHR0erXr59OnDjhMu7MmTN69NFHlZSUpKCgIF122WVq165dmZfDp0yZoiuuuELBwcGKi4tTu3btlJCQUGrOMWPGWK9HcnLyOWss78/I0qVL1apVK4WHhys0NFQtW7bU5s2b3X5N3LVu3Tq1a9dOVapUUVhYmJo3b66GDRvqtddeK3P87312+YEDB9SjRw/FxcUpMDBQNWvW1FNPPXXO8b83n9Pp1LRp09SwYUMFBQUpMTFRffv21eHDh13G5efn695771WNGjUUFBSk2rVrq02bNurQocNvzn/RMrhkzJo1y7Rp08YsWbLEXHbZZaagoMAYY0yfPn1Mnz59jDHGlJSUmPnz55tffulzcnLMzp07jSSzevVqY4wxP/74o2nRooVJSkoyn3zyibn++uuNJDN27Fjz4osvGn9/f5OdnW2MMWbu3LnG19fXVKtWzcyePdusX7/ejB8/3gQEBJihQ4da+/nwww+Nv7+/6d+/v1m9erVZv369GT58uPHx8TEvvPCCNe7EiRNmz549Ji4uztx8882mRo0aZu7cuebjjz82AwcONHv37nXrdfn444+Nv7+/uemmm8z7779v1q5dax555BHj6+trhg8fbo1zOp3mm2++MXPmzDGSzM6dO83OnTvN7t27zZkzZ9zapzv7XbVqlQkICDC33nqrWblypdmwYYMZOHCgkWTatGnj9rg1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hboOB886c+aMGTdunGnevLnZvXu3dV36+eefN5Jc1iecOnXKREVFma5du5r169ebJUuWmLp16xpJ5vXXXzclJSUmKyvLtGjRwtx///0mPz/fzJ0718TFxZmMjAxjzM/rh9544w1TWFhoJk6caCSZ6Oho8+qrr5oNGzaYSZMmmaCgIPPYY49Z+503b55xOBzmgQceMGvWrDGfffaZefzxx018fLxJSkqyxh0+fNjs3LnTxMXFmfHjx1vXuXNzc//Qa/Phhx8aPz8/k5aWZlauXGk+++wzM3z4cOPv7++ycPtcC6O//vrrUut6PLnfTz75xPj7+5vbb7/dfPLJJ+bTTz81AwcOLLWAurzjjDGmfv365pprrjGffvqp+eCDD0yLFi2MJDNx4kRr7UFWVlaZ6xOysrJc5irvuN27d5vQ0FBzww03mBUrVphNmzaZmTNnmqZNmxp/f3/z7bffGmOMOXbsmLWG4ey6g5ycHKvt7Nf5yJEjJj4+3qSkpJglS5aYjRs3mqefftpERkaali1bWl+TjIwMExsba5o1a2beeecds3nzZvPaa6+Ztm3bGofD4bLOTZJJTEw0L774ovn888/N8uXLTf369U2jRo3c/voWFxebtm3bmsjISDNjxgxrQXHjxo1NtWrVXNZknWth9C/XXZTX2QXZ1apVMy+//LLZtGmTef311039+vVNtWrVrDV4xhiTnZ1t7euXP0+7du2ybpxwOp2mevXq5q677jKbNm0yH3/8sbn33nuNr6+viYuLM//73/+s+fr06WN8fX3NkCFDzPvvv282btxo7rnnHuPr6+uy5mvs2LFGkunXr5957733zObNm82oUaOMJPPOO+9Y4woLC82uXbvMzp07zfjx401cXJxV7w8//GCNK+/3/rBhw0xSUpJZsWKF2bhxo5k+fbqJi4szksy8efPM8ePHrbHfffed2blzZ6mf9++++87tr8nZdXhXXnmlmTt3rvW9EBcXZzp37lxq/EMPPWRq1KhhPvroI7Nu3Tozbtw406BBA/Pkk08aY4zZtWuX8fX1NU899ZTZunWreeedd8z1119vHA6HSUtLM4cOHXKZb/r06aZSpUrm3XffNRs3bjT/+te/TIsWLczf//5362vcvn17Exsba15++WWzefNm895775mePXsaf39/88QTT1hztWnTxoSEhJgnnnjCfPLJ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HR2toKAgtWzZUt999507L9fvOnPmjO6//35FR0ercuXKSk1NVVJSks6+D22fPn2UmpqqgwcPKjY2VrGxsUpMTNSPP/5ozbF582ZdddVVCg0NVZUqVfTAAw9Y22/btk01atTQW2+9pUGDBllzjB492qWOjz/+WFdffbUqV66sevXqadasWS79n376qZo1a6aQkBAlJiaqSZMmmj59ukdfC+BiQwgCbObDDz9UgwYN1KBBA5f2pUuXqn379uWeJzIyUuPHj9e+ffu0adMmzZs3T7t27bL6H3vsMSUlJengwYNav369Lr/8ch07dszqX7Nmjd544w2tXbtWBw8e1D//+U/l5OTo9OnT1pjrr79eZ86c0ejRo8u8VNWtWzft3btXq1ev1g8//KA6depoz549ysvLkyT5+PioXbt2+uijj/Tjjz+qS5cuGj58eLmPsTz+/e9/a9u2bdq+fbu+++47de3aVVlZWVaImTlzplasWKG4uDht375d27dv17Zt21StWjVrjkqVKmnIkCH65ptvtGfPHm3btk0rVqyQJDVp0kRffvmlOnfurCeffNKa45chaN26dUpLS9ODDz6ogwcP6qWXXtLo0aP16quvWmP69OmjwYMHKysrSwsXLlRAQIBOnDjh0dcCuNhUjHPdAM6brKwsxcbG/ul5SkpK9PLLL+vhhx9WUFCQTp06pZ07dyo5OVmSVFhYqNTUVIWFhSksLEzz58+3wsnZ/ri4ONWoUUOBgYG655579Le//U3h4eEu+/H19ZWPT+m/17788kutW7dOR44cUUREhCRpxowZysrKsgLGmTNntH//fr344os6duyYqlatWuqS359VWFiopKQkxcTEyNfXV8OGDdN9991n1RwSEqJq1arJ19f3nK+7MUaLFy/WY489JofDoTNnzmjnzp265ZZbJEnR0dEKDg5WeHh4mXM8/fTTGjRokHr06CFJatu2rR5//HE988wz+vvf/27V2aRJE1WqVEktW7bUZ599ppKSEo++FsDFhjNBgM1UrVr1T69POXz4sP76178qNTVVK1eu1OLFi1W3bl2XBdSPP/64Zs+ercqVK6tGjRq6+uqrtWzZMqv/hhtuUIMGDRQVFaXo6Gg1aNBAw4cP16lTp8pVw/fff68aNWpYAUj6OTAtXrxY8fHxkqQRI0YoPT1dzzzzjD799FMNHjzY44u8e/furcLCQoWFhSk2NlZXXnmlpkyZIqfTWa7tCwoKdMMNN6hatWpaunSpli9frtTUVLfq/O677/TSSy9Zl8piY2M1atQoHT582Bozc+ZM3XjjjapSpYqSkpLUqVMn7dy50+3jBS4lnAkCbOa6667TP//5T3311VeqX7++1V5UVCQ/Pz/5+vr+7hwbN25UnTp1NHbsWKstJCTEZcycOXP03nvvqVq1asrJydGWLVvUpUsX3XDDDYqJidHnn3+ulJQUzZw5U9nZ2crKylLPnj31wgsvaOjQob9bQ+3atXXw4EHl5ua6BKEjR46oevXqcjgc+s9//qPx48fruuuukyRlZmb+7rzueu+999S3b18tWrRI2dnZOnz4sDp16qQmTZpYa6B8fX118uTJMrffs2ePCgoK9OKLL1ptkZGRpcb91hw1atTQ3XffrbvuusulvXLlyta/Fy9erP379+vEiRPKy8vTzJkzdffdd2v37t1uHzNwqeBMEGAzderU0b333qtu3bpp48aNysvLU3p6uho2bKiPPvrIGldSUqLi4mKXf59d53LZZZfphx9+0Pbt25WVlaXHHntMK1eutPqlnxf7du/eXd98840iIiJUWFgoHx8f646zH374QY8++qjeeustBQUFKTAwUIWFhQoICLDmcDqdKi4ultPpdPm3JDVt2lTXXHONevXqpb179+rHH3/U5MmTVa9ePWtx9WWXXab3339feXl5+uyzz9SnTx9Jcqnz7LzGmFLHWR7ffPON+vfvr48//liVKlWSj4+PTp8+7XIcMTExKiws1Jo1a5Sdna3Zs2erVatWysvLU1xcnE6dOqVPPvlEOTk5mjFjhmbNmlWqhjp16uj9999Xbm6uvvjiC91zzz2aPHmyJOm+++7Tyy+/rL1796py5co6duyYZs+erUGDBlnbv/nmm7rvvvuUl5ensLAwnTp1yqVGwJYMANspLi42Y8aMMfHx8SYkJMS0bNnSvPvuu1b/5s2bja+vr5Hk8ujdu7c1ZvTo0SYiIsJER0eb7t27m/79+xtJZu7cucYYY+68805z/fXXmxo1apiAgABzxRVXmIULF1rbr1ixwjRu3Ng0btzYBAUFmapVq5p7773XFBUVGWOMyc/PN6GhoaVqCAwMNEeOHDHGGJOXl2f69+9vYmNjTXh4uLnlllvM5s2brX189dVXplmzZiYkJMRceeWVZubMmSYkJMQkJiYaY4w5fPiwCQoKKrWPa6+9ttyv5QsvvGCuuuoqU69ePRMQEGCqV69uRo4caZxOp8u4BQsWmLi4OBMcHGxatWpl5s+fb/XNnDnTREdHmypVqpiOHTuakSNHGklm7Nix1pjc3FzTsWNHExgYaOLj4819991nDhw4YPXPmzfPNGjQwAQFBZnExETTr18/s337dqu/bt265rrrrjORkZFWDdu2bSv3cQKXIocxbvzJAwAAcIngchgAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALAlQhAAALCl/wOvLI+ntMT1pgAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "input_string = \"XXXXXXX\"\n",
    "circuit = create_counter_circuit_seven(input_string)\n",
    "result = QuantumUtil.measure_circuit(circuit)\n",
    "QuantumUtil.histogram_of_classical_states(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below, the gates for this circuit are shown. Control qubits for Toffoli and CNOT operations are indicated with an asterisk."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "X.........\n",
      ".X........\n",
      "..X.......\n",
      "...X......\n",
      "....X.....\n",
      ".....X....\n",
      "......X...\n",
      "*......X**\n",
      "*.......X*\n",
      "*........X\n",
      ".*.....X**\n",
      ".*......X*\n",
      ".*.......X\n",
      "..*....X**\n",
      "..*.....X*\n",
      "..*......X\n",
      "...*...X**\n",
      "...*....X*\n",
      "...*.....X\n",
      "....*..X**\n",
      "....*...X*\n",
      "....*....X\n",
      ".....*.X**\n",
      ".....*..X*\n",
      ".....*...X\n",
      "......*X**\n",
      "......*.X*\n",
      "......*..X\n"
     ]
    }
   ],
   "source": [
    "circuit.print_gates()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Application in Grover's Algorithm\n",
    "In the notebook below, the counter is applied in a Grover's algorithm to search for binary strings of length $n$ having exactly $k$ ones ($0 \\leq k \\leq n$). \n",
    "\n",
    "https://github.com/nicokuijpers/QuantumSim/blob/main/QuantumSimCounterGroverSearch.ipynb"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}