{ "cells": [ { "cell_type": "markdown", "metadata": { "id": "7FV_m2u2Hny8" }, "source": [ "##### Copyright 2022 The Cirq Developers" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-03-29T09:30:09.757810Z", "iopub.status.busy": "2025-03-29T09:30:09.757195Z", "iopub.status.idle": "2025-03-29T09:30:09.761541Z", "shell.execute_reply": "2025-03-29T09:30:09.760885Z" }, "id": "2XSh1-J7HrcU" }, "outputs": [], "source": [ "# @title Licensed under the Apache License, Version 2.0 (the \"License\");\n", "# you may not use this file except in compliance with the License.\n", "# You may obtain a copy of the License at\n", "#\n", "# https://www.apache.org/licenses/LICENSE-2.0\n", "#\n", "# Unless required by applicable law or agreed to in writing, software\n", "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", "# See the License for the specific language governing permissions and\n", "# limitations under the License." ] }, { "cell_type": "markdown", "metadata": { "id": "Me7G0WVTHwHg" }, "source": [ "# Cirq basics" ] }, { "cell_type": "markdown", "metadata": { "id": "aAFfDwu7IFyx" }, "source": [ "\n", " \n", " \n", " \n", " \n", "
\n", " View on QuantumAI\n", " \n", " Run in Google Colab\n", " \n", " View source on GitHub\n", " \n", " Download notebook\n", "
" ] }, { "cell_type": "markdown", "metadata": { "id": "67gUU740MSXd" }, "source": [ "This tutorial will teach the basics of how to use Cirq. It will walk through how to use qubits, gates, and operations to create and simulate your first quantum circuit using Cirq. It will briefly introduce devices, unitary matrices, decompositions, and transformers as well.\n", "\n", "This tutorial isn’t a quantum computing 101 tutorial: it assumes familiarity of quantum computing at about the level of the textbook “Quantum Computation and Quantum Information” by Nielsen and Chuang.\n", "\n", "For more in-depth examples of quantum algorithms and experiments, see [Experiments](../experiments)." ] }, { "cell_type": "markdown", "metadata": { "id": "1dOjJlgrNUuz" }, "source": [ "To begin, please follow the instructions for [installing Cirq](./install.md)." ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:09.765107Z", "iopub.status.busy": "2025-03-29T09:30:09.764520Z", "iopub.status.idle": "2025-03-29T09:30:28.995874Z", "shell.execute_reply": "2025-03-29T09:30:28.994977Z" }, "id": "bd9529db1c0b" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "installing cirq...\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\u001b[31mERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.\r\n", "tensorflow-metadata 1.16.1 requires protobuf<4.21,>=3.20.3; python_version < \"3.11\", but you have protobuf 4.25.6 which is incompatible.\u001b[0m\u001b[31m\r\n", "\u001b[0m" ] }, { "name": "stdout", "output_type": "stream", "text": [ "installed cirq.\n" ] } ], "source": [ "try:\n", " import cirq\n", "except ImportError:\n", " print(\"installing cirq...\")\n", " !pip install --quiet cirq\n", " print(\"installed cirq.\")\n", " import cirq\n", "\n", "import cirq_google" ] }, { "cell_type": "markdown", "metadata": { "id": "xr-MMoXgNsUQ" }, "source": [ "## Qubits\n", "\n", "The first part of creating a quantum circuit is to define a set of qubits (also known as a quantum register) to act on.\n", "\n", "Cirq has three main ways of defining qubits:\n", "\n", "* `cirq.NamedQubit`: used to label qubits by an abstract name.\n", "* `cirq.LineQubit`: qubits labelled by number in a linear array.\n", "* `cirq.GridQubit`: qubits labelled by two numbers in a rectangular lattice.\n", "\n", "Here are some examples of defining each type of qubit." ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:28.999750Z", "iopub.status.busy": "2025-03-29T09:30:28.999265Z", "iopub.status.idle": "2025-03-29T09:30:29.004420Z", "shell.execute_reply": "2025-03-29T09:30:29.003683Z" }, "id": "PsgSo-H0Os8X" }, "outputs": [], "source": [ "# Using named qubits can be useful for abstract algorithms\n", "# as well as algorithms not yet mapped onto hardware.\n", "q0 = cirq.NamedQubit('source')\n", "q1 = cirq.NamedQubit('target')\n", "\n", "# Line qubits can be created individually\n", "q3 = cirq.LineQubit(3)\n", "\n", "# Or created in a range\n", "# This will create LineQubit(0), LineQubit(1), LineQubit(2)\n", "q0, q1, q2 = cirq.LineQubit.range(3)\n", "\n", "# Grid Qubits can also be referenced individually\n", "q4_5 = cirq.GridQubit(4, 5)\n", "\n", "# Or created in bulk in a square\n", "# This will create 16 qubits from (0,0) to (3,3)\n", "qubits = cirq.GridQubit.square(4)" ] }, { "cell_type": "markdown", "metadata": { "id": "4zE6AutyQhQ6" }, "source": [ "There are also pre-packaged sets of qubits called [Devices](../hardware/devices.ipynb). These are qubits along with a set of rules for how they can be used. A `cirq.Device` can be used to ensure that two-qubit gates are only applied to qubits that are adjacent in the hardware, and other constraints. The following example will use the `cirq_google.Sycamore` device that comes with cirq. It is a diamond-shaped grid with 54 qubits that mimics early hardware released by Google." ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.007480Z", "iopub.status.busy": "2025-03-29T09:30:29.006985Z", "iopub.status.idle": "2025-03-29T09:30:29.016042Z", "shell.execute_reply": "2025-03-29T09:30:29.015347Z" }, "id": "B0Dwgu-lQLpq" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " (0, 5)───(0, 6)\n", " │ │\n", " │ │\n", " (1, 4)───(1, 5)───(1, 6)───(1, 7)\n", " │ │ │ │\n", " │ │ │ │\n", " (2, 3)───(2, 4)───(2, 5)───(2, 6)───(2, 7)───(2, 8)\n", " │ │ │ │ │ │\n", " │ │ │ │ │ │\n", " (3, 2)───(3, 3)───(3, 4)───(3, 5)───(3, 6)───(3, 7)───(3, 8)───(3, 9)\n", " │ │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │ │\n", " (4, 1)───(4, 2)───(4, 3)───(4, 4)───(4, 5)───(4, 6)───(4, 7)───(4, 8)───(4, 9)\n", " │ │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │ │\n", "(5, 0)───(5, 1)───(5, 2)───(5, 3)───(5, 4)───(5, 5)───(5, 6)───(5, 7)───(5, 8)\n", " │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │\n", " (6, 1)───(6, 2)───(6, 3)───(6, 4)───(6, 5)───(6, 6)───(6, 7)\n", " │ │ │ │ │\n", " │ │ │ │ │\n", " (7, 2)───(7, 3)───(7, 4)───(7, 5)───(7, 6)\n", " │ │ │\n", " │ │ │\n", " (8, 3)───(8, 4)───(8, 5)\n", " │\n", " │\n", " (9, 4)\n" ] } ], "source": [ "print(cirq_google.Sycamore)" ] }, { "cell_type": "markdown", "metadata": { "id": "j1QTjyxLSe5c" }, "source": [ "## Gates and operations\n", "\n", "The next step is to use the qubits to create operations that can be used in the circuit. Cirq has two concepts that are important to understand here:\n", "\n", "* A `Gate` is an effect that can be applied to a set of qubits. \n", "* An `Operation` is a gate applied to a set of qubits.\n", "\n", "For instance, `cirq.H` is the quantum [Hadamard](https://en.wikipedia.org/wiki/Quantum_logic_gate#Hadamard_(H)_gate) and is a `Gate` object. `cirq.H(cirq.LineQubit(1))` is an `Operation` object and is the Hadamard gate applied to a specific qubit (line qubit number 1).\n", "\n", "Many textbook gates are included within cirq. `cirq.X`, `cirq.Y`, and `cirq.Z` refer to the single-qubit Pauli gates. `cirq.CZ`, `cirq.CNOT`, `cirq.SWAP` are a few of the common two-qubit gates. `cirq.measure` is a macro to apply a `MeasurementGate` to a set of qubits. You can find more, as well as instructions on how to create your own custom gates, on the [Gates documentation](../build/gates.ipynb) page.\n", "\n", "Here are some examples of operations that can be performed on gates and operations:" ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.018823Z", "iopub.status.busy": "2025-03-29T09:30:29.018478Z", "iopub.status.idle": "2025-03-29T09:30:29.023479Z", "shell.execute_reply": "2025-03-29T09:30:29.022844Z" }, "id": "wDW-yU-fesDl" }, "outputs": [], "source": [ "# Example gates\n", "cnot_gate = cirq.CNOT\n", "pauli_z = cirq.Z\n", "\n", "# Use exponentiation to get square root gates.\n", "sqrt_x_gate = cirq.X**0.5\n", "\n", "# Some gates can also take parameters\n", "sqrt_sqrt_y = cirq.YPowGate(exponent=0.25)\n", "\n", "# Create two qubits at once, in a line.\n", "q0, q1 = cirq.LineQubit.range(2)\n", "\n", "# Example operations\n", "z_op = cirq.Z(q0)\n", "not_op = cirq.CNOT(q0, q1)\n", "sqrt_iswap_op = cirq.SQRT_ISWAP(q0, q1)\n", "\n", "# You can also use the gates you specified earlier.\n", "cnot_op = cnot_gate(q0, q1)\n", "pauli_z_op = pauli_z(q0)\n", "sqrt_x_op = sqrt_x_gate(q0)\n", "sqrt_sqrt_y_op = sqrt_sqrt_y(q0)" ] }, { "cell_type": "markdown", "metadata": { "id": "BnBGLMVvWVkz" }, "source": [ "## Circuits and moments\n", "\n", "You are now ready to construct a quantum circuit. A `Circuit` is a collection of `Moment`s. A `Moment` is a collection of `Operation`s that all act during the same abstract time slice. Each `Operation` must be applied to a disjoint set of qubits compared to each of the other `Operation`s in the `Moment`. A `Moment` can be thought of as a vertical slice of a quantum circuit diagram.\n", "\n", "Circuits can be constructed in several different ways. By default, Cirq will attempt to slide your operation into the earliest possible `Moment` when you insert it. You can use the append function in two ways: \n", "\n", "By appending each operation one-by-one: " ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.025961Z", "iopub.status.busy": "2025-03-29T09:30:29.025742Z", "iopub.status.idle": "2025-03-29T09:30:29.031352Z", "shell.execute_reply": "2025-03-29T09:30:29.030598Z" }, "id": "HEuqEZcXkz3Q" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0: ───H───\n", "\n", "1: ───H───\n", "\n", "2: ───H───\n" ] } ], "source": [ "circuit = cirq.Circuit()\n", "qubits = cirq.LineQubit.range(3)\n", "circuit.append(cirq.H(qubits[0]))\n", "circuit.append(cirq.H(qubits[1]))\n", "circuit.append(cirq.H(qubits[2]))\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "ccd445492b19" }, "source": [ "Or by appending some iterable of operations. A preconstructed list works:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.034411Z", "iopub.status.busy": "2025-03-29T09:30:29.033787Z", "iopub.status.idle": "2025-03-29T09:30:29.038781Z", "shell.execute_reply": "2025-03-29T09:30:29.038110Z" }, "id": "HEuqEZcXkz3Q" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0: ───H───\n", "\n", "1: ───H───\n", "\n", "2: ───H───\n" ] } ], "source": [ "circuit = cirq.Circuit()\n", "ops = [cirq.H(q) for q in cirq.LineQubit.range(3)]\n", "circuit.append(ops)\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "a0a5de4d8f01" }, "source": [ "A generator that yields operations also works. This syntax will be used often in documentation, and works both with the `cirq.Circuit()` initializer and the `cirq.Circuit.append()` function." ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.042174Z", "iopub.status.busy": "2025-03-29T09:30:29.041541Z", "iopub.status.idle": "2025-03-29T09:30:29.047542Z", "shell.execute_reply": "2025-03-29T09:30:29.046873Z" }, "id": "HEuqEZcXkz3Q" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0: ───H───\n", "\n", "1: ───H───\n", "\n", "2: ───H───\n", "0: ───H───\n", "\n", "1: ───H───\n", "\n", "2: ───H───\n" ] } ], "source": [ "# Append with generator\n", "circuit = cirq.Circuit()\n", "circuit.append(cirq.H(q) for q in cirq.LineQubit.range(3))\n", "print(circuit)\n", "# Initializer with generator\n", "print(cirq.Circuit(cirq.H(q) for q in cirq.LineQubit.range(3)))" ] }, { "cell_type": "markdown", "metadata": { "id": "a6bd4d3152d5" }, "source": [ "Note that all of the Hadamard gates are pushed as far left as possible, and put into the same Moment since none overlap.\n", "\n", "If your operations are applied to the same qubits, they will be put in sequential, insertion-ordered moments. In the following example, the two-qubit gates overlap, and are placed in consecutive moments." ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.050565Z", "iopub.status.busy": "2025-03-29T09:30:29.050015Z", "iopub.status.idle": "2025-03-29T09:30:29.055276Z", "shell.execute_reply": "2025-03-29T09:30:29.054513Z" }, "id": "Lbez4guQl31P" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0: ───×───────────\n", " │\n", "1: ───×───×───────\n", " │\n", "2: ───────×───×───\n", " │\n", "3: ───────────×───\n" ] } ], "source": [ "print(cirq.Circuit(cirq.SWAP(q, q + 1) for q in cirq.LineQubit.range(3)))" ] }, { "cell_type": "markdown", "metadata": { "id": "3FC9bdlXmShh" }, "source": [ "Sometimes, you may not want Cirq to automatically shift operations all the way to the left. To construct a circuit without doing this, you can create the circuit moment-by-moment or use a different `InsertStrategy`, explained more in the [Circuit documentation](../build/circuits.ipynb)." ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.057899Z", "iopub.status.busy": "2025-03-29T09:30:29.057684Z", "iopub.status.idle": "2025-03-29T09:30:29.062200Z", "shell.execute_reply": "2025-03-29T09:30:29.061541Z" }, "id": "4AEahodTnYiI" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0: ───H───────────\n", "\n", "1: ───────H───────\n", "\n", "2: ───────────H───\n" ] } ], "source": [ "# Creates each gate in a separate moment by passing an iterable of Moments instead of Operations.\n", "print(cirq.Circuit(cirq.Moment([cirq.H(q)]) for q in cirq.LineQubit.range(3)))" ] }, { "cell_type": "markdown", "metadata": { "id": "j406AKYsobpq" }, "source": [ "### Circuits and devices\n", "\n", "One important consideration when using real quantum devices is that there are often constraints on circuits that are able to be run on the hardware. `Device` objects specify these constraints and can be used to validate your circuit to make sure that it contains no illegal operations. For more information on what constraints `Device` objects can specify and how to use them, see the [Devices](../hardware/devices.ipynb) page.\n", "\n", "The following example demonstrates this with the Sycamore Device:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.064584Z", "iopub.status.busy": "2025-03-29T09:30:29.064370Z", "iopub.status.idle": "2025-03-29T09:30:29.070112Z", "shell.execute_reply": "2025-03-29T09:30:29.069505Z" }, "id": "9UV-dXJOpy8B" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Qubit pair is not valid on device: (cirq.GridQubit(5, 6), cirq.GridQubit(4, 5)).\n" ] } ], "source": [ "# Create some qubits.\n", "q0 = cirq.GridQubit(5, 6)\n", "q1 = cirq.GridQubit(5, 5)\n", "q2 = cirq.GridQubit(4, 5)\n", "\n", "# Create operations using the Sycamore gate, which is supported by the Sycamore device.\n", "# However, create operations for both adjacent and non-adjacent qubit pairs.\n", "adjacent_op = cirq_google.SYC(q0, q1)\n", "nonadjacent_op = cirq_google.SYC(q0, q2)\n", "\n", "# A working circuit for the Sycamore device raises no issues.\n", "working_circuit = cirq.Circuit()\n", "working_circuit.append(adjacent_op)\n", "valid = cirq_google.Sycamore.validate_circuit(working_circuit)\n", "\n", "# A circuit using invalid operations.\n", "bad_circuit = cirq.Circuit()\n", "bad_circuit.append(nonadjacent_op)\n", "try:\n", " cirq_google.Sycamore.validate_circuit(bad_circuit)\n", "except ValueError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "metadata": { "id": "xZ68bWEjoMKt" }, "source": [ "## Simulation\n", "\n", "The results of the application of a quantum circuit can be calculated by a `Simulator`. Cirq comes bundled with a simulator that can calculate the results of circuits up to about a limit of 20 qubits. It can be initialized with `cirq.Simulator()`.\n", "\n", "There are two different approaches to using a simulator:\n", "\n", "* `simulate()`: When classically simulating a circuit, a simulator can directly access and view the resulting wave function. This is useful for debugging, learning, and understanding how circuits will function. \n", "* `run()`: When using actual quantum devices, we can only access the end result of a computation and must sample the results to get a distribution of results. Running the simulator as a sampler mimics this behavior and only returns bit strings as output.\n", "\n", "Next simulate a 2-qubit \"Bell State\":" ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.073239Z", "iopub.status.busy": "2025-03-29T09:30:29.072446Z", "iopub.status.idle": "2025-03-29T09:30:29.084465Z", "shell.execute_reply": "2025-03-29T09:30:29.083806Z" }, "id": "AwC4SL6CHpXm" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Simulate the circuit:\n", "measurements: (no measurements)\n", "\n", "qubits: (cirq.LineQubit(0), cirq.LineQubit(1))\n", "output vector: 0.707|00⟩ + 0.707|11⟩\n", "\n", "phase:\n", "output vector: |⟩\n" ] } ], "source": [ "# Create a circuit to generate a Bell State:\n", "# 1/sqrt(2) * ( |00⟩ + |11⟩ )\n", "bell_circuit = cirq.Circuit()\n", "q0, q1 = cirq.LineQubit.range(2)\n", "bell_circuit.append(cirq.H(q0))\n", "bell_circuit.append(cirq.CNOT(q0, q1))\n", "\n", "# Initialize Simulator\n", "s = cirq.Simulator()\n", "\n", "print('Simulate the circuit:')\n", "results = s.simulate(bell_circuit)\n", "print(results)\n", "\n", "# For sampling, we need to add a measurement at the end\n", "bell_circuit.append(cirq.measure(q0, q1, key='result'))\n", "\n", "# Sample the circuit\n", "samples = s.run(bell_circuit, repetitions=1000)" ] }, { "cell_type": "markdown", "metadata": { "id": "a9a791442b74" }, "source": [ "### Virtual Machine Simulation\n", "\n", "Cirq also provides the [Quantum Virtual Machine](../simulate/quantum_virtual_machine.ipynb), which is a simulated virtual version of quantum hardware devices. It consists of two primary components: \n", "1. A [virtual Engine interface](../simulate/virtual_engine_interface.ipynb) that enables you to verify and run circuits with the same interface that quantum hardware would have.\n", "2. A set of [noise models](../noise/representing_noise.ipynb) that try to realistically replicate the noise present in actual Google quantum hardware devices.\n", "\n", "The QVM is intended to serve as a replacement for the Google quantum hardware, in two cases: \n", "1. Running your circuit on a QVM can give an approximation of how your circuit runs under the influence of hardware-like noise. This can be useful to help you reconfigure or change your circuit to be less impacted by noise when run on actual quantum hardware.\n", "2. During the preparation process before running your circuit(s) on hardware, you can seamlessly use a QVM to test that your workflow or pipeline works before eventually switching to the nearly-identical hardware interface.\n", "\n", "Read more about the QVM and its uses in the [Quantum Virtual Machine](../simulate/quantum_virtual_machine.ipynb) page, or just start using it with the [QVM Creation Template](../simulate/qvm_builder_code.ipynb) page." ] }, { "cell_type": "markdown", "metadata": { "id": "be79fa541b8a" }, "source": [ "## Visualizing Results\n", "\n", "When you use `run()` to get a sample distribution of measurements, you can directly graph the simulated samples as a histogram with `cirq.plot_state_histogram`." ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.087542Z", "iopub.status.busy": "2025-03-29T09:30:29.086947Z", "iopub.status.idle": "2025-03-29T09:30:29.217171Z", "shell.execute_reply": "2025-03-29T09:30:29.216410Z" }, "id": "69dca44091f4" }, "outputs": [ { "data": { "image/png": "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4RoxYoT8/Py0atUqNWvWTNIvVxQ++eQT3XXXXTp9+rSOHz+u48eP68SJE4qLi9OBAwfsT28FBQVpz549OnDggDsPyW769OlKTU1Vp06dtG7dOj3zzDOKiYnRTTfdpO+++65aY9SvX9/+c1FRkY4fP64ePXrIMAx9/fXXv7v9smXLFBgYqP79+9vP3fHjxxUTEyN/f399+umn1arj/fff14YNGyotoaGhv7ttUFCQtm3bpqNHj1ZrX7+2Zs0ahYWF6d5777W3eXl5acKECTpz5ozS0tIkSWvXrpWXl5ceeughez8PDw8lJCRcdOxx48ZVanP2fD/44IP2n4OCgnT99dfLz8/PYb7Z9ddfr6CgIP3nP/+p5lEDtYvbWMAVlpKSouuuu04FBQV666239Nlnn8nHx8e+/uDBgzIMQ3/729/0t7/9rcox8vLy1LRpU82YMUNDhgzRddddpxtvvFG33Xab7r//frVv3/5KHU4l9957r+69914VFhZq27ZtWrRokVJTUzV48GB9++23vzuZNysrS1OmTNGqVasqzbEpKCj43f0fOHBABQUF9jlCv1XdidK9evWy37r7tepMRp49e7bi4+MVHh6umJgY3X777Ro1apRatmz5u9v++OOPatOmjTw8HP8t2rZtW/v6iv9ee+219ttRFVq3bl3luJ6envZA/WvOnG9fX99KtzEDAwPVrFkzhzlTFe21NUcKcBZhB7jCunbtan8aa+jQoerZs6fuu+8+7d+/X/7+/vY5IU888YTi4uKqHKPiD1qvXr106NAhffDBB1q/fr3+93//V3PnztWCBQvs/wK3WCwyDKPSGGVlZbVxeHZWq1X9+/dX//795eXlpcWLF2vbtm3q3bv3RbcpKytT//79dfLkST311FOKioqSn5+ffv75Z40ePbpa82XKy8sVEhKipUuXVrn+YnOOXOmuu+7SLbfcohUrVmj9+vV64YUX9I9//EP//ve/NXDgwFrff1V8fHwqBShnz3e9evWqHPti7VX97w5wB8IO4Eb16tVTcnKybr31Vr322mt6+umn7f/69/LyUmxs7O+OERwcrDFjxmjMmDE6c+aMevXqpWnTptnDzjXXXFPl7YSKKwSX8tt/rV+uzp07a/HixcrOzr7kuLt379b333+vxYsXa9SoUfb2Xz9d9nu1tWrVShs3btTNN9/scIvmSrv22mv15z//WX/+85+Vl5enm266Sc8995w97Fys/oiICH3zzTcqLy93CCf79u2zr6/476effqqzZ886XN05ePBgtWt05nwDVzPm7ABu1qdPH3Xt2lXz5s3T+fPnFRISoj59+uiNN96wh4NfO3bsmP3nEydOOKzz9/dX69atVVxcbG9r1aqV9u3b57Ddrl27tGXLlt+treJzWKrzoYJnz55Venp6les+/vhjSb/M5bjUuBVXCH59RcAwDL388svVru2uu+5SWVmZZs6cWWmb0tJSpz4N+nKUlZVVuv0TEhKiJk2aOLwvfn5+Vd6Wu/3225WTk6P33nvP3lZaWqpXX31V/v7+9itjcXFxunDhgv75z3/a+5WXl9sfBa8OZ843cDXjyg5QB0yaNEl//OMftWjRIj366KNKSUlRz5491a5dOz300ENq2bKlcnNzlZ6erp9++km7du2SJEVHR6tPnz6KiYlRcHCwduzYYX/kucIDDzygl156SXFxcRo7dqzy8vK0YMEC3XDDDSosLLxkXTExMZKkZ555Rvfcc4+8vLw0ePDgKj+M7uzZs+rRo4e6d++u2267TeHh4crPz9fKlSv1+eefa+jQoerUqZOkXwJYUFCQFixYoICAAPn5+albt26KiopSq1at9MQTT+jnn3+W1WrV+++/X+Xcj4raJkyYoLi4ONWrV0/33HOPevfurUceeUTJycnKzMzUgAED5OXlpQMHDmjZsmV6+eWXNWLEiMt7o6rh9OnTatasmUaMGKEOHTrI399fGzdu1Pbt2zVnzhyH+t977z0lJSWpS5cu8vf31+DBg/Xwww/rjTfe0OjRo5WRkaHIyEgtX75cW7Zs0bx58xQQECDpl1ugXbt21eOPP66DBw8qKipKq1atsj8yX52rcs6cb+Cq5rbnwID/MhWPnm/fvr3SurKyMqNVq1ZGq1atjNLSUsMwDOPQoUPGqFGjjLCwMMPLy8to2rSpcccddxjLly+3b/f3v//d6Nq1qxEUFGTUr1/fiIqKMp577jmjpKTEYfx33nnHaNmypeHt7W107NjRWLduXbUePTcMw5g5c6bRtGlTw8PD45KPoV+4cMH45z//aQwdOtSIiIgwfHx8jAYNGhidOnUyXnjhBaO4uNih/wcffGBER0cbnp6eDo9K792714iNjTX8/f2NRo0aGQ899JCxa9euSo9Tl5aWGuPHjzcaN25sWCyWSo+h/8///I8RExNj1K9f3wgICDDatWtnPPnkk8bRo0errL9CxaPnx44dq3J9RETEJR89Ly4uNiZNmmR06NDBCAgIMPz8/IwOHToYr7/+usM2Z86cMe677z4jKCjIkOTwXuTm5hpjxowxGjVqZHh7exvt2rWr8jH9Y8eOGffdd58REBBgBAYGGqNHjza2bNliSHJ4FDw+Pt7w8/Or8niqe74vNkbv3r2NG264oVrnCXAXi2EwgwwAzGLlypW688479cUXX1z006yB/zaEHQC4Sp07d85hEnZZWZkGDBigHTt2KCcnx60TtIG6hDk7AHCVGj9+vM6dOyebzabi4mL9+9//1tatW/X8888TdIBf4coOAFylUlNTNWfOHB08eFDnz59X69atNW7cOIcJ6gAIOwAAwOT4nB0AAGBqhB0AAGBqTFDWL586evToUQUEBLjs4/EBAEDtMgxDp0+fVpMmTSp999uvEXYkHT16VOHh4e4uAwAAXIYjR46oWbNmF11P2JHsH79+5MgRWa1WN1cDAACqo7CwUOHh4fa/4xdD2NH/fYeM1Wol7AAAcJX5vSkoTFAGAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACmRtgBAACm5tawM23aNFksFoclKirKvv78+fNKSEhQw4YN5e/vr+HDhys3N9dhjKysLA0aNEgNGjRQSEiIJk2apNLS0it9KAAAoI7ydHcBN9xwgzZu3Gh/7en5fyVNnDhRH330kZYtW6bAwEAlJiZq2LBh2rJliySprKxMgwYNUlhYmLZu3ars7GyNGjVKXl5eev7556/4sQAAgLrH7WHH09NTYWFhldoLCgr05ptvKjU1VX379pUkLVy4UG3bttWXX36p7t27a/369dq7d682btyo0NBQdezYUTNnztRTTz2ladOmydvb+0ofDgCgjop8+iN3l/Bf64dZg9y6f7fP2Tlw4ICaNGmili1bauTIkcrKypIkZWRk6MKFC4qNjbX3jYqKUvPmzZWeni5JSk9PV7t27RQaGmrvExcXp8LCQu3Zs+ei+ywuLlZhYaHDAgAAzMmtYadbt25atGiR1q5dq/nz5+vw4cO65ZZbdPr0aeXk5Mjb21tBQUEO24SGhionJ0eSlJOT4xB0KtZXrLuY5ORkBQYG2pfw8HDXHhgAAKgz3Hoba+DAgfaf27dvr27duikiIkL/+te/VL9+/Vrb7+TJk5WUlGR/XVhYSOABAMCk3D5n59eCgoJ03XXX6eDBg+rfv79KSkqUn5/vcHUnNzfXPscnLCxMX331lcMYFU9rVTUPqIKPj498fHxcfwBV4B6x+7j7HjEAoG5w+5ydXztz5owOHTqka6+9VjExMfLy8tKmTZvs6/fv36+srCzZbDZJks1m0+7du5WXl2fvs2HDBlmtVkVHR1/x+gEAQN3j1is7TzzxhAYPHqyIiAgdPXpUU6dOVb169XTvvfcqMDBQY8eOVVJSkoKDg2W1WjV+/HjZbDZ1795dkjRgwABFR0fr/vvv1+zZs5WTk6Nnn31WCQkJV+zKDQAAqNvcGnZ++ukn3XvvvTpx4oQaN26snj176ssvv1Tjxo0lSXPnzpWHh4eGDx+u4uJixcXF6fXXX7dvX69ePa1evVrjxo2TzWaTn5+f4uPjNWPGDHcdEgAAqGPcGnbefffdS6739fVVSkqKUlJSLtonIiJCa9ascXVpAADAJOrUnB0AAABXI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTI+wAAABTqzNhZ9asWbJYLHrsscfsbefPn1dCQoIaNmwof39/DR8+XLm5uQ7bZWVladCgQWrQoIFCQkI0adIklZaWXuHqAQBAXVUnws727dv1xhtvqH379g7tEydO1Icffqhly5YpLS1NR48e1bBhw+zry8rKNGjQIJWUlGjr1q1avHixFi1apClTplzpQwAAAHWU28POmTNnNHLkSP3zn//UNddcY28vKCjQm2++qZdeekl9+/ZVTEyMFi5cqK1bt+rLL7+UJK1fv1579+7VO++8o44dO2rgwIGaOXOmUlJSVFJS4q5DAgAAdYjbw05CQoIGDRqk2NhYh/aMjAxduHDBoT0qKkrNmzdXenq6JCk9PV3t2rVTaGiovU9cXJwKCwu1Z8+ei+6zuLhYhYWFDgsAADAnT3fu/N1339XOnTu1ffv2SutycnLk7e2toKAgh/bQ0FDl5OTY+/w66FSsr1h3McnJyZo+fXoNqwcAAFcDt13ZOXLkiP7yl79o6dKl8vX1vaL7njx5sgoKCuzLkSNHruj+AQDAleO2sJORkaG8vDzddNNN8vT0lKenp9LS0vTKK6/I09NToaGhKikpUX5+vsN2ubm5CgsLkySFhYVVejqr4nVFn6r4+PjIarU6LAAAwJzcFnb69eun3bt3KzMz07507txZI0eOtP/s5eWlTZs22bfZv3+/srKyZLPZJEk2m027d+9WXl6evc+GDRtktVoVHR19xY8JAADUPW6bsxMQEKAbb7zRoc3Pz08NGza0t48dO1ZJSUkKDg6W1WrV+PHjZbPZ1L17d0nSgAEDFB0drfvvv1+zZ89WTk6Onn32WSUkJMjHx+eKHxMAAKh73DpB+ffMnTtXHh4eGj58uIqLixUXF6fXX3/dvr5evXpavXq1xo0bJ5vNJj8/P8XHx2vGjBlurBoAANQldSrsbN682eG1r6+vUlJSlJKSctFtIiIitGbNmlquDAAAXK3c/jk7AAAAtYmwAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATI2wAwAATM3psLNkyRIVFxdXai8pKdGSJUtcUhQAAICrOB12xowZo4KCgkrtp0+f1pgxY1xSFAAAgKs4HXYMw5DFYqnU/tNPPykwMNAlRQEAALiKZ3U7durUSRaLRRaLRf369ZOn5/9tWlZWpsOHD+u2226rlSIBAAAuV7XDztChQyVJmZmZiouLk7+/v32dt7e3IiMjNXz4cJcXCAAAUBPVDjtTp06VJEVGRuruu++Wr69vrRUFAADgKtUOOxXi4+Ml/fL0VV5ensrLyx3WN2/e3DWVAQAAuIDTYefAgQN64IEHtHXrVof2ionLZWVlLisOAACgppwOO6NHj5anp6dWr16ta6+9tsonswAAAOoKp8NOZmamMjIyFBUVVRv1AAAAuJTTn7MTHR2t48ePu2Tn8+fPV/v27WW1WmW1WmWz2fTxxx/b158/f14JCQlq2LCh/P39NXz4cOXm5jqMkZWVpUGDBqlBgwYKCQnRpEmTVFpa6pL6AADA1c/psPOPf/xDTz75pDZv3qwTJ06osLDQYXFGs2bNNGvWLGVkZGjHjh3q27evhgwZoj179kiSJk6cqA8//FDLli1TWlqajh49qmHDhtm3Lysr06BBg1RSUqKtW7dq8eLFWrRokaZMmeLsYQEAAJOyGIZhOLOBh8cv+ei3c3VcNUE5ODhYL7zwgkaMGKHGjRsrNTVVI0aMkCTt27dPbdu2VXp6urp3766PP/5Yd9xxh44eParQ0FBJ0oIFC/TUU0/p2LFj8vb2rtY+CwsLFRgYqIKCAlmt1hrV/1uRT3/k0vFQfT/MGuTuEgDUIfw+dp/a+n1c3b/fTs/Z+fTTT2tU2MWUlZVp2bJlKioqks1mU0ZGhi5cuKDY2Fh7n6ioKDVv3twedtLT09WuXTt70JGkuLg4jRs3Tnv27FGnTp1qpVYAAHD1cDrs9O7d26UF7N69WzabTefPn5e/v79WrFih6OhoZWZmytvbW0FBQQ79Q0NDlZOTI0nKyclxCDoV6yvWXUxxcbHDN7c7e/sNAABcPZwOO5999tkl1/fq1cup8a6//nplZmaqoKBAy5cvV3x8vNLS0pwtyynJycmaPn16re4DAADUDU6HnT59+lRq+/X8HWfn7Hh7e6t169aSpJiYGG3fvl0vv/yy7r77bpWUlCg/P9/h6k5ubq7CwsIkSWFhYfrqq68cxqt4WquiT1UmT56spKQk++vCwkKFh4c7VTcAALg6OP001qlTpxyWvLw8rV27Vl26dNH69etrXFB5ebmKi4sVExMjLy8vbdq0yb5u//79ysrKks1mkyTZbDbt3r1beXl59j4bNmyQ1WpVdHT0Rffh4+Njf9y9YgEAAObk9JWdwMDASm39+/eXt7e3kpKSlJGRUe2xJk+erIEDB6p58+Y6ffq0UlNTtXnzZq1bt06BgYEaO3askpKSFBwcLKvVqvHjx8tms6l79+6SpAEDBig6Olr333+/Zs+erZycHD377LNKSEiQj4+Ps4cGAABMyOmwczGhoaHav3+/U9vk5eVp1KhRys7OVmBgoNq3b69169apf//+kqS5c+fKw8NDw4cPV3FxseLi4vT666/bt69Xr55Wr16tcePGyWazyc/PT/Hx8ZoxY4arDgsAAFzlnA4733zzjcNrwzCUnZ2tWbNmqWPHjk6N9eabb15yva+vr1JSUpSSknLRPhEREVqzZo1T+wUAAP89nA47HTt2lMVi0W8/i7B79+566623XFYYAACAKzgddg4fPuzw2sPDQ40bN5avr6/LigIAAHAVp8NOREREbdQBAABQK5x+9FyS0tLSNHjwYLVu3VqtW7fWH/7wB33++eeurg0AAKDGnA4777zzjmJjY9WgQQNNmDBBEyZMUP369dWvXz+lpqbWRo0AAACXzenbWM8995xmz56tiRMn2tsmTJigl156STNnztR9993n0gIBAABqwukrO//5z380ePDgSu1/+MMfKk1eBgAAcDenw054eLjDVzhU2LhxI98vBQAA6hynb2M9/vjjmjBhgjIzM9WjRw9J0pYtW7Ro0SK9/PLLLi8QAACgJpwOO+PGjVNYWJjmzJmjf/3rX5Kktm3b6r333tOQIUNcXiAAAEBNXNZ3Y91555268847XV0LAACAyzk9Z2f79u3atm1bpfZt27Zpx44dLikKAADAVZwOOwkJCTpy5Eil9p9//lkJCQkuKQoAAMBVnA47e/fu1U033VSpvVOnTtq7d69LigIAAHAVp8OOj4+PcnNzK7VnZ2fL0/OypgABAADUGqfDzoABAzR58mQVFBTY2/Lz8/XXv/5V/fv3d2lxAAAANeX0pZgXX3xRvXr1UkREhDp16iRJyszMVGhoqN5++22XFwgAAFATToedpk2b6ptvvtHSpUu1a9cu1a9fX2PGjNG9994rLy+v2qgRAADgsl3WJBs/Pz89/PDDrq4FAADA5ZyeswMAAHA1IewAAABTI+wAAABTI+wAAABTczrstGzZUidOnKjUnp+fr5YtW7qkKAAAAFdxOuz88MMPKisrq9ReXFysn3/+2SVFAQAAuEq1Hz1ftWqV/ed169YpMDDQ/rqsrEybNm1SZGSkS4sDAACoqWqHnaFDh0qSLBaL4uPjHdZ5eXkpMjJSc+bMcWlxAAAANVXtsFNeXi5JatGihbZv365GjRrVWlEAAACu4vQnKB8+fLg26gAAAKgV1Qo7r7zySrUHnDBhwmUXAwAA4GrVCjtz586t1mAWi4WwAwAA6pRqhR1uXQEAgKsVn6AMAABMzekJyg888MAl17/11luXXQwAAICrOR12Tp065fD6woUL+vbbb5Wfn6++ffu6rDAAAABXcDrsrFixolJbeXm5xo0bp1atWrmkKAAAAFdxyZwdDw8PJSUlVfupLQAAgCvFZROUDx06pNLSUlcNBwAA4BJO38ZKSkpyeG0YhrKzs/XRRx9V+s4sAAAAd3M67Hz99dcOrz08PNS4cWPNmTPnd5/UAgAAuNKcDjuffvppbdQBAABQK5yes3Pu3DmdPXvW/vrHH3/UvHnztH79epcWBgAA4ApOh50hQ4ZoyZIlkqT8/Hx17dpVc+bM0ZAhQzR//nyXFwgAAFATToednTt36pZbbpEkLV++XGFhYfrxxx+1ZMkSp74dHQAA4EpwOuycPXtWAQEBkqT169dr2LBh8vDwUPfu3fXjjz+6vEAAAICacDrstG7dWitXrtSRI0e0bt06DRgwQJKUl5cnq9Xq8gIBAABqwumwM2XKFD3xxBOKjIxU165dZbPZJP1yladTp04uLxAAAKAmnH70fMSIEerZs6eys7PVoUMHe3u/fv105513urQ4AACAmrqsr4sICwtTQECANmzYoHPnzkmSunTpoqioKJcWBwAAUFNOh50TJ06oX79+uu6663T77bcrOztbkjR27Fg9/vjjLi8QAACgJpwOOxMnTpSXl5eysrLUoEEDe/vdd9+ttWvXurQ4AACAmnJ6zs769eu1bt06NWvWzKG9TZs2PHoOAADqHKev7BQVFTlc0alw8uRJ+fj4uKQoAAAAV3E67Nxyyy32r4uQJIvFovLycs2ePVu33nqrS4sDAACoKadvY82ePVv9+vXTjh07VFJSoieffFJ79uzRyZMntWXLltqoEQAA4LI5fWXnxhtv1Pfff6+ePXtqyJAhKioq0rBhw/T111+rVatWtVEjAADAZXPqys6FCxd02223acGCBXrmmWdqqyYAAACXcerKjpeXl7755pvaqgUAAMDlnL6N9ac//UlvvvlmbdQCAADgck6HndLSUs2fP1+dO3fWI488oqSkJIfFGcnJyerSpYsCAgIUEhKioUOHav/+/Q59zp8/r4SEBDVs2FD+/v4aPny4cnNzHfpkZWVp0KBBatCggUJCQjRp0iSVlpY6e2gAAMCEnH4a69tvv9VNN90kSfr+++8d1lksFqfGSktLU0JCgrp06aLS0lL99a9/1YABA7R37175+flJ+uUTmz/66CMtW7ZMgYGBSkxM1LBhw+xPfpWVlWnQoEEKCwvT1q1blZ2drVGjRsnLy0vPP/+8s4cHAABMxmIYhuHuIiocO3ZMISEhSktLU69evVRQUKDGjRsrNTVVI0aMkCTt27dPbdu2VXp6urp3766PP/5Yd9xxh44eParQ0FBJ0oIFC/TUU0/p2LFj8vb2/t39FhYWKjAwUAUFBbJarS49psinP3LpeKi+H2YNcncJAOoQfh+7T239Pq7u3+/L+tbz2lJQUCBJCg4OliRlZGTowoULio2NtfeJiopS8+bNlZ6eLklKT09Xu3bt7EFHkuLi4lRYWKg9e/ZcweoBAEBd5PRtrNpSXl6uxx57TDfffLNuvPFGSVJOTo68vb0VFBTk0Dc0NFQ5OTn2Pr8OOhXrK9ZVpbi4WMXFxfbXhYWFrjoMAABQx9SZKzsJCQn69ttv9e6779b6vpKTkxUYGGhfwsPDa32fAADAPepE2ElMTNTq1av16aefOnybelhYmEpKSpSfn+/QPzc3V2FhYfY+v306q+J1RZ/fmjx5sgoKCuzLkSNHXHg0AACgLnFr2DEMQ4mJiVqxYoU++eQTtWjRwmF9TEyMvLy8tGnTJnvb/v37lZWVJZvNJkmy2WzavXu38vLy7H02bNggq9Wq6OjoKvfr4+Mjq9XqsAAAAHNy65ydhIQEpaam6oMPPlBAQIB9jk1gYKDq16+vwMBAjR07VklJSQoODpbVatX48eNls9nUvXt3SdKAAQMUHR2t+++/X7Nnz1ZOTo6effZZJSQkyMfHx52HBwAA6gC3hp358+dLkvr06ePQvnDhQo0ePVqSNHfuXHl4eGj48OEqLi5WXFycXn/9dXvfevXqafXq1Ro3bpxsNpv8/PwUHx+vGTNmXKnDAAAAdZhbw051PuLH19dXKSkpSklJuWifiIgIrVmzxpWlAQAAk6gTE5QBAABqC2EHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYmlvDzmeffabBgwerSZMmslgsWrlypcN6wzA0ZcoUXXvttapfv75iY2N14MABhz4nT57UyJEjZbVaFRQUpLFjx+rMmTNX8CgAAEBd5tawU1RUpA4dOiglJaXK9bNnz9Yrr7yiBQsWaNu2bfLz81NcXJzOnz9v7zNy5Ejt2bNHGzZs0OrVq/XZZ5/p4YcfvlKHAAAA6jhPd+584MCBGjhwYJXrDMPQvHnz9Oyzz2rIkCGSpCVLlig0NFQrV67UPffco++++05r167V9u3b1blzZ0nSq6++qttvv10vvviimjRpcsWOBQAA1E11ds7O4cOHlZOTo9jYWHtbYGCgunXrpvT0dElSenq6goKC7EFHkmJjY+Xh4aFt27Zd8ZoBAEDd49YrO5eSk5MjSQoNDXVoDw0Nta/LyclRSEiIw3pPT08FBwfb+1SluLhYxcXF9teFhYWuKhsAANQxdfbKTm1KTk5WYGCgfQkPD3d3SQAAoJbU2bATFhYmScrNzXVoz83Nta8LCwtTXl6ew/rS0lKdPHnS3qcqkydPVkFBgX05cuSIi6sHAAB1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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import matplotlib.pyplot as plt\n", "\n", "cirq.plot_state_histogram(samples, plt.subplot())\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": { "id": "b4f20cffe4ae" }, "source": [ "However, this histogram has some empty qubit states, which may become problematic if you work with more qubits. To graph sparse sampled data, first get the `Counts` from your results with its `histogram()` function, and pass that to `cirq.plot_state_histogram`. By collecting the results into counts, all the qubit states that were never seen are ignored." ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.220228Z", "iopub.status.busy": "2025-03-29T09:30:29.219964Z", "iopub.status.idle": "2025-03-29T09:30:29.322822Z", "shell.execute_reply": "2025-03-29T09:30:29.322093Z" }, "id": "07ec16b02594" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Counter({3: 503, 0: 497})\n" ] }, { "data": { "image/png": "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z3/Wn//8ZxUUFOimm27Sc889Zw8756s/IiJC33zzjSoqKhzCye7du+3rK//72Wef6fTp0w5Xd/bt21fjGp0538DVjDk7gJv16dNHXbt2VVpams6ePauQkBD16dNHb7zxhj0c/Nrhw4ftPx89etRhnb+/v1q3bq2SkhJ7W6tWrbR7926H7bZv366NGzdetLbKz2GpyYcKnj59WpmZmdWu++STTyT9MpfjQuNWXiH49RUBwzD08ssv17i2u+66S+Xl5Zo+fXqVbcrKypz6NOhLUV5eXuX2T0hIiJo0aeLwe/Hz86v2ttztt9+uvLw8vffee/a2srIyvfrqq/L397dfGYuPj9e5c+f0z3/+096voqLC/ih4TThzvoGrGVd2gDpgwoQJ+uMf/6j58+fr0UcfVXp6unr27Kl27drpoYceUsuWLZWfn6/MzEz99NNP2r59uyQpOjpaffr0UUxMjIKDg7V161b7I8+VHnjgAb300kuKj4/X6NGjVVBQoLlz5+qGG25QcXHxBeuKiYmRJD3zzDO655575OXlpYEDB1b7YXSnT59Wjx491L17d912220KDw9XYWGhli5dqi+++EKDBw9Wp06dJP0SwIKCgjR37lwFBATIz89P3bp1U1RUlFq1aqUnnnhCP//8s6xWq95///1q535U1jZu3DjFx8erXr16uueee9S7d2898sgjSk1NVXZ2tvr37y8vLy/t3btXixcv1ssvv6xhw4Zd2i+qBk6cOKFmzZpp2LBh6tChg/z9/bV27Vpt2bJFs2bNcqj/vffeU0pKirp06SJ/f38NHDhQDz/8sN544w2NHDlSWVlZioyM1JIlS7Rx40alpaUpICBA0i+3QLt27arHH39c+/btU1RUlJYtW2Z/ZL4mV+WcOd/AVc1tz4EBvzOVj55v2bKlyrry8nKjVatWRqtWrYyysjLDMAxj//79xogRI4ywsDDDy8vLaNq0qXHHHXcYS5YssW/397//3ejatasRFBRk1K9f34iKijKee+45o7S01GH8d955x2jZsqXh7e1tdOzY0Vi1alWNHj03DMOYPn260bRpU8PDw+OCj6GfO3fO+Oc//2kMHjzYiIiIMHx8fIwGDRoYnTp1Ml544QWjpKTEof+HH35oREdHG56eng6PSu/atcuIjY01/P39jUaNGhkPPfSQsX379iqPU5eVlRljx441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gLqNr4sAcFXy9vbmW+sB1AhXdgC41KlTpzRixAj5+/vr2muv1axZs9SnTx899thj9j4Wi0VLly512C4oKEjz5893aNu9e7d69OghX19f3XjjjdqwYYN93a+vpqxfv16jRo1SUVGRLBaLLBaLpkyZUm1927dv16233qqAgABZrVbFxMRo69atFxzj7bffVufOnRUQEKCwsDDdd999KigokPTLLbdbb71VknTNNdfIYrFo5MiRkn75xu3U1FS1aNFC9evXV4cOHbRkyZJLPrcALg1hB4BLTZgwQRs2bNCHH36o1atXa/369dq2bdslj/X444/r66+/ls1m08CBA3X06NEq/Xr06KG0tDRZrVbl5uYqNzdXTzzxRLVjDh8+XM2aNdOWLVuUlZWlp59+Wl5eXhcc49y5c5o+fbq2b9+upUuX6ocffrAHmvDwcL3//vuSpD179ig3N1cvv/yyJCk1NVULFy7U3LlztXPnTo0fP15/+tOfHEIbgNrHbSwALnPy5Em9+eabeuedd9SvXz9J0oIFC9SsWbNLGi85OVlDhw6VJM2ZM0crV67Um2++qSeffNKhn7e3twIDA2WxWC56aysnJ0cTJkxQVFSUJKlNmzb2decb44EHHrD/3LJlS73yyivq0qWLTp48KX9/fwUHB0uSQkJC7HN+SkpK9Pzzz2vt2rWy2Wz2bf/zn//ojTfeUO/evS/hjAC4FFzZAeAy+/fvV2lpqbp162ZvCw4O1vXXX39J41WGBEny9PRU586d9d13311WjSkpKXrwwQcVGxurGTNmaP/+/RfdJisrSwMHDlTz5s0VEBBgDyo5OTnn3Wbfvn06ffq04uLi5O/vb18WLlxYo30CcB3CDoArzmKxyDAMh7Zz585dkX1PmTJFO3fuVEJCgj799FNFR0frgw8+OG//U6dOKT4+XlarVYsWLdKWLVvs/UtLS8+73cmTJyVJH3/8sbKzs+3Lrl27mLcDXGGEHQAu06pVK3l5eWnz5s32tuPHj+v777936Ne4cWPl5ubaX+/du1enT5+uMt6XX35p/7msrExZWVlq27Zttfv29vZWeXl5jeq87rrrNH78eK1evVpDhgzRvHnzzjvG7t27dfToUc2YMUO33HKLoqKi7JOTf71vSQ7bRkdHy8fHRzk5OWrdurXDEh4eXqM6AbgGc3YAuIy/v79Gjx6tCRMmqGHDhgoJCdEzzzwjDw/Hf1f17dtXr732mmw2m8rLy/XUU0/Jy8urynjp6elq06aN2rZtq9mzZ+v48eMO82d+LTIyUidPntS6devUoUMHNWjQQA0aNHDoc+bMGU2YMEHDhg1TixYt9NNPP2nLli32eUHVjdG8eXN5e3vr1Vdf1aOPPqpvv/1W06dPdxg3IiJCFotFy5cv1+2336769esrICBATzzxhMaPH6+Kigr17NlTRUVF2rhxo6xWqxITEy/nVANwhgEALnTixAnjT3/6k9GgQQMjNDTUmDlzptG7d2/jL3/5i73Pzz//bPTv39/w8/Mz2rRpY6xYscIIDAw05s2bZxiGYRw4cMCQZGRkZBhdu3Y1vL29jejoaOPTTz+1j/HZZ58Zkozjx4/b2x599FGjYcOGhiRj8uTJVWorKSkx7rnnHiM8PNzw9vY2mjRpYiQnJxtnzpy54BgZGRlGZGSk4ePjY9hsNmPZsmWGJOPrr7+2bzdt2jQjLCzMsFgsRmJiomEYhlFRUWGkpaUZ119/veHl5WU0btzYiI+PNzZs2HC5pxmAEyyG8Zsb5wDgYn369FHHjh2Vlpbm7lIA/A4xZwcAAJgaYQcAAJgat7EAAICpcWUHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACYGmEHAACY2v8HSoRHBwGTdecAAAAASUVORK5CYII=", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Pull of histogram counts from the result data structure\n", "counts = samples.histogram(key='result')\n", "print(counts)\n", "\n", "# Graph the histogram counts instead of the results\n", "cirq.plot_state_histogram(counts, plt.subplot())\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": { "id": "ef90dabdd52e" }, "source": [ "A histogram over the states that were actually observed can often be more useful when analyzing results. To learn more about the available options for creating result histograms, see the [State Histograms](../simulate/state_histograms.ipynb) page. " ] }, { "cell_type": "markdown", "metadata": { "id": "06Q_7vlQSu4Z" }, "source": [ "### Using parameter sweeps\n", "\n", "Cirq circuits allow for gates to have symbols as free parameters within the circuit. This is especially useful for variational algorithms, which vary parameters within the circuit in order to optimize a cost function, but it can be useful in a variety of circumstances.\n", "\n", "For parameters, Cirq uses the library `sympy` to add `sympy.Symbol` as parameters to gates and operations. \n", "\n", "Once the circuit is complete, you can fill in the possible values of each of these parameters with a `Sweep`. There are several possibilities that can be used as a sweep:\n", "\n", "* `cirq.Points`: A list of manually specified values for one specific symbol as a sequence of floats.\n", "* `cirq.Linspace`: A linear sweep from a starting value to an ending value.\n", "* `cirq.ListSweep`: A list of manually specified values for several different symbols, specified as a list of dictionaries.\n", "* `cirq.Zip` and `cirq.Product`: Sweeps can be combined list-wise by zipping them together or through their Cartesian product.\n", "\n", "A parameterized circuit and sweep together can be run using the simulator or other sampler by changing `run()` to `run_sweep()` and adding the sweep as a parameter.\n", "\n", "Here is an example of sweeping an exponent of a X gate:" ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:29.325872Z", "iopub.status.busy": "2025-03-29T09:30:29.325605Z", "iopub.status.idle": "2025-03-29T09:30:30.346609Z", "shell.execute_reply": "2025-03-29T09:30:30.345906Z" }, "id": "ElyizofbLGq9" }, "outputs": [ { "data": { "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjcAAAGwCAYAAABVdURTAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvc2/+5QAAAAlwSFlzAAAPYQAAD2EBqD+naQAAYXBJREFUeJzt3XlcVOX+B/DPDLILA6QwaCQuaCHimohL3gzSNE2792aWuWR208yF7Kr3lwtaoZZbF8tbaeb1urTYYhqlqJWKeRNJCXIh1FTABWVHcOb8/uCekYEZOGc4wyx83q8Xr+LMOTPPcZg53/M83+f7qARBEEBERETkJNS2bgARERGRkhjcEBERkVNhcENEREROhcENERERORUGN0RERORUGNwQERGRU2FwQ0RERE6lma0b0Nj0ej0uX74MHx8fqFQqWzeHiIiIJBAEAUVFRWjVqhXU6rr7ZppccHP58mWEhITYuhlERERkgT/++AN33313nfs0ueDGx8cHQNU/jq+vr41bQ0RERFIUFhYiJCTEcB2vS5MLbsShKF9fXwY3REREDkZKSgkTiomIiMipMLghIiIip8LghoiIiJwKgxsiIiJyKgxuiIiIyKkwuCEiIiKnwuCGiIiInAqDGyIiInIqDG6IiIjIqTS5CsVE5Ph0egFHs/NxpagcgT4e6NnGH8fO30BuQRnySyoQ0Nwdgc3dARVwpbAc+SUV8PNyw83Sqse0vh7o3TYALmounkvkjGwa3Pzwww948803cezYMeTk5ODzzz/HyJEj6zzmwIEDiIuLw6+//oqQkBC8+uqrmDBhQqO0l4hsLyk9B/E7M5BTUG7YpgIgyHweP09XTOwXimmDwhjkEDkZmw5LlZSUoGvXrli7dq2k/bOzszFs2DA8+OCDSEtLw8yZM/Hcc8/h22+/tXJLichWdHoBKVnX8XnqRcz+OA0vbE41CmwA+YENANwsq8SqvWcQGf8tluz8FSlZ16HTW/JMRGRvVIIg2MWnWaVS1dtzM2fOHOzatQvp6emGbU8++SRu3ryJpKQkSa9TWFgIjUaDgoICLpxJZIfEIafcgjIcOnsNezKvoKCsslFeO1jjgYXDwzEkIrhRXo+IpJNz/XaonJuUlBTExMQYbRs8eDBmzpxp9phbt27h1q1bht8LCwut1TwiaiBTQ06NKbegHFM2p+LdsT0Y4BA5MIeaLZWbm4ugoCCjbUFBQSgsLERZWZnJYxISEqDRaAw/ISEhjdFUIpIpKT0HU0wMOTUm4X8/cz47gUNnr3GYishBOVRwY4l58+ahoKDA8PPHH3/YuklEVEPFbT3+8Xm6Rbkz1lBQdhtPf/AT+i/bh6T0HFs3h4hkcqhhKa1Wi7y8PKNteXl58PX1haenp8lj3N3d4e7u3hjNIyKJaubVfJOei5IKna2bVUsOh6mIHJJDBTfR0dHYvXu30bY9e/YgOjraRi0iIrlsnVcjlwDglU9/QektHYL9PFkfh8gB2DS4KS4uxtmzZw2/Z2dnIy0tDQEBAbjnnnswb948XLp0CZs2bQIAvPDCC0hMTMTf//53PPvss9i3bx8+/vhj7Nq1y1anQET1qF5w79y1Uqzee9puhp+kKirXIe6TXwCwPg6RI7DpVPADBw7gwQcfrLV9/Pjx2LhxIyZMmIBz587hwIEDRsfMmjULGRkZuPvuuzF//nxZRfw4FZyo8TR2L43Goxliw4PQL6ylyQrFKVnKTS33cnPB3x5oxyCHqJHIuX7bTZ2bxsLghqhxiLOfrPUFE6zxwPxh98Hf292wDIOUISOxJ2lTSja+Sc+rc18p/LxcsfTxLszJIbIyBjd1YHBDZH06vYD+y/Yp2mNTvVdGibWhdHoB/ZbuQ25hw9uoAph0TGRlTlvEj4gcw9HsfEUCGx8PF8QPj7BKIq+LWoVFI8IV6V1i0jGRfWFwQ0QNVnOV7u9+zW3wc6oAvPmXrlbtDRkSEYx3x/ZQJC+oetIxl3Egsi0OSxFRg1gjadjfyxUJjZjHIgZnl2+UYtHXGSgqv93g5+RQFZGyOCxFRI1i94kcTN2Sqtjz2WqatYtahej2dwG4C94ezRRLhI7fmYHYcC2HqIgaGYMbIrLI7hOXMW3rcUWe68U/tUf/sJZ2kaui1FCVgKoKx0ez8/8XOBFRY2FwQ0SyJaXnYOqWhgc2KgBajQfiHu5k86CmuiERwYgN1xotEbE7PRelFiwRcaXIMSoxEzkTBjdEJItOLyB+Z0aDn0cMZRYOD7erwEZ0Z6gKGNXjbiz7i4DEfWfx3g9ZstbBCvTxsFYTicgMp18VnIiUpdQ0b63Gw6ESbl3UKsyICcPxBQ8jwNtN0jFqFXCjpMLKLSOimhjcEJEsDR1mmdQvFFsn98HBOYMcJrCpzq2ZGm+MioCUvia9ALy4JRVJ6TlWbxcR3cHghohkacgwy6yYjpg/vDOi299ll0NRUolJx8Ga+v8tBACLvvoVOn2TqrpBZFMMbohIlt5tA6D1lR/gaH3dMW1QByu0yDaGRATj4JxBmD/svnr3zS28hWlbUpGSdR0Vt/VIybqOL9MuISXrOoMeIitgQjERSabTVyXVFpZLX1Vb7J9ZNKKzQ/fWmOKiVqGFj7ukfb9Jz8U36blQq6qGq0SsZkykPPbcEJEkSek56PnaHqzae9rslGhvNxf4ebkabXO0xGG55A7T1eyoyS0ox5TNzMshUhJ7boioTmJvzaq9p+vd18ejGX74+yAcO3/DsM6UPRTms6bebQMQrPGweAaZgKreLVYzJlIOgxsiMispPQeLvvoVuYW3JO2fW3gLx87faFIVeV3UKiwcHo4XNlu+DAWrGRMpi8NSRGRSUnoOpmxOlRzYiJpiRd4hEcGYFRPW4Odpiv92RNbA4IaIahGrEFsyj6epVuSdNijMollk1TXVfzsipTG4IaJaLK1CHKypyrFpilzUKiwaES6puJ8pTfnfjkhpDG6IqBZLhkdUsN91ohqLnOJ+NTX1fzsiJTGhmIhqkTs84u/lioTHuzjtdG85qq8o/u2vOfgo5TyEOsb3VABeGtQBPh6u+DLtUpOYYUZkbSpBqOtj53wKCwuh0WhQUFAAX19fWzeHyC7p9AL6L9uH3ILyOvNu/DxdMbFfKKYNCuPF2IzdJ3IwdYu8mVQs7EdUm5zrN4eliKgWcXozALM5JLNiwnBsfixmxHRkYFOHoZHBWCdzqIqF/YgahsENERnR6QWkZF3Hrdt6zIzpiKAaM4CCNR5YN7YHgxoZxHWo/jMpCn6ervXuL/aWxe/M4NpTRBZgzg0RGSSl5yB+Z4bRTCmNRzP8pUdr9AtrCa0v80Es5aJWQa1W4WaZtHW5WNiPyHLsuSEiAHeK9tWcAl5Qfhufpl5C/M5fUVBWwcCmASyZhcbCfkTyMbghIklF+26WVjIPpIEsKdLHwn5E8lkc3FRUVODUqVO4ffu2ku0hIhuQWrRPAPNAGkJcZFNK35cKLOxHZCnZwU1paSkmTZoELy8vdO7cGRcuXAAAvPTSS1i6dKniDSQi65Mz9CHmgZB8UmahiQQAQyOq6uUwmCSSR3ZwM2/ePPzyyy84cOAAPDzudJfGxMRg+/btijaOiKxLnBl1Jq9I1nHMA7GcWMVYW8fUcDGtaf2hcxjz/hH0X7aPw4FEMsieLfXFF19g+/bt6NOnD1SqO/cenTt3RlZWlqKNIyLrMTUzSirmgTRM9SrGV4rK0cLbHVAByZl52HDoHGp21Ih1b94d24OF/YgkkB3cXL16FYGBgbW2l5SUGAU7RGS/xJlRcgc7VAC0zANRhItaZTTFW6cXMPuTX0zuK6Dq3z5+ZwZiw7WcsUZUD9nDUr169cKuXbsMv4sBzQcffIDo6GjlWkZEitPpBRw6cw1zPztpUWADcIFHa6kvqbt63Rsiqpvsnps33ngDjzzyCDIyMnD79m2sWbMGGRkZOHz4ML7//ntrtJGIFCB3GEoFGAVAWq53ZFVS85iY70RUP9k9N/3790daWhpu376NLl264LvvvkNgYCBSUlLQs2dPa7SRiBrIXIG+uoiBzaR+odg6uQ8OzhnEwMaKpOYxnc4tQkrWdc6gIqoDVwUncnLiCt+WJA6LOTYH5wziUJSV7T5xGdO2Hq+VTGwOVw6npkbO9duitaX0ej3Onj2LK1euQK/XGz32wAMPWPKURGQlUgv0mcL1jRpHUnoOXtxyXFYeVA5nUBGZJTu4OXLkCJ566imcP38eNTt9VCoVdDqdYo0jooZTIkeDeR7WI2Xpi7pwBhVRbbJzbl544QX06tUL6enpyM/Px40bNww/+fnM4ieyN0rUpGFdG+tRqmeNiO6Q3XNz5swZfPrpp+jQoYM12kNEChPXM8otKGddGzvEnjUi5cnuuYmKisLZs2et0RYispIn77+HdW3sFHvWiJQnu+fmpZdewssvv4zc3Fx06dIFrq6uRo9HRkYq1jgispxOLyBx31l8eCgbN8sqZR/PujaNgz1rRMqTPRVcra7d2aNSqSAIgkMkFHMqODUFSek5mLvjJG6WygtqArxdMf/RztD6Vl0w2WPTOMQ6RABkBzjvPNUdQyNbKd8oIjtj1ang2dnZFjeMiKwvKT0HL/zvQilXfkkltL4enPbdyMSVwmtWkPbzquoZrytIXbIrE2q1ij1sRNXIDm7atGljjXYQkQLEacUNweRU26i5Unigz53hpqPZ+fju1xx8ePh8reO4YjhRbRYV8cvKysLq1auRmZkJAAgPD8eMGTPQvn17RRtHRPI0ZFqxiMmptlNzpXBR77YBiPs4zeQxXDGcqDbZs6W+/fZbhIeH4+jRo4iMjERkZCR++ukndO7cGXv27LFGG4lIoob0uqhQVdKfyan2hyuGE8kju+dm7ty5mDVrFpYuXVpr+5w5cxAbG6tY44hIHkt7XTjt275xxXAieWT33GRmZmLSpEm1tj/77LPIyGjYWD8RNUzvtgHQ+soPcLQaD+Zs2DGpQSuHFImqyO65admyJdLS0hAWFma0PS0tDYGBgYo1jIjk25ORi/LbdZdj8PdyxesjI+Dv7W6UuMoeG/slpRaOWgXcKKlo1HYR2SvZwc3kyZPx/PPP4/fff0ffvn0BAIcOHcKyZcsQFxeneAOJSBqxVoq5i5+3mwuef6Adpg0KYyDjYFzUKiwcHm6ohWOKXgCmbknFrCthCG3hzaCVmjTZRfwEQcDq1auxYsUKXL58GQDQqlUrvPLKK5g+fTpUKvv+ILGIHzkjnV5A/2X76kw61fq649Dch3ixc2C7T1zGtK3HoZf4rR3MKtPkRORcv2Xn3KhUKsyaNQsXL15EQUEBCgoKcPHiRcyYMcPuAxsiZyVlCnhu4S3OpnFw/t7ukgMboGoG1QubU7H7xGXrNYrIDskObqrz8fGBj4+PUm0hIgtxNk3TYOn7N23rcew+kaNwa4jsV4OCGyKyD5xN0zRY+v6J+ThJ6QxwqGlgcEPkBMTZNOYGhlmgzznU9z7XJ35nBnRyxrWIHBSDGyInIM6mAVDrwscCfc6jrvdZClYxpqaiQcFNeXnDx+/Xrl2L0NBQeHh4ICoqCkePHq1z/9WrV6NTp07w9PRESEgIZs2apUg7iByRTi8gJes6vky7BI2nG9Y+1QNajfHQBQv0ORdxBfGa77NUzLuipkB2nRu9Xo/XX38d69atQ15eHk6fPo127dph/vz5CA0NNVm92Jzt27cjLi4O69atQ1RUFFavXo3Bgwfj1KlTJgsCbtmyBXPnzsWGDRvQt29fnD59GhMmTIBKpcLKlSvlngqRw9LpBSTuO4sPD2XjZlmlYXuwxgPzh93HAn1ObkhEMAbdG4Q+CcnIl1m4j3lX1BTI7rl57bXXsHHjRixfvhxubm6G7REREfjggw9kPdfKlSsxefJkTJw4EeHh4Vi3bh28vLywYcMGk/sfPnwY/fr1w1NPPYXQ0FA8/PDDGDNmTJ29Pbdu3UJhYaHRD5EjS0rPQc/X9mDV3tNGgQ1QNewwdctxHM2+jkcjWyG6/V0MbJzUsfM3ZAU2zLuipkR2cLNp0ya89957ePrpp+Hi4mLY3rVrV/z222+Sn6eiogLHjh1DTEzMncao1YiJiUFKSorJY/r27Ytjx44Zgpnff/8du3fvxtChQ82+TkJCAjQajeEnJCREchuJ7IU4/LR45694YXMqbpZW1rn/qr1n0G/pPs6OcWJyhpeYd0VNjexhqUuXLqFDhw61tuv1elRW1v2FW921a9eg0+kQFBRktD0oKMhskPTUU0/h2rVr6N+/PwRBwO3bt/HCCy/gH//4h9nXmTdvntGyEIWFhQxwyKEkpecgfmdGvUX6asotLMeUzanMt3FScoaXtKxUTE2M7J6b8PBw/Pjjj7W2f/rpp+jevbsijTLnwIEDeOONN/DOO+8gNTUVO3bswK5du7BkyRKzx7i7u8PX19foh8hRiOtFyQ1squP0X+ckZVq4n6cr/vNcFA7OGYTYcK0h+Twl6zr/Jsipye65WbBgAcaPH49Lly5Br9djx44dOHXqFDZt2oSvv/5a8vO0aNECLi4uyMvLM9qel5cHrVZr8pj58+fjmWeewXPPPQcA6NKlC0pKSvD888/j//7v/6BWc2Y7OQ+dXkD8zgyzC2FKIeDO9N/o9ncp1TSyA9UX01QBRn8nYsCz9M9d0K9DC5O9f1x3ipyZ7Gjgsccew86dO7F37154e3tjwYIFyMzMxM6dOxEbGyv5edzc3NCzZ08kJycbtun1eiQnJyM6OtrkMaWlpbUCGDHvR+b6n0R2T8p6UVJx+q9zMjctvPr0f3O9f7kFVcOWzMsiZyS75wYABgwYgD179jT4xePi4jB+/Hj06tULvXv3xurVq1FSUoKJEycCAMaNG4fWrVsjISEBADB8+HCsXLkS3bt3R1RUFM6ePYv58+dj+PDhRsnNRM5AyYCE03+d15CIYMSGa3E0O7/W9P+6ev8EVPXwxO/MQGy4lonG5FQsCm4A4Oeff0ZmZiaAqjycnj17yn6O0aNH4+rVq1iwYAFyc3PRrVs3JCUlGZKML1y4YNRT8+qrr0KlUuHVV1/FpUuX0LJlSwwfPhyvv/66padBZLeUCEhUqLqL5/Rf5+aiVpkcdqyv94/DluSsVILM8ZyLFy9izJgxOHToEPz8/AAAN2/eRN++fbFt2zbcfffd1minYgoLC6HRaFBQUMDkYrJrOr2A/sv2WTw0Jd6Hc7ZU0/Vl2iXM2JZW735rnuyGx7q1tn6DiBpAzvVbds7Nc889h8rKSmRmZiI/Px/5+fnIzMyEXq83JPoSUcNVX0eoPn6ezaD15bILZKxFc3dJ+527VmrllhA1Ltk9N56enjh8+HCtad/Hjh3DgAEDUFpq3x8S9tyQo0lKz8HcHSdNFu6r3jtjLu+Cmqak9Bws+upX5BbeqndfFdjDR/ZPzvVbds5NSEiIyWJ9Op0OrVq1kvt0RFQPMWHU1FpSNYuzMW+CgDv1keTcuTKxmJyJ7ODmzTffxEsvvYS1a9eiV69eAKqSi2fMmIG33npL8QYSUdUQ1YyYMEwb1IG9M1QnS+ojMbGYnI2k4Mbf3x8q1Z0v0JKSEkRFRaFZs6rDb9++jWbNmuHZZ5/FyJEjrdJQIjI/K4ZI1JD6SKyHRM5CUnCzevVqKzeDiIiU0JAAhfWQyFlICm7Gjx9v7XYQEZECLAlQWA+JnA0XYyIiciJSFtSsSQAwf9h9zN8ip8HghshO6fQCV3Em2arXR5ITqizZlcl1pshpyK5z4+hY54YcAVdxpoYy9zf0aGQw3v8xu9b+rGhN9k7O9ZvBDZGdMVejhBcfkkunF4xKB/Rs44+Bb+43O5tKzL05OGcQh6jI7li1iF91Fy9eBAC7X0+KyBHo9AKOZF3HnM9OchVnUkTN0gEpWde5kCY1CbJzbvR6PRYvXgyNRoM2bdqgTZs28PPzw5IlS6DX663RRiKnl5Seg/7L9uHp9T+hoKx2BXBR9YsPkVxSp4mz3g05Otk9N//3f/+H9evXY+nSpejXrx8A4ODBg1i0aBHKy8vx+uuvK95IImdmSal8XnzIElKnibPeDTk62cHNRx99hA8++AAjRowwbIuMjETr1q0xdepUBjdEMlhSKh/gxYcsI04Tzy0oN/s35+/litzCcqRkXefyHuSwZA9L5efn49577621/d5770V+PrvKieSwpFR+MIutkYWkTBO/UVqJWdvTMOb9I+i/bB+nh5NDkh3cdO3aFYmJibW2JyYmomvXroo0iqipsGR4aeHwcN5Nk8WGRATj3bE9oPFyrXff3IJyTNmcygCHHI7sYanly5dj2LBh2Lt3L6KjowEAKSkp+OOPP7B7927FG0jkzOQOL82K6chp4NRgseFaLPoqA4D55HWAM/TIccnuuRk4cCBOnz6NUaNG4ebNm7h58yYef/xxnDp1CgMGDLBGG4mclpgDIYXW1x3TBnWwcouoKTianY/cQmm9huIMvY2HslklmxyG7CJ+Fy5cQEhICFSq2hH8hQsXcM899yjWOGtgET+yN1JmS6nA4n2knC/TLmHGtjTZx7FKNtmSnOu37J6btm3b4urVq7W2X79+HW3btpX7dERNnpgDYa4HJ1jjwcCGFGXpbLsc5uCQg5CdcyMIgslem+LiYnh4cHoqkSWGRAQjNlxbNVxQUIb8kgoENHeH1teD03FJcVKmhNeFOThk7yQHN3FxcQAAlUqF+fPnw8vLy/CYTqfDTz/9hG7duineQKKmomapfCJrEaeET9mcChUgK8DhEg3kCCQHN8ePHwdQ1XNz8uRJuLm5GR5zc3ND165dMXv2bOVbSEREihOHQ2uuHC4Vq2STPZMc3Ozfvx8AMHHiRKxZs4bJuEQNUH215hbe7oAKuFZ8C4E+HIaixlN9OPTQ2atI3J8l+VhWySZ7Jjvn5sMPP7RGO4iajKT0nDrvljkjhRqTOBzau20APku9VG8vjgqAllWyyc7Jni1FRJYTp33XdQFhVViyBTEPR0qfIatkk71jcEPUSKQukik+Hr8zg0XTqFGxLAE5C9nDUkRkGTmLZHJGCtkKyxKQM2BwQ9RILJldwhkpZAt1lSWongzPBHiyV5KCm6+++kryE44YMcLixhA5M0tml3BGCtkTU8nwTIAneyQpuBk5cqTR7yqVCtWXpKpesVin0ynTMiIn07ttALS+HpIWLOSMFLI35tZAExPgmYtD9kRSQrFerzf8fPfdd+jWrRu++eYbw6rgu3fvRo8ePZCUlGTt9hI5rD0ZuSi/XX/wL94qcEYK2Yu6kuGZAE/2SHbOzcyZM7Fu3Tr079/fsG3w4MHw8vLC888/j8zMTEUbSOQMpKz8LdKym5/sTH3J8EyAJ3sjO7jJysqCn59fre0ajQbnzp1ToElEzkWnF7Doq7qngPt7uWLB8M6ckUJ2SWpiOxPgyV7IrnNz//33Iy4uDnl5eYZteXl5eOWVV9C7d29FG0fkDBL3nak3z+ZGaSW0vh6Ibn8XAxuyO1IT25kAT/ZCds/Nhg0bMGrUKNxzzz0ICQkBAPzxxx8ICwvDF198oXT7iByGqSmyezJysWrvGUnH866X7FXvtgEI1nggt6DcZA8kE+DJ3sgObjp06IATJ05gz549+O233wAA9913H2JiYoxmTRE1JaamyGp93VF+Wy/5OXjXS/ZKXJphyuZUqACjAIcJ8GSPVEL1Od0ylZeXw93d3aGCmsLCQmg0GhQUFHBlc1KEnGRhc4I1Hjg4ZxAvDmTXWOeGbEnO9Vt2z41er8frr7+OdevWIS8vD6dPn0a7du0wf/58hIaGYtKkSRY3nMjRSF0vqj686yVHUH1pBlYoJnsmO6H4tddew8aNG7F8+XK4ubkZtkdEROCDDz5QtHFE9k7OelHmzIrpyLtesns6vYCUrOv4+sRlAMCjka2YAE92S3bPzaZNm/Dee+/hoYcewgsvvGDY3rVrV0MODlFT0dAkYK2vO6YN6qBQa4isg8NR5Ghk99xcunQJHTrU/jLW6/WorKxUpFFEjsLSJGDV/34WjejMO1+ya2JOWc0eSnHZhaT0HBu1jMg82cFNeHg4fvzxx1rbP/30U3Tv3l2RRhE5CnGKrLnwRAXAz8sVWl/jIEir8eBaPGT3uOwCOSrZw1ILFizA+PHjcenSJej1euzYsQOnTp3Cpk2b8PXXX1ujjUR2S8oU2aWPd2ESJjkkqcsubDyUjQn92vJvmuyG7J6bxx57DDt37sTevXvh7e2NBQsWIDMzEzt37kRsbKw12khk14ZEBOPdsT2g1Rj3zmg8XTEzJgyx4Vq4qFWIbn8XHuvWmkmY5DCk5pQt2ZWJ/sv2cYiK7IasOje3b9/GG2+8gWeffRZ33323NdtlNaxzQ9ai0wtI3HcWHx7Kxs2yO/lnTLwkR5WSdR1j3j8i65h3nuqOoZGtrNQiasrkXL9l9dw0a9YMy5cvx+3btxvUQCJntCcjF6v3njYKbICqbvsXNqdizd7TzE0gh1JfTpkp07Yex+4T7MEh25I9LPXQQw/h+++/t0ZbiByWlGJ+q/aeQb+l7LonxyHmlAGQHODoBWDqFs6iItuSnVD8yCOPYO7cuTh58iR69uwJb29vo8dHjBihWOOIHIXUYn65hVXTZzlTihyFmFNWs85NfeJ3ZhjyzYgam+y1pdRq8509KpUKOp2uwY2yJubckDV8mXYJM7alSdpXXEGZa0mRI9HpBWw8lI0luzIlH7N1ch9Et7/Liq2ipsRqOTdAVbE+cz/2HtgQWYucYn7i9Nmj2fnWaxCRwlzUKkzo1xbBGul/67kFZVZsEZF5soMbIqrNksTLhi7dQNTYqufgSLFkVyZzb8gmZOfcLF68uM7HFyxYYHFjiByRTi/gaHY+HonQYsOhc5KPs3TpBiJbGhIRjHee6o5pW4+jvsl/N0oqmGNGNiE756bmEguVlZXIzs5Gs2bN0L59e6SmpiraQKUx54aUZGpBwZqVimtizg05g90ncjB1S/3f9/x7J6XIuX7L7rk5fvy4yRecMGECRo0aJffpiByWuKBgzUCmvsAGABYOD+cXPTm0oZHBWKfugX98fhL5JeYXTeYSDWQLiuTc+Pr6Ij4+HvPnz5d97Nq1axEaGgoPDw9ERUXh6NGjde5/8+ZNvPjiiwgODoa7uzs6duyI3bt3W9p0IovUV9eGC2ZSUzAkIhjzH+0saV8u0UCNSXbPjTkFBQUoKCiQdcz27dsRFxeHdevWISoqCqtXr8bgwYNx6tQpBAYG1tq/oqICsbGxCAwMxKefforWrVvj/Pnz8PPzU+gsiKSRsqDgzdJK/GdSD6jVKi6YSU6rZgBfl9wC1nmixiE7uHn77beNfhcEATk5Ofj3v/+NRx55RNZzrVy5EpMnT8bEiRMBAOvWrcOuXbuwYcMGzJ07t9b+GzZsQH5+Pg4fPgxXV1cAQGhoaJ2vcevWLdy6dcvwe2Fhoaw2EpkidabTtZJbeKxbayu3hsh2xJmCuQXldQ7JAlVBvwos8EfWJzu4WbVqldHvarUaLVu2xPjx4zFv3jzJz1NRUYFjx44ZHaNWqxETE4OUlBSTx3z11VeIjo7Giy++iC+//BItW7bEU089hTlz5sDFxcXkMQkJCYiPj5fcLiIppM504owocnbi9PApm1PrTaYHjOs8scAfWYvs4CY7O1uRF7527Rp0Oh2CgoKMtgcFBeG3334zeczvv/+Offv24emnn8bu3btx9uxZTJ06FZWVlVi4cKHJY+bNm4e4uDjD74WFhQgJCVHkHKjpqu9uVZwh0rttQGM3jajRWbJEA+s8kTU1OKG4sLAQX3zxBTIzpZfktpRer0dgYCDee+899OzZE6NHj8b//d//Yd26dWaPcXd3h6+vr9EPUUPVtaAgZ0RRUzQkIhjzh0kv8MdeTbIm2cHNE088gcTERABAWVkZevXqhSeeeAKRkZH47LPPJD9PixYt4OLigry8PKPteXl50Gq1Jo8JDg5Gx44djYag7rvvPuTm5qKiokLuqRA1iHi3qtVwRhSRTi9gya6MevdTAQhmryZZmezg5ocffsCAAQMAAJ9//jkEQcDNmzfx9ttv47XXXpP8PG5ubujZsyeSk5MN2/R6PZKTkxEdHW3ymH79+uHs2bPQ6/WGbadPn0ZwcDDc3NzkngqRxXR6ASlZ13Hrth5v/aUr/vNcFNY82Q1bJ/fBwTmDGNhQk1PfDEKRAPZqkvXJzrkpKChAQEBVxJ2UlIQ///nP8PLywrBhw/DKK6/Ieq64uDiMHz8evXr1Qu/evbF69WqUlJQYZk+NGzcOrVu3RkJCAgBgypQpSExMxIwZM/DSSy/hzJkzeOONNzB9+nS5p0FkMVNViYM1Hlg4PJwJktRkSc2heSQiCLHhpnvniZQiu+cmJCQEKSkpKCkpQVJSEh5++GEAwI0bN+DhIW8MdfTo0XjrrbewYMECdOvWDWlpaUhKSjIkGV+4cAE5OXcKPoWEhODbb7/Ff//7X0RGRmL69OmYMWOGyWnjRNYgViWueYcq1u9ggTJqqqTm0HyTnsdifmR1steWeueddzBjxgw0b94cbdq0QWpqKtRqNf75z39ix44d2L9/v7XaqgiuLUWW0ukF9F+2z2zXO9fQoaZM/HxIqXcjfjqYm0ZyyLl+y+65mTp1Ko4cOYINGzbg4MGDUKurnqJdu3aycm6IHI2UqsRi/Q6ipqauGYQ1icFP/M4M6OpbWpzIAhZNBe/ZsydGjRqF5s2bG7YNGzYM/fr1U6xhRPZmb0aupP1Yv4OaKnMzCE3hzQBZk0VrS128eBFfffUVLly4UGsK9sqVKxVpGJE9SUrPwfpD5yTty/od1JQNiQhGbLgWq/acRuL+s/Xuz5sBsgbZwU1ycjJGjBiBdu3a4bfffkNERATOnTsHQRDQo0cPa7SRyKbEFcDrw6rERFVc1Cr069BCUnDDmwGyBtnDUvPmzcPs2bNx8uRJeHh44LPPPsMff/yBgQMH4q9//as12khkU6zfQSSfuERJXZ+GAG9X9Gzj32htoqZDdnCTmZmJcePGAQCaNWuGsrIyNG/eHIsXL8ayZcsUbyCRrUntNn+2XyhnfhD9j5QE4/ySSgx8cz+nhZPiZAc33t7ehjyb4OBgZGVlGR67du2aci0jsgM6vYAfT0v7u2ZhMiJjUhKMWSOKrEF2zk2fPn1w8OBB3HfffRg6dChefvllnDx5Ejt27ECfPn2s0UYim0hKz8HcHSdxs7Syzv2Ya0Nk3pCIYAy6Nwh9EpKRX1J7DUABVZ+h+J0ZiA3XcliXFCE7uFm5ciWKi4sBAPHx8SguLsb27dsRFhbGmVLkNJLSc/DC5lTJ+zPXhsi8Y+dvmAxsRNWnhXMJE1KC7OCmXbt2hv/39vbGunXrFG0Qka1V3NbjH5+nS95/ZkxH5toQ1UFq3hqnhZNSLCrid/PmTXzwwQeYN28e8vOrCjClpqbi0qVLijaOqLElpeegT8LeOu8yawpt4WXFFhE5PqnTvTktnJQiu+fmxIkTiImJgUajwblz5zB58mQEBARgx44duHDhAjZt2mSNdhJZnbgoptxi8PxCJqqbOC3c3LpTzFsjpcnuuYmLi8OECRNw5swZo1XAhw4dih9++EHRxhE1FrFQn9zAJphfyET1qmtauPg789ZISbKDm//+97/429/+Vmt769atkZsrbe0dInsjtVBfdSrwC5lIKnPTwrUaD64OToqTPSzl7u6OwsLCWttPnz6Nli1bKtIoosYmN5HR38sVCY934RcykQziulNHs/NxpagcgT5VPZ+8QSClyQ5uRowYgcWLF+Pjjz8GAKhUKly4cAFz5szBn//8Z8UbSNQYpObNNHd3weQB7TBtUBi/kIks4KJWcbo3WZ3sYakVK1aguLgYgYGBKCsrw8CBA9GhQwf4+Pjg9ddft0YbiaxO6jo4qfMfxoyYjgxsiBSi0wtIybqOL9MuISXrOnR6uZlvRLXJ7rnRaDTYs2cPDh48iBMnTqC4uBg9evRATEyMNdpH1Chc1CrMHxaOqVtqF+4Tw5g3RnWBWzOLqicQkQlJ6TmI35lhlO8WrPHAwuHhHPKlBlEJgtCkwuTCwkJoNBoUFBTA19fX1s0hO2HqS1bEL1si5e0+kVPnzQSTjKkmOddv2T03QNWMqf379+PKlSvQ6/VGj3EJBnI09dW3mT/sPn7JEilo94nLmLb1uMnHuNYUKUF2cPPGG2/g1VdfRadOnRAUFASV6s4fXvX/J3IE9dW3UQFYsisTgyOC+SVLpICk9BxM3WI6sBFxrSlqKNnBzZo1a7BhwwZMmDDBCs0halz11bfhlyyRcsSbCam41hRZSnZ2pFqtRr9+/azRFqJGxwX9iBqP3GKZZ/KKOYOKLCI7uJk1axbWrl1rjbYQNTou6EfUeOTeJCTuP4sx7x9B/2X7kJSeY6VWkTOSPSw1e/ZsDBs2DO3bt0d4eDhcXV2NHt+xY4dijSOyNi7oR9R4LL1JyC0ox5TNqZxBRZLJ7rmZPn069u/fj44dO+Kuu+6CRqMx+iFyJFzQj6jxSCmWaYp44xG/M4NDVCSJ7Do3Pj4+2LZtG4YNG2atNlkV69yQKSwmRtQ4xNILAMzOUqzL1sl9mNzfRFm1zk1AQADat29vceOI7BEX9CNqHOLq4OaKZtaHyf0khexhqUWLFmHhwoUoLS21RnuIGp24ts3XJy4DAB6NbIXo9ncxsCGykiERwTg4ZxDmD7tP9rFM7icpZPfcvP3228jKykJQUBBCQ0NrJRSnptYup01krzgcRWQbLmoVWvi4S96fyf0kh+zgZuTIkVZoBlHj0OkFw9DTuWulWL33dK1xf87MIGoccnthmNxPUskObhYuXGiNdhBZXV2LY1bHtW2IGkd9pRhEfp6umNgvFLHh2kZrGzk22Tk3RI5InKEhNYGx+rILRGQddZViqO5mWSVW7T3DYn4kGYMbcnr1LY5ZF87MILIucfaUVlP/EJU4ZMwAh+oje1iKyNHIXc+mOs7MILK+6qUYcgvKsGRXJvJLKmrtJ96gLPrqVw4ZU53Yc0NOz5LeFxWqZk1xZgZR43BRqxDd/i5oNZ4mA5vqcgtvIXHf2UZqGTki2cHN4sWLTda4KSsrw+LFixVpFJGS5Pa+cNkFItuRejOyau9pDk+RWbKDm/j4eBQXF9faXlpaivj4eEUaRaQkuevZaDUenAZOZCNybkb+8flJfH78ElKyrnPNKTIiO+dGEASoVLUvE7/88gsCAtiFT/ZHnJExZXMqVDC/no043XTaoDD22BDZiHgzIiVPLr+kErO2pwFg8U0yJrnnxt/fHwEBAVCpVOjYsSMCAgIMPxqNBrGxsXjiiSes2VYii0mZkVFQVonVe89gT0ZuI7aMiKqrPj1cDs6kouokrwr+0UcfQRAEPPvss1i9ejU0Go3hMTc3N4SGhiI6OtpqDVUKVwVvmsTKxJdvlGLR1xkoKr9tcj+xxPvBOYPYe0NkQ2v2nsaqvWdkHcPPr3Ozyqrg48ePBwC0bdsWffv2rbWmFJG9klqZGDAu3hfd/i7rN46ITJo2KAxbj/6B3ELpsx35+SWRpGGpwsJCw/93794dZWVlKCwsNPlDZE/kViYWsXgfkW25qFVYNCJc8kSA6vj5JUk9N/7+/sjJyUFgYCD8/PxMJhSLicY6nU7xRhJZoiGViVm8j8j2xFy5f3x+EvkllZKP4+eXJAU3+/btM8yE2r9/v1UbRKQUSyoTi2P2LN5HZB+GRASjrFJvmBVVHxbfJEBicDNw4ECT/09kz+R2TbN4H5F90vpK74nh55cAC9eWunHjBtavX4/MzEwAQHh4OCZOnMg6N2RX5HZNa1kng8guibVvcgvKzQ4zq1VA4hgW36QqsisU//DDDwgNDcXbb7+NGzdu4MaNG3j77bfRtm1b/PDDD9ZoI5FFpFQmDvB2xarR3bB1ch8cnDOIX4xEdqh67Rtzn+fEMd0xNJKfX6oiuc6NqEuXLoiOjsa7774LFxcXAIBOp8PUqVNx+PBhnDx50ioNVQrr3DQt4mwpwLgysfgFyWUWiByHqbIOrEzcdMi5fssObjw9PZGWloZOnToZbT916hS6deuGsrIy+S1uRAxumhadXkDivrP48FA2bpbdmW3BL0QixyQW5LxSVI5An6rkYebYNA1WKeIn6tGjBzIzM2sFN5mZmejatavcpyOyGlN3eVw/isixuahVRgX6dHoBKVnXGeyQEUnBzYkTJwz/P336dMyYMQNnz55Fnz59AABHjhzB2rVrsXTpUuu0kkgmcTiqZrekuH5UJ60Pe22IHByHqcgcScNSarUaKpUK9e3qCEX8OCzl/HR6Af2X7TNb44brzxA5PnM3MMync16KD0tlZ2cr0jCixlBf8T6uP0Pk2OqqPi6gKsCJ35mB2HAtb2CaKEnBTZs2bazdDiLFSC3ex/VniBwTb2CoPrITijdt2lTn4+PGjbO4MURKkFq8j+vPEDkm3sBQfWQHNzNmzDD6vbKyEqWlpXBzc4OXl5dFwc3atWvx5ptvIjc3F127dsU///lP9O7du97jtm3bhjFjxuCxxx7DF198Ift1yTndKLkFtQrQm0kR4/pRRI6NNzBUH9kVisWqxOJPcXExTp06hf79+2Pr1q2yG7B9+3bExcVh4cKFSE1NRdeuXTF48GBcuXKlzuPOnTuH2bNnY8CAAbJfk5xXUnoOXtxy3GxgI+L6M0SOS2r18dzCcqRkXYeuvi8Ecjqyi/iZ8/PPP2Ps2LH47bffZB0XFRWF+++/H4mJiQAAvV6PkJAQvPTSS5g7d67JY3Q6HR544AE8++yz+PHHH3Hz5k3JPTecLeW86pslBdxZf4Zl2okcm7nq46ZwerhzkHP9lt1zY06zZs1w+fJlWcdUVFTg2LFjiImJudMgtRoxMTFISUkxe9zixYsRGBiISZMm1fsat27dQmFhodEPOaf6kgyBqqEqf2+3RmoREVnLkIhgvDu2B7Sa+oeecgvKMWVzKpLScxqhZWQPZOfcfPXVV0a/C4KAnJwcJCYmol+/frKe69q1a9DpdAgKCjLaHhQUZLYH6ODBg1i/fj3S0tIkvUZCQgLi4+NltYscE5MMiZqWIRHBiA3X4mh2Pi7fKMWirzNQVH671n5iz86ir37l9PAmQnZwM3LkSKPfVSoVWrZsiUGDBmHFihVKtcukoqIiPPPMM3j//ffRokULScfMmzcPcXFxht8LCwsREhJirSaSDTHJkKjpcVGrUFBWgde/yTQZ2FSXW3gLifvOYkZMWCO1jmxFdnCj1+sVe/EWLVrAxcUFeXl5Rtvz8vKg1Wpr7Z+VlYVz585h+PDhtdrTrFkznDp1Cu3btzc6xt3dHe7u7oq1mexXzzb+CPB2Q35JhcnHOUuKyPmYq1Rszqq9p9FJ25z5N05OsZwbS7i5uaFnz55ITk42bNPr9UhOTkZ0dHSt/e+9916cPHkSaWlphp8RI0bgwQcfRFpaGntkmiidXsCavWfQ+/W9dQY2AGdJETmTuioV1yV+ZwZnUDk52T031Yd46rNy5UpJzzd+/Hj06tULvXv3xurVq1FSUoKJEycCqCoK2Lp1ayQkJMDDwwMRERFGx/v5+QFAre3UNCSl52DujpO4WVpZ535azpYgcjpSJhGYwurFzk92cHP8+HEcP34clZWV6NSpEwDg9OnTcHFxQY8ePQz7qVTS7o5Hjx6Nq1evYsGCBcjNzUW3bt2QlJRkSDK+cOEC1GqbdjCRnUpKz8EL/5sKWpcAb1d8/8qDcGvGvyMiZ9KQyQGcWODcZAc3w4cPh4+PDz766CP4+/sDqCrsN3HiRAwYMAAvv/yy7EZMmzYN06ZNM/nYgQMH6jx248aNsl+PHJ/YHS1Ffkkljp2/wbs0IifTkMkBnFjg3GTfyq5YsQIJCQmGwAYA/P398dprr1l9thSRSG53NO/SiJyPlErFpmh93TmxwMnJDm4KCwtx9erVWtuvXr2KoqIiRRpFVB+5wQrv0oicj4tahYXDwwFAVoBTfluPPRm51mkU2QXZwc2oUaMwceJE7NixAxcvXsTFixfx2WefYdKkSXj88cet0UaiWuQEK8Gc/k3ktMxVKvbzcoWXm4vJYwpKK1mx2MnJzrlZt24dZs+ejaeeegqVlVUzVJo1a4ZJkybhzTffVLyBRKaI3dG5BeV1TgNVgdO/iZxd9UrFV4rKEejjgZ5t/PHA8v0ordDV2p8Vi52fxQtnlpSUICsrCwDQvn17eHt7K9owa+HCmc6jvoXz/L1ckfB4F07/JmqCUrKuY8z7R+rdb1ZMR1YsdhByrt+ye25E3t7eiIyMtPRwogYTu6Pjd2YYJRf7ebpiYr9QTBsUxjsyoiZKal4eKxY7J4uDGyJb0+kFaDzd8PfBnZBfUoGA5u7Q+lbl1zCoIWra5OTlxe/M4PCUk2FwQw4pKT2nVo9N8P+qEPMLiojEvDwpJSNyCspxJOs6+oVJW5CZ7B9LtpLDEXNtan5p5RaUcwYEEQEwniYuxYtb+N3hTCQFNz169MCNGzcAAIsXL0ZpaalVG0VkTl0L5YnbuCgeEQFVeXmzJCYL3yzj9HBnIim4yczMRElJCQAgPj4excXFVm0UkTn1VSYWcGdRPCKiaYPCoPWVl3/DmyPHJynnplu3bpg4cSL69+8PQRDw1ltvoXnz5ib3XbBggaINJKout1DaDAgut0BEQNXw1KIR4ZiyObXOmliA8c0R16JzbJKCm40bN2LhwoX4+uuvoVKp8M0336BZs9qHqlQqBjdkNUnpOVjy9a+S9uVyC0QkEstGzP3sJG6WVda7P2+OHJ+k4KZTp07Ytm0bAECtViM5ORmBgYFWbRhRdWIScX13XioAWi63QEQ1DIkIho+HK57+4Kd69+XNkeOTPRVcr9dbox1EZtWVRFydOAGc08GJyJQ+7e6qc9kW3hw5D4umgmdlZeGll15CTEwMYmJiMH36dMNSDERKqy+JWBTg7YZ3x/ZgpVEiMqmuVcR5c+RcZAc33377LcLDw3H06FFERkYiMjISP/30Ezp37ow9e/ZYo43UBOn0AlKyruPLtEs4dPaapGNeHXYfAxsiqpO5VcS1Gg/eHDkR2Qtndu/eHYMHD8bSpUuNts+dOxffffcdUlNTFW2g0rhwpv0zVX1Yiq2T+3CGAxFJotMLRquIc9kW+yfn+i07uPHw8MDJkycRFmZcGOn06dOIjIxEebl9Z5kzuLFvUhOHqxPHyQ/OGcQvJyIiJyXn+i17WKply5ZIS0urtT0tLY0zqKhBpCYOm8JxciIiEsmeLTV58mQ8//zz+P3339G3b18AwKFDh7Bs2TLExcUp3kBqOqQmDtc0M6Yjx8mJSBEcrnIOsoOb+fPnw8fHBytWrMC8efMAAK1atcKiRYswffp0xRtITYelhbNCW3gp3BIiaopM5fsFazywcHg4b6AcjOxhKZVKhVmzZuHixYsoKChAQUEBLl68iBkzZkClYnRLlrO0cBYLbhFRQ4n5fjV7j3MLyrmgpgOyqM6NyMfHBz4+Pkq1hZq43m0DEKyRF6gEs+AWETVQXfl+4jYuqOlYGhTcECmpeoEtqZhITEQNodML2Hgou858v+oLapJjkJ1zQ2QtOr0AjacbHokIwjfpefXuP4uJxETUAHJranFBTcfB4IbsgtwvGa2vO6YN6mDlVhGRs7Kkphbz+xyH7GGp33//3RrtoCbMXCKfKar//Swa0ZnDUURkEbk1tVRgfp+jkR3cdOjQAQ8++CA2b95s99WIyf7J/ZLh+i9E1FByampxQU3HJDu4SU1NRWRkJOLi4qDVavG3v/0NR48etUbbqAmQ+iUz7cEO2Dq5Dw7OGcTAhogaRE7ujL+3K57tFwqNpxtnSzkQ2cFNt27dsGbNGly+fBkbNmxATk4O+vfvj4iICKxcuRJXr161RjvJSUn9kgkLao7o9nfxzomIGkxq7oynqwvySyqx/tA5jHn/CPov28d6Nw7C4qngzZo1w+OPP45PPvkEy5Ytw9mzZzF79myEhIRg3LhxyMnhHwDVT+qXDBP5iEgpYk2t+m6Vyip1Rr+zoJ/jsDi4+fnnnzF16lQEBwdj5cqVmD17NrKysrBnzx5cvnwZjz32mJLtJCdV35cME/mISGliTS25g0ws6Oc4ZAc3K1euRJcuXdC3b19cvnwZmzZtwvnz5/Haa6+hbdu2GDBgADZu3IjU1FRrtJecTPXCfTUDHCbyEZG1DIkIxqyYMNnHsaCfY5Ad3Lz77rt46qmncP78eXzxxRd49NFHoVYbP01gYCDWr1+vWCPJuQ2JCMa7Y3tAW2PpBc6MIiJrCm3hbfGxLOhn32QX8Ttz5ky9+7i5uWH8+PEWNYiapiERwYgN1+Jodj6uFJUj0KdqKIo9NkRkLQ3J5WMeoH2THdx8+OGHaN68Of76178abf/kk09QWlrKoIYs5qJWIbr9XbZuBhE1EWLOX25BuayCflrmAdo92cNSCQkJaNGiRa3tgYGBeOONNxRpFDUNOr2AlKzr+Dz1Itb/+Ds+P34JKVnXmahHRI2irpw/U5gH6Dhk99xcuHABbdu2rbW9TZs2uHDhgiKNIuem0wtI3HcWHx7Kxs2yylqPB2s8sHB4OHNtiMjqxJy/mmvb+Xm5AgBult75jtLyu8lhyA5uAgMDceLECYSGhhpt/+WXX3DXXRxSoLolpedg7o6TRl8YNeX8r5YEk4mJqDGYy/kDwDxAByU7uBkzZgymT58OHx8fPPDAAwCA77//HjNmzMCTTz6peAPJeSSl5+CFzdJLBMTvzEBsuJZfJkRkdeZy/pgH6JhkBzdLlizBuXPn8NBDD6FZs6rD9Xo9xo0bx5wbMktcIFOq6rUk+OVCRERyyA5u3NzcsH37dixZsgS//PILPD090aVLF7Rp08Ya7SMnIWcV3upYS4KIiOSSHdyIOnbsiI4dOyrZFnJilgYprCVBRERyyQ5udDodNm7ciOTkZFy5cgV6vd7o8X379inWOHIecoMU1pIgIiJLyQ5uZsyYgY0bN2LYsGGIiIiASsVkT6qfJcWyWEuCiOyJTi9w9pSDkB3cbNu2DR9//DGGDh1qjfaQkxKLZU3ZnAoVUGeAwzo3RGRvktJzatXC4XeV/bIoobhDhw7WaAs5OXPFsjQezRAbHoR+YS2h9eXdEBHZl6T0HEzZnFrrpiyXNbnslkoQBFm17lesWIHff/8diYmJDjkkVVhYCI1Gg4KCAvj6+tq6OU0Su3aJyFHo9AL6Ld2H3ELTkyLE/MDvX3kQx87f4PeaFcm5fsvuuTl48CD279+Pb775Bp07d4arq6vR4zt27JD7lNQEMKAhIkeUuO+M2cAGuFOTq09CMvJLKgzbOWRlW7KDGz8/P4waNcoabSEnZG4dKX7wicjeJaXnYNXeM5L2rR7YAByysjXZw1KOjsNSjaeudaTEPht+8InIHun0Avov22dR8VGROGR1cM4g9lQrQM71W23JC9y+fRt79+7Fv/71LxQVFQEALl++jOLiYkuejpyQuI6UuQUyxYg6fmcGdPomFV8TkQOwtKp6ddWXkaHGJXtY6vz58xgyZAguXLiAW7duITY2Fj4+Pli2bBlu3bqFdevWWaOd5ECkriPF9aOIyF4pufQLl5FpfLJ7bmbMmIFevXrhxo0b8PT0NGwfNWoUkpOTFW0cOSa5dzz84BORvVFy6RcuI9P4ZPfc/Pjjjzh8+DDc3NyMtoeGhuLSpUuKNYwcl9xghR98IrI3llRVr4nLyNiO7J4bvV4PnU5Xa/vFixfh4+NjUSPWrl2L0NBQeHh4ICoqCkePHjW77/vvv48BAwbA398f/v7+iImJqXN/anxygpVgfvCJyA6JVdWBOxMgLMFlZGxDdnDz8MMPY/Xq1YbfVSoViouLsXDhQouWZNi+fTvi4uKwcOFCpKamomvXrhg8eDCuXLlicv8DBw5gzJgx2L9/P1JSUhASEoKHH36YvUZ2RLzjqe/jrAI/+ERkv8Sq6lqN/N5ltQpY+xRng9qK7KngFy9exODBgyEIAs6cOYNevXrhzJkzaNGiBX744QcEBgbKakBUVBTuv/9+JCYmAqjqGQoJCcFLL72EuXPn1nu8TqeDv78/EhMTMW7cuHr351TwxrH7RA6mbkk1+7i/lysSHu/CDz4R2T2dXsDGQ9lYsitT1nFbJ/fhZAkFWbVC8d13341ffvkF27Ztw4kTJ1BcXIxJkybh6aefNkowlqKiogLHjh3DvHnzDNvUajViYmKQkpIi6TlKS0tRWVmJgADTQxu3bt3CrVu3DL8XFhbKaiPJl5SegyW7TM+W8vN0xcR+oZg2KIw9NkTkEFzUKrTwcZd9HCdL2I7s4AYAmjVrhrFjxzb4xa9duwadToegoCCj7UFBQfjtt98kPcecOXPQqlUrxMTEmHw8ISEB8fHxDW4rSWNugTnRG6MiMDSyVaO2iYiooSyZ+MDJErYjO7jZtGlTnY9LGRpSytKlS7Ft2zYcOHAAHh6m/4jmzZuHuLg4w++FhYUICQlprCY2KWJ9G3OBjQrAkl2ZGBwRzF4bInIocmZPcZaU7ckObmbMmGH0e2VlJUpLS+Hm5gYvLy9ZwU2LFi3g4uKCvLw8o+15eXnQarV1HvvWW29h6dKl2Lt3LyIjI83u5+7uDnd3+d2JVL+ai2HqBaHO+jYs2kdEjkqcPTVlcypUQJ03cQAMM61Ssq5zwWAbkB3c3Lhxo9a2M2fOYMqUKXjllVdkPZebmxt69uyJ5ORkjBw5EkBVQnFycjKmTZtm9rjly5fj9ddfx7fffotevXrJek1SRlJ6DuJ3ZhgFM16uLpKO5Tg0ETkicfZUze++6rT/WxQYQK21qbhgcONRbOHMn3/+GWPHjpWcKyPavn07xo8fj3/961/o3bs3Vq9ejY8//hi//fYbgoKCMG7cOLRu3RoJCQkAgGXLlmHBggXYsmUL+vXrZ3ie5s2bo3nz5vW+HmdLWaZ6L825a6VYvfe0xYWtOIOAiBxZ9e/DFt7ugAq4VnzL0DuzJyO3ztzDd57qztxDC1h1tpTZJ2rWDJcvX5Z93OjRo3H16lUsWLAAubm56NatG5KSkgxJxhcuXIBafaccz7vvvouKigr85S9/MXqehQsXYtGiRQ06BzLNVC+NJTgOTUTOwEWtMnuDVl/uIQBM23ociVBhaCR7cKxFds/NV199ZfS7IAjIyclBYmIiQkJC8M033yjaQKWx50ae+mY/yaEC8O5YFrUiIueVknUdY94/Imnfdfw+lMWqPTdiboxIpVKhZcuWGDRoEFasWCH36ciOSbkDkUqtAhLH8INMRM4tt1B6D3f8zgzEhmuZZGwFsoMbvV5vjXaQHZK7undd9ALg7+1W/45ERA4qKT0HS77+VfL+nD1qPYrl3JDzUXpWE2dJEZGzsnQIn9+L1iE7uKleEK8+K1eulPv0ZEeUrq7Jap1E5IwaMoTP70XrkB3cHD9+HMePH0dlZSU6deoEADh9+jRcXFzQo0cPw34qFccQHZ2cipx14SwpInJmlgzh83vRumQHN8OHD4ePjw8++ugj+Pv7A6gq7Ddx4kQMGDAAL7/8suKNJNuoXpHTUtWrdTJpjoickdyhJX4vWp+6/l2MrVixAgkJCYbABgD8/f3x2muvcbaUE4oN12JmTEd4u0mrPuzjYRwvazUenP5NRE5N7tASvxetT3bPTWFhIa5evVpr+9WrV1FUVKRIo8g+WFK8b/GIztBqPLmWChE1GVKG8AO8XfF/Q8Nxs7QCAc3dofF0g04v8PvRSmQHN6NGjcLEiROxYsUK9O7dGwDw008/4ZVXXsHjjz+ueAPJNizN/NdqPDmtkYialLoW1RRDl7/2vBtvfXeKa001EtkViktLSzF79mxs2LABlZWVAKqWXpg0aRLefPNNeHt7W6WhSmGF4vrp9EKtBd/qIybHHZwziHciRNQkmertDtZ4YETXYLz3QzbXmmogOddvixfOLCkpQVZWFgCgffv2dh/UiBjc1E9O+XDgzp0Jx5CJqKmrvqhmoI8Herbxx8A399d5syhWcOdaU3VrlIUzc3JykJOTgwceeACenp4QBIHTv52E3Mx/LbtWiYgA1F5UMyXrer294HoBmLolFbOuhCG0hTfzFRUgO7i5fv06nnjiCezfvx8qlQpnzpxBu3btMGnSJPj7+3PGlBOQmvk/7cEO6NehBT+ERERmyLlZXLX3jOH/mY/TMLKngs+aNQuurq64cOECvLy8DNtHjx6NpKQkRRtHtiFm/psLV1So+uDNiu2I6PZ3MbAhIjLD0grEuQXlmLI5FUnpOQq3qGmQHdx89913WLZsGe6++26j7WFhYTh//rxiDSPbETP/AdQKcFh8iohIOvFmUS4xGTZ+ZwZ0+obUiG+aZAc3JSUlRj02ovz8fLi7uyvSKLI9sXifxtPVaDuLTxERSVf9ZlEuAXdWDid5ZAc3AwYMwKZNmwy/q1Qq6PV6LF++HA8++KCijSPr0ukFpGRdx5dpl5CSdd1wd5CUnoP+y/Zh1d7TuFlWNd3fz9MVs2LCcHDOIAY2REQyDIkIxjtPdYelnd1cOVw+2QnFy5cvx0MPPYSff/4ZFRUV+Pvf/45ff/0V+fn5OHTokDXaSFYgtx5DQVklVu89g05aHwY3REQyDY1shUSoMHWL/LX6uHK4fLJ7biIiInD69Gn0798fjz32GEpKSvD444/j+PHjaN++vTXaSAoTqw/XnJ6YU1COf5kpNMXxXyKihhkaGYx1Y3sgwNu1/p3/R+vrzpXDLSCriF9lZSWGDBmCdevWISwszJrtspqmXsTPkurDNW2d3IdLLBARWajith59EpKRX1JR775ebi6YPKAtere9C9eKbzXpGjhWK+Ln6uqKEydONKhxZFtHs/MbFNgAHP8lImoIt2ZqvDEqAlM2Vw1R1dXDUFqhw5rkswDOGraxBk79ZA9LjR07FuvXr7dGW6gRKBGYcPyXiKhhhkQE492xPaC1YJo4a+DUT3ZC8e3bt7Fhwwbs3bsXPXv2rLWm1MqVKxVrHCmvIYGJuDgmx3+JiBpuSEQwYsO12HgoG0t2ZUo+TkDV93H8zgzEhmub5BBVfWQHN+np6ejRowcA4PTp00aPcW0p+ycWlLJkaEoAi/cRESnJRa1CCx/5NeKq18BhDmRtkoKbEydOICIiAmq1Gvv377d2m8iKXNQqzB8WbtF0xGf7hXKMl4hIYQ3pUWcOpGmScm66d++Oa9euAQDatWuH69evW7VRZD1J6TlYsivDomNjw7UKt4aIiCxdogFgDqQ5koIbPz8/ZGdnAwDOnTsHvV5v1UaRdZirb1MfcaFM5toQESnP0iUaWAPHPEnDUn/+858xcOBABAcHQ6VSoVevXnBxcTG57++//65oA0kZOr2A+J0ZdU45NIULZRIRWd+QiKoCf3N3nMTN0kpJx5Tf1mNPRi7TBUyQFNy89957ePzxx3H27FlMnz4dkydPho+Pj7XbRgrQ6QUczc7HobNXLUoi1rKeAhFRoxBnTyXuO4sPD2Ub1vYzp6C0ElM2p3IxYxNkVSgGgIkTJ+Ltt9922OCmKVUoNrV+lBQB3q4Y1a01YsK1TbYSJhGRLYk3prkFZViyK9NsNWOxRMfBOYOc/rvaahWKAeDDDz+0uGHUeMT8GrnDUPOH3YcJ/do6/YeEiMieuahViG5/F1Kyrte5TAOnhJsmO7gh+6fTC1j0lbz8GjH6Z2BDRGQ/pE715pRwY7KXXyD7l7jvDHILpf+hM2mYiMg+SZ3qfe5aqZVb4lgY3DiZpPQcrNp7RtYxWo0HE9KIiOyQWAOnvtvO1XtPc62pahjcOBFxurdU3u4umBUThoNzBjGwISKyQ2INHClpBvE7M6DTy820dE4MbpzI0ex8WTOjSm/psHrvGezJyLViq4iIqCGGRARjVkxYnftUTywmBjdORW5CmRjfM9onIrJvoS28Je3Hm9UqDG6ciCVrjDDaJyKyf1K/3zccOsfcGzC4cSq92wZA62vZImqcRkhEZL+kLq6pAnvjAQY3TmVPRi7Kb+ssOpYryxIR2S+pi2uKvfGr9pxGStb1JhvkyF5+wdE50/ILYnnuK0XlyL5agtXJ8qaAA02rdDcRkaNbsvNXrD90TvL+wU60PqBVl18g+2DJulEqwGg6IYv3ERE5lphwrazgJregvEkurslhKQckrhsld0FMf283o99ZvI+IyLFILeonaqqzYtlz42DEQn2W/InOH3YftBpPXCkqR6CPB1f8JiJyMGLuzZTNqZKPEfNwjmRdh1qtahLXAAY3dq56Xk2gjwf0giC7x0ak1Xhy1VgiIgc3JCIY747tgX98fhL5JZWSj5v8759RWnFn0okz5ePUxODGjpnKq/Fyc7HouYI1VVE6ERE5viERwSir1GPW9jTJx1QPbICq3pwXNqfinae6Y2hkK4VbaFvMubFTu0/k4AUTeTU1/zilYtIwEZFzsbSuWU3Tth7H7hPOVfiPwY0d2n3iMqZtlT6eWhe1CnjnKSYNExE5G7nJxeboBWDqllSnqmzM4MbO7D6Rg6lbjkOppPbEMd0xNJKBDRGRs6le2E+JfnlnmlHF4MZO6PQCVu05jRe3KNNjE6zxwLqxPZxuHJWIiO4Qk4u1EpZmqI8zrTPIhGI7kJSeg7k7TuJmqfSsd3OmPdgB/Tq0cOopfkREdMeQiGDEhmux8VA2luzKbNBzfftr1dCUo08X5/ILNpaUXpU4rIRgLqNARNRk6fQC+i/bh9yCcotqoZliT9PF5Vy/OSxlQ2JBPqVwRhQRUdOldA4OcGe6+O4TlxV6xsbBYSkbEAvzHTxz1eKCfDXNiuloF5E1ERHZjpiDI3ftwfq8uOU4XsotQlS7u3Ct+JbdD1lxWKoR6fQCEvedxYeHsnGzrOH5NSKtrzsOzX3Ibv/IiIiocVWvbt/C2x1QAdeKbyEpPRffpOcq8hqNPWTFVcFtQPxDyi0oQ35JBfy83HCztAIBzd0R2Nwd/z2Xj/d+/N3iInymiKHMohGdGdgQEZGBi1plcrmdQB8PxYIbcchqfPQ9uCfA23C9EwMpW/bu2EVws3btWrz55pvIzc1F165d8c9//hO9e/c2u/8nn3yC+fPn49y5cwgLC8OyZcswdOjQRmyxMVPLJCht8oC2+PpEjtFraO0o0YuIiOyfWPhPyaTjj1IumH3MVgnJNh+W2r59O8aNG4d169YhKioKq1evxieffIJTp04hMDCw1v6HDx/GAw88gISEBDz66KPYsmULli1bhtTUVERERNT7ekoPSyWl52DK5lTF/khq8vdyRcLjXTAkIrjWIpr2PN5JRET2ydrXrerEK9S7YxteKV/O9dvmwU1UVBTuv/9+JCYmAgD0ej1CQkLw0ksvYe7cubX2Hz16NEpKSvD1118btvXp0wfdunXDunXr6n09JYMbcdqdNXpsvNxc8LcH2mHaoDAGMEREpKik9BzM/eykovmf5qhQNdLQ0FIlDjMVvKKiAseOHUNMTIxhm1qtRkxMDFJSUkwek5KSYrQ/AAwePNjs/rdu3UJhYaHRj1KOZudbbSjq/Wd6YUZMRwY2RESkuCERwVj7dI9GeS0BjV/92KbBzbVr16DT6RAUFGS0PSgoCLm5phOecnNzZe2fkJAAjUZj+AkJCVGm8aiq4Kg0FarGKPuYSAQjIiJSSp92dymy8KZU1rhmmuP0RfzmzZuHgoICw88ff/yh2HMH+iiz3HxNLMZHRETWZo2if3Wx1jXTFJsGNy1atICLiwvy8vKMtufl5UGr1Zo8RqvVytrf3d0dvr6+Rj9KEbPOlRKs8VAk6YqIiEgKcwtvan3d8WhkMPw8XRv8GuKIRO+2AQ1+LqlsOhXczc0NPXv2RHJyMkaOHAmgKqE4OTkZ06ZNM3lMdHQ0kpOTMXPmTMO2PXv2IDo6uhFabEyMei3NOvdyVWNol2D0C2sJrS9nPxERUeMTF940NRu3+izd7KslWJ18RtZzi1e0xh6RsHmdm7i4OIwfPx69evVC7969sXr1apSUlGDixIkAgHHjxqF169ZISEgAAMyYMQMDBw7EihUrMGzYMGzbtg0///wz3nvvPZu035JS136erpjYL5QzoYiIyC6YK/pXc/u9wT6yrne2qsdm8+Bm9OjRuHr1KhYsWIDc3Fx069YNSUlJhqThCxcuQK2+M3rWt29fbNmyBa+++ir+8Y9/ICwsDF988YWkGjfWUj3qNVeh2B4qNhIRETWEo1zvbF7nprHZcm0pIiIisozD1LkhIiIiUhqDGyIiInIqDG6IiIjIqTC4ISIiIqfC4IaIiIicCoMbIiIicioMboiIiMipMLghIiIip8LghoiIiJyKzZdfaGxiQebCwkIbt4SIiIikEq/bUhZWaHLBTVFREQAgJCTExi0hIiIiuYqKiqDRaOrcp8mtLaXX63H58mX4+PhApVJ2Ma/CwkKEhITgjz/+cMp1q5z9/ADnP0een+Nz9nPk+Tk+a52jIAgoKipCq1atjBbUNqXJ9dyo1WrcfffdVn0NX19fp/2jBZz//ADnP0een+Nz9nPk+Tk+a5xjfT02IiYUExERkVNhcENEREROhcGNgtzd3bFw4UK4u7vbuilW4eznBzj/OfL8HJ+znyPPz/HZwzk2uYRiIiIicm7suSEiIiKnwuCGiIiInAqDGyIiInIqDG6IiIjIqTC4qcPatWsRGhoKDw8PREVF4ejRo3Xu/8knn+Dee++Fh4cHunTpgt27dxs9LggCFixYgODgYHh6eiImJgZnzpyx5inUS845vv/++xgwYAD8/f3h7++PmJiYWvtPmDABKpXK6GfIkCHWPg2z5Jzfxo0ba7Xdw8PDaB97ew/lnN+f/vSnWuenUqkwbNgwwz729P798MMPGD58OFq1agWVSoUvvvii3mMOHDiAHj16wN3dHR06dMDGjRtr7SP3c21Ncs9xx44diI2NRcuWLeHr64vo6Gh8++23RvssWrSo1nt47733WvEszJN7fgcOHDD5N5qbm2u0nyO/h6Y+YyqVCp07dzbsYy/vYUJCAu6//374+PggMDAQI0eOxKlTp+o9zh6uhQxuzNi+fTvi4uKwcOFCpKamomvXrhg8eDCuXLlicv/Dhw9jzJgxmDRpEo4fP46RI0di5MiRSE9PN+yzfPlyvP3221i3bh1++ukneHt7Y/DgwSgvL2+s0zIi9xwPHDiAMWPGYP/+/UhJSUFISAgefvhhXLp0yWi/IUOGICcnx/CzdevWxjidWuSeH1BVUbN628+fP2/0uD29h3LPb8eOHUbnlp6eDhcXF/z1r3812s9e3r+SkhJ07doVa9eulbR/dnY2hg0bhgcffBBpaWmYOXMmnnvuOaOLvyV/E9Yk9xx/+OEHxMbGYvfu3Th27BgefPBBDB8+HMePHzfar3Pnzkbv4cGDB63R/HrJPT/RqVOnjNofGBhoeMzR38M1a9YYndsff/yBgICAWp9De3gPv//+e7z44os4cuQI9uzZg8rKSjz88MMoKSkxe4zdXAsFMql3797Ciy++aPhdp9MJrVq1EhISEkzu/8QTTwjDhg0z2hYVFSX87W9/EwRBEPR6vaDVaoU333zT8PjNmzcFd3d3YevWrVY4g/rJPceabt++Lfj4+AgfffSRYdv48eOFxx57TOmmWkTu+X344YeCRqMx+3z29h429P1btWqV4OPjIxQXFxu22dP7Vx0A4fPPP69zn7///e9C586djbaNHj1aGDx4sOH3hv6bWZOUczQlPDxciI+PN/y+cOFCoWvXrso1TCFSzm///v0CAOHGjRtm93G29/Dzzz8XVCqVcO7cOcM2e30Pr1y5IgAQvv/+e7P72Mu1kD03JlRUVODYsWOIiYkxbFOr1YiJiUFKSorJY1JSUoz2B4DBgwcb9s/OzkZubq7RPhqNBlFRUWaf05osOceaSktLUVlZiYCAAKPtBw4cQGBgIDp16oQpU6bg+vXrirZdCkvPr7i4GG3atEFISAgee+wx/Prrr4bH7Ok9VOL9W79+PZ588kl4e3sbbbeH988S9X0Glfg3szd6vR5FRUW1PoNnzpxBq1at0K5dOzz99NO4cOGCjVpomW7duiE4OBixsbE4dOiQYbszvofr169HTEwM2rRpY7TdHt/DgoICAKj191advVwLGdyYcO3aNeh0OgQFBRltDwoKqjX2K8rNza1zf/G/cp7Tmiw5x5rmzJmDVq1aGf2RDhkyBJs2bUJycjKWLVuG77//Ho888gh0Op2i7a+PJefXqVMnbNiwAV9++SU2b94MvV6Pvn374uLFiwDs6z1s6Pt39OhRpKen47nnnjPabi/vnyXMfQYLCwtRVlamyN+8vXnrrbdQXFyMJ554wrAtKioKGzduRFJSEt59911kZ2djwIABKCoqsmFLpQkODsa6devw2Wef4bPPPkNISAj+9Kc/ITU1FYAy31v25PLly/jmm29qfQ7t8T3U6/WYOXMm+vXrh4iICLP72cu1sMmtCk7KWLp0KbZt24YDBw4YJd0++eSThv/v0qULIiMj0b59exw4cAAPPfSQLZoqWXR0NKKjow2/9+3bF/fddx/+9a9/YcmSJTZsmfLWr1+PLl26oHfv3kbbHfn9a2q2bNmC+Ph4fPnll0Y5KY888ojh/yMjIxEVFYU2bdrg448/xqRJk2zRVMk6deqETp06GX7v27cvsrKysGrVKvz73/+2Ycus46OPPoKfnx9GjhxptN0e38MXX3wR6enpNsvfkos9Nya0aNECLi4uyMvLM9qel5cHrVZr8hitVlvn/uJ/5TynNVlyjqK33noLS5cuxXfffYfIyMg6923Xrh1atGiBs2fPNrjNcjTk/ESurq7o3r27oe329B425PxKSkqwbds2SV+Stnr/LGHuM+jr6wtPT09F/ibsxbZt2/Dcc8/h448/rjUEUJOfnx86duzoEO+hKb179za03ZneQ0EQsGHDBjzzzDNwc3Orc19bv4fTpk3D119/jf379+Puu++uc197uRYyuDHBzc0NPXv2RHJysmGbXq9HcnKy0Z19ddHR0Ub7A8CePXsM+7dt2xZardZon8LCQvz0009mn9OaLDlHoCrLfcmSJUhKSkKvXr3qfZ2LFy/i+vXrCA4OVqTdUll6ftXpdDqcPHnS0HZ7eg8bcn6ffPIJbt26hbFjx9b7OrZ6/yxR32dQib8Je7B161ZMnDgRW7duNZrGb05xcTGysrIc4j00JS0tzdB2Z3kPgaqZSGfPnpV0k2Gr91AQBEybNg2ff/459u3bh7Zt29Z7jN1cCxVLTXYy27ZtE9zd3YWNGzcKGRkZwvPPPy/4+fkJubm5giAIwjPPPCPMnTvXsP+hQ4eEZs2aCW+99ZaQmZkpLFy4UHB1dRVOnjxp2Gfp0qWCn5+f8OWXXwonTpwQHnvsMaFt27ZCWVlZo5+fIMg/x6VLlwpubm7Cp59+KuTk5Bh+ioqKBEEQhKKiImH27NlCSkqKkJ2dLezdu1fo0aOHEBYWJpSXl9v9+cXHxwvffvutkJWVJRw7dkx48sknBQ8PD+HXX3817GNP76Hc8xP1799fGD16dK3t9vb+FRUVCcePHxeOHz8uABBWrlwpHD9+XDh//rwgCIIwd+5c4ZlnnjHs//vvvwteXl7CK6+8ImRmZgpr164VXFxchKSkJMM+9f2bNTa55/if//xHaNasmbB27Vqjz+DNmzcN+7z88svCgQMHhOzsbOHQoUNCTEyM0KJFC+HKlSt2f36rVq0SvvjiC+HMmTPCyZMnhRkzZghqtVrYu3evYR9Hfw9FY8eOFaKiokw+p728h1OmTBE0Go1w4MABo7+30tJSwz72ei1kcFOHf/7zn8I999wjuLm5Cb179xaOHDlieGzgwIHC+PHjjfb/+OOPhY4dOwpubm5C586dhV27dhk9rtfrhfnz5wtBQUGCu7u78NBDDwmnTp1qjFMxS845tmnTRgBQ62fhwoWCIAhCaWmp8PDDDwstW7YUXF1dhTZt2giTJ0+22ZeOIMg7v5kzZxr2DQoKEoYOHSqkpqYaPZ+9vYdy/0Z/++03AYDw3Xff1Xoue3v/xGnBNX/Ecxo/frwwcODAWsd069ZNcHNzE9q1ayd8+OGHtZ63rn+zxib3HAcOHFjn/oJQNf09ODhYcHNzE1q3bi2MHj1aOHv2bOOe2P/IPb9ly5YJ7du3Fzw8PISAgADhT3/6k7Bv375az+vI76EgVE199vT0FN577z2Tz2kv76Gp8wJg9Lmy12uh6n8nQEREROQUmHNDREREToXBDRERETkVBjdERETkVBjcEBERkVNhcENEREROhcENERERORUGN0RERORUGNwQERGRU2FwQ0QOadGiRejWrZusY1QqFb744gurtIeI7AeDGyKyK3/6058wc+bMevebPXt2rQX6iIgAoJmtG0BEJIcgCNDpdGjevDmaN29u6+YQkR1izw0R2Y0JEybg+++/x5o1a6BSqaBSqbBx40aoVCp888036NmzJ9zd3XHw4MFaw1L//e9/ERsbixYtWkCj0WDgwIFITU01+1oVFRWYNm0agoOD4eHhgTZt2iAhIaERzpKIrI3BDRHZjTVr1iA6OhqTJ09GTk4OcnJyEBISAgCYO3culi5diszMTERGRtY6tqioCOPHj8fBgwdx5MgRhIWFYejQoSgqKjL5Wm+//Ta++uorfPzxxzh16hT+85//IDQ01JqnR0SNhMNSRGQ3NBoN3Nzc4OXlBa1WCwD47bffAACLFy9GbGys2WMHDRpk9Pt7770HPz8/fP/993j00Udr7X/hwgWEhYWhf//+UKlUaNOmjYJnQkS2xJ4bInIIvXr1qvPxvLw8TJ48GWFhYdBoNPD19UVxcTEuXLhgcv8JEyYgLS0NnTp1wvTp0/Hdd99Zo9lEZAMMbojIIXh7e9f5+Pjx45GWloY1a9bg8OHDSEtLw1133YWKigqT+/fo0QPZ2dlYsmQJysrK8MQTT+Avf/mLNZpORI2Mw1JEZFfc3Nyg0+lkH3fo0CG88847GDp0KADgjz/+wLVr1+o8xtfXF6NHj8bo0aPxl7/8BUOGDEF+fj4CAgIsajsR2QcGN0RkV0JDQ/HTTz/h3LlzaN68OfR6vaTjwsLC8O9//xu9evVCYWEhXnnlFXh6eprdf+XKlQgODkb37t2hVqvxySefQKvVws/PT6EzISJb4bAUEdmV2bNnw8XFBeHh4WjZsqXZnJma1q9fjxs3bqBHjx545plnMH36dAQGBprd38fHB8uXL0evXr1w//3349y5c9i9ezfUan4tEjk6lSAIgq0bQURERKQU3qIQERGRU2FwQ0RERE6FwQ0RERE5FQY3RERE5FQY3BAREZFTYXBDREREToXBDRERETkVBjdERETkVBjcEBERkVNhcENEREROhcENEREROZX/B+r1Bb3pMAkHAAAAAElFTkSuQmCC", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import sympy\n", "\n", "# Perform an X gate with variable exponent\n", "q = cirq.GridQubit(1, 1)\n", "circuit = cirq.Circuit(cirq.X(q) ** sympy.Symbol('t'), cirq.measure(q, key='m'))\n", "\n", "# Sweep exponent from zero (off) to one (on) and back to two (off)\n", "param_sweep = cirq.Linspace('t', start=0, stop=2, length=200)\n", "\n", "# Simulate the sweep\n", "s = cirq.Simulator()\n", "trials = s.run_sweep(circuit, param_sweep, repetitions=1000)\n", "\n", "# Plot all the results\n", "x_data = [trial.params['t'] for trial in trials]\n", "y_data = [trial.histogram(key='m')[1] / 1000.0 for trial in trials]\n", "plt.scatter('t', 'p', data={'t': x_data, 'p': y_data})\n", "plt.xlabel(\"trials\")\n", "plt.ylabel(\"frequency of qubit measured to be one\")\n", "plt.show()" ] }, { "cell_type": "markdown", "metadata": { "id": "M8oLYwusz4XE" }, "source": [ "## Unitary matrices and decompositions\n", "\n", "Many quantum operations have unitary matrix representations. This matrix can be accessed by applying `cirq.unitary(operation)` to that `operation`. This can be applied to gates, operations, and circuits that support this protocol and will return the unitary matrix that represents the object. See [Protocols](../build/protocols.ipynb) for more about this and other protocols." ] }, { "cell_type": "code", "execution_count": 16, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:30.349614Z", "iopub.status.busy": "2025-03-29T09:30:30.349344Z", "iopub.status.idle": "2025-03-29T09:30:30.356570Z", "shell.execute_reply": "2025-03-29T09:30:30.355916Z" }, "id": "xn9nnBA70s23" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Unitary of the X gate\n", "[[0.+0.j 1.+0.j]\n", " [1.+0.j 0.+0.j]]\n", "Unitary of SWAP operator on two qubits.\n", "[[1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n", " [0.+0.j 0.+0.j 1.+0.j 0.+0.j]\n", " [0.+0.j 1.+0.j 0.+0.j 0.+0.j]\n", " [0.+0.j 0.+0.j 0.+0.j 1.+0.j]]\n", "Unitary of a sample circuit\n", "[[0.+0.j 0.+0.j 1.+0.j 0.+0.j]\n", " [1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n", " [0.+0.j 0.+0.j 0.+0.j 1.+0.j]\n", " [0.+0.j 1.+0.j 0.+0.j 0.+0.j]]\n" ] } ], "source": [ "print('Unitary of the X gate')\n", "print(cirq.unitary(cirq.X))\n", "\n", "print('Unitary of SWAP operator on two qubits.')\n", "q0, q1 = cirq.LineQubit.range(2)\n", "print(cirq.unitary(cirq.SWAP(q0, q1)))\n", "\n", "print('Unitary of a sample circuit')\n", "print(cirq.unitary(cirq.Circuit(cirq.X(q0), cirq.SWAP(q0, q1))))" ] }, { "cell_type": "markdown", "metadata": { "id": "Ls6Tnx90Y94Q" }, "source": [ "### Decompositions \n", "\n", "Many gates can be decomposed into an equivalent circuit with simpler operations and gates. This is called decomposition and can be accomplished with the `cirq.decompose` protocol. \n", "\n", "For instance, a Hadamard H gate can be decomposed into X and Y gates:" ] }, { "cell_type": "code", "execution_count": 17, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:30.359519Z", "iopub.status.busy": "2025-03-29T09:30:30.358925Z", "iopub.status.idle": "2025-03-29T09:30:30.363405Z", "shell.execute_reply": "2025-03-29T09:30:30.362603Z" }, "id": "u8JwZaAUfbSv" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[(cirq.Y**0.5).on(cirq.LineQubit(0)), cirq.XPowGate(global_shift=-0.25).on(cirq.LineQubit(0))]\n" ] } ], "source": [ "print(cirq.decompose(cirq.H(cirq.LineQubit(0))))" ] }, { "cell_type": "markdown", "metadata": { "id": "B8ciZZSSf2jb" }, "source": [ "Another example is the 3-qubit Toffoli gate, which is equivalent to a controlled-controlled-X gate. Many devices do not support three qubit gates, so it is important to decompose them into one and two qubit gates." ] }, { "cell_type": "code", "execution_count": 18, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:30.366052Z", "iopub.status.busy": "2025-03-29T09:30:30.365815Z", "iopub.status.idle": "2025-03-29T09:30:30.375728Z", "shell.execute_reply": "2025-03-29T09:30:30.375040Z" }, "id": "bbjRWlzjgPwf" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0: ───T────────────────@─────────────────────────────────@─────────────────────────────@────────────────────────────@───────────────────────────────────────\n", " │ │ │ │\n", "1: ───T───────Y^-0.5───@───Y^0.5────@───T^-1────Y^-0.5───@────────Y^0.5───@───Y^-0.5───@──────Y^0.5────@───Y^-0.5───@──────Y^0.5────@───────────────────────\n", " │ │ │ │\n", "2: ───Y^0.5───X────────T───Y^-0.5───@───Y^0.5───T────────Y^-0.5───────────@───Y^0.5────T^-1───Y^-0.5───@───Y^0.5────T^-1───Y^-0.5───@───Y^0.5───Y^0.5───X───\n" ] } ], "source": [ "q0, q1, q2 = cirq.LineQubit.range(3)\n", "print(cirq.Circuit(cirq.decompose(cirq.TOFFOLI(q0, q1, q2))))" ] }, { "cell_type": "markdown", "metadata": { "id": "VWcik4ZwggXj" }, "source": [ "The above decomposes the Toffoli into a simpler set of one-qubit gates and two-qubit CZ gates at the cost of lengthening the circuit considerably." ] }, { "cell_type": "markdown", "metadata": { "id": "rIUbvdVQkHbX" }, "source": [ "### Transformers\n", "\n", "The last concept in this tutorial is the transformer. A transformer can take a circuit and modify it. Usually, this will entail combining or modifying operations to make it more efficient and shorter, though a transformer can, in theory, do any sort of circuit manipulation.\n", "\n", "For example, the `cirq.merge_single_qubit_gates_to_phxz` transformer will take consecutive single-qubit operations and merge them into a single `PhasedXZ` operation." ] }, { "cell_type": "code", "execution_count": 19, "metadata": { "execution": { "iopub.execute_input": "2025-03-29T09:30:30.378658Z", "iopub.status.busy": "2025-03-29T09:30:30.378057Z", "iopub.status.idle": "2025-03-29T09:30:30.386149Z", "shell.execute_reply": "2025-03-29T09:30:30.385524Z" }, "id": "5WvfOdaG5C_6" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "(1, 1): ───X^0.25───Y^0.25───T───\n", "(1, 1): ───PhXZ(a=0.304,x=0.333,z=0.142)───\n" ] } ], "source": [ "q = cirq.GridQubit(1, 1)\n", "c = cirq.Circuit(cirq.X(q) ** 0.25, cirq.Y(q) ** 0.25, cirq.Z(q) ** 0.25)\n", "print(c)\n", "c = cirq.merge_single_qubit_gates_to_phxz(c)\n", "print(c)" ] }, { "cell_type": "markdown", "metadata": { "id": "xRfQqzdx7lUI" }, "source": [ "Other transformers can assist in transforming a circuit into operations that are native operations on specific hardware devices. You can find more about transformers and how to create your own in [Transformers](../transform/transformers.ipynb)." ] }, { "cell_type": "markdown", "metadata": { "id": "8QbTGmKlYT4i" }, "source": [ "## Next steps\n", "\n", "After completing this tutorial, you should be able to use gates and operations to construct your own quantum circuits, to simulate them, and to use sweeps.\n", "\n", "There is much more to learn and try out for those who are interested:\n", "\n", "* Learn about the variety of [Gates](../build/gates.ipynb) available in Cirq and more about the different ways to construct [Circuits](../build/circuits.ipynb).\n", "* Learn more about [Simulations](../simulate/simulation.ipynb) and how it works.\n", "* Learn about [Noise](../noise) and how to utilize multi-level systems using [Qudits](../build/qudits.ipynb).\n", "* Dive into some [Experiments](../experiments) and some in-depth tutorials of how to use cirq.\n", "\n", "Also, join our [cirq-announce mailing list](https://groups.google.com/forum/#!forum/cirq-announce) to hear about changes and releases or go to the [Cirq GitHub repository](https://github.com/quantumlib/Cirq/) to file issues." ] } ], "metadata": { "colab": { "collapsed_sections": [], "name": "basics.ipynb", "toc_visible": true }, "kernelspec": { "display_name": "Python 3", "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.10.16" } }, "nbformat": 4, "nbformat_minor": 0 }