QuantumSimThreeQubitAdderGrover.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# QuantumSim - Grover Search using 3-Qubit Adder\n",
    "Author: Nico Kuijpers <br>\n",
    "Date: January 26, 2025\n",
    "\n",
    "In this notebook, a quantum circuit for a 3-qubit adder is included in a Grover oracle to find all possible combinations\n",
    "of $3$-bit numbers $a$ and $b$ for which it holds $a + b = S$, $0 \\leq S \\leq 14$. Although QuantumSim is used in this notebook,\n",
    "the code can be readily converted to Qiskit.\n",
    "\n",
    "The $3$-qubit adder is introduced in this notebook from QuantumSim:\n",
    "\n",
    "https://github.com/nicokuijpers/QuantumSim/blob/main/QuantumSimThreeQubitAdder.ipynb\n",
    "\n",
    "For an implementation of Grover's algorithm in QuantumSim, we refer to this notebook:\n",
    "\n",
    "https://github.com/nicokuijpers/QuantumSim/blob/main/QuantumSimGroverAlgorithm.ipynb"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from quantumsim import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3-qubit adder\n",
    "Below python functions *carry()*, *carry_inverse()*, *sum()*, and *three_qubit_adder()* are defined. With these functions, a quantum circuit\n",
    "can be created to compute the sum of two $3$-bit numbers $a$ and $b$. This circuit will then be used as a part of a Grover oracle to find all possible \n",
    "combinations of $3$-bit numbers $a$ and $b$ for which it holds $a + b = S$, $0 \\leq S \\leq 14$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Carry gate\n",
    "Below, python function *carry()* is defined to extend a quantum circuit with a Carry gate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "def carry(circuit:Circuit, carry_in:int, x:int, y:int, carry_out:int):\n",
    "    \"\"\"\n",
    "    Extends a quantum circuit with a Carry gate. \n",
    "    A Carry gate determines the sum of the carry-in bit and bit values x and y.\n",
    "    The resulting sum will be stored in the qubit containing the y bit.\n",
    "    The carry-out will be stored in the carry-out bit.\n",
    "\n",
    "    Parameters:\n",
    "    circuit (Circuit) : The quantum circuit to be extended\n",
    "    carry_in (int)    : The qubit containing the carry-in state\n",
    "    x (int)           : The qubit containing the bit value x\n",
    "    y (int)           : The qubit containing the bit value y, here the sum x + y (mod 2) will be stored\n",
    "    carry_out (int)   : The qubit to store the carry-out state. Should be |0>.\n",
    "\n",
    "    Returns:\n",
    "    None\n",
    "    \"\"\"\n",
    "    circuit.toffoli(x, y, carry_out)\n",
    "    circuit.cnot(x, y)\n",
    "    circuit.toffoli(carry_in, y, carry_out)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inverse Carry Gate\n",
    "Below, python function *carry_inverse()* is defined to extend a quantum circuit with the inverse of the circuit introduced above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def carry_inverse(circuit:Circuit, carry_in:int, x:int, y:int, carry_out:int):\n",
    "    \"\"\"\n",
    "    Extends a quantum circuit with an inversed version of the Carry gate. \n",
    "    A Carry gate determines the sum of the carry-in bit and bit values x and y.\n",
    "    The resulting sum will be stored in the qubit containing the y bit.\n",
    "    The carry-out will be stored in the carry-out bit.\n",
    "\n",
    "    Parameters:\n",
    "    circuit (Circuit) : The quantum circuit to be extended\n",
    "    carry_in (int)    : The qubit containing the carry-in state\n",
    "    x (int)           : The qubit containing the bit value x\n",
    "    y (int)           : The qubit containing the bit value y, here the sum x + y (mod 2) will be stored\n",
    "    carry_out (int)   : The qubit to store the carry-out state. Should be |0>.\n",
    "\n",
    "    Returns:\n",
    "    None\n",
    "    \"\"\"\n",
    "    circuit.toffoli(carry_in, y, carry_out)\n",
    "    circuit.cnot(x, y)\n",
    "    circuit.toffoli(x, y, carry_out)\n",
    "   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sum Gate\n",
    "Below python function *sum()* is defined to extend a quantum circuit with a Sum gate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def sum(circuit:Circuit, x:int, y:int, out:int):\n",
    "    \"\"\"\n",
    "    Extends a quantum circuit with a Sum gate. \n",
    "    A Sum gate adds bit values x and y to the state of the third qubit.\n",
    "    |out> --> |out> + |x> + |y> (mod 2)\n",
    "\n",
    "    Parameters:\n",
    "    circuit (Circuit) : The quantum circuit to be extended\n",
    "    x (int)           : The qubit containing the bit value x\n",
    "    y (int)           : The qubit containing the bit value y\n",
    "    out (int)         : The qubit to which bit values x and y are added. \n",
    "\n",
    "    Returns:\n",
    "    None\n",
    "    \"\"\"\n",
    "    circuit.cnot(x, out)\n",
    "    circuit.cnot(y, out)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3-Qubit Adder\n",
    "Using the Carry gate, inverse Carry gate, Sum gate, and a CNOT gate, a $3$-qubit adder can be constructed.\n",
    "Below, python function *three_qubit_adder()* is defined to extend a quantum circuit with a $3$-qubit adder. \n",
    "Calls are made to functions *carry()*, *carry_inverse()*, and *sum()* defined above. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "def three_qubit_adder(circuit:Circuit):\n",
    "    \"\"\"\n",
    "    Extends a quantum circuit with a 3-qubit adder.\n",
    "    Input x = x0 x1 x2 is the state of qubits q1, q4, q7 (least significant --> most significant)\n",
    "    Input y = y0 y1 y2 is the state of qubits q2, q5, q8 (least significant --> most significant)\n",
    "    Output z = x + y = z0 z1 z2 z3 will be the state of q2, q5, q8, q9 (least significant --> most significant)\n",
    "\n",
    "    Parameters:\n",
    "    circuit (Circuit) : The quantum circuit to be extended\n",
    "\n",
    "    Returns:\n",
    "    None\n",
    "    \"\"\"\n",
    "    # Consistency check: number of qubits mus be at least 10\n",
    "    if circuit.N < 10:\n",
    "        raise ValueError(\"At least 10 qubits are needed for 3-qubit adder\")\n",
    "    \n",
    "    # Create a 3-qubit adder by extending the circuit with\n",
    "    # Carry gates, inverse Carry gates, Sum gates, and a CNOT gate\n",
    "    carry(circuit, 0, 1, 2, 3)\n",
    "    carry(circuit, 3, 4, 5, 6)\n",
    "    carry(circuit, 6, 7, 8, 9)\n",
    "    circuit.cnot(7, 8)\n",
    "    sum(circuit, 6, 7, 8)\n",
    "    carry_inverse(circuit, 3, 4, 5, 6)\n",
    "    sum(circuit, 3, 4 ,5)\n",
    "    carry_inverse(circuit, 0, 1, 2, 3)\n",
    "    sum(circuit, 0, 1, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the python function *three_qubit_adder()* defined above, a quantum circuit can be created to compute the sum of \n",
    "integer values $x$ and $y$, $0 \\leq x,y \\leq 7$.\n",
    "The function has as input the $3$-bit representations $x_0 x_1 x_2$ and $y_0 y_1 y_2$, where \n",
    "$x_0$ and $y_0$ represent the *least* significant bits and $x_2$ and $y_2$ the *most* significant bits.\n",
    "\n",
    "Below, python function *create_three_qubit_adder_circuit()* is defined to create a quantum circuit to compute the sum \n",
    "of $x$ and $y$ represented by $x_0 x_1 x_2$ and $y_0 y_1 y_2$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def create_three_qubit_adder_circuit(x0:int, x1:int, x2:int, y0:int, y1:int, y2:int):\n",
    "    \"\"\"\n",
    "    Creates a quantum circuit with a 3-qubit adder.\n",
    "    Input x = x0 x1 x2 will be the initial state of qubits q1, q4, q7 (least significant --> most significant)\n",
    "    Input y = y0 y1 y2 will be the initial state of qubits q2, q5, q8 (least significant --> most significant)\n",
    "    Output z = x + y = z0 z1 z2 z3 can be obtained by measuring the states of q2, q5, q8, q9 (least significant --> most significant)\n",
    "\n",
    "    Parameters:\n",
    "    x0, x1, x2 (int): 3-bit representation of input x (least significant --> most significant)\n",
    "    y0, y1, y2 (int): 3-bit representation of input y (least significant --> most significant)\n",
    "\n",
    "    Returns:\n",
    "    Circuit to compute the sum of x and y\n",
    "    \"\"\"\n",
    "    circuit = Circuit(10)\n",
    "    if x0 == 1:\n",
    "        circuit.pauli_x(1)\n",
    "    if x1 == 1:\n",
    "        circuit.pauli_x(4)\n",
    "    if x2 == 1:\n",
    "        circuit.pauli_x(7)\n",
    "    if y0 == 1:\n",
    "        circuit.pauli_x(2)\n",
    "    if y1 == 1:\n",
    "        circuit.pauli_x(5)\n",
    "    if y2 == 1:\n",
    "        circuit.pauli_x(8)\n",
    "    three_qubit_adder(circuit)\n",
    "    return(circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Convert integer value to binary number\n",
    "Function *convert_to_binary_lsb()* converts an integer value to an array of bits of given length with least significant bit first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "def convert_to_binary_lsb(value:int, nr_bits:int):\n",
    "    \"\"\"\n",
    "    Converts an integer value to a bit array of given length with least significant bit first.\n",
    "\n",
    "    Parameters:\n",
    "    value (int)   : Integer value to be converted\n",
    "    nr_bits (int) : Length of output bit array\n",
    "\n",
    "    Returns:\n",
    "    Converted bit array with least significant bit first\n",
    "    \"\"\"\n",
    "    # Convert value to a binary string\n",
    "    # bin(value): Converts the integer to a binary string with prefix '0b'\n",
    "    # [2:]: Removes the '0b' prefix\n",
    "    # zfill(nr_bits): Pads the binary string with leading zeros to ensure it has a length of nr_bits\n",
    "    binary_string = bin(value)[2:].zfill(nr_bits)\n",
    "\n",
    "    # Convert the padded binary string into an integer array\n",
    "    bit_array_msb = [int(bit) for bit in binary_string]\n",
    "\n",
    "    # Reverse the list to make it LSB first\n",
    "    bit_array_lsb = bit_array_msb[::-1]\n",
    "    return bit_array_lsb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Convert binary number to integer\n",
    "Function *convert_to_integer_lsb()* converts a binary string to an integer. \n",
    "In the binary string, the first bit is the least significant bit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def convert_to_integer_lsb(binary_string:str) -> int:\n",
    "    \"\"\"\n",
    "    Converts a binary string with least significant bit first to an integer.\n",
    "\n",
    "    Parameters:\n",
    "    binary_string (str) : Binary string to be converted\n",
    "\n",
    "    Returns:\n",
    "    Converted integer value\n",
    "    \"\"\"\n",
    "    # Reverse the binary string such that the most significant bit becomes first \n",
    "    msb_binary_string = binary_string[::-1]\n",
    "\n",
    "    # Convert the binary string with most significant bit first to integer\n",
    "    value = int(msb_binary_string, 2)\n",
    "    return value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Grover Search\n",
    "Below python functions *create_grover_oracle()*, *create_grover_operator()*, and *create_grover_circuit()* are defined.\n",
    "With these functions, a quantum circuit of $10$ qubits can be created to find all possible \n",
    "combinations of $3$-bit numbers $a$ and $b$ for which it holds $a + b = S$, $0 \\leq S \\leq 14$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grover oracle\n",
    "Below function *create_grover_oracle()* is defined to construct a Grover oracle of $10$ qubits for given required sum $S$, $0 \\leq S \\leq 14$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "def create_grover_oracle(required_sum:int) -> Circuit:\n",
    "    \"\"\"\n",
    "    Creates a Grover oracle to check wether the sum of two 3-bit input values is equal to the required sum S, 0 <= S <= 14.\n",
    "    Input x = x0 x1 x2 will be the initial state of qubits q1, q4, q7 (least significant --> most significant)\n",
    "    Input y = y0 y1 y2 will be the initial state of qubits q2, q5, q8 (least significant --> most significant)\n",
    "    Output z = x + y = z0 z1 z2 z3 can be obtained by measuring the states of q2, q5, q8, q9 (least significant --> most significant)\n",
    "\n",
    "    Parameters:\n",
    "    required_sum (int) : Required sum. Must be at least 0 and at most 14\n",
    "\n",
    "    Returns:\n",
    "    Grover oracle circuit\n",
    "    \"\"\"\n",
    "    # Consistency check\n",
    "    if required_sum < 0 or required_sum > 14:\n",
    "        raise ValueError(\"Required sum must be at least 0 and at most 14\")\n",
    "    \n",
    "    # Qubits containing the binary representation of the sum\n",
    "    indices = [2, 5, 8, 9]\n",
    "    \n",
    "    # Determine the qubits that should be zero\n",
    "    sum_binary = convert_to_binary_lsb(required_sum, 4)\n",
    "    zero_inds = [indices[ind] for ind in range(len(sum_binary)) if sum_binary[ind] == 0]\n",
    "\n",
    "    # Construct a circuit of 10 qubits\n",
    "    circuit = Circuit(10)\n",
    "\n",
    "    # Three-qubit adder\n",
    "    three_qubit_adder(circuit)\n",
    "\n",
    "    # Apply a multi-controlled Pauli Z operation on the qubits containing the sum\n",
    "    # Apply Pauli X operations on qubits that should be zero\n",
    "    # Apply Hadamard operation on target qubit 9\n",
    "    # Apply a generic Toffoli operation with control qubits 2, 5, 8 and target qubit 9\n",
    "    # Apply Hadamard operations on target qubit 9\n",
    "    # Apply Pauli X operations on qubits that should be zero\n",
    "    for i in zero_inds:\n",
    "        circuit.pauli_x(i)\n",
    "    circuit.hadamard(9)\n",
    "    circuit.generic_toffoli(indices[:-1], 9)\n",
    "    circuit.hadamard(9)\n",
    "    for i in zero_inds:\n",
    "        circuit.pauli_x(i)\n",
    "\n",
    "    # Reverse three-qubit adder\n",
    "    circuit_three_qubit_adder = Circuit(10)\n",
    "    three_qubit_adder(circuit_three_qubit_adder)\n",
    "    circuit_inverse = circuit_three_qubit_adder.create_inverse_circuit()\n",
    "    circuit.append_circuit(circuit_inverse)\n",
    "\n",
    "    return circuit\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grover operator\n",
    "Below, function *create_grover_operator()* is defined to create the Grover operator from a given Grover oracle."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "def create_grover_operator(oracle:Circuit) -> Circuit:\n",
    "    \"\"\"\n",
    "    Creates a Grover operator from a given Grover oracle.\n",
    "\n",
    "    Parameters:\n",
    "    oracle (Circuit) : The Grover oracle\n",
    "\n",
    "    Returns:\n",
    "    Grover operator circuit\n",
    "    \"\"\"\n",
    "    grover = Circuit(oracle.N)\n",
    "    grover.append_circuit(oracle)\n",
    "    for q in range (grover.N):\n",
    "        grover.hadamard(q)\n",
    "    for q in range (grover.N):\n",
    "        grover.pauli_x(q)\n",
    "    grover.hadamard(grover.N - 1)\n",
    "    grover.multi_controlled_pauli_x() \n",
    "    grover.hadamard(grover.N - 1)\n",
    "    for q in range (grover.N):\n",
    "        grover.pauli_x(q)\n",
    "    for q in range (grover.N):\n",
    "        grover.hadamard(q)\n",
    "    return grover"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grover circuit\n",
    "Finally, function *create_grover_circuit()* is defined to create the Grover circuit. This function has as input parameters *required_sum*, and *nr_iterations*.\n",
    "The latter determines how many times the Grover operator is repeated in the Grover circuit. \n",
    "Using Hadamard gates, the input qubits are brought into superposition. The remaining qubits have initial state $|0\\rangle$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "def create_grover_circuit(required_sum:int, nr_iterations:int) -> Circuit:\n",
    "    \"\"\"\n",
    "    Creates a Grover circuit to find a possible combination of two 3-bit input values for which holds that the sum is equal to the required sum.\n",
    "    Input x = x0 x1 x2 will be the initial state of qubits q1, q4, q7 (least significant --> most significant)\n",
    "    Input y = y0 y1 y2 will be the initial state of qubits q2, q5, q8 (least significant --> most significant)\n",
    "    Output z = x + y = z0 z1 z2 z3 can be obtained by measuring the states of q2, q5, q8, q9 (least significant --> most significant)\n",
    "\n",
    "    Parameters:\n",
    "    required_sum (int) : Required sum. Must be at least 0 and at most 14\n",
    "    nr_iterators (int) : Number of times the Grover operator will repeated in the Grover circuit\n",
    "\n",
    "    Returns:\n",
    "    Grover circuit\n",
    "    \"\"\"\n",
    "    # Consistency check\n",
    "    if required_sum < 0 or required_sum > 14:\n",
    "        raise ValueError(\"Required sum must be at least 0 and at most 14\")\n",
    "\n",
    "    # Create the Grover oracle\n",
    "    oracle = create_grover_oracle(required_sum)\n",
    "\n",
    "    # Create the Grover operator\n",
    "    grover_operator = create_grover_operator(oracle)\n",
    "\n",
    "    # Create the Grover circuit\n",
    "    circuit = Circuit(oracle.N)\n",
    "\n",
    "    # Apply Hadamard gates on the input qubits, but not on the other qubits\n",
    "    # The input qubits are the qubits having the input values x0, x1, x2, y0, y1, and y2\n",
    "    input_qubits = [1,2,4,5,7,8]\n",
    "    for q in input_qubits:\n",
    "        circuit.hadamard(q)\n",
    "    \n",
    "    # Repeat the Grover operator\n",
    "    for i in range(nr_iterations):\n",
    "        circuit.append_circuit(grover_operator)\n",
    "\n",
    "    return circuit"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example\n",
    "In the example below, Grover's search algorithm is applied to find all possible inputs $a$ and $b$, $0 \\leq a, b < 8$ for which it holds $a + b = S$.\n",
    "\n",
    "The optimal number of iterations $k_{\\text{opt}}$ is defined by\n",
    "\n",
    "$k_{\\text{opt}} = \\left\\lfloor \\frac{\\pi}{4} \\sqrt{\\frac{N}{M}} \\right\\rfloor$, \n",
    "\n",
    "where $N$ is the number of possible inputs and $M$ is the number of possible solutions.\n",
    "\n",
    "Since $0 \\leq a, b < 8$, there are $8 \\times 8 = 64$ possible inputs, so $N = 64$.\n",
    "\n",
    "If there were no upper limits for $a$ and $b$, the number of possible solutions for sum $S$ would be $S + 1$.\n",
    "\n",
    "However, both $a$ and $b$ are at most 7. This limits the number of possible solutions to $8$.\n",
    "Hence, the number of possible solutions $M$ for given $S$, $0 \\leq S \\leq 14$, is defined by\n",
    "\n",
    "$\n",
    "M =\n",
    "\\begin{cases} \n",
    "S + 1 & \\text{if } S \\leq 7 \\\\\n",
    "15 - S & \\text{if } S > 7\n",
    "\\end{cases}\n",
    "$\n",
    "\n",
    "Below, a Grover circuit is created for required sum $S=9$. In this case, the optimal number of iterations $k_{\\text{opt}}$ is $2$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Required sum                 : 9\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 6\n",
      "Optimal number of iterations : 2\n"
     ]
    }
   ],
   "source": [
    "import math\n",
    "\n",
    "# Determine number of possible inputs and possible solutions\n",
    "required_sum = 9\n",
    "nr_possible_inputs = 2**6\n",
    "if required_sum <= 7:\n",
    "    nr_possible_solutions = required_sum + 1\n",
    "else:\n",
    "    nr_possible_solutions = 15 - required_sum\n",
    "\n",
    "\n",
    "# Determine optimal number of iterations \n",
    "nr_iterations = max(1, math.floor((math.pi / 4) * math.sqrt((nr_possible_inputs/nr_possible_solutions))))\n",
    "\n",
    "# Print \n",
    "print(f\"Required sum                 : {required_sum}\")\n",
    "print(f\"Number of possible inputs    : {nr_possible_inputs}\")\n",
    "print(f\"Number of possible solutions : {nr_possible_solutions}\")\n",
    "print(f\"Optimal number of iterations : {nr_iterations}\")\n",
    "\n",
    "# Create the Grover circuit\n",
    "circuit = create_grover_circuit(required_sum, nr_iterations)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below, the circuit is executed and 20000 measurements are performed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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BQCxatUqt+l2u11ERUW57XMy132qrT777DMBQGzYsMFt+tGjR0VsbKzYvn27x+XOFOR48swzz4j09HS3abNnzxbDhw8XJ06cULbdvn37xOTJk93Svf322yIhIUEcOXJEOBwOIYQQJ0+eFBMmTBBVVVUe17do0aJmg5zW9n1PcnJyBACxY8cOj/N9sb+fPn1a6PV68cEHH7gFU48++qj473//q/x96tQpj8Hu7t27mxz/PBk3bpy4//77lb/LysrEzp07xaRJk8SkSZOU/Hbt2uXWx7Ozs4UkSWLr1q1u+VVXV4vIyEhxxx13KNOmTZsmJk2apPwnVggh1q9fL/7yl7941SY9CS9X9UCvvvoqXnrpJRQWFvokP/lJEK1WC4vFAgBup51tNhvGjBnjtsxVV10Fh8OBjRs3ori4GHv27MFrr70GnU7n9nn99ddRVlaG0tLSJut94oknEBcX1+Zyy+u94YYbmlyznjlzJpxOJ9atW9fm/Nu73lOnTmHXrl245pprmuQxf/58LFmyBABana6t7rrrLgwePLhd6dauXYstW7bAaDS6bd+rrroKAHD06FG39IMGDXJrm7i4ONjtduXv1atX45JLLkFwcLDbcldccQXy8vLc1pufn4/AwEC39Q4bNqzJet99912888478PPzg1arRXh4OJYtW6ak9cbatWsRFxeHCy64wG16cHAwJk2ahJ9++snrPFtj9erVSEhIwMiRI92mJyQkIDc3F4MGDfI6z1OnTuHee+9Fnz594O/vj7CwMLz//vsoLi52S3f//ffDZrMhJiYGWq0WAQEBmDx5MkaPHu2W7vrrr0dmZib69u2rHDNGjRqFtLQ0GAwGr8vmTd9ftGgRRowYgdDQUPj7++OKK64AgCZ18SWLxYK3334bDz30EEwmE/R6PaKiorB79270799fSWez2TBw4ED4+fkhPDwcAwcOxMCBA5GamtrknqkdO3bg6quvRnx8PCwWC+Lj47F79263elitVgwcOBBBQUEICgpS8hswYIBynAZ+76tCCAwbNsxtH/H390dBQYHbPjJ37lwUFhbCZrNBo9EgKCgId911V5Pju5rwxuMeaODAgZg2bRrmzJnTqvSiheu5bSHnKUkSHA4HAOC5555rcgO0JEkICAhAWFhYkzy0Wq3PytBYR96o5+16nU5nq/JtbbozlcmT1rbzmdI5HA5MnjzZ4/0tBoMBvXv3dpvWmvZvTX0dDgcyMjI8PgGn0+nQq1cv5e/LLrsMhw4dQmFhIYqLi2G32zFv3jxMnDhRuQ+rtYQQXXazZ3v6gSeTJk1CaWkp5syZg5SUFNTV1eG9997D999/75bOZrPhm2++QWVlJU6ePIny8nL89NNPuP/++5GSkoLLLrsMAGA2m/Hhhx/inXfewYkTJ1BeXo7t27cr93rcfvvtXpexNXV+5513MGvWLDzyyCMYN24c/Pz8cPjwYVx99dVer89bM2fOxA033ICTJ0+ipKQEBQUFeOSRRzB9+nRkZWV5lVdBQQHGjh2L8847D//85z8RGxsLu93e6uN5Yw6HAzqdDlu2bIFG437eQqPRICYmRvm7V69e2LBhA0pLS1FQUICKigosXboU06dPR1paGgYMGNCmMnRnPJPTQz3zzDNYtmxZkxt1g4KCAPx+U6ds69at7VpXcXEx1qxZ4zZt2bJl0Ov1OO+88xAeHo64uDjs27dP+d+G/OnTpw/Ky8vbtf7mhIaGIiUlBR999FGTeR988AE0Gg0yMzO7bL2hoaFITU3FJ5980iTdmjVr8Prrryv5tSYd4Hn7FhYWNrnB0NeGDh2KnTt3om/fvk22cU1NjdeB9JgxY/Ddd981OcN37NgxPPjgg8qP3tChQ/Hbb78hJiamyXqFEEqADQB9+/bFoUOHEBERgdTUVGRmZuL6669HQUEBSkpKvCrf6NGjkZOT0+RMYFlZGb788ssOezR8zJgxyM3NxYYNG9ymV1dX4/HHH/f6qZ2SkhJs2LAB77//PqZPn47hw4dj1KhRbj98skcffRQvvPAC/P390bt3b6Snp+Oee+6B0WjE3r17lXTymDdmsxm9evVCWloaZsyYgYSEBLd0reFN3//qq69w880346mnnsL555+PoUOHYvjw4V6try1KSkrQt29flJWVITo6GgMGDMC4ceNw5ZVXeqyvTqc7Y3/bsGEDHA4HVqxYgYkTJyI9PR0XXnghjEajx/Qt5Td06FA0NDTAbrc32UeCg4PdhgC57rrr8J///AdBQUHo168fhg0bhnvuuQdCCOzfv9+LVulBuuo6GbVefX29mDt3rhg2bJjYvXu3cl34n//8pwDgdn9AVVWVsNlsYsqUKWLDhg3iiy++EH369BEAxAcffCAcDocoLCwUw4cPF3fccYcoLy8XixYtEtHR0eLkyZNCiN/v3/nwww9FTU2NmDdvngAgwsPDxb///W/xyy+/iOeff16YTCbx+OOPK+t97733hCRJ4q677hJr1qwR69atE0899ZSIiYkRSUlJSrr8/Hyxc+dOER0dLZ599lnlOnNpaWmb2ua7774TOp1OTJo0SXzzzTdi3bp14pFHHhF6vd7txujmbjzet29fk/tqfLneH374Qej1enH11VeLH374Qfz0009i1qxZTW5Qbm06IYTo37+/GD16tPjpp5/Et99+K4YPHy4AiHnz5inX/gsLCz3eH1BYWOiWV2vT7d69W/j5+YmLLrpIrFy5UmRlZYkFCxaI9PR0odfrxYEDB4QQQpSUlCj3EMjX/e12uzJN3s7Hjx8XMTExIi0tTXzxxRdi48aN4qWXXhIhISFi5MiRyjY5efKkiIyMFEOHDhWff/65yM7OFu+//74YO3askCTJ7T4zACIhIUG8+eab4ueffxZfffWV6N+/vxg0aJDX27ehoUGMHTtWhISEiNdee025YXfw4MEiLCzM7Z6o5m48dr3vobXkG57DwsLEW2+9JbKyssQHH3wg+vfvL8LCwpR74IQQori4WFmX6/60a9cu5cEEp9MpoqKixPXXXy+ysrLE999/L2655Rah1WpFdHS0+O2335T8ZsyYIbRarXjggQfE119/LTZu3ChuvvlmodVq3e65evLJJwUAcdNNN4nly5eL7Oxs8dhjjwkA4vPPP1fS1dTUiF27domdO3eKZ599VkRHRyvlPXz4sJKutX3/4YcfFklJSWLlypVi48aN4tVXXxXR0dECgHjvvfdERUWFkvbgwYNi586dTfb3gwcPer1N5PvgzjnnHLFo0SKlL0RHR4uJEyc2SX/vvfeK2NhY8b///U+sX79ezJ07V6SmpopnnnlGCCHErl27hFarFS+++KLYvHmz+Pzzz8WFF14oJEkSkyZNEnl5eW75vfrqq8Lf31/897//FRs3bhR///vfxfDhw8Wf//xnZRuPGzdOREZGirfeektkZ2eL5cuXi+uuu07o9Xrx9NNPK3mNGTNGWCwW8fTTT4sffvhBrFu3TkycOFH4+fm1+/7I7opBTg+watUqIUmSACAAKHfWNzQ0iCFDhog777zTLf3//vc/MWDAAGGxWMSQIUPE0qVLhZ+fn9BoNGLVqlXi4osvVvKaPXu2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pk2b5nYmZvr06Tj//PPxwAMP4ODBg8jPz8fEiRO7pC5ERETU/XTZmZyIiAikpKTghx9+wE033YRNmzbh0UcfVebPmTMHQghER0ejtLQUzz33nNvyAwcOxNy5c5GZmYm7774bS5Ysgclk6uxqEBERUTfVZWdyZHfddRfuuuuuJtP9/f2xfPnyMy5755134s477+yoohEREVEP1uWDARIRERF1BAY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5RNSsxEdWdnURiIjajEEOERERqRKDHCIiIlIlBjlERESkSgxyiIiISJUY5BAREZEqMcghIiIiVWKQQ0RERKrU7iDn888/x5dffumLshCpGsecISLqXF4HOb169YLVakVFRQUee+wx3HPPPbj55psxZ86cjigfkRsGCkRE1FpeBzlhYWF44oknEBAQgC+//BJfffUVvvvuOyxcuNCrfBwOB+bMmYPo6GiEhIRg1qxZaGhoUOZXVlZi8uTJsFgsmDBhAsrKyprksWDBAthsNiQlJWHVqlXeVoWIiIhUzOsgZ9++fZg5cyYA4NSpU4iJiUHfvn1x6tQpr/I5dOgQjhw5gh9//BHZ2dn46quv8MYbbyjz586dC6fTiby8PAQGBmL27Nluy+/evRuPPfYY1q5di1dffRVTp05FdXW1t9XpcB195oFnNjoP29oztgsRdVde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R4/ixx9/xFNPPfV7oTQaTJ8+HS+//DJKSkrwwgsvYNq0aTAajcry06dPx7Jly7Bnzx6sWLEC+fn5mDhxorfVISIiIpXyOsiZN28enE4noqOjkZKSgqioKDidTjz33HNe5fPNN9+guLgY48aNwznnnIMLL7wQx44dU+bPmTMHQghER0ejtLS0Sf4DBw7E3LlzkZmZibvvvhtLliyByWTytjpERESkUl7feBwQEID//e9/2Lp1qzIY4JAhQ7xe8datW88439/fH8uXLz9jmjvvvBN33nmn1+smIiIi9fM6yJENGTKkTcENERERUWdo02CARERERN0dgxwiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVMnrIGfq1Kn49ttvO6IsRERERD7jdZCzcuVK9OvXr8n0f//73z4pEBEREZEveB3kpKWlwW63u01zOBy45ZZbfFYoIiIiovbyOsh55ZVXcPvtt6OoqMhtuhDCZ4UiIiIiai+vX9D55JNP4vjx40hLS1MuWzmdTkiS5PPCEREREbWV10HOt99+i1WrVrkFNQ0NDbj44ot9WjAiIiKi9vA6yLn33nsxduzYJtMTEhJ8UR4iIiIin/D6npy///3vHqcfPny43YUhIiIi8pVWn8m5+uqr8fLLLzd7g7HRaERERITPCkZERETUHq0Ocj777DNs3rzZLciR78vJycmBn58fysrKfF9CIiIiojZo9eUqrVaLw4cP48iRI8rn7bffRkREBK655hps27atA4tJRERE5J1Wn8nJzs5WvmdlZWH27Nkwm8146623MGjQoA4pHBEREVFbtTrIGTJkCHbv3o3Zs2ejuLgYzz//PEaPHq3MnzFjBt5///0OKSQRERGRt1p9ueqWW27Bueeei969e2PevHkQQmDt2rVYu3YtVq1ahQ8//LAjy0lERETklVafyXn33XcxZswY/Prrr/j11187skxERERE7dbqIOfiiy/Gt99+2+z85cuX+6RARERERL7Q6stVZwpwAGDSpEntLgwRERGRr3g94jERERFRT8Agh4iIiFSJQQ4RERGpEoMcIiIiUiUGOURERKRKDHKIiIhIlRjkEBERkSoxyCEiIiJVYpBDREREqsQgh4iIiFSJQQ4RERGpEoMcIiIiUiUGOURERKRKDHKIiIhIlRjkEBER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Zw+qq6vx5ptvKtNCQkKapDtTHrGxsbjxxhtx/fXXu00PCAhQvi9duhTHjh1DZWUlysrKsGDBAtx4443YvXu313UmUgueySFSmd69e+OWW27BVVddhY0bN6KsrAwrVqzAgAED8L///U9J53A40NDQ4PZdvs8kPj4ehw8fxrZt21BYWIjHH38c33zzDVzf55udnY2pU6di//79CAoKQk1NDTQajfLE1uHDh/HXv/4Vn3zyCUwmE4xGI2pqamAwGJQ8nE4nGhoa4HQ63b4DQHp6OkaPHo3p06fjyJEjKCoqwvz585GSkqLcvBwfH4+vv/4aZWVlWLduHWbMmAEAbuWU8xVCNKlna+zfvx+33norvv/+e/j7+0Oj0aCurs6tHhEREaipqcGaNWtQXFyMd999F6NGjUJZWRmio6NRVVWFH374AXa7Ha+99hreeeedJmXo3bs3vv76a5SWlmLLli24+eabMX/+fADAbbfdhrfeegtHjhxBQEAASkpK8O677+Kee+5Rlv/Pf/6D2267DWVlZbBaraiqqnIrI9FZSRCR6jQ0NIg5c+aImJgYYbFYxMiRI8V///tfZX52drbQarUCgNvnhhtuUNI88cQTIigoSISHh4upU6eKW2+9VQAQixYtEkIIce2114oLL7xQxMbGCoPBIPr16yeWLFmiLL9y5UoxePBgMXjwYGEymURoaKi45ZZbRG1trRBCiPLycuHn59ekDEajURw/flwIIURZWZm49dZbRWRkpAgMDBSXX365yM7OVtaxd+9eMXToUGGxWMQ555wjFixYICwWi0hISBBCCJGfny9MJlOTdZx//vmtbss33nhDnHvuuSIlJUUYDAYRFRUlZs+eLZxOp1u6jz/+WERHRwuz2SxGjRolFi9erMxbsGCBCA8PF8HBwWLChAli9uzZAoB48sknlTSlpaViwoQJwmg0ipiYGHHbbbeJnJwcZf57770nUlNThclkEgkJCeKmm24S27ZtU+b36dNHjB8/XoSEhChl2Lp1a6vrSaRGkhBe/JeGiIiIqIfg5SoiIiJSJQY5REREpEoMcoiIiEiVGOQQERGRKjHIISIiIlVikENERESqxCCHiIiIVIlBDhEREakSgxwiIiJSJQY5REREpEoMcoiIiEiV/h8foDMcDhNy9gAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "result = QuantumUtil.measure_circuit(circuit, nr_measurements=20000)\n",
    "QuantumUtil.histogram_of_classical_states(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Testing\n",
    "Below, function *test_grover_circuit()* is defined to create a Grover circuit, execute it, and measure the results. \n",
    "A histogram of the results with valid input is plotted if parameter *plot_histogram* is True.\n",
    "\n",
    "From the resulting measurements a set with the $M$ most common occurrences of result strings is\n",
    "created, where $M$ is the number of possible solutions defined above.\n",
    "If $S$ is the required sum, then all result strings in the most common set should have input\n",
    "qubits representing $a$ and $b$ for which it holds $a + b = S$.\n",
    "\n",
    "The corresponding additions of the most common results are printed and the total number of violations is counted.\n",
    "Finally, the list of solutions found by Grover's search algorithm is printed. \n",
    "Note that this list is NOT corrected for any violations found during the test."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "import re\n",
    "\n",
    "def test_grover_circuit(required_sum:int, nr_measurements:int, plot_histogram:bool=False, nr_iterations:int=None):\n",
    "    \"\"\"\n",
    "    Tests a Grover circuit to find all possible combinations of two 3-bit input values for which it holds that the sum is equal to the required sum.\n",
    "    Input x = x0 x1 x2 will be the initial state of qubits q1, q4, q7 (least significant --> most significant)\n",
    "    Input y = y0 y1 y2 will be the initial state of qubits q2, q5, q8 (least significant --> most significant)\n",
    "    Output z = x + y = z0 z1 z2 z3 can be obtained by measuring the states of q2, q5, q8, q9 (least significant --> most significant)\n",
    "\n",
    "    Parameters:\n",
    "    required_sum (int)    : Required sum. Must be at least 0 and at most 14\n",
    "    nr_measurements (int) : Number of measurements after execution\n",
    "    plot_histogram (bool) : Plot histogram of result strings having valid input strings\n",
    "    nr_iterations (int)   : Number of times the Grover operator will repeated in the Grover circuit\n",
    "\n",
    "    Returns:\n",
    "    None\n",
    "    \"\"\"\n",
    "    # Determine number of possible inputs and possible solutions\n",
    "    nr_possible_inputs = 2**6\n",
    "    if required_sum <= 7:\n",
    "        nr_possible_solutions = required_sum + 1\n",
    "    else:\n",
    "        nr_possible_solutions = 15 - required_sum\n",
    "\n",
    "    # Determine optimal number of iterations\n",
    "    opt_nr_iterations = max(1, math.floor((math.pi / 4) * math.sqrt((nr_possible_inputs/nr_possible_solutions))))\n",
    "\n",
    "    if nr_iterations == None:\n",
    "        nr_iterations = opt_nr_iterations\n",
    "\n",
    "    # Print \n",
    "    print(f\"Required sum                 : {required_sum}\")\n",
    "    print(f\"Number of possible inputs    : {nr_possible_inputs}\")\n",
    "    print(f\"Number of possible solutions : {nr_possible_solutions}\")\n",
    "    print(f\"Optimal number of iterations : {opt_nr_iterations}\")\n",
    "    print(f\"Number of iterations         : {nr_iterations}\")\n",
    "    \n",
    "    # Create a Grover circuit\n",
    "    circuit = create_grover_circuit(required_sum, nr_iterations)\n",
    "\n",
    "    # Execute the Grover circuit and measure multiple times\n",
    "    result = QuantumUtil.measure_circuit(circuit, nr_measurements=nr_measurements)\n",
    "\n",
    "    # Plot a histogram of the results satisfying the pattern |0..0..0..0>\n",
    "    # where . can be either 0 or 1. These are all valid input strings.\n",
    "    if plot_histogram:\n",
    "        pattern = r\"\\|0..0..0..0>\"\n",
    "        valid_input = [s for s in result if re.fullmatch(pattern, s) ]\n",
    "        QuantumUtil.histogram_of_classical_states(valid_input)\n",
    "\n",
    "    # Count occurrences of each string in result\n",
    "    counter = Counter(result)\n",
    "\n",
    "    # Get the nr_possible_solutions most common strings as a list of tuples (string, count)\n",
    "    most_common_strings = counter.most_common(nr_possible_solutions)\n",
    "\n",
    "    # Get nr_possible_solutions most common strings only\n",
    "    most_common_strings_only = [item[0] for item in most_common_strings]\n",
    "\n",
    "    # Convert most_common_strings_only to a set for faster lookups\n",
    "    most_common_set = set(most_common_strings_only)\n",
    "\n",
    "    # All strings in most_common_strings should fulfil the requirement\n",
    "    indices_input_a = [1,4,7]\n",
    "    indices_input_b = [2,5,8]\n",
    "    nr_violations_common = 0\n",
    "    for string in most_common_strings_only:\n",
    "        binary_string_a = ''.join(string[i+1] for i in indices_input_a)\n",
    "        binary_string_b = ''.join(string[i+1] for i in indices_input_b)\n",
    "        a = convert_to_integer_lsb(binary_string_a)\n",
    "        b = convert_to_integer_lsb(binary_string_b)\n",
    "        print(f\"Result = {string}, a = {a}, b = {b}, and a + b = {a + b}\")\n",
    "        if a + b != required_sum:\n",
    "            nr_violations_common += 1\n",
    "\n",
    "    # Print the solutions\n",
    "    print(f\"Number of violations in set of most common strings is {nr_violations_common}\")\n",
    "    print(\"Solutions found (not corrected for violations):\")\n",
    "    print(sorted(most_common_set))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below, a Grover circuit is tested for required sum $S=7$. The number of possible combinations for which $a + b = 7$ is equal to $8$.\n",
    "A histogram of resulting strings representing valid inputs is plotted. When inspecting the histogram, it can be observed that $8$ \n",
    "result strings occur more frequently than the other result strings.\n",
    "These $8$ result strings represent the $8$ possible combinations of $a$ and $b$ for which holds $a + b = 7$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Required sum                 : 7\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 8\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n"
     ]
    },
    {
     "data": {
      "image/png": "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RESkBBZzTQ4RERGRMbHJISIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJDY5REREpEhscoiIiEiR2OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJDY5REREpEhscoiIiEiR2OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFMnO3BMgIiLle27M5iKXX5z1ainPhJ4lPJNDREREisQmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRI/HQVEZGFK+qTSfxUEtHj8UwOERERKRKbHCIiIlIkNjlERESkSGxyiIiISJHM1uTk5+dj0qRJCAgIgJeXFwYPHoy8vDxdfvfuXXTq1AkuLi5o27YtMjIyCu1jwYIF8Pb2RmhoKHbs2FGa0yciIiILZ7ZPV507dw4XLlzA9u3bYW9vj9atW6Ny5coYOnQoAGDq1KnQarW4cuUK4uPjMW7cOHzxxRe67U+ePInx48djz549OHv2LLp164bLly/D2dnZXIdEROAngYjIcpityalatSqWL1+u+7lr1644dOgQAECr1WLZsmVYu3YtvLy8MHr0aDRv3hyffPIJHB0dAQDLli1D586dERYWhrCwMEyePBkJCQno1q2bWY7HWvFL84iISKks4j45ubm5OHjwIDp37gwAuHLlClJTUxEREQEAqFOnDrKysnDmzBmEh4cDANRqNV577TXdPqKioqBWq9nkUCFs5IiInk1mv/B4+fLlqFChAmxtbTFkyBAAQFpaGpycnHRvPalUKpQtWxapqam67dLS0uDl5aX72dvbWy9/WE5ODjIzM/UeREREpFxmP5PTpk0b2NnZYdSoUZg+fTomTZoElUpVaD2tVqu3/OF1Hs4fNnPmTEyZMsV4E6dSx2s9iIjIEGZvcnx9fdGjRw/k5eVh0qRJmDRpEnx9fZGdnY2srCw4OztDRJCeng5fX1+97TQaje5njUajlz9s7NixGD58uO7nzMxMBAcHm+agiIiI/oX/k2YeZm9yCri4uOguKg4MDISfnx8SExPRpEkTHD9+HC4uLqhSpYpu/cjISCQmJup+VqvVGDduXLH7d3R01O2fiP7BF14i4+HzyfKYrcmZMmUKnJ2d0bt3b9y5cwczZszQXTRsY2ODuLg4zJkzB+Hh4fjwww8RGxur16TExcWhadOmGDFiBM6ePYuUlBR06NDBXIdDRESljB8qoMcx24XH7dq1w88//4yKFSuiadOmaN26NSZMmKDLJ02aBBFBQEAA0tPTMX36dL3tw8PDMXXqVDRu3BhDhgzBqlWr4OTkVNqHQURERBbKbGdyIiIisGvXrmLzMmXKYMOGDY/cR3x8POLj4408MyIiIlICi7kmh4jI2vHtE+Pj75SeBpscKhZfXMhS8G/RcpiiFtayT7I+bHKIiIjMiJ/KMh02OWQSfNISEZG5mf1rHYiIiIhMgWdyiKjU8AwfEZUmNjlERKSHF+2SUjx1k/Pjjz/CwcEB7du3N8Z8iIiMhv9Yk5Lx7/vxDG5yKlasiJs3byIlJQWzZs3C0qVLkZubi/79++ODDz4wxRypBPjHbnxK+Z3yLSIielYZ3OSUL18eAwcOhJubGzZu3IhNmzYB+OdrGtjkEJG1UEoTS0TFM7jJ+fvvv9GnTx8AwM2bNxEYGAhXV1fcvHnT2HMjIiKyKDwzal0MbnKcnJyg1Wqh1WqRmZkJb29v/Pbbb6hUqZIp5kdERPTMYlP1dAxucrp06YLOnTsjNDQUL730En7++Wf069cPzz33nAmm9+zh7c2JiEyLr4nPDoObnPnz5+O7775DdnY2evXqhQ0bNqB///7w8fExxfyIiIiInojBTY6dnR169+6t+7l79+5GndCzgP8XQURKxNc2sjRPdJ+cnJwcJCQkICUlBcOGDcO+ffvw/PPPw86O9xYkImXjP+RE1sPgriQlJQUtW7bE3bt3cevWLcTFxWH+/PmIjo7GoEGDTDFHIiIiKgVKa+INbnKGDh2KFi1a4LPPPkNQUBDy8/MRGxuL2bNns8khIiKrprR/5J91Bjc5u3btwunTp2Fra6tbFh0djTfffNOoEyN61vDFlYgsmTW+Rhnc5Li6uiIjIwPe3t66ZQ8ePOD1OERERBbCGhsSUzC4M2nfvj0GDx6M77//HiqVCsA/Hytv0aKF0SdHZI344kJEZBkMbnJmzpyJrl27wt/fH7m5uahbty4CAwOxceNGU8yPiIiI6IkY3OS4ubnh119/RVJSEs6dO4egoCBERUXBxsbGFPMjIiIieiJPfCFNvXr1UK9ePWPOhR6Db4MYH3+n1o81JDI/S30eGnz6pW3btqhfvz4GDhwIALh27Rq6dOmCO3fuGH1yRERERE/K4CbH3d0d2dnZuibH398f2dnZmDFjhtEnR0RERPSkDH676uDBg9i8eTPCwsJ0y2bNmoUOHTpg5syZRp0ckaWy1FOzRET0fwxucjQaDfz9/fWWBQcHQ6PRGG1SpGxFNQhsDoiIyNgMbnLq16+PlStX4t1339UtW716NerWrWvMeRERmQ3P1BEpg8FNzscff4zmzZvj4MGDCA8Px/Hjx7F582bs3LnTFPOjZwzP8jy72Fg8GT5niIpn8IXHkZGRSEpKgre3N/bu3QsfHx8kJSUhIiLCFPMjIiIieiJPdJ+cypUr49NPP9VbJiK6r3kgIiIiMrcnvhlgWloacnJyAABarRYvvvgirl69WuLtc3JyMHHiRCxevBh2dnYYMmQIxo0bp8vLly+Pmzdv6n5+77338Mknn+jtY8GCBZgwYQLc3d3x3//+16K+P0vpp96VfnxEREr1LL1+G9zk/PLLL+jTpw8AwNnZWbc8LS3NoP1Mnz4d27Ztw969e6HVatGyZUtUr14dnTt3BgDcvHkTubm5/zfRh77l/OTJkxg/fjz27NmDs2fPolu3brh8+bLenIiIiOjZZXCTM2jQIMydOxc9evTQW/76668btJ9XXnkFb731FkJCQgAA3bt3x6ZNm3RNDlC4sfm3ZcuWoXPnzggLC0NYWBgmT56MhIQEdOvWzaB5EJWmZ+n/oIiIzM3gC48zMzPxyiuvFFq+Zs0ag/bTsGFDXYMDAMnJyfDw8Cjx9mq1Wu9i56ioKKjV6mLXz8nJQWZmpt6DiIiIlMvgJuf1118v8iscunbt+sSTSExMxMaNG/H222/rLX/11VdRqVIldOzYEefPn9fL0tLS4OXlpfvZ29sbqampxY4xc+ZMeHh46B7BwcFPPF8iIiKyfAY3OVu2bMHHH38MLy8vVKxYERUrVkRoaCjWr1//RBPQaDTo0aMHRowYofdVEYMHD8bIkSOxZcsWuLu74+WXX9Zd6Ayg0Ce5tFrtIz/dNXbsWGRkZOgeycnJTzRfIiIisg4GX5Nz//59XLhwQW+ZVqtFw4YNDR48OzsbMTExqFy5MqZOnaqXzZ8/X/ffixYtgqenJ44ePaobx9fXV++rJDQaDXx9fYsdy9HREY6OjgbPkYiIiKyTwU1OampqkWdMHvVWUVHy8/PRvXt3ZGdnY8uWLbC1tS12XVtbW9ja2sLG5v9OPEVGRiIxMVH3s1qt1vsIOhERET3bDH67SqVSIScnB2vXrsW8efMAAPv27UNeXp5B+5k4cSL27t2Ljz76CBcvXsT27dvx/vvvAwCOHDmCJUuW4Nq1a7hx4waGDRuG4OBg1KtXT7d9XFwc1q9fj1OnTiEhIQEpKSno0KGDoYdDRERECmXwmZyUlBS0bNkSd+/exa1btxAXF4f58+cjOjoagwYNKvF+tmzZglu3bundwK/g/jsuLi5YsWIFhg4dCpVKhaZNm2Lz5s1wcHDQrRseHo6pU6eicePGcHd3x6pVq+Dk5GTo4RAREZFCGdzkDB06FC1atMBnn32GoKAg5OfnIzY2FrNnzzaoyUlKSio2q1GjBrZv3/7YfcTHxyM+Pr7EYxIREdGzw+AmZ9euXTh9+rTeNTTR0dF48803jToxIiIioqdh8DU5rq6uyMjI0Fv24MGDR96dmIiIiKi0GdzktG/fHoMHD0ZmZqbuU1bz58+3qC/HJCIiIjL49MvMmTPRtWtX+Pv7Izc3F3Xr1kVgYCA2btxoivkRERERPRGDmxw3Nzf8+uuvOHbsGM6ePYugoCBERUXp3cOGqLQV9cWX/NJLIqJnm8FNzu3bt+Hp6Ym6deuibt26JpgSERER0dMz+PRLdHQ0fvjhB1PMhYiIiMhoDG5yLl68iGbNmhVaHhcXZ4z5EBERERmFwU1O27ZtsXv3br1l+fn5WLlypdEmRURERPS0DL4m59NPP0W7du3g6+uLxo0bm2JORERERE/N4CYnNDQU2dnZaNq0qe4+OSJS5DeTExEREZmLwU1OdnY2tFqt3rK8vDy9L88kIiIiMjeDr8lZv359oWV2dna6bxAnIiIisgQGNzkxMTFFLl+8ePFTT4aIiIjIWAxuckaMGFHo01VERERElsbgJmfRokXw9vYutHzbtm1GmRARERGRMRjc5FSsWBF2dvrXK2u1Wrz88stGmxQRERHR0zK4yZk5cyYGDhyI7Oxs3TIRKfSJKyIiIiJzMvgj5AkJCbh06RKioqIQGRkJ4J8zObxPDhEREVkSg5ucr776Cv/9739hY/N/J4Hy8/OxfPlyo06MiIiI6GkY3OR07NgRb775pt4yEcGwYcOMNSciIiKip2bwNTnr1q0rtEylUiE1NdUoEyIiIiIyBoObnOJ8++23xtoVERER0VMz+O2q9957DxkZGXrLRATLli3DoEGDjDYxIiIioqdhcJPz6aefYvHixbpPU2k0GsybNw/vvfee0SdHRERE9KQMbnI6depU6Ms4mzRpwguPiYiIyKIYfE3Ojz/+WGhZpUqVcPz4caNMiIiIiMgYDD6Tk5iYiPv37+t+zsrKwpIlS1C3bl1jzouIiIjoqRjc5Dz//POIjo6GiAAAHBwcUL16dcyZM8fokyMiIiJ6UgY3OUOGDMHcuXNNMRciIiIiozH4mhw2OERERGQNDG5y2rZti/r162PgwIEAgGvXrqFLly64c+eOQfvJycnBqFGjUK5cOfj5+WHGjBl6+d27d9GpUye4uLigbdu2he7NAwALFiyAt7c3QkNDsWPHDkMPhYiIiBTM4CbH3d0d2dnZuibH398f2dnZhZqUx5k+fTq2bduGvXv3YseOHfjss8/0vjJi6tSp0Gq1uHLlCjw8PDBu3Di97U+ePInx48dj9+7dmDdvHrp164asrCxDD4eIiIgUyuAm5+DBg1i7di1q166tWzZr1iysWrXKoP288sorWL9+PapXr46aNWuie/fu2LRpEwBAq9Vi2bJlGDlyJLy8vDB69GisXLkSOTk5uu2XLVuGzp07IywsDDExMQgMDERCQoKhh0NEREQKZXCTo9Fo4O/vr7csODgYGo3GoP00bNgQISEhup+Tk5Ph4eEBALhy5QpSU1MREREBAKhTpw6ysrJw5swZ3fpqtVqXA0BUVBTUarWhh0NEREQKZXCTU79+faxcuVJv2erVq5/qPjmJiYnYuHEj3n77bQBAWloanJyc4OzsDOCfbzkvW7as3jedp6WlwcvLS/ezt7f3I78JPScnB5mZmXoPIiIiUi6DP0L+8ccfo3nz5jh48CDCw8Nx/PhxbN68GTt37nyiCWg0GvTo0QMjRoxAWFgYAOi+F+vftFqt3vKH13k4f9jMmTMxZcqUJ5ojERERWR+Dz+RERkYiKSkJ3t7e2Lt3L3x8fJCUlKT31lFJZWdnIyYmBpUrV8bUqVN1y319fZGdna27kFhEkJ6eDl9fX711/v0WmUaj0csfNnbsWGRkZOgeycnJBs+XiIiIrIfBZ3IAoHLlyvj000+fauD8/Hx0794d2dnZ2LJlC2xtbXVZYGAg/Pz8kJiYiCZNmuD48eNwcXFBlSpVdOtERkYiMTFR97NarS70Cax/c3R0hKOj41PNmYiIiKyHwWdyZs6cieHDh+Obb74BAKSnp+Ozzz4zeOCJEydi7969+Oijj3Dx4kVs374d77///j+TsrFBXFwc5syZg9u3b+PDDz9EbGysXpMSFxeH9evX49SpU0hISEBKSgo6dOhg8DyIiIhImQxucvbu3YtFixbB3t4ewD9nSL788kssXLjQoP1s2bIFt27dQosWLVCrVi20atUKly5d0uWTJk2CiCAgIADp6emYPn263vbh4eGYOnUqGjdujCFDhmDVqlVwcnIy9HCIiIhIoQx+u+rSpUtYuXIl2rVrBwBwdnbGp59+ilGjRqF///4l3k9SUtIj8zJlymDDhg2PXCc+Ph7x8fElHpOIiIieHQafybl48SKaNWumt6xhw4Y4e/asseZERERE9NQMbnIqVqyIvXv36i07dOgQQkNDjTYpIiIioqdl8NtVo0aNQp8+fTB9+nSEhYXhjz/+wOTJk/Hxxx+bYn5ERERET8TgJueNN96ASqXCRx99hHPnzqFSpUqYM2cOYmNjTTE/IiIioifyRPfJ6dmzJ3r27GnsuRAREREZzRM1ORcvXsSnn36qO5MzdOhQPPfcc0aeGhEREdGTM/jC42PHjqF27dq4du0aGjdujOvXr6NOnTo4fvy4KeZHRERE9EQMPpMzcuRITJo0Cf/5z390y+bNm4f//Oc/2Lp1q1EnR0RERPSkDD6Tc+TIEfTt21dvWa9evfS+R4qIiIjI3Axuctzd3XHr1i29Zbdu3YK7u7vRJkVERET0tAxuctq3b4/BgwcjIyMDAJCZmYmhQ4eiY8eOxp4bERER0RMzuMmZMWMGtFotAgICUL16dfj7+0Or1Rb6Ak0iIiIiczL4wmM3Nzf89ttvSEpK0n2EvF69eqaYGxEREdETe6L75ABAvXr12NwQERGRxTL47SoiIiIia8Amh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFMrjJ6datG3755RdTzIWIiIjIaAxucjZv3oxq1aoVWv7f//7XKBMiIiIiMgaDm5y6detCo9HoLcvPz0e/fv2MNikiIiKip2VwkzN37lwMHDgQN27c0FsuIkabFBEREdHTMvgLOidPnoyrV6+ibt26urettFotVCqV0SdHRERE9KQMbnJ++eUX7NixQ6+pycvLQ5s2bYw6MSIiIqKnYXCTM2zYMDRr1qzQ8pCQEGPMh4iIiMgoDL4m55NPPily+fnz5596MkRERETGUuIzOa+//jrmzJlT7AXGjo6O8PX1NdrEiIiIiJ5GiZucH374AYmJiXpNTsF1OZcvX4arqysyMjKMP0MiIiKiJ1Dit6tsbW1x/vx5XLhwQff4+uuv4evri+7du+PYsWMGD75q1Sp06dIFfn5+hbLy5ctDpVLpHsOHDy+0zoIFC+Dt7Y3Q0FDs2LHD4PGJiIhIuUp8Jufw4cO6/z506BDGjRsHZ2dnLFy4ELVr1zZ44Ly8PGzatAnVq1fHunXrCuU3b95Ebm7u/03UTn+qJ0+exPjx47Fnzx6cPXsW3bp1w+XLl+Hs7GzwXIiIiEh5Snwmp169ejh58iRiYmIwYsQIvP/++9i0aZOuwendu7dBA9vZ2WHFihV45513HrlOweNhy5YtQ+fOnREWFoaYmBgEBgYiISHBoDkQERGRcpW4yenXrx+ef/55VK5cGTNmzICIYPfu3di9ezd27NiBFStWmHKehajVakREROh+joqKglqtLnb9nJwcZGZm6j2IiIhIuUr8dtWiRYsQHR2No0eP4ujRo6ack86rr76Kv//+G7Vq1cInn3yCihUr6rK0tDR4eXnpfvb29kZycnKx+5o5cyamTJli0vkSERGR5Shxk9OmTRv88ssvxeYbNmwwyoQKDB48GJ07d0ZAQACmTZuGl19+GSdOnICjoyMAFPoaicd9tcTYsWP1Ll7OzMxEcHCwUedMRERElqPETc6jGhwAiImJeerJ/Nv8+fN1/71o0SJ4enri6NGjaNiwIQDA19dX79vQNRrNI+/T4+joqGuQiIiISPkMvuOxOdja2sLW1hY2Nv833cjISCQmJup+VqvViIqKMsf0iIiIyAKZtcnJycnB/fv3AQB3797VfWT8yJEjWLJkCa5du4YbN25g2LBhCA4ORr169XTbxsXFYf369Th16hQSEhKQkpKCDh06mOU4iIiIyPIY/AWdxnLjxg0EBQXhwYMHAAA3NzcEBgbiypUrcHFxwYoVKzB06FCoVCo0bdoUmzdvhoODg2778PBwTJ06FY0bN4a7uztWrVoFJycncx0OERERWRizNTnly5dHTk5OkVmNGjWwffv2x+4jPj4e8fHxxp4aERERKYBVXJNDREREZCg2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFYpNDREREisQmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFYpNDREREisQmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFYpNDREREisQmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFYpNDREREisQmh4iIiBTJrE3OqlWr0KVLF/j5+RXK7t69i06dOsHFxQVt27ZFRkZGoXUWLFgAb29vhIaGYseOHaUxZSIiIrISZmty8vLysGnTJlSvXh1paWmF8qlTp0Kr1eLKlSvw8PDAuHHj9PKTJ09i/Pjx2L17N+bNm4du3bohKyurtKZPREREFs5sTY6dnR1WrFiBd955p1Cm1WqxbNkyjBw5El5eXhg9ejRWrlyJnJwc3TrLli1D586dERYWhpiYGAQGBiIhIaE0D4GIiIgsmEVek3PlyhWkpqYiIiICAFCnTh1kZWXhzJkzunXUarUuB4CoqCio1epi95mTk4PMzEy9BxERESmXRTY5aWlpcHJygrOzMwBApVKhbNmySE1N1VvHy8tL97O3t7de/rCZM2fCw8ND9wgODjbdARAREZHZWWSTo1KpCi3TarV6yx9e5+H8YWPHjkVGRobukZycbLwJExERkcWxM/cEiuLr64vs7GxkZWXB2dkZIoL09HT4+vrqraPRaHQ/azQavfxhjo6OcHR0NOm8iYiIyHJY5JmcwMBA+Pn5ITExEQBw/PhxuLi4oEqVKrp1IiMjdTnwzzU6UVFRpT5XIiIiskxmbXJycnJw//59AP/cFyc3N/efSdnYIC4uDnPmzMHt27fx4YcfIjY2Vu9MTFxcHNavX49Tp04hISEBKSkp6NChg1mOg4iIiCyP2ZqcGzduwN3dHWFhYQAANzc3hIaG6vJJkyZBRBAQEID09HRMnz5db/vw8HBMnToVjRs3xpAhQ7Bq1So4OTmV6jEQERGR5TLbNTnly5fXu+/Nw8qUKYMNGzY8ch/x8fGIj4839tSIiIhIASzymhwiIiKip8Umh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFYpNDREREisQmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFYpNDREREisQmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFYpNDREREisQmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURERKRIbHKIiIhIkdjkEBERkSKxySEiIiJFstgmJyEhAba2tlCpVFCpVHBwcMCRI0d0+d27d9GpUye4uLigbdu2yMjIMONsiYiIyNJYbJOj0WjwxhtvIDc3F7m5ucjOzkZERIQunzp1KrRaLa5cuQIPDw+MGzfOjLMlIiIiS2OxTQ4AqFQq2NnZwc7ODjY2/zdVrVaLZcuWYeTIkfDy8sLo0aOxcuVK5OTkmHG2REREZEksuskpzpUrV5Camqo7s1OnTh1kZWXhzJkzxW6Tk5ODzMxMvQcREREpl8U2OSqVCvv27UNkZCRq1qyJSZMmITc3FwCQlpYGJycnODs769YtW7YsUlNTi93fzJkz4eHhoXsEBweXynEQERGReVhskxMWFoaePXtixYoVWLBgAVasWIFp06YB+KepeZhWqy1yeYGxY8ciIyND90hOTjbZ3ImIiMj87Mw9geJERkYiMjISAFC9enVMmTIF06ZNw5QpU+Dr64vs7GxkZWXB2dkZIoL09HT4+voWuz9HR0c4OjqW1vSJiIjIzCz2TM7DHB0ddRcfBwYGws/PD4mJiQCA48ePw8XFBVWqVDHnFImIiMiCWGyTs3jxYuzYsQN3797FsWPHMGXKFPTs2RMAYGNjg7i4OMyZMwe3b9/Ghx9+iNjYWJ6pISIiIh2LbXLy8/MxaNAgeHt7o0OHDnjttdcwZswYXT5p0iSICAICApCeno7p06ebcbZERERkaSz2mpx33nkH77zzTrF5mTJlsGHDhlKcEREREVkTiz2TQ0RERPQ02OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJDY5REREpEhscoiIiEiR2OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJDY5REREpEhscoiIiEiR2OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJDY5REREpEhscoiIiEiR2OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJKtvcvbt24cqVaqgbNmy+OSTT8w9HSIiIrIQduaewNPIy8tDt27d8NFHH6FBgwZo1KgRGjdujKioKHNPjYiIiMzMqs/kbN26FU5OToiNjUWVKlUQGxuLJUuWmHtaREREZAGs+kyOWq1GRESE7ueoqKhi37LKyclBTk6O7ueMjAwAQGZmpknmps25X+TyzMxMxWdA0cdvSVlBrvQMsIzfN+tk/XUqyJ/lDLCMWlhbnYytYJ8i8viVxYoNGjRIBgwYoPv5l19+kcDAwCLXnTx5sgDggw8++OCDDz4U8EhOTn5sn2DVZ3JUKpXez1qtttCyAmPHjsXw4cP11tVoNPD29i52G2PIzMxEcHAwkpOT4e7uzqwEmaXNhxnrZM2Zpc2H2bNbJ2MREdy5cwcBAQGPXdeqmxxfX1/8+eefup81Gg18fX2LXNfR0RGOjo56yzw9PU05PT3u7u7FFpxZ8U8ES5oPM9bJmjNLmw+zZ7dOxuDh4VGi9az6wuPIyEgkJibqflar1fxkFREREQGw8jM5rVu3RlZWFr7//ns0aNAAK1euxKZNm8w9LSIiIrIAVt3k2NnZYc2aNejTpw9u3ryJSZMmWdyZHEdHR0yePLnQW2XMis8sbT7MWCdrzixtPsye3TqZg0qkJJ/BIiIiIrIuVn1NDhEREVFx2OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJDY5REREpEhscoiIiEiR2OSUgry8PMyYMQNF3VzaFJk5xmTGOllzZmnzYcY6WXNWkrzUCJncl19+KTY2NrJkyZJSycwxJjPWyZozS5sPM9bJmrOS5KWFTY6J5ebmSmhoqHz22WdSuXJlyc/PN2lmjjGZsU7WnFnafJixTtaclSQvTWxyTGzx4sXyyiuviIhIq1atZNmyZSbNzDEmM9bJmjNLmw8z1smas5LkpYlNjgnl5+dLtWrVZO/evSIismvXLqlWrZpotVqTZOYYkxnrZM0Za2EdGetkHdnj6mQOdua9IkjZ1qxZAz8/PzRq1AgAEB0dDR8fH6xatQoqlcroWY8ePUp9TGaskzVnrIV1ZKyTdWSPq1OPHj1Q6szSWj0jateuLdu2bdNb9uuvv0rt2rVNkpljTGaskzVnIqyFNWQirJM1ZCKPrpM58EyOCU2bNg0tW7bUW9amTRvk5OQAgEkyc4zJzPCMdbKcjLWwjox1so7scXUqbSoRc3+InYiIiMj4eCbHRHJycpCQkAC1Wo3U1FSoVCr4+voiKioKL730En755RejZh06dICIlOqYzFgna85YC+vIWCfryB5Xpw4dOsDBwaHU/y3mmRwT2LlzJ7p164agoCA0aNAA3t7e0Gq10Gg02LFjB86fP4/KlSujefPmRsnUajUuXrwIAAgNDS2VMZmxTtacsRbWkbFO1pE9rk5qtRpXr17F6tWr0axZs1L995gXHptAxYoVZcOGDcVm48aNk9DQUKNlIiJ+fn7i4+NTamMyY52sORNhLawhE2GdrCETeXSdREQ2bNhQ7LamxO+uMoGMjAxUrVq12OzFF19ERkaG0TIAyM7OLvbCLlOMyYx1suYMYC2sIQNYJ2vIgEfXCQCqVKlS7LamxGtyTGDq1Klo1KgRunTpgoiICHh5eQEANBoNqlWrhvbt2+PFF1/EwoULjZKp1Wrk5uYCAPr161cqYzJjnaw5Yy2sI2OdrCN7XJ3UajV++uknTJs2DaWN1+SYyMmTJ7F8+XKo1WqkpaXpLsCKjIxEw4YNceDAAaNmcXFxAFCqYzJjnaw5Yy2sI2OdrCN7XJ3i4uIQFhZW6v8Ws8khIiIiReI1OURERKRIvCbHhHJzc3HmzBm9+wVUqVIF9vb2j9zu119/RXBwsMHbbd++HU2bNi3VMbmdcbezprkqfTtrmqvSt+Nrm/VvB/xTx4fvhmxypf55rmdAZmamxMfHS9myZcXJyUn8/f3F19dXHB0dxcvLSwYPHiwZGRlFbte/f38BYNB2IiLXr18XAKU2Jrczfg2tZa5K386a5qr07UT42mbt2xXIysoSGxubYnNT4TU5JtCuXTu4u7tj9OjRqFOnjl728ccf48cff0RWVhaGDx+ul33yySdwcHBAYmIitFptibcryE+cOIFjx46VypjczvDtjh07hsGDB+POnTtF1tCS5qr07VgL69iuIOdrm2Vv97jnE/DPR8wHDhyI/Pz8InNTYZNjAq6urkhJSYGnp2ehrHLlyrC3t8f//vc/NG3aVC/bvXs3nn/+eRw6dKjQH8KjtivYVkQK/fGZakxuZ/h2AFCxYkVcvHgR0dHRhTJLmqvStwNYC2vYrmBbvrZZ9nbAo59PAJCfn499+/aVepPDa3JMoE2bNnjzzTcxatQo1K9fH46OjgD++T6ryMhIHD16FO3bt8dPP/2kt12nTp2Ql5cHrVaLnJycEm8HAO3bt8emTZtw4MCBUhmT2xm+XWJiImxsbFCpUiXs3LmzUA0taa5K3461sI7tAL62WcN2j3s+AcC9e/fg5uZWZGZSpf4G2TPg7t27MmrUKPH39xcbGxtxcXERFxcXsbGxkfLly0urVq3k7t27RW43cuRIcXJyMmg7EZE7d+5I1apVS21Mbmf4dgEBAdK3b1+ZM2dOkTW0pLkqfTvWwjq2E+FrmzVs97jnk4iIVquVzp07F5ubCt+uMiERwZUrV/RuihQYGAiVSmWS7cwxJrcz7nbWNFelb2dNc1X6dtY0V25nWdjkEBERkSLxZoBERESkSLzw2EQSExOxZMkSqNVqvZsmRUVFISoqCocOHSoy69OnDyIjI4vcZ15eHipWrIjLly8XmQUFBaFLly6lNubBgwfRunVr1KhRg+MZYbxn4Rgtabw+ffoAQLHPUyUcoxLG42ub9Y9XktxU+HaVCcydOxezZs1CbGwsoqKi4O3tDa1WC41Gg4ULF2LPnj1o2rQp+vfvr5ep1WqsXLkS48aNw9ChQwvtt+Dq9KI+Svnhhx9izJgxGDZsWKmMOXfuXMycORM3btzAypUrOZ4Raqj0Y7Sk8dRqNRYtWgQAePvttws9Z5RwjEoYD+Brm7WPV9LcZEx5VfOzysvLS86ePVtstm3bNilbtmyhzM/PT2xsbASA2NjY6D0A6B4PZwW5SqUqtTH/vZzjlWy8h/erxGO0lvFERDw9PcXd3b3ITAnHqITx+NpmHeM97rXNxsZGVCpVsc9FU+LbVSbg7e2NxMREVKpUqcgsISEB3t7ehbJGjRpBq9Xi6NGj+P333/WygQMHokKFCvj6669x/vz5QttGR0cXexrQFGM2b94c8fHxGDVqFMcr4XgA8M4772Dr1q1F1lAJx2gt4wGAk5MTpJgT2Uo4RiWMB/C1zRrGAx792gb8cyanVq1aRWamxLerTGDfvn3o3r07nJ2dERERAS8vLwCARqPB7t27kZaWhoCAADRq1Egv27lzJzIzM7Ft2za8+OKLevtcvXo1Nm7ciB9++AHZ2dmFxty1axeaN2+OKlWqlMqYBceYkpKCbt26cbwSjAcA3333HXr16lXkXT+VcIzWMp5arUZGRgZsbGzg4eFR6DmjhGNUwngAX9usYTzg0a9tAPDgwQO4u7sXWWNTYpNjIvn5+di6dSvUarXe/QQiIyPRokUL7Nixo9jMwcGh2H3evn0b5cqVKzJPS0tDUlJSqY2Zn5+PH374Af/73/84XgnHK6iTr69vsfOx9mO0lvFat24NAI98nlr7MSphPICvbdYwXkGdinttA4CbN28WW2NTYZNDREREisT75BAREZEi8cJjE1Kr1UXeayAyMtIkmTnGZMY6WXPGWlhHxjpZR/a4OpkD364ygRMnTiA2NhZXr15FZGSk3r0GDh8+jOzsbDg5OeH55583Snb06FF4eXlBRKDRaEplTGaskzVnrIV1ZKyTdWSPq9PRo0cREBCAlStXIjw8vFT/PWaTYwK1atVC//79ER8fD5VKVSirXr06Tp06hZMnTxolExEEBgZCRHD16tVSGZMZ62TNGWthHRnrZB3Z4+okIvjiiy/w1Vdf4c8//0SpKqX78TxT3N3dJSUlpdhMrVaLm5ub0TIRETc3N3F1dS21MZmxTtacibAW1pCJsE7WkIk8uk4iIsnJycVua0q8JscEhg4diiZNmuCtt94qdF+H+vXro2HDhmjSpAl+/fVXo2SJiYmwtbWFnZ0dZsyYUSpjMmOdrDljLawjY52sI3tcnRITE7F48WIMGzYMpY1vV5nIli1bsHTpUqjVhe81ULNmTZw6dcqoWe/evQGgVMdkxjpZc8ZaWEfGOllH9rg69e7dG6+88kqp/1vMJoeIiIgUiffJISIiIkVik2Ni9+/fx/nz53HhwgXcv3/f5NmjnDlzxiSZpRyjNR1fSXJjH8ejsme5ho+bqxKOUQnH9zRztZZjVPLxlSQ3iVK/1PkZkJeXJx9//LHUqFFD9xXzqv//NfM1a9aU9u3bGzULCwuTOXPmSG5ubrFzys7OFnt7e6NleXl5MmvWLAFgEcdoDccXFhYms2fPlo8++kixx2gtNXxcLZRwjEqooYjIvXv3xMbGxmJeT1lDw7OS5KbCT1eZQN++fXHp0iXMnDkTUVFRejdF6tmzJ3bv3o169eph+/btRskOHz6MadOm4bfffsO4ceMKzef06dNIT09HXl4edu/ebZRsxowZuvshXLlyxeTH+P3332P58uVFHqO1HN/hw4cxYMAAAMDChQsL/W0o4RitpYaPq4USjlEJNQSADz74AFqtttReT1nDJ6vT8ePHi82Af84oFfcN5abEC49NoEyZMkhOTkbZsmWLzP744w/UqlUL9+7dM0oGAAEBAbh27Rqee+65QllycjJEBFqttlD+pNmlS5cQGBiIq1evFvrDNcUxBgUF4cGDB7h58yZCQkKs8vgKcq1WW+RpYyUco7XUsGCuxdVCCceohBoWHCMAaLXaQpkSjlEJNSzI8/Pzi8yAf24IWLBOaWKTYwLNmjVD7dq1MXbsWPj7++tlL774Iu7duwdnZ2ccPHjQKNnVq1fRpk0b3L17FxcvXiw0nwEDBsDb2xuzZs0q9Af2pFmzZs1Qo0YNLFy4sNCLjymOMS4uDv/73//g5OSE33//3SqP7+rVq2jQoAEAIDExsdDfhhKO0Vpq+LhaKOEYlVBDAGjSpAn27t2Lq1evlsrrKWv4ZHV66623sGTJkiKbUQC4e/cuPDw8Sr3J4dtVJrB69WoMGTIEoaGhKFu2rN5NkW7fvg0fHx+cPn0a/v7+RsnS09PRqFEj1KlTp8j59OnTB5s3b0bdunWNlq1evRqDBw8GAKMdx6MyjUaDKlWqYMOGDVZ7fOnp6XjppZcgIkX+bSjhGK2lho+rhRKOUQk1LDjGsLCwUns9ZQ2frE59+/bFzz//XGQGAM7OzsVua0o8k2NCGRkZ+OOPP/RuilSrVi14eHiYJOMxWsfxPW6/SjhGazk+Ux2/JR2jEo7vWThGpR+fubDJISIiIkXifXKIiIhIkXhNjolcvXoV3333HdRqNVJTU3WnCqOiotCyZUts27bNqFnPnj0hIqU+5sMXAhbQarVo1qxZkR8ntJbsypUraNq0KSIjI626Tqxh0TW0tFqwhsVnDRs2RNeuXS3i980aGp6VJDcVvl1lAqtWrcKAAQPQvHnzQvd1WL9+PRITE9GgQQN06tTJKJlarcZvv/0GAGjTpk2pjblr1y589dVX6NatW6Hfwf379+Hm5lbklfTWkBXUMCMjAzNmzLDaOrGGRdfQ0mrBGhafLV26FH369EHHjh2ttk7Peg1LkpuMCW80+Mzy9/eXw4cPF5stWbJE/Pz8jJaJiJQrV068vb1LbcyIiAgJCAgQW1tbCQ0N1Xs4ODiInZ2dALDazNbWVvz8/MTGxsaq68QaFl1DS6sFa1h0VlBHlUpl1XVSeg0L8uKy0NBQCQkJKfa5aEp8u8oEbGxskJOTU2x279492NgUvhzqSTMAUKlUkGJOypliTF9fXzz33HPYtWsXlixZopeNGTMGPj4+2Lhxo9VmXbt2xYgRIzB69GiDfi+WVifWsOgaApZVC9aw6AwAunTpAo1GU2j543431pIpoYYAMHLkSKjV6iIz4J8zOe3atSsyMyW+XWUC69evx5tvvomoqChERETo3aNg8+bNOHHiBOrUqYNXXnnFKJlarcaBAwcAAI0aNSqVMX/66SecO3cOa9asQceOHfWOf9GiRdi5cydWr16NvLw8q8wKapiRkYExY8ZYbZ1Yw6JraGm1YA2LzgBgzZo16NatG1q3bm21dVJ6DQFgwYIFiI+PL/ZmgDk5OXB1dS1yW1Nik2MiGo0Ga9asgVqt1rtHQWRkJFq1aqW7AM1Y2WuvvQaVSlVqY9avXx8tW7ZEtWrVCh27VqvFrVu3kJKSUujmT9aSFdRwzpw5SE1Ntdo6sYbF19CSasEaFl9DAPj999/x119/mf33zRoWXyetVotdu3ahRYsWRdYQAI4dO1bqNwRkk0NERESKxPvkEBERkSLxwmMTSk1NxdGjR/XuiRAREQFfX1+TZOYYkxnrZM0Za2EdGetkHdnj6mQObHJMICUlBf3798dvv/2G0NBQvXsiXLp0CZ6enrh9+7bRssuXL6Nx48YAgN27d5fKmMxYJ2vOWAvryFgn68geV6fLly+jdevW+OqrrxAYGFiq/x7zmhwTaNSoERo1aoRx48bB09NTL3v++ed1H1s9fPiwUTKNRoNatWoBAE6ePFkqYzJjnaw5Yy2sI2OdrCN7XJ00Gg1mzZqFvXv3Yv/+/ShVT3WXHSqSq6ur3Lx5s9js9OnT4uLiYrRMRMTFxUWcnZ1LbUxmrJM1ZyKshTVkIqyTNWQij66TiMiNGzeK3daU+HaVCcTGxqJdu3YYPHhwofs6FNw7JyoqCqdPnzZKlpiYiDJlygAAVq5cWSpjMmOdrDljLawjY52sI3tcnRITE/H5558jNjYWpY1vV5mAVqvFwoULsXTpUhw9elT3XR22traoX78+QkNDcf78eSQlJRkli4iIwBtvvAEAWL58eamMyYx1suaMtbCOjHWyjuxxdYqIiECvXr3Qr18/2NraojSxySkFN2/ehEqlgre3d6lk5hiTGetkzZmlzYcZ62TNWUny0sImh4iIiBSJNwMsBfn5+cV+n4cpMnOMqfSsKPfu3TN6Zqr9MuNzRglZcSzx742Z4bkp8EyOifz4449YvHgx1Go1NJp/vkHXy8sLUVFRqFGjBk6dOmXUrG/fvhCRUh1T6Vnfvn3RuXPnIuubm5sLT0/PIp+0T5qZar/PcrZ69WrExsbC29ubzxkrzR71PDTV3w2z0n1tMyV+usoERo0ahY0bN2LAgAGYMGGC3k2RJk6ciPnz56Nx48bYsGGDUTK1Wo133nkHADBp0qRSGVPp2c6dOzFq1Cj89ttvGDdunF59b926BY1Gg6ysLFy+fLnEGQAkJycXmz3pfpkVnc2YMQNbt26FiPA5Y6WZWq3G6NGji3weWtrf27OcAY9+bQP+OYuTnZ1dZGZSpf6h9WeAm5ubXLt2rdjs2LFjUqZMGaNlIiJlypQp9h4EphhT6ZmPj4/Y2NgIAFGpVHoPALqHIdm/80dlxhyTGcTGxqZQfUX4nLGGTESkXLlyfM5YePa417aCR3HPRVNik2MC9erVk48++khyc3MLZXXr1pW2bdtK7dq1jZbl5uZKQECA+Pv7l9qYSs969uwpbdu2lTp16hTK4uLi5IMPPijyCfuoTESkR48eolKpisyedL/Mis7q1asnU6dOLfL3zeeMdWS5ublSv3598ff3L5SJWNbf27OciTz6tU1E5M6dO2Zpcvh2lQmsWrUKvXr1wpQpU1CrVi29myKdPn0aZ86cgYigYcOGRslOnDiBSpUqAQA8PT1LZUylZ0lJSfD09MSuXbsK1bdnz57YsGEDypYta1AGAG+88QbWrVtXZPak+2VWdLZq1SrExcXxOWPF2YkTJxAUFITmzZsXqq+p/m6YGf+1DQCcnJyK3daUeOGxCf39999Qq9VIS0vTfRtrZGQkqlevbpLMHGMqPSPrx+eM9WdET4pNDhERESkS75NDREREisRrckwkJycHCQkJUKvVSE1N1Z1+jYqKwksvvYRffvnFqFmHDh0gIqU6JjPWydKzDh06wMHBocjnqIigd+/eWLZsmcE5M8vILG0+zJ6sTqbEt6tMYOfOnejWrRuCgoLQoEEDvfs+7NixA+fPn0flypXRvHlzo2RqtRoXL14EAISGhpbKmMxYJ0vP1Go1rl69itWrV6NZs2aFnqf379+Hm5ub7osEDcmZWUZmafNh9mR1MiU2OSZQqVIlzJ07Fx06dCgy6969O77//nucP3/eKBkA+Pv7Q6vVIi0trVTGZMY6WXrWqVMnnDt3DmfOnEHDhg3xsD/++AO3bt0q8pM7J06cQG5uLjIyMgrlzEovA1gna8iAR9cJAPLy8rBv375Sb3L4dpUJZGRkoGrVqsVmL774Ir766iujZQCQnZ2N4vpVU4zJjHWy9Cw9PR2VKlXC+fPn0bt370L5jBkzcOvWrSKzWbNmwdPTE4cOHSqUMyu9DGCdrCEDHl0n4J/Xvn379hWZmRKbHBOYOnUqGjVqhC5duiAiIkLvvg/VqlVD+/bt8eKLL2LhwoVGydRqNXJzcwEA/fr1K5UxmbFOlp5lZWXhwIEDmDt3bpEvvNevX8eoUaOKzG7fvo2jR48W+YLOrPQygHWyhgx4dJ0AICsrCwMHDiwyMyW+XWUiJ0+exPLly4u870PDhg1x4MABo2ZxcXEAUKpjMmOdLDmrU6cOoqOji3zbGPjnRXfx4sWIj48vMrt48SLOnDlTaHtmpZcV5KyTZWcFeXF1KpCQkFDs89FU2OQQERGRIvE+OURERKRIvCbHhHJzc3HmzBm9e3dUqVIF9vb2JsnMMSYz1smaM9bCOjLWyTqyx9XJHNjkmMCdO3cwduxYrFy5EllZWShbtiy0Wi3S09Ph4uKCoKAgJCcnIzs72yiZq6srXnvtNWi1Wvzwww+lMiYz1smaM9bCOjLWyTqyx9XJ1dUVPXv2xLRp0+Du7l66/yA/0XeX0yO9+uqr0qNHDzl27FihrEmTJhISEiJNmjQxWpaUlCQBAQESEBBQamMyY52sOWMtrCNjnawje1ydkpKSpEePHvLqq68WykyNTY4JuLi4yO3bt4vNLl68KC4uLkbLCnJnZ+dSG5MZ62TNWUHOWlh2VpCzTpadFeTF1UlE5Pbt28Vua0psckygY8eO0rFjR9m/f79kZ2frlmdnZ0uTJk3E399fmjRpYrRs79694u/vL35+fqU2JjPWyZoz1sI6MtbJOrLH1Wnv3r3SqVMniYmJkdLGa3JMYMWKFfjggw/QpUsXpKWlwcnJCcA/d3z08fFBhQoVcObMGbi4uBgl8/PzQ7du3aBSqUptTGaskzVnrIV1ZKyTdWSPq5Ofnx/eeOMNTJo0CaWN98kxIRHBlStX9G5QFhgYCJVKZZLMHGMyY52sOWMtrCNjnawje1ydzIFNDhERESkSbwZIREREisQmh4iIiBSJFx4b0YYNG7Bhw4Yis0uXLiE5ObnI7O7du7h37x58fX0NygryMmXKPFH2JGMyY52sOSvIWQvLzgpy1smys4K8uFoAQOPGjYvNAGDx4sWPzJ8Wmxwjqlu3Ljw9PYvMUlNTkZqaWmSm0Wig0WhQuXJlg7KC3MvL64myJxmTGetkzVlBzlpYdlaQs06WnRXkxdUC+OffRXPihcdERESkSLwmh4iIiBSJTQ4REREpEpscIiIiUiQ2OURkdlu2bMG+ffvMPQ0iUhg2OUTPqJCQEKhUKtja2uLatWtmncsnn3yCb7/91iT7btq0KVQqFVQqFQ4dOmSSMYjIMrHJIVKouXPnolKlSnBwcEBoaChq1KiB7du36/JLly4hNzcXwcHByMnJMeNMgXHjxmHAgAEm2ffu3buRl5eHpk2bIisryyRjXL9+HS+88MJT7WPYsGFISEgw0oyICOB9cogUafz48Vi3bh2WL1+O8PBwrF+/Hm+++Sbu3Lmjt56dnWW8BDRv3tyk+7e1tTXpFwTev3+/2PtglVR6ejo0Go2RZkREAM/kECnO5cuXMXv2bPz444948cUX4e7ujt69eyMmJgbu7u4l3s/PP/+M2rVrw9nZGeXLl8f06dP18itXrqBt27bw8PBA+fLl8cILL+C1117TW2fy5MkIDAyEq6sr6tWrh5CQEFy/fl2Xb9u2DTY2NlCpVPjwww8LzSEzMxMDBw5EYGAgPDw88NJLLyEsLAwXLlwAADx48ACxsbHw8fGBk5MTGjZsiLNnzxry63qs3NxcDBo0CD4+PnBzc0NUVBRCQ0NRcIux3r17IyoqCsnJyfDz84Ofnx9CQkJw48YN3T4OHz6M559/Hq6urihbtizeffdd3fZJSUkICgrC6tWrMXToUN0+Jk6cqDePrVu34oUXXoCbmxuqV6+Ob775Ri///fffERERARcXF4SEhKBevXqYN2+eUX8XRNaGTQ6Rwvz666+oWbMmatasqbd8/fr1aNGiRYn34+XlhWnTpuHixYs4dOgQvv32W/z555+6fMKECQgNDUVycjL279+PqlWr4vbt27p8165dWLFiBXbv3o3k5GTEx8dDo9HgwYMHunVatWqF3NxcTJw4sci3krp27YoLFy5g586dOH/+PCpXroxTp04hIyMDAGBjY4PmzZvjt99+w40bN9CpUyeMGTOmxMdYEt999x2SkpJw7NgxnD17Fl26dMH169d1TcqCBQuwefNmBAQE4NixYzh27BiSkpJQvnx53T7KlCmDESNG4PTp0zh16hSSkpKwefNmAEC9evVw9OhRdOjQAR988IFuH/9ucvbu3YuYmBgMGTIEycnJ+OqrrzBx4kT897//1a3Tu3dvDB8+HNevX8eqVavg4OCAu3fvGvV3QWRtLONcNREZzfXr1+Hn5/fU+8nPz8fChQvx3nvvwcnJCffv38eJEycQHh4OAMjOzkZUVBTc3d3h7u6OZcuW6ZqPgjwgIABBQUFwdHTE22+/jddeew0eHh5649ja2sLGpvD/bx09ehR79+7F1atXdV+XMn/+fFy/fl3XQOTm5uLSpUv48ssvcfv2bZQrV67QW3JPKzs7G6GhofD19YWtrS1Gjx6NAQMG6Obs4uKC8uXLw9bWttjfu4hg7dq1mDBhAlQqFXJzc3HixAm0a9cOAODj4wNnZ2d4eHgUuY/Zs2dj6NChiI2NBQA0a9YM77//Pj7++GO89dZbunnWq1cPZcqUQcOGDbFnzx7k5+cb9XdBZG14JodIYcqVK/fU14ekpKTg5ZdfRlRUFLZs2YK1a9eiSpUqehcov//++1i0aBHc3NwQFBSEF154ARs3btTlrVu3Rs2aNeHt7Q0fHx/UrFkTY8aMwf3790s0h3PnziEoKEjv++BsbW2xdu1aBAYGAgDGjh2LhIQEfPzxx/j9998xfPhwo19E3atXL2RnZ8Pd3R1+fn6oVasWPvzwQ2i12hJtn5WVhdatW6N8+fJYv349Nm3ahKioKIPmefbsWXz11Ve6t7L8/Pwwfvx4pKSk6NZZsGABXnrpJZQtWxahoaFo3749Tpw4YfDxEikJz+QQKUzLli0RHx+Pv/76CzVq1NAtz8nJgZ2dHWxtbR+7j4MHD6Jy5cqYPHmybpmLi4veOosXL8aGDRtQvnx5aDQaqNVqdOrUCa1bt4avry/27duHunXrYsGCBbh16xauX7+Onj174osvvsDIkSMfO4dKlSohOTkZ6enpeo3O1atX4e/vD5VKhe3bt2PatGlo2bIlACAtLe2x+zXUhg0b0KdPH6xZswa3bt1CSkoK2rdvj3r16umuQbK1tcW9e/eK3P7UqVPIysrCl19+qVtW1BcaPmofQUFBePPNN/HGG2/oLXdzc9P999q1a3Hp0iXcvXsXGRkZWLBgAd58802cPHnS4GMmUgqeySFSmMqVK6Nfv37o2rUrDh48iIyMDCQkJCAsLAy//fabbr38/Hzk5eXp/XfBdSYVKlTA+fPncezYMVy/fh0TJkzAli1b8O/v8z18+DC6deuG06dPw9PTE9nZ2bCxsdF9Yuv8+fMYNWoUVq9eDScnJzg6OiI7OxsODg66fWi1WuTl5UGr1er9NwDUr18fTZo0QVxcHC5cuIAbN25g1qxZqF69uu7i5QoVKuDnn39GRkYG9uzZg969ewOA3jwL9isihY6zJE6fPo3+/ftj69atKFOmDGxsbPDgwQO94/D19UV2djZ27dqFW7duYdGiRWjUqBEyMjIQEBCA+/fvY9u2bdBoNJg/fz6++eabQnOoXLkyfv75Z6Snp+PIkSN4++23MWvWLADAgAEDsHDhQly4cAFubm64ffs2Fi1ahKFDh+q2//777zFgwABkZGTA3d0d9+/f15sj0TNJiEhx8vLyZNKkSRIYGCguLi7SsGFD+emnn3T54cOHxdbWVgDoPXr16qVbZ+LEieLp6Sk+Pj7SrVs36d+/vwCQJUuWiIhIjx49pFWrVhIUFCQODg5SrVo1WbVqlW77zZs3S506daROnTri5OQk5cqVk379+klOTo6IiGRmZoqrq2uhOTg6OsrVq1dFRCQjI0P69+8vfn5+4uHhIe3atZPDhw/rxvjrr78kIiJCXFxcpFatWrJgwQJxcXGRkJAQERFJSUkRJyenQmM0bdq0xL/LL774Qp5//nmpXr26ODg4iL+/v4wbN060Wq3eeitXrpSAgABxdnaWRo0aybJly3TZggULxMfHR8qWLStt27aVcePGCQCZPHmybp309HRp27atODo6SmBgoAwYMEAuX76sy7/99lupWbOmODk5SUhIiPTt21eOHTumy6tUqSItW7YULy8v3RySkpJKfJxESqQSMeB/aYiIiIisBN+uIiIiIkVik0NERESKxCaHiIiIFIlNDhERESkSmxwiIiJSJDY5REREpEhscoiIiEiR2OQQERGRIrHJISIiIkVik0NERESKxCaHiIiIFOn/AShB58J75R9ZAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result = |0010100100>, a = 6, b = 1, and a + b = 7\n",
      "Result = |0010010100>, a = 4, b = 3, and a + b = 7\n",
      "Result = |0010010010>, a = 0, b = 7, and a + b = 7\n",
      "Result = |0100100010>, a = 3, b = 4, and a + b = 7\n",
      "Result = |0100100100>, a = 7, b = 0, and a + b = 7\n",
      "Result = |0100010010>, a = 1, b = 6, and a + b = 7\n",
      "Result = |0010100010>, a = 2, b = 5, and a + b = 7\n",
      "Result = |0100010100>, a = 5, b = 2, and a + b = 7\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010010010>', '|0010010100>', '|0010100010>', '|0010100100>', '|0100010010>', '|0100010100>', '|0100100010>', '|0100100100>']\n"
     ]
    }
   ],
   "source": [
    "test_grover_circuit(required_sum=7, nr_measurements=20000, nr_iterations=2, plot_histogram=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Uncomment the code below to test the Grover circuit for all $S$, $0 \\leq S \\leq 14$.\n",
    "Note that running this test may take some time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Required sum                 : 0\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 1\n",
      "Optimal number of iterations : 6\n",
      "Number of iterations         : 6\n",
      "Result = |0000000000>, a = 0, b = 0, and a + b = 0\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0000000000>']\n",
      "Required sum                 : 1\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 2\n",
      "Optimal number of iterations : 4\n",
      "Number of iterations         : 4\n",
      "Result = |0010000000>, a = 0, b = 1, and a + b = 1\n",
      "Result = |0100000000>, a = 1, b = 0, and a + b = 1\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010000000>', '|0100000000>']\n",
      "Required sum                 : 2\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 3\n",
      "Optimal number of iterations : 3\n",
      "Number of iterations         : 3\n",
      "Result = |0000010000>, a = 0, b = 2, and a + b = 2\n",
      "Result = |0110000000>, a = 1, b = 1, and a + b = 2\n",
      "Result = |0000100000>, a = 2, b = 0, and a + b = 2\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0000010000>', '|0000100000>', '|0110000000>']\n",
      "Required sum                 : 3\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 4\n",
      "Optimal number of iterations : 3\n",
      "Number of iterations         : 3\n",
      "Result = |0010010000>, a = 0, b = 3, and a + b = 3\n",
      "Result = |0100100000>, a = 3, b = 0, and a + b = 3\n",
      "Result = |0010100000>, a = 2, b = 1, and a + b = 3\n",
      "Result = |0100010000>, a = 1, b = 2, and a + b = 3\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010010000>', '|0010100000>', '|0100010000>', '|0100100000>']\n",
      "Required sum                 : 4\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 5\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n",
      "Result = |0110100000>, a = 3, b = 1, and a + b = 4\n",
      "Result = |0110010000>, a = 1, b = 3, and a + b = 4\n",
      "Result = |0000000010>, a = 0, b = 4, and a + b = 4\n",
      "Result = |0000000100>, a = 4, b = 0, and a + b = 4\n",
      "Result = |0000110000>, a = 2, b = 2, and a + b = 4\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0000000010>', '|0000000100>', '|0000110000>', '|0110010000>', '|0110100000>']\n",
      "Required sum                 : 5\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 6\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n",
      "Result = |0100000100>, a = 5, b = 0, and a + b = 5\n",
      "Result = |0010000010>, a = 0, b = 5, and a + b = 5\n",
      "Result = |0010110000>, a = 2, b = 3, and a + b = 5\n",
      "Result = |0100110000>, a = 3, b = 2, and a + b = 5\n",
      "Result = |0010000100>, a = 4, b = 1, and a + b = 5\n",
      "Result = |0100000010>, a = 1, b = 4, and a + b = 5\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010000010>', '|0010000100>', '|0010110000>', '|0100000010>', '|0100000100>', '|0100110000>']\n",
      "Required sum                 : 6\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 7\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n",
      "Result = |0000010100>, a = 4, b = 2, and a + b = 6\n",
      "Result = |0110110000>, a = 3, b = 3, and a + b = 6\n",
      "Result = |0000100100>, a = 6, b = 0, and a + b = 6\n",
      "Result = |0000010010>, a = 0, b = 6, and a + b = 6\n",
      "Result = |0110000010>, a = 1, b = 5, and a + b = 6\n",
      "Result = |0000100010>, a = 2, b = 4, and a + b = 6\n",
      "Result = |0110000100>, a = 5, b = 1, and a + b = 6\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0000010010>', '|0000010100>', '|0000100010>', '|0000100100>', '|0110000010>', '|0110000100>', '|0110110000>']\n",
      "Required sum                 : 7\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 8\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n",
      "Result = |0010010100>, a = 4, b = 3, and a + b = 7\n",
      "Result = |0100010100>, a = 5, b = 2, and a + b = 7\n",
      "Result = |0010100100>, a = 6, b = 1, and a + b = 7\n",
      "Result = |0100100010>, a = 3, b = 4, and a + b = 7\n",
      "Result = |0010100010>, a = 2, b = 5, and a + b = 7\n",
      "Result = |0100100100>, a = 7, b = 0, and a + b = 7\n",
      "Result = |0010010010>, a = 0, b = 7, and a + b = 7\n",
      "Result = |0100010010>, a = 1, b = 6, and a + b = 7\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010010010>', '|0010010100>', '|0010100010>', '|0010100100>', '|0100010010>', '|0100010100>', '|0100100010>', '|0100100100>']\n",
      "Required sum                 : 8\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 7\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n",
      "Result = |0110010010>, a = 1, b = 7, and a + b = 8\n",
      "Result = |0000110100>, a = 6, b = 2, and a + b = 8\n",
      "Result = |0110010100>, a = 5, b = 3, and a + b = 8\n",
      "Result = |0000000110>, a = 4, b = 4, and a + b = 8\n",
      "Result = |0110100010>, a = 3, b = 5, and a + b = 8\n",
      "Result = |0110100100>, a = 7, b = 1, and a + b = 8\n",
      "Result = |0000110010>, a = 2, b = 6, and a + b = 8\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0000000110>', '|0000110010>', '|0000110100>', '|0110010010>', '|0110010100>', '|0110100010>', '|0110100100>']\n",
      "Required sum                 : 9\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 6\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n",
      "Result = |0010110010>, a = 2, b = 7, and a + b = 9\n",
      "Result = |0010110100>, a = 6, b = 3, and a + b = 9\n",
      "Result = |0100110100>, a = 7, b = 2, and a + b = 9\n",
      "Result = |0010000110>, a = 4, b = 5, and a + b = 9\n",
      "Result = |0100110010>, a = 3, b = 6, and a + b = 9\n",
      "Result = |0100000110>, a = 5, b = 4, and a + b = 9\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010000110>', '|0010110010>', '|0010110100>', '|0100000110>', '|0100110010>', '|0100110100>']\n",
      "Required sum                 : 10\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 5\n",
      "Optimal number of iterations : 2\n",
      "Number of iterations         : 2\n",
      "Result = |0000010110>, a = 4, b = 6, and a + b = 10\n",
      "Result = |0110000110>, a = 5, b = 5, and a + b = 10\n",
      "Result = |0110110100>, a = 7, b = 3, and a + b = 10\n",
      "Result = |0110110010>, a = 3, b = 7, and a + b = 10\n",
      "Result = |0000100110>, a = 6, b = 4, and a + b = 10\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0000010110>', '|0000100110>', '|0110000110>', '|0110110010>', '|0110110100>']\n",
      "Required sum                 : 11\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 4\n",
      "Optimal number of iterations : 3\n",
      "Number of iterations         : 3\n",
      "Result = |0010010110>, a = 4, b = 7, and a + b = 11\n",
      "Result = |0100010110>, a = 5, b = 6, and a + b = 11\n",
      "Result = |0010100110>, a = 6, b = 5, and a + b = 11\n",
      "Result = |0100100110>, a = 7, b = 4, and a + b = 11\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010010110>', '|0010100110>', '|0100010110>', '|0100100110>']\n",
      "Required sum                 : 12\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 3\n",
      "Optimal number of iterations : 3\n",
      "Number of iterations         : 3\n",
      "Result = |0110100110>, a = 7, b = 5, and a + b = 12\n",
      "Result = |0000110110>, a = 6, b = 6, and a + b = 12\n",
      "Result = |0110010110>, a = 5, b = 7, and a + b = 12\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0000110110>', '|0110010110>', '|0110100110>']\n",
      "Required sum                 : 13\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 2\n",
      "Optimal number of iterations : 4\n",
      "Number of iterations         : 4\n",
      "Result = |0010110110>, a = 6, b = 7, and a + b = 13\n",
      "Result = |0100110110>, a = 7, b = 6, and a + b = 13\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0010110110>', '|0100110110>']\n",
      "Required sum                 : 14\n",
      "Number of possible inputs    : 64\n",
      "Number of possible solutions : 1\n",
      "Optimal number of iterations : 6\n",
      "Number of iterations         : 6\n",
      "Result = |0110110110>, a = 7, b = 7, and a + b = 14\n",
      "Number of violations in set of most common strings is 0\n",
      "Solutions found (not corrected for violations):\n",
      "['|0110110110>']\n"
     ]
    }
   ],
   "source": [
    "# for i in range(15):\n",
    "#    test_grover_circuit(required_sum=i, nr_measurements=20000, nr_iterations=None, plot_histogram=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}