community/algorithms/shor_algorithm.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"../../images/qiskit-heading.gif\" alt=\"Note: In order for images to show up in this jupyter notebook you need to select File => Trusted Notebook\" width=\"500 px\" align=\"left\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## _*Shor's Algorithm for Integer Factorization*_ \n",
    "\n",
    "The latest version of this tutorial notebook is available on https://github.com/qiskit/qiskit-tutorial.\n",
    "\n",
    "In this tutorial, we first introduce the problem of [integer factorization](#factorization) and describe how [Shor's algorithm](#shorsalgorithm) solves it in detail. We then [implement](#implementation) a version of it in Qiskit.\n",
    "\n",
    "### Contributors\n",
    "Anna Phan\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Integer Factorization <a id='factorization'></a>\n",
    "\n",
    "Integer factorization is the decomposition of an composite integer into a product of smaller integers, for example, the integer $100$ can be factored into $10 \\times 10$. If these factors are restricted to prime numbers, the process is called prime factorization, for example, the prime factorization of $100$ is $2 \\times 2 \\times 5 \\times 5$. \n",
    "\n",
    "When the integers are very large, no efficient classical integer factorization algorithm is known. The hardest factorization problems are semiprime numbers, the product of two prime numbers. In [2009](https://link.springer.com/chapter/10.1007/978-3-642-14623-7_18), a team of researchers factored a 232 decimal digit semiprime number (768 bits), spending the computational equivalent of more than two thousand years on a single core 2.2 GHz AMD Opteron processor with 2 GB RAM:\n",
    "```\n",
    "RSA-768  = 12301866845301177551304949583849627207728535695953347921973224521517264005 \n",
    "           07263657518745202199786469389956474942774063845925192557326303453731548268 \n",
    "           50791702612214291346167042921431160222124047927473779408066535141959745985 \n",
    "           6902143413 \n",
    "           \n",
    "         = 33478071698956898786044169848212690817704794983713768568912431388982883793 \n",
    "           878002287614711652531743087737814467999489 \n",
    "         × 36746043666799590428244633799627952632279158164343087642676032283815739666 \n",
    "           511279233373417143396810270092798736308917 \n",
    "```\n",
    "The presumed difficulty of this semiprime factorization problem underlines many encryption algorithms, such as [RSA](https://www.google.com/patents/US4405829), which is used in online credit card transactions, amongst other applications.\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Shor's Algorithm <a id='shorsalgorithm'></a>\n",
    "\n",
    "Shor's algorithm, named after mathematician Peter Shor, is a polynomial time quantum algorithm for integer factorization formulated in [1994](http://epubs.siam.org/doi/10.1137/S0097539795293172). It is arguably the most dramatic example of how the paradigm of quantum computing changed our perception of which computational problems should be considered tractable, motivating the study of new quantum algorithms and efforts to design and construct quantum computers. It also has expedited research into new cryptosystems not based on integer factorization. \n",
    "\n",
    "Shor's algorithm has been experimentally realised by multiple teams for specific composite integers. The composite $15$ was first factored into $3 \\times 5$ in [2001](https://www.nature.com/nature/journal/v414/n6866/full/414883a.html) using seven NMR qubits, and has since been implemented using four photon qubits in 2007 by [two](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.99.250504) [teams](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.99.250505), three solid state qubits in [2012](https://www.nature.com/nphys/journal/v8/n10/full/nphys2385.html) and five trapped ion qubits in [2016](http://science.sciencemag.org/content/351/6277/1068). The composite $21$ has also been factored into $3 \\times 7$ in [2012](http://www.nature.com/nphoton/journal/v6/n11/full/nphoton.2012.259.html) using a photon qubit and qutrit (a three level system). Note that these experimental demonstrations rely on significant optimisations of Shor's algorithm based on apriori knowledge of the expected results. In general, [$2 + \\frac{3}{2}\\log_2N$](https://link-springer-com.virtual.anu.edu.au/chapter/10.1007/3-540-49208-9_15) qubits are needed to factor the composite integer $N$, meaning at least $1,154$ qubits would be needed to factor $RSA-768$ above.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:22.738849Z",
     "start_time": "2018-09-26T17:12:22.719241Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "        <iframe\n",
       "            width=\"560\"\n",
       "            height=\"315\"\n",
       "            src=\"https://www.youtube.com/embed/hOlOY7NyMfs?start=75&end=126\"\n",
       "            frameborder=\"0\"\n",
       "            allowfullscreen\n",
       "        ></iframe>\n",
       "        "
      ],
      "text/plain": [
       "<IPython.lib.display.IFrame at 0x1101a0b70>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.display import IFrame\n",
    "IFrame(\"https://www.youtube.com/embed/hOlOY7NyMfs?start=75&end=126\",560,315)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As Peter Shor describes in the video above from [PhysicsWorld](http://physicsworld.com/cws/article/multimedia/2015/sep/30/what-is-shors-factoring-algorithm), Shor’s algorithm is composed of three parts. The first part turns the factoring problem into a period finding problem using number theory, which can be computed on a classical computer. The second part  finds the period using the quantum Fourier transform and is responsible for the quantum speedup of the algorithm. The third part uses the period found to calculate the factors.\n",
    "\n",
    "The following sections go through the algorithm in detail, for those who just want the steps, without the lengthy explanation, refer to the [blue](#stepsone) [boxes](#stepstwo) before jumping down to the [implemention](#implemention). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From Factorization to Period Finding\n",
    "\n",
    "The number theory that underlines Shor's algorithm relates to periodic modulo sequences. Let's have a look at an example of such a sequence. Consider the sequence of the powers of two: \n",
    "$$1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, ...$$\n",
    "Now let's look at the same sequence 'modulo 15', that is, the remainder after fifteen divides each of these powers of two:\n",
    "$$1, 2, 4, 8, 1, 2, 4, 8, 1, 2, 4, ...$$\n",
    "This is a modulo sequence that repeats every four numbers, that is, a periodic modulo sequence with a period of four.\n",
    "\n",
    "Reduction of factorization of $N$ to the problem of finding the period of an integer $x$ less than $N$ and greater than $1$ depends on the following result from number theory:\n",
    "\n",
    "> The function $\\mathcal{F}(a) = x^a \\bmod N$ is a periodic function, where $x$ is an integer coprime to $N$ and $a \\ge 0$.\n",
    "\n",
    "Note that two numbers are coprime, if the only positive integer that divides both of them is 1. This is equivalent to their greatest common divisor being 1. For example, 8 and 15 are coprime, as they don't share any common factors (other than 1). However, 9 and 15 are not coprime, since they are both divisible by 3 (and 1). \n",
    "\n",
    "> Since $\\mathcal{F}(a)$ is a periodic function, it has some period $r$. Knowing that $x^0 \\bmod N = 1$, this means that $x^r \\bmod N = 1$ since the function is periodic, and thus $r$ is just the first nonzero power where $x^r = 1 (\\bmod N)$.\n",
    "\n",
    "Given this information and through the following algebraic manipulation: \n",
    "$$ x^r \\equiv 1 \\bmod N $$\n",
    "$$ x^r = (x^{r/2})^2 \\equiv 1 \\bmod N $$\n",
    "$$ (x^{r/2})^2 - 1 \\equiv 0 \\bmod N $$\n",
    "and if $r$ is an even number:\n",
    "$$ (x^{r/2} + 1)(x^{r/2} - 1) \\equiv 0 \\bmod N $$\n",
    "\n",
    "From this, the product $(x^{r/2} + 1)(x^{r/2} - 1)$ is an integer multiple of $N$, the number to be factored. Thus, so long as $(x^{r/2} + 1)$ or $(x^{r/2} - 1)$ is not a multiple of $N$, then at least one of $(x^{r/2} + 1)$ or $(x^{r/2} - 1)$ must have a nontrivial factor in common with $N$. \n",
    "\n",
    "So computing $\\text{gcd}(x^{r/2} - 1, N)$ and $\\text{gcd}(x^{r/2} + 1, N)$ will obtain a factor of $N$, where $\\text{gcd}$ is the greatest common denominator function, which can be calculated by the polynomial time [Euclidean algorithm](https://en.wikipedia.org/wiki/Euclidean_algorithm). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Classical Steps to Shor's Algorithm\n",
    "\n",
    "Let's assume for a moment that a period finding machine exists that takes as input coprime integers $x, N$ and outputs the period of $x \\bmod N$, implemented by as a brute force search below. Let's show how to use the machine to find all prime factors of $N$ using the number theory described above. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:26.676176Z",
     "start_time": "2018-09-26T17:12:26.670043Z"
    }
   },
   "outputs": [],
   "source": [
    "# Brute force period finding algorithm\n",
    "def find_period_classical(x, N):\n",
    "    n = 1\n",
    "    t = x\n",
    "    while t != 1:\n",
    "        t *= x\n",
    "        t %= N\n",
    "        n += 1\n",
    "    return n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For simplicity, assume that $N$ has only two distinct prime factors: $N = pq$.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\"> <a id='stepsone'></a>\n",
    "<ol>\n",
    "<li>Pick a random integer $x$ between $1$ and $N$ and compute the greatest common divisor $\\text{gcd}(x,N)$ using Euclid's algorithm.</li>\n",
    "<li>If $x$ and $N$ have some common prime factors, $\\text{gcd}(x,N)$ will equal $p$ or $q$. Otherwise $\\text{gcd}(x,N) = 1$, meaning $x$ and $N$ are coprime. </li>\n",
    "<li>Let $r$ be the period of $x \\bmod N$ computed by the period finding machine. Repeat the above steps with different random choices of $x$ until $r$ is even.</li>\n",
    "<li>Now $p$ and $q$ can be found by computing $\\text{gcd}(x^{r/2} \\pm 1, N)$ as long as $x^{r/2} \\neq \\pm 1$.</li>\n",
    "</ol>\n",
    "</div>\n",
    "\n",
    "As an example, consider $N = 15$. Let's look at all values of $1 < x < 15$ where $x$ is coprime with $15$:\n",
    "\n",
    "|  $x$  |         $x^a \\bmod 15$       | Period $r$ |$\\text{gcd}(x^{r/2}-1,15)$|$\\text{gcd}(x^{r/2}+1,15)$ | \n",
    "|:-----:|:----------------------------:|:----------:|:------------------------:|:-------------------------:|\n",
    "|   2   | 1,2,4,8,1,2,4,8,1,2,4...     |      4     |             3            |             5             |\n",
    "|   4   | 1,4,1,4,1,4,1,4,1,4,1...     |      2     |             3            |             5             |\n",
    "|   7   | 1,7,4,13,1,7,4,13,1,7,4...   |      4     |             3            |             5             |\n",
    "|   8   | 1,8,4,2,1,8,4,2,1,8,4...     |      4     |             3            |             5             |\n",
    "|   11  | 1,11,1,11,1,11,1,11,1,11,1...|      2     |             5            |             3             |\n",
    "|   13  | 1,13,4,7,1,13,4,7,1,13,4,... |      4     |             3            |             5             |\n",
    "|   14  | 1,14,1,14,1,14,1,14,1,14,1,,,|      2     |             1            |             15            |\n",
    "\n",
    "As can be seen, any value of $x$ except $14$ will return the factors of $15$, that is, $3$ and $5$. $14$ is an example of the special case where $(x^{r/2} + 1)$ or $(x^{r/2} - 1)$ is a multiple of $N$ and thus another $x$ needs to be tried. \n",
    "\n",
    "In general, it can be shown that this special case occurs infrequently, so on average only two calls to the period finding machine are sufficient to factor $N$. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "For a more interesting example, first let's find larger number N, that is semiprime that is relatively small. Using the [Sieve of Eratosthenes](https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes) [Python implementation](http://archive.oreilly.com/pub/a/python/excerpt/pythonckbk_chap1/index1.html?page=last), let's generate a list of all the prime numbers less than a thousand, randomly select two, and muliply them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:28.800866Z",
     "start_time": "2018-09-26T17:12:28.789601Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "semiprime N = 16241\n"
     ]
    }
   ],
   "source": [
    "import random, itertools\n",
    "\n",
    "# Sieve of Eratosthenes algorithm\n",
    "def sieve( ):\n",
    "    D = {  }\n",
    "    yield 2\n",
    "    for q in itertools.islice(itertools.count(3), 0, None, 2):\n",
    "        p = D.pop(q, None)\n",
    "        if p is None:\n",
    "            D[q*q] = q\n",
    "            yield q\n",
    "        else:\n",
    "            x = p + q\n",
    "            while x in D or not (x&1):\n",
    "                x += p\n",
    "            D[x] = p\n",
    "\n",
    "# Creates a list of prime numbers up to the given argument\n",
    "def get_primes_sieve(n):\n",
    "    return list(itertools.takewhile(lambda p: p<n, sieve()))\n",
    "\n",
    "def get_semiprime(n):\n",
    "    primes = get_primes_sieve(n)\n",
    "    l = len(primes)\n",
    "    p = primes[random.randrange(l)]\n",
    "    q = primes[random.randrange(l)]\n",
    "    return p*q\n",
    "\n",
    "N = get_semiprime(1000)\n",
    "\n",
    "print(\"semiprime N =\",N)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now implement the [above steps](#stepsone) of Shor's Algorithm:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:29.140212Z",
     "start_time": "2018-09-26T17:12:29.130741Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "semiprime N = 16241, coprime x = 7076, period r = 1998, prime factors = 109 and 149\n"
     ]
    }
   ],
   "source": [
    "import math\n",
    "\n",
    "def shors_algorithm_classical(N):\n",
    "    x = random.randint(0,N) # step one\n",
    "    if(math.gcd(x,N) != 1): # step two\n",
    "        return x,0,math.gcd(x,N),N/math.gcd(x,N)\n",
    "    r = find_period_classical(x,N) # step three\n",
    "    while(r % 2 != 0):\n",
    "        r = find_period_classical(x,N)\n",
    "    p = math.gcd(x**int(r/2)+1,N) # step four, ignoring the case where (x^(r/2) +/- 1) is a multiple of N\n",
    "    q = math.gcd(x**int(r/2)-1,N)\n",
    "    return x,r,p,q\n",
    "\n",
    "x,r,p,q = shors_algorithm_classical(N)\n",
    "print(\"semiprime N = \",N,\", coprime x = \",x,\", period r = \",r,\", prime factors = \",p,\" and \",q,sep=\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quantum Period Finding <a id='quantumperiodfinding'></a>\n",
    "\n",
    "Let's first describe the quantum period finding algorithm, and then go through a few of the steps in detail, before going through an example. This algorithm takes two coprime integers, $x$ and $N$, and outputs $r$, the period of $\\mathcal{F}(a) = x^a\\bmod N$.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\"><a id='stepstwo'></a>\n",
    "<ol>\n",
    "<li> Choose $T = 2^t$ such that $N^2 \\leq T \\le 2N^2$. Initialise two registers of qubits, first an argument register with $t$ qubits and second a function register with $n = log_2 N$ qubits. These registers start in the initial state:\n",
    "$$\\vert\\psi_0\\rangle = \\vert 0 \\rangle \\vert 0 \\rangle$$ </li>\n",
    "<li> Apply a Hadamard gate on each of the qubits in the argument register to yield an equally weighted superposition of all integers from $0$ to $T$:\n",
    "$$\\vert\\psi_1\\rangle = \\frac{1}{\\sqrt{T}}\\sum_{a=0}^{T-1}\\vert a \\rangle \\vert 0 \\rangle$$ </li>\n",
    "<li> Implement the modular exponentiation function $x^a \\bmod N$ on the function register, giving the state:\n",
    "$$\\vert\\psi_2\\rangle = \\frac{1}{\\sqrt{T}}\\sum_{a=0}^{T-1}\\vert a \\rangle \\vert x^a \\bmod N \\rangle$$\n",
    "This $\\vert\\psi_2\\rangle$ is highly entangled and exhibits quantum parallism, i.e. the function entangled in parallel all the 0 to $T$ input values with the corresponding values of $x^a \\bmod N$, even though the function was only executed once. </li>\n",
    "<li> Perform a quantum Fourier transform on the argument register, resulting in the state:\n",
    "$$\\vert\\psi_3\\rangle = \\frac{1}{T}\\sum_{a=0}^{T-1}\\sum_{z=0}^{T-1}e^{(2\\pi i)(az/T)}\\vert z \\rangle \\vert x^a \\bmod N \\rangle$$\n",
    "where due to the interference, only the terms $\\vert z \\rangle$ with\n",
    "$$z = qT/r $$\n",
    "have significant amplitude where $q$ is a random integer ranging from $0$ to $r-1$ and $r$ is the period of $\\mathcal{F}(a) = x^a\\bmod N$. </li>\n",
    "<li> Measure the argument register to obtain classical result $z$. With reasonable probability, the continued fraction approximation of $T / z$ will be an integer multiple of the period $r$. Euclid's algorithm can then be used to find $r$.</li>\n",
    "</ol>\n",
    "</div>\n",
    "\n",
    "Note how quantum parallelism and constructive interference have been used to detect and measure periodicity of the modular exponentiation function.  The fact that interference makes it easier to measure periodicity should not come as a big surprise. After all, physicists routinely use scattering of electromagnetic waves and interference measurements to determine periodicity of physical objects such as crystal lattices. Likewise, Shor's algorithm exploits interference to measure periodicity of arithmetic objects, a computational interferometer of sorts. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "####  Modular Exponentiation\n",
    "\n",
    "The modular exponentiation, step 3 above, that is the evaluation of $x^a \\bmod N$ for $2^t$ values of $a$ in parallel, is the most demanding part of the algorithm. This can be performed using the following identity for the binary representation of any integer: $x = x_{t-1}2^{t-1} + ... x_12^1+x_02^0$, where $x_t$ are the binary digits of $x$. From this, it follows that:\n",
    "\n",
    "\\begin{aligned}\n",
    "x^a \\bmod N & = x^{2^{(t-1)}a_{t-1}} ... x^{2a_1}x^{a_0} \\bmod N \\\\\n",
    "& = x^{2^{(t-1)}a_{t-1}} ... [x^{2a_1}[x^{2a_0} \\bmod N] \\bmod N] ... \\bmod N \\\\\n",
    "\\end{aligned}\n",
    "\n",
    "This means that 1 is first multiplied by $x^1 \\bmod N$ if and only if $a_0 = 1$, then the result is multiplied by $x^2 \\bmod N$ if and only if $a_1 = 1$ and so forth, until finally the result is multiplied by $x^{2^{(s-1)}}\\bmod N$ if and only if $a_{t-1} = 1$. \n",
    "\n",
    "Therefore, the modular exponentiation consists of $t$ serial multiplications modulo $N$, each of them controlled by the qubit $a_t$. The values $x,x^2,...,x^{2^{(t-1)}} \\bmod N$ can be found efficiently on a classical computer by repeated squaring."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Quantum Fourier Transform\n",
    "\n",
    "The Fourier transform occurs in many different versions throughout classical computing, in areas ranging from signal processing to data compression to complexity theory. The quantum Fourier transform (QFT), step 4 above, is the quantum implementation of the discrete Fourier transform over the amplitudes of a wavefunction. \n",
    "\n",
    "The classical discrete Fourier transform acts on a vector $(x_0, ..., x_{N-1})$ and maps it to the vector $(y_0, ..., y_{N-1})$ according to the formula\n",
    "$$y_k = \\frac{1}{\\sqrt{N}}\\sum_{j=0}^{N-1}x_j\\omega_N^{jk}$$\n",
    "where $\\omega_N^{jk} = e^{2\\pi i \\frac{jk}{N}}$.\n",
    "\n",
    "Similarly, the quantum Fourier transform acts on a quantum state $\\sum_{i=0}^{N-1} x_i \\vert i \\rangle$ and maps it to the quantum state $\\sum_{i=0}^{N-1} y_i \\vert i \\rangle$ according to the formula\n",
    "$$y_k = \\frac{1}{\\sqrt{N}}\\sum_{j=0}^{N-1}x_j\\omega_N^{jk}$$\n",
    "with $\\omega_N^{jk}$ defined as above. Note that only the amplitudes of the state were affected by this transformation.\n",
    "\n",
    "This can also be expressed as the map:\n",
    "$$\\vert x \\rangle \\mapsto \\frac{1}{\\sqrt{N}}\\sum_{y=0}^{N-1}\\omega_N^{xy} \\vert y \\rangle$$\n",
    "\n",
    "Or the unitary matrix:\n",
    "$$ U_{QFT} = \\frac{1}{\\sqrt{N}} \\sum_{x=0}^{N-1} \\sum_{y=0}^{N-1} \\omega_N^{xy} \\vert y \\rangle \\langle x \\vert$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As an example, we've actually already seen the quantum Fourier transform for when $N = 2$, it is the Hadamard operator ($H$):\n",
    "$$H = \\frac{1}{\\sqrt{2}}\\begin{bmatrix} 1 & 1 \\\\ 1 & -1 \\end{bmatrix}$$\n",
    "Suppose we have the single qubit state $\\alpha \\vert 0 \\rangle + \\beta \\vert 1 \\rangle$, if we apply the $H$ operator to this state, we obtain the new state:\n",
    "$$\\frac{1}{\\sqrt{2}}(\\alpha + \\beta) \\vert 0 \\rangle + \\frac{1}{\\sqrt{2}}(\\alpha - \\beta)  \\vert 1 \\rangle \n",
    "\\equiv \\tilde{\\alpha}\\vert 0 \\rangle + \\tilde{\\beta}\\vert 1 \\rangle$$\n",
    "Notice how the Hadamard gate performs the discrete Fourier transform for $N = 2$ on the amplitudes of the state. \n",
    "\n",
    "So what does the quantum Fourier transform look like for larger N? Let's derive a circuit for $N=2^n$, $QFT_N$ acting on the state $\\vert x \\rangle = \\vert x_1...x_n \\rangle$ where $x_1$ is the most significant bit.\n",
    "\\begin{aligned}\n",
    "QFT_N\\vert x \\rangle & = \\frac{1}{\\sqrt{N}} \\sum_{y=0}^{N-1}\\omega_N^{xy} \\vert y \\rangle \\\\\n",
    "& = \\frac{1}{\\sqrt{N}} \\sum_{y=0}^{N-1} e^{2 \\pi i xy / 2^n} \\vert y \\rangle \\:\\text{since}\\: \\omega_N^{xy} = e^{2\\pi i \\frac{xy}{N}} \\:\\text{and}\\: N = 2^n\\\\\n",
    "& = \\frac{1}{\\sqrt{N}} \\sum_{y=0}^{N-1} e^{2 \\pi i \\left(\\sum_{k=1}^n y_k/2^k\\right) x} \\vert y_1 ... y_n \\rangle \\:\\text{rewriting in fractional binary notation}\\: y = y_1...y_k, y/2^n = \\sum_{k=1}^n y_k/2^k \\\\\n",
    "& = \\frac{1}{\\sqrt{N}} \\sum_{y=0}^{N-1} \\prod_{k=0}^n e^{2 \\pi i x y_k/2^k } \\vert y_1 ... y_n \\rangle \\:\\text{after expanding the exponential of a sum to a product of exponentials} \\\\\n",
    "& = \\frac{1}{\\sqrt{N}} \\bigotimes_{k=1}^n  \\left(\\vert0\\rangle + e^{2 \\pi i x /2^k } \\vert1\\rangle \\right) \\:\\text{after rearranging the sum and products, and expanding} \\\\\n",
    "& = \\frac{1}{\\sqrt{N}} \\left(\\vert0\\rangle + e^{2 \\pi i[0.x_n]} \\vert1\\rangle\\right) \\otimes...\\otimes  \\left(\\vert0\\rangle + e^{2 \\pi i[0.x_1.x_2...x_{n-1}.x_n]} \\vert1\\rangle\\right) \\:\\text{as}\\: e^{2 \\pi i x/2^k} = e^{2 \\pi i[0.x_k...x_n]} \n",
    "\\end{aligned}\n",
    "\n",
    "This is a very useful form of the QFT for $N=2^n$ as only the last qubit depends on the the\n",
    "values of all the other input qubits and each further bit depends less and less on the input qubits. Furthermore, note that $e^{2 \\pi i.0.x_n}$ is either $+1$ or $-1$, which resembles the Hadamard transform.\n",
    "\n",
    "Before we create the circuit code for general $N=2^n$, let's look at $N=8,n=3$:\n",
    "$$QFT_8\\vert x_1x_2x_3\\rangle = \\frac{1}{\\sqrt{8}} \\left(\\vert0\\rangle + e^{2 \\pi i[0.x_3]} \\vert1\\rangle\\right) \\otimes \\left(\\vert0\\rangle + e^{2 \\pi i[0.x_2.x_3]} \\vert1\\rangle\\right) \\otimes  \\left(\\vert0\\rangle + e^{2 \\pi i[0.x_1.x_2.x_3]} \\vert1\\rangle\\right) $$\n",
    "\n",
    "The steps to creating the circuit for $\\vert y_1y_2x_3\\rangle = QFT_8\\vert x_1x_2x_3\\rangle$, remembering the [controlled phase rotation gate](../tools/quantum_gates_and_linear_algebra.ipynb\n",
    ") $CU_1$, would be:\n",
    "1. Apply a Hadamard to $\\vert x_3 \\rangle$, giving the state $\\frac{1}{\\sqrt{2}}\\left(\\vert0\\rangle + e^{2 \\pi i.0.x_3} \\vert1\\rangle\\right) = \\frac{1}{\\sqrt{2}}\\left(\\vert0\\rangle + (-1)^{x_3} \\vert1\\rangle\\right)$\n",
    "2. Apply a Hadamard to $\\vert x_2 \\rangle$, then depending on $k_3$ (before the Hadamard gate) a $CU_1(\\frac{\\pi}{2})$, giving the state $\\frac{1}{\\sqrt{2}}\\left(\\vert0\\rangle + e^{2 \\pi i[0.x_2.x_3]} \\vert1\\rangle\\right)$.\n",
    "3. Apply a Hadamard to $\\vert x_1 \\rangle$, then $CU_1(\\frac{\\pi}{2})$ depending on $k_2$, and $CU_1(\\frac{\\pi}{4})$ depending on $k_3$.\n",
    "4. Measure the bits in reverse order, that is $y_3 = x_1, y_2 = x_2, y_1 = y_3$.\n",
    "\n",
    "In Qiskit, this is:\n",
    "```\n",
    "q3 = QuantumRegister(3, 'q3')\n",
    "c3 = ClassicalRegister(3, 'c3')\n",
    "\n",
    "qft3 = QuantumCircuit(q3, c3)\n",
    "qft3.h(q[0])\n",
    "qft3.cu1(math.pi/2.0, q3[1], q3[0])\n",
    "qft3.h(q[1])\n",
    "qft3.cu1(math.pi/4.0, q3[2], q3[0])\n",
    "qft3.cu1(math.pi/2.0, q3[2], q3[1])\n",
    "qft3.h(q[2])\n",
    "```\n",
    "\n",
    "For $N=2^n$, this can be generalised, as in the `qft` function in [tools.qi](https://github.com/Q/qiskit-terra/blob/master/qiskit/tools/qi/qi.py):\n",
    "```\n",
    "def qft(circ, q, n):\n",
    "    \"\"\"n-qubit QFT on q in circ.\"\"\"\n",
    "    for j in range(n):\n",
    "        for k in range(j):\n",
    "            circ.cu1(math.pi/float(2**(j-k)), q[j], q[k])\n",
    "        circ.h(q[j])\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Example\n",
    "\n",
    "Let's factorize $N = 21$ with coprime $x=2$, following the [above steps](#stepstwo) of the quantum period finding algorithm, which should return $r = 6$. This example follows one from [this](https://arxiv.org/abs/quant-ph/0303175) tutorial. \n",
    "\n",
    "1. Choose $T = 2^t$ such that $N^2 \\leq T \\le 2N^2$. For $N = 21$, the smallest value of $t$ is 9, meaning $T = 2^t = 512$. Initialise two registers of qubits, first an argument register with $t = 9$ qubits, and second a function register with $n = log_2 N = 5$ qubits: \n",
    "$$\\vert\\psi_0\\rangle = \\vert 0 \\rangle \\vert 0 \\rangle$$\n",
    "\n",
    "2. Apply a Hadamard gate on each of the qubits in the argument register: \n",
    "$$\\vert\\psi_1\\rangle = \\frac{1}{\\sqrt{T}}\\sum_{a=0}^{T-1}\\vert a \\rangle \\vert 0 \\rangle = \\frac{1}{\\sqrt{512}}\\sum_{a=0}^{511}\\vert a \\rangle \\vert 0 \\rangle$$\n",
    "\n",
    "3. Implement the modular exponentiation function $x^a \\bmod N$ on the function register:\n",
    "\\begin{eqnarray}\n",
    "\\vert\\psi_2\\rangle \n",
    "& = & \\frac{1}{\\sqrt{T}}\\sum_{a=0}^{T-1}\\vert a \\rangle \\vert x^a \\bmod N \\rangle\n",
    " = \\frac{1}{\\sqrt{512}}\\sum_{a=0}^{511}\\vert a \\rangle \\vert 2^a \\bmod 21 \\rangle \\\\\n",
    "& = & \\frac{1}{\\sqrt{512}} \\bigg( \\;\\; \\vert 0 \\rangle \\vert 1 \\rangle + \\vert 1 \\rangle \\vert 2 \\rangle +\n",
    "\\vert 2 \\rangle \\vert 4 \\rangle + \\vert 3 \\rangle \\vert 8 \\rangle + \\;\\; \\vert 4 \\rangle \\vert 16 \\rangle + \\;\\,\n",
    "\\vert 5 \\rangle \\vert 11 \\rangle \\, + \\\\\n",
    "& & \\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\, \\vert 6 \\rangle \\vert 1 \\rangle + \\vert 7 \\rangle \\vert 2 \\rangle + \\vert 8 \\rangle \\vert 4 \\rangle + \\vert 9 \\rangle \\vert 8 \\rangle + \\vert 10 \\rangle \\vert 16 \\rangle + \\vert 11 \\rangle \\vert 11 \\rangle \\, +\\\\\n",
    "& & \\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\, \\vert 12 \\rangle \\vert 1 \\rangle + \\ldots \\bigg)\\\\\n",
    "\\end{eqnarray}\n",
    "Notice that the above expression has the following pattern: the states of the second register of each “column” are the same. Therefore we can rearrange the terms in order to collect the second register:\n",
    "\\begin{eqnarray}\n",
    "\\vert\\psi_2\\rangle \n",
    "& = & \\frac{1}{\\sqrt{512}} \\bigg[ \\big(\\,\\vert 0 \\rangle + \\;\\vert 6 \\rangle + \\vert 12 \\rangle \\ldots + \\vert 504 \\rangle + \\vert 510 \\rangle \\big) \\, \\vert 1 \\rangle \\, + \\\\\n",
    "& & \\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\; \\big(\\,\\vert 1 \\rangle + \\;\\vert 7 \\rangle + \\vert 13 \\rangle \\ldots + \\vert 505 \\rangle + \\vert 511 \\rangle \\big) \\, \\vert 2 \\rangle \\, + \\\\\n",
    "& & \\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\; \\big(\\,\\vert 2 \\rangle + \\;\\vert 8 \\rangle + \\vert 14 \\rangle \\ldots + \\vert 506 \\rangle +  \\big) \\, \\vert 4 \\rangle \\, +  \\\\\n",
    "& & \\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\; \\big(\\,\\vert 3 \\rangle + \\;\\vert 9 \\rangle + \\vert 15 \\rangle \\ldots + \\vert 507 \\rangle +  \\big) \\, \\vert 8 \\rangle \\, +  \\\\\n",
    "& & \\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\; \\big(\\,\\vert 4 \\rangle + \\vert 10 \\rangle + \\vert 16 \\rangle \\ldots + \\vert 508 \\rangle +  \\big)  \\vert 16 \\rangle \\, +  \\\\\n",
    "& & \\;\\;\\;\\;\\;\\;\\;\\;\\;\\;\\; \\big(\\,\\vert 5 \\rangle + \\vert 11 \\rangle + \\vert 17 \\rangle \\ldots + \\vert 509 \\rangle +  \\big)  \\vert 11 \\rangle \\, \\bigg]\\\\\n",
    "\\end{eqnarray}\n",
    "\n",
    "4. To simplify following equations, we'll measure the function register before performing a quantum Fourier transform on the argument register. This will yield one of the following numbers with equal probability: $\\{1,2,4,6,8,16,11\\}$. Suppose that the result of the measurement was $2$, then:\n",
    "$$\\vert\\psi_3\\rangle = \\frac{1}{\\sqrt{86}}(\\vert 1 \\rangle + \\;\\vert 7 \\rangle + \\vert 13 \\rangle \\ldots + \\vert 505 \\rangle + \\vert 511 \\rangle)\\, \\vert 2 \\rangle $$\n",
    "It does not matter what is the result of the measurement; what matters is the periodic pattern. The period of the states of the first register is the solution to the problem and the quantum Fourier transform can reveal the value of the period.\n",
    "\n",
    "5. Perform a quantum Fourier transform on the argument register:\n",
    "$$\n",
    "\\vert\\psi_4\\rangle\n",
    " = QFT(\\vert\\psi_3\\rangle)\n",
    " = QFT(\\frac{1}{\\sqrt{86}}\\sum_{a=0}^{85}\\vert 6a+1 \\rangle)\\vert 2 \\rangle\n",
    " = \\frac{1}{\\sqrt{512}}\\sum_{j=0}^{511}\\bigg(\\big[ \\frac{1}{\\sqrt{86}}\\sum_{a=0}^{85} e^{-2 \\pi i \\frac{6ja}{512}} \\big] e^{-2\\pi i\\frac{j}{512}}\\vert j \\rangle \\bigg)\\vert 2 \\rangle\n",
    "$$\n",
    "\n",
    "6. Measure the argument register. The probability of measuring a result $j$ is:\n",
    "$$ \\rm{Probability}(j) = \\frac{1}{512 \\times 86} \\bigg\\vert \\sum_{a=0}^{85}e^{-2 \\pi i \\frac{6ja}{512}} \\bigg\\vert^2$$\n",
    "This peaks at $j=0,85,171,256,341,427$. Suppose that the result of the measement yielded $j = 85$, then using continued fraction approximation of $\\frac{512}{85}$, we obtain $r=6$, as expected. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Implementation <a id='implementation'></a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:32.454145Z",
     "start_time": "2018-09-26T17:12:30.093921Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit import BasicAer, execute\n",
    "from qiskit import QuantumCircuit, ClassicalRegister, QuantumRegister\n",
    "from qiskit.tools.visualization import plot_histogram"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As mentioned [earlier](#shorsalgorithm), many of the experimental demonstrations of Shor's algorithm rely on significant optimisations based on apriori knowledge of the expected results. We will follow the formulation in [this](http://science.sciencemag.org/content/351/6277/1068) paper, which demonstrates a reasonably scalable realisation of Shor's algorithm using $N = 15$. Below is the first figure from the paper, showing various quantum circuits, with the following caption: _Diagrams of Shor’s algorithm for factoring $N = 15$, using a generic textbook approach (**A**) compared with Kitaev’s approach (**B**) for a generic base $a$. (**C**) The actual implementation for factoring $15$ to base $11$, optimized for the corresponding single-input state. Here $q_i$ corresponds to the respective qubit in the computational register. (**D**) Kitaev’s approach to Shor’s algorithm for the bases ${2, 7, 8, 13}$. Here, the optimized map of the first multiplier is identical in all four cases, and the last multiplier is implemented with full modular multipliers, as depicted in (**E**). In all cases, the single QFT qubit is used three times, which, together with the four qubits in the computation register, totals seven effective qubits. (**E**) Circuit diagrams of the modular multipliers of the form $a \\bmod N$ for bases $a = {2, 7, 8, 11, 13}$._\n",
    "\n",
    "<img src=\"images/shoralgorithm.png\" alt=\"Note: In order for images to show up in this jupyter notebook you need to select File => Trusted Notebook\" width=\"500 px\" align=\"center\">\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we cannot run this version of Shor's algorithm on an IBM Quantum Experience device at the moment as we currently lack the ability to do measurement feedforward and qubit resetting. Thus we'll just be building the ciruits to run on the simulators for now. Based on Pinakin Padalia & Amitabh Yadav's implementation, found [here](https://github.com/amitabhyadav/Shor-Algorithm-on-IBM-Quantum-Experience)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First we'll construct the $a^1 \\bmod 15$ circuits for $a = 2,7,8,11,13$ as in **E**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:32.467183Z",
     "start_time": "2018-09-26T17:12:32.459175Z"
    }
   },
   "outputs": [],
   "source": [
    "# qc = quantum circuit, qr = quantum register, cr = classical register, a = 2, 7, 8, 11 or 13\n",
    "def circuit_amod15(qc,qr,cr,a):\n",
    "    if a == 2:\n",
    "        qc.cswap(qr[4],qr[3],qr[2])\n",
    "        qc.cswap(qr[4],qr[2],qr[1])\n",
    "        qc.cswap(qr[4],qr[1],qr[0])\n",
    "    elif a == 7:\n",
    "        qc.cswap(qr[4],qr[1],qr[0])\n",
    "        qc.cswap(qr[4],qr[2],qr[1])\n",
    "        qc.cswap(qr[4],qr[3],qr[2])\n",
    "        qc.cx(qr[4],qr[3])\n",
    "        qc.cx(qr[4],qr[2])\n",
    "        qc.cx(qr[4],qr[1])\n",
    "        qc.cx(qr[4],qr[0])\n",
    "    elif a == 8:\n",
    "        qc.cswap(qr[4],qr[1],qr[0])\n",
    "        qc.cswap(qr[4],qr[2],qr[1])\n",
    "        qc.cswap(qr[4],qr[3],qr[2])\n",
    "    elif a == 11: # this is included for completeness\n",
    "        qc.cswap(qr[4],qr[2],qr[0])\n",
    "        qc.cswap(qr[4],qr[3],qr[1])\n",
    "        qc.cx(qr[4],qr[3])\n",
    "        qc.cx(qr[4],qr[2])\n",
    "        qc.cx(qr[4],qr[1])\n",
    "        qc.cx(qr[4],qr[0])\n",
    "    elif a == 13:\n",
    "        qc.cswap(qr[4],qr[3],qr[2])\n",
    "        qc.cswap(qr[4],qr[2],qr[1])\n",
    "        qc.cswap(qr[4],qr[1],qr[0])\n",
    "        qc.cx(qr[4],qr[3])\n",
    "        qc.cx(qr[4],qr[2])\n",
    "        qc.cx(qr[4],qr[1])\n",
    "        qc.cx(qr[4],qr[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we'll build the rest of the period finding circuit as in **D**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:32.481843Z",
     "start_time": "2018-09-26T17:12:32.470502Z"
    }
   },
   "outputs": [],
   "source": [
    "# qc = quantum circuit, qr = quantum register, cr = classical register, a = 2, 7, 8, 11 or 13\n",
    "def circuit_aperiod15(qc,qr,cr,a):\n",
    "    if a == 11:\n",
    "        circuit_11period15(qc,qr,cr)\n",
    "        return\n",
    "    \n",
    "    # Initialize q[0] to |1> \n",
    "    qc.x(qr[0])\n",
    "\n",
    "    # Apply a**4 mod 15\n",
    "    qc.h(qr[4])\n",
    "    #   controlled identity on the remaining 4 qubits, which is equivalent to doing nothing\n",
    "    qc.h(qr[4])\n",
    "    #   measure\n",
    "    qc.measure(qr[4],cr[0])\n",
    "    #   reinitialise q[4] to |0>\n",
    "    qc.reset(qr[4])\n",
    "\n",
    "    # Apply a**2 mod 15\n",
    "    qc.h(qr[4])\n",
    "    #   controlled unitary\n",
    "    qc.cx(qr[4],qr[2])\n",
    "    qc.cx(qr[4],qr[0])\n",
    "    #   feed forward\n",
    "    qc.u1(math.pi/2.,qr[4]).c_if(cr, 1)\n",
    "    qc.h(qr[4])\n",
    "    #   measure\n",
    "    qc.measure(qr[4],cr[1])\n",
    "    #   reinitialise q[4] to |0>\n",
    "    qc.reset(qr[4])\n",
    "\n",
    "    # Apply a mod 15\n",
    "    qc.h(qr[4])\n",
    "    #   controlled unitary.\n",
    "    circuit_amod15(qc,qr,cr,a)\n",
    "    #   feed forward\n",
    "    qc.u1(3.*math.pi/4.,qr[4]).c_if(cr, 3)\n",
    "    qc.u1(math.pi/2.,qr[4]).c_if(cr, 2)\n",
    "    qc.u1(math.pi/4.,qr[4]).c_if(cr, 1)\n",
    "    qc.h(qr[4])\n",
    "    #   measure\n",
    "    qc.measure(qr[4],cr[2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we build the optimised circuit for $11 \\bmod 15$ as in **C**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:32.493545Z",
     "start_time": "2018-09-26T17:12:32.484582Z"
    }
   },
   "outputs": [],
   "source": [
    "def circuit_11period15(qc,qr,cr):\n",
    "    # Initialize q[0] to |1> \n",
    "    qc.x(qr[0])\n",
    "\n",
    "    # Apply a**4 mod 15\n",
    "    qc.h(qr[4])\n",
    "    #   controlled identity on the remaining 4 qubits, which is equivalent to doing nothing\n",
    "    qc.h(qr[4])\n",
    "    #   measure\n",
    "    qc.measure(qr[4],cr[0])\n",
    "    #   reinitialise q[4] to |0>\n",
    "    qc.reset(qr[4])\n",
    "\n",
    "    # Apply a**2 mod 15\n",
    "    qc.h(qr[4])\n",
    "    #   controlled identity on the remaining 4 qubits, which is equivalent to doing nothing\n",
    "    #   feed forward\n",
    "    qc.u1(math.pi/2.,qr[4]).c_if(cr, 1)\n",
    "    qc.h(qr[4])\n",
    "    #   measure\n",
    "    qc.measure(qr[4],cr[1])\n",
    "    #   reinitialise q[4] to |0>\n",
    "    qc.reset(qr[4])\n",
    "\n",
    "    # Apply 11 mod 15\n",
    "    qc.h(qr[4])\n",
    "    #   controlled unitary.\n",
    "    qc.cx(qr[4],qr[3])\n",
    "    qc.cx(qr[4],qr[1])\n",
    "    #   feed forward\n",
    "    qc.u1(3.*math.pi/4.,qr[4]).c_if(cr, 3)\n",
    "    qc.u1(math.pi/2.,qr[4]).c_if(cr, 2)\n",
    "    qc.u1(math.pi/4.,qr[4]).c_if(cr, 1)\n",
    "    qc.h(qr[4])\n",
    "    #   measure\n",
    "    qc.measure(qr[4],cr[2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's build and run a circuit for $a = 7$, and plot the the circuit and results:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-09-26T17:12:32.830902Z",
     "start_time": "2018-09-26T17:12:32.495963Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAABCMAAAPWCAYAAADat1LsAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADl0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uIDMuMC4yLCBodHRwOi8vbWF0cGxvdGxpYi5vcmcvOIA7rQAAIABJREFUeJzs3XlcFfXi//H3Ac0dsdz3rc0VQsIshRaXAsNE28yumlqapWlet6/d8peG6a28pSWVqSGVmQapqeWCqYkraGqpqXS1DDURXHA5zO+PHpwryHKQw8w58Ho+HufxyDlzZt7QnJnD+8x8xmYYhiEAAAAAAACTeFkdAAAAAAAAlC6UEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFSUEQAAAAAAwFRlrA4AwH2NGDFCiYmJlqzbz89P77zzjiXrBgAAAFC8ODMCQJ4SExMtKSOsWi8AAAAAc3BmBIB8+fn5ad26daauMyQkxNT1AQAAADAXZ0YAAAAAAABTUUYAAExnt9t18eJFGYZhdRQAAFCKGIahixcvym63Wx2l1KOMAAAUu4yMDEVHR6tXr15q0qSJypQpo/Lly6tSpUq666679PLLL2vv3r1WxwQAACVQYmKihg8frjvvvFPly5dX+fLlVaZMGTVv3lyPP/64Fi1apMuXL1sds9ShjAAAFBvDMBQVFaUGDRqob9++2rp1q+68807961//kiQNHjxYZcuW1bvvvquWLVvqwQcf1JEjR6wNDQAASoSff/5ZISEh8vf314cffqjKlStr2LBhmjx5siSpbdu2Wr9+vXr37q3GjRsrJiaGszZNZDP4bQPIQ9ZAklYNYGn2euFaqampevzxx7Vy5UqFhIRowoQJuv/++2Wz2SRJNpvNccA/ceKEPvroI73xxhvKzMzUhx9+qCeeeMLK+AAAwIPNnj1bw4cPV6VKlfR///d/6tevn6pVq+Z4PutziN1u14oVKzRp0iRt2bJFERERmj9/vipWrGhh+tKBMyMAAC535swZPfDAA1qzZo1mzpypNWvW6IEHHnAUETnVqFFD48aN008//aQ77rhDTz75pObOnWtuaAAAUCK8/fbbeu6553Tfffdpz549eumll7IVEVfz9vZWaGioNm3apMjISC1evFgPPfSQLly4YHLq0ocyAgDgcoMGDVJSUpKWLFmioUOH5llC5NSwYUOtWrVKnTt31sCBA7Vjx45iTgrAnc2bN0+RkZFOzWsYhsaPH6+vv/66mFMBcGdr1qzRyJEjFRERobi4ONWuXdup13l7e2vMmDGKjo7W+vXrNXLkyGJOilJVRsydO9dx+rczAgICtHLlyuILBAAl0KJFi/Tll1/qtddeU2hoaKFfX758eX3xxReqWbOm+vXrx4BSQCllGIbWrFmjcePG6Y033ihw3jFjxuiNN95QfHy8SQkBuJtz587pmWee0c0336z58+erTJkyhV7Gk08+qZdeekkffPCB1qxZUwwpkaVUlRE52e12jR49WjVq1FCVKlUUERGhkydPOp4PDw9XXFychQkBz3L27FnVqFFDixYtcky7cOGCOnTooF69eikzM9PCdDCDYRh67bXX1KpVK/3zn/+87uVUq1ZN7733nnbv3q3Fixe7MCEAT2Gz2TRnzhz16dNH48ePz7OQyCoipk2bpueff15vvfWWyUkBuIv58+fryJEjioqKKtKYD6+//roaNWqkSZMmuTAdcirVZURkZKRiY2OVkJCgo0ePSpL69u3reJ4yAiicypUr6+WXX9akSZMcAwI9+uijKleunBYsWCAvr1K9yykVNm7cqJ9++kkjRoy4rm8jrtajRw81adJEs2bNclE6AJ7G29tb8+bNy7OQyFlEvPvuu05fFgag5Jk1a5YCAgIUHBxcpOVUqFBBzz//vOLj47Vnzx4XpUNObvGXwcKFC9W8eXNVrlxZXbp00ahRo9S7d+9iX29UVJTGjBmjpk2bqmrVqnrzzTe1YsUKJScnS/r7Vi/e3t7avn17sWcBSophw4bp+PHj+uqrrzR48GAdPXpUsbGxKleunNXRYIJVq1bJy8tLjz32WJGX5eXlpSeeeEIbNmzQ+fPnXZAOgCfKq5CgiABwtT/++EM//fSTnnzy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tkz79u1TaGioLl26ZEJaeBrKCAAAALgdwzD06KOPKjg4WL/++muB8+/evVudOnXSgAEDTEiXt6VLl+quu+7SlClTCpzXbrerf//+6tChg3755RcT0gHOO3LkiIYNG6Z7771X0dHRuuGGGwr1+m7duik6OlpbtmzR5MmTiyklPFmpKiPmzp2rkJAQp+cPCAjQypUriy8QAAAAcmWz2TRjxgxduHBBISEh+RYSu3fv1n333ady5copMjLSxJTXevDBB/Xkk09qwoQJ+RYSWUXEp59+qldeeUW33nqriSmBgr388suSpDlz5qhs2bLXtYyIiAg99dRTmjJlio4cOeLCdCgJSlUZkZPdbtfo0aNVo0YNValSRREREdmuaQoPD1dcXJyFCQEAAEqvtm3bavXq1fkWElcXEWvXrtXNN99sQdL/8fb21vz58/MtJK4uIiZNmqSJEydakBTI29GjR7VkyRINHTpUjRs3LtKypkyZoszMTM2ePds14VBilOoyIjIyUrGxsUpISNDRo0clSX379nU8TxkBAABgrfwKCXcrIrLkV0hQRMATfPHFF8rMzNRzzz1X5GU1aNBAYWFhio6OdkEylCRuUUYsXLhQzZs3V+XKldWlSxeNGjVKvXv3Lvb1RkVFacyYMWratKmqVq2qN998UytWrFBycrKkvw9+3t7e2r59e7FnAQAAQO7yKiTcsYjIklshQREBT7F161Y1atRITZo0ccny7r33Xh09elTHjx93yfJQMlheRmSN0LpgwQKlp6crLCxMM2bMkL+/f6GWExkZqTZt2jg9f2pqqn777TcFBAQ4pjVr1kw+Pj5KSkpyTAsPD1dsbGyhsgAAAMC1ri4k7r77bkly2yIiS85Col27dhQR8Ah79uxR27ZtXba8rGX99NNPLlsmPJ+lZcT58+c1cuRIRUVFKSgoSDabTQMHDpTdbneUEQ888IBq1Kih119/Pd9ljR07Vrt27XJ63enp6ZKkqlWrZpvu6+urtLQ0x79DQ0O1bNkyp5cLAACA4tG2bVt98MEHSklJkfT3l1ruWkRk8fb21ieffKLGjRsrMTFR999/P0UE3N758+fl4+PjsuVVqVJFknThwgWXLROer4yVK4+Pj1dmZqYefPBBx7QTJ05IkqOMmDt3rr7//nvHmA6ukvWGyHkv6tTU1GxvvOTkZDVs2NCl686NzWYr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un14am53wWUaAFAKHThwQB999JE2bNignTt36sKFC5KkunXrKiAgQGFhYerTp48qVapkcdL88SEAQFF44j7EEzNLnpvb3e3bt08ff/yxNm7cqMTERGVkZEiS6tevr4CAAIWHh+vxxx/Pc3wJd+Gp24en5nYXlBEAUMplZmbq4sWLqlixoscdUPkQAKAoPHEf4omZJc/N7UkyMzOVkZGhSpUqedzv2lO3D0/N7S4YMwIASjkvLy+3/8YEAADkz8vLSxUrVrQ6BmAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGAqyggAAAAAAGCqMlYHAAAAAICiOHfunL7//ntt375d+/fv1+XLl1W1alW1bdtW7du315133imbzWZ1TABXoYwAAAAA4JH+/PNPTZkyRXPnzlVaWpq8vLzUtGlTHTx4ULVr19Ynn3wiSWrRooVGjBihZ555Rl5enBwOuAPeiQAAAAA8zpdffqmWLVvq/fffV1hYmNasWaP09HQdOHBAkvTHH3/o999/18cff6zy5ctr8ODBCgkJ0eHDhy1ODkCijAAAAADgYf7973/r0UcfVdOmTZWYmKgFCxbo3nvvVcWKFbPNV6dOHQ0YMEDbtm3TJ598ol27dql9+/b66aefLEoOIAtlBAAAAFDKJSUl6ddff3V6/tWrV+vMmTPFmChvMTExevnll/Xoo49q48aNatGiRYGvsdls6tevnxISElSmTBl17txZKSkpJqQFkJdSVUbMnTtXISEhTs8fEBCglStXFl8gAAAAwGJ2u12PPfaYQkJCnCokYmNj1a1bN40bN86EdNkdO3ZMQ4cO1d13363o6GiVLVu2UK+/9dZb9e233+qvv/7S888/X0wpATijVJUROdntdo0ePVo1atRQlSpVFBERoZMnTzqeDw8PV1xcnIUJAQAAgOLl7e2tL774QhcuXCiwkIiNjVWvXr3Url07vfHGGyam/NvEiRN18eJFffLJJ4UuIrK0adNGr776qhYtWqS1a9e6OCEAZ5XqMiIyMlKxsbFKSEjQ0aNHJUl9+/Z1PE8ZAQAAgNKgbdu2Wr16db6FxNVFxIoVK1S1alVTM546dUqfffaZ+vXrp5tvvrlIyxoxYoSqVaumWbNmuSgdgMJyizJi4cKFat68uSpXrqwuXbpo1KhR6t27d7GvNyoqSmPGjFHTpk1VtWpVvfnmm1qxYoWSk5Ml/b1T9vb21vbt24s9CwAAAGCl/AoJq4sISfrmm2+UkZGhQYMGFXlZFSpU0NNPP62vv/5aGRkZLkgHoLAsLyPmzZunUaNGacGCBUpPT1dYWJhmzJghf3//Qi0nMjJSbdq0cXr+1NRU/fbbbwoICHBMa9asmXx8fJSUlOSYFh4ertjY2EJlAQAAADxRXoWE1UWEJG3btk1VqlSRn5+fS5bXqVMnXblyRbt27XLJ8gAUjqVlxPnz5zVy5EhFRUUpKChINptNAwcOlN1ul7+/v/7880916NBBISEhCgoK0urVq/Nc1tixYwu1I0lPT5eka3amvr6+SktLc/w7NDRUy5YtK+RPBgAAAHimqwuJoKAgSbK8iJCkffv2qWXLlvLycs2fMK1bt3YsF4D5yli58vj4eGVmZurBBx90TDtx4oQkyd/fX9WrV9cPP/wgb29vHTp0SI899pi2bt3qknVXqVJFkq65JVFqaqp8fHwc/05OTlbDhg1dss782Gy2Yl8HgJLNE/cjnpgZgPvwxH2IJ2aWpM2bN8vX19fqGJKc/x06O1+/fv3Ur1+/IiRyLU/cRjwxs+S5ud1JUX6HlpYRKSkpqlmzZrZpMTExqlWrlmrXrp1tempqaqEuwyiIr6+vGjZsqB07djhO9Tp06JDS0tKyrScuLk4REREuW29eDMMo9nUAKLlsNpvH7Uc8MTMA9+GJ+xBPypw1RsTtt9+u3bt3q379+lq3bp2aNWtmWaZu3brpxIkTTo3n5szves+ePWrVqpWio6PVp08fV8UsEk/aRrJ4YmbJc3O7i5CQEEnSunXrnJovN5ZeptGiRQsdPHhQ8fHxunTpkmJiYhQZGZltvIjDhw/rnnvuUdeuXfXII4+4dP2DBw/W1KlTdfjwYaWlpWnMmDHq2rWrGjduLEk6d+6c1q5dq7CwMJeuFwAAAHBXVw9W+cMPP0iSU7f9LG6tW7fWnj17dPnyZZcsb+fOnZLk0i88ATjP0jIiMDBQEyZMUM+ePVW/fn0lJCQoKCgoWxnRpEkTbdiwQQkJCRo2bFiey5oyZYpatmxZqPWPHTtW3bt3V2BgoOrVqye73a7o6GjH86tWrXJcLgIAAACUdHndNaOg236aISgoSBcvXnQUJEX13XffqXLlyrr99ttdsjwAhWP53TQmTZqkU6dOKSUlRTNmzND+/fsdZcTFixcd8/n4+Khy5cp5Lmf8+PHas2dPodbt7e2t6dOn6+TJk0pPT9fixYuzFQ9xcXEKDw8v5E8EAAAAeJ78bt+Z320/zRIaGqobb7xRs2bNKvKyTp06pYULF+qpp55SmTKWXrkOlFqWlxFXS0tLU3JysqOM2Lp1qzp16qR7771XPXr00IwZM0zN06hRI/Xu3dvUdQIAAABmy6+IyGJ1IVGhQgUNHjxYixcvLvLZERMmTNDFixc1dOhQF6UDUFg2w41G7di0aZO6deumM2fOFMvIpomJiUpMTHSr0XIBwBU8cRAmT8wMwH144j7EXTPb7Xa1a9dO5cuXz7WIyJk7KSlJ999/v55++mm99dZbpmY9e/as2rRpIy8vL23ZskU33nhjrvPl97teunSpunfvrlGjRmn69OnFGbfQ3HUbyY8nZpY8N7e7KMwAlnnN41ZlBADg+njiAdUTMwNwH564D3HnzCkpKSpXrlyuZ0TklvvQoUNq1KiRvL29zYrosGHDBj3wwANq1aqVli9ffs3d+aS8f9fffvutIiIidNttt2njxo2qUKGCGZGd5s7bSF48MbPkubndhSvKCLe6TAMAAACA+WrWrJlrEZGXpk2bWlJESNI999yjxYsXa8+ePWrdurUWLVpU4B+VZ8+e1fDhwxUaGqpbb71VK1eudLsiAihtKCMAAAAAeJSHHnpIW7ZsUf369dW7d2+1atVKb7/9thISEnT27FlJ0vHjx7V8+XK98MILqlevnv7zn//o+eef14YNG1SjRg2LfwIADB0LAAAAwOO0bt1amzdvVnR0tGbOnKmRI0dme75OnTqSpLJly6p3794aPny47rzzTiuiAsgFZQQAAAAAj1S2bFn1799f/fr102+//abt27dr//79GjdunN555x35+fnJ399fPj4+VkcFkAMDWAJACeCJgzB5YmYA7sMT9yGemFnyzNyemFnyzNyemFny3NzuggEsAQAAAACAx6GMAAAA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6tTJ6Nq1q9GsWTOjTZs2xqZNm6572Vdf4+mMfv36GdOmTbvu9XmC4OBgS66dLso6rcjsivXmfP2uXbuM77//vsDXffXVV0bZsmWvGSMiN8uWLTN++eWXPNdZWM68vjjeV564jZi9zrNnzxrTp083mjRpYkgyvLy8jIceeshYtWqVaRmux/r1642ePXsa3t7ehiSjXr16xuTJk43Tp0+blsETt4+Sst/79ddfjW+++Sbb2Da52bFjh1GuXLlrxojIzbp1/5+9e4+zsq73/v8eEAVxBhDxHCpgpakhRAgbFJWDpmbIj0pNaxMby12e0KAsLUsbVHZQ7lK0khL2nYaF6C26TcFTouVOQ7eaghwsRchxBBVkZv3+8HYSBcEYrjXMPJ9/Tdf1bX0/8JA1a16zrmvNKf3xj3/c4J7vl+e9prvn2rVrSz/96U9LPXv2bLgOuW/fvqVp06Zt8j1IymH+/PmlL37xi6W2bduWkpQ6depUOvfcc0tLliwp92gb9Nprr5V+9KMflT70oQ+VkpQqKipKgwcPLt10003lHu09zZs3r/TZz3621KZNm1KS0i677FK68MILSy+++GK5R9ugl19+uVRdXV3q2rVrKUmpdevWpU9+8pOlO++8s9yjvaff/e53peOOO67h+3nXrl1LEyZMKNXW1pZ7tA1atmxZ6YILLijtvPPOpSSlNm3alE488cTSgw8+WNgMW+v38815zPda894XHhestrY2ixYtaviN3xlnnNHwVuNvf/vb6dGjxyZ/Fnlj2GuvvTJy5MjC9qNlOfDAAzdp3QknnJCnnnqq4e2+7+UTn/jEZk615fl31Tjat2+fsWPHZuzYsVmzZs16f/PWFA0cODADBw5MfX191q5du8kfZ1ukv/71rzn22GPz+OOPZ+XKlev89vgLX/hC/vd//zft2rXLmDFjctJJJ+Wss85quNv5I488kpdeeqlcozd53bp126TfPB188MF54oknNul5r6m9C2h9PO81jtatW2fUqFEZNWpU1q5dmyQbvYdOU/CRj3wk11xzTa6++uqsWbNmkz89q5zatm2br3zlK/nKV76SN954I61atXrPj2duKj7+8Y/nv/7rv1Iqlbaav+uqqqqMGzcu48aN26q+nx9xxBE54ogjmvT383fq0qVLvvOd7+Q73/lOVq9enW233bZJXdqVJPPmzcvZZ5+d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jB8/Po8++ugm7/vKK68kSTp06LDO8Y4dO6a2tvaf+8MAsNV6+umnc9NNN2X8+PE57rjj1jm300475YYbbkh9fX2uvPLKMk0IADRXkyZNyh577JGf//znadeuXcPxVq1a5cwzz8yIESNy5ZVX5rXXXivjlJtnm3IP8E5z585NRUVFjj/++Hed69ixY37zm9+kc+fOefzxx3PaaaflnnvuaZR9KysrkyQvv/zyOsdrampSVVXVKHu8l/ETpmzxPQDYdH+8/64kyRe+8IX1nt99990zdNiwTP3ltGzT5YMFTgYANGd1dXW57bbb8rWvfS3bbrvtetf867/+a2bMmJFRZ34ze3X/UMETJgsW/y3Jxn+OfWvd+jS5GLF8+fJ06tQpFRUV7zrXuXPnhq+32267tG7dutH27dixY7p27ZqHH344PXv2TJIsWLAgtbW17+tyj39W9bgxW3wPADbd5ZfX5o6b/k923HHHDa7ZsVOntG+3nedwAKDRrFq1Kpeff/p7vgbp1KlTkuTU4YNz9NFHFzVagwdunZ5k4z/HvrVufZrcZRq9evXKwoULM2vWrNTX16empia33XbbOmvq6upyxhlnZPz48Y2695gxYzJhwoQsXLgwtbW1GTduXIYNG5a99967UfcBoOnbb7/9kiR33HHHes+vXbs2d911V8M6AIDGsP322+cDH/jABl+DJP94ffLhD3+4qLEaXZN7Z8QBBxyQa665Jueee25OPPHEVFZWZtSoURk2bFiSpFQqZdSoUTn22GNz1FFHbfBxLrnkkkybNi2PPfbYJu89fvz4vPTSS+nTp09Wr16dIUOG5LrrrtvsP9Mm7e0yDYAmpb6+Ph067ZjvfOc7GTJkSMPlfG+54oor8txzz6XvEZ/0HA4ANKq99+uVO26fmdtvvz1Dhw5d59zixYtzxRVXZJ99989V1/93WeZrjMs0KkqlUqlRp9rCvvKVr2SXXXbJt771rXKPAkAzd/PNN+dTn/pUPvShD2XcuHEZMGBAnn/++Vx99dW59tpr88lPfjI33nhjo142CABQW1ubgQMH5oknnsiZZ56Zk08+Odtvv31uueWWTJgwIa+++mruvffeHHjggWWZb9CgQUmSOXPmbHTdhtZsVTFizpw5GTp0aPr3758k2XHHHXPjjTeWeSoAmrNbb701Z599dp588smGY9tuu12+9KXTctlll23wxlIAAJtjxYoVOf300zNjxozU1dU1HN+ja7fcctON+ehHP1q22RojRjS5yzTey6BBg7JmzZpyjwFAC3L00UfnqKOOyue+/LUMOeQjad++fe577LlM+vZZ5R4NAGjGOnfunF/96ld57rnn8uVzL8z/d/Sh+ehHP5r/mj2vrCGisWxVMQIAyqGioiIf2Gffho/5/OMC94gAAIqxxx57ZP+eH8+pp56aJPmv2fPKPFHjaHKfpgEAAAA0b2IEAAAAUCgxAgAAACiUGAEAAAAUSowAAAAACiVGAAAAAIUSIwAAAIBCiREAAABAocQIAAAAoFBiBAAAAFAoMQIAAAAolBgBAAAAFEqMAAAAAAolRgAAAACFEiMAAACAQokRAAAAQKHECAAAAKBQYgQAAABQKDECAAAAKJQYAQAAABRKjAAAAAAKJUYAAAAAhRIjAAAAgEKJEQAAAEChxAgAAACgUGIEAAAAUCgxAgAAACiUGAEAAAAUSowAAAAACiVGAAAAAIUSIwAAAIBCiREAAABAocQIAAAAoFDblHuApqSuri7jx4/Ptddem9dffz1Dhw7NVVddlZ122qncowFQzuVgfQAAIABJREFURq+++mrm//H3ufDC59K+ffv8/cXV5R4JAGgBSqVSHnzwwdx/5//Nd17/Wz760Y+mvq6u3GM1CjHibaqrqzNz5szMmzcvnTt3zqhRo3LKKafk1ltvLfdoAJTJlClTMm7cuNTU1OSWtx1//qmHMnXq1HTq1KlsswEAzdeCBQvy2c9+Ng899FCS5J7bZyZJqjrumCN7d8uwYcPKOd5ma7KXadx333058sgjU1VVlY4dO2bkyJFbfM+3XnB269YtHTp0yKWXXprZs2dn0aJFW3xvAJqea665Jqeddlp69+6du+++O3V1dfnrX/+a73znO5k9e3aOPvrorF7tXRIAQON6/vnnM2jQoDzzzDP5z//8z9TU1GTNmjX57W9/mw/ssVuOO+643H333eUec7M0yRgxY8aMDB8+PKeffnqWLVuWJUuWZPTo0e/rMaqrq3PQQQdt8vqamposXrw4vXv3bjjWvXv3VFVV5ZFHHnlfewOw9Xv99dfz9a9/PYcddlhmz56dgQMHplWrVtltt91ywQUX5Be/+EXmzZuXG264odyjAgDNzKRJk/LXv/41d9xxR04//fR06NAhbdq0yfHHH5977703e+yxR8aPH1/uMTdLRalUKpV7iLdbtWpV9tprr1xzzTX51Kc+tc65F154IcOHD8+2226b1157LZdcckmOPPLIRtl3yZIl6dq1axYsWJB99tmn4fhee+2Viy++OJ/73OcaZZ8NGT9hyhZ9fADenyce/WNmTp+S22+/PUOGDHnX+VKplA99+MNZvTY5cczYMkwIADRHpVIp/3nxeRkyZHB+c+ON613zgx/8IOecc06+ePaF2WmX3QueMJl+1cQkyUmnvfdroOlXTcziBU+u91yTu2fE3LlzU1FRkeOPP/5d53baaafcc889ad26dRYsWJDPfOYzDdfPbK7Kysokycsvv7zO8ZqamlRVVTXKHu+letyYLb4HAJvusssuy8zpySGHHLLe8xUVFel3yCGZM2eO53AAoNGsXLkyl379S+m3gdcgSdKvX78kyQmDP55PfOITRY3W4IFbpyfZ+M+xb61bnyZ3mcby5cvTqVOnVFRUvOtc69at07p16yRvRoL3cxnGxnTs2DFdu3bNww8/3HBswYIFqa2tbdR9ANg6vBWply5dusE1S5cuLSRYAwAtR9u2bbPNNtts9DVIkq36dUiTe2dEr169snDhwsyaNSvHHHNMamtrM2/evIY7hS5cuDCnnHJKnnzyyfz85z9v1L3HjBmTCRMm5PDDD0/nzp0zbty4DBs2LHvvvXej7rM+LtMAaFpeqa1N69atc+WVV2by5MnvOv/kk0/mzjvvzL8MPtZzOADQqLrvd1Cuu+66XHzxxQ2/IHlLqVTKT35yZSo7dMpNd/85N9/3eOHzLVj8tyQb/zn2rXXr0+TuGZEkU6dOzSWXXJLnnnsulZWVGTVqVC6++OJ11ixYsCBHHHFEnn322fU+xiWXXJJp06blscce2+R96+rqMm7cuFx77bVZvXp1hgwZkilTpmSnnXbanD8OAFupUaNG5dprr83kyZPzpS99KW3atEmSzJ8/PyNGjMgLL7yQ//3f/81uu+1W5kkBgObkgQceyIABA3LooYfml7/8ZfbYY48kb17C8a1vfSuTJk3KxIkTc84555RlvkGDBiVJ5syZs9F1G1rTJGPEhqxevTrbbbddkjcv5xg0aFDmz59f5qkAaK5ee+21jBgxIrfeemt23XXX9OvXL88//3x+//vfp2PHjpk1a1YGDBhQ7jEBgGZo2rRp+cIXvpBSqZRBhx+e9ttvnzlz5qS2tjZf/epXM3ny5PXe3qAIjREjmtxlGu/loYceyje+8Y20bt06b7zxxnrfNgsAjaVdu3aZNWtWZs+enbPOOz9PPfVU2rdvn8OOGp7rp16ZnXfeudwjAgDN1Mknn5x+/frlyiuvzC+n/ypdduyQT37ykylV7p7Jk6vLFiIay1YVIwYMGJC777673GMA0IK0bt06xxxzTO6Z/1zDHaPHT5giRAAAW1y3bt1y6aWXplXnHuu8DtnaQ0TSBD9NAwAAAGjexAgAAACgUGIEAAAAUCgxAgAAACiUGAEAAAAUSowAAAAACiVGAAAAAIUSIwAAAIBCiREAAABAocQIAAAAoFBiBAAAAFAoMQIAAAAolBgBAAAAFEqMAAAAAAolRgAAAACFEiMAAACAQokRAAAAQKHECAAAAKBQYgQAAABQKDECAAAAKJQYAQAAABRKjAAAAAAKJUYAAAAAhRIjAAAAgEKJEQAAAEChxAgAAACgUGIEAAAAUCgxAgAAACiUGAEAAAAUSowAAAAACiVGAAAAAIUSIwAAAIBCiREAAABAocSIt6mrq8t5552XLl26pLKyMiNGjMjy5cvLPRYATUCpvj61tbVZs2ZNuUcBAFqYtW+8kZUrV6ZUKpV7lEYjRrxNdXV1Zs6cmXnz5mXp0qVJklNOOaXMUwFQTi+++GLOP//8/Pj749KhQ4e0a9cuM6b+Z+bMmVPu0QCAZqxUKuX666/PgAEDMvFbX0llZWX23XffPHj3f+e1114r93ibrcnGiPvuuy9HHnlkqqqq0rFjx4wcOXKL7zllypSMGzcu3bp1S4cOHXLppZdm9uzZWbRo0RbfG4CmZ8mSJTnkkENSXV2dIw4flMsuuyxnn312Xl7+txxxxBG56qqryj0iANAMlUqlnH322fnMZz6TF154Id/61rfy/e9/P7vvvnvu+r+/ztChQ7Nq1apyj7lZmmSMmDFjRoYPH57TTz89y5Yty5IlSzJ69Oj39RjV1dU56KCDNnl9TU1NFi9enN69ezcc6969e6qqqvLII4+8r70BaB5OPfXULF++PPfff39mzpyZc889N5dffnkWLVqUT3ziE/nyl7+cP//5z+UeEwBoZn79619n8uTJOfPMM/Pkk0/moosuyvjx43P33XfnV7/6Ve6///6MGzeu3GNuliYXI1atWpXTTjstU6ZMyYgRI9K2bdtUVlZm2LBhDWtWrFiRTp065brrrtvg44wfPz6PPvroJu/7yiuvJEk6dOiwzvGOHTumtrb2ff4pANja/fnPf86cOXPyzW9+M3379l3nXLt27TJ16tRst912+clPflKmCQGA5upHP/pRunfvnv/4j/9Iq1br/tj+6U9/OqecckqmTp3a8HPs1mibcg/wTnPnzk1FRUWOP/74Da753ve+lwEDBjTqvpWVlUmSl19+eZ3jNTU1qaqqatS91mf8hClbfA8ANt0f7v1dkuTkk09e7/nOnTvnqKOOyq9+fWOq9upZ5GgAQDO2du0bueeee/LNb37zXSHiLSeddFKmTp2afzv7guy9734FT5gsWPy3JBv/OfatdevT5GLE8uXL06lTp1RUVKz3/NNPP50VK1asczlFY+jYsWO6du2ahx9+OD17vvmicsGCBamtrX1fl3v8s6rHjdniewCw6SZu80p+d/P1adeu3QbXbL/99umww/aewwGARvPqq69m4je/stHXIEnyryOPWucqgqK8/rfHk2z859i31q1Pk7tMo1evXlm4cGFmzZqV+vr61NTU5Lbbbms4f8EFF+TCCy/cInuPGTMmEyZMyMKFC1NbW5tx48Zl2LBh2XvvvbfIfgA0XW+F6VtuuWW951evXp3bb7+9YR0AQGNo165dPvjBD27wNUiS3HzzzWndunUOOOCAAif7h0mTJmXSpEmbtG5Dmtw7Iw444IBcc801Offcc3PiiSemsrIyo0aNyrBhw3L//fenc+fO6d69+0Yf55JLLsm0adPy2GOPbfLe48ePz0svvZQ+ffpk9erVGTJkyHvel6IxuUwDoGkp1denc5dd8+1vfztDhw7Nzjvv/I9zpVIuuuiiLF++PG127Oo5HABoVHt+8KO58+YbMn369Jx00knrnJs/f35+/OMfp9uHDsyPrttwsGgqNvTuiYpSqVQqeJZ/2g9/+MPMmDEj7dq1y9NPP5327dvnyiuvTL9+/co9GgDN0L333puhQ4dmxx13zFe/+tUMGDAgzz//fK6++urcdttt+eIXv5irr756g5cWAgD8M15//fUMGzYs99xzT04++eScfPLJ2X777XPLLbfkyiuvTPv27XP//fdv1e/i36pixNt9+9vfTo8ePfK5z32u3KMA0Iw9+OCDGT9+fO66666GY7vuumvOOuusnHfeeRu8sRQAwOZ49dVX841vfCM/+9nPGj41o3Xr1jn++OMzceLErTpEJFtxjACAIv3lL3/JggUL0r59+/Tt2zdt2rQp90gAQAuwcuXKPPTQQ1m7dm0+8pGPZPfddy/3SI1CjAAAAAAK5b2lAAAAQKHECAAAAKBQYgQArMfZZ5+dgQMH5swzz1zv+VtvvTUf/vCHM2DAgIInAwCas429Bpk6dWoOPfTQ9OnTJz/+8Y8Lnq7xiBEA8A4PP/xwVq5cmXvuuSdr1qzJQw899K41hxxySB555JEyTAcANFeb8hrkpJNOyt13350HHnggV111VRmmbBxiBAC8wwMPPJAhQ4YkSQYPHpzf//73Oe+881JfX5+jjjoqixcvTqdOnbLddtuVeVIAoDnZlNcgb32i15o1a7LffvuVc9zNIkYAwDvU1NSkqqoqSdKhQ4fU1NTkhRdeyJgxY3Lcccela9euZZ4QAGiONvU1yEUXXZR99903vXv3Lue4m0WMAIB36NChQ2pra5MktbW16dixY0477bRcf/31GT16dJmnAwCaq019DXLBBRfkmWeeyQ033JAVK1aUa9zNIkYAwDv069cvv/vd75Ikd9xxRw455JB897vfzYUXXpjq6uoyTwcANFeb8hpk9erVSZJtt90222+//VZ72agYAQDv0KtXr7Rt2zYDBw5M69atc//992f48OEZO3Zs/vznP+exxx7LH/7whwwePDjz58/P4MGD8/rrr5d7bABgK7cpr0G+//3vZ9CgQfmXf/mXfOYzn8kOO+xQ7rH/KRWlUqlU7iEAAACAlsM7IwAAAIBCiREAAABAocQIAAAAoFBiBAAAAFAoMQIAAAAolBgBAAAAFEqMAAAAAAolRgAAAACFEiMAAACAQokRAAAAQKHECAAAAKBQYgQAAABQKDECAAAAKJQYAQAAABRKjAAAAAAKJUYAAAAAhRIjAAAAgEKJEQAAAEChxAgAAACgUGIEAAAAUCgxAgAAACiUGAEAAAAUSowAAAAACiVGAAAAAIUSIwAAAIBCiREAAABAocQIAAAAoFBiBAAAAFAoMQIAAAAolBgBAAAAFEqMAAAAAAolRgAAAACFEiMAAACAQokRAAAAQKHECAAAAKBQYgQAAABQKDECAAAAKJQYAQAAABRKjAAAAAAKJUYAAAAAhRIjAAAAgEKJEQAAAEChxAgAAACgUGIEAAAAUCgxAgAAACiUGAEAAAAUSowAAAAACiVGAAAAAIUSIwAAAIBCiREAAABAocQIAAAAoFBiBAAAAFAoMQIAAAAolBgBAAAAFEqMAAAAAAolRgAAAACFEiMAAACAQokRAAAAQKHECAAAAKBQYgQAAABQKDECAAAAKJQYAQAAABRKjAAAAAAKJUYAAAAAhRIjAAAAgEKJEQAAAEChxAgAAACgUGIEAAAAUCgxAgAAACiUGAEAAAAUqkXHiOuvvz49evTIDjvskKFDh2bs2LEZOXJkuccCAACAZq3FxoipU6dm7NixmTZtWl555ZUce+yxmTx5cg4++OByjwYAAADNWouMEa+++mrOOeecTJkyJX379k1FRUVGjx6durq6hhhx3XXXpV+/funXr1/uuuuuMk8MAAAAzcc25R6gHObOnZv6+vocffTRDcdefPHFJMnBBx+cmpqaXH755XnggQeycuXKDB48OA8//HBatdoy7eass85KkkyaNGmz1gAAAMDWoEXGiGXLlmXnnXde59j06dOzyy67ZNddd81tt92Www47LG3btk3btm2z++6759lnn023bt22yDx/+tOfMnfu3EyePHmjazdlDQAAADQFpVJpvcdbZIzYf//98/TTT2fu3Lnp169ffv3rX6e6ujr9+/dPkqxYsSKdOnVqWN+pU6esWLFii8WIJDnssMMyZ86cDZ4fNGhQkrznGgAAANgatMh7RvTp0yfnn39+TjjhhOy5556ZN29e+vbt23C/iM6dO+ell15qWF9TU5POnTuXa1wAAABoVlpkjEiSiy66KCtWrMiyZcsyefLkPPXUUw0xom/fvrnnnnuyevXq/P3vf89zzz2Xvffeu7wDAwAAQDPRIi/TeKfa2tosWrSoIUZ07NgxZ511VsOlERMnTtxiN68EAACAlkaMSDJ//vxUVlame/fuDcdOPfXUnHrqqWWcCgAAAJonMSJJ//79U1tbW+4xAAAAoEVw7QEAAABQKDECAAAAKJQYAQAAABRKjAAAAAAKJUYAAAAAhRIjAAAAgEKJEQAAAEChxAgAAACgUGIEAAAAUCgxAgAAACiUGAEAAAAUSowAAAAACiVGAAAAAIUSIwAAAIBCiREAAABAocQIAAAAoFBiBAAAAFAoMQIAAAAolBgBAAAAFEqMAAAAAAolRgAAAACF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\n",
      "text/plain": [
       "<Figure size 1384.6x1282.26 with 1 Axes>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "q = QuantumRegister(5, 'q')\n",
    "c = ClassicalRegister(5, 'c')\n",
    "\n",
    "shor = QuantumCircuit(q, c)\n",
    "circuit_aperiod15(shor,q,c,7)\n",
    "shor.draw(output='mpl')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAdAAAAFWCAYAAADZtMzFAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADl0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uIDMuMC4yLCBodHRwOi8vbWF0cGxvdGxpYi5vcmcvOIA7rQAAIABJREFUeJzt3Xl8VOXZ//HPRRAKCGg0xqAiIjaipRjEHUFU+rgvaLUupdqfD25FLVXb+tS1ap+qKLZ1qxXX8lStqHWrGwouFJVNFEhVNoGg7CKKgXD9/rhP0iEmkDmZzJxkvu/XKy8zZ04m13iT+Z7lPtcxd0dERETS0yrXBYiIiDRHClAREZEYFKAiIiIxKEBFRERiUICKiIjEoAAVERGJQQEqIiISgwJUREQkBgWoiIhIDK1zXUAubbPNNt61a9dclyEiIgkyderUpe5etLn18jpAu3btytixY3NdhoiIJEhhYeG8hqynQ7giIiIxKEBFRERiUICKiIjEoAAVERGJQQEqIiISgwJUREQkBgWoiIhIDApQERGRGBSgIiIiMShARUREYlCAioiIxKAAFRERiUEBKiIiEoMCVEREJAYFqIiISAwKUBERkRgUoCIiIjEoQEVERGJQgIqIiMSgABUREYlBASoiIhKDAlRERCQGBaiIiEgMClCRyCuvvMK+++7L3nvvzciRI7/1/B133MH+++9Pv379OOGEE/j0009rnluwYAGDBw9mv/32Y//992f+/PkAuDvXX389++yzD/vttx/33HNP1t6PiDSt1rkuQCQJqqqquPzyyxkzZgxdunThsMMO44gjjmD33XevWef73/8+Y8eOpX379owaNYqrr76aUaNGAXD++eczfPhwBg4cyJdffkmrVmHbdPTo0SxcuJCJEyfSqlUrlixZkpP3JyKZpz1QEWDSpEnssssudOvWjTZt2jB48GBeeOGFjdY5+OCDad++PQB9+/Zl0aJFAMyaNYv169czcOBAALbccsua9e6//34uu+yymkAtKirK1lsSkSamABUBKioq2GGHHWoed+nShYqKinrXf+SRRzj88MMB+OSTT+jcuTNDhgxhwIABXHXVVVRVVQEwZ84cnnzySQ499FB++MMf8sknnzTtGxGRrFGAiqTpscceY8qUKQwbNgyA9evXM2HCBK677jpeffVV5s6dy+jRowGorKykbdu2jB07liFDhtT8jIg0fwpQEaCkpISFCxfWPF60aBElJSXfWu/1119nxIgRjB49mrZt2wJhb7VXr15069aN1q1bc/TRR/P+++/XPHfssccCcMwxx/Dhhx9m4d2ISDYoQEWAPn36MHv2bObNm0dlZSVjxozhiCOO2Gid999/n+HDhzN69OiNzmX26dOHVatWsXTpUgDGjx9PaWkpAEcddRRvvPEGAG+99RY9evTI0jsSkaamWbgiQOvWrbnppps4+eSTqaqq4owzzqBnz57ceOONlJWVceSRR3L11VezZs0azj77bAB23HFHRo8eTUFBAddddx0nnHAC7s5ee+3FkCFDALjkkksYOnQod911Fx06dOD222/P5dsUkQwyd891DTlTVlbmY8eOzXUZIiKSIIWFhZPcve/m1tMhXBERSUtjmo5su+229O/fn/79+3P66afXLL/wwgvZa6+9ap6bPn16Vt5LY+gQroiINFhjm460a9eO8ePH1/na1157Lccff3xW3kcmaA9UREQarDFNR1oaBaiIiDRYY5qOAKxdu5ZDDz2UQYMG8dxzz2207g033EC/fv244oor+OabbzJffIbpEK6IiDSJ6qYjzz77bM2yadOm0aVLF+bOncvxxx/PHnvswS677MKVV15JcXExlZWV/PznP+f222/n8ssvz2H1m6c9UBERabDGNB2BsMcK0K1bN/r161fTdGT77bfHzGjbti2nn346kydPbuJ30ngKUBERabDGNB1ZuXJlzaHZZcuWMXHixJqmI4sXLwbCLQCfe+45evbsmaV3FJ8O4YqISIM1pulIeXk5w4cPp1WrVmzYsIGLL764Zvbuueeey9KlS3F3evXqxYgRI3L5NhtEjRTUSEFERFKokYKIiEgTUoCKiIjEoHOg0iJd/uDWuS4hY276yYpclyAiddAeqIiISAwKUBFJtMY0Lgf44osv2HPPPTe6KH/q1KkcdNBB7L333vzqV78inydTSnwK0ByJ+6Hw6aefcsghh9C/f38OOOAA7r///pqfGTNmDP369eOAAw7gmmuuydZbEWky1Y3LH3vsMSZMmMATTzzBrFmzNlqnunH5m2++yXHHHcfVV1+90fM33ngjBx544EbLLr30UkaOHMl7773HJ598wiuvvNLk70VaHgVoDjTmQ6G4uJgXX3yR8ePH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\n",
      "text/plain": [
       "<Figure size 504x360 with 1 Axes>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "backend = BasicAer.get_backend('qasm_simulator')\n",
    "sim_job = execute([shor], backend)\n",
    "sim_result = sim_job.result()\n",
    "sim_data = sim_result.get_counts(shor) \n",
    "plot_histogram(sim_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see the measurements yield $x = 0, 2, 4$ and $6$ with equal(ish) probability. Using the continued fraction expansion for $x/2^3$, we note that only $x = 2$ and $6$ give the correct period $r = 4$, and thus the factors $p = \\text{gcd}(a^{r/2}+1,15) = 3$ and $q = \\text{gcd}(a^{r/2}-1,15) = 5$. \n",
    "\n",
    "Why don't you try seeing what you get for $a = 2, 8, 11, 13$?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [default]",
   "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}