From 9631707134b9311375efab61fb76f0f6f87130ca Mon Sep 17 00:00:00 2001 From: Cryoris Date: Wed, 22 Jan 2020 19:49:58 +0100 Subject: [PATCH 1/8] migrate from Qiskit/qiskit-aqua#747 --- notebooks/0.7_ansatz_design_doc.ipynb | 1797 +++++++++++++++++++++++++ notebooks/img/ansatz_rep.jpg | Bin 0 -> 23913 bytes notebooks/img/ansatz_scheme.jpg | Bin 0 -> 144371 bytes 3 files changed, 1797 insertions(+) create mode 100644 notebooks/0.7_ansatz_design_doc.ipynb create mode 100644 notebooks/img/ansatz_rep.jpg create mode 100644 notebooks/img/ansatz_scheme.jpg diff --git a/notebooks/0.7_ansatz_design_doc.ipynb b/notebooks/0.7_ansatz_design_doc.ipynb new file mode 100644 index 0000000..e70ab52 --- /dev/null +++ b/notebooks/0.7_ansatz_design_doc.ipynb @@ -0,0 +1,1797 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "# Ansatz Design Doc\n", + "\n", + "Discussion: January 8th, 2020
\n", + "Author: Julien Gacon" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "# Overview\n", + "\n", + "1. [Motivation](#motivation)\n", + "1. [User benefit](#benefit)\n", + "1. [Proposed structure](#structure)\n", + "1. [Implementation](#implementation)\n", + " 1. [The `Ansatz` object](#ansatz)\n", + " 1. [Variational forms](#varforms)\n", + " 1. [Feature maps](#featmaps)\n", + " 1. Others" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "# Motivation" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Creating a new variational form\n", + "\n", + "Currently, creating a new variational form class requires a lot of copy+paste. \n", + "\n", + "Remember: `RYRZ` has all of that, too!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "class RY(VariationalForm):\n", + " \"\"\"Layers of Y rotations followed by entangling gates.\"\"\"\n", + "\n", + " def __init__(self, num_qubits, depth=3, entangler_map=None, entanglement='full', initial_state=None,\n", + " entanglement_gate='cz', skip_unentangled_qubits=False, skip_final_ry=False):\n", + " self.validate(locals())\n", + " super().__init__()\n", + " \"\"\" 30 more lines ... \"\"\"\n", + " self._bounds = [(-np.pi, np.pi)] * self._num_parameters\n", + " self._support_parameterized_circuit = True\n", + "\n", + " def construct_circuit(self, parameters, q=None):\n", + " if len(parameters) != self._num_parameters:\n", + " raise ValueError('The number of parameters has to be {}'.format(self._num_parameters))\n", + " \"\"\" 39 more lines ... \"\"\"\n", + " return circuit" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "Setting up a new variational form should be quick and easy, more like:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "class RY(TwoQubitAnsatz):\n", + " def __init__(self, ...):\n", + " super.__init__(single_qubit_gate='ry', ...)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "If a user wants to quickly try a new format, it would convenient to set up the variational form in just a single line. Not all ideas must become a complete, new class." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "rxrycx = MultiQubitAnsatz(num_qubits, single_qubit_gate=['rx', 'ry'], two_qubit_gate='cx', depth=4)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Adding and inserting layers\n", + "\n", + "The circuits that current variational forms build are not extensible. For algorithms, such as adaptive VQE, adding new layers to the variational forms is necessary. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "varform.add(additional_gate, qubit_indices) # add `additional_gate` at `qubit_indices`" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "Other applications require the insertion of a new gate or layer not at the end of the variational form but somewhere in the middle. The position could e.g. be handled by the appearance of a certain `Parameter` instance." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "This can be used for the calculation of analytic gradients. By inserting a set of Paulis after a parameter and controlling the operation on an ancilla, we can compute the gradient with respect to that parameter (see [this paper](https://arxiv.org/pdf/1701.01450.pdf))." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "target_param = Parameter('θ') # this variable is also used in the circuit \n", + "varform.insert(target_param, instr_to_insert, qubit_indices)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "notes" + } + }, + "source": [ + "The insertion might be difficult to implement, what would the `position` be? This feature might be too specific and implementation of special cases may be left up to the users." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Combining variational forms\n", + "\n", + "A variational form is essentially a gate preparing a parameterized state. For chemistry, this could be the preparation of certain excitation. If we want multiple excitations, we should be able to just combine the respective variational forms." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "S0, S1 = single_excitation('θ0'), single_excitation('θ1')\n", + "D = double_excitation('θ2')\n", + "UCCSD = S0 + S1 + D" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "If some variational forms prepare subsystems, they should be able to be combined at certain qubit indices." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "varform = sub_varform.append(other_varform, indices)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "notes" + } + }, + "source": [ + "Possibly allow only `combine` and not `__add__`, since this is dangerously close to `add(new_layer)` and might result in confusion of what types can be added." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## DIY: special variational forms\n", + "\n", + "Variational forms can be very diverse and for special problems, special structures may perform better than others. Therefore, users should be able to their own Ansaetze as variable as possible.\n", + "For this we can support automatic repetition (with correct setting of the parameters).\n", + "\n", + "![Automatic repetition](img/ansatz_rep.jpg)\n", + "\n", + "The repetitions can either be specified by a single integer or layer indices." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "varform = Ansatz([gate_1, gate_2], [indices_1, indices_2], reps=3)\n", + "varform = Ansatz([gate_1, gate_2], [indices_1, indices_2], reps=[0, 1, 0, 1, 0, 1])" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "Instead of gates we can also allow fancier options, e.g. provide a Callable that accepts a repetition number or similar." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "What happens to the parameters in the gates if they get repeated? Do they just get repeated? \n", + "If we stored them in a list, the user could later on overwrite them in `construct_circuit`. \n", + "\n", + "We could also add some default parameters, since the user might not expect there to be the same parameters? If these default parameters haven't been substituted we could raise a warning.\n", + "\n", + "Repeating the parameters is probably the more intuitive solution. If the user wants different parameters, they must be set afterwards -- as it is also the case with default parameters." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Operator Ansatz \n", + "\n", + "Several algorithms, such as QAOA, require an Operator-evolution type Ansatz, such as \n", + "\n", + "$$\n", + "V(\\theta) = e^{i\\theta_1 \\hat O_1} e^{i\\theta_2 \\hat O_2} e^{i \\theta_3 \\hat O_1} e^{i\\theta_4 \\hat O_2}\\cdots ~.\n", + "$$\n", + "\n", + "Currently, this is cumbersome to implement. Similar to the ''DIY'' Ansaetze, we could support an `OperatorAnsatz` based on `Ansatz`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "varform = OperatorAnsatz([Op1, Op2], reps=4)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Unification of circuit-producing concepts\n", + "\n", + "The concept of a variational form is broad. In support of a clear structure, we should group similar concepts. Then,\n", + "* users are less confused and see what concepts have the same base,\n", + "* we can reuse the same base functionalities,\n", + "* we ensure that similar objects in Aqua behave the same way.\n", + "\n", + "Therefore, a common base for feature maps and variational forms would be sensible. Aqua hosts more facilities to construct circuits, as e.g. the `InitialState` or the `UncertaintyModel`, but as discussed towards the end of this doc these are best not derived from Ansatz.\n", + "\n", + "However, it should be our goal that all objects producing circuits in Aqua behave the same way. Ideally, they also feel like objects from Terra. This means finding a similar base for \n", + "\n", + "* variational forms\n", + "* feature maps\n", + "* initial states\n", + "* uncertainty models\n", + "* grover operators\n", + "* amplitude estimation $\\mathcal A$ operators" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "class MyFeatureMap(Ansatz):\n", + " # implement\n", + " \n", + "class MyMultiQubitVarform(Ansatz):\n", + " # implement" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Pre-transpilation & default parameters\n", + "\n", + "Terra provides the `Parameter` class for parameterized circuits. This can speedup the repeated execution of the same circuits with different parameters, as we can pre-transpile the circuit and substitute the parameters afterwards.\n", + "This significantly improves our performance since transpiling is costly!\n", + "\n", + "By transpiling the circuit the first time `construct_circuit` is called, the user benefits from pre-transpiling without specifying it manually." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "-" + } + }, + "outputs": [], + "source": [ + "def construct_circuit(self, transpiled=True, # set to False for untranspiled circuit\n", + " parameter_prefix=default_prefix)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "Also, we could simplify the setting of parameters, if the user just quickly wants a circuit to look at." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "circuit = varform.construct_circuit() # uses some default naming \n", + "circuit = varform.construct_circuit(parameter_prefix='θ')" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Optional barriers\n", + "\n", + "Barriers can be very useful for visualization, but if a circuit is executed only and not looked at, we don't need them and they can even slow down transpilation. Why insert them by default?" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "circuit = varform.construct_circuit(insert_barriers=True) # False by default" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "For this feature we would have to store a `has_barriers` variable and if the user changes back and forth between barriers and no barriers we would have to rebuild the circuit. (Workaround possible by storing both, but back-and-forth changing is not likely anyways.)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "# User benefit\n", + "\n", + "Let's summarise the benefits of having an `Ansatz` class satisfying the requirements from the motivation.\n", + "\n", + "1. Beginner user\n", + " 1. flexibility: can get creative and easily assemble new variational forms\n", + " 2. performance: can `construct_circuit` without specifying parameters, and thereby benefits from potential speedup without even touching Terra's `Parameter` class\n", + "2. Advanced user\n", + " 1. needs less copy+paste to implement standard variational forms\n", + " 2. can also benefit from `Parameter` related speedup\n", + " 3. has lots of lots of flexibility\n", + " * by adding and combining varforms\n", + " * inserting new layers\n", + " * wrapping parameterized gates\n", + " 4. gets less confused by the multitude of Ansatz-like objects in Aqua" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "# Proposed Structure" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "The Ansatz class reconciles all classes that prepare an ansatz or wavefunction. Objects of the Ansatz type share the Ansatz interface and can be used as building blocks in larger circuits and algorithms. This has the key advantage, that the same concepts behave similarly and we avoid code duplication. \n", + "\n", + "More specialized types, that can also provide an easy setup or special behaviour, are derived from the Ansatz. \n", + "\n", + "See the next Figure." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "![Ansatz design](img/ansatz_scheme.jpg)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "## Unify base classes\n", + "\n", + "Currently, Aqua (6.x) distinguishes between a `VariationalForm` and a `FeatureMap`, which are both abstract classes that specify interfaces. These interfaces, however, almost identical and could be merged. Further, to new users the terms \"variational form\" and \"feature map\" might be confusing, whereas the word \"Ansatz\" wraps both concepts.\n", + "\n", + "Thus, by introducing the `Ansatz` as joint class we can directly derive `PauliExpansion` and `TwoLocalGateAnsatz` without introducing new levels of inheritance, which might be sources of confusion." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "## Composition vs. Inheritance\n", + "\n", + "The objects `RY`/`RYRZ` are displayed as objects derived from not `Ansatz` but an intermediate type. This is discussed in the [implementation section](#standard_varforms)." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "# Implementation \n", + "\n", + "To be discussed in more detail.\n", + "\n", + "1. Ansatz\n", + "1. Variational forms\n", + " 1. TwoLocalGateAnsatz\n", + " 1. Standard Forms\n", + "1. Feature maps\n", + " 1. Pauli expansions\n", + " 1. First/Second/... order\n", + "1. Initial state objects\n", + "\n", + "Note: We know use the term Ansatz for the concept of a parameterized circuit preparing a parameterized state, not variational form." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Ansatz \n", + "\n", + "### Requirements recap\n", + "\n", + "1. Take a list of gates and a number of repetitions and construct an Ansatz of desired depth\n", + "2. Provide `construct_circuit(params=None, transpiled=True, insert_barriers=False)`. Note, that `params` must support `list[float | Parameter]`.\n", + "3. Combine two Ansatz objects at given indices\n", + "4. Insert new gates at a specified place\n", + "5. Backward compatibility with all previous `VariationalForm` objects" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "Code checklist:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "def __init__(self, layers, indices, reps)\n", + "\n", + "def construct_circuit(params=None, transpiled=True, parameter_prefix=default_prefix, insert_barriers=False)\n", + "\n", + "def __add__(other) # easy appending of Ansaetze, and maybe for various kinds of RHS/LHS types?\n", + "\n", + "def append(other, connection_indices=None) # for Ansatz + Ansatz at special indices\n", + "\n", + "def add_layer(gate, indices=None, position=end) # to add a new gate/QuantumCircuit\n", + "\n", + "def insert_at_param(target_param, gate, indices=None) # to insert after/before a certain parameter" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "### Implementation proposal #1: `QuantumCircuit`\n", + "\n", + "Make an Ansatz essentially a `QuantumCircuit` object. " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Advantages \n", + "\n", + "* already provides: `__add__(QuantumCircuit/Ansatz)` and `append(Gate)`\n", + "* gives the user a Terra-like feel for the Ansatz" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Technical Issues\n", + "\n", + "* parameter setting by `list[float | Parameter]` not inherently supported\n", + "* a circuit doesn't have `construct_circuit` -- but we can work without that\n", + "* how to insert barriers or new gates at arbitrary positions? (use `data` member?)\n", + "\n", + "We lose flexibility. What was the initial gate object the user gave us? Missing performance benefit of pre-transpilation." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Design Issues\n", + "\n", + "* inserts another level of inheritance (or maybe just use `QuantumCircuit` as component?)\n", + "* `construct_circuit` is required for backward compatibility and the method name is very misleading \n", + "* an Ansatz fits more the concept of an Gate in the sense that it has no registers attached. Therefore it should probably not be a `QuantumCircuit`." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "### Implementation proposal #2: `Gate`\n", + "\n", + "Make an Ansatz essentially a `Gate` object. This could achieved by either deriving from a gate or wrapping it." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Advantages\n", + "\n", + "* intuitively that's what an Ansatz is: a (parameterized) gate\n", + "* provides some required functionalities: allows setting of parameters as list, can be controlled, repeated, etc. \n", + "* no registers bound to it\n", + "* stores parameters as `list`, setting parameters by `list[float | Parameter]` is straightforward\n", + "* a `construct_circuit` method makes sense and is maybe missing anyways (or `to_circuit`)\n", + "* gives the user a Terra-like feel for the Ansatz" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Technical Issues\n", + "\n", + "* how to insert barriers or new gates at arbitrary positions?\n", + "* need to implement the appending of new gates/instructions (use `definition`?)\n", + "* exposes us to future changes of Terra's hierarchy" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Design Issues\n", + "\n", + "* inserts another level of inheritance (or maybe just use `Gate` as component?)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "### Implementation proposal #3: `list[Gate]`\n", + "\n", + "Base an Ansatz on a list of `Gate`s or `Instruction`s (each item with a set of qubit indices).\n", + "The parameters would be kept in a list." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Advantages\n", + "\n", + "* natural implementation of repeating layers\n", + "* not dependent on changes in Terra\n", + "* internal data structure reflects input parameters of the user\n", + "* appending new instructions is trivial\n", + "* adding two Ansaetze (or even other objects, e.g. `QuantumCircuit` or `Gate`) is straightforward: just add the respective lists of gates, the indices, reps, and the parameters\n", + "* barriers are easily inserted in between the layers" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Technical Issues\n", + "\n", + "* same issue as with `Gate`s to insert a new gate somewhere inside a layer" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Design Issues\n", + "\n", + "* this implements a parallel structure of functionalities that might go into Terra anyways" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Conclusion: Suggested design\n", + "\n", + "Ansatz as `QuantumCircuit` is not suitable: not the same performance benefit as the other designs, loose information of user input, `construct_circuit` is miselading. \n", + "Using `Gate`s instead seems very convenient, conceptually and from an implementation point of view. If the Ansatz interally maintains a `Gate` (vs. being derived from it) gives us better control of the user information and naturally gives a sense of layers. \n", + "\n", + "**Suggestion** Use design #2, and implement it as the Ansatz internally maintaining a `Gate`, but feeling like one. " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## (Previously called) Variational forms " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Backward compatibility\n", + "\n", + "Does Ansatz provide all functionalities of the current `VariationalForm`? " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "Almost.\n", + "\n", + "Missing:\n", + "* `num_parameters`\n", + "* `setting(self)`\n", + "* `parameter_bounds(self)`\n", + "* `depth`" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### `setting`\n", + "\n", + "Prints a formatted version of `self.__dict__`. This can be replaced by implementing `__rep__` and thus, `setting` can be removed." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### `support_parameterized_circuit`\n", + "\n", + "This is necessary since Terra doesn't allow to bind complex values to a `Parameter` object. Once this is allowed, the `support_parameterized_circuit` attribute can be removed." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### `parameter_bounds`\n", + "\n", + "The `parameter_bounds` are supposed to be the valid ranges for the parameters of an Ansatz. They can be forwarded to an optimizer to limit the search range and, thus, improve performance.\n", + "\n", + "An issue with allowing this attribute is that it suggests the Ansatz will enforce the parameter bounds to be respected. However, this is not correct.\n", + "\n", + "Possible options:\n", + "\n", + "1. Keep the attribute and give a warning, that the bounds are not enforced. Here we have two choices:\n", + " 1. the bounds are an attribute of the Ansatz itself\n", + " 1. the bound on a parameter is an attribute of the parameter itself. The Ansatz forwards parameter bounds it gets to its parameters, and if asked for bounds, the Ansatz asks the parameters.\n", + "1. Generate the parameter bounds on demand, based on the gates the Ansatz contains. If the standard gates knew their parameter range for optimization, this could be solved elegantly.\n", + " 1. Issue: the standard gates providing bounds is dangerous, as periodicity might be a feature we want to use, or the gate angle is subject to a coefficient invalidating the ranges." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### `depth`\n", + "\n", + "This equals the `reps` keyword of `Ansatz`. Both `VariationalForm` and `FeatureMap` use the word `depth` instead. Depth however, is ambiguous and could also refer to the circuit depth instead of the number of layers. \n", + "Using `reps` instead of `depth` in the future is therefore desirable. With a deprectation warning the attribute `depth` can still be supported for a while. \n", + "\n", + "Another possible use of `depth` could be the following. One restriction on current hardware is the depth of the circuit to be simulated. To easily create Ansaetze of feasible circuit depth, the `depth` attribute could specify the maximum depth of the Ansatz. Instead of repeating the input gates _x_ times, we could repeat them until the maximum depth is reached." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## TwoLocalGateAnsatz" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Requirement recap\n", + "\n", + "Input: number of qubits, one qubit gate(s), two qubit gate(s), depth/reps, entanglement, skip_unentangled_qubits, skip_final_rotation, (initial state?)\n", + "\n", + "Output: the specified Ansatz" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Implementation proposal\n", + "\n", + "In the initializer, build the rotation and entanglement gates from the single- and two-qubit gates and the entanglement information. From the depth/reps set up the correct repetition indices. In `construct_circuit`, build the circuit. Theoretically, the `construct_circuit` of the `Ansatz` class can be used.\n", + "\n", + "Hence derivation is sensible." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "class TwoLocalGateAnsatz(Ansatz)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Points to discuss\n", + "\n", + "* Should the keywords `entanglement` and `entangler_map` be merged to `entanglement`?\n", + "* Deprecate the `initial_state` keyword?" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "Should the keywords `entanglement` and `entangler_map` be merged to `entanglement`?" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Pro\n", + "\n", + "* Having multiple keywords forces the code to decide which keyword overrules which. This can be opaque to the user. If we don't enforce a \"keyword hierarchy\", we could throw errors if multiple are set. (And who likes runtime errors?) \n", + "* Assume we add a new possible input type, e.g. `Callable`. Then we would require yet another keyword and choose which keyword is actually active if multiple are set. With one keyword only, we just have to add an `isinstance` if-statement (which we anyways need).\n", + "* The user doesn't need to think about which keyword he needs to use for the entanglement input, whether it is specified via string or pairs of qubits." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Contra\n", + "\n", + "* The signature doesn't clearly show what input types of entanglement exist. (Then again, there is such a thing as docstrings.)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "**Conclusion** Yes, merge `entanglement` and `entangler_map` in `entanglement`." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Standard Ansaetze\n", + "\n", + "Such forms as `RY` or `RYRZ`." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Implementation proposal #1\n", + "\n", + "As subclass of `TwoLocalGateAnsatz`." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Advantages\n", + "\n", + "* super easy to implement\n", + "* natural design: The standard Ansaetze are specifications of the two-local gate ansatz, obtained by fixing the single qubit gate and providing a default two qubit gate." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Issues\n", + "\n", + "* adds another level of inheritance\n", + "* `RY(Ansatz)` is elegant to read, since `RY` is just an Ansatz" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Implementation proposal #2\n", + "\n", + "As subclass of `Ansatz`, using `TwoLocalGateAnsatz` as component." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Advantages\n", + "\n", + "* `RY(Ansatz)` is intuitive to read\n", + "* no new level of inheritance" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Issues\n", + "\n", + "* probably need to wrap all functions of `TwoLocalGateAnsatz`" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Conclusion\n", + "\n", + "Inheritance is easier to implement and reading `RY(TwoLocalGateAnsatz)` is still comprehensible.\n", + "Therefore, choose inheritance over composition." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "class RY(TwoLocalGateAnsatz):\n", + " def __init__(self, ...): # repeat all keywords here to enable IDE detection\n", + " super().__init__(single_qubit_gate='ry', ...)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "class RYRZ(TwoLocalGateAnsatz):\n", + " def __init__(self, ...):\n", + " super().__init__(single_qubit_gate=['ry', 'rz'], ...)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Feature maps " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Backward compatibility\n", + "\n", + "Does Ansatz provide all functionalities of the current `FeatureMap`? " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "Yes -- except `self.feature_dimension`." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### `feature_dimension`\n", + "\n", + "Possible solutions include\n", + "\n", + "* New class `FeatureMap(Ansatz)`: An additional class for just one new method, that exists under another name, is not really justified.\n", + "\n", + "* Add the method `feature_dimension` to `Ansatz`: If Ansatz is not used as replacement of current feature maps this method remains unused.\n", + "\n", + "* Deprecate `feature_dimension`, use `num_parameters` instead: Deprecating `feature_dimension` is probably not a good idea, since it is a legitimate attribute of a feature map." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "**Conclusion** The best solution seems to be adding, but deprecating, the `feature_dimension` method." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "### Implementation proposal\n", + "\n", + "The hierarchy within the \"feature map\" branch should be the same as for the \"variational form\" branch. Meaning, we implement a `PauliExpression` and the specialized classes as derived objects. This design is also the current form." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "However -- is the additional layer `PauliZExpansion` truly necessary?" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "def __init__(self, feature_dimension, depth=2, entangler_map=None, entanglement='full', z_order=2, \n", + " data_map_func=self_product):\n", + " pauli_string = []\n", + " for i in range(1, z_order + 1):\n", + " pauli_string.append('Z' * i)\n", + " super().__init__(..., paulis=pauli_string)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "-" + } + }, + "source": [ + "Later on used in the definition of the first- and second-order expansions." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "-" + } + }, + "outputs": [], + "source": [ + "class FirstOrderExpansion(PauliZExpansion): # resp. SecondOrderExpansion\n", + " def __init__(self, feature_dimension, depth=2, data_map_func=self_product):\n", + " super().__init__(..., z_order=1) # resp. z_order=2" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "subslide" + } + }, + "source": [ + "#### Pro\n", + "\n", + "* simplifies the definition of Pauli Z expansion feature maps (such as `First/SecondOrderExpansion`)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "source": [ + "#### Contra\n", + "\n", + "* introduces an additional layer of inheritance\n", + "* if `First/SecondOrderExpansion` is the main motivation for this class, then the two minor changes they introduce is probably not worth introducing the `PauliZExpansion`" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Initial states\n", + "\n", + "The `InitialState` class allows to obtain circuits that prepare certain (fixed) states. Currently, these include a the zero-state, a uniform superposition, the preparation of a specified statevector, or the an Ansatz with certain parameters.\n", + "\n", + "A fixed circuit is merely a special case of a Ansatz with zero parameters, thus, the initial states can be seen as Ansaetze. \n", + "\n", + "However, all the parameter business and repeating is not needed for an initial state object and we could probably simplify the object. Also the initial state includes some functionalities (as statevector preparation) that an Ansatz doesn't. Thus, it might be less confusing for the user to keep the `InitialState` object. " + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Uncertainty models\n", + "\n", + "Uncertainty models (UM) encode their underlying probability distribution in the amplitude of the qubits, i.e. they perform the mapping\n", + "\n", + "$$\n", + "|0\\rangle_n \\mapsto \\mathcal P_X |0\\rangle_n = \\sum_{x} \\sqrt{p_x} |x\\rangle_n.\n", + "$$\n", + "\n", + "In this sense they could also fall in the category of an Ansatz with empty parameter set, i.e. an initial state.\n", + "\n", + "However, to set up the UM for an arbitrary probability distribution they must be trained (e.g. via qGANs). To this end, they accept an Ansatz $V(\\theta)$ and tune the parameters until the operator $\\mathcal P_X$ is approximated well enough. \n", + "\n", + "Hence, they should not be an Ansatz, but rather use on as component. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# How would the Ansatz turn out?\n", + "\n", + "Here's a code skeleton of the `Ansatz` class wrapping a gate, along with how this design would fit in the workflow of Aqua." + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit import QuantumCircuit\n", + "from qiskit.circuit import Gate\n", + "\n", + "class Ansatz:\n", + " def __init__(self, gates, qargs=None):\n", + " pass # include the setup functionalities as discussed in this document\n", + " \n", + " @property\n", + " def num_qubits(self):\n", + " return self._gate.num_qubits\n", + " \n", + " @property\n", + " def params(self):\n", + " return self._gate.params\n", + " \n", + " @params.setter\n", + " def params(self, params):\n", + " self._gate.params = params\n", + " \n", + " def control(self, num_ctrl_qubits=1, label=None):\n", + " return self._gate.control(num_ctrl_qubits, label)\n", + " \n", + " def repeat(self, n):\n", + " return self._gate.repeat(n)\n", + " \n", + " def inverse(self):\n", + " return self._gate.inverse()\n", + " \n", + " def copy(self):\n", + " \"\"\"Get a copy of self. Can be used to append a copy of self to a QuantumCircuit.\"\"\"\n", + " return copy.deepcopy(self)\n", + " \n", + " def to_instruction(self):\n", + " \"\"\"To support QuantumCircuit.append(this)\"\"\"\n", + " return self._gate \n", + " \n", + " # potentially\n", + " @property\n", + " def definition(self):\n", + " return self._gate.definition" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Amplitude Estimation\n", + "\n", + "Using the `Gate` interface also for Amplitude estimation's $\\mathcal A$ operator, we would write the algorithm as follows." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "A, Q = AOperator(...), QOperator(...) # A and Q support all Gate functionality\n", + "\n", + "m = 3\n", + "i_objective = m\n", + "ae = QuantumCircuit(m + 1)\n", + "\n", + "# initial A operator\n", + "ae.append(A, qargs=[i_objective]) \n", + "\n", + "# Q operators\n", + "for mi in range(m):\n", + " ae.barrier()\n", + " ae.append(Q.repeat(2**mi).control(), qargs=[mi, i_objective])\n", + " \n", + "# final fourier transform, this should also behave like a Gate\n", + "ae.append(Standard(m), qargs=list(range(m)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Replacing the $\\mathcal A$ operator with a `Gate`-interface leads to the following changes and replacements summarized in this table.\n", + "\n", + "\n", + "| before | now|\n", + "| :- | :- |\n", + "| inherit from `CircuitFactory` | inherit from `Gate` |\n", + "| overwrite `build(self, qc, q)` | overwrite `_define(self)` |\n", + "| `build_inverse()` | `inverse()` |\n", + "| `build_power(n)` | `repeat(n)` |\n", + "| `build_controlled()` | `control()` |\n", + "| `build_controlled_power(n)` | `repeat(n).control()`
specialized doesn't exist yet: add `controlled_power` |\n", + "| `a_factory.build(qc, q)` | `qc.append(a_operator, indices, [])`
or `qc += a_operator.to_circuit()` |\n", + "\n", + "The following cell shows an example code skeleton for the $\\mathcal A$ operator and concrete implementations of such operators used in AE. Since the $\\mathcal A$ operator has barely any functionality on top of the `Gate` methods, it is sensible to directly derive it from the `Gate` class." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "class AOperator(Gate):\n", + " def __init__(self):\n", + " pass \n", + " \n", + " def value_to_estimation(self, value):\n", + " return value # not doing anything by default\n", + " \n", + " \n", + "class BernoulliAOperator(AOperator):\n", + " def __init__(self, probability):\n", + " self._probability = probability\n", + " \n", + " def _define(self): # this was previously in the build method\n", + " circuit = QuantumCircuit(1)\n", + " circuit.ry(probability, 0)\n", + " self._definition = circuit.data\n", + " \n", + " \n", + "class LinearYRotation(Gate):\n", + " def __init__(self, slope, offset, num_state_qubits, i_state=None, i_target=None):\n", + " pass # define self.i_state, self.i_target\n", + " \n", + " def _define(self):\n", + " circuit = QuantumCircuit(max([self.i_target] + self.i_state[:]))\n", + " circuit.ry(self.offset, i_target)\n", + " for power, i in enumerate(i_state):\n", + " circuit.cry(self.slope * 2**power, i, i_target)\n", + " self._definition = circuit.data\n", + " \n", + " \n", + "class MyFunction(AOperator):\n", + " def __init__(self, c_approx, num_state_qubits):\n", + " pass # define self.slope, self.offset, self.num_state_qubits\n", + " \n", + " def _define(self):\n", + " circuit = QuantumCircuit(self.num_state_qubits + 1)\n", + " linear_y = LinearYRotation(self.slope, self.offset, self.num_state_qubits)\n", + " circuit.append(linear_y, list(range(self.num_state_qubits + 1)), [])\n", + " circuit.z(num_state_qubits)\n", + " circuit.append(linear_y.inverse(), list(range(self.num_state_qubits + 1)), [])\n", + " self._definition = circuit.data" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Uncertainty Model\n", + "\n", + "Uncertainty models in Aqua allow us to load a discretized probability distribution in the amplitudes of qubits. Currently, they are implemented as `CircuitFactory`, but should follow the same flow as the Ansatz and amplitude estimation's $\\mathcal A$ operator." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "class UnivariateDistribution(Gate): \n", + " def __init__(self, num_uncertainty_qubits):\n", + " self._definition = Custom(...).definition\n", + " \n", + " @property\n", + " def low(self): # also implement: high, num_values, values, probabilities\n", + " pass\n", + " \n", + " @staticmethod\n", + " def pdf_to_probabilities(self):\n", + " pass\n", + "\n", + "class UnivariateVariationalDistribution(UnivariateDistribution, Ansatz): # use case? UVD as Ansatz\n", + " def __init__(self, ansatz):\n", + " self._definition = ansatz.definition # or ansatz.to_instruction().definition or such\n", + "\n", + " def set_probabilities(self):\n", + " pass" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Application of uncertainty models on QGANs:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "qgan = QGAN(real_data, bounds, num_qubits)\n", + "distribution = UnivariateVariationalDistribution(some_ansatz)\n", + "qgan.set_generator(distribution)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Application to a circuit:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "distribution = NormalDistribution(num_uncertainty_qubits=4, mu=0, sigma=1)\n", + "circuit.append(distribution, list(range(num_uncertainty_qubits)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Advanced amplitude estimation example: Ansatz + uncertainty model + function mapping\n", + "\n", + "\n", + "This is an example combining an ansatz, an uncertainty model plus the mapping of a linear function in an amplitude estimation experiment. Here, the ansatz can encode optimization variable and the uncertainty model could represent a probability distribution." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "n = 3 # qubits for the uncertainty model\n", + "k = 3 # qubits for the Ansatz\n", + "\n", + "prob = NormalDistribution(n, mu, sigma) \n", + "varform = RY(k, entanglement='linear', reps=2)\n", + "\n", + "# either encapsulate the logic in a fixed class derived from AOperator\n", + "a_operator = MyAOperator(prob, varform)\n", + "\n", + "# or do directly what would be done in MyAOperator\n", + "f_mapping = MyFunction(n, k)\n", + "a_circuit = QuantumCircuit(n + k + 1)\n", + "a_circuit.append(prob, prob_indices)\n", + "a_circuit.append(varform, varform_indices)\n", + "a_circuit.append(f_mapping, f_indices)\n", + "a_operator = AOperator(a_circuit)\n", + "\n", + "# or do the application of the cost function more explicitely\n", + "a_circuit = QuantumCircuit(n + k + 1)\n", + "a_circuit.append(prob, prob_indices)\n", + "a_circuit.append(varform, varform_indices)\n", + "# apply the mapping F directly\n", + "for i in range(n):\n", + " a_circuit.ry(angle, i) \n", + "# etc.\n", + "a_operator = AOperator(a_circuit)\n", + "\n", + "# or maybe even use the Ansatz constructor facilities?\n", + "f_mapping = MyFunction(n, k)\n", + "prob_indices, varform_indices, f_indices = list(range(n)), list(range(n, n + k)), list(range(n + k + 1))\n", + "a_as_ansatz = Ansatz([prob, varform, a_operator], [prob_indices, varform_indices, f_indices])\n", + "a_operator = AOperator(a_as_ansatz.to_circuit()) \n", + "\n", + "# then go about calling AE\n", + "ae = AmplitudeEstimation(m, a_operator)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### VQE\n", + "\n", + "Under the hood, not much would change in the VQE algorithm. We are more flexible in how to use the Ansatz though. Depending on if we implement a `to_circuit` method (which seems very useful at the moment) the changes boil down to using `ansatz.to_circuit(params)` instead of `var_form.construct_circuit(params)`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def VQAlgorithm(QuantumAlgorithm):\n", + " # no changes at all\n", + " pass" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def VQE(VQAlgorithm):\n", + " def __init__(self, var_form: Ansatz):\n", + " # only change: either add a preferred_init_points method to Ansatz, or accept such a kwarg in VQE\n", + " \n", + " def construct_circuit(self):\n", + " # we could do\n", + " wave_function = self._var_form.to_circuit(parameter)\n", + " \n", + " # or\n", + " self._var_form.params = parameter\n", + " wave_function = self._var_form.to_circuit() \n", + " \n", + " # or\n", + " self._var_form.params = parameter\n", + " wave_function = QuantumCircuit(self._var_form.num_qubits)\n", + " wave_function.append(self._varform, list(range(self._var_form.num_qubits)))\n", + " \n", + " # rest of the implementation...\n", + " pass\n", + " \n", + " def _eval_aux_ops(self):\n", + " if params is None:\n", + " params = self.optimal_params\n", + " self._var_form.params = parameter\n", + " wavefn_circuit = QuantumCircuit(self._var_form.num_qubits)\n", + " wavefn_circuit.append(self._varform, list(range(self._var_form.num_qubits))) \n", + " \n", + " def _energy_evaluation(self, parameters):\n", + " # parameterized circuits should be supported completely (Terra will implement support for complex values)\n", + " # otherwise this is supported exactly the same as before\n", + " \n", + " def get_optimal_circuit(self):\n", + " self._var_form.params = self._ret['opt_params']\n", + " circuit = QuantumCircuit(self._var_form.num_qubits)\n", + " circuit.append(self._varform, list(range(self._var_form.num_qubits)))\n", + " return circuit" + ] + } + ], + "metadata": { + "celltoolbar": "Slideshow", + "kernelspec": { + "display_name": "latest", + "language": "python", + "name": "latest" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.5" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/notebooks/img/ansatz_rep.jpg b/notebooks/img/ansatz_rep.jpg new file mode 100644 index 0000000000000000000000000000000000000000..55f34b6c702939eaa80d6993d848f910299f669d GIT binary patch literal 23913 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 Ml>g`V?cN&rH|d4=sQ>@~ literal 0 HcmV?d00001 diff --git a/notebooks/img/ansatz_scheme.jpg b/notebooks/img/ansatz_scheme.jpg new file mode 100644 index 0000000000000000000000000000000000000000..b5c5c68dca5e31988c57d4a8431c1cc1e79ad1d8 GIT binary patch literal 144371 zcmeFa2S5|sx-dEv1q2183PMn-R6(jhA|hP`RC>uqK$;Lm5tNXiD7^>>C@P>dktV%L z=!l3k0qG>5QY8TlfwX_zd!KXe+2@>h@4NTC^Zwtr2PRpwvS!VEYkjl6{tf*TeGcF< zH8e2<7#IK`4g3S>Sm1_1u=iyEFgFKe0RUhHm>GnCJzxoJ0zesr|5`R=kO7!}t!D&) zNN<4o_crIi?;ji3+pp*R_RW~h_?H$e$FrIKQf4ao(UiUhXj*z9ZXm9EA+Cy@P&^K3 zo;ERO{?Q}2{aTj%waE2RByKzrs9;_SV|%npI*p>^7*Cn#>%%S2TNs+0HTV?}#^ZWt zP8%?C0f3+Xjezq;r^W2-9mH4$Kv>uT9^eF^?do>@s-C6g*&luSBm6yn?fdUOh@-#W zJ20&9qp!dF=|4Z%=XN#V2H1=O?kesc*WJK@I1ZM5gKk^}>lvPcW!_7^zm{MBCyPrK-^z!7ly7(h|F|xokGOg( zz}wU7hM3CnN#4g;re#67>x|oT-8zSH;BEa>AhdbEzxBL5X7Qp>m!yh9i zqpYQ+dF*J{)09fP! z05j!pb*k|IkSz}YoT-1SlTro%E+qhHeoAivxLKJ>SdKF>90eG;8JM^k=p6tA9O^v` zzixlIEe1v=<~@5^SlRZmgAJ;=07eETCPrqaJ$rs2DnlsvJHX7n=im`#y}dkEt}I8d z@v7WOdd@0-y1bR|{2*T9#HE0{Z2R~H1P=*GN=eHclT}qy*U;2Dsei`6(8$=t^uk4J z8(Z)e-P}DcdwO~MT)z=`Gbs4h?eKf|BO;@sW0F%IrlzGodYthhCpRy@;AP>fipr|$ zn%cVhhPL*O&aUpaJ@1BwKaPx!eHx#@;^r4VfBCw&v`pC8-1<)3ChhG0fQtcO`VB1b z^Eb%;02en17b7z>6En*XxEL6Nz@3SkdCw8$y$AKISX{61996l)%6mHLd3h_F_=)p) zzDogv`}iePv66%zp#2Kje+{s^|1HS=3fSM^ngsL##$PukMsSvxn82B02Dd#ddwy&z ztSrB7tiNyje%;uAZ2SMZ(ZNm_z&^l}_k#cX*;v^A`rCiGK%WK|w(Il>fP;wvL?$L~ z00vMgFJfeXpK8Y(LCcU?UX zSF{jb8yE{hz~alCac1Xs3qW{QMxNG2L4e=|`q z4wiWM_H10&jPc0hXoaKDbJxQ-F^jKiYeyaYiqjk7J8WtQfQ$Dtw|G5G;m1)-5_fu5 zoMzq-m|9T$ud7FNEO6%H#ud%oC?3xJVT%y9~K-;(C-%>`yPA%e@+jBr&&`1!_>E3Q=ybinGGhBfOqi<7ix}W%-suBB*Q1%=nCmrU+-j{S zkrDySUT$G+8J+$3ZZ8u!&ReTTEfs%;4z#PHTg_+^ zNWpZfa64S+1_9T%pOZC^l`{2s{cb!{(PSC-^AoGg;1hN`lIN}Q zSjrQ{~#2lg-#M3d$rB{oma!UI7ka}x zi-iuXnhnCXl1~DZ@6_n3J~+{XTGxDx)-80oJftv~oqR~gPBmzzSoml#UX#H3n0XBUhlLwknzCFYMlIZJYTL2{6z0|%DUgVyqw8Zry6a%HJ_ zc-2(JT|U)jaQV2r&#e0JB1(V`JnRW>r}a=^yB4l+M~X8Zv3iYc9Xzu>=h;!VYQYmc z);8LEb5z;sO>gj-fV3bRQnYGFe%Yj% z?N*1-4~2e;4MgRLbgQBCqanKFhuuwFEtI#NryDAgR5d;MD>qNwE2{)%tl0 zF7Ha0;I!GZP59Crl;V}|GM{5iVxp47Rl3eVonoanG>YWJW%@s6;m^aOXSw{49(e6J zmWU>^&^dEXTz>PYi`baFBw2UDp`hq&+;mRl*SV~i)Hf|47f6_RfuM9{4#=)ffyGZHq2 zbj9__ov)*H4t+x?s)gFZ-^@NbdU;dgn7mc8-3?X-Y2bQH4jo{=N(WL5>*+vw<3&0! z$p4Umpb-i7p)@{k369T$;3vfE4TFl4Efa`)mqtofBXRa zy^m@kjS(fNnJ6)eEIz#z&FhsOB+7@^=N~M&U{xPuY$kVXTE$o*B?1cq3jAX4-o?uulyUV?!e zDECwTE8T}5QQfI=AiZz27`L5sNyoo+5z)8KxTWUjzhrW}r*K-rSLPlUYlK?7_}MT! zsSSopa$nJ(LWn3rO#yDdE%7}yXMU3=6THKb;T-q&G%3g+^%@7a;rQ`h2|K4y60S{o zW|L{x^VA+*tDky@&o9Q^TLcfV%OJnXk4*4!<-U>f?(LilT{}#Khtfp3EHHD zDJ=K-ooHaTIVB#PFb;Y8z;@}j3{a*_>I3NsS_CCX3dd?B?CB;dMXlX`(>tLe*)O#qG>4zQ4ttyYqG+FT=*j*lOyW@cQ@-R8K}kEl#+Mt>mG@?PZlIhi9&S z*^Q2M56&v=X%?3$SK5Vf%RoZDlwBct%Nq$#x#WB_qTeTr9L>08r3JW z8;?qOJE+F9r&`s$l9A39k*j|Z2EF>4noeOVKn?AtuUYM(y`GUDQ4JiFs=Sqb(qZz| z={w0s{G|_G;#>G&D?xdq{1sD`zAA~gC8mzaQ+!Km3b2Snb}zaGqMEc$I>3#i+vLeP zf$6_s?d}{+e5mOnw;c9&xSQV8)LH4Md$8brZjap)*D3m%eNN0ECP z&up-pWlYbvxu`7pvr@Hn%rCVAo|{-QeAs)4kV0f4nGm|M1?{uO*X0F3OZ`k-NLtus7h6eFClv)OsSb7qMLXAD9D56AObKAI2Cu4U)qX5=l@j@J6h zv}pR133&e~urkqyey+vmMe{XMANe%MQ|?z2hO>}@&Zc)XD}H2rq&kUA5=7T|d^!}X zVI6OX(~{I<-U$dECeFOE3PjAsA7EYBN!Cc_^I*x>pZ&%%CI<1@K0XDDE;3d7D$}Mi znQ5xAX|jSi5t9#n>OPl};yAA1wzeyWQzDsS{9(I1RS+^2K?i!a&~4V_Yjj}XSvDP* zT|v_%Fj!e?9UWLaH-KLMj-dn6gW!{HyVgwy zPTvft18DHf9cbeB0Q45O86DVr2KML4e;BY4lOK#uBAO#VVsjo5hBZH6&nMA5^oZxc ze3+TUHaE{=oSVYRX>8mX>V%s22j?8k8Y)+&+n(ZiiN?A{$PFvIOksj(JZ^1YZ%3wR zy;+~OWt2H{&)`G69?OGwdK?9*zvwO4Oe43jGA3=NeIiTwrFUaw3I(kUc!8gAXP^)N zRLcPq7CoNu0m6rLBIOV`?X0d9w!RXUvxj^+t}l_Y*Si0#gjKfg=|T~_$%*`vSGNmvYzd#sl@iIsx@K8>gmJvl> z2|y3@fwJBl5<&?mTCS!8N!0hc#o9Ta{|PcjV%!QZW!aOSt14C)Nj1bJFuPCd{& z%w?nxzdBainYE!-NC*7sz!JA+1!mieLI>1&tqhRZ#eXG(LAX&}m=&5h9r%Ra?S=b~ zwL&Uvqjj{OJ0tZIokp%yeNA_s7Mh+iVz|mtFDsHR7GeuNWcb%j40J$WJ&_LF!J`T9 zb~EMLN7B4)tYUqqm#80a)q5Bht6m5NuYQx)7V-}RQ<`Y;v1-j>P-&~^CBiTFLr=+q zy_;Wdc*J?VR%X%LV|^d)8_RuAKql&)Q##XIWo6)Q`BN^{BR|EH!PJYAqKM!vI^R~2 zkRJOxdh=EL5DRAq=00#iZ+<7=ZAzgDcFzS-c9tO|q3_@Q_?BHOn^2+|d8ey#_y*OJ z`Yy1X&aE$Co_)TNPEk&5S>M_G2*ax_(t!wNk_a7u-j1a0eG}?vfS^@e#%yuJC~Qg8 ztOz=g<@*iFM~%IruvIi0ebV{SQFh%+!olH(A0(-@m0DcC0}r(AfP)eQC9?S#h~J^; zEsws?MrR#|$v&T2>MT`C>Xt(dzuefStAX0&B>~+CUo8An5b=E$u?3$A3Zm=m-Pn+L z@e95T2)?B^_FVeBFHWyJ;v`-MIO@=D3)Y>EkM{bY0@WyUCT#mi`N%>6qJTiR`prUi{wM5+B zDKDli{}{PGia8+>D{!~^QIpm@M3@wGdZb|D((8}aj*eypoZC0s+$XjLtsM2gFhOcx{;<$7ZF0_WwyXmbhmTFyL*``^J<=^kGi5kI~u z#nn%(ye$LQP;4BE1>K+d99)#joX~%uyWI!BKEBVtMH}B)a1W`PY*b)>=&YICbYNPI{2<$h-xa zQ-hW~IrhzIb{S3`hDXBi1`GTy+yr9s*X_|}vA}DyvB9`ibXKm<{6Kg^kN2WUT`_x!v1F8`+!ywGb-ngJGeu`O@U@?}{_U>(wVTA_rS!0z+MH zR8(GO<~pyHZ+}?y)jivA9X0j%LiI$+tPak7@3&WYuTvlDF1H@;($Y7axj58C zx_U7c7=NcK zfw#`dEm3w~>&VSLt>Ugsg=J$51C}iFi0+O=A{xB?Q9Qhnk3R2ZjRW8E!Dl4eEtpUMzJgV)a#x0Wkzc(H%bt76muA40&_M> z%gEXOG;PPzrQ(c{sx&A!VkH_KeUe;g5RxJOp~Pp!KWTmUNT*Zk;&!+Q5F83 z4se4a4~*(jR_hDm^B5J~fhKd(0ej!IiCw4y$WxZU$slnsG1_ZOTZ3eMX^W95d#Vk7 zW;6bTJ12eY&o%1zH7d$bkL3-DcLl?W@#zO`H+Ko?9f{-fZ8bA6yg)*klthzv*~QardeO(^x1X`H5qX1iROwzD9ghfWbA=g~Jd%cB#! z6OP(%N4=yC6O5s{+7pbXr>htkyak75EHYN_nQDqUA#nEJh@9oe|>+Rq_IH6idt6&qnd@N@x z`4HpV$VwSCJgBF}c=b;R&t*ns?T5-!#0V^L->C|yUN;;kd#~4o&FiR}-8x;k;M@vN zOOBYgb5P?QGhJIo6tMdOv&+79OnT~Gw?aU?En z*XGIP`|?|)Tz~hC@TTOqfW1`GTj6VPf2XO*@yXtxAXz)s$2`&YyGY*8bV=^Zm+~WgSR_auZEM)>xvpbPqC_5_f;+9O?VB{9#y&D z{jQ_*Vi?L3sf@`Y_E2l8F^LmCO*BTlABJ*thC9PRwpNbazp*I}f=!ySEIuVEVXgC= ziC7^sDwr&}7{iO=TR`unagdDWy6^kxC}ABn{S?-Y+T|GA`W!vbUf1mnaLl5~?Dkd}Xy>`#O|}KCJ@U1b1v)T4 zLR{lpb3I|o>n(e|{j^^oatwXlc%dlb>F4*a)D}u;MjdcGsB-tA1G|!Gbl_F@9@G3E9P zQZHdn=SoO=*EQD=L@qWiYy3ez|ENPO==`u#VoQTirH;M>**&*S$|oxWzD>_;P_qL3 zvmJGj!cV|-ak4Ept3_hd@3|2q-*i=qJNHPfPc>BCx#*V!#Y=22xom=pkwjt{9e81n z*y#a#&JW&NPz~&ZP3& zJvyn$QCuJf>VQthY|ci_?rY*CTre|N>T(FK-!M_%<}Oe8GX115LGLX~T;aQ?9N~B1 zs*q1Xtw{&dTx7?xBc-o|V6}}t8fMc@Hq^_;ar6V&>t&mMvn zT2O9pMNs;n<~KTN!T*IE_b&P8&hMNrYS-B>yhokP|J6@=NKD(mj- zPUNUEd=pf=Nx>IF8~^hwtD-$UU|WKqP8?)Yj_-EK(L&J+y_Ce?tiw@AQ2NqGftKM= z5QGj;@&5-fR#yvX;Sd@-`U}La6Ww1%d5lg12_Qj$qRe?8vxpd@1M4p_qzoALk6ryo zfZJCD%XYw_Nm1H>PQPeA3hJ_s;A^S-K}L%DU4Rbo82z!k%8IOA4m1h8yGNmJe4vsQ zv*AHAnymf`=YdL-Y_XmZ-va5tLFcZ7r1I*@8RqSPI~(0Xfm%BJUAzHT_aOWK2uTB) zjn;+PM}fUED)znZBPx+0#gXKrB0awGhTTZ$7&=G!!nDux@Seh+bNNyi%vN8j&ZbUQ zNRD=yIH(SVPGS}f$cKY%?S@bgAE?5Z`0=UWN~_S*5@LnwbFL7U2O_Z*yZJ+!YTu_- zG>0VYURXwj$-asMSODN8gGHINYIm=2Os1^qRKI`kiyiTz{d!h;LcZA`oo?~}XC(S( zs6+o`rry7(9;v;cCHu;>>_o)@Gf~d{lp}&pVvUL{u!kpfn82L z+WtgU@s;+66^}hPD%ZXe>8jmdY7~ zAt{3MKd*{z6Q9TIims#a&R|GFm+#QaoRw;AP%vgl++itC%mOd)eiKeQg9Me@`qS$) z_F@>R4}y;(tOB-CQd`&ql#^PBuS$(YWkcEh|GdwY+IVLeFjcJu=!OIGbhxKk)_gcTE%j?g%`w zk_HOj1*)KA4z^n6 z&j;dJlh!Mw_lS-`Aokhy^TS&qMIka}51%P3+8F00%^&U#ZRLn80oj00FwpIH(SI0* zH=LzBI|JLWL%>!YszAQ7H)iXV-Fv5p!}l(grqs%Z+{))Il+&*H9%}yu^Y>>N5ji_y zyTVod6z*Ekm)|ze$_e9KH~}MZpx=&t>h51hf4Nom_ie1G;RFj>#M%ka1;h^w9vE4= zX!U*KSq>ct>!yVNdCs3>@FyPp`7Hdo9{jl`{_jHY5Hp4T^(j|A@5 z&9A*TnH%e^-BI#6J;nP-fZ=>!Q0f;92W&yO6eO;_B_LDdo|^M&8T(}+b=Xm&k!YOh zVqXL=v$<`}YvppQ?!W1v&+zZ?)hbgXh0}o}aAx$UUI^{M%vhdn21O4P@XPMPRy`8w zfHA_il7WJFh}lZ}Rg-aI=;e!;d9{5qFT(zJ+;v7FJMtP?Ls!TtV0Tu# z5S;k3x9`&WM?fpD)8*&?EYRuSUFYHp1}*C~tW)C}W@%|AE~$U0aDIrHUcTM^T_v3$ zzNsr4BU5_9^1rF)WBPY^(EN#2|85NWXV?1!68*o6RsRO(kw3BOpUv{WyYAnLRsV(n z{(r!#Tkh3McY&0iouif-EHhtqqYEh(yKP>^0DMEb49h^u>9%Q(h=$T zU#-5YEq%6g7yk^t=F#4QEm3y$QfOH zytZL|s8#IXsY5Lv>vJD%wYfCHg=gu38K+h z-J_u)9YNPVc@rm*E78}>HC`J`ozm>(g66;Cdbsd>&&`er)76C|ps}j`7ML4oq=1&@ zWSeK(tBedLL7~#qzAT*%!4;uZY>Hp}WFP3dv>CM(VdL-qL}1$V4qP zdIv(tJ`fS}6;tgW%CiBRHzJnwzd#vLyqKQ9s9#@m%sN9!Bn?uFt}kXKfw5@7qE~4M z+2-pYOq`~Q_Lz8_Sk#)KG5l2*avkavb6ycaiySc?0alcNuSQ6*tJU4 zp@WPYNyjc(I2XaK((&K4dD8oN43D*kOe;lfH#gXA`pz#7mlpP{EbgwNo>)0;|7EEE zIwQ#XC6WDn{eKzP#NUU1fJNWn`t0wsmGhU;XBZg#CtUzHRBd(tI$f~eXZ6(o5#1)K zd7mJ6FrzEGNdtS=_*~c@l?o_l8d=_sDgVv0{IBjY2~RV=A`lsumCsxgoTskSssZo5 zmy;bg3l-7hOFJVxMa?L?mffeL2D}U<)Dop_flXDkuNk$I(&s*SN@#Xshz?vspD-d; zVW!~kN6r6i^=}^uc;al;Y`Ydxm~h%L{^+N8?T!y)X;vM%cXZ;I2VRPF#MfUu!1r+< z)wk3aj!(FQ3n`J>bf|WWzF{`51xfP=~7{n6{%b%8>0=O>(vI6lI+ZSy?LHIAY z;UX%>bAj8zdb#nPdF`gQ_i((XjFG$V@3;f`9dGPaZT4jRiA4YA$0^4aNf`{^(kupp zhw~z>Y9FpiJO^j4;H&LQY>AxQmwQopT5(%+z>^M?oD$*t50NBX{W>?7n)SCtdP-5D zr*Uo@&texb^H$SS!qKs4R;&?d8E|6&y|H~}a3E%`3hr9}H&ZtgL$H}L%`-3U6+e(2p; z#MWmlgBdUH{t6{Xc-T`6%_Vt(dR6x!t5g5ugM+z4T>%NbTWTe~h2M^9$8l^S2*su{ zOjR!`ReQrFE=w&GSmb#R{6ngiA5wwSx92x6U*88wviM@)H&vg&b~td~weO{-|1HIh z7F?KQc8)N1@4E%tayS)ozSgVOO-k!zx0q;o9fxiwGMy|#5&DRfF7(Y*B$(Hxp#83? zC%MOIG75BdytA-eWfVWq+9*W69rGPuKPt|7x9Cnjbs`OuT3cHhy?eO&>W!}sYI#lQ zvKG*dY2!fl|4sD<1K}+}^MB;Nfgjs~YS0MlTPfAJ$^ z(zx)nn>GG+Pxsu(F>Qz2MLbuFKFLr`ir@WX_TaK;j2C(WLX0Na&e!Q^;EU!i=MW%< zDd!^AzK1xD)y6BjCtHVv#`?*;la=!fB5Zx%5wHh+XdcoAQKE#I6nwWM^{JA4lWmzk zFC?zY#5LoxvBo_`o%3>4#Gk%-}GK86~CR6*Ly4lOG?FS;;{ z&Q}a%CyWX@%=#woWFvpEre1rBpk z2SzZ%X{_m!Eq!Q0q-$l)!Pl{nHo0=YQutD?{EXD-=B9mdhe+D%hriJ5d#s+)h*F7L zF24=1T!+pc@~L1>oJJ?)Fy$zIV>UhryE$o8^dyR3`;vb+?}n4M0J%WRx-($5+IoFW z*%iP10Wt2-Zt+paE-=KSG1k&I&?^67dY>05hkaaWarNabNG!_N~OC zkoxl-^(m%aVz$+cgZ80Ju81lCT8_WzxVBVa}Y|9LjHN%~bV!eSKBq#K03LU3Ge@V(bq z`Q(-PA+bW4mV?FnUcbxSj|?IoK?V|LYH<(&S|3d0O9DI^v)|p?PtPb#jVgK?+W+#! zFUU>@*a?v{N##3_!vJ#4-@)};5cq-Evrl_i(x%dPev7fx z59st;aQ%3UX02umQiVis^t38N&)`4Hq6U8e1#|w~O+cauv^O|EIjraE_dwhvg2U&! zcdf0uP~&S`6A{Zgek1Rz_rrR2$Mix$=R1B920yvF+r74jtVMd#+RUGf)AUzs49Ray znC#OwTu2@g?2*nsal}82rxl>OfZ`?_spu4;KSH(aP_WI0uD;P|$&u#rhS+bt%*!Ie zEX;>R^?>kJ;I7>B{}AL(0V5*r-lT+*o{{w^nuNrt=3_p}KDHCESj8JfMiHaJmTBda zlW$+y@SW;VjSJ$=^c|~mqyrO$7@uc1yB&tB@<^f$XZ`YA#9N7@%^T0KednczvrkT`8#pk(kt4U)E%h}AC$f4M^4VG8p9V5s1mji`O`zdBF`tVH|5pAr zCCfiL^)~xbi|BwiCnv2pi&cpxu}qw|!rVIFZZxdZFF&))bJvRfm(+MZ2NPE2d#Cr> zg`v3d-E9`6W0BpVib_$UYNT2}e4(0zhPtT8aB)lWg!Ik}`(&|08lJh8eXciy*q9I51AD&+MDnA&_ zm~zy3`5t6!`Jb%0%{ruNvJoi}yS-+DPoGnNT;RR!faqXV`hsbA+CywaROH5GTH3Nj z91E|vKw7eVy74a}KL4tsvhB{Qj$DJ_VB=sqS7$fuw6?`Ziv)_JFP2=6bf4Z|wHmY0 zCVpdQESNm*VrUQ=`L6?*y}jXt4fHf@sM6QW6r6_?+7j&{!yu>uV))%JoayNZY<`8t zD0i|d(1HYFc38}Z|A6biCwIVzVZ6X>CZ_4DbO6*;ZK4-%SEHK876jJ7hxFKaY8IF} z!UaL)w8`cin;G&PD^SPN*dLN=7P3UpX7Sq++Dw)Ut4>;SMq75zHzeF&4U%O zsZL={9bZSAm&$tK6PXawMLJMxvHG1b%KdpfIKwQ9(dPry4s^dUGxBlQ)$$#^vU~bO zOZI^r+CFizGijaZHi#4{K+4^Hx6+Y$w7$9Fv68~Xn)uMxTm5rgsyF1)k{oYovJ3AX zgs$Li6TyT@l#_!{DZ6*&-a?~^ekBqKQ$~nujQyLUlYGsH)B8~fI?yIwfcl88jqHr| z^Fs||(UGEz(7o|t?-ZZoWO4-#)X(4UR`_T>EBhv_Y#+&k&~A-qq43Dz3c_{tHIi_N z5w*8#+qdIt*HgdC-9hjup{GM%S)ZFb6)MBDW--n}d`3WYCf*fQqh_O&`&@H_-Oi1w z84gVdUuQ{q;XPO!FQ41^`0&A=E;g?Zd(DFp_n~U2Sxoi)r*wb|lru_TZCU$iqCGlE zi?vW0&TB7yu1z+I*Kc4OEQ^;f;v}rKtdmdYy~^r_MBXlFT_;Ht1q+{x?0Hj#r`=b7 z86II$Epl#jnG%9CS-6me?ID(di?Dleu`4yLnLGbk?K|kc0sES*O_z84>4Z&o&zUf2 z5Q&X^5$RY(8knu118Z(rsJf0@x=>UbD;3{$)x36c>jBeksnI9W!)ip^wF`J{Tw*tDzgL4s z+idhiK|6b&`p&n~vK#e^ImzGnTijX`nScT?zH4J2gtTeI#UJjmIPKS*nuOhYrrbJ?L zFQDhj1D2C$?@w~vbfX@GANr(#6}ibS_vMt)_SrDcDFxIk?`wAL`40N|e&oYf4Qt5I z^<-Y=?wYAfVNgkGD#oWw0BJ^ujD|8&g7K@OT%^jmPsupq(1iJ@L+X>Y&c0HY(~QyL z@{QA`4GlHyvewjBXi#^E)F#Y=na(`>!M7f?*U%J5CAdY0WmW`)|D1fS~nDa%i&RH<%JmX@_{48`jwAYd`c)lC#;DW{YIli9bI954%mD7O z;+lf<-O4W9#5Df#p{t&3y(+xteOKV|=qig22s?!h|Fr`hK6@ZAkq4Z{0B>T0e`1KY zyh488%lyxw=aegqhtxa#Hf7Vrw_^%ILqp+5Xru6ICrD*rF0YM&l0t!`Uqm# zjISf^iTlv3iz%`l>kSKbS~%09_~g1Ze3# z*1KcyKz9V=`b=+$Nx%Js3@!|Mk9wCTjO4-xwOW&k@M>!Hs$fnJ zb^NkM&2Guij8oodre}m5@4YyLNz+H^oCmC8wlUsNU2tAgPy^exGYTZve30c~x%a%W zzGk?XV(%yJQ)_nRi^>@5=(c=rovd+!q@Z@toOY-MSv#1qmw1Yra^o3GcWqB?YX0(^123oA7D*U)0=kBT}qnbd6Q-BbwW-B%IckdeurU}d4R=@d>r+0R-igD9x6snLwmpBu^5Jm zd8NT8Y)+;n)!8lAg!>-kO=h|kAeW=a1T6OmKi|I*MBz)qct;_{3)P%XeS9)&|FMaKoG~MyNnq0Bw+V%d+WBd+HQ-i{HqD_H($^cuZbAE=iaR(_!%z7=X z>>Ki#pL{_z!nw8fdfcAQ5HP19-#X14I!Wv513gdAOk1)HKq`vS)yonE#F&&eM7D_R zFqtbDX+}(vhOBIdDSvh=AlN>m1cEuc6qn(`EURzG(q0aiE9ZUXjMpjprM~B8$4`n> z-7&W3S2>i&Xgr?S7r$I|IL=Obx|thHAY}oDFTV~fpv5>)6sXT~s732AAH+n!%A7ic=L_#{4gmK*zYVzHF`MR%PSS4lmF_wxpBG`l%1ZTC6SGB|+H8*l)B0@sJMnS&s%^n^Ey+ zwgGisH+@^GU#w<98^HM304$Og`Idr6u;d98u7MSi3Z@OLPKd#Ky>*!>huyofmbXbEjTu@G(i$OzN`bnkNib4~WX?kiQjY_bYL2Zkycj!S~UWy|{uAICy(wUiGNL8XH;iqelh|DrQeiI?C0eEe_^PlKtc& zPE4T|H_K2&s3pxJND+Ky(t$TGf(!JMzd5T2vJmfo$q{$y^y9VVSUJqyGzAJ-5c}lRo$8AN$o17$jmNIFZ#R3=MeWZA9sZ^;(TJH~ zW&#)63)HOELv$eK^7@v!OV}}rHDQdx$39njCzMdzkvJz3)PB-ZV4@(RDk?A8Oiofe zPjVsV(Bn%M%}dvgS*1^0F<=FslE{FHvn)Zz^@(j`C^gb#C#bGc2-a<4Cup?3jxD09 zNp7x{D%5r*%AZ-t@5)frcw1T_m-AZMi#e;RwzGdCc@hVW#~Tsd@J=c|4*40oCF`-@ z7iY;r@0hP2N>GO!dFJRp*ZPUYvRvIvsn6vkX`6hL)*ay0tWM2^Vfjdr_-#u}MEiwC z{Hn#CZ<)gjcTenj`C-KGNzRP`#uHud^WUt`L)L-_N1!?uWM$O*8MaD7WP)n1;CB&! zvR#9EgH0-PtneMN^NETFgJb!Ut`5n{+?*1?^-q3SA+9t~p9GGQzPjRvCR@L3oBJkV zyFNa-V1gQfB#UdPsM>8FKb(dAAj9)?Hu4$S8HilM3xlS6M!;F)$nPmk1?jTX;h{vKw z?y&OAOxGP1wqqaj{!H+?kYwb(XR`>##Rk z?5Mbq##FN16Sfvt;S=R5XUV5vXDEV5OC;nuL^w8(aA^3-hf)RD{FINVX=tv&*fz?4 z4YP`C8YZTZA_MU`b1aFpBTHZXh_Tr-eeUC3lihLM{ZFyCM4* zGxfshw>jeC625Olwv@#|s+78CKV?~va^^+{F5nVgZ+l-xxCY-yBAVN;&E7tC6SA08 zbNrlp>k`}mj8EF|hx4IVO$Y+CCk16sU~}oS8}2l487$rXN_*zN$h4_VyaKBQ-{w}8 z)vZLb6=>$n>b9EI6Nr-<>Bzd|eJSlmoc)d$)Ihd96(Zw6)uh&g+^G_n^Q6*t_49Lz z9v(wv=Tm4QKS8thrBAHV)9Y`hQpT)@voqQLH!fY1A(WzV_!77^vMB-;)v_>e zQ08P=C4fm)&B~}fmMlXP+fiuW#67g08F@lv%xrrA#b!XPaYW2qg-ubl=SuPTWiLvN za-->JuZ$oJjc|z^L3@tjB%xSLo|_ zU{~mAoD^R6a5c$q%DTQT4%7w|Z4}Vhux^2b5S&t%#iX=TbUSI*Ddh})=iw#eDqqG( zCf$p#K$&i$)`tqJdcx5@Sre6Avj-?aSj_k)5shEN#G>Sa8~7XU3U_xVq`T);>b~VX zB$=iq$hgR7*~qg|M4`?nf;yvCbC{diS-pQ35@5_k8y9Ts=f(wZn3^W zZSEeePo?GGTAAdLY%bSNFo_N&2pO^~1slIYf8(lRo}767sROxi_7&#DOUw7oJ!B`;I~O%lCoYQ>=}D5t zy+lF?+AWtZ4lAyUtJqIXzBAdld_?kCRpsVq)40;bMSVt$W^fMp_Q6Js2U$?ZoP3s| zj^B>f;okpVy|!UJLh+0(_pQEi=ZEi?*$=9(*WN!AWxj0p3)9-{L;*3rmYM_!ymzwB5H}oaR_U7}O2i|@O9#6lb=bXDSUcq%=CmeqC5p1rwR*0{*L)+XIOGpbg zSi&R5$E6Hh-}t>R;}Z46ClLo2KzEOO3yH;09f}yi=Tzy`!3Jx3qB( z5dkIi4nb)uO}Z!$8%@Mup$kzEX#z?O5E4Xs6%Y^*B7&k+=}L=qkS1MvFA9MKH3U-p z?sv|dnRCv(znNJxYi9k{`o2G0hQRaWd7j+&-q*hNwf8>CHh0w9Q_i5U+r^`S>&Ha5 zR4%X6E>Bk{1>em;<0A7dm5HJZ$hNP@^^344TMb7SMY^)^b?Q@xkTZg1&+~NcrJhf} zJ7L8udRki*B}cJ2MU|yhfiDl1aMtuIU3x@@AXCBeIeE(Nte(d}V&h6yH#7(1lk*&U zoBkPij>HI@t7q8Q98beJN5%A0GbV4o2m16&yPYHRi7j!5yt=I1Es}@7T@)97=lmX& z&UO(unIlijqMmeZSE@!t*FAciURdmPLFDvr2A|#nowrQCg#RRMbW}l!u8W(OsXMji zgZn2AI&=Lm`GLY+3=ywHc~fi_gd>yEX~XA5v;RhB0py>5k!d}J5w3Xdv7yjl;9?)< zr(7L{i9{g6pERgbPN0lp+jrAymTrCV*i<8Xh+Ud?%)Z{rng=G#9u4+eBd zD{ZDP*t*VH<0{6rue#@3-59qSxm;6hy3CR=D}qt>?zWJ&$vwz@_|V#>I%d%`0!x4o zu##hM4OSn$Pq{kyE8cF{urjLp*Gxlty1z#G#e!`$qKY8RY@C6JJxN#vDiP+ZhpRde;C*Vs6>WZj+Q0oHDz%LgCtGZWJn%bwtzJj2e8 zx8brTck@|IWGmoHaxaA2?wr+cGB&~S8N zbYG_DSJ(oChzQ^E4ZhS{s}MkX{%TAN^|3ajC`+(H1G~7Eqialy%39O{<~)?@1^Ro| zWL~yYbU$!t^yY;hxXOdGjuCT`12VS*9F3;EKh(Nz(Um!|1Pk2b{xw(Z0lT-dAx2Ny z?m$Wnsq0KXQaVdBB*6iY$B#q1d99tT7q1t6n* zzh_7Y{RV|7LT@{Vp~((8GyN)U@}|ATId30D_rlmcbdR~!B)isDPU{t{?_cJS%reDc zrH`8*t0^q3tY^08yT+t!2Gh4#N~iKc=sYLsO6cAiT^@SBzzuTY^0zhfAF#@VB2tOG z4g0_efgL6&*0a~N=>*eY@c@<26ESG9$g2tEs4}`2Hr+a3|NOotv!VR^9%TboEkTCh z5)0Y2dlHX-8f?C%z%i{RWD&bi$~9e10G`51^9LLB@?qQY@q{BqXC)WnOpc#9{F_0g z!6WQF<5W*m-yaJeG~Fu;#iao-*=7z0<49G}gHU#uGc;;WSXXrpdF3+s@qO{tsa91x z6~$MT9p4wvWg$tOm3`em1h+h%Yco7R_aUkU+OoFe=}NS8jLUN$Jgl?sYDvHXWk&Z< zb;VfKr~257rQ7LWwO5+EFMe;f=I_nX0iI2Uyg_;kbei`QCvX&zh}8b% zXm!i$uGN+26(YOEw+B|P+bxG5#wa>G z&6_{4JRR2X;{;P7tq$gj5U2O)9w+NT!*Xjs3~O7J!re+Qj=2Z;OJ_Hv1tkxfec9_x zG333oQbW9L5bc4PFU;)1E<(afs7x;{7uKo?mxn}33_deFiwH`O?RE=2E%ZHv;Lp}Ju6`G~62re}p}wKWMg$&raQLL~#MR%-)I zZX@b*lc0%DVmmYrtw`3QNFoIc#xV%-hNhW17D< zbsRguu*?+lg!BwR_xsRT@uLJKygwuo1z&)Q&6Z|3EGBYv5UO8Ksl5DQ+Q}fH7Ip6u zTXuM+W^f!xw@y+P3u4f$=zcp@5P+3cV%(k0Ny*m16_RQqZyG`m%|3os+b!vk)PEFx zkv`{5|LR5dT$rK{jx{mV4vu&57r;FaXZ`R~I^x;(20wu+Q}UnLt7V+TUB%7kVRsy{ zJeZB)Yk!0_f zamdH~lA64bX#TrX72(YTICN(SWWr)Wf(c4AaGonE_9Y60^IiaJ08Pw@T&5U=ET}BS zlWT`R4U|nIx=dLb>0`JmTpKR3Nt*!Mq!8E*-jAZCs26xl+;xjPH_!S$JGOgmy|}n9 zY8mZSSgt&|9A0)DH;$Pv0O$NAr^Jga9B;u2qI9H3IOo>sqTwagC-Sme_(QUS%tZtf zUqq)`topJErBA@z5+{s1aDojt7a-tv4pPk^Pw2A9BUdsVXO{09pUVm`(!JUy^;#nh zje2)Ibw=#)9g8&xFM1SH>%WO}V2Q@LU?XP5iL#-`K1Ph~+7jBkViuLOYUC<1vM<={ z&yWat%B+pXM;L-}6f2Z9(Z9KD0^5$`M@b&ksH4X_Ip{P9hbpu^GJ53i$(~;%g10Y{ zgQR}m5;~Yrk7cDRl@?J{$%v)&w)%QEu15=U2rf4Z<=li>g|SzQewTYV^RkPQ0~u57 zSSUzjmOim;lVu4Zg!J>Q`esdvef8Z>)m?7Y#?EfSgy+tVrX4SqGe(f2t(2|`G0AKfC$@&(J(GLIuiyyD6rn!luSduZi@KSlIkBh?j)KN!)$c*o9>@|3_);wCr~Qv zlH36~NWrk`dFo~?;sf1uykx7~dfv&;r}e5#7S?g8N)0iKuGEZYQw>G|&NZF z@IS7UjeTa=!;mh}@&TNk%$jdZZ2Rya{pv_=U6%2fyn{UuI`KD)g+2JhBbsC+TJ$0n zQk8rwk?sZG4%yPo|C+@ZXif0qQ@Ve59Wom;B1`#ttRC!LYM>etltb! zx1X@jb=Ip@b7Tr4mu@!nr+QLmV*n0+rmVxBms;0>qyGB(AGC;nsSAcdVIBbrR40lj zy%)p&3qJd;W-?}jXX?z%ky*!0j9l)X<>`u37wG(wIM{pNJwR_UOHvG4w&M|%+jvd& zs$^$7-tqQ`kJ=|2mqG@Pwww^_X{ogdfSzV*L{~f4^`|WA93Mb@@mRnOR|`shtg5Sh zBz5!BsR#poQNBAD4w|xjf)Z{4S+2|e+@|AV2F*Rl~gG6&%L8-G3evp>w-%X(mk|$q7^o`@;wNKOiX{hxGcWsD66yoh2<$qf|l4|M!AXNAV3q) zI;b1O;07MD|21Km=!K2t+Un|>1ZK-EkDNuhh`RcZomlxezGt{J!9uq5`Ld`c1vJP{ zSLdWqPEier0Inr8FfLI}DpF6r`yMwmJ7KFxdtX_3?$j!O^cNl>r-WNvTS;zP@UI=D zVN+TPod@oCs!x~A=GYH_2XDN{sx?P=WmvZ0L;EBxlJd`j@!( ze6v=&+g5qe>u_qASJSV((Ytq^`qw09!*b__86T<*D%!63 zSRd!Xu5B25BK#{S%Zn8z$A(^aT_uVu^;~2dhHxG7#AOk~z0m~uLbX~LA5`$2VcT@s ztr;gY<<_tVr5Tv1^!R#;#BrN@frP+_0iAWN;H~_eI9)A7ONv~A1Vo)R10V(lCeO8D zstlSb8FUH#a`IG*@QX=~rtADtImq+QTL)yjUVp(q{D4pveam(W@)*r;O&@{^0!i2Q zqy-qZjf>LE;TkfC&caV_R`dmVzqYy*5ctmRjZFsE-Q?w*dq$EwOJR?@Z==KL9dnht z&55CtkZ9lS&?b!$l>M@*zn`}$S-73XSy$cKj(Z`J z>cy~^)>uSm;{yV)0g?w<+Nqd&ma}~k!M$Jg#ihZb0zmLLwtO6Y^&;-Gd?~#!k|0C68^2zah*XLeBoYH zPjV9AKhUQMEbTo%ijf5iIXIcfNAEr=s82)B#Pu#iR4xOlf3Jk9#EppumFPzR*(E+` zkfwN2Pmv7-+7NSI;%)b?*#F?un)Nn+ zArde`+L%Qc8%nof#A6f8`A|ACqmW5U7&Cce6X}?yCGt?YQq4rNuKY+8m)lPYDTc81 zZgD#V%8gRUjfP$yZICXRn3R&JN`~t^dz%!Zb?$5Ur{%SnJqtRk%i>Wv3tC)*}bK2;y{RTElU+5+&)Zt;9>8cJn&x<`Q&Sk#o09 zAUDd1qOZ1g^*%b%roVjFh-03SIeyvPa7Ktdz(dE0&epx?$qhv04#U+jcGvMq^(AEO zweV6kN`}IHny$J({}il>KUiau~fbtnMl&Lp=16o)-VAVS6liIE|)-+;DMXx#Udjyj+jZ2 zMb9{GC1TOyKu0jbfTFOKU3_6anAOolW@v2IaLxE+KIO8T*Jf-*K<1H3eoD_{#A~yZ zmzXYgpwuigg#BbLab?(JA{CNNz*bp0hrHPgW7mGrbchf>Is#-n&k+-9Np4CHcm?yS zeLB0ARnA6UG(PFxB?NE9h+*!|7?bXiuNPB&XxJt>@@i+hE=MhWw9W*6Jz;T-E*SNr z)j(94p+%*y=7PM3fP>Px$Z|S3tpHsW*-Cm#P}+0{1USnlE@Yxny5(4d!4Y=#-Q;(^ zN-6F*X0}deL+1&r>`(HA@%8<{XbgOvGY1HiwzMtk24wpuH}J35E&L&O3pZA(ddAtq zL)}1X{H(Q+9vc%FraUzZM)1Z2buApcT>B_3X6cUBG3^oi zmnn}Qr;OnwF!qoL3=htAJA781fJ4 zl#HwbKh*a>*N&vh%cQ*Caz=q_v$`{g=frPT(ST0 z&`?x7_xv8qs#2Th*UBZt<{)9$jvPd&=us4i*T;xhBoS?>EDM!e=Me z7vhpLvms}&9GGTxbx)CRU~mj5MrmA%w^-z(qJw+)_1`|7u)M7cPiIIIGL{NBtPx-o z;&=RrgA<7p7}%S@e+!^bp}V1cR6SUnG}%|m|Eyvq(yB~qcp_Ef%9d4zpAq}p`}Z&Q z=Vn~Qml4WH7UW@K(L!gW?g^?nEf0PC!aH*9)ynas>EXW2gPRHtxNzA7=>$#(`>1*D zx3Mqg9a5GN@3+GQKEVj4umroK2rkzqIePb(yjph$n>va|p3jDQv}YCkapPcgVgciM zpy~f3Ok<;E$Ws-FWed1yi;h_tT-G8c!NVR|y4BkGN?~-Sa>-=R`*7T}*b`Y1fg#*= zI+WgJiez7a$LsPdwPA%e*q5Z)eB<@0#_wFdnq*X_JMa7$&s}Y@1dBEk(``V@z-*!r zv=hS{zjCbXLuGUPEtler>p!v;7OEJ@hA@10X4+9&L~P2mFLx$*R3Rp*D3`U z_##v}hMPt657wBinPA`Zr=?{E=WFnDcDlQ}3tu{-e8O-k;WXcMzVmE_3=E7RCl0j# z2~W)Y@9ClcGL!N@sfRv;R;MzP%NMt&D1Zs>7=Sn<+z5#9DhHP$SBzVA;^r{_$hEoS zMrn)JWD}n+-TmP^zw|ROhCvP}5T@oM$H5#C ztkksb*H_$A-D-Ldh0WOTRmPzg4nm^QX8@Ziu5CuS;Z~Ew`DH0dk&;q1jxXV5>?DJp$4#Q-jQM!ah22>9@Ug^2cA;XW z7b`cQ}kC=mM^H8DH$W7(8+ zd0n8qcL$ejHT8))HDyQNf2etUv1Qy?zDLH4fjQsOXvtgEG3!@y3iMFU zh2x1fbhf+5GDkOpL315y+1+LX$Jws)-hpa&%fkK!aS1^|{i zfdg$YF1nQ6CGR4mH@POd{UX7uXB2w!Jz7;zZG~~iPe4yPQCve{A}B`!4{3_9-I;h8 zJsv0?or~P))D*TIO{iV?Q1+^PxXL%_Uc_OAdml5I)Lc9jZ5zfM&UmTBeb`?k0cM1G z2{EZk3aBS&wl*KE`<3&~smOYA`pSFh@rke~A}iu>+>INbEyJZB8ulAZshP5LBPw=d zaIV2#M~w|>ujpbfIftr-O62bjuD%~B*`E9r;`7{4qVD5Fxw(ppz_|p~1Z}{`Z4!yQ z3;vx`1Cv>#%dyu+t0CMr1}=+pEUqfjRl-SEG5PIM$$Fegp(nL`e4na5kw_ZCU0nwY z4k6$Q0P%Iqq+bUl;tTTl)cm!`M~_&?P{y=kMRmw2fg{~6%Z8Ol+nf&Pp$}vvv3t&(d^c+|!ObAjO znSBu(HddSTZFj%;bYH>DRo0kuQ(DQ3TrywU^zqQNbDA;M@upfAIn^pFI%-&zcFPedq;QPA%^w<*jg!VMv5+a z49kRZiy$|@`8J7YQ-Cd+HD$Ojxm(V(-c$3-Sv)jiJv3`|H_gz!&0rJA*zMVh*`Ht$ zbt4h^mI zZof)n81}Fvz$S)Ixe>gt5q3Kh*(Q+&HiU1HdSIebL&Pr+pB@ooEc45QpZnbY!7utmrb>X|CyZmSYgtXrd`VZ-RAe6iB@ ztaQLieT3Urr>FT}ud0M8cUB!JrO?i!z>W#cWniFXQ&kw&VGGCK|7KWujm8e17flRN zhX{OcI{d{K7A1W9tZZ~?)rL!Tum-C+vP3E8^!;!tgCtuA)Z06ohlLJ~mI;z=t`G;p zd~wWf?^eIn(X)Nu*cR-*Y>3W%>OJQs{0*$IJ}g<*AkG(Y6nPW)*9xaLft>~y0_N7o zsvRKS=^Tsqmostq=Ge}7HFJz9F-<0t^2sc5${#Q_xFv)z8A3{+y;!bEUxc>SDwk&Y zpSqkGpW%JHBVJM}fO*A=YdOw{H;$=@LFAh!NW|rE5DVIIN2uPzzGCo}SvA7f(;9hs z+RC6h#!}Np=c1NZ*aTc1B`6ccr5?VSm(|bZ}dumR~Jbz|r`}u==ey}n~2`hlKP~wDt3xcCb+6DWS zer#BJ)cX4Xp3^qKe$Dh_j?(Ouk-SNr7GIOanSPGL62Xu47|_~1gaXnqEgRQ;{H)ETYZwn%;UROm{`g>H$UT`DhPzN{TH$wcxQ zY5U{tjNW?6zTOt{|92#5(v41f;&CDcx$eyzIcQ=KYlU z>;uC$KE5Z4l@_@B>#We)cRrT~DBsqO6){lj70SK(fMNaxbZGJf(+?cUge*Y3xq!th zP%fj+6Pu!GSuc?rwh2GZ*HdhZe=|II>```4VWn9uxqatqB=;-vM{%JnsuX)Fg!Zx; zIw`UciI)Q+_c8I)BiaIv-VVC)K|x0oj5BJCngZ_VUsM$3lsdwea99@lX2g^wg~~nN zBu`FX7{eA(JqV)(VJL)r`tct|6?F+ahp)@{hNoG+$rfz5V7buG+T3}CnhsWc2@=r; zrr*^*(bc4$N$(nMu*v_9<@jZ2|C_yyIK%U+obGGO5Y>dvTO@p4~mx_ zpaC_)iq~a9aS=RQdd$x6bEF^9^n}i&?ceV4mmnoCEZ^O9n^*_-@f^+-Gf}iSI@ewX z0ZFq8T3;NDtKpoh5ABk{$l;iAyK=4TBK2n_d=2g$*SG!5SsX=_LFKj6b-*n>qdpw; zK=Zjk*?b1V9nAF0M;mTFD(ZYhatqM4vi{O3dA9PTgtoD2TynS#2d;$Il%)$Q40FN> zAg4%YK$_U857wqie$rOqtdaI;<7{ta--yx!$A~4=j@SxnH`ZC+^6lM^SqHIFwCpAk z`j@8Dv=>0QrG_4)AFUwhCpj&gL$EnpXUEfO@^qHHY~b$dZPCoV-xCjgl`?HP-5%B4 z+_^r=%SfIe=z?jhY^;=%$cy9i@~}fb+fkW{u?oG`GSv>nms~^)ywCMtEtBL~iA<`A zc6j`0KAAzSNd*)(x|98vI>TUYjgZS<8hn?s;uXJl+7PBK1}(o$p6#l*bdbN|b{}J= zT5Y=Gtef%+Eg}8e=x&WK?bS@!-| zV8ni@>1H?+s*s4MO}YEWH{B%{cvFJVbHY@uMkQqw-93FmHg5S#U+lJpMT(Q=thwmuBN@DN13AFeki1!!?H;$?;)}+Qh2{ z9dkM_H95)#2C8l|(g$2=H(rJ4UZ6#RdzmpH-66|DL$&pS59KW?*xdLquKo`1RhOGKN(|Lc}BIB@0K9Qe(u+1@DcA`KOfs4y|<8aC{63S)YQ{b)71Wz zRt5te!nt|>5P*3jNf-_~)JEIyp(@b#A@8Z_gfLhHP;RqF%(<%=Syk*NZJI^4F z`@7x;ps5S^`A{0zn@|LS$Cl5#4nYmZd@}L5^-q25{;DT4Kh-!#4Kk*Gd&zO_Pn2np zekfUX?GqvvdQge3WJ0`jk=_pHMP~ROm7%nFwO7B;#;t9WW%|e? zM9DK#mgUG0nA5=I@VqDf;hdn_%sFFncmefF?XW_Fdy&Y82N4Ow)8{8+t!;YbRl1LU zh@w4bPKvu=_V}UqcUaB#<_r9Rh-R??lut*OFTaB$-(dr^9t9tRm`i48~ zpDQH01(Qz-vY0byuK(g?+=DNQ`IG3he6$F%a-lOySI`A}-#PJ2SvM~FBCv(-2n;;gpAj6B0N>@g71>I&P zN2-Hx0-f({GL|km-WGRtM37nFhJ_exI15LMRWw`r62ryMX6lvdcU05JS z&G>6IhQsa5gNeCI6ER#831)ki?>@h`Vz7Sk6X+$=By0yvUR#Z1lFa{}P;g z7G6>l@BT2}v^DxIrkpM0*ZQEG8xs6fN_h$6(d^ z*?j244O%WFsXeTe2IwZ5CDJdt#oHXw`WZ;=&FCfr~tK98?hXMrK7>O66 zsIEh&=;Fjuclt4;tH_kGSlfH0fWr+rhcgWZGIMPnW*}tm^(79w0#LX?XG_iRS%gHv zD(%AgmiHfIrpIn6@b64{Vjm1oyF^JRK6IQDa_@Pnf4<*skb09CL}#;E$b*IWls%z~ z5jBbn3D(G#9@7Ldjg|AKY86~`+U^S-ZdLO#EUK3{dE4R@eF9TC(1wY}ap@jHrhj@r zY3w);<-@qS$*j(w?{*`_3aJV|MRiPhP$8byl+_SjaauISahnUp_=nUNK{U7-dz+k2 zWCPP(E!r#wsT*9<+3snV;#cma86=IIs?_+x_Nsi(9u|(RuHEz|t}SXN=rWPTdln-@ znxwyDrUW#O6BU$-@2m8kj`H-qcVb-SRYm@1Vwgg8gdFKOc;*jjxw?nw6WHpt)*y@k z8P{3|f8y)O=9-on8G&Nw&*j~*`z3G_FIyk;QN(fx!C^HwS;f`ZR3!4!rr?7cCUZ#o*{Vl=+3cR%_Nfz00M*`~ zJ4}xJ1giwK+qi?sn&D01vG9cwRrrVks%v!zv<(`Rf~&|N=iCmc#C;CpmRl)dpGUMC z!^kIgqndPXuV-nq1}~iW*%NGm_bUjVY;}%+RYu2m?Y(;Rp-mv6A&wpeBGLa8bF=WDAIW3c+^Rmb2TsvEN48NcJXV!i#3GuZB z&*sO$6e%)d-k`liwa1CznD)5Ta3@7Sb<@!sY})mdWzaRsdBZDb4ihY zPRF`02usiu{(xJ*8QixYWB7EHs8`5Li;&1bSyFXmD9VObP})bTxACm74laPF^iDle zGg0a}82RAB)XKMH)%{}tO7G18{S*EVoI7vvgf8(7!>0z{G%oROul(-E1)R-xe-+Zf zEJdU8YEjw^jdF8R*`V-0cjx#M$Hl(yNewRh@|)q*H@D1T%n}|Qxo2Vgr;S4Rlt316 z2>z08|Izh32=f2>`cHbD#4s%CN&;8q*^Xs)#X?Y+H|<5v)@`~bqg5Y;nvW#J9ln>W z$v8L?Vb1U*3Gti+BV5}~M6k^ULrLDWSLy>t$mT9m$g1FrEE(>X3*@ioW!!brG0x{w z)?U*d-v|Z|VTr&*XWd=EMPN9`mk{mS0^hNG^kW@n_-d0or$hVo1g#`vjGU5I;!x!c z$*C7Yqv9CFuvA`e`qj!sPg9w67JJvOo);ylG4A0A{-hgZ+&d~G`4NCx6Fp1f?+9Ozku8}zW0kMeKQs-k zG$aoxE6h}=CRX%m&ZgUARjz)NSc6@s_d?6fBSB7Hc%WTL0GVe>jwVXB9VW~oQ*N2Z zC$qAtb{;X2U*lq39DohOJ4Mj94he`YQaYjZn)nIVF z-&oMkY+jYQn<-{{ooNjSo6dn)HHczD=0wVMy6802qy$%98I{lKX&5d$kjmXQBgpxX z`2JL@n4p|e`#9|VF5a=|n+ajJ4OY!x88Dw=Pf>4kd%ZcbrC>No&}shYVt8-Q$mPXp zSuajQSfQFJOA-}AmYj!9Y%k1W2?Gm#c{VP7daskMo*Q}ldn;;B#YQuTtfVlVVKh5$ z2GT*=S@Q;)wScpQFUhv!ViANC%mdIfWoTslI(>k`0t|S~fValLIXw5?Zw4Z<);}FO z)35bue=LT90G~7<1rXqPEke`wLSp=Ekh2}Ktk|=}kM^o#pP@%|Fp}A3+27!X?ma(- zcgG?-oA_w4IM=Koq&5VQgig0{1knq3GsofO{B_lRZyB#1psl1K`JTFWC0{)f-!T3S z&&x=NY$^Mipal3CXc_t>>Ljs!_3?bXwTp)@jG^`3(fGDLH+e4m`P+&k5mu=6kruL~ z^O?9)@dmP^Wy4 z@u)`>W^%e7`Ed!#gq8|=Mj==|sRoj_zwciLsveIa#jWg~40D-ObNNc1s{CA|0_kZ^b3*Hp~lHVK{ln+|^M>@V&uo%vPd17aQ?pe-yfNyoD+DsfOv2$)z;IuxZ( z$iF{lLOhfcabs+1qV2}3Zgy(i&VzeN52YS9H#0oU5vIj9okI5Nq~jfkvDe8NFFW0J z8fzoniFuq{+gF@2ez3(QAJ`&_Ft+K4}XVp zl~FwxzQtFppABAlT4l>GXt%Ip*!3af-j7K~`HLMY*&ImB<`W9g;1L&vqva};yrk{%`!%Lnq-!Ekee z_Od~+i_`0Ti`}u#?RM$m&-Ypr4kx{Vo84^>t}I0NVcC4)6EuJTB8PLJ%wh^^9~R<& zGhhUx!^)@S!#F+oeR;MWB|dAOmUtTc9l(iKk@!jXDD91}?YU2;^i}rj z`T3dQB`;+k@b7f1KKFa~$vK-3e(VrK*(D%$zas)=M7a@m+qa*~sknDb&?5n4kU@_jD&Alzrt9J&wXtorXb6!d z%=bd!`eb|Yf%Rr(_77?@hW@CoxO~IcR*c<3EYB)wX}a<=^!`~b^06gcd|*M0ucx4H zmp0tDK+W5Q#a zbbip?+92X{YwPUQ6GP?x?nQ+=y=}>GnWmgSno&6^CCsr>Jz>#J(x|{Ow2aG*Z^PCy z@t8MRhIt>74YNI%vNm2+oKksQ`E)HQ4qEB_Z(Cmd;Z&=t%E)`LE$la|>esI^o!y{{ z2~-y|tb@TW4F5cH=0BG&{u2*<;Qxp3{kIFT{#uarKk>i7&%cUp$JO5ec6X8n*(pu? zQ%&tD1o(YE_5!utYjkApUtW*=f3&dY{U3SXJS`RYAz9imO-|!q7SdnZ1VjIMw9J2R z@w{)iUIIBvcCsL{CiV;4#`kTfzwo4JyUR?I`lrqD53#&py5w^*j{fN^mY!l{vv8-t znlr7htT(3Qtwufc1WJd1!;26LT3v`71B(X()oXIKH;(4Ju9p`pI!MU7g)p6Dl8$DQ zN_P7IG7!v^E0{sE-wcCuRFgo&CI(bA30wr#=DWWc_RSQ6H4#=>PNRgclV1Z*hsNC- z+Lf&EvxO+JKMucg`klts5Qaxr=pW7kCA`GB!1qt#_5p5=E~~0;^fVyMCIu}*IPIps z)!olNn6BxcenbBBg@aeDmXp4Qo0+moy|)509cF(pmTrle|A0vvq-7b`0}>6pht&XRC6x9Wwq6JZJ#N!w63M2B zssb7xf+hy)jmD=(uG6dRLH#C_tO#9(PE^(7sI0#kG6)0I6H1de=`m&Wgx?H{E|5=3 zlednPwV#LIL2WwG_sTx5=h2*j&`%ylxDD$<{L6vFIY6-RwCieosV_#GA5mH$~apYiUmAyswf6 zC)|r~Vq%pPU%ZZtO#!zP%D03SL(7;D3O@0W6Fy62(if4N#c5Zcx9vo@_a9Ou{-D*Z^*mCM*^$+T^Jf$8dYtSTu=rym@Mz${!q4`F|rVSf69Je3xa)T4 z5@iU!YvHaBA3aNUOFpOR5!KOji1YQymK!EAbQu?n|%C6k2yaT1iO} zIkWdPhhihCL$uXH&TWD%BIVG6{j~(nDBhUdoIqqo&WH;7j^5NLIseu2>K$dba`aGG2zpw&{&`6DytOTl=-tnPerNzY6qhP zPqJ$J-|Q#Pf8B>?G5_8+oU%seIu=e`di!lyp}o3=^>`|WS!%=umT9xku(3GAPAkyF zwNjt_w-?F}|3&dg%4I71;BoTfx5ynGzoE%3!TS}dwxeS=kf%06Sq0CWYSm&;gD+-g{-?!&Jj$YT}+v&{zm-e6kQG3vT z{=JI}hWHB%vsWLqIQJU3xN+*ialO9;_M@m*F{%2q6i(;$Y=P|a`jk;wtV!=ZPm+u` zt`xxREJOmVzf(k0&E+yEnj!(Ss}QPMSuSg3yjd7FQU6}HSoh6D{wzn30`UyExFh;2O#d6p}ZxkbG&`KW(A6h&8WYXZznAQUA@L^OL4}&E+Z= zO!e1-nf1p6@$@|zgeDd(cne3b!r$9EIg zdXHuGm@5}2-F>>WdhSEZN71>&CJiKH$sa#MfZ3AWy%mdcC!Oo2Sqt~LFSz@vs$}rb z_1y~Km*7>4d85)-ZCUZb6f*JBi}7_nqE7c&72{qafqgMCgf70Jt6NJpu&SQc3 zX_Hg(3f`PgU)A?oDhA$rjDQ2I7EiwLo8e*tK++)_h~PH(3GhV5%&uYlsHGZY^KlDp z?E~$U!(g4eHE!3R#w@%>AI5wchR~U&0soY_S44V4t|zQ@&OxeZ&=%p|!1(2}y_!ng zdMaFOQ`5&DbPFd4jW}qnHdO*_DnfWd4;PaIHg&8C0h-o{B6)!0^Xou5hjtd_TH<>%t?k#-?msF%+-Dc~74YN3v=xoL&LRlMB2_OT(QNJiyqO@6}{c*ur);_*5L8Y8e zTfA+&0MmMf%K4ii_YIWF@)5AQ>TOgmF!7+rmV9%e5n)Lf%MJ+gb!l>02~q8u`s$eI z{n+juSaF&QEHt*W7IdbPpuMba-H#TNry8b*8eb>`)lZouh^ll133`2)>;bj6bYYA6 zNZQfUK!>XXe4tR?KfY12{WtaltmeOcz#lxHl8Sa)sqy%PZD=R87y1v@FYzCKuEj0r zQzgLd7+e8X%s20EZJ*L#P8Irfi%7-vg0Ji!)*ATee|X0&=x>jQ{oScw?Lk~|C|H-m z|1}r3XS1Z#Ho%0s1T1_BN~G{j{sZ+DO%cg7m{R|T$_cD8kJi^2RUnBh`r*Bl{ul+F zABe)TLBiF7Ois+YwGL3^?P01t;4kaN{I<^QXVN4~b0qe0BM&iVIOzfpH^h>EW7YHk z(*VAZVr;kJUc*Mc47wXQx-=*g43<1QaZqx^QitwI9OX!$FKyEeO7cjTDRY%5uMYPX zRn`+(_si;N|q$gc?kdPJ1J?%9~dag$&vt64dPS!|(= zP8-_$yhN`X`|@7awOQ7#f$p4){YwOuMG?f49B5tLQ-dRCeY^~}khd-$Ob%ucDhmfa zNk-y-3JcJ~mk2|0-HSu`>Y7Gdhg(&(&pPgFa%rYK80PgXCYziv|vfIxV2(AGw}dPL!%mqe`-xA76@D-E$N*^GS$8HO8GtJQhSKy4&;? z4aB}su_r5f@DCLY+xleicJy8FY~j@rw@%;Yt}x&(IuaE%ANSDB>F;6hFjb6Tv!J&f z=40H0WBZmopquR?U!h)?=8t?<$upho<+i!54IwEgmAT;~I;1 z%ybz$*JfjWWB6VmA}C<$QjO?z5f&ryDn^bw^goF`{~wL^XA?dCi|_rrG}>RLp8l6{ z`9E>6AK)>VovSDW;KIcK@WLIKJnIXY^kGo@T*+?YoMZhoo~i)5xJd z&+yD}=W8}#+LoSW?V+Sq1SmwKKDA}1*UtfZ^~6 zxf&GoG2624^Gg4alERdWy&=crh+t(~3{^pC>Kr}nC=-4EH^X*nu$_BygSkejOlsim ziWIlqBx}v!L?!mPTk9P!a^>>VTLx;XkE+5)?^1O04&2t~@cYo!XOC&&T999(oSLGO z`F4PE^zY6HB~;-aZ0~cbK`0x)8Jf(R=_R9}$Iee2;oh}G{9&;3aRmP0*Fi6x>k=}3 zf+%M^%$nrtbhW^ z8+Kz7P&Vc=od=hRqpTRBPtYgY?jTvtA0%eaz;v!8{_-fJf=~en(T_tXx#&iidHGz* z2}~D!5k`x|kX(v3t@k!aNV4N1EV7QHBxs2xk>b`S&_P-iv^;z9^uyQbEAm#)v-95` zWVj}`ZrvIEh<9Vv%=LQe(yO|O$&)TW^c=rDJ57um#Zo!T5s5 zamNBgEH$;%WY7h@gB?SYt}i)rldez35P32&b?`5g(!T+Dg<}}v8Vk)EzI>_=$vu<3 z&dO9GA+f{Z_M>M>bF-WX`U{iSFagAK?G`SCin0Dl1*XzZn$y4xLLoLa^i3o320$plYHY@Kg+QQp)S%!YjsG1EAn|%zLia#FobxgmSM@ymn ziRUdHUZ#<97p7nThrRaLRip?avC%|~fDn2_MFa$tA|QdK zAfQqrprWWm1*8+{J(1p2dY6vUA)$sezR5mk@1ySh?6c3a&-Y&MkN1byV7gc8wX+Y>>IWSU$;r6YTI`y;8lf}Tdyr2$ zJg8daXlvpE&JUi0D(CEGsjw0!b=-;4=N0CT-s)XV$lEn8(g1&czqQ~o--^zz3!%-& zFQlJ%%^5FM0olP<_7Z?Ii05P^KACR&(Wza?gqErBVeGds44Nc91_r`CVZ;D*I>ghE zSqv@3c4VSLnGMjKrrH5884p3zpX`$OjOYjQ8iszcO`NoMjJT$OKdJsv)`Sy_u*0oL zK&)U0iCRBZ|1#RU18h{bTse}5($`Z?5Fx2N)N?J%tD5WXzIwqlkFO{260b|K_VG*W zc8}bQF=y_Intpi%YQEj1+95U z<@m=52VWpxP7);A6kjN{#6@UV<}6fcw-wjC-KSv~2;*Um<)@t?0HF_vr`bY{cV9#O zXvSRZ@1E@sj^hjw)B~*SU51u+WUj&*Ki$UOg+{bV%M8C%;=&nJjjwVJBiUEU?mR`H zvX8$hTS(F&F(GD-_xyQ{msbRe0{7S+IbFNQWs}3SqsX~nt>)D1XMEYWjLGIA$_5#G zjw1`!=X|o>revozV=4pSsb@dM3Z}5#CWz{dW_Z{>#6Y8z+*Nh^Oc&@&DzCOaJqj zr~iow=P&&{O-72Tj-(|}jU9h$y1k<+3Em3gpEGs;p4E>2m>B;hz-U9nIT%Yp0*ak{ ztWPd5MkYc@a{P_`+0-L@g6$4!IGn^~C-M7qqrDDCNm~>NYb5)&Lz@=rS5l3sGt0G? z0v*gRkun5@QY$^SEwivDin@Z3oz#hDB@#g_JRlAd$sl8riM&Ub@gX6!iG-#pStr|k zg5A~VZWU3NJPv>9I-RmamQECa$nH^;nRirend?B*UeVEdIX2Sz5La2<%GVU{B_HQo>H?2jCf~rFjfTwDLvZ^3e8gT$82HbONj4+d# z0B{%_;}x9LiC~3B-~IE_$L^<_+e^~&=i_l?(FMH4SwT4ZEo|xtZhi=&@B^K%@$0Sb z80Z)9bf~5Z`tBvgPxN(ZSIK|i_8hTr($ZW9(Ed`P%_4jJZYNWEmUP07nq%)9D@};x z<#nvD+)28>?#YeV*MrBYY_$FPt{*oXG?{p2@0g!rM(c`Og&AUmJj_Dub#L*I0YhUN z@Nn<|HOTM-?wO9$MV5zgo=6YU1hjAWw3Ggs}(?!ANOY25=Zv} zP=ZCv3R{*D$fFE@=A?eZ)fh#S#EOnKkvXRi(NLC@t)@sn+y?14WK?CEv6xM+%Q@U2 z%}cA^J6V;{2RyEX6uQ7TDWwcV6J#n(IZE(}Kxj8FS ztoS8a?XW{-as{GULs4|D(WR?^w_qAIgbpr7xKWw8j#`a@>yO-nZU&?11)WAo^}1z5NGxzjoqqGIlw0J0~D${bhJAMDqO8AGJ=h?{NlJA|D?&9MCnNm3srhbqzO%S65X+}3xxK@Q* zS&c{KnR#1P`P&DFJ4)-y)!!`$97^Vnc+Iu~Uj7M+Q8N7yBY|+FvwCo{SD+l9INo$E z;*+gdPJCtDE;~M@)S8T1{vCOTB4YVobGA@_g2cStf6mjDNaGmHAj1lehO+wU;aE1P1Iui^y>#XW;64J&d?fvp3}%Zmv5 z2H>9o*YAgKp|&u$<2C_Lf%Po-q9YI`8Zo$q4D5f@5wXu54fO zY#2p*(7C?$iZ5kQ6qC^!mzI}})g3l+S@y`E+%jJ9n9wwHgVklDj|g`La;M(b)bN@& z;h-ATc=v`Kr5oH7zY&Feg*^F}2jLID`D{goISB2aS?a##82iv9A@@O?Cdz1=iUpYY zxQFEMgz+4op2K;U$rm$sO8S9N>$+znD>p3l1RWMGoR96iF#O*0z<}}5P4NP{Pm&at z_1;D6X65Urm>MrBM&GuYJePZ{@1X=f=ICcc73g!%D=*>6S%vMg3O;H%B)XzoD;=_B z3%`W)$K&FSFr7WyI_`m8y+{{Yg~deUnCqb>_s_nqH%@sEJKyVe9FlI&GaHU;%m*D2 zEv8A^68zXQ1ef*`fC>X!;(zz`uUm~qBDY3azrS#kFaL~7(#M4e9ntBoFY`8rI}EbN zo9!fe+#0$#8 zM%bvj_&IvbizM@2uibj&cQdZ$D%j&=sRCisd@v8_AGiTQX5Xp>w z9(enod0s5K;DloFlr8BG3wq`L$(Q|0Huu*SrW77P?sE)8$8L?R;(yQ$^@pRc|4V;Hc^JoGUmZT z@H$vmTN!k)Ie)`HT^Sv6!qGH9H_Ar}I>|0KTCQtY*s{Cg%6zHg=xD&_%~dM+W6YX0 zTtxW|2n)AEbBf;im{8yy;!G0+7F;~63Iz?Tj?`9n)l%gs;$1vt7@&wFE`$1X8f*fh z>WN{#GQ!t_Gv`wPECGp;5&Lh&Hu1jgWXdTEX!|6;TC~A<-qn?T+AKMV0mY5^d8{|j z-u2_~?zqLZC&Zx)Z5FqPwp#{$q@fnBHypZjo$BcgZ-|#c@V2Lrm*GJK?0HEJa+wr;m<; z-rr{#UY?d@JwZlPz^O-2A?~<1K%y8hfC!9Mri&tWsAreXWlzvDp;ToDP!|$w*@1b~9sd6O97I3%Ng?CLDx0EaxkM1lfjJsEt5hL_y zdqTR@JaU*bAR8NoAnBJN21hHr-9T3eD0^b*LED)*Hm5#)H^UrTS++8_F|A9kj^I#Y zX=O24g>n0GdGZb_Pp^;+5JBD7&148^ZygLR&AQj|6zT0gEq_09bEfK}^ba;=>8_w4 zc}jyjcv-9Y=^gb=jK_!(aWb4)PNXTcEy?&^rAuT|2Ho+VU+AL5_gQ(CSCP5Fl_5_b z)yjS<8j8Gg_~oUN6q?8yhW5G-*iOs|;KR2qf6<6YUb#0>tZ}42N=N5iNgE-AMB>Y1 z+kwrB?6-M0`;oTqcNJo&pM=vBHNDZAcD$P+Ux$3y9rns2PUzfTHq+FTC)`IqWxop7 zyfxLQIxKoqH%MMX_i(J?q{3I*%t%M-wcUY->N$_lRAf}~6!A%o|H-MQ=r}dp1OdCj zI=#-KyaA`h*>iv$^}pctt;~~%XBkQFNSlJ?{Bj)kv$Lno+X#+t3BUa1i_#e1sLF(% zM}HR_Ks1{c5VRpqrY0UbTyt5?#*|?nQ5-ilGLz#yUQixbm7}?}tKO#R)}pF2U>;&> zj{rAzM;6l&ZS46&!H=&E#;pbLI`=rQ(~+y_MV>8eQtyCWn>OAn{!*vYSNr^cYmCD} z#|Pq^sHZox)EG?_lRS*sS8l_7AUPaIJa%a&7aJkG3!hzi&LZtv-lDCM1~;lECJ~J6 zU8|j0_YDmO4XJprqhsQ+AbBp(-XyiS0k!vJfh4&_uQAw9Q@6 z*wy08<%a20$Z}siofjL)@Ti9N_vL&Kb0$Y2eQ~mUb@Xwz36CkCh+jZfI zx{Z{(S;E+@GK(gIoRX6dB~s6@{Y98gA^X?CBq^_&LD&c;W;?w7hkx^1ja|lXI3di% z?fWXedjT6F0f}yNJ8SS3^i~JygbjAfr+4%$>!Hr6HS5nDI4Xrxnk42bmwghsfYZy) zZBsm*=Mp&4E>Zk|?d8ruo$%*AOLx4lxSGOAJ#cp77<)R@pW@8aP6s+@e;_yIVDnqa z;^>mDTd?&NU{vYyhap1A2Yl*BD}BF;hRvkrC=oEY2k(^owQ-I#$z%4?o^~3aRsap) z)`6(wIz|cD3#Ecpm~R?!WgnK}hz;yt*wlfTZOa4539A1Y_eB(ZDG+Fzw#67#mXvKCy<1bm z@%sIU3tNU^gUSZZQ}{6A)v;m!p}Z>dYusAgw`W>IH?^J5Lw$g;!q$BNCD&N>56xwl zZBK@-__X7RCEU|AdL-t?!B(d8PRnt{fRF3qfO+}sS zj`2A%l%jFL^(*l-emNJz30}DVkQ{YC|MDo%)FS#nU8DNBjp5zT(TsI+^xcP%DVLzp zW#$>|T`&SKSxo~}ww7Dbfe9S3NBne68+wSyktb5ug9L~5;&mjQ30P6}NeH^4)_vmG zGl%|{IC`ko4_9c6zShz^6p$|v;cPmqo(8Z9T>pxsI*^LML^3afi`{!3$WA!OYy5DX zGW$@1*;)rG`L{p=wLxtehrfuFcY)z*)cvy5Jei zd=OZ&QVT3zEA+!<+j1p0WN!m4YyjET@`+B|n!$;P9e^nI*d0*Q!49GdVuc_3!xe$@ z7CU_w&%6`G-1f}JoNE<^AkJOD?6##@j^%n}n0xk=MK=UpdNyeLM6FHutLY^S2kjKx zo|Z)mG)ozEgZPMVGXMKCqN}Y0d z5Fbboj;x3|@ak;L%5(r_|rXHwJ?BwpgsjHby6H+6dYZd40C8s1D-RN znj6FFcbs2E@xyLT$qxa1B5wwwY2*4kPA0Owz6d)A<5^fp{7SK47d*E=GD$KF?eIj_ zILg*L=6ZrvyjM$t7>|Hk$?UxPMj$br6oB0w|84CbRVbc#P~roCceCXo>IR5%2vnqs z(YB%K3^aw4&NYDeNgJ*mlOOdIZGL?S8{)f<@0~gX%`ZX&2omxRI4wVFF#z&cmpfBg z9B|7MJwOtqW4lYVoWyKn!nvQn&njPZ+u-2=iWuO%1zu99hrHpEKd&P3@g>n1r z-i*vV%jSj~Lq{6Dv$m_Kt!s_hXosrsh(0ztEk|xKBt4CHRZ!nTI{di6Zv|1226Mx zr)Ky!=Li(NPY}Mc%VkRRHt%L+2VXLd)X@*{$Wa1tWA6aLsYEqXk!8fdXr9NneWM0_ z_HDilTeo!NRoKz2%&dY%X&v>P1d#m@2byur5@dncIGOv3tVBf2Bo*Nd0&#^)_^k7M z^$he418g0;56PM7J%ONX>ZcpQfA>voXp)~NoEgvy6bDT*% zB+$>G^Z$Fx-{bm!{Fbv9@ZEU>grr-!*yM&w7I!i&yKBNnsF{IV7q4^PrlNn^%!{7E z1G8nb+~ae0g$)4bQ^CG8*=++ijFYxGP+~&$hSFtTaT=XYTdyo1<}WEX_YH(KKwJGq**?N+hUi9lhIvYE&Q$#-?h=CKR9!1&KvPp=S|-C|M^pYUa`;QOvIr$u92gJ`-ICDKxbOrl%Mf@tz0Sj|OG7 z=4RqB2p|ff_^a)|HA+jcyj=s{SKIzB01tZi|DdchAN$}@{Y_GT zZy)yT6oQBQQ5$zrFj0vG9*&QN25(|SfDP;~$5E6(>U20~>gFa^F6o9H5-qn}qqKTo zKI3m~=Z|(VmnCRzBrli3;c7Ovah!M2JNHn0j>Ucv(rRc-%L&J1Zl*tCuXr%Bauhw| zPlS$iA0}bTiJehPB^1lG2_*P3gwT|uGaa4MkT&Ur5wn%+#>+la_`D%XIwMGA=CzSf zfG?2YvLOoa1x^uz5F|%{wpCvPwOy4YEHen=fCjo-K$%@f_~JGcofh@wGu|1w64i$( zq8<0Gi;<^10hr!ax)Yd!2B(~0N_aX|W)~=~yBd{i78di_hNk$DqxMn6&YG^H9`MJn z;(b-X)Ky;zPxGa3l)Ye%bfx1^KNtbm-A7BDj?Ksk+-$mDV`J*+RQs)2hYzcTRey7N z!vmQie)qbnC)M{cUSLiQ$sDfiZZ8<<`Q)mpBhs>X0G}#6*RFE&o2VhL{66(fUyaul zJyd`55JZeFv}fM8p^t?5UepXWUdF4ME(^a0EgYo)Pi9j)C_?ckV+XfyzzI-X!#vy4 zkj%DN8iEI;tiLWFTv`B4-aezX#LOW2Jto+>P7lDl5lyJXhZ3*Y?E-xz$vrmHvWuS@ z>(+G-FNan^U4Xth8_gz68&26q6@1>SKj|&=_qjVbI(P2Ct^hXzBTU; zSD3!kJu#5@xhBN0JfG(LL~B^TEK^sxJda+J`bjz9RT12=>$~=$;XXmiD9InynCi|= z4h(h}Jt4p+CpVBAb2!_^O2yLBM3_UXhO(7ada4G*SXGhxac!+peYX{P zMiHcZ0*E&nX9pYT0%j1o`}aElKVJzo6!?7f?ZeH>6))IJeg2(LXG6b}D{7z=)2DvM zdU_m;^`tdu;&(9Oppif@6RQ}p^cDsD$gRPHa0Ulc5Gd6(&shk+l@ZH4ggI0|K@73O z&yba(lKUrah=B=SI1ipLA=CRJOiq8wF*+fd%gQJCh%-LYhJwd8GQJQb7JQl-g7L^s zWS_Y@K}&-M;K^D(QUb#hlxk?%agZwPJ1D8|I997YszuI}BjZeJGSF4_w1IoF>!FElF*wVWRsU$i217Tq>u*oQj z`QXe7atY+dB2*9n8C`|FK()ny7&Ba?ynl%e6g)N^u!<39o_>s|M%0NPLo9<;0(`Ge zB)$c;F+DUpI|RG0h%U)_u-{)1dSIoTnG?8d*s@UYIyZ%mB%Yfd-XHqfGWR1ZCRi9D>t09p&dX z)cbe|MY}$K?Lx>+#e!G4bgUNs6TBO-be@sSRO_Z>mGVLY(|ak_Wy3+SkCkiK{lJ>y^sL2hYi;cU@j~rpwCxpp>u_3-o3X zJ9_;3K7KuS$4U_2&|WKFK@CkoOI73`=lwzxk4I*n!xncG!kUkIp*G5Y9?9Ygd3s4l zEi#&6h~G>~xKF&=zy8H6<&-;d)3x9vi&`%aVVsZk^+=149y(H~=ibEK`uc3HIzsQ( z?-amKI<)f7>v$VLMx_E9MA%C?p%gwiyK`JMZK^vUR;(m+O4-2iuDjZMyP*Gg2JxomeXM)#y57c$0syjfgmx28#Le$g1n zDrbWN-qNvvKbqk3CqMgN7Vt{d`AShdhEVsj>-p6A9U8}!Z=P##l^zHe)zD@;Bv>3c z`Wg?S>43{L6x5{gp8f)ycZaUhuNP99jl>_^gWG<5^sS$#WG0F?J!E47XrcdK5Mn>E9jYc3iNye)G=z&!;OGC${C#tBNX7niI=b| z`vACL?a=U5$j8;97z89D*R?3m(=C~k$fk`LWzd7{MFvhl0~WUq43IH4ztTk5V?l{H zX1D*Ij#PS-qk|an>Bu)Vg^%Ve-}rcz#e7cz?W~ne9QpTD}-p4fW z@hGqhKOfRly=>vX9CW5!tTxf`qlDh2q}n7cjZYrQP2Tathg_d*NjRgc)svS*6(9vM zb(H;xQvhUIh>%=3GY>}T&FK{Ltimp>!5DGjsJE!P%d4}p43&!k}I4a@! zyTRDz$~}^%Vb;Nk!%6t|!tsXpn=7*+DoM|$3C$`Z&qQNPDa|Sku6F1%(9Db?$-?OZVQnyM)NE#U+y|wn__l> z99ku7HPO?C^U_BP040*aNFk2B?eqm-Qv=NE_m?@PjDR4JBdLQ{*0h%MVmEGn0v!Z2 zqP~?K34fB}KRC;2VT#ddf79WvT;g>pKWMK(XElGS?V;)#ch?q5A@#PUr)Tt;C#ZAs z2D-^zREwzuafu|wOMf_fw|(OuS%`l_XIgAH^f`kJG*1g^aDR|>O8LGs&e7yyLjga6 ziRJP^cY&-sy+={!xY)=%Mq*+Di;&CB>&zcYErPHb0RulbwhG;V$LPVc``vd3Bu7lgrc zl*@Msayj_<6xRZJ1wt170c5X>NbC)M)0axxhu`n7>vP%QqC2WvzRR=fP)s_} z45YH}zk*XX}`NT$Ou8hzx@I;r#zf8~Qp5s>UW_^geP(28%%bjGL{L;MRt@GPs z!Ak+ajg%WAQs>~*LsDssm(WO%CxTfz3_{G?lW8NLLhyAqXC1*)jfl zl$Y8Gk0r9_7~#Bm5njrPcK>jZ+)Jl1RgXm?MHjl>Pu&U1ffxYBmX@0J^cQ<7!Z(rJ zI_z1lqbE+%a%u4RC79UlM>6Q9+sO$9m>^3dqo$c)*t++3R!l8l& zNwP+};9+KWxvCvZ~v4?&ZvyT<$Tzbft^%V%_6c3 zm}fks6ze+J7G~O66zu)tzQ~u`(_tz+ykoC9?SVeomP7)5F!IoVPybqUCq(fcgu0c7 zk%28kLb!^}3l5Gaz1jt|+nO$$SX3Q1>40rA*rdC2la6Qy&~85wizSCwS&xhveO$2- z;{TQuYpFEmncj{{1A44A}h=WhmL9V886OztZ1VEN-s9X{QT(#HRaFjJhrfLUZ z7=IwH`;l@kaj6qaY-Ve8LA%J`YaO-DL=Lu25`{cR|^EBq;O) zZD5pX7vc}Jb%2S2cly98OalcbZbD=Q@9SC&c8DK0BKYr?g#EhY;!jJ)Az(zi^YTQV zb;s_`XW(exu#We^3B?Z^()}ZFjP=YNAT=|N+(t1k?_+P?*N8cEc^A%l)0tD-5nhE^ zhs2&^Z(Y(^Orx$40eSF)A)LT9v-a>|6@y75($|&Dh-nyFh2v(v#CcOwJ}20f%OWb` z<7_KuTeh0B2fq?LRov3nw@k<*#*8Kerm#JZRkg2?Ea{C;W2EMy8mn(Qt17ruN(Sld z2xQBA>9={n-&i7@yW2x^w4no?Is1WD6qN7GvEsN_+E}VSv5{-+t%bxAjMLtqx!Z66 zl=WW$IUyR6c@%wG-zu|VULiFD*wzp6Ok26u8~yXspi&GA(CmM^uVW9vD^J~>z}Nts z-Str`LI2^WC01c3hmq9HIOayVdCtT^;%GN5Y6X52Wb=QLpvxy2FV(kEJoJN&TIfdw zzI-ShQa;?^^0537rr^pIQQ;GkH*TZy_4U=3s`n zb$7-c7t9pRZO&Hm`(iQ4-&)H<7<0T3;Qjpl))jkgy^8Rcau%p0)Ue!i@N3_8^iHM< zAv_r)RYb;@&T{BFsy~SBbcptS<&a`|zo~E5z%<_L>Rh~Z_{p*G^u``@X*3A*(-_YJ z(?ImFltxaNM!&Q3;8(tvDU`5e{D0xG5 z%w{-0Qvh?C3@q8hK~i6aot>T7m(Z_qy7p|(1{hED--^#oRPu3Qn}36@ zcq6NDDa!poIs5oQy>%fO(C| z2J-JOkA8Np^xaPC2wezj#28ucioGntIyX`yIr&mv{!z_`oyrGTH-yYv0Wa)Fb)5Xa zWfH`v)nB`mIJnn*GN$Tq$&=BvS1+=S@*3yJT=A;u!quRyqPZb$8?icL9M^ybI9EBX$6O1yaVd@I~v%uy{1;r9^Fl_|>-{ESb-w>+uBoxuEh~d!)Xi z!}_zX^zT-e!R)8R?;?OXKvKIGlgvuf)MlsGrJmZLruQu&5+qoNZMDQ(>K0d)`$yBpqmu`*ANUxFj3Chxt$o34+7b3!$Mo9zhmS__;xZP>)rDxvQMp@iN5 zo(5_!7@`kLb{5YLa?&H5H$t7D>|^GrdXHQKZq`#*~Vct|+l zE{!ZH%+l7u89Nkxy3kuFSSIrFIbdLc>(s=BY9f83;HZm;nt|$RBwb%U|DTvPu6vT9 zbr&(EiiqgwHv$~*_wbHyDW^=r`MOOe?OSSIKf04X`11C>BUDtA15F#lVY5xmI$YZhm#P@Aa=w& z#015*KMONRwp{@)>z5X6UZ$4qKX!SvKWlcXMfpPmKSqyiI60XnUV-4X?~^nMNa)gw zT8ev%%;Nf1|82#j`uUs_bEs)Rt}EGjgKsl&C-EBR^kNBih_8tp&xov3Vm*_sls{kG zF<<;;mKHuWKJSh{@jG$(og8K!T7|8(Z*N_N?V+}Dj-qcL%X~;i{CxM^(2s%`OA`Ty zX03GO4snh%?L25Sjg4lcBSrv)G;;|DWTJgBYYo>z`V*&E-T|Yh<_>s6s;g!L03@rJ zMsY3o-IvqqF3=@?Pl?1T-DlKlkb#hZZ8+(I%rmr_CS^8%D+dF!rtl)yZ2eES3`Z#Q zU2)Glej%(vnBAMN_?X#lp(Dn@!R}Y4+Fli0PEQb%43CjN$1(ZD_xdc*kSmv)*XqCj zo74*U$IunziXc-Kq!3-?7((7?6siu9DNYZAc%dm3US?PcJ{Fk45fm`p%%@@7khD*5 z)C&A25bOCM&wqA#{2^BN&)=;hRae7TRFQ%3Mc@})X4ADg zZ$~Oo37mAyVBeqj>vjCya)EidU6{)hhXF?vjkEIhm)kzekF&gFxIbg^Y7CzZ+l;aj z9G-(y@)Lz+Q~cx0$r|Tg?ap4Zm%-PRnI!MPWJV*~ghwsJD-kRE)#ZS~;Ya{a(~JV@ znO%x>iW&F}A_O{E00J?I- zZw$TIw+aK33gYqaCe^{Ng})P_yU@E#IG62xgXiQI|EomnCun-UpZTMvc{~PvL{Maz zHlm+fLEoqe>EoH5Jtq0anz`Od7aj;puw~3~=y#?FI*yKjv8_)-Z3i1dfJg={jO;M8 zBkpid(Y}0~$M}el{&9WKbAM-zK$Y5}fnlfVGFxyw7&)@@3C1hP)`wTCP0caM&epPZ zksWIAL7Z)gHr#NkF7MjNQ?DzmEWX^ZGw&}MhBQO==x#(AFWx_M&Cij2kNOXS%!J^WTB0Kbh|VeJ4R&^*~^Y*|&R9Ptym>+i1L&%>##I3|nS9B29qr1>oW*!eW^?TCG= zy#01OD{sRwe!FSmQ5m*JF|tk^6ZOuAgU2e+xcI_jw761 zv|*^Mft4=W2pnj=+fp)`jeTB?3Wp1j@)LHvk3%1SH4z4dn5n|Maz#X5N}Q;rnG}ik zP{catCEEhj>|O0-QN(2R&c7l~c<~?PNhIZ;`|AZw9|jE=oIq3=LBKgbBkeGIoBoMX zPd@yie>-y@T?)NvA}L9L-Ak{k<}0>-K3#gr_T%Z#x0KH=;9DdY4;S)Ce5FXbza17$ zh&6@;#y(#c99CV7XLWa9+2|!+iNqpU)i;-0BPy}HcD{W4v8r8Z^iok=9jxH=?psDR zUphaCu6NP&aU$+OIAOcYoVQ_iPEggZkTd>MX#n5_lwkzKwUc>pTdIY#RsxMc(ue|Ay&|NOcC%eT|C-nfk0>tU z3@R?kpONC!t7{X_bdK{DM&~9VcO&dXOWKO&ZJQte6-5QSihn68_wN){0e%amyxjLl zvu44dc^ff9UhSlf)`^ls`POabAz^LJ9j^=?kJpyH%`#5_)k~_|5$*sa8Au)>pY2G$ZLNfz&ArKzKgl>#t;JpfLs?cYfp%bLV3e*-%CDGx3?0mQRf%SJ$G3V^^IuLlSBn8**y zz)1~=jUW!bkh#|DH8cr=(!ofA7}R77x&uD}6)n9M8UJ+SvE7E?wqj|?tFT8d^~}3b z%rm#O=!Y9hAu5kFXm_H3>YNx~Aghf@Hft?Yl^sA)l#64)J9ygw8XI5Wm?j3$Pe0IK zgV-CJ7;R9E%C9%8{5=t>1pLcS@7-_YCpD$X z+FhIN8&_EDxX^HFtFfZpfl||33yo5v$nHF*wl8?0mZ{J}vLscO;KoP+$*)P=Vs|xA zcW=`u-b~GB5FqQ;1XXCu_A%JGW4{Y%N1@HoNTjC}vvRG`LuViUbh>)CuauIQ>E+k>k>J}f>*dvp#az0hbnTb94jHL* zt=IO-@?GQ9(6o;vl`xaR=c3oXxEr&b^CeSlstU2LGu zyRO3O*$_X;uN3}Y(i$EmO&r?|jr{Gi#qE6tT2O%8(Q_Q8P$TfSYLUP#{ChVlu{LmL z>>6`|I3kz{JUMU(B4X0s(YI1G;`+)HJ1J(RvU@I)v)(+G;yA%JRsYC~Rgi!2Aw_q{ zxeWdgG`SbU-O2l_htkth)FWjw9CVtmXmOnl-}XQ@L2KR1ovHVB;HsybH%w-E;z|p7 zAIR>w6lK)nC?~2xOP;St|KPp;i#O`|OKb5d>tGYCm56J`&*)}(og1`5Qod6%20fd8u8?(Rb@;l)^%FEU z0u~6_$YnWF`6^8NLFrSd2yg0peGOwNFP72;x*Z$I9A`dxVP=M+V{psJh1VPp*UGj2 z?jSS{feOSnCY+LWp4mp0y?Z&y%FBWG)y>TwodsnhOS=_=ejp9MoyOC%t(tdp;>pwq z%eap*!jT>~(Ko-MzvmJcAoC7%l$9tCEFD-hoOQ4s_g3*vv27B>{iV?-Zj>NkII!gUd20}?-bxrF zij)zQm>^UF9F*E_518_vPZ1pNiaWL@%;ppn%zt_v@(G)zA=?{c?=xlVvHKfwFX9Ti zM;v5)eaMl+(0vSgm@k{g$wvX1&Neqwv${ECPFHW;Hu<}P+s+@E8Z_}(PxN&EQzq$Q zA=|G}|0hO@pgVPYSu|SRT4MXV%5Ppl+4-Gj-;LIbyUatzRdROWDpY5u50Q$7mhbVN z%^@xOFHE1S*Uz;Lm+doe4pe%uOGIE_z)G-o+^tP_)Q5hVOLFJpI^E;&=v7!&-W?3@ zu*~J54SkYLsf#)?Ik_fg-}dg+@Obv#Vxe|D0iclI&!qrW>gR#uf~$aN9H20z1=X3e zNY{UMDe0U0-g9vg7KQtpDf(Y+vJcdA@=BykwtR{K4%Bx;Gk&0@Pi{gZ7%8Cuvj^!D zFntafUE^4K@Ql_I=!d~3U>aKgJ@|qIX!7L9naI}v{xd;siNHgnh5sO=O+S3+?KIG1 zJ`9ZlMsIPZ^`bqZhA`rV`fg27ruF?C6{{4`{+{2z!jPkHS%p3GF~iQu6$t<7b7(E4 zD>ETokZXs&!T;CKK<1rBkg5ll1Jrlvrg%D+FR8i@5OPA0&YQJ1f6W6G`GnE`u-N{y zddZmr#Vu`-k)ts)jD0to?p+R!ewbHCRC2%Y0}1f&BkC3NC3lJuX}E&Onl0pjCe7d= z=!P?<=fNPS$W+mDUeU#0h+W$df6lklYMsGzZN&A-fg?l*p;v^8B4I~uO_SC*{0#Av zkn^8zf@lA~cHw!~KlTl?mt6mWz)7;LKnAda3DoZ%J1Y*3GM*lSKmYp0bgDP3$V1Ra z&o{iI6rSBce~j=4;H|JTLm~rTGTHIj{&Tve-zy!Z>0?&-VcY#XC67F;ldPMZ1FZvq zWh2bD6P^WX#BCcMqSv{hd8=KA6VqkfI+`_J4Q2L@Q{%I~XpJhY-&XaWfP9`kJ@7Jw zSz*k+96(1TStzzK?s3)iTDIWk=WB!dzX4 zM6=B!C!9WuKILnC;>8v=_8-Q}K$t{MSt@x`V8h!$IdWnPQ9#REgd-6M$D%bV9;TedpVvHzNw zq?L$R>7|hKnNKYSrbVyZ(8jm%Q}ULMGH}IqB#!#3Lg$eEEu*Tl4;A&Ue##yfjX31! zb0|X5Szh9P_=Ukc8&8Z?5t?6fK1P6skMF3h5vBbb3EWl`t<%Ltr1a;~^W*Ii^&;j; zwjK|34;`x&-~asIMCgQMljK&HGqNFHoDIB{3biu6N#2N&$J8+==v{R`9@(EX1nR-} zD&iIKmlLT8527o+_B2HDBLk=Qw4|12$7mF8(3=i<$uY`PputnAQs?6OqUdUpXex*> zlKB2YuHhHPsrYzMN%hNgIg6R7RTvyi;4)21H>sI>DVFqBX7*}k^wdfmI$X%|cmqoTCr>$4Zie9oF72y+<~qGK>f{tHk&g~1 zjN(t8le_wM$`!f$tx*t_4oYtl zq=6N5&|jS$9JE- z_p9%__dffabMO7WG0qlPU4xJ50kwZ|>=ib{Lr^G?2Stdfd|&;f5k@K9JGxxzD6MnV=y!AB^#w$#)pliH7yBZn>TwV^be^XMOkd zrx&!RFjrLE2dlyyqNYVtMLvpBKaZLk!j!Kj60H$kNJ!sQ;-gwNLXldaXQ_55dq z^PP5o70##s5YFq&wvag5rze}y)P8+az7J|y{o3a1T3Re0m)gC%ZdJ!b{9=$L%F-?o z3rCgcYM5SMo84++mc*Nq(cZ4glSWVRuT$8j<({4B#(ZXy0d5JBo#3bxSZ3wCfg6&O zy@S{<1vy?V9;nt-D@%=~OI|XL(~&&nk;n0IM&*i{WVbA2^cudss3&h#3Tm%rGtHB( zrKep{;Y|Z>_kwE6&-#gId;lo)JTcjitS%8cX3&Hy-ii~>5aZZ!SE$by3r&qC4Xqia zd0rH}aKNkMvi@TE)$!v?-4*UFN6bX>{mklMe1xGHod%yu0(weGmDlrqou_Ni>xs+w zHy^56>2>06Sv3|?P2RglnCFGQO2ZmR=@=2jaAwm6D;d+0p^jK>w7cNTxmUbi?SnE_ zy41k9Hh3o+viTJ_7>3|;vz$}S@R4KkwVrn(E(@poY+a9u`@Cqzb-{~Ga^Is{0=RI} zZ35a|VU-swO(8ubey3(6@LTB>IeXt%hx{>@TJlvCwRwcy@M>2#kQEuShN(;St6F1G z_;Xkrl=tgVxQ5G9^x;W!UE8WSy%JMcQ3i{NIQ=c^K|O5Vuo!Dz0Fel~&t1 z=b&^}@6M=dL&S~GFReo_H_k*{rR_zRhPI3v43|$ueZ-v{C8JFYqz$@PP8*EMxzyX0 zMN>UAmcR9k1zvK;GaQ@twF>W5i+!BrjYCey_YuI4c>2|5Ik}^C@?>l+-9woksVN@a zo_$#yhhE>1jz-q$pfU##XAxh%Q?WWY$a7P~`?qtZMb1=@T=2=-r*p1-UY9m&W*L@) z;4h2nJ6Bj9cGGA-6=L80GZZ0`1~wYd1xq$6xXyIJ#5ap){1e$*6O?Q@MIt%4Vl4z7 zMadpW`6}^HmviF;xoq;XE?jE{8e$`ZO?+735G9H`mCu|u?An-j*aj~d_%XXUqDmq( zeqY4HZ%V*V#uKiCjeb-s1n2HnKYIJT0k*&Lap^Swvz}IAecz1pZp<%kvQ-@xNSrg_ zX(kLrOGv(}CYOP(Yc;F-A@#!pB(np9iAZ~~$nm^nZ(Nj<_<4b_h85CdQz5bw&1wg~ zMd45hp;S#-Q&i@-z0iC<;s#;_#$3ueyxtgt0RD^zX9C&nz1_GQt@*lLL(TgfVr;E& zJiCaYJ8O*U)b_4lK1r_QAq4T32-a}*{flQ>;Cs*c+$;NTR6aYhc|Oa!%bp{$VxPtI z1M^sF(b>)9y_Yj)q4}y-Sl<>KZnTL@kX1uK>GKE8n6f~NYl`?zr+qsO(gMzthpPFr z2pN}>93SH+l;Znml|QG)hZgUnE1;myqNn01;x#zdl_pG6b6;ZG8gx!M-UVo?Qd&m<(=|V-?@22EO$Dg{?zx$nR13f6#*hzN_Apj8AF!Bal{? z_4lMg!Zt4P6O#QKHYoJbskw^ec5}Tfwolmm5hmJ<4^myWm1~&R8Le0orWVbfMkJQ> zkXQ7 zRXU5;aY8p|#F-8{^{StMLx)Ii1#rcl(kd4;8^L8|a%9BoR#F~im^Xp-v>nZth`T)E z;iNm{B;;+k2aw{OW{`O-ewpxbI;?~r{MPUZ$%^tPs|AkIhpWHx?;O^p8jDa;ny!(= zs}W+Rx}KuTVW3C}OJnus9H@roNr$Ai;p}3M9uK|}OS>y(>|Ulj>~GlDdmn21LsGX} zg$Ktf4vAABjvy(CR)byjkX->gfo?~`r}r6 z#VfZZ=THO}5I3;JUIkW@CqVEv^w;{Q9oTOISu-F(_ksFm@juQZW#dwTk|jF7}{{Q+zH#NQN|0sU0o}f4mV+;IU(_d?z2#ovT4b?{`b4i zP35x%m$G?sTfeSKeuE6NQ*@wD(RhKUKwxh(RQ#KnfdSwyqC$Zc8y(;iaFDNSa}%3Q zFwS);F}>Gm77xucBOdGMBy8oL5ICgyS>zq+?Wdc$Ms2u)JicE3tlAOPrR}39FAJIl z{eTFQH&9U%X9p-p;D-nyINFA3_V<2v^_7FgwxR@nl&|#j4Gssxx!Ptt-aU>d}gT zM*B`Rimr!IQy3N~Oalmr-#RRHL@C&Mq0-olE4p^tY*#e!MLQKg?Kgpkl3SBg(A9a2 zTQourdBACsmE?*Uo+)u@@I@^aj#$R)iA390UcY$h(Pugy8YjEd(;Dh)EL2x#4~k?t zZ|@!^Dj3h;lEzNhUPc#|@UjcEz4nD#c7|pB(WSMG*^gp(+E3-)9^=HX_$SO;{ z^UU6@QnMvJOHcN6MB7r@x_}t~44Jp9CWoKm)vIvp(Qa;VO>Yd8RgK)A=*z0swAydD zCOOw;Q7k*}B$|>QdJ}etL`P1dh*Cx-xS!5suO7f%Yr>b?2<;ge?josM?7OC^Z#SWOgyRM3lhF!y}8xy0hUO<2V8x4<}&4#*J{5LHsd2nCzXBT}77 zEajLWJ3}#4a+|5W(_MiCN3VNJJaLq~R2m8KMKm}(ykjJF!ikwl$X8vFkJz2ZazUo! zpJ~}GM)YOjf~=hxQCrlz9n-)Hwh!M!1S}O>p4q@RcpFY zYDANdnaRt)EL$<+(r#eGB({^UVJVSZ!Efub8ds*psEP$*T{b;|VJpV!vd9!m@Hav!d zQhvdWgcGiJ^Rq8;g$MfgDy83}Q?cfl3hoYuF;QA3*%6E|C(D**X+Z+I!Dr$m4xjCv z4|_STJt!GAonUIE0@pjX9W~fv8!qQoNv&o+Z`NF^La@p}3{J9C+hfxj1CFJ;&s16K zG)#z<_qs{VZ;l!Sua~3T* z>s3z;$SYVG@*zSLexe3ax?ZQIb2WCo;Y6nf5z{p;C=&63{y@nr7@}M&hIlHJ1l6?ySNfBo@=#AT1rOjC!QCOA2jv5aX*cKO; zmq^QQRzw{i>Ud$F6h;-~GJyteC}7E%-f|vvVLyV9tb2I z?5nK$&>x~HqsElkuu>hLK+q} zCH@$G9-K{ff{STC$>nBdm%p2Uk&2~(-8;9&s6;gp@%pr4gVoLH4wg~tQgU{|(Wq~}`-526biRoN zSR~Wyon%H|5~ zn_O7V?ZzoadIT^P(#R2-u<{Dz7ihQWCu#e6Ucy)im0q~C&}m|fzw(o&dTnJ}CHg1G z;c~fN#6)sl8XwZRD;QQR_+kQ)lA+=^-+1Q4Sg0M(9m7ux2n)^!6#fuZUn=s0$9{K3 z*fo}g6|}ECbBU=WJe`u1a-S*qyzYPojQgO=6xwKHC4CdbA?%cV-0evzs_aBz=V55ocN5=^wtD;edJ2Uz2KpIS zwTcu{n}8jdVwgd&o7df(I&w_Xn=b3nR~nk+T^9-i?Ti$E{Um+0bSB}==86pj2aPO= zl(DeQYZnWt_T_v2?1PrWu#9=;U8>!f@KpNObXnwzYNAp#ECVi%>sY_<+TSi7ejw$; z)0Os3{z5x^S~)qcojm{I25WiTk)Q`tZb$rlry-%Ms+TcOD^Pdbg!M29+$_-o;k>*S zdQ5qALQ!<6X!r@D7o}BM@PSJfD2W{TinLYh$Y}u{Ed|J)-2!R+VH`TdyGEyFgtlS1 ztCXOB5qB5mmW~mWjW&4Igk;h!lBm!{4E6}!jK4thnuB`JK$9wh4+~HiMDJwrPVkSs z2|8%Fy0D+iWgL||`(ioY+Y(>H&tFHPd7qtCx#em~^$N=zC>6h*nsK+>^lWC2Vq2v^ zum&U+&9ADYup)))J4cwouFFFi5W=@{i|VJk)2I6`4W25x+5b8MUZ``b_ZVZye&3T1 zpcb+z+RRp0%KKfT7Ungk$XakDxLdGdx3ixh?WDuyeZ%vlyh8d#PRf+&(@%dqr^aH} z9JKs_99exiaC&{X;Zrg`L!{l^Ki#>nZR1w4Y67m9&ER^W>dtG{cR!R71o1ygjhW$m zIAjPo9nmu&tHQjnS8FKj*rAuBkAlCP@b|B}yCGA4uT%M!S>Gh^t6>M)lbLjY;MB7M zWl!-Fta*4+aEh{Pf%)w?if*cnwdE@(u@h30F!=yA&UwhMpQySFvFst8&u+gwpdg4%Y9G4LFlaucDRZ{C8J0N%@iz6k!*- zmbQ5PTM8#|K!JSk`FADHl4twO3TyhMOR9XO+_PRJU@ku6`0}!EKh`6={Nh`#KIc2f zda|`Rj3a(5bN>2}Yk9el0ac6LV^Xkh-&oe67 z^>Sq}=>3q9hN-znsC5Zxz+wXHF zQTa}&%-qKCyzz?_mRAf+SEXRcu+5poiURZgSp5!U%!b*&NVMI~=Y))Ip%+*ZK`@Rk z>Rmep(Y_9wg~tQ8sh=Zdb$VVigu(6fuoqlRZNiD971P%d4M5QMIx4#D_GU);R0NLN>% z0DE5OVCxh6`Vh4uD&6T#bp%2_OXl#&%WmP;WxD|)??ZTcvvL}40lAHP@}GGd2zukJ zJ^=|SJDm9);hb}AhuCL5srhCM2kx|&txApv^Q5!lT&;h1wLbBdAGdBPHU$;3W$iJl z|HL(a-66($_OTGBlGSH=Y7MHA+l@ghsV*y(lEa_ouQl}e`S(TY+AQiRIF=412fT{^ z5S~eX6ZdrV{4DC9hmGbgTT12<5s75#ULs%$T6xKTI~f0oj~=H?f)8nU)h;48G`D$? zUBf}kr07`m9|BE(y<{?ew@KQ5d!U83-$8AtpTwQYCc;PtJq2*~T!ODQ7N3%Xit+bn zeE;D=?OyENH7geu{#*88Gpa-VP*ymz^c5g6z=icyE z4rbHkKmVig&%0nY2$*WLKIQ&m5ZLN$@X}d8 zbQckab|FlJi6MLrVfgL&DK~CE7wvAZoPsy0fuF54HM!iM-Cg5(@Cw5&`rtD!sVemWR-PQ`PU)V5aZ1G zFQY-`pkHP-1sL4?C870ie>pq9E;nyBj-W!}k-?YBiYhkC=f4ndzOcJ{P<~g#28krYxO4agr=yiNnjV>!$)`b2Zgtk zBC`5rtgOZkus0VSP>1CqWt=`U z_UabX_7Tag(S}cv44(wwOhC!|O<#3uxr%0a1HE)M++i2HP%tobV(%L6|gR0zKWZ%6f6IH>v4I1N-p=n#dZ;T*a z4#+^sdDh`R%EkHSXd-JGSrU!~b`3zL!nt`cElAQIZhK<~5SRrm_=~MLmpU1lC(0T=*PADW?%%l;=u4 z5`4J$CTiS0-H+C5ad<3z`O?x&9S5@k9!EfP4|*=3H|>3K(mHzS4-OA`zB;5t;oCz^ z)7GO@UOZg>Gys#GmyIVk=B!0)!6kA(TeVB9jTJbCllm%UXq@Mn(W^_ z-}!=Tg~(x_qJ=0Xc-B({v5(^qhGHVsC-wVQ?Q~z4mPX!ue0=8WyRfi*@893&)S#k% zVCjqJQqGTTPRbc=@^$oOZ&0gVDAGDOS*R1zR)?lo#k(1z(*nst> zWVgtY8kmK(Tyt86^A4jY(lfwLn5X*D818W#b+VR;VS9jCDzZ*Woyjj6gZxC)@8Ymj zi(D({z0JBm+^}y|l*5dPnnl=njPAe{%|)1vGo*-nrRBBXBfs2p1V>B?)YxKw;h2?k z0#4RQT02a_R%Gpg%YuuQzRPj0kzToQQ63Y+`v<5HHpsdwTauBimk2sUP2pk-xEv1d zlFMOaDJ5gEk)G`Krus~lO40$uQyChoaz|7~r|l{+Kgjf4_9T z98SPh#A;z=%&%FEd_)Vr{Tk5< zD|QS~HG(^1(n4(ndrR+s>z(VZKOS*XbASE&s+%Y2yArt7HZ_3U&keg{iDj*4J~i4H zR=70eEVaEMv}?LSaXz(XV&H9&&Jrw9NtRFCgQyH4+CgGS0vL_?GN?ohYxaUeAEsW$jNTLfx zi_>{d$hFHgz6%=oW-neVxz^U%TheX~F$lg=tP!K}z?k)R&+C1)`*8*FSuW5r*O14B zjt91j7c89a+FE4Tez>G5F%=yAdAgSP2hwU$@$QwgjfyovK(#E=^@Z(rGV)7wIuc_= zQU$;kObZOYAoPzogJ18u#c!$&3Z|j+GsNNHm7MQX66ylv993yd3N`$&d`PDGVv&CS z`_F?3J)b%=oTBc`nIx7+EjO zDRT8)RY`&>^{3WW)WH6-@+i|35tA6o=6xDSPR7b0#dic=y6GNC;4fTErb_-HY<-D# ziQZKJr8=@E8#Fe1*VvOJu&fW<5WId@HZ~iQFYT}|B*SCdr6O21R5U`8US#RBw~EKQ zT>BRU(@-DL0yLsyj-dmk&~@yc-y#Z8NkQ?u#X1yDbVJu3=N62_JqmmgIFR+_1b-ln zuLZ=(Ln7!luTqw*+glT%AfPoVwQXq|88Ui3vaScm^R`qNt(9p#MYNn5G(tX86&h1< z2~nq3(Darpy!r6_Rhn$du(N31(>*s*5ULxTlSP;0KIF_QB6QbG-{|z;nJmaLEA{A4tL4J@o>^S9f+J@4P+wO;1*q$=J zHjVzpbfJ>z8C!`qpR1*#NLSxGo9{7;*BX1grW1&gUh2~*pbvGC-j$1vNW%;Hfftt( z<+cuZQlzkDAv0+V%j)#F%jKh9utUx}mNpr#bE-B$DJz$mdUj*Z>b{)u;g5-b>_Mj} zw?X?J0RWY{vj`!QB6fXc97B}m@C(-MTQil6X!7@EGGZFPf>{0_5)8{yR%k?p1bo|Y z-lGjGaUnME&y!EQ*M5Q~hauw1!GNLW4uGQNkwe?rR1cgD2KGH@NXlw}bUpejJKmZg zHT|_3IGooPEn0p#qsn-1B!%3)F)LvKuX_5#ZuZ@e5O5717}gN^NCCnPwRdAr;pJJT zFmI5oGW2-J)7PCfQ>|aj7LSy)z4rE~2{4;ee~Obwj_S;Ce{!Q4fv9L<)gwV@s81=M zC(pnduW&fmYUPOTKq5I2*|5i-Kh=rLi9D2?iw=es&adnc zp)P!n%dv6wGv`0{lh7rF)m7DFM<=eHs7$uK&wZEONp17NePDPqGK0B`!ZG6Y2oJEM z^=0esIb#bfgYrEBs++?_*E98(dP_8^)~+zacfp|;BLKUD!-&pWfo|J@eBpjsW_ggA zT^4Ji=Q>*)ac%tmz+LKEzv=tfKP)W@fjk46^FPnEzq;jNUz=ud~Rx{AsO)Re<1Mb0`$J)IKgwzngU(`V#u=%-}6Ryon?kC*dY@$#PoGMW>SWR}# zD`$Du*5Q25VrHUe+>$3Na&-Nm$UDUW9IAf((Pg3qToH?`H(*={u-J2$WhzdH^ zIWhj48%us_P#&MI;oByfdLuGI^k!87BA-x9JWY}zd_-x^FzYT=vOZaz;(Aix=XJW|K2MC(! zF5jtG)P)IUquRJ*g_zvdl{~S>{-Vi}@8%zJft0HIs)a=nA7(w9;9zaCe}J4xq3^)D z)j{^Z!D&?yhVQ(Pj}?B|aZm{8#FV1jca0s_yJ?qTVWnj8`cz0i$q;p2EGsF~q6_Ko zE>6!}QzRR!5-4#(d=Uox1TLnrETOO&jcM$qPM4%-y4aQiwr)P=dHdx7H54X&4==P+ zu!H|pOc=ru0kx7y5m=~92%TEJ&;X58y{YQJ?_Yv7iF$dXWiCOlV)Ht4c*f0>jQK%L z*yT^j+zqgUi#Ckd@e-e8M7%3!$?4|P?_!Rd(0rv1r&@gnph6N@c4SsVGyQV$;RIjI zY5;4=;?AJ9WSDPtU|+|J8IQ9cW_^T)z=Y5s1qX8TbSHqL2JL{=ml^-Btu;539L%fb z*=d>7EVLB8;$XL}lfK==ZoM~ozoZ2Xd~Y3tOKdh62K{s)>O6$tM$3c2csomkcPgY$|4 z1MrJ(459(1+##2D#ZojS6C-FF76pvyJD0C;G zgr)$U`xF+q1i`Xcya7q?G{K{vxOwcda5KMX43^t7@A!k4R7^3iuF}qPlQ{YsuKDqs z6AXyv&UCHf4@#SQ#18EyIawCwX66Rq|$ zcK6Tfse$F37qae}I=^4yb%OI0G9s0;@7sU_!C*Qt$cNH9&e-YI?DS3F4N!!f1?2`zY& z{%XzF%?@bnK~%P1z2bBGR5hg(aUuN1>U`|EphH8G0f?73-&#p!rR>vWU^<}r;F^ua z$Zf8;uds$A9i?B~n7Z52fnbr^RL6+U{)Vnl#9<9VexiaOQHv0YO*@A>7^;{&ved~t zt;Dd>(qvdpkxHO5H6Mv?n?}L)z>iXCrZ_HJ}Fburb|DRofm5wFHK82uyXbN zx8!T~?kd`^+1Apjc5~}%=_y@kUZg!bd@uSDiJAi;Oi;+}kisX}R~px1LB!;`E$*|Y z+K0QgG4$?fuLR;?8MuU7rtYO-yn>JKtKY`DwMajdA&G@fn`TTi3o`HP{bC@WE*d7h z(c|k*()zr}!`}|C@^!bdAPN)QOb1 zR3{JPL-fg{>+Uv9K}0c1M{;OHbR#`QfZ*i<{8W>-WeFxDvt^q~SF4!5)!Lm>{jynE z(|pqvv&uE?!mlJ2)kZI7B?aB=1h(Ze@ zVCm{&Lfhg!y@b<;TqAdGtz8(&Ut8~m|HLg-` zw&|R#VRUZ%O0Ou=1#Lgu_L)m{`n2LGkr8V(9TW|+T91{!C71!&^-Pk;WoV;v;9_D! zo0!Lq!~^H;B=qWNWvMrR4B(c-1W&x_U^TbxrAlzqQCWr7kI21;qy|21?V06SF8>^* zVQ{%glUQH-lAQX(5S3wmYCWWy@5;nrJK`;tgXNgDsceM8I;E6@O6o2{$iwav&88hy|-AMH;yrh7^lu?*{PRR3suE` zsQcCR06(fT3e_}=?(@@>_d4bTlWzb;DUB6{y)>4Nus zDgbn2mYb2=LtsJFYf|t<0lV~_3TW8wK8ZI7S4U_3NLDP6`K9ms_dVeM`gwtGj6 z`jo}jELVPS6Y+l1qT!vzb@S^FZ9hK2JfjIN(vrA`c${y<#=&-lYBuh&d`h=0{5%Fp zjp&Eax!$c7$1ZK^qPrve6XiFq(=|{wX<~$!GDCQ;7X`oKTl`K{igry~TY$x*3H^KP ztC84Z-2w4FSE9$Fd3zWidhbbphmv#}i zT>-@geAa$RZBFdpMDB5e73L>yP+18MF#@qK8xd4me82l1C(0nX3|WYIiCpnpnT7f@`2BI9MSCWyL=VsjQ?ra zYQ~a3n#>4Lohh(?v8*m3fUJ4~G?-XcZ2~hE)d*vq#?gkso&A|7!{FEaq@@vEUvy0} z5mm-qj`8iT)H+mN9YF_d{IQeM$Pjf2r|5iwr3FKSc)YvYy@yIu9%pIZom3Kdm}k7% zsY%nlJiU4QYjVZME}r~r?@ROTZ{-h5nr~x2Wb^46`G%Qwrj@#po{>E%RptPnF*ez< zhA$Gqk!fWef-aXvQ{uI(usfv4)8JS|&xN&or>ZjELdLBB!Mg#aLI64~(U)~FJV@!> z)8h;fa|ht^Z!ruG{m@Xz1wiL|@ckK``x_ea0}+9XPeXUrB2_4#bU?K7Wth*exeQxy zrCM=HjlqWE86r5#90mn|q6e+jSaft6L#cGQ4R>*{MpaawdGDz~d`Fh(g%xV12o2Xv ztY+Qp4XmD^mz=?czZ)P zO73&}A$qV_5`88)*Fd}jm+RvDTReDe%P~rSeu(kH%?#65R>jZVT-M?$cT=xOFLmd3 zC`X+QN}UVEm#-F+#~C-uzfm?xVS_crlTLTh`3Py_Q_y<>A z^s3vaBe9bEn;S(AKr+81^8T6}uJixd*hrd2(NhLt9A3UySVV!Bl^P%3+;UBql(!nv z7)&;IRJ7ku9r27>$f33lJMqL7lg8?d5GZ!=ldV!bnc+zMl7P#*k>9knAj$ZQ;$LJXO9}9# z?If!M%6|Gc^G)oZz=%KmPiT~Zp+KLU8hV7QXY3BK*7kAJwQ_7%=&HTN>WWa*1tn8s zs$i>b3vl#2RxY+$u0e|{bbV`KBIRqz z<;!U}H&S?I7ddzhy>-pB0y*6>zzz*bl_IjAXMpoK8*n_7Nywz?_-csn_^blsn1g-c2mIZYlq1=kZS zi9076Kcrt)8avtU;VH=HAoXCAi2)ncw|0r)wB)oKz=hMI)#(<}7}nv8QYA)y<c(#Pof8TH(lpWz=sYhrzxWwMm-u38bn7= z3vH8IL|OOosN>t?Ieg6T)9<40Q?XFdJb>8_wV;1>D(=BKk|N$xc#w;S70-6XGI-e6J@wFxieV?$pG&;vBXpVj}Ka{cGOO+iK zBq4mLAs=T3T`ey5EnT(vYz$6|@c0NkV?kru|Ok4&BQ1Cm?s;PvX~Sc{pzT za86w~cz}l!+p>~|Tc4(FS`S0=l9XmnxMr4s?hfX_hDzP?N9T+ht|Zxo+!9Jzquzb7 zoq>V1puz;D$b}RcIM<+knH#g8IOQ-VQ%B(FF@sfp8h2>YG0$VS7GK?P*MN9V8G>a3 z^`^n9FVk80J{Qacpay~L`Ok4ywaGU%U?l_)0(@iyel&kO-d1OVBNz*_s-tl>#U7d`A+3s z2ON6QWi< z|F^w=`u}$(`m-77|CE`CrcPbL4>|)2^Imr8dORUn)?Ko&GI%0?Zh!F@y{K68(YS{p zI);7OsH9(Fz(63<+RfstMz`re~U69CO;8%3JSD4;hF>u(Y8*YTD>F zdyb%O{{2(|0?@`q6KzO})ulK-0yAnJQIvWTZZ%6lyti|2|u9l~`S z_sMyE)n-}2qsG!$K*dZ87DOmNaGyL3Q$h5l6+cIpsK-r7sUPw8lE*?LywF_s`Re`B z2VWKC0JhMIJATeTX;VF@f*7hAB$+kBe?)!abJ@&(7r`K(h^q%iK&1>lQGEoH7G5ht zD8*d@CTARc)aAGXU89$#(iGLkC*vcuq{l{f7l+VpfGz(izVEi%ud+H2kfoX*+FW@$ z`{47NxsR*}A_KXp$7l~QJog_h*RKMb?HErQl+y z80ppGTOzyF`E;Qz*tv;oUF0pO@?I3z`$ZF!iRkJ@HxutZ@BU3s#T@O!LASyoKLtnr z{3<9$%brqf3!NW;lDHuo(nRI7O?}X=={Tp;45cU8VpoSA%@LBO16>0~Ty5k^qo_2) zHH?b|8n_KxuEFxXvC=>FaxZojdNh9fs$8t6uqv+yTEn!>B`&4}6kaB$jPL!>$s7v^ zomyX6oMIi3Z2l4Z=j2bJhhHtha+W|jtIZQlclen23X@@FY`56-g*gvgEa*P7F|Rt5 zgJ=$bM8lPc9`K+Zgt%Y0G?!oUF#M$ScG#UhgQ&$cgZLTYiL>p3pTm#VDM?o4pelgB z+2nAR+k;eD(7=;DG-PQIhB!4)ZCuD`Q1nuIRqsNYgLp?`$3|ha%3{iFa~!pZ7=2`+uC=5gG2ATh@S>{s5>q|B#%BO0H(c zuHzGHu{Obh7_hRnumHhEu9;<~o%~+%>ufK&!TL@?B9o?dv403yIQ)xRrJeqT0ewvK z)d=gQ_UZ7%;b_m++;ej7k$R7pg8~!af=kL$o z{Z_%CUe*c|Lh;W(;H(Ew4QWh^0SOOt4nLe;(oHb64ZpQtZdN?>Gel@+C_hL<%jbss zQ|4KNC2=l8+NEdm_4=bF;%w6T)WO~U*SNuKa(HI{+#p3T6=b6L zX&(ir(@*fX%2Q7GxSVf!8|p1-a@*CVcRVo;s;+*V5QopK#vUwnopEDWlvfr=n6equ z6xBALnW%neHO%5`_eP<&w(A%00SrPd2f~@@4;kVsN;BQMk0|l|l#U`%5HBnE`8@T_ za*=^s_jIPTC7BR%wjNq?7f+X3S)O={b;}KiKNpuBQ5=U@hruoc27%!%7*O{Q;CAZY zy-)j1Cq&LIA{o{U3D3p|M%w3ArwUaO{i?lS$EC)H;>&{?dB+nw6}*n9>`nd}fGEAP zbOFsxkr~t3)E?P9)Q~>z3)h*GTu~-Y2z82_=UG%$Q?figs8^2F3DiS?T;2MQJ#!|a zrGav;lQFpea-L$@n_9ag$vW(puNfa@cJs?h%PI;0k%}_eryP}_R>;^t$3`Sum81UR zM>+7{t4YnK=cDA(Le-fna6Zv*k9|0q88NQW$8%9*-uc;~=#)G&5r|h@s^qjaE53SA z1T?DzIbx2l-IZI+=ad@66$u`1l*kR!vz`Cy*%Tyyx#8=|UB3J~ve%xPj!Rv8xq2b&fdMO;d(6*R4(cd!-mP`c zRS^saxX`n|q0K)K=YQwnKi`Pn-M5&AKjQ@1^C&}||06at46vH&zHL}iJQCC1y`_Bo zO-0AKf3T|9_pjcs-n;Vsg)JnH*ksqfyqUc+e1cPpWwL0n;@Np z8I@4})~9k$rh>&inbh2^u1xYCsJ>dbki4vyyBzIe*OZce_PK+(*+J&_9BpIwl{dTX zmOWVbQ7>-hnq(NA5OehDv&{C*=xt3kRXH8P@GN4QxVUNE^_5RjLAw-P)O%-D&Z-z0 z$aMH^Q=f3N!}H@T#H$hobFEZV2b|5?^ejqJx(wC8@A*?Rwf`mp1Y@)6@WqT9^$s(( z%f&akzgz0WeV_``%YQGCe#+v+sfV|hTAIF76-75g9@o+mY$!)?K2>gSZ=YWBJuAz7 zbf8S}(%}%H4Z7uLI&xbrq+gMbrqZf8-2hcpM`1Li4cqF2I$j}9$N+_I8QShp?$;r;XqPe|dU{K-Rpu!dC0VoDe8 zRFd<1tKj&kCC=w3)Q0Y<7*y1u6hM$qorfnl9B&iVH-N|YRy=N4`>fmH@N7lnzzxNX z@`2$c)Ynan4yT@nQLMX_%?^pBoWcj4LXuhdkaIvrrv>>nUQIIQ*GuhZ8}D|?A>`sZ zMHfc&-9fU0h2zhs4kVT!0l4w^*tA*X&j$10?ET)FKboKkC~x$x5V9QUi&I|zS1DEn zI{(ZRe*u&xQZ-5}1o}W_xY22WgF_}bwp|~th_{xE=gXN(KN=Pu7U}9J z)Pn|!4{u2aqZzB^{E{C(#iS@tES=?3iV(Iq9O~t)z^OiSutp;OP8aQYR#kOt`cpw- zC*%U%+G2aehbqo9n|gCzI&XO=VQ3vN6d*0nA2;-GrpqnK1wk$jZ7r5W-tFaImJAs^ z$xSC3+3ayPKc;S0uqDRE6gYK1oKGWY{Uv5$?;;PWwtyvpTOcb%K~iyJDRVu)OWjMd zx#Yc}%S74E;)3_TPCC3E{m<@;y??v-S^xAl3w*|YKk_}GKL<*HvGem3qeBwAxhU7kr zfe781q+69w^q&UCHlMo~r5COfC!utv_FL-#m({kGp=z}^ei`~NwQ!uzl|v$C*ff=C zuSGoyIK4zyNBhiWu+5X_=37OxXgQ@^J@2wblhduDmg!!F%iRlDq(3@lNm(Xa%)IVxKudx7a}21{w%wn#@|vCJX25h*gi1$8IO+ zwg?|TRi}j)yyKxT*9`O^4ZLtM&^-J@thg^72rf8But|~ww#RC2pm#+eE)iCJFakG; zW)(uvm4)olTOud7K!@i$aP-FmYB@wX0C4Z-<9~c- zFZD7|$H)LdJCgi?TqaEkLXj9L)c9zUC?6|%e?D}54~YZ4&YEC_*L|^%0w#;^RGctw zCS2cyEd{z73?*`}ce~-z3^*S+mFfIK=a33}`?O4tJ?U7>zC&hu%< z)|Pi}MH@0)Fz8cEzv-b{)qYsM>bNLnN0M=5Mld`X1|`t)V=3!Kz}#^T8Ijd%1!MBN zd+Bvn*y9d6i9ClV!hB;J_n zfK36@=o$0MoWAIj!q081#3nnICUa`JSr)Z6Rm#>TlVVT{W$L2c+pMfh7cKjY$`S@| zD6b@46bLxPqPgNS;}(*}0hFQ+Pj@MYN!K5GcMtkI_H2g0njM=g zo~(Op+ftvPq>7uP-lc6)_^BB5{_8S>3H?7gW6@H^$&-!C=%4q-@aHAgN60TLo?n+& zf2o=wtN#ys?-|$Bwyh6GQBgpORB2H}QHm&nh?J;ES5OoX5TYW@2tkw{2!iwy0RaIa z2r5z|y%XswBE2KM*Mt%RDgLMT+`X^6p1tom@BO_W&If+1tYodMwKC?MV?5&-&lvtn z)h++!O8mEdaM&m#JqeHp9{=acer^l>&*GNi&b+nytOziKn)|vAGRDlfF2` z4j1mLzb5~P_;eJ?*O!1{XH z`KPU6y8j*&$K)Q4wa&ENIBTA|uLa@8T&;9@!(4$Y^BCzs1bjP+orXoqvW1m3HV5)McVg4#Wc=ZAp6AwAB)iC`<{KLgK3N@m7(Q|b+_Ic*0#A{H}o<`OggQuD4gUw z>y);q$@Lw$>c+D*{|v$Uv-k1RUJ6t_^1ujQ5bg@Q-t)QpbWhAyOnkGYO*v3QP3l{D zx4l9BTy}3B`*}g5Ic`)JMUBdtFjg58=8}3pW0*ta^(j4=OGbt!Z@7Sj9fd$n$c6V z5#@IFKFq4v`~H&%(Ncd=$^G>6Q4O_o60`0fTOVCktaXF3p@W+Jr?cc_s!6J77=r)i&vDqjK+yMut=-$59E`YZ}J zqSrUqQG*t6Y7yoer+>V@y5{N+b9vxa-om$VaMOpy;=Zq7w&ztfmyuO*@{Q|h>V^iq z5^MB=wfi+W!rX`VUq&6D0UWy#`R~s4@BPUZ;K^H{DQWynW+Dh*#^>qV5h?#@FPQli zG&(52FU98?EP;3W;TxABj*osPS@L^1gn!q*eka59)|#a@-DmdtdND zd_L&%DnWWpOTya>@9}CGF06X_$`!9o_W6iRcExHJ>)7%vX{_7{i#%!<{WvaCf%_%P z8#RZ8(j5%zDZ$isT7`-@)svP$RU1KKgm-lxm#z}%AFfVw#n;{$>Khkd(!P{0t8PPG zlj2!EA)=k@;PMo$S|KqO#@sNpzrEu2Xh=a-yIkfO=>>ZWO5VWWfymQB4c9|`KPZ8Y zd|tuSA|hKOE)*&V>Od6ryg~efQac_nq8AVmSK*XyGBD6WDou4dWs((Df4l~2m+_>( z`g6x6lv~-oDC{^Ne z7~WdCpQq+a&zPP!@0XZmy(=+WVeua#lwKQ67#ha#7@o@%(N4P)tpK5MrBv-9j}lx+ zqeSbv>}%%alSJ$#Lco)peVsREdC%TA+BZ<(pdQ6}$V6K&?t}|e;r;yw?N#o?mRdIQ zQR`YX;~ZU)h+ULVo-I2PfH*w4_&HvQPjg%dLfK{9J9<^!__-e>5{Q#jw!!1^gv-)U zuXZ#yCdMC(UD}Mff@Jlrmj&hdXJ+z&cDu?5B z)l+L&5dPV?ZV%1#w~~iKmjXt$TUgUqWIt$S$Sl zF7A-m!XDN&{fya??eC2`JAbCi{vK)Rr+r2dC@nIDU^KE8VM^5{=7fwk#kDqZXRr4k z{u~i5FA9k>e%NqfTyEGEXIRpzB%OsQdMc2&kLfSl+B*9$UU7P8UvI?(t1K2?UvS#&AOd~mLISeBtlM`S z=6gzu5KwO-{Bmb&XNAK48xwwfyjSf-HOHQ_Y&srM5Y@~(2JyT~yf%)n#d$Z4D#C)? zqX%JxXLB4jMZ8!`TYa7Ge#WHMltv!fKu~|CcQ1tH3S;qA0~}K7(Y(Ss^Q<8=;zp9~ z>xX`t<2&Pm79cy~iMYqm0{NQZe$|?dDrxeyw@q(tx13gOdtf%jk=-|zc+N~#hhGt} z)#CDR*z;kI6{1`gOl;w$x{@D`V1iZlk>zvDZ=!1q#;?a;KJtax_6VC$$(`jxZzcA5 zhdMT<6u)-EHv)dU1_@0|kWOw>IfTelDSyb{EFAXcTu*Gx5lWtB#)XU7R27StUKzU? zAy9)hxB!)fR)GcspP?>f1jmSQIg1WD%yO&UDbp~ow50cS;%(6i{j=hcSMN%DYwp;t z(FWzBi@EBI^msd=gS-?=VtOvL?K>uY*qo8SeKm9pTcS_yzx_{~n>&*7>q>Cy!BER;%)-a`mVA4b^q`=~nFm_U(H%u#aH{ z_-b6gs(M+s3g`T6dcv;jm3cApMU{n88<*Z`bJxhLML33@-xjn3!n)iz%7z zVwLY`;)SU}GgU;!9J|S7QI^j>YFcJm7d|vaG@KX8TnQL$@snNdgVLF7U!%CmSEZWM z9(#$BJ(ukZjN)~kXTLV}_-JwTu9c%je3STsag2hQqnZ~M6rIL-F;EfRizqGPwd!tR zk#u z+mAZg7B9fHl9knM>X&c@{}d|HE&18YcK6|M);gAn+m{{jgiFhPj+D_aVVU$c6`2l; zRxqMjdFaipi_s~??F9;xrh(%tz4^PIXWf6eGae#y+M(0Q zuu-!WgvoH=RAGF3=g!jNGMi5Abdgw|ATEz+vsX`_ma`Xn1)@}FFT8fRHjPO8KdMB$ zHy1=M;&=C+cXHy1wiW7=H$0lB9R->?Buq()GCCj=6ma3-J`&BPyS?^MHOP-COjNaJ zdv$8c{Jvz4W(Ek~sLYK;d}4Q3LJD;vn(QKP5}re#=}-Y>BGWI~(aiLlT7=APpgE}-r+6S0-!u9+g(F0kexWJq7t2E+Se@i zHQ9=CO6g>(%wU80fme&HpQe|B2Y`{Gy;?s~&e2=qFE?ZY{QpT>&3W0q?uS-BSQVW+ zSRzrqeT+Rz7qWUWSY;97iHC>7_~a@r=uB*si((6tBRU^nlH~|32H zX;A2Yz83PSt-kkNB|3sZ=fi63q({^Ix~$?4k`j%s9xJ-6arG(NS(hcoZ5B5Z zBQkQdc06T6w5};1sy!=(2|&TDS+Q?yW7+GCNUAx!kpj%TVah)M&jg}xnJpg zh!M~din#Rf+`wH11Zv#3wUu$Hxw*1(vZ5&VfoSWcFu`2Smu+ng`;B$a>$C1w;(&(( zIhwBEmNEH7p;WRFl;CIL`ex8(=o;t!Oj4K@?}x?@=ZiI6IH(5|?^Jow3cMg*t=N35 zPXUZ~9xhaMkW6`B7M?B~JCqfQW;tuoXEgPe9)s_;^x-wP~miKHDU+#xRZ?O?|M)Ce$(p04$I=^cJ z8%&e9_gRb!!~$hm8h+#BhkdFCj1MU%o?nEAzzEuUz9e^S-LMeq0@45F>Cz0;NlQXN z0KL_CJU>{YWYscI@g!!_P_tD~q)E)I76Q!~&QGgmWApj~7HX<8A+vViF27lc$Nal; zlZ`70)1@W$-ylj)7I#GE`du1T^Kkkn_4)t3o^EI7lm)rv~U5sbhb zejnOG4=`p}mJ8i3ZJ6vB9ngq0yhFam=kP8aCaG`wg;VsHK@Fw@&ow;nZscERrdR8J zt9u=xqcEM@acLewY6@&EaB%y=)Hrp5x$-gdizJEF%n@rU7k(5TB$cBiMp0uU8^GCR zgC>ePA1!J#2i}is!<_su*C4V>UPHlWIu5T_|srdAS@HtCCCdxbslsb5EpstcR zC`NVs63E@I&u93lZRytZk6llfMIl-ob;SqV3zA*9wz1WIz%)pM?nQNM0%um&aK2SM z1%%0Gi5K1dlbK=f4mDS)4vrIWR^)&&wq9Qnl3brfH6w>*%*2b;K{>1MAD<|ZnLF## zxZO_cPC<}$Os{6f%S4OwN9re@KAZ-?!=-!Qas(fWAe8*<|n;-0A5GHl@Juzd`haub_~ZFKur z(ISs)99CCuGi999-_6KDdF0grx;<+&uyFxe+s1n{CpoAv*}DETPHMu$l7v-w$C7ts zGe>GEmNfrSBkCxDE{Y=rlFXx^8%DtpmR{X$uEA4#HJ@C@4{(OS)>*S}OJw!vS=NM4=JK^6UyZR_n1Ho`p+%I~nE{u{lmjJo5{~5FhX15G=g^dMJIRT6~ zbe6!H&Xb=!7vt>Tz6GgKc*0*|&CMr+;lOv;uw=yq@3xsjQyXZ|=Hsm9z<3j?& z>|__cPA8pwK19ODrI$v?v--?s$#xOxqN4XQl8FFY*MP(^|bD>fr*yzkb2{;8^uXF*4?nX_yOn${0Z86c)Kg-7%p(J zf^7`OMz+2bt|N6H`w!{fAe4ByPuvM4mgb6LJqsBXI1MkXq>OyX_WQ z$f)|r!Ys!ZhdztwNts4(>f9365UMvN$58;wz50q5Cz;oX954>`!?Go}J<`0mk#DM{ zJQ#7&?8?VUwaomym$zm(!u4Qg+%&W~40X$tr!#3$G<)ah%55-5!U|$bkXX3UjYpd>51}lreFc&B zYD1$&tPN+HcC6YksJ?f%2egQtg0xiAv7VspNjLxsnQ`U=weC(e+!*uD)=b& z;{R=E!1=%wZb2u_q#m05tYd2Pd;Zd&i?r<4j?C|35bw!(DM^*8VO#M`gX3iJ6u9E`|ZE(bQos-AJ zSdua~k*E}wO?9>DN z(t{L3blZq4sGQkZ45OCfx|ohKfW-_)LXq(VQ^W3cwjeBjAuc#(E3x84|G>SXyn*bH zx`k$u{n9xrH`&v+xjV_NH~%%i?HBnQc#J%p4TTye7> zsj$+AyUZf)GQnifP8~1SfPuIg)eYxk8sIGR?rsF0REM%%#V%=s^>6O+qoU5ZF6K;x zs>w8-z8ivwY|}m+mixl%dE2?2UN^uLFY6@?TzYp*!!)tczYxQklRef|`tEGu6Ozc% z-X2(m_m`llw9hJcKTJGq_DcI3bqQ{;I_byIopi}dvG9E;j+d_CQ-}M6zP!B6(sLC1 z)i`)FxT-qWJXa0khN}hC5A>cYF3~1JM|D5cpMR1^VWNHEKw*s2wWo(8W!VlezL}Dn zy$;5}kuXB>Xlww=z;hhOMpixFp`??sM~#$k{l?UEPX2<6@!{1Ri!iIG&rXJ(pIuJu zn0RbLmms)2QF2Sw8f_7@aYqIg#3hPG)*2T0le&gZmF|C;Xtw9tr$`w#kuvS03<9-u zAp#hS1qe8+tI?(Wwt@t%ll{H6Bw~O6`zJ9Hf+xjOSRx&gSzh!o5(P$()h!{o9e7UE z{uI|3#PyTaDyf!S9d%D8GA3yWqFc`A>_0XtT%~yu%NYvT3ii0ovT}@D% z{j%<;?KOAm_E{G9O@63*D_SD@bdTJM#^T~Al7%cyVkZZTVi|3D_*pTQ)_0`}XflA& zqp8$v*srlN>ZdO|xbS)4x@8bhq+X6sO}CA=&$m3DklBCU)Ar1EQ;+A}HZQjG*=y|7 z-M!SlAVR<57W zcMsm0u2I=TaPgMCOIUvVNJ_r8?D~DP`vv8iS&Owr4Dzu|DNASe-@m&dS7~i+oo1qX zJFQx%u&_+hp_Xa)co^3$@$W+WBajo~&5#FlDYC~16q+6Bx?F1l3+%a^uy|V4=$#MQ zRIhRQAZO|(^8IEk<4`%%(PUOJVEKgUIxn$~3cE2V(@cC?V1a|LZrAdod5;jvNr5=_ z^AAPsBu&lYVl7xsiaH_~>e1W17|F}VQFUHt$Zn&09QQgzG!D}f1cQqWPe zbm47{j{}gb2EPRXNw!4y1<->S!4ge~>ws#10Kdt93!WK#nMD)VK}QX_wtpz@{G6e_k+Fd$ zE=p70cq@Rao8L`&|6UsW-?8uao5TL5wD5ao{7=gZQ~noN#{cG+Y$*x4iXJ6x%h2xU z)z$l~`1fk)zpd~01M2%rgcwvscDJd1y(}oMyDh@U$Lm#aI;}AE8>D5um`2wlW?YHt zI(RzbwVKs8h@H(h$STba)DlKfZRq`=OksL!fDW{a$Q`7I3xZ9h|Kw9`3)8&{u@AL_ zn}2a|+mGLu+Sl^#;qj?xZmv_+5BXw-E=IF$i|}Rp{6N1`&W^9<4{zg-z;W@=vNv%% z{Esb-g!N=pWMru%zv#G%ye)6n)M56+5o+i;r8YRDUjyzy8N35&q)o8|NbXHfyqLE%sKBhy7<=$iA1N zbf;APvF;g8y;~{4$5{R@I{qKO_22Es{yegN$8Y_+%2R(}ooqg9*nqPxi+hOEjqzxV zlh8S1vYlUL=xN8S+w7Va5Tq7_PrnYreDb486>!K{>8xN_FI9enJidZnk@J9oj9REWd;!e+zIABc^=y@KgFM2-iDs$9 zO!3P{<6TF#8Pl)&9#A526IFq4q5d6BG4ww&DuCyi0@sF9Qx{iX<5)Q z(@h(H>a;8O1Ug#*Purohd=}svC-AF_!lS>wCy+nz7a%Kwu~)W1-+3MgMsxvwybtJA zf(uOIY^U0dP&zwh?X0>bniQX}7HL{t`Q+dLlmXdyD+wbqQfao$K#)cR?uxd$jh^mT zIsKc{b^iALDMx}~-7kjeK8H5~NLIXb&(u|HHGN;e2zF5!EU`648+kMCUm|Z`ZAb5IUIWBwN{z$rbUTyc=!KCJ-)Sgxw>u3h*8gZSkP{Ew-N?HG9!ch74-(2F)hsK;e5AIKlz`ryzO zmuMlGmJg}(?H%a>c`7FSU8Mhz0@>}QYi-?G|AMXX+w>vi!GZsw;E&-bflM83lHHK=PG zI;4`4P5)>v(nVDzM8k@X3(u~7z2Lzo8WD2l@jiJqNjF7Q4P%P;S*ES!o8M(?0Tg1M zkDl38b&M7Yn}{+;_u2zY=prcZQflN3|2W^oD=)wQLeH!hVxY77_H0{ywZ37Q3s7}= zn-WZ31(Dg`bCdqV82lfR#~(8BzlcKr&i+4T4E|k7s9((ptfmb^V(?wArdNrI{g=JU zP#09~7`OUlsvWARQ&qRX#D>oYqPB-_Qe%Pk7%uN9&S+amwZ3ookpRUi>X)<5c^Y!= z2CtTNQJHP0#?fR11-7+MuH_?|91k1CfvJ5)vj+xBmBtVY!4l;Z9RRE(!>H-fD<`+A zB!ZGN)D5HmCqj=>nH^Vk}+?bVq*4^V$X~eN{#~N@{iTuoAu$a zw35iG$&9f^-sk4xO)>n=8ypHI_x!LfoB5-7@-ca8oLD{E*2+6j7Z;X|I`-D9-y|oU zVBSFjlWaA}0buyaEj2wRy3xl=NQQ>{8l^JNOSPYj>$mhXbqj@jX1u?;rA%?8st^O} z_4=+g(zg**dW4`4=Q1A?!K1<59w0IzSnR*tABaaz*r5{uDf|LM@hj}TfpVF&-~;wQ2n3WGq+ zJI~DiDd)%wkoQ9iI;Si$Pl_h#$@O+z<&nL9-tP)TxF+!&G+|gs$qLK%4RWtptX}_y zUb@s9|6sdpd^bKm_9XGCyZuKJHvma%;o#z1BXYa|N?O;A2}Mtkl)%D$ix+fr;B{KB z^lY#UdEcJu7cR!uB5f(;_To`RL7qlfz-yCh8MB>}H(OFXF(7;U3tI$X#Ba=6;s@J2 zTZIb-zRU2Y_;&%8Uwjl4XwqBgPr@Fq!0AVT5)EciGK~%**OgcJ4=O($1yfQvLho^3 z9P*{bjqc^&s4ec1@~^C9`jWeCb@%lg`N(sF4+|dcKY-ySJ5jVz+5}AC!SZe=ofh`l zyb{w)iI0~)fAXkXE{$lsvaR2pV|MExF@Iz#ff!Qz&bH%b!d?x%h}XI0eU(>Awzc&f zc!pvb@nQ1)vKz)p{|w!6UkQ=bG%n;k15`ESxWn#8pvT9?4v6Y6xT~k_$k}5bzV4$4b{FPOOvdj^J>Yv*@e!^=*xk*YBixERY5~VVOzGz;4jiK)^-4bW<9L zU}{k1Xjs}F{^SqIi+AmH6zk5~V zhXbMiIqn~i_x~@?B?-;_4PuLc^HY_(QIbhqU0DKGg4k~kZkyC7x{fLqB8|@>7KeZE z=W-ZG7*NoEcnr5i3it-ms0RS|!UpjF^s4bBrhu&;``hrnMxvqbI!k#A-5)9-K34Ym z?YeqRaK3>^N5_N<~%B8qcVdPxPRJq0{1}hAdxZ*I%788?z{;W4JFy2!u&Fjir&6~835L=UIaW#g%aXo&RqCS4r$!{;NZ^X)G z$Kh?Bi>tfV0c)uRQ{hB_lg3L3j3IJOG>vK~_nK=Va&Nuo15twQR#Hrg07U|R5)+f- zXRm#n%bst03U-vY4)z#YbPAJapcHRg`1b zoq?}-ZvzbZm{nj59wOx>Yb$@E7xZ;>E`2lKFWSLC*%V8ZI-IBIb*K2)iBFh{52*+4 zdNY~xk>kd3A>SZH)4_{WsT}zE5tu(I*Y$eed58Ji={C9miO7m)}76bz0zfWc*?ktdHU2>#bP4#WU~sx0llE_LJM+h(Wfev789sDfts_HK<%hE`BpC$7h+vi6(r2CV2^mURH^n3`%jp_A$Lf$yq5s(= zoul`|Y&$SV#%7gPR?(Bq%Mi+@*D>Q`>< zPXR7l6y6%Xc?K4OUS9=5)ccGE3yIQUFzaQ`o33LZXN6@!!5@qwnr~|ijD?;t76^T3 z^HrD6yZ(mYX-%aOKpCltqou-TvcGs8rV)!RJ>ZuxoKFXqgA|wiO50kcBNQ(mb*!|N1P*#EuXHeXf7B(-#7z- zKnTO+Yp?=q8h1IKGKZ!g$NcK$4_5>=%?9x(d8|iu$wRqAtG>yXrZram4%;L3UZituo49}tDF=h;!wLRZkSdr&Hz;vQt zciPHI(J>j7k({(g0jk+;Oc(LfYD){i$~-wF(D$m}Zr0N-{RaQTP|IVP4^Jjt;Rn@Jx=xlQ$-2c(=eplpG zLe)FIzPT&1`<|U~+S~T*={d_Yx1XwOXm9H2(Xdsg$&PKZaAwrCvV!*PyrOs8Wbep| zzSwEJ-zch8(5PeNuwR`eZl_6J+F=#DYqmM2kMyp6$;qhYSbWK9iLkZbnDg>(za^}R z^M#FGqPJn!441w^meWBy^s?XVX!-HSi2m8ODn2mcGN<;Pa1OurYwP`uIsg9euQJm1D8Y

