Shor's Algorithm in Cirq.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Python 3.7.7\n",
      "\n",
      "Cirq version 0.7.0\n"
     ]
    }
   ],
   "source": [
    "# Imports\n",
    "\n",
    "import sys\n",
    "'''\n",
    "!{sys.executable} -m pip install --user -q cirq\n",
    "!{sys.executable} -m pip install --user -q google-api-python-client==1.8.0\n",
    "'''\n",
    "import cirq\n",
    "import math\n",
    "import random\n",
    "import numpy as np\n",
    "import sympy\n",
    "!{sys.executable} --version\n",
    "print(\"\\nCirq version \" + cirq.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quantum Computing Simulation using Google's cirq library for Python\n",
    "### Dmitri Friedenberg\n"
   ]
  },
  {
   "attachments": {
    "b276a9d7-7f0a-4829-91d2-9cd45cdafe5e.png": {
     "image/png": "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BShAAQpQgAIUoAAFKEAB5xVgqHfetmfNKUABClCAAhSgAAUoQAEKUMDBBRjqHbwBWXwKUIACFKAABShAAQpQgAIUcF4BhnrnbXvWnAIUoAAFKEABClCAAhSgAAUcXICh3sEbkMWnAAUoQAEKUIACFKAABShAAecVYKh33rZnzSlAAQpQgAIUoAAFKEABClDAwQUY6h28AVl8ClCAAhSgAAUoQAEKUIACFHBeAYZ652171pwCFKAABShAAQpQgAIUoAAFHFyAod7BG5DFpwAFKEABClCAAhSgAAUoQAHnFWCod962Z80pQAEKUIACFKAABShAAQpQwMEFGOodvAFZfApQgAIUoAAFKEABClCAAhRwXgGGeudte9acAhSgAAUoQAEKUIACFKAABRxcgKHewRuQxacABShAAQpQgAIUoAAFKEAB5xVgqHfetmfNKUABClCAAhSgAAUoQAEKUMDBBRjqHbwBWXwKUIACFKAABShAAQpQgAIUcF4BhnrnbXvWnAIUoAAFKEABClCAAhSgAAUcXICh3sEbkMWnAAUoQAEKUIACFKAABShAAecVYKh33rZnzSlAAQpQgAIUoAAFKEABClDAwQUY6h28AVl8ClCAAhSgAAUoQAEKUIACFHBeAYZ652171pwCFKAABShAAQpQgAIUoAAFHFyAod7BG5DFpwAFKEABClCAAhSgAAUoQAHnFWCod962Z80pQAEKUIACFKAABShAAQpQwMEFGOodvAFZfApQgAIUoAAFKEABClCAAhRwXgGGeudte9acAhSgAAUoQAEKUIACFKAABRxcgKHewRuQxacABShAAQpQgAIUoAAFKEAB5xVgqHfetmfNKUABClCAAhSgAAUoQAEKUMDBBRjqHbwBWXwKUIACFKAABShAAQpQgAIUcF4BhnrnbXvWnAIUoAAFKEABClCAAhSgAAUcXICh3sEbkMWnAAUo4AgC/+///T/ExcXh+fPn/E8DyTEgHhcJCQmOcBizjBSgAAUoQIEcKcBQnyObhYWiAAUo4PgCt27dQlBQEPLnzw8PDw8UL16c/2lg9RjImzcvihYtivHjx+PJkyeOf/CzBhSgAAUoQIFsFGCoz0Zs7ooCFKCAMwgkJSWha9euKFGiBH799Vc8e/bMGarNOn6kwP379zFq1CgULlwYwcHB0Ol0H7lFrk4BClCAAhRwDgGG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WPwXOHv2rD744APmlPefjDURQAABBBAocQFCfYkPAQ1AAAEEEAikgFGsbd68eerYsaOqVKmiJ554Qjt27AjkISy3L2NO+f79+3svrzfmlF+2bJmYU95yw0yHEEAAAQQsKkCot+jA0i0EEEAAAXmLuL388suqU6eOmjdvrrfffltGsTcWKbs55RMSEqBBAAEEEEAAAZMJEOpNNmA0FwEEEAgJgZSTOrQzVt+u3ahtPyX4zKdekP5fuHBBMTExuu+++7xno3v06KHVq1fLKAIXSotxO8KiRYvS55R/+OGHAzen/LmD2hJ7QN7ZA0MJlb4igAACCCBQwgKE+hIeAA6PAAIIIJBR4LS2TovSddUvV732vTRwUF91alpNf2zcTX9fE+fnPOwZ95f18enTpzV16lRdf/31qlmzpl544QXt27cv64oWemXbtm167LHHlDan/Pz581XoOeU9p/Tjus8UPX+6xg+/T21qlVFY1f5almghOLqCAAIIIICACQQI9SYYJJqIAAIIhIaAR8ei+6u206k/DVqpk2mdTvxOL7UsJUfl2/TuTzlPvZa2en7+3b17t4YPH65q1arpxhtv1KxZs3TuXB6TtefnACW47vHjx7PMKX/48OHAtShlj95/8B79tc+DevqpzvqT0ybHH/vpU0J94IzZEwIIIIAAAn4IEOr9QGIVBBBAAIFiEPD8R+90/IPs9nD9bfH5DAdM1qanG8lpc6rJc1tUFPXsjaJwS5cuVdeuXVWmTBm1bNlS69evz9AGczx0u91atWqVd3q/cuXKqU+fPsUyp7z7h7G6zkWoN8enhFYigAACCFhNgFBvtRGlPwgggIBZBRI/Vb/LHbKFXaHHv0nK0Au39k9oLZfNrlI3v6tfivA2eOOy/KpVq3or5l911VXecPzqq6/q6NGjGdoTfA8zzynfvXt379R+0dHRxdJYQn2xMHMQBBBAAAEEshUg1GfLwosIIIAAAsUucGKG7ihtk83ZQEPXZzwf79HhN25SKZtNrmajtCMl8C0zCuY99dRTaty4sQ4cOJB+gNjYWD300EPegNypUyctXrxYRrG5YFjymlPeuI++Vq1aGj9+fJE3l1Bf5MQcAAEEEEAAgRwFCPU50vAGAggggECxChyfnhrqr8wS6g/9IzXUX/OStgc41BvhuHPnzrrllltkFNHLbjGKys2bN08dO3ZUlSpVvGfyd+zYkd2qRf5afuaUN6ata9GihQYMGKDff/+9yNpGqC8yWnaMAAIIIIBAngKE+jyJWAEBBBBAoFgEEpfovkrG5fd19GiM7+X3e19tJZfNplIdJuvnAF5+/9///lfXXHON92y8cV+9P8uhQ4f08ssvq06dOmrevLnefvttnThxwp9NC7xOYeaUNwr/3X333Wrfvr1OnkwvP1jgtmS3IaE+OxVeQwABBBBAoHgECPXF48xREEAAAQTyEnAf0pvty8huv0zdP85YgT5Z3z5Z31sor+HTGwNWKO+7777zTmn3xhtv5NWybN+/cOGCYmJivMXowsPD1aNHD2+ROuNS/kAsgZxT3mjT008/7a0RUBTT9xHqAzHi7AMBBBBAAIGCCRDqC+bGVggggAACARfwKOGTfqrpdCji3nk6mpaNT3+jJxu75AjvqLf2BmZKuyVLlngL4i1fvjwgvTAu2582bZquv/56RUZG6vnnn1dBw3PGOeWNWwKMOeUTEwMzT9zMmTO90/etXbs2IP1O2wmhPk2CfxFAAAEEECh+AUJ98ZtzRAQQQACBHAVOa+u0gbohspJqXn+3+t7fQx0aXK4qTf+qsTG/KC3n57i5H2+89tpr3gJy27dv92Pt/K/yww8/aPjw4d7w3LZtW82aNUvGJfC5LUU+p3yGg3/99dfeHzRmz56d4dUCPPT8R1M611C16jUUWaOKwitUUMXwyxURGakaEdXV+uXvCrBTNkEAAQQQQACB/AoQ6vMrxvoIIIAAAkUv4D6jI3u3K3bzd9p96IQy3mFf0IMbheKioqK8c9AXxxR1xj36S5cu9d7PXqlSJe+xjSJ3aYsxp/xnn32me++9V8bl+3379i2WOeWN4+/du1f16tXzXlFg3EbAggACCCCAAALmFSDUm3fsaDkCCCCAgJ8CRiE7o1Bct27ddP78eT+3Ctxq8fHxmjRpkpo0aaIrr7zS+69xmX6rVq00ffp0/e9//wvcwfzck3F1wI033uj9UcGo7s+CAAIIIIAAAuYUINSbc9xoNQIIIICAnwL//ve/vQXiRowYoWA4K71582Zve/bs2eNnD4puNaMYX79+/XTdddcpLi6u6A7EnhFAAAEEEECgyAQI9UVGy44RQAABBEpawCgIFxERoffff7+kmxLUxx87dqx3ir7vv/8+qNtJ4xBAAAEEEEAgqwChPqsJryCAAAIIWEDAKARXrVo1rVmzxgK9KfouLFq0SFWqVNHKlSuL/mAcAQEEEEAAAQQCJkCoDxglO0IAAQQQCAYB4xL75557TvXr19ePP/4YDE0yTRtiY2NVo0YNvfXWW6ZpMw1FAAEEEEAg1AUI9aH+CaD/CCCAgIUEjIJv3bt310033SSjEBxL/gUOHz6spk2b6tFHH5VRoT+YFk/SacUd2qsdW7Zq/6lATHAYTL3zpy1uJScH15j402rWQQABBBAoWgFCfdH6sncEEEAAgWISMAq9GQXfHnjgARkF4FgKLnDmzBl16tRJt99+e4lU5s+u5cmbx6trq6aKLO+QzRGhASsTs1styF/zKG79dD3d507dduutuvXWW3V7r39oix8fV8+RaA1pUVlOZ0U16T9PB8j2QT7WNA8BBBAoPgFCffFZcyQEEEAAgSISMAq81a5dW+PGjSuiI4Tebo2z9I899ph3+r1Dhw4FCcBxfdC5nOzlO2vWsSBpUgGacXJON1Ww22Sz2eSIGKC8f5/wKGHqbSqduo3N1UYTs0v1KXu0YO56mfHnjgIwsgkCCCCAQKoAoZ6PAgIIIICAqQWMwm5Ggbf/+7//M3U/grXx77zzjvc+e2MqvhJfzq9QVHWHXK0naJ+Jz1Qnrhyo6o78hHop5Ye3dVs1p+z2MF1+03htzXJ23639792hGl1m6XSJDxQNQAABBBAoTgFCfXFqcywEEEAAgYAKGAXdjMJuW7ZsCeh+2ZmvwKpVq1S1alUtWLDA941ifpa8+Rk1cjrV6JnNypJpi7kthTlc4mf5D/XG8dwnD2jbtn06kZL16Oe/+7vaVnSodGdCfVYdXkEAAQSsLUCot/b40jsEEEDAkgLGpeFGIbc///nP+s9//mPJPgZbp3bu3Omdy3706NEl1DS39r/eRi5HhKKWny+hNgTmsAUN9TkdPXHP+7q3rkt2m41QnxMSryOAAAIWFiDUW3hw6RoCCCBgRYH//e9/3gJud955p4yCbizFJxAfH69WrVqpb9++SkpKKr4De490XLO7XiZH+S6adSxZCbvXaPmyGG37+awCVQc/KX631q2K1pIVa7U7Ph/XAriTlZ+i9L6hPkqLdyzWi/e2Ur1qlyui/vXq9tx87Uz/aHsU9+0UjXgoSv379/f+RQ2Zlnr5vVvxa0brlhoXA71xj76zdjv1NdYb8Izm7s3mlH4xjxqHQwABBBAoegFCfdEbcwQEEEAAgQAJGAXbmjRposcffzzoplsLUBeDfjeJiYnq2bOn2rRpo19//bX42pu4QgOM++mb9NST/btr4Kipmjd3ovq1bKKukzbpVCFaknRotcb1bqVmHQdqzPQFil40TaPu76qoGT/keZm/+9Bsda9ZSqXr9NWCo/79vJAx1NvLRKjmlS3UbfAj6tM6Ui5vMTyHKt30qr5LvyDBo8NvtVeZtOJ6le7TJ0Y1PPcBLZvwrKJaV5HDdvEefWeDLhr27LN69vnxWppdMb1COLEpAggggEBwChDqg3NcaBUCCCCAQCaBTZs2qXr16nr33XczvcPT4ha4cOGCXnzxRV1xxRXas2dPsRw+OXaEGjvtckZ20Ts7zqUf8+zyKNUo1UjDNxTsyoHTmyfotshwNX9ipY6mFt/zJKzSiJtqqmKj4dqYxwn75A3D1MBpk911tUZu9e/MuE+oL3+jxu9KrVd/foOGN3Z6q+Lb7OXV4c19SqsHmLi8v6qmFddLC/VehWTFjmgsZ2qo55769I8GDxBAAIGQESDUh8xQ01EEEEDAvAJGgTajUNvq1avN2wkLtvyjjz7yjstXX31VxL1z68CktirlqKpeC4/7HCtl12i1dDnV+Jn8V+d3H56nnjWd+sNfxmlXhvCeFPOI6oS5FPm3jxWX58n3U/r+kyl679NdSr9i3qeFWZ9kDPW+U9ol6eshdRXmDeh2lcpQ5d9nG0J9VlReQQABBEJYgFAfwoNP1xFAAAEzCBiF2erWratdu3aZobkh18Z169YpIiJC06ZNK8K+n9BH91SQo9xdej/BN2UnxTyqOmEOVeu/PJ/HP6Gl/WspzBGhPotPZto2UXEHj+is76EyrVPwpz4B3Weeerf2TWgtV+pZd0eVB7Qs9SS+zzaE+oLjsyUCCCBgQQFCvQUHlS4hgAACVhAwCrH16dPHW5jNKNDGErwC+/fvV8OGDTV06FB5PEWQhBNXaVBkmFw3vKaf0q5H93K4dXDSjXLZnGo8IjZfQJ74D9S5gl2Oav0UfTZfmxZ6ZZ+A7hPqPToyuYNKpYZ6e8WeWpR6X73PNoT6Qo8BO0AAAQSsJECot9Jo0hcEEEDAIgJGATajEFuvXr1kFGZjCX6BkydPqmPHjuratavOnbt0z3sgWp52iX2DYRt8C9d5jml21wqyO6orann+jpm0apAiw+wq22mGEgLRyHzswyegZwr1h99slx7qw/70mL5JLRXgsw2hPh/arIoAAghYX4BQb/0xpocIIICAqQSMwmtGAbaXXnpJRkE2FvMI/P777xo0aJCaNWum//73vwFreNLXQ1TXWU73zDnts09PwkfqFu6Qq+FQrUuvFO+zSo5Pzi/socvsTtV/8lvfHwpy3CJwb/gE9IgBWpH+u5Vbu8dcm3r5vUOV7v1YaTcG+GyTOdQ/exWF8gI3POwJAQQQMJ0Aod50Q0aDEUAAAesKGAXXjIJ4c+bMsW4nQ6Bnr7/+umrWrKl//etfAentxTP1lXSfdx63tF2maNe4G1TWVVcPLInLMFe9R3HrZurVCfP13cmcbwVI2TZS17icqv/UuuxDfdKPmjNivL7O68cCzzFtmvWqXpuzRSdyPlxao73/+gT0P/bTp+mhPkmfP1jzYqG8sNoa9Nml0ns+2/iE+hRtHXl1+n34pTvN1AnjKInndN7P9vg0jicIIIAAAqYTINSbbshoMAIIIGBNAaPQmlFwbf369dbsYIj16tNPP1WVKlUUHR1d+J6n7NDoluXVbNR2pU0adyZ2jNqGV1H7sRt956hPWqMhfwqTzRam2g+uVo4X5bv3acrtlVX2urHambbT1JaeP7haY3t20sMLDqQfL6dOJK99QvWcNtmcTfTclgwl9HPawMjbnw1U9dTp6eyu6zVuT2qhgMT1GtbQKZvdpbp9F+pIhlB+blEvhafOU28v20Wz0y9a8OiX6XeoXOp7zivu19zYNXpr8HAtjM+wg1zaw1sIIIAAAuYWINSbe/xoPQIIIGB6AaOwmlFgrVGjRjIKrrFYR8A4U2+csZ8wYUKhO3Vu22R1u/oG9R37jiaP7KO2LW/X8AV7soZ2z8/6+IEGqlixhmp2GJ0lsGdsiCcuRqM7N9U1XYZp4rSZmjpplB67v4d6DnxFn+zxr3qe58giDWgUrkpNH9HSTJX5Mx4r42Mj1NcoW1Mdnhyr4bfXVUTzPhr1xj/0QrcGKleutto/Pl9708/eexS/fqoebFVZjtQCejZHRbWMektf/5z6Y8DZzRrXvqpcaaG//FUauPBQ+hz3GY/NYwQQQAAB6wkQ6q03pvQIAQQQMI2AUVDNKKx2880369SpU6ZpNw31X+DIkSNq3ry5Bg4cKOOe+0ItSfH6YeNabdh+WKd8quBns9eUHRo7aJx2ZToLn3VNt84c3q51a77Rhq0/KiG1MF3W9QL3ivvnTYrZeTL1loFEHd26WovmzNHCFWu1O96/s/1ZWuM+rt0xizV/4Ur980gxdCJLA3gBAQQQQKCkBAj1JSXPcRFAAIEQFzAKqRkF1QYPHqyUlDyTV4hrmbv7xo83d999t7c6vlElv1iWE3M1+NFo+Xe+vVhaxEEQQAABBBAoEgFCfZGwslMEEEAAgdwE0i7LnjhxYm6r8Z6FBIzbLIYPH+6dz37fvn1F3DO3Dkx5SC+syfGO+iI+PrtHAAEEEECg+AQI9cVnzZEQQAABBCRv4TSjgNrSpUvxCEGBGTNmeAsifvvtt0XW+8TvJ6v/Q3N0KK9L9IusBewYAQQQQACB4hMg1BefNUdCAAEEQl7AKJhWq1Ytbdu2LeQtQhkgJibGO3XhRx99VAQMbh34PFqxuUxnVwQHZZcIIIAAAgiUmAChvsToOTACCCAQOgJGgTSjUFqLFi1kFE5jQWDv3r2qV6+eXnjhBV24cAEQBBBAAAEEECigAKG+gHBshgACCCDgn4BRGK1jx47eQmlGwTQWBNIEfv31V7Vt21Y9evTQb7/9lvYy/yKAAAIIIIBAPgQI9fnAYlUEEEAAgfwJGAXRGjZsqKefflpGoTQWBDILJCcnq2/fvrr++usVHx+f+W2eI4AAAggggEAeAoT6PIB4GwEEEECgYALr1q3zFkQzCqOxIJCXwNixY1WnTh3t3Lkzr1V5HwEEEEAAAQQyCBDqM2DwEAEEEEAgMAJGAbRq1arJKIjGgoC/AgsXLvQW0Pvss8/83YT1EEAAAQQQCHkBQn3IfwQAQAABBAInYBQ8MwqfGQXQjEJoLAjkV2Dz5s2qUaOG3n777fxuyvoIIIAAAgiEpAChPiSHnU4jgAACgRcwCp0ZBc+MwmdGATQWBAoqcPjwYTVt2lRDhgyR281k8wV1ZDsEEEAAgdAQINSHxjjTSwQQQKBIBYwCZ0ahs379+skofMaCQGEF/ve//+mOO+7w/hmPWRBAAAEEEEAgewFCffYuvIoAAggg4KeAUdisbt26MgqdsSAQSAHjLL1xtt44a2+cvWdBAAEEEEAAgawChPqsJryCAAIIIOCnwKpVq7yFzYwCZywIFJWAcX+9cZ+9cb89CwIIIIAAAgj4ChDqfT14hgACCCDgp0Ba0IqNjfVzC1ZDoOACRkX8qlWrih+QCm7IlggggAAC1hQg1FtzXOkVAgggUGQCxiXRjz32GJdEF5kwO85JwLjVw5jLfsyYMTmtwusIIIAAAgiEnAChPuSGnA4jgAACBRcwCpZ16tSJ4mUFJ2TLQgrExcV5izL27dtXSUlJhdwbmyOAAAIIIGB+AUK9+ceQHiCAAALFIsA0Y8XCzEH8EGD6RD+QWAUBBBBAIGQECPUhM9R0FAEEECi4gHHfvFGozLiPngWBYBC4cOGCXnjhBdWrV0979+7N0iRjikWmwsvCwgsIIIAAAhYUINRbcFDpEgIIIBBIgUWLFnkLlBmFylgQCDaBDz/80Pv5jImJ8Wla7969NXnyZJ/XeIIAAggggIAVBQj1VhxV+oQAAggESMCYe94oTGYUKGNBIFgFvv32W0VERGjGjBnpTdy4caOuvPJKGWf0WRBAAAEEELCyAKHeyqNL3xBAAIECCiQnJ6tfv37egmRGYTIWBIJdYN++fWrYsKGGDx8uj8fjbW7Lli0VHR0d7E2nfQgggAACCBRKgFBfKD42RgABBKwncPz4cd14443q0aOHjIJkLAiYReDkyZPq0KGD7r77bp07d07ffPONateurTNnzpilC7QTAQQQQACBfAsQ6vNNxgYIIICAdQV+/PFH1a9f31uAjMuWrTvOVu7Z77//roEDB6p58+Y6cuSIBgwYoMcff9zKXaZvCCCAAAIhLkCoD/EPAN1HAAEE0gSMQmPVqlWTUXiMBQGzCMTHx+svf/mLhgwZIqOoo/HcWCZMmKCaNWt6z9ZXr15dmzdvNkuXaCcCCCCAAAL5EiDU54uLlRFAAAFrCsycOdNbaMwoOMaCgNkEvvvuO02aNEldu3ZV5cqVdeedd2r16tVasmSJqlSp4r3P/s9//rOMs/gsCCCAAAIIWE2AUG+1EaU/CCCAQD4EjIJiTz/9tLfAmFFojAUBswskJiZq9uzZatGihRo0aOD9fNeoUUONGjXSuHHjzN492o8AAggggEAWAUJ9FhJeQAABBEJD4Pz587rnnnu8hcWMAmMsCFhNwJjWzpivPjw8XJUqVVLp0qWVeT57q/WZ/iCAAAIIhJ4AoT70xpweI4AAAjp69Kj3TKZRUIxLkvlAWF3A+LwbV6Q4nU6FhYVp3bp1Vu8y/UMAAQQQCCEBQn0IDTZdRQABBAyBbdu2qVatWt5CYoggYBaBX375RWPHjtWYMWMK/PfEE0+obNmystls6tu3b4H3U5g2FNe2hw8fNsvQ0k4EEEAAgUIKEOoLCcjmCCCAgJkEli5d6i0cFh0dbaZm01YENHHiRBlV7EeOHFmovxdffFH16tXTo48+Wqj9FLYdRbl9nTp1NGrUKD41CCCAAAIhIkCoD5GBppsIIICAUR3cmOJr69atYCBgOoHXX3/dewm96RpeAg0ePXq0XnrppRI4ModEAAEEECgJAUJ9SahzTAQQQKAYBVJSUjR48GA1a9ZM//3vf4vxyBwKgcAJEOr9tyTU+2/FmggggIAVBAj1VhhF+oAAAgjkIHDq1CndfPPN6tKli86dO5fDWryMQPALEOr9HyNCvf9WrIkAAghYQYBQb4VRpA8IIIBANgIHDhzwzs09bNgwGfPRsyBgZgFCvf+jR6j334o1EUAAASsIEOqtMIr0AQEEEMgksH79ekVERGjatGmZ3uEpAuYUINT7P26Eev+tWBMBBBCwggCh3gqjSB8QQACBDAJz585V1apV9dVXX2V4lYcImFuAUO//+BHq/bdiTfhP7PoAACAASURBVAQQQMAKAoR6K4wifUAAAQQkXbhwwTtF1xVXXKE9e/ZggoClBPIT6j1JpxV3aK92bNmq/adC79YTQr2lPvp0BgEEEMhTgFCfJxErIIAAAsEvkJiYqF69eqlNmzb69ddfg7/BtBCBfAr4G+qTN49X11ZNFVneIZsjQgNWJubzSOZfnVBv/jGkBwgggEB+BAj1+dFiXQQQQCAIBRISEnTDDTeoT58+SkpKCsIW0iQECi/gb6i/eKTj+qBzOdnLd9asY4U/ttn2QKg324jRXgQQQKBwAoT6wvmxNQIIIFCiArt27VLdunVl/Ec8CwJWFshXqD+/QlHVHXK1nqB9biurZN83Qn32LryKAAIIWFWAUG/VkaVfCCBgeYHPP//cWxDv448/tnxf6SAC+Qn1yZufUSOnU42e2azkEKQj1IfgoNNlBBAIaQFCfUgPP51HAAGzCrz77ruqXr26Nm3aZNYu0G4E8iXgf6h3a//rbeRyRChq+fl8HcMqKxPqrTKS9AMBBBDwT4BQ758TayGAAAJBIeB2u/X444+rSZMmOnToUFC0iUYgUBwC/of645rd9TI5ynfRrGPJSti9RsuXxWjbz2eVnzr47uRkBceV+0mK371Oq6KXaMXa3Yr349IDQn1xfCI5BgIIIBA8AoT64BkLWoIAAgjkKnDmzBndeeeduu222/S///0v13V5EwGrCfgd6hNXaIBxP32Tnnqyf3cNHDVV8+ZOVL+WTdR10iadyhPGrUOzu6tmqdKq03eBjubnl4A8952fFZJ0aPU49W7VTB0HjtH0BdFaNG2U7u8apRk/5J7sCfX5cWZdBBBAwPwChHrzjyE9QACBEBA4ePCgypQpo3bt2iklJSUEekwXEfAV8DfUJ8eOUGOnXc7ILnpnx7n0nZxdHqUapRpp+Ia8ZohI1oZhDeS02eW6eqS2pv/PLVlb3uilW9q39/7v0Pjfov9/7dX+1r56Z1v6ztLblf2D09o84TZFhjfXEyuPpl4x4FHCqhG6qWZFNRq+MddaAYT67FV5FQEEELCqAKHeqiNLvxBAwFICRpX7yy67TGvWrLFUv+gMAv4K+Bfq3Towqa1KOaqq18LjPrtO2TVaLV1ONX5ms8/r2T459b0+mfKePt11xuft0/s2aPXKFVqxIv9/K1dv1H7f3fns+9ITtw7P66mazj/oL+N2ZQjvSYp5pI7CXJH628dxud5KQKi/pMkjBBBAIBQECPWhMMr0EQEETC+wd+9eNWzY0PT9oAMIFFTAv1B/Qh/dU0GOcnfp/QTf6+aTYh5VnTCHqvVfXtAmFM92J5aqf60wOSL6aPHJTIdMjNPBI3nXBiDUZ3LjKQIIIGBxAUK9xQeY7iGAgDUECPXWGEd6UXABv0J94ioNigyT64bX9JNPlTu3Dk66US6bU41HxBa8EUW+pUfxH3RWBbtD1fpF62wBj0eoLyAcmyGAAAImFSDUm3TgaDYCCISWAKE+tMab3mYV8CfUp11i32DYhgyXrUvyHNPsrhVkd1RX1PJL99lnPUpJv5KkVYMiFWYvq04zEgrcGEJ9genYEAEEEDClAKHelMNGoxFAINQECPWhNuL0N7OAP6E+6eshqussp3vmnPbZ3JPwkbqFO+RqOFTrCjx1fZLWDG2ky8qUVunS+f8rU+HPGrE+96r10nkt7HGZ7M76evLbvNb16aLPE0K9DwdPEEAAAcsLEOotP8R0EAEErCBAqLfCKNKHwgj4E+ovnqmvpPs+ScxwqBTtGneDyrrq6oEluReYS9vIc2yTZr36muZsOZGpIJ1byYmJOn/+fD7/EpWY7HM/QNqhMv2bom0jr5HLWV9Prcs+1Cf9OEcjxn+t3H6bINRnYuUpAgggYHEBQr3FB5juIYCANQQI9dYYR3pRcAF/Qr1Sdmh0y/JqNmq70iaPOxM7Rm3Dq6j92I1+zFFvtC9Za5+oJ6fNJmeT57Ql+2xd8I7ksaV73xTdXrmsrhu7M70PFzc5r4Orx6pnp4e14EBa77LfGaE+exdeRQABBKwqQKi36sjSLwQQsJQAod5Sw0lnCiDgV6iXdG7bZHW7+gb1HfuOJo/so7Ytb9fwBXvk/530Hh1ZNECNwiup6SNLlamIfgFant9NPIqLGa3OTa9Rl2ETNW3mVE0a9Zju79FTA1/5RHv8qJ5HqM+vOesjgAAC5hYg1Jt7/Gg9AgiEiAChPkQGmm7mKOBvqPfuICleP2xcqw3bD+uUP1e953jUEnzDfUaHt6/Tmm82aOuPCUrKR1MI9fnAYlUEEEDAAgKEegsMIl1AAAHrCxDqrT/G9DB3gXyF+tx3Zfl3CfWWH2I6iAACCPgIEOp9OHiCAAIIBKcAoT44x4VWFZ8Aod5/a0K9/1asiQACCFhBgFBvhVGkDwggYHkBQr3lh5gO5iFAqM8DKMPbhPoMGDxEAAEEQkCAUB8Cg0wXEUDA/AKEevOPIT0onACh3n8/Qr3/VqyJAAIIWEGAUG+FUaQPCCBgeQFCveWHmA7mIUCozwMow9uE+gwYPEQAAQRCQIBQHwKDTBcRQMD8AoR6848hPSicAKHefz9Cvf9WrIkAAghYQYBQb4VRpA8IIGB5AUK95YeYDuYh8Oabb8rlcumee+4Jqr+yZcuqQoUKQdemMWPG5CHK2wgggAACVhEg1FtlJOkHAghYWoBQb+nhpXN+CPz222/69NNPFR0dHVR/YWFhmjdvXlC1yTA6c+aMH6qsggACCCBgBQFCvRVGkT4ggIDlBQj1lh9iOmhSgVKlSikpKcmkrafZCCCAAAJWECDUW2EU6QMCCFhegFBv+SGmgyYVINSbdOBoNgIIIGAhAUK9hQaTriCAgHUFCPXWHVt6Zm4BQr25x4/WI4AAAlYQINRbYRTpAwIIWF6AUG/5IaaDJhUg1Jt04Gg2AgggYCEBQr2FBpOuIICAdQUI9dYdW3pmbgFCvbnHj9YjgAACVhAg1FthFOkDAghYXoBQb/khpoMmFSDUm3TgaDYCCCBgIQFCvYUGk64ggIB1BQj11h1bemZuAUK9uceP1iOAAAJWECDUW2EU6QMCCFhegFBv+SGmgyYVINSbdOBoNgIIIGAhAUK9hQaTriCAgHUFCPXWHVt6Zm4BQr25x4/WI4AAAlYQINRbYRTpAwIIWF6AUG/5IaaDJhUg1Jt04Gg2AgggYCEBQr2FBpOuIICAdQUI9dYdW3pmbgFCvbnHj9YjgAACVhAg1FthFOkDAghYXoBQb/khpoMmFSDUm3TgaDYCCCBgIQFCvYUGk64ggIB1BQj11h1bemZuAUK9uceP1iOAAAJWECDUW2EU6QMCCFhegFBv+SGmgyYVINSbdOBoNgIIIGAhAUK9hQaTriCAgHUFCPXWHVt6Zm4BQr25x4/WI4AAAlYQINRbYRTpAwIIWF6AUG/5IaaDJhUg1Jt04Gg2AgggYCEBQr2FBpOuIICAdQUI9dYdW3pmbgFCvbnHj9YjgAACVhAg1FthFOkDAghYXoBQb/khpoMmFSDUm3TgaDYCCCBgIQFCvYUGk64gEGwCnqTTiju0Vzu2bNX+U55ga14xtMet5GR3QI5DqA8IIztBIOAC/od6j5JOx+nQ3h3asnW/QvMrMVkB+koM+DiyQwQQQMDMAoR6M48ebUcgiAWSN49X11ZNFVneIZsjQgNWJgZxa3Nqmkdx66fr6T536rZbb9Wtt96q23v9Q1uSc1r/0uueI9Ea0qKynM6KatJ/ng4UMtsT6i/Z8giBYBLwL9Qna/P4rmrVNFLlHTY5IgbInF+JcVo//Wn1ufM27/fhrbferl7/2KK8vxI9OhI9RC0qO+Ws2ET95x1QIb8Sg+kjQFsQQACBEhcg1Jf4ENAABKwscFwfdC4ne/nOmnXMvP08OaebKthtstn8/Y9xjxKm3qbSqdvYXG00MbtUn7JHC+aulz8/dxDqzfv5oeXWFvAv1KcaHP9AncvZVb7zLJn3K/Gk5nSrILvN+E50KGLAyry/wzwJmnpb6dRtbHK1mZjND50p2rNgrtb784Vo7Y8UvUMAAQTyLUCozzcZGyCAgN8C51coqrpDrtYTtM/Ep2USVw5UdUd+Qr2U8sPbuq2aU3Z7mC6/aby2ZjmV5db+9+5QjS6zdNoPUEK9H0isgkAJCOQn1J9fEaXqDpdaT9hn4jPViVo5sLoc+Qn1StEPb9+mak677GGX66bxW7Oc3Xfvf0931OiiWf58IZbAOHNIBBBAIJgFCPXBPDq0DQGTCyRvfkaNnE41emZzlv+AM1PXEj/Lf6g3+uc+eUDbtu3TiZSsvT3/3d/VtqJDpTsT6rPq8AoC5hHwP9Qna/MzjeR0NtIzm7P8ymeeDitRn+U71Bvdc+vkgW3atu+Esnwlnv9Of29bUY7SnQn1Jvok0FQEEAgeAUJ98IwFLUHAYgJu7X+9jVyOCEUtP2/qvhU01OfU6cQ97+veui7vpaiE+pyUeB0Bcwj4Herd+/V6G5ccEVEy91diQUN9DuOZuEfv31tXLuN2JUJ9Dki8jAACCOQuQKjP3Yd3EUCgwALHNbvrZXKU76JZx5KVsHuNli+L0bafzypQdfCT4ndr3apoLVmxVrvj83Hmy52/Csy+oT5Ki3cs1ov3tlK9apcrov716vbcfO08kwblUdy3UzTioSj179/f+xc1ZFrq5fduxa8ZrVtqXAz0xj36ztrt1NdYb8Azmrs3y/mrtJ2Ky+/TKXiAQFAJ+B3qj89W18scKt9llo4lJ2j3muVaFrNNP58N2Dei4nev06roJVqxdrf8/0rM7ywdmUJ91GLtWPyi7m1VT9Uuj1D967vpufk7dekrMU7fThmhh6Iufh/27x+lIdMuXn7vjl+j0bfUuBjojcv5nbXVrq+x3gA9M3dv1jP6QTXyNAYBBBAIHgFCffCMBS1BwFoCiSs0wLifvklPPdm/uwaOmqp5cyeqX8sm6jppk04VordJh1ZrXO9WatZxoMZMX6DoRdM06v6uiprxQ56X+bsPzVb3mqVUuk5fLTjq339MZwz19jIRqnllC3Ub/Ij6tI5M/Y9Rhyrd9Kq+S78gwaPDb7VXmbTiepXu0ydG8Sf3AS2b8KyiWldJvR/VJmeDLhr27LN69vnxWppdMb1UJ0J9IT4wbIpAEQr4G+oTVwzw3k/fpOeT6t99oEZNnae5E/upZZOumrSpUN+IOrR6nHq3aqaOA8do+oJoLZo2Svd3jdKMH/L4sdN9SLO711Sp0nXUd8FRP39wzRjq7SoTUVNXtuimwY/0UevI1B8sHZV006vf6dJX4mG91b5MenG9Svd9okS5dWDZBD0b1VpVUmuW2JwN1GXYs3r22ec1fikV8ovwY8uuEUDAYgKEeosNKN1BIFgEkmNHqLHTLmdkF72z41x6s84uj1KNUo00fENS+mv5eXB68wTdFhmu5k+s1NHU4nuehFUacVNNVWw0XBvz+G/Y5A3D1MBpk911tUZuzfnMeMY2+YT68jdq/K7U8sznN2h4Y6e3Kr7NXl4d3rxU/CpxeX9VTSuulxbqvTtNVuyIxnJ6i0zZuKc+IzSPETChgH+hPvV/93anIru8o0tfiWe1PKqGSjUaroJ9JZ7W5gm3KTK8uZ5YeTS1+J5HCatG6KaaFdVo+Mbcf+hM3qBhDZyy2V26euRWP8+M+4b68jeO16WvxOFq7LxYVNRevoPeTK+Qmqjl/aumF9e7GOovDvbF/6+4uA2X35vwfwA0GQEEgkKAUB8Uw0AjELCagFsHJrVVKUdV9Vp43KdzKbtGq6XLqcbPbPZ53Z8n7sPz1LOmU3/4yzjtyhDek2IeUZ0wlyL/9rHi8jz5fkrffzJF732669LloXkcPGOo951fOklfD6mrMG9At6tUhir/PtsQ6vMQ5m0EzCvgV6h3H9CktqXkqNpLvl+JKdo1uqVczsYFKJ7n1uF5PVXT+Qf9ZdyuDOE9STGP1FGYK1J/+zguz7Pvp77/RFPe+1S70q+Xz2ssMob6TFPaJX2tIXXDUn/oLOWt8n9xb77bEOrzMuZ9BBBAIH8ChPr8ebE2Agj4JXBCH91TQY5yd+n9BN+UnRTzqOqEOVSt/3K/9nRppRNa2r+WwhwR6rP45KWXvY8SFXfwiAJ2a2rmvedY/d6tfRNay5V61t1R5QEtSz2JT6jPhMhTBCwq4FeoP/GR7qngULm73pfvV2KSYh6tozBHNfVfns8J2k8sVf9aYXJE9FHWr8Q4HTwSuPolvkPnG9B95ql379OE1q6Lod7mUJUHlqVu6rsNod5XlGcIIIBAYQUI9YUVZHsEEMgqkLhKgyLD5LrhNf3kMz+9Wwcn3SiXzanGI2KzbpfLK574D9S5gl2Oav0UfTaXFYvgLZ+AHjFAK9P/29ujI5M7qFRqqLdX7KlFqTeR+mzDmfoiGBV2iUBwCPgT6hNXDVJkmEs3vPaT7/z07oOadKNLNmdjjYjNcPlRnl3zKP6Dzqpgd6hav2gV71eib0D3CfWeI5rcoVRqqLerYs9FqT3x3YZQn+cAswICCCCQLwFCfb64WBkBBPwRSLvEvsGwDRkuCZXkOabZXSvI7qiuqOWX7rP3Z59J3v8otqtspxlK8GeDAK7jE9AzhfrDb7ZLD/Vhf3pM36SWCvDZhlAfwNFgVwgEl0DeoT7tEvsGGrbBN7h7js1WV+PHyupRyt9XYpJWDYpUmL2sOs0o9m/EnOep9xzWm+3SQn2Y/vTYN6mDRagPrk8trUEAAasJEOqtNqL0B4EgEEj6eojqOsvpnjmnfVrjSfhI3cIdcjUcqnXpZZF9VsnxyfmFPXSZ3an6T37r+0NBjlsE7g2fgB4xQCvSz9S7tXvMtamX3ztU6d6PlXZjgM82mUP9s1dRKC9ww8OeEChRgbxD/cXaG85y98j3K9GjhI+6KdzhUsOh6y5ViverN+e1sMdlsjvr68lvfX8o8GvzQq3kG9AjBqzQpa/E3Rpzberl945Kuvfj9G9Enx8CfM/UP6urUovrUSivUAPDxgggEMIChPoQHny6jkBRCVw8U19J93nncUs7Sop2jbtBZV119cCSDMWbPHFaN/NVTZj/nU763n6ftqH335RtI3WNy6n6T63LPtQn/ag5I8br67x+LPAc06ZZr+q1OVt0IpfjZTy4T0D/Yz99mv5fsEn6/MGaFwvlhdXWoM8uVZry2cYn1Kdo68ir0+/DL91ppk4YB0s8p/O5tIcp7TKOCI8RCB6BvEN96pl6n+8BSSm7NO6GsnLVfUBLMlT49MSt08xXJ2j+dydzKXKXom0jr5HLWV9Prcs+1Cf9OEcjxn+dx48FHh3bNEuvvjZHW/z9QpRvqP9jv08vhfqkz/VgzYuF8sJqD9Klr0TfbTKG+pStI3W1K636fSfNvPiFqHO5fSEGz/DTEgQQQCAoBAj1QTEMNAIBiwmk7NDoluXVbNT29CmSzsSOUdvwKmo/dqPPHPVJa4boT2E22cJq68HVuVyS796nKbdXVtnrxmpnppnozh9crbE9O+nhBQfSj5eTaPLaJ1TPOCvkbKLntmT/H8OZt80Y0O2u6zVuT2qhgMT1Gtbw4nRQdfsu1JEMofzcol4KT52n3l62i2anX7Tg0S/T71C51PecV9yvubFr9Nbg4VoYn2EHmRpBqM8EwlMEgkQg71AvpewYrZblm2nU9rQvrzOKHdNW4VXaa+zGjHPUJ2nNkD95fygMq/2gcv9KnKLbK5fVdWN3ZvreO6+Dq8eqZ6eHteBA2vFywEpeqyfqGdNyOtXkuS3Z/2CaZdOMAd0u1/XjdOkrcZgaeqcMrau+C49k+FHinBb1Ck+dp96usl1mK+0r0fPLdN1Rzn7xPnznFbp/bqzWvDVYwxfGZ9g+SyN4AQEEEEAggwChPgMGDxFAIHAC57ZNVrerb1Dfse9o8sg+atvydg1fsEeZY7vn54/1QIOKqlijpjqM3plrAzxxMRrduamu6TJME6fN1NRJo/TY/T3Uc+Ar+mSPf6WiPEcWaUCjcFVq+oiW+pahzvHYRqivUbamOjw5VsNvr6uI5n006o1/6IVuDVSuXG21f3y+9qafvfcofv1UPdiqcuqczDbZHBXVMuotff1z6o8BZzdrXPuqcqWF/vJXaeDCQ74FtDK1hlCfCYSnCASJgD+hXjqnbZO76eob+mrsO5M1sk9btbx9uBbsyfKNqJ8/fkANKlZUjZodNDrzL5g+ffYoLma0Oje9Rl2GTdS0mVM1adRjur9HTw185RP59ZXoOaJFAxopvFJTPbI0wc8QbYT6Gipbs4OeHDtct9eNUPM+o/TGP15QtwblVK52ez0+f++ls/eeeK2f+qBaVXakFtCzyVGxpaLe+jq1N2e1eVx7VXWlBnt7eV01cKEO+RRZ9ek4TxBAAAEEMgkQ6jOB8BQBBAIokBSvHzau1Ybth3Uqj/9AS9kxVoPG7fLj4G6dObxd69Z8ow1bf1RCamE6PzYs8CrunzcpZmfapbCJOrp1tRbNmaOFK9Zqd7x/Z/uzHNx9XLtjFmv+wpX655G8O0GozyLICwgEhYB/of5iU5Pif9DGtRu0/fCpXH/Ek1K0Y+wgjduVx5l2Y7fuMzq8fZ3WfLNBW39MUN7fJoVlc+vnTTHamXa/VOJRbV29SHPmLNSKtbtVsK9Et47vjtHi+Qu18p9HiqEPhTVgewQQQCC4BAj1wTUetAaBkBU4MXewHi3uuepMpE2oN9Fg0dSQEshPqPcf5oTmDn602Kfv9L99rIkAAgggEEwChPpgGg3agkCoCrgPaMpDL2hN5itRQ9Ujm34T6rNB4SUEgkCgKEK9+8AUPfTCmiy3KwVBd2kCAggggEAQChDqg3BQaBICoSWQqO8n99dDc3K/pzy0TLL2llCf1YRXEAgGgYCH+sTvNbn/Q5rDTeXBMLy0AQEEEDCFAKHeFMNEIxGwsID7gD6Pjs11OjsL997vrhHq/aZiRQSKVSDQod594HNFx6bV8CjWrnAwBBBAAAGTChDqTTpwNBsBBEJLgFAfWuNNb80jEOhQb56e01IEEEAAgWARINQHy0jQDgQQQCAXAUJ9Lji8hUAJChDqSxCfQyOAAAIIeAUI9XwQEEAAARMIEOpNMEg0MSQFCPUhOex0GgEEEAgqAUJ9UA0HjUEAAQSyFyDUZ+/CqwiUtAChvqRHgOMjgAACCBDq+QwggAACJhAg1JtgkGhiSAoQ6kNy2Ok0AgggEFQChPqgGg4agwACCGQvQKjP3oVXEShpAUJ9SY8Ax0cAAQQQINTzGUAAAQRMIECoN8Eg0cSQFCDUh+Sw02kEEEAgqAQI9UE1HDQGAQQQyF6AUJ+9C68iUNwC//rXv3wOmTnUx8bG+rzPEwQQQAABBIpagFBf1MLsHwEEEAiAAKE+AIjsAoEACDRs2FBr1qxJ31PGUP/Pf/5TdevWTX+PBwgggAACCBSHAKG+OJQ5BgIIIFBIAUJ9IQHZHIEACcyZM0ft2rVL31vGUH/nnXfqvffeS3+PBwgggAACCBSHAKG+OJQ5BgIIIFBIAUJ9IQHZHIEACbjdbjVo0CD9bH1aqDfO0teuXVvJyckBOhK7QQABBBBAwD8BQr1/TqyFAAIIlKgAob5E+Tk4Aj4CM2bMUK9evbyvpYX6gQMH6h//+IfPejxBAAEEEECgOAQI9cWhzDEQQACBQgoQ6gsJyOYIBFAgISFB4eHh3rPyRqj/7bffVLVqVR0+fDiAR2FXCCCAAAII+CdAqPfPibUQQACBEhUg1JcoPwdHIItAmzZt9Pnnn8sI9UbhvGuuuSbLOryAAAIIIIBAcQgQ6otDmWMggAAChRQg1BcSkM0RCLDA66+/rocfftgb6p966imNGjUqwEdgdwgggAACCPgnQKj3z4m1EEAAgRIVINSXKD8HRyCLwL///W/VqFFDLpdL9erV07Zt27KswwsIIIAAAggUhwChvjiUOQYCCCBQSAFCfSEB2RyBIhBo3LixwsLCVKtWrSLYO7tEAAEEEEDAPwFCvX9OrIUAAgiUqAChvkT5OTgC2Qo899xzstvt3svws12BFxFAAAEEECgGAUJ9MSBzCAQQQKCwAoT6wgqyPQKBF1i0aJFsNpumTZsW+J2zRwQQQAABBPwUINT7CcVqCCCAQEkKEOpLUp9jI5C9wNatW72h/ssvv8x+BV5FAAEEEECgGAQI9cWAzCEQQACBwgoQ6gsryPZmFbhw4YLmzp2r6dOnB93fW2+95Q31vXv3Drq2GV4ffvih3G63WYeediOAAAII+ClAqPcTitUQQACBkhQg1JekPscuSYHY2FhvcB48eLCC8a9cuXJq3rx5ULbNuDXgq6++Ksnh49gIIIAAAsUgQKgvBmQOgQACCBRWgFBfWEG2N6vApk2bdMMNN5i1+SXa7ltvvVVffPFFibaBgyOAAAIIFL0Aob7ojTkCAgggUGgBQn2hCdmBSQUI9QUfOEJ9we3YEgEEEDCTAKHeTKNFWxFAIGQFCPUhO/Qh33FCfcE/AoT6gtuxJQIIIGAmAUK9mUaLtiKAQMgKEOpDduhDvuOE+oJ/BAj1BbdjSwQQQMBMAoR6M40WbUUAgZAVINSH7NCHfMcJ9QX/CBDqC27HlggggICZBAj1Zhot2ooAAiErQKgP2aEP+Y4T6gv+ESDUF9yOLRFAAAEzCRDqzTRatBUBBEJWgFAfskMf8h0P2VDvPqWD/4zRssULtWjJZ1q3K06J+fw0EOrzCcbqCCCAgEkFCPUmHTiajQACoSVAqA+t8aa3lwRCL9Sf1taZD6ptzbJyVaynNl3vVbcOV+lyl0uVm/5VYz8/opRLPLk+ItTnysObCCCAgGUECPWWGUo6ggACVhYg1Ft5dOlbbgKhFeqTtevNm3W5wy5nnZ766KekVBqPEr58Ss3+YJe9TCMNWX1CntzQUt8j1PuBxCoIIICABQQI9RYYRLqAAALWFyDUudB2/QAAIABJREFUW3+M6WH2AqEU6t2HpqlTJYdsNpeu+/sPcvuQnNL87uGy2+xyXfWMNvpxLT6h3geQJwgggIBlBQj1lh1aOoYAAlYSINRbaTTpS34EQifUu/XThNYqbbfJZi+v7h+fy8SUrM3PNJbTZpMtrKYGrz6f6f2sTwn1WU14BQEEELCiAKHeiqNKnxBAwHIChHrLDSkd8lOgoKE+KX631q2K1pIVa7U7PtnPoxmruZWc7HuOPB8bF2LVE5rV5Q+ye0N7pAavTrv0Pm2Xbu0b/xe5jPdtLjV94bs8760n1KfZ8S8CCCBgbQFCvbXHl94hgIBFBAj1FhlIupFvgfyG+qRDqzWudys16zhQY6YvUPSiaRp1f1dFzfhBeUZ79yHN7l5TpUrXUd8FR/26bz3fHcppg5R/6vmmLtmM0O6spye+zdxaj46+01GlvKHerst6LFRe5+oJ9Tlh8zoCCCBgLQFCvbXGk94ggIBFBYxQf8UVV+i3336zaA/pFgLZC+Qn1J/ePEG3RYar+RMrdTT1ZLsnYZVG3FRTFRsN18bMOTnzIZM3aFgDp2x2l64eufXSmfDkLXqj1y1q376d2rXL51/79rq17zuZj5T1edKXeqhWWGqob6Ch6zM31qO4KbekhnqbSt36nuLzqJZHqM/KzCsIIICAFQUI9VYcVfqEAAKWE3j33Xe9/7HfvXt3y/WNDiGQm4C/od59eJ561nTqD38Zp10Z8nBSzCOqE+ZS5N8+VlweIdhox6nvP9GU9z7VrjMZW3Va+zas1soVK7Qi338rtXrj/ow7y/5x4koNrG4UyTPO1DfQsA0ZOuHdwqP49269FOo7vK0jefSHUJ89Na8igAACVhMg1FttROkPAghYVmDmzJmqUqWK5syZY9k+0jEEMgv4F+pPaGn/WgpzRKjP4pOZdpGouINHdDaPAJxpo+J/mvS5HoxMO1NfX0+tyxrqj77d4VKov4Uz9cU/SBwRAQQQCE4BQn1wjgutQgABBLIV2LVrl6666io98MADOncuc3XsbDfhRQRMLeBPqPfEf6DOFexyVOun6LMm7W5yrEY0dl48Ux/2Jz22JnOhPI8Ov9Eu/Z768t0/Vl7fAJypN+lngWYjgAAC+RQg1OcTjNURQACBkhY4f/68oqKi1LhxY+3cubOkm8PxEShSAX9CfdKqQYoMs6tspxlKKNLWFOXOj2nGHWUuVr93/FH9Ps08Eb1bP712Q2r1e6euejY2z8J/hPqiHC/2jQACCASPAKE+eMaCliCAAAL5Epg7d673cvzp06fnaztWRsBMAv6E+vMLe+gyu1P1n/w2z6BboL4nrdHQRpepTOnSKp3vvzKq8OcRfhzWrR/GXieXd576Muo863SmbZK16elGqfPU19CAFXmdp5cI9ZkIeYoAAghYVIBQb9GBpVsIIBAaAj/99JOuueYa9e7dW2fO+FT2Cg0Aeml5AX9Cfcq2kbrG5VT9p9ZlH+qTftScEeP1dV5zwMmjY5tm6dXX5mjLiUw34buTlZh4XsaVMvn6S0yUv9Peu/e/o1vCjWJ5TjUYut63L554Tb/DmMfeLlfDofo284n8bD4JhPpsUHgJAQQQsKAAod6Cg0qXEEAgtAQSExP1yCOPqH79+vrXv/4VWp2nt5YX8CfUy71PU26vrLLXjdXOFF+S8wdXa2zPTnp4wYFLU9T5rnLpWfJaPVHPuK/dqSbPbfEN1ZfWKsJHSdoxsb0qO2xyVG6vcbFpZ+uTdXDhA7rSZZe9TCMNWXVCmX5yyLZNhPpsWXgRAQQQsJwAod5yQ0qHEEAgVAUWL16sqlWravLkyaFKQL8tKOBXqJfkiYvR6M5NdU2XYZo4baamThqlx+7voZ4DX9Ene/ysnuc5okUDGim8UlM9sjTBr+AcePLT2vbBI+pQt7zCSlfT1R1u001Nqqmso7Sqtuyt1746KrefByXU+wnFaggggIDJBQj1Jh9Amo8AAghkFDh48KCuu+463XPPPTp5MvPUXhnX5DEC5hDwN9Rf7I1bZw5v17o132jD1h+VkLmAvDm6fLGVnnM6umujYj5boZWff6ttB0/lfaVBpv4R6jOB8BQBBBCwqACh3qIDS7cQQCB0BX7//XcNHTpUdevW1ebNm0MXgp5bQiB/od4SXQ5YJwj1AaNkRwgggEBQCxDqg3p4aBwCCCBQcIHly5erWrVqmjBhgi5cuFDwHbElAiUoQKgvOD6hvuB2bIkAAgiYSYBQb6bRoq0IIIBAPgV+/vlntWnTRnfccYeOHTuWz61ZHYGSFyDUF3wMCPUFt2NLBBBAwEwChHozjRZtRQABBAogkJKSoueff141a9bU2rVrC7AHNkGg5AQI9QW3J9QX3I4tEUAAATMJEOrNNFq0FQEEECiEwBdffKHq1avrlVdekcfjz4RYhTgYmyIQIAFCfcEhCfUFt2NLBBBAwEwChHozjRZtRQABBAopEBcXp44dO3r/fvnll0Lujc0RKHoBQn3BjQn1BbdjSwQQQMBMAoR6M40WbUUAAQQCIGCcpR89erT3rL1x9p4FgWAW2L59u2w2m9q2bVuov9atW6ty5coqX768mjdvXqh9FbYtxbW94bZu3bpgHl7ahgACCCAQAAFCfQAQ2QUCCCBgRgHj/nrjPvvnnntOxn33LAgEq8DWrVu94dQIqAX5mzt3rq644grdeOONeuONN/TNN98UaD8FOXZJbrNly5ZgHVLahQACCCAQQAFCfQAx2RUCCCBgNoFff/1VnTp18lbINyrlsyBgNYEPP/xQVapU0cyZM63WNfqDAAIIIICAV+D/2bsP6KbKxg3guRlsaUEohRZaBCrIVPZSirJkSD8RUFYHUIYylS1SKjKVvRGkzAIilCEfWzZSASmjfKUsgZb+oWBpT1qT+PzPTZM06Uw6M56ew2ma3PuO33v9zvfkfe97Gep5IVCAAhRwcAHxGfbz5s3TPtNefLY9fyhgDwKJiYkYOHAg3nrrLURERNhDl9gHClCAAhSgQKYCDPWZsvBNClCAAo4ncP78eXh6emLMmDFISUlxPAD22G4E/vzzT9SuXRt+fn5ISkqym36xIxSgAAUoQIHMBBjqM1PhexSgAAUcVCA+Ph4+Pj5o2rQpoqOjHVSB3bZlgZUrV2qX24v30fOHAhSgAAUo4AgCDPWOMMrsIwUoQAELBZYsWQIXFxfs2LHDwjN5OAWKRuDvv/9G79690bBhQ9y+fbtoGsFaKUABClCAAkUgwFBfBOiskgIUoIAtCPzxxx+oWbMmhg0bBqVSaQtNZhsdVODSpUuoUaMGhg8fzmvVQa8BdpsCFKCAIwsw1Dvy6LPvFKAABXIQSEhIQN++fbWzn5GRkTkczY8pUPgCCxcu1C6337lzZ+FXzhopQAEKUIACViDAUG8Fg8AmUIACFLB2gTVr1vA+ZWsfJAdrn7j/w0cffaTd/+Hu3bsO1nt2lwIUoAAFKJAmwFCfZsFXFKAABSiQjYD4WLA6derA19eXO4pn48SPCl7g7Nmz8PDwwNixY/HPP/8UfIWsgQIUoAAFKGDFAgz1Vjw4bBoFKEABaxMQHw8mhnox3PPZ39Y2Ovbfnn///RezZ89GpUqVEBYWZv8dZg8pQAEKUIACZggw1JuBxEMoQAEKUMBUICQkRLscX1yWzx8KFIZAXFwcOnXqhNatW+Phw4eFUSXroAAFKEABCtiEAEO9TQwTG0kBClDA+gTEjfPEx4d9+umnEDfU4w8FCkrgxIkTcHNzw+TJk6FSqQqqGpZLAQpQgAIUsEkBhnqbHDY2mgIUoIB1CIiPuhMfeSc++k58BB5/KJCfAhqNBt988w0qV66M//73v/lZNMuiAAUoQAEK2I0AQ73dDCU7QgEKUKDoBHbs2AEXFxcsXry46BrBmu1K4MmTJ/D29kb79u0RExNjV31jZyhAAQpQgAL5KcBQn5+aLIsCFKCAAwtER0ejSZMm8PHxgfi4Mf5QILcChw4d0s7OBwUFQZyt5w8FKEABClCAAlkLMNRnbcNPKEABClDAQoGUlBSMGTMGnp6eOH/+vIVn83BHFxDvl584cSLc3d1x8uRJR+dg/ylAAQpQgAJmCTDUm8XEgyhAAQpQwBIB8XFj4mPH5s6dC/ExZPyhQE4CDx48QKtWrdClSxf83//9X06H83MKUIACFKAABXQCDPW8FChAAQpQoEAExMeOiY8fY0grEF67KnTv3r3aL4HmzZvHL4HsamTZGQpQgAIUKAwBhvrCUGYdFKAABRxUQFxOPWnSJFStWhW//fabgyqw21kJiLdrjB49Wnu7xrlz57I6jO9TgAIUoAAFKJCNAEN9Njj8iAIUoAAF8kdAv/HZzJkzufFZ/pDafCl37txB48aNubGizY8kO0ABClCAAkUtwFBf1CPA+ilAAQo4iID+EWXvv/8+H1HmIGOeVTdDQ0NRsWJFLFmyJKtD+D4FKEABClCAAmYKMNSbCcXDKEABClAg7wLi48lmzJiBKlWq4MiRI3kvkCXYlIBSqcTQoUNRs2ZN/PHHHzbVdjaWAhSgAAUoYK0CDPXWOjJsFwUoQAE7Fjhx4oT2sWVTpkyBWq22456ya3qBW7duoUGDBujbty8SEhL0b/M3BShAAQpQgAJ5FGCozyMgT6cABShAgdwJxMXFoXPnzmjTpg3++uuv3BXCs2xCYOPGjahQoQLWrFljE+1lIylAAQpQgAK2JMBQb0ujxbZSgAIUsDMB8Rn2c+bMgaurK/bt22dnvWN3EhMTMXDgQNSpUwcREREEoQAFKEABClCgAAQY6gsAlUVSgAIUoIBlAuLjzDw8PDBu3Dj8888/lp3Mo61S4Nq1a6hduzZ8fX2RlJRklW1koyhAAQpQgAL2IMBQbw+jyD5QgAIUsAOB+Ph4fPTRR2jWrBnu3r1rBz1y3C6sWrVKu7t9SEiI4yKw5xSgAAUoQIFCEmCoLyRoVkMBClCAAuYJLFq0CC4uLti1a5d5J/AoqxH4+++/0adPHzRs2BCRkZFW0y42hAIUoAAFKGDPAgz19jy67BsFKEABGxUIDw9HjRo1MHz4cCQnJ9toLxyr2foxGzZsGMRH1/GHAhSgAAUoQIHCEWCoLxxn1kIBClCAAhYK6Gd9GzVqhNu3b1t4Ng8vTAFxdUXFihWxY8eOwqyWdVGAAhSgAAUoAIChnpcBBShAAQpYtYD+/uzNmzdbdTsdsXH6fRCaNGmC6OhoRyRgnylAAQpQgAJFLsBQX+RDwAZQgAIUoEBOAvqd1P38/LiTek5YhfS5/okFY8aMQUpKSiHVymooQAEKUIACFEgvwFCfXoR/U4ACFKCAVQron3n+1ltv4fr161bZRkdo1L///os5c+agUqVKCAsLc4Qus48UoAAFKEABqxZgqLfq4WHjKEABClAgvcDGjRu192+vXbs2/Uf8u4AF4uLi0LlzZ7Ru3RoPHz7MojYNkl/G4N6tq7gYfgcvNFkcZtdvq5GSorbrHrJzFKAABShgPQIM9dYzFmwJBShAAQqYKXDr1i00aNAAn332GRISEsw8i4flReDkyZNwd3fHpEmToFKpsigqBefn9EDzem4oI5VA6uqP/Ta5Eb4GMadX48t+H6Jjhw7o0KEDOvX5HhfNuMtA82g3Rr5THnK5E+r6bkY0s30W1wrfpgAFKECB/BJgqM8vSZZDAQpQgAKFKiA+Ni0wMBC1atXC5cuXC7VuR6pMo9FgxowZqFy5Mv773/+a1/VnP6JbaQFluq1HnHlnWOVR8SE+KCtIIJGY+wWFBk9XdkRx3TkSRWvMzyTVq25uw6bTNvlth1WOExtFAQpQwNEFGOod/Qpg/ylAAQrYuEBoaChcXFywdOlSG++J9TX/yZMn8Pb2Rvv27SG+NvcnaZ8fKksVaDU3CrY8Ua3cH4DKUktCPaC6sQQdK8khCDK8/u4chKef3VffwYrOVdB9/UtzOXkcBShAAQpQIFsBhvpsefghBShAAQrYgsCdO3cgPlbtP//5D168eGELTbb6Noqz8uLsfFBQEMTZevN/UnD+q9qQy2vjq/PpE635pVjDkcoDlod6sd3q+GhcvhyF5xnuUkjCpW/bwElaHN0Y6q1hiNkGClCAAnYhwFBvF8PITlCAAhSggPhYtdGjR6N69eq4cOECQXIpIN4vP3HiRO398+J99Bb/qO9gXmsFpK5+CEuy+GyrOiG3oT7zTihxc10veCoESCQM9Zkb8V0KUIACFMiNAEN9btR4DgUoQAEKWK3Anj17tI9bmz9/PsTHr/HHfAFxR/tWrVqhS5cu+L//+z/zTzQ+8tkG9HhNijLd1yMu5SmuHw/D3qOX8fCVJbP9xgWmf52M2OuncHD3z9h38jpiLVgMoE5Jseh2ANNQ74edV3diaq/mqFHpdbjWbAafSVtwzbBPowYxvy3HhEA/+Pr6av/5jVyVuvxeHYvjQR+gijbQi8v55aj2Xn/tMf5fbcKtDDP66fvMvylAAQpQgAJZCzDUZ23DTyhAAQpQwEYFHjx4oA2nXbt2xbNnz2y0F4Xb7L1792q/DJk3b16evgxR7vPX3k9ft/do+H4cgOkrN2PT/AFoXLcHFpzLy60Rybj36yz0bd4I7QNmYvW23QhdNR0De/hhzY2ckr0a9zZ8DPdixeHRfxsem/n9gnGoF0q4wr3WO/AZMhz9WrlBod0MT4py736HS4YVCRrcX9QOJfSb65X7DLuUgDp6L+ZO9EOrilLtpntiqPfqPk67ImLynD3cIb9wL3XWRgEKUMDuBBjq7W5I2SEKUIACFBAF9MvIq1atilOnThElCwH9bQuenp44f/58FkeZ+3YKLkyoA7kgh1v3pbiaqD/vFcL8qqBY7fE4k6x/z5LfL3F+bke4Ob+NUfsf62bbNXh6cALedXdC7fFnkX2sT8GZcV6QSwQoGkxDuJkz4yahvkxbzInQ7VifdAbj68hTA7pQBt4L0zYEVIb5wkW/uZ4u1Gt7mnIBE/TncPm9JYPPYylAAQpQIAcBhvocgPgxBShAAQrYtsChQ4e0G74FBwdbuOGbbffbnNZHR0drNxj08fFBfHy8Oadkf4w6GgvaFIPUpQ+2myyQUCEiqDEU8jq52DxPjfube8NdXgotZ0UYhfdkHB3uAZnCDZ9ujUGOk+8v/sSu5SvwS4RhvXz2fQFgHOqlrv7Yb3gKXTKOjfSETCIupRdQrNVcROm2+Tc5h6E+R2MeQAEKUIACeRdgqM+7IUugAAUoQAErFxAfx9auXTt88MEHiI2NtfLWFk7zduzYgYoVK2LJkiX5V+HzjehZVorSXdfhqUnKTsbRER6QSSvBN8yQjM2r9/ke+FaVQeraDzvTf++gjMHdR69yDvTm1ZThKJOAbhLq1Yia2woKbaiXQFpxEPbqumVyDkN9BlO+QQEKUIAC+S/AUJ//piyRAhSgAAWsUEB8LNs333yDKlWq4MiRI1bYwsJpklKpRGBgIGrWrIk//vgjXytVHhwMN5kCLWbfNt2QTn0XC9oqIJHXwYQL2S+UN22QBrE/dkNZQYpKA3bjlemHBf6XSUA3CfUaPFrsjWK6UC849Uao7r56k3MY6gt8jFgBBShAAQoADPW8CihAAQpQwKEEjh8/Djc3N0yZMgVqtW7NtIMIREZGokGDBujbty8SEsxfhm4ej36JvRfGnTEN7pq4DehRVoC0sh/CDPfZm1NqMg4OdoNMKIkua56ac0K+HmMS0NOF+vsL3zOEeln1z3FCt1eAyTkM9fk6HiyMAhSgAAUyF2Coz9yF71KAAhSggB0LxMXFoVOnTmjbti3++usvO+5pWtdCQkK0y+3XrFmT9ma+vkq9z1xeuidCXhoXrMHTjT5wlirw5thTMGwUb3xIlq+TsP2T1yDIa2L0b6ZfFGR5Sj5+YBLQXf2xz3DngBrXZzbRLb+XolyvrdDfGWByTrpQP/Et3eZ63CgvH0eJRVGAAhSgAEM9rwEKUIACFHBIAfEZ9rNnz4arqyv2799vtwaJiYkYNGgQ6tSpg4iIiALsp26m3jjIirWpIjCrRUkoPAfh5xijG+01MTi19jvM3XIJ8UZvmzZQhcvTGkIhr4kxpzIP9cmRIZgw51iOXxZo4s5h/XezEXLxudn34JsE9AoD8Ish1Cfj0FD31I3yZNUw+EDaqgeTc4wtVOGY1kChe6RdcXRZ+1zbVWViktntMbXhXxSgAAUoQIFUAYZ6XgkUoAAFKODQAmfPnoWHhwfGjRuHf/75x64srl27pg3zvr6+SEqybI48NxCqq0FoXKYRpl/RPzMuARdmtoFzxXYIPmv6jPrk4yNRXSaBRFYNQ3/Nek2+Omo5OpUviabB16AvNbVtSbj7azB6dxmGbdGmn2RsewpOjqoBuUQCed1JuJj59wMZTjMO6IKiGWbd1G9xfxrj3pRDIijg2X87Hhl9KZEY2gfOuufUCyW7Y4N+1YLmCVZ3Lg1Bex++HG8M3IQLxxdhyPjtiDU6P0Mj+AYFKEABClAgBwGG+hyA+DEFKEABCti/wPPnz9GjRw80a9YM9+7ds4sOr169WrvcXlx2X3g/ibi82AcNWvRH8NLFmNavDRp3Go9tNzOGds3DrRjk5QSnKu7wDrqWTRM1iDkahG71GqL7uPlYtXYlFkz/HAM/6Y2AGbtw06zd8zR4FOqP2s7lUG/4nnQ782ddtRjqq5R0h/foYIzv5AnXt/th+g/fY4qPF0qXroZ2X2zBLcPsvQaxp1diaPPykOo20JNIndDYbxGOPUz9MuDV+Vlo56LQBXsBZd4KwPZ7jrWvQ9ba/IQCFKAABXIrwFCfWzmeRwEKUIACdiewcOFCuLi4YNeuXTbbN3EDPHEjvIYNG0LcGK8ofpJjb+DsyTO4cv+F6S74mTRGdTUYg2eZcVuAOgH3r5zC8RNnEB75FLp96TIpMf/eUj88h6PX4nXL45V4HP4rQkNCsH3fSVyPNXO6P11z1M+u4+jOLdi+/3c8KoxOpKuff1KAAhSggP0JMNTb35iyRxSgAAUokAeB8PBw1KhRAyNGjEBysm2lLvERdeKj6oYNGwbx0XW28PN80xCM2G3WdLstdIdtpAAFKEABChS6AEN9oZOzQgpQgAIUsHaBv//+G3369EGjRo3wv//9z9qbq23f4sWLtasMduzYYRPt1TZSHY3lgVNwPOPqfNvpA1tKAQpQgAIUKGIBhvoiHgBWTwEKUIAC1iuwatUq7X3pW7ZsydDI8+fPo1u3bhneL6g3rly5gvbt22coPj4+Hj179kSTJk0QHR2d4XPrfUOJPxf7IjDkXo5L9K23D2wZBShAAQpQoOgFGOqLfgzYAgpQgAIUsGIBcQf52rVrw9/f32QHeZVKpV2m/9tvvxVK6z/66COIs/HGP+IXC56enhgzZgxSUnJ3j7dxeYX6Wh2NQ7svZPM4u0JtDSujAAUoQAEK2KwAQ73NDh0bTgEKUIAChSUgPut94MCBqFu3Lq5fv26o9qeffkK7du0MfxfUC/FeeTc3N8N98v/++y/mzp2LSpUqISwsrKCqZbkUoAAFKEABCtiAAEO9DQwSm0gBClCAAtYhsHHjRu1y/HXr1mkbpFar8eabb2L37t0F1kCNRoP33nsPy5Yt09YRFxeHzp07o3Xr1nj48GGB1cuCKUABClCAAhSwDQGGetsYJ7aSAhSgAAWsRODWrVto0KAB+vXrh1evXuHChQvaGfOCCtjBwcHw9vaGGO5PnjwJd3d3TJo0CeLyf/5QgAIUoAAFKEABhnpeAxSgAAUoQAELBcTHxQUGBsLLywviBnZz5sxB27ZtIc7c5+fPmTNn4Orqir/++gszZsxA5cqV8d///jc/q2BZFKAABShAAQrYuABDvY0PIJtPAQpQgAIFL/DPP/9g+vTpWL16Nc6dO4eEhARtpaGhodrHyC1duhQdOnTQHpNfrRF3tffw8MCmTZu0u96LO9/HxMRAvJ/+3r172nvpZ82ahT179uRXlSyHAhSgAAUoQAEbFGCot8FBY5MpQAEKUKDwBZYsWaLdAb9p06YoXbo02rRpgxUrVuDSpUvax8l17dpVO6suLpHPjx8fHx+I/8TZ+aCgIO2XCaNGjdLWIS7B79KlCyZMmABxEz3+UIACFKAABSjguAIM9Y479uw5BShAAQrkUkCcuRd3ne/bty+cnJy0G9d16tRJO2vv4uKC2NjYXJacetqiRYu09+mLZQ0YMED76DxxQz5xCf7//ve/PJXNkylAAQpQgAIUsC8Bhnr7Gk/2hgIUoAAFCllAfNzdli1bIM7UizP4crkcr7/+Op48eZKrlsybN09bRpkyZbSz8uPHj+dsfK4keRIFKEABClDAMQQY6h1jnNlLClCAAhQoBIFnz55BXCIvlUq1wdxkKb7mBaJO78H6H4IR/MMG7DkTjZca00Z169YNEolEO+N/4MAB7Y73pkfwLwpQgAIUoAAFKGAqwFBv6sG/KEABClCAAnkWePDgASpUqKB9pr1YmOruzxjd0hUVvNrh44DP8bmfD971coHbu18h7EHqjvkvX77UBnpxR33x8XX8oQAFKEABClCAAuYIMNSbo8RjKEABClCAArkVSDqLqY0ro/mYPYhWGhWieoyDXzaDW/MZ+N34faND+JICFKAABShAAQrkJMBQn5MQP6cABShAAQrkWkCDmB+7o/K78xGZ2SPsVTcxp40bfELiwLn5XCPzRApQgAIUoIBDCzDUO/Tws/MUoAAFKFCwAkrsGeiGtvPuILNMD6hxZ15bVAs4AE7WF+xIsHQKUIACFKCAvQow1NvryLJfFKAABShgBQJJCO1dER1WxGYxE69BzPIOcP3sZ4Z6KxgtNoECFKAABShgiwIM9bY4amwzBShAAQrYiIAaN75tDrfPdiI+0xY/R2hfN7SaE5nFTH6mJ/FNClCAAhSgAAUoYBBgqDdQ8AUFKEABClAg/wU0D9d1DOCsAAAgAElEQVSjp1s9DN8fk262XoMne4eijvt/EPKYd9TnvzxLpAAFKEABCjiGAEO9Y4wze0kBClCAAkUmoMGTsNFo7FodH4yYhdU79mN/6Cp8G+gNj0qNMTZD2C+yhrJiClCAAhSgAAVsUICh3gYHjU2mAAUoQAHbE0iMOoDFEwPw8fut0LpDLwyZtAQH7yTZXkfYYgpQgAIUoAAFrEqAod6qhoONoQAFKEABexf4999/ERQUhJ9//tneu8r+UYACFKAABShQCAIM9YWAzCooQAEKUIACeoH4+HiUKFECU6ZM0b/F3xSgAAUoQAEKUCDXAgz1uabjiRSgAAUoQAHLBcRQ7+zsbPmJPIMCFKAABShAAQpkIsBQnwkK36IABShAAQoUlABDfUHJslwKUIACFKCAYwow1DvmuLPXFKAABShQRAIM9UUEz2opQAEKUIACdirAUG+nA8tuUYACFKCAdQow1FvnuLBVFKAABShAAVsVYKi31ZFjuylAAQpQwCYFGOptctjYaApQgAIUoIDVCjDUW+3QsGEUoAAFKGCPAgz19jiq7BMFKEABClCg6AQY6ovOnjVTgAIUoIADCjDUO+Cgs8sUoAAFKECBAhRgqC9AXBZNAQpQgAIUSC/AUJ9ehH9TgAIUoAAFKJAXAYb6vOjxXApQgAIUoICFAgz1FoLxcApQgAIUoAAFshVgqM+Whx9SgAIUoAAF8leAoT5/PVkaBShAAQpQwNEFGOod/Qpg/ylAAQpQoFAFGOoLlZuVUYACFKAABexegKHe7oeYHaQABShAAWsSYKi3ptFgWyhAAQpQgAK2L8BQb/tjyB5QgAIUoIANCTDU29BgsakUoAAFKEABGxBgqLeBQWITKUABClDAfgQY6u1nLNkTClCAAhSggDUIMNRbwyiwDRSgAAUo4DACDPUOM9TsKAUoQAEKUKBQBBjqC4WZlVCAAhSgAAVSBRjqeSVQgAIUoAAFKJCfAgz1+anJsihAAQpQgAI5CDDU5wDEjylAAQpQgAIUsEiAod4iLh5MAQpQgAIUyJsAQ33e/Hg2BShAAQpQgAKmAgz1ph78iwIUoAAFKFCgAgz1BcrLwilAAQpQgAIOJ8BQ73BDzg5TgAIUoEBRCjDUF6U+66YABShAAQrYnwBDvf2NKXtEAQpQgAJWLGBRqNck42XMPdy6ehHhd15AY8X9KrCmqVOQoi6w0lkwBShAAQpQwOYFGOptfgjZAQpQgAIUsCUBs0N9ynnM6dEc9dzKQCqRwtV/P5S21FF9WzUxOL36S/T7sCM6dOiADh06oc/3F5Gi/zzL3xo82j0S75SXQ+5UF76bo8FsnyUWP6AABShAAQcWYKh34MFn1ylAAQpQoPAFzA71uqY9+7EbSgtl0G19XOE3Nt9qjEeIT1kIEgkk5n5BoXmKlR2L686RQNF6PqIzpHoVbm7bhNM2+W1HvuGyIApQgAIUcHABhnoHvwDYfQpQgAIUKFwBy0J9Evb5VYZU0QpzozIk2sJteJ5qU2J/QGVILQn1UOHGko6oJBcgyF7Hu3PCM8zuq++sQOcq3bH+ZZ4ax5MpQAEKUIACNi3AUG/Tw8fGU4ACFKCArQlYFOpTzuOr2nLIa3+F8zmvV7diCiUOWBzqxe6oER99GZejnkOVvndJl/BtGydIi3djqE9vw78pQAEKUMChBBjqHWq42VkKUIACFChqAUtCvfrOPLRWSOHqF4akom54nurPbajPolLlTazr5QmFIIGEoT4LJL5NAQpQgAKOIsBQ7ygjzX5SgAIUoIBVCFgS6p9t6IHXpGXQfX0cUp5ex/GwvTh6+SFe5dc2+MmxuH7qIHb/vA8nr8dmWN6eNZgaKRZtSZ8u1PvtxNWdU9GreQ1Uet0VNZv5YNKWa0jQV6iJwW/LJyDQzxe+vuI/P4xclbr8Xh17HEEfVEkN9OJyfnk1vNdfPMYfX226lXFGX18mf1OAAhSgAAXsVICh3k4Hlt2iAAUoQAHrFDA/1Cuxz1+8n74ueo/2xccB07Fy8ybMH9AYdXsswLkXeehf8j38Oqsvmjdqj4CZq7FtdyhWTR+IHn5rcCOnZf7qe9jwsTuKFfdA/22PzXzMnnGoF1DC1R213vHBkOH90MpNkboZnrQc3v3uUtqKBM19LGpXwrC5XrnPdkEJNaL3zsVEv1aoKBU33RNDvRe6j5uIiRMnY84e7pCfh6uCp1KAAhSggI0KMNTb6MCx2RSgAAUoYJsCZof6lAuYUEcOQe6G7kuvIlHf3Vdh8KtSDLXHn0Gy/j1Lfr88j7kd3eD89ijsf6zbfE/zFAcnvAt3p9oYfzaHVJ9yBuO85JAICjSYFm7mzLhpqC/Tdg4idDvWJ50Zjzry1IAulPHGQsOGgEqE+boYNtdLDfWpHU25MMFwDpffWzL4PJYCFKAABexRgKHeHkeVfaIABShAAasVMDfUq6MXoE0xKVz6bMcz496oIhDUWAF5nVxsnqe+j8293SEv1RKzIozCe/JRDPeQQeH2KbbG5Ly2/8Wfu7B8xS+IMKyXN25gZq+NQ70Urv77YXgKXfIxjPSUpc66C8XQam6UrgDTcxjqM3PlexSgAAUoQAGAoZ5XAQUoQAEKUKAQBcwN9c839kRZaWl0XffUdIl78lGM8JBBWskXYYZkbF4Hnu/xRVWZFK79diI+3SnKmLt4lG8366crHKYB3STUq6Mwt5UiNdRLpKg4aK/uZNNzGOrTm/JvClCAAhSgQKoAQz2vBApQgAIUoEAhCpgX6pU4ONgNMkULzL5t+nx69d0FaKuQQF5nAi4YTbbn2AVNLH7sVhaCtBIG7H6V4+H5e4BpQDcJ9ZpHWOxdTBfqBTj1DtVVbXoOQ33+jghLowAFKEAB+xFgqLefsWRPKEABClDABgTMCvX6JfZe43DGJLhrELehB8oKUlT2C0u7z96cficfxGA3GYSSXbDmqTkn5OcxpgHdNNTfx8L39KFehuqfn9BVbHoOQ31+jgfLogAFKEABexJgqLen0WRfKEABClDA6gXMCvXa+8zlKN0zBC+Ne6R5io0+zpAq3sTYUxY+uT5pOz55TYC85mj8ZvJFgXEFBfXaNKC7+u9Lu6defR0zm+iW30vLoddW/Y0BpueYhvqJeEu3uR43yiuoMWO5FKAABShgKwIM9bYyUmwnBShAAQrYhYBZoV43U28cZMXOqyJmoUVJBTwH/Qzj/ew0Maew9ru52HIp3vT+e2Mx1WVMa6iAvOYYnMo01CcjMmQC5hzL6csCDeLOrcd3s0Nw8XnOm+qlNsE0oFcY8EtaqE8+hKHuqRvlyaoNxgHD5num5xhbqMKnoYFC90i74l2w9rlYixKJSea2xxiGrylAAQpQgAK2LcBQb9vjx9ZTgAIUoICNCZgV6qHC1aDGKNNoOq6odB1MuICZbZxRsV0wzpo8oz4Zx0dWh0wigazaUPxqePZdehg1opZ3QvmSTRF8TV+o7piku/g1uDe6DNuG6HQfpS8FKScxqoYcEokcdSddRKbfD2Q4yTigC1A0m4Wbuq0ClKfH4U25BILCE/23PzL6UiIRoX2cdc+pF1Cy+wbDqgXNk9XoXFrQPaf+DQzcdAHHFw3B+O2xRudnaATfoAAFKEABCtilAEO9XQ4rO0UBClCAAtYqYF6oB5B4GYt9GqBF/2AsXTwN/do0Rqfx23AzQ2jX4OHWQfByckIVd28EpQ/sxhCaGBwN6oZ6Dbtj3PxVWLtyAaZ/PhCf9A7AjF03Ydb2eZpHCPWvDedy9TB8T7qd+Y3rMnkthvoqKOnujdHB49HJ0xVv95uOH76fAh+v0ihdrR2+2HIrbfZeE4vTK4eieXmpbgM9CaROjeG36Jiu1Fc4P6sdXBS6YC+UwVsB23HPdE9BkxbwDwpQgAIUoIC9CjDU2+vIsl8UoAAFKGCVAmaHem3rkxF74yxOnrmC+y9ySqwqXA0ejFkROU21A+qE+7hy6jhOnAlH5NPkQnBS4+G5o7gWr1ser3yM8F9DERKyHftOXkesedP96dqpxrPrR7Fzy3bs//0RCqMX6RrAPylAAQpQgAJWIcBQbxXDwEZQgAIUoICjCFgW6i1ReY5NQ0ag0J9WZ0kTeSwFKEABClCAAvkuwFCf76QskAIUoAAFKJC1QEGFenX0cgROOW7ZY+6ybiY/oQAFKEABClDARgQY6m1koNhMClCAAhSwD4ECCfXKP7HYNxAhvKncPi4S9oICFKAABShggQBDvQVYPJQCFKAABSiQV4GCCPXq6EPYfSGbx9nltdE8nwIUoAAFKEABqxVgqLfaoWHDKEABClDAHgUKItTboxP7RAEKUIACFKCAeQIM9eY58SgKUIACFKBAvggw1OcLIwuhAAUoQAEKUEAnwFDPS4ECFKAABShQiAIM9YWIzaooQAEKUIACDiDAUO8Ag8wuUoACFKCA9Qgw1FvPWLAlFKAABShAAXsQYKi3h1FkHyhAAQpQwGYEGOptZqjYUApQgAIUoIBNCDDU28QwsZEUoAAFKGAvAgz19jKS7AcFKEABClDAOgQY6q1jHNgKClCAAhRwEAGGegcZaHaTAhSgAAUoUEgCDPWFBM1qKEABClCAAqIAQz2vAwpQgAIUoAAF8lOAoT4/NVkWBShAAQpQIJ2ASqXCDz/8YHg3fahPTk7G4sWLDZ/zBQUoQAEKUIACFLBEgKHeEi0eSwEKUIACFLBQ4N9//0X9+vVx4MAB7ZnpQ/3SpUvRvXt3C0vl4RSgAAUoQAEKUCBVgKGeVwIFKEABClCggAV27tyJpk2bamsxDvXiLL2bmxv++OOPAm4Bi6cABShAAQpQwF4FGOrtdWTZLwpQgAIUsBoBcba+QYMGOHjwoMk99cuWLUOPHj2spp1sCAUoQAEKUIACtifAUG97Y8YWU4ACFKCADQqsWbMGn376qUmob968OY4cOWKDvWGTKUABClCAAhSwFgGGemsZCbaDAhSgAAXsWiAmJgblypXD06dP4ezsjCdPnqB8+fIQN9LjDwUoQAEKUIACFMitAEN9buV4HgUoQAEKUMBCgRYtWmD37t3aUL969Wp89tlnFpbAwylAAQpQgAIUoICpAEO9qQf/ogAFKEABChSYwOzZsxEQEKAN9V26dEFoaGiB1cWCKUABClCAAhRwDAGGescYZ/aSAhSgAAWsQODWrVva3e6dnJxQtmxZJCQkWEGr2AQKUIACFKAABWxZgKHelkePbacABShAAZsTqFGjBkqUKIHOnTvbXNvZYApQgAIUoAAFrE+Aod76xoQtogAFKEABOxYYPnw4ZDIZli5dase9ZNcoQAEKUIACFCgsAYb6wpJmPRSgAAUoQAEAixYtgiAIOHbsGD0oQAEKUIACFKBAngUY6vNMyAIoQAEKUIAC5gvs3bsXEokE9+/fN/8kHkkBClCAAhSgAAWyEGCozwKGb1OAAhSggPkC4rPX58+fD3Fp+YABA9C/f3/+y8Kga9eu2lBfr149GmVhJF4/AwcOxOeff44VK1ZwQ0Hz/1PkkRSgAAUo4IACDPUOOOjsMgUoQIH8Erhx44Y2mJYrVw6DBw/GsmXLEBISwn85GLRv3x5ff/01nbJx2rhxI5YsWYI+ffqgfPnyGDFiBP7666/8unRZDgUoQAEKUMBuBBjq7WYo2REKUIAChStw6dIlVKpUCXPnzkV8fHzhVs7aHErg8ePHmDBhAjw9PXH37l2H6js7SwEKUIACFMhJgKE+JyF+TgEKUIACGQT0gX7fvn0ZPuMbFCgogZUrV8LDw4PBvqCAWS4FKEABCtikAEO9TQ4bG00BClCgaAVq166NHTt2FG0jWLtDCogrQ7p06eKQfWenKUABClCAApkJMNRnpsL3KEABClAgS4EjR46gQYMGWX7ODyhQkAJKpRIuLi64c+dOQVbDsilAAQpQgAI2I8BQbzNDxYZSgAIUsA6Bnj17YvXq1dbRGLbCIQUmTpyIsWPHOmTf2WkKUIACFKBAegGG+vQi/JsCFKAABbIVqFixImJjY7M9hh9SoCAFzp07h+bNmxdkFSybAhSgAAUoYDMCDPU2M1RsKAUoQAHrEFAoFPjnn3+sozG21ApNMl7G3MOtqxcRfucFNLbU9nxqqzolBep8KCsyMhJeXl75UBKLoAAFKEABCti+AEO97Y8he0ABClCgUAUEQYBG44iRNA/MKecxp0dz1HMrA6lEClf//VDmobiiOlUTcxqrv+yHDzt2QIcOHdChUx98fzEl5+ZoHmH3yHdQXi6HU11fbI7OW7QX76d/4403cq6XR1CAAhSgAAUcQICh3gEGmV2kAAUokJ8CDPW513z2YzeUFsqg2/q43BdS1GfGh8CnrACJRAKJ1BX++3P+ekLzdCU6FtedI1Gg9fzoTGbsVbi5bRNO51ycdpM8hvqivhBYPwUoQAEKWIsAQ721jATbQQEKUMBGBKwj1KsRuWIG1t3L24yv5eR5qTcJ+/wqQ6pohblRhd1uy3ua5RnK/QioLLUo1EN1A0s6VoJcECB7/V3MCc84u6++swKdq3TH+pdZ1mz4gDP1Bgq+oAAFKEABCoChnhcBBShAAQpYJGAVoT7+AIZ4tcGcwg7Heak35Ty+qi2HvPZXOJ8x01o0BkV6sPKA5aFebLA6HtGXLyPquSpj85Mu4ds2TpAW78ZQn1GH71CAAhSgAAWyFWCoz5aHH1KAAhSgQHqBIg/1qjsI6eMJhaJl4Yb6PNarvjMPrRVSuPqFISk9qi39ndtQn1UflTexrpcnFIIEEob6rJT4PgUoQAEKUCBLAYb6LGn4AQUoQAEKZCZgSajXvLiFA6u/xcQvhmHE2K/xw7ZzeJicVqrq2jZMHxsIfz9f+PoOxg+ndHE35QpCJo5AgPZ9f4wPuQFxflcZtQdTO1VFMTEAylzRrJd4nj8mbIlMvUc7JQYXt32HyWsuIQUqxF7cjNlfjsTwsTOw5vh96KvO93rTupTlq2cbeuA1aRl0Xx+HlKfXcTxsL45efohX+bXnYHIsrp86iN0/78PJ67GwZDGARbvSpwv1fjuvYufUXmheoxJed62JZj6TsOVagsFBE/Mblk8IhJ+vOFa+8PUbiVW65ffq2OMI+qBKaqAX79GXV8N7/VPH9KtNt7RjbijI6AWX3xth8CUFKEABCji8AEO9w18CBKAABShgmYB5oV6Fe7u+QPPqb2PA97tx5vdz2LcsEM3Ky1G27iBsuKmP1wCSI7HAuzQESXF8uO6FUWMS8NvYtyCXyFBt+FFtIFfe/x3HDq1HwJtySBT1ELjpMI4cOYqzNy5jz7cBeK9qCQgSAc59t+Lyah94KPSbs0kgSMuj9TenYbhlOz/qjTT30XRK7PMX76evi96jffFxwHSs3LwJ8wc0Rt0eC3DOuNtGAma9TL6HX2f1RfNG7REwczW27Q7FqukD0cNvDW7kmOzVuLfhY7gXKw6P/tvw2JwvGIxDvVACru618I7PEAzv1wpuOm9puXfx3aW09Qia+4vQroR+c71y+GyXuBueGtF752KiXytUlEpS79GXe6H7uImYOHEy5uzJbDO9VBGGerOuDB5EAQpQgAIOIsBQ7yADzW5SgAIUyC8Bc0K98uJ0NClTFt4/3Dba5VyDuD3+8JQLUNQKxP5n+gSZjBNfvAFZhlAPJG72QSkhLdRr+6C6jpmNFZCYLL9XQ61W497CdighCCjzTnt83P9b7Dx7A5GX92K2Tw2UECQQFF4YfUIfNvOjXjNVUy5gQh05BLkbui+9ikT9aa/C4FelGGqPP2NYRaD/yKzfL89jbkc3OL89Cvsf6zbf0zzFwQnvwt2pNsafzSnVp+DMOC/IJQIUDaYhPJPb3TO0wyTUl0HbORG6x/Ml4cz4OpCLM+4SAWW8F8Kw5YEyDL4u+s319KE+teSUCxNQR64L9Vx+n4Gbb1CAAhSgAAVyEmCoz0mIn1OAAhSggIlAjqFe8xCruzhBWqIDVsbog7uuCHU0FrYrCUEojiZBf+qWV6fgt1E1IM8k1Cdt+Q9KmxXqU8tX/jIAFaQCSnkvRLRxQFVewvTGxSFIpKjQbxdeaQ/Pv3pNgDL5Qx29AG2KSeHSZzueGX+uikBQYwXkdXKxeZ76Pjb3doe8VEvMijAK78lHMdxDBoXbp9ia3t+4bv3rF39i1/IV+CUibcm8/qNMfxuH+nSPtEs+NhKestSALhQz2uXf5ByG+kxd+SYFKEABClAglwIM9bmE42kUoAAFHFUgp1CvebISHUsKkLr6I+MjzNW4OasZFBIJFK3n4Y52cjn/wrVy7yC4SAU4f7oz3WZ0Gjxc2l47W6+oP1U3I51/9eZ0LTzf2BNlpaXRdd1TmHzNkXwUIzxkkFbyRZgZz2c3ruf5Hl9UlUnh2m8n4o0/EPceiLmLR/l2s376wrPe/V4dNRetFLpZd2lFDNqr6xRDfTpE/kkBClCAAhTIPwGG+vyzZEkUoAAFHEIgp1CfcmoMasklkFYYiD2ZBNWk0N5wEiSQe43DGe0Ec/6F66xDPZDy22jUlEsgq/45Tmhv6c+/erMfeCUODnaDTNECs2+bPp9efXcB2iokkNeZgAtGk+3ZlwdAE4sfu5WFIK2EAbtT1x3keE5+HWAS0F3hb/TNjebRYngX04V6wQm9Q3W3Opicw5n6/BoKlkMBClCAAhQQBRjqeR1QgAIUoIBFAjmFelX4VNRXSCAU88biRybz0tp6lGG+cJFKoGgxG5GFNlMPqC5N0bZL0TgIEdql+YUU6vVL7A1fYui5NYjb0ANlBSkq+4Wl3Wev/zi738kHMdhNBqFkF6x5mt2BBfCZSUBPF+rvL8R7+lAvq47PU789AUzOYagvgFFhkRSgAAUo4MACDPUOPPjsOgUoQIHcCOQU6pG4F76VpZBIneETYnIHuba6lyE9UVqQo+6ki7rHrqXg3Fe1tffUd1odZ9Ik/T31VQMPp20kl+lGeamn6WfqnXqHplt+DyQfCEAVmQweup30gfyr16TR6f9IPoaRnnKU7hmStvO+eIzmKTb6OEOqeBNj9Y/yS39uVn8nbccnrwmQ1xyN3yyZ4c+qPEveNwnorvDfl7YcQ319Jprolt9Ly/XCVv19ASbnpA/1E/EWN8qzZAR4LAUoQAEKUMBEgKHehIN/UIACFKBATgI5hnok4/ev39buQl+q5SwY7+EGJOHIcE/InTtiWbR+Kboa0fNbQyGRo9bo33Q7qQOauFOY28UdckGK1/vvNrwPdSRmtxB3v6+PqZfEKXcVHt6KgrjNmz7UF/9gOUz3iFPi1FgvKEo1Q/BV/Q56+Vdvtma6mfpyn+1K64PY6ohZaFFSAc9BP5u0VRNzCmu/m4stl+JN7783rkR1GdMaKiCvOQanMg31yYgMmYA5x/Q7/RufbPpaE3cO67+bjZCLz7Ouz/gUk4BeAQN+SQv1yYeGwl27UZ4M1QYf0I6J9lSTc0xDvSp8Ghro78Mv3gVrn4tnKJGYlHGVh74ZfKSdXoK/KUABClCAAlx+z2uAAhSgAAUsFMg51ANIuowFH7hAJryGt0fsRJQ2W6bg4YGxaFyuOj75KUq3831q5arfp6JBMQFCiWrw9v8Kk0d/ivfaDMSqWT1QWpBAWrEFBo7/Dr9od9Z7gS0fO0MQFPDoOhHBEz7DoO+vaGf9U0O9BEKJ+hi+575udl+Np8cmoqmzKzr8cMU0WOdTvdkTqnA1qDHKNJqOK/rvExIuYGYbZ1RsF4yzJs+oT8bxkdUhk0ggqzYUvxqefZe+BjWilndC+ZJNEXxNX6jumKS7+DW4N7oM22b6BID0RWj/TsFJ7ZMHJJDXnYSLmX5BkO5E44AuKNBs1k3dYwuVOD3uzdTH43n2x3bjWy8SQ9HHWfeceqEkum94aShU82Q1OpfWfSZ/AwM3XcDxRUMwfntsll8yMNQb+PiCAhSgAAUowHvqeQ1QgAIUoIBlAmaFerHIpCjsCeqHtl6VUM7lDTRo0hRtfcZi5aknRs+u19f9CuErB6Kp22soUcYN73w8AwceqJC05WO4eLTBgOk/4fSDtFln5ZVl+OSt8ijlVB3eo3cYwqt+pr5s+5GY5NMKjZu3RtuW76BRq16YuvNWhiX5QP7Uq+9Flr8TL2OxTwO06B+MpYunoV+bxug0fhtuZgjtGjzcOgheTk6o4u6NoPSB3bgCTQyOBnVDvYbdMW7+KqxduQDTPx+IT3oHYMaum7rH9hmfkNlrDR6F+qO2cznUG74HT7OeHE87WQz1VUrC3Xs0gsd3gqfr2+g3/Qd8P8UHXqVLo1q7L7DlVtrsvSb2NFYObY7yUt0GehIpnBr7YdGxh7oyX+H8rHZwUehDfxm8FbAd9/QLOdJqNrxiqDdQ8AUFKEABClCAoZ7XAAUoQAEKWCZgdqi3rNh8OVof6jM+0i5fis9jIcmIvXEWJ89cwf0X2SRWbS0qXA0ejFmpO/plW6864T6unDqOE2fCEflUu61/tsfn+UP1Q5w7eg3xui8AlI/D8WtoCEK278PJ67G6fRIsrUWNZ9ePYueW7dj/+6O0/ROyKIahPgsYvk0BClCAAg4pwHvqHXLY2WkKUIACuRdgqM+9nflnPsemISNQ2E+rM799RXskQ33R+rN2ClCAAhSwLgGGeusaD7aGAhSggNULWHuorygV4Nx3RyZL7a2e1tBAdfRyBE45btlj7gxn2/8Lhnr7H2P2kAIUoAAFzBdgqDffikdSgAIUoAAAaw71iVt7oawgoETXH6F/mprNDZryTyz2DURIdjeV21yn8rfBDPX568nSKEABClDAtgUY6m17/Nh6ClCAAoUuYJWhPvE69q36Fv5NykEqkUAoXRd9vlmB/TfTNtcrdKhcVqiOPoTdF7J5nF0uy7Wn08RQX6NGDXvqEvtCAQpQgAIUyLUAQ32u6XgiBShAAccUKFWqFBITM2zbXrQY6pd4cjca0dHG/+4iJqMM97UAACAASURBVCGnDemKttmsPXcCf/75J+rVq5e7k3kWBShAAQpQwM4EGOrtbEDZHQpQgAIFLfDGG2/g2rVrBV0Ny6dAlgJ79uzBBx98kOXn/IACFKAABSjgSAIM9Y402uwrBShAgXwQmDp1KkaNGpUPJbEICuROoFu3bvjxxx9zdzLPogAFKEABCtiZAEO9nQ0ou0MBClCgoAX++usvvP7663j16lVBV8XyKZBBQLzFomLFilAqlRk+4xsUoAAFKEABRxRgqHfEUWefKUABCuRRYNCgQejVqxdUKlUeS+LpFDBfQPwiqXXr1ggKCjL/JB5JAQpQgAIUsHMBhno7H2B2jwIUoEBBCKSkpKBr16745JNPGOwLAphlZhAQA32bNm0QGBiIf//9N8PnfIMCFKAABSjgqAIM9Y468uw3BShAgTwKiMH+o48+Qq1atbBo0SL8/fffeSyRp1Mgo0BsbKx2Zr5KlSoYMWIEA31GIr5DAQpQgAIOLsBQ7+AXALtPAQpQIK8CZ8+exaeffgpnZ2fUrVsXrVq14j8a5PkaaNmyJerUqYNy5cppZ+cjIiLyeqnyfApQgAIUoIBdCjDU2+WwslMUoAAFCl8gPj4eYvASQ/6ZM2f4jwZ5ugbOnTuHGzducEPGwv9PmTVSgAIUoICNCTDU29iAsbkUoAAFKEABClCAAhSgAAUoQAG9AEO9XoK/KUABClCAAhSgAAUoQAEKUIACNibAUG9jA8bmUoACFKAABShAAQpQgAIUoAAF9AIM9XoJ/qYABShAAQpQgAIUoAAFKEABCtiYAEO9jQ0Ym0sBClCAAhSgAAUoQAEKUIACFNALMNTrJfibAhSgAAUoQAEKUIACFKAABShgYwIM9TY2YGwuBShAAQpQgAIUoAAFKEABClBAL8BQr5fgbwpQgAIUoAAFKEABClCAAhSggI0JMNTb2ICxuRSgAAUoQAEKUIACFKAABShAAb0AQ71egr8pQAEKUIACFKAABShAAQpQgAI2JsBQb2MDxuZSgAIUoAAFKEABClCAAhSgAAX0Agz1egn+pgAFKEABClCAAhSgAAUoQAEK2JgAQ72NDRibSwEKUIACFKAABShAAQpQgAIU0Asw1Osl+JsCFKAABShAAQpQgAIUoAAFKGBjAgz1NjZgbC4FKEABClCAAhSgAAUoQAEKUEAvwFCvl+BvClCAAhSgAAUoQAEKUIACFKCAjQkw1NvYgLG5FKAABShAAQpQgAIUoAAFKEABvQBDvV6CvylAAQpQgAIUoAAFKEABClCAAjYmwFBvYwPG5lKAAhSgAAUoQAEKUIACFKAABfQCDPV6Cf6mAAUoQAEKUIACFKAABShAAQrYmABDvY0NGJtLAQpQgAIUoAAFKEABClCAAhTQCzDU6yX4mwIUoAAFKEABClCAAhSgAAUoYGMCDPU2NmBsLgUoQAEKUIACFKAABShAAQpQQC/AUK+X4G8KUIACFKAABShAAQpQgAIUoICNCTDU29iAsbkUoAAFKEABClCAAhSgAAUoQAG9QCGG+iTcObwea/dcw0t97UXxW6WEUlUUFRdEnVZiatw1VRyu/rIOe28UJbIKcVd/wbq9N1CUrdCyJN3B4fVrseda4Vz1qrir+GXdXljKr34WgV83rcaqn/bg4sNkACrEXgjF7kuF027jSyh/X2uQEHUUIdvOIU6TvyWzNApQgAIUoAAFKEABCliDgGWhXnUTu+dMRmDvLujYoQM6ZPuvEz5deMnQR82j5figpACJoj6mhhdB1Eq6i8MLh6Jd9boYdUIMLQX38+rEPMza9wwFnSGK3NSIUPMsHFtmDERbj9KQCiXQc1OS0aeF9FLzDOFbZmBgWw+Ulgoo0XMTiqAVRp3V4NHyD1BSkEBRfyoK7rLX4Fn4FswY2BYepaUQSvSE+fxJiFjni7bv9cHQfi1RWSFAWqYm2rZ7C86yYmi74C7URj2ynZevcCtsAYZ3qYNyCgGKxjNwrQj+Z8d2vNhSClCAAhSgAAUoQAFbFbAs1Ot6qXmyCb0qSSGRKNDwy0O4GRmJSO2/W7jx5wUcCZmO7m+UQIUBv6S5qCKxaURXdBywGBdfpb1d4K80T3FmzWQMbOOO4oIEEtkb+KIgQ73mCX7s7ozS7RbiTkGnoaIyzWTQNC/v49bNk5japBiEIgv1L3H/1k2cnNoExQRrCPWAKnITRnTtiAGLL6LgLnsNXt6/hZsnp6JJMcGiUP/q+GjUdnoX32sv1kRcmv0eykklkEjEfwobDvVKPIq8gSsrP0IFqYShPpP/ZvkWBShAAQpQgAIUoIB9COQq1EMdhbmtFNr/09/s25uZzuQlh09H20+3WoFSChITU4CUcExtoCjwUK++PgvNiwsQFPUx+fcUK+h/YTZBiX1+rkU3U6/rqnKfH1ytYqa+MO0BKPfBz9WSmfrn2PwfZ8g9R+KYfvGK5inOhSzBt5/VhtymQ32qvfr6TDRRFE2oV0euwIx19zL938dCvjJYHQUoQAEKUIACFKCAHQvkLtRrHmDhe8WyDfXQPML+X85aEV081n1YvIBDvRInvqgJhVwGQSJD1YADBTg7a0W0hqYk43CgO2RFNVOva0fy4UC4y6xjpt5AUxgvkg8j0F1m/kx98gl8Xl0Gee0vcc7k+ycVrk5/Gwp7CPVRc9GqSEJ9PA4M8UKbOVEM9YVx7bMOClCAAhSgAAUo4MACBRfqrQ41ERs/KuBQ/2wbers1xthvPkZFqQTSch9hQ0xB31lvTdDJODKsatGH+iPDUNUhQ/0RDKtqQah/tQk9SwmQ15mAC/Ya6u/MQ+tCD/Uq3AnpA0+FAi0Z6q3pf6DYFgpQgAIUoAAFKGCXAvkf6lXXMHfaejzNkGWVeHh2E4LHL083K6hzTX6IM5vmYvLo4Qgc8SVmrj6IyIT8NE9CSIGGejXuLPSGa6eVePDqKEZUl0EilEDruZG5nKlLwM2wxZj6RSCGjZmORVsP4/iWHxH2wPhG/axMNXhxcz+WTg3Grnvi8S9xc/9KzBz/BcYGrcfZGP2OYSrEXNyKeRNGYsTYYGy88DTd5n4piLm4Dd9NXoNLKYAq9iI2z/4SI4ePxYw1x3Ffv2TbMEw5hfok3D2xAXMmfYHAwJGYOHsjTj3IUIihtMxeqGJ+R+jCrzFm2BAMGzcDK/ffyvA0heQsQ70Gz6/txYqg8RgxZDACR03B/M1noN3sPV1lCTfDsHjqFwgcNgbTF23F4eNb8GPYA9OxTLiJsMVT8UXgMIyZvghbDx/Hlh/DYDpED3F2UzDGLz8Hk9ysrU+FmN9DsfDrMRg2ZBjGzViJ/bcy2W1e8xzX9q5A0PgRGDI4EKOmzMfmMw+RQS7ZzFAffwRzAnzh+1kbuMvEL58aoscgX/j66v8Ngk/jCpBmOVOvwYtbB7D624n4YtgIjP36B2w7l9Ye9b3dmD7YT1eeH/yHz0TYPTWSL2/A+KH+8NPV4xcwHFO36Z5QoIrA5kmB8PfzhZ//51gTnlEr3RBpd+jPyU+dLtSrYi5g03fjMfLzSVi47zYSMxRq5jWifo6IvYswefY+PFEn4+6vizBh1EQsP3Ieu6d2QtViAiQSGVyb9dI6+E/Ygkjj/3Qz1Ms3KEABClCAAhSgAAUokDuBfA/1r85NQrNuKxBrCPVq3N0bDN+2qRvVZbYzt/rhbox8uyLeHLABf8Yn48X1zQh4qxSKObvB09MT1avXxHvfnM9dDw1nFXCoT7mAifXd0f/nF9qwcWV6IygECeRvjsfZDOnL0KgsXrzA8Ukt8E7fZThx+zGeRJ3FTyObwlnRANMui4E8a9OEi2sx+qN6cJaJTxqoh8ln/sS6zxrC06suarmUgCARUKxGAPY8fYoT33ijasVqqOlRXruJoFC6ESadEmOOGnfCvkXAe1VRQpBAcO6LrZdXw8dDAUG7gZoEEkGK8q2/wWmTDJpNqH91Gct6N0WrATOxftcv2PL9ULSsKIfU+R2M2vs43ZcJmbEk4/aWoWharxMmhxzD75dOIuSLpigrLYla/TYiSv89BYDMQ70Sfy7rgaplauGTH/bjwqXTCJ32PlxlMlTstAy3jALXi+OT0OKdvlh24jYeP4nC2Z9GoqmzAg2mXU57RN6L45jU4h30XXYCtx8/QdTZnzCyqTMUDaYhdYjuYm+wL9q6F9eaZ9iJP/k2tgxtinqdJiPk2O+4dDIEXzQtC2nJWui3MSqtHuWfWNajKsrU+gQ/7L+AS6dDMe19V8hkFdFp2S3TLxnMDfVJt3B4SwhClgegvkICmftHCP4pBCEh+n8/YXav6pnfU6+6h11fNEf1twfg+91n8Pu5fVgW2Azl5WVRd9AG3NRd6wlXvkfHClJIpC7ovztti8CUqLXo6SqDRFoOPTfEmI77q5/Rz9UDfULuZPzCIv0lYaZfWqj/BqdPzkKnWtVQu44HnBUCBLkb+mx5ZNQGM64RTRxOLh6OLm+WhVR8qkGzIBxY4wN3hRjiJZB5DsKqQ4ewPuBNrV+9wE04fOQIjp6NxAvD/yam7wz/pgAFKEABClCAAhSgQO4F8hjqpXitWiM0a9ZM+6/p215wKSGg2AfGoR7QaDTQxKxC51KZ7MyteYC13cpDWqYr1hlN7786NBQeMgGlmk3BoWs3cfeZOTN32UEUbKh/udcXVeuMw2ldqFHfXYz2pQVIZFUw8Bcx6Jv/o3mwBO3LeGHcGaM+q+9iaec2+FqbGLMxFa2Vv2F0LTkkMle07D8Za84/TQ2Jry5hRsvSEITiqOPdGwHzjulmqRNxZWZLlBKkcP5km3bmW61WQ31vIdqVECCUeQftP+6Pb3eexY3Iy9g72wc1SgiQCAp4jT5h9Ni4LEK9Jg57/Gqg9ogjMJZ4vnsg3MSZ4sqfYeez7Hw0eHZgGLxK1cboE0bLN+J/Qg+tsRuG/Jr2zUmmof55CHycBNNHy6mu4OuGCkgULTBbP42qeYAl7cvAa9wZo5l1Ne4u7Yw2X+tDvQYPlrRHGa9xMB2ipejc5uvUUA+N9rqPWdUZpdLvxK95hgPDvFCq9miYdqcHSgsSyNyGQN+d5yE+cBIUqD813BD0VVe+RkNxSXmL2aazv+aGeh215skyvF9MYsHyeyUuTm+CMmW98cNto29BxPH194RcUKBW4H4804bXFFycVBcKQYHGQRGGtgMqXJpSHwqhGJoGXzf5UkLsVwvvBYgyKjrTq8ICP32ol7m+A5/R6xAeLzZOg8fbP4WbTECxlnPSDM26RjRQqzVIPDIMnjIJ5FXfgc/4nxF15zDm+HVHrxlHEKdR4frMxto9Cbj8PtMR5JsUoAAFKEABClCAAvkokMdQr0CD0WG4fPUqror/Lp3Elonvwa2jaajXtjf5AAKqZNyZWxO7Cp1KCpBV/xwmT5pL3Im+5aQQir+PZY/zY4qrAEO95iFWdXFB6zlGM6eaOGz9RFzCLMCpy2o8sqALKRcnoa5Cjmq91uK60frg+MPrsd34OXlZmELzAIvaFYNE/ia+NNkBTY2oua2gkMjhNe60yWyo+kawbpfwIEToZ72Vv2BABSmEUt5YGK1/UxxNJS5Nb6yd3ZdW6IddhonYzEO9OnIuWpeqhA+DtmHHjh1p/34MRCOFBBLp6xjwizLry1oVgZlNikHR2Kht4tGaZ/htgT98+k7DXiPgTEP9i90Y5KbA6z1/whPDWLxI3TxRdDqr+wIl5SIm1VVAXq0X1priY/32O7oQqgus8mrotfa60RLueBxev93kUYbJBwJQJd1O/KqImWhSLH3YFbvzGxb4+6DvtL2G6+XF7kFwU7yOnj89SZtRfrEOHxYXV4F8CX2zU/8bM3P5vU7a0lCvebgaXZykKNFhJdJvFaGOXoh2JQUIxZsg6M/Ua0V9czZaFBcgf2uiyT37KSe/wBtiIH5zPM4YvotJxqmxTdDzR6N+ZnFFWOKnD/WK+lNwyfgSTtyGXmUFSCv5Ikx/6Zl7jYhrWSK/Q3NxlUO1AOwz/qZK22aG+iyGjm9TgAIUoAAFKEABChSAQJ5DfYZH2qVcwNej1xgtv9e1WtyZO5NNvNTR89FGITH9P9fiKcnHMNJTBomiFebmOHVnjkzBhXrVnzPQuFLGTfESD6fO5gnFmiLYkJTNaOurwxhRQ1zqLqCUZ3sMW3QId4zCvaGELEyhicHyD4qlLr//3TjJAHGrOqK4RI46Ey4YzUQDmsdL4F1MAkXdyTCcotyLQS5SCM6fYmeSoVbtC83DpWgvztYr6mNquL6OzEP9s7UfoqTMDd1nrMP69esz+bcRR6KMViWYVgX13QVoqxBQ0meTUYBOd5DRn5mGevHzlGSkaCdqX+LWweX46tMPUEdcIi6viTGn9PW/wuERNbS3TgilPNF+2CIcygT/1eERqCEuuRZKwbP9MCw6dCfTtok78Ztu2qfG3QVtoRBKwmdTZoNq1BHdy5TkFG2g17y8hYPLv8KnH9TRPntdXnMMDM0Wjy3QmXoNnqzsiJKCFK7++6HPwYbWqm9iVrPUx1y2nncn9W3NAyzvUAaC7A2MPKY/IwEHAxvjjWqlIcjc4B+mW3nxaj8GNx4I7d0rhkIze2GZnyHUN56Ba/rLVCxW/4XYa59gu/G1bdY1Aqjv6HbVb/YtbmZYWcBQn9nI8T0KUIACFKAABShAgYIRyP9Qj5c4d+x8xke5ZRU4Us5jQh2F9rnuU4yn0l5uRS9nKRR1JmS+sZ7FHgUV6hNxZHh1KEq7ouabb+JN439e7nAS722XyFFz1ImMQSibPiTd2IQRLStpw6VEvA++SisMWXPJ9L7crEw1sViRZajvlEWoX4r24lLsupNwUZ9vswn1SPkNo2uKS/yr43PDEovMQr0u4MiqIOCgYVo2m55n/CjlzDh4ySUo3nEV4jJ+nOGdLEO95gWubp6Ij5o2Rfexy3Ho9mOs7148XagHkHQDm0a0RCXdfdJCsSpoNWQNLpncFJ2EG5tGoGUl3T4DQjFUaTUEay69SJtRz/T+/hScGecFuaQ4Oq4ypzeA5sVVbJ74EZo27Y6xyw/h9uP16C7O1BdqqE/BqTG1IJdIUWHgnkyu5SSE9naCoF0FckY3JhrEbfoPyktlqOK7F2J8V99bjm7tZuDU9n6oJJWinM9G7ReAz7f2RZPPjxrdypFhWHVvWOaXdaj/FUPcZBBK/wdbjEO9mdeIoVyG+qwGiu9TgAIUoAAFKEABChSSQAGE+ixanlUAhQZxh79EYycZXveehfPiPa+aOJya1grO5ZtjyvHnJiEpi9LNeLtgQr0mNgT/qdwY068YTwPqm6PG7fltUVKQQOrSF6HP9e+b+VvzAhE7ZqB3w/KQC+Iy9XJot+Ba2slZmRZGqFddwpT64v3ojRFkWIWQWahX48681tr7i+tN/t3o3uq0buT0Sn8PuayKH8IMS/2NztI8R9TttJ37Mw31qiiE9PfCa+49sTJCP0OegA2ZhXpt0Rq8iNiBGb0borxc/GJGinLtFpjO9op3ALyIwI4ZvdGwvFy7iaC0XDssMJoSztgWFa583RAKiQxV/MIyfvkllvk8Crd1+0uookLQ3+s1uPdcibRmbyiCUK9C+NT6UIhfMHkvNtwekDYKSoT5umh3zG8xOzLt7YS98K0ig/T1T7D1mRJnvmqNXj/FQJOU+oQIoVQ7LIx6gNXdW2Gq8Zd6aSWke2WZnyF8Z5ipzyTUW3CNGMplqE83PvyTAhSgAAUoQAEKUKCwBawg1ItdfoFTUz5Ex0HDETDIH4P9fTF08nIcuWs8hZZXmoII9WpEzmsL165rMgk5qe3VxG3FJxWlkAhl8P7SeyYbg2XVI/W9Pdh5Vr9cWdxM/wmOzfCGizR1dtZwXmGFeqfeCE0/FNrlyzLIPIbjqGECPrNQDyj3+6OyVAKZqw82aB+xZ+iB9sXzfVMw46BRf00/BhJC0ae8uJO6Mzotj85gmHBiIoYtvWt4P2OQ1uDpRh84SxVoNP2q0RcLaaF+tH4du/oe9uw8azQTrcKTYzPg7WK8TF+Ne3t2wnSIjmGGtxhq5ag55pShBxnbInanD8pLJZA6d8Ly6PRrtxNwYuIwLL2rBjRPsdHHGVJFI0y/avSlUYI+1I8uxOX3QOJeX+04Sp19EJJhY8OXCOlZGoK8LiYZlnqIDEqc+KIG5EJZdJnzA3q1HIOT2mtJv2GeAg18A+D9/ry0DesMepm/MNtPXBmQ7pF2hhKT04d6C64R43IZ6g2kfEEBClCAAhSgAAUoUDQCuQz19/B929T7Z013ts6mE0b3f4foJ0q1h6fg2sL38UbPzJ5tn0l5qgc4vOQbzNpy2WQn9UyOTPdWIjb2KK5dLj7yuCGFmh5jadlJJ/CFlwcC9hvtyG5aoriWG0dHVIdMIu68PhkXs6ja+DTVlenoNCAUcYYN3cRgH46p9RWQe41NOzQr01zdU69bfm+8qZl++X3xD7A83c5oylNj4aUohWbBxiE5GYcD3SETSqCn8SAnHsPnNcWZbAGl3+qH5WdjdPfzJ+Ph8e/QreUwHDB5NF5aF1NfvcS+gKqQSSSQOjXBqJ3654sn4/7hYHRt1Asb03a/g3gfu7tMQImeIbr73FUIn9ZAOztefYTREu+Xv2NaEwUkMg8MP5oMTVwsoLqC6Z0GINQUP3WWWu6FsafFexNUuDK9EwaExpmsIlGFT0V9hRxeY08bOpB2T72+LQBe7kNAVZl29t+pySjsvK37DyL5Pg4Hd0WjXhtTN/NThWNaA7F91THiaNq3Ki9/n6bd1DD1CxUN4mJ1CVu8HtxlEB8bacxvaEy6F5pHqfsoyNPt4p/av0ba1RVtFqR9WYLk3/H12yUgCKXQclaEyZ4MSDqC4Z5yOHdchvTfU4guDRQCFMXLof3CKMOXL9oNFLVPUSiLLquNHy2XrqHp/zTXTwzfUbp737OaqS/lo1t+b8E1og31unKbBONG+u9loEbk7BZav/pTL2m/RFI9vIWo7P5nIn0f+TcFKEABClCAAhSgAAXMFMhdqE85jbFeckgkMngMP2I0q5lNra9C0cdZgKSYNxYb7VSu3dyrmgzS8g3Rc/AofDlpKr7+ZiZmzVmARSvWI/ToDTw3+j/Nyp/7aWc5BZNl39nUq/9I8whLvItBIq2AAb+kBST9x+Jvy8pOxrU5bVC27MfYmtmScKOCk0L7wFm3fL7D0kijmWKjg4xeisvNG5X4//buPybK+44D+D1wxw/50Uc6GB0/btR6E80ETi05C1tuHqz1lInl6ETU2ZM52tHGwg51BXUlZLpWaiut2mJoFuugU+nKrNHaTufKbVk8s01xMVpLtEeNOGI11XBP3svz3B3cU7HDM/RZ0vcfJM8dz/f5Pt8XxyXv7/M8n28GSlp6AsuDAVJ/BxalibA0HR/Z83amvpN4TgmrmUpYHWkgFxkrUMJtZvV76ur3//41LHI174yf4VBw4iEQ6nVCDL5b3YXzgfd9nx5G/SwRqUWb4VFdYL+K3Q4Rgi4K1i19IYFXwsDBWuQlRChreeuEKIhpWfh2aiIMsVPw07e/sF75yAkPb0neLqycEqvc4q4T9IhPNSIzJQ56QybK2oNV6f27X93tULzl28T7AhMjg3uWIDVCByHaiKKnmrGpsQp2WzlKzLEQBAMmzV2ByuVblFDfkBuDjJIW9PjXZpPx0bEoDaKlCceVegPyLeC5iMkoQUvP5cA4JfR3LEKaaEGTfyflZD4L/O3Vt6xL8HatxJRY/9rmgj4eqcZMpMTpYcgsQ/vwCgeD2LMkVVlBIdpYhKeaN6Gxyg5beQnMcqV5wyTMXVGJ5Vs8wYHDEfwfCw58WPDWjZtuF7L1OkQkleN3qkmVG/jg5/JElAE5DR7V5/X68edhS4mEkJCHJ946438G/mYf/rhqBiZmOdB+JuSOgmCXvtPYODsGkd9ain1Xgm/KzxlcwPZHEhGZfKePpozVD7j513pM1fsr7atWCri+F5VykcSoOdgamBAa82dEntbxNCorN0Smr8D+Ub5O/rPrUYiCAIPRjvrnXKhY9gI8wVoVIQTcpAAFKEABClCAAhSgwN0K3FmoHzqFvRufxRN2E+LlkKrTQYgxwvq4C7/afUIVEkdOTIL3/a2oK53mbyMYkDmnGs1dZ/y7SP3YXzcLSUpBOf8x5eMO/wh6fKNgHY4GQoevdxtKjQlIMj+DA6EBYaTDL2wN4Z8dG1C3/HtIVwqfCYg3zcXKNS/jcMjVXbnRWI8teQ+iudKCtCi5+nkcHrA54XrdrRQCU3UueXH4xRr8aGoiIgJjEqLSYFm8Fh29o4SfQOMhz3rYpufDbDJicp4V9oUOzC8uQc0OdyDk39506GQnGp0FuC/4HPiMCrhePIDzV9zYudaJwjR/YbcIMQeO2s1496MB9LStxrLZ9wWe2xeRW+5CW88gELxSn/gDPLm6FLNn5OOhQgvMubNR9su30BsSZqTLx7C9dgGy5XXj5bsS0q2oatiFE8EJAkgY+NvreNqeg7TEaBhi78UDBUuw8b2Lw1duVXajvPB5j6DFaYUpeQIM0SKyLBVo2n9+5IqxdBnHttdiQXacEv4FQzqsVQ3YJZ+EdBHda4owSYxCtJiFQmcr3ANDOLezDMYEEaZ5G3BIvhthyIP1tunIN5tgnJwHq30hHPOLUVKzA+5gyJev1K+3YXq+GSbjZORZ7VjomI/ikhrscAdCvuTF+1vrUDotPnAumZhT3Yyu4ZUcfPAeaYHTakLyBINyTpaKJuw/r05+0sVurCmaBDEqGmJWIZytbgwMncPOMiMSRBPmbTgEryTh8rHtqF2QraxzrxMMSLdWoWHXiVEU5UR6Cnuan0F57kT/51Le//tOrH3tGC5dOopXVj2KHFGegBEQmfIgKuvb4A4J/dfPdGHD4kKYvjkRKfdPx8xZhShd9SqOfhIy+6bqWULfq/NR0Ph31QSBvMtARwVmVh8YpiH4YAAAA4pJREFUdeUA1SFuefG//G7g+Bu/wGPmJP8YI+7FzMUutH5wAaff3oTahdOQEKGDTojG/Q/XYPO7H8M3ps/IINxtLiyelYxI+TtQiIHR6sS63/eqx/a5B1sdU5E04R5kWZ9Gp2pJyFsGwzcoQAEKUIACFKAABSgQtsCdhfqwu/myhp/jH63LsPT5Izjp+RB/OtiNfZ278dv2Nuxo3Ywm11I8lHYPfrjN+2UH4e/GQyAY6kdZ0m48uuMxKUABClCAAhSgAAUoQAEKUODOBDQO9RL6u5yY8mAjQuuAqYcg4aMXbHj45Qvqt/lq/AUY6sffmD1QgAIUoAAFKEABClCAAhS4CwFtQ/3Nv6DuO3oYcurx4W2eS5eu/BnPzq3Azo9Dq8bdxYjZdOwCcqhPjoAg/hidIbfaj/0A3JMCFKAABShAAQpQgAIUoAAFxlNA21Dv68VLNvmZVwFxWVYsW/0bvPbmXvyh+x10dbbjpcYVKM4vxtoD/SFF18aTg8dWCVx7E2WJAoQYO9rGVL9A1ZovKEABClCAAhSgAAUoQAEKUGCcBbQN9fLgrp3GvqafwJqdgthgsTxBj8QMM+Y9uQWHgyXXxxmChw8VuIZ/vbMNTY/PxESlmFgcpj22Dq90n/JXOw/dldsUoAAFKEABClCAAhSgAAUooJmA9qE+ZOhDn13Cxb4L+HTwBq/Mh7h89Zs+DH5yDmfPnlX9nPNeHXOl+q/+nNkjBShAAQpQgAIUoAAFKECBr5/A/1Wo//rxc8QUoAAFKEABClCAAhSgAAUoQIHwBRjqw7djSwpQgAIUoAAFKEABClCAAhSggKYCDPWa8rNzClCAAhSgAAUoQAEKUIACFKBA+AIM9eHbsSUFKEABClCAAhSgAAUoQAEKUEBTAYZ6TfnZOQUoQAEKUIACFKAABShAAQpQIHwBhvrw7diSAhSgAAUoQAEKUIACFKAABSigqQBDvab87JwCFKAABShAAQpQgAIUoAAFKBC+AEN9+HZsSQEKUIACFKAABShAAQpQgAIU0FSAoV5TfnZOAQpQgAIUoAAFKEABClCAAhQIX4ChPnw7tqQABShAAQpQgAIUoAAFKEABCmgqwFCvKT87pwAFKEABClCAAhSgAAUoQAEKhC/AUB++HVtSgAIUoAAFKEABClCAAhSgAAU0FWCo15SfnVOAAhSgAAUoQAEKUIACFKAABcIX+C/kqq9GN7bW+gAAAABJRU5ErkJggg=="
    }
   },
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Quantum programming languages are a major developing topic in the field of quantum computing. As the availability of different quantum computing systems increases, the need rises for a clear syntax with which to program a series of operations on an arbitrary quantum computer. \n",
    "\n",
    "# Review of literature and high-level quantum programming proposals\n",
    "\n",
    "Discussion about quantum pseudoprogramming began immediately after Shor's algorithm and Grover's algorithm each took the spotlight in 1994 and 1996 respectively. In \"Conventions for quantum pseudocode\" \\[1\\] in 1996, E. Knill's often cited paper began the initiative to develop a common method for programming quantum computers. Although a physical implementation was nowhere in sight, the need for adopting expressions for constructing a quantum system was immediately clear. A number of quantum programming language proposals followed in the decade after Knill's paper, well documented by Peter Selinger's \"A brief survey of quantum programming languages\" \\[2\\].\n",
    "\n",
    "### Imperative languages\n",
    "\n",
    "Within a few years of Knill's paper, several proposals for *imperative* quantum programming languages emerged. The first proposed imperative language was **Quantum Computation Language (QCL)**, introduced in 1998 in B. Ömer's Master's thesis, \"A Procedural Formalism for Quantum Computing\" \\[3\\]. His thesis presented a fully developed imperative language, with examples such as the QCL implementation of Coppersmith's algorithm of a fast quantum discrete Fourier Transform (Table 2.1):\n",
    "\n",
    "```java\n",
    "    operator dft(qureg q) { // main operator\n",
    "        const n=#q; // set n to length of input\n",
    "        int i; int j; // declare loop counters\n",
    "        for i=0 to n-1 {\n",
    "            for j=0 to i-1 { // apply conditional phase gates\n",
    "                CPhase(2*pi/2^(i-j+1),q[n-i-1] & q[n-j-1]);\n",
    "            }\n",
    "            Mix(q[n-i-1]); // qubit rotation\n",
    "        }\n",
    "    flip(q); // swap bit order of the output\n",
    "    }\n",
    "```\n",
    "\n",
    "Generally, initial proposals for quantum programming languages were imperative, likely due to the intuition that the languages are designed to manipulate physical objects (qubits and gates), more easily expressed in an object-oriented language. The imperative languages that followed included **Q Language** (an extension of C++, from \"Toward an architecture for quantum programming\", S. Bettelli 2002), which tracked quantum memory using a class \"Qreg\" to create registers; and **quantum Guarded-Command Language (qGCL)**, modeled after Edsger Dijkstra's \"Guarded Command Language\", defined by P. Zuliani in his thesis, \"Quantum Programming\" (2001).\n",
    "\n",
    "### Functional languages\n",
    "\n",
    "As functional programming has risen back into the zeitgeist of the last decade or two among the software engineering community, quantum computation has seen its share of attempts at functional languages. Selinger defined the **Quantum Programming Language (QPL)** in another paper from 2004, \"Towards a quantum programming language\" \\[4\\]. His paper describes QPL as, \"*functional*, in the sense that each (atomic or composite) statement operates by transforming a specific set of inputs to outputs.\" The language implements natural solutions for issues like the no-cloning property, where the syntax of the language prevents an implied duplication of a quantum state. Selinger's paper also defines **Quantum flow charts (QFC)**, an excellent tool for illustrating a quantum functional program:\n",
    "\n",
    "![image.png](attachment:b276a9d7-7f0a-4829-91d2-9cd45cdafe5e.png)\n",
    "\n",
    "### Quantum Computing Simulators\n",
    "\n",
    "Going further high-level, we come to quantum circuit simulators. Quantum computing simulators not only allow for the simple construction of circuits in a programming language, but may run an input vector through a circuit to simulate the probabalistic results moment by moment. For instance, take the Quantum Forier Transform (QFT) - a simulator can simply compute the Fourier transform classically, and update the qubit states (note that it *could* also properly simulate the full circuit for QFT). This allows for advanced simulations to include features such as noise, error rates, run-times for individual operations, and so on."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Cirq\n",
    "\n",
    "Finally, we come to the simulator of focus in this notebook. Cirq was announced as an open source Python framework for Noisy Intermediate Scale Quantum (NISQ) computers on Google's AI Blog, on July 18, 2018 \\[5\\], fully available at https://github.com/quantumlib/Cirq. Cirq is actively used on Google's \"Bristlecone\" quantum processor, and has even recently been incorporated into TensorFlow Quantum (also by Google), \"an open-source library for the rapid prototyping of quantum ML models\" \\[6\\]. TensorFlow Quantum is a very recent development just announced on March 9, 2020.\n",
    "\n",
    "### Notable features\n",
    "\n",
    "#### Graphical ASCII printing of circuits"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit:\n",
      "(0, 0): ───X^0.5───M('m')───\n",
      "Ran circuit 20 times. Results:\n",
      "m=00101001001100001011\n"
     ]
    }
   ],
   "source": [
    "# This example is modified from https://github.com/quantumlib/Cirq .\n",
    "\n",
    "# Pick a qubit.\n",
    "qubit = cirq.GridQubit(0, 0)\n",
    "\n",
    "# Create a circuit\n",
    "circuit = cirq.Circuit(\n",
    "    cirq.X(qubit)**0.5,  # Square root of NOT.\n",
    "    cirq.measure(qubit, key='m')  # Measurement.\n",
    ")\n",
    "print(\"Circuit:\")\n",
    "print(circuit)\n",
    "\n",
    "# Simulate the circuit several times.\n",
    "simulator = cirq.Simulator()\n",
    "result = simulator.run(circuit, repetitions=20)\n",
    "print(\"Ran circuit 20 times. Results:\")\n",
    "print(result)"
   ]
  },
  {
   "attachments": {
    "898c3b91-7ccd-4a2a-bbe9-32440ec0bc2b.png": {
     "image/png": "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"
    }
   },
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Moment-based circuits\n",
    "\n",
    "![image.png](attachment:898c3b91-7ccd-4a2a-bbe9-32440ec0bc2b.png)\n",
    "\n",
    "(credit [cirq.readthedocs.io]())\n",
    "\n",
    "By grouping operations into \"moments\", Cirq constructs operators in parallel and better simulation of scheduled operations on real hardware. This also permits inspection of the state of a circuit at each moment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0: ───I───H───@───────\n",
      "      │       │\n",
      "1: ───I───────X───@───\n",
      "      │           │\n",
      "2: ───I───H───────X─── \n",
      "\n",
      "state at step 0: |000⟩\n",
      "\n",
      "state at step 1: 0.5|000⟩ + 0.5|001⟩ + 0.5|100⟩ + 0.5|101⟩\n",
      "\n",
      "state at step 2: 0.5|000⟩ + 0.5|001⟩ + 0.5|110⟩ + 0.5|111⟩\n",
      "\n",
      "state at step 3: 0.5|000⟩ + 0.5|001⟩ + 0.5|110⟩ + 0.5|111⟩\n",
      "\n"
     ]
    }
   ],
   "source": [
    "qubits = cirq.LineQubit.range(3)\n",
    "circuit = cirq.Circuit(\n",
    "    cirq.IdentityGate(num_qubits = 3).on(*qubits),\n",
    "    cirq.H(qubits[0]),\n",
    "    cirq.H(qubits[2]),\n",
    "    cirq.CNOT(qubits[0], qubits[1]),\n",
    "    cirq.CNOT(qubits[1], qubits[2])\n",
    ")\n",
    "print(circuit, \"\\n\")\n",
    "\n",
    "simulator = cirq.Simulator()\n",
    "for i, step in enumerate(simulator.simulate_moment_steps(circuit)):\n",
    "    print('state at step %d: %s' % (i, step.dirac_notation(3)) + \"\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Easily extensible operations and classes\n",
    "\n",
    "Cirq is designed to be extensible with abstract classes for gates/operations, simulators, etc. This allows for creation of operations such as unitary operations corresponding to a complex function. The catch is that Cirq allows such operations not to be reflective of the full circuit - that is, the operation does not have to be the sum of normally-defined gates, but can simply hide a classical operation. In the next section, we will see how Cirq can use this to abstract the hardest part of Shor's algorithm."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Shor's algorithm with Cirq\n",
    "\n",
    "### Review\n",
    "\n",
    "A brief review of the procedure for Shor's algorithm \\[7\\] is as follows:\n",
    "\n",
    "___\n",
    "\n",
    "\n",
    "We begin by picking a number $N$ to be factored.\n",
    "\n",
    "##### Classical component\n",
    "\n",
    "1. Pick a random number $a < N$.\n",
    "2. Compute $\\gcd(a, N)$. If $\\gcd(a, N) \\neq 1$, then this common divisor is a nontrivial factor of $N$, so the algorithm is done (though for large numbers it is likely that the algorithm can be run again on those factors). Otherwise, we proceed.\n",
    "3. Use the **quantum component** to determine $r$, the period of the function $f(x) = a^x \\mod N$.\n",
    "4. If any of the following conditions are true, return to step 1.\n",
    "    - $r = 0$\n",
    "    - No candidate $r$ was found\n",
    "    - $r$ is odd\n",
    "    - $a^{\\frac{r}{2}} \\equiv -1 \\mod N$\n",
    "    - $\\gcd(a^{\\frac{r}{2}}+1\\text{ mod }N, N) = 1$\n",
    "5. We can factor $N$ by $\\gcd(a^{\\frac{r}{2}}+1\\text{ mod }N, N)$.\n",
    "\n",
    "##### Quantum component\n",
    "\n",
    "We receive $a, N$ with which we must solve the period $r$ for $f(x) = a^x \\mod N$. We define the unitary operation $$U_f |x, 0^q\\rangle = |x, f(x)\\rangle, \\ \\ f(x) = a^x \\text{ mod } N.$$\n",
    "\n",
    "1. Let $n_0$ be the number of bits in N. Let $n$ be the unique integer satisfying $N^2 \\leq 2^n \\leq 2N^2$. Initialize an input and output qubit register, with $n_0$ and $n$ qubits respectively, to the state $|\\psi_0\\rangle = |0\\ldots 0\\rangle_n|0\\ldots 0\\rangle_{n_0}$.\n",
    "2. Let $q=2^n$. Prepare a superposition $$|\\psi_1\\rangle = \\frac{1}{\\sqrt{q}}\\sum_{x=0}^{q-1}|x\\rangle|0\\rangle$$ by applying $q$ Hadamard gates.\n",
    "3. Apply $U_f$ so that $|\\psi_2\\rangle = U_f|\\psi_1\\rangle.$\n",
    "4. Measure the output register of $|\\psi_2\\rangle$ (recall this register has size $n_0$), and discard the result of that measurement (the point is to force the input register into a particular superposition). This puts the input register into state $$|\\psi_3\\rangle = \\frac{1}{\\sqrt{m}}\\sum_{k=0}^{m-1}|x_0 + kr\\rangle.$$\n",
    "5. Apply the Quantum Fourier Transform (QFT) to $|\\psi_3\\rangle$ to obtain $|\\psi_4\\rangle = QFT|\\psi_3\\rangle$.\n",
    "    - *Note: Many sources describe incorrectly describe this as the \"inverse QFT\". This confusion is due to the fact that QFT is the quantum analog of the inverse discrete Fourier transform - but it should properly be referred to as just \"QFT\". Still, Cirq follows the trend of calling this the \"inverse QFT\".*\n",
    "6. Measure $y$ from the input register of $|\\psi_4\\rangle$.\n",
    "7. Determine the continued fraction representation of $y/q$. Test each convergent $j'/r'$ in order, where $j'/r'$ is reduced to lowest terms. If at any point $r' < N$ and $$|\\frac{y}{q}-\\frac{j'}{r'}|\\leq\\frac{1}{2q}, $$ then $r'$ is the candidate value for the period. Return $r'$ to the classical component's step 3.\n",
    "\n",
    "___\n",
    "\n",
    "With this in mind, let's first examine how Cirq can deal with the circuit for modular exponentiation in Shor's algorithm, satisfying the unitary operation\n",
    "\n",
    "$$U_f |x, 0^q\\rangle = |x, f(x)\\rangle, \\ \\ f(x) = a^x \\text{ mod } N$$\n",
    "\n",
    "This is not at all a simple circuit, and minimizing the number of operations to achieve this unitary function for variables $a, N$ has been the subject of much recent research and contention. Shor's landmark paper did not specify how this unitary operation could be achieved, not even discussing the number of qubits needed for the operation. Given that this operation is seen as **the bottle-neck** for applying Shor's algorithm, the debate over optimizing such a circuit is warranted.\n",
    "\n",
    "In “Fast Quantum Modular Exponentiation Architecture for Shor’s Factorization Algorithm” \\[8\\] (2013), Pavlidis and Gizopoulos present a circuit with a depth near $2000n^2$ requiring $9n+2$ qubits, where $n$ represents the number of bits of the classical number being factored, where \"the total quantum cost of the proposed design is $1600n^3$. The implementation is complicated, and this notebook will not attempt to program that circuit into Cirq. Instead, we'll use a simple trick to ignore the physical circuit requirements entirely, and simply *pretend* we have such a physical device ready for use. The following code creates an ArithmeticOperation in Cirq which sweeps all the troublesome circuitry under the rug."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Code modified from https://github.com/quantumlib/Cirq/blob/master/examples/shor.py\n",
    "\n",
    "from typing import Callable, List, Optional, Sequence, Union\n",
    "\n",
    "class ModularExp(cirq.ArithmeticOperation):\n",
    "    def __init__(self, target: Sequence[cirq.Qid],\n",
    "                 exponent: Union[int, Sequence[cirq.Qid]], base: int,\n",
    "                 modulus: int) -> None:\n",
    "        if len(target) < modulus.bit_length():\n",
    "            raise ValueError(f'Register with {len(target)} qubits is too small '\n",
    "                             f'for modulus {modulus}')\n",
    "        self.target = target\n",
    "        self.exponent = exponent\n",
    "        self.base = base\n",
    "        self.modulus = modulus\n",
    "\n",
    "    def registers(self) -> Sequence[Union[int, Sequence[cirq.Qid]]]:\n",
    "        return self.target, self.exponent, self.base, self.modulus\n",
    "\n",
    "    def with_registers(\n",
    "            self,\n",
    "            *new_registers: Union[int, Sequence['cirq.Qid']],\n",
    "    ) -> cirq.ArithmeticOperation:\n",
    "        if len(new_registers) != 4:\n",
    "            raise ValueError(f'Expected 4 registers (target, exponent, base, '\n",
    "                             f'modulus), but got {len(new_registers)}')\n",
    "        target, exponent, base, modulus = new_registers\n",
    "        return ModularExp(target, exponent, base, modulus)\n",
    "\n",
    "    def apply(self, *register_values: int) -> int:\n",
    "        assert len(register_values) == 4\n",
    "        target, exponent, base, modulus = register_values\n",
    "        if target >= modulus:\n",
    "            return target\n",
    "        return target ^ (base**exponent) % modulus\n",
    "\n",
    "    def _circuit_diagram_info_(\n",
    "            self,\n",
    "            args: cirq.CircuitDiagramInfoArgs,\n",
    "    ) -> cirq.CircuitDiagramInfo:\n",
    "        assert args.known_qubits is not None\n",
    "        wire_symbols: List[str] = []\n",
    "        t, e = 0, 0\n",
    "        for qubit in args.known_qubits:\n",
    "            if qubit in self.target:\n",
    "                if t == 0:\n",
    "                    if isinstance(self.exponent, Sequence):\n",
    "                        e_str = 'e'\n",
    "                    else:\n",
    "                        e_str = str(self.exponent)\n",
    "                    wire_symbols.append(\n",
    "                        f'ModularExp(t*{self.base}**{e_str} % {self.modulus})')\n",
    "                else:\n",
    "                    wire_symbols.append('t' + str(t))\n",
    "                t += 1\n",
    "            if isinstance(self.exponent, Sequence) and qubit in self.exponent:\n",
    "                wire_symbols.append('e' + str(e))\n",
    "                e += 1\n",
    "        return cirq.CircuitDiagramInfo(wire_symbols=tuple(wire_symbols))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This may seem oddly simple for such a complicated circuit. The magic is in the method:\n",
    "\n",
    "```\n",
    "    def apply(self, *register_values: int) -> int:\n",
    "        assert len(register_values) == 4\n",
    "        target, exponent, base, modulus = register_values\n",
    "        if target >= modulus:\n",
    "            return target\n",
    "        return (target * base**exponent) % modulus\n",
    "```\n",
    "\n",
    "Here, we see that this Cirq operation really just wraps `a**x % N`. Of course, this still means we get a classical run-time when factoring numbers, but that is to be expected."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The Algorithm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "'''\n",
    "Attempt to factor N with a single run of Shor's algorithm.\n",
    "If this returns None, then it probablistically failed and\n",
    "must be run again.\n",
    "If this returns -1, then the number is prime.\n",
    "'''\n",
    "\n",
    "def shor_factor(N, seed=None, verbose=False):\n",
    "    if type(N) is not int:\n",
    "        raise TypeError(\"n must be an integer.\")\n",
    "    if N > (2 ** 30):\n",
    "        raise ValueError(\"Number is too large. Try n <= 2^30.\")\n",
    "    if N < 1:\n",
    "        raise ValueError(\"Number must be positive integer greater than 1.\")\n",
    "        \n",
    "    if N % 2 == 0:\n",
    "        if verbose:\n",
    "            print(f\"{N} has trivial factor of 2.\")\n",
    "        return 2, N // 2\n",
    "    \n",
    "    # using sympy.isprime is certainly 'cheating' - but Shor's algorithm\n",
    "    # doesn't work on prime numbers, so we can save some wasted effort here.\n",
    "    if sympy.isprime(N):\n",
    "        if verbose:\n",
    "            print(f\"{N} is prime. Aborting.\")\n",
    "        return -1\n",
    "    \n",
    "    '''\n",
    "    1. Pick a random number  𝑎<𝑁\n",
    "    '''\n",
    "    random.seed(seed)\n",
    "    a = random.randint(2, N-1)\n",
    "    if verbose:\n",
    "        print(f\"Chose random number a={a}.\")\n",
    "    \n",
    "    '''\n",
    "    2. Compute  gcd(𝑎,𝑁) . If  gcd(𝑎,𝑁)≠1 , then this common divisor \n",
    "    is a nontrivial factor of  𝑁 , so the algorithm is done \n",
    "    (though for large numbers it is likely that the algorithm \n",
    "    can be run again on those factors). Otherwise, we proceed.\n",
    "    '''\n",
    "    gcd = math.gcd(N, a)\n",
    "    if gcd != 1:\n",
    "        if verbose:\n",
    "            print(f\"gcd({N}, {a}) is {gcd}, which is a trivial factor.\")\n",
    "        return gcd, N // gcd\n",
    "    if verbose:\n",
    "        print(f\"a is relatively prime to N.\")\n",
    "    \n",
    "    '''\n",
    "    3. Use the quantum component to determine  𝑟 , \n",
    "    the period of the function  𝑓(𝑥)=𝑎^𝑥 mod𝑁 .\n",
    "    '''\n",
    "    if verbose:\n",
    "        print(f\"Finding order of `{a}**x % {N}`.\")\n",
    "    r = quantum_find_order(a, N, seed, verbose)\n",
    "    if verbose:\n",
    "        print(f\"Quantum routine returned period r={r}.\")\n",
    "    \n",
    "    '''\n",
    "    4. If any of the following conditions are true, return to step 1.\n",
    "    '''\n",
    "    # No candidate 𝑟′ was found\n",
    "    # 𝑟 is odd\n",
    "    # 𝑎^(𝑟/2)≡−1mod𝑁\n",
    "    # gcd(𝑎^(r/2),𝑁)=1\n",
    "    if (r == 0 or\n",
    "            r is None or\n",
    "            r % 2 == 1):\n",
    "        if verbose:\n",
    "            print(f\"The period r={r} failed on classical step 4. Try algorithm again.\")\n",
    "        return None\n",
    "    \n",
    "    c = (a**(r // 2)) % N\n",
    "    d = math.gcd(c+1, N)\n",
    "    if (c % N == N-1) or d == 1:\n",
    "        if verbose:\n",
    "            print(f\"The period r={r} failed on classical step 4. Try algorithm again.\")\n",
    "        return None\n",
    "        \n",
    "    '''\n",
    "    5. We can factor  𝑁  into  𝑔𝑐𝑑(𝑎^(𝑟/2)±1,𝑁) .\n",
    "    '''\n",
    "    if verbose:\n",
    "        print(\"Algorithm succeeded. Returning factors.\")\n",
    "    return d, N // d\n",
    "\n",
    "'''\n",
    "The quantum component of Shor's algorithm. Returns 'r',\n",
    "the candidate period.\n",
    "'''\n",
    "def quantum_find_order(a, N, seed=None, verbose=False):\n",
    "    n_0 = N.bit_length()\n",
    "    n = 2 * n_0 + 3\n",
    "    \n",
    "    '''\n",
    "    1. Initialize an input and output qubit register, \n",
    "    with  𝑛  and  𝑛0  qubits respectively, to \n",
    "    the state  |𝜓0⟩=|0…0⟩𝑛|0…0⟩𝑛0 .\n",
    "    '''\n",
    "    input_qubits = cirq.LineQubit.range(n)\n",
    "    output_qubits = cirq.LineQubit.range(n, n + n_0)\n",
    "    order_circuit = cirq.Circuit()\n",
    "\n",
    "    '''\n",
    "    2. Let  𝑞=2^𝑛 . Prepare a superposition\n",
    "    |𝜓1⟩=1𝑞⎯⎯√∑𝑥=0𝑞−1|𝑥⟩|0⟩\n",
    "\n",
    "    by applying  𝑞  Hadamard gates.\n",
    "    '''\n",
    "    q = 2 ** n\n",
    "    order_circuit.append(cirq.H.on_each(*input_qubits))\n",
    "\n",
    "    '''\n",
    "    3. Apply  𝑈𝑓  so that  |𝜓2⟩=𝑈𝑓|𝜓1⟩.\n",
    "    '''\n",
    "    order_circuit.append(\n",
    "        ModularExp(output_qubits, input_qubits, a, N)\n",
    "    )\n",
    "\n",
    "    '''\n",
    "    4. Measure the output register of  |𝜓2⟩  \n",
    "    (recall this register has size  𝑛 ), \n",
    "    and discard the result of that measurement \n",
    "    (the point is to force the input register into \n",
    "    a particular superposition). This puts the input \n",
    "    register into state |𝜓3⟩.\n",
    "    '''\n",
    "    order_circuit.append(cirq.measure(*output_qubits, key='output'))\n",
    "\n",
    "    '''\n",
    "    5. Apply the Quantum Fourier Transform (QFT) \n",
    "    to  |𝜓3⟩  to obtain  |𝜓4⟩=𝑄𝐹𝑇|𝜓3⟩ .\n",
    "    '''\n",
    "    order_circuit.append(cirq.QFT(*input_qubits, inverse=True))\n",
    "\n",
    "    '''\n",
    "    6. Measure  𝑦  from the input register of  |𝜓4⟩\n",
    "    '''\n",
    "    order_circuit.append(cirq.measure(*input_qubits, key='input'))\n",
    "    if verbose:\n",
    "        print(\"Generating order-finding circuit:\\n\")\n",
    "        print(order_circuit, \"\\n\")\n",
    "    simulator = cirq.Simulator(seed=seed)\n",
    "    input_result = simulator.run(order_circuit).measurements['input'][0]\n",
    "    y = int(\"\".join(str(x) for x in input_result), 2)\n",
    "    if verbose:\n",
    "        print(f\"Circuit returned value of input register, y={y}\")\n",
    "\n",
    "    '''\n",
    "    7. Determine the continued fraction representation of  𝑦/𝑞 .\n",
    "    Test each convergent  𝑗′/𝑟′  in order, where  𝑗′/𝑟′  is reduced \n",
    "    to lowest terms. If at any point  𝑟′<𝑁  and |𝑦/𝑞−𝑗′/𝑟′|≤1/2𝑞, \n",
    "    then  𝑟′  is the candidate value for the period. \n",
    "    Return  𝑟′  to the classical component's step 3.\n",
    "    '''\n",
    "    def continued_fraction(num, denom):\n",
    "        res = []\n",
    "        quo, rem = divmod(num, denom)\n",
    "        while rem != 0:\n",
    "            res = res + [quo]\n",
    "            quo, rem = divmod(denom, rem)\n",
    "            denom = (denom-rem)//quo\n",
    "        return res + [quo]\n",
    "    \n",
    "    def cf_to_frac(cf):\n",
    "        num, denom = 1, 0\n",
    "        for u in reversed(cf):\n",
    "            num, denom = denom + (num * u), num\n",
    "        return num, denom\n",
    "\n",
    "    cf = continued_fraction(y, q)\n",
    "    if verbose:\n",
    "        print(f\"Continued fraction for {y}/{q} is {cf}.\")\n",
    "    \n",
    "    # test each convergent\n",
    "    for i in range(len(cf)):\n",
    "        j, r = cf_to_frac(cf[0:i+1])\n",
    "        if math.fabs((y/q)-(j/r)) <= (1/(2*q)):\n",
    "            if verbose:\n",
    "                print(f\"Using convergent j/r = {j}/{r}. Returning to classical routine.\")\n",
    "            if r == 1:\n",
    "                return 0\n",
    "            return r\n",
    "    # all convergents failed\n",
    "    if verbose:\n",
    "        print(\"All convergents failed. Returning to classical routine.\")\n",
    "    return None"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we are ready to run the algorithm. Note that this is a *very expensive* algorithm on classical systems - so we use a rather low $N$ to test the algorithm, or else we wait an eternity to factor a number like 99."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Chose random number a=10.\n",
      "a is relatively prime to N.\n",
      "Finding order of `10**x % 21`.\n",
      "Generating order-finding circuit:\n",
      "\n",
      "0: ────H───e0─────────────────────────QFT^-1────────M('input')───\n",
      "           │                          │             │\n",
      "1: ────H───e1─────────────────────────#2────────────M────────────\n",
      "           │                          │             │\n",
      "2: ────H───e2─────────────────────────#3────────────M────────────\n",
      "           │                          │             │\n",
      "3: ────H───e3─────────────────────────#4────────────M────────────\n",
      "           │                          │             │\n",
      "4: ────H───e4─────────────────────────#5────────────M────────────\n",
      "           │                          │             │\n",
      "5: ────H───e5─────────────────────────#6────────────M────────────\n",
      "           │                          │             │\n",
      "6: ────H───e6─────────────────────────#7────────────M────────────\n",
      "           │                          │             │\n",
      "7: ────H───e7─────────────────────────#8────────────M────────────\n",
      "           │                          │             │\n",
      "8: ────H───e8─────────────────────────#9────────────M────────────\n",
      "           │                          │             │\n",
      "9: ────H───e9─────────────────────────#10───────────M────────────\n",
      "           │                          │             │\n",
      "10: ───H───e10────────────────────────#11───────────M────────────\n",
      "           │                          │             │\n",
      "11: ───H───e11────────────────────────#12───────────M────────────\n",
      "           │                          │             │\n",
      "12: ───H───e12────────────────────────#13───────────M────────────\n",
      "           │\n",
      "13: ───────ModularExp(t*10**e % 21)───M('output')────────────────\n",
      "           │                          │\n",
      "14: ───────t1─────────────────────────M──────────────────────────\n",
      "           │                          │\n",
      "15: ───────t2─────────────────────────M──────────────────────────\n",
      "           │                          │\n",
      "16: ───────t3─────────────────────────M──────────────────────────\n",
      "           │                          │\n",
      "17: ───────t4─────────────────────────M────────────────────────── \n",
      "\n",
      "Circuit returned value of input register, y=4096\n",
      "Continued fraction for 4096/8192 is [0, 2].\n",
      "Using convergent j/r = 1/2. Returning to classical routine.\n",
      "Quantum routine returned period r=2.\n",
      "The period r=2 failed on classical step 4. Try algorithm again.\n",
      "------------------------------\n",
      "\n",
      "Chose random number a=5.\n",
      "a is relatively prime to N.\n",
      "Finding order of `5**x % 21`.\n",
      "Generating order-finding circuit:\n",
      "\n",
      "0: ────H───e0────────────────────────QFT^-1────────M('input')───\n",
      "           │                         │             │\n",
      "1: ────H───e1────────────────────────#2────────────M────────────\n",
      "           │                         │             │\n",
      "2: ────H───e2────────────────────────#3────────────M────────────\n",
      "           │                         │             │\n",
      "3: ────H───e3────────────────────────#4────────────M────────────\n",
      "           │                         │             │\n",
      "4: ────H───e4────────────────────────#5────────────M────────────\n",
      "           │                         │             │\n",
      "5: ────H───e5────────────────────────#6────────────M────────────\n",
      "           │                         │             │\n",
      "6: ────H───e6────────────────────────#7────────────M────────────\n",
      "           │                         │             │\n",
      "7: ────H───e7────────────────────────#8────────────M────────────\n",
      "           │                         │             │\n",
      "8: ────H───e8────────────────────────#9────────────M────────────\n",
      "           │                         │             │\n",
      "9: ────H───e9────────────────────────#10───────────M────────────\n",
      "           │                         │             │\n",
      "10: ───H───e10───────────────────────#11───────────M────────────\n",
      "           │                         │             │\n",
      "11: ───H───e11───────────────────────#12───────────M────────────\n",
      "           │                         │             │\n",
      "12: ───H───e12───────────────────────#13───────────M────────────\n",
      "           │\n",
      "13: ───────ModularExp(t*5**e % 21)───M('output')────────────────\n",
      "           │                         │\n",
      "14: ───────t1────────────────────────M──────────────────────────\n",
      "           │                         │\n",
      "15: ───────t2────────────────────────M──────────────────────────\n",
      "           │                         │\n",
      "16: ───────t3────────────────────────M──────────────────────────\n",
      "           │                         │\n",
      "17: ───────t4────────────────────────M────────────────────────── \n",
      "\n",
      "Circuit returned value of input register, y=0\n",
      "Continued fraction for 0/8192 is [0].\n",
      "Using convergent j/r = 0/1. Returning to classical routine.\n",
      "Quantum routine returned period r=0.\n",
      "The period r=0 failed on classical step 4. Try algorithm again.\n",
      "------------------------------\n",
      "\n",
      "Chose random number a=8.\n",
      "a is relatively prime to N.\n",
      "Finding order of `8**x % 21`.\n",
      "Generating order-finding circuit:\n",
      "\n",
      "0: ────H───e0────────────────────────QFT^-1────────M('input')───\n",
      "           │                         │             │\n",
      "1: ────H───e1────────────────────────#2────────────M────────────\n",
      "           │                         │             │\n",
      "2: ────H───e2────────────────────────#3────────────M────────────\n",
      "           │                         │             │\n",
      "3: ────H───e3────────────────────────#4────────────M────────────\n",
      "           │                         │             │\n",
      "4: ────H───e4────────────────────────#5────────────M────────────\n",
      "           │                         │             │\n",
      "5: ────H───e5────────────────────────#6────────────M────────────\n",
      "           │                         │             │\n",
      "6: ────H───e6────────────────────────#7────────────M────────────\n",
      "           │                         │             │\n",
      "7: ────H───e7────────────────────────#8────────────M────────────\n",
      "           │                         │             │\n",
      "8: ────H───e8────────────────────────#9────────────M────────────\n",
      "           │                         │             │\n",
      "9: ────H───e9────────────────────────#10───────────M────────────\n",
      "           │                         │             │\n",
      "10: ───H───e10───────────────────────#11───────────M────────────\n",
      "           │                         │             │\n",
      "11: ───H───e11───────────────────────#12───────────M────────────\n",
      "           │                         │             │\n",
      "12: ───H───e12───────────────────────#13───────────M────────────\n",
      "           │\n",
      "13: ───────ModularExp(t*8**e % 21)───M('output')────────────────\n",
      "           │                         │\n",
      "14: ───────t1────────────────────────M──────────────────────────\n",
      "           │                         │\n",
      "15: ───────t2────────────────────────M──────────────────────────\n",
      "           │                         │\n",
      "16: ───────t3────────────────────────M──────────────────────────\n",
      "           │                         │\n",
      "17: ───────t4────────────────────────M────────────────────────── \n",
      "\n",
      "Circuit returned value of input register, y=4096\n",
      "Continued fraction for 4096/8192 is [0, 2].\n",
      "Using convergent j/r = 1/2. Returning to classical routine.\n",
      "Quantum routine returned period r=2.\n",
      "Algorithm succeeded. Returning factors.\n",
      "(3, 7)\n"
     ]
    }
   ],
   "source": [
    "for i in range(5):\n",
    "    res = shor_factor(21, seed=i+13, verbose=True)\n",
    "    if res:\n",
    "        print(res)\n",
    "        break\n",
    "    print(\"-\"*30 + \"\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sources:\n",
    "\n",
    "\\[1\\]: E. Knill. Conventions for quantum pseudocode. Technical Report LAUR-96-2724, LANL, 1996. (https://pdfs.semanticscholar.org/60d1/e63ca31555ec7013c5eb9a8a63788398fd14.pdf)\n",
    "\n",
    "\\[2\\]: Selinger, Peter. (2004). A Brief Survey of Quantum Programming Languages. 1-6. (https://www.mscs.dal.ca/~selinger/papers/flops04.pdf)\n",
    "\n",
    "\\[3\\]: B. Ömer, A Procedural Formalism for Quantum Computing, Master thesis (computing science), Technical University of Vienna, 1998. (http://tph.tuwien.ac.at/~oemer/doc/qcldoc.pdf)\n",
    "\n",
    "\\[4\\]: Selinger, Peter. “Towards a Quantum Programming Language.” Mathematical Structures in Computer Science, vol. 14, no. 4, Aug. 2004, pp. 527–86. Cambridge Core, doi:10.1017/S0960129504004256. (https://www.mscs.dal.ca/~selinger/papers/qpl.pdf)\n",
    "\n",
    "\\[5\\]: \"Announcing Cirq: An Open Source Framework for NISQ Algorithms.\" (https://ai.googleblog.com/2018/07/announcing-cirq-open-source-framework.html)\n",
    "\n",
    "\\[6\\]: \"Announcing TensorFlow Quantum: An Open Source Library for Quantum Machine Learning.\" (https://ai.googleblog.com/2020/03/announcing-tensorflow-quantum-open.html)\n",
    "\n",
    "\\[7\\]: Shor, Peter W. “Polynomial-Time Algorithms for Prime Factorization and Discrete Logarithms on a Quantum Computer.” SIAM Journal on Computing, vol. 26, no. 5, Oct. 1997, pp. 1484–509. arXiv.org, doi:10.1137/S0097539795293172. (https://arxiv.org/pdf/quant-ph/9508027.pdf)\n",
    "\n",
    "\\[7\\]: Pavlidis, Archimedes, and Dimitris Gizopoulos. “Fast Quantum Modular Exponentiation Architecture for Shor’s Factorization Algorithm.” ArXiv:1207.0511 [Quant-Ph], Nov. 2013. arXiv.org, http://arxiv.org/abs/1207.0511. (https://arxiv.org/pdf/1207.0511.pdf)\n",
    "\n",
    "\\[8\\]: Cirq on GitHub. (https://github.com/quantumlib/Cirq/blob/master/)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.7"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {
    "height": "121px",
    "width": "160px"
   },
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "336px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}