Qiskit - Deutsch-Jozsa - Bruna SM.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Deutsch-Jozsa \n",
    "==============\n",
    "\n",
    "*Author: Bruna Shinohara de Mendonça. Last updated: 10 May 2022.*\n",
    "\n",
    "This might not be you first rodeo with the concept of Oracle [1], but here we will find it in a different context.\n",
    "\n",
    "Consider that we have a function that, given an input (the qubits in the register), it may return:\n",
    "\n",
    "I - All measurements in state $\\vert 0 \\rangle$ or in state $\\vert 1 \\rangle$;\n",
    "\n",
    "II - Half of the measurements are in state $\\vert 0 \\rangle$ and half in state $\\vert 1 \\rangle$.\n",
    "\n",
    "Function I is said to be **constant** and function II is said to be **balanced**.\n",
    "\n",
    "Going back to classical computation: how could we differentiate these functions?\n",
    "In that situation, we may need to check half of the inputs and one more: this would be the \"worst case\" scenario, i.e., the situation where all the states in the first half are either zero or one, so we would need to check one more state to make sure it is (or isn't constant). In other words, for a number $n$ of inputs, the worst case scenario requires"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "$$\\text{Shots}_{\\text{Classical}} = n/2 +1$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Let's get quantum?\n",
    "==============\n",
    "\n",
    "The neat thing about Deutsch-Jozsa algorithm is that calling the function only one time is enough to tell its type!\n",
    "We don't even have a \"worst\" case, since we always have"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "$$\\text{Shots}_{\\text{Quantum}} = 1$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "How?\n",
    "===========================================\n",
    "\n",
    "Here is the algorithm for a generic number of input qubits.\n",
    "We need two registers: one will store the $n$ qubits that will be used as input, initialized in $\\vert 0 \\rangle$. \n",
    "The other will store a $\\vert 1 \\rangle$ state, that will work as an auxiliary qubit.\n",
    "\n",
    "Thus, our first step is:\n",
    "\n",
    "<ol>\n",
    "   <li>\n",
    "        Prepare two quantum registers as instructed above:\n",
    "        \n",
    "\n",
    "$$\n",
    "\\vert \\psi_0 \\rangle = \\vert0\\rangle^{\\otimes n} \\vert 1\\rangle$$\n",
    "\n",
    "\n",
    "   </li>\n",
    "    \n",
    "   <li>\n",
    "        Apply Hadamard gates to all qubits, including the auxiliary one. We may write the obtained state as:\n",
    "        \n",
    "\n",
    "$$\\vert \\psi_1 \\rangle = \\frac{1}{\\sqrt{2^{n+1}}}\\sum_{x=0}^{2^n-1} \\vert x\\rangle \\left(|0\\rangle - |1 \\rangle \\right)$$\n",
    "\n",
    "Note the appearance of a misterious $\\vert x \\rangle$ state. This generic way of writing it is intentional, since this state is only necessary for the implementation of the oracle, but it does not intefere in the final state.\n",
    "       \n",
    "   </li>\n",
    "   \n",
    "   <li>\n",
    "        Apply the quantum oracle. Here, it will act as $\\vert x\\rangle \\vert y\\rangle$ to $\\vert x\\rangle \\vert y \\oplus f(x)\\rangle$,  $\\oplus$ being the operation of addition modulo 2 [2]:\n",
    "        $$\n",
    "            \\begin{aligned}\n",
    "            \\lvert \\psi_2 \\rangle  \n",
    "                & = \\frac{1}{\\sqrt{2^{n+1}}}\\sum_{x=0}^{2^n-1} \\vert x\\rangle (\\vert f(x)\\rangle - \\vert 1 \\oplus f(x)\\rangle) \\\\  \n",
    "                & = \\frac{1}{\\sqrt{2^{n+1}}}\\sum_{x=0}^{2^n-1}(-1)^{f(x)}|x\\rangle ( |0\\rangle - |1\\rangle ) \n",
    "        \\end{aligned}\n",
    "        $$\n",
    "       \n",
    "   </li>\n",
    "\n",
    "   <li>\n",
    "       We now apply Hadamard gates to all qubit in the first register:\n",
    "        $$\n",
    "        \\begin{aligned}\n",
    "            \\lvert \\psi_3 \\rangle \n",
    "                & = \\frac{1}{2^n}\\sum_{x=0}^{2^n-1}(-1)^{f(x)}\n",
    "                    \\left[ \\sum_{y=0}^{2^n-1}(-1)^{x \\cdot y} \n",
    "                    \\vert y \\rangle \\right] \\\\\n",
    "                & = \\frac{1}{2^n}\\sum_{y=0}^{2^n-1}\n",
    "                    \\left[ \\sum_{x=0}^{2^n-1}(-1)^{f(x)}(-1)^{x \\cdot y} \\right]\n",
    "                    \\vert y \\rangle\n",
    "        \\end{aligned}\n",
    "        $$\n",
    "       \n",
    "where $x \\cdot y = x_0y_0 \\oplus x_1y_1 \\oplus \\ldots \\oplus x_{n-1}y_{n-1}$.\n",
    "       \n",
    "The $\\vert x\\rangle$ state is already omitted from the equations, as it does not interfere at all after this point.\n",
    "   </li>\n",
    "\n",
    "   <li>\n",
    "       Measure the first register.\n",
    "   </li>\n",
    "We will have two possible outputs when evaluating the probability of the final state to be in $\\vert 0 \\rangle ^{\\otimes n}$. \n",
    "This is given by \n",
    "\n",
    "$$P(\\vert 0 \\rangle ^{\\otimes n}) = \\lvert \\frac{1}{2^n}\\sum_{x=0}^{2^n-1}(-1)^{f(x)}(-1)^{x \\cdot y} \\langle 0^{\\otimes n}\\vert y \\rangle \\rvert^2$$\n",
    "    \n",
    "Note that $\\langle 0^{\\otimes n}\\vert y \\rangle = 1$ if $\\vert y \\rangle = \\vert 0^{\\otimes n}\\rangle$ (and zero otherwise). \n",
    "When $\\langle 0^{\\otimes n}\\vert y \\rangle = 1$, $(-1)^{f(x)}(-1)^{x \\cdot y} = (-1)^{f(x)}$\n",
    "    \n",
    "Therefore, our probability reduces to     \n",
    "$$P(\\vert 0 \\rangle ^{\\otimes n}) = \\lvert \\frac{1}{2^n}\\sum_{x=0}^{2^n-1}(-1)^{f(x)}\\rvert^2$$\n",
    "    \n",
    "Now, if our f(x) is balanced, the equal number of zeros and ones will cancel the terms in the summation. Something like:\n",
    "    \n",
    "$$P(\\vert 0 \\rangle ^{\\otimes n}) = \\lvert \\frac{1}{2^n}(-1)^{0}+(-1)^{1}+(-1)^{0}+(-1)^{1}+...\\rvert^2 = 0$$\n",
    "\n",
    "However, if our f(x) is constant, the sum would lead to:\n",
    "    \n",
    "$$P(\\vert 0 \\rangle ^{\\otimes n}) = \\lvert \\frac{1}{2^n}(-1)^{f(x)}2^n\\rvert^2 = 1$$\n",
    "    \n",
    "since $\\lvert(-1)^{0}\\lvert^2 = \\lvert(-1)^{1}\\lvert^2 = 1$.\n",
    "    \n",
    "Here is a sketch of the circuit:\n",
    "</ol>\n"
   ]
  },
  {
   "attachments": {
    "Untitled%20Diagram.drawio%281%29.png": {
     "image/png": "iVBORw0KGgoAAAANSUhEUgAAAcIAAACRCAYAAABQdbioAAAH6nRFWHRteGZpbGUAJTNDbXhmaWxlJTIwaG9zdCUzRCUyMmFwcC5kaWFncmFtcy5uZXQlMjIlMjBtb2RpZmllZCUzRCUyMjIwMjItMDQtMThUMTElM0EyNCUzQTU5LjE2NVolMjIlMjBhZ2VudCUzRCUyMjUuMCUyMChXaW5kb3dzKSUyMiUyMGV0YWclM0QlMjJLSFo5amhiaTRBUjU0MGhhZjBaNyUyMiUyMHZlcnNpb24lM0QlMjIxNy40LjUlMjIlM0UlM0NkaWFncmFtJTIwaWQlM0QlMjIzaU5YNWtfSEdyVmtycExHdGJGQiUyMiUyMG5hbWUlM0QlMjJQYWdlLTElMjIlM0U3VnBaYjZNNkdQMDFlV3dFR0VoNHpESXp2ZEpVazFFMGF1JTJCakF3NnhTakExcGxsJTJCJTJGZGhnTmtNSFVtV3AxT2FoTXNmT1olMkJOenZzVnVCbUMyM2YlMkJnTU5vOEVBOEZBMFB6OWdNd0h4akd5RGI0WHdFY01zRFU3QXp3S2ZZeVNDJTJCQkpUNGlDV29TVGJDSDR0cEFSa2pBY0ZRSFhSS0d5R1UxREZKS2R2VmhheExVWjQyZ2p4ckEwb1ZCRTMzRUh0dGs2TmdZbGZnOXd2NG1uMW0zbmF4bkMlMkZQQjBrUzhnUjdaWlZENmN1RGJBTXdvSVN4cmJmY3pGSWk5eSUyRmNsMjRIdmIlMkZRV0M2TW9aSDIlMkI4UExuNmZkaWN6OEo0OFhUNCUyRmIlMkI0WThaYmUlMkJzek1vckRCTDV3bkt4N0pEdkFBcTlpZGhJJTJGaFNTa0lQVERkc0clMkZFbm5UVXFTMEVOaUJvMCUyRnhjJTJCSXVSdlpsUmxDWG1OJTJGeXdYcnhUWnclMkJTQ3lSWXdlJTJCSkJkdWRHV2xNR21zc2M1UmxFQUdYNnRtNGVTYjc4d1Y4eXdJSmhQYkdoU21vWW03VWhsR21PdGJpSW1DWFdSJTJGRloxWXhWRGx0TmhpRUhxSTlZd3hCdVYxeTZobExjVE9CeCUyRllnNkJzdlhXT3pua2NhbHV5T3pISWQ5VmVLZ01pOFNBJTJCQjhMdHBSNVFNMXBlU096ZUZhQjVMSDBVeXBFOVhLVjJIZDdlVSUyQkZuSTFFMEUwaVR6R1JhRkwwa21DS3ZQOUNodWdhdWdxZHI0Z3l6RlBjVDdoQ3dZTEVtR0VTOHI0VllZeHNWWWJYT0FobUpDQTBuUU1Bb0duNmhPTSUyQmhSN21KRmY2blBURCUyQnp3JTJCdXl1dGhvUUtucWN4byUyQlM1U0tKR29SMnhHclElMkZWVDA1S3lPRkZRTU1IVE9ES2dJRExRTFQ3V0ZlaTdUSnFjYmZ5V1E1SjNtY0c4QTR4bTV2cDBON3pKNWtoMmolMkZMOXBEU3o3Tjk1V3UlMkJhSHlzRUFVOHhkRVZHSjluWmV2TyUyRldTVG5uZXlzc2J6dm5lUEdEcnFwNnU2JTJCVzVUdnA0T1ZtdkY3ejhuR1dWciUyRkRCNlc2REdWcEdxY2ZQZDd3Z3IwdEtjZVdwTlFMT3ZNT1ZLV0ZRZXZLZDAxQmlVZFJxMHZ4U3J2T0klMkZTUDBMJTJCWDIlMkJzaXMweVNjMmRUS2o5RU1BY2JRYXVyUDFJY2o1MEpCd0RnaFluOXhXWEpwYTBQZHFuQUpQZ0NYbyUyRjVVdXNrS2RkTzN5cUw3ejFVQlFQZlpUMlAlMkJyNFFGV0pSZ0tlNUIlMkJ2eUxtOEVzamVSRHphcURSb3Fla3FobGZkZEk4azI2YzBHSUVWR2VPOFE3NGREUDg5SWxKQUhVS2ptUHdoVU42RVpMT2xGUFh1Zno1YmFEc2gwd1FhcG8lMkJTeDk4d3haa3pTbFpJVVhIMnElMkZKT0tRUDUyUkxVJTJGeWhyYUVJVDhpYUElMkZMc2lzM29lVTIlMkJDb3pNM1hUSEs3T3AwaVE3emlyeXd3RzJCZnU3cUl3VGZ0RjdUZVJIVnZzZWVMclU0cGlmSVNyMUpRZ1ZwNWt1RjFyT3JCRVpJRUo0N1hpTVJkbXhyd2lxcW9HSlhTV0VLSG9RZTlkNWFtRndQa1VZYiUyQnBDQSUyQiUyRnFyeWRWU1Q2YVNJcHdOcTZQcXQwTEZ1RTBOdEtweTJiU0ozb05WcHk1Z1hMZDlrR1R2Z0FTNHYyVFZrb3lqclp5cnUwT0FEZmU2aFIlMkZ4aTZPNE9lVFBVJTJCb2YzQWFiYm95Ym1ZbnRwdUFLV2VnRW9IUG1NZ0NydXBiMHduNUFBJTJCaGh5dUdJYlUlMkIwWGRhVlkwYlFYTnhXS1FybmRYdE9VTmhONWQwRFlMUWJHVGolMkZtN21HSTBkRGNKUlQlMkZFViUyQmZqRXBpRWZqcWxhZjNqWE5OZHJwNkRwbkYzNGRtV0tzREZhT3B4SCUyRkJGa3pHNk1VMDlydnMlMkJIMHZXVzNkcHQySUp0RjNJWEtBJTJCdiUyQjlJaXl2NmRheHJkZVAwNXVlMnRUa3dyNnlST0luYXlxa0slMkZLV21mbW9hV1hVMWFiMHJjJTJGdGlhcnJTdGRHWG1zNnRKa3U3cHByNFklMkZsRG9PeCUyRlNlV3ZxY0MzdnclM0QlM0QlM0MlMkZkaWFncmFtJTNFJTNDJTJGbXhmaWxlJTNF30EWlgAAIABJREFUeF7snQWcVUX7x59zN9ll6VxAllZKROwAjL9Sdr4WDfpapC3YRfoqipQdmEgYr752EyqIICDdDVts3PP//g73rJdlaQWUM5+dz7177pw5M8+Zmd88OY4FKaBAQIGAAgEFAgocwhRwDuG+B10PKBBQIKBAQIGAAhYAYTAIAgoEFAgoEFDgkKZAAISH9OsPOh9QIKBAQIGAAgEQBmMgoEBAgYACAQUOaQoEQHhIv/6g8wEFAgoEFAgoEABhMAYCCgQUCCgQUOCQpkAAhIf06w86H1AgoEBAgYACARAGYyCgQECBgAIBBQ5pCgRAeEi//qDzAQUCCgQUCCgQAGEwBgIKBBQIKBBQ4JCmQACEh/TrDzofUCCgQECBgAIBEAZjIKBAQIGAAgEFDmkKBEB4SL/+oPMBBQIKBBQIKBAAYTAGAgoEFAgoEFDgkKZAAISH9OsPOh9QIKBAQIGAAgEQBmMgoEBAgYACAQUOaQoEQHhIv/6g8wEFAgoEFAgoEABhMAYCCgQUCCgQUOCQpkAAhIf06w86H1AgoEBAgYACARAGYyCgQECBgAIBBQ5pCgRAeEi//qDzAQUCCgQUCCgQAGEwBgIKBBQIKBBQ4JCmQACEh/TrDzofUCCgQECBgAIBEO7bGOjG7U+Tu5M7k5uRPyCfvW/VBncHFAgoEFAgoMD+okCRQDix9+iXzHVbOykJ1Vv3v3LTrhozsceoPhaya+Nj41qc+cjVi3ZV/h/0+/v05axIf9bzuY5ci3wK+ct/UD+DrgQUCCgQUOAfS4EigXB8zxGXhpzQy2aO47ru0LaDOvXYFQUm9Bw1xRxr4jjh+9oM6NJ/V+X/Ib/PjQDf5AgXeB+f1wZA+A95u0E3AgoEFDgkKLBD0eg7PUdXi3Pc2VChmDgdCt7YemCnl3ZGlYm9Rw11XevumDPdwk6HNoM7TP8HU7EmfZtHFidYh7yW7APjARM5v9vjmQbnDO76y+7SfVLfF6u2fvTKJbtbPigXUCCgwJ5RYFLPkbdYyOkDU3Ffm4Gdh+7Z3UHp/UGBnS7Y43s8VyUUypsCZ1iOxuSYhWeHXOvdalDnj3fUuAm9RlzgWOhl19w4Pru1Gdhx5P7oyAF4xmU88xXyg+Q7Is93I+BY+wC0xyb1HvUlG5GTIs/OiHXiGp014Or5RbXl7f5jSsVvCi+Eiy9hrrMow91w+CWDe2YdiHb/zZ4ZT3ujc8Jf9H/03NzV9139LhIXVSbM9Wzylsjn7nzXGNlYKOu+IBVBgQ/7jmqWm28/RP2Uj7Tt/lYDOvSPXCvJZ9lI1riKvePcf/crW7yU7A3m9XzpgXP41CY7MyDwX0eBXXIuvMhUXuQnZi4cUCiXzxxW+/+GzOnXemDHmUU1bVzvEY1j3dDr/FbSXJuQUWLxdZf07w+Q/qNSX3rzCDlaHyggPFDGMpUbVa23NCt3i9Ok+hFWJrmkxYZibXN2+uQXvnrn8chClxGZUJkD/3XnsFJJxY92HLYrTkgvZtXjk549aeqSX7TQVSBXJNcnXx25R4A/4W/yBrWwTyXrfcRocYl86nvhXPg3EcMvo+/+//73vwkJ9msz83ma5rfork8BY3Suyv8NyZKeHErp+qPTGvZfvmFV2bAbtlLJJSwnL8+ycrKZlxnhjC2ZMImuxtruJNFT9NtATidrfmoTpjk9h/wQ+bPdqSgosz0FBIQauJrkGsRK/oTXAqGkQZ6bGJeQEBOKCbFu5rPAxsSEQrYlNzc9MydzY9jlLf9xr15sPOLRmPi4uGR98jsDIEfP0stM+oe8iAfoh/SB2rn9HumTjGWeIvsc4l/d1VI84AryJeRT/+qHUf9C8pXkg9kQSONYO+sgHVwU0AYrmazNyT89icuTId3x+7mj2HV460GQtlKgBVmSO1n17zQJnPb3wFzKMxuRD7Xd4a7exd78/h03HRt9Y8mkFMvckm25+TDv+55UicBdu08/reBL5X2v+i+rQZzgUZHaNbZ/JC8ma0OXF8n5KRZ/dLzFHJFr7pRNlv0F19VXP2tzqO/6zDnMSsBRO84i26hFRvX42d8A6jNc0ZKbF7eEW/PMnbrQ1t+qa2RtLPXpzzW1KVTHyrzDxWLzbJ1cbVSfNpA+B+vPyZgqVvycBIvvjqphxXxb36EQ1bYRd9a0MoOool665T26yjarT/rdz2qH9z3J4ipWsOT/UGfuQtvYMVKnftdz/XZ6/1e25CvjLe6sXAtPXWabnoj0R7d4YoRIeW08kipZ8XvD5savsowR/C/bAm16NXaOI8eRxbnULdSHf+K/0dbkOczJbESdJZITkkxMQX5+vuWH8y2HObolN8eycrOZs1m5ufl5noi5WHxicRgI/iAaUp3EeDF+lrFy45rf+NSGQmNTYCsaV4p89+l4Ll/e/ScSdRd9Ei1OILeIfB4TRZd6fBftdpi8QS/x2PVnXJ0/fclv73766zdaSEpEKinDp7ImsiZruE6lGo2KJySVhjeM2ZSVubRiyXKHcX9WfExM/oK1y76du2LBT5TbTNbO3MsXHXt2mw3pm8/4aOZX2hEqrSZLpChjnCDtHQUklpV41l9sJS4Z+G7PZyYj6hw3b+Wi0KK1y0x5fcZGy8zJ0mTjM9s2ZG7KXLN53WbK5VYvV6VKSrHiTkpishUnpzBZy5cot/iZj145J9dyBSJKGlQPk0+L/C9u+M69a/Zffhc6bWtK1mKhxVepP7nA0Ku6lT47yWIlLt7yq63WONQC5EtAVN7/7gBYb7AiVcu0vBFLbOMLUa2PLs+KH1OqipV8K2xO9jxb245ymi9FplpWdoRjbu0Myx283DbvcNFKteKnJVm86Jw719ZJV6T5JMDcru6qVuL8RIu9Md/CP823DbLyLnKDW8xiytFO6bZjAPaLcyxf+qci6yxjiTXKWNJoAHPNPFt/KeV84N+uX7WszPOoS6plAcLQSWoRPV8bD7X5fLJE60qSJkh6sb834Dt6HX/29UQqlLhSG4VJZNEt/b1eo3uwSWCjsuPEYrw4xnUu2+LmbUT6pnV4W8mGY8+3GdDpmiJquJtr90SuSx+5zeb4z+7gQVaf5vuRZI1hjTeJjleRi5NlrHkm2dtJ7IL2WwfkmzcNCxeLTXR4WXOdPOeqNkM7itsoMk3sOVKD+gqUS9Il3c1CcRjj+qpw2N0IKP7iuOF7Ww/q8m30zRN6jbzuw+lfDHj8w+eE3EpqrDhDfQZpDylQo3zV7+evXiKAUtLCczN5mf4Z3+fpOiE3bgpvNmUn1eajn3gGWfd4BoAmbOH0Q5uBnQpPKLmJHE2W4t7f1Oxhy//y4jN4QgPyh2SJprSpU3qePIaFvS4L/BOM2dgcy3sFjuhFrmvSKGmDVpBqWumBlGOSOZsAt3/xg8C1Blm+stvovGtbmbe5VnKpbbw8y/JX8t3fRMqSuCClWckbYi3mgnxzf4bD680PAhfmj2eAIu7bSxWs2NEpVuwxFkd3vWX3W2uZ33BZC6Oerw1kARgWt/gKla34q1SUAYd5QaSd5fnUXCvw64UDLnmYlfT6m2E5Q5Zbut67NsMy7pKkRm3wUoLFJFezkuP46gLCbfkUoKlPqnebDWyalX4g1pwTIiCsPimpT+JeJEFQkhpBInwrbcXy1luWv0nxH/lP+TyDjvw30hnp1ws2T5P6jOzthp3HdtVRNh5vhVx3rOvEsGFxt7HjYK4ObDuwk0/j6Kqw4/C4oYNtbpamTdoYShKg9V66Yn+DpE9xa1pXxDzJZ30N+VeyxpiyxuXOkiQa95MlpZLNijYE2nyMJQ8ja2OwywAnBaLR7qddfnq7o05/i40Mk81N4IdP8sOx17QbfE2RDZnUe/T1MgfmxaxxXJvkWPgV1IH9AdK63Fsazv617Lzcey4c0m2534uJPUddCFc4dvD7o32xinRrh5P/FDneLgj2j/l5Qs+RT3cdc3u3ZetXmUShL107ZC6TQy4cBWnSbaPLW447hfdTbWcd5/cNvIz3+ZQsfZvEe/wSlxlxTH6SRaqvH/yc780PQqJKBCJavEl+NTIZtHjD5jkT6lr5FozV3JCFUn6zVfVZ3TWBUsmadAVAeLiVezjGQv+Cy3GzLe+2ObZWQFeFrJ1ntHtKXgOr9ELI3LMBgrEzbXVP71FmR5AlChTH5aUGVv5K6hQnuulnW6kFQYtWGllA/DNZCwOoVLFhsjmf8V5iuPDmdFtxI5c1V7WQCGR9nbRXbxOrtIr3l/CTrVD7VKf6K/ce1SnuhF1LcnItS2HBcau45vyPOrVIa96pHeKItfj4KbaRVYKObuk1lnkqXKv6oV21ysoKuQCwj7AKj8aYcyU03TTdVmvjJPBTUAltQESnAsBOtvi5ALBvHDKa3zpFPfMf8bVWhcPC81YtcmRM8foNT/564ePXyeCsIE3oPfIWx3UkXdlV2sgL/y/v9aLCBV3X6dN2UMcBha4/yf/XRd6NrFAPdNIcVHuuJ28jPdnDhn1Peek+lbfZqBaqJ43/tVmUqFhSFNkzCAhl07BLUXG0jlB6lR8n9ho1j3dYNhy2bH6sALCNKl4i5oaW/TtsZyI9odcYXCXCLDYu3IezKS/WOsTmu6cDgvfAjTAhnBrY0dzddlDngpf2Xq9RJ7/y7YSJz3/1trdTh4P8GUAVaxuk3aQA72hD19F3lFy6foVVK5tqT7eXH79lh9xwl1aDumjH76Ux7cckVigb1o5IC9jOk8sgc7wFtFByP8H3yReJ6jctiuIgBBzaxBxsaQENqk6W+O8Z0YX8GlkcCnbqxTLgYLQRe22KLRPASK8gfXWBiftRVqUXu/KHALfFcIT5lNPc0OIujkjiYolfvNTUKt/BYqUXsHKaLdeu1wcXiapn/VEutR1z6R3mlLPJ8urOs9Xi3lVfGllcrFdnA0s9LM7cX3k2BmehTetsY/35liEw8V1ytHv2AFPpKEudTVvr5lve9QDRGC6pb03IC8i+f2h8E6ssCc+RAPvaqbZM4C/9ncBSICzpTXSdX1HnibT3qZ9tRR9+0/NVp3brBRwufb+dvj8gZVbYwi1/tBVf87ukRGrrNnTi+dOps+EMW7kUbliArfQcub3fl7/7J+5Lg68e3vvmNZvXW1r5qvbk1SyDrrsF4Lq83eBO2kh5aUKvUbczDqRe2HVy2fg42+jo+VdxTtyObQZ1ejaqAn9eyrf5gLhvRbVFumxtdAonzQ2JK8X9+bpOSSTFNWouCMAFZDtKMkL0ReyFy2iDLl20JCwCX6mNNKd8qdlOaR0NhGLpPf/ASb1Gf0PrjjQ3/C5IdQGglus6ANrALgML1za+96gT8C18hfJzeD11nZDbofWALv9jUNyFLWk/3pleTDZa4rvbDO4iUYu913dUvSc+ePGLiT994i28gOEXvNj9YfW4U2L8XX4ECF97ZMLwSz6f/b1VK1PZnu4gyYCf3P8CXP8X3RdE2Z9D5GjObk+7+jliUp/7k3uI6tdC5xul7Gl9f2V5AYwWei2yz5IXlLLkkhmWNQWDD48bKW/JbiVLrD/d1srqVhNQoK5xKmBBF+e+zWIzjslxPrPqzGm2TDtR+dKKu/P1ppSt1AruaoLALd1yGsA16tniwFVvAbgcaZWOBZ2YqE4cAHf3FFsxhN816dPUvkhGdpRaLtncWcyleLisjYDLHdNshcSXAliJRQWYAiMvNbVU6e86kD8FhKRDFJhJLKwFwAes+COt8sc8/yT0knmOxZw1xZYKTLVYyuBimzqPssoyw7+FOmdSpxYWLVR6vnb16rsHmDz7Usqw2YC/MXfEVFsucZ0WNG0YBMAFgNnEUuFW3OtcC3/4k61UfN73yP4mSiLrovRefjf/Np9a8658qte96zI22NmNm9sNZ4rp3pr0jmJinO6tHu3kiZUn9hoJ1+J4O9i9TKg28i9oO6irz+1IBK6xJ6t1cWIHKt3Lg++KergAWpyZ5sM26rIdNFDqHK1VytItS3QaneTCpf7JAE5J9gC6JomF7kGq6W1GNQ+kxpm2O4SIBkJfrurdR5SYN3h75zPKHwDoGvH5fxTeAGDdykIbbTSgl1qdhUNguIHtSnPK9Gk7sPOw8bcMPyyUG3s3187n3mwW46/Cofx+bR/t8utbtz1XdsAbQ6d/PWeqZ4EY48SMz3fzNZmDtBsUOLPhyZv/O+PL4mWLl7bnuxWWkthGXANvbP1YJy0y/vt8j/e5S1n5jh/tfE1wBIlGfSCUiEwcxcGWfNASN/gKs2NJPas0YYvlVf/N1m5mQfK5XolOZQUpXZV2k1lNrcrxLNaytvwI4KjqWihrqi2VXkviLe1gNak8zq2pla/tWqwMwxIBw6d+tGW38V3+crKSFCfo6cYAlurMC4l3yiGOnUJ9J/NdC5bEsdoZC4jyKlrF5MoWmg2oFA9ZzGLaOQPOTaJDTXSBkOor4DCPscpdQaThLLEbAUs9U/pA1Svdrc81AoKV3oAL1NyFqwsN5vlaqMTdqZwWkwLAOtqqXIN4d7TmKtytQE1co+oUYAoExeVaY0ttGmPuN7QVqVFoORxzYy5rHqusOPAowKx0CQZEcOTuSoBV4Ksdu2hA272NgJIMmSTC+tsnRKKuLEOvOul8u+x4qVYLJ+f+1gM63M3m30VVBKPgGXLtZXLzLBQ6v81jHQUEGkvi7sXBb7cg7OUD9vS2ftzg90fj9SaydHX7kgSGmgdtoirRfNImrTNZ81xifY0pSXY0rlR+IlkWtLuVooHw39wh5C5IE3qPfgwurzf8/XAWhtfDjoN+w63MxF/KonoHMUgLZK+Tuw6PW5ES8yoTI4V3XA5u8AtYdxHCJvQYcQovTC+/LlxmKvc/mpyyuF/L/v3zGlSps+SXpXM8UUl8TNxzmBS3362WB4XEBt6RlFDMXr9e63mR6SM4OVlNeQnO8B02I7s9OLar0bXJvFMZTQgQpafS7v9gSwIqLdwiypv1rcIT6AbrZVr+BRiuH4Gl5MNwhr4BgsRVErfMa2pVDwtb/jTG+W8AxwDA6+XVltGM8r7BkTgxgZZSCL3cXMa6gG8JHKNEzz64CYi9cmmWlljKshG5Og2oN6ME4PLpVk5QwKpdqw8uMXCX4hQElnpOWdDkyF9smUS84gRF8wIOsxk6RFbAn8SJ5pvT7GdbJr2onq+6fTErIFjxKfqCjslJ4fMnAEtiIukZJb6UYUyBmBUQbAkHKokQ1YaaTLOl2snXIGvjUMA1NrLDSsdY7kLqS6dg+VzLr4u+U3pJ7dwFcgVi3kZWsVGshdTHMLSsuMQ2CSQl+tImQO9AUac8d4oUS1i92baoXX/nJNpKL2tdW15m5zYtmHqF+7SUzt+ikJUYEd4DEyGrz71NeWzeLkVaJ/G/NkzS9ev7/k5SdWnsamMpyYg2RwX68T+hMX4AE78qSXA0Nj8jRzNQ6r82VrsbqMCrLxoI9aDtLJre6zu6azjflSIWkVun1ojl5Jwo030izLiajPfCIcpwwkucXDEUkDyJ4NsrkY07TrxzTeuHOnpKzom9Rl/OPbz4rSGqmEy3tRrY8bnDyqYuwczfA8NicQmPEx3FA9Ag7ZQCt/Drw4Q2CI+7+Rnf+Mi74Yf5P9vCNUvt5LrNrFLJCpt4yze3GdBR+iNx7+h0HXH/9t7Pn1m5lNJ2TI3GNuyjF+2z2d/Z3efdaCM+edXmrFxgTdMaWt/WXQz3ioKG3PjCvbnzVi3UYD9YgVBci7idx2pY6TNxF2gIN3jxPNvw8dFW+cd0y3Vm2xqJQwWWSqNrWIXbS1loGgtSziZLrlfSMn9nnP6MuE96HO20VVbm7KobM9JKiqyE0Q2KAAs3hCOT8YhEMdGA5QBuE9n0NWe8JwFwbRFJfkUZgZHEiwIaiRAFqgLgGgArhHZ/AdyGwmFKZykuS3X6ZZFn1k5IsYzlAHUp8uCfbLk4UQGWwEVc+gJyXBOr+Cj1ye+R0BdOafR9x8HlqS7NM1m8asH2xKxsAmqzCZhKOwWYAwFMjS1xbyorkZvPNapPS+hTLqLbqpS/fbIt045cIijpEfVsZVjOUqUcK6b+EVQj1A5O9FO++yCosaPfxO3KoMk39JKlr3+ai6r5uyVxtZ607LymZ37WpeVl2xiTbTsvy0t/OCk2JnRXXn74AlZKbci8FDUvM5iXybsxL/NZm7UGaD0/nfy/A0A4bdTEpWm++Jbaf3YzBHieei2SZC3vWSLva4oGQolMxNpul2Tgku8i13dcrBM7HzWu76gUjGLuYY4RYNvNYkJ+YOHQQ36QbWTlN4ddu5PKPyQfY/lu+9ZDOmsR8NKkXqMwRsDM1XW1SM/BMKdPhxF9x61JX+cpSlMSkx7cnJ1ZMDD2tZN/8f3Sd0jk6HMZf/HjCqqXCORRcj4WvNKxtvB/6TzqNiOsk3U49SK76JhW3mXpKNyU/Dbt+nfLxOr0hS9m/3DlIxOH4zuYZK/9+z9215uDbeoCn+H5owuXHtfGrj5ZFvlbU8+XH7DZyz2jRXEhheX3+6vvO3uOuI4E3CR+LmUJDeByrlhgGz9rbJWbxJnz9lrL6rfA1ku0Mp7sITw6w7VVLYXdtIMxicQtoVsw6mgDgApYJB7UIi8LSAfQGgUA/ksOz+j7xky25XoPvkJeNPEMVDAOka8gsjGnPHW+NMWWS1yjhUL1SSQpMadA8EvqakKGw3S47mYARJqLAiFxWLK6Lngx6Oam8i4bM9gE1AIS7Yr93bfKheEExWV04dkZAFYxvj822ZZqnKpObWIEbB64CVhLWPo0wO0IBctHHKu60sji9sU1+mJOQLAy9btlAHXVMZN2SlesPokT0e7fE/OqXwAmtHBqUecY6pQIS9yeOKbo/uCnWfYDOMUzs/4wHJfBjcRc0k3+3ZLv26t2d4fbS43m9oqalypIRwcKFQHD3p/P+t6i5+Utrz2aMWPJ7O1claLnpcK3tRvE696aTiTLenJ/Jm3YPNct0naSxT+xIWLUpB/0o5NJvbGdVe3ePC8aCGUIU5R/ilfvpBseL2Hxyb/y0vKXbM6r1e2Zbrnv9xndND8MIHL8EkXK8EbHhMOxD8nlAs7wXF7uCywGb/GKr2ZGt2836A+d1YRbh5V28hLupMwNnoTH3McvH9bj6k1Zmz0wLJVUoh+O31oQDuYkFlz+Zb7Men+2tRcP83UBsViifcrL1AJi7A69dkQDoXfBxbQ+5PZsM6Dz8NoVqi+du2phqri++y7ssQ0QAnzZDavWTez76sMeV6jf/XTzi/d53GLNCtW2/L5qsZyHD7akhTimIhgHdyOHdUkztrCIy2KzCuChxVhJXLEmlufXSrSV4ZmWe+3RlppBXJ53f7HVoq24IXF62u1mY3RyB6BGxBhnPZ9Eo18msZ4MhsRhCgA9wDrSUu9l3HfkawncJVbDCWrDIHcKAZHARdxePmCpCCRn0K53qA9aOifjjH7BSssQAPpxJKWX9HRz9OF1friQsllwdwJxLQgSUwv8xbFm4PbQB/DTPE7nUxzmD4CwJCwS46rObUSiGAeNg6ttDbih76tcZopNET0EbuIa5azsP/sz5j66QUftOTLHMtKm20bpiAVwKuO3MwTHPBHaszkMzUXEKm5P4mWfExbQ6R05ja1SL8o9lmk5i9Hfyp9YnKWS6tJYlsj175Skn+oaabDe/5hoC9EdzkvvBtRN5v7IhrSNNqRFzUvN5yNSa1tR8xLLfGGp3XxWh3eHfDBm79Ufe0dtv9+SjPwVrhvanI0ga/yqfo133zJWG8ECA7K9a36UaLRe5ZpfsNPfpeUmL3Y6E/ewXq8+9MSspXO1mNSKjYnNaHHE8XkdT7lwZcmkErUwrHkwc2HKPSnVNzZw3dALvKAZbKAxU3dHI0aNNnG0CX1HHOGEQ/fhi3gW7zHriuE9YjdkbJKi3konl7yNqCi743Ozt/3fl/skApEo5EBxRtEycy2IWYie8TFzK+x8wlHSta8ueLx77pa83Bb+hPN3q5H/53/12+SZD45/qk1hILzh+f72++rF1qR6fXvgol7rWqd0LO/0Jw7DwZHEqXiO7qUtaep6y9RmYUV5S6pZzUqNR5/Ve7qtHMw1bdyQJ5Z6YoFtOMlnPQgRNjPVUioAlmKjfatYiXpmN7LKXWB7dO8sFu+jsL5sPNnwrtiqm5MhjcAt/WirdB2izf5StDG9EEmGG+Pfp3LaNUt8JXBZAyeIHse5kO9PAC5wVu5moteMJ9KNDHfUD5UVF+pxmIAgVoZuf+6JobIraaP0QAJhXy+4FKDuxm+4M7gE9g0hmrTwGtt8xkLbrAVE9UlvIr2gF94QveAQgn11oT8Cv+bUKU5C7iTiQATqEe429TXqvIAKFGruBuh1IVyeuGWJjFVWjswqi9i44uOA6nVwQnn5Fqr5ky2R36MATu0UWMuIwgGwL6Lf1OsZ5ggoBejiqBQEQUkcs64V+CxGrh/MHzIMuTjSQK0NXjQjJGCem8ku5yVlbxv7aNbPi2cXKzwv61aqsXLwFXf3mbFk1lO3vPZIcuF5ee6QbpaXn2e3tbvWTqrb7GP8iuUFsL+Sb6mtMbmdP/I+NkLi/VFkP2KZLIxbkyWSV/pTONACjrDlESdYr9adEc+4naJ1fkV14tR6xyz+fPYP2mFuk8qllFn6xNX9KqckFp/B9qQ0L79/fqzzemye+wLf45AlpRBZYRZGNv6uqeD+ST1GN3dD4cEAZr0Ow/vErtq8TnpETlEo1Rtz5O3cNvaRuPt6u164ZNMaAL5P1L7Wuaf3y0TZ55i1cHpm7egAf+L9aQdl12O+3Qoz7qLSnW8MCk9b+EuoTsXqy4dceXdlf5Le0qabnXr4sfbToplLbn99YFUm4KrBV9xZYMRw7bN3eWHbTqzT1O4459+SB+cWWxsq0fLZ7f1M97RDf0J5uS14i3yENp/yGVPfyvcsZrEnwRlp4RYn1QxRKQuVexXRVUastnSJWzzRdkkr9s6p7U9bAAAgAElEQVRGy7o8Uk7+rV83tMqtMLiRv+x3LN7NuDYablBuBjKS0X0CjcVwk+ehi2PxQwZioSTAoB/coPwZBZbiniVTno2fIibu4fbc+B5lzmRuvI61ZiqAqU2fxLASNQoANPnlMN+acjJMywe0xvFsjT1xmDKmWUCeBQji1G5PkWMp+wufFQkEMPgXWyXwUdJ8Ulkv5iIg2At/vjsR75YA4B5GxCu1iLhlWaAqiIZ3ligAPJD2IRJwbgVF6bPzIn1S37VZVZ/8dorD606ZofSdKt1LAFa1We3UWuHX6ao/1DMxoks4BiBUP9UXbcQlYZGeS0n0EjD/XaJP/Ze2+gCkdyQdlpcEhhjHeL6DO5uXvorCB7pt5+Vxb3Ufc8czi9ctf78wEOK4b9m5W+yG/7vGzm7k8TObuNfXg/vN+Ks+tRHW62xJ/vRPfIg2RmK2pNsWbeUf6CdteLXuyRXpD5HVXj68AAiPq9Uk9+7zblDlmIMj6nPcrm0HdN5eabQVjWWaWmQiuOyTz3UbhF7ClWJzHc75y8MhuycUtnPQBZ4acmwJVEtIzsq+qOWwf3til+iED+NF6ED+03HkLZUIMivnUXGGBxMYanIrZJA4hRrkP9Myak9eoxYjxHSeLmUbY5nINXv0slsNq9wi6/QnXP3UOpse+9etXxPD0HOt8O/BktcTwRCPdP64HiPO5729yM8Nu425w5asW2EtjzjeemNIszW5WwDfg0FMqk2Jx8WQtOiISyuB+G8Y42gkBhuaMIcfbuWvJdxY9xwL/2eWrULX7Ynh5K/nJwGhrNI2wblUYnH/L/cvAIQUpSUZIDqNT4lF1WcZgv1wtFU8DneLT3kZ/DlZ3DMbQxIthhLhaMJqMn+Djg8HfLcPLgUDQTtxPFiLuugxN3RAfylRrLgzn3NLx2n9CCpEh6eQLM5anq0xJ2DxrTS/bGoVz+bZ8p+CE3Q+YFI3yLPwdIDVNyfWPJc4SdxojnwAAeyRDBqBNaLTZeLCBOoCQS1q0uer3L8p9zhtvY+2EmXHYumT+i71hfpTjvwJOb+xVWyHGPgtGRDxsOeps32k7wpkoGcL7DIQG5+M+/3/KMd5pc5jcJaSbIhb1vPFZWqjok2er5jW+5So1tdB8fWgTRpv2igpnUeONuzQNU/4sDvzsjAQ+vd8N3fa5/eOe+JUTv9ZyLz8AVp7OrJLn7zB0rMzrWPzS+zCZgX2RnmAocbeX5kkldBmS+Nmjyw1d9IoGX6JC5QUQZt6zVv5R0YnbZI0F+TOtQ9uYVurLABCxJufjuvxDE707mpyIpxZKr+OC8WGerd6uMOCqBZIye6Zzbc96rTx1552ZdufF82cdNvrA+Qgq+vakdfBZaK+E4rRgEaP4KYw6N+DUgt5IDrBMJPHqcIBTRe1frSLv3Bt00s4m/s6jLjljlWb1oKl6AyTU/quz9i8nVXrX/mGi6hbVm2yiRb3JefN3XEQ/aua6IVUIjiv+0r3x0tcsu2mYrcNDXw9or/z9Cfcio2rrdNI4SwrXf/+cXJ1ea/3qE7tR9zyDBuU0FnsOm9k9+mnpJRQsaKiD/1Vnd9BvQInz2GZJO5qEbE1a2AM0zPbSif9Yr+EEYfeWsIS+nFCxFi4JenSVmHm/wD6wb7E6YwwKd79N9W28l+kWCwgiJurOc9z7d9rLONY4pNKFK2JLyCcDCdYCsD4HIMTHOZtLTltjq1rstGyNaG1EInDm9oMjhEu7D+IS18m3igA6uKLaIdvtpxxOONroyEuS+U1J36valWLlbM8GdFgdeoUhyut8Z0t1djTXNOiMx1n9dpsOtktuxt4/kTAkgXYzf/V1nXMNKKsb03qlzg8RLKpJ1L+cy7oeIMsxMU1cX8QtyjAVp0Sx65oZhXOzLeYDwHt5wA4PbMj/WlF3FFtBiTeVHnVuRSOuRmNpk6Bm80DBNU+gbWvx5GYczVgeQR1CWTxlXR+jkTsEfApNJs24b6LyOEJBEXHWElzTUniVekYfSfqyOWD7qNgbfy/hif1/XDGV4XXqz91Xuq9bvXVjhl55fCeZ67P2GSFjdsw6RqC3+I+c0w7obT0z+LK/ixrUW0OJXHTu5b1qQIwSF1QOPn+zH+KaqoACHnK1+/3GNsuP7SZnbAzD45Q8vt70dvFs495KuzmYARzrXaAfmQNmVg/+m6vEZczuJ+d+OOnc4Z9/IIMC5QEEl7jJ/Yeg4Vd+G6dPsK/8p96hXpbM8E+l1+hm593cZvB3TwxTOE0HN/EW1/su2F95kZ2rmwbS1Xov2yDt4M/EEmO1uIc1A9xu9EcxH5vz0l1mmV9NWdyIieB2GvX/0dbzYlxTtylnEivhWqPJ5w4xN+W/+5SVwEYSG+o+odccee4NoM6a4erJK6lWtsmLe3a06UG8VIOQCo91IFO0v35kSQkVvmeWJiPJFvsQjiZMwiMfRHxLsfKX266rbqK3+XLVwzOZzbuA2//aCs1AX3f2HxOVECWmlhFrg8YlLzDmH0ScZ8s1TQGBIKIQ21h2CoJBMsCMHMoexYLePsZtmoBvwsABWyLAKDD+f0N6pDrxUhAYzDi0E/g3CpRVi5J4rJUr+gvPZ5EiACD04jyieS7sPwcynX1UXWuhFvUQaASGWXw/PGxcJbCt3WW9TgBvT+PvAyVFTc1t6GlplLma55dUbJLBslFcGSilwBLUgUBzqwIYE3m988B3yf5fA3AHARgijYCaW145a85o5ZVLJtCoADapzrhBsNH/mArJCVRneq/wGFdY6tSJsbCAsHDKJuVY7FVptsi0V/90diR9EnPtxbct8rKb8FoiKMxMn2ORnWK+ziYwXCh+qc+3IuB2dHVGxI32xnT+rGOW63X9nZervjds+z2k+Yljvsblq5f6dlSKMEhLsoPh6u1atwC0auG9taUl1es0rlD/+XR9S9K2iDqgXrPRYufdv/B0uNMIGu8KiSgQNDfzBWuRfr6m8mSyOyz/2k0EEpRfuL4XsNx6o3Fb8mZF7bcs0NO7EBm20UQvtjL37474cWv3pFYUEmTwbOjf48T6ddnZn7xr2E3+f4jHkhGtxz/Q7EX0kPgo2UlebB2gPMkxsEZq9XZgzp5+pAiknarIkYoPjYuJycv90AsuL6PjEBGi5Z27wc0cfK1OwXrMvSy9lzXgo0ndhr2JmLO3fat2c6ydAe9YtUcEdHtihuoGAqFho7vOfJ4DKFKopiXHuhgSAUOzTRmQJzFTK9n5Z5LsLjjQZh1ruX9DAjOAwQlatNYjYcbfBYxaWO4E9/aTfpCcdueWL66lbitrCVdKXknIKiJKTGfdr/SR04G4NADufUYx8QHdQi55r5POU1SgYDmlyw5i+G68RGg9VPYtpwXZ4mTcep/Ee7tqt9tYysdkhUhnjaaAoS1+AFijBW6nDZshE2bDpBL3iXQEACnw+muK2fFxiG2FHiiu5TlqlMPveBsOF0BptQOaqOsRMUlZ2OlKnCEK3NSIqCuTaVEkmqrxvZsQBDQDcHBuYsB6f/jaKc5tPsXAFNuIgsidUr3pM0rdVb6ivJH01HFJr6edspgRO1UnQLN5bQ1HhrKt60uNCKgf+jSybZEO3q/nPSH2mBJ3Cq9pNpe7Bdb2zjHcq7mu8SnSpI2qb0Hq5hUa5inn5eltcSbW5O7hT6/2npgxz9EKJFfdvSxO/MSer+L3tG3EJVfaKPyKeW+GNPl4aNgMoohs3i5zeBOot9fmaQHlXhWffeM0PYySeQu5kJzRu9bY3hnScYy0s1o85G2l88suC0aCMXBiZOzcTeNqBgb68hVYhl+gw3H9xh5LOcP3vvqtxNPff6rtzxz87dvHlP6/CEdvHBTSmMvHhtzyeuXeAYb+Kb1Q17tG3IUPGxinzGVLByWuPQaJqKOrOd+ZwMWo+XYyJ7NQJH1WXTSblB6A9+nStZ8Ek/uzyS9ivy1NAn7k3V6wAFPdSql5c9ZsSDkB/eNbpAv5qxapmqrER3vy8bPSItQtNhvxy4WO+kZi/K9vCOJQrQQCn39BeqA0yPSAEkcJNpTGoKl6NElLb5utpWonmwZi+DA8vEPlF5BIFiCw2lP4Kih5+HUrsFYRFbAAo5GVa3koxynRLg1Dwxz6zM8OY/vLEBGHMwCsjaB0wBB9LRuSwi7hpxI2coAqkJCSdznuQjUsVKbi1siukNnPQcANyltiSMBmOUsjBdssi0Dfrd14uh81waB7Io0K9WRY5CuBQiX0bbSs2yNRITisGRdmQ/CLE2zMhL9skl0V+tw4USOdgKw2MGuvY/rMmCRNae6ILFkZh0r9xD3HYX0pgIXfwMstXhpA6NxIQAS3dIxePmeZ8attpV1K3vuHU5THUG1wbZobqp9op82wOsAwecAwTZUQIBwexMQbM/1ArDmuxbneIAN/aVLdJ2QdJBjoZFcC/xyMn3XHFcb8uDO57I21IIT7fiDLRvDNdFaIKxFT1yrgF1gI+A82NJnNMizVLnvwp4AoS8g29pMf17y1ZOY+dak0Z3YHcvSbTvtjkc/LwmVuG35ECo6kG+wsz/o49tMSIrh+9Pu6XM1vuXnqg2OjKWKEoUWrlNGaLJQ1bjcltB7+nTKRwOhXmILvw6c5lNj8xEzOU62G5vdpO3D161vULXuyF+W/Oax+XB47ACdh0qFiz924uBLfPbVE8ldffKFOZeccPYZbR/rInHidglAbEIQbgBRJ1V4Yp4MAvRlLVm/qlX3MbdrkmnAa+crJWx1suqVpek7kd/UbpVR/iu/y3dFE1G7ZYkA5IS9q+cW1Sa10W/n3n7f5n52fD3gxso1Puxwe+hirRN/JH8yPXxp3zCuKN/NXDZ3ebeWl//hFU9RX7l+WoMTV/c6u5N8cXYr4bjLq/JClGkAaqHz+3MgPtXm6OdqzHg7ctIqzhMsD3itLmGJeMs78USU+R1OTGNVUobEhlaRcH9uPqCgMad6igGMZUtiy4VYLp2wYAJMfwMhrs23jmPQxsQQPiyG+5FnumF951mEu/KmQMGmQ9d1AfCDaJ66m33fbkuud+ud7IdChRvswlU6gOrWY9RJiIPFmUYn3eMWs7iYrWW9vrsbbYvoGL0p811vXMKsxcdBL95RPuHWtOnwaemPfXGZfpJkwi/jPSvyw558L3yPf68+1a7o/4v6XriMNhaeZGFnQPjIJX1dxJgrbn9jwA9dT7u8zrlHnVEgUfHnpTjC0+ufuBlDQT/E3w5f89yVC+bf9OJ9Wne0VkoMqrVKbSuc9Y52dl2/+1nldvR/9G9ieOQeo42UXBl0jzaBu/upTZEM/4Q/AnTNT4+h2kWSCLUNeV8AuOAR0UAorsE3W/YKjO0xqFhyqKTCqHEsk3NM28EdtYuU7sWIZjITcRmcgWcI8wCh0nSIqDeoz2921uzOzS+pxdC/rvWATgKTItNR1Ru4XVpcalXLVNIJFLZs3Urr9izuUtun6MGtX6MnZvRgjv4teuD613c28Av/ph21FlZdlyjM173tanLs6WQqXF9RE7Coa7L0S5Crg1we/ORbe+p/3/CF0+lzpsyfseSUesdguLQ1+Vaj/zr+nFxOrf/h4mNbNS6VXOKPWGpFvIRCESzEKXu6rKisu/yFrfDnntBtR+9uV+9ai1BPNYIFeC4+gbVxD5hXzOLT0Jm9jVGKxDfaeFU5zEodXs6STphpK/pxNIoct0txaO7/wb0pJNtMOKtX6lrZfjh67y8T9CIovt0l9d8DkcjE1Y7E3whI5+fT3L9Rp7qyQOK4VJDYx/wxf6IBSUgFSBfMrejfdqdt+7uMFsuXIg8tvAnz+1vUdf+aT8aiNqaFr+1OWd0jYy1vU3nfRXCE1f9gVIqal2FOMv9+/k+bFq1Zln3JcW3ELRfMS180+vXcqZsbVqmbVKJY8Z1aZN762iP505f8pjKii7hs//0VtUEt3J8d/R99vajvuqbNiejtA6xfzh8P24yxQoNkZ2Nsd8af5oMAtMW+Dr5oIJSIRiGTtktYcKK4DDX6zwdj7nt/xhcPRgrUGt9z1OkxIZMhjDt90ayUW19/TKIlpVMm9Bx1NTOrCwD3SOsBHbeaHxadQu/eNKJDTGxIMuHk3LycRecNvVa7ApmHK91PljjS58SK+tQA2NnvhX/bVXlZWcl4QcAxhixiR3OC/g51ZxNtdyZY9P0+J7m716QoTiLSxNIBl99W4MtY1ITzyZ6Rk5mRHJ/khWuK9le6pU3X9D6vPvL2Zce3adD88OMkBt5haje4C7xN2Eoml5i9MWOTxDHRE0737ej/nf22s3ui27KryaG+aZeoU9BzEIsSeiUhfpWlT+GAWS0O2swILMMYmpyyyXIWzjU8EmgzoNmkjBVLy7b8dVz7rJaVPhpOsgY+btoECQzFfWyGCwoBsoxzVwf2bkSEib7NcYmOonI+UDvo1pIpG0eZzYhkc/i/pESzcIgJWyyf0DFeUX8ced8pj/57K79IFueoxSUKxHb2Zv52v/kLJ2CtcHUO/o9iI1wMf1yf01OnxEH6HIZLuWrQTkWlV5Qdwo44N927s83Xrn7f2WZsR/VKfOvZUFx90gXTLj2+jYx7vLSzeYlkJy8rZ8uCpITE2oX9CHUva+vDpYuXOgyGQWLDItPA90ba/2Z6kdVEF6mQ9nbjuStmoah6pSLxA5/syXN39g52Z0ALG4rknHbn5ugy0UCocE8iYJEJUeiE31cvanXD8/f4E1O+VjgZe07cN4367PUH3pr8gbfI3ntRjzvufmPwg4RZuw0R6AMA4msodVV+p+mtm54a1+PF+89ZuFbv0ksa6DK82Z/pWR4mLbd2d5JBH1Dr0J10XDpLbTwegDsvw2RCp7TthBvV+WGCbhct9fQn3Kn14CjbehzlgoSE8PG5OaGasAxP878vYtymCecP7W4YLFm7o87I7HnuFWUPApeJ6PYdxj8LdQFuD0UgRvgWM+g3WyN9gkRp0sWVRbd3LTuhY9BVebtwLEv7IpLrxwI8Z76tPLOOVUmFk5xGgO6nZttqOdXLpPsnrE67F7eEd5kAWQoNxoyXnusKrD7Ph4uUgccCclpTq9QBHLsUF42+HGz7NKB7L6JRGeiEaM9kDE9kAqiNlu7RIr8UQ5avER9q8+cFnl5vWfV+t/Xqj/RycQQAaIfFZzsKp1EX79rlzMLQo7QhjhMybkD/qDB/GrfieMUNV8Hi9WVARsZluVi9rvzV1mihVp3+Dn4O7iQXIebtCmCPpp4x9BFdYui0FZZ+/wbLVls0xkS334nQU4XNAk77IYw/LB7Q+g7aSiep37UAagP7M5z01dBTc6dajMUAZO5PWJxKt6xQdOqv9HyyPs9Dfyi/O4508iLm3M87uTtSn3SiMraRNaKX8Aedhr6yCbpV/fsrWYYgXj1+mQP8KaDyudQriLl8HUyCxs42QLjDeYmU/a63BscoxFrUvPS6hDnuBeF8LGZDnhGJdIHbpEcmPG0EObEKJctmrtq41luHg7T7FCgAQk4gcPtfcBM6PXekk5I4rnX/KzcVrobzs0Z2Hn1bJwV0JmkhlkxXik25FXj6wAolyuaN6fzoevZsHNPi9uMNZrJne4mF+nvi4XmK5B0kiSE1mf1YkOICNXn2Z3qWh2nBUlJoHz8qx/5sw+4+S4uEOMFh5H9P7Dn6JXgIb8eo6PVKO4oqo9/mEyZNVqdYn1qN8gp84qXFYewV2g3stkabG/4n3qYTrZexS5/AcXdLprU5sqX9+8wrlyH6PlCRdYqiU4FDvYAw2eI+wudPYdak6/P8W9Eb5sEtjtfRNVNtxdgGVvFyOvg8q/hS9IJtV1r6bAw2FsC9rcMhXeGytPBIUvIz0Vtg0cLF4y0WFwzng5CFP0XcKqB9m99llHI4VqhtAJbrmViDWdT7A4Jnssi/nGF5byRZbCNA8DTKCUDFocpKVJanYwFmzaUHyHdS9/XE6JRbgxb4WHSZp8N5tuddwCWGUUHEv4tF9wzmFzq3nCGAg/y4BBwCrSVNLG1NjOXI0llAL/Pympst95zfbHV07M659JPDeqVPcp8j6k7XZlb5KrjbZ+jTMPokvY1AWG1dcYyVTw9bnBzGBXpaG7Yss03NiczjbSYibZ3RzKqcA8f2IH0GLF10plZxnq1uscFyfWmR+iTL2A0NrEF8oq2jfY78MidDL0WRUTkBup5dAHL4YL5KXZcgqt6I/lBlZAkrNY04eu/oo4MgpdGG+ZF2dMUC/+2QxdEH15sj+zAvPUEBltqntRrQ4dNJSNuQiT/Nu/MMF5XuH/ekfTN3qtVkLj9xTf9fmZcyHAvSblKgAAiPrXWk2+/cG7NYTLcgeSgFkL3suuGXMY7YhiMipuikT3/9doecI8+9hXPvNiL0gWVlgLvuSuavzjFEpOqsxJCjKFN7LbbyG/HFctIrbheGbTf7tLfFnuVGLVLSI11DPthjHMpYRbQUV+5x28SBfZEXKgDf68RisywnO7bxBU9es/aDnqOrwX38J/oMQz8mKSJU69umq2R7C+D2a+z1A//cG8VlLVeVZa1YJpFaPDFpJGmXPB9gGs8ircNkT5Z4lEX7EzibzQBKu0W2fiYBo4fBEZ3LGX8tkc9JByoz/9MAoo24Yqzi0NwvOSKpI070q6DNAsBSYiEt7JXqWfnzilucjkV6XZFVtNAn2LpfMyz3g+IWfy0Ap3P+NOd814YF1COgvgm69+GHh/j8FLCUAYLmRHY9K9MCvaUsrbXAvquTKeCiJrEuHo5v33cEBydAhWelmkb2fPuoU4YE4mTFNTUE1AdwKK6CXfubmiWEeasO10uwAPd9LGZbN7GqdfDzm4mhylS4WNFNdfmuFT9SpzbJLK6OOO6aeZZ39U+2Sjtiv84FHPpFFJzQW/RBR1rBHbqn4NTf6VdbG+37Jw5Pmzidcj+fPssHDJFnbu0fbLXo4pvge2CpcjxbFsq9KZsNYL9P38/jf0X+GUSWlaQfREHFD3RSmyVK96RZBKE4gYN6P4Fu27t9Oc56haLc3QYjWVsNQ3EMVqILZYHvhMOvQ2sxIdbvraE2mePXCIlohESU8Hht2wGdtNEK0m5QoAAIq5Wt/P3T7e9vyo5wLofxLmeFE2eWATBy5HLoGdfJHS5OgWtlUxKTv9mcnVGU8+Q2FjyTeo7paE64Py9LPk4zUXlUlTogJcdpdOp/tp5RGEm+n57+lY/eHx6hu9GJP6HIc9Qhf5xnydK9/R2SzxGKEynYXCDClk6z/fYd8Bamgh3kLjrIJsBtqgmnclsnsxfktiHHZRnRfoilUsFGdBLTQHKtPwf23nMQEE1yYD8upThlhR0TN6gFdhUBoS9DNNkr3kIlcy23Vp45X8HhFUMEej5iyKlwi03hFiekW86jWJjewT1a5LXQnoiOb8vhVu5/AEprFnCZep8AYGlB9kR3NazMpWUsUXqSzwErz+gMDvLFPMsvjoC2EhONo5iWiXPU4iSuKBvu6UQWdXb27tPMu1OZJ5WoU+GixPGsqWYlTq9gxYfyG0c1uTr26Dp8Eu/BJ7ED4L0BENbGTXX5DmsAVmVAw2nH86boLERezqfcB2dfAFicopG6hY5Jvzs7Et0FUKrMOHIqoh89FtEjfsQeh6mNhYCVEHV2Gu0T59WYNo/CV1I08EFwDf6HyXDCH3GNUyoUZs09m43Ca7RRJxP4SeuHF7aROjXnZU0iY572xC8VbSQmlWRoQSSrnO/XyUlwTmfC5MmfUmJX6U9kpSgQ1Bw4WJLGn8ah+ulJt8b3HNM65ISLDEsJTb+DtuKIfUnYrvoxA2aioCwhKfvyPh4i9GFIoQ9TS1e0ER0jZhyO8xbnkCqwe5B2QYFoHeHQiT1Gvo+k/m1CBi8NuW5P2G/5RCGHdwhj40pn9gznDg7j3MFliXGJj+Jb2D5jS1aIk+UXc7K84hoqPtx2sTd1IC87nwcB1aq8+GziVzL489u1HtBFlqqS4/kiU02Gbcz898MblExfgV0Vbksipr9L8ieczJb9hdBrO5zh47xYcQqFkou/m0MoroLQVzvuq2OZYTfvLDY/BT49k/qM7NjjxQef4ZSSmDLJJe2F7tqQy+LD6Yd/obiYA52kg/LHn/Sc0nvLVeJXdgDrj8BHDd3e05yK8Bgi4O8AwdR0y+423zZqkYqF01I0leU/2nJZ5Eo01zDR4sZxLFNNwCyznpWtgM7rMgbvSEKt9UHsKneeJfgdXl3RkjX+f6tpy47EwzgfveO1+Pb15XSH9+MstmzEd07vSRxDcfRdpahH3KYARQt5zzWW3nahbZLYcQn1nVjVSkBgR+LBTO6/AP3dWRjwTNKkXWfZZ8+3dXAaBeAxAzDryrvQe/+OfpxOuYzZtu5f9NG3Js2rYeVWl7F4zbk8ors0IrrLevSTz6Cf7IBrQweAUBtRgbXaOheR5I3UpRBCEkE2B4ymAkaaK76FcV5Dq7Ac+igU3fcsykgHHAySXAfuTZIVHywF2F4INcAaEjmIgj2XilcAQblkKSybniv6qM84paWeQcPly8iH+0Vkg/EGP2lx10ZQG2bpfg8mIFxAe6qTfyfL9cpLGA+eQ2+1MSvC+tOdAgfXD5INgSDagOwqfQQY+uHnDJ/iDvgUj9ZNHK9mQ6+SmtVLqyjni653Vech/Xs0EEqk8zA7jPoM5o+lhLf88ClxsQlrEYN0gkvsKm04O71yTIa3w/l5Q9oN6TYVveGnANxJgOLNZz/WyYvIsaM0vveo80Ouw47V1YGdbudRt84hZJoA1hsrZD9qzf56KQJBiRWldNcC8HdKWlhijk5r8N29F/Ya2mZgRxmEFCR0fBJNy5ChcCKSuXMfIpa7ePm7Ep2EY8Khq84e3OHlqEo8jrNEsRR75Tpv35DBZNup28V+JKpEUp44jSTxujZaWihn4/z9Eg7ddTlUszZGID/AUdWB87sXtwr1J6mBVXoi0UIt5tmyylSgOqqmWenrCPHVG52UYmjOZupRlNoAACAASURBVPw3hEPZmGP5X3OckwBnbmVLPqOylVTYwC1hi2k6zRYv4zin+hirfE65ZwGIK/Nsy9E/2VoFlhZHVKm2lZNFq8BoPnMJ8HK/hnMc8tPWEGYLMHKpidXqk8wR4oxa2Swr3YI4qfEKuQaQ83/eExzXJH2iwErvcAn6vROoS3r1X/hkbLhHb7asPnNsfQFIIJtbTJg1PSMN/eaxhEL7BSOcC+EwX86xvDFE3Lme3wRc4sw2AKyclejcRhum03dZQCYss40XLrcMz1pFCQ7695pW6vWt9HFaKY4pn+cuto3XrLIMcW2enpMsDmkN9BPXLHGyaLwJcEuL6ofKCgQ5zqoc9IoXt62INXEY36R948Xr9+apRLc+EBZwmX6bDvCn6O1ZvOMetoQTXgoU8IBhSxZQzmgt8sSahUkpKQ0z0jdfik2FDAx3DmCO8yLcnjYC4tplLio6oq7oZs1xqfJSOK8n4SsV5ShIu6BANBC2p6xEhLb1BHr7msGvswVPbzegk2eX650M4bpdWEjZMcun1v0Iy7i7+dIdCeq1WJO91HpgB+0ed5om9nn2wnvfHPLKd7//6McR3KnF6q7q28vftYMSAEqnphiTf7fk6SIQaRsibbV9AoC0zUaCyBVXsHIQOaWwCT4ik4EdL5zQe/QdiKsBxCL0F1HUYBy8RBg1/70qor4MO+ZgDHBiRFx+sNBOgCw3BiUBnByL18JJ1QNcxrLBa4VO8FayxH/DOfFBxhZJiB/PQgz5VK7lYeW5SvqoxGqWcl1pSx6w0NaH4ZS0i/8FjlFm/ZVxqWjL5484gNeqY2U+VEQZ6jyR61INFMdg5k2etRoQZEVy7oDj8eOfFkdXuAVdo/TuSXCaR8JxEvbNXcC98n8UaCNSrfQSIlwWeFci7xaAxTq4rqcRPZ5K2R8QN4ojktGKuAdOqKhYgvMR5f60iOfxftyLAeG3AGvFRZVYWOLGDRy9hLWqq6gmranzQ9qRikERcVZtIVywdHO+mFUcaw04Vok1pd8ToDXNsJwHiXITbUC2BGDTbkhcrE6N6Q8t7sGVBKBeozml+vROPOtPdIhXo0N8jvE0U5wP5c9AxCqdrvqi5IGlvlCvHMMFuHCXnuhUnLPaKBDVOBettIk9qIDw/xqd+sOH0z/XRsJL1cqmfrd47TK9L88U/oPez1dALP8cVk8SgW+bOCcUFYOn82OtvRv6iPPeoUP976sWfXTDC/dIrCorUq0HpcqXKN/q2S4P3xvrxLWMxB3e7jHBhe0pEA2Ekr1vE76MhfQjBm0L4ke0bzWgYwHHNLHHmEYWykec4XRDPxSDE9An+WH7AMWAVuR50TLsHRBdnJjvE6Nd+zaO/PvhRWmxk5FCe7IWy79dwvl9DFFj1H5LiI23iiXLuZwTyELoiQYllpGJ+gZOkk88o8HJXYjTGq8XpXgosUimv53308Ofz/puRumk4iVPPfz4C0ollTw1L5wXp1Ouda5ZJgcX4HfIIbxLvMDbKzeufntD5mYtvL5+QqJHz2XjIErSgfqWkXqvz5LTAbA34aTmElh7BeEuzsEqcjScoKxB5aNWn9/ZLDjz0c9JJMoWO6lNBUthvLvJs2zdZLilEzCgWQtAlVlqmy7BtUAi0UTigX4BRY8AMIiduUwbhOK1rextKRZ/PvV9y+RKl3EL10U3LdzFWeDFqTZjkTueNj3C5zEYvFyI+4LAIhsQHQHgyQiJUyLCLSfbip/RP15PaLY7KbthmYUbrLSVitrhLbaEcEsvYUnSYxLD07mLMnch8p01zVbczjXfMhU3hdRraec5zOcb6ac2CRIFf0cb6mdiePOrLV/INQ9cj7ByyUkWTxQlZyMcnubquTkY1fxsy/XdE+2qrYg4xRWzUDsKrXUPeQCGObPRo0p3p+Rzgz9inEOINR2L5QpIkQK5jyE6VVg7XxTogaVugkbo/Rye4YrbeQMaSsQqEBSgy4hOACgbA8XULRClRp55QD+euOaer69/rp+sX5lnMZaHzwNJ40yqDPVRovo45m8qthZl5XSiQBVEmiHnw2tnZhHgQv6ucnGJiYuJTYbxiE1kjifFF7NimF/F850zWm19+ibLd736/RinWs/1bnR/kPaAAtFAKL+x7U6BwAL0BV4Eh35urwcaO3ZsTPK3m7vDxt/C+okhjH2PgXc1dIwpBNK+stWgTn4k/+gmiRPrELkg/ZMX33Q/J0l5tbMUIP5t0wl1jsr9Zs40XwezP/shfVHBrnd/PngXz9Ii44vttGi/XMtKnV/Kkq5GVzcMq82uWZY7kqgxz/Kb4hrW59DevjjIt8CApgyityzEh7VqW4UPgaKyWzg1BT9C7dAvxljGBeReJ1apFuU8AOsN7mmJGPB2gEUqgVhcNloTYJrnOjJtP50FXDIqLeCeSLSpVcEy1BU3eSkDsA5lHkT02gvOVBadnA5R8RlAsBorYH1+uwpwnYTF6Cl1rfRY5l9x3MzaTLWVn1NWItFSoMKCBpYq/aY4R3HsMhBCnrjhRgJ5KxiErLDFLXhcBX6H6wAqcY6fwQ0eyUkcHdCVdvzRVolWMtBpWMWKx1WyEuLmELk6GAyJg7b502yZjMikN/XGG2LTi2iTH1JMlssC2cbTbfWZcDzioAVQEtv+eIJVzefsR+jtEnDfaULfvoY2ck0RCKo+1StuGv1hqtYEmf6LZiXhmmuxUZD+UAu8gFXcldoidxjZExxUQPher2eO+XLOT18Mfn9UAoAmUu2PJKDV2D9Q6+n+6ONf+oxoIJSlkyeWKJwm9Bx5PxFiZEU3Bm6vY1FlxvccgWVUSGaEjdEnpruOt6MbhuWhvzvUbVowZAWmJKs1TwwQpL2jwISeo0/MzM18hFNBio2f/PEidofazGhCaHGQu4DEJsqegp7dZQLvMZSbn5cjzo+k96+s5F1Q4mxKt2QxQqfDCYozxI3GXZexUcAhlxJxPjLnPxiTH2JKbdMpCK/WtwovJ1joW/bNJwICzxFXVFyILA0blLHkxjWsJKI992a4E3GISRi5fARg1IWrenKmrdJhoNKxXMYJFRiX5GuObAAEHwYEGcfOkyzo0q1rMW+IRedg9G1zAIirAN3TcJUQ16LfiqPfa0+9bACdXoABRyGFf0QU+xaiWFl0zgCQH0KUehocWhxc3QBEhtowyi9xIOAIF+4dASW9YFokrwA01OZTeHHaWHagfcdwpuJ8wF6xH3eZEBfP4YxBiegkSWjChiBEO+BY3TQGBdaIzr3UXW6Zbe64wjZ7J1iQS2F9e3qMxZ4FqAuMfqa96xWQHQOe7hjwSLzpBy9YwHeJTyWh8GOMHpZh+cfOspXS50brDxHdbjWi4dkv8VwOD7bLAWDd6+uyVbfEhQqyIRG4RPQS/QpED7akzYqCAAvE/agW0h+KDtqseSeOxMXExR1do+EZCbFxpTdlpa+YtnCm1kWpjDSP5XKhLE44p2zx0qWrlK5YDwldaPmG1UR3zbO1cIaRpPEuK5mDyZXkYHsnO2yPD4RaBCUqlDhNWS9J1/wgraELmp3dqk6l6tfBjs985tNXpBfwX5DEUVps9ZlcMqF4uUZphx9TLrlM1RBvDNFA1rtTP5JFnUy9fS5COsftoiP8bah2iDR0Ys8xPR0nfAZ+gq3/Rl3WmJVYaVx1K1U1yeJqAyQpLKpvzrAVAhKJjbQIpx1llR7HgGZx5IT2EO4R6OZi/48F/mX0azI0yiM6zRT0iQKGpUyIqgBTV0BxKPV9yCItlxsB3eF1rVx79H+cvq76nUnotKRvF8ez4QgrfyHtuJ37h+k4I4BhIeCRB7CJuxQIXgsIXkej2Ww4EyPiVOosexV1Eg3G+Z77xEl6XJvahQtHR54lEeEtRLVJA6iuXWNZe2O0JDBTpJv/wuXdDqABog66U0+XeAJ9fw4OWsHmPa6WjcIxBAbQZlZizizKPwgtZuIq8Tr+h5rnC1SOLICahdWpbA3gfl30ps5FvJxb8cP0XChIWuA9kSj6y4HUJz2pRMl9oM/z0EfrjEBQNPatQ/VeMATzothoXAqcZY16yCSprPBNPI719S0c5/1oQZ5YOUh7R4FojnDvatjzuxQ9xo/esud3B3cEFNg5BbQwJmBs8i1BtI9HxJlPJJj/AWyysJPvqxbUIxtYhSsQd7aGs0tFJLrucCv7ICCI1aT7X0KmtadMycOw1syyLc+vtkzNk0UAhVQE+Mm5nM+33NeV1uY4p+M5tUKuQ1gEOqU5QFfuONI3rkC/dy5hyZCUuO8AcJcgHn0DbvDcRbb5ytWW/jHgeyb6uDHUKYtQz1eQ+9Ko82QMeJ6Vng4GoeEUWyju0tOToas8DZ0l3IYzhGg4q5bbpqFwuz5nv1fjA8CfVcfK6pzQFzHI2UA/usNhToNuUh8IrGRF24hzBfFrtFcBtgq09WxoguWrTkNeLlGnz54IvCYD+LI2lsj0buoF3Gw8gC7LVnGCAnUvegwgyGLuPomD/x1w0tI7bqFuuQeoHp9r9ESnlSxlI6Av31Bt1mXXcMgB4V694OCmnVJAk0ccoHZcsogTlyeWXDvq6CSz5ejjOfS/xr//qbK+aE2fvshNg9jnKjXwtfs8mEJyBcPjn0cBcSLJWENmVcTMB0CcQbgw6ep84CrHYloR94YxEv/J2Rzx6ZUA5ihcKmYgDpWhg/wRq8B1fYD+zl1nmVqQV/B/oji5eMtv+J2tklWjZ1yC2LMfwCRAaEWElKOIkOKJ8qpYSjOe9QzPmYy+78SI1eQI4oIOnWPrHsdlo3KCOf+jzu/hTDfKVzBSZ1UMcZ7CZzGN3zoCuvKvFXdZFd3e4XCJcrJ/bZ1tenCxZczcVxD0hwB+j2vZPHRLtsTnAMNV0215FyawRG2V8Gusi7+kODTpJJvkW3xLMEj+h+cvsk3tOLJKHIloL1EgodZSBXx9WEhupi64PWcpLh8XZlquD9jiBgWCGNq4HwO8IwgfB0frXAwXehlcqIxLPC5U9ek79H+LEHjnY7CkJmvtkZGd1hjpxoIUUGCvKbCzXaTAUbJqDbToaPB7/bDgxoAC+4EC0mOWBiywu09egvuDdGDa7KWRtcHLJeLLa5xPuArgaQZneBKKRQ7OtZW5lnXkLOOwCMpiuDKIsGon/2grx2Bo0xWgw3G8PKCYcwGh2OTz6okpEWu2RlR4EsBUTebugJYMX6qifywNqLzGBFuXbaXrJ9uGNID2F0KYfYsIsUMDYnciDv0K96PF+MglUKY5voIC4Nq06WqejYuAg3hwmfRhAoPDq1uJKuWs+HPU+SnAekY5S56NY7/vh/unkJZT79OrW+kEAKfnEtskt6ZE2lKNNilkmEKnnQH4tcjANzLR4l/EF3MAUXhkhSquURzrCkAQx3sbCcBhuRpCfOw2wBfzeuKEKviDwFL9mcsGIha96UzKKpIN8UmNQ4vzhhG6TcDv6xn1KdGpAo0PQ18JB7xZYdmUFANWItIACP+Ut3/oVrJP4pRDl2xBzw9iCohTq4BFZD5+bxKvibNQPEdt7NbD/V1XzGI74vxePduyXPSHGHtYAu4BJ8+2VURQsgacVXgOJy3cyvVeAJG4vlsAQqtsJXoutg0yoFFdTXCcT61iJWQxKb/AWQCrdFdNEKlkNrDK7wIaJQDZIzlpfTFiwlkAZVmAUlGUfiWay5cY5Oh0jKpMwlPlK8j1hpwGcUwZS5J/40+RINTinJqVsoQytawsekcHnebSxhiW3Aaw3I0riH7/UxNxWj8jTmtnKpXYURwvvsIhiWblK9iCPvzE85ewY5iO/6GCs8sJXpxgLOHbikOcT/j+LFkc3VUECxhLsABFVSkAN+Kw/p5o6xfq/RAz9UzoMA86zKHPN3JtAVlgKTpPJsLMsTyLMHOeyFSGWr61t54td4wACP/UEXDoVRYA4aH3zv/RPWbBTkdUKItZGWTJl06ifumTVqJ3iwO4pgBOjxJo+m4MX3SCQy3OJbwEEahcfQ6DkzwOw5dRTIypLLqnEj/0W6whj0N/l4WIT1FCxF2K84lFVMex4A5yOreyRJ9ckyELP1Z6iXbUp/wJcrKnnPSH7XGV6LLQNjyv3wHZGoBrI4JQNJ9sSxTDswk6So5bqiAusjyRX5oo8kukznLo4hDlOnGARj0sNvFBdMfBHREUePPODGQUH/ZLTti4CA649VLbeDsGNRInSre2syTZY3NycRz5e8ZbXCJ0OobnX4v+cwLt58ioUHXoowgv0t0JtNLSLHluWSupzcQ39O8J+vECn7+ymdD5nuIY08iSMKE/rAx4OmUISVdtvqUSSNtaEF7uKsLM+Ragnkj0WKsSAyetewX4Z/FM0V4bBSX5EQqgP91Ff4KfAwrslAIBEAYD5J9GAZnb1yBj1ehZIErcKKBZ2NgqfYwYMoXFtB4giF7Kmq+3nOsX23r530mvdzIuELdTpjHxSGvFWrjVEtv4FAYp4kxkCCL9tvzzcCGo1JJyZ7OA4/huTQFCLchVecaDXMelwTmfmJwTOJuQxTr0PA7zz6J/vB5Q5ISJMK4HIUVuuUK+gtznASttuhWLVB2NdAvX5T4R0UFWHgR4oyN0iH2asz7b4gh55pQDNO5EPyeT+cInGAhMdMhkqIaV/j+MdRRO72HqvIdriRgP3chm4SFyYVuA6LEwBmvXfLjnIwHAJPr5FIA2HFHwQNwsblxlmZ3gjmWyr6T2I75M1XPXIjo9TWJg0Z5Qax0ItSaHf9FXWUG8ZUSjjQP+km4r+jIQ0elQOFyJWEVnbSgi1qSpcu2A7s6LcMKysu1P7hd5roBYARTEEQpggxRQYK8oUCQQYp7bC030DYTVStudWhVUG5GJygcuEbtDsKDMX0kBHT0kMZ1EZhJjyt/sbY5IujbZYofAaTXCiUu+f5cROu2+RbZBfnzSgbcgvmebklasA+ggkdtiXALeYyFfgZhQAKgFWoY05YgVGkOsUC3uGHE4w1mgtYA3Qa94M/q08wGN7oreArDVBNh+oZ45hEU7Fi6oG/OEINYOXKr7INFfFGVGbS0FF3om3CgWk+5YRI/duSZOrwnAymkToVOYqMcBZNMAkZfgNJtzyv1EgFU+uqdh/ToGoE2lXAY6SIk031C99KVebSutCDvTAH/fZ7chbiMvZ1t+TcKl6Zg7cc/bJcAvm3Ir+RQg/U8uHehcm6P3/IBnv0VgAVm3+qBFbNBUPbMc5apGzg5sDriNAdy0yVCSsY98Cm/lsyPPbe5YLO4i+bOgzzfQRyJR+dl5XDXpR7hgHdir46SWRWKSiiuU76R/RJvcJ3wdYQCERb3I4NpuUaBoIOw5ajAxRhW9Id8JuQ+0fqyzvwMrstIJPUbXpJxEUfhpOxe0HdRRBgNBCihwICjgh5uSpaEWTXGGvyPOW4g4j9i4+fMAqt6ckzecCCwSsSnW5XGlLakJwaM9fzomxY06lw+OaQWuFDohQqHkJC6U36A4Hw7ydYko6CxggW7PtYaHW/mu+Ap2E+fFNW++oAecDndUc51tbloWKaMOvcU4ZhVl3ka3JrGtFzGlvBWrgauGAEv1KVqLp4MEWPsArJcQn/OCqbbkbYCUcwsdTrRwOQdxuUSXiQDovQBoe+qcj8HNCRjcSAwsMClHWLWhgHparOXV9a1cOS7pOfSi4uAe4lmKMiP9XpGJ0za+SbHE6YhDxV3WJiQbuj93CwAu1xDp/wRu5aDHPTz/BNwtKgPGALHTBxHuFE6ll2+yyqk92QAbPpoOXLpzA5uHpziGitMqwvWI3nNOuuXJkTyNLJGozj+EHq5OqCBIlduAzYEMatRuAXCHSIMDINzRywuu7xEFdiganXTzyJPcGOcTtoyoF5xl4bB7Q7vBnWTNVWQa239sfPLmzT9QoSbybThhYzIdpIAC+50CAj4FbtDBxeKY1mPxeBcWmmdgEHMrHOGThPt6fpatlj+bgmE3INeJcF51OJqooWM5MvZI+d3WdcYqUlFaBFpyxG8CGOEv51zEdwWROBowKUPotavgEO/NN+clnMXbq8dEXxmOAcjVhAjrTnTI2YgAv4DzIYShOxPDEYVDk9gzTWURlw5g3sjFoxn1iZOtjTP9TQT1pv3hPlNsxcCjrSq+t+GvAHECUeYcjaXmPJ7bG/8/GY9kxFj+8T/YSomFPTcLQPQKQJQg1+65gIisP0tBh2Fwj9IPjuA5t/Lc67GAfRS9YZHnVOI3+O0CWy8umEAClYYDcqcvtDVN1lqOODeJOQ8HbDtLxIsxS/M4C+eGLST94Cro2wZXCe9gYHIi91fGZ/M12jOU9vSIOO/3W2dZdxL3VRsQWeFqYzCXdt0EPeRcLxeJp2irvus3PVNHw4l7VNIB4TLoCUSjEYIEH3tHgZ3qCHVCeb7jTmNgS3yCOMeZht9uB84j3C4mqf94DoaVaflxAOg4IqlLTBOkgAL7kwLiLCSil/9bd6wtS+AO8A6nMzxOWOMb4PLeIcyaxKEaw9KtHYlT+2lb425aL35H7BY+Gh3YzQTXFoC0J8saNANu6nTA7TMmDVyXcy5czTc4vXfi9Ir/IK78CMMYmfOzEyx7VTFLGIlV6CsxloAYNu9LOFHpEDMRAaqMZ1xCVszS8xCfiuPsxYKPy4GVA4A6Ybn5IPNOkWi8cyXhxtC5OZXgtPoglhxdx0r/q4QVe5GfOMjAPRVw4QT5rTpF7j+C+8UND6VOhfmKRd83AH2fOKlxlL0aHeexGOt8h9g3C7ArEgjxbcTBPTyaMHRX4Q7yKMB2Z+T4J3Gsx0OP1nCXEjN3UdtxcWCtcOust6xbATcFZRcoV6ppJWM4yWMS/Xmf/pwLCB4BZ/iLxLv0RW2SiFVcJkc/VWnGpkEiYwWP30C9AkBl0UzlZCCjZyoFQBghRPCxbxTYpbHMhFuHlXZyEqYiKi3Hzm89gzmVwT4uP8+97tyhXWSqvl3i3K1nCMSts8mWsEW86tzBnYPwP/v2noK7d58COs2kJVljrhtHMI2Es9qCSDINbuwrIqUIGBTYQZxEYw6/rVDeio9mbH8AyMjH7aL1tuVeDEHeiZRTcHaBkfRg4iDFlTzPAv0wTvntcJh/HfHebMSF0mVxiFxyI+qEc3NWsejX5p7/Aa7SbZXkHMSTsE6VLksivrxaVqZ6KUsUmL1OfTqNJZa2XAC46uis97gm7kdWqM8CHLL2nAjYdk+zUi1wsQDcXUDQrgPYFDTbA0E4vjCcn9r+G/cLXDgcr1wfxKeKG/o1bfJOegFYsZi1ahwu/CLWrH7838JUFrf5EVzwh9BvcgTE1f6GuHK0ZJMxlDoGoLvsCwgOYV24aIvlvkeQbAG7gKs25xXm1rTSik+7kPZ4MVDh+ObQliRC1Ol/uVSIaywV8SsUNy5OEuvY/Nrfy71zK6DquRLjyjhI71BJPqKK2xlwhIXfXPD/HlFAQCjdhz7lxyRRhL5rxyezcyXGLHKixOQyMaGY2Jy83KzE+IREjhhxsnK3rNucla6drgarBqqyyseUSyldjeOBSnG8iLMufePqnPwc7b71jCCyzB69oqDwHlJA59Zpgfy9sqV8zJFInTjzD5cH93d0Vjq5QAfkSrSnAOWb4YxegTOqmm95TyLavBFR5tNEfdE5fhIzSmx6BrkvQJQLJzNP9wqgcMUAREt+Rr2bASJZkmrsF0fE+gkixKPR63HKQrgHEwpuxq1BdJrWgI5cC7Toa37pkFode5ZHfbpfqTHP+IIJxDFKy70whOgZuwLSipG6kOc044gkotHEfonbRhJ1P4GuUb95hjUqHzn4tiFiyJoKHVfPylzECRaAtfurY6lHTrEpBBSoNArdZWv0oO+yMVDcVYWEKyp15/ndeX4Vnp0a6WNVwPrEw6zEc/w/nrZfgq5P/oXDEf2iu1wh3aVoIfG0TpNQkPOEiLFLGFHqMOrrjsVrW9wlZDHrAXgNK5tZxhK0idEGRpaqD6Cb9LlKtU3XZbgjlYtEpUoBEO7gxQWX94wCAj0P6PZjCgJu70diH4KP8g8OXljTylTQyX5wSUtZ8AVAOjdvATmNnFnfKl6DHu1KxH/49YWvRc/1LmJTBY7WoluDLJWAyrJ4O+KiVhFCDQf51Rv4Thmn2BJLP261bVL54hjMPIzBzDUAIMAZqsjEUlSVhutsy784lUH6dQ+slOCyiBjjXMgEPFrWoFyqCghKv5kJ6NRSGXz4GuPqIL17HM9v+oMtnQGIcQaiU0ViRkBQ1pMFIMhv5wHqNwE0rXDi/4joNU0SLA5uyc1wLL4J8UqXc+16rt1Hn+dwbqDEp+JIi0zoIJ8vaQlXsss95uetukvPuR9wG0ebZtHuk46zChXzLFb62BROsmg+19apDx6HJ1cRyjWkPfUVVCAijv0Wkeh/EInKMjcSLCAuvaaVn0BZXoEDiLpZEStXf9Mgkahn1IMryO/oFfVulKTvlHFQwBHu6CUG13eLAh4QcjSPnVLvmJxZS+f9tmrzWgGjuDb5X+1NEncoSzHltYeVSS1Vt3Ja/XmrFsfNX73YF8UqWrws8BT1I0gBBf5MCnCUj+FAHsomEHYcll7r4fAkptPiKdAQN5ZV18o0TLIE+ep9hehSJy1MByxl5SixqcawjL4UIF4czstwKC7gdT6L/3uA4I+AESc+ZLTDSV1uFJxoX7I9XKKMPiYyyN9lEmE56pZCHHr/vK3GIJ6FJZkT5SvDJTojZRDCgi/3Ao5pqoyjv1OW/704pWonosJv0NNV4Vn3wB0N539A3mkM9zULzkv6MQGJwDWxDofplrB4ggI4Q9Bd9mpkJUvHWvIMQKg0nO6JP9rSH2tb+aNKWpwsup1ZtvZOwqTt8DxO2vIVbTqeZz0OMIsDE90a0nZEsk4u7VQAc51LKO65OdzlA9BPR1alKdPWHljptiOI9kkcR6XNrw4CXgJd1gDgnmhY9antuFsQZ9TqIE5+G3HvlRgDNcO1Q3pLPdMXiSKartR7kiZVLQAAIABJREFUsW1+DL/ECIkCIPQJEXzuGwU8IOQcQZfzBPVdotF5aB56tB3QWUYHFcn+mVgFn51aXHId52KdDC85+7mv372506kXtaxZvuodyfGJ8XExCf1xn5C4piBN6jmCg0hDr9zx5sDcHxfO9EWuEk/J+k6Ot0H6kygwsdfISexsvmk7oJOOqzkUkw6VvUSnvCO+y8YqkkXafJGkdIBaRTdjpPIdIsxSiPPkZ+j8ausu4EBZxdaVkYZAUPfMIBLNWII8XyxuhcW6BPq3/xGcGmOajKsX2yaBLqt17DGNrPw7ABbzx8FAzH0LAFmZbrmvE/Bb70HgJhFgHtaga4pbwo/U91/AhHiiHuB9DmgchbKr7gw4J13D6vMpxJtnAjqfUK4DZYbxHXcBd9NqW3EcMkKBtQClOBNzeUNLxVjGmQ8IeiLVCFgfSYPORBf3kcpJbMtnrXm2dlqG5epYtB0mTqJYi0Wqjqg6KlJI4DaOdlbxwRoQlIvV7bhzfAww60goWX42hOtsjzj6GujVVf6U6g9WtO9gaHR6tqVX+cU2SUXiWc1Sx52KX8p3ge1A7hnEPb51uoDeE4lGxK+vI152ia/qb6gDY5mdvcTgt92mgC8adbH21KS+GHBbSFjFCngE/hZyY+5oNaiD5PjbpYm9R/Wn7L+1w2MBuDA3huDB+fYU/6uOZawJXdsM7CI/JS/ha3hGek76m9c+e1fS+oyN2ukpadK3JSvyR5D2kQK8Q+2evUN4eQ85MSH3ylaPdZbOTHox6Xj8T+22E9LKVql+VFpDOB53w9tTPhTXosN35Venz78rt14AhIg9L8f9QQup6KJFWoYZKzlT7/5EC10BCPJ/qDqWk+css40CFv1+GFmASWi0ysch7vsIjs4L0wYIvg+nec56y74JR3yFL1O9Ojx3yNaIMI4c5h8lr+Nw3Mm/2hq5XSj5xh6zZDzD/2XkeK4f4Lpeh/u6kPJtZtpqvatYDFG6I5IUgK7mUOEjESX2gFvClcKNhcM8E4tMiSJ9dwKc1KvQFrdprGUf9p2t2wQIvsecPJ37usvClLKJRIQZBiieM9fWxtFvHWO0w4T4cQGWp+UAJO9ke9EOEH2LjcMJGLDUx4BlPs9oxjO+p86luI7U+dQWeEZAGCe148DfOxh/AyMBw+l8mU5cG4Fl7XXoPqX380SiiEo7QE/8JN2e0E7BxV3oouOcfE5Qz55xjFU6CrcMj5Ol/b8SCMF3upd4VRtpdLVBZJmdvdPgt51TIFpHmDSx56gXUIWch4XoaPa2fLqxDHYNtAfxC9Qk3SZN7D36Rk6jlzUaahH30jaDO78P93e8GwqJvazNIegf5+WFO/nWpRP7jGnyxa/fv/fwhKckqvLTUr5oZyw9SZD2kgKPXty366gv3xi+Pn0jMbQSLIOT5TO2ZFp2rozq9irpRu3cpYMRQEhEuNeV7VUL9uKm/2/vPMCrKtL/P+emQAoQOgSQIBYE7FiwY6fau6JUKz+VZlfcVVGptt1FKYptwbYrTdRVRF17A7siUXpPKKEkuef/+Q537t6EBDBq/lFnnuc8995z50x5zznznbfDCb6O9ecxLKxLWWDFpcjfT2G4BG5zibRyIiJRcgKGJMcNWpJZ4hysHDU//e+STGtjtgKR3Td5ZnNzFt9qPM9RAA/Lsi3DcTeQSFGi/1a7mzo9cWPoS1+jaBOOLUgBgBYBQDLxd07nWtgVWux2Pi93ekG4JEKnJV29xRRdh+O+XDqkA2uPVegUxp+GnpEQYuEutD1SfxGp5QwitYhbcu4EiFkbdaEeIdSix31ols6KGaP0YAx3MAZJZgDW2pcReWbEIrPOSWPKpSwc32J0k4pScz5i4Kd1Pb8nYKBzAeM+lXOKyeqCBeyGUq8bvpPa8LZtYmod2chkoGMNn/9oa35CFXSf2Qpu8CHAKM5PhawdDS7GnUM6TqWpinIvrl1pCi4hW4hCqolu4qLlWK8Nw0ccuod8sf33jLWjHJMyoPE6wnLvqP9jZyiQCIT19QBOHzh+Mi9eZx7MuyJhqBiDg6i0ks8v+H13x5G9pROJlxkDx1+Is/14QSGqxn5kTJYPkJkxYHxfdoAjccZPgbu8rfOIXnfrvHwTZ3zx1qujZ45PTB+jhUhg6ALu7szYfZ2tFNCCIwfjI35jgkhsrtiSApeqXBTqS9ah8zmUvVu6QRla6EA82PAjnue6PM+ZPOd3zTXLlRVB3KKAUKCp65bhz3Y3wNabpLejF5v1itVJkNHaE+EOxamJy9ytkal5WLbJlOjvXf7Xhq4l/oIbcZgfyHcXLkwgSDSaRujAIq8CcDcjvhwKR4U1ZvAgIDiWMSikmgqxSm3kF1mRinPS5nAqYy0gy8Qd35mVAktrZanx0gbCm+ADgbD0eICG+v0roDcRox8FEyCPWsp5DGA8HKeTwsS6KvPjGzi/poDgdFmDqoaCEWBspM3uYIDM6hTh5B6Eiz0HAL6fuYgepJ1KOwwucjx0mMu1csK386Hus3B9uyXoPpviNtIXtxG4QPMaawRRaYL32LxMwqpXIfFyOXI4Fu5rmjLoqMTI6+i/OQ9gX8S8EunK1UTFW41u7276/3aaAolAqIfvR105fcD4R7GiOzUaBo+hPnwEZyU9rLK4S2Lr9l5ycvLdJ997sQwJbJk6cGxn6qA0D+AgwnGdR/SW/5GZfMVDmZnV08ZgZ3AWwMpOL9qT/2YrCs3s/06d9eDLE90Lo+rySVTanHKd9Xd6Vn+eilrEra+ZK83qNGZVamyqpaSSpp0lNcIeP4hYLhF3lqK8DflvTftsloIebxrYqc/96alpWanJySYlSeox2L/iwo2vffHWTa9/9b64P21W5HfmRFGqkhv7HbdYqGLkdjQRWA3hUGBpif2jChiN8YzChbFni7yIXkvGMTmx8QvoBWZrEDXyXIa4HJhxZENfT5YHxceUEdkxHBLRWYd4OJ0xvEAtAEyyLATtWdSTSOU0qMAUi6MUYEkEuJCLcteZbImaFfPzuHamaSferylEuJk51ywljJgV6zXF6vQ6EgqfQlu8W8FfAlP8JoNat9EUPUekFo3V+ubF6sMtNSbsWOQn6QVjOrSnCHP2MkYrp8bqXANQDmNcOwOCr8PxNkDEm8EYtXmQSPOsmqb6P/k6DhC08T0RK3dPM0kAVvBuzCdRczwIMTKbpGAT5+y1lEz0oTfiw3kDNDoRTlJcY3W43cvxgVQknS/oZ19o+AX0qw0HqQ2W7pk4weQ2piZpmjLhBEO49EB624D6ir6jjY7LniEOU/kjPUcYI7r/qBgFEoFQL5j8pGzB6OIhXjKMWcL/bojmn58R1OqEdSminXALO9Bm2JpO5/c9nUb0lL7CTBk4rn1SGD7HSyy/xHfgAHu4tmYMmHCQIlTwLO+B7nBGalLxxSfcc2n+Zcee9+9/vPa0FgJXZKAgMJR4xJftU+AS/hY3InpL5yMd141TBkwoJIzY6O1eGtrUNYO3RCP/SkmKzuchEEeUWJRG/JQEcbiAUNaNsq5UEZBeUEVvkJzJZZGsyDLioARK7+eYekfXNEnSz20BBLG6tLE65Uvo9FESsW1uZZpsyTChnsNFhSYcXGC2TEM0KjAVUGqRti4VGI6cxxbjQr5LJynOJJ0A3f0xotEGUeDgdJKKTSojlT1YyBuSW+8wGpqNpeqnuC9oIZdrQFPEil0QK8qdYTXv17FsPF8AwCJwjB8jur0qNk69oypfAyBPc4/aYVCTDaDKMX02lpvvk/RXOneJFhW7VKLDHRU9P2MxzqmFTvVi+twNPd6PgFgTQOx7xjIbbtMCD1xcc1xSPqRffBjD1tTTxqEtiY7xxTTZZFfc6xOzQPpl69LBvGcyj+eweO2u65nj2cxRz+xG5t8OsTDjC0kNteFWjGAk8rX5DznId2hp1orr/8oYboVj7AjHKPHoHRw2KADFA+GO7q7/f6cokAiEEsdILBQvRIgZFUSC0xFtrgqLoxd0Gd3nKzJT3MjWmMC5ZjYXH8T3x5LD4J6TRvZcMGPwuD2jxdp9h/IHWhmkBud3GtpTi64tUxGXsvvT4pTC522dRvS+99IO54558p0pfdZviluCSRzUgUN533wphwKd9+2wcdpnr2vBdUUpaaxh07Rrx14LGyi90o7KnKTQXFMUGJLI2sWrVAnO7zyip/RErggAtXMXKAh8qyJX6PwIFZ3EZUj4GpGjALE5Rx4LqgyH9uZwGwA99+KAN6EXRDUgfWj0dNi059eaTV/NN3mKGqM5y62IDPL1W2IV+ZBEe9RV4Gd2FgUDMKCRpbUWc+smwSEdl6QjOtqxoG9kYX8fEFgOCAqIBb42ZiccFe4UAVbaAeAaDqBufYxaVjBW6cMEbLIQFWh/Dfen7A13AOjHsvHE4Kz4M4BpAcAkK8pcDukGnaGOhldekfRlaDa3srHJfIK+h8REncq1iLoiXAIIik4qmXCMk+AYlXbqipj+UGmnnkT0eUSSiRLrdKl8CDXG/chcMQ7Xj1oxR3ostdL3b2Sy5FrSiI1ah2KTvAZtyqdwsK/E3FY0bs1xKTTD+Cc4ImKKziCBMgHOrX5ROlc971p7tD6IQ3eWr54j3N5d9v/tkAJlikYTr8KARpEcTmdhrVUchhd0w2jmhWv+npMaSb391S/f7vSP/zxZq92u+6Rc3+Wyu9OLI/dsTAtT4BkxRgjSeDlroFc8v9PI3nFDmDF9x6Q0rZGsRKUXYEzzA0B74ctzZneY/P6MoUvy4hHbtKD81jqvHRKnqlbgnmy4cuJt6bkrtY4S/+vE7uu6tT3q6BMS6Dxt4IT+JozuVOBz5IRvSLTHhmdbY4owvKzzyN5jYrTYk08BjJ6b9zhsCK8qVqYwHnFFMvISJ5UPt3MJLJ30qNI5tf7YrHCch4YuIkpsmY6oEd1TcCcr7EDA6m7cAr7B4ERzl4WogPDoeia9oLnJkp5c/oZa9NPXm82jvjGr3uC7AEviS7VP8tlscTcaB7q1FLi9wo8BsOSfTH5HDEOkD7ecE0Yzl+FaoOf9MY6W9N9WuQIR3V7Mb2VdsP52GisAkwrAzOX9un+j2YL+LuVb3rNiQFAbIYG96u6MeuEu6klcqdBxMkD5HtA6SgQBBCWiTAN8XBQoZbm4gSg9pJAyT8Tin2aiP3wY/eHZEOYidHfWsIajFYYwV8oQhoekNYApzjwNrvF9xNJNGffVcIgT6YMsIWEOsUs7IfrVs2TnyFgUzq4LdBrI9QdwP/oinj4FQx/RVnTVRlococTJkh6peCCMEcJ/VIwCiUAos3G5M2xTxAVy8kqAK4slcABiT+lcpCRXTEGzV5OWa4adc+MsFtTj2KfdvuHQGvdlvLfuKeqzcIYtEYGcU9oNAz1kax52dqFmH3I3zfzwh8+fefStZ8eyuFvzf4p8n9yDXrHZ/UGvAgijfSbcFCxes9TUzcgyEy+L493U9BoLTuswZIgWCYOLyyDux707QwYehEIWua2KwtIlMIM7D+/lnK+1yGrR0mJpnaqrWJnGeMSlCRSurmtSazcxtaW/Ro0dXDjXLJEDuMJ/adGWkZa4wdr4zTXHb+6/0GAywHI8QLQCTkX6RHGRChMmINyThRqVgRXJiftpAkfzJPUUnFscoIAtwQE8WyC7AADpgLGLNoM5S8z6HovNWum5rDM8cUDbE/Bbi76MeTTmk+ioHv6PV+HWoRBsshBVu2pLYlZEjyH+fUsO4btAtuF3ZtUFa81m69jPcRuHjGbKKwJwgabesyI40dsAp4MBwbq6AIBCBxrujYi3+cKt/n7JgP/JgL/eefSRi7UZSoZet0GvG9gs3IOD/E2xzloR7Ls1RjPKMvGAc8QH6KfDNcJZRh6C47yDPoi8Y27DFeTueWa1nPDFme+GYc3p1JPI/UG4Ru5D5DNEw09gTDQ2Nv8cPhVnVPdXHLxE0ioeCLdzw/1fO6ZAHAiHnjO43w2T7lV4qTKLxJq8IMNZTVb1f/qujd8smSenY1saZTX4clyvoXXQGb7JwlsTt4u60Wj0tiCIHBsx4alYy2WHYfSqLiN7y6epRJkyYNwFJBwbBYhm5W9cN+nW50af8d2yXBcNX1aK5cVB3PHs/qA1pvYf+/ktz41s88mPX5o9G+9qRp7v1iE74Y3Q856OI3uhz5Wud5wMPYb+clKEd8SMoKyfHocW4UQjml/exa/Tgos1KmDpz4L9NNxJQx70UVhzymlbY46LLvkukKnO4vymXgZAMBUQDBFJyuBE/0knKKCLAhoDAA2Aw8wBMFtQdzqcmDZzDgQ1A1mLEke0MYActAc46gBYWqgPhQsc/KPJ0zsgzma/hia9YVOTpYDZUiWQFio8V1zSErPhasBSRj8apw7pET9njDPoG33gYkSo2QK+A4nX2Yu4nQ6I29U16X0Joh3Xz5ciqdwQpJO3sU0BnkMAHnFYJzHOl2l/Eu2ftt5s7PCNWSOpjOXw4EIfgQvFWC5y+Edm4Xu4Y5ybZdKeBgSVV/H0WB8xB/nsCag9NgPU9tlAdPoofZCH0Eyjjz6IV/dGvDoH69q3uR+isWjXDheNbrhoSAw8lXqXMJa3uaYV320OSA61L7rJ+lxALn2hPlVmlZqn/+kp8LMoEAfCx+Eq6mTUXgQXdz2RYfRyb1OmDnjkdPQSk/7x2lMrX/n8rTr4qGmXqpdq5syBE88oCgtvg2MU5yg9TTuA8T1eivkk60VEFW5iU/5A5+E9y1yUWbDFuchBdu3VT/w1/ftluTJlV5FoypmX/6zJ/ZEr79Nsz4I5C75J27XBLuaBi8QEbFN+xJ/zoi7Derw5rf/YG6C9RGG/qLD439VlBBmCyOrAkcvR4hc1+NtcPJNmlero4+am1o/E1TyN+J+zWbClk3OuB45rU3bz+ugPR2JfexYL+0+AYOY3ZtkxOE9KxKnA2xLDSZRPiDUSr2wVDTfg+C+LtAw3xIWpPX0KBJeiZxxExXsjpvh4dFwKOnECHNsDGN3I4EhcqNX30Z50efvCqT6OvuwCZa7PMwUjfzB50sUKhDSGmK6xCRua8K9sLI+GY0R8GJy2zKy7fKFZJ/Gm3sO2JBdmW5T1Txzzq+MuUVrMLY5UOkQFVchsaGrh0Z+hzcwTAijGTCAAM4iwa/0Iv+Y2xK1IUdUHjrWnEuoi0hzV0tQ6MMtkvMUmYI4LDO7oigHRJbhVEKggKeczs3ARwQLuZIHprZRLiFOlzyOKTvZHiKn3XG7yD1poNljpApuVi+Au2WgHn8IxdmAspzDHSdDiLmihjYNooXv3KcZBb2McJCMn0UUuVyqzYp/+w1OgQhSIA+GjfYZ9Wr9GHZtKBjDDajNyS+cRPSQSKlGmDppwZBCNTkac+d11k+7e54tF3yt6vRYfK6bAlYIgu5Fbw2jYFiD8ghcG8LSWdQowTLvBNCxNFZppmzK93xM1w5RNE0lK3e2aJ26PfreMpOJbi7ibIRWa4R/3Isv5yFViTA+tx+WUIPz3OQ/0e61dy307DurYx4mS/lc5xNo0MClkETEzP3/THJjT1rSo36zc5u7494Nvv/P9J4dTQUZQAoSqVgQMx4tra2Fq740lZD4RXgTesvx0Ok3LtXFktTJ1T8mwuQPDRYBgFovzYavNetXX/PRsSzSq51eZHRSOTaEGv55jVlxMSDaJ9ASCWqit6PJg07xFsSnE6jTAmCZMBlzOA5SeAJwUuSeXQ6LOLHwAT8K1oQf/ixNF6hHiYrFlKg7zsvbU2HJibX9IZJWWiAklNpUYUeLrfuvMpgHfmtV6BsQtWfEpXNSdTPIwQPc8LFh7o3tzHJM2tnrnBILiMF2EGzmot8b4RhFx/k7mjb9hoap6mlMO6aQOb2gytQa8TL2TG5qGGU1MJJcxFwCCCgyuejasGlam9QGzZwCwGwG9e+Ge8eEM2NyGebR9MGmqVmBkdAdc39X4OQ6FHtqYNW1hsnrgTnGj1obQVEdE+0M+1y7jfhCTdKm4QdFVouyl0o9+b9Z8TmABrVvikp3r0Cy+++IpUGEKJOoIGyD+lBMxO1NrCNCAPxcAaLd1GdVbSvx4mXrNI3sFSZFJA566K/vrJfPq1smo9eHqDfnyM4yXl/AtLA4DsSobeREw7Q92lQENPoVrMMqYg5gNMVDZZebAR1oUhpEn+z0+pP385XG1pbgQGS34spUClvOpm1l7y8RLh5cbMWRp/grTa6yko1iLnHjxwyftfZT1B0ss3J81D736RM0Zn81KOmrPg811XUTqssukd6eaiW/bUJB6RioamP23vIcSGR6bZlKiOLvjD7RGIjpxcS4ai4BDi2sqYcya4Q6Aw3awCQvN9JVm0xGLTZ50gRLNSwelIBNyEVBkFAWYFheyaZkNtr020WLXguDWOtkLaY/g0tEXAboBSnWE0Yv0impDxjOAb4MGGSZZgCdDGPWxCtCa86VZLumHM7gRyMTErNlLeBfn815KXHoPUWPuxohHRkEyuMnhaAT3dTTc2LV8H15sIs9hxTlHxj5wwnLxUN+OG5aeUeLdC4tMamPCsu2H6uI/6DqnoOu8hHrWnUPtUk/BMcSV7g4QrmT+jCdotNgU7LfU5OVy3hr7cCyT+Jc252Eccxh+mIqIo7FGOXeYsmvgOnEcouCXIe6HjEnxUKs3NzV71zOZGBEFOMxH26NT/Apx7QOIUq9cZtZ3RkepTY2lGT6NXxKmLZeNQm2AUKSWb6HUJvIjnKUTvngKVJQCiUCoRW3NtAHje/MQ/wNd3wL20BKVtrfiTR7OLiN6avG1ZcqAMfUGPz3sm68Wf19n/+ato385Y8BlXUdujSqTWKYOGHsFC8Mt6ADn4IzfQrpA9Iy4RgQLL/jHNces2SA3JlskdnKf+h62abK7WbFudfLytauQ7DGKEPHqVn85/a8XQIuWDvc98VPfEw8tLPqtz8QjsZ3EtlzbpfvYmfNqU2NU3V/6WV4bMoiQw/uyyVc9EM2olq7d/jbli0XfmcH/tEF9zM3drlraKKvex3B81uQ/sWAAZX/2OOpMc+ZBkqCVXZ7/cKYZ98ZkHPCTtxQWF4kztPdqO4ca2lGdxP9/Tv2y6krcZmmBkcpwuCxxcwIX6bQFavKVVX+1EYlOxVpzT/RVydQ7gxieAkynixLn910OYcNyTb6cyqXvwjso2omoLdJPiQtUO3IhkdhRuff0fpBh3Ug0Ogqu5i04JxmVCdAEKI1YzH9kUX+D72w0AyWoLSg0RUvRSYrbE6CqntoWeClnoYCd3IYRwrhFn6XNMTG9pP4XEOUQKKBGmklFHRG+XsMs7ozz/k/UK6SegEJg6RzxFwJmLelXnKQsaqdyfAVg4tNo67r+5SfZHT9JBc4+Fw5vCr9f4/cRq82GLvNNvgBKnKn8F+Hgsu9hzoiBt8C5JjcFyGZxPgBcewGuMk5ShJnJnN8f7vhAuMFvcNnohk+hQjGmsQk5FX3hLAxt2mBo8zYc41RozDpk9bNy3/iecTPmoN43ZmU1slO44OhyEdI9e1f9lXNw2v4niYAkTDpEX/c98dOdV93y6pR1XWJ99z3xM/GaxHHofOJvfXe/S593dUv/X/oa93tnPx1tEuu7c4mf2/teHu113tE/8bs7F/vb3p/SpaxzZVT7dU4lAqH8wiT6wcDiEaw1IzzAYVoYJN0chFE51HZguB+yEJzdbXif+bHupaQ/qXWT3fKGnXvjCjiLZ9AhlbDcUL3J145Mywhq3gKaKdu3FoEjecHW0vnqb5csOPvap4bICVc6QT34+tSO3H3fjXpDqR8QGSW6uWiL5ID6XztyGzw6dogrSvyu3+6c+64XSN/dp+OkBK4OJMv6LA2qpYF3Z8DOLfYO2EqDQ+IddZuC7d1lObe7ezb7ictHHls7vZYzMopflwiE9557vdHmAsvc/Jx6TSX2ixcHhK2yW64a3KlvesNa9bZpS5X/9dEr5pFZ/zTpqdXNIS33n//6V++4xM76O/GF2NHv7dXd0aK2vRdPL7To4l4k6QFdEe3ttWSWT8F3LhkQIJzSmiICOes/XVuioCNLIiWQbQuH8hBLR92b0i81SJOJk2FNkHZdSOb6AEd80G+l2nTFvmuIAgPAMICrY48ZBvQfYvVZ+n7b34BFwBgj+DFGAeQIwb5DwNo9N46+UdxDkuAGCQq8vJgwcBGsTQnFYkNzqiTWV7b7CFkxQqw1QzYCOOwXgyS8ugkFR3rMgesE+EayG84nCnkt2NYMWN5V/CoRbjYktBqy4yzCRuWFxGHFTLwucYwCIrevD1eYDbZdDHgC0lQFS6ANnF6ozCDUU8wjkHdtyFgtndAVJqHPNXDQer/c/KhbD1FSCu3KL2Q5O2H3d8m5JV5Tiu6J00uca+Lm29Gq9GfpDXoiTbfZvCfQu/T7nfjel/W9vHOJG2+3zriNdulNfHmMgdvgu3Ws9O+yGIbS5xzz4M6XZia0hurQeffpvrv/3HnFL9Z/+kw8p+/uXOI9+82/lwmE6nXq4Il7BcWFz/N+pYfR6HvRMPJQJBJ9kN2kdH/Ts4ozzzxs1NmSkZ3UrG7292Mu+Ws17tIS3u3vO43ocSF1tlnMpwyasHskjN7M4ytgrcZnDerlFZmijt1G9JU5eukiNkXiIu2GdPNkWm13579iUduJ4FgaLHf0WzvHn3OovdL13Y5xR7vFxJ2l9F3aDIgjUXSfyFOXj96nVnqNEi4QiUD4YPchcf0fQbnhItPiC78DwvPadw3fnzcnv23TPVJ6HHlmekpycomd2ZRP/mMwljJpAOGkqx4w1zx++/ofVijN3Dbg4MBKt6q83d32AH9nFim1XdZiJDolgqE2eAJEuzix2Kaw6Fp3AYxN8laZDfpfdNM49ZzpZTTExKyLhWMmQOEeN4k/Vc8tSEKbYhbpanuZ+nvmm42rAbk6RURf+sos/x6xqHvJdZ82oW+rBbDlwAFtpoEogAHIrviGera/WFG6oK68AAAgAElEQVSbGxDb1iIx7lFktv8uy6TnbDaFpJxYoeS4WkB0z6Wby2ce+8P57gpgvYIlZ1sAqSkgm9Cc/Sox4kQsM8+GK6uF7u0BuNtLmWwKoCNXDnT3du5Ku5YHWF7B+IiZuvRuQqIdiQ7vFMDqTSxexd1JKiOOO5V+16EbvAMw/QqAups2b+WBqkuKp08Bd4mDU0ksvBf9Xs8Geint9cWVKq2NqTdazvboJJ9ls/AY9aoBtCcBloMIYHAHyX0lVpXIuDFg3R2u/Vg43NegVzu401zOSxyrOUkULG5fa0dZ0pzSQFGaLv63p4ClQCIQKuWKdCDxYo1XUjcrKWkOu9dMKl/OHrYGIRVxXAsb/d/jf1k2b/lPcrqdSdaJCdEgMoEN7oeAW1IYDS7qMqqnrO62KS9eO/7opIiBc8QQTy90YAhuEnTsNLznawmVZWFn/RQpWqhkdSYxjy9bKaDIO1rsFftSIkpbsL7Vqi2DCFsSgZD/yqVdCdHowR1XRKPmhKRqwWKW7PuQSscDbb/48atmzOtPWyB8tp/WuqA4vUaQ2WFIDy2QVal0YTDaqDkRpsz8FX6tOib8y3nearC4DkXXdgvnWnBIJOqsSauhxzuGVE2TEOURq22VM9qSBakW3Lj+ThNGJ7YYwf0i2tuFdqvjJnEqoKFnVhaiORxktG+QFJjkj3mHdE7/NYRrugI3CaW9cgY3+k9gKzGr7qPEvNJtroi5EUjEKTGr9J65WFceAWBJHTGKz9pwW1eiuyxz0wGoj4Wj7UlAgb2LTES69raA1fkY1igknPSCApe8mCXrmYRE3BuwEk1eQlT5YkxUKdCRzk7j+JTA5K8x7z2KTWpOktnyMGPYH5CfR5g3QjPaObWD1reymTgGv8DDFXkGXebLDFBi6mmIbmUNbv0pMR5SEI6VAJ2LoHPoPqbxJSkYFAGu59O24h8P/cgsletOGw5JkbQx1nMn0agvngIVpkAiEFodYVktTR0wbgyc3uGRSNiAB/JvOFcPkX/azc+M+OsnP32ZvEvd7Hk/rVq824yBj5A9OzIBmQ8PZ4g+MHJhKXAr0fz0/uPPwedQfkwKeYX7W3hJlxHWMMf5qqm+FgqJAaXb8WUrBcTJuW2/Ng8u9qJ54ZpRWalJNXM5Z0WfiUC4M8Rz4lM2JxYM0ft+NuXasQezuXkAQDz43x+/Yh5+HdFotTTzzFVxt9N1AOl2c9ztTN+/ch0BoCQKQmsHZBfDYUg83wbQ+jupj6Qnk+WrwMaB23pkwvV3N41wLQgzNhG+jOS6LjmtlKdaeK2bhMYLCKLDQ8q4NWh8681mS9fPzUpxK7oHAg3VV6g1beK0gGsDk0GewyvhfBI3itZNQuOg7jt8No/VTQcEtWHUGAWSORwrDzFNMPAJv+UF1jVP8V7KgR25bZhoxKMh2oJ4kSSE1e6CM9sLwOm2zKw9b6FZT3SXuCVrEWDUBq5Lfo3KDPEf2vwMbvUTgO2iWN/WiIZDsU6vpM5g+ruQ9jpQ92TaXgfXJ0tP6yKCvu949H634BZCdoxFNwOCSrkk/fTngKAsmHWP9ou5aPTFyGePT81CGRDlcK4fbhu4U0VuBgB357pToYOMbBQwQbrx+Rw9OTwQxu+y/1JRCiQCocQi5SZjnd5/HA80Dx6uFRhLNMBoQi9mvGCsER3Uqfd1rfc94v6MtWsnwCnsTd3WfF5UKl7lNmMlr+ENcJIyKkga8vx9uR/Mn6OXTSWX4zAOgaEv/6OAFm8bj+6AnDaFt59x7dldR/QWt2PLlOvG7BIpSpYxRY0KAyEXs8itxAf0eIGh2sWq+KTnPpj27ITZz2Vyvw1GOq7LQoCwXMvV/483TgutpAoyqtB3q+9CfDkLIw5tHjRmmearOJeKuojyyDYf4bkLf8KIRQu3DSxPERCKrjIqkTvF7XyQYd0QOs20hVXsQaixXM6JwxJXbjlM6kmvLe5H+u/FgOvwL8wyAZgrFiw5Nm2NXBP0gfaEUTM5LP7NOE+oMdunxKECTFl+vkufAGukOz6Iz8CJPQUICbDKLBjofI7o9FXavRqry6uwvhQn6CxZqxNsfD7BxgUu7yKyPJ3QbfPRX66KWZ1qbJqPgF1961MbMADYgnEv5p6E/rI7OlRJKLQ21AMskSaZTcxhV665Xn3LLWK5iRyy2CyWOFj1GvCfjHaelD8jn1iT1rmynqnOBjn4O36FV/D/JgyK7p9jlisUnDhgXafQbaKp6OElReXdeH9+pyiQCITa7cmqrtxCRgo5x44iK4Gs1bYpWByGZx7U6ZvisLhHUpB0PGrC/2MhxZcKF4wRveKrZlnXvj5kcuawF/62YPpns1wgZC2+R3P44NvbEowNho3sYg7b/UBzUzfFljaI5sy5XUf0eks/pvV/jEwfZC5Y9F2GsxrdmScizhH+r/JKrH3jYMhpBT++q0b1DPPPKwmGsrVMBgiragQgcUjiDJ0PnsarfHaKjSkRo543B4Kpe5r6g8gKD3AFGwrNpjZfmbza/O9i5cqC0bpS7Guy94fNJBNDCEha1cEAODKBgMDPRqvh+BTxJYGxzT85innZFvP5FOI/WYJaYI7VF9CQZLcpPrdRhYNDJBruhovnPsRFVVsCStVX2wKiW/kcjG/hBYgcJ3Df3weABbbaDJUwglIHGKWE+EveCLjdCWDeAWDK6lN9SsQpgNM4ZwrM8016di1ToHevJsCke+rmLpGlFd3Sf66aZT5DmLeCAqQvMuv7ERNU3KQVnbbF6hQ6noPo4hQAVcHEH6LuZnSAx+HSIhraCD9wiTdi6LM/fUkniJKyRtcmpsazXDcTt4tuROhBQhR0iYmGdZ8kBpUPo4sl64FQhPPlF1EgDoRje929unHN+pd3HtVLYc3KLco9OPnd6c9PfOv50hzAmvMO63rmhe1Pla3+AbxU77D7e5qHXL8LeAnGIPa8bTtNy9pUL7OKdnvaBcdN337RLP9gF3fe+9izps19zd6nY/Y61AzqpI20K+Gnpqj4ss73XfqeRNVzFnz/wXWT7rH36n86wnAeG5r7EFmx6w5Ty7IsLUWyRDAcwn+6jyumDZpwZ1AYzu00uoRutypSW2DSg0NBWZ0xkQwtBAZxMSfRVlo0NNVxaSAUvAkPgxsUp3EGhzPQiltWAwbiyAVQtXmJ7mDRVjQY53qh/uS0Llo4Axv5Ab4OCEpR6zZ7cV1je9M0jYgp0gtavSLgdnKMu1Rd9eOA9RDaeYPfMiIjskqYTzgzcb0CBL0z2yiC65jqL7UwdU6WPpH+5b+YG7tJOaIB4l0cR8N7ABysxUNxufvNM3kXEdlFIdmkFxQI6lMgKI4M38TgL9QVICeRRukm0ighBbLzarqLyWqO8Qv1wscA9idRlyhLRxHc4nk/mNUyuBFYNm1majZuYDKfIlrOhR+YJU9igdoU45yvFIkG4JMxmLjuLevNlrG4TdCfLW/Grpf+VIHUPRDGCOM/Kk6BOBA+3POusEltbRDDVZwcRXiu8Z2H9bB6kNKFUGsH4tfEjjok7Y+yFph3O4/spfBotswcMOEEdp56UVvwAszEfrQGWi0sRoN/dxzRM3HVdpdIAW6jd1DkQS9xVbli2opP9w9zpXQl1kDgxL2PNFefeMk2E4PmHxcnBX3+9tJj7WbMfcNmjyhlLPNdcRA9KSmMPD1/xYJDrpo4xLZRBke4tW10hiZafETnkX3VmbhCiavtSv87KQInPWejOWQYpnI9BwBgSyqGHT/x7It7uRK9mIy1cjgUrs1l35BocyOL82w+FYVJusdxLNraGIjDEbAJsCy44vs2i0Ud/XbwAxtBl0pIbboikHRiVm3+BCTSw18FYDnAEABp7DH9YRMZiXBOQSqIV2YWKzC9rhOXJZGhuKVrOMj3F8F1Ie1TxMGtaPNV6uq+CVR1aBwCa+aEN4UJJlCnBhuAMwkYcAluDQJBjU/zEjeKcUzjrsxHQEreURspaiPGNg9jdPNorE2rE4WLAwSDRsz5KOqLVpl5ZuNtcIISUTufRmW9gIMM8xRAXH3QPhxzsIYNgAJ7G3SWz3D9cdBCCXlzOQTIsiGQRMQGVefwQChi+fKLKBAHwuu7XdbryN0OkuXXFowi5PuQyp+TgmgwptOontqBligvDx6XXVgUaqcs0VA96kcyakbOT7QeJEvClSyg7BpxNzKBkp02BzQ/BDSPSWhMhgDSV8gARNHuBYLSVfhSPgVkPKQFxnTZ71hz+XEyniu7PPbW8wsnvzdNnEppIORMMK8oKdw/tTjozQbF5i8sFwi3Nr/g3Ieunr5u03qFntECLv3V76kIUKTzE1fjjHsEGvcBgs/zvBOyK3gcEOzOOYGLFl4t7i5QRJqisvBbBjcyVnoBcBHxxb04ELTgBhjcTFvUDQGt4EvqibN0oCKaiX6qywPfBGAJNS4492AUerEhsb61yFtOkGMTOjfF8CU0m3mL9639QpN/KKAlNxABr0ScAjjbJuPUp343Yl7z4VgVjkzPgbM61f/K/Sf9pwBdLgvXwX31h/vSJkt9au62/4NNk1qIOHXNcr3rfCajS3wRlw6JmDWXHPWL4/zhuGhIb4qe0240mhKs4DEMjhRjWICqNhWl52iWmdu3mOT6c81Pa/gtY7h0xMt6poporHpdk72ePoYS9k2WvQJQpXEiP2Eoq1ONT1y99LGJ+lY174unwM+iQKKOsPGMAeN2QyTzEi0grQg/xIdQgbMLiOiiHePo0kYvQ4YMiRy0rhkvQiBnswU8oPskByldTxrevUTC1mnXkg4oosUjZHGRX2w4f3NqyiGnDyUh9lbQk15Dfl7aGe5MLrWfNck/YGUZeryqeXXYq33uwE69WTfKLs9+MMNMmC1XMekNx7HhLuXTF4Y/RYPiA7uOuNQ6y+0osszomRPyCLgukMjlaPE7pK3AUBsJifJkIIZLeMpoHMiviZikeZ+axVqorTUjh0BAz6aMOVi868PhpLhN4SzATS49VtcVo4MFt1gWeulqBUTzWcyPYzEXCDndegIINr6WmzLSbkCN+TdtSn/p+ha4itNDf9i4D1IY6dlwWTAn4Ct4Cq4fAgFJbTROJ2ZVmDdlr+9GXdxEIlGA1VmdOsCyuj70gg/SL3FGzU3UH4oUZxj6Q73/6lP32OoPNQ9FzaHOcdSVuLgu0XheIxqMQDCXw260CMi9sbbJeI86ll58tmPuL8fiilpL0hidxIkiKg6fBPgu47uMjXaF89PzJMv1ZKx7Z+A/iI40nhORbB2Zm+BAP8GlRfdHPpUDODwQxojqPypOgUQg1IOf/9Kg8QdEw/BlDCRIqmv6ECwQ0/CAMGkEjghsFIBRySZlTCLYEZbtE5LAbuC6uZFIpHWwpVrXTg9cGI+d5oanLAgh0WXotBYvf+Hpoy9bsaV4i/wQBYjyhbPiPl92SAFZL9ps9JTh0/qPz4aH1wK6TXFA2DirgRnbS5vyMssijF10H0y3A06Y0bfDOSeBl9tEWdH/98181LxMcG6KuIPddzjSqllBgCQAk/jRineJNFOIsYcARc+iNfjgEPckCYVCkoX7m+w83oOaMR2WRKMCAMvhUCy4nQV39YPJllhfRjZr8Mc7koDToqUDS4k61W7Rfqbp7sQE/RIQkCHNB4CgAFriTb2LWuytEQ9AsQufcisQQO3Pu9Mfd4RZsTriGuOiUwDzAsb3uDabvLe11piNLX8wa8RBCTDUrtX1HWB2Qb1RBKgFiIBDWV8+Tv9j+RRgOdGp+sO3sBE6SJuuSYYzDQGw9wCwfyS0acfKOKW3Fl30eSK5BN/H0V56WWcc4+o9wpwPA+QaxsTMB/5k1nZcYdZLyqE6rTj/CTeiP2JSGdmJzvU49xTBDXYv2AqEAmTlJvRACBF8+WUUSARCLQI2ftKUARNaYY2GZVlQl+CKR6zMC75sUKeoLyB2DRxipnIOIj79O1aJD3Yadqn178OiFFGQwXw78jYvSjOsRKW7KLMQf/TWgU/dNeTrJT+ofxX5A2mH7svOUeAIqlk0okjHdT00HccCKDqWKC6rRPN6TcxBLeTuVnZ5d94neY+8MWnM0jUrhnEvM1lsxXnsWrr2sOkPm1lfvWca12qwaUn+8jLDsO3cFP6/13Jcn5zuLUdD0TMsfaBA0unvzuQ7uiqy1ZpGIX52CwC3NhjSyOjGiToth8UhH0At5ro/CEGiHXAi1/vhwFKgZXV9+l+O+FvVBmY+ICSwcsDquDuBlsScEl8KxAAh8zcAhEDVFqj1v85bru0QU6dmkaku3a0NiI5fX2uiyAgkNVcVJzrVOLEQD9DHkyUGwzZEpxIzqp7a1Dg0H4GwgFkWmlJtpNH/XPq/PaFNrRuKYXooz59EyKLn0YhRv8D1Qhkm1I42ARon3HKTehjRKbAAG7egO2vFiYReu2yxWfco/2verYhQMyqFuKTQRHPUmNqhLyQFVXA8/odfcr10hAJCrRkCZ/ld+uIpUGEKJAKhAyXbGBaBjTCOQLwT8BCH+5It4kd7fuB4HGbZQYYhqW5sGLXXAMXbOw7v9Q4c36UwEkMBys/56224DCnnyyraibuEnnYhr/AM/pwX5jBtp0cVm3ejyDB9wLgnuCHlKwx3QCseABzBg6NIk2X95jCu0UJzSeJld774N/Pf7z4yu5Kq6cHut39BXYHB77U4MJR+zOk7NWe3gGteF3M8KokyMT1Xc0ErODwBjfSCDjgsh4eoEQdzQwYXQwi1oDsiSXGSEgeqnkDIApYa3QqYYXvovSq24AuwXF0HwqqnKDA91D7tvgJgabMjmjsjGis6jbXJ9wAQCzF6MSdTVwGpc2L/awwWhGM6ScTrhERFh0n/0k+qnvoVaFv9YaxNPQsCJEAqmD/XrOixxWyRH6tAS20uRIy5hPihqi+wlLHOfCLRDCAijTN4ExBajpn5yChItgAK63YagQUGE1hAsnv9L9DNpI4yWdzC+Ifxuyl0H0Y6rbMAzbPhRKWflQpF4CxuU+HVrEuLL54CFaWAA0IB2jaisNeHTKhesC6ql6duUZLZ9ZR7e9mg3CpTrn2sSRAp7oWoSE5sVmcUDaN3AYrrgzAymdZWR8Pgiq4jem5VUP2vSNRxVeyndAxlivQqOqE/0XXi3uUWIXrKjNwWuDn5oblNhjstcV+Zos7S9OL+5RdGww6njOxt/cdeGjj++OJo+BQ4YP28hrxwn/nghzlmj0YtzKgLxECZ5Wx4rK7td1wEQHLWdmBIHj1zneZDNJbR6KWuViDpNqZBSxzxFQ3G6QXjHB45A4lWE5F+ewsvEz6Fix1nqXdDoKH3KAZYjVnAbcokgeIuAJHEexqDwDCuPwQQZLE6g/YKeFG/jUVWEQA7IxrLtWmc6AWRCBgZ+WD4Er2SUGSIR22b6tv1X4T+8hweBr138hkOaFPAJ/GvgEyA57hbgbANcxjTXy5aagpOX2TyNB9XbF3qiQvswCFgzF9i8i9YbDZobhpbvE3qSad3B4f8DU9Hz3kPek5FihFtBIL1ED9fzAROBwRlBJRMRJyhRJjpz/cblOeQT6lPHBDqvKxoPRAm3BT/9edTwAGhLOCc+GSbVgixppxtzbGg6dox5rCdWGkqi2UkDLGQCw7npQEsw7cxtDnURMNqxZFo24RsFXK+tdwLZVbs5fn5o/ZXiALyY9POXItvCZknnJwctmXIES/c6PXofb8F6ORrtt3CPdxIHspjuo7qLWteW+A2X+D8qZc/erP5adUS07BmPTO+j/M8MJ8Bhs4QYkfNV9X/tRCLbs4lROLHa8gkUYTYTlaVMgATUDnxZSkxZ7YNnQad5VM4hO8CGNUtIeZsZxp1xK9uOrQMCUB9zAdmgUSpDljjIlbOBQDHauql0OZqAEt6wkTDnESu8VT+ExiF1B1G//LJdcCq/iVGdJyoxskmKqyGe8Wu75tFCqCtOpqbAFntyqpTbh+4f4TgZpAPd4fBz3K5nbh1ws7/INOY9EvBFLldUa/OBlPU9WuzXJs0p7uM04n58D1gIxGqT7mdyKhGICawFNf4OXWUz3H0h4RkI7jBWZkmBcv08OGYr6SGJiMZhbyTe8dADtFMHLkvngIVpoADQnEMMsAQx6dDhi5yZncpMZJI8/NiEAbHrC7Ie6jfxNslknApj6Qn0pFeO6NmnY77Hn1ew5r1D0+OJGEQExYXR6MbRr00XlyjsmW74M16iLUL9aXiFJCo2hlRKPZiiQIYCiBLiC0BwVUsa4ivrUO8oqSUX7CkQLzXscvwnq+6ShKLnzKq77+KiotMywa7mPsvUjO2FAOE5W6kKj7FSr9SnMYzHJYzbGwyCtghpi03G/SeyKpWuikBpkBFC7gFF7gxNop2M/J0zJ1CC7vqqWiRtmLGWN1N1K3GppJ0K0ukUysPWKWWINl1KGvq3WhXurgShjmxJgWYJLYNSSUSTAIEJWFJBGFr8KK6EjnyIRBJoe7BH5hF4thyOARWDrBj+sts+ROnC7DRdR6NrlPjcAY/ieCmDRkbhaAmesGzsboVR6tnIVEcLLHxi7SlzdlanqtXMfZxDvIamjVMgo4ypLuMudbc3zTLjpjiecxrNuJQZatREa1kJKZnV5yhVC8eCGPE8R8Vp0CijrDirfy8KyXb/z3rlX7ebH+72tpMHFAvs3bhxEtH3I+uTrvjEmVq/7FLMW4qIbYUd1FYFG2dmpR8VDSIyndQi0t5hbjbpjth2yTKUpE4z/obCgQFhrEyHyDcxrDmt5v6b9oyejsjcb7lDEkj9C3Wj9poKNCDQMaJGR2HpaDe2ujNYQGXxaQAS5s8AUGca1NbAJH0YgLZe6grvbiAxQFrghGNjWGqqC2FKejn3zVL1LfTHyZyjWpT1wEM4Wy4JoknyzG4aYqoNyp9Mor94ByASIDi3sO46FTjBLReAbSO4WsSdY+nrnR/DoTjuk76foLzClIg/WU/QFgcdY7a0DkOKw4+wDTEkCZJBi15tPcZ7YmDVd+ai8Zr6SQOmM8nNpnaA6ubNYsB1qUY3LgxOh3qcOq4gBIeCGPE9h+/jAICQnF90h9JPKpPd5TXsvSJiUW/dYirdJ/639Vzn1ogxGW6qB6/bOR/8qurpVSbt7lwswWfh7rfblo0aHYPmT5KGB1NGTCmFal/PuMmlw6Hlw9wWV0PXN7/BWF4JzdJC02ZhRv7EGCoEGIvcyhhcsH0geNuAiWvh8v8hraO/oPdDs1HnKH0onp+9Z7IOEk6uARdX1MW5Kg4kzW7EiuTC1RPC7doG9f1iTY42KMLCzrR2GR0XYrh6QBTf8fb3Nc02SPZhFbUB91PxX3AAZbaLC2OFQjj2hB+DQiKW000uIlzogCMIuJIJKq4vzfBYUnXpnGqfilgb4LeLZTERy4dZ8TAzYFwHNz2M80OSjLFiM5DnRtG/65NbQBKiIPpH6OZgPGHP+JXeCQ+leIA1bc1tuGQT+O50EYuHCnQ6gfErSnMHY447iepzYXqPsZxFIfjCEvQWXTzxVPg51JAL255JTF7e2nw+7n9+Pq/MgUObLH3px/NnysOxJBN3uy3S+tVM+fOluGBfNG06GnxS0uKRDJqpdfMSkupFklLqW7TJ5GQ12AAs+T9Hz4V55Oflpq24ZQDjju+cVbD49ZuXGfWblxv1m3aYDZsLjDL8lealevWmNUbrHTNFfmJVdUg278GpbVAi47Su7kg1uKEZEDkDMsiJPjVQk0kiMIvOKmNoFMXaFMpn1u9XwG6uCyirRA6LdxCElst3Nps6v2S7lH13PsVYH2ZzUURnNvzcBOQXlJjcWmkVNcW9GjVktHJ8ZXsv1FZZ6ov1XWbWo3HFvqW4QncXbgRLkuqD7WnQ/0KtFz/EdwWFCWKyYT5HJqz2nSSI9XV3AjYmiRJg22TsSrtVGI9ba5VL6TvesxfUXzIPlysoBs675Ibqz31Ea1mkrWpk46TOK9BCjSV24meYw1HmwbV1UZaYlFtCjwQ2rvry69Bge0B4a/Rvm/jt6OAFuG4Mctv102ZLYszklXiH7loYRdnKC54pyxu/8jEqIJz04YCv+WSnHcVHKcf0u+AAh4Ifwc3aTtDlM/guRxdOMQ9aNcs1k36Q2f05Kwda++/S+vTthQXpq/fXFC8ZM3yBXzXAi8uRtyJkwBsSU1OCepkZGVVT0k16zcVmCKiKuTDKRJqT23JZF2+bX+GIjAUbSUWlk+eOJTCTJN6MFlVssgr+PlmUyTORe+RuB7RX9yR47KiBL2+UH+vMgUTOC8uTZy61APyRdQ9siqFmqb6odVN0iFwbIuoqwD0alPWleKI1GY8E0tDk9EPrqn6arPxMbgsGatIXC3uUPdHejbLDdJefXIQ9qaB9WSvf5BTut/i5DQv1ZMBjOVa65n08+HcspnPB2SJkFGNuDDpMPW/5i3ODY4xqVaWqaaM8ZtXmgKJKcXdyXpZbauOc7EKapvqBOaOpMHdvcchtxPRSIZ1Gp/a1GeAe8S+cKLSQQbrTeE7hG/TnNWO5qWxWreTWB/qpwWH9KE5HF40GiOO/6g4BTwQVpx2v8sr/9V/fLNTR/aU8cUOCz6J32Pc0AIT+tUEVLB+hH/CooXYuSJsIq/f+SkmuR9iw7dwJxBHIhGjsiUI4ASWNjqTShtTH2fvoNYCs+7QtUrUsLWOjGNkrSnDGVvYgSTvbhqQTSFcif5M+i8Vha8TYEo3GfffbWXqk7Yo2Btd292ETpMRkzYw0vepX+kF4+/0XqY++RKD4i/NchmXqMhQR0Co+28TO6u0NHXJqhy5CrHlx1+blcrd6OakTZLGKSC2hTZl9JI636w7ZpPZpHEJwCSqVHvx54pUTKdlmJRb2RHM/M6skCGX5qK5SzSqccaBHf9MiTkzmNN1ZKjQJs6JggWcsn7WNdaaNaGoz210saXq+J+eAjtFAQ+EO0UmX+lPToE4GLYwtW9DN9f2O7OasKK2yPBDmwRZPorDihecwRMLRa4AAAP4SURBVKcVmM1/BwjlL6fFXaChOnJmt7q2coraU+xXgZA4t3ih/+sAt3rk9VOcTbUp012Bofov0eYepu5UMtGLo1WRrlOclNxAtpuAO9a3xlCi/5amzr1wwgetMQVXrzAblQZJXKj61xhLzGl3U/c/LC4bY/1rnOpb3KDajCfbhruuj6/mZCxzn841+ZI0yOhHOkbV3YamibSIfc/lU4cvngIVpoAHwgqTzl/4J6OAwLC0q4kCayukmMSjEnWWLolcjLhGcVhyHyoNgon1JA5sw6GYoTvi3MXhSXyqjPJxTpTvGmtiERDJsEqAlbuD+yYA1Fg1J5uRpJyiNuWTqH4Vhm17QTkE6qLdjxxxn0rXblOTvvtCU6Cg4qKnXFVED/3eJnB/qbGontqzriy+eApUlAIeCCtKOX/dn50Czv1BXMs2i3sp4ggExDnGfQXLIZ4ATGJO6cTU7vaKxIISNUrMWMKkt4yLnHO/2iwtYkys7uaUy0np3rZXxN1Kh6ioNTvTpvN/3F6bzvVEc7Kh43zxFKgMCnggrAwq+z7+iBSQH5zTUe1ofgIMcS3O6KO8+gJCAeaOQEjXOz+8HYGg6qpNAcv2AEv11L/GuiNg17wFWnH/x+0QICfW7o6AXU0cyqF6HgR39ET5/39VCngg/FXJ6RvzFPjTUEDc486IJJ2YdkcgLMLtbJt/GiL7iVYOBTwQVg6dfS+eAp4CngKeAlWUAh4Iq+iN8cPyFPAU8BTwFKgcCnggrBw6+148BTwFPAU8BaooBTwQVtEb44flKeAp4CngKVA5FPBAWDl09r14CngKeAp4ClRRCnggrKI3xg/LU8BTwFPAU6ByKOCBsHLo7HvxFPAU8BTwFKiiFPBAWEVvjB+Wp4CngKeAp0DlUMADYeXQ2ffiKeAp4CngKVBFKeCBsIreGD8sTwFPAU8BT4HKoYAHwsqhs+/FU8BTwFPAU6CKUsADYRW9MX5YngKeAp4CngKVQwEPhJVDZ9+Lp4CngKeAp0AVpYAHwip6Y/ywPAU8BTwFPAUqhwIeCCuHzr4XTwFPAU8BT4EqSgEPhFX0xvhheQp4CngKeApUDgU8EFYOnX0vngKeAp4CngJVlAIeCKvojfHD8hTwFPAU8BSoHAp4IKwcOvtePAU8BTwFPAWqKAU8EFbRG+OH5SngKeAp4ClQORTwQFg5dPa9eAp4CngKeApUUQp4IKyiN8YPy1PAU8BTwFOgcijggbBy6Ox78RTwFPAU8BSoohTwQFhFb4wflqeAp4CngKdA5VDAA2Hl0Nn34ingKeAp4ClQRSnggbCK3hg/LE8BTwFPAU+ByqGAB8LKobPvxVPAU8BTwFOgilLg/wH0/+T4yIJBdQAAAABJRU5ErkJggg=="
    }
   },
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![Untitled%20Diagram.drawio%281%29.png](attachment:Untitled%20Diagram.drawio%281%29.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Example: two-qubit register\n",
    "\n",
    "How about we implement Deutsch-Jozsa algorithm in Qiskit?\n",
    "Let us start simple, $n = 2$.\n",
    "\n",
    "### I: Create initial states of the registers\n",
    "\n",
    "In this case, we initialize by creating $\\vert 0,0\\rangle \\otimes \\vert 1 \\rangle$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# imports:\n",
    "import numpy as np\n",
    "from qiskit import IBMQ, Aer\n",
    "from qiskit import QuantumCircuit, assemble, transpile"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "n=2\n",
    "dj_circuit = QuantumCircuit(n+1, n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "note that we use `n+1` qubits, since we need on more qubit to use as auxiliary.\n",
    "\n",
    "### II: Add Hadamard gates"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 206.997x264.88 with 1 Axes>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bits = []\n",
    "\n",
    "for qubit in range(n+1):\n",
    "    dj_circuit.h(qubit)\n",
    "\n",
    "# Put the n qubit in state |->\n",
    "dj_circuit.x(n)\n",
    "dj_circuit.draw(output = 'mpl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Here, we also use a X gate to obtain a $\\vert - \\rangle$ state, as seen in the original algorithm.\n",
    "\n",
    "### III: Call the oracle\n",
    "\n",
    "The oracle function may be constructed in different ways, depending on whether you are aiming for a balanced or constant function. Here, we use an oracle that can be both, depending on the parameter `\"bits\"`.\n",
    "\n",
    "This oracle is inspired by this QHack 2022 problem [3] - feel free to try it out!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def oracle(bits):\n",
    "    for i in bits:\n",
    "        return dj_circuit.x(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "How exactly this oracle works? We will see this in a second with an example, hold on ;)\n",
    "\n",
    "### IV: Apply Hadamard to qubits in the first register:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "for qubit in range(n):\n",
    "    dj_circuit.h(qubit)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Finally,\n",
    "\n",
    "### V: Do the measurement"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "for i in range(n):\n",
    "    dj_circuit.measure(i, i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "All together now:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "# I: Create state |00>x|1>\n",
    "\n",
    "n=2\n",
    "\n",
    "dj_circuit = QuantumCircuit(n+1, n)\n",
    "\n",
    "def full_circuit(bits):\n",
    "\n",
    "    # II: Apply Hadamard to all\n",
    "    for qubit in range(n+1):\n",
    "        dj_circuit.h(qubit)\n",
    "\n",
    "    # Put the n qubit in state |->\n",
    "    dj_circuit.x(n)\n",
    "    dj_circuit.h(n)\n",
    "    dj_circuit.draw()\n",
    "\n",
    "\n",
    "    # III: Call Oracle\n",
    "\n",
    "    oracle(bits)  \n",
    "\n",
    "    # IV: Apply Hadamard to all qubits in the first register\n",
    "\n",
    "    for qubit in range(n):\n",
    "        dj_circuit.h(qubit)\n",
    "\n",
    "    # V: Measure first register\n",
    "    for i in range(n):\n",
    "        measurements = dj_circuit.measure(i, i)\n",
    "    \n",
    "    # get results\n",
    "    \n",
    "    aer_sim = Aer.get_backend('aer_simulator')\n",
    "    qobj = assemble(dj_circuit, aer_sim)\n",
    "    results = aer_sim.run(qobj).result()\n",
    "    answer = results.get_counts()\n",
    "    \n",
    "    return list(answer)[0]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "We can now create a Python function to tell us whether the funcion is balanced or constant:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def oracle_type(bits):\n",
    "    sample = full_circuit(bits)\n",
    "    ans = ''\n",
    "    if sample[0]=='0' and sample[1]=='0':\n",
    "        ans = \"constant\"\n",
    "    elif sample[0]=='1' and sample[1]=='1':\n",
    "        ans = \"constant\"\n",
    "    elif sample[0]=='0' and sample[1]=='1':\n",
    "        ans = \"balanced\"\n",
    "    elif sample[0]=='1' and sample[1]=='0':\n",
    "        ans = \"balanced\"\n",
    "    else:\n",
    "        ans = \"Neither constant nor balanced\"\n",
    "    return print(ans)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Let's call the function, having [1,1] as an input:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "constant\n"
     ]
    }
   ],
   "source": [
    "bits1 = [1,1]\n",
    "oracle_type(bits1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Why is it constant? Let's take a look at our oracle's definition:\n",
    "```python\n",
    "def oracle(bits):\n",
    "    for i in bits:\n",
    "        return dj_circuit.x(i)\n",
    "```\n",
    "\n",
    "Therefore, in this example, our function is producing\n",
    "```python\n",
    "dj_circuit.x(1)\n",
    "dj_circuit.x(1)\n",
    "```\n",
    "However, our note that CNOT is reversible (you may check it yourself by multiplying the corresponding matrices!). Thus, applying it twice does not change anything."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Some final questions\n",
    "\n",
    "1. How to construct different types of oracles? You can find different approaches for both balanced and constant types. Be creative!\n",
    "2. How to generalize our code for more qubits?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "[1]: Grover's algorthm is covered here: https://qiskit.org/textbook/ch-algorithms/grover.html\n",
    "\n",
    "[2]: Modular arithmetic: https://en.wikipedia.org/wiki/Modular_arithmetic\n",
    "\n",
    "[3]: QHACK problem:\n",
    "https://github.com/XanaduAI/QHack/blob/master/Coding_Challenges/algorithms_100_DeutschJozsa_template/deutsch_jozsa_template.py"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}