=LA 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∨jqQGY(rP`qzHLstG7 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 Date: Wed, 22 Jan 2020 19:55:08 +0100 Subject: [PATCH 2/8] use directory according to rfc naming scheme --- .../0.7_ansatz_design_doc.ipynb | 0 {notebooks => ####-ansatz-rfc}/img/ansatz_rep.jpg | Bin .../img/ansatz_scheme.jpg | Bin 3 files changed, 0 insertions(+), 0 deletions(-) rename {notebooks => ####-ansatz-rfc}/0.7_ansatz_design_doc.ipynb (100%) rename {notebooks => ####-ansatz-rfc}/img/ansatz_rep.jpg (100%) rename {notebooks => ####-ansatz-rfc}/img/ansatz_scheme.jpg (100%) diff --git a/notebooks/0.7_ansatz_design_doc.ipynb b/####-ansatz-rfc/0.7_ansatz_design_doc.ipynb similarity index 100% rename from notebooks/0.7_ansatz_design_doc.ipynb rename to ####-ansatz-rfc/0.7_ansatz_design_doc.ipynb diff --git a/notebooks/img/ansatz_rep.jpg b/####-ansatz-rfc/img/ansatz_rep.jpg similarity index 100% rename from notebooks/img/ansatz_rep.jpg rename to ####-ansatz-rfc/img/ansatz_rep.jpg diff --git a/notebooks/img/ansatz_scheme.jpg b/####-ansatz-rfc/img/ansatz_scheme.jpg similarity index 100% rename from notebooks/img/ansatz_scheme.jpg rename to ####-ansatz-rfc/img/ansatz_scheme.jpg From 628f85a97d2deb06f21bd07663d1aa59dd73f118 Mon Sep 17 00:00:00 2001 From: Cryoris Date: Thu, 23 Jan 2020 08:53:17 +0100 Subject: [PATCH 3/8] rename according to naming scheme --- .../{0.7_ansatz_design_doc.ipynb => ####-ansatz-rfc.ipynb} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ####-ansatz-rfc/{0.7_ansatz_design_doc.ipynb => ####-ansatz-rfc.ipynb} (100%) diff --git a/####-ansatz-rfc/0.7_ansatz_design_doc.ipynb b/####-ansatz-rfc/####-ansatz-rfc.ipynb similarity index 100% rename from ####-ansatz-rfc/0.7_ansatz_design_doc.ipynb rename to ####-ansatz-rfc/####-ansatz-rfc.ipynb From 850e2bc48f06ac43decc488c7f281c04b615898a Mon Sep 17 00:00:00 2001 From: Cryoris Date: Fri, 24 Jan 2020 17:41:19 +0100 Subject: [PATCH 4/8] insert RFC overview table + review notes --- ####-ansatz-rfc/####-ansatz-rfc.ipynb | 98 +++++++++++++++++++++++---- 1 file changed, 86 insertions(+), 12 deletions(-) diff --git a/####-ansatz-rfc/####-ansatz-rfc.ipynb b/####-ansatz-rfc/####-ansatz-rfc.ipynb index e70ab52..2e41027 100644 --- a/####-ansatz-rfc/####-ansatz-rfc.ipynb +++ b/####-ansatz-rfc/####-ansatz-rfc.ipynb @@ -8,19 +8,30 @@ } }, "source": [ - "# Ansatz Design Doc\n", + "# Aqua 0.7: Ansatz Design Doc\n", "\n", - "Discussion: January 8th, 2020
\n", - "Author: Julien Gacon" + "| **Status** | **Proposed/Accepted/Deprecated** |\n", + "|:------------------|:---------------------------------------------|\n", + "| **RFC #** | 0001 |\n", + "| **Authors** | Julien Gacon (jul@zurich.ibm.com) |\n", + "| **Submitted** | 2020-01-06 |\n", + "| **Updated** | 2020-01-24 |" ] }, { "cell_type": "markdown", - "metadata": { - "slideshow": { - "slide_type": "slide" + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "ename": "SyntaxError", + "evalue": "invalid syntax (, line 4)", + "output_type": "error", + "traceback": [ + "\u001b[0;36m File \u001b[0;32m\"\"\u001b[0;36m, line \u001b[0;32m4\u001b[0m\n\u001b[0;31m 1. [User benefit](#benefit)\u001b[0m\n\u001b[0m ^\u001b[0m\n\u001b[0;31mSyntaxError\u001b[0m\u001b[0;31m:\u001b[0m invalid syntax\n" + ] } - }, + ], "source": [ "# Overview\n", "\n", @@ -1425,13 +1436,76 @@ "Hence, they should not be an Ansatz, but rather use on as component. " ] }, + { + "cell_type": "markdown", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Notes from the design review\n", + "\n", + "Notetaker/Steering: Donny\n", + "\n", + "### High-level Impressions\n", + "* Kevin (@kdk)\n", + " * Terra can help in some areas, e.g. Barriers for print but not transpilation\n", + " * Should clarify what the Terra objects under the hood will be, or hide them, so as not to confuse users\n", + " * Should think harder about eager transpilation timing, so transpile only happens when we know about the backend\n", + "* Stefan (@stefan-woerner )\n", + " * What is the difference between the three types of terra circuits?\n", + " * Transpilation - there is a difference between optimizing the gate and transpiling for hardware\n", + " * Initialstate, UncertaintyModel - All overlapping, should be made the same\n", + "* Panos (@pbark )\n", + " * Transpilation - Not doable to do pre-transpilation, because it depends on the parameters. Would be hard if doable.\n", + " * Agrees with Stefan that more thought needs to go into organizing Featuremaps, InitialState, etc.\n", + " * Inserting parameters will be difficult and maybe overly complicated\n", + "* Christa (@Zoufalc ) \n", + " * We need the gate insertion for gradients\n", + " * Initial state and uncertainty problem isn’t really an ansatz, it’s just a fixed circuit\n", + "* Ali (@ajavadia )\n", + " * Implementation - Should this just be derived from QuantumCircuit, or gate or something else, because it has a lot of overlapping functionality (append, etc.)?\n", + " * Difference between circuit, gate, instr - On our radar. Transpiling only one section of a gate should work by transpiling a circuit, and then calling to_gate(), and using that as is.\n", + " * Steve (@woodsp-ibm )\n", + " * Originally, Aqua came from a place where components were each pieces of circuits. We didn’t care what was under the hood, but want a consistent interface. Whatever we do here should be the same in the all the components.\n", + " * It’s good to have common classes, but not necessary to mush everything, e.g. InitialState, together into one class just to say we did.\n", + " * Parameters, transpile - if it’s not necessary to pass hardware information we shouldn’t. It would be better to just pass the user a circuit and have them transpile.\n", + " * Mutability - If I have an Ansatz and do an append, will the algorithm understand? If you want to build an ansatz, can you just stack some together, instead of building complicated functionality to modify?\n", + "* Donny (@dongreenberg )\n", + " * Like that the purpose of the Anastz as a thing that provides a service of repeating gates, and like Ali’s point that maybe this is just a sparse representation of a circuit.\n", + "Context on transpile - when we got rid of caching, we started trying to do this eager transpile.\n", + "\n", + "### Quick walkthrough of the main ideas + open questions\n", + "* Julien (@Cryoris) \n", + " * Philosophy: Python is a language with lots of syntactic sugar and just works, and wanted to see that in the ansatz.\n", + " * Wanted things to be easy to understand across Aqua, where if you understand the Ansatz you realize that you understand the Featuremap and other too\n", + " * Backward compatibility must be maintained\n", + " * Combining things - InitialState, FeatureMap, etc. motivation is just to simplify these to make them familiar.\n", + "\n", + " \n", + "* Questions\n", + " * Bounds - The Ansatz has bounds, but doesn’t enforce them. Should a gate have bounds?\n", + " * **Unresolved, table for later**\n", + " * Can we support a “parameterized_circuit” property in the gate?\n", + " * Kevin: yes\n", + " * Inherit or hold Circuit / Gate / Instruction?\n", + " * **Table for later**\n", + "\n", + "### Ratings\n", + "* All - Conditionally Approve, pending resolving Circuit inheritance vs. encapsulation discussion.\n", + "\n", + "After follow up discussion, it was decided for the Ansatz to hold a gate or circuit, rather than inherit from Gate or QuantumCircuit, to allow for some flexibility as this design settles (inheritance introduces strong coupling which is hard to extricate later), and to allow for diverse Ansatze, such as linear combinations of circuits, not-gate.\n", + "\n", + "**Final rating: Approved**" + ] + }, { "cell_type": "markdown", "metadata": {}, "source": [ "# How would the Ansatz turn out?\n", "\n", - "Here's a code skeleton of the `Ansatz` class wrapping a gate, along with how this design would fit in the workflow of Aqua." + "Here's a code skeleton of the `Ansatz` class wrapping a gate, along with how this design would fit in the workflow of Aqua. \n", + "This is just an interface." ] }, { @@ -1775,9 +1849,9 @@ "metadata": { "celltoolbar": "Slideshow", "kernelspec": { - "display_name": "latest", + "display_name": "Python 3.7.5 64-bit ('latest': virtualenv)", "language": "python", - "name": "latest" + "name": "python37564bitlatestvirtualenv76cfe9d7d3f749489cf2ff69593234af" }, "language_info": { "codemirror_mode": { @@ -1789,9 +1863,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.5" + "version": "3.7.5-final" } }, "nbformat": 4, "nbformat_minor": 2 -} +} \ No newline at end of file From 38daff37d54d0be5a47d60adab28be3f14939c2a Mon Sep 17 00:00:00 2001 From: Donny Greenberg Date: Mon, 27 Jan 2020 12:34:14 -0500 Subject: [PATCH 5/8] Rename to 0001 --- .../{####-ansatz-rfc.ipynb => 0001-ansatz-rfc.ipynb} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename ####-ansatz-rfc/{####-ansatz-rfc.ipynb => 0001-ansatz-rfc.ipynb} (99%) diff --git a/####-ansatz-rfc/####-ansatz-rfc.ipynb b/####-ansatz-rfc/0001-ansatz-rfc.ipynb similarity index 99% rename from ####-ansatz-rfc/####-ansatz-rfc.ipynb rename to ####-ansatz-rfc/0001-ansatz-rfc.ipynb index 2e41027..b42ddf2 100644 --- a/####-ansatz-rfc/####-ansatz-rfc.ipynb +++ b/####-ansatz-rfc/0001-ansatz-rfc.ipynb @@ -1868,4 +1868,4 @@ }, "nbformat": 4, "nbformat_minor": 2 -} \ No newline at end of file +} From 19d36ece004eaf7e0a58102cc8831a80aa9a6e3b Mon Sep 17 00:00:00 2001 From: Donny Greenberg Date: Mon, 27 Jan 2020 12:41:16 -0500 Subject: [PATCH 6/8] Rename ####-ansatz-rfc/0001-ansatz-rfc.ipynb to 0001-ansatz-rfc/0001-ansatz-rfc.ipynb --- {####-ansatz-rfc => 0001-ansatz-rfc}/0001-ansatz-rfc.ipynb | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {####-ansatz-rfc => 0001-ansatz-rfc}/0001-ansatz-rfc.ipynb (100%) diff --git a/####-ansatz-rfc/0001-ansatz-rfc.ipynb b/0001-ansatz-rfc/0001-ansatz-rfc.ipynb similarity index 100% rename from ####-ansatz-rfc/0001-ansatz-rfc.ipynb rename to 0001-ansatz-rfc/0001-ansatz-rfc.ipynb From 29abe92dc35f94b57a700fb43141a240b698ca22 Mon Sep 17 00:00:00 2001 From: Donny Greenberg Date: Mon, 27 Jan 2020 13:16:55 -0500 Subject: [PATCH 7/8] Rename files for merge into master. --- .../img/ansatz_rep.jpg | Bin .../img/ansatz_scheme.jpg | Bin 2 files changed, 0 insertions(+), 0 deletions(-) rename {####-ansatz-rfc => 0001-ansatz-rfc}/img/ansatz_rep.jpg (100%) rename {####-ansatz-rfc => 0001-ansatz-rfc}/img/ansatz_scheme.jpg (100%) diff --git a/####-ansatz-rfc/img/ansatz_rep.jpg b/0001-ansatz-rfc/img/ansatz_rep.jpg similarity index 100% rename from ####-ansatz-rfc/img/ansatz_rep.jpg rename to 0001-ansatz-rfc/img/ansatz_rep.jpg diff --git a/####-ansatz-rfc/img/ansatz_scheme.jpg b/0001-ansatz-rfc/img/ansatz_scheme.jpg similarity index 100% rename from ####-ansatz-rfc/img/ansatz_scheme.jpg rename to 0001-ansatz-rfc/img/ansatz_scheme.jpg From a48d383fe97aaf7593e255ec9294af68c11ca211 Mon Sep 17 00:00:00 2001 From: Donny Greenberg Date: Mon, 27 Jan 2020 13:24:08 -0500 Subject: [PATCH 8/8] Change status to accepted --- 0001-ansatz-rfc/0001-ansatz-rfc.ipynb | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/0001-ansatz-rfc/0001-ansatz-rfc.ipynb b/0001-ansatz-rfc/0001-ansatz-rfc.ipynb index b42ddf2..a043382 100644 --- a/0001-ansatz-rfc/0001-ansatz-rfc.ipynb +++ b/0001-ansatz-rfc/0001-ansatz-rfc.ipynb @@ -10,7 +10,7 @@ "source": [ "# Aqua 0.7: Ansatz Design Doc\n", "\n", - "| **Status** | **Proposed/Accepted/Deprecated** |\n", + "| **Status** | **Accepted** |\n", "|:------------------|:---------------------------------------------|\n", "| **RFC #** | 0001 |\n", "| **Authors** | Julien Gacon (jul@zurich.ibm.com) |\n", @@ -1864,8 +1864,17 @@ "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.5-final" + }, + "pycharm": { + "stem_cell": { + "cell_type": "raw", + "source": [], + "metadata": { + "collapsed": false + } + } } }, "nbformat": 4, "nbformat_minor": 2 -} +} \ No newline at end of file