{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Getting Started with OpenQASM on Braket" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "# Use Braket SDK Cost Tracking to estimate the cost to run this example\n", "from braket.tracking import Tracker\n", "t = Tracker().start()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "OpenQASM is a popular human-readable and hardware-agnostic quantum circuit description language. It is open-source and has been actively maintained by a [Technical Steering Committee](https://medium.com/qiskit/introducing-a-technical-steering-committee-for-openqasm3-f9db808108e1) formed by IBM, Amazon, Microsoft and the University of Innsbruck. Amazon Braket now supports OpenQASM 3.0 as an *Intermediate Representation* (IR) in addition to the in-house *JSON-Based AWS Quantum Circuit Description* ([JAQCD](https://github.com/aws/amazon-braket-schemas-python/tree/main/src/braket/ir/jaqcd)). In this notebook, we demonstrate how to submit OpenQASM tasks to various devices on Braket and introduce some OpenQASM features available on Braket." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Create and submit an OpenQASM task\n", "\n", "Submitting a quantum task with OpenQASM is just as simple as using JAQCD. You can use the Amazon Braket Python SDK, Boto3, or the AWS CLI to submit OpenQASM 3.0 tasks to an Amazon Braket device. We will go over each method in this section.\n", "\n", "\n", "### A Bell state\n", "\n", "We will start with by preparing a [Bell state](https://en.wikipedia.org/wiki/Bell_state) in OpenQASM:\n" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "bell_qasm = \"\"\"\n", "OPENQASM 3;\n", "\n", "qubit[2] q;\n", "bit[2] c;\n", "\n", "h q[0];\n", "cnot q[0], q[1];\n", "\n", "c = measure q;\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Compare this to the same Bell state written in JAQCD:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{\n", " \"braketSchemaHeader\": {\n", " \"name\": \"braket.ir.jaqcd.program\",\n", " \"version\": \"1\"\n", " },\n", " \"instructions\": [\n", " {\n", " \"target\": 0,\n", " \"type\": \"h\"\n", " },\n", " {\n", " \"control\": 0,\n", " \"target\": 1,\n", " \"type\": \"cnot\"\n", " }\n", " ],\n", " \"results\": null,\n", " \"basis_rotation_instructions\": null\n", "}\n" ] } ], "source": [ "from braket.ir.jaqcd import CNot, H, Program\n", "\n", "program = Program(instructions=[H(target=0), CNot(control=0, target=1)])\n", "print(program.json(indent=2))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Immediately, we can see a difference: In OpenQASM, users define their own qubit registers, and thus the syntax is closer to what quantum algorithm researchers are used to; on the other hand, in JAQCD, qubits are indexed by integers and the convention is closer to that of hardware providers. Also, JAQCD has result types and basis rotation instructions embedded in the language while OpenQASM doesn't support them inherently (but later we will show how to use the `pragma` syntax to support them in OpenQASM)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "### Use the Python SDK to create OpenQASM 3.0 tasks\n", "\n", "Most Braket users might want to use the Braket Python SDK to submit OpenQASM tasks. To submit our Bell state program in the Python SDK, we first choose the quantum device that we want to run our program on. In this example, we will use the SV1 state-vector simulator for demonstration." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [], "source": [ "import boto3\n", "import json\n", "from braket.aws import AwsDevice\n", "sv1 = AwsDevice(\"arn:aws:braket:::device/quantum-simulator/amazon/sv1\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To submit the OpenQASM task, we initialize an `OpenQASMProgram` object using the Bell state program text string `bell_qasm` we defined above and send it to the SV1 simulator." ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "scrolled": false }, "outputs": [], "source": [ "from braket.ir.openqasm import Program as OpenQASMProgram\n", "\n", "bell_program = OpenQASMProgram(source=bell_qasm)\n", "bell_task = sv1.run(\n", " bell_program, \n", " shots=100, \n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Submit OpenQASM 3.0 programs using the AWS Command Line Interface\n", "\n", "Alternatively, if you like the command line experience or you are not a Python user, you can also choose to use the [AWS Command Line Interface (CLI)](https://aws.amazon.com/cli/) to submit our Bell state program. Before doing that we have to make sure we have [AWS CLI installed](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). The following code saves the `bell_qasm` string to a file named `bell.qasm`:" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [], "source": [ "with open(\"bell.qasm\", \"w\") as f:\n", " f.write(bell_qasm)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Then we can use the command below to submit the task via AWS CLI. Remember to replace the placeholder \\\"amazon-braket-my-bucket\\\" with your own bucket name.\n", " \n", " aws braket create-quantum-task \\\n", " --region \"us-west-1\" \\\n", " --device-arn \"arn:aws:braket:us-west-1::device/qpu/rigetti/Aspen-M-3\" \\\n", " --shots 100 \\\n", " --action '{\n", " \"braketSchemaHeader\": {\n", " \"name\": \"braket.ir.openqasm.program\", \n", " \"version\": \"1\"\n", " },\n", " \"source\": $(cat bell.qasm)\n", " }'" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Figure out what OpenQASM features are supported on each device\n", "\n", "Different devices on Braket support different subsets of OpenQASM features. To see what are the supported OpenQASM features on each device, we can simply check the device capability for OpenQASM actions. As an example, we can take a look at the `action` field in the device capability of SV1 simulator:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['ccnot',\n", " 'cnot',\n", " 'cphaseshift',\n", " 'cphaseshift00',\n", " 'cphaseshift01',\n", " 'cphaseshift10',\n", " 'cswap',\n", " 'cy',\n", " 'cz',\n", " 'ecr',\n", " 'h',\n", " 'i',\n", " 'iswap',\n", " 'pswap',\n", " 'phaseshift',\n", " 'rx',\n", " 'ry',\n", " 'rz',\n", " 's',\n", " 'si',\n", " 'swap',\n", " 't',\n", " 'ti',\n", " 'v',\n", " 'vi',\n", " 'x',\n", " 'xx',\n", " 'xy',\n", " 'y',\n", " 'yy',\n", " 'z',\n", " 'zz',\n", " 'gpi',\n", " 'gpi2',\n", " 'ms']" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# supportedOperations\n", "sv1.properties.action['braket.ir.openqasm.program'].supportedOperations" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['braket_unitary_matrix',\n", " 'braket_basis_rotation',\n", " 'braket_result_type_sample',\n", " 'braket_result_type_expectation',\n", " 'braket_result_type_variance',\n", " 'braket_result_type_probability',\n", " 'braket_result_type_amplitude',\n", " 'braket_result_type_adjoint_gradient']" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# supportedPragmas\n", "sv1.properties.action['braket.ir.openqasm.program'].supportedPragmas" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['braket_result_type_state_vector',\n", " 'braket_result_type_density_matrix',\n", " 'braket_noise_amplitude_damping',\n", " 'braket_noise_bit_flip',\n", " 'braket_noise_depolarizing',\n", " 'braket_noise_kraus',\n", " 'braket_noise_pauli_channel',\n", " 'braket_noise_generalized_amplitude_damping',\n", " 'braket_noise_phase_flip',\n", " 'braket_noise_phase_damping',\n", " 'braket_noise_two_qubit_dephasing',\n", " 'braket_noise_two_qubit_depolarizing']" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# forbiddenPragmas\n", "sv1.properties.action['braket.ir.openqasm.program'].forbiddenPragmas" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The SV1 OpenQASM `action` field lists supported/forbidden OpenQASM features on the device, including `supportedPragmas`, `forbiddenPragmas`, `maximumQubitArrays`, `maximumClassicalArrays`, `requiresAllQubitsMeasurement`, `supportedResultTypes`, etc. The names are self-evident, but readers are encouraged to visit the [Amazon Braket developer guide](https://docs.aws.amazon.com/braket/latest/developerguide/braket-using.html) for full information of what these fields mean." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# OpenQASM features on Braket\n", "\n", "Braket supports many useful OpenQASM features, either through the OpenQASM program syntax or Braket-specific pragmas. We will walk through some of these features in this section.\n", "\n", "## Simulating Noise with OpenQASM\n", "\n", "With the fully on-demand, high-performance, density-matrix simulator [DM1](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html#braket-simulator-dm1), you can easily investigate the effects of realistic noise on your quantum programs. Now, we show how to use OpenQASM programs to leverage the circuit-level noise simulation capability of DM1.\n", "\n", "To simulate noise, we have to be able to specify different noise channels. Although syntax for noise channels is not available in the OpenQASM language, Braket uses the `pragma` statement to extend OpenQASM for defining noise channels. Here is an example of an OpenQASM program that prepares a noisy 3-qubit [GHZ state](https://en.wikipedia.org/wiki/Greenberger%E2%80%93Horne%E2%80%93Zeilinger_state):" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [], "source": [ "noisy_ghz3_program = \"\"\"\n", "// noisy_ghz3.qasm\n", "// Prepare a 3 noisy qubit GHZ state\n", "OPENQASM 3;\n", "\n", "qubit[3] q;\n", "bit[3] c;\n", "\n", "h q[0];\n", "#pragma braket noise depolarizing(0.1) q[0]\n", "cnot q[0], q[1];\n", "#pragma braket noise depolarizing(0.1) q[0]\n", "#pragma braket noise depolarizing(0.1) q[1]\n", "cnot q[1], q[2];\n", "#pragma braket noise depolarizing(0.1) q[0]\n", "#pragma braket noise depolarizing(0.1) q[1]\n", "\n", "c = measure q;\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In the example above, we inserted the depolarizing noise channel with probability of 0.1 after each gate in the circuit. The `noisy_ghz3_program` is equivalent to the following program in the Braket SDK:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "Circuit('instructions': [Instruction('operator': H('qubit_count': 1), 'target': QubitSet([Qubit(0)])), Instruction('operator': Depolarizing(0.1), 'target': QubitSet([Qubit(0)])), Instruction('operator': CNot('qubit_count': 2), 'target': QubitSet([Qubit(0), Qubit(1)])), Instruction('operator': Depolarizing(0.1), 'target': QubitSet([Qubit(0)])), Instruction('operator': Depolarizing(0.1), 'target': QubitSet([Qubit(1)])), Instruction('operator': CNot('qubit_count': 2), 'target': QubitSet([Qubit(1), Qubit(2)])), Instruction('operator': Depolarizing(0.1), 'target': QubitSet([Qubit(1)])), Instruction('operator': Depolarizing(0.1), 'target': QubitSet([Qubit(2)]))])" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from braket.circuits import Circuit, Observable, Gate, Noise, FreeParameter\n", "\n", "noisy_ghz3_circ = Circuit().h(0).cnot(0, 1).cnot(1, 2)\n", "noise = Noise.Depolarizing(probability=0.1)\n", "noisy_ghz3_circ.apply_gate_noise(noise)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To see if `noisy_ghz3_program` and `noisy_ghz3_circ` are indeed the same, we can run both circuits and compare the results:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [], "source": [ "dm1 = AwsDevice(\"arn:aws:braket:::device/quantum-simulator/amazon/dm1\")\n", "\n", "noisy_ghz3_circ_task = dm1.run(noisy_ghz3_circ, shots = 10)\n", "noisy_ghz3_program_task = dm1.run(OpenQASMProgram(source=noisy_ghz3_program), shots = 10)" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "sdk measurement results: Counter({'000': 6, '011': 2, '111': 1, '100': 1})\n", "openqasm measurement results: Counter({'100': 4, '111': 4, '000': 2})\n" ] } ], "source": [ "sdk_result = noisy_ghz3_circ_task.result()\n", "openqasm_result = noisy_ghz3_program_task.result()\n", "sdk_measurement = sdk_result.measurement_counts\n", "openqasm_measurement = openqasm_result.measurement_counts\n", "print('sdk measurement results:', sdk_measurement)\n", "print('openqasm measurement results:', openqasm_measurement)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As expected, the measurement counts of the two are very close.\n", "\n", "In addition to depolarizing noises, we can simulate more complicated noise types with Braket, e.g., `pauli_channel`, `amplitude_damping`, etc. Check the [Amazon Braket developer guide](https://docs.aws.amazon.com/braket/latest/developerguide/braket-using.html) for a complete list of noise channels supported on Braket. Here we give another example of general noise channels defined by the Kraus representation." ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [], "source": [ "noisy_program_with_kraus_operators = \"\"\"\n", "// noisy_program_with_kraus_operators\n", "OPENQASM 3;\n", "\n", "qubit[2] q;\n", "bit[2] c;\n", "\n", "h q[0];\n", "#pragma braket noise kraus([[0.9486833, 0], [0, 0.9486833]], [[0, 0.31622777], [0.31622777, 0]]) q[0]\n", "cnot q[1], q[2];\n", "\n", "c = measure q;\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We inserted a single qubit noise channel defined by two 2x2 complex Kraus operators in the example above on qubit `q[0]`. Braket will validate if the Kraus operators indeed form a Completely-Positive and Trace-Preserving (CPTP) map." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Submitting parametrized tasks with OpenQASM\n", "\n", "The on-demand [SV1 simulator](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html#braket-simulator-sv1) and [DM1 simulator](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html#braket-simulator-dm1) support submitting OpenQASM programs with free parameters. You can set the value of the parameter when you submit the task, like so:" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [], "source": [ "parameter_qasm = \"\"\"\n", "OPENQASM 3.0;\n", "input float alpha;\n", "\n", "bit[2] b;\n", "qubit[2] q;\n", "\n", "h q[0];\n", "h q[1];\n", "rx(alpha) q[0];\n", "rx(alpha) q[1];\n", "b[0] = measure q[0];\n", "b[1] = measure q[1];\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `input float alpha` line indicates that we have an input parameter of type `float` named `alpha`. We can specify a value for `alpha` when we submit the task using the optional `inputs` argument to `run`. `input` should be a `dict` of `string`-`float` pairs." ] }, { "cell_type": "code", "execution_count": 16, "metadata": { "scrolled": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Counter({'11': 4, '00': 4, '10': 2})\n" ] } ], "source": [ "input_dict = {'alpha': 0.1}\n", "param_sv1_task = sv1.run(OpenQASMProgram(source=parameter_qasm), shots = 10, inputs=input_dict)\n", "param_sv1_result = param_sv1_task.result()\n", "print(param_sv1_result.measurement_counts)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Similarly, we can specify values for parametrized noise operations:" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [], "source": [ "parameter_noise_qasm = \"\"\"\n", "OPENQASM 3.0;\n", "input float beta;\n", "input float alpha;\n", "bit[2] b;\n", "qubit[2] q;\n", "h q[0];\n", "h q[1];\n", "rx(alpha) q[0];\n", "rx(alpha) q[1];\n", "#pragma braket noise bit_flip(beta) q[0]\n", "b[0] = measure q[0];\n", "b[1] = measure q[1];\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can see there are now two `input` lines, one for each free parameter." ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Counter({'11': 4, '01': 3, '00': 2, '10': 1})\n" ] } ], "source": [ "noise_input_dict = {'alpha': 0.1, 'beta': 0.2}\n", "param_dm1_task = dm1.run(OpenQASMProgram(source=parameter_qasm), shots = 10, inputs=noise_input_dict)\n", "param_dm1_result = param_dm1_task.result()\n", "print(param_dm1_result.measurement_counts)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Simulating arbitrary unitaries with OpenQASM\n", "\n", "The on-demand [SV1 simulator](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html#braket-simulator-sv1) allows us to simulate arbitrary unitary gates in a circuit. With OpenQASM, we can use the `unitary` pramga to insert these arbitrary unitary gates: " ] }, { "cell_type": "code", "execution_count": 19, "metadata": {}, "outputs": [], "source": [ "program_with_unitary = \"\"\"\n", "// noisy_program_with_kraus_operators\n", "OPENQASM 3;\n", "\n", "qubit q;\n", "bit c;\n", "\n", "#pragma braket unitary([[0, -1im], [1im, 0]]) q\n", "c = measure q;\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `1im` in the `unitary` pragma is the OpenQASM notation of the imaginary number $i$, thus, we were simply using the pragma to perform a Pauli Y gate. We can check it by submitting the above program to SV1." ] }, { "cell_type": "code", "execution_count": 20, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Counter({'1': 10})\n" ] } ], "source": [ "unitary_task = sv1.run(OpenQASMProgram(source=program_with_unitary), shots = 10)\n", "unitary_result = unitary_task.result()\n", "print(unitary_result.measurement_counts)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As expected, the Pauli Y gate flipped the initial 0 state to the 1 state." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Qubit Rewiring with OpenQASM\n", "\n", "Amazon Braket supports the [physical qubit notation within OpenQASM](https://openqasm.com/language/types.html#physical-qubits) on Rigetti devices. When using physical qubits, you have to ensure that the qubits are indeed connected on the selected device. Alternatively, if qubit registers are used instead, the `PARTIAL` rewiring strategy is enabled by default on Rigetti devices. The following example shows how to use physical qubit notation in an OpenQASM program:" ] }, { "cell_type": "code", "execution_count": 21, "metadata": {}, "outputs": [], "source": [ "ghz_program_with_physical_qubits = \"\"\"\n", "// Prepare a GHZ state\n", "OPENQASM 3;\n", "\n", "bit[3] ro;\n", "h $0;\n", "cnot $0, $1;\n", "cnot $1, $2;\n", "ro[0] = measure $0;\n", "ro[1] = measure $1;\n", "ro[2] = measure $2;\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can run the above program on the Rigetti Aspen-M-3 device," ] }, { "cell_type": "code", "execution_count": 23, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Measured qubits: [0, 1, 2]\n" ] } ], "source": [ "# choose the quantum device\n", "aspen_m = AwsDevice(\"arn:aws:braket:us-west-1::device/qpu/rigetti/Aspen-M-3\")\n", "\n", "ghz_program_with_physical_qubits_task = aspen_m.run(OpenQASMProgram(source=ghz_program_with_physical_qubits), shots = 10)\n", "measured_qubits = ghz_program_with_physical_qubits_task.result().measured_qubits\n", "print(\"Measured qubits:\", measured_qubits)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As we can see, physical qubits 0, 1 and 2 are indeed being used and measured." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", " Note: This section and the next verbatim box section uses the Rigetti Aspen-M-3 device. When you run this notebook, make sure the device is currently available. You can find QPU availability windows on the Devices page in the Amazon Braket Console\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Verbatim Compilation with OpenQASM\n", "\n", "In [a previous example notebook](https://github.com/aws/amazon-braket-examples/blob/main/examples/braket_features/Verbatim_Compilation.ipynb), we talked about verbatim compilation on Braket to gain more precise control on Rigetti devices. With OpenQASM3.0, we can use the `box` syntax together with the `verbatim` pragma to perform verbatim compilation. Here is an example:" ] }, { "cell_type": "code", "execution_count": 24, "metadata": {}, "outputs": [], "source": [ "program_with_verbatim_box = \"\"\"\n", "OPENQASM 3;\n", "\n", "bit[2] ro;\n", "#pragma braket verbatim\n", "box{\n", " rx(3.141592653589793) $0;\n", " rx(3.141592653589793) $0;\n", " cz $0, $1;\n", "}\n", "ro[0] = measure $0;\n", "ro[1] = measure $1;\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To program with verbatim boxes, we need to make sure that\n", "- we are using native gates supported by Rigetti devices. Native gates can be found using the following script:\n" ] }, { "cell_type": "code", "execution_count": 25, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "The native gates for the Aspen-M-3 device are:\n", "rx\n", "rz\n", "cz\n", "cphaseshift\n", "xy\n" ] } ], "source": [ "print(\"The native gates for the\", aspen_m.name, \"device are:\")\n", "for gate in aspen_m.properties.paradigm.nativeGateSet:\n", " print(gate)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- we use the physical qubit notation.\n", "- qubit operands are indeed connected on the physical device. Recall that the device qubit connectivity can be found using the following commands:" ] }, { "cell_type": "code", "execution_count": 26, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{'0': ['1', '7'], '1': ['0', '16', '2'], '10': ['11', '113', '17'], '100': ['101', '107'], '101': ['100', '102', '116'], '102': ['101', '103', '115'], '103': ['102', '104'], '104': ['103', '105', '7'], '105': ['104', '106'], '106': ['105', '107'], '107': ['100', '106'], '11': ['10', '12', '26'], '110': ['111', '117'], '111': ['110', '112', '126'], '112': ['111', '113', '125'], '113': ['10', '112', '114'], '114': ['113', '115', '17'], '115': ['102', '114', '116'], '116': ['101', '115', '117'], '117': ['110', '116'], '12': ['11', '13', '25'], '120': ['121', '127'], '121': ['120', '122', '136'], '122': ['121', '123', '135'], '123': ['122', '124', '20'], '124': ['123', '125', '27'], '125': ['112', '124', '126'], '126': ['111', '125', '127'], '127': ['120', '126'], '13': ['12', '14'], '130': ['131', '137'], '131': ['130', '132', '146'], '132': ['131', '133', '145'], '133': ['132', '134', '30'], '134': ['133', '135', '37'], '135': ['122', '134', '136'], '136': ['121', '135', '137'], '137': ['130', '136'], '14': ['13', '15'], '140': ['141', '147'], '141': ['140', '142'], '142': ['141', '143'], '143': ['142', '144', '40'], '144': ['143', '145', '47'], '145': ['132', '144', '146'], '146': ['131', '145', '147'], '147': ['140', '146'], '15': ['14', '16', '2'], '16': ['1', '15', '17'], '17': ['10', '16', '114'], '2': ['1', '15', '3'], '20': ['123', '21', '27'], '21': ['20', '22', '36'], '22': ['21', '23', '35'], '23': ['22', '24'], '24': ['23', '25'], '25': ['12', '24', '26'], '26': ['11', '25', '27'], '27': ['20', '26', '124'], '3': ['2', '4'], '30': ['133', '31', '37'], '31': ['30', '32', '46'], '32': ['31', '33', '45'], '33': ['32', '34'], '34': ['33', '35'], '35': ['22', '34', '36'], '36': ['21', '35', '37'], '37': ['30', '36', '134'], '4': ['3', '5'], '40': ['143', '41', '47'], '41': ['40', '42'], '42': ['41', '43'], '43': ['42', '44'], '44': ['43', '45'], '45': ['32', '44', '46'], '46': ['31', '45', '47'], '47': ['40', '46', '144'], '5': ['4', '6'], '6': ['5', '7'], '7': ['0', '6', '104']}\n" ] }, { "data": { "image/png": "iVBORw0KGgoAAAANSUhEUgAAAb4AAAEuCAYAAADx63eqAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4yLjIsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+WH4yJAAAgAElEQVR4nOydeVxU9frH32c29k1AQTBR0VQUBTX3XXMrK5c0s9verfxV2mrL7Zq2WFbWzcryVlbazSxLS1Mzc9/3hUVADRFBFpV9YGbO749xhhmYgZkBdcDv+/Xy9YIzZ845A3ie8zzfz+d5JFmWZQQCgUAguE5QXOsLEAgEAoHgaiICn0AgEAiuK0TgEwgEAsF1hQh8AoFAILiuEIFPIBAIBNcVIvAJBAKB4LpCBD6BQCAQXFeIwCcQCASC6woR+AQCgUBwXSECn0AgEAiuK0TgEwgEAsF1hQh8AoFAILiuEIFPIBAIBNcVIvAJBAKB4LpCBD6BQCAQXFeIwCcQCASC6woR+AQCgUBwXSECn0AgEAiuK0TgEwgEAsF1hQh8AoFAILiuEIFPIBAIBNcVIvAJBAKB4LpCda0vQCAQCGojt0jLj/szSMoqoKBMh7+nivZh/kzsFkmwr8e1vjxBA0OSZVm+1hchEAgEtjh85iIfb0pl84kcALQ6g/k1T5UCGRh0YyiPD4ymS4vAa3SVgoaGCHwCgcAlrnQWtmTXad5Yk0SZTk9NdylJAk+VkpdHt2dqr6g6n1fQ+BGBTyAQOMXVyMKMQS+R0gpD7Ttfxkut4OXRHUTwE9SKCHwCgcBhrkYWll9cTt+3N1JaoQegT5tg5oztRPNALw6ducizPx7m7MVS8/592wTz4qgOtA71oaBUh1anp2WwjysfT3CdIFSdAoHAISqzsJqDHoAsQ2mFnjfWJLJk12mnzpOUVUCZzhj0grzVLJzajff+SKbrnPUcOXuRBXfFmfeNburLh5PjeHd9Mp1fW8+o/2xh0daTzn40wXWGUHUKBIJaMcgyPh5qq9JjTZnY+ukDiAj0Mu8ryzKSJNV6npJyHVmXysyBdWRMGCnZRaw5lgXABxtSOPiv4bQJ9SEtp5gnBkfz3Z50Nl0uu14oqWD5/gxmDGsn1J4Cu4iMTyAQ1MqWEznoDZVBr7ZM7OYPthAzax0xs9bR6bV15BWXWx3vyy+/ZNWqVdXOk3iu0Or7ds38SDxXYP6+tELP33kltG3qB0DcDUEArH2qP3teHMr8O7sS6KXmxwMZdf/QgkaLCHwCgaBGcou0VsEHrDMxrc7ABxtS6BDuT5vQ6mtrN0U1wUutJK9IS3FxMdOnT+fBBx/ktttuo3fv3ixbtgytVgtAXpEWg0Ud1VujorCswup4hWUV+HoYi1Vh/p6Mi4vgsaUHGPTeJjzVCl4c3YGkKgFUILBElDoFAkGN/Li/evZUUyaWllNste/4+EjWH8/ip983sOrtJyktrRSm7Nq1i8mTJwMQFhbGCx8vI7JlK/PrJeU6fD3VVsfz9VRRpNUBUKbTs3x/Bqdyjef8+K9Ulj7Ui18PZ9b6uYQp/vpFBD6BQFAjSVkFtAn1tdrmrVGRX6y12maZiZnwVCsY1SmMh7/Zx4adRyksrJ6JqVQqbr75ZubNm0e6IZAird782onsQsbHR5q/91IradnEh5TzxuMknSvEUphu+uriefuBr2Y7RhbzN5wQpvhGjih1CgSCGiko01XbVlsmZmJkTDiXSivYdSqfMXdM4PPPPycmJgalUglAnz59SEpKYvXq1XTs2JGm/l6olQo8VAqUCol1Cdm0C/NjZEwYHioFTw1tS1JWgTmrXL7/DBO7taBFkBeeagWPDWzDnwnn2Lzqf+zfvx9ZlikqKjIHxyW7TjN50S7+SMxGqzNYBT2Assvb1idkM3nRLqcVqYKGgcj4BAJBjXgpq3sXasvETIyPj+CnA2cBaOLrxcOTHubhhx/m+++/588//+Tzzz+3UnvG3xBE/A1B3NY1gg82nOCDP1N4bMl+Zo/txAeTunLozEWe+N9B8/7L92cQGeTFL4/3BWBzSg7/XnmEC/t/p3v3Zeb9vvnmG6S2/R02xVvaMQBhim9kiMAnEFxHOLuulZOTw2/ffErnl15CoZDwUCnQGWTWJWTz4ugOjIwJ46/k89UyMTAKT3q3DublX47hqVLQPtzP/NrkyZPNa3tVeeTbffyRmG22NGxPy2Po/M12P9P8DSnM35ACgGwwUJKyE0Opcf1x2rRp3H///cTFxbPycKbDdox3J8QytksEFXrj/nqDjFJRux1D0DAQgU8guA5wZV1LlmXWrl3L3+u/Mu87Li7SoUzMuG8EB9Ivkp5fgodKwQSLDLEmpg2KZmtKrrlzizNIso7WpSlomjcnKyuLzMxM3nzzTe586t8ofYLM+5nsGDN/OsKfSed5eng7FtwVxx2f7jDv89mWNN774wSSBCM6NmPh1O5OX4/APREtywSCRo4zbcbUEgwPKaST5wU2btzIihUrMBgMhI57Ge+2PUFyXhbgSuCoa6/O8vJy+vTpw4EDB1izcStpclOa+Xvy7I9HALirRwsmdGvB+IU7Lr9XycF/DWfMR1tJyynm3QmxnLtUxnt/nADAQ6VgxwtDhNqzkSAyPoGgEeNMAJFlKJfh17Nqlm5aw6X9vwGgUCgo2fcznq3iUKg9nb4GT5WSxwdFO/Ue05qaq31BNRoN69atY+nSpZyWwlBgfQBH7Bj39GrJPb1acuZCKYu2pPHjgQz+OaCNU59D4J6IwCcQNFKcbTOmUSp4/fZOjOoURmn5GN59fz4bVi3ngQcewMvLi4QKJWsyFS5kYe2JjXTeFjC1VxSxkYF8simVv5JzkDCqLk2YJkEMvjGUxwdFVztHcHAwTz75JNOXHXTajvHVjtO8viaRwjId/duGsOCueL7cdsrpzyBwT0TgEwgaKfbajNlb15o+rC1RwT70fXsjob4a/jf9CWbPnIGnZ2WWF3eVZ+TFRgaycGp38oq0/Hggg6RzhRSUVeDvqaZ9uB8T4ms3m7tixzieWZkNbkrOYeWhs9wY5oegcSACn0DQCDG1GQv1qwwKtTV8Hh8fybM/HqagTEdBmY7lB8/xUL/WVsetaxbmKsG+Hi6XGf09q9/mHLVjmJBl4zqfoHEgAp9A0Ahxts1YTqGWZv6eVq+fyC6iqFyHh1ppdZz6yMKuJjHhARiQnbJjjOoUxuYTOZRW6OkXHcIdcRH8mZR9jT+JoL4QgU8gaIQ422bM5/LaVqFFWTCvuBwJ+961umRhV5OHB1RmrY7aMe7v04q3x8ciARkXSnll5TFeGd3hGly94EogAp9A0Ahxdl2r+PLalq+HCq2u3Px1SbmOJj6aK3/BV5iqpnio2Rh/5+c7zV+b7BjulMUK6oYoWgsEjRB761odLAQalutaBWU6sgvK6BDub369Q7g/5wu11Y7TEJk2KBpPlbL2HW3gih1D4N6IwCcQNEJiwgPQqBTmdS1HGj6vOJDBE4Oj8fdU0SbUh7tuakHWpdJaztQw6NIikJdHt8dL7dwtT6WQeGpo/Yl0BO6B6NwiEFwHmNa1+rYJZvbYTkQEXfbxLT9Mhg0fX1mFgf9uO8kj/Vs3qhKfo11sTKgkUCoVYkxRI0MEPoGgkWJrXctRGnN/yiMZF812DL1BRmeo/QdUX75EgXsgSp0CQSNFrGvZxmTHeHpYW8CxpwLLMUViRl/DRwQ+gaCR4uq6Vl3ajDUUDLJMU38vLOfQ9mkTzJ8zBpL42kj+91AvIgK9qr1Po1IyunNzswpW0DARdgaBoBEztVcUu0/l8+uRcw6/Z1iHZm5XznN2jmBtONvOzcTMke1JPV9IEx8N0U1FC7OGigh8AkEjZsmu02xIdK7jyIbEbJbsOu0Wwc+VOYK14Uo7NzBOh78xzI//7Ulnco8W5BVp3U74U98PCI0VEfgEgkaKs9MZxnQO54G+regY7s/Rs5c4knHxmpY7a1NgmnqErk/IZsuJXIeFJ862c0vLKUYhweyxMcxccYT2YUavozuNKboSDwiNGbHGJxA0UuyV8977I5muc9Zz5OxFFtwVZ379Ykk5X24/xaebUzHIMp9sSr0Wlw1YzhGs3XZQm/CksLCQY8eOmb9PyiqopuT01qgoLKuwfp/FmKL7+7Ti0JmLHLs8tcEgQ9I52w2trzZLdp1m8qJd/JGYjVZnsAp6YHxA0OoMrE/IZvKiXUKcg8j4BIJGiSvlvO1peQBM6t4CgL+Sc65JOc/ZTHXmyPaM7dIcP08VhWU6zl0qJTzAi2+//ZZ58+aRnp6ORqPh7NmzqNVqLhSVQZU+pjW1c2vq58F9faK4ZcE2q9cLqgRKe1zJ8qOzg4ZNDwiAW5SyrxUi8AkEjRBXynlVkbg25TxnhSc/7DvDh3+mUFqhJyzAgxWP9gXg0KFDHD161HwcjUaDj48PvsOn0f2Jh6zOWdOYoq4tAmnq58GGGQMA8FAr8VQpeW9CLCNHjuSXX36xmllo4kqXHw+fucgba5JsBr1bY8N5amg7mgd6klOo5dkfD7P39AUASisMvLEmidjIwEat3K0JEfgEgkaIs9MZbFGmM1z1cp4rmerJ3MqgLcvGz/ThgsW8//77VsdWKBTMnDmT4L53olAqHB5TdCa/lH7v/GU+zi2x4dzWpTkPv/g6B/74g9jYWPr3709ERASzZ88Grtz6pCUfb0qlTKevtr1fdAgvjGzPE/87yKGMizT1q55Vlun0fLIptVE2KHAEEfgEgkaIK1PHbR/HsXIe1E9Jz9VM9bGBbfi/wdH4eKhIzyvm9+R82rRpQ1pamvl9jz32GK+88orVsR0ZU1SuN5BTVPnAUFimo0Jv4MDP/8VgMJCSkkJKSgrDhg0Dqpcfj88aYXVOT7WSb3f9zaxfj7tcfswt0rL5RI7NoDpjWDv+szGVg2cuApBdUL3RuCxfu1K2OyACn0DQCKmPqePG46hZtWoVQ4YMwdfX1+Y+9VnSczVT/XRzGp9uTiMm3J+bY5rRddCtrP3oZUaOHIlOp2PMmDF07drVvL+zY4os+elgBrsPHEYus/65nTx5kvX7knljzSmr8mPMrHUWn0XJ3peGseaota/SXvkxOTmZ9PR0+vTpg4+Pj3m7rQcEAIUEnSMC2JCYzaZnB+GhUrA+IZs31yRWE71cq1K2OyBUnQJBI8SV6QwKCTxUClQKCUkCXw8FEd4Gbr/9dkaMGEFubi4nTpygrKzMfJ76UBRWVFSwbp0xONQ1Uz1+roCyCgND2jcF4Pfff2fDhg3MmDGDwYMHm/erazu36PI0unbtSnBwMAqFArVaTVRUFPe/+z2l5faz5FGdwsgrLmfP6fxqr5nKjyYyMzPp0qULN998M2PGjGH37t2YWisnZRVU+1kDhPh6oFEpGNUpjImf7WT0f7YSE+7PE0Pa2jif46Xs3CItCzenMX3ZQR74ei/Tlx1k4eY08ooa5tgqkfEJBI0QV6aOj4uL5N2JXczfH5s1im+WfIcsy+zYsYOmTZsiSRKff/45Dz74YJ0UhXf3bMncuXMJCQlh0aJF7N27lzNnzuCrqR6MnM1UlQqJ8MvtxiTJ9gR5Uzs3R6+/8tyKy+txI4HXKCkpoW/fvowbN47HZjxPn7kbKdfbP974+EhWHLCdrZnKjzmFpSz6aD5z5sxBqzUGls2bN9O7d28UCgUdO3akoMsUiOxc7RhlFcY1v693nibn8izF/247xRNDonl3fXK1/fMKS5Bl2e7PqbH6A0XgEwgaKc6W8348kMGPl2/KkgQ3d2jG4ofuN78uyzLTpk3jnnvucdpy8NKoDgzv2IxQPw/OF5SRnl/CG2+8QUlJiTmLadWqFc0G3sVLL73isPBEkuCuHjfw25FMCsp0dIkM4B+9W5KSXVTrz8e0nubImCJ70xm8vb3Zv38/kiTx2ZaT2IkfAEQEetGzVTDP/3TE7j7asjLajfgHF3f+aOMaJNq3b8+8efNYnuHNhtSCavsUlOnIvFhq9VlqskH+sXolL6auYu7cudVeuxoCnWuFKHUKBA0ce2WoqT1b1qmcNzRcR3l5OSpV5fPx2bNneeyxx1i154RT5vjSCh0PfbOXzq+t45nlhwn2UdO1a1csp6K9+uqrZGz4hseHtGNcXCTJc0bxxOBo8ovLeWzJfp67+UYOv3ozXVsEWmWqI2KaseW5wRyfNYL5k7qyZNfftA9zrI/m1F5RLHukFyM6NsNDpcBTZX1L9FQp8FApGNGxGcse6WXzxq5QKJAkyW750cQdcRHsO51PxoUahvuqNEx5/Dm2bNnClClTUCqNvz8vLy+2bt3KsWPHGDFiBN2jm+Ohsn37Xr4/g3v7RBHso8HfU8WDfVvxZ9L56jvqKyjNSuPdd98lIiKC5s2bm8U/9dlAwB0R8/gEggZKzWUoBTLQOtSHk+eL0Ood/29uLOd14M745hw8eJDQ0FBmzpzJ8uXL+fXXX/ELbc7RYl/CArx49kdj9nJXjxZM6NaC8Qt3XD6GkoP/Gs6Yj7ba9Aguuieejd9/xtw5rwGgVCpRqVQUFxfz2HcHr8kcwbwiLT8eyCDpXCEFZRX4e6ppH+7HhHjHVKkPfL2XjbYCzGU2PjOQTzelsdyOMMXE0PZN+eLeHgCsWrWKxYsXc9dddzFx4kTzPrlFWvq+vdFmoFUpJP59awy3dWmOVqfnt6PnmPt7UrV9ZV05GR/fh6HUmDkqlUq++uorYgfdyuRFuyitsLZKfP9wL+JaBJq73mQVlDH0fevqgZdaybJHerm9P1CUOgWCBoijZajEzEtIyKiUKvSy7HQ5r2fPngB89913DBkyhJEjR/Lf7X+jVFgfyBlzvIdKQZcWQRTeei/S67O56667ePTRR8nMzESpVDJtUDRbU3Kr3XgdoS5zBIN9PeqkcLSlpDURf0MQYf6e1dScto9TKeQZO3YsY8eOrbZPiK8HA9uF2nxA0Blk/rXyGP9aeaza+0xIQEnaPitlql6v55NPPiHojC9lFRqb73t11XGW7Ttj97gNxR8oAp9A0MBIyykyizLUSokPJ8URGxlAZJA3kz/fya5TFopBSUHH5v7MujWGTs0DKC7X8dnmNBZtO2XexZQdDr4xlMcHRdt8WlepVDz66KNA3c3xb97RmcRzBWw9eYmEhARuvPFGK3FFXYUn1yrbaB/mj4cqy2YWNiE+grXHsygurzmYe6oUtA93rExblwcED5WCIW086DhvHkuXLuXw4cMMHTqU8Xffx9wEBbKLi2ANxR8oAp9AcAWp7z6NuUVajmRcsgoI+/7O58vtp/hkSny1/YO81Xx9/03MWZ3AX0nnWTilG9FNfbmja4RL5Tyom+XgxVHtadfMj7sW7aJnqya0b98VW9SH8ORqM6FbJPM3nLD52ku/2M++LJGBCRYK1pqo2wNCB6b2GgXAE088wT333MP06dM5XN4UTeoJu2uVz4+4kRdGtudkThHvrk+2fsi6TEPwB4rAJxBcAa6UDHz3qTwrUUmFXubL7acB0NuIDg/1a82WlBxWHspEkuCb3adZOLU7k3rc4OInc90cP2NYWwa1a8qkRTsp0uqsSnq2mNoritjIQD7ZlMpfyTlIVJZwwbFM9WpSU/nRESTJ+FmceSCqjwcEjUbDsmXLAFi27KDdoDd3bRIp2YVU6GVu7RLOf+/twej/bCU9v8Rqv2vR6s5ZROATCOqZKyUDzy3Skp5XYtXHsjbibggkOauQnx7tQ8tgb45kXOJCsZYgH9fLUDHhARiQHbYcADw+sA1ju0Rw52c7uVhS4XBJLzYykIVTu9dZeHK1uBbrk/X5gGArmzdx6HILNICfDpxlbJfmDL6xKV/vPG3jOI63ursWiMAnENQjV3JMjL02VTURFuBJp+YBTP1yN8lZhbwyugMdHVxDsocr5vjnR7ZHq9Oz6dlB5m01WN6qUVfhydXCVH6cs7p6i7CaqOv6ZH09INQk0KmKLGPXt1hbNn+tEYFPIKgnqpq6axOeLL6vBz2imli9X3H5TvLiiy+yb98+mjVrxpIlSwDbopLa0FYYWHc8iyMZlwB4b8MJ7ukd5fD77a1R7jqZx+aUHIfN8VEvrjZ/XRfLQUNBb3C81qlWSpfX3KLqfN66PiDYE+j4e6ro2iKQ3afy0RlkbokN56ZWTXjtt4Rqx3BGoHOtEIFPIKgnqs6Rg5qFJ/ct3mv+WpJg3VMDaNfMj5MnTzJv3jz0emO5bMeOHbRq1Yqym+6jzfBeTl1TYlaBVecOR9eealuj1MsyEjV3BbFHXSwH7o4p46864b0m3KmLiD2Bjkqp4Jmbb6RNqC8Gg0xaThGPfLufU7nVPZrOCHSuFSLwCQT1gK05crUJTyyJCPCiTagv059/mQXvv20OegCnTp3izJkzdO88DqVCslpb0xtkNEqFueSkvtxpxBSolu/LYOHUbizecZoT2YU8OSSakzlFZKUc4YUXXmD16tX4+/tbXYuja5TOlCpNXGvLwZXE3mDYAC8174yPpX/bEPKLy3lnXTKrDmeaX9fqZbcZDGtPoJNfXM5tH2+v9f2uCHSuBSLwCQT1gCvrb5aMi49gz6lcluxMQ6/XI0mSuZ1X586d2b59O35+leUjy7W1jc8MJDLIG4BvHzAazvu9vZGMi6XsPJnHvHVJfHlvD7w0SvaeyuXRWfM5/stCMjMziYyMpFmzZrz++utMmjTJuTVKJz6fu1gOriT2BsPOuS2GCr2B7m9soGO4P1/e14PEcwWknK/sJ+pOxu9r1UDgaiICn0BQD7iy/mbJuPhIFmxM5Z7/m8nsNYuYNWsW77//Ph4eHrz99tv4+fnZbVNlOR3cFkt2p7NkdzoAagXk/PgZl84bM47CwkLuvfdeRo8e7fQa5fShbZk2OJpyi+u57eNtpFp0anE3y8GVwt5gWC+1kpEx4Yz4cAsl5Xr2/X2BDYnZjIuL4O11ldMS3Mn47ao/UClB/7YhRFyejOHOuFN5WSBosNQkA6+N7i2DCPX1YM2xcxSUVeDn58dbb71FcnIyZWVljBplNBqbylA1TQCoCUmCoR2a8eLTT1htP3v2LM888wwbEzJtrlFOX3aI8wVl2OK3I+eImbWOTq+t4//+d4CJ3VtwR9cIhrZvyh1dI5gxvB07XhjCwqndG23QA/sZf+sQH/QG2WotLPFcIW2bVRd/mIzf7sDUXlG8PLoDXmqlw39vetm4zt3n7Y38c8k+DlvYH9wNkfEJBPWAMzLwqoyPj2Tt8SxKyvVmGbhGo6Fdu3bV9q2PMtSqxWuJjY0lJSWFsrIyzpw5Q7FOQeK5QsKDKqd8O7NGKcuwIy2Pdyd0ueYZy7XA3mQGbw8lRVprT5u9Vm7uZvyuzR9oi4YyqkhkfAJBPWBr4jmARqkwj48xCU8s8VApGBMbzo/7MxySgZvKUF5q5/7rWopKXnnlFQ4fPkxSUhJ9+vRh9erV3PHM21bjhxxlaIemHPrXcNZPH8BdPW5wm4zlamMv4y/R6vH1qNLKzcP29HjjcdzL+G3yB+54YQgD24WidDD7c/dRRSLjEwgcoLaem/ZM3TUJTwBGxIRRUFrBzpN5eKgUDsnA66uP5Q033MC2bdsASPrrrNNrlL8dPcd3e9LJLdLStUUQC++OZ+3xLKeO0Viwl/GfzC1GqZCICvbmdJ6xtVeHcH9Ssm1ndu5q/M64UMqWlFzsTbeKCvZm3VMDWHMsixk/HDJvL60wuI1i1RIR+ASCGnCm5+Z//kxmQ+J5JEVlNlab8GTV4UxWHc50WgZe330sXVmjTLVQJR5Iv8BXO04zrENTp4/TGLBn/C6t0LPueBZPD2/HCz8dpWNzf4Z3bMb4T3dUO4Y7G7/tKVZNzL6tE4cvN0moijspVk2IwCcQ2MGZnpubks8TmH0I2f9GJIWn0+dyRQZen30s67JGaUKWZdTK63P1pKbJDK+sPMa88bHsf2UYF0oqeOWXY1ZWBhPuavy2p1g1cWtsOAWlFRw4f4GWwT7VXncnxaoJEfgEAhs423NTq5M5538jwzuGseN0wVWdI1cffSxtNZ6uzRw/vEMzdp/Ko6BMR5fIAO7v24oEi2G01xM1TWa4VFrBI0v21/h+dzZ+1+RR9fVQMWN4O6Ys2s3kHi3s7uduo4pE4BMIquCsnw1g5sj2TOrRAgmjwu/+xfsazBw5sN94uqY1ylu7hPPOhFg0SgVZl8pYtPUkjw10jxvbtaCxGr/tKVYBnhnejh/2niHLjt3FhLspVkXgEwiq4GzPzSk33cDwjs0Y9eFWkGR+frQvf8wYwOurExrEHDkTj3y7r1rGUtMa5ZPfV4oYTI2n3TFjuVqYFLevr06gTOd4Xxt3b+Nmb/23Y7g/faNDGPPRVgeP4z6KVRH4BAILXOm5OT4+kv9uPWl+6l3wVyqzxsY0qDly0HgzlqvF4TMX2ZKSi6PTiNwp468Je+u/vVo3ITLIix0vDAHAW6NCqZBo27QftyzYZuM47qNYFYFPILDAlZ6bbZv5kphVWcZJziowZ00NZY4cuN6qyt0zlqtBbUKoqiglGN6xmVtl/Pawp1j9bk86vx4+Z/7+4f6tiQzy4pWVx6odw90Uq9enBEsgsENSVoFTI2UAfDQqCi3KOLnF5WhUDfO/lrOtqlQKiXbN/NiYnMP0ZQdZuDmNvCLtlb9QN6JSCOVY0AOjUKhfdIjbBz0wKlZtUVZhIKdIa/5XUq5DqzOQX1xebV93U6yKjE8gsMAVP1txuc6qBZWvh4qyCj2eamV9XtpVozaPoEYpmR8OFBJW/q2q3sYuLdz/xl4XbI0i+kfvlkyIj+TGMD9+PZzJsz8eqfa+Mjc1dttr1NC7TXCNlgaAD/5MsbndHRWrIvAJBBa44mdLyS6iQ7i/OQB0CPcnq6CMKBuepoaCPY9gbpGW45kFGGQZkCiv0sqjofRqrC9sGbuzC7Qs+CuVAW1D8ayhtZw7Gbuvt8HDIvAJBBa44mdbcSCDh/q15q/k88gyPDKgNen5JQ068JmwXKNMyynilo+2ojMYjeo1WTxMvRrfWZfErV2aE+CluVYf4Yphz9i97nLbts4RAYQH2G9m4C7GbkcbNbiCu67/isAnEFjgip9t6Z50WilB53oAACAASURBVDQx9ioEo0DmjriIq3/xV5DcIi1HMi5ZlfRqsniYuKdXK1Kyi4iNDGyw6572qOvwYbj2xm5nGjVYUlv25+6KVRH4BIIqOOtnA5i7Nom5a5PMfraH+reucf+Gxu5TeVbeRkdGFkUGeXFHXASvr0lg/sSuaFSNK+urydjtKNfS2G1rfRJg/p1d6dsmGC+NkpwiLZ9tPsmyfWes9pEko7BJKUkNwqNaFRH4BIIqCD+bNblFWtLzSqy8jY7w2tgY5q1Loqxcj1ZnuOYlvfqmLsOHrY/jmLG7tgkhzmKv8fQnm1J54acjlOsNtAn14fuHe3E88xLHMivb0clA/+gQerYObhAe1aqIwCcQVMFVP5unSnLL9Yy64kpJb0THZigliXUJ2fRq1cR4HDfq1WiJqwEl+8xpwLvO5z+XfpItW0oZMGCAzdedmRDiqIq2psbTlg20Zdn4r2Wwj3Xgk2F7Wh7zGujgYRH4BAIbODPzzoTOAFtTc+kcEdioZPxJWQVOzerzUiuZOaoD9y/eY94mI7tVr0aoW0BZtWoV235bRpOB9yArrG+jSoVkLAMqpGoiqapolBK71/3M6Ld/Y82aNYSGhqJWq4mONlYNnJkQ4oyKtraHmTm3dWJCfCReGiXHzl7ir+Tz1fa51uuTdUEEPoHADpZ+tj8Ssu0O4TShM8iNUsbvbEmvVYgPkUFeLP9nbwDUSgV+nmpmjY1x+Bj1XdarirMB5cVRN3JnXDg6nY709HTuvvtuSgxKAvvfjVRFs/PE4GimD2tn/t5SJFUVrVbLxQO/YygtZuDAgWg0Glq0aEFqaqrTE0JME88Bm397siwjXZYm17Y++a+Vx/j3qmPE3xBEr9bBlNvY190aTzuDCHwCQQ3ERgbSLzqETck56B0QMjhyA2poNPFW28xe7Fk8krML6TN3o/n98S2DmD02ho//SiUgdR033XQT/fv3t3muK1HWq4orAWXWL0eYNm0aZUf/QKerfBAoPbkf77Y9sYx+H/yZYtfMbYkkgZx5HENpZQmxvLycUaNG2RSeaJQK5tzWib7RwQR6a0jPK+addclsuvyzguoTzxcsWEB+fj7Lly9n2LBhzJ8/H3DsYcYgw76/L3BHXARTe7Vk8Y7T1fZxp8bTziACn0BQA6YRRaYMoLYRRb1bB/PkkLbERPhTWKrjSMbFBr/m9+7EruavHbV45Fi0LbtUUo5Bltnz1+9sWPAikiTRrVs3hg8fzpw5c8z7XamyniWmgDKxewu73VU81QpeHt2RMZ3DUSklEs8VMOnzXTQZ8iBZ51IgKxUAhUJB8Z4VeLWKR1I7n4V6KBVkbPsf3t7elJaWIl/+0F999RVb5PaU+Vl/NqVC4tylUiZ/vouzl0oZfGNTFkyJZ+QHW8i4WGrxc6o0xn/++eccPXoUgMTERHbs2EG3bt04rOwAvo4pj5UKiZZNbK9lulPjaWcQgU8gqAFnRxSVlOv4Yf8ZPA8rmDY42m06c9jC0XJibpGWHq+vQ5asW7DVZvEwsetUPr3fWMeZz1/HoDeqCHfv3k2nTp3M+9R3Wc8eJiVjTd1V3rojFpVCYtj8zVwsKadjuL/xBaUG/94TKVn3IV988QWTJ092+tpNGI3dHbh79jEkSWLfvn306dOHESNG8NGixQz9cGc1n1xphd4qk9yYdJ4z+SV0igiwCnyyDH8mZtOpe2+OXw56AHq9nj179hAQEEC3UYPZlAflVUSdwT4a+rQJ5s+k85RV6OkXHcLYLs158vuD1T6DuzWedgYR+AQCO7gyouhwxiUOZ1yib5tgwD06c1TF2XKirugCJal78WxzE5LCeRO6JMHNnSNZIukosdj+zTffcO+99+If1bnGLOy2rs158/bO5vcpJAkvjZJbPtrqVL9LSyWjve4qbUJ9GNahKb3nbqRIaywHmtSMkkKBV5seDBk/2Rz0wDkhlD1jd/fu3dm6dSuhoaGsTb6ISqWstbQe4quhdYgPKeerr7NVVFRQ4NsahWIPBosHt40bNzJ48GByi7T0fXsjYH0OGZjasyVv3N4ZSYKzF0uZ/VsCGxKri1vcrfG0M4jAJxDYoTF05qiKw+XE49lsTMyiU0UKv//nReSgG2gW1RVJYb8Flz08VUqmxofyjcGAUqlEr9fj4eGBr68vt99+O03Hv0JZcFu7WdjKQ5msPJRp/n5CfCRPDInmWGYBkkS1rDoxMZGHH36Y5557jltuuQWl0pipOvL77BIZyNmLpcwY1pY74iI5X1jGBxtSWHs5UGrUKvr949lq76utsbcjxu6ePY3l4qS9B2s1xqsUEh9MiuOnAxmk5RRX30GpZspjz/HwJy8TExND+/btkSSJiAhjR6EQXw8Gtgut1qghv7icSYt21fJTcs/G084gAp9AYAdnZfy2cFb5diXVjE6VE4EKg8R+/Q2oOwzh2dt70nJoV95ef8KlWX39Y1pSWlpKYWEhQ4YM4eWXX+b222/nXH4R/d/dhCxLDve4HB8fyYqDZ43XadHvUqkr5aWXXmLx4sWUlpZy4MAB/Pz8ePrpp3nkkUcc6rQSFuBJ+zB/1h7LoudbG4i/IYgv7+1Byvki0nKK0MkKTubZHrtkr7G3s8bu2oQnkmTsrlKhN/DqquM1HKeCjh27cvToUauysonruVGDCHwCgR2uZmeOK61mNIl0TEGrNpHOg31bcW+fKIK81ZRoR6NQSIT6eaJSKetU0vPz82Pv3r3m71cezUapVKJzsPVXRKAXN7VqwnM/HTZv0+v1jHx8Fge/m4fBYDCLREpLSyktLWXmzJnMnDmTsDtn4dG65vVWbYWBcp2Bj/5KRW+Q2X0qn50n8xjQNoS0HKOxu7bfp2Vjb9ODTOK5Ap776YhDDzL60poflN4ZF0uIrwf3Ld5T4+xIk/DEVtCD63vwsAh8AoEdXBlRZPs4an799Vc2bNjABx98YPZSmbgaakZnRTp/JGazfP8ZCsp0BHqp+P6R3oT6edZLSc8SZ/tdjouPYO/pfDIuVIo5dLJEtlaFwWBAkiRz4APQaDT4+vry73//m+QmvVl9vPpalSWJWQXVtlX9nfh7qsnNzeXs2bN06dLF5nFcfZApKytj88rvMMSMRmFDKfrG7Z2IburL3V/srvHn5qjwpD7WJxsiIvAJBHZwZUSRJBn9VmqlcY3KQ6HnwMZVLP15Abm5ufz8888EBwezYsUKWrVqdVXUjK6IdNLzLWQokkR+cbl5uG59lfTA+ax6XFwkn2xKrbZ9+OixvP/5s3z11Ve88847nDt3Do1Gw+zZs5kxYwYajYaFm9PYkJyLVmew211lz6l8Mi+V8vigNnyyKY2uLQLp3SaYuWuNP3OVJNM21NtcUl2+fDlhYWG0b9+egIAAoG4PMs8++yznd60itNOYau+LCPTi7p4t0Vbo2fvSMPP2l345arUGCs4JT+r7YaYhIMmyI82YBILGhStraSb/2rbnB5v9ayZM/rVerZrw/SO9rV7btGUrgwdW9mF84oknmD9/PpJCwcpDmcz44RBQe/nxkf6tGR8fSUSQFxdLylFKEuGBXrV+1oWb05BlmVA/D5vTwHfOHMKMZYeszgUwtktz3ri9E36eavKLy/kzKZuJ3VrUej5nmL7sIL9UuWk/M7wd4QGe1a61W8sgvn3gJnq8sYHiKjr8O7pGMH+S0W9oMBj44Ycf6N27Ny1btjTvY1IyanUGpg9ta9VdBSp/v22b+vL2+Fjah/lx9kIp765PZl1CNgCSQceZBfeiL6mcOq9QKFi0aBEPPPCAa2N+dFoq9vzAxX2/UlJifOAIueMlvNv2cllFO6JjM5dsNPXxMNMQEBmf4LrC2RLUsNd+IKXEy+oGVJN/bdepfKJeXA1U3oBK//iv1T4ZGRm8/vrr9L/zn06VHyUJnl5+iKSsQqKCvfmhSoDdvHkz48aN4/nnn+ehhx4iONhoqXBVpLPqcCarDmcSFezNuPhIcgu19R742of546E6h1Yn19rjcnx8JL8fy6oW9KqW9RQKhZXdwISlkrGm7iop54sY9+mOatslCUZ0juDvAb1Zu3atebvBYCAuLq5Wc3xkoBfbXhhCsbYyy124JY2PNqai7DER3Yn9UJJKaGgoTbL3URbdHXB+lFNdhCeW65ONGRH4BNcNTkn5E84RmrGNg3/+Quhdb7os4398UDSzVhQSEhJCXl4ekiSRlpbG2bwCmvSdRHhQ5ZT22sqPn205af46LaeY1UfPMbFbC9QKmbfeeos333yTsrIyZs2axauvvkqrVq2Ii4vjXNvbaDOom9PXb+J0Xgkp2YXc16eVw+9xNKOe0C2SeWsTAEWNPS49VApu6RzOo0v3VzuXM2W9+lAyPvrJJbMtw0Tv3r3p9tRCyhShNZrjAWJnr6/WsFpSagjqO5l7WpUxb948oC7G+IYtPLkaiMAnuC5Iyyky30TiWgTy9PB2dI4IQG+Q2XUqn1m/Hien0ChTl4F24YG8+uCzdP7sNSSlmvkbkvl86ymHz2d5A1qxYgUAv/32G3PnzmXr1q18tuUkdV1l6N4yiP9t2MOMu0ZSWFhoPl5ZWRkAycnJnDx5kpueGlKn8wAoFQrCAjy5ePEiqampdO9uu4zmbEbtp4bStH2oW3WvMQvT6gzEzl5fbbuzfrL6UDJ+/PHHXLp0iY8//pgff/yRTZs24RkYyl3/S0XGvjm+JiSFAs/W3Xjmxcq1u+tVeHI1EIFP4FZcCR9bbpGWIxmXzDe6AC81/9uTzmMpuegMBmaP7cS7E2K59yujzD7IW83X99/EnNUJ/JmQxfeP9KZT8wC81Mo63YBuueUWbrnlFqDuHsEZw9oiSRJvf7+BoqIiFAqFVQbi5eXFc889xyuvvMLinWecFulM6t6CDYnZ5BWXE93Ul2mD2nD+UglfzPs3n376Ke+88w4tWrRgzJgx+PgYs1ZnRB2bkrIZGJDP6g9mkmfwodkNsXXKqp2hrgElLi4OgP79+7Ny5UoGDBjAZ1tOolarHVKobn9+CDIy21JyefP3RC6UGO0RGo2GlUez+eeAyr+L61F4cjUQgU/gFlxJH9vuU3lWa2mW3ewBvt55mmUW62UP9WvNlpQcVh7KRJJgwV/GziBRIT71dgOqi0fwH71bMi4ukomf7aTf0JEkLn6ZnTt38uWXX/L111/j5eXFtm3bzFL7hwdUNiN2tMl095ZBPHvzjfh4KMkvLmf1kbPMuL0vpReNP7tnnzV2L0lOTqZdu3ZOq1O1elib7U1B0y708i9mbP8W/Hd/3lUr69VHQFEqlYwbNw5wzJaRX1LOrQu2kXCugCBvNbPHduLDSXH84yvj3MJyve2ZhfWpohUYEYFPcM25kj623CIt6XklVlL+qvRs1YSU7MobTtwNgSRnFfLTo31oGezNkYxLXCjW1usNyFWP4MRukTw2sA13fraTrIIyercORqFQ0LdvX/r27cu8efNQqVT4+/tbve+Rb/dVa09Vk0jnuZ8qFZUmkU6fbrH8+eefFtsliouLHZp40KdNMHPGdqJ5oBeHzlzk2R8Pc/YiNBn6EO8+3o8erZvSrFnNfweW11MfZb2rbcsoKddz9KxRDZpbVM6/Vx1n78vD8NEozYKdmszx14vw5GogAp/gmnKlfWy19WdsH+bHk0Pa8vC3+8zbwgI86dQ8gKlf7iY5q5BXRnego4VqsD5uQK54BG/r2pznR9zI5EW7OXOh1KZJuUmTJjbPVx+ijpeXeaFQKMxNj2VZpkePHsQ/tZAyTbhdUUeQt5qFU7sx86cj/Jl0nqeHt2PBXXHc8ekOJLWGL3ak06N102tW1quP36crDzLy5fkLCouGBg11zE9DQwQ+wTWjahut2kQni+/rQY+oJlbvN900du3axcyZMzlx4gRHjhwhJCQEqHktrWWwN4vvu4nXfktg7+kL5u3aCgPrjmdxJMP4dP7ehhPc0zuqXj+7K+XHZ4ffSKC3hlXT+prfq1RYd4GxR32IOt566y2mT5/O7Nmz2bNnD+fPn+f0uVxu/+pYjaKOkTFhpGQXseaY8fUPNqRw8F/DaRPqQ1pOsdUEi4Za1jPaMrJqNMd3jgigoLSCU3nFBHipmXVrDDvT8ii8bG9oyGN+Ghoi8AmuGVXbaNUmOrlvcWWPR0mCdU8NoF0zP4qLi3n++efZunUrAM2bN6dNmzZ07tyZv1uOos2oftXOHRHoxdIHe/LRxhR+vtzw2ERiVoHVLDRnxZeOCnTuXriZbacKHPYI9p9X+ZorJuW6ijo6depEp06d6NevH8nJyfj5+bH9wHlUKlWNI3TaNfMj8VxlK7DSCj1/55XQtqkfaTnFNidYNLSy3oRukczfcALAri3jZG4xz918I8G+GorKdGxNzbWac9eQx/w0NETgE1wTbLXRqk10YklEgBdtQn15+4MFzHrxObOEH4yzyJKSkrh06RJxseOqPXmH+Gr47qGefL3zb5buSa927OX7Mlg4tRuLd5zmRHYhTw6J5mROEbOf+z8eeugh+vWrHkjBeYFO9sZvkG8YfdXUjFA/og4PDw9iY2MBx0Qd3hoV+cXWEw0Kyyrw9TDefpydYOGOOGqOX3U40+b2hj7mp6EhAp/gmuDIbLSqohNLxsVHsOdULgvXH6aiosJq7UmtVrN48WKmTJli/Z7LT94y0DLYx9i2amhb8+sxs9YBsPNkHvPWJfHlvT3w0ijZdyqPmR98yYolS/juu++4+eab8ff3Z+nSpeaG044KdNYdz+KPo2cp3bmUrK3LadIzD/8B9yErHV/bqatJ+eqLOnT4Vlm78vVUmQe9Go9T+wQLd+d6HvPT0BCBT3BNqM3HZkt0Ysm4+EgWbEzl9nun8f7qzzl69CgDBw6kpKSEiRMnmoOeZX9GSz6080RuYsnudJbsNmaDkkFH+kf/wqDXo9frWb16NVFRUZX7OtVhQ8KgUKHuMYm4sDAO/PCfWoOm+Z31bFK+WqKOE9mFjLco4XmplbRsYj05vDGIOq7nMT8NDRH4BNeEmjIFe6ITE91bBhHq68GaY+fo3ToYSZKIjY0lISGB0NBQVKrKP2t7k6YdRZJgaMcwvq4owfJWdsstt1BUVISPr69TAp3pQ9sybXA05ToDcBt6g9ygTcqOiDrWJWTz4ugOjIwJ46/k8zw1tC1JWQXmyeGNSdRhtY5aoae2PzmFBPf2jhLdVq4yIvAJrgn2MoWaRCcmxsdHsvZ4FiXleqtMITw83Ob+dS1B3drag7XNmlFcXExBgVGkodPpePrppxk8ZRoa/2Dz/rUJdAB+O3KOGT8cshKoNFQ1oyOijg/+TOGxJfuZPbYTH0zqyqEzF3nif41X1DG1VxRnL5Ty2daTtT5sGWT4euffRAZ5ieB3FRGBT3BNsOVjq010AuChUjAmNpx/frvf4UyhriWo23pFcVtGBrIsM3XqVDQaDZ9++innC0pZvj+DZhbvcUagI8tYSfmh4akZHRV1bE/LY+j8zdW2N0ZRx5Jdp1m88zQ1DEe3wpUZi4K6IQKfoN5xRM5vy8dWm+gEYERMGAWlFew8mYeHSuHUsE2oW8NfSZJYunSpuRn0ioOZVuZjW9gS6Azt0JRD/xrO+UIt3+1Oryblb2gIUUcljnSxMfHkkGieHn4jd/93F9vT8nhjTRKxkYFuVcpurIjAJ6g3nJXzj3nrF45dVFr52GoTnZhmxLmSKdTXWppJyemKQOe3o+f4bk86uUVaurYIYuHd8ay9bPxuqLiaUXuqpEYn6vh4UyplOn2to4luaOLN6M7hZBdU2nDKdHo+2ZTq0gBZgXOIwCeoF5ybdZdFZM4edq1ZVudZd85ytaT89gQ6qeeLzF8fSL/AVztOM6xDU6c/h7vhTEZtQmeAram5dI4IdLrxuDuSW6Rl84kcZLn20URzboth7tokXr+tk3mbrdK34MogAp+gzjjVbxOokCXS/LsQ0i6V18fH89bvSVdd/n0lpfyOCHRMyLKMWlk9I2iIWGbUfyRko68l+OkMskuNx90VR7ypAKM7hVGuM7ApOafaa7a62AjqHxH4BHXC2X6bADNHtmdSjxbArVToDSgkqUEO23RFoDO8QzN2n8qjoExHl8gA7u/bigSLdl4NndjIQPpFh7ApOafGNmYmXGk87q440sXGR6PkuRHtueeL3TZfbwxdbBoCIvAJ6oSz/Tan3HQDwzs2Y9SHW0GS+fnRvg3Wx+aKQOfWLuG8MyEWjVJB1qUyFm09yWMDG8/TvUnccWcP2+IOtVLiw0lxxEYGEBnkzeTPd7LrVD6lFYYGL+5wpIvN9GHt+PlgBhkXS2s4TsPvYuPuiMAncBlX+m2Oj4/kv1tPknV5UX/BX6nMGhvTYH1stubc1STQefL7Q+avTT4+d/xcruKIuGPf3/l8uf0Un0yJt9re0MUdjnSx6dsmmLAAL+7p1RKAJj4efDwlnoWb01i45eTl4zT8Ljbujgh8Apdxpd9m22a+JGZVfp+cVWAVNBqaj01I+StxRNxRoZf5cvtpAPRV6toNXdzhSBebKV/sRm2hYl45rS+vr04wPzA2pi427owIfAKXcUXO76NRUWhRysktLkejarjiDiHlr8RRcUdNuKu4wxFvqqNdbCwxyDKXSisouTyBvbF1sXFXROATuIwrcv7icp15HA2Ar4eKsgo9nmrlFb3WK4mQ8htxRNxRG+4m7nDWm9oxUObAeUONXWwssZy/2Bi72LgrDfdRW3DNcUXOn5JdRIdwf/P3HcL9zet9DZmpvaJY9kgvRnRshtKBoegmKf/kRbtYsuv0Fb++q4Ej4g7HjuMe4o4lu04zedEu/kjMRqszVAvqZZe3rT+ezYSF27jjufdZ98EzyPpyl87X2Erf7ozI+AQu44qcf8WBDB7q15q/ks8jy/DIgNak55cQFexzDT5B/XI9S/nBMXGHY8dxXNzh6LR7Z3Ham2qQ2G9oiU9kB54eHMVnu8+L0URujAh8ApdxRc6/dE86LZp4s+6pAYBxXeiOuIiret1XCpOn0WTFcMTTCMbsr3ebEMp1hga93umIuENvkNEoFZhanKpVCjxUCnM2ZRJ3PPbYYzRt2pTXXnvN5rmcLUE6Q239NqOb+vL+xC60vPywdvTsJWb9epzU8xA05EGGdGlDSHBwg/SmXi9IsuzKlDKBwIgtOb+jWI7laQxsSj5PbpHWfIMc1C4Ub42SLRaexmb+HlYjisCoDB3YLoS2Tf0I8tFci0uvFyyH/k4f2tZK3AGYxR3bnh9MZJC31Wv93t5o9LbpK4hOWMymtb8BcNNNNxEYGMjrr79OfLzR/nClB/ea/qZv7hiGLMtmS4bp9+rvqcLfU03GxVIUEvyjdxSTurdg1H+2Wv1NH8m42OC8qdcLIuMT1Akh5zfiiqcRIDLIizviInh9dQJzx8W6rZTfkZJiiK8HA9qGsP54Vo3iDktBhyWSBF2aqln17irzBIydO3ciSRLz5s0DnCxBulBKdsSSUVCmM69nSpKE3iCbS/WWloyG6k29HhCBT1An6jrrrrE86briaQR4bWwM89YZp3WD+0n5nS0ptixOQtZ7u9x4fNadPdnxTgg5OZUPDbIs8/PPP1Pq3bTGEmRNpeWqXWHOnz9PVlYWOTk5DB061HwuZywZR169GW+NEoUk8f5lGwNUt2Q0NG/q9YAIfII644qcPyrEh84RjSPogWueRqMCVGJdQja9WjVBRnYrKb8zEzc2HM9Ec+w3kn5bhH/8GJoMfQhZ6bhIxfQg1C7Eg44dO1JSUsKBAwcAiI6O5rfffuOzBBllyzi7XWFqapdn2RVGlmXuv/9+1qxZg1KpZNGiRYwfPx5/f3+nLBmxs9fjpVYyvlskZy9UtiBzN0uGoDoNdyVd4FaY5PwdwhzrOpGUVXjdSPlteRq91EpmjurArF+PVzmO41L+3CItCzenMX3ZQR74ei/Tlx1k4eY08oq0tb+5FipLirU/yMiAHiXF7UYQ0usO8nb/wpxxXfFSK6llTi+SZPxZvDy6A1N7ReHt7c2mTZvYs2cPK1euJCoqisOHD/Pbhs14tooHJNYdz2J9QjYXSqxtA5tO5LDmWBZFWh1lFQa+3nmabi2bGK/xcgnyyIlT9O7dm3XrjGIrvV7PAw88QEBAACEhIfy4crVTP6fSCj1Ld//N+3d2IdhifdZdLBkC24iMT1Bv+HioOJVbDNSuaOzVKpgnh7SlU4Q/RVprU3tDxFlPY6sQHyKDvFj+T+Oan1qpwM9Tzfw7u5KXl0dCQgL9+/e3ecwrqWg0Hf+ddcnMurUTfaODCfTWkJ5XzDvrkitba6kVvDy6I2M6h6NSSiSeK2DS57sIGHw/CVlF9dJ4fMyYMYwZMwaAr3aloVAowOB4Ob1qaVlbVka/e56lcI/1ZASFQkFoaCjvvPMOO+R2rE3Kc+KnBQpJwkutJMzfk7xiYzAW/Tbdm4Z9txG4DblFWo5kXDKv89U2paGkXMcP+8+w6rCC/xvclpM5RQ16vc9ZT2NydiF95m40fx/fMojZY2P4aVcKO799h6VLl/LKK6/QsmVLJk2ahK+vsYzqcPmxDnPuPt6Uis4gc+5SKZM/38XZS6UMvrEpC6bEM/KDLWRcLOWtO2JRKSSGzd/MxZJyOl5uSqCXFeaSYn2KO5ztCmOrtIxKw5THn6Xno7fw7rvvkpCQAMCTTz7Je++9h0KhoGRzGn+lXqjRktG7dTAXistJzCrAW6PimZvbcam0gtQc45Bh0W/T/RGBT1Av7D6VZzWeqDZF4+GMSxzOuETfNsHIyG7dld8RRaOznka9QSbHoiR5qaQcgyzzxO39MJQa5/PNmTMHgGHDhuHr63vFFY2mz7r5RA5ancFKlbkx6Txn8kvoFBGAh1rBsA5N6T13I0VaY4n3WKbxmmWqN5quD3GHM11h7LXLA6hAxf3338+dd97Jo48+Stu2bXn00UeN2SSO9ds8kV3I/jaudwAAIABJREFUa7fGEBbgSVmFnsMZl7j3qz3mwCz6bbo/IvAJ6kxukZb0vBIrKX9VbCkaLXHHrvzOlhRvnvMjyUUeSBbd92saUWTJ7tP5vPbrcUYM6svvv/9u3i5JEunp6VxUBNRYfryta3PevL2z+X0KScJLo+SWj7banHNnMBhIT08nKirK6jrsqRpDfDW0DvEh5XwhXSIDOXuxlBnD2nJHXCTnC8v4YEMKay/L/69Eo2lHu8LU1C7PeBxjCdLHx4dvv/222ushvh4MbBfKH4nZNVoy1hzLsrld9NtsGAhxi6DO1CYBN5Wd3vw90e4+ppulu+Bwn8aEbO78bAePvbeUrQtfrnOfRp1OZ84+wCjlHzJkCA+8twydvrL82Pm1dbz7xwkWTIknMtCLlYcyiZm1zvzvXyuP8XdeMccyC8yKRhNarZbJkyfTqlUrunfvzvfff09JSQlgu6SoUkh8MCmOnw5kkJZTTFiAJ+3D/Cks09HzrQ38e9Vx3pvYxaxqvRKqRmNXGOPPRXm57GhZglQqJJr5e9TYLs/REuS0QdF4qlxrmt6YvKmNGZHxCepMTVL+mspOljh7s7xSPRrBeZO0Vi+zOtMTTVg0E9ooWJOpsBJy1Ialp/GTTz7hwoULvPrqq2zfvp2cnBz+zs5n1Kf70Ffo7ZYfq070Hh8fyYrLGY+lqfpU0lEmTpxIZmYmAPv37+eee+5Br9cTHBxMk9tfgpDK8p4kwfw7u1KhN/DqKqMCVVthoFxn4KO/UtEbZHafymfnyTwGtA0h7fI6l7PqVEdG/rz/RzJgvwRZW7s8R0uQwpva+BGBT1Bn7K2/1FZ2qn6c2m+WV1rRaOq3abrh1aZOfbBvK+7tE0WQt5qS8jEoJOh2PIvXXWypFR1tzBZWrVrFmTNn8PDwYOOpElQqVbXG15blR0siAr24qVUTnvvpsHmbrqKCmyY/xcnVn1W7Dp1Oh1KppHfv3vh1iWH72crfwzvjYgnx9eC+xXvQGYwfJjGroNoxqn5Of081b731Fl27dmXUqFE2P7+zv0v/4gxyNOE1liDtlZadLUE6400V/TYbHiLwCepME291NeVbbVMaJAk0SgVqpbF85aFSEOStpn///jz11FNMmDCh2nuuhqJxy4kcK5FOberUPxKzWb7/DAVlOgK91Xz/cC/u7hVF5zpK+dVqNa1bGwUzjpQfLRkXH8He0/lkWJiq9ZKS9t0H0F4+w+7duykpKaG0tBSlUkmfPn1YunQpLVq0YOHmNPZln0CrM/DG7Z2IburL3V/stjr/nlP5ZF4q5fFBbfhkUxpdWwTSu00wc9caS9kKWcffh3fw8bv/BuC2227D29ubhQsX4uXlBThnjt+YkEXQ6b84tuk3mk15CxTOZ/SulCDrw5IhcE9Ek2pBvWMqO80Y1o5irXU2aCo79WrVhO+r9K3cffQEvbu0ByAwMJC+ffvy66+/As6VH00YS08dnFI0Lt93hlA/D3MbrKrENPdn2SO96XT5c1gS6K3mkynxxN8QZB6sWx9S/ge+3svGpPPm7yUJ/jMpDl9PFQ9/s8+ciZn465lBfLIpleVV1l6Htm/KF/f2QJZl9uzZw9SpU4mPj+f7779Huuw0NzWaDvH1YPsLQ9BW6K2O/9IvR1l5KJO2TX15e3ws7cP8OHuhlHfXJ7MuIdt4fQY96R/dY1anglFMkp+fj0ajcel3aSgvI6YimbunTLnifwe2EP02Gxci4xPUiCPrL7lFWnq9uQFdlUeomhSNu07lE/ViZZcMyaAj/aN/mJsTX7hwgYkTJwLOlx8f6d+a8fGRRAR5cbGknHMXSwkP9Kr1s7rab3Nsl+a8cXsn/DzV5BeX8+uRTCZ2awHUj5S/qqLRVvnRRLeWQTTz92DN0XM2jmNUNEqSRM+ePUlJqf77sVQ1Wv5+qpJyvohxn+6otl2SYETn5qzw9SDHYtmxuLiYNWvWENVtYI3q1MhAL7a9MMTqgWnhljQ+2pjKKe84YiMDeXl0h6teghT9NhsXIvAJbOLs+ovuzGHk5p2tpPyOIkkwtGMYi8utS3a//PILPj4+NInp51T5UZLg6eWHSMoqJCrYmx8sMktZlpk6dSqHDh1i8eLFdO/e3ZztuNJvE2DV4UxWHc4kKtibcfGR5BZqzYGvPrCcc2ev/GhifHwkvx/LorjcelqGM6bquk7cuO+m5iyrqMDb25vSUmP0Cw0NZdq0aXiPmI4qspNdc7yJ2Nnr0VcJ6lq9wcocL0qQAlcRgU9QDcfXX7LYcCyTsp1LyUs5RNjdc0Hh/Dw5T5WSSZ0CORwXR25uLn///TdNmzZFrVbzxZJljJoWQ3hQ5YT22szxn205af46LaeY1UfPMbFbC7IzzzBlyhT27NmDXq9n0KBB+Pj40L9/f4YMGcKRnFDahMbZvEZH1Kmn80pIyS7kvj6tHP7sjioa5284QUSgF3f3bIm2Qs/el4aZj2EqP3qoFNzSOZxHl+6vdh5nTNV1VTX2atecCxcuIMsyTzzxBAcPHmT79u2cLyilz9sbKa2wb44/dvaS3eOLkT+C+kIEvgbKlZLzp+UUmW949idNGyXrMhLtI4J49csFdL0hCIMsMX9DMp9vPeXw+Uw3y+Hdohi+dy+yLPP8888zYMAAbr31VhZuTsNQyzJ0beb47i2D+PC7X3n5wfEYLDLHkpISSkpKWLFiBfv376f5+Bdtvt8ZdapSoSAswJPc3FwCAwNRqWz/F3M2o24fYOBQTnGN5UetzkDs7PXVtrtiqq4PVaMkSSxYsAC93pg5rjiYiVKhQGeoXZ26/fkhyMhsS8nlzd8TuVBiVJqKkT+C+kAEvgbGlZTzV+23eb6gjMeXHrCaNP3R5DhG/WcrAEHear6+/ybmrE7g4SUH+O6hnnRqHoCXWlmnm6Vp6Ci4Xn40MWNYWyRJYuEaY1BVKpXmG7FGoyE4OJhly5bRv39/Fm056VS/TYBJ3VuwITGbvOJyopv6Mm1wG3KLtIzt242Y/2/vvMObLNcHfH9Jd0s3HbRA2ZTSQhlSpsoUZIioIHIURXAexe1xHJWluP2JiuIAxYGIHoYoUEbZoyCUVQpltUA33Svr90eaNGnTNkkHSfve1+V11S/Jl6Qp35P3ee/neSIi+PDDD3F3d6dt28rUpyV2alxSJlO7OBL3+St43vlfq+fcWVNU3VBWo1yuFX3MsVPdnORMWLKbU9fy8XFzZN7EnnwyNZr7vzsIiJE/goZBBD47orF1/qr9NmubNA3w8JCO7DybydqjV5EkWLJdu/8S5u/eYPsvlo77MeT+ge25MzqUu7/cx4jb7+DDZS+yZs0aPvzwQ06ePMmkSZNYvnw5bm5ugOX9NkG7mnx+dDfcneXkFJXz57ErPHvnEIqvZ3D58mU2bdpETEwMe/bsASwvji9VqPnuWB4qrxCGumcSr2pLmQVbb/Utqm7IlGLVz9JUcXxxuYrjFenOrMJy3lh3kkOvjsTdSa7ftxQjfwT1RQQ+O6GxGxTX1m+zpknT0e28OZNWwJpHB9Hez42E1DyuFzXs/oul43503N03lMdu7sQ9X+4jLb+UgR398PLy4qGHHuKhhx7i9OnTdOvWzag9GMCcH+LZcjrd6ItFbXbqC2sqyx4kCXr7SZTkVu5BqtVqfWA1Z9zPoE5+zJ/YkzberhxNyeX5345xJRcCbnuUl2YPIyE194YUVTe1napDg/a4zGCwnxj5I6gvIvDZAVV1/rr23pbP7E//MF+jxxteOABKS0txcalMm9Wm8tc0aTrIy4WebbyY8e0BzqQV8Nq4cHoYmIMNcbG0dNwPwKTebXhxTDemLTtAyvUSk0ZjeHi4yeerr9H44vhI1r8k06dTAWJjYxk5ciSetz+HUi3VaDQWlStZOqMvL69JYGtiBs+O6sqSe6OZ/MVe1Mjt3mg0x07t3dab/BIFF7KL8HJ15M0JEexLzqagorxBjPwRNASigN0O2HEmg6zCMn1RtaeLA54ujkZ7b1P7tdXvvRkiSbDp6WF0DdReLJ588klWr16NQqHgwoULeHl5ATB31T90au1BsJdLjcXbkgRHXhvFyA/jyC4q56+nhnLiSp5+1ePt5sjR10c3xq9AjznF8bteuJUgLxfKDS6ocpmkLyqvi/oUy0/pFcgXX3zBpUuX+PTTTxk9ejTz588ndtcBvkwLBXn11cpfTw3lk61n8XFz5K6+bZmydG/FOeX88/oobv90F8mZRTg7yNj70nD9atnejEZziuM1GnhhdDf8PJwoLFWy61wW7/yVqB/hVPV3IBBYg1jx2ThZhWWcvpZvlIKsa+/NkBAvVzq19uB6URkn/znEN998Q2lpKQB+fn54e3vTp08fUjtN4LG7b6v1tVSdNH06LR/Db02WfoUy10wd8p/vSVH7mD3uZ+h72/U/SxKM6RFo0ay/+hqNzz77LADjx4+nW7dutGvXjsPFvjjHJlWTOwyNxhkD2nP6WmW3kxKFikvZxXQJaEVyZpHdG43mFsevO3bV5HEx8kfQUIjAZ+PUloKsae/NkDv7hBB/MZv7nn6d5A1LjW5TqVRcv36dwMBAWod3tnjS9Or4VJbO6MvyvRdJSi/gqeGdOZuezwOTb2PVqlVGJqMhlpip7Tw0HP5hEa2nLbQ7o3HUqFH6n80zGh3IKSozuk9BqQIPZ+0/0+ZgNNY3lSxG/ggaAhH4bJzadP6a9t4MubNPKEu2ncMlsAMBAQFkZWXpa9kiIiLYtm0bAQEBxo8xc9L0vvPZvLcpkW8f6I+rk5z4C9k88voH7Nu3j+7duxMZGcnw4cNZtGiR/tzmmqmbTlxj07EUsrcuo/TKGVqn7CKv4wiUFoyQtD+jUYlHFXHDw8VBP+Vcex77NhrFyB+BLSACn41Tm84P2nTYjwcuGe296ejX3ofWHs5sPHGNgUNv5ZuvXyQhIYGbbrqJdu3a8fbbb+uDnm7/peqqpKZJ0zpWHrjMygMVgolKQcrKjwFtcXi/fv147LHHKu9bsXcW4uNWq5wzd0QXnri1s3aPbsEEHGTg7OhQZ9DUYa9GY1J6AVMMuqu4Ospp72tc2N0cjEZLUsk6wvzdiQwRQU/QMIgJ7DZOTTq/IYZ7b4ZM6RPK3yfTKC5X6S+YUVFRFBcXk5SUxIQJE/T31e2/VJE/zUaSoE+QM5rSyov01atXefnll8nOzianqJyFGxMpUaj1hfG95m0mev5mYk+n8+k041ZhGxKu6aeJ954fS0JqLjNiwlg1J4YxPQJxdpDh4mD85+viIMPZQcaYHoGsmhNjU7PRDCeI64zGWd8fMvqiselUOl2DWnFbRBDODjKeHtGFxLR8/dih5mQ06j7L8CDz3k9iWgHTlu1n5f6LjfvCBC0CseKzcUzp/HXtvYHWfrs9KphHfjhc7YJZtXZNR333X2I88zjdrRvXrl0jPz+f3bt3061bN1auXEnbfiMoUSgBySI5B6BUqTJS+e2xR6O5/TYfW3mYeRN78vHU3hxNyeXfP/+jv48l/TbtgRNXcpk1uAMDOpquadTx1PDOPDuqG/d9vd+i2lSBoCZE4LuBmGM1muomUtfeG8CYiCDySxTsO5+Ns4PMrAtmffdfZsSE8eLDUykqKmLMmDG89tpr3HbbbRSWlrPpZDraTouV1CbnjAgP4Ojro8goKOP7fRdZfTiV7MIy/e+luRqNe5KzGfFRXLXjzc1oPJaSy/ubz3L/wPZ8ZKKmMTVXu2fdzteNcZHBpOdrTeQShZqFGxOJCvUW+30CqxGB7wZgab/NB5btZse560Y6f117b7pROZZeMBuiObG7uzu7d+/W//+Z9CL96B9DapJzNhy/xk8HL5NVWEbvtj4sva8PJeUqI5XfHhFGYyWf7TjH9ZLyGqc06ALf/EkRvPN3Igsm9dTfzzADIBBYg9jja2JW7r/ItGX72XI6nTKluppMUlpxbPOpdP2exvW9q9Coyms4Y+1Yc8Fs6L207MKyGics6OScD+/phZ+7dqTRuYxCMgrKUGvgyOXrfLf3IiN7BNq9yq9bUbs6WvbPzsVBalZGY1ZhGXFJmdW+VFWd0jCuZxDlSjU7zhinPg3HEwkE1iBWfE2INf02X/3tCNePnScktAxFxIQm0/kbci+tTFX7+61aGF8VjUaDhGT3Kj9YZzQq1bDrXBaRId4WT9ywRUzVplataXR3kvPCmO7865sDJs9RtZhfILAEEfiaCEv7bQK8fFt3pvZvC2+NR6FWs/lkWpPr/A2xl+bqIEOhUpst54wKD+TAhWzyS5X0CvVi5qAOvLc5sVmo/GBcHL/lVDqqOoKfUq2xeuKGLVK1mN9UTePckV35459UfcqzKs2hmF9w4xCBr4nYmZRpNPKnrll3029qx6gegYz9ZBeg4Y/HBjfYfLSmZmSPIMB8OWdCr2DevSsKJ7mMtLxSlu5M5s+EazwzquuNfBsNSlSoN0M6+7PjTCYqZeNM3LBVqtammqppHNzJjyAvV/4V0x4AX3dnPpveh6VxySzdeb7iPPafARDcGETgawKs6bc5pU8oX+86T1qFzbZk+znenBhhlzq/qeL42uScp345Wu2YuWaqvXAsRTteSK2BxXdGmRxT5CiX+GRqNFGhXoT6uDHtq33sv5Bj91ajYW1qTVMapn9zAEcDmWvtE4NZ8Ocpo1KH5pIBEDQ9IvA1Adb02+wS6MHptMpUzpm0fKP0pj3p/IYqvzWzQJqbyg9aq7FUqcLFQV7jmKL0glLiL+Xw7Z4LfD69j/6x9m416sYT+Xs411rTaIhaoyGvREFxxTDa5lTML2h6ROBrAqzpt+nu5ECBQSonq6gcJwf7lXCFyl+JodVYolDVrPSfLOHbPRcBUBl8YzC0Gm3ty4A5tal39Q3l/U2nuZJbUmtNoyFD3t1u9P/NrZhf0LSIwNcEWNNvs6hcqe/KD+Dh7ECpQmX2TDlbw9ri+Oam8kPtGYCqSn9N2JrVaEltalSoF2UXjiBrF21Um2ouzTEDIGha7HcJYUdY02/zbHoh4cGe+tvDgz31+332yoyYMF4dF46ro9zsnqA6lf9YSm7jvrgmxNSIIqiu9NeGLVmNZtemnkznzs93EnrLvWTsWImkrv0LYU00twyAoOkRga8JiAj2wslBpu+3KZdJDOnsT0SwJzJJu5p77fZwI6X/9yOpPDykI4GezgS0cmbOsI5czim+we+k/hgWx8vNCH46lb85NSg2lQEwpfTXfZ4bbzVW1qbWXZOoAVTIkfe7m+cWfsKCKdEWF/OL8USChkCkOpsAa/pt/njwMm193dj09DBAmx6bHB1yQ15/Q9OSVX4wnQEwpfTXfR7zrUZzp91bwrGUXN7ddIY3J/Q0aaXWXKsKf1yUmDbam1fHhd+QUVOClo0IfE3EnB/iq1mNdfXbfOfvRN75OxFJgjE9Anl4aMda728v6Ir5dTWI5hTzg3b1N7CTP+VKtV2LPjqrUfclpyalH8BJLtOnhR0rWsWVKdV6q/Hjjz8mJyeHefPmmXwuS/vCWsJnO86hVGtqtFJrq1WtOnHD3mpTBfaNpNFYI5gLLOVYSi7Tlu23ymp0dZSzak5Ms/lHv+NMBlmFZTz/WwKgXQF5ujgaXSCn9murL+bX8cQtnbm5qz9dAlrhU9HX0x4xrGsM8XZlz0vDKVOojFZ6OqV/94u3EurjZvT4IYu3kZpTwNDsv1nz0woUCgU333wzgYGBPPvss/Tt2xeoe9q9DmtWUzUNLgb466mhfLL1LH+frPxiJ5dJTL+pHa+MDSf8jb8BbW3m3peG61ec9lSbKrBvxIqviajvyJ/mEvSsKeYHCPVxZXJ0CAv+PMU7d0bZpMoP5qUU/T2cubmLP5tOptWp9FfV+EEbqCJ9JX56/yvUFd2Atm7dikwm49FHHwWs6wtrSSq5JjPVlJVaU61qVTPVnmpTBfaNCHxNiDUNisP83YkMaR5BD6wr5gd4a2IE721KpLRixWxLKj9YnlLsrDjP3yoHJJmLxc/l4iBn4X2DSfk5kmPHjumPq9Vqtm3bhke7iFr33qLbevPsqK5EhnihUmvYfyGHN9efJLOgrFpXmHfeeYdNmzbh6urKxo0b9c9lykytyUqtqVbVlsxUQctCBL4mRtdv8+XfEzhlxj/6xLQCpi3b32w29a0p5tcaoBKbTqUT08EXDRqbumDWlVLU7VltPplO7MmruCX+xYn/LcUjeix+I2eD3Py0rWEGwMnJiY4dO3Lx4kUAAgICWLVqFd+edcCtY58a9968XB35+eBlHjubhVKtZt7Enrx/VxQPfHfIaO/twoULLFiwgKIibRALCgqie/fuDBo0iL3lncExUP+66rJSTdWqgm2YqYKWhwh8N4CE1FwuZNVep6WjuRmNlhbzF5ereHlsOA8uP1jlPOZfMBvDaNRhUUoRrc6f13EkvgOucWXHL/x21PqJGwcPan8nGzZsYObMmSQmJqKQuzDw7VhKFOoaO8IY7r0BrNh3kVVzBmpfowa2JmZw94wH+eOXH1CpKvek09PTSU9PR61W4zcyigyDwQnmWKmmxk+JfpuCG4EIfE2MpeOJBnb046nhXYgI8aSgRElCaq5d7/dZWsyvQbu/t/oR7YXZUS6jlYsjH93TmzNnzpCRkcHQoUNNnqcxjUbd+RduTGTR5CgGd/LD1UlOZmEZX8adZ1V8ivZ5HGW8Oq4Ht0cG4yCXOH0tn6lf7cfn1lkkZZU2yMSN8ePHk5GRgUwmY2lcMjKZDNTGgbi2jjADOvhyNr3yuKKsjJ2p5ajVauRyuT74hYSEsGXLFsLDw1kal8z52CTKlOoardQhnf1rHT8l+m0KbhQi8DUxlo4nKi5X8uvhFFyOyXji1s523ZwYtMX8ajT6Yv665vMp1RoGvbNN//g+7X2YNzGC5bFH+GX+Exw/fpwXXniBgIAAnnjiCZyctGlDs9OP9Zhzp2s0/fmOc7y0JoFylZpOrd35ZXYMJ6/mceJqPm9PjsJBJjHyozhyi8vpUdGNR4XMSOev78QNWUXrL0v23gC6B7XiqeFdmP1DvMEDnJj+2Au8/fc3fPnll8ydOxcnJyeWLFlCeHg4oO23+VFsEiHerjU2mlYo1bXWqop+m4IbhQh8TYg1RuOx1DyOpeYxuJMfYLvNicG8lKI1xfyZhWX6x+QVl6PWaHhlxljUJfmAVsBwcnLikUcewcnJqdGNRt171TWaPmtQb6jRaP9r7+dOiULFyPAABr6zjcIy7Wd84qr2NWuo/lk2hNVYNZVc295bez83ls+8ibc2nOLQxetVzqPAxcWFp556ittvv53OnY1bhBlO3KjNSq2pVlX02xTcSETga0KsNRoNsbXmxGB5SnHwyytI1fgaNSiuq5hfx4GLOby1/iRR3Tpy9Gjl3D6lUklCQgKuId1rTT9O6t2GRXdE6h8nkyRcneSM/3SXyTl3CoWC06dPExUVZfQ6qn6W8yf15K4+obg6yTlxJY/tZzK4LSKIK7klPDOyC5OjQ8koKOXj2Mr6tsb4LKumkmvaewvxduXHWQP4dNtZ/vjnionzaPfeJEmqFvR0iIkbAntFBL4mxBqjsSq2poBbklLckZhONBeJX/EJgfe9bbXK//gtndn0ei6SJGHYf+GWW24hfM5HlLq3qzH9uPboVaNZb3f1CeXfwztz4mo+koRRKjknJ4fx48ezb98++vbty7///W/uvPNOWrVqVS2l+PraE7yx7gR92vkQ09GPcqWaIC8Xugd58veJNAa8HUufdj58+0B/zmYUkpxZ2CifpWFXmJr23gI9nfnp4QGs2HeJHw9eNvE7Nm/vTdSmCuwVEfiaEGvGE5k+jx0ajRooU8He8iBatY/god5e/JKkoNTKC+bOnTtRKpXMnj2blJQUEhMTSU7NYMznB9FQc/pRl2rUMaVPKL9XrHgM59zFbf6Thx56iMJC7XkOHz7MrFmzmDlzJr6+vvhM+g8EhhudS62B+EvXmRwdwoyY9pQp1JQr1Xy6/RwqtYYDF3LYdz6bYV38Sa4QPBr6s7yrbygfbjlT695bmJ877f3cmTuiC3NHdNHfFvHmJu3vAfP33iypTRX9NgW2ggh8TYilRmNNgc/TxZGSkhJcXV1rPE9jG42W2qmzBnfggUFh+Lg5Ulx+OzIJupxMY4GVF8y2bdsCsHHjRvLz85EkidjzhTg4OOgbX5tKPxoS4u3KTR18eWFNZRG4orycnhMfJm37yurvWa3GwcGBCRMmoO4fzc7LpsdEyWUS7X3d2HI6vdptVd+np4sjL7/8MhMmTGDw4MEmz2fpZ+lVlEqqIrjWvbdPDEodDLFm760hzFSBoCkRga8JsdRoBO2FyEkuw1Gu3Q/zdHGgi78LgYGBzJ8/n9mzZ6NWq/HwqEyhNoXRaKmduuV0OqsPp5BfqsTbzZFfZsdwX0wYkfW8YDo5OeHv7w9UNxpNpR8NubNPCIcu5pBqkFpWyxzoM3wCrQIUbN++neLiYgoLtQF1/PjxLFu2DH9/f5bGJXPgahIezg4M6uTH1sQMShUqhnT2Z2KvNjz1yz8cvJDD1bwSHr+lE5/vSKZ3W28GdvLjnb+1Io1Mo+LSsb2se/99Pv74Y6ZOnYqLiwtLlizB0VG7x2ZJcfy2U2n4XY4jYevaeqeSLaUhzFSBoKkQTapvIDqj8blR3YyMxnc3JZKYpt37iengyy8VxcU6du3Zy7AhlauDgQMHsnfvXsCy9KMObQox3CKjcXV8Cq1bOesbTRtiqiGxId5ujnw+vQ992vnoJ8o3xAXzoRWH2JaYYfK2hXf05GxGIcv3XtQf2/7cLXy+4xyrq4gqI7oH8M0D/dFoNBw4cID777+fKVOm8Pbbbxv9DgYv3oa7swNfTO9DeLAnkgRXcktYvvcivxzS1vF1CfBg8ZQouge14sr1Et7ffIZNp7QrQUmt5PKn9+vtVABvb2+ysrKQy+VWfZbq8lI65h0bKwogAAAgAElEQVRl1qxZLPqrcf8OBAJ7Raz4Gghz99Lu/r8tHLxSarbRuP9Cjj5lJUkQqslm9zsPGN1n9uzZgOXpxzlDOzKlTyghPq7kFpdzLbeEYO+a06c6rLVTJ/Zqw8I7etLKxZGconLWJ1zl7r7alGVDqPy1pZJ16Ucdfdv7EOjpzMbj10ycp9JojImJISmpumVrqPNPXba/xuc9m1HInV/srXZckmB0zxB+QIGhypSfn8+BAwdwb9ujVjs11NuV3S8Np6isct946c5kPt12jrTgQRXiiZh1JxCYQgS+emLp/kvyus/R9J5hdRrqjTsGMuod4+Pr168nLy+PHsOnoDL4gl9X+lGS4NnVR0lMKyDMz41fDVaWRUVFDBo0iMuXL/Pll18yceJEXFy0r9laO3XdsausO3aVMD837uwTSlZBmT7wNQQ6o7G29KOOKX1C+etEGkXlxiq+Jd1E6qvzT+7uzionJyRJoqRE+7vy9/dn8uTJ+Ex8kVL/bjXaqbnFWikmat5mVFVahJWp1GLWnUBQCyLw1QNLmxOr4ldzJW4D3VoFUdp9HErMH6aqMxp7BGkLtXNycvjtt9+IiIjg8ccfJ27/Ec5kFhPsXbmqqas4/sud5/U/J2cW8efxa9zdty17dm5nxowZZGZmolarmTlzJiqVis6dOzNmzBgOOPai05hBNb7WuuzUi9nFnE0vYOagDma/f0uMRg0wY0B7Ft4RqU8/zttwitjT2jSos4OM8ZHBPPrj4WrPY4nRWF+d/7b+YeTm5qLRaJgxYwbp6enExsaSnlvE4He3g0aq0U7NLc6t8fyGdqrYexMIqtMiAl9jKP3JmYUmL3hPDe/Ms6O6cd/X+9mTnA1oL6YxnQJ4+Yn/o2vAtzg7ObIzKYNHVh6xKg21dOlSAFatWkVYWBgDBgzgnGMHatquNbc4vm97H976/AcWP/Og0XHdauTUqVP4+fnhcUvf2n41QN12qlwmI8jLhZMnTxIeHq5vuVUVS1fUAaosUgp8ak0/linVRM3bXO24tUYj1E/nlySJlStX6nti/nEsDblcjrIWO9XXTduabc+Lw9GgYffZLBb9dZrrFStBMetOIKiZZh34GkvpzyosIyE1r1rQa+frxrjIYNLzjTX3zgEefDItmudXH+PQpRx+nTOQYV0DWDUnpl5pqKlTp+p/rm9x/DMjuyCTJDYcT8Pd3R2FQoFCoUCj0eDi4sLAgQP5/vvvCQ0NZdnO8xbbqVP7tSX2dDrZReV0DvDgiVs7cS27gJsiI5k1axZPPvkk3t7etG/fXv+aLCuOz2CQaxrxKxYTMH1RkxqNDaHzS5KEg4P2n6M5dmpOcTkTluzm1LV8fNwcmTexJ59Mjeb+77QTG2yt0YFAYEs0W6uzroumDms29v88fpWSclU1o3HFg/35bu9FFkzqyUtrEvQrvk+m9uZSTjEfbklCkrTz5QwbTTeU0Rjd1ptgLxeTpqXuvZpKP94/sD2zh3Tk7i/3EdHGk6/v70d8fDwLFixg/fr1vPvuuzz33HNIkmTyvObYqe9NieKWbgG4O8vJKSrnz2NXeGbyYEpytV9K5HI548aNY926dYB1dqq6vJSCnSt48KGH2HjViVKl+X/aDWU03gg7FaC1hzOHXh1JxBt/6/ctdXaqQCAwplmu+BqzSXFWYRmXs4uNGk0DjOsZRLlSzY4zmdUeE93Oh0s5xfz99FB83ZzYfyGbnMIyfBuwObG1xfF39w3lsZs7cc+X+0jLL2VgRz8kSaJ///6sXbsWjUZjMuDN+SGeLafTjb5U1GanvrCmMhhLEkT5og96ACqVCj8/bSNuc8b9DOrkx/yJPWnj7crRlFye/+0YV3Kh9ehHmDlhMH1Sc2+I0djUdqoODdo3KTP4rMSsO4HANM0u8FVV+g0xtf+2ee4wQgwUft2FXqPRoFaruXjxIq1atSIgIAAwrfK7O8l5YUx3/vXNAZOvKcjThTujQ/jXtwdJzy/l43t6k11crg98DYE1xfGTerfhxTHdmLbsACnXS0wajTWt8uprNN7RxZF1VY4vX76c4uJiygfMpFSprtFovJJbwtIZfXl5TQJbEzN4dlRXltwbzeQv9qLQYPdGozl2au+23uSXKLiQXYSXqyNvTohgX3I2BRXlDWLWnUBQM80u8FXtKKKjpv230R/v1P8sSXDolZH4ezjz6aef8sILL1BeXs706dP5/vvvkcvlJvfS5o7syh//pJKaa3r/rFSpYvXhVP3U9f/bdpZfHxlo8r6maKxxP8+P6oa3mxPrnqgshpfLTAe6qtTXaBzTyZ3ly5eTnJzMggULePjhh5k3bx4rflnDF1fLQO5Yo9EYGeLF2fRC/Qrz49iz/PP6KDq1dic5s8jujUbdrLva7NSJvdrwwuhu+Hk4UViqZNe5LKNyDTHrTiComWYV+EzNu9Mxf1IE7/ydyIJJPWt8/E1hvrg6yjly4gzvv/8+5eXadODPP//MqlWrCAkJwWnkUzx130Sjxw3u5EeQlyv/itGKGb7uznw2vQ9L45JZuvM8idcKjIxLDboLuek0og5L5Zzof39Ojltbs4vjh763Xf+zqb3Huqiv0fjAA9pC/GHDhtG7d2/8/f3xir4N5+wk/Xs1ZTS+MLobp69VdjspUai4lF1Ml4BWJGcW2b3RaE5xvK4m0hRi1p1AUDvNKvDV1FGktv03Q6b0CeWv41d56IlXKEhJ0R/XBaiRI0ei7h+NXCYZpRSnf3MAR4Ngs/aJwSz48xQ7KgLW6sMpPDW8C3/8c4XMwjIeu7kTCSnZTBkWzaZNm4iMjKz2WiwxGuOSMhnhk8up3z5u8h6NDWE0jhxZOT3AHKPRzcmBnKIyo3MUlCrwcNb+OTcHo1HMuhMIGo9mFfhMpSHr2n/T4eIoY2zPIGZ/H8/AsVNw8C9l48aNgNY4TEtL08sXOnQpxY+rdLpXazTklSgorrDrVh9OJdTHlf89rk0p7kzK4NFXFnPt2jX69u1L9+7d8fHxIS4uDrBczilVqFmf6oRH+x6MaV3EzgJXylSWGo3Wz0dryJSiqdFNVcf9FJcr8agibni4OOinnGvPY/64H1tEzLoTCBqPZhX4TF0069p/03FbRDB5JQr2X8hhRPcufP3GBoYMGcKgQYNwdXXVBz1dc+IyZc0XoyHvbq927KPYs3wUqw2QkkbF5Q3LAe2E7+PHj7N48WLAcjnn/buimNgrBIVKDUzCxVHOLwcvWT3upz40ldGYlF7AFIP9K1dHOe193TmbUbnKaw5GoyWpZB1h/u5EhoigJxDURrMKfKYumnXtv+mY0ieENUeuVJzHEUmS2LNnT7XzGe6/WFMBKUkQ5Sfnclmh0fGDBw+ye/dulK27WCTnAHy5M5kPqtQI1nfcz43CHKPxyOVc/jMunNsigth+JoOnR3QhMS2f5EytPNScjEZdKvnl3xM4ZUb6NjGtgGnL9ouG0wJBLTSrwGdK6a9r/w205QYDO/rx6v9OmHXRrO/+y9h2aspHjyY3N5f4+HjkcjnBwcG8tmAxU55/j2Af92qPM0fOaQ49Gs0xGgEeW3mYeRN78vHU3hxNyeXfPzdfozEhNZdHb+5ETAfTNY06DDMC5talCgQtEbsJfNYq/XXtv2nvG8KRy7lczinG2UFW50WzvvsvM2LCePSecQC8+uqrSJLEggULWBqXjNrEMrIuOedfMe35V0x7Uq6XsGxncrM3GgH2JGcz4qO4asebm9GoK+YP9XHl+ezqNY0nrmrt1qoZgRKFmoUbE4kK9bapFb1AYAvYfOCzVOmPeORjCr07GSn9hpjaf/s8LpnP45Itumg2RHNigIULF+p/tkbO+W7vRRZsPE1BqZKhXfxZcm8fvt19oc7Xb8sIo7GSz3aco1SpqrGmURf4TGUESpUqfTG/QCCoxKYDn6VNirsVn+TcumVNpvQ3hMpviDVyzsmrlfVsO85ksvboFboF2ff+lrUragcZzB1hW3uW9SGrsIy4pEz9376pmkaoOSNgmPpuLitggaAhsNnAZ6nSX6bScFTqyORZTzN2bDTvbDrTJBp4Q+6l1UfO0aHRaOfN2TvWGI0g8WHsWY6k5Fo8ccMWqVqXaqqmsa6MQNVifoFAYKOBz1Kl30kuY8EdPRnbM4hShRqFSo1cLmvSJsUNsZdmjZwztmcQcUmZlFSYj5OjQ9iamF6v12ErVF1Rq1Rqahu4oFRrUKo1bD6Vzs6kLLs3G6sW80P1msYQb9c62uXZfzG/QNDQ2GTgs7Tf5tyRXQjzc2fw4m0EeLqw5tFBDZ6GbAqskXMeHNSBxVOikIDU6yW8tvYEr40Lb8qX3ajoVtRL487x/uYkzFn6WTpxw1YxlfrWoatpHNDBt86MgL0X8wsEDY3NBT5r+m1O6RPK878dI79USX5pIT8euMSswR3sUuk3Ne7HkKpyzj1f7dP/rKvjs7X3VF+OpeTyydZzvHdXL5NjihzlEp9MjSYq1ItQHzemfbWP/Rdy7N5s1KW+/dydaqxp/GTb2TrLdZpDMb9A0JDYXOCztN+mp4sDgZ4uRk2Lz6QVUFiuxNlRDtiX0i+MxurozMaaxhSdSS8g/lIO3+65wOfT+xg91lbNRnPKc3TF/HXVNBpSNSPQnIr5BYKGwuYCn6VKv3tFY+ICg7RQdlE5EuaN17E1hNFojKHZWJvS/+2eiwCoqiyVbc1stKQ8566+oby/KZGcovJaaxoNqZoRaG7F/AJBQ2Bzgc9Spb+oojGxh7MDZcpy/c/F5Up83Z0a98U2EsJorKRqBqAmpb82bMVstKQ8RyfnKFOOomkTVWNdam00t2J+gaChsLnAZ43Sn55fSniwJ7vPZQEQHuxJRkEZoT5uTfraG5KWbjTqMGdMUV3YgtloaXlOiULFq78dJi/lLN5BPUBm+Ze45pr6Fgjqi80FPmuU/t+PpPLvWzuTkJpL61bO3HtTW+Iv5gA+N+hdNAwt2WjUYc6YouV7L5pxnhtnNuraji2aHGVSzukc4MGHd/eivZ+2R+vxK3m8uf4k5zKg9aC7eHhYJ5bvvSjGEwkEDYTNBT5rlP6PYs+y4I6e7HlpOKUKNV/vPs+coR1pDqg1GgI9XVGqqwc9UzWNOpwc5IyLbENRmVK/D2qPmDOmyBxaOcvrnHgP5kknllKXnHM5p5jHfzxCam4JMgnuHxjGp9OiGft/u1AicSGriFfHhTdpXapA0JyxySuipUp/uUrNi2sSeHFNQrNT+i2tadTx8m3dOZdRgK+7E50D7NfqM2dMEWibGOhimqODDGcHmT5F6uIgY/+m35n2x2J++eUXk8HP0p6w5mKunKNb2UqShEqtIaxi9aeTcxbeEWl3dakCga1ik4FPKP1arKlpBOjTzoduQa34+eBlpvVvazNGoyHmrqy0ZuNpNDjUqvRve+5m/Z7uDw8NAGDI4m2k5pZQWlbG4dWfcbiskIiICIKCgrjvvvuYNWsWYJ10Yu5qyhI5J+G/o3FzkiOTJD6MTdIfN5Rz7K0uVSCwRWwy8Fmr9Ls4SM1qX8PSmkYAmQTzJkbw8u8JdA/y1J7HBoxGHZaurPzcnVClJJDdJrJWpd/U1A3QBo3SC0dQFuUCcPr0aZKSkpg+fTqgDXqero7EPX9Ltb236LbePDuqK5EhXqjUGvZfyOHN9Sdr3T+tmk61RM6JmrcZV0c5U/qGcuV6pcFcVc6xp7pUgcAWsdluxjNiwnh1XDiujnLq2JbRo1TDrnNZHEvJbdwX10QkpuVX29vT1TS+tf6Uycc8OKgDR1Ny9eNq1BpuuNGoY+X+i0xbtp8tp9MpU6qr9aEsrTi2+VQ605btZ+X+iyxZsoSrscvRqMqtek5nRxklR9YaHVOpVOzbt49dJy+zcGMin247x5B3txP51mZmfx/P86O70rONJ16ujvx88DJD3t3O4He3UVSm5P27ovQdYRJSK//OZs+eTevWrRkxYgQlJZVBqzY5J9jLhRkVprKOEoWKHw9c4sN7euFnUI4j2o4JBA2HTa74dBgq/VtOpaOqQ2psbjq/pTWNAa2cmTkojPFLdlc5j3kXzcYQO3RYp/MfIWfrX5BziS4Fx7ns1xeFxvzvaq6OMl4c3YX47CFI0lB+/PFH8vLyiIyMpKCggKnzvsWpQ1/OZlSm1A333v48fs3ofCv2XWTVnIGAcUeYDRs2sHz5cpRKJTt27KBVq1b4+/vTt29fLrW5Bfx7mHx9Nck5MknC1VFOkKcL2UXagC/ajgkEDYdNBz7QKv1DOvuz40wmKjNqtpqTzm9pTeP5rCICWjkT+8wwAJwd5bg4yPnont61Go2NJXYYnn/hxkR90Avzc2PT08PYeCKNZ349WvE+nHhjfA9u7R5QIXRkMHfVUXxHzGLVqm+I6Rpc516cjqpm44NDPgPgueeeY+zYsfzxxx94BoQw6J2tlFd8mzKnMH5AB1/OpmtXzxoNxJ5Ko2OPXlw4naC/j0ajQaVSkZmZib+/P91uimDDJWjl4lijnDOksz/Xi8o5nZaPm5MDz43uSl6JgnOZhRWfgWg7JhA0JDYf+HQjikpNBD1TOv/tkcE8NLgDPYI9OX4lj4TUXLvd87O0plGp0hjtdY2PCuaO3iF8ufpvDv70Prt27cLV1dXoORpT7NCh0/l1zJvUk2OpeUb3WXpfXxKu5DL4nW2UKFR0C9Re6CVHZ5YfvEJM1+B6T9zo0KEDiYmJ2ueLS674IqB903UVxncPasVTw7sw+4d4/TGVSokyJBrHc6fRaDQoldoVekxMDGvXriUgIICswjL+XLyt1n6b43oG8daECIK8XChVqDiWmscD3x3UfwERbccEgobF5gOfpTp/bnE53+65QKfW7gzq5G+TDYrNxZqaxszCMv1tBaVKypUqvpv/FGV5WbRt25bQ0FAmTpzIvHnzrEo/WrqSrjpFfEJUMPklCo5kXNcXbA/t4k8bbxemLTuNbkvzpL7puGTUa7OhJm6YM+tOVxjf3s+N5TNv4q0Npzh08Xrl70TmyF0Pz+WDTd+ydu1a7rrrLvz9/fnuu+8ICAgAwN/DmZu7tmbL6fQa5ZyNJ9LYeCLN5G2i7ZhA0PDYdOCzRufXrfym9msL2FaDYkPM3U8b/sYvJJe619irsSabEWDNkVR+/d86SnO1Kczs7GxycnK477776kw/Pn5LJ54wKAuRyySc5DL6Ltxi0agfQzPVw9mBZ0Z1ZfqyA0zr31Z/PLqtN+czi/jg7t7c0q01l3OKWbTxNAcu5ACme23W12w0Z9YdQIi3Kz/OGsCn287yxz9XTJxHgUwmY/LkyRQVFeHi4lLtPqI8RyCwLWzW6gTrdP6q6C6atsKxlFzm/BDP4MXb+Cg2if8dvcq2xAz+d/QqH8cmMWjxNh5ZGc+xlFyUSiVHf1pstdHo4iinq+KC0TGNRsPXX3/NorWHa00/fr4jmYg3N+n/WxqXzP4L2VwvVujFDkPOnz/PuHHj9KlEHYYrq+dGdeXXQymkVVmlB3m5Mqxra/adz6b/wli+3nWeZf/qh4+bVuhojF6bhrPuJkQFV9TPwbAu2r23PclZBHo689PDA1ix7xI/Hrxcw3kqpRNTQQ8qy3NcHS375ybajgkEjYNNr/gsHVFkCksumo1pNYIF+2kn04k9eZWiXT9w/dxRnA+swnXQfahl5n9cuovmaVUwAffey65du7hy5Qpdu3ZlyMixbLlcgCTXXrRNpR+rcmefUD7Zqi2qrjrqZ+3atdx///3k5+ezdetWoqKiePLJJ5k0aRIZ17WCRo9gTwZ39uf2T3dVO3eZQkVKTjG/xqcAsD7hGk/c2pl+7X3ZcjodaHgzVdsR5lqte29Pj+hCez935o7owtwRXfSPjXhzE2CZdGLJxA3RdkwgaFxsOvBZqvPXRE5RCQkJCURFRZm8vbGtRrBQ5wdUyHEaMI3ZEyfw1Yv3W200ErMQgMLCQsaPH8+iRYtIUASyKzaJMqW6xvSjITeF+eLn7sRfBvtQErD41x38+cGzJCUl6cWO8vJy4uPjmTlzJgChd7+KvNNAYjr6Eurjyt6XhgPg5uSAXCbRJWAI3++/xIjwQOPfQZX36OniiFqtRlZDytfSz/CuvqG89/cpcpSaGvfePtl6lk+q7KkavUYsk07qK+cIBIKGwaYDnzUjikxx5cJZ+j4yi7///psRI0YY3dYUVqPOTDUV9EyZqS/f1p2JvdrQysWBglIl1/JK6n3R9PDwYMeOHQD8uuqfOtOPhkzpE8pfJ67pBRrd72XFuu1knKpeSO/k5ERkZCQ///wzW6/K+Cg2iZ8OXmb9scq6uNlDOxLq48pra0+gUmt4dVw4U/qE8Mc/VxgTEUSwlwvxl3L0762VOp+AgAB27txJjx7GdXHWfIZTegVSdO4Qzh37N+msu4aScwQCgfXYdOCzZkSRTAJHuQwHmYQkgRNKEnb8hVKpZPTo0YSGhpKfn8+iRYtoFT220a1GsNxM/TU+hU+2nqVEoSLIy5nfHx0MNNxFU7eSri39qMPFUca4yCDm/HC42m3jJ9/Ngi+e4YcffuCzzz7j8uXLODo6smLFCqZOnYokSfgEl/FRbBKlCjWlikrjtLhcSZlSTU5FgfbD3x9i/qSezJvYk+TMQmb/EM/1Ym16s6y8nO9ef5bs7Gz69u3L0KFDkSSJ1atXs+5UjsWf4eu/H+XJf39DSeoZgsOib8isO9F2TCC4cdh04LNG578zOpT37+6lvz3p7Ums+KGQmbt/Qa1WM2HCBB588EF6945mXcI1s1dhr4wNZ1SPQFq3ciYjv5TLOUW08zW9H2aINWbq+awi/c8aDRSUKY3GC9X3oqlbSdeWftR1fxkTEUReiYJ957NNnMeR4OBgXnzxRV544QW++uor+vTpQ//+/fX3MdT5DVdjVT/HQxevc9sn1QOwBLThOnuTtdJMaWkpW7Zswdvbm3M5ilrN1JgOvvz0cIyRTfnfdSdYc+QKnjfP5PORgai9Qy3uCSukE4HAvrHpwAeWjyj67Uiq3uKUJAhSpBP/8SPI5XJUKhVXr15l/vz53PvcfORu1S9cNa3CShRKHv7+EOeziugd6s3KWQOMbl+0aBG7d+/mnnvu0e9vgfVm6mM3d+LJWzvj7uxASk4xf/yT2mCig27UT23pRx1T+oSy5kh1jb+q2CFJEo888ojJ56uXzu8oZ7iPgv0yGWqDVXNRURHz1hyg1GAsvanC+PSCUga+s63aeWUOTuzMcmHpbWGAkE4EgpaEzQe++tZAPTeyJ1LMLwQEBPD000+zbt06Hp37AllKFwJNPKamVdhHsZUrlH9ScjlwIZsBHfxwc5KzevVq/vvf/6JSqdi8eTPx8fE8/fTThIWFcfRiBhFt/Y3OZY6Z+kVcMl/EJRMR7MnoiECu5da8B6fDklE/5qQfAz2dGdTRj9cNAqEOS8QOa6dt6FZWrleKmD59OtnZ2cTGxqLRaLhrxoPsTS8HC8xUIySZ3kwV0olA0LKw+cBX34vmXTFhwE0AxMXFMWvWLEKGTEFmom+lufWBzg4yerbx4sOf/+K9p+6jsLAQTcVSQaVS8dlnn/HZZ58hl8sJuudNIh6eavR4S8zUk9fyGda1NcO7B9R4H0uNRn8PZzq6lnIqz8FI7KiafkzPL6Pza39Vez5rxI766fxhTJkyBYC33nqLEydOMOyBFzlshpnq5+7MoVdGUqpQsflUGu9vTtJ/iTIsjBfSiUDQcrD5wAcNVwPVqlUrfv31V+au+gePGsb9mFMfuGhyJKfT8ll3+BIODg5IkqQPfADe3t4sXryYWbNm8dxvCdUeb6mZKpdJyErzuHChhA4dOhjdZo3ReHd0MIeWL8Bt4itIMtNF17VhrdjRECurN954A4C5ZpipyZlFjPt0F8mZhYR4u/LB3b14/fZwXvmfdgVrqsZTSCcCQfPHLgIfNGwNVH3qA/8ztjtdA1tx77L9DOg3gEOf5pCSksKdd95JfHw8vr6+pKam6ptBW2qmShLc278dGxKukl+qpFeoF/fHtOeDr3/i3rdfYtGiRZSUlDBgwADOagItNhpfW/MPjz32OIVnj+B1fD2a6MmoJcsL461N9zWlmZpZWKbvXZp6vYR3/krkmwf66wOf9jxizp1A0NKwm8AHDXfRtLY+8JmRXbilawBTl+2jsEypb1fVtm1b1q9fr+/VaDgBwVIzVZJgTEQgL47phqNcRnpBKd/tSeb9155BXZLPo48+ikwm44nXF7NJ2cMo6Jka9zOxVxteHNMNX3cndp/N4oU1CahHzGL2lDF8+NrT1hfG15OmNFN1aNCWuxifR8y5EwhaGnYV+HTU96JpTX3g4zd3YmKvEO75ch+5xYpqVmNQUFCNz2eJmarRwAPfHdL/v4SGoqT9qEsqJqqr1ajVapJdulCaayz8VLUauwR4sGhyJA8tP8SJq3m8PTmSBZN68uRPhyloqx2oaq9ihzlm6sCOflzOKeZKbgnBXi68NKY7W06l6+8r5twJBC0Tuwx89cWa+sAXb+tOmVLFjudv0d/H9FjX6tTHTHWQoG3+SXreeiu7d+9GoVDgHxLG8SwVyCsDtSmr8Y7eIWw9nc7Bi9oOKB9sSSL2mZvxcHFk57nsBh/105SYY6b2aOPJR/f0xsvVkevF5Ww6lcb7m87o7yvm3AkELRNJo6ktwdV8qWsVVhuSBGN6BFo058+SXp06tPtp4frU4tatWxkzZgxPLPkff1+R6+UOD2cH1j05WG81tvdz55lfj7LsX305fOm6kTBz8s0xTP1qH+cyCnlmVFe7Fjma+jMUCATNA5seS9SYPHFLZ1wc5FY91hqrcUZMGK+OC8fVUY6JSgojJAlcHeVGQQ9gxIgRXLx4EcknxKhkoSar0c1J2+vTkIJSJR7ODo0y6qepaerPUCAQNA9abOC7ETPSZsSEsWpODGN6BOLsIMPFwfi5XRxkODvIGNMjkN2zL0UAAAkvSURBVFVzYkxKJKGhoUZWqs5q/GbPhWr3LS5X4lFF5PFwcaCwTPt4ezcarf0MXRwk0XJMIGjBtMg9Ph03YkZaQ+ynGVqptVmNcUmZhAd76u/b1scVJ7mMCxW9QJuD0WjJZ6hDqYZd57KIDPG2esyUQCCwX1rsHp8hCam5dmU1Lo1L5qOKriUujjJaOVcGMEOr0c/did8fG8RDKw5x4ko+iyZH4iCT+Pcv/+DiILP7PT5DdJ/hllPpqMz4ixZ9NwWClkuLXvHpsDerUWc0ArVajTlF5bz6vxN8PDUaHzdH9pzL4vmKTjLNzWiMCvVmSGd/dpzJRKVs3DFTAoHAvhErPjtFGI3GHEvJZdqy/fqSEVPF/DrenRLFPf3acvP727mUXYyro5xVc2JsYjUvEAganxYrt9g7wmg05rMd5yhVVtZJmhpRBNCvvQ/tfd2MjpUqVXy+41yjv0aBQGAbiMBnp1hrNMok6Browd5kbQF7cyCrsIy4pEz96ldXzL83OcvofnKZxFsTI3hj/Umj4xoN+hFFAoGg+SMCnx1jSW2gDrUGjqXm8XFsEoMWb+ORlfEcS8lt3BfayBgO+9WNKFrw5+lq95s1uAMHL+SQmFa9flE3okggEDR/ROCzc+qqDayJUqWaMqWazafSmbZsPyv3X2zcF9qIJKbl1zmiKNjLhekD2vHhliST52gOBf0CgcA8hNXZDKhqpW48fo3jV/JQmyG+NAe70ZwRRf8d34P/23qWgrLqI6kqz2PfBf0CgcA8ROBrRvh5OBPTwY+PY8/qg15Vu7F1K2cW3RFJVKgXgZ4uDFm8jdTcEkoUahZuTCQq1Nvu7EZzRhS183WjX3tf/jO2u/5xvz86iLc2nGLdsasV57H/gn6BQFA3IvA1M+qyGzUaDXFnM/ki7hy/PzbY6LE6u9HeyhzMGVEkATKDjdBDr47k4e/jOXVNO+5JjCgSCFoOIvA1I2qyGw1HFWUVlrNy/yXkVSeyYmw32krBflZhGb8dTiUxLZ/8UiWeLg50D/Lk7r6VTQXMGVFkipzicv3eYHMr6BcIBDUjAl8zwpTdqBtVZC46u/FGtzI7lpLLZzvOEVcxCLjMqI1cGh/FJnFLt9Y8fnNnerX1ZmCYJ9uTcpAMhglXnbFoSNh//tT/LEnalnS2EuwFAkHjIgJfM8Icu7EubMFu1M4urLnptK6X6uZT6cSdyeSOMDW7vvwAzbAnkGQuFj9fcyzoFwgENSMCXzPCHLvRvPPUbTeak4K0BksG9mo02iD406lS8tXu/HdYO5bFZ1kx7FeMKBIIWhIi8DUjzLEbxy/ZXed5Eg4fQHN/PyQTVfGWpiAt4VhKLgs3JuoDV1UjdWBHP96Y0IM2Xq6oNBoOXsjhv+tOkJ4P/qPnMLJPFwICWjfpmCmBQGB/iMDXjDDHbgRwdpDpDUeniuG3eslDUUby4Z28/noaCxYsQK1Wo1KpcHR0tCgFuTMpy+KgUpeRejajgPu/PUhGQRlOchnPjurKgkmRzP4hHpVGpjdSo0K97WrMlEAgaFpE4GtGmGs3npk/Vn/btuduASplD40kkffPJhbuXc17772HQqEgNDSURb/utCgFaWlRvLlGqiFqjYYwP23DaQ2VRqq9jZkSCARNiwh8zQh/D2du7tq62riiqnajodFohFpNSfIh1CXa2rby8nIkSSLm9qm1piBv7RbA47d0oltgK8qUKrYmZjB/wymKylUmi+Lz8vK4fv06YWFh+mPmGqltvFz4++lheDg7oNJo+M/vx/W3VTVS/Tycb7idKhAIbA/Rq7OZUZ9xRRIquiovMmLECBwcKr8T7cttRYmistVX1RRkKxcHlmw/x01vxzLiwziCPF14ZVw4UH3kz759+/D29qZTp04sW7aM3Fxtg2xzjdSreaVEzdtM9IItfLD5DMmZhfrbbMFIFQgEto8IfM0Ma8cVuTrKmD+5N3vW/URsbCy//fYbMpmMATePxKVjX7TrKdMjf9Ydu0pcUialCjX5pUp+PpRC3/Y+QGVRfHpeMQsWLGD4cK1wo1areeyxx/D19cXb25stO7TSjc5I/WbPhVpfb16JgjVHrvDVv/oZFeOLfpsCgaAuRKqzGaLbU6uP3Thp0iRWrFjBGVk7fj1dBGq12UXxAzr4cja9ciVWXl5O+NiZXN+32uh+KpUKSZIIDQ0lvEtHDmVaZqTKZRKtWznj4exAXok24Il+mwKBoC5E4GumzIgJq7fdOGPGDOau+ocypTZ9aE5R/JDO/kzpE8odn+/RH9PIHBh0+934dnZhw4YN5ObmotFoCAoKYv369fTr14+lcckkxCbVaqSOiQjibHoBF7KL8HFz4rXbwzlxJU8f9ES/TYFAYA4i8DVjGsJutKQoPrqtN59M7c1jPx7mQlaR0W2BoWF88+r3qFQq7r//fo4fP86KFSuIjo4GzDNSgzxdeG1cOH4eThSVKdl/PodHVh7W31f02xQIBOYgaTS1JcIELZ25q/7hf0ev8tDgMJ4f3Y2iinl2uhTkuYxCxi/ZTUSwJyseuomX1iSwNTGj2nkm9w7ho6m9a32uOT/EVzNSzUWSYEyPQLubLCEQCJoeseIT1Io5RfFdAz1Y/uBNvLnupMmgZ24K8olbOrPrbBYlClWd963+HKLfpkAgMA9hdQpq5a6+2tRhqUJNZmGZ/j/DFOTsIR3xc3di8ZQoTr45hpNvjmHz3GH6c5ibgqyPkSr6bQoEAnMRqU5BnTR1CrKu1miG5xb9NgUCgaWIwCeok2MpuUxbtt+qFKSro5xVc2IsXo0lpOaKfpsCgaBREIFPYBaWjAvSoU1BhtdrNSb6bQoEgoZGBD6B2YgUpEAgaA6IwCewCJGCFAgE9o4IfAKrEClIgUBgr4jAJxAIBIIWhajjEwgEAkGLQgQ+gUAgELQoROATCAQCQYtCBD6BQCAQtChE4BMIBAJBi0IEPoFAIBC0KETgEwgEAkGLQgQ+gUAgELQoROATCAQCQYtCBD6BQCAQtChE4BMIBAJBi0IEPoFAIBC0KETgEwgEAkGLQgQ+gUAgELQoROATCAQCQYtCBD6BQCAQtChE4BMIBAJBi0IEPoFAIBC0KETgEwgEAkGLQgQ+gUAgELQoROATCAQCQYvi/wGMUcagJzp4jwAAAABJRU5ErkJggg==\n", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import networkx as nx\n", "# access and visualize the device topology\n", "print(aspen_m.properties.paradigm.connectivity.connectivityGraph)\n", "nx.draw_kamada_kawai(aspen_m.topology_graph, with_labels=True, font_color=\"white\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can submit a task of the above program with verbatim box." ] }, { "cell_type": "code", "execution_count": 27, "metadata": { "scrolled": true }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "DECLARE ro BIT[2]\n", "PRAGMA INITIAL_REWIRING \"NAIVE\"\n", "RESET\n", "RX(pi) 0\n", "RX(pi) 0\n", "CZ 0 1\n", "MEASURE 1 ro[1]\n", "MEASURE 0 ro[0]\n", "\n" ] } ], "source": [ "verbatim_task = aspen_m.run(OpenQASMProgram(source=program_with_verbatim_box), shots = 10)\n", "verbatim_result = verbatim_task.result()\n", "meta = verbatim_result.additional_metadata.rigettiMetadata\n", "print(meta.compiledProgram)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As shown above, the two consecutive `rx` $\\pi$-rotation gates did not get optimized and we confirm that our program was indeed executed verbatim." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Requesting Result Types with OpenQASM\n", "\n", "Braket provides [a rich library of result types](https://docs.aws.amazon.com/braket/latest/developerguide/braket-result-types.html) for circuit executions. With OpenQASM, requesting different result types for our tasks is easier than ever using the `result` pragma. Next, we give an example of requesting result types for our Bell state program submitted to SV1. Before doing that, let's see what result types are supported on SV1:" ] }, { "cell_type": "code", "execution_count": 28, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "name='Sample' observables=['x', 'y', 'z', 'h', 'i', 'hermitian'] minShots=1 maxShots=100000\n", "name='Expectation' observables=['x', 'y', 'z', 'h', 'i', 'hermitian'] minShots=0 maxShots=100000\n", "name='Variance' observables=['x', 'y', 'z', 'h', 'i', 'hermitian'] minShots=0 maxShots=100000\n", "name='Probability' observables=None minShots=1 maxShots=100000\n", "name='Amplitude' observables=None minShots=0 maxShots=0\n", "name='AdjointGradient' observables=['x', 'y', 'z', 'h', 'i'] minShots=0 maxShots=0\n" ] } ], "source": [ "# print the result types supported by SV1\n", "for iter in sv1.properties.action['braket.ir.openqasm.program'].supportedResultTypes:\n", " print(iter)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "With knowing the supported result types on SV1, we choose to request the `Expectation` of $X \\otimes Z$ observable on `q[0]` and `q[1]` and the `Amplitude` result type for a `shots=0` task of our bell program:" ] }, { "cell_type": "code", "execution_count": 29, "metadata": {}, "outputs": [], "source": [ "bell_with_result_type = \"\"\"\n", "OPENQASM 3;\n", "\n", "qubit[2] q;\n", "\n", "#pragma braket result expectation x(q[0]) @ z(q[1])\n", "#pragma braket result amplitude \"00\", \"11\"\n", "h q[0];\n", "cnot q[0], q[1];\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The location of the `result` pragma is very flexible as long as it's after the qubit register definition (if you use physical qubits, you can put `result` pragmas anywhere after the program header).\n", "\n", "We can submit the above program and receive the results for our requested result types." ] }, { "cell_type": "code", "execution_count": 30, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[0.0, {'00': (0.7071067811865475+0j), '11': (0.7071067811865475+0j)}]\n" ] } ], "source": [ "bell_result_types_task = sv1.run(OpenQASMProgram(source=bell_with_result_type), shots = 0)\n", "bell_result = bell_result_types_task.result()\n", "values = bell_result.values\n", "print(values)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "At last, we want to remind our Braket OpenQASM users that there are two requirements when requesting result types:\n", "1. For `shots=0` tasks, requesting non-simultaneously measurable result types is allowed, but for `shots>0` tasks, it is not allowed. For example, we can write the following OpenQASM program in a `shots=0` task but not in a `shots>0` task, since the two result types are not simultaneously measurable:" ] }, { "cell_type": "code", "execution_count": 31, "metadata": {}, "outputs": [], "source": [ "program_with_non_simultaneously_measurable_result_types = \"\"\"\n", "OPENQASM 3;\n", "\n", "qubit[2] q;\n", "\n", "h q[0];\n", "cnot q[0], q[1];\n", "\n", "#pragma braket result expectation x(q[0]) @ z(q[1])\n", "#pragma braket result expectation hermitian([[0, -1im], [1im, 0]]) q[0]\n", "\"\"\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "2. Do not use measurement instructions and request result types in the same OpenQASM program, otherwise a validation error will be raised. Since measurement instructions are basically equivalent to `#pragma braket result sample z(qubit)`, we encourage users to adapt a consistent style of requesting result types in the same program." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Conclusion\n", "\n", "In this notebook, you learned how to submit OpenQASM tasks and use OpenQASM features on Braket. Hope you enjoyed it! You can find more information about OpenQASM3.0 in its [live specification](https://openqasm.com/), and you can learn more about OpenQASM support on Braket in the [Amazon Braket documentation](https://docs.aws.amazon.com/braket/latest/developerguide/)." ] }, { "cell_type": "code", "execution_count": 32, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Task Summary\n", "{'arn:aws:braket:::device/quantum-simulator/amazon/sv1': {'shots': 120, 'tasks': {'CREATED': 1, 'COMPLETED': 3}, 'execution_duration': datetime.timedelta(microseconds=14000), 'billed_execution_duration': datetime.timedelta(seconds=9)}, 'arn:aws:braket:::device/quantum-simulator/amazon/dm1': {'shots': 30, 'tasks': {'COMPLETED': 3}, 'execution_duration': datetime.timedelta(microseconds=264000), 'billed_execution_duration': datetime.timedelta(seconds=9)}, 'arn:aws:braket:us-west-1::device/qpu/rigetti/Aspen-M-3': {'shots': 20, 'tasks': {'COMPLETED': 2}}}\n", "Note: Charges shown are estimates based on your Amazon Braket simulator and quantum processing unit (QPU) task usage. Estimated charges shown may differ from your actual charges. Estimated charges do not factor in any discounts or credits, and you may experience additional charges based on your use of other services such as Amazon Elastic Compute Cloud (Amazon EC2).\n", "Estimated cost to run this example: 0.63 USD\n" ] } ], "source": [ "print(\"Task Summary\")\n", "print(t.quantum_tasks_statistics())\n", "print('Note: Charges shown are estimates based on your Amazon Braket simulator and quantum processing unit (QPU) task usage. Estimated charges shown may differ from your actual charges. Estimated charges do not factor in any discounts or credits, and you may experience additional charges based on your use of other services such as Amazon Elastic Compute Cloud (Amazon EC2).')\n", "print(f\"Estimated cost to run this example: {t.qpu_tasks_cost() + t.simulator_tasks_cost():.2f} USD\")" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.8.15" }, "vscode": { "interpreter": { "hash": "590fab68195cf107911461461f81d5c472d3d6127f579badfcfad30f03e5cab2" } } }, "nbformat": 4, "nbformat_minor": 5 }