From ee62b5727d4389a8f0a67e6ba35991cec9214339 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:42:48 -0500 Subject: [PATCH 01/11] add metadata back in --- docs/tutorials/algorithmiq-tem.ipynb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/tutorials/algorithmiq-tem.ipynb b/docs/tutorials/algorithmiq-tem.ipynb index a2a1d32b343..78646b97a05 100644 --- a/docs/tutorials/algorithmiq-tem.ipynb +++ b/docs/tutorials/algorithmiq-tem.ipynb @@ -4,6 +4,10 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "---\n", + "title: Tensor-network error mitigation (TEM) - A Qiskit Function by Algorithmiq\n", + "description: Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.\n", + "---\n", "# Tensor-network error mitigation (TEM)\n", "\n", "Algorithmiq’s Tensor-network Error Mitigation (TEM) method is a hybrid quantum-classical algorithm designed for performing noise mitigation entirely at the classical post-processing stage. With TEM, the user can compute the expectation values of observables mitigating the inevitable noise-induced errors that occur on quantum hardware with increased accuracy and cost efficiency, making it a highly attractive option for quantum researchers and industry practitioners alike.\n", From 5cdcfe4103fe9546554e30dcc712a5a21f0bdfb8 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:43:15 -0500 Subject: [PATCH 02/11] run ./fix to convert outputs to .avif --- docs/tutorials/algorithmiq-tem.ipynb | 105 ++++++++++++++---- ...4894c44-e399-4b9d-a3ff-38a28ff32ece-0.avif | Bin 0 -> 2476 bytes ...81a4e25-bc9c-47d0-b9f1-172eb5516484-0.avif | Bin 0 -> 30547 bytes ...3a2168d-98df-491e-a1f8-05de5684ab96-0.avif | Bin 0 -> 2492 bytes 4 files changed, 86 insertions(+), 19 deletions(-) create mode 100644 public/docs/images/tutorials/algorithmiq-tem/extracted-outputs/24894c44-e399-4b9d-a3ff-38a28ff32ece-0.avif create mode 100644 public/docs/images/tutorials/algorithmiq-tem/extracted-outputs/381a4e25-bc9c-47d0-b9f1-172eb5516484-0.avif create mode 100644 public/docs/images/tutorials/algorithmiq-tem/extracted-outputs/c3a2168d-98df-491e-a1f8-05de5684ab96-0.avif diff --git a/docs/tutorials/algorithmiq-tem.ipynb b/docs/tutorials/algorithmiq-tem.ipynb index 78646b97a05..255b73c73be 100644 --- a/docs/tutorials/algorithmiq-tem.ipynb +++ b/docs/tutorials/algorithmiq-tem.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "e6e50bd6-8ac4-40b1-ac0f-6e22b6af1377", "metadata": {}, "source": [ "---\n", @@ -17,6 +18,7 @@ }, { "cell_type": "markdown", + "id": "1f5e328d-fe93-4ee2-995b-2e70b36ea0de", "metadata": {}, "source": [ "# Running error mitigated many-body physics experiments with TEM function" @@ -24,6 +26,7 @@ }, { "cell_type": "markdown", + "id": "b63a662c-a4e9-4b5f-92fd-46352a2bd0bd", "metadata": {}, "source": [ "This tutorial is based on the following reference: [L. E. Fischer et al., Nat. Phys. (2026)](https://www.nature.com/articles/s41567-025-03144-9). This reference discusses a real simulation on quantum hardware of up to 91 qubits. In this tutorial, we are going to recreate a similar simulation on a smaller circuit size.\n", @@ -35,13 +38,14 @@ "\n", "The quantity we want to observe is the correlation function. The [reference paper](https://www.nature.com/articles/s41567-025-03144-9) discusses how this quantity can be rewritten as just an $\\hat{X}$ Pauli operator on the $n-th$ qubit.\n", "After a number of physical time steps $t$, we compute the value of the Pauli operator $\\hat{X}_{n=t}$.\n", - "Depending on the parameters of the system, the value of this observable will be equal to a value that can be computed exactly, or only simulated through approximate methods. Specifically, for $|J|=|b|=\\pi/4$ it is equal to $[\\cos(2h)]^t$, which will be the value we will use to benchmark the results of this tutorial. Furthermore, at the given time step $t$, $\\langle\\hat{X}_{n\\neq t}\\rangle$ is zero. For more details on how to obtain these values, and for comparison with approximate classical simulation results outside of these parameters, see [L. E. Fischer et al., Nat. Phys. (2026)](https://www.nature.com/articles/s41567-025-03144-9). \n", + "Depending on the parameters of the system, the value of this observable will be equal to a value that can be computed exactly, or only simulated through approximate methods. Specifically, for $|J|=|b|=\\pi/4$ it is equal to $[\\cos(2h)]^t$, which will be the value we will use to benchmark the results of this tutorial. Furthermore, at the given time step $t$, $\\langle\\hat{X}_{n\\neq t}\\rangle$ is zero. For more details on how to obtain these values, and for comparison with approximate classical simulation results outside of these parameters, see [L. E. Fischer et al., Nat. Phys. (2026)](https://www.nature.com/articles/s41567-025-03144-9).\n", "\n", "TEM works by first characterizing the noise for each unique layer of two-qubit gates in the circuit, as well as characterizing the readout error. Then, the circuit is executed on the quantum machine. Finally, the tensor network error mitigation is performed on the classical resources of the IBM Cloud and the mitigated value is returned. In this example, the circuit has two unique layers to characterize." ] }, { "cell_type": "markdown", + "id": "243ecc1c-5ea6-48bf-b2ee-cb8c88875b86", "metadata": {}, "source": [ "# Table of Contents\n", @@ -54,13 +58,15 @@ }, { "cell_type": "markdown", + "id": "4b30f191-9759-49de-ba8f-7cc616b61ec6", "metadata": {}, "source": [ - "# Setup\n" + "# Setup" ] }, { "cell_type": "markdown", + "id": "9cf6d15e-324b-474a-886c-c3dca5a24141", "metadata": {}, "source": [ "As a prerequisite, ensure that the necessary dependencies are installed." @@ -69,6 +75,7 @@ { "cell_type": "code", "execution_count": null, + "id": "1eeec332-29ca-4882-8129-d1c93ed82b2b", "metadata": {}, "outputs": [], "source": [ @@ -78,6 +85,7 @@ { "cell_type": "code", "execution_count": 2, + "id": "ad0002b7-dbff-4699-af52-ba0df72ed200", "metadata": {}, "outputs": [], "source": [ @@ -93,6 +101,7 @@ }, { "cell_type": "markdown", + "id": "b95b9e75-37fe-4f86-a923-0a833c7960f8", "metadata": {}, "source": [ "# Error mitigation with TEM" @@ -100,6 +109,7 @@ }, { "cell_type": "markdown", + "id": "651a3f04-c8ba-4a39-8415-52d7e313ba2a", "metadata": {}, "source": [ "We provide here a circuit that implements the kicked Ising model described above. The circuit is prepared as follows. First, there is a state preparation phase, in which the first qubit is in the state $|+\\rangle$, while the others are in Bell pairs $(|00\\rangle + |11\\rangle)/\\sqrt{2}$. This is followed by the brickwork structure that implements the unitary evolution $\\hat{U}_{\\text{KI}}$. The number of physical time steps correspond to $t/2$ layers of the circuit." @@ -107,6 +117,7 @@ }, { "cell_type": "markdown", + "id": "1f6f9970-63fb-40f4-9586-261cba23cb88", "metadata": {}, "source": [ "Let's visualize a small version of the circuit, with 12 qubits and 6 time steps:" @@ -115,13 +126,13 @@ { "cell_type": "code", "execution_count": 3, + "id": "381a4e25-bc9c-47d0-b9f1-172eb5516484", "metadata": {}, "outputs": [ { "data": { - "image/png": "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N954g507d5Kfnw/AihUrCA4OrhHDdGKrlAMHDnDZZZdVfY6JianxedmyZdx00014e3vXqDdu3DiWL1/O5s2bueiii1TFlEgkEolEIpFIJJKGgqo7xK1bt+amm25i3rx5qlYmvuSSS/Dy8mLbtm1V35WVlbFr1y5CQ0NrlN25c2eNz//++y/dunUjOzub2NhYwsPDGTZsGD179qy666oWX19funbtSseOHc2eDFsjIyNDUR5ubm4MGDCAt99+m3379uHl5cWSJUsIDQ2ladOmnDt3jq5du9b4LyQkRFUuBw4cqHEnOyYmpsbnpUuXMnLkyKrPRqORcePGsWTJEjZs2EDnzp1VxZNIJBKJRCKRSCSShoS6s0EgMjKSAQMG0KdPH6ZPn87ll1+Ou7s7u3bt4tixY/Tu3btOHV9fX0aPHs2rr75Kq1at6NixIx988AGFhYU888wzNcqeO3eOl19+meeff569e/cyd+5cPvroIwICAmjdujVffvklHTp04Ny5c7z22mv2t9xOlOSxc+dO1q9fz80330y7du3YuXMnaWlp9OzZkxYtWjBp0iReeuklDAYDAwcOJCcnh23btuHn58cTTzwBwJIlS3j99dctPjZtMBg4fPgwb775ZtV3p06d4p577gEgNTWV3bt311g9e+zYsfzyyy8sXbqUFi1akJycDEDLli0dfndfIpFIJBKJRCKRSJwN1SfEl1xyCfv27SMiIoLXX3+d8+fP07RpU0JDQ5k0aRJjxowxW++9997DYDDw+OOPk5eXR58+fVizZg0BAQE1yv3vf/+jqKiIfv360aRJEyZOnMhzzz2Hm5sbv/32GxMmTKBXr15ceumlzJkzh+uvv96uhtuLu7u7zTz8/PzYvHkzn376Kbm5uVx88cV89NFH3HbbbQC88847tG3bllmzZnH69Gn8/f25+uqrmTp1atU2cnJy6jyaXp1Tp05RWFhY447wZZddxltvvUXv3r05duwY/fr1o02bNlX/f/78+QB1+uy7777jySefFOgViUQikUgkEolEInE93IzG/34LSNKgGDFiBAMHDmTy5Ml6pyKRSCQSiUQikUgkTokmq0xLnI+BAwfy8MMP652GRCKRSCQSiUQikTgt8g6xRCKRSCQSiUQikUgaJfIOsUQikUgkEolEIpFIGiWqF9VqTOzatQuoXMAKKhcUA+jbt69uOUlcC6khiShSQxJRpIYkokgNSUQw6QekhiT2YcmDQBsNyRNiBbRu3VrvFCQujtSQRBSpIYkoUkMSUaSGJKJIDUlEcJR+5AmxAjIyMgDw9/fXNxGJyyI1JBFFakgiitSQRBSpIYkoUkMSERylH6c8IS7/LBJjYrLNcm5BgXhMNP+7x1qi9mrE2/sgvkBZ2RBfeOsqO5JyYHyl/Q+O2wdK22Cp/0Q1JBq/NvKKqEQUR/mQIzxITXxLOejtQ86Qv/QhibPRUH3IUXMJUfT2IUfMZ6UPSURoVHeIjYnJcDTWdrl6yAXUX42IL4D9mQ5MyMHxlfY/OG4f1FcbLOWv9T6UV0QlokgfslLW/jAWcYb8pQ9JnA3pQxbK2R/CKnr7kCP2n/QhiQiO0o9cZVoBAQEBBAQECG8ne9dyDbJx3fgNAXv7UCsNSRov0ockINZ/0ockomihIb09QO/4DQHpQxK9cJR+HHpCHBMTQ0REBKNGjeL333/niy++IDs7W/V2IuNO1Phb3xQUFFBQoPCZkVqk/j2H5MWzKTpzkOJzhylJOaN6G2u2xfNU+GaidiXpEl+0/+OT8xk1fQtzfzmMvT97Xb0d9iDSBi36UERDEgno60MGg5GPfjjI829vJSWjqN7jg7gPifgouL4HgfQhiTj2akgLDWfnljBh1nbeXrCP8nJDvccHsXFc5aMz7PNRkD4kkThKPw49IV60aBFTp06lS5culJSUMHToUI4ePap6O8WGCuacPk5URpoDsrSNl5cXXl5edtWtKM6nWccwvENC8e4YRtP2nVTVP3g8k/+9sZnvl53gkdc2cfp8br3GB7H+NxiM3DH2H75efJwpn+7iw+/tM/Hq7bAHkTZo0YciGpJIQF8feityL2/M3cOXi2K5Y+w/9R4fxMZwDR99fRNx5/NUb8PVPQikD0nEsVdDWmj47pfWMffXo8z8Yh9jI7bXe3wQG8dVPrrQPh8F6UMSiaP042a095adAiIiIvD39ycqKop7772XzMxMHnzwwTq3ukePHk1CQkLV53fwIpQmVZ8j404wpnO3qr8mjlDBNEodlT79+vUDICcnB4CWLVsCEB0dbbVe2vBZlAWGAWA0GMg7sIHihFhaDXoQD782Ncp6Jh+m7fLXLW7rfP5F7Evv/d8nI9e020E7H+tGJhpfaf+D7X1QYXBnQ8Iwiit8AOjgk0Cfdrut5l+7DbXb0e6OsVbzV9MGS/kr7UNb+89eDUkkJhztQ7Y0DBCd0o+Uog4ANPMoYFjwOtzcrOftTD5U00cNXNPuX1U+WrsN1T3IkfmbchA9jkgfkogi6kOiGgbYmHAD+WV+ALTxTuW6wB028xaNr+V8tLqP+ngUMFSlj0L9+5BW81mTfkD6kMQ+LHkQmNdQcHAw8+fPV7x9hy6qNXXqVABSU1N54IEHLJarnXDZlDcVLQIQ2jOUZe/PEEvSCqYfgY6PjwcgJCQEgPDwcKv1nt16YRGCrC2/UZJyGu+Q0DrmARAWGsbXzy2zuK28glJuHLWKmNhMeoe1Yf1XX+Dd1PpuE42vtP9B2T54Knwza7afJ7egjJXfj+XKHrZXiKvehtrtsJW/mjZYyl9pH9raf/ZqSCIx4WgfsqVhgK17k3ly2mbOpxTw9D19mDd1gs28ncmH8gpKGfbsKg4cz6R3WDvVPlq7DfWVvykH0eOI9CGJKKI+JKphgOmRe/h68XEyc0v4ctbD3D3M+gm0FvG1nI9W99Gn7PBRqH8f0mo+a9IPSB+S2IclDwJtNFQvq0xPnz5dqL7pKlbtq1n1ha+vr911Ww15RCh2C18vtv90J7eN/odV82+mSRN1T7mLxgfx/v9u5mBSM4p46s0tik6GzSHaDpE2aNGHIhqSSEBfHxp4dSAHFt7D3S+uY97U/vUeH8TGsMlHbx9jn4+C63sQSB+SiGOvhrTQ8PQxvZnwaC8ee30Tdw/rVO/xQWwci/ooSB+SSBylH7nKtAKysrLIysrSLX6TJu54N21i1yTOWWjXuhlN3G08G9SA0VtDEtdHbw35NPOgqVcT2wWdFA8P1/dRUfTWkMT10VtDrVo2xcOFx7Cr+6gW6K0hiWvjKP045e8QOxvyR8QlokgNSUSRGpKIIjUkEUVqSCKK1JBEBEfpR54QK0D+iLhEFKkhiShSQxJRpIYkokgNSUSRGpKI4Cj9OOUJsVtQIEqWvnYLCnR4LqD+akSIisfb1ZStr/hK+99U1hEobYOlcqIaEo1fG3lFVCKKo3zIER6kdrvO6EPOkL/0IYmz0VB9yFFzCVH09iFHzGelD0lEaFR3iD0mjtE7hRqovRrx1lUOTKYe4jtD/+vdBq33obwiKhFF+lD94gz5Sx+SOBvSh+oXvfN3xP6TPiQRwVH6cd2VCSQSiUQikUgkEolEIhHAKe8QOxvy8Q6JKFJDElGkhiSiSA1JRJEakogiNSQRoVE9Mu1syMc7JKJIDUlEkRqSiCI1JBFFakgiitSQRIRGtahW+WeRGBOTbZZzCwqsl/c71F6NeHsfxBcoKxviq/07Gkr7D8z3od75A2x5cR55cbbb0KJzIIM+HVfn+8aiIUf1v6gGRDUoihYaFtWQ1vvQ1TTk6j6k1IPAvA/pPQbM4WoaEo2v93FAbx91xBhyNQ05m4+rpbH7kN7HATU5uLoP6T0XspZDdRrVHWJjYjIcjbVdrh5yAfVXI+ILYH+mNrETUwv49P8Os/NgKm/M2c2ER8No37qZ1TpK+w/M96GW+RcVl/P90uOs2nqefccyOXA8k8u7t7JZLy8umdToY3bHlRoSQzS+qAZF0aL/RDWk9T7UU0N7jqTz2f8dJvpgKt8uOc6jd1xCU68mVus4kw/Z46P15UEgfchR8fU+Dujto47Yf3ppqLzcwOL1Z/hl5Sn2HElj854kBl0diJubm9V6zuTj9vhoY/chvT1Iixwaiw8561xIKXJRLQUEBAQQEBAgvJ3sXctVlf9j9Wl6P7SUD384SGpmMe99G8NV9y9hxeZzwrnUB2cT87jsnsW8PDuav6PiOZ9SwLBnVzIuYrveqdU7emlIa/SO7+qI9J8eGjIajTz5RhS3PL+an5afJCWzmHER27n83sUkpRUK51IfWPLRlS7io1qihYacwQOcIQdXRm8fUhs/O7eEqx/8i6ff3MLSjedITCvironruHPcWioqDEK51AdGo5EnXNxHtaQh+JDe8RsC9vahVnOh2jj0hDgmJoaIiAhGjRrF+++/z7x58+zaTmTciRp/1bJ43Rne/yaGvIJSu+oXFBRQUKDwfn8tUv+eQ/Li2RSdOUjxucOUpJxRVC8zp4QXZ+8kOb0IoxEiw/tjMEBSehHPz9hGQWGZ4hxE+696G9Rw78sbOHU+j+LSisr44f1Jzy7h5xWnWLsjQdW2eo29C+/WfnR9aKiqeiZE+0AUPTRUnU3RicxYsI/kdPUHXy3ii/b/uaQ83l6wj+37U+yqD/br2IS9bdCi/0AfDS1cG8fiDWfJyCkBKsdwUUkFx8/m8uCrG1TloIcPZWQX8+IH/5r30XfU+SiI+ZDeHgT2a0gLDRsMRr5edIy5vxymrEz9SYwz+NCm6ETe+cI+HwX9PKh2bD18SCT+029u4dDJLAqKyoHKcZyVW8qG6ETm/HxYVR56+NDCtXEs0chHQfqQiIazckuI+Go/y6PO6hIfxPaBqI+C6/uQyFzIGg49IV60aBFTp06lS5cujB49mubNm9u1nWJDBXNOHycqI0113Y++P8iT0zbz2me7uW30Grvie3l54eXlZVfdiuJ8mnUMwzskFO+OYTRt30lRvW+WxJKaUVT1ObidT9W/07KK+WXVacU5iPQf1GyDUk6fz+V8Sk3BmtqQnVfKrK9jVOWQtPUgfaY9zqmFUarqmRDtA1H00JCJVVviuf/VDbwVuZdho1ZRVFxer/FBrP9z80u5+fnVTI/cyz0vrWPrXmXvQ9XGHh1Xx942aNF/oI+GPvrhEHkFF04aq/vQyfhcUqp5lC308KFvFseSmllc9bl6/qmZ6nwUxHxIbw8C+zWkhYZHz9zGmIgdvDT7Xx6eslGXHET2gclH3/x8LzeOWkVxiTofBf08qHZsPXzI3vjFJeXsOpyGsdrzmKZxXFRSwdeLj6vKQw8f0tJHQfqQvRo2Go3c9Nxq3pi7h8embubrReoeRddqDInsg+o++uhr6n0UXN+HROZC1nAzGo0Oe20gIiICf39/oqKimDFjBgsWLGDmzJn4+vrWKDd69GgSEi7cMXwHL0K58F5FZNwJxnTuVvXXxBEqmIb1u77RKf1IKeoAQLMmBQy7aB02Xjmpol+/fgDk5OQA0LJly8ptRkdbrZc2fBZlgWEAGA0G8g5soDghllaDHsTDr02Nsp7Jh2m7/PU624hJv4Jz+Z2IDO9PcDsf+vVqS/ShSvElpBby0ZzvCW111Gx8pf0H5vuwev6129DujrGK8s8obkV0yjWUG73qtCEhtZAp76/i+uBNZvMHGHzUgzb5Na/X9Hj6No59u6rGd+nNDWzuWXdioqWGRHC0hiz1f3UOZlzGmbwuleXdSxjcYTM+ntbvcIhqWFSD1ckp9WNb0kAqjJ4AdG95jEsDrL/PUlvDtdtRXceW+lBUQ6Yc7PUAE3pqaGPCDeSX+ZkdwxMjNtI/cDt+Xrlm6zqDD4n4qDkPAuU+pOUYEEVUQ6IaBtiWNIDMksp6Lb2yGBy02WbeohrW8jhQ00eL//NR6ycyohrWcgzp7UP2xi8ub8rmpCGUVDQz60OT3vuHYRettxhfKx83ofY4AtZ99MWIjVxnxUcbig+Z9APqNKSlhssNTdiYMJTiisoLEh18EujTbrfN3EU1rKUPVfdRP69shgTZvigiqmEtx5DIPrTkQWBeQ8HBwcyfP9/stszh0EW1pk6dCkBqaiqXXnopn3zyidlytRMum/Kmohe4Q3uGsuz9GVbL/L3pHGPe3UZyehEjb7qMXz+YoDB72LVrFwDx8fEAhISEABAeHm613rNbL7xAnrXlN0pSTuMdElpnxwOEhYbx9XPL6nz/w9LjjJ65nTEzK9+3XTrnRkZOWAdACx8Pfnh3NHcP62Q2vtL+A/N9WD3/2m1Qmn9qRhFXPfgXiamFZttw301X8OdHL1vMa+XI8LoLSZi5dhMaGsqkpTPrfK+lhkRwtIYs9X91Dp/MYsSEtZxNzGfA1Rez5qtfaNLE+sMhohoW1WB1SssquP7plRw8kYnRCKt/fZPOF7VQnL8JSzq21IeiGjLlYK8HmNBTQ7c8v5p/diSYHcMXtW/FsoXf4tfc/JVaZ/Ch7/46zth3Lfvoj++O5i4LPmrWg0CxD2k5BkQR1ZCohgE+/uEgH3x3gMzcUl54bAjvvTjJZt6iGtbyOFDTRzux5qvRqny0dhtq4wgf1WIuYkIvDZWXG+h6xx+cTSowO477hHZi2W+W89bKx02oPY6ALR8NsOqjDcWHTPoBdRrSUsMAIyasZdOuJMrLDfw6dxRD+r5pM3dRDWvpQ9V9dPRjg3nvxVcU529Cr7lQ7dhq96ElDwLbPqSEelllevr06UL1TVcgal/NUsKd13ekT1gbHp68kV/ev96u+LXvaKuh1ZBH7Kr30G2XMH3BPs4k5AOVdzNMtG/jw4jrOyrelkj/gX1taNe6Gb17tiYlvYgKQ6Vxm9rQrpU300dfrXqbx75brbqOCdE+EEUPDZkI6xrArl9HcveL6/jni9tsTuK0jg9i/e/l2YRN397O4ZNZTJ2zx+bJsCVE22FvG7ToP9BHQzPGXs3eo+mkZ1e++2Yaw54e7gy6ur3FSZw59PChh2/rwowF+ziTWNdHA9v4cKcKHzVhrw/p7UFgv4a00PDLT1zG3cM68cxbW3jvxb665CCyD0R9FPTzIC1im6hvDXl4uHPvTZ2Z/8dRioor1yMxjWN/Py/Cn79S1fb08CHrPhqoykdNSB+yj78+vZFDJ7N49aNohvTtUO/xQWwfiPoouL4PicyFrNEoVpnu0NYHv+ZeNpfnt0RWVhZZWVkaZ2Wdpl5NWDHvZrp19KNlc0/GzNyOfwsvenRuyer5t9h1MK5vfn3/Bob0CaRdK28AXvrgXy5q78unk68lrKv2K8Q5M3poqDqtWjalZXMvPD2dXzfm8PJswlU92+Dp4Zr5a4EeGrrm8nZETOhDcDsfvDzdGTNzO+1be3PjtUF8O2NQveZiD95NPVjxuXkfXeUiPqolevtQ54ta0NzHU7f4ori6j2qBHhr64KW+jLi+Ix3aVP5U2oRZOwhu58OrT1zGyBsurtdc7OGay9vx7oQ+XNTeNX1Ua/T0IXd3Ny7v3srmz105M67uo6I4Sj9O+TvEzoajfgTaFqGXBHBs2X1s2pXE8bM5hHbxZ1Bv27+75yz4+niy/uvbOXo6m817kmjt780dg0Jo5t34ZKeXhiQNB700NOq+Hjxy+yWs2BJPdl4pN/TtQLeLW9qu6CS4uo9qifQhiSh6aKhJE3d++2Ao8cn5/LM9gaZeTRg+OAR/v6b1nou9PHdfDx51YR/VEulDEhEcpZ/Gd2ZiB476EWgluLu7MfSaIIZeE1TvsbWiZxd/enbx1zsNXdFTQ5KGgZ4a8vXx5IFbutR7XK1oCD6qBdKHJKLoqaGQwOY8c8+l9R5XK1zdR7VC+pBEBEfpxylPiN2CAlGy9LVbUKDDcwH1VyNCVDzerqasUpT2n6lsbfTOH6BFZ2X71lK5xqIhR/W/qAZENSiKFhoW1ZDW+9DVNOTqPqTUgyyV1XsMmMPVNCQaX+/jgN4+6ogx5GoacjYfV0tj9yG9jwNqtuvqPqT3XEhpWUfdIXbozy45EyPGr2XZ3JtU1TGtaHbq1CkALrnkEgD69rXvRXZJ48OZNGTPGHA2GkIb1OJMGpK4Js6kIVcfw66ev704k4Ykrkf1VaadQUOuPo5dPX97sORBoI2GGu/KEBKJRCKRSCQSiUQiadQ45SPTzoZcAEAiitSQRBSpIYkoUkMSUaSGJKJIDUlEkItq6YhcAEAiitSQRBSpIYkoUkMSUaSGJKJIDUlEaFSLaj01bTMnz+XaLNe1ox/fvTPY4fmovRrx9j6IL1BWNsQX3rrKjqQcGL/8s0iMicmK6rsFBeIxcYzKDG2jtA2W+k9pGyzlLxq/No7SkCP0A+Ia0HsMbHlxHnlxyvJv0TmQQZ+Oq/O9qIa0xtU05Oo+5Az5Sx9yLh9Xi6gP6T0GzOFqGtJ7LiGK3j7kiGO5Gg3pPZeAxuNDDXUupBSnPCE+eS6XrftSNNnWuaR8vlkcy8ETmazdkcCN1wap/v1JtVcj4gtgf6baTLVDNL4xMRmOxiora38Yq9RXGyzlr/U+1FND6VnFfLPkOAdOZPLnmtPcPawTHh7Wlw8Q1YCW+ZeWVfDHmji270/hVHwuWbklBNj4/cm8uGRSo48JxRXVkNZIH7JS1v4wFnGG/BuSDx06kcmPf5/g0Mksdh9Oo09YW5t1nMnH07OK+WZxrCofFfUhvceAOaQPWShnfwir6O1Djth/ajSkZXyDwcjKLfGs2nqe42dySEwtIKid7WWNncmH7PHR+vIhZ/UgpTToRbWmztlFv0eWMeOL/ZxJzOeBSRvo/eBfZOWWqNpOQEAAAQEBwvlk71ouvA1Xjt8QsLcP9dLQt0tiufy+xUyds4uzifk89eYWQu9axJmEPOFc6oPYuGx6jFjE8zO2Mf+PYxw9nU2vuxfxx+rTeqdW70gfkoBY/2mhIbXxDQYjD07awNBnVzH7+0PEJeRx6+g13PzcKsrKDEK51BffLonl8nsXM3Xubpf0US3RQ0Nao3f8hoCr+VBqRhFX3LeER1/fROTvR4k9m0Pvh5by3jcxQnnUFwaDkQdc3Ee1Qqu5UG1c4oT4mXu6E9zeh0lPXqa4zj/bz7Pgj2OkZBQBEBnen+y8UvbHZvLw5I2q4hcUFFBQoPCZjVqk/j2H5MWzKTpzkOJzhylJOaN6GwkpBfy66hTJ6YW6xI+MO1Hjr1qKS8r5c81pYmIz7KoPNdthDyJt0KIP9dDQyXO5TP1sN0lpRRgMlWOgoKicE+dyGTFhLWp+cU1UA/bsP4PByIgJa4lLyKOwuByAz8P7k5hWxMQP/iUxVV1/9hp7F96t/ej60FBV9UyI9oEoevvQ7sNpLFobR2lZhS7xRfvf5KOmY4JaXN2DwH4NicT/6IeDLN8ST1pWMVDpQxnZJWzek8yrH+9UlYcePnTibA5T5+wmKV3cR0HMh/T2INBHQyYqKgws23iWLXuUPQKsdXwQ3wciPgrSh+yNf+/L6zl0Movc/DKgchwnpxfx4Q8H2XkgVVUeevjQRz8cZIVFH41WnYMr+5DIXMgaDj0hjomJISIiglGjRvHuu+/y0UcfkZ+fr3o7Py47yfzwAfy4THnnz/xyP1m5pVWfg9v5AGA0wsETWaT/JyoleHl54eXlpTzhalQU59OsYxjeIaF4dwyjaftOquqfTy5g8FMreGTKJoY8tYK0THWTOdH4AMWGCuacPk5URprqukajkVteWMODkzdy43Or+WONfXf2qrfDHkTaoEUf6qGhWd/EkJJ5QeemMQCQmFbIvqPKL1CI9B/Yt/8270mukT9caENKRhGf/HRIVQ5JWw/SZ9rjnFoYpaqeCdE+EEVPH/pmcSy3PL+aB17dwJ3j1tZ7fBDr/+o+OvjJ5ap9FFzfg8B+DYnE/3pxLIVF5VWfTWO4pMzAkg1nVZ1Q6uFD7317gJQMbXwUxHxIbw8CfTRk4tHXNnHvKxu4Y9wa3v1yf73HB7F98PWiCz46Yrx6HwXpQ/bEP5eUz8n4musSmcZxRnYJ0+fvU5WHHj5k3UfPqL4w58o+JDIXsoabUW0vquDNN99kxowZzJo1i7Fjx/Ltt98ybtw4PDxqvro8evRoEhISqj5vSxpAZkmbqs9tW3kzZ8p1hM/bzan4C48otWqazoAO28zG3phwA/llfkSG9ye4nQ/9erUl+lAaCamFTIzYyHWB22npZX3hrn79+gGQk5MDQMuWLQGIjrZ+NSZt+CzKAsMAMBoM5B3YQHFCLK0GPYiHX5saZT2TD9N2+esWtxWffxH703v/98lIv3Y7aO9jXYSi8d/Bi1CaVH2OjDvBmM7dqv5W5wgVTKMUS5QbmrAxYSjFFZWDt4NPAn3a7baaf+021G5HuzvGWs1fTRss5a+0D23tP0dryFr8rUkDySppbXYMjJ25lavb7ibIN8lsXVENKN1/1tpwJu9iDmZcWRnfTBve+nAJ1wb+azb/wUc9aJNf93pfj6dv49i3q2p8l97cwOae5XXKimpIK/TUkInolH6kFHUAoFmTAoZdtA5bSzE4kw/V9tFr2u2gnQofrd0GJRrWIn9TDqLHEVENicRfG38TxRU+ZsfwS7PWMzR4PR7u5u+WaenjoP44ArA1cSBZpfb5qKgPaTkGRNFTQyY2JdxAXpkfAG28U7kucIfNvEXja3kcEPVRqH8f0mo+a9IPqNOQFvEzilsRnXIt5UZPs+N4yvuruD54k8UcnMGHrPnoy7PWMzR4HU3czT86rdSHXHUuBOY1FBwczPz58xVv36GLanl7exMZGcn+/fv59ttvad68OaWlpXVOiGsnPOiJ5TUW1Xrsjq48ER7FxMfCmP3dhUcMQkPDWPbDFLOxr39qBVF7khkzczsAS+fcyMgJ6wAIahvA4t++prW/t9X8d+3aBUB8fDwAISEhAISHh1ut9+zWCy/QZ235jZKU03iHhNYZvABhoWF8/dwyi9tKTC1gyFMrORmfy6Wd/Fnxw+e0CbCet2j8silvKl6EIbRnKMven2Hx/xuNRoY9u4qoPUl4NHHn83f/x93D3rS53eptqN0OW/mraYOl/JX2oa3952gNWYv//IytfLkw1uwYaOPfjK8/j+DKHuZX6xPVgNL9Z60NW/YkM2LCWrLzSuu0wc0NXn3yRt5/aarZnFaODDe/iISZ63+hoaFMWjqzzveiGtIKPTVk4oelJ5j00U7Ss0u4/rpL+Ttygs28ncmHElMr7xCfis+jRyd/Vvz4uU3/F9WwFvmbchA9johqSCR+jxELiT2TY9aHLu7QlhV/L7a40KWWPg7qjyMAz729la8W2eejoj6k5RgQRU8NmXj0tU0sXBuHwWDk1RfuYPLT1k+gtYiv5XHgh6UneOWjnWTa6aNQ/z6k1XzWpB9QpyEt4p9PLqDfI0tJSi8yO47vGBTGss9ftpiDM/iQLR9d/vcSiz6q1IdcdS4Etn1ICQ49IZ46tXKympqayosvvmj3dkyPRlY/GbbFmy9cxf2vrCczt+bVCnd3uLJHa5uToer4+tpehc4SrYY8YnddgKB2vmz9cTh3jvuHlZG32DwZ1jo+UHUFqPbVRCW4ubmxav4trP83kdk/HOTuYZ3sykG0HSJt0KIP9dDQlKcvZ+nGc2bfmbyova/FSZw5RPoP7GvDwKvbE9imGdl5da84BrZuxkuP91K9zWPfrVZdx4RoH4iipw89MbIbfcLa8PRbW1g256Z6jw9i/R/UzpdtP95Z5aNq/N+Eq3sQ2K8hkfgv3N+DafP2kF9U886Dd9Mm3HdTJ1W/+qCHD015+nKWbTLvo8EqfdSEvT6ktweBPhoy8VPEEJ4a2Y0ZC/Yx+enL6z0+iO0DUR8F6UP2cFGgL5d2aklSet0x3Ma/KdPHXK1qe3r4kDUfvf9mdT5qwlV9SGQuZI16WVRr+vTp9RGmBkOvCWLiY2EEtmmGmxskpBYS4OdF79A2/Pr+9aq2lZWVRVZWlmMSVUD71s0IbOOj+mTYWWjq1YTbB4fQwsdT71R0Qw8NdbnIj48m9SOorQ8eTdxISC2kha8nl3ZqybK59h2M6xM3NzeWz7uZriEtaO5Tee0uKb2Q4HY+zJ82gMA2Pja20LDQ24fCugbQvlUzmz8146y4uo9qgR4amvhYGHcNu5h2rSr7PSG1kLYB3gzt14H3Xuxbr7nYwyUhlT7aoW2zOj76twv4qNbo6UPu7m7ceF0w/jZ+ds+ZcXUf1QI9NLTw42FccWkr/FtUvnuamFpIYJtmTB11paKfLtKbiY+FcddQ8z46a6Lz+6iWOEo/Tvk7xFrx5gtXM+reHvyw7ARx53NZ+tmNDLw6UPWVFEf9CLSk8aCXhh69oyt3DArhx79PcupcLj/PGsLtg0Jo0sQ1DsaXhPhxdOl9LN14lh0xqRgMcHTpvbTw1X5BBWdH+pBEFD005Obmxk8R13PibA4/rzhJfFIB67+6jcu6t6r3XOzF1X1US6QPSUTRQ0Ot/b3Z98ddbIhOYvXWePILyziw8G7atmpW77nYg5ubGz/Ncm0f1QpH6adBnxADdGjrw2vPXCG0DUf9CLSk8aCnhvz9mjLh0TDbBZ0UDw937r2pM/fe1FnvVHRF+pBEFD011O3ilkwf09t2QSfF1X1UK6QPSUTRS0Nubm4MuyaIYdcE1WtcLXF1H9UCR+nHKU+Iu3b007ScKGqvRoSoeLxdTdn6iu8WFIjSpcfdggKVB1OB0jZYKqe0DZbyF41fG0dpyBH6AXEN6D0GWnRWrktLZUU1pDWupiFX9yFnyF/6kHP5uFpEfUjvMWAOV9OQ3nMJUfT2IUccy9VoSO+5BDQeH2qocyGlOPRnl1wd04pmp06dAuCSSy4BoG/f+n9ef8T4tS7x3qc1GkIb1OJMGpK4Js6kIVcfw66ev704k4YkrokzacjVx7Gr528P1VeZdgYNSVwPSx4E2mjIKe8QOxvynRmJKFJDElGkhiSiSA1JRJEakogiNSQRQb5DrCPynRmJKFJDElGkhiSiSA1JRJEakogiNSQRoVG9Q+xsyKtZElGkhiSiSA1JRJEakogiNSQRRWpIIkKjukNc/lkkxsRkm+XcggLxmDjG4fmovRrx9j6IL1C27RBfeOsqOxOzgNL+A/N9qHf+AFtenEdenO02tOgcyKBPx9X5vrFoyFH9L6oBUQ2KooWGRTWk9T50NQ25ug8p9SAw70N6jwFzuJqGROPrfRzQ20cdMYZcTUPO5uNqaew+pPdxQE0Oru5Des+FrOVQnUZ1h9iYmAxHY22Xq4dcQP3ViPgC2J+pTeyKCgOrt53nVHwuq7ee5+b+wbi7W/8dZaX9B+b7UMv8AfYfy2BDdCLxyfnkF5bR3MfTZp28uGRSo4/ZHVNqSAzR+KIaFEWL/hPVkNb7UE8N5eSVsnj9GU7H53L4ZBZhXQNs1nEmH6ruo2u2neem62z7aH15EEgfclR8vY8DevuoI/afnho6FZ/Lii3xnE3KJz2rmDYB3jbrOJOP2+Ojjd2H9PYgLXJoLD7krHMhpTS+X5W3g4yMjKorEiJk71quqnxMbAbd71zIQ5M3cuR0Ng++uoEeIxYSG5ctnEt9kFdQyqAnlnPz86t55cNoYo5n0mPEQr5felzv1OodvTSkNXrHd3VE+k8vDc379Qhhdy/iube3cvh0Njc8u5IbR62kqLhcOJf6oLaPPjCp0kePn8nRO7V6RwsNOYMHOEMOrozePqQ2fnm5gXteWsfA/y1n4nv/cuB4Jpfft5hp8/YI5VGfzP3FtX1USxqCD+kdvyFgbx9qNReqjUucEEfGnajxVy3nkvLZfTgNg8G+6y8BAQEEBNi+kmeO1L/nkLx4NkVnDlJ87jAlKWcU1SsuKWfkxHWcPp9HfmE5keH9yS0o48S5XO4Y9w/l5QbFOYj2X/U2qOGhyRvZHpNCWlYxAJ+/0Z+E1EImf7yLA8fVXS7qNfYuvFv70fWhoarqmRDtA1H00FCNbWQUsfNAKqVlFbrEF+3/4pJy/o1JJf0/LdmDvTo2YW8btOg/0EdD2/enMH3+XhJSCymvMBIZ3p+0zGKidifzZPhmVTno4UPFJeWMnLDWrI/ePnaNKh8FMR/S24PAfg1ppeHYuGwOnbDvVoEz+JCIj4J+HlQ7th4+JBJ/0kc7WbX1PMkZRQBEhvcnKa2Ieb8eYfE65dsBfXxo+/4U3l6gjY+C9CERDVdUGNh1KI2EFIXP8GocH8T3gYiPguv7kMhcyBoOPSGOiYkhIiKCUaNG8cknn/DJJ5+QkpKiejvFhgrmnD5OVEaa6rqL15/huseWcf3TK3hg0gbV9QEKCgooKFA/eAAqivNp1jEM75BQvDuG0bR9J0X1fll5mpT/zB8guJ1P1b9TMopYuvGs4hxE+g9qtkEpyemF7D+WiaHafNPUhrSsYqZH7lWVQ9LWg/SZ9jinFkapqmdCtA9E0UNDJmJiM7nm0WVc//RKhj27SvVJgGh8EOv/ktIKhjy1khueWcm1jy3j5Dn77uzZo+Pq2NsGLfoP9NHQm5/vJSO7pOqzaQyXVxjZHpNKTl6p4hz08KGfl58iJfPCRRQRHwUxH9Lbg8B+DWmh4fe+iWHgE8sZ9OQKXpm9U5ccRPaBqI+Cfh5UO7YePmRv/LIyA0s2nKW45MJFCNM4zs4r5d2v9qvKQw8fsu6jKap8FKQPiWj4zvFrGfL0Cq59bBnr/k2o9/ggtg9mfR3DAAEfBdf3IZG5kDUcekK8aNEipk6dSpcuXXjmmWfIzc3Fy8tL9Xa83ZswoUt3hrRuq7ruD0tPkJhWREFRBXuPptt1l9jLy8uuvAEC730NNw8v0lYvoPml1yqu9++B1BoHgOrkF5az63C64m2J9B/UbINSTp7LpaCozPL/j89VlUNGzCnSD5zGWG7flXnRPhBFDw2Z+GrRMc4k5lNcWsHRuGzOJefXa3wQ6/9jcdkcjcumuLSCU/F5/LjspF052KPj6tjbBi36D/TRUGJaocX/V1xSztkk5VrSw4d2HrTuo7tV+CiI+ZDeHgT2a0gLDa/cEk96dgnZeaVs2p2kSw4i+6C6jx6LyyY+Wf2ETC8Pqh1bDx+yN35GTjFlZZYvPqg9mdTDh6z7aIUqHwXpQ/ZquKCwjIMnMikqruB8SiFfLlT2brVW8U2I7IOVW+LJEPBRcH0fEpkLWcOhi2p5e3sTGRnJ/v37iY2NJSAggNzc3Dq3ukePHk1CwoUrNe/gRShNbG7/yNEjTBsxwmqZ07md8XDrQbnRk5z0M9x110jF+ffr1w+AnJzKO1ItW7aszO+dd6zWSxs+CwLDAMja8hslKafxDgnFw69NnbKHjxxmxAev1/n+ZM4luNGTz8MHEdzOh3692rJ0zo0AJKYWMH9+JEc2mM9Daf+B+T6snn/tNijNv7DMh+LCQYA3keH9a7QhIbWQaR/+xQgr+27wUQ/a1L5eY6x7MePIkSMsMLMdLTUkgqM1ZKn/q5Na2AYv9z6UGppSWpDK+Bf+RxN363c3RDUsqsHqlBs8MJYMBlrgTjkbls1h/z9ZivM3YUnHlvpQVEOmHOz1ABN6aigpcRDQyuwYfmnWel596TmaNjE/IXUGH7Llowvmf85hCz5q1oNAsQ9pOQZEEdWQqIYB4jMuw52LMeBO8tkYRoz41mbeohrW8jhQ3UdLClIZN/pxmrgp99HabaiNI3xUi7mICb00VGFwJytrGOBj1ocmv7/a6lxCKx83ofY4AmI+2lB8yKQfUKchLTVsNEJ+1mAgADcqOLFnISNGfGozd1ENa+lD59PFfBT0mwvVjq12H1ryIDCvoeDgYObPn28zbxNuRqOZUaUx06dPZ/r06YrLl015U9mqeD0vxfP9GTaLrdwSz+SPd7Hz5zvxVbDCsYldu3YBEB8fD0BISAgAffv2tVrv2a3KV1S7shV8PbDu99m5JYTdvbjqyuLSOTcycsI6AC5q70PssvvxaWb+eobi/gOzfahF/gDXPLKU6EMX7sCY2hDg58XCj4Yx9Jogi9tdOTJc0cqK7fr14PalM+t8r7WG7MXRGrLW/9XZEZPCs29tZdO3t9O2VTOb5UU1IKrB2iSmFvDLylMs23SOzd8Pt7lJLTQsqiGt9qGeGlqy/gxPTttMbn7l0x7Vfej6PoFs/PYOi9t1Bh/K+s9Hk+zwUaUeBOZ9SOsxIIIz+JDRaOTXlad4/7sD7PntLjw8bD+gJhpf6+PA9v0pjJruOj6q1bEc9NXQA5PWs2jdmapXsEzj2KdZE96b0Jfxj4aZr4hz+LiIjzYUHzLpB9RpSEsNQ+UTBd8tPc7vq06z42dlJ//O5EPVfXTv73fRpInz+6hW+9CSB4FtH1JCvSyqpeZk2BHcPiiELhe1UHUyXB1fX198fX01zso6/n5N+fyN6+jQphnu7pCQWkgTdzeC2vrw7YxBFidxzsTCj4fRraMfPt6VV5YSUgtpG+DNU3d1t3oy3BDRQ0PVue6K9lwS4qdoEueMBLXzZdKTl+PfoqneqeiGHhq6a+jFPHRLF9oEVPZ7Qmohvs086NG5Jb/Ptm+Bu/okwK8pkS7uo1qipw+5ubnxyB1dubhDC0Unw85I/ytd20e1QA8NfT19EFd0b00L38o5XEJqIa1aenHLdRcx9mH73oOsT+4aejEPmvHRni7io1qjpw+1bOHFi4/1ctkxXN1HlZwMN0QcpZ/GNRuwk6ysysczW7VqVa9x7xraiQFXtufz346wYWcib4+5itEPhtKqpWucFIQENufg4nv4bdUplm+O59CJTDZ/fwc9OvvrnVq9o5eGJA0HPTTk5ubGF28NZPwjocz79Qgbo5P46q2B3HdTZzw9XeNg7Oo+qiXShySi6KEhv+Ze7Pp1BCu3xPPLytNEH0xj9fxb6dtLv/dg1eDm5saXbw1kggv7qJZIH5KI4Cj9yBNiBTjqR6CV0LZVM6aP6a1bfFGaejXhiZHdeWJkd71T0RU9NSRpGOipoV7dWrHgTQXP5jspru6jWiF9SCKKXhpq0sSdO6+/mDuvv1iX+Frg6j6qFdKHJCI4Sj9OeULsFhSIkheb3YICHZ4LUPUD0P7+/orKh6i4k6+mrFKU9p+pbG30zh+gRWdl+9ZSucaiIUf1v6gGRDUoihYaFtWQ1vvQ1TTk6j6k1IMsldV7DJjD1TQkGl/v44DePuqIMeRqGnI2H1dLY/chvY8Darbr6j6k91xIaVm1HqSUellUyxkYMX4ty+bepKqO6QXu7Oxs4ELna/HytqRx4EwasmcMOBsNoQ1qcSYNSVwTZ9KQq49hV8/fXpxJQxLXo/qiWs6gIVcfx66evz1Y8iDQRkNOeYfY2XDU1QhJ40FqSCKK1JBEFKkhiShSQxJRpIYkIjhKP43vbX6JRCKRSCQSiUQikUiQd4gVIRcAkIgiNSQRRWpIIorUkEQUqSGJKFJDEhEa1aJaT03bzMlzuTbLde3ox3fvDHZ4Pmpvz7+9D+ILlG07xBfeusrOxBwUv/yzSIyJyYrquwUF4jFxjMoMbaO0DZb6T2kbLOUvGr82jtKQI/QD4hrQewxseXEeeXHK8m/ROZBBn46r872ohrTG1TTk6j7kDPlLH3IuH1eLqA/pPQbM4Woa0nsuIYrePuSIY7kaDek9l4DG40MNdS6kFKc8IT55Lpet+1I02VZZmYHNe5JJSi8kOb2QwDY+qreh9mpEfAHsz1QdRjNE4xsTk+ForLKy9oexSn21wVL+Wu9DPTVkMBjZEZNKUnohp8/n0uUiP5t1RDWgdf8dP5PD4VNZZOWWYDQacXNzs1o+Ly6Z1OhjQjFFNaQ10oeslLU/jEWcIf+G5EMFhWVE7UkmOb2QnLxSWrbwslnHmXzcHh8V9SG9x4A5pA9ZKGd/CKvo7UOO2H9qNKR1/PPJBew+kkZ6djEVFQaaNLH95qgz+ZA9PlpfPuSsHqSUBv0O8aK1cXQb/id3v7SOPUfS6f3gUh6evJHycoOq7WRkZFRdkRAhe9dy4W24cvyGgL19qJeGog+mcemdfzJ83D/sOZLOgMeXc+OoVeQVlArnUh9k5pQw6InlDHpyOQ+8uoGdB1PpMWIRB46L96WrIX1IAmL9p4WG7In/4XcH6DFyIfe9vJ49R9IJu3sRkz+OxlV+5CL6YBrdXdhHtUQvDWmJ3vEbAq7mQyWlFdw9cS39HlnKA5M2sOtQGl3v+JPV2+KF8qhPZru4j2qFVnOh2rjECfEz93QnuL0Pk568THGdA8czGfPuds4m5ZNXUIbRCIlphSzZcJbRM7epih8QEEBAQIDatAFI/XsOyYtnU3TmIMXnDlOSckb1NsrKDJxJyFN9Iq9V/Mi4EzX+qsVoNBKfnE9+YZld9aFmO+xBpA1a9KEeGkrNKOKel9ZxMj6P7LxSjEZIzihi465E7pq4TlUOohqwd//dMXYNW/elkJpZTHm5kbJyI8fP5nDnuLXk5qubjPYaexferf3o+tBQVfVMiPaBKHr7UG5+KQkpCp9dc0B80f4X8VFwfQ8C+zUkEn/h2jgivonhfEohRSUVGIyQkFrIF38eY87Ph1XloYcPmXz0lAY+CmI+pLcHgT4aqk5yeiFZuSW6xRfdByI+CtKH7I3/v6lRrNhynqT0IsrKjZRXGDmTmM9T4VsUvaJZHT186M9/TjPLgo/O/eWI6hxc2YdE5kLWcOgJcUxMDBEREYwaNYq1a9fy2GOP2bWdH5edZH74AH5cprzzw+fuJjWzuOpzZHh/oPIq0eptCapOzgoKCigosM/AKorzadYxDO+QULw7htG0fSdV9XPzS7n2sWX0e2QZA59YTmFReb3GByg2VDDn9HGiMtJU1wV4fGoUfR5aypX3L2H3Yfu2Ub0d9iDSBi36UA8NffJ/h0hKL6z6bBoDBgMcPpWt6iAgqgF79l9MbAan4vNqfGdqQ1J6IQv+OKoqh6StB+kz7XFOLYxSVc+EaB+IoqcPRe1K4sr7l9D7ob947u2t9R4fxPo/J0/MR8H1PQjs15BI/He+2E9W7oWLV6YxnFtQxtxfjqi6u6GHD33yk3UfPRWvbjIt4kN6exDooyETUz/bxdUP/sWV9y/hjzWn6z0+iO2DTdFJXHn/X/R+6C+en6HeR0H6kD3xM7KL2bY/hbJqF0NN4zg5o4i35+9VlYcePjTzyxgrPnpY9V1iV/YhkbmQNRx6Qrxo0SKmTp1Kly5dKCwsZMCAAXZtx9/Pi4LCclr4eiquc7LWRDq43YV3h4tLylUdxLy8vPDysv2cvjkC730NNw8v0lYvoPml16quv2zTOfYezSAtq5joQ2lE7Umq1/gA3u5NmNClO0Nat1Vdt7ConKjdSaRmFnMqPo8PvrPvqmb1dtiDSBu06EM9NLR5TzKGajfDqo+BjOxiYmKVP3Ii0n9g3/6LPpRGWlZxje9MbSgrN7Jpt7KFQkxkxJwi/cBpjOUVquqZEO0DUfT0oY9/OkRcQj4pGcWs+zdR9cFXbx/6O6qmj27eq85HwfU9COzXkEj87Lyad/NqHItLKygqVj4e9fChzXut++j+Y+oe3RPxIb09CPTRkIllm86RlFbEuaQCvlyo7p1IrcaQyD745P8OEpeQR0pGMWt3qPdRkD5kT/wjp7Lr3ASrPo4PHFf3gq8ePmTNR4tKKiguUecnruxDInMhazh0US1vb28iIyPZv38/nTp14uTJk6SlpdG2bc1OHD16NAkJCVWfjyQNANpUfX7sjq48ER7FxMfCmF3thOrIkcOMGPGl2diJiYOBACLD+xPczod+vdqydM6NJKQW8lLEeia9NJpmHsVm65ro168fADk5OQC0bNkSgHfeecdqvbThsyAwDICsLb9RknIa75BQPPza1Cl7+MhhRnzwusVt5ZY2p6n7AEoM3jR1L+Kjdycx37PIofHfwYtQmliNYeLI0SNMGzHC4v83GiE383qgJW5UcHjXMkaM+NTmdqu3oXY7bOWvpg2W8lfah7b2n6M1ZC1+XGofINjsGJgQsYmPZ8/gh7nmJ3OiGlC6/6y1IbmgPe5ufTAYPcy24b1Pf2HEiM/N5jT4qAdtzF3vMzMBOXLkCAvMaEBUQ1qhp4ZMxGZ3x51uGPAgK+0cI0eOtJm3M/lQTR8t5MN3JxHpodxHa7ehvvI35SB6HBHVkEj89LQbAV+zY/jlWet48IF7sLRGnpY+DuqPI6DER9/mh7nmJ9SiPqTlGBBFTw2ZSEm+DmgHGDh1ZBsjRtg+oRCNr+VxIDb70v98tAlZaWdV+yjUvw9pNZ816QfUaUiL+PllzSkqHAB4mx3H4bOXMcLKvnMGH7Luo+t54H7LPqrUh1x1LgTmNRQcHMz8+fMVb9/NWA9vY0+fPp3p06crLj/oieWKVpkeeFV7tvww3Oz/++nvE4yeuZ2C/x6NWzrnRkZOqHzfp2+vNkT/YtuIdu3aBUB8fOVL9yEhIZX1+/a1Wu/ZrcpXlLuyFXw90HqZqF1JPBG+mV8/uJ7rrmhvc5ui8cumvKl4VUJ6Xorn+zOsFklKK2TW1zFs3pPMvj/vsrlCMChvg6X+U9wGC/mLxjfhaA1Zi7/7cBq3vrCGjJzKK4vVx8AlF7Xg+PL7cXc3vy9ENaDFGCgrM9B1+B+cS7rwaIypDW1bebP5uzvo0dnf7DZXjgxXvKpiu349uH3pzLrxBTWkFXpqyITRaGT+H0f58PuDRP8ykjYB3ja362w+tCk6iSenuZaPNgQfenn2v8z99WjVu9umMezmBvff3JnfZ1t+h80ZfHzXoTRuG7OGjOy6PtrlohacsOKjoj6k9RgQwRl8KK+glHe+2M/yqHgOLr5b0QrBes8lquOKPqrVfNakH1CnIa3iX37vYg6eyKr6bBrHfs09+b+IIdx5/cUWt+sMPmTNRx+4uTO/WfFRpT7kqnMhsO1DSqiXRbXUnAxrxaN3dOXGa4No2bzyMeuE1EI8PdzpHNyc3z9Q9xK5r68vvr6+jkhTEUP6duDy7q0UTeKckQ5tfZjz+nV07NBc0clwQ0QPDfUJa8sTI7vR2r8pUDkG3N0rH7X5MWKIxUmcs+Dp6c7X0wcS1Nan6spnQmohbfybMvbBnhZPhhsqevqQm5sbYx4MpVfXVoomcc7I9f1c20e1QA8NvTu+D1f1aIVvs8oH0hJSC2nWtAmhXfz5Ypp9r1HVJ317teV/d3Y166M/uYCPao2ePtTC14sPXu5H145+ik6GnY2G4KNaoIeGfp89lI4dfPFoUjleE1ILCfDz4s7BHRk+pGO95mIPlnw07JIAFriAj2qJo/TjlL9DrAXu7m4s+fRG1u5I4NP/O8z/LT/JO2OvZvSDPfFrru7Z86ysyqtKrVq1ckSqkkaAXhr6aNI1PHxbF9775gA//X2SSU9cxsv/u4z2rZvVax72ctN1FxH9ywhmf3+w8h363Ums++o2rrjUMb9D58xIH5KIooeGmnl7sP3HO1m4No4vF8by28pTzH3tOh67sytNvZQ9yqk3H796LQ/fdgnvf+uaPqol0ockouihoZ5d/Nn/593M/eUIq7edZ9WWeJZ8eiODewe6xI2ahuCjWuEo/TTYE2KovBp3c/+LuLn/RULbcdSPQEsaD3pqqE9YWxZ+PEy3+KIEt/fl0yn2L+DRUJA+JBFFLw15eLjz0G2X8NBtl+gSXwv69nJtH9UK6UMSUfTSUIBfU9584SrefOEqXeKL0hB8VAscpR+nPCHu2tFP03KimH4A2t/fX1H5EBV38tWUdcQ2zZV1CwpE6YvlbkGByoOpQGkbLJVT2gZL+YvGr42jNOQI/YC4BvQeAy06K9elpbKiGtIaV9OQq/uQM+Qvfci5fFwtoj6k9xgwh6tpSO+5hCh6+5AjjuVqNKT3XAIajw811LmQUuplUS1XxfQCd3Z2NnCh87V4eVstI8avZdncm+o9rpY0hDaoxZk0JHFNnElDrj6GXT1/e3EmDUlcE2fSkKuPY1fP3x6qL6rlDBqSuB6WPAi00ZBT3iF2Nhx1NULSeJAakogiNSQRRWpIIorUkEQUqSGJCI7Sj+st0yeRSCQSiUQikUgkEokGyDvECpCLSEhEkRqSiCI1JBFFakgiitSQRBSpIYkIjWpRLWdDPt4hEUVqSCKK1JBEFKkhiShSQxJRpIYkIjhKP055Qlz+WSTGxGSb5dyCAvGYOMbh+ai9GvH2PogvUFY2xBfesrECfEJKAZk5JSSlFdKhrY/NbSrtPzDfh1rnn1dQyuGT2eQVlGE0GhX95tuWF+eRF2e7DS06BzLo03F1vm8sGlLS//YgqgFRDYqihYZFNaT1PtRTQ0ajkSOnssnKLaGgsAxfH0+b23U2HzqfrM5HlXoQmPchvceAORqqDzlqDIuit49qPYZAXw2VlFYQE5tJTn4pBoMRd3fbcwln8nF7fLSx+5AjNKyWxuJDes+FrOVQnUZ1h9iYmAxHY22Xq4dcQP3ViPgC2J8pHjcts4j7Xt7Aifgc0rKK6fPQX/TsEsCfHw0lwK+pxXpK+w/M96FW+VdUGBg3awfLo86RX1hOYXE5YXcv5sd3B9MnrK3VunlxyaRGH7M7ttSQGKLxRTUoihb9J6ohrfehXhravCeJUdO3kpVbSnZeKT3vWsT9N3fmw1f6Wb245Sw+VOWj53JIyy6m90N/EdYlgD9s+Gh9eRBIH3JUfL2PA3r7qCP2n14aivhqP1/8eYz8onLyC8voNvxPPnn1GkbccLHVes7i43V8dOQiHrilM7Nt+Ghj9yG9PUiLHBqLDznrXEgpLrGoVmTciRp/1WIwGCktq7A7fkBAAAEBAXbXN5G9a7nishUVBoY+u4rNe5NJSiuivNxIYloRG6ITuWnUKtT8WpZo/6X+PYfkxbMpOnNQVb1xETv4cdkJzqcUkp1XSmmZgaOns7lr4jrik/NVbavX2Lvwbu1H14eGqqpnQrQPRNFDQ9UxGo2UlNo/BkTja9H/JaUVqnRfG3t1bEKLNtjbf6CPhk6czeGhVzdy/GwuaVnFlJUbiE8u4MuFx3jt0122N1ANPXyoosLADc+srPTR9EofTUorYn10Ijc9p85HQcyH9PYg0EZDIhquqDBQXm4Qii+Sg+g+EPVRZ/Ag0N+H1Maf8/NhPvjuIOf+e8qjtMzA6fN5PDt9K9EHU1VtSw8fMuujKQV8YYePgvQhENOw6FxCNL7oPhD1UVf3Ia3mQrVx6AlxTEwMERERjBo1ik8++YR169bZtZ1iQwVzTh8nKiNNfQ6xmYTdvYjuw//kjc922xW/oKCAggKF9/trUV14xecOU5JyRlG9lVviOZt04aQxMrw/AEYjnE7IY8teZY/AgFj/AVQU59OsYxjeIaGK6+Tml7J8czyFxRcmD6Y2JKQW8u6X+1XlkLT1IH2mPc6phVGq6pkQ7QNR9NBQVf2MIno/+Bfdhv/JY69vUn0gEI0PYv1vNBq596X1dB/+J/0eWUZWbonqbYB9Oq6OvW3Qov9AHw29MXcPSelFVZ9NYzi/sJzfVp2muKRccQ56+NCKzfGcS77QZzV89Lw6HwUxH9Lbg8B+DWmh4b82nKHHiEV0v/NPvlqo/o6X3j6UIuijoJ8Hgf4+ZG98g8HIZz8fJie/tOo70zhOyypm8ifqTij18KHweZZ99FeVPgrSh0Q0PPG9HXS/808uu2cxJ8/l1Ht8ENsHf204w6UjFtL9zj/5epF9Tw64ug+JzIWs4dAT4kWLFjF16lS6dOlCq1atyMrKoqJC/dVVb/cmTOjSnSGtrT9ma463IvdwLC6Hs0kF/Lr6FAaD+oOYl5cXXl5equtBTeF5dwyjaftOiuqt2HKevIKyqs/B7S6885aVW8qqrecV5yDSfwCB976Gm4cXaasXKK5z8EQW+YVlNb6r3obtMequ6mbEnCL9wGmM5fZdnRftA1H00JCJWd/EsO9YJvHJBfyzPYFzSeruzovGB7H+P3wyi/XRiZxLLmD34XQ+//WI6m2AfTqujr1t0KL/QB8NHTqZVeNz9TFcWFLBibO5inPQw4dWbIm36qNrtiWoykHEh/T2ILBfQ1po+KMfDnEyPpe4hHwW/Kl+Iqe3D71XzUfX7kggPln9hEwvDwL9fcje+GlZxRQV1zxhrD6Oz6vcD3rNh6pTPf+iYnU+CtKH7NVwUXE5S9af5VxSAYdPZTNt3t56jW9CZB989MMhTsXnEZeQz/w/7DshdnUfEpkLWcPNKPrcgBUiIiLw9/cnKiqK8ePHs3XrVsaNG0fz5s1rlBs9ejQJCRcmJu/gRShNqj5Hxp1gTOduVX9NHKGCaZRijSOZoZzKvQRwx88zhyHBmxTn369fPwByciqvIrVs2RKA6Ohoq/XShs+iLDAMAKPBQN6BDRQnxNJq0IN4+LWpUdYz+TBtl79eZxvHsi7lRM6lRIYPILidD/16tSX6UOXVmITUAuZ9/iWXtDxtNr7S/gPzfVg9f4DMqF8oSTmNd0goAdfdoyj/3NIW7EjuT6nBm8jw/jXakJBayNQPljMoaIvZ/AEGH/WgTX7N6zU9nrqVY9+trvFdenMDm3vWvbqqpYZEcLSGLPV/dc7lhXAo8zIqjJ74eOQzOCgKT3frV6RFNSyqweqUVHixJXEIRRU+uFFB77a76eBr/c5ebQ2DZR1b6kNRDZlysNcDTOipoaiE68kta2l2DL8UsYGBQZvx8SgyW9cZfOhYVg9O5HS3y0fNeRAo9yEtx4AoohoS1TDA7tQ+JBUGA9DGO5XrAnfYzFtUw1oeB2r76JCgKDxU+Cio17CWY0hvH7I3frmhCRsThlFc0cysD7363j8MvWi9xfha+bgJtccREPPRhuJDJv2AOg1pqWGjETYl3kB+mR9g4FL/WLr7H7eZu6iGtfShXal9SS4MAuzzUdBvLgRi+9CSB4F5DQUHBzN//nyz2zKHQ0+ITUyfPp3p06crLl825U1liwD0vBTP92dYLVJebuDNz/fww7KTbPn+DrqE+CnOY9euykdx4uPjAQgJCQGgb9++Vus9u/XCC+TWDoAAV7aCrwfW3UZ8cj59H15GSkalSS6dcyMjJ1Q+ct6hTTMOLLqHNgHeZuMr7j8w24fV87eFpfyNRiM9Ry4i9syFR1JMbfBt5sGCaQN4bHhXi9tdOTJc0UIS7fr14PalM+t8r6WGRHC0hiz1f3WMRiOf/HSID78/yOJPb+Tay9vZzFtUw6IarM3G6EQ+/+0osWdyOLi4bg7W8reFpT4U1ZApB3s9wISeGpr362EmfRRNSWnl+0rVfeiK7q3Yv/Bui/GdwYfOJeXT7xELPtq2GQcWWvZRpR4E5n1I6zEggqiGRDUMUFBYxqsfR7M8Kp79C++mVUvLC5rVjg/2aVjL44DRaOTjHw/x0Q8HWfLpjVyj0kdt4Qgf1WIuYkJPDV3/1Aqi9ly4CGoax03c3XjliV68/1I/8xXRzsdtYdtHd1W9f17dhy7vHkDMQsvHtIbiQyb9gDoNaalhgCOnsnh7/j72x2ZwdOl9ilYqF9Wwlj6UX1jGZAEftYaj50Igtg8teRDY9iEl1Msq02pOhrXGw8OdiIl9OXQyW9XJcHV8fX3tjt9qyCN21QsJbM7oB3ow55cjZOaUkJBaCEBr/6a8+uTlFidxzoKbmxvfvTOI+17eQGJaZe4JqYX4NPOg/5XtePi2LjpnWL/ooSETbm5uvPy/y9i0K1nRybDW8bXghn5B3NAviBHj1+qdimq06j89NPT8fT35Y00cuw+nU1RSUeVDF7X34ceIwXbnU1907ODaPqo19mpICw37+ngSGT6A8ylrFU3iHJGDCG5ubrzyxGVE7U5WdDLsbOjtQyLxv585mOufWUl8cj4GQ+VcwsvTndBL/HnzeQf8zo7GPH9fT35fE8eeOj7qy08RQ3TOrv7R04dCLwng9w+HMmL8WkUnw1rHF6W5oI/qjSbHEoG5kDVcYpVpvcnKyiIrK8t2QY15a/TV/PXpMG68NojI345y64BgVn5+Cy/9r1e952IP113Rnu0/Deepu7rRq2sA3/91gvlv9GdV5C00adK4pKeXhiQNBz005OnpzvqvbmfOa9fSJ7QNkb8d5YX7e/Dv/43g8u6O+S1Aranuo/N/r+ajj7uGj2qJ9CGJKHpoqFNwC3b/OpKXH7+My7oF8NXCWN5/sS/bf7xT0W/56o2npzsbzPronS7jo1oifUgigqP045S/Q+xsOOpHoJUwqHcH1n7ZQbf4olwc1IJvZzj/nSRHo6eGJA0DvTTk6enOs/f24Nl7e+gSXwtc3Ue1QvqQRBS9NNQmwJvZr/Rj9iuWH492ZhqCj2qF9CGJCI7Sj1OeELsFBSr6gWq3oECH5wLqfwQ6RMXdfDVllaK0/0xla6N3/gAtOivbt5bKNRYNOar/RTUgqkFRtNCwqIa03oeupiFX9yGlHmSprN5jwByupiHR+HofB/T2UUeMIVfTkLP5uFoauw/pfRxQs11X9yG950JKy6r1IKXUy6JazsCI8WtZNvcmVXVML3BnZ2cDFzpfi5e3JY0DZ9KQPWPA2WgIbVCLM2lI4po4k4ZcfQy7ev724kwakrge1RfVcgYNufo4dvX87cGSB4ELLarl6jjqaoSk8SA1JBFFakgiitSQRBSpIYkoUkMSERyln8a1spFEIpFIJBKJRCKRSCT/Ie8QK0AuACARRWpIIorUkEQUqSGJKFJDElGkhiQiNKpFtZwN+XiHRBSpIYkoUkMSUaSGJKJIDUlEkRqSiOAo/TjlCfFT0zZz8lyuzXJdO/rx3Tu2f9InPauYwuJyKioMdv3+rdqrEW/vg/gCZWVDfOEtjX9XXjR++WeRGBOTFdV3CwrEY+IYlRnaRmkbLPWf0jZYyl80fm0cpSGl8bNzSygsKqe0rAIvzyY2y4tqQOsxUFJaQWJqIWXlBkXb3PLiPPLilOXfonMggz4dV+d7UQ1pjd4aUour+5Az5N/QfCgprZCiknKMRiNubm42yzubj2fnllBYrNxHRX1I7zFgDr01pBa95xKi6O1DjpjPqtGQ1vHLyw2cTymgtKxCcQ7O5kNqfVSpDzXUuZBSnPKE+OS5XLbuSxHezpFTWTwZvpnzqQVkZpfQbfifjH8kjJce76VqO2qvRsQXwP5Mtdlqh2h8Y2IyHI1VVtb+MFaprzZYyl/rfaiXhpLSCnn09U0cP5NDelYx3Yb/yf03deaDl/vh7m7ZSEU1oFX+5eUGJr6/g7+j4ikrM5CdV8pto1fzU8T1tAnwtlgvLy6Z1OhjQrFFNaQ10oeslLU/jEWcIf+G4kMbdiYyftYOMnNLyMop4dIRC5k1oQ/33tTZaj1n8fGktEIefW0TsWdyyMhW7qOiPqT3GDCH9CEL5ewPYRW9fcgR+0+NhrSKbzQaifgqhq8Wx1JSWkFWbin9H1/GTxHXc0mIn/W6TuJD6/9NZML7O8jKKSEzp4QeIxYya0Jf7rmpk9V69eVDzupBSnGJRbWeuac7we19mPTkZYrrnE8u4JYX1rDrcDpJaUWUlBmIS8jn7fn7mP3dAVXxAwICCAgIUJt2HbJ3LRfehh7xI+NO1PirB6l/zyF58WyKzhy0q75WbbC3D/XQUEFhGUOeWsHG6CQSUgspKTNwLqmA+X8c5Zm3tqiKK9p/9u6/h6ds5Nu/ThCfXEByRhHFpRWs3pbA4KdWqLrCC9Br7F14t/aj60NDVdUzofc4kD6kb/+7ugeBNhpSGz/6YBoPT9nIkdPZJKdXHotPnM3lhXe2sTzqrKpt6eFDVT66K4nEtJo++qxKHwUxH9J7DIA+GtIakfh67wPpQ/bFD5+7hw++O8DZxPxKHyqtYEdMGsOeXUVaZpGqbenhQzsPpPLIaxs5ciqbpP989PjZXJ5/Z6tqHwXX9iGt5kK1cegJcUxMDBEREYwaNYo///yTRYsWUVpaqno7Py47yfzwAfy4THnnv71gL+dTLjyjEBneH4Cc/FI+//0oZWXKHr0EKCgooKBA4TMbtagu/OJzhylJOaOqfnm5gZET1tJjxELuf2U9BoO6azCi8QGKDRXMOX2cqIw01XUBZn6xjx4jFnLNI0tJSiu0axsVxfk06xiGd0ioXfVF2qBFH+qhoW+XHOdsUn7VZ9MYKCyuYO2OBFUHAVEN2LP/zibmsXVfCsUlF058TW04m5jPH2viVOWQtPUgfaY9zqmFUarqmRDtA1H09KG483n0eWgpPUcu5NOfDtV7fBDr//JyAyPG/0OPEX/y4KQNqn0UXN+DwH4NicR/+cOdpGYWV302jeH07BKmztmjKg89fOibJcc5Z8FH12xX56Mg5kN6exDooyET/7f8JKF3LeLK+5aw72h6vccHsX1wOj6XPg8tpccI+3wUpA/ZE7+wqJyflp8kt6Cs6jvTOI5PyefDH9RdXNDDh175KFozHwXX9iGRuZA1HHpCvGjRIqZOnUqXLl3YsWMHnp6elJSUqN6Ov58XBYXltPD1VFxn2/7UGp+D2/lU/buwqIxjcdmKt+Xl5YWXl5fi8tWpLnzvjmE0bd9JVf2/NpxlxeZ4Ys/ksGzTOTbuSqzX+ADe7k2Y0KU7Q1q3VV23pLSCrxcfJ/ZMDtGH0pn8cbTqbQAE3vsabh5epK1eYFd9kTZo0Yd6aGjh2jhKq134qT4GUjOLVL2WINJ/YN/+2xCdRHJ6zcmmqQ2FxeX8tvq0qhwyYk6RfuA0xnJ1d5ZNiPaBKHr60KsfR7PnSDrH4nKY99sRjEZ1J5R6+9BfG86ycst5Ys/k8tfGs0TtTlK9DVf3ILBfQyLxzyfn1/hc3YcysksoLilXvC09fGjh2jhKLPhoWpY6HwUxH9Lbg0AfDZn44LsDHD2dTczxTKZ8sqve44PYPpj8yS72HEkn9ox9PgrSh+yJvz82g7xqJ8NwYRwbDLB663lVeejhQ/E2fLSkVJ2fuLIPicyFrOFmtGdEKiQiIgJ/f3+ioqIYPnw4FRUVDBo0iEsuuaRGudGjR5OQkFD1eVvSADJL2lR9funxXnz+2xEmPhbG7O8uXMlp1TSdAR22mY29KeF68spaEhnen+B2PvTr1ZboQ2kkpBbyUsQGBnTYiq+n9SsM/fr1AyAnJweAli1bAhAdbf2kLm34LMoCwwAwGgzkHdhAcUIsrQY9iIdfmxplPZMP03b56xa3lVHciuiUayk3euLpXkL/wG34eeU5NP47eBHKhQVDIuNOMKZzt6q/1TlCBdOwfNffaISNCcMoKG8OGOnid5KwVkes5l+7DQCZUb9QknIa75BQAq67x2r+atpgKX+lfWhr/zlaQ9bi/5t8LWnF7c2OgfHvbqZP212080k1W1dUA0r3n7U2JOQHsS/9aow0MduGmR//Qe925q+MDj7qQZv8utf7ejx1K8e+W13ju/TmBjb3rDspF9WQVuipIRMHMi7nbF4nwI3mnrncELzRZt7O5EOiPgrqNaxF/qYcRI8johoSib8u/kaKKnzNjuGXZ61n2EVrcXczPw3R0sdB/XEExHxU1Ie0HAOi6KkhE5sTB5NTWvmoZAefBPq0220zb9H4Wh4HDqRfztn8Ttjro1D/PqTVfNakH1CnIS3iZ5e05N+U6ygzNDU7jl//YAWDgzZbzMEZfGhd/E0UVfjY5aNKfchV50JgXkPBwcHMnz9f8fYdekJsYvr06UyfPl1x+UFPLFd01XXgVe3Z8sNws//v/W9imPb5HsrKK5u3dM6NjJywDoAenVty5K97ba7OtmtX5RXI+Ph4AEJCQgDo27ev1XrPbr3wAr018wK4shV8PdDq5pj9/QFmf3eQN1+4knEPh1kvrEH8silvKl6EgZ6X4vn+DKtFtuxN5t0v93M0LocTy+9TtDpn9TZYw1L/KW6DhfyV9qGt/edoDVmLv2LzOR6ZsqnqMaHqYyAk0JcTy++nqZf5fSGqAaX7z1ob8gpK6TlyEQmpFx6zN7UhwM+Lv+fexICrAs1uc+XIcMWLSLTr14Pbl86s872ohrRCTw2ZKCouZ2zEdpZHxbNq/s30DrV9ZdjZfMjko2+9cBVjH7b9qJqohrXI35SD6HFEVEMi8R+evIHfVl94vaG6D93QtwMbvrndYnwtfdwa1vJfHnWOR1+zz0dFfUjrMSCCnhoycfxMNi9/uJN9RzM58te9tGxh+y6RaHwtjwOiPmoLR/iQVvNZk35AnYa0iG8wGOk+/E9Onb9wEdQ0jr2buvPZlOt47r4eFnNwBh+y5qND+3Vg/deWfVSpD7nqXAhs+5AS6mWVaTUnw1ox/pEwflt9mkMnsyivMFZNqtu3bsb88AGKlio34evra3cerYY8YnddE68+eTlb9qQoOhl2RHxRBl0dyOoFtzJi/FpFJ8POhhZ9qIeGbhsYwjWXt2XL3sr3cE1joI1/U6aPvsriJM5ZaOHrxStPXMbML/eTmVP5qkVCaiG+zTwY3DuQ/le21znD+kVPH2rm7cG3MwYzYvxaRZM4reNrgclHlZwMOxta9Z+9GhKJ/8nka4k+lM7p/yajJh8KCfTlq+k2zoCcgNsHubaPao0eGjLRvZM/y+fdwojxaxWdDGsdXxRRH9UbV/Uhd3c3Pn3tWp55c0vVe7gJqYV4erpxebfWPDmym40t6I81H/3yLef3US0RmQtZwyVWmbYHn2YebP1hOK89cwU9Orfkkx8PccfgEDZ8fRvX9+2galtZWVlkZWU5KFNJY0APDbm7u7Eq8hbef7EvvboG8MmPhxjSO5Aln97I03dfWq+52MtLj/fijw9vYMCV7ejW0Y8Ffxzlo0nXsPiTG1Vd1GoISB+SiKKHhgLb+PDv/93J6Ad60P1iPz756RD/u7Mr23+80+bPnTgD7u5urPz8Ft6b2MdlfVRLpA9JRNFDQ8MHd2TNglu5+bpgunX0Y+4vR3jr+auI+u52l7hR4+o+qiWO0o9T/g6xVvj6ePLOuN68M6630HYc9SPQksaDXhpq0sSdCY+GMeFR9U8XOAvDrglm2DXBeqehO9KHJKLopaG2rZoRGT5Al9ha4OHhzsTHejHxsV56p6I70ockouiloSt7tGbNF7fqElsLXN1HtcJR+nHKE+KuHZVd7VBaThS1PwIdouJuvpqyjtimubJuQYGKf2DbLcj8O5yiKG2DpXJK22Apf9H4tXGUhhyhHxDXgN5joEVn5bq0VFZUQ1rjahpydR9yhvylDzmXj6tF1If0HgPmcDUN6T2XEEVvH3LEsVyNhvSeS0Dj8aGGOhdSSr0squWqmF7gzs7OBi50vhYvb6tlxPi1LJt7U73H1ZKG0Aa1OJOGJK6JM2nI1cewq+dvL86kIYlr4kwacvVx7Or520P1RbWcQUMS18OSB4ELLarl6jjqaoSk8SA1JBFFakgiitSQRBSpIYkoUkMSERylnwa7qJZEIpFIJBKJRCKRSCTWkHeIFSAXkZCIIjUkEUVqSCKK1JBEFKkhiShSQxIRGtWiWs6GfLxDIorUkEQUqSGJKFJDElGkhiSiSA1JRHCUfpzyhLj8s0iMick2y7kFBeIxcYzD81F7NeLtfRBfoKxsiC+8dZX1MkajkQqDEaPRqOi3V5X2H5jvQ63zBygprUDN+m1bXpxHXpztNrToHMigT8fV+b6xaEhp/6tFVAOiGhRFCw2Lakjrfai3hioqDFQYlI9hZ/MhtT6q1IPAvA/pPQbMobeG1CIaX+/jgN4+6ohjud4aKi2rwKBiLuFsPq7WRxu7DzlCw2ppLD6k91zIWg7VaVR3iI2JyXA01na5esgF1F+NiC+A/ZnicUvLKpj8cTRLNpwlNaOYzrf9wYO3dObd8X3w8LD8+rfS/gPzfahV/gA//X2CiK9iyC0oIzOnhBET/uGrtwbRvnUzq/Xy4pJJjT5md1ypITFE44tqUBQt+k9UQ1rvQ700dD65gFFvb+HgiSwysosJu2sRb4+5mvtu7my1nrP4UGlZBa9+FM1fG8+SklFU5aMRE/rQpIllH60vDwLpQ46Kr/dxQG8fdcT+00tDa3ec59WPd5GWWUxGTjFDnlrBV28NpHunllbrOYuPxyfn89zbWzl4Iov0/3x0xtirufcm6z7a2H1Ibw/SIofG4kPOOhdSilxUSwEBAQEEBAQIbyd713JV5e8Y+w/z/zjGuaQCiksrOJuYz5xfjnDvy+uFc6kPPv2/Q0x8/1+OnckhMa2Q4tIK/t4Uz8AnlpOTV6p3evWKXhrSGr3juzoi/aeHhtIyixj81HJWb0sgIbWQ4lIDR05n88I72/huyXHhXByN0Wjk9jFrWPBnpY+WlBpczke1RAsNOYMHOEMOrozePqQ2/qqt8Tz6WhQxsZkkphVSUmpg855khj67krjzeUK51AdpmUUMeWpFlY+W/Oejz8/Yxvd/Ob+Pak1D8CG94zcE7O1DreZCtXHoCXFMTAwRERGMGjWKzz77jClTpnD27FnV24mMO1HjrxrSMosY+uxK+jz0F/+3/KTq+gAFBQUUFCi831+L1L/nkLx4NkVnDlJ87jAlKWcU1dt1KI19RzMoLTMAEBneH4Dikgr+PZDK0dPZinMQ6T+o2QallJZV8MlPh8jKvXDia2rDmYQ8Pvv5sKoceo29C+/WfnR9aKiqelWxBftAFD00ZKK4pJyRE9bS58G/ePfL/fUeH8T7P3zubvo89Bf3v7Kesv/GhFrs0XF17G2DFv0H+mjo3a9iOJOYX/XZNIYzckqY+dV+DCoe/dPDh3YdSmffsUyzProjRp2PgpgP6e1BYL+GtNDwoRNZ9H/8b655ZClb9yp7hFPrHET2QVHxBR+N+Gq/6vqgnwfVjq2HD4nEn/RRNGlZxVWfTeM4IbWQyZ9Eq8pDDx+y5qMzvlDnoyB9SETDX/x5jD4P/cUtz68mO7ek3uOD2D44dCKL/o8to98jS9m2N8Wu+K7uQyJzIWs49IR40aJFTJ06lS5duvDUU0/RqVMnLr74YtXbKTZUMOf0caIy0lTXnfDev2yMTmLPkQxmLNin6j1WE15eXnh5eamuB1BRnE+zjmF4h4Ti3TGMpu07Kar3098nyci5MFiD2/lU/Ts1s5jfVp1SnINI/0HNNihl39EM8grKanxnakN5hZHF686oyiFp60H6THucUwujVNUzIdoHouihIROzvj7A31Hn2HM0g89/P0JyemG9xgex/j8Vn8uXC2PZcySDJRvO8PnvR1RvA+zTcXXsbYMW/Qf6aGjtjgSqW2Z1H8orLONYXLbiHPTwoZ+WnyDTio/+vlq5j4KYD+ntQWC/hrTQ8IT3drAjJpXoQ+m8/OFOXXIQ2Qezvolh2ab/fPS3o6RkFKnehl4eVDu2Hj5kb/yM7GKyap24VB/H+45mqMpDDx+y5qP5hWXEnslRlYP0Ifs0XFJawfvfxrDnSAb/7Ejg1Y/VXUzRagyJ7IPxs7az40Aauw6l89Lsf+2K7+o+JDIXsoab0Z4zRIVERETg7+9PVFQUX3zxBWvWrOHBBx+sU2706NEkJCRUfX4HL0JpUvU5Mu4EYzp3q/pr4ggVTMP6o7f70q7ifEFHAHw98rgheAMK1lMBoF+/fgDk5FSaVcuWle+qREdbH0Rpw2dRFhgGgNFgIO/ABooTYmk16EE8/NrUKOuZfJi2y1+vs43DGWGczutKZHh/gtv50K9XW6IPVYovIbWQz+Z9Q3d/84/aKO0/MN+H1fOv3YZ2d4xVlH92iT//Jl9LmbFpnTYkpBby2gcrGRJk2cwHH/WgTX7N6zU9nr6NY9+uqvFdenMDm3uW290HSjQkgqM1ZKn/q3MiuyvHsnsC7ng3KWRwUBRNm1hvs6iGRTVYncLyZmxJHESpoRlg4LLWB+jUwvqTJrU1XLsd1XVsqQ9FNWTKwV4PMKGnhjYm3EB+mZ/ZMfxixAYGdNhGc898s3WdwYcOZfQiLu8Su3zUnAeBch/ScgyIIqohUQ0D7Ei+jvTidgD4e2UyKGiLzbxFNazlcUDUR2u3QYmGtRxDevuQvfFLKzzZlHgDJRXNzPrQpPf+YdhFll9/0MrHTag9jgBsSriBPDt9tKH4kEk/oE5DWmrYYHRjY8IwCst9ASOdWsRxWWvbd0lFNaylD4n6KOg3F6odW+0+tORBYF5DwcHBzJ8/3+y2zOHQRbWmTp0KQGpqKv7+/mZPhoE6CZdNeVPRC9yhPUNZ9v4Mq2Vy8kr53xtRbNmbzM+z7uW2QS8qSx7YtWsXAPHx8QCEhIQAEB4ebrXes1svvECeteU3SlJO4x0SWmfHA4SFhvH1c8vqfH/geCY3jlrFmJnbAVg650ZGTlgHQPvW3mz7+U0uCfEzG19p/4H5Pqyef+02KM2/osJA1zv+5Exifp02eHq6ETH+ZiY9+YrFvFaODK+7kISZazehoaFMWjqzzvdaakgER2vIUv9Xp6zMwDNvbWHF5nNETOjP8w+Mt5m3qIZFNVibj388yJL1ZzmblM/+1XNwd7d+Vau2hmu3w1b+atpgKX9TDvZ6gAk9NTT1s928/12MWR/q2rEd6//+2eKKzc7gQzGxGdz4nCUfbWbVR816ECj2Ia3HgAiiGhLVMFS+KvPs9K3sO5bBxm+e4fLur9rMW1TDWh4HRH20dhtq4wgf1WIuYkJPDV15/xJiYjPNjuP/3XklP7w70WJ8rXzchNrjCIj5aEPxIZN+QJ2GtNQwwMJ/4vjs58Ocis/l0PLp+Pp42sxdVMNa+lB1H930zTNcptJHQb+5UO3YavehJQ8C2z6khHpZZXr69OlC9U1XIGpfzVJCyxZeLJ1zEyPGr+W2QSG2K5jB19fXrnoArYY8Yle9y7u3YuDV7Vmz7TyFxRUkpFY+5tq8mQe39L/I4iTOHCL9B/a1oUkTd6aPuZpXPtxJRnbl404JqYW4u0P3ji0Z/UAP1ds89t1q1XVMiPaBKHpoyISnpzs/RgxhxPi1PP9Az3qPD+L9//L/LuPl/13GiPFrbZ4MW0K0Hfa2QYv+A300NPmpy1i0/gzH/3ukz+RDbQO8+eClvop+vsiEHj50xaWtGXR1YF0f9fHglv7BqnzUhL0+pLcHgf0a0kLDnYJbsO6r2xgxfi2Xd2+lSw4i+0DUR0E/D9Iitgk9NDT3teu4f9J6UjIq3yM2jeNOQc2ZNbGPqm3p4UOTn7qMReviOH42FxDzURPSh+zjvps7c9/NnRkxfq2ik2Gt44PYPqjuo5fZ4aPg+j4kMheyhlxlWgFZWVlkZWXVe9yFHw1j2nNX0v1iP977OoZLO7XknXG9+X7m4HrPxR6eGNGN/5s1hN6hrekY6MsH3x7g6bu6s+3HO1Ubkaujl4YkDQc9NOTv15TtPw7n8eGX0CmoOe99E8M1l7Xljw+HcvewTvWai72Y9dGxruOjWiJ9SCKKHhoa1DuQFZ/fwuDegXQM9OX9bw9wz7CL2fL9cILaOWZyrCX+fk3Z9uOdNXy0Xy/X8lEtkT4kEcFR+nHK3yF2Nhz1I9C2cHd347Vnr+S1Z6/UJb4W3DoghFsH2HdnviGhl4YkDQe9NNTa35sfI67XJbYWNAQf1QrpQxJR9NJQ79A2RH13hy6xtaBNgGv7qJZIH5KI4Cj9OOUJsVtQoKIfqHYLCnR4LqD+R6BDVFywVFNWKUr7z1S2NnrnD9Cis7J9a6lcY9GQo/pfVAOiGhRFCw2LakjrfehqGnJ1H1LqQZbK6j0GzOFqGhKNr/dxQG8fdcQYcjUNOZuPq6Wx+5DexwE123V1H9J7LqS0rFoPUopDV5l2JkaMX8uyuTepqmN6gTs7Oxu40Pl9+/bVMjVJA8aZNGTPGHA2GkIb1OJMGpK4Js6kIVcfw66ev704k4Ykrkf1RbWcQUOuPo5dPX97sORBoI2GnPIOsbPhqKsRksaD1JBEFKkhiShSQxJRpIYkokgNSURwlH7koloSiUQikUgkEolEImmUyDvECpALAEhEkRqSiCI1JBFFakgiitSQRBSpIYkIjWpRLWdDPt4hEUVqSCKK1JBEFKkhiShSQxJRpIYkIjhKP055QvzUtM2cPJdrs1zXjn58947jf0tS7dWIt/dBfIGysiG+8NZVdiTlwPjln0ViTExWVN8tKBCPiWNUZmgbpW2w1H9K22Apf9H4tXGUhhyhHxDXgN5jYMuL88iLU5Z/i86BDPp0XJ3vRTWkNa6mIVf3IWfIX/qQc/m4WkR9SO8xYA5X05DecwlR9PYhRxzL1WhI77kENB4faqhzIaU45QnxyXO5bN2XIrydrNwSJn8czfqdiSSnFzHgf3/zwUt9GXCVuqXN1V6NiC+A/Zlqs9UO0fjGxGQ4GqusrP1hrFJfbbCUv9b7UC8NlZRWMD1yLwvXxpGQWshVDyzhzeev4u5hnazWE9WAlv3368pTzPomhtyCMtKzipkeuYc3Rl2Fp6flJRDy4pJJjT4mFFdUQ1ojfchKWfvDWMQZ8m8oPnQ2MY+XPtjJvtgMUtKLuPWF1Xw65Vp6dLaeh7P4eHFJOdMj97FonTofFfUhvceAOaQPWShnfwir6O1Djth/ajSkZfz1/yYydc5uUjKLSMssYnzEdiIm9qGFr5fVes7iQ+Z89LMp13KpDR+tLx9yVg9SSoNdVCs3v5T+j//NN0uOE5eQT1FJBdv3p3L3i+tZtvGsqm0FBAQQEBAgnFP2ruXC23Dl+A0Be/tQDw2Vlxu44ZmVfPTjIU7G51FUUsH+Y5k889YWPvz+gHAu9cG0eXsY/e42Dp7I4mxiPgVF5bz37UFueWE1jeQX46qQPiQBsf7TQkNq459NzGPQkytYsuEsZ/47Fq/ZnsDQZ1dx4HiGUC71QXm5gaHPruLjn1zXR7VEDw1pjd7xGwKu5kM/Lz/JQ5M3EH0ojbOJ+RQWVxD5x1EG/G85hUXlQrnUB67uo1qi1VyoNg49IY6JiSEiIoJRo0bx1VdfMX/+fFJS1N/5feae7gS392HSk5cprvPhDwc5cTYX05w5Mrw/AGlZxUz6KFrVZLqgoICCAoXPbNQi9e85JC+eTdGZgxSfO0xJyhlV9Y1GI699uoshT63g7fl76z0+QGTciRp/1bJs41kGP7mchyZvsNt4qrfDHkTaoEUf6qGhJRvOcPB4JmXlBuDCGMjKLeWznw9TUFimOAdRDdiz/7JyS/jur+Pk5F3IMzK8PyWlFew9ms76nYmqcug19i68W/vR9aGhqupVxRbsA1H09KHc/FLufWkdQ55awbp/E+o9Poj1v9FoZMonlT46Y4F6HwXX9yCwX0Mi8Se+/y/xyRdimnwoKa2Q0TO3q8pDDx9asl47HwUxH9Lbg0AfDZnYcySdG55ewR1j15CaUVTv8UFsH4j6KEgfsid+RYWBaZ/vIT27pOq7yPD+GAwQeyaHLxequ3uqhw9Z8tHEtELGvLtDdQ6u7EMicyFrOPSEeNGiRUydOpUuXbpQVFREeno63t7eqrfz47KTzA8fwI/LlHf+4nVnqDBcOOkNbudT9e+c/FKOn8lRvC0vLy+8vKw/UmGJiuJ8mnUMwzskFO+OYTRt30lV/XX/JjLv18Ns3pPMJz8dZvfhtHqND1BsqGDO6eNEZaiLDVBWZuDl2TvZsjeF31fHMfmTaNXbgJrtsAeRNmjRh3po6Is/Y8mvdgGi+hjIyC5h0+4kxTmI9B/Yt/9Wbo4nudakx9SGnPwyFvyh7iCWtPUgfaY9zqmFUarqmRDtA1H09KEX3/+XxevPsnlPMuMidqi+O6+3D637N5HPf6v00Y9/PMyeI2I+YA96exDYryGR+PuP1XxWsLoPnU3Mp6zMoHhbevjQFwu181EQ8yG9PQj00ZCJUdO3sml3Miu3nOe5GVvrPT6I7YOJ1Xx0/Cz1PgrSh+yJv/doBjn5NS9cmcZxaZmBn5afVJWHHj5kzUfjEvJU+Si4tg+JzIWs4WZ04HOHERER+Pv7ExUVxQ033ICHhwc33HADl1xySY1yo0ePJiHhwtWybUkDyCxpU/W5bStv5ky5jvB5uzkVn1f1faum6QzosM1s7I0JN5Bf5kdkeH+C2/nQr1dbog+lkZBayIsRG+kfuI0WXnlm65ro168fADk5lSfPLVu2BCA62vpJXdrwWZQFhgFgNBjIO7CB4oRYWg16EA+/NjXKeiYfpu3y1y1uK7mgPbvT+mKkCe6Uc237HbRuZv1lBNH47+BFKE2qPkfGnWBM525Vf6tzhAqmUWoxF4PRjQ0Jwygq9wXgIt+zXNV2v9X8a7ehdjva3THWav5q2mApf6V9aGv/OVpD1uJvT+pPRklbs2Ng7Mwt9Gm3m0Af8wsliGpA6f6z1oZzeSHEZFwFuJltw9sfLaJfe/P9OPioB23y617v6/H0bRz7dlWN79KbG9jcs+6TC6Ia0go9NWRiT2pvEgsvAsDXI58bgtfj5mY9b2fyIVEfrd0GJRrWIn9TDqLHEVENicRfF38TRRU+ZsfwS7PWM+yidTRxMz+Z09LHQf1xBC7MR+zxUVEf0nIMiKKnhkxsSrievLLKuG29U7g28F+beYvG1/I4sDu1N0kCPgr170NazWdN+gF1GtIiflZxADtTr6XM4GV2HL/2/iqGBG+ymIMz+JCIjyr1IVedC4F5DQUHBzN//nzF23foolpTp04FIDU1lRdeeMFiudoJD3pieY1FtR67oytPhEcx8bEwZn934RGD0NAwlv0wxew2J763g7m/HmHMf49kLZ1zIyMnrAOgc3Br1i3/iSZNrN8g37VrFwDx8fEAhISEABAeHm613rNbL7xAn7XlN0pSTuMdElpn8AKEhYbx9XPLLG7LYDDyZPhmlm48y4O3dOeLt57DzYaDisYvm/Km4kUYQnuGsuz9GVbLfP7bEb5eHMv55AJi/n6DVi2b2txu9TbUboet/NW0wVL+SvvQ1v5ztIasxf9mUSzj39thdgwEt2vBP4vn4u9nfl+IakDp/rPWhqS0Qno/9BdJaUV12tDcx4Mf3n2Me240348rR4abX0TCzPW/0NBQJi2dWed7UQ1phZ4aMpGcXshDr25kX2wGc1+7nf+NmGgzb2fyoRo+euulfPGmOh+t3Yb6yt+Ug+hxRFRDIvFvHLWS9TuTzPrQ1T0vYsXvf1mMr6WPg/rjCMDXi44x4b1/7fJRUR/S+lgsgp4aMrFiczxvfr6H0wl5bPt5LN0unmozb9H4Wh4HRH0U6t+HtJrPmvQD6jSkRfyS0gq63/kn55IK6ozjJu5uTHv+et4a/bLFHJzBh0R8VKkPuepcCGz7kBLqZZXp6dOnC9X/5KdDADVOhm3xxqgrWbbpHGcS8wFISC0EoFVLL1575gqbJ8PV8fX1VZFtTVoNecTuugDu7m78GDGEEePX8uX0QfUeH6i6AlT7aqJSxj4UytiHQhkxfq2ik2FziLZDpA1a9KEeGnrszq588n+HOHI6G6Pxwhho4evJ/Td3tjiJM4eoBuxpQ4e2Ptw2IITf15ym4L9HFhNSC3F3h24dWzLi+o6qt3nsu9Wq65gQ7QNR9PShwDY+bPruDkaMX8v/RugzhkT6v4aPvjXQrviu7kFgv4ZE4n86+Vpuen41yemVrz+YfKhdK28+nnSNqm3p4UOPDe/Kp/932KyPPqDSR03Y60N6exDooyETdwwO4Y7BIYwYv5ZuF7e0XUHj+CC2D0R9FKQP2UNTryaMfyiUd7+JITu38g6maRx3Cm7OxEfDrFWvgx4+pKWPmnBVHxKZC1mjwa4y3a51MzZ9ezs3XhtEcDsfZn6xnx6dWzL39f48d18PVdvKysoiKyvLQZlKGgN6aKipVxO2/DCc+27qxEXtfXj3y/10uagFbz5/JR+/ap+B1jdfvz2QyU9dRqeg5gS19WHW1zE8fNslRH13Ox4eDda+zCJ9SCKKHhrq1a0VK+bdTL/L2hLUtvJYfOWlrfj9g6EM6duhXnOxB++mHmz5YTj33ljXRz9yER/VEulDElH00NCkpy7nw5f70a2jH0FtfYj4aj+3D7yILd8Pt+uiVn3Tq1srlruwj2qJo/TjlL9DrBUXB7Vg7Ze3UVZmoKSsguY+nnZtx1E/Ai1pPOiloQC/pvzx4TDKyw0UlZTT3MfT5qOizoSbmxtvvnA1056/ivzCMny8PVQ93dGQkD4kEUUvDV0d2oadP4+guKQcoxGaebvW1CPAryl/fuS6Pqol0ockouiloWfuuZSn7+5OQVE5TT2b4OnpWnOJ3i7uo1rhKP04ZW927einaTlPT3ch4av9EegQFXfz1ZR1xDbNlXULClT8A9tuQYHKg6lAaRsslVPaBkv5i8avjaM0pLSch4c7LTyUr8onqgGtx4CbmxstfJXn36Kzcl1aKiuqIa3RW0NqcXUfcob8G5oPeTdVN+VwNh9X66OiPqT3GDCH3hpSi95zCVH09iFHzGfVaMgRcwm1N8eczYfU+qhSH2qocyGlOHSVaVfH9AJ3dnY2cKHz+/btW++5jBi/lmVzb6r3uFrSENqgFmfSkMQ1cSYNufoYdvX87cWZNCRxTZxJQ64+jl09f3uovqiWM2hI4npY8iDQRkNOeYfY2XDU1QhJ40FqSCKK1JBEFKkhiShSQxJRpIYkIjhKP671AL1EIpFIJBKJRCKRSCQaIe8QK0AuIiERRWpIIorUkEQUqSGJKFJDElGkhiQiNKpFtZwN+XiHRBSpIYkoUkMSUaSGJKJIDUlEkRqSiOAo/TjlCXH5Z5EYE5NtlnMLCsRj4hiH56P2asTb+yC+QFnZEF946yo7krKC0v4D832od/4AW16cR16c7Ta06BzIoE/H1fm+sWjIUf0vqgFRDYqihYZFNaT1PnQ1Dbm6Dyn1IDDvQ3qPAXO4moZE4+t9HNDbRx0xhlxNQ87m42pp7D6k93FATQ6u7kN6z4Ws5VCdRnWH2JiYDEdjbZerh1xA/dWI+ALYn6lN7EVr43j/2wMcOZ3NdY8t441RVzJ8SEerdZT2H5jvQy3zP3Qik9c+3c2JczkkpRXywbcxTHysF029mlitlxeXTGr0MbvjSg2JIRpfVIOiaNF/ohrSeh/qpaGi4nI+/OEgv606zdmkfO55cR2zJvbh0s7W83AmH1r4TxwffFfpo9c+uozw52z7aH15EEgfclR8vY8DevuoI/afXho6m5hH+Nw97DqczvmUAqZ8Es3UZ6+kZQvrP4PlLD5eWFTORz9e8NG7X1zHewp8tLH7kN4epEUOjcWHnHUupBS5qJYCAgICCAgIEN5O9q7lqsqPn7WDZ97awq7D6RQUlfPvgTQenxrF1Dm7bFd2AtZsO8+Nz61ixZZ4jp/NJa+wnGmf7+WGZ1ZSWlahd3r1il4a0hq947s6Iv2nh4aKissZ+MRyZizYx5HT2RQUlbNkw1lueGYl2/Ypu+ugN+MjtvPs9As+uvNgpY+Gz9mtd2r1jhYacgYPcIYcXBm9fUht/KOnsxn4xHL+b8UpYs/kUFBUeZHu2seWkZ1bIpRLfWDOR/9yMR/VkobgQ3rHbwjY24dazYVq49AT4piYGCIiIhg1ahTffPMNkZGRVb8fpYbIuBM1/qqhpLSC52dsZfi4New/lqG6PkBBQQEFBQrv99ci9e85JC+eTdGZgxSfO0xJyhlF9U7F5/LnP3Hk5JcBEBneH4DsvFK+++sEianK8xHpP6jZBqUYjUbGRewgJaP4Qh7h/SktM7DvWAY/LlOXS6+xd+Hd2o+uDw1VVa8qtmAfiKKHhkwYjUZe/2wXt49Zw8ot8fUeH8T7f+E/cdw+Zg1vR+7F3p9Ot0fH1bG3DVr0H+ijobm/HObgyUzKKyr73ORDSelFPPf2NlU56OFDJ8/l8uda8z767V/HVfkoiPmQ3h4E9mtICw1n5pTw0OQN3PvSOtX9rlUOIvvAaDTy+qf2+yjo50G1Y+vhQyLxn35zM+dTCqs+R4b3x2CA2DM5TPt8r6o89PChub8c5tApbXwUpA+JaHhHTAp3jFnDhFnbKSsz1Ht8ENsHoj4Kru9DInMhazj0hHjRokVMnTqVLl260LVrVwwGA8eOqX/0o9hQwZzTx4nKSFNd95UPd/LVolhWbD7Po69vUl0fwMvLCy8v64/lWKKiOJ9mHcPwDgnFu2MYTdt3UlTv60WxpGQUVX0ObudT9e+UjCJ+Wn5KcQ4i/Qc126CUA8czyc6reeXW1Ibikgq+WKjsER4TSVsP0mfa45xaGKWqngnRPhBFDw2Z+Py3I3zy4yFWbT3PmHe3q76iLhofxPo/Ka2Ql2b/y6qt5/ng+4P8ukq59qtjj46rY28btOg/0EdD/7fiFGVlFy5AVPehjJwSTp/PVZyDHj701aJjNS7KVc8/OaOIn1eo05KID+ntQWC/hrTQ8BPhUfy+Oo7F68/y8JSNuuQgsg8+/+0In/z0n4/OVO+joJ8H1Y6thw/ZGz83v5RzyTUnv6ZxbDTC6m3nVeWhhw9p6aMgfcheDVdUGHjijc2s3HqeyD+OMu3zPfUa34TIPnjiDTEfBdf3IZG5kDXcjPbeblFAREQE/v7+REVFMXXqVDZu3Mizzz5L8+bNa5QbPXo0CQkJVZ/fwYtQLrxjGhl3gjGdu1X9NXGECqZRajWHXSl9SS4KAsDHI5+hwetxc1OWf79+/QDIyckBoGXLlgBER0dbrZc2fBZlgWEAGA0G8g5soDghllaDHsTDr02Nsp7Jh2m7/PU62ziQfjln8zsTGd6f4HY+9OvVluhDleJLSC3k47nf0TPA/MUFpf0H5vuwev6129DujrGK8s8sDmBn6rWUG7zqtCEhtZAp76/i+uBNZvMHGHzUgzb5Na/X9Hj6No59u6rGd+nNDWzuWW53HyjRkAiO1pCl/q/OkcxQTuVWttnLvZjBQVE08yi2WkdUw6IarE5eaXO2Jg2k3NgUgB7+h+nmf1Jx/iYs6dhSH4pqyJSDvR5gQk8NbUy4gfwyP7Nj+MWIDVwXuB0/rzyzdZ3Bh0R81JwHgXIf0nIMiCKqIVENA2xLGkBmSWW9ll7ZDA6yPZkX1bCWx4HDmaGcFvDR2m1QomEtx5DePmRv/JIKL6ISr6ekoplZH5r03lqGXbTOYnytfNyE2uMI2PLRjVwXuM2ijzYUHzLpB9RpSEsNVxjc2ZgwjKKKygsSwb7xXN3W9hMGohrW0odq+mgWg4M2K87fhF5zodqx1e5DSx4E5jUUHBzM/PnzzW7LHA5dVGvq1KkApKamcsUVV3DFFVeYLVc74bIpbyp6gTu0ZyjL3p9htcyp+Fzuf2UDx8/m8NYLN/DqUxMVZg+7dlW+qxsfX/l4VEhICADh4eFW6z279cIL5FlbfqMk5TTeIaF1djxAWGgYXz+3rM7363cmct/L6xkzczsAS+fcyMgJlabf2r8pq+a/St9ebc3GV9p/YL4Pq+dfuw1K8y8sKqfHyIXEJxfUaYObG7z4WH8+fvVli3mtHBledyEJM9duQkNDmbR0Zp3vtdSQCI7WkKX+r052bgl3jv+HfUczefKuq5g3dazV8mriW8pBVIPVMRqNPPPWFrbuTSEzp4Tdq9/H18dTcf4mLOnYUh+KasiUg70eYEJPDT01bTPfLz1h1ocu7tCGtX//hKen+QeNnMGH1v2bwP2vbDCbfxv/pqy04qNmPQgU+5CWY0AUUQ2JahhgU3Qi42bt4GxiPl+/cw/33fyKzbxFNazlcUDUR2u3oTaO8FEt5iIm9NKQ0Wjk0hELOXE21+w4vqV/d5YtmGAxvlY+bkLtcQSs+2jHDq2s+mhD8SGTfkCdhrTUMMBbn+/h19WnSc0oJvqvVwlq52szd1ENa+lDG6MTGV/lo/dy382TFOdvQq+5UO3YavehJQ8C2z6khHpZZXr69OlC9U1XIGpfzVLCJSF+7P3jLkaMX8urT11uV3xfX9sDxhKthjxiV72h/TpwSYgf+46lYzBU3s0AaOLuRs/O/hYnceYQ6T+wrw0+zTx45PZLiPz9KHkFle/vmdoQ0t6XKU+bvzhijWPfrVZdx4RoH4iih4ZM+Ps1ZcsPdzJi/FrmTe1f7/FBrP/d3Nz4dsZgAEaMX2vzZNgSou2wtw1a9B/oo6G3x1zN2h0JVWPX9Ldlc0+ev/9Si5M4c+jhQ8OuCTLrox5N3OjRRZ2PmrDXh/T2ILBfQ1po+Pp+QRxaci8jxq/lvps765KDyD4Q9VHQz4O0iG2ivjXk5ubGG6Ou5OUPdpL532PqpnHcvnUzPnyln7XqddDDh6z56OgHeqryURPSh+zj7bG9eXtsb0aMX6voZFjr+CC2D24Q9FFwfR8SmQtZQ64yrYCsrCyysrLqNaabmxsbvr6NO4d0JLidD2/P38tF7X2498ZOrFlwa73mYi+zJvbh5cd70bGDL+1be/POF/vp26sN/3xxK+1bN9M7vXpFDw1JGhZ6aKhjh+asjLyZq3q0pkObZrw9fx+dgprzxqgree0Z9Re16psqHx18wUeD2/lwz7BOrJnvGj6qJdKHJKLooaEnRnTjg5f70uWiFrRv7c2MBfsIu8SfPz68gV7dWtVrLvbQsUNzVnxe00cvDmpO+KgrmfK0fTdqXBnpQxIRHKUfp/wdYmfDUT8CbQu/5l789dlN5OaXkpJRRIe2PjS38+6YHri5uTF9zNW8MepKziTm0bK5F+0a2YmwCb00JGk46KWhy7u3Zu8fd5GcXkh+YTmdgprj4eE611L9mnvx1xzX9VEtkT4kEUUvDT1zz6U8dVd3ziTm4eXRhIsCHXOXyFFccalr+6iWSB+SiOAo/TjlCbFbUKCiH6h2Cwp0eC6g/kegQ1T4tJKyfs298GuufEU1pf1nKmtPTmrKenq60+3ilrYLVqNFZ2X71lK5xqIhNftKDaIaENWgKFpoWFRDWu9DvTUU2MbHdqFqOJsPqfVRpR5kqazeY8AcemtILaLx9T4O6O2jWo8h0FdD7u5udLnIT9kG/8PZfFytjzZ2H3KEhtXSWHxI77mQ0rJqPUgpDl1l2pkYMX4ty+bepKqO6QVu028nmzq/b9++WqYmacA4k4bsGQPORkNog1qcSUMS18SZNOTqY9jV87cXZ9KQxPWovqiWM2jI1cexq+dvD5Y8CLTRkFPeIXY2HHU1QtJ4kBqSiCI1JBFFakgiitSQRBSpIYkIjtJP43yBQSKRSCQSiUQikUgkjR55h1gBcgEAiShSQxJRpIYkokgNSUSRGpKIIjUkEaFRLarlbMjHOySiSA1JRJEakogiNSQRRWpIIorUkEQER+nHKU+In5q2mZPncm2W69rRj+/eGezwfNRejXh7H8QXKCsb4gtvXWVHUg6MX/5ZJMbEZEX13YIC8Zg4RmWGtlHaBkv9p7QNlvIXjV8bR2nIEfoBcQ3oPQa2vDiPvDhl+bfoHMigT8fV+V5UQ1rjahpydR9yhvylDzmXj6tF1If0HgPmcDUN6T2XEEVvH3LEsVyNhvSeS0Dj8aGGOhdSilOeEJ88l8vWfSnC2ykvN/DLylNE/n6Uo6ezmfjeDl575go6tFW37L3aqxHxBbA/U2222iEa35iYDEdjlZW1P4xV6qsNlvLXeh/qpSGj0cjKzfHM/v4ge49l8PjUTbz1wtV07Wj9pytENaBl/x09nc30+Xs5djqbhLRC1v2bwI3XBlutkxeXTGr0MaG4ohrSGulDVsraH8YizpB/Q/GhwqJyFvx5lJ9XnOLkuVxmLNjHxEfDaNnC+s9gOYuPG41GVvzno/tU+KioD+k9BswhfchCOftDWEVvH3LE/lOjIS3jxyfn8+6X+9lxIJX45AJ+X32a+2/ujLu7m9V6zuJD9vpoffmQs3qQUhrsolrl5QZuem4Vo2duY+fBNHILypj76xH6PbKUwyezVG0rICCAgIAA4Zyydy0X3oYrx28I2NuHemjIaDTyZPhmHn19E1F7kskrKOP/lp9i0BPLWbU1XjiX+mDhP3Hc8PQK/lgTx4ETWWRkl3D/KxsYH7Fd79TqHelDEhDrPy00pDZ+bn4p1zy6jNc+28XeoxnkFpTxzhf76PvwUlIyioRyqQ9MPvrY65vYXMtHV29zDR/VEj00pDV6x28IuJoP7TqUxrWP/c0XC2M5cDyLrNxSnp2+hTvH/YPB4Py/PuvqPqolWs2FauOQE+KYmBgiIiIYNWoU77//PvPmzQPgjz/+4Isvvqj6DSmlPHNPd4Lb+zDpycsU1/l6cSz/HkyjsLgCgMjw/hiNcD6lkEdf36QqfkFBAQUFCp/ZqEXq33NIXjybojMHKT53mJKUM6q3sfCfOB6YtIG/N53TJX5k3Ikaf9Vy4mwOj0zZyLtf7rfbeKq3wx5E2qBFH+qhoa17k/k76hw5+WVA5RgASM4oYszM7ZSXGxTnIKoBe/ZfcUk5L83eSUpm8YU8wvuTnVfKb6tPExOboSqHXmPvwru1H10fGqqqXlVswT4QRU8fqqgw8Nbne3js9U2cTcyr9/gg3v9/CvgouL4Hgf0aEok/+eNojpzOoqys0vsjw/tTXmHkxLlcRk3foioPPXxoixUfHf2OOh8FMR/S24NAHw2ZSMss4qlpm3ll9k5KSivqPT6I7YOKCgNvzqv00XNJ6n0UpA/ZE99oNPK/N6JITC2s+i4yvD/5heVs3pvMH2tOq8pDDx+y6qNvq/NRcG0fEpkLWcMhJ8SLFi1i6tSpdOnShdGjR9O8eXMAiouLGTp0KEePHlW1vR+XnWR++AB+XKa8879cGEtxyQXDDG534THp5PQiVZM6Ly8vvLysP5JgiYrifJp1DMM7JBTvjmE0bd9JVf29R9IZPXM7f/4Tx6i3t3LibE69xgcoNlQw5/RxojLSVNc1GIzc9eI6fl11mne+3M+7X+1XvQ2o2Q57EGmDFn2oh4Y+/OEQWbmlVZ+rj4GMnBI271H2XhGI9R/Yt/9WbT1PelbNK5+mNqRnl/DJT4dU5ZC09SB9pj3OqYVRquqZEO0DUfT0odc/203E1zH8vOIUd01cV+/xQaz/9x5JZ8x/PvrcDPU+Cq7vQWC/hkTi/7MjAUO1c8bqPrT3aAYVFcpPKPXwoY809FEQ8yG9PQj00ZCJe19ez/dLT/DJ/x1izMxt9R4fxPbB65/tZtY3lT46coJ6HwXpQ/bEP3yy8umy6pjGcX5hOXN+OaIqDz18yJqP7juizkfBtX1IZC5kDTej0aj5swIRERH4+/sTFRXFjBkzWLBgATNnzmTFihVkZmby4IMP1rjdPXr0aBISEqo+b0saQGZJm6rPbVt5M2fKdYTP282p+Asnsq2apjOgg3lT3JhwA/llfkSG9ye4nQ/9erUl+lAaCamFvBixkWsDt9PSy/rCXf369QMgJ6dy8tSyZUsAoqOjrdZLGz6LssAwAIwGA3kHNlCcEEurQQ/i4demRlnP5MO0Xf66xW2dzw9mX3pvwA0wcE27f2nnY12EovHfwYtQmlR9jow7wZjO3ar+VucIFUyjFEtUGNzZkDCM4orKwRvkc57e7fZYzb92G2q3o90dY63mr6YNlvJX2oe29p+jNWQt/takgWSVtDY7BsbO3MrVbXcT5Jtktq6oBpTuP2ttOJvXkQMZlStMmGvD9A+XcE3gv2bzH3zUgzb5da/39Xj6No59u6rGd+nNDWzuWW53H9gaA6LoqSET0Sl9SSkKAsDHI5+hwetxs/7alVP5UG0fvbbdDtr6pCvOv3YblGhYi/xNOYgeR0Q1JBJ/XfxNFFX4mB3DL81az7DgdTRxNz+Z09LHQf1xBGz7aO+2u+lgwUdFfUjLMSCKnhoysSnhevLKKuO28U7jukDbr86IxtfyOBCd0o+Uog4A+HgUMDR4nSofhfr3Ia3msyb9gDoNaRE/o7gV0SnXUG70MjuOp7y/iuuDN1nMwRl8SMRHlfqQq86FwLyGgoODmT9/vuLtO2RRralTpwKQmprKpZdeyieffALAAw88YLZ87YQHPbG8xqJaj93RlSfCo5j4WBizv7vwiEFoaBjLfphidpsPvLKeP9eeYczMSsNcOufGqityIe1bsfqv72nmbb35u3btAiA+vvI9oZCQEADCw8Ot1nt264UX6LO2/EZJymm8Q0LrDF6AsNAwvn5umcVtFRaVc/MLq9lzOJ1rLw9kzRdf4uXZxGJ5LeKXTXlT8SIMoT1DWfb+DKtlxr67nWVR58jOKWHdLxPo2cX2s//V21C7HbbyV9MGS/kr7UNb+8/RGrIWf8aCfbzzxT6zYyCwjS+L/+8jOnZobrauqAaU7j9rbTh6Opvrn15BamZxnTZ4ebrz0aSRjHt4qtmcVo4MN7+IhJnrf6GhoUxaOrPO96Ia0go9NWRi75F0Hn5tI+eSChj78HV88PJEm3k7kw9V99HrrujA6gVfqfLR2m2or/xNOYgeR0Q1JBK/z0N/sedIhlkf6n5xe1b8/ZfF+Fr6OKg/jgC8PX8vM7/cb9FHF1nxUVEf0vpYLIKeGjIx+7sDfP7bUdKyivn508e4uf9rNvMWja/lcWDPkTQeeW3Tfz56LR+8PEFx/ibq24e0ms+a9APqNKRF/Jy8UsLuXkRCaqHZcTzq3n58+dbLFnNwBh8S8VGlPuSqcyGw7UNKcOgq09OnT9dkO6ZHI6ufDNti5vg+bNmXQnJ65SOXCf+9O+DbzIP7b+5s82S4Or6+viqyrUmrIY/YXRfAp5kHW76/gzvG/sOKz2/GzdblRI3jA1VXgGpfTVTK52/0Z/bL/Xjw1Q2KTobNIdoOkTZo0Yd6aGj8I6F8sySWc0mV71qYxoCnhzt9e7WxOIkzh6gG7GlDzy7+hHUNIGN3MhX/vXtuakNwOx+eGtld9TaPfbdadR0Ton0gip4+dHVoG44suZc7x6/lg5f72a6gcXwQ639RHwXX9yCwX0Mi8WeO781jr0dVPbJoGsMBfl689swVqralhw9NeDSMb/86romPmrDXh/T2INBHQyZefepyxj8Syn2vbODm/hfVe3wQ2we9Q9sK+ShIH7KHli28uHXARfyy6hRF/60rZBrHQe18CH/uSlXb08OHtPRRE67qQyJzIWs02FWmu3dqya/vXU+3jn60CWjK65/u4qL2vjx9d3dmv6LOiLKyssjKUrcytZa4ubnh0cTdrkmcs+DTzMOl8xdFDw0F+DVlzYJbuaxbAO1aefP6p7sIbufDyBs68sds+xaWqm/+nnMTtw26iKC2PrRs7snb8/dyVY/WrPvqNnx9PPVOr17R24eaNHHHo4nrHjIago+KooeGbh0Qwoev9OPioOa0aunF1M920zHQlzdGXclTd6m/qFXfmHy0V9cLPhrU1rV8VEv09iHvph64u/AYdnUf1QI9NLRg2gAeue0Sgtv74Nfck7c+38ulnVqy+ONhdl3Uqm9c3Ue1xFH6ccrfIdaK6/sFEfv3fcTEZpJXUMaVPVrRwlf9i9iO+hFoSeNBLw316OzPgUX3cCwum9SMInp28adtq2a65GIPvj6e/D33ZlIyioiNy6ZDWx+6XdzSdsUGiPQhiSh6aejJkd157I6u7D2aQXmFgd6hbWjqZf2RdWeiR2d/Di52XR/VEulDElH00JCHhztfvz2I7NwSDp7Iwr+FF726BbjUBVJX91GtcJR+nPKE2NaP3asp5+bmxpU9xDpP7Y9Ah6i4m6+mrCO2aa6sW1Cg4h/YdgsKVB5MBUrbYKmc0jZYyl80fm0cpSGl5Xp09qdHZ2WxQVwDWo+B9q2b0b618gloi87KdWmprKiGtEZvDanF1X3IGfJvSD7k4eFOv8vaKtvgfzibj6v1UVEf0nsMmKOh+pCj5hKi6O1DjpjPqtGQ1vH9/ZoyqLe6feVMPmSPjyr1oYY6F1KKQ1aZbiiYXuA2/W6yqfP79u1b77mMGL+WZXNvqve4WtIQ2qAWZ9KQxDVxJg25+hh29fztxZk0JHFNnElDrj6OXT1/e6i+qJYzaEjieljyINBGQ055h9jZcNTVCEnjQWpIIorUkEQUqSGJKFJDElGkhiQiOEo/jfvNfolEIpFIJBKJRCKRNFrkHWIFyEUkJKJIDUlEkRqSiCI1JBFFakgiitSQRIRGtaiWsyEf75CIIjUkEUVqSCKK1JBEFKkhiShSQxIRHKUfeUKsALVXI97eB/EFysqG+MJbV9mRlBXKP4vEmJisqKxbUCAeE8fU+E7v/AG2vDiPvDjbbWjROZBBn46r873SPjDXfkcgr4hKRHGUDzlqDLu6Dyn1IDDvQ6LtdwTShySiNFQfsjQG9c5f+pBEUhN5h1hH1F6NiC+A/ZnaxD4Vn8sH3x1g275kxr67nclPXcbFQS2s1jEmJsPRWEXbN7fEuJb55+SVsuCPo6zcep7jZ3LYvj+F665oZ/O33/LikkmNPmZ3XKV9UF9LrMsrohJR9PIho9FI1O4kPvnpMNv3p/DJjwcZdV8Pmvt4Wq/nRD5U3UfHRWzn1Sdt+2h9eRBIH5K4Dnr5UHFJOT/9fZJfV53m0Mkslked4/ZBIbi7W59LiM4F9PZR6UMSSU3kHWIdCQgI0GQ72buW4993uOLy3y6JZeqc3aRkFAMQ+ftRFq8/w2eTr+WBW7tokpMjOX4mh1teWM351ELKyw0A3DluLcOHhPD9zMEu9YPoomilIUnjRQ8fMhqN3P/KBtZHJ5KdWwrAa5/tZt5vR9nw9W02Tyqdgdo++vlvR1m09gxzXruW+29xfh/VEulDElG00JDauVB6VjGDnlzOmcR8iksqAHj0tU30Dm3DmgW34unp3OvDGo1G7nt5PRt2JdXx0Y3f3E7HDs11zrB+kT4kEcFR+nGIi8TExBAREcGoUaN4//33mTdvHgA7d+6s+rcrUVBQQEGBwmf3apH69xySF8+m6MxBis8dpiTljKJ6aZlFhM/dc+FkOLw/AMnpRbw0eye5+aWKc4iMO1Hjr1qqt0END7y6gTOJ+VUnw5Hh/cnMLWHpxrOs2Byvalu9xt6Fd2s/uj40VFU9E6J9IIqIhiQS0MeHfl5+ijXbz1dN4iLD+1NaZuD0+TwemrxRVQ56+FBqRhFvmPPRDPU+CmI+pLcHgfQhiTj2asheDwJ4ctpmjsXlVJ0MR4b3J7egjO0xqXz4g7p5iR4+9PPyU/yzI8Gsjz746gbVOUgfkjRmHKUfh5wQL1q0iKlTp9KlSxdGjx5N8+aVV7+uueaaqn+7El5eXnh5edlVt6I4n2Ydw/AOCcW7YxhN23dSVO+rRbGkZBZVfQ5u51P177SsIn5eeUpxDsWGCuacPk5URpriOtWp3galnDibQ1JaYY3vTG3IyS9j9ncHVOWQtPUgfaY9zqmFUarqmRDtA1FENCSRgD4+9Nkvh8kvLK/6XN2Hzibl1xnj1tDDh75eHEuqBR9NzSriFxU+CmI+pLcHgfQhiTj2asheDyosKmd/bEaN70zjuKS0gh//Vndip4cPaemjIH1I0rhxlH7cjEaj5q8NRERE4O/vT1RUFDNmzGDBggXMnDmT8+fPV/3b19e3qvzo0aNJSEjQOg1h+vXrB0BOTg4ALVu2BCA6OtpqvbThsygLDAPAaDCQd2ADxQmxtBr0IB5+bWqU9Uw+TNvlr9fZRkz6FZzL70RkeH+C2/nQr1dbog9VGlhCaiEfzfme0FZHzcZ/By9CaVL1OTLuBGM6d6v6W50jVDCNmndJqudfuw3t7hirKP+M4lZEp1xDudGrThsSUv+/vXuLjaKK4zj+650tUEppaWm7YFli7RJCiinKtRAotFQlATVifDIGlQZjCBFDqtQGCI0JKDEiYsQYICYmEBBBUMEgYrDRF2vkAYgIFqWNm1jkEi7xoVlt2RmZ3ZnZ2e1+P0/NZmfnnM3//DpndvecK1rVdlCzyr4ybL8kzfw5U4WX+9+vue/pBp16/2C/x7qH3Naxqpu6k9X3wKj/Toq1hoAwt3PIbAxL0tHfZuvyjTzDMfzi+qOaUnJCedl/GR6bCDl0txzduPkDVZnkqFEGSdZzyG7/nUQOwS67ORTrtdC1mzk6drFW12/5DHNo5YbDmlP+pen57V4LWM0ht3J0oORQuH4kcgixMcsgybiGysrKtGXLFsuv78pviFevXi1JunTpkiorK7Vp0yZJ6vd3X9E0OJ7a29slSefP93691+/3S5Kam5v/97hnjv+3CEPo6490/Y+zGuQPRvwDkKTxwfF6b+m+iMd3fnpaS1/7RsvWnpAk7d08Vwtf+EKSlDc4Szs3NOmh2tGG57+x6lXLiygEq4La19Zq2v47+2C1/d2ha5r46B51dl0x7MOShmrtalth2q4DC5sjF5IwuHcTDAa1cu/aiMetvgdG/XdSrDUEhLmdQ2ZjWJIalx3SgeMXDMdwefFw7d+93XRRmETIoR37T+vZVvMc3dXWpMaZxjlqmEGS5Ryy238nkUOwy24OxXotdOvWbQUaP9a5zsuG43jyhArt22mcX5L9awGrOeRWjg6UHArXj0QOITZmGSQ5U0OuLqrV0tLi5svHTd9Ps6NVUPtkTMc9Nq9Ca97+QWfO90jq/TQjbFRRrhbM8JsdGiF8F/DOu4FWxdKHwuGDNK16pPYc+fXf3xCH+1A8wqc1z0W/P8Gp7Z9FfUyY3ffALjs1BEje5NDa5fer/adudYV6f4MbHsM52emqm1J21xVS+/Iihx6f35ujZy9E5mjpyFw1TLeeo2Gx5pDXGSSRQ7Av1hqKNYMyMtL1VOM4vbGjQ39f7f30MzyOC4blqHXZpKhez4sccjJHw8ghpCq36iexl+ZLEKFQSKFQKK7nzM7K0KF36hUM5KtgWI6a1p3QiPwcTby3QJ+/W3/XrQYSwYfralU/tUwlhT6lp0svbfxOY0YN0bY101RZke918+LKixrCwOJFDVVXFWrzyw/KXzJYg32ZWr7+W40q9Onh2tHa+sr0uLYlFtlZGTq8tV7BsZE5enhrcuSok8gh2OVFDbU2TdKShrEqLcpVZkaaVrx+UuXFuWp5vlrzp5XHtS2xqK4q1JurInP0kVnJkaNOI4dgh1v1w7ZLFni1iXjAn6eO3YvU3tGtXzp7NM6fp0nByK8aJapBOZn65K15OtfZo5M/dil/aLZm15Qm/BYJbmAjetjlVQ090RDQorn36MjJi+q5ckNTJ45UWXHy3OEP+PPUsSd5c9RJ5BDs8qKG0tPTtK1lhrr+vKpj3/+u7KwMzXmgVLm+5LmEXbIgoMV1yZujTiKHYIdb9ZM8aeIhLzcRT0tL0+QJRZo8oSju53bKmNKhSbFfqZvYiB52eVlD2VkZqp+e+J/EmBkIOeoEcgh2eVlDRQU+La6riPt5nZLsOeoUcgh2uFU/TIgtiPZuhD+Km37RPNeqtNISWV06PK20JOIxr9svSUMrItsVzfOsvgdG/XcDd0Rhl1s55NYYTvYcsppBZs+12383kEOwa6DmkNkY9Lr95BDQn1v148q2SwNFeEWzM2d696oMBAKSpJqaGs/ahORCDcEuagh2UUOwixqCHX1XmaaGEAuzDJKcqSEmxAAAAACAlJR6qxsBAAAAACAmxAAAAACAFMWEGAAAAACQkpgQAwAAAABSEhNiAAAAAEBKYkIMAAAAAEhJTIgBAAAAACmJCTEAAAAAICUxIQYAAAAApCQmxAAAAACAlMSEGAAAAACQkv4B+j1PZUweoTQAAAAASUVORK5CYII=", "text/plain": [ - "
" + "\"Output" ] }, "execution_count": 3, @@ -145,6 +156,7 @@ }, { "cell_type": "markdown", + "id": "a674e407-504d-4812-82bf-98e91ec9a4b4", "metadata": {}, "source": [ "Let's now build the observable, $\\hat{X}_{n=t}$. It is constructed as a simple Pauli string with the order matching the one used by Qiskit:" @@ -153,6 +165,7 @@ { "cell_type": "code", "execution_count": 4, + "id": "a9a87f6c-176d-4c85-85e5-6751aea0c90b", "metadata": {}, "outputs": [], "source": [ @@ -164,6 +177,7 @@ }, { "cell_type": "markdown", + "id": "ba5f7042-4abd-4ae7-a091-591678377e8f", "metadata": {}, "source": [ "In our small 12 qubit, 6 time steps example, the observable looks like this:" @@ -172,6 +186,7 @@ { "cell_type": "code", "execution_count": 5, + "id": "b2608df1-b4e4-4143-bea5-a65ab8045fd4", "metadata": {}, "outputs": [ { @@ -191,6 +206,7 @@ }, { "cell_type": "markdown", + "id": "e588fafe-8db8-4445-8893-a78190b27b64", "metadata": {}, "source": [ "Qiskit functions use PUBs as the way to collect the inputs. In our case, let's consider a single circuit and observable as our PUB:" @@ -199,6 +215,7 @@ { "cell_type": "code", "execution_count": 6, + "id": "fc48eb54-148b-4b0d-8424-a135cb92039e", "metadata": {}, "outputs": [], "source": [ @@ -208,6 +225,7 @@ }, { "cell_type": "markdown", + "id": "9a4bcd8d-ae21-40ab-b0e2-510236ba92de", "metadata": {}, "source": [ "Next, we get access to the TEM qiskit function. Let's first set up the required authentication to the IBM cloud and select a backend from the available devices. The token, available backends and corresponding cloud resource names (CRN) can be obtained by logging in to your account at `https://quantum.cloud.ibm.com/`." @@ -216,6 +234,7 @@ { "cell_type": "code", "execution_count": 7, + "id": "6c9f80a8-4a65-4daa-94bb-a98edd6a1989", "metadata": {}, "outputs": [], "source": [ @@ -232,6 +251,7 @@ }, { "cell_type": "markdown", + "id": "10df1803-5245-42b2-8eea-c0773cd655b6", "metadata": {}, "source": [ "Let's load the TEM qiskit function from the qiskit function catalog:" @@ -240,6 +260,7 @@ { "cell_type": "code", "execution_count": 9, + "id": "2473b284-108f-45fe-a8d8-3aed584137f6", "metadata": {}, "outputs": [], "source": [ @@ -254,6 +275,7 @@ }, { "cell_type": "markdown", + "id": "3c732819-4dca-421c-bc2b-45ff5a5912db", "metadata": {}, "source": [ "We can now run an experiment on the kicked Ising circuit with error mitigation provided by TEM. Using default settings, TEM can be run in a simple way with an expected QPU run time of around 5 minutes depending on the chosen QPU:" @@ -262,6 +284,7 @@ { "cell_type": "code", "execution_count": 10, + "id": "b826e025-f36b-4fb5-90bd-e1ef36f5c1b2", "metadata": {}, "outputs": [], "source": [ @@ -270,6 +293,7 @@ }, { "cell_type": "markdown", + "id": "4b692a80-5a10-4131-9d7f-785fedbe4221", "metadata": {}, "source": [ "With default options, TEM function runs three jobs on the quantum computer: noise learning, readout mitigation and circuit sampling. The number of shots used by each of these can be changed in the options passed to the function. By default, these parameters are set to achieve a precision of 0.05 in the mitigated expectation values." @@ -277,6 +301,7 @@ }, { "cell_type": "markdown", + "id": "25b6f313-a928-493e-837f-45e6e7836aef", "metadata": {}, "source": [ "You can check the status of your job at [quantum.cloud.ibm.com](https://quantum.cloud.ibm.com/) or with:" @@ -285,6 +310,7 @@ { "cell_type": "code", "execution_count": 11, + "id": "05e202ff-5b86-4a93-a693-86fbb1cf3e02", "metadata": {}, "outputs": [ { @@ -301,6 +327,7 @@ }, { "cell_type": "markdown", + "id": "8e427c75-72fb-4a97-b723-97d695a692d3", "metadata": {}, "source": [ "We can now check the raw results and the mitigated ones. The `tem_evs` defined below are the expectation values of the requested observables, in this case just one observable, $\\langle \\hat X_{n=t}\\rangle$, and `tem_std` are the corresponding standard deviations." @@ -309,6 +336,7 @@ { "cell_type": "code", "execution_count": 12, + "id": "3ca34069-1363-4e37-9718-91639d817a82", "metadata": {}, "outputs": [ { @@ -321,7 +349,9 @@ ], "source": [ "# Get the results of the TEM job\n", - "tem_results = tem_job.result()[0] # Get the first and only result from the job\n", + "tem_results = tem_job.result()[\n", + " 0\n", + "] # Get the first and only result from the job\n", "tem_evs = tem_results.data.evs[0]\n", "tem_std = tem_results.data.stds[0]\n", "\n", @@ -330,6 +360,7 @@ }, { "cell_type": "markdown", + "id": "f90f503e-ab80-4550-a7cf-dfeea12babb0", "metadata": {}, "source": [ "We can also check how much quantum runtime was used for each call at [quantum.ibm.com](quantum.ibm.com), or inspecting the result metadata from the Python code." @@ -338,6 +369,7 @@ { "cell_type": "code", "execution_count": 13, + "id": "b05818d6-b680-483e-9084-f3fd2de067ab", "metadata": {}, "outputs": [ { @@ -350,15 +382,16 @@ ], "source": [ "# Get the runtime of the TEM job\n", - "tem_runtime = tem_job.result().metadata[\"resource_usage\"][\"RUNNING: EXECUTING_QPU\"][\n", - " \"QPU_TIME\"\n", - "]\n", + "tem_runtime = tem_job.result().metadata[\"resource_usage\"][\n", + " \"RUNNING: EXECUTING_QPU\"\n", + "][\"QPU_TIME\"]\n", "\n", "print(f\"TEM Runtime: {tem_runtime} seconds\")" ] }, { "cell_type": "markdown", + "id": "6be333a8-41c9-4ba9-b07d-a0ac50149add", "metadata": {}, "source": [ "## Customizing TEM parameters and advanced options" @@ -366,6 +399,7 @@ }, { "cell_type": "markdown", + "id": "abee6fc2-90d6-4608-ad21-c606c936dd94", "metadata": {}, "source": [ "The TEM Qiskit function provides several advanced options to customize your error mitigation workflow. These options allow you to control the precision, number of shots, noise learning strategies, and other parameters to better suit your experiment's requirements and available quantum resources.\n", @@ -384,6 +418,7 @@ }, { "cell_type": "markdown", + "id": "24db681c-b306-41e0-8507-626ef279b076", "metadata": {}, "source": [ "You can pass these options as a dictionary to the `options` argument when running the TEM function:" @@ -392,6 +427,7 @@ { "cell_type": "code", "execution_count": null, + "id": "a2e9a032-91cb-4a18-9a00-00a149e60459", "metadata": {}, "outputs": [], "source": [ @@ -407,6 +443,7 @@ }, { "cell_type": "markdown", + "id": "db700868-4dae-48c8-be1a-668ef2e63177", "metadata": {}, "source": [ "Custom options for the noise learner can also be passed. They follow the definitions used in the Qiskit [`NoiseLearnerOptions`](https://quantum.cloud.ibm.com/docs/en/api/qiskit-ibm-runtime/options-noise-learner-options):" @@ -415,6 +452,7 @@ { "cell_type": "code", "execution_count": 15, + "id": "30591014-3bc6-4548-ba0d-dc5cc22e9dcc", "metadata": {}, "outputs": [], "source": [ @@ -430,6 +468,7 @@ }, { "cell_type": "markdown", + "id": "216ad12c-8c70-4073-8515-b07fd57f74d4", "metadata": {}, "source": [ "Let's try re-running the experiment with these custom options specifically tuned to the circuit at hand. The expected runtime is around 15 QPU minutes." @@ -438,14 +477,18 @@ { "cell_type": "code", "execution_count": 16, + "id": "ebce8e14-433f-4858-96c6-9d90ff0353af", "metadata": {}, "outputs": [], "source": [ - "tem_job_custom = tem.run(pubs=pubs, backend_name=backend_name, options=options)" + "tem_job_custom = tem.run(\n", + " pubs=pubs, backend_name=backend_name, options=options\n", + ")" ] }, { "cell_type": "markdown", + "id": "bd8d2c12-c9da-4ac3-97c0-d53be1455091", "metadata": {}, "source": [ "If the job is not set as private, we can save the job id and recover the result at a later point:" @@ -454,6 +497,7 @@ { "cell_type": "code", "execution_count": 17, + "id": "0f99101b-9e72-45c8-8b00-9f3a257b8b3b", "metadata": {}, "outputs": [ { @@ -472,6 +516,7 @@ { "cell_type": "code", "execution_count": null, + "id": "22729b9e-be9c-4ded-b214-49f2b202577c", "metadata": {}, "outputs": [], "source": [ @@ -482,6 +527,7 @@ { "cell_type": "code", "execution_count": 19, + "id": "0c751dac-e856-4371-aaed-f67aca31061f", "metadata": {}, "outputs": [ { @@ -502,6 +548,7 @@ }, { "cell_type": "markdown", + "id": "edfef6f9-6bac-42bb-8bd2-95f977f7b31b", "metadata": {}, "source": [ "We can now inspect the results and the metadata to get insight into the experiment:" @@ -510,6 +557,7 @@ { "cell_type": "code", "execution_count": 20, + "id": "dd189b2d-860b-4b9a-88c2-7e5c62b1f160", "metadata": {}, "outputs": [ { @@ -536,13 +584,13 @@ { "cell_type": "code", "execution_count": 21, + "id": "c3a2168d-98df-491e-a1f8-05de5684ab96", "metadata": {}, "outputs": [ { "data": { - "image/png": "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", "text/plain": [ - "
" + "\"Output" ] }, "metadata": {}, @@ -565,6 +613,7 @@ }, { "cell_type": "markdown", + "id": "d643bdb4-22e0-4f55-b3a8-d5ef39f6e696", "metadata": {}, "source": [ "Finally, we can check the impact of the custom options on QPU and classical runtime:" @@ -573,6 +622,7 @@ { "cell_type": "code", "execution_count": 22, + "id": "09cf2226-c48c-483b-aa49-80186229ae95", "metadata": {}, "outputs": [ { @@ -589,9 +639,13 @@ "job_metadata = results_custom.metadata\n", "\n", "# Get the runtime of the TEM job\n", - "qpu_runtime = job_metadata[\"resource_usage\"][\"RUNNING: EXECUTING_QPU\"][\"QPU_TIME\"]\n", + "qpu_runtime = job_metadata[\"resource_usage\"][\"RUNNING: EXECUTING_QPU\"][\n", + " \"QPU_TIME\"\n", + "]\n", "classical_runtime = (\n", - " job_metadata[\"resource_usage\"][\"RUNNING: OPTIMIZING_FOR_HARDWARE\"][\"CPU_TIME\"]\n", + " job_metadata[\"resource_usage\"][\"RUNNING: OPTIMIZING_FOR_HARDWARE\"][\n", + " \"CPU_TIME\"\n", + " ]\n", " + job_metadata[\"resource_usage\"][\"RUNNING: POST_PROCESSING\"][\"CPU_TIME\"]\n", ")\n", "\n", @@ -601,6 +655,7 @@ }, { "cell_type": "markdown", + "id": "7cea6cf1-5530-4bf6-83da-ad2e9ff96806", "metadata": {}, "source": [ "## Scaling TEM to large circuits\n", @@ -613,6 +668,7 @@ { "cell_type": "code", "execution_count": 23, + "id": "f7ea1d3c-d745-48cc-8922-b070b2b5fd44", "metadata": {}, "outputs": [], "source": [ @@ -634,6 +690,7 @@ }, { "cell_type": "markdown", + "id": "854c3208-8c0f-4f7d-b260-0abba2bc71a0", "metadata": {}, "source": [ "Let's define some performance-oriented options:" @@ -642,6 +699,7 @@ { "cell_type": "code", "execution_count": null, + "id": "64882a71-3027-4e25-b714-9e9d6b13cd49", "metadata": {}, "outputs": [], "source": [ @@ -660,6 +718,7 @@ }, { "cell_type": "markdown", + "id": "4ba36257-1974-4274-b04c-6daf3afe9d72", "metadata": {}, "source": [ "Finally, let's run the experiment, get the result and visualize it. This will take around 4 QPU minutes." @@ -668,6 +727,7 @@ { "cell_type": "code", "execution_count": 25, + "id": "6faf7f80-dec9-49d2-80e7-d4e6fdea5100", "metadata": {}, "outputs": [], "source": [ @@ -677,6 +737,7 @@ { "cell_type": "code", "execution_count": 26, + "id": "333b2335-b480-4bf9-854c-5155eedee900", "metadata": {}, "outputs": [ { @@ -695,6 +756,7 @@ { "cell_type": "code", "execution_count": null, + "id": "02115e11-4638-433a-b825-8891173b67ed", "metadata": {}, "outputs": [], "source": [ @@ -705,6 +767,7 @@ { "cell_type": "code", "execution_count": 28, + "id": "a04dd421-a212-473c-a8a9-4c8edcfc3667", "metadata": {}, "outputs": [ { @@ -729,9 +792,13 @@ "job_metadata = tem_job_large.result().metadata\n", "\n", "# Get the runtime of the TEM job\n", - "qpu_runtime = job_metadata[\"resource_usage\"][\"RUNNING: EXECUTING_QPU\"][\"QPU_TIME\"]\n", + "qpu_runtime = job_metadata[\"resource_usage\"][\"RUNNING: EXECUTING_QPU\"][\n", + " \"QPU_TIME\"\n", + "]\n", "classical_runtime = (\n", - " job_metadata[\"resource_usage\"][\"RUNNING: OPTIMIZING_FOR_HARDWARE\"][\"CPU_TIME\"]\n", + " job_metadata[\"resource_usage\"][\"RUNNING: OPTIMIZING_FOR_HARDWARE\"][\n", + " \"CPU_TIME\"\n", + " ]\n", " + job_metadata[\"resource_usage\"][\"RUNNING: POST_PROCESSING\"][\"CPU_TIME\"]\n", ")\n", "\n", @@ -742,13 +809,13 @@ { "cell_type": "code", "execution_count": 29, + "id": "24894c44-e399-4b9d-a3ff-38a28ff32ece", "metadata": {}, "outputs": [ { "data": { - "image/png": "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RS+88IIKCwvro0cAAACHGQ43OTk5tq98+/j46Pz585KkqKgorVu3zrndAQAAGGQ43AQGBtrOUNy+fXt9++23kq5cc6q6i2kCAAA0JMPh5v7779fnn38uSYqJidGMGTP04IMPKjIyUmPHjnV6gwAAAEYY/rbU8uXLVVlZKUl67rnn1LJlS+3YsUOjR4/W1KlTnd4gAACAEYbDzcmTJxUUFGS7PX78eI0fP15Wq1UnTpxQ+/btndogAACAEYYPS3Xs2FFnzpypMn727Fl17NjRKU0BAADUldOuCl5cXCxvb2+nNAUAAFBXDh+Wio2NlXTlquBz5sxR06ZNbfdVVFRo586dCg0NdXqDAAAARjgcbvbs2SPpyszN/v375enpabvP09NTvXv31syZM53fIQAAgAEOh5tt27ZJuvL173feeUe+vr711hQAAEBdGV5zs3jxYl2+fLnK+NmzZ1VUVOSUpgAAAOrKcLgZP3681q9fX2U8LS1N48ePd0pTAAAAdWU43OzcuVNDhgypMj548GDt3LnTKU0BAADUleFwU1paWu1hqfLycl28eNEpTQEAANSV4XDTv39/LV++vMp4SkqK+vXr55SmAAAA6srw5Rdee+01RUREaO/evXrggQckSenp6fruu+/05ZdfOr1BAAAAIwzP3Nxzzz3KzMzU7bffrrS0NP35z39W586dtW/fPt1333310SMAAIDDDM/cSFJoaKjWrl3r7F4AAACum+GZG0k6cuSIXn31VU2YMEGnT5+WJP33f/+3/vd//9epzQEAABhlONz89a9/Va9evbRz507913/9l4qLiyVJe/fuVUJCgtMbBAAAMMJwuHnppZf02muvacuWLXbXl7r//vv17bffOrU5AAAAowyHm/3792vs2LFVxlu3bq2CggKnNAUAAFBXhsNNixYtlJubW2V8z549ateunVOaAgAAqKs6XVtq9uzZysvLk8ViUWVlpbZv366ZM2cqOjq6PnoEAABwmOFw88Ybb6hbt24KCgpScXGxevTooX/913/VwIED9eqrr9ZHjwAAAA4zfJ4bT09PrVixQnPmzNGBAwdUXFysPn366M4776yP/gAAAAyp00n8JKl9+/YKCgqSJFksFqc1BAAAcD3qdBK/VatWqWfPnvL29pa3t7d69uyplStXOrs3AAAAwwzP3MTHxys5OVnPP/+8wsPDJUmZmZmaMWOGcnJyNG/ePKc3CQAA4CjD4WbZsmVasWKFHn/8cdvY6NGjFRISoueff55wAwAAXMrwYany8nKFhYVVGe/Xr58uX77slKYAAADqynC4iYqK0rJly6qML1++XBMnTnRKUwAAAHVVp29LrVq1Sl9++aXuvvtuSdLOnTuVk5Oj6OhoxcbG2uqSk5Od0yUAAICDDIebAwcOqG/fvpKkI0eOSJL8/f3l7++vAwcO2Or4ejgAAHAFw+Fm27Zt9dEHAACAUxhec3PmzJka79u/f3+dmli6dKmCg4Pl7e2tAQMGaNeuXQ7tt379elksFo0ZM6ZOzwsAAMzHcLjp1auXvvjiiyrjCxcuVP/+/Q03sGHDBsXGxiohIUFZWVnq3bu3hg4dqtOnT9e63/HjxzVz5kzdd999hp8TAACYl+FwExsbq0ceeUTPPvusLl68qFOnTumBBx7Qm2++qbVr1xpuIDk5WVOmTFFMTIx69OihlJQUNW3aVKmpqTXuU1FRoYkTJyoxMVF33HGH4ecEAADmZTjczJo1S5mZmfr6668VEhKikJAQeXl5ad++fRo7dqyhxyorK9Pu3bsVERFxrSE3N0VERCgzM7PG/ebNm6fWrVvrqaee+tXnKC0tVVFRkd0GAADMq07XlurcubN69uyp48ePq6ioSJGRkQoMDDT8OAUFBaqoqFBAQIDdeEBAgPLy8qrd55tvvtGqVau0YsUKh54jKSlJfn5+tu3qxT4BAIA5GQ4327dvV0hIiH744Qft27dPy5Yt0/PPP6/IyEj93//9X330aHP+/HlFRUVpxYoV8vf3d2ifuLg4FRYW2rYTJ07Ua48AAMC1DH8V/P7779eMGTM0f/58NWnSRN27d9eQIUP0xBNPqFevXjp58qTDj+Xv7y93d3fl5+fbjefn51c7E3TkyBEdP35co0aNso1VVlZeeSEeHjp06JA6depkt4+Xl5e8vLyMvEQAAHADMzxz8+WXX2rBggVq0qSJbaxTp07avn27pk6dauixPD091a9fP6Wnp9vGKisrlZ6ebrvi+C9169ZN+/fvV3Z2tm0bPXq0hgwZouzsbA45AQAA4zM3gwYNqnbczc1Nc+bMMdxAbGysJk2apLCwMPXv31+LFy9WSUmJYmJiJEnR0dFq166dkpKS5O3trZ49e9rt36JFC0mqMg4AAG5ODs/cjBgxQoWFhbbbCxYs0Llz52y3f/75Z/Xo0cNwA5GRkVq4cKHi4+MVGhqq7Oxsbdq0ybbIOCcnR7m5uYYfFwAA3JwsVqvV6kihu7u7cnNz1bp1a0mSr6+vsrOzbeeZyc/PV9u2bVVRUVF/3TpBUVGR/Pz8VFhYKF9fX1e347DExERXtwA4VUJCgqtbMMySkeHqFgCnsQ4e7OoWDDHy+e3wzM0/ZyAHMxEAAECDqtN5bgAAABorh8ONxWKRxWKpMgYAANCYOPxtKavVqsmTJ9vOGXPp0iU988wzuuWWWyRducwBAACAqzkcbiZNmmR3+4knnqhSEx0dff0dAQAAXAeHw83q1avrsw8AAACnYEExAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwFcINAAAwlUYRbpYuXarg4GB5e3trwIAB2rVrV421K1as0H333adbb71Vt956qyIiImqtBwAANxeXh5sNGzYoNjZWCQkJysrKUu/evTV06FCdPn262vqMjAw9/vjj2rZtmzIzMxUUFKSHHnpIp06dauDOAQBAY+TycJOcnKwpU6YoJiZGPXr0UEpKipo2barU1NRq6z/88ENNmzZNoaGh6tatm1auXKnKykqlp6c3cOcAAKAxcmm4KSsr0+7duxUREWEbc3NzU0REhDIzMx16jAsXLqi8vFy33XZbtfeXlpaqqKjIbgMAAObl0nBTUFCgiooKBQQE2I0HBAQoLy/PoceYPXu22rZtaxeQfikpKUl+fn62LSgo6Lr7BgAAjZfLD0tdjwULFmj9+vX69NNP5e3tXW1NXFycCgsLbduJEycauEsAANCQPFz55P7+/nJ3d1d+fr7deH5+vgIDA2vdd+HChVqwYIG2bt2qkJCQGuu8vLzk5eXllH4BAEDj59KZG09PT/Xr189uMfDVxcHh4eE17vfmm29q/vz52rRpk8LCwhqiVQAAcINw6cyNJMXGxmrSpEkKCwtT//79tXjxYpWUlCgmJkaSFB0drXbt2ikpKUmS9O///u+Kj4/X2rVrFRwcbFub06xZMzVr1sxlrwMAADQOLg83kZGROnPmjOLj45WXl6fQ0FBt2rTJtsg4JydHbm7XJpiWLVumsrIyPfroo3aPk5CQoLlz5zZk6wAAoBFyebiRpN/97nf63e9+V+19GRkZdrePHz9e/w0BAIAb1g39bSkAAIB/RrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACmQrgBAACm0ijCzdKlSxUcHCxvb28NGDBAu3btqrX+o48+Urdu3eTt7a1evXpp48aNDdQpAABo7FwebjZs2KDY2FglJCQoKytLvXv31tChQ3X69Olq63fs2KHHH39cTz31lPbs2aMxY8ZozJgxOnDgQAN3DgAAGiOXh5vk5GRNmTJFMTEx6tGjh1JSUtS0aVOlpqZWW//OO+9o2LBh+rd/+zd1795d8+fPV9++fbVkyZIG7hwAADRGHq588rKyMu3evVtxcXG2MTc3N0VERCgzM7PafTIzMxUbG2s3NnToUH322WfV1peWlqq0tNR2u7CwUJJUVFR0nd03rEuXLrm6BcCpbrS/QUlSSYmrOwCc5kb7G7zar9Vq/dVal4abgoICVVRUKCAgwG48ICBABw8erHafvLy8auvz8vKqrU9KSlJiYmKV8aCgoDp2DcAZFixY4OoWgJuan6sbqKPz58/Lz6/27l0abhpCXFyc3UxPZWWlzp49q5YtW8pisbiwMzRGRUVFCgoK0okTJ+Tr6+vqdoCbDn+DqInVatX58+fVtm3bX611abjx9/eXu7u78vPz7cbz8/MVGBhY7T6BgYGG6r28vOTl5WU31qJFi7o3jZuCr68vb6yAC/E3iOr82ozNVS5dUOzp6al+/fopPT3dNlZZWan09HSFh4dXu094eLhdvSRt2bKlxnoAAHBzcflhqdjYWE2aNElhYWHq37+/Fi9erJKSEsXExEiSoqOj1a5dOyUlJUmSpk+frkGDBmnRokUaOXKk1q9fr++//17Lly935csAAACNhMvDTWRkpM6cOaP4+Hjl5eUpNDRUmzZtsi0azsnJkZvbtQmmgQMHau3atXr11Vf18ssv684779Rnn32mnj17uuolwES8vLyUkJBQ5VAmgIbB3yCcwWJ15DtVAAAANwiXn8QPAADAmQg3AADAVAg3AADAVAg3uCmsWbPGofMbWSyWGi/l0RhMnjxZY8aMcXUbANCoEW7QYAYPHqzf//73VcYdDR7XIzIyUocPH7bdnjt3rkJDQ6vU5ebmavjw4U59bgIJbkYWi6XWbe7cuTp+/HiN93/77beSrrw/WCwWde/evcpzfPTRR7JYLAoODm7gV4fGzuVfBQcago+Pj3x8fH61rqYzXQMwJjc31/bzhg0bFB8fr0OHDtnGmjVrpoKCAknS1q1bddddd9nt37JlS9vPt9xyi06fPq3MzEy7E7auWrVK7du3r6+XgBsYMzdoVK7OcixcuFBt2rRRy5Yt9dxzz6m8vNxWExwcrNdee03R0dFq1qyZOnTooM8//1xnzpzRww8/rGbNmikkJETff/+9bZ9fzg6tWbNGiYmJ2rt3r+1fiWvWrJFU9bDUjh07FBoaKm9vb4WFhemzzz6TxWJRdna2JKmiokJPPfWUOnbsKB8fH3Xt2lXvvPOObf+5c+fq/fff15/+9Cfbc2VkZEiSTpw4occee0wtWrTQbbfdpocffljHjx+37VtRUaHY2Fi1aNFCLVu21KxZsxy6Gi7QGAQGBto2Pz8/WSwWu7FmzZrZalu2bGl3X2BgoJo0aWK738PDQxMmTFBqaqpt7OTJk8rIyNCECRMa9HXhxkC4QaOzbds2HTlyRNu2bdP777+vNWvW2MLHVW+//bbuuece7dmzRyNHjlRUVJSio6P1xBNPKCsrS506dVJ0dHS1YSAyMlIvvvii7rrrLuXm5io3N1eRkZFV6oqKijRq1Cj16tVLWVlZmj9/vmbPnm1XU1lZqdtvv10fffSR/va3vyk+Pl4vv/yy0tLSJEkzZ87UY489pmHDhtmea+DAgSovL9fQoUPVvHlzff3119q+fbuaNWumYcOGqaysTJK0aNEirVmzRqmpqfrmm2909uxZffrpp076LQM3lieffFJpaWm6cOGCpCv/SBk2bJjthK/AL3FYCo3OrbfeqiVLlsjd3V3dunXTyJEjlZ6erilTpthqRowYoalTp0qS4uPjtWzZMv3Lv/yLfvOb30iSZs+erfDw8Govqurj46NmzZrJw8Oj1sNQa9eulcVi0YoVK+Tt7a0ePXro1KlTdn00adJEiYmJttsdO3ZUZmam0tLS9Nhjj6lZs2by8fFRaWmp3XP953/+pyorK7Vy5Urb1elXr16tFi1aKCMjQw899JAWL16suLg4jRs3TpKUkpKizZs31/XXCjRaAwcOtDsTvSQVFxfb3e7Tp4/uuOMOffzxx4qKitKaNWuUnJyso0ePNmSruEEQbtDo3HXXXXJ3d7fdbtOmjfbv329XExISYvv56r/cevXqVWXs9OnTdV5Hc+jQIYWEhMjb29s21r9//yp1S5cuVWpqqnJycnTx4kWVlZVVu1j5l/bu3asff/xRzZs3txu/dOmSjhw5osLCQuXm5mrAgAG2+zw8PBQWFsahKZjOhg0bql0w/M+efPJJrV69Wu3bt1dJSYlGjBihJUuWNECHuNEQbtBgfH19VVhYWGX83Llzdpex/+WxdunKOpjKykq7sV/WXJ35qG7sn/dztvXr12vmzJlatGiRwsPD1bx5c7311lvauXNnrfsVFxerX79++vDDD6vc16pVq/pqF2iUgoKC1Llz51+tmzhxombNmqW5c+cqKipKHh58hKF6rLlBg+natauysrKqjGdlZalLly4N2ounp6cqKipqrenatav279+v0tJS29h3331nV7N9+3YNHDhQ06ZNU58+fdS5c2cdOXLkV5+rb9+++uGHH9S6dWt17tzZbvPz85Ofn5/atGljF5IuX76s3bt31/UlAze82267TaNHj9Zf//pXPfnkk65uB40Y4QYN5tlnn9Xhw4f1wgsvaN++fTp06JCSk5O1bt06vfjiiw3aS3BwsI4dO6bs7GwVFBTYBZirJkyYoMrKSv32t7/V3//+d23evFkLFy6UdG1m6M4779T333+vzZs36/Dhw5ozZ06VABQcHGx7vQUFBSovL9fEiRPl7++vhx9+WF9//bWOHTumjIwMvfDCCzp58qQkafr06VqwYIE+++wzHTx4UNOmTdO5c+fq9xcDuMDPP/+svLw8u+3SpUvV1q5Zs0YFBQXq1q1bA3eJGwnhBg3mjjvu0FdffaWDBw8qIiJCAwYMUFpamj766CMNGzasQXt55JFHNGzYMA0ZMkStWrXSunXrqtT4+vrqz3/+s7KzsxUaGqpXXnlF8fHxkmRbhzN16lSNGzdOkZGRGjBggH7++WdNmzbN7nGmTJmirl27KiwsTK1atdL27dvVtGlTffXVV2rfvr3GjRun7t2766mnntKlS5fk6+srSXrxxRcVFRWlSZMm2Q55jR07tp5/M0DDi4iIUJs2bey2ms4U7uPjY3cOHKA6FiurEwGHffjhh4qJiVFhYaFDJwUEADQ8VmMBtfjggw90xx13qF27dtq7d69mz56txx57jGADAI0Y4QaoRV5enuLj45WXl6c2bdroN7/5jV5//XVXtwUAqAWHpQAAgKmwoBgAAJgK4QYAAJgK4QYAAJgK4QYAAJgK4QYAAJgK4QYAAJgK4QYAAJgK4QYAAJgK4QYAAJjK/wOuF7Q4Z53ExwAAAABJRU5ErkJggg==", "text/plain": [ - "
" + "\"Output" ] }, "metadata": {}, @@ -778,7 +845,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -792,7 +859,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.14" + "version": "3" } }, "nbformat": 4, diff --git a/public/docs/images/tutorials/algorithmiq-tem/extracted-outputs/24894c44-e399-4b9d-a3ff-38a28ff32ece-0.avif b/public/docs/images/tutorials/algorithmiq-tem/extracted-outputs/24894c44-e399-4b9d-a3ff-38a28ff32ece-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..42149d06d157575beda18c3a67dadf6e77571f77 GIT binary patch literal 2476 zcmYLKdpr~B8=oOfb4d$xBuYZL<}$a)oO6s43dh~B&CF~V<}z`J<<4@8h}=#oa)~In za@la0`{qt`l$=6IZfErC^LzeypYQkkJm1gzJnug*0059glR}8dAS@cdiGz&CqSf$N zB!_bm@hB4VK<9*vm#2^a4+sDdu^yzK_-7U*VoCTz!o@i?us#Hj17>0b00Isa0N33g z835p0=4hM%QGO}_6%K`AvA&0699B$ee~#2PWoTJ%&JSP!CZKu7=yg%8l>^k99kNdFLBqz}>S@V!o9iTFdnv2wQO zjskK6fIKlk-dK(xf%QlISd()d$Lw?XK%6CyO5;6|BoP2Vzc~7=&jJsRhJ>*CxX{%| zU@b){SH@d5^o}~7M#%A?w2%vvF2t`-tbVxvdyn0vWZ|CklDW|`%jUi4cN=pBn$D%? zvT-AECeChF2@>-Lp#B~IYvV68DCti;d21lty|uPVR^lZ?uwU8j`SbjGMG%a;ygaFBp_9eVb`D-OA$+ld?K4N6g6x8ieDJ%e{j$iS;$Vm_RoIfEB7~RdKktS-EZ8uzsmzeu@AP^ zxA}dFZ|@b4NX2>S4OU`C{NHxmM=U8kfqUcjcj|#Ao1rz3Xw_DUR6>|Rps1aAa?S(c zCd+}uuv??e+@xz6Q2&K~Cu{LGI(+nUINgO!dzltL`@7nxn>p%&p`T-ok+f3*t!;ce zM`(55X?DIzf7|%Hr#h9y#AUwy^jn|Ut{t`r-09G03cU9b-IvQQRT`e3mb=EkRjU;v z=pJ+R*+2nfE3*7gS2Q?z{faS^5sZHMN>QzH?VCu*R!&Xa7tsdPSrNu}n{BB87iWH`cc4p3=^f!oGX0Zn$o?j`Sz48PLF<`fs|>Xn@+xM%YtFOn-D$N-A3dK8MO zv6N*$o)mI@!u7T>#_5FldwG+U;_Fc>x4MzhJ3|-uwD6I6r*TkK3j6 z8$i}fPPPd?*3;Qfc|94s(F6{fIgv24cHF71w!3_Kd1UjEAxK&v!s@&2$<64B0_tU> zN!H2tpC#49?z?5Dw^nAjsm#zudZv#G{4GipS-xNXP!uI6Fzpf`)>|Z(bagiCwHBzh zhIu0LQv5x49)#oq!8#;cn#{XjY5!h<4gC(E`4CmnrM=9Y#(Q7>bJxVP(y64c(7R4$ z5F@X0??Q5N|tU7pRKrPupRr$BXg(iK#-91Z_#{PNU4F zX1)v%L|HMYlB&!nhp?)J@1|#d=(-%${Tu5H^UhbYSxwJChHbH5;lJ{HQv*~qpt4L* zVLLcyGOl|uKTm|ks;fOq=CjfF-S|GXaH`CvsW|RZdzzJd7g0cUoHPRo+W%;*;r~KZ zkOm9dfHKm{U=He{i7rn0^yjHDGs5Vw^0l3w^qq|rc;(lZ<%w6!V5_mn5vBH6F9DV& z?i^6&S9XeN5HRYB$+OyHn-+@s-2npujcdoMQ|~JHO2(TJRM2Khe&Ji+`rO9(jw?J3 zhh4uGaAQn)w5rgdq~UWS*`XO#|I9|UYD%nA@kEw`=7ePDm4aEJ7`g0>Qs%JZTN+`K)qapSsLu`~mjz{n17ye!p#DO2d% z**aU=?h)2Nud-M@foN`Fk8_*;L+*4D3LX1nWOjTh>SBB*X?7|-WwI?xQC-4C!>iQb z&1T_rO4w_XT?;~3)2k};v|7_U^Yo;IjIMBB$r#ycNIH81NflGV5z-vK-O#`=2X8YL z7IX4&72!mnBWazh!S}VhS(uFMV1$*=J0--nLRpV6Ol#xb`U7OX`J#djvWh^)82cgg z_dnkdoWo$iU1F8s&-rz6GK&-WP(YqEy8~(Txy9*S!6;9NkiL=)Feh<9DY{}S_0eY8 zw`6Lo{)I?i!+-1P7O8FOjzIYFe)zYG1UpAY$z6)0IY^=bia}`)blov?ix|GW24?eW z1n=n#Sd8|?r)8*aB8OXf{S0cO2!ps;JHUFAC?V)0*W4zqA=xAbMJFX*kG_j23_ewq zu;NBT)Ely+A+3G&c6xlew2=%c35~Vjrs7LIajd7Y58bMp#x-A;GwOAoMpeiu%;W9_ zm!3`@O`Gf5J)J{Qg71hQnUBGuB<|Jri#38GWq?ol-pFRdB-y&c$Y-o zIzu0K|MCr+EH;3MOfs;S*bE=eEUm-9Lrbzf>_&X$6W7}jHZm4yT`|Sy36@E7d$qP`eO{@K?5f>JJHU8JHs)U?4c z8i)X;6;&s&Uiw?o{6HCMZA;*g@>5o>r53HNAFcb3J<*%FKdWlA2G1KCr?wUDB~e6f zTDtP6juyYO%aIr4TdiQ&gxisCR@pFHw}Z_l%(XA-U3;qwV>%}vDNjv9AI&`<0&rCGtd|) zKFAZ_)j0E)kL`+NL5r{8k(LxOF`0~WV{%fJ(FiK2`>WNc?5}J0%=F<{W%|S)CvRIO z=Q?yCw`+D_*$f?WU4*F^nvy%NEsi-hY%9(A==lymdj3fDGaMps^jv&MH+(&>6~uy8 W9r?KWFl?&BXu~>j##7sLPH|Af%O#K!4=E&zaorLoKZ`Tu9(94uXI z{~G}Q(=3)Y_QwB-L<9hU0RDpj0H*xU0sy#1{=@!>JMRA>0Brw44ogeB|31clv#9?9 z)Bl$JV;j0LF#d<}|AYTB{|DAtIygD}OGa5b7~B7|Fotf7!hwJ={~@4QIy;#D#{mEU z9{Q)w{#^(TmL8V>MIay`{@MSp9_K&Mzb^il1N={h!_d`3_&>0#lO30>gQ@v{l@OP) zrLhB-v!}C*sjV~DzZy#$OG775E<+m!i~pV%uBC(Rf1Q8Sf87HI0s#X6frJ2ohW!Ju zES*gM*XF<5{Uh7__kjL2={jm_V(5Yd00o6%`o-r40b#*H!1Q_nhy(x>MNufQO|68L z*`HX1aN4$v;t=bVpBW+XvQvPmoaEp6Cc3gAdg+K2$N!6ybKqfO8{40($;|1Jz(jr41m%83p+&TbwOQhJlB1^%w zFJ3HK&bD8_YYy-}XWab&L3&lELEi)!vjU^iq6w5LicJ{?O((K4&Zx`N&YXG4S*j7S zm6QtY-Rg+~258iEY=WljjQvmSiE%$T3-`Tg6V~!Ru$syTrW}xw4-w-&F{cnF6#8e(at@HN})GT6PrmS3XjGwUyA!!zD+CJ38 zP0bPQa>0{-p28x9C^tkifv=UAd{fglxR7*$X9Ms0`Pxs`F%XE9%W9>mn7#teW}7NA z=%ld32re7oFcS&oU!%QtB?CjwkP9E4pbnd)03!xbv6-be%F^H8#iHy|k4_)nyN=A~ z)L4Rzzf0G{^OSD2KlxHWFnT5LL8_~GJmtEr^wrA zJA3HA^VE}N%WZ2bz_~J8E7Orc3KLN(2f!Z1w(qjZtEVKurYvsAwRB32r&x+A3jfOq*F(PsAfzMDEGZBBS{>ii%c))6F(%u_xX^?iczX{ ztFLSDWUlUtkgq-Svvm0(mB8M#xF{Sba*g~tOpciggaX_-V<)z~1&jP(PKNQM=#P?o z^tG$Iw?);)zDnGWu3OA3s(<^j1VfE&6wdT@4Xhqh3CG)Sat*d>-_z?Mdz5rgUtlwm0ki!(mmUFqNlh3Gs+gNkGV*ehWs&+p}R^hgPl88ht)$-F6XOPx)t^ylFbmJ@EHGlh%oRJtX<%_FnUvD>(% zVxfX0ilVCzqN1&buTlG>iY3BmoKcxnsB17RuFnZ$(uV*GS)(Y9?33~Vf+h-!GJ9B% z<`)C2^`)UM4C{Z6nc_02TL{Vjt$G$6-#V3J`{j70DI_jQwTe5NV%1#vs7!Cfs8 z^}K6W-D&R?4 z9`J3V8-TF@tYSMtKFQmnLWptT45BalE)xH@x8Z1M61Hf2^re6>z`2oaSy6(wdOrlx$}{YWqG5 z)0lnyN?CRh{ve8!x?_9--?om`I*Ge>e9SBli+lZ~f_uJC-*9+B!BkWW6L+)Ht)(?2 zO0fY1xRHE06j!ODg-w~mq`$Q5H0Lc5y^}-U#Arn>&?iMA@jTcl(uEW2>^~d4k z>YmF$?7hvoy?M>5o+}F_z8((To2ILIE@##iiep(yu)|gP?o%sFEV7TWA~SkSU4j^B zq1;lbDX2?gg$2XfFgofD3dv93>ydEUg-%~6+S%2>Zm-VPp7ZC{c3V+g-FqDEBmU1w zxGupLm)*zR&tl=Eln^DpYCSTdS4)+}&sF8$AIS{6aNKoMF2X8nre`Dy-2G8JJvl$E zNLJp#dop#I)}PlPLdboTeBus9bo7wk?vUBNs+?PX3B$GUfMI^CX$!sFTH6AB2y}b@2_F+*_hsJH zb%%Rdinf?ckF3@pfn%xbRvA^+OOA?jXarvZMXIYx_(bkDL3b{Z>WxfmOH7;cV9VP^ zUds}vH}I{j^=Bij>n7#WN-hy(O$TAs#x;3=M9|c)?{3rsZBAuAd63r;mmEg<_nDNM z^)|xM2K{cUOedG+rDM6@P<>=@6&@4b0r$-z2DAudMURMHzSDODd(eAiug>oFPT392 zxk0mge^nHL&~9&N$487}&4A%yCG)&wR%y5H{L_d5lX9qi+xvhq{y125cm4q&zBubY zsDRm4@TacjTJXu_KFp?Y(G=hhcASjNj51%0O!DpU^D)^a+=U_R_NI|SQb@C-!7mTj z(Jsy%Xo(l3PYCFxmpt&y+C1B~tZdVmvKK7w0`Oc!o{~$j(DlMuEc69UiAj} zooUvI6Bd1hq$Uz2TaP7U?DY2p20Z~iK^|W)Ti=O{6TfCgsaaZon*+P+viPqQ?70=~ zn@U;1iN~lNFZzi$PP<)Y(UJuuR?{_6^Ss28fxp0`pV`sMAjisb9VJq zQbp>f8F{)By$ZMXnnJmZaa&R=CFo^sOt>&TJ|b`S{JmVaowP_*^aQD&g|gL&&Pmp9 za)>!4fF8omTn_qW!0=~)&@#boTfoH*R!H9Jyhd^z*RYW@ZJ|9#Rf=7&!x$&ha+Onx zPnL_YN%u?i{P@Jhj--Op$8Py<)!Unjn!$Q9SyZl3@*{)yPu63C%E|D9=aC(#pql&V z+So@TV1YkaSk@eEGzH zn`DfwKRu7U-I=wFVvYU`Y9j^~gzMLa7B42I)&XrI%P=%lQ*Oi&1{Uhduf6jam%(u= z8%7#03vF;P{?y__!k!#}Or!*qiKJ+0;#(hsrNj)M6%JOdAo)Is{?6v_U{lI5*>7RP zSSW|)$iugmGGsaxOd@Tx8v&Acua$zQssQGH$kKv-vBBSJfa0q0_5dv$`Rkv7*6L@|XtGt|yZIha zFTZ$HbEF`FRHML=r7A{VX3(HRb+4)x<_h%QMpxohfa?I8C`|GMFj5>dcvJgRr#~d?!aT19=NyHWkW9t%bKJ`8c!=j6 z07FXc<}Qaw(Nd&*fW;~4ymyAq6yT0MDS=_VvHh_~5*e5za|adR;wC`|z12n)z8`&1 znlxx^TUdpoe&iwW7EVv$mnGplSVPjKd^^DEZ&Umq=Lz4^X`R&~+<__#*a#v0=YwGJ zAsC*v%}9E+RC$^(tS0mAaHegeOt7Fi55St3238j7V@8ytGih;oIdDx!+a_=tbKpiHPX@Yk?H zivq=L<=H6Xk)?EGBi?Gy>Ib$F$6v*#I&Io7CZc1jCK_%c4B)QXpBX+C+VXe}$AYt5 z7FTk`fkUrW^RD^p##r8&$W$wRu3PHMk>K)hN=vT}A3Y}U%u3d8mritJ!J zKRw<&5RFOr=qS0NJWc5&ZC4ZLZ`Z?M_8B9y!Z!bKOY767iG)w2ud-g&^GRAnv2qN2 zv?aN{4KKU)RN@$q{&J(|k-C-N4DVVQ|KUO;z{U`yldSmn>ju7I|0rfi^p^}rcFX_UAbBTHXcPGd-kR(~2*pO_u~bE#o`a@Dtr zEerZXH`C=Almh%nN0!jrc?VrhqaP0h5{pP7l$O4i{CQP=OUd?wKpwY}1VA0974rLC z9V~NrX-GeK_@y6SAJP$7%dBLk>7fn(Al!_qDEf^KjUwgu2?P>!UFeyg`7;$MeoIxIhdlKCL5JE_ zcPp<`fD`d9#n@?ZYeu|)PvGizs-BxEG}EM+trA~6LV^dlw@{>n6$Pbvq}K_(^6v_=%CS<|K^THk9>MFSE*{q3 z6!uy$0I%cgEKdjsOQUB9YR~?wXw%WthsY~@Qox|6+@d#tG#q8EGhi8dq zK!kE$Y7E?Uyz;@*RN#niZXY?-k^nM4P+IHdq{8tbj#l%~xNf9C9yBznYqd*F* zL4gcDEIW@<&u9Z>3OD$3sd$I^n|hUd`o&%vz#O+AI96$ytTc)Fn~lq!6jPM-oJiUZ z6%UJP=ID5Ho6-}zycy(NlBE|m&{i*$Slk0j#0I71=RSc^uQn0r_jc7+jCxSjr5-!4 zeKr=j?}*O)auIOg=)c*HW!YTsdEnI=(y~JKLT11^S-(VC;Y}HkZJip^Og481{R=#b5h2KKm}PT;&a@e3OG_Tt|XXzMNcZqSx7J=ybtaw z-#|Bc2`5iS)yrom3}p%sGAnI0zHhC}6sqWP<^IAqBjdHUIX1hZ=r9+`B)l=__^qE; z>1MXdg2jF?BNHhIH!j%zj{Dx0{F~B7dQA3()a$(E8_cl>^if zhV_ygOvF+J9}9;Sorz3Q36IWbNcTO;mWBTK5aL2a(@-Q_&04Ja50=eWW9;7T(EzzW zofh!iawzdN^@Rtq**>y~Qr6lZa*NOCpLh{x!+kj3Vf~bo$ zoN&;^gLY!0L^iVPYPmRur7d*DbO{+7;k?;1rgyMhi-eGNqe*i3MU{Dko;q9KmGvDZ zN)X5BL*-qwSM3nsp4`cU;lAV?+5#P3eivO7!mYj%!_x4MtaBNj8qW4OvcA%^9m+1u zUTi`u0M(-HO%iy>=}v_D!`g<2*1GyA3yhC=@+LD;N+zepDHDvNog3l${$ZTpw>m_p zFJLIVFuUGyoFM%UNoc0llnjlc6Xq=%Zex3v<{C{=QIq?MupF_>?X0XC&$Y7Op19Hs zj$qMwabbA2pCb2fuBbM+5%W33M#Z%G)~X1 zn5+^sv9 z4V}_yh+l_(pW!!mGWoVncx9lp~vMbqHOa?i#? z0y49JtD%&qS<&Wz*^(yvkq?6)SAg`ws5c-`>mCuU0zgLVE37J1HyH7M5hilZRV0ga?E(56E8UoHc@>Bkpx$r0%^_DZ;{c&GU_O3yor;0O zh0~$i!4c{WafL-;Psn(<6&(<0C7US?g-al*@7-^18dCoX|HfQUB!v4p`o zWFd(biG$#T)6;bN1>H_5ZilUO+Ue8)Kb}1o?;AJm_cSfj=1+wFq>>)*c52+y=o z%omQM%cgEXLJW!dl4_PzS5JME^~7K-2AN&P%_U_a~l5;!2c zov01oYdjMe>=3j=iG;sG28V*0UnriQJ`90_paNJWt~~l@z{L)|-x}W7v`S}?K>8#X zR5?kDXIZ>DmVi`!kW_wqv~y%NPI2sgUm(3&H<^-kHoF(5NULv%YQ*s3K~cb7DA}6> z9g;4luHS;aTso$g=tDaUA-4(24>3#~!j@|${$YKv81_0?1iXmh1nO%A&YE6t#vdXo(&)jM=^ylGQ8w)Q*b<6p*H@rBORAc?1-Mh2|m-4y_ z25id_N1TaU)GN5KRiexJknv_sw?-1wwk`VeVhi8-DEMvA#lWJZ73G_%GcD zNztxMJIilRB{9zHSn#Gh>)bjGg`SBP_>~f()dW(<+-fv=8(2ECEw`JT{OTg(eptrr zk#PWo;&|t@#+61K9X25q!C00)S~Yy@SvB7Xv*&F}Woj(Nm1{V-i-cqIm8z0lq5i!Y zBAmM^EMIM8HrC3WnUnTo^+P7Fw^$HZM2DE0HT<_2KI zHt)af^*Px1!$EI6{t1rZrv~e26&1div8*b?tbqjhR>Ph!U7pow1WeuLZ&5amV@lY{ z(?S)x?$>4x7_Qcgz4}|dDCtuaq->owYzvJ%oKKVWq0Hu^JzRvA0}r#~yU7LN*?-5- zR<6>Cw4&e}=|m-;!&-{qo7HE@WqrC-)FEGPPFHv}%Ty3rDzpoj`cVS|%>fHI{Cnzs zm0ka)&uz4l`XTm*N_^c};hSvt(RnWB>D+FAX8JomDb9q+jvd`JS%D_0sKH7*MAZR@6X7hu3Kgz8zuGi+AsVTA0AmUNqEC6L_zVK;SUXUi$C)L8lmXga2QIIaH?742M<3|vg=+5pXRN<>vt{*daqhH;MqLhA z`7Imi25F6M)M8g?b<0Kgbg9#n0>)cc2<`n8*@fNN*nAkhwv!Ot{RgVO zaa@*-U;!XTfcj7ceY|LCh6a&bCK{B>v|y!w<$)r02xMOILgKPgf8XCGDpZZcbjjxIpB)X*Ko{VrglZqm#xm-xx% z9@r(M09#y$IAl}wwz+aE6*XO7+tSqo!!Uvf0sR#_-Z$KW^wxO2eUJ9j}n%?mJIt7u}0h0I9sl(Gi2$68w>=>8j(Dsw%!*+nwekJYUvf2}9 zr{#bdH_JH+gP{4YYow%;K>UhnWs<%rZGlE_hT`{q4Q^%*Rw{Ke=3`b#MnqU}Br{tr z=;wOphjPPM23l3soRxb;<0>H8p5cKEtuZ-wdw9tp1ty3HKmt%468_@qG*@EOBR6S= z#u=CD>l?c`%?HJ=Xe(dbl=ta%cR0WnHTKj=eDL>qB8(S_uDz9 z2tHjVX}Al|)y(GsP=5uuYo&zB7OOEyO{x;sndbPUGYA8-M%@p z2U7TKM^&E-M z0m97ZaI5#sljK5~w?XrThq=ljxy@k(M7VD<``HNxXKd*71bA924|ctdet^X#;lcsq zm_g{auQ%MRTr`d!VMZ6;7(`9^Sw;sKG~wXh=|&2xJ#kT(CpfpqqIW8`5O=eeAc4ia zv#Iik?CrYNviT~fA9h)ARA6vlhocU^hv%m*Eset=JSp6CE5!D1BR3>Uo&?{eO1cSB zLW5_6fJ|rX(%o06%d7JUdG)^KDaeQghXM;Ud>{s5{T1<8 zIK0CU2L3h=SoLOneo&_4(2D++9Z6==kTXvo_uyn>n<2&IkoVz{F9D;|5$}4cYH=}r z5Gq+wUlik9>`>I1t=q#>rha5gXRNWOu!Td(+pM9v7!;4?Ey*%h#JmT=_8sFcPv=u) zA*cBxh+JZl$l#$`^QEN1IIuuneqsWE%=<)HdsHBrS`+Cpsdvm;!Ki_DpK_S?Hz|Cd z3EHxOsfGKmPsw&0m{c+Pgu3NRXd;U(M1z42Sml&>;4v=@Y&Bk{YM2wln5?xixJjWs zd|nT+Xe@0!bg=DHwOT62?JKu1E&2=<=k%FgL!54^nc(YUdlJJTk&XI5+=yqUHC@@C zTGIn_$hpMN3)W4I~PkrByoRFHoJ8wf@#TDXJvWP_?rnRoL=0v1 zXbffu1XgcHeI~*G1RYYOC%>sg21o~ zgrGh978cP;o-5`lZ5t+K>1>IK{z$ zeiUbRP-9Y7Kx&sBXfXM7Hk6)YKg7bN9yXp^u}M;Os8@@9!E`VI&Dl9E;5?ucPF*tg zG`JQ36$|#E7s&SRh2T=7p*ceaKE7WW*C@Z5suVeTDzMp48rNY5;cX{XUrHNH6mO)R zgRSTD)gp6m{f3uPOs5gYvi=e!@xbla2L><8Uv(=>?a2 zh8=~q@?##D66c(6;Xpq#G^1Go;*%cpsNnx#UCJPQF-vV=#&=lh!8?4y8Uy8-N%Nfe zX(I3|QDZhzuIos7i`7a@oW&jj>A}Xv?2I30xEjy2D!B4PL8;n-l8U#j`ptt&&6120 zhLfFpo|zi{+r_SLjGz%p=;%XQ|T~*F(m2(a4yTn`fz?MC#4cU zt;*wcTmD({tn+4OqtCorWkJ2-y5h*)*W<(f=9fIjw29IxziRf*| z9&TgjTfmp8xKM9yk2o9?J2ll5q020|-l@PS6|{x-w-lwzt8L3rtvz!Z`vmnONPOHK zP_k(*R8K6(mqvTW6^A%~&J=RnRsB8f2VR5}1vP7x7PjaSO)~^AegG#UPm)D7^zV%;C z>dOE_cdb}wEzChlp30>;ZH~JU)M-Q|i9DA!CR+ONZFT&BQ6gL(2W5O( zuSVMy8&B|iAr+`id;4?lgxec8NrVV}-cG1nbYt(itDKm(&0oK~LO0qyWzqLRWtw2^zA60Q`v^C~mSDAHGoWB&aa!zns2t_-?9ybR zCpqaoBSgeY;ozkrb8P)JGtU~Y_5`tw0R;>%ouvuF&n9mmQ}7DN=B*}37$aK;n|GOK z9sZARw)j|o!8AxA4UDJ@qc~%WNX?pu%LFHP96Q{bHV#^3OZ*MAEi|P?4mnYCk78~r zU^oaaT-i_F_nVGLz^HCOHpW|d+Qk)QH?1PJ1K<^aXCe%>dMMajGudcN^|6exKC%Mv zrFR0(?iV6q4k?NH_6n%8qNSN1eW|U_rqp^3ZY-XorF?cP5e`?(QqeuZT21-aInp2$mo+enSoB-gMoF zo1fHPxnZ0e8FSCBGUNGCF>zw33LpL`ZoH`AUDt_ThKLv+G>~T9!Ys*PY+V$ef~0_W z$zaT{eI&6Gz!Kog6lkS&aVspch^R?#-U!2j+f){cI(Ei9@PT&e#_SA*Qio5hNqG6G zpik`9Kbnudf*yKK&t5e;!??xU5SF~@G043E6thk*WG{YCi*%98<;~%3?jMZ4HF>Fr zikYK^o&nZ4SWm;-$bCXcBW|eiT35@+-vp$|)U4~}TO;cTXah`$*NU3t5JgGcAmr2O zpxgkFK9>H~U(SXujKAIASDbogU?iN>x{3tA{pwP_{ z=Sllqu26`Q@YmGE#M zdQ0uC2ud5DA1SNr2YO=LdWX>GZo*%&ieea!aec8|e(%ksm{OK#R^+v=@FFi9l{r6x zTi!kUm8;nRDjwmB*%un;-fuPfYy78Lcx{YTc_)t=LWQ%sf8g5VwbWXD8}__;)Nx&N zOPc)SGSv5G+X?cf24DKo8#wW<3V+%}*T7}aYQu}t`9l0D8{roy+*`#`4?qNM`ey#7 zl7~S+z5kI8Y&I{Yk``uibPVzv?eN=*pO-9O9n-L#ZW@V9&2Cvh!QDl(ZLHqUl28=) z*_AQciY+m%OPt=*6j~JY7lHlDOx4l{8BR?1v4G=)UOC_W%@~MX#q$Ey6zcIRr+D2F z8}N)DGfyTW^6wj#?f_5qxZcGrgUKvOZ?I?mxIW_cc-Hfw7_8*y=LI$e{kJqt!wX7j zO=~TjXKLCkb~j&&femp!thZ_CJsnx2^mWLp=LoZB7CmJ4i^buOK}q6P+M>krKtn{X z2nYD7^&^!di>y{LxH3dyj-47B&e1o^-{hw}FZi^_8dsaQkbXJU>6BKQcDl?zXux#{ zd*W!B^70#3i~O&c>VNEgV0*7L+eK#@kpXpoUlcAa5c-C9($V8Lq> z%*d_^#9I)(^WT8|0J5Pmj!{Zjrr+W4Dg*`KE+n*y2@&>5%MkW5YSVo;F@L`AOzFsh z5P~a*IT6S_J3?64WQV9meL8-XLbS*=_=A-UUk#{b6V-)V^^^Pcj06NKXX2mNsiZY7 z7D#$Gm9S1PDV*unfs2%nfYp}3)RGzS5WTrX_yLDuI&jLlfaQ~&Y1v8q@`hwB@aqO! zP4X47TCsbhQfzb?qhxBS(MCvXH?n2zk~&=(%o9cETZm`^K8w20Nq?3)NZXg?UZPTc zTsMN6MRR<;QzvVBt8mWQ?T#Ebjjpbj<`i+_|dMs72fR<@LR?D##oj46=c$XrbHDm9v_Tx z`<ob-bvKG0XF_4VK4=BL;1;hf+bB&JV@p2P~U*RzKDX zbp~CG2tGAcAs=$kQA#V0``06L=Eo72ihvBS)0FE=K8#tk?#Vu2suroFYJwK^V4!m_ zu63sT&Md0hlUipTbP>HR#u{vw^r118+T}it&k?g*$&}z1A8&$__!!A7a6YSdM5hT) zCt^24#r_+`u6fYIw>YVH=pU`LN(>U0ZZH{HoO3;FDbvB#VJD&}#GnSg&8B-7TXUaa z1Wihp;@#!MHZ<2&r;EyhaIx9_Eo{ovO$RP!hRsx-8-E<(wCi95Z0#j86N0>d6Ay=L zA{TaAIVLbpnf-d6G3}hZ2MUmG(36M0=NCDyKy~p9%P79(PRx+gFfebBgZicK`i!sy zg1D3&XiHXceZd(Ujm5%BLVo!DfJo|Nb_<~rD~BGMT~ZF~_y)`qYAICLIZ4C(C-mN@@CF2G`_D9YHs_vh^VRFuDiD6*E{l2ux+sf5(U1E z*emsoc7XjDYT%2Nb<2#O9GV9asYwjqot65E6Roz#25vr=qHSfx`I`Gb;CQ8E$uDDKMF!1n&_j{$#1{8yBw~srA z5RzQf&BeZAKgaW-Mw#xP12z;n&u}uO9FO$OXAS#;NJ5*)H&DEJ%63j2bE;vQ?ww_i zIx&$SrE*RG7EtFXc+XRe?FC2FER&mG_`TEHH&)MkOYhaU8S>aW5OQXCx>e0><;^ds zmb?g@9DU}7FbB()n9=?K{+4+HOwS~3t5yVKh{$s{w{1-Ij5R=|oB5-}NyPca(*JwQ z5&qGfmMQLJGz?47x7}jHLHUmFh2qF#Gl_ECDN;^X-aXCW7_(zHtvc0|RK~uj&R^|O z?f&joRznYsv>PwbqWb!Pfbw?{xrG-aN3al4SI1gAeq^m(QqEgicL0(t<-H{H4HR-> z(6k+MU{qoI#}D7}vwIBgbgp6Z<|QYpn?jE973mpsMxhj{>q^-{5=e!a2kUJGcp z)ti&jWb^z_Xd#>{w-V8=O>kZ87_d%#|HV4osF!#Wp7H4xya1cX z?$C*_{^6V?QUL(e@VyZ*aCEo#Bjg#nBnGczU1oBJv~C!y3wiO5_U1MG?u4xI>SgpAvmT zvE+%%}N#&~hw&gEkt!?@_@D(sp&&^<*VM4zlVeZ>nP>;)$ zxai?|86H`kw)?#gOMY`F0h6X1cx3S!nCpxX_{9V7mspb{ix(t<+%G0Ctr)plVSnuu zzfP!7U@`An7dYb6Ggs6J++yAG`eV`DPUF=^e@w5~Ox+E7O;vq!greZ?&)TXWr7&dfUVl-zhzG> z$BYzBf0{BJC|#hXxdP>=B2J|+R@*Pt!=CL|x1PR8r@6y0t`2(1sHu_-YG#28dT zO4v%)^(jNrIGp3M{qhwf%HRlW@el7Nv@+izyoxB#9mleKTyYs>I>>m;0FvO+ijRc3 zmBuMKK>z+GE9fCq%40#Qt3)8xxEXyYC2|O{Ux$i);yXT-8{#)yOThGXHa3) zl3qzdHegt2`t?4RlBNkCvc=e4*XzM6Y2O0M@)z|$j^Kz5+5iMh!KR(X8#OPIt8sp^ z%fvWr5;**eCf}XpsDtn3OnyScx+LYpA~$Qx;`c?Q^N9aUd(*ip2l5HZ{HJ|oT%vi!J&SOe zHft8O>wwNn?s4{~kUR{5aXKwI3uJ~^fd31IMiB>`B0i+@MR%yr>VAPO*YwAa0)%>m z27PU85-KxcENl7fhJ7&S0tXB72MngnB7xGM$RQe0b0L9t6D@KI&J@(OuMj9B+F%!Q zqKD}sV~;}xAy8YxoHJ;Y0?goiGlD(+tL$&yXvp`%68^sc=)iTvIa3HFt~~~}Y09gH zR(-sk2JCh7`>3F;KOWslaT(nJGshYfiDa&;*RUC0nT@ZtT2{9b;&G;UzOQ+Vh-?gG zDhf)R^d*gb*1Ue~Mh7i^Rq2%QzZ~WlR=kJyBn%!0mF|xR?tjO-n|u@c?_Aq}Yr@|9 z73!@Zg)!`&je87Gxa}Y1^a17C;%jah(0)Tr9?A2wibDs8A%KBo8(`!3bkU=pXn0fm z9C$w`?l`b|-e%x$Z`u2>QBkuE0v34%(lytd8Q&?#XixQBA)D?3yKRFlYOtpM7+%e zc6+LgQ?^`ly3Tu>%s>mNjuBJX>uT9LD;wvf=fHS3;WWDCMRUmXA4t*#>OK90j~bDM z{?WtDeBC#0tzqLZ$f}NbZhauj6&qJ~S_>seb%kg)1qXk>Yxr=y_4o|&Ib)s!cEtVy z;k)l_Ert=SsD+D4)Xovq^D7QP_P2_}r5^BVKX-c+wyieCqUS=dc5^Ch@)Hx)h>Dfr zDiKAh+Vo-N5bf(CD{8$48@H>SEJ0_~|9v{i4Fpub#<#BrksA?gbhYKL(o|6vIPq_N zHXf9~ivtKW{B@os9W81rl?BR$43abRh4u#i>xQTr1?L~@#GS5uiH~R(u7#eafc9Q$ z>(BZi$5ke6&X3EYt|oFT(@N));ei79s=)yc?PN?BG(FqI_gFosJg*MUy5UIk_USX% zt8-L)%h;{JE9kFz$!0*c2!&LP+wKzuK_A5)`H>~(8_B37j&vY1;!qzUd2DuUP#PGhSjxo{9DU_;+@u?!FN((Wim&Za{Hmaj^#^Q_C9LA-2EHiuBsx!sp zxl0qCkc@*Y>x_1wrfP+odyVa=a4sDf1DwD7tLjGd4tTs>+`VCACYDotiGjnedZZVJ z`{8O~eU{H@hf<)p7rUlN@^OH3b+n?)$+2W+@pXVX;75Gjgen<&LS?o?LX%}8sLOyZNNMPL|Wj&^C`5J^Cs0jOACQ(3T zP%2(Ezgbo;!+pzyYokD-skHX_3?lPx6T8u}@3yrSBw>W^c=|`Nizbz>gJ;#5V_g@) zSa18yeW4Yp$+$_#^eaNg>a+3QbL~t&=gakK-&NE{Ipdr6?>gy9T4Zhcu}dJ6LgBlJ zI-F0?@R2yi2Uo*+8P8}LEazkW#q_xPIF1ftUd-YO;C%Lv^TM$@TG?$o2+UOppJ5US z{b@99Jc!Z6vagLjOXvPt{7(;$e53jWYx+u*_eeXvU_LZ*N>q8hVHiI6PUdLn!sm3D zGSp;2*>`$Bnwa zcb1=9IS4M19UuD2cs$dZiwE%)iO*oY)e0QW_d_Y1uG84BZut>e4vqDouX6!W?HzLC zr<@ETllnfDOvn~V;;6J2kglwBO9y7%x71QMaT#n^ntO2WjTpJaU!y@ZPqvB3S|F?3 z3`g;Vu(kul0|4S~r(S36A}+3%@ZFXDJZ>!#O?p7=F!%nh*TOFzg)8oo`rUQ@k>l$w zu5G$ZtsiFXxVs?hSl3_5Cb6PF>g@cT@Ns0@mLz-IKLtfFLc|m-O!Llxcx>Up^AJJh zNA=F)AK@==_<47p3j~?W3nGrVCCTJ*Rj%&4^whQYfH_JO z8&XdTjXlz&)~&vh&;W#x*sm~tEiK^Y@}#&waLdY9m;L+MW{E3>i?91T+^qL>rj~UB zT1&I7c4oZ5DdAGZ-t||;+p?%o#8W%zVltr}0`wW{CV0W(B+@^^zf(}u1Q`(*ec1(+ zyGME$#L~~9rCeC*F)5acV!sWVbr&ImN4e5_W@Lgvpxxz3ziYvfMd0_SIKBWGAw8bE zEsT`tgATyS<9Tg}*bx)Ht?q49n=7&{h(n>6oHql48E6Q_3){-Qy4ZcR2dMDHU;C<_~VY{O!h$ zb!CT$&OZD`CBJXmUBu0t!q6;%YLpLS}#9Sc-2&ky^v)(x<;w{r^ej+ z!IoV6M^!m`|K`nhafcw!X1~bxb4c1m8dTjA-gH61iM%0g96V-yL z6cWYL)fXdg#2%hQc2?ESP>2I?#NDwAdps5?Q6f+%ZT`^7dbxVa@rn zYMCHSAAkzO9R8~7^Wp50Ca2@R zQ-%!SJ|?Ym%$KUaGWGi=s+3J#a0RWx;r4U5#g_7&E6Q0xygiOOIDcwg)|vbOgq^zS zKVJ!BnmJk12}!5>(NX@s`S+#IFgjS|{>=6V?gTBGltf6+hoo$C%+%!aYge<27&8fs zK9XfYY~l>2Y@+OJ5baOA@Wxk8B9s!wrObVGDLE?EUd^yx{=Wc`Hg3sD;{Z}J-Sff1 zf#4*c#IbU^{*AoauE83mHN}6OMDhx=;c&3II15sBG%5w*B@D1<~*fmfu`;(c2`TAblkULY~N`hSy<~O}mU!@&Zw77-m^yAzuTo&HX)*Vu>UM9RMl9oIm zzG3_Vq<~5m=TlMoW-m_&H}y6p`VeO;*Fq#Xv4E>h{|$AM%YK^Ldb|cz z7YLwkAM*BIc1UxqNnV$_3;IL=auT4iCBq!)(dE|4u`kR2KN?RK7Z@_F>p;6==P$Q% zL&*1f%mvhnjse@hsV3`sbGih3DavBA9u~LTiB;s*pNesT$M&a5X)VUc1k>)>)g30L z3K0l@!CLHw0!RrydIeW+PtctaC}N7~FLgkIy5-VO)a=|4-5<~u3pHVcfFOpYy!Lo_ z@?`bB76!lW=?Yh$DoLRWnoVV_kb4}?#rf-WN%$117f?*35j9z)BdytKTzg6VN1EbX z_xAEHjgGJ@V(12p&ys9#;y$%wl)!wM;{|)sw}=_mpW<~7g(+#~-o9%W$SyvyxDCAG z$b#6=eXW6*B44w)a1ply!Xt;ez>7rOmT)B)zs#C@O=m7~Q?@~fsTCNF7x79m9Ruj8 zU8`z$9pg7a8@&uwS=taY?Wz`g7*A(IkNM`;6rhl6dqQJLu`e?e6ImNHW3s4aNK zjl2CCgMCOLWJZLH8u%0kjB`Dj4#Udh?U&BjGD{Qo{$2SO1wba|@J7rzn0kUkiKU z47X?1jf0igEHnh%y!eV2_^Ss1tP}H}t$%q14na?YEeL=(zH1u4FN#-m&(A;s%r1qW zfioL3V|N9i3A6A&B048k)qrYwMa)EA=#zXYMz_`#+xsrizzVGGJ|=CDa;St!eOK3~Hy=#JY^=XxUJ@MK0*=qfKgn3bG7 zA;WZ+J-uxBO8M+*V@PHJw8HV}d5KYw=iYJ--H%|)H&Khk@ zr7fb5*S(F|3vK6P4iWyjOe6P6Tv#4*PJ^}fpH^ui{q#^#!=Z>kI@?^@X*n=1KnK>} zMhBWGmjF{wCLjfzfj{Ruz@_CC3P}h{O5AQ{UpT#lM)_>s>BIL3?jc8A-+S95v@dc- zD5Ahj@vD5+sb9!w8Bwc~^J7=@M$hi|F}_yV1Yn1n;Dy|@avoXsYZLJHH5>e)JjMRt z#qRd=li})v3vLd^N#)3LGB;NOx0+T+MEq}&`uTLWVItU7_BY@(Eelf$o%FYE!9a)k z2b#0Tc_H3f=u*+N9Yb`?FnkG0abg)!I{qlqHIisDx&IhH%WKe=tll%hzgs%qN<-O* zrBwF8cgwLio{y&jTs96NQLM*h?DTl9l;)VOrn%Jodr<=_YHDO=!--fTdI z+__8DFnRcD&R9r&>+s83PB^_i8ejtU8m#j#fVn`zYuWp9P!Ch>uL-C4Zo<@h)EjHz$(K_DP4P^Q;%}pTyKxGUgSO>`<8s3@F;i}{`_XU z&AXIwjRx5>2r0IZW~O0&Pi9i0Lv;LRWhHxi&6lGb=Z8#19YSg=W=tu>8M!YM7@Xwj zAR&Nd28uK~-&Nc$HFN?ny$1_UUY6kH=M6g)VuPSG;-hq3s>GrHhG;->RWe1OmYorA z1w~pwl8DZ~WZ(#xpwbSvTsn-DIjAB21}_R>oSgQ0zZ+voY%X59<;t_aWCC2#eiZk9 z9WmWq&hP+S3#Gnw%hIe#Vru^;4oOW)R)9?n4SM;)Lr(`K_q`WO9W9Rg<`c0$sGkjn z2o~*~5_rm-UjuR;n|6U$uV(_W{Hw~x-yqd|4&|FN4rBVEGo_v!t7b43 zAErCjvv#8=pAAQZqP^=m7B#ZUgXRQtxo=e8cjRFKwH%I;rS#9WGufNR*C?r)BIjFw za~apPe?gAG=(6mCnRbW|*TcwQ5TNLe<2w&gY2%()u`i6j+= zwMxNvT_P3CQ*l)dXH~91M!pwGOFfaxSiip*PxgdrNA7O{^0~Lz-i;jBAStlSqiCrw z9Hk=6SSse3VZfDIBJEP;JbN1SMwmnB2jRTi81hW#jG()QRa~13DGCoW)2*P<4kl%N zF*UfUdk}VJwh;ZoTbz!Xo2UcZ)!ePI7YdZR?w?TTZ5(Vz`Ah{{|BP@gRy0I zW5oM(o(F|aALdPk;*tGhbvM@^?RXVMnZKR>#anitP5@0#*{NuNc8Q2JyeJx ze*ls|{?*v~3j^RB8^By6&-Ly1^1*Duv=^i!=VNcxG^o88Y6gY6;s`=N;~yv-}3EbTmD50omg&bvrc4M>~44?HHOWt%sts3FdI;A;ri#mOr5 zFo5NWfzFE|3d(i@brmN8dtI0#$GwvWf~=~Pe88!wXf3mYp?xg_7pMvY={z0pV{{a^ zFMK`_0pUFTD2mu5C$%zwDI{Oy5~M}un_R}=xG-&6>_c~$=fy>?n`mUnfh120x8a_q z`&v}=`9QH(&D{eLSDr3gqz_Z*YqGtK0F8~A2aq{mL(R}suSpVnO8V%C)}gg!0ss{9 ze7UTzZhRtKp4_e)x61#gA%|L2jr}n6r2UXbU@X?wLV!SmLfew*`mgVkwq`X~Vq_nE zklk#Pe$lh=x^q^O`XL+Ns$Gj1K3`BvV>rzR{VlU43T1vuNj)5?z)tE{#}*w+A(e^8 zp(u^*vD-Qx9F3~-I#cErBH(`os#)Mm@6)vr zBd4C#aYLI#)p|yQOQcgc(p~4KNKUi4-3D=_h}@1LMC^kuyoy7YDplYua%?Y$MDkaj z?@ySy-x7e2sl<1K?LNPc$ZbA-9>yv9TC14aln~p=%uElCnLH90>%UYcN#1Jq!!@qr zBOwDa>5wF~)sSfJuNcEY)cin$$q`-e-=yN7QrY~+6W@pPj%gDNae>*ePLbgs_|FI- z=SX|mjL7v^KnOwzKw;p>WztIB+76MIOyHfd?|$;Jmwq?2%1ms9MKQ7rv$P zcO?7T58q}L4RrAh@uEUR1x35|r+>y^#s>SDppUMXK!;sw>c4;xkH#zwigCR+Vof^0 zNsH!LIw*aWrT!qBSypEEHe25g2bDgB#Aot{(QB<=rx9<3c?3DWOf_DE&>hDYy5e^^ z1nnoHd_^}~W6;`!u&0F`@$wK^Uh3#Vj+nV`ycj%p&yn1#q$ZFw)vkj){LR?*_`HfO zdVdff-lgI^!Ux=uwkUn{bx9-Tlf*)%1XO6u)$e;YtBHHlfuQn$B`Zop%sJ%KCL+h(N1QiD|hb zMoq@$(8OQN2WE{`PntvS0&7^;_m>!m`uJvjn)r&=3IedA!2zq*8nzBL=CfKNNPZ|P zocT@=hhky+aQG4kJ*nmb6cnE$)?N~n1xYZke>DF5FC1j)xH`HFEwSp|(MKX(#oSD+ ztu5-7NHDFR0O=LOtsS?d4CrZc&s{dV){(${Q{6qwhj26(M?WXG5p`r?CHnTZJHePG zHf};5rXT;+)=}6wUi2*JF$e)bMvU~WHj?pxmxM>=??qB1ksD2Bop;$QH7jz?yBk=wr28c?}$quk`KqmY(FIb#gc!wQoI zZ&!=7TaW5EpX$c3lS;~*bTkTuvNk~zP!$ejqv}6(Tg$7lY~2_t3JBujue7t%(@Pk+ z1;-H=Nf5t+1hTgZ&c)i=C%_qT+*(SNd`DttAl$^sYJ0GpwHP8w8UeMi@vZ1GrjEOQ3_T7p5e|8n-rQ$G{mQZYI9N98djj00p(P&vl0g(~&M?s(kKtby*#C<7FsAONC0NS?b1o)nQ zXT517w4rtRRuE$R8khNfN&ZZTaSM&vbmh|00BWlf!55vP8m39KRhbhO z<5ze+n&l77fAViqfzr4{*J0!j3jY>%(WlEEB%kJ;x+v;cgcsDrk_hG2d_-a>Mqtp( z_#qLSOJ;<^)0hQ;SxgOW!CYTq*AQ|tO0#DbzXUBhG!moJs|5)1X##(mp7cn;3IW8t zSWQZ> zWzZ+u8TN% z&`e5MDahopLNA#6LOY(S0|n4^h-G_O+gcQe=&s!51%Goi3ltc_e7e_v>Q!K7ag1mb*qv zzHRqC#0&jnI?MY;B)LN$pa~~SWEJ^~gIfCy&zY~l_cEAa)CR%T)!Hd(j^V`4mo6H6 zLrXvLQ@m94C6KOF2Vgcu8&E%b{S`rGXRb_6(Bj4a@^{Cvpx9yNi*U9G$1zI-9{3Z~ z*`f1^9UnjjYxwcJZtRDV8Y?4|y}TVV;ar0a%u_4`boYf%wFSr!idS;L{0hMq<=qnQ zEE4&y<|~h6)c4{)r!sl4Dp#YmY3BW4^ZMSlXd?GxLXU8MhIq*l`$afjqIbX0e`_m` z2FNb0mWd)Q*9Xg?PX7|W9@x!=B*8?pNH~PHdj&XDRh(gdvW+wT1yHGW-8#M{&-wCK z3Do-2%hfb)y(k~oD(G<3Iwhnb*T3iynr$_A*`?_e!-@-HFiin-t&2J{7O*&aK?a(X zcU%CT@~8?9OPUZ6XQ3w~=vKhQ=b0LrK_VF#y1UHLv>GU_9pScQ3IYh=1xk&U!-GTO zFt`yUNJ3TDP~Z1@|EuJahTE^^COc8{HKj2m)Bu}1`iQiO-@I2Ej{yHH^GQuPL6#MH zQO##JMAEt7>+DUdc|ikijnOvLF#{3|`)JeiE;LXEXdt7=l0i{)X-v5mJu2k?%~Kh{ zy;3zMA}8Y6arYf7V1ZX1LtxJ49z_&j=@!>SZJV6KJT+BRk;M-DeL|a(RfvRc1C2Pl zdFpxb$uTY6N+nCyxY!%BLwgE~3A#+!;MRs{$lSx>``Oxo_~d%=e{;y8m-*3plI4X` z@|{J~NX8bb26Bhz+`@~c5O%5Y z9|^2sp9C8bY$Gz&l4wdux~@>BNgLJ7Gr+MY4sttGNG+YQ%lUhqRA~W?hZ)=Lx=6|2 zcQ%`*LL@SU6tS8>(NS12ve{wG zQ^1g;ZS1z?42THcUKHtGt~0ccCXkyFMa9fqU`rBFL1z zk9~nq`@}{|PB{tOPTCWzvb0%*q*S-n+E5R|4l7Jz;@mci*a|bLb?pp0FfCo93~U)+?J~jK6V&k)dFhPQOr=bk`cJ2DC>gBo|BHg_(tO7 zUq%D$HqL}?-lUAIXEX{*K5`Q6+ncv5^7Pkv0i-+Ar(wsdQ(c$NE@3$@{ekmR#A;jB zkKE(p-pP1)Fcndynqey+55*)ON>{y~C7Tx*Jq)8s!-~R>w0n^p>_iOgL0#S65!>Ny zyE8Sk(wSmd1$x1Nr@rMa!x%)ZU&&6!lqS2(L=dVb5BjD zZGt7*4L&Ro>P#Lon;Zq4p4=(Wkxa3I5vfjx!*tXo3Z(83$5H4BEm!eoaLx(LAdX@| zXw0e8^?2&!DU%XyDUEUJrJ)2B6D2tL4`hoWJRt~nBT$Nv!zA})1`GxK<62E09@XB$ zP#7uf`t47pDz?+e!El;Qm7|aFJFhnj$7sfycCqPS}g0cK;j7 zT9z4o2$RC&A_P6!$aZDv!18$m&-FBrsp|XlV|o=oo-X&-pzgL_nV7+MB{M>4`IEf5 zl@bwkLx|@(j;xs8Blt>(h90tLqV`3ig0`MgwRi%VEA$l=+2HzQEdE3AVa(PJ7+l}G zn%*OUHfp2ncgfH$@(uu@x^=r_xZbjA9tt4iBFM|rx9FWWr0Ht zuya?i(tgkRk#tdzClM&7>(}d&Q3a>9mkzpn2Ox%=bGb^$tE{a1*esB6r71UCq!r7z z>rF6)*j#-TsfA(MssC31qvS$37idb{eD#b!*%yaE!z%zv+_AK8m>4z`T-fO$(15h& zIn`$=lEnWNc=jBDX{;Yb@%E4>f>x^{Tk2mr=ut;sL9(Z8X$M^;mtl zRtFEr_;yjrCt2%NqI0eY3Gst_ayI#HJFuwhBdFs9vmj5}qGhWf!+Oq}Ldv&2M8_ia z;DIMdYDN>vvD+;H#5573&RSU8PS6ZiPz~td>K%_76#8}6iTMRTu${&c{b`*_l06zI z7?uVu6lm@>2agibsS6T%QUm=SphfGjz}lS}n2ui|VGQ!9RluvIHqr(&eRe%VWH{X$ zpDZI&Gj0|vNBm8FBcLr~FMrEtTBjNC|39~*1hr_~zxlrViaD-?oRrS}g*ju(HK;0m zb$>vD(Le*P2T>n)!G(nRl-~TUk~nU-hx*4cVIjkhYSPdbmLIPNJuRUC^|9?a~f8kz65T*G*TD^0b32%E}fS>RkDMJ?q30U z<;e4wnfaXd3QEgx4Pie3xo*yWdQqosm}br!8q`uDdU9u6rwLJh-tRYQ6A?JvvAOTG zzEmn#jN9QLZHSs3zRb%sD`&WE!x=l5E8KB?`qZ9E2I_Ow-}87x*06%XbkS=QJa8rU z3yr)Y6zVgpL7#WfdrBj2Icv@`EArTy2@YoOzX|ke)fNh|s8}>PRfndbwOgy9A>g1R z)OtTD(r9WUz#=U$iM}Eq3O;Dtd`pCBj>|asskHq#3}+K(!vwTr#I4D zo4)TN^9bO}NHRi4J*E#@>d4cB7||H|sLr~>elKz>-6&m=dk+w7P^=0gzFrz<+n~o? ziJ%_!}gi9Y5@JeLzk*!M{zEWee4Ty8@&*XfC5FWAPI@2L!;^PJ&n83vWiAkDgx{6niG`*f*aoc@USeQS0o&>u9vc-Ch1c~$6jgWMsnu{T!$Llg zs&q(a&gmY|9^8KiNHsGkZ}K6LJ_a@QK?!{}1o55&-Oi{*6HCtU1;Cj7=Nc{@pY$^4zJX zLQV=i?6J0tx#IjQVqP-xTlOsH30L&&j&mBEO(572tFY(0B_$$QV<<3l^cPHb(Kj47&SM==G8a_t{bPcVVv^c!GFk&RT1EB%>hZ! zkWkLKdHVU-MMeSXC}~Ws4azF+2-J08QROMV#$#2cUhZvVc9_t#F9 zT*=trCuR!j4Qd){0#o}N8y-fiVUG^Zj6qm6E(n>?OtwPA!^Bte(7M~YR_KQTP!Lgs zDL8yU2cdKp&5`4D@QQq>mAqiL=5JKp(@F8xM*))<4Fkj4iBzJn!J$zLcw!vX$s>$x z_|6^p`^-Yy-!ro&_9`7+>ZIsC1G1+zUez4O?ewfZJO2m8;HRx z+{K<1hAfwrKq2P^MvWWz`R#?s{a+~9nD}KxP6rg!eiWu>B|Vm2hYwpJcKPzY{iBFK zAA@R*3|9Q;Vr5&eNmK;lz2u(}Mj?`(ew6z56~R8v-iE`-wCocV4ZS+yo`U?-|87th zkue^3iZ&~%;>!Fo%VkdR-YvIhB$YLPZVWgu%`x0@109-4!qvN+g>XnYSv`>OZJ;rO z(Hf&VVTVaq5MVqIItRwEK-oJ}`VIsh@d3&aM)uBaeZ3K4We$vhK2y}Du!p{0Otra+ z1V^hFX6%r!IRNQJeF5_uEPZArv~S4a*}6vfd{9*nJgnPD47Un#T7!RUwp6(ns=1^{ z=!#!VLjjAH9D}WR;4`a@$5kjnYq3Vwn{0RfePdNPBff0x2aye+1xfkmtfXIC^orGD zch+KPb(939FV0jlTsckSZ<49YWB`35vMaGDG(^NspSsJq#CN}ln4k%qQLUYYg+}5n9 zyoZ+FGNLK&&hw<#p8Pl|ydtV(V7hi<=*gBk25O}c8gkaIvuZ^%jMvSo2MfkhDtcWD|J~J`!w>c+ zfuJHx|INSKrqPk`@70kJG5 z-MlevZGxMrrnC#l7TF|zCR)IM6GvqBqyV6E?i~)03UX@=^cxpuUhLtW1x1-*{yP?) zy+N}|I}XSx(OdmsW1_hf$kd-blL3DgFEw?==SZ6nu3j-uGMc0)>#=QELu)T%p{}UznBY5?x2T3HH)L zj|IO9-i``cob@3BTX|D5JZv7n$;&|Lj7Ey=FaQUI*8+b`inC!neUs0rq`3djA^Vn zKc-lpiGih_tGg?i8OAL9_a$J70f2fm?oCdV|L9iQvh3B|pf(KQZe8wl`MSAhuEF%G zbI)4;H`vee*QQ3(Es)?$OMX2?A`%yR%Y9UVg#i;}*1EnMf(+cmZ!-2^uCo;}rghgv z8%yL^U1N9QVA09yL8nCzX-TgDYxvfMHW_t}H7l(8Z zsHnnJersGB(YBm_f<^X*ch}VYVGQr$=a);6xY5+9cqG zc#O+gW}VRH)|B@J;Q9~|UmU@M=$Vb5lA5*-=s7q;!ty?RM&__Ht;sm7Tf?jBI3_FA zt__d+z<}s#t&K+Pb2+A!Hl_)O&UBk{20leKsTYpuBIb-KwT;LYMr=WUH;VCibolGe z*%+HJwlNal5Wb0&g1Rww$1}`@LM4WEe=+01+jGm$eq0ghNrK#Ry?^n`u)2Fly^(>H z8ndwy>o@wuwED3x*%mhY2FkSz49F0_%P~njq zy?i6uQiRDx{7SDp>gRfUm4Z{=h3W}<^~JxS5ES)7op-!+_R#M)M%_t*i-xAkkfmA$ zs;;Zhg0oixMjf1;T8mJ#2s}#hO7tDw(4y2#^YI;=i?7m=l_&npxxpjO2&5Ulm4ysZ z1~TC9RP4xuMmJZ9klb+lD+W&vIDR=Ne*p(ivY#*6%5ZLMnZ)ycE4>e9v(;h<`1zVg zFfXrxrC#Kp<|$p@wfUs!c$6$XkgNvAUqYy^VJl{h@q&E$w%!2BZ-hLGoRSnuh5mg8 zcPQ-5JbQUPfjt?+ggsTgM)wIK>_Pj!BV|)fC7?t7ZI6LUJlsQ&sMlrZtv}1rIgA4a z=Bbcs2V-3J)dv!1wGtIK25@r+JdG(eFCesTLI*>G#mCQa^Z0G|5VWt91YGFd+F zQRi_$UqYervW3$;GF^1@Ms>5O*y9V+`uN=jKA8p<@u&QId}s@?=X6Yc6h6v)=|$l* z1pJzuTdT(TNJy?0deUO6Szow~3&M$=73^R1VwLv5rXk32?nR@1_NjTs%sGKPp-TAq~f9AWSlZ)ZT6Pe6*v9 zMX?iO_+CKo`an$76i4Q9XypshHHmLE6R^6p>!r%&U>N!i{b29PJ>*Xycp$EgWPsEx zv!V8MI_x*6F;lo(1Zpo}bGd!khTcHr$=p^$S#ucTI*9RY zhsF5hE=f7}{AxN=07EprcW|nLMZXa0EnR|qxu;yWeK_pD^X6$(;#a)6afjME9b9Rb zza87euSo7ZE;MbWPiHoW9wMU*3aqfimNfqm!)J-$9d3=yiXU2Vfef4<|Caa+`CJ(! zKfn{?3J#$uMmz=BGC%2VU44mIdXK0&esb~95iZG|bAX1pIxf50)4>Oz5+eu#WERg% zXLRQmaUuMMJowrh-^)*z{&SBp8!w$Crh`>`B?4q2nf?>Q{2D#p!QZPh`KCId7U7Kw zBC;@IGl$5M2jWN7osJ>s!mIgOnK>2{tSQ-KoIGgurW4lI$OR9^2D`ys*n@y+886@8 z-$E81CkoPI`1VBGbhM_8Zxr_d2y@F306D6-=+lE`SP}7}GItZNHxLtm z%3&zx0zMB{wNX}b_E_OZH1=wB^iRQmDaL6-JwLQ<2(E%oCvh2GRBJytxG0LFaM*(0Qh6F_a8y>$V!VoD;A;w{K9#rXis9TkVj_ZQQaAoHUk zZZ#Jn+udg51sirdpcmA@MI^TqF}T4JzZ}P5ci}Um{KAU|hYCaTX5QVWA>fIthIaZ!U5P z?nnBUH;>`IKx*SWiAhpwQ&;K4xi|5dK&;P>PI`5=M%jD7$>9

bd+_u7x#UBMZN?S73soh%9r zecu8eik6dyY9uzUKah)?2^60z8X61E>f9vMVY<5c6GMJgTbI5B>7aKlh1}EMCcvGB zVKMQ!{U(AW0)yv_cS}l};l}DWtPYwgboohD>pG?!9+T2O;Rnn2CCIqirl_QQ0PgfU ztcl&@+zLaK^p`UOdT2HIUWBpm(Bqzz!F0EoJprQchaX2#fb=T;tyPWJ!Lwj@inCn_ zb2nrY#u&%DjFtB3wZ*xl9`$H7bQ|mEARU@BMknOScy^%bJv%|?8rbNOqU>GS9ZTdVYzF$ z%kK1S>AWo3w@iAa-TVuo&Q!UMoE zc^iVgUpdL%?q46iiLQ{I`=~>2TDq>7{Chv^YN-Nf_s{h`L}lDL$+5|nUllFB^D4m} zf_TW45-Ok-^pM(1(+-yP_GY~TFjO|*TD^^|63?!W`xoqP+{ho2@$YDM@D6q$M~Y%# zg5CT+v#?2uR(ZRTmIIH3Doihog(8C&6jmGH3RR zP$a9s>oJFn^$O>8N6*{gD@NQFNj8uiKj>c{U~(_Nnf9qWUbF)Z@E^l0>J_$iYwTI- z@P5Tr#gC!Z+~8FMx}sb>nlU%oUiLh0O}uZ?2Ms8_G=HA5s9jz|nAjOsxXrEj^iyEt z7StH*BW5Z8f2c+f!nTp29K4XVoWCLi@aTC2ri>lYWZO|1GS|3~61@e*!q=XDz{P5> zE-(-k`-TJhJm znxcUPPu|1x=7XQ3CJhr##O@wx4f1=!`)8~t_cJRjQG(coivr34f63Dn+erxNW+jI{WXth zxpdv`oAHpl)mt$>Hc#ZO*h7c8QG|6;QWYi&sEiYENgX`{Bs8%&L$JYIC|C@GT8r#| zA&wHMLGeqFnt5xVr!L4in%HB7Wy?Zh?s64<{SgmBDtE{)~6zi->`n8hOJIG)L~F@8qZLD8(bMR~7b_=bxR zOq~?YbnGDsnc}pP+w?Czwxa!rb9exE08aIhwzC;b6N-;_V7-`(gVWU?S(S>nRqSn^I%M{6hZgPMDEXb=W9 z1jprRacX05ogedUXxL47TKXykU#ywOZmcgbcOod-QtCat+{Us+tv0OpB#M4J}lt!OhofE4GWSKDVdzG?fWK1tS z6k!8jIMrd1dqy1x389?P4uJ=kY+8sNoy#5`Zqch8OP@uIg`C_d%5!QXVCUZZL=|I; zSm(#>N}19c^C%g8GOCEuZfT#2X4wWZkv5$2Kjn0Qgkxs<&REur=vyPt$%1ps&n9Gh z_h$Y{lDp7uFf@2SYQ}|!%!eGKM8B_qIDC;kL3!UlnoV1qpL{nA6f-3B`K=)_l;t@B>wJr z>AxXhW+ literal 0 HcmV?d00001 diff --git a/public/docs/images/tutorials/algorithmiq-tem/extracted-outputs/c3a2168d-98df-491e-a1f8-05de5684ab96-0.avif b/public/docs/images/tutorials/algorithmiq-tem/extracted-outputs/c3a2168d-98df-491e-a1f8-05de5684ab96-0.avif new file mode 100644 index 0000000000000000000000000000000000000000..123e1ef14e8fdc1666919aa6c178f140eb0a3329 GIT binary patch literal 2492 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 literal 0 HcmV?d00001 From a5c9551ed98b7679313f363b54a03c32bf08c56c Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:44:32 -0500 Subject: [PATCH 03/11] add to notebook-testing.toml --- scripts/config/notebook-testing.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index 4caa79c07c5..cddf930d1a3 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -160,6 +160,7 @@ notebooks = [ "docs/guides/qiskit-transpiler-service.ipynb", # We never run tutorials notebooks + "docs/tutorials/algorithmiq-tem.ipynb", "docs/tutorials/dc-hex-ising.ipynb", "docs/tutorials/ghz-spacetime-codes.ipynb", "docs/tutorials/sml-classification.ipynb", From 19f364c2a04b723ee20b68c8025ab3cc1a588d2e Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:46:00 -0500 Subject: [PATCH 04/11] Update qiskit_bot.yaml --- qiskit_bot.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 0570b905ba2..7fcbd7a8c56 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -640,6 +640,8 @@ notifications: - "@ThomasMerkh" - "@alexshih" - "@HuangJunye" + "docs/tutorials/algorithmiq-tem": + - @HuangJunye" "docs/tutorials/global-data-quantum-optimizer": - "@abbycross" - "@pandasa123" From 04f5da64e6327a37b86a4e5f57aa8e7f0d929c97 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:48:16 -0500 Subject: [PATCH 05/11] Update qiskit_bot.yaml --- qiskit_bot.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 7fcbd7a8c56..17b5bd18800 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -641,7 +641,7 @@ notifications: - "@alexshih" - "@HuangJunye" "docs/tutorials/algorithmiq-tem": - - @HuangJunye" + - "@HuangJunye" "docs/tutorials/global-data-quantum-optimizer": - "@abbycross" - "@pandasa123" From 23701cd9df15c2b52a022555df888bb7c71554dd Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:50:30 -0500 Subject: [PATCH 06/11] title to match index --- docs/tutorials/algorithmiq-tem.ipynb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/algorithmiq-tem.ipynb b/docs/tutorials/algorithmiq-tem.ipynb index 255b73c73be..695bd180449 100644 --- a/docs/tutorials/algorithmiq-tem.ipynb +++ b/docs/tutorials/algorithmiq-tem.ipynb @@ -6,12 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Tensor-network error mitigation (TEM) - A Qiskit Function by Algorithmiq\n", + "title: Simulate a kicked Ising model with the TEM function\n", "description: Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.\n", "---\n", - "# Tensor-network error mitigation (TEM)\n", + "# Simulate a kicked Ising model with the TEM function\n", "\n", - "Algorithmiq’s Tensor-network Error Mitigation (TEM) method is a hybrid quantum-classical algorithm designed for performing noise mitigation entirely at the classical post-processing stage. With TEM, the user can compute the expectation values of observables mitigating the inevitable noise-induced errors that occur on quantum hardware with increased accuracy and cost efficiency, making it a highly attractive option for quantum researchers and industry practitioners alike.\n", + "Algorithmiq's Tensor-network Error Mitigation (TEM) method is a hybrid quantum-classical algorithm designed for performing noise mitigation entirely at the classical post-processing stage. With TEM, the user can compute the expectation values of observables mitigating the inevitable noise-induced errors that occur on quantum hardware with increased accuracy and cost efficiency, making it a highly attractive option for quantum researchers and industry practitioners alike.\n", "\n", "In this tutorial, we will showcase how TEM allows to obtain meaningful results for the dynamics of a quantum system, which would be inaccessible without error mitigation and require substantially more quantum resources if other error mitigation methods such as PEC and ZNE are used." ] From c6ee7decd50cf7790057f30f5b5b54e8e26a2042 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:51:47 -0500 Subject: [PATCH 07/11] Update _toc.json --- docs/tutorials/_toc.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/tutorials/_toc.json b/docs/tutorials/_toc.json index 7d80dc85b76..df63295dac7 100644 --- a/docs/tutorials/_toc.json +++ b/docs/tutorials/_toc.json @@ -166,6 +166,10 @@ { "title": "Simulate 2D tilted-field Ising with the QESEM function", "url": "/docs/tutorials/qedma-2d-ising-with-qesem" + }, + { + "title": "Simulate a kicked Ising model with the TEM function", + "url": "/docs/tutorials/algorithmiq-tem" } ] }, From 0d4051a32992e98ff911b5ad1a7cf2139912630e Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 11:07:09 -0500 Subject: [PATCH 08/11] fix metadata in guide --- docs/guides/algorithmiq-tem.ipynb | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index 14dc905a1f4..c18750f98cc 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -1,18 +1,17 @@ { "cells": [ - { - "cell_type": "markdown", - "id": "f7d9993f", - "metadata": {}, - "source": [ - "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez, Minev, Kandala, Temme, informationally */}" - ] - }, { "cell_type": "markdown", "id": "dde95705", "metadata": {}, "source": [ + "---\n", + "title: Tensor-network error mitigation (TEM) - A Qiskit Function by Algorithmiq\n", + "description: Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.\n", + "---\n", + "\n", + "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez, Minev, Kandala, Temme, informationally */}\n", + "\n", "# Tensor-network error mitigation (TEM): A Qiskit Function by Algorithmiq\n", "\n", "\n", From 796b0dc0acccccc88e7ac81eb4e5f7085d07c20e Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 12 Feb 2026 10:05:00 -0500 Subject: [PATCH 09/11] Update algorithmiq-tem.ipynb --- docs/guides/algorithmiq-tem.ipynb | 868 +++++++++++++++--------------- 1 file changed, 434 insertions(+), 434 deletions(-) diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index 95cd5d4d13e..f2ee0d193e6 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -1,436 +1,436 @@ { - "cells": [ - { - "cell_type": "markdown", - "id": "f7d9993f", - "metadata": {}, - "source": [ - "---\n", - "title: Tensor-network error mitigation (TEM) - A Qiskit Function by Algorithmiq\n", - "description: Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.\n", - "---\n", - "\n", - "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez, Minev, Kandala, Temme, informationally */}" - ] - }, - { - "cell_type": "markdown", - "id": "dde95705", - "metadata": {}, - "source": [ - "# Tensor-network error mitigation (TEM): A Qiskit Function by Algorithmiq\n", - "\n", - "\n", - "Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "b130b1ae", - "metadata": {}, - "source": [ - "{/*\n", - " DO NOT EDIT THIS CELL!!!\n", - " This cell's content is generated automatically by a script. Anything you add\n", - " here will be removed next time the notebook is run. To add new content, create\n", - " a new cell before or after this one.\n", - "*/}\n", - "\n", - "

\n", - "Package versions\n", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit[all]~=2.3.0\n", - "qiskit-ibm-catalog~=0.11.0\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "47066e9a", - "metadata": {}, - "source": [ - "## Overview\n", - "\n", - "Algorithmiq’s Tensor-network Error Mitigation (TEM) method is a hybrid\n", - "quantum-classical algorithm designed for performing noise mitigation entirely at\n", - "the classical post-processing stage. With TEM, the user can compute the\n", - "expectation values of observables mitigating the inevitable noise-induced errors\n", - "that occur on quantum hardware with increased accuracy and cost efficiency,\n", - "making it a highly attractive option for quantum researchers and industry\n", - "practitioners alike.\n", - "\n", - "The method consists of constructing a tensor network representing the inverse of\n", - "the global noise channel affecting the state of the quantum processor and then\n", - "applying the map to informationally complete measurement outcomes acquired from\n", - "the noisy state to obtain unbiased estimators for the observables.\n", - "\n", - "As an advantage, TEM leverages informationally complete measurements to give\n", - "access to a vast set of mitigated expectation values of observables and has\n", - "optimal sampling overhead on the quantum hardware, as described in Filippov et\n", - "al. (2023), [arXiv:2307.11740](https://arxiv.org/abs/2307.11740), and Filippov\n", - "et al. (2024), [arXiv:2403.13542](https://arxiv.org/abs/2403.13542). The\n", - "measurement overhead refers to the number of additional measurements required to\n", - "perform efficient error mitigation, a critical factor in the feasibility of\n", - "quantum computations. Therefore, TEM has the potential to enable quantum\n", - "advantage in complex scenarios, such as applications in the fields of quantum\n", - "chaos, many-body physics, Hubbard dynamics, and small molecule chemistry\n", - "simulations.\n", - "\n", - "The main features and benefits of TEM can be summarized as:\n", - "\n", - "1. **Optimal measurement overhead**: TEM is optimal with respect to\n", - "[theoretical bounds](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.131.210601),\n", - "meaning that no method can achieve a smaller measurement overhead. In other\n", - "words, TEM requires the minimum number of additional measurements to perform\n", - "error mitigation. This in turns means that TEM uses minimal quantum runtime.\n", - "2. **Cost-effectiveness**: Since TEM handles noise mitigation entirely in the\n", - "post-processing stage, there is no need to add extra circuits to the quantum\n", - "computer, which not only makes the computation cheaper but also diminishes the\n", - "risk of introducing additional errors due to the imperfections of quantum\n", - "devices.\n", - "3. **Estimation of multiple observables**: Thanks to informationally-complete\n", - "measurements, TEM efficiently estimates multiple observables with the same\n", - "measurement data from the quantum computer.\n", - "4. **Measurement error mitigation**: The TEM Qiskit Function also includes a\n", - "[proprietary measurement error mitigation method](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.5.033154)\n", - "able to significantly reduce readout errors after a short calibration run.\n", - "5. **Accuracy**: TEM significantly improves the accuracy and reliability of\n", - "digital quantum simulations, making quantum algorithms more precise and\n", - "dependable." - ] - }, - { - "cell_type": "markdown", - "id": "5f761442", - "metadata": {}, - "source": [ - "## Description\n", - "\n", - "The TEM function allows you to obtain error-mitigated expectation values for\n", - "multiple observables on a quantum circuit with minimal sampling overhead. The\n", - "circuit is measured with an informationally complete positive operator-valued\n", - "measure (IC-POVM), and the collected measurement outcomes are processed on a\n", - "classical computer. This measurement is used to perform the tensor network\n", - "methods and build a noise-inversion map. The function applies a map that fully\n", - "inverts the whole noisy circuit using tensor networks to represent the noisy\n", - "layers.\n", - "\n", - "![TEM schematics](/docs/images/guides/algorithmiq-tem/tem_scheme.svg \"Error-mitigated estimation of an observable O via post-processing measurement outcomes of the noisy quantum processor. U and N denote an ideal quantum operation and the associated noise map, which can be generally non-local (and extended to grey boxes). D stands for a tensor of operators that are dual to the effects in the IC measurement. The noise mitigation module M is a tensor network that is efficiently contracted from the middle out. The first iteration of the contraction is represented by the dotted purple line, the second one by the dashed line, and the third one by the solid line.\")\n", - "\n", - "Once the circuits are submitted to the function, they are transpiled and\n", - "optimized to minimize the number of layers with two-qubit gates (the noisier\n", - "gates on quantum devices). The noise affecting the layers is learned through\n", - "[Qiskit Runtime](/docs/api/qiskit-ibm-runtime/noise-learner-noise-learner)\n", - "using a sparse Pauli-Lindblad noise model as described in E. van den Berg, Z.\n", - "Minev, A. Kandala, K. Temme, Nat. Phys. (2023).\n", - "[arXiv:2201.09866](https://arxiv.org/abs/2201.09866).\n", - "\n", - "The noise model is an accurate description of the noise on the device able to\n", - "capture subtle features, including qubit cross-talk. However, noise on the\n", - "devices can fluctuate and drift and the learned noise might not be accurate at\n", - "the point at which the estimation is done. This might result in inaccurate\n", - "results." - ] - }, - { - "cell_type": "markdown", - "id": "2995da29", - "metadata": {}, - "source": [ - "## Get started\n", - "\n", - "Authenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the TEM function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "cc0a8093", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", - "\n", - "tem_function_name = \"algorithmiq/tem\"\n", - "\n", - "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", - "\n", - "# Load your function\n", - "tem = catalog.load(tem_function_name)" - ] - }, - { - "cell_type": "markdown", - "id": "ae7adcc7", - "metadata": {}, - "source": [ - "## Example\n", - "\n", - "\n", - "The following snippet shows an example where TEM is used to compute the expectation values of an observable given a simple quantum circuit." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "ab05b87f", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit import QuantumCircuit\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "\n", - "# Create a quantum circuit\n", - "qc = QuantumCircuit(3)\n", - "qc.u(0.4, 0.9, -0.3, 0)\n", - "qc.u(-0.4, 0.2, 1.3, 1)\n", - "qc.u(-1.2, -1.2, 0.3, 2)\n", - "for _ in range(2):\n", - " qc.barrier()\n", - " qc.cx(0, 1)\n", - " qc.cx(2, 1)\n", - " qc.barrier()\n", - " qc.u(0.4, 0.9, -0.3, 0)\n", - " qc.u(-0.4, 0.2, 1.3, 1)\n", - " qc.u(-1.2, -1.2, 0.3, 2)\n", - "\n", - "# Define the observables\n", - "observable = SparsePauliOp(\"IYX\", 1.0)\n", - "\n", - "# Define the execution options\n", - "pub = (qc, [observable])\n", - "options = {\"default_precision\": 0.02}\n", - "\n", - "# Define backend to use. TEM will choose the least-busy device reported by IBM if not specified\n", - "backend_name = \"ibm_marrakesh\"\n", - "\n", - "job = tem.run(pubs=[pub], backend_name=backend_name, options=options)" - ] - }, - { - "cell_type": "markdown", - "id": "6e2a97e2", - "metadata": {}, - "source": [ - "Use the Qiskit Serverless APIs to check your Qiskit Function workload's status:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "47b0db71", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "QUEUED\n" - ] - } - ], - "source": [ - "print(job.status())" - ] - }, - { - "cell_type": "markdown", - "id": "fbaeace8", - "metadata": {}, - "source": [ - "You can return the results as:" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "ad5b9a53", - "metadata": {}, - "outputs": [], - "source": [ - "result = job.result()\n", - "evs = result[0].data.evs" - ] - }, - { - "cell_type": "markdown", - "id": "e5e138d3", - "metadata": {}, - "source": [ - "\n", - " The expected value for the noiseless circuit for the given operator should be around `0.18409094298943401`.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "c6ffb685", - "metadata": {}, - "source": [ - "## Inputs\n", - "\n", - "**Parameters**\n", - "\n", - "Name | Type | Description | Required | Default | Example\n", - "-- | -- | -- | -- | -- | --\n", - "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", - "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least-busy backend will be used. | \"ibm_fez\"\n", - "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n", - "\n", - "\n", - " TEM currently has the following limitations:\n", - "\n", - " - Parametrized circuits are not supported. The parameters argument should be set to `None` if precision is specified. This restriction will be removed in future versions.\n", - " - Only circuits without loops are supported. This restriction will be removed in future versions.\n", - " - Non-unitary gates, such as reset, measure, and all forms of control flow are not supported. Support for reset will be added in upcoming releases.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "1ebd5f9b", - "metadata": {}, - "source": [ - "### Options\n", - "\n", - "A dictionary containing the advanced options for the TEM. The dictionary may contain the keys in the following table. If any of the options are not provided, the default value listed in the table will be used. The default values are good for typical use of TEM.\n", - "\n", - "Name | Type | Description | Default\n", - "-- | -- | -- | --\n", - "`tem_max_bond_dimension` | int | The maximum bond dimension for the tensor networks. | 128 |\n", - "`tem_compression_cutoff` | float | The cutoff value to be used for the tensor networks. | 1e-10 |\n", - "`compute_shadows_bias_from_observable` | bool | Whether the bias for the classical shadows measurement protocol should be tailored to the PUB observable. If False, the classical shadows protocol (equal probability of measuring Z, X, Y) will be used. | False |\n", - "`shadows_bias` | np.ndarray | The bias to be used for the randomized classical shadows measurement protocol, a 1d or 2d array of size 3 or shape (num_qubits, 3) respectively. Order is ZXY. | np.array([1 / 3, 1 / 3, 1 / 3]) |\n", - "`max_execution_time` | int or None | The maximum execution time on the QPU in seconds. If the runtime exceeds this value, the job will be canceled. If None, a default limit set by Qiskit Runtime will apply. | None |\n", - "`num_randomizations` | int | The number of randomizations to be used for noise learning and gate twirling. | 32 |\n", - "`max_layers_to_learn` | int | The maximum number of unique layers to learn. | 4 |\n", - "`mitigate_readout_error` | bool | Whether to perform readout error mitigation. | True |\n", - "`num_readout_calibration_shots` | int | The number of shots to be used for readout error mitigation. | 10000 |\n", - "`default_precision` | float | The default precision to be used for the PUBs for which the precision is not specified. | 0.05 |\n", - "`default_shots` | int or None | The number of shots to use per PUB. If provided, overrides the specified precision. Otherwise, the number of shots is estimated to provide the precision requested. | None |\n", - "`seed` | int or None | Set the seed for the random number generator for reproducibility. | None |\n", - "`shots_per_randomization` | int | The total number of shots to use per random learning circuit. | 128 |\n", - "`layer_pair_depths` | list[int] | The circuit depths (measured in number of pairs) to use in learning experiments. | [0, 1, 2, 4, 16, 32] |\n", - "`layer_noise_model` | NoiseLearnerResult, Sequence[LayerError], or None | The precomputed noise learner result from a previously executed run. | None |\n", - "`private` | bool | Whether the QPU jobs should be private. Setting it to `True` will prevent subsequent downloads of the experiment data and is recommended for confidential jobs. | False |\n", - "`tem_enforce_linear_circuit` | bool | Whether to enforce the circuit to be in linear topology. | False |\n", - "\n", - "#### Precision\n", - "\n", - "The precision of the results can be requested in three ways. The precision can be passed in the PUB, and it will apply to that PUB only. Otherwise, a `default_precision` can be passed in the options as specified above. Finally, for advanced use, the specific number of shots per PUB can be passed in the options with `default_shots`, and it will override any other precision option.\n", - "\n", - "If a `default_precision` or a per-PUB value is passed, the number of shots is estimated in order to achieve the desired precision. This is done based on the chosen QPU parameters and error rates. It does this by:\n", - "\n", - "- Calculating the error per layered gate (EPLG), which quantifies the noise introduced by layers of two-qubit gates. If backend properties are available, it extracts the relevant fidelity; otherwise, it uses a default value.\n", - "- Counting the number of two-qubit gates in the circuit, as these are typically the main contributors to noise.\n", - "- Computing a noise prefactor based on the number of two-qubit gates and the EPLG.\n", - "- Using the requested precision, it estimates the required number of shots by scaling with the noise prefactor and the inverse of the square of the precision.\n", - "\n", - "This approach ensures that the number of shots is sufficient to achieve the desired precision, taking into account both the circuit structure and the backend's noise characteristics." - ] - }, - { - "cell_type": "markdown", - "id": "7a04364c", - "metadata": {}, - "source": [ - "## Outputs\n", - "\n", - "A Qiskit [PrimitiveResults](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) containing the TEM-mitigated result. The result for each PUB is returned as a [PubResult](/docs/api/qiskit/qiskit.primitives.PubResult) containing the following fields:\n", - "\n", - "\n", - "Name |Type | Description\n", - "-- | -- | --\n", - "data | DataBin | A Qiskit [DataBin](/docs/api/qiskit/qiskit.primitives.DataBin) containing the TEM mitigated observable and its standard error. The DataBin has the following fields:
  • `evs`: The TEM-mitigated observable value.
  • `stds`: The standard error of the TEM-mitigated observable.
\n", - "metadata | dict | A dictionary containing additional results. The dictionary contains the following keys:
  • `\"evs_non_mitigated\"`: The observable value without error mitigation.
  • `\"stds_non_mitigated\"`: The standard error of the result without error mitigation.
  • `\"evs_mitigated_no_readout_mitigation\"`: The observable value with error mitigation but without readout error mitigation.
  • `\"stds_mitigated_no_readout_mitigation\"`: The standard error of the result with error mitigation but without readout error mitigation.
  • `\"evs_non_mitigated_with_readout_mitigation\"`: The observable value without error mitigation but with readout error mitigation.
  • `\"stds_non_mitigated_with_readout_mitigation\"`: The standard error of the result without error mitigation but with readout error mitigation.
  • `\"resource_usage\"`: A dictionary containing the time-resources used by the TEM.
" - ] - }, - { - "cell_type": "markdown", - "id": "fd045ee6", - "metadata": {}, - "source": [ - "## Fetching error messages\n", - "\n", - "If your workload status is ERROR, use job.result() to fetch the error message as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "0433171c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray()), metadata={'evs_non_mitigated': array([0.06979321]), 'stds_non_mitigated': array([0.05510763]), 'evs_mitigated_no_readout_mitigation': array([0.07031416]), 'stds_mitigated_no_readout_mitigation': array([0.05566318]), 'evs_non_mitigated_with_readout_mitigation': array([0.08313754]), 'stds_non_mitigated_with_readout_mitigation': array([0.05702442])})], metadata={'resource_usage': {'RUNNING: OPTIMIZING_FOR_HARDWARE': {'CPU_TIME': 0.966265}, 'RUNNING: WAITING_FOR_QPU': {'CPU_TIME': 11.436938}, 'RUNNING: POST_PROCESSING': {'CPU_TIME': 10.379288999999998}, 'RUNNING: EXECUTING_QPU': {'QPU_TIME': 171.0}}})\n" - ] - } - ], - "source": [ - "print(job.result())" - ] - }, - { - "cell_type": "markdown", - "id": "e9ec2e67", - "metadata": {}, - "source": [ - "## Get support\n", - "\n", - "Reach out to [qiskit_ibm@algorithmiq.fi](mailto:qiskit_ibm@algorithmiq.fi)\n", - "\n", - "Be sure to include the following information:\n", - "- Qiskit Function Job ID (`qiskit-ibm-catalog`), `job.job_id`\n", - "- A detailed description of the issue\n", - "- Any relevant error messages or codes\n", - "- Steps to reproduce the issue" - ] - }, - { - "cell_type": "markdown", - "id": "5a6a25c8", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "\n", - "- [Request access to Algorithmiq Tensor-network error mitigation](https://quantum.ibm.com/functions?id=4b1b9d76-c18b-4788-b70b-15125111fbe6)\n", - "\n", - "" - ] - } - ], - "metadata": { - "description": "Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.", - "kernelspec": { - "display_name": "tem-qiskit-function (3.11.14)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.11.14" - }, - "title": "Tensor-network error mitigation (TEM) - A Qiskit Function by Algorithmiq" - }, - "nbformat": 4, - "nbformat_minor": 5 + "cells": [ + { + "cell_type": "markdown", + "id": "f7d9993f", + "metadata": {}, + "source": [ + "---\n", + "title: Tensor-network error mitigation (TEM) - A Qiskit Function by Algorithmiq\n", + "description: Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.\n", + "---\n", + "\n", + "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez, Minev, Kandala, Temme, informationally */}" + ] + }, + { + "cell_type": "markdown", + "id": "dde95705", + "metadata": {}, + "source": [ + "# Tensor-network error mitigation (TEM): A Qiskit Function by Algorithmiq\n", + "\n", + "\n", + "Qiskit Functions are an experimental feature available only to IBM Quantum® Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. They are in preview release status and subject to change.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "b130b1ae", + "metadata": {}, + "source": [ + "{/*\n", + " DO NOT EDIT THIS CELL!!!\n", + " This cell's content is generated automatically by a script. Anything you add\n", + " here will be removed next time the notebook is run. To add new content, create\n", + " a new cell before or after this one.\n", + "*/}\n", + "\n", + "
\n", + "Package versions\n", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "qiskit[all]~=2.3.0\n", + "qiskit-ibm-catalog~=0.11.0\n", + "```\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "47066e9a", + "metadata": {}, + "source": [ + "## Overview\n", + "\n", + "Algorithmiq’s Tensor-network Error Mitigation (TEM) method is a hybrid\n", + "quantum-classical algorithm designed for performing noise mitigation entirely at\n", + "the classical post-processing stage. With TEM, the user can compute the\n", + "expectation values of observables mitigating the inevitable noise-induced errors\n", + "that occur on quantum hardware with increased accuracy and cost efficiency,\n", + "making it a highly attractive option for quantum researchers and industry\n", + "practitioners alike.\n", + "\n", + "The method consists of constructing a tensor network representing the inverse of\n", + "the global noise channel affecting the state of the quantum processor and then\n", + "applying the map to informationally complete measurement outcomes acquired from\n", + "the noisy state to obtain unbiased estimators for the observables.\n", + "\n", + "As an advantage, TEM leverages informationally complete measurements to give\n", + "access to a vast set of mitigated expectation values of observables and has\n", + "optimal sampling overhead on the quantum hardware, as described in Filippov et\n", + "al. (2023), [arXiv:2307.11740](https://arxiv.org/abs/2307.11740), and Filippov\n", + "et al. (2024), [arXiv:2403.13542](https://arxiv.org/abs/2403.13542). The\n", + "measurement overhead refers to the number of additional measurements required to\n", + "perform efficient error mitigation, a critical factor in the feasibility of\n", + "quantum computations. Therefore, TEM has the potential to enable quantum\n", + "advantage in complex scenarios, such as applications in the fields of quantum\n", + "chaos, many-body physics, Hubbard dynamics, and small molecule chemistry\n", + "simulations.\n", + "\n", + "The main features and benefits of TEM can be summarized as:\n", + "\n", + "1. **Optimal measurement overhead**: TEM is optimal with respect to\n", + "[theoretical bounds](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.131.210601),\n", + "meaning that no method can achieve a smaller measurement overhead. In other\n", + "words, TEM requires the minimum number of additional measurements to perform\n", + "error mitigation. This in turns means that TEM uses minimal quantum runtime.\n", + "2. **Cost-effectiveness**: Since TEM handles noise mitigation entirely in the\n", + "post-processing stage, there is no need to add extra circuits to the quantum\n", + "computer, which not only makes the computation cheaper but also diminishes the\n", + "risk of introducing additional errors due to the imperfections of quantum\n", + "devices.\n", + "3. **Estimation of multiple observables**: Thanks to informationally-complete\n", + "measurements, TEM efficiently estimates multiple observables with the same\n", + "measurement data from the quantum computer.\n", + "4. **Measurement error mitigation**: The TEM Qiskit Function also includes a\n", + "[proprietary measurement error mitigation method](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.5.033154)\n", + "able to significantly reduce readout errors after a short calibration run.\n", + "5. **Accuracy**: TEM significantly improves the accuracy and reliability of\n", + "digital quantum simulations, making quantum algorithms more precise and\n", + "dependable." + ] + }, + { + "cell_type": "markdown", + "id": "5f761442", + "metadata": {}, + "source": [ + "## Description\n", + "\n", + "The TEM function allows you to obtain error-mitigated expectation values for\n", + "multiple observables on a quantum circuit with minimal sampling overhead. The\n", + "circuit is measured with an informationally complete positive operator-valued\n", + "measure (IC-POVM), and the collected measurement outcomes are processed on a\n", + "classical computer. This measurement is used to perform the tensor network\n", + "methods and build a noise-inversion map. The function applies a map that fully\n", + "inverts the whole noisy circuit using tensor networks to represent the noisy\n", + "layers.\n", + "\n", + "![TEM schematics](/docs/images/guides/algorithmiq-tem/tem_scheme.svg \"Error-mitigated estimation of an observable O via post-processing measurement outcomes of the noisy quantum processor. U and N denote an ideal quantum operation and the associated noise map, which can be generally non-local (and extended to grey boxes). D stands for a tensor of operators that are dual to the effects in the IC measurement. The noise mitigation module M is a tensor network that is efficiently contracted from the middle out. The first iteration of the contraction is represented by the dotted purple line, the second one by the dashed line, and the third one by the solid line.\")\n", + "\n", + "Once the circuits are submitted to the function, they are transpiled and\n", + "optimized to minimize the number of layers with two-qubit gates (the noisier\n", + "gates on quantum devices). The noise affecting the layers is learned through\n", + "[Qiskit Runtime](/docs/api/qiskit-ibm-runtime/noise-learner-noise-learner)\n", + "using a sparse Pauli-Lindblad noise model as described in E. van den Berg, Z.\n", + "Minev, A. Kandala, K. Temme, Nat. Phys. (2023).\n", + "[arXiv:2201.09866](https://arxiv.org/abs/2201.09866).\n", + "\n", + "The noise model is an accurate description of the noise on the device able to\n", + "capture subtle features, including qubit cross-talk. However, noise on the\n", + "devices can fluctuate and drift and the learned noise might not be accurate at\n", + "the point at which the estimation is done. This might result in inaccurate\n", + "results." + ] + }, + { + "cell_type": "markdown", + "id": "2995da29", + "metadata": {}, + "source": [ + "## Get started\n", + "\n", + "Authenticate using your [IBM Quantum Platform API key](http://quantum.cloud.ibm.com/), and select the TEM function as follows. (This snippet assumes you've already [saved your account](/docs/guides/functions#install-qiskit-functions-catalog-client) to your local environment.)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc0a8093", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", + "\n", + "tem_function_name = \"algorithmiq/tem\"\n", + "\n", + "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")\n", + "\n", + "# Load your function\n", + "tem = catalog.load(tem_function_name)" + ] + }, + { + "cell_type": "markdown", + "id": "ae7adcc7", + "metadata": {}, + "source": [ + "## Example\n", + "\n", + "\n", + "The following snippet shows an example where TEM is used to compute the expectation values of an observable given a simple quantum circuit." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "ab05b87f", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit import QuantumCircuit\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "# Create a quantum circuit\n", + "qc = QuantumCircuit(3)\n", + "qc.u(0.4, 0.9, -0.3, 0)\n", + "qc.u(-0.4, 0.2, 1.3, 1)\n", + "qc.u(-1.2, -1.2, 0.3, 2)\n", + "for _ in range(2):\n", + " qc.barrier()\n", + " qc.cx(0, 1)\n", + " qc.cx(2, 1)\n", + " qc.barrier()\n", + " qc.u(0.4, 0.9, -0.3, 0)\n", + " qc.u(-0.4, 0.2, 1.3, 1)\n", + " qc.u(-1.2, -1.2, 0.3, 2)\n", + "\n", + "# Define the observables\n", + "observable = SparsePauliOp(\"IYX\", 1.0)\n", + "\n", + "# Define the execution options\n", + "pub = (qc, [observable])\n", + "options = {\"default_precision\": 0.02}\n", + "\n", + "# Define backend to use. TEM will choose the least-busy device reported by IBM if not specified\n", + "backend_name = \"ibm_marrakesh\"\n", + "\n", + "job = tem.run(pubs=[pub], backend_name=backend_name, options=options)" + ] + }, + { + "cell_type": "markdown", + "id": "6e2a97e2", + "metadata": {}, + "source": [ + "Use the Qiskit Serverless APIs to check your Qiskit Function workload's status:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "47b0db71", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "QUEUED\n" + ] + } + ], + "source": [ + "print(job.status())" + ] + }, + { + "cell_type": "markdown", + "id": "fbaeace8", + "metadata": {}, + "source": [ + "You can return the results as:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "ad5b9a53", + "metadata": {}, + "outputs": [], + "source": [ + "result = job.result()\n", + "evs = result[0].data.evs" + ] + }, + { + "cell_type": "markdown", + "id": "e5e138d3", + "metadata": {}, + "source": [ + "\n", + " The expected value for the noiseless circuit for the given operator should be around `0.18409094298943401`.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "c6ffb685", + "metadata": {}, + "source": [ + "## Inputs\n", + "\n", + "**Parameters**\n", + "\n", + "Name | Type | Description | Required | Default | Example\n", + "-- | -- | -- | -- | -- | --\n", + "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", + "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least-busy backend will be used. | \"ibm_fez\"\n", + "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n", + "\n", + "\n", + " TEM currently has the following limitations:\n", + "\n", + " - Parametrized circuits are not supported. The parameters argument should be set to `None` if precision is specified. This restriction will be removed in future versions.\n", + " - Only circuits without loops are supported. This restriction will be removed in future versions.\n", + " - Non-unitary gates, such as reset, measure, and all forms of control flow are not supported. Support for reset will be added in upcoming releases.\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "1ebd5f9b", + "metadata": {}, + "source": [ + "### Options\n", + "\n", + "A dictionary containing the advanced options for the TEM. The dictionary may contain the keys in the following table. If any of the options are not provided, the default value listed in the table will be used. The default values are good for typical use of TEM.\n", + "\n", + "Name | Type | Description | Default\n", + "-- | -- | -- | --\n", + "`tem_max_bond_dimension` | int | The maximum bond dimension for the tensor networks. | 128 |\n", + "`tem_compression_cutoff` | float | The cutoff value to be used for the tensor networks. | 1e-10 |\n", + "`compute_shadows_bias_from_observable` | bool | Whether the bias for the classical shadows measurement protocol should be tailored to the PUB observable. If False, the classical shadows protocol (equal probability of measuring Z, X, Y) will be used. | False |\n", + "`shadows_bias` | np.ndarray | The bias to be used for the randomized classical shadows measurement protocol, a 1d or 2d array of size 3 or shape (num_qubits, 3) respectively. Order is ZXY. | np.array([1 / 3, 1 / 3, 1 / 3]) |\n", + "`max_execution_time` | int or None | The maximum execution time on the QPU in seconds. If the runtime exceeds this value, the job will be canceled. If None, a default limit set by Qiskit Runtime will apply. | None |\n", + "`num_randomizations` | int | The number of randomizations to be used for noise learning and gate twirling. | 32 |\n", + "`max_layers_to_learn` | int | The maximum number of unique layers to learn. | 4 |\n", + "`mitigate_readout_error` | bool | Whether to perform readout error mitigation. | True |\n", + "`num_readout_calibration_shots` | int | The number of shots to be used for readout error mitigation. | 10000 |\n", + "`default_precision` | float | The default precision to be used for the PUBs for which the precision is not specified. | 0.05 |\n", + "`default_shots` | int or None | The number of shots to use per PUB. If provided, overrides the specified precision. Otherwise, the number of shots is estimated to provide the precision requested. | None |\n", + "`seed` | int or None | Set the seed for the random number generator for reproducibility. | None |\n", + "`shots_per_randomization` | int | The total number of shots to use per random learning circuit. | 128 |\n", + "`layer_pair_depths` | list[int] | The circuit depths (measured in number of pairs) to use in learning experiments. | [0, 1, 2, 4, 16, 32] |\n", + "`layer_noise_model` | NoiseLearnerResult, Sequence[LayerError], or None | The precomputed noise learner result from a previously executed run. | None |\n", + "`private` | bool | Whether the QPU jobs should be private. Setting it to `True` will prevent subsequent downloads of the experiment data and is recommended for confidential jobs. | False |\n", + "`tem_enforce_linear_circuit` | bool | Whether to enforce the circuit to be in linear topology. | False |\n", + "\n", + "#### Precision\n", + "\n", + "The precision of the results can be requested in three ways. The precision can be passed in the PUB, and it will apply to that PUB only. Otherwise, a `default_precision` can be passed in the options as specified above. Finally, for advanced use, the specific number of shots per PUB can be passed in the options with `default_shots`, and it will override any other precision option.\n", + "\n", + "If a `default_precision` or a per-PUB value is passed, the number of shots is estimated in order to achieve the desired precision. This is done based on the chosen QPU parameters and error rates. It does this by:\n", + "\n", + "- Calculating the error per layered gate (EPLG), which quantifies the noise introduced by layers of two-qubit gates. If backend properties are available, it extracts the relevant fidelity; otherwise, it uses a default value.\n", + "- Counting the number of two-qubit gates in the circuit, as these are typically the main contributors to noise.\n", + "- Computing a noise prefactor based on the number of two-qubit gates and the EPLG.\n", + "- Using the requested precision, it estimates the required number of shots by scaling with the noise prefactor and the inverse of the square of the precision.\n", + "\n", + "This approach ensures that the number of shots is sufficient to achieve the desired precision, taking into account both the circuit structure and the backend's noise characteristics." + ] + }, + { + "cell_type": "markdown", + "id": "7a04364c", + "metadata": {}, + "source": [ + "## Outputs\n", + "\n", + "A Qiskit [PrimitiveResults](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) containing the TEM-mitigated result. The result for each PUB is returned as a [PubResult](/docs/api/qiskit/qiskit.primitives.PubResult) containing the following fields:\n", + "\n", + "\n", + "Name |Type | Description\n", + "-- | -- | --\n", + "data | DataBin | A Qiskit [DataBin](/docs/api/qiskit/qiskit.primitives.DataBin) containing the TEM mitigated observable and its standard error. The DataBin has the following fields:
  • `evs`: The TEM-mitigated observable value.
  • `stds`: The standard error of the TEM-mitigated observable.
\n", + "metadata | dict | A dictionary containing additional results. The dictionary contains the following keys:
  • `\"evs_non_mitigated\"`: The observable value without error mitigation.
  • `\"stds_non_mitigated\"`: The standard error of the result without error mitigation.
  • `\"evs_mitigated_no_readout_mitigation\"`: The observable value with error mitigation but without readout error mitigation.
  • `\"stds_mitigated_no_readout_mitigation\"`: The standard error of the result with error mitigation but without readout error mitigation.
  • `\"evs_non_mitigated_with_readout_mitigation\"`: The observable value without error mitigation but with readout error mitigation.
  • `\"stds_non_mitigated_with_readout_mitigation\"`: The standard error of the result without error mitigation but with readout error mitigation.
  • `\"resource_usage\"`: A dictionary containing the time-resources used by the TEM.
" + ] + }, + { + "cell_type": "markdown", + "id": "fd045ee6", + "metadata": {}, + "source": [ + "## Fetching error messages\n", + "\n", + "If your workload status is ERROR, use job.result() to fetch the error message as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "0433171c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray()), metadata={'evs_non_mitigated': array([0.06979321]), 'stds_non_mitigated': array([0.05510763]), 'evs_mitigated_no_readout_mitigation': array([0.07031416]), 'stds_mitigated_no_readout_mitigation': array([0.05566318]), 'evs_non_mitigated_with_readout_mitigation': array([0.08313754]), 'stds_non_mitigated_with_readout_mitigation': array([0.05702442])})], metadata={'resource_usage': {'RUNNING: OPTIMIZING_FOR_HARDWARE': {'CPU_TIME': 0.966265}, 'RUNNING: WAITING_FOR_QPU': {'CPU_TIME': 11.436938}, 'RUNNING: POST_PROCESSING': {'CPU_TIME': 10.379288999999998}, 'RUNNING: EXECUTING_QPU': {'QPU_TIME': 171.0}}})\n" + ] + } + ], + "source": [ + "print(job.result())" + ] + }, + { + "cell_type": "markdown", + "id": "e9ec2e67", + "metadata": {}, + "source": [ + "## Get support\n", + "\n", + "Reach out to [qiskit_ibm@algorithmiq.fi](mailto:qiskit_ibm@algorithmiq.fi)\n", + "\n", + "Be sure to include the following information:\n", + "- Qiskit Function Job ID (`qiskit-ibm-catalog`), `job.job_id`\n", + "- A detailed description of the issue\n", + "- Any relevant error messages or codes\n", + "- Steps to reproduce the issue" + ] + }, + { + "cell_type": "markdown", + "id": "5a6a25c8", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + "\n", + "- [Request access to Algorithmiq Tensor-network error mitigation](https://quantum.ibm.com/functions?id=4b1b9d76-c18b-4788-b70b-15125111fbe6)\n", + "\n", + "" + ] + } + ], + "metadata": { + "description": "Introduction to TEM, a Qiskit Function by Algorithmiq, to compute estimations with software post-processing error mitigation using tensor networks.", + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + }, + "title": "Tensor-network error mitigation (TEM) - A Qiskit Function by Algorithmiq" + }, + "nbformat": 4, + "nbformat_minor": 5 } From 0819de346770a94895523e0be17db167c973e13b Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 12 Feb 2026 10:06:18 -0500 Subject: [PATCH 10/11] add version info cell --- docs/guides/algorithmiq-tem.ipynb | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index f2ee0d193e6..515f2166068 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -13,6 +13,16 @@ "{/* cspell:ignore POVM, mathbf, Filippov, Lindblad, Leahy, Rossi, García, Pérez, Minev, Kandala, Temme, informationally */}" ] }, + { + "cell_type": "markdown", + "id": "d606b64e", + "metadata": { + "tags": [ + "version-info" + ] + }, + "source": [] + }, { "cell_type": "markdown", "id": "dde95705", From 14a57bffd70961bc6c7c0f2cbde168b7a43e477d Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 12 Feb 2026 10:08:18 -0500 Subject: [PATCH 11/11] add to cspell --- docs/tutorials/algorithmiq-tem.ipynb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tutorials/algorithmiq-tem.ipynb b/docs/tutorials/algorithmiq-tem.ipynb index 695bd180449..4466ae97c6a 100644 --- a/docs/tutorials/algorithmiq-tem.ipynb +++ b/docs/tutorials/algorithmiq-tem.ipynb @@ -11,6 +11,8 @@ "---\n", "# Simulate a kicked Ising model with the TEM function\n", "\n", + "{/* cspell:ignore Floquet, linestyles */}\n", + "\n", "Algorithmiq's Tensor-network Error Mitigation (TEM) method is a hybrid quantum-classical algorithm designed for performing noise mitigation entirely at the classical post-processing stage. With TEM, the user can compute the expectation values of observables mitigating the inevitable noise-induced errors that occur on quantum hardware with increased accuracy and cost efficiency, making it a highly attractive option for quantum researchers and industry practitioners alike.\n", "\n", "In this tutorial, we will showcase how TEM allows to obtain meaningful results for the dynamics of a quantum system, which would be inaccessible without error mitigation and require substantially more quantum resources if other error mitigation methods such as PEC and ZNE are used."