{ "cells": [ { "cell_type": "markdown", "id": "fed083e4-9be1-480c-82e9-4bfd7dbccf1f", "metadata": {}, "source": [ "# Adjoint Plugin: 2 Checking Gradients\n", "\n", "In this notebook, we will show how to use the adjoint plugin for `DiffractionMonitor` outputs and also check the gradient values against gradients obtained using transfer matrix method (TMM) to validate their accuracy for a multilayer slab problem." ] }, { "cell_type": "code", "execution_count": 1, "id": "51963da1", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
[14:48:02] INFO Using client version: 1.9.0rc1 __init__.py:121\n", "\n" ], "text/plain": [ "\u001b[2;36m[14:48:02]\u001b[0m\u001b[2;36m \u001b[0m\u001b[34mINFO \u001b[0m Using client version: \u001b[1;36m1.9\u001b[0m.0rc1 \u001b]8;id=396746;file:///Users/twhughes/.pyenv/versions/3.10.9/lib/python3.10/site-packages/tidy3d/__init__.py\u001b\\\u001b[2m__init__.py\u001b[0m\u001b]8;;\u001b\\\u001b[2m:\u001b[0m\u001b]8;id=281179;file:///Users/twhughes/.pyenv/versions/3.10.9/lib/python3.10/site-packages/tidy3d/__init__.py#121\u001b\\\u001b[2m121\u001b[0m\u001b]8;;\u001b\\\n" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import numpy as np\n", "import jax.numpy as jnp\n", "import jax\n", "import tmm\n", "import matplotlib.pyplot as plt\n", "from typing import Tuple, List\n", "\n", "import tidy3d as td\n", "from tidy3d.web import run as run_sim\n", "from tidy3d.plugins.adjoint import JaxSimulation, JaxBox, JaxMedium, JaxStructure, JaxSimulationData\n", "from tidy3d.plugins.adjoint.web import run as run_adjoint" ] }, { "cell_type": "markdown", "id": "b33d0892-62d3-4329-810f-f29ce10056b4", "metadata": {}, "source": [ "First, we define some global parameters describing the transmission through a multilayer slab with some spacing between each slab.\n", "\n", "The layout is diagrammed below.\n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "ccbd2c6a-419d-4570-8f91-f57ad5bad813", "metadata": {}, "outputs": [], "source": [ "# frequency we want to simulate at\n", "freq0 = 2.0e14\n", "k0 = 2 * np.pi * freq0 / td.C_0\n", "freqs = [freq0]\n", "wavelength = td.C_0 / freq0\n", "\n", "# background permittivity\n", "bck_eps = 1.3**2\n", "\n", "# space between each slab\n", "spc = 0.1\n", "\n", "# slab permittivities and thicknesses\n", "slab_eps0 = [2.**2, 1.8**2, 1.5**2, 1.9**2]\n", "slab_ds0 = [0.5, 0.25, 0.5, 0.5]\n", "\n", "# incidence angle\n", "theta = np.pi/8\n", "\n", "# resolution\n", "dl = 0.01" ] }, { "cell_type": "markdown", "id": "48dd37b0-ba97-45cd-a861-53ea6ae3fa74", "metadata": {}, "source": [ "## Transfer Matrix Method (Ground Truth)\n", "\n", "Next we use the `tmm` package to write a function to return the transmission `T` of `p` polarized light given a set of slab permittivities and thicknesses. We'll also write a function to compute the numerical gradient using TMM and will take these to be our \"ground truths\" when evaluating the accuracy of our values obtained through FDTD and the adjoint plugin.\n", "\n", "### Transmission Calculation with TMM\n", "\n", "First, we write a function to compute transmission." ] }, { "cell_type": "code", "execution_count": 3, "id": "cc4f6e91-6a53-476e-b4c6-e76e50246426", "metadata": {}, "outputs": [], "source": [ "def compute_T_tmm(slab_eps=slab_eps0, slab_ds=slab_ds0) -> float:\n", " \"\"\"Get transmission as a function of slab permittivities and thicknesses.\"\"\"\n", "\n", " # construct lists of permittivities and thicknesses including spaces between\n", " new_slab_eps = []\n", " new_slab_ds = []\n", " for eps, d in zip(slab_eps, slab_ds):\n", " new_slab_eps.append(eps)\n", " new_slab_eps.append(bck_eps)\n", " new_slab_ds.append(d)\n", " new_slab_ds.append(spc)\n", " slab_eps = new_slab_eps[:-1]\n", " slab_ds = new_slab_ds[:-1]\n", "\n", " # add the input and output spaces to the lists\n", " eps_list = [bck_eps] + slab_eps + [bck_eps]\n", " n_list = np.sqrt(eps_list) \n", " d_list = [np.inf] + slab_ds + [np.inf]\n", " \n", " # compute transmission with TMM\n", " return tmm.coh_tmm(\"p\", n_list, d_list, theta, wavelength)[\"T\"]" ] }, { "cell_type": "markdown", "id": "c6c0da6b-2d2f-4be5-80e6-c84afd8d1a23", "metadata": {}, "source": [ "We run this function with our starting parameters and see that we get a transmission of about 98% for the set of input parameters." ] }, { "cell_type": "code", "execution_count": 4, "id": "c1743e54-d7f3-468a-8ac4-d42d4c2bc8dc", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "T (tmm) = 0.997\n" ] } ], "source": [ "T_tmm = compute_T_tmm(slab_eps=slab_eps0, slab_ds=slab_ds0)\n", "print(f\"T (tmm) = {T_tmm:.3f}\")" ] }, { "cell_type": "markdown", "id": "452db467-f486-468d-8ec9-b9e669755c92", "metadata": {}, "source": [ "### Numerical Gradient with TMM\n", "\n", "Next, we will use our `compute_T_tmm()` function to compute the \"numerical\" gradient to use as comparison against our adjoint results with FDTD.\n", "\n", "The derivative of a function $f(x)$ w.r.t. $x$ can be approximated using finite differences as\n", "\n", "$$ \\frac{df}{dx}(x) \\approx \\frac{f(x+\\Delta) - f(x-\\Delta)}{2\\Delta}$$\n", "\n", "with a small step $\\Delta$.\n", "\n", "To compute the gradient of our transmission with respect to each of the slab thicknesses and permittivities, we need to repeat this step for each of the values. Luckily, since TMM is very fast, we can compute these quantities quite quickly compared to if we were using FDTD.\n", "\n", "Here we write a function to return this gradient." ] }, { "cell_type": "code", "execution_count": 5, "id": "15d5bae1-6fc7-41c8-8772-2e80505be17d", "metadata": {}, "outputs": [], "source": [ "def compute_grad_tmm(slab_eps=slab_eps0, slab_ds=slab_ds0) -> Tuple[List[float], List[float]]:\n", " \"\"\"Compute numerical gradient of transmission w.r.t. each of the slab permittivities and thicknesses using TMM.\"\"\"\n", "\n", " delta = 1e-4\n", "\n", " # set up containers to store gradient and perturbed arguments\n", " num_slabs = len(slab_eps)\n", " grad_tmm = np.zeros((2, num_slabs), dtype=float)\n", " args = np.stack((slab_eps, slab_ds), axis=0)\n", "\n", " # loop through slab index and argument index (eps, d)\n", " for arg_index in range(2):\n", " for slab_index in range(num_slabs):\n", " grad = 0.0\n", " \n", " # perturb the argument by delta in each + and - direction\n", " for pm in (-1, +1):\n", " args_num = args.copy()\n", " args_num[arg_index][slab_index] += delta * pm\n", " \n", " # compute argument perturbed T and add to finite difference gradient contribution\n", " T_tmm = compute_T_tmm(slab_eps=args_num[0], slab_ds=args_num[1])\n", " grad += pm * T_tmm / 2 / delta \n", "\n", " grad_tmm[arg_index][slab_index] = grad\n", " grad_eps, grad_ds = grad_tmm\n", " return grad_eps, grad_ds" ] }, { "cell_type": "markdown", "id": "d3c362ca-fb31-4ead-8e7c-fcc24d0faecc", "metadata": {}, "source": [ "Let's run this function and observe the gradients. These will be saved later to compare against our adjoint plugin results." ] }, { "cell_type": "code", "execution_count": 6, "id": "b5d1cc93-6d6e-43a7-8e5f-f1829770f3d5", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "gradient w.r.t. eps (tmm) = [ 0.00353246 0.0255666 0.02079163 -0.00767556]\n", "gradient w.r.t. ds (tmm) = [ 0.12389213 0.27248157 0.14586663 -0.02167071]\n" ] } ], "source": [ "grad_eps_tmm, grad_ds_tmm = compute_grad_tmm()\n", "print(f\"gradient w.r.t. eps (tmm) = {grad_eps_tmm}\")\n", "print(f\"gradient w.r.t. ds (tmm) = {grad_ds_tmm}\")" ] }, { "cell_type": "markdown", "id": "50ca68ae-ca5a-49aa-9969-ac6d43324ea9", "metadata": {}, "source": [ "## FDTD (Using adjoint plugin)\n", "\n", "Next, we will implement the same two functions using Tidy3D's adjoint plugin.\n", "\n", "### Transmission Calculation with FDTD\n", "\n", "We first write a function to compute the transmission of a multilayer slab using Tidy3D.\n", "\n", "As discussed in the previous adjoint tutorial notebook, we need to use `jax`-compatible components from the tidy3d subclass for any structures that may depend on the parameters. In this case, this means that the slabs must be `JaxStructures` containing `JaxBox` and `JaxMedium` and must be added to `JaxSimulation.input_structures`.\n", "\n", "We use a `DiffractionMonitor` to measure our transmission amplitudes. As the data corresponding to this monitor will be used in the differentiable function return value, we must add it to `JaxSimulation.output_monitors`.\n", "\n", "Below, we break up the transmission calculation into a few functions to make it easier to read and re-use later." ] }, { "cell_type": "code", "execution_count": 7, "id": "4d12f133-a8d8-4e59-938f-fca4d2e2fa0b", "metadata": {}, "outputs": [], "source": [ "def make_sim(slab_eps=slab_eps0, slab_ds=slab_ds0) -> JaxSimulation:\n", " \"\"\"Create a JaxSimulation given the slab permittivities and thicknesses.\"\"\"\n", "\n", " # frequency setup\n", " wavelength = td.C_0 / freq0\n", " fwidth = freq0 / 10.0\n", " freqs = [freq0]\n", "\n", " # geometry setup\n", " bck_medium = td.Medium(permittivity=bck_eps)\n", "\n", " space_above = 2\n", " space_below = 2\n", "\n", " length_x = 0.1\n", " length_y = 0.1\n", " length_z = space_below + sum(slab_ds0) + space_above + (len(slab_ds0) - 1) * spc\n", " sim_size = (length_x, length_y, length_z)\n", "\n", " # make structures\n", " slabs = []\n", " z_start = -length_z/2 + space_below\n", " for (d, eps) in zip(slab_ds, slab_eps):\n", " slab = JaxStructure(\n", " geometry=JaxBox(center=[0, 0, z_start + d / 2], size=[td.inf, td.inf, d]),\n", " medium=JaxMedium(permittivity=eps),\n", " )\n", " slabs.append(slab)\n", " z_start += d + spc\n", "\n", " # source setup\n", " gaussian = td.GaussianPulse(freq0=freq0, fwidth=fwidth)\n", " src_z = -length_z/2 + space_below/2.0\n", "\n", " source = td.PlaneWave(\n", " center=(0, 0, src_z),\n", " size=(td.inf, td.inf, 0),\n", " source_time=gaussian,\n", " direction=\"+\",\n", " angle_theta=theta,\n", " angle_phi=0,\n", " pol_angle=0,\n", " )\n", "\n", " # boundaries\n", " boundary_x = td.Boundary.bloch_from_source(\n", " source=source, domain_size=sim_size[0], axis=0, medium=bck_medium\n", " )\n", " boundary_y = td.Boundary.bloch_from_source(\n", " source=source, domain_size=sim_size[1], axis=1, medium=bck_medium\n", " ) \n", " boundary_spec = td.BoundarySpec(x=boundary_x, y=boundary_y, z=td.Boundary.pml(num_layers=40))\n", "\n", " # monitors\n", " mnt_z = length_z/2 - space_above/2.0\n", " monitor_1 = td.DiffractionMonitor(\n", " center=[0.0, 0.0, mnt_z],\n", " size=[td.inf, td.inf, 0],\n", " freqs=freqs,\n", " name=\"diffraction\",\n", " normal_dir=\"+\",\n", " )\n", "\n", " # make simulation\n", " return JaxSimulation(\n", " size=sim_size,\n", " grid_spec=td.GridSpec.auto(min_steps_per_wvl=100),\n", " input_structures=slabs,\n", " sources=[source],\n", " output_monitors=[monitor_1],\n", " run_time= 10 / fwidth,\n", " boundary_spec=boundary_spec,\n", " medium=bck_medium,\n", " subpixel=True,\n", " shutoff=1e-8,\n", " )" ] }, { "cell_type": "markdown", "id": "9addea1f-4dd8-4e5e-a058-b94638fb2d70", "metadata": {}, "source": [ "Let's generate a simulation and plot it to make sure it looks reasonable." ] }, { "cell_type": "code", "execution_count": 8, "id": "bc0dc456-e742-4299-ae5e-22daa49e3997", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
INFO Auto meshing using wavelength 1.4990 defined from sources. grid_spec.py:510\n", "\n" ], "text/plain": [ "\u001b[2;36m \u001b[0m\u001b[2;36m \u001b[0m\u001b[34mINFO \u001b[0m Auto meshing using wavelength \u001b[1;36m1.4990\u001b[0m defined from sources. \u001b]8;id=324563;file:///Users/twhughes/.pyenv/versions/3.10.9/lib/python3.10/site-packages/tidy3d/components/grid/grid_spec.py\u001b\\\u001b[2mgrid_spec.py\u001b[0m\u001b]8;;\u001b\\\u001b[2m:\u001b[0m\u001b]8;id=646067;file:///Users/twhughes/.pyenv/versions/3.10.9/lib/python3.10/site-packages/tidy3d/components/grid/grid_spec.py#510\u001b\\\u001b[2m510\u001b[0m\u001b]8;;\u001b\\\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "image/png": "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1cLS0lK9+eabuvrqq8tVLUkREREBH48cOVJRUVH+j5ctW6aSkhLdd999ioyMDFiXnJyst99+W5KUkpIiSVqyZImOHj1a4SxlX8EXL16s0tLS6n4K1dpv0aJFat++vbKysrR//37/pX///pKkFStWSJLefPNNlZaWatKkSQGfj1T+saiOzz77THv37tXo0aMVGxvr337VVVcpKyvL//ic7K677gr4+NJLL9U333xT5X3FxcX5/1xQUKD9+/fr0ksv1dGjR7Vx48Yazy59//c2ZMgQ/eEPf5D7/++/9fl8WrhwoYYOHaqEhAT/2vnz52vp0qVVXoYNG+bfp6ioKODM6GSxsbEqKiqqdL6ioiJ5vd4K9y27/uT/nm5tVfdzsmqfFu7bt0/5+fkBh/zKtG7dOuDjf/3rX5Kkdu3aBWz3eDxq06aN//rWrVtr7NixmjFjhubPn69LL71U11xzjW6++WZ/eDfccIN+97vf6b/+6780YcIEXX755frZz36m6667rtz/6Cerzn7//Oc/9dVXXyk9Pb3C29i7d68kacuWLYqMjNR5551XrcejKqd7fCQpKytLf/3rXwO2xcbGlpuxfv36OnToUJX39eWXX+qhhx7SBx98oPz8/IDr8vLyajq637Bhw7Rw4UJ9+OGH6tOnj5YtW6Y9e/bolltuCVjXu3fvGt92XFycSkpKKrzu2LFjAV8wTrd/cXFxhfuWXX/yf0+3tqr7OVmNnnPVRE2GONX06dM1YsQILV68WO+//77uvfde5eTkaM2aNWrWrJni4uK0atUqrVixQm+//bbee+89LVy4UP3799f7778fcMQ8daaq9istLVWnTp00Y8aMCm+jefPmZ/x51abTfY5VOXz4sPr27avk5GRNnTpVmZmZio2N1d/+9jeNHz++RmcCpxo0aJAaNWqkV155RX369NErr7yijIwMDRgwIGDdvn37qvWcKzEx0f88r3HjxvL5fNq7d68aNmzoX1NSUqIDBw6oSZMmld5W48aNtXPnznLbv/vuO0ny79+4ceOA7aeurep+AlT3/NHn87nk5GQ3ZMiQSteVPec69XnZggULnCT3zjvvBGwvLi52KSkp7tprrz3tbX700UdOkps4ceJp10ybNs1JckuXLq36k6lkvyuvvNI1bdo04HlTRR577DEnya1fv77SdR07dqzWc66yV72eeeaZcmvbt28f8Fyq7NXCU02ePNlV9Vf6xhtvOElu5cqVAduff/75cq9e/vSnP63xS/H333+/q1+/vjt48KBLTEx0999/f7k1Z/Kcq+y556mvFpb9v/G///u/lc71wAMPVPhqYdnff9mrhYcPH6701cLbbrut2o9FtZ9zRUZGaujQofrLX/6izz77rKJIK91/wIAB8ng8euqppwLWvvjii8rLy9NVV10lScrPz9eJEycC9u3UqZMiIyP9h+qDBw+Wu/3OnTtLqvhwXqY6+/385z/Xzp079cILL5RbW1RU5H/lc+jQoYqMjNTUqVPLfbU/+fNLSEjQ4cOHTztTmYsuukgNGzbUs88+G/A5vPvuu/rqq6/8j88PVXbEO3nGkpISPfPMM+XWJiQk1Pg08ZZbbtGhQ4d055136siRIxW+gncmz7n69++v1NRUzZkzJ+C25syZo/j4+IDHZ//+/dq4cWPAc/brrrtOPp9Pzz//vH9bcXGxXn75ZfXo0cN/RpKSkqIBAwbolVdeUUFBgX/tvHnzdOTIEV1//fXVfzCqnaH7/ntcGRkZLj4+3t13333uueeec4888ojr0KGD/3tVpztyOffvr6wDBw50Tz/9tLvnnntcVFSU69atmyspKXHOff+VtWnTpu6+++5zzzzzjHvqqadct27dXExMjPv444+dc87993//t+vSpYt76KGH3AsvvOCmTZvmmjZt6po1axbwvbBTVWc/n8/nrrzyShcREeFuvPFGN2vWLDdz5kx31113udTU1IDP6+GHH3aSXK9evdzjjz/uZs2a5YYNG+YmTJjgXzN69GgXERHhfvWrX7k//OEPbvny5c65ir/PVfbY9ejRw82cOdNlZ2e7+Ph416pVq4DvBf6QI9f+/ftd/fr1XcuWLd306dPdjBkzXJcuXdwFF1xQbp7f/va3TpK7//773YIFC9yf//znSm+7TMeOHZ0k1759+2qtr67Zs2c7Se66665zL7zwghs2bJiT5KZNmxawruxxOPV7iNdff73/qPTcc8+5Xr16uejo6HJH8XXr1jmv1xvwExqxsbE1/l5djb+J/K9//csNGzbMpaenO6/X69q0aePGjBlT7pvIFcXl3PcvvWdlZbmYmBjXqFEjN2rUqID/cb755ht32223uczMTBcbG+tSU1Ndv3793LJly/xrli9f7oYMGeKaNGniPB6Pa9KkifvFL37hNm3aVOns1d2vpKTE/eY3v3EdOnRwXq/X1a9f33Xt2tVNmTKl3GnFSy+95Lp06eJf17dv34BT0927d7urrrrKJSUlVeubyAsXLvTfXmpqaqXfRD5VdeJy7vtTqYsvvtjFxcW5Jk2auF/+8pduyZIl5eY5cuSI+8///E9Xr169Kr+JfLKyKB999NFqra+J559/3rVr1855PB6XmZnpnnjiiXKn8KeLq6ioyD3wwAMuIyPDeb1e161bN/fee+9VeD8ffvih69Wrl4uNjXXp6eluzJgxLj8/v0azRjjH7y1E7XryySd1//33a+vWrWrRokWwxwka4kKtcs7pggsuUIMGDfzfE/yxMnspHj8uhYWF+vOf/6wVK1Zow4YNWrx4cbBHCjqOXKgVW7duVevWrVWvXj2NHj1a06ZNC/ZIQUdcgBHeiQwYIS7ACC9ohKDS0lLt2rVLSUlJ1foJe+ecCgoK1KRJk0p/cBl1i7hC0K5du87oB4S3b9+uZs2aGUyEM0FcISgpKUmSdO+996p9+/ZVrv/qq6/01FNP+fdDaCCuEFR2KpiQkOB/D1tlyt6IeCZv0oQdTtBD2KnvDkB4Ia4QVlBQcNp33yL0EVcIi4qK0v79+wksTBFXCEtKSlJMTAyBhSniCmERERFq0KABgYUp4gpxkZGRBBamiCsMEFh4Iq4wQWDhh7jCCIGFF+IKMwQWPogrDJ0aGD/JEZqIK0ydHNjJv7wSoYO4wlhZYGf6e+Nhi7jCXGRkJG81CVHEdRbgrSahibgAI8R1FuC344Um4gpzpaWlvFoYoogrjJWWlurAgQPV+lcaUfeIK0yVhXX8+HFeLQxRxBWGTg4rLS1N0dH8nqFQRFxh5tSwPB5PsEfCaRBXGCGs8EJcYYKwwg9xhQHCCk/EFeIIK3wRVwhzzhFWGCOuEFZQUEBYYYy4QpjP5yOsMEZcISwpKYmwwhhxhTB+8iK8ERdghLgAI8QVwngTZHgjrhBWUFCg0tLSYI+BM0RcIczn8+nAgQMEFqaIK4QlJSXp+PHjBBamiCuERUdHKy0tjcDCFHGFOI/HQ2BhirjCAIGFJ+IKEwQWfogrjBBYeCGuMENg4YO4wtCpgfGTHKGJuMLUyYHx66xDE3GFsbLA+HXWoYm4wpzH4+HXWYco4jIwZ84cnX/++UpOTlZycrJ69uypd999t8a34/P5VFJSUuUFoYm3uhpo1qyZfv3rX+vcc8+Vc06///3vNWTIEK1fv14dOnSo9u2cOHFCx44dq3Idp4WhKcLxUlOdSE1N1WOPPabbb7+93HXFxcUqLi72f5yfn6/mzZvrL3/5i3r16lXlba9evVpXX3218vLylJycXKtz48xx5DLm8/m0aNEiFRYWqmfPnhWuycnJ0ZQpU8ptT05OVmpqapX3QVChiedcRjZs2KDExER5vV7dddddeuONN3TeeedVuDY7O1t5eXn+y/bt2+t4WljgyGWkXbt2+vzzz5WXl6fXXntNw4cP18qVKysMzOv1yuv1BmFKWCIuIx6PR+ecc44kqWvXrlq7dq2efPJJPffcc0GeDHWF08I6UlpaGvCiBc5+HLkMZGdn64orrlCLFi1UUFCgBQsWKDc3V0uWLAn2aKhDxGVg7969GjZsmL777julpKTo/PPP15IlS/STn/wk2KOhDhGXgRdffDHYIyAE8JwLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMBId7AFQieMFUsmh6q1DyCGuULZnhbRtZzXWbbKfBTXGaaGBnJwcdevWTUlJSWrYsKGGDh2qr7/+OthjoY4Rl4GVK1dqzJgxWrNmjZYuXarjx49r4MCBKiwsDPZoqEOcFhp47733Aj6eO3euGjZsqHXr1qlPnz5Bmgp1jbjqQF5eniQpNTW1wuuLi4tVXFzs/zg/P//7PzTqJ7XoVfUd/Gu1pOk/dEzUMuIyVlpaqvvuu0+9e/dWx44dK1yTk5OjKVOmlL8iJkny1K/6TmKSfuCUsMBzLmNjxozRF198oT/+8Y+nXZOdna28vDz/Zfv27XU4Iaxw5DJ0991366233tKqVavUrFmz067zer3yer11OBnqAnEZcM7pnnvu0RtvvKHc3Fy1bt062CMhCIjLwJgxY7RgwQItXrxYSUlJ2r17tyQpJSVFcXFxQZ4OdYXnXAbmzJmjvLw8XXbZZWrcuLH/snDhwmCPhjrEkcuAcy7YIyAEcOQCjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEBRghLsAIcQFGiAswQlyAEeICjBAXYIS4ACPEZWDVqlW6+uqr1aRJE0VEROjNN98M9kgIAuIyUFhYqAsuuECzZ88O9igIouhgD3A2uuKKK3TFFVf84Nv58sZsxcSlVb2uaP8Pvi/UPuIKAcXFxSouLvZ/nJ+fH8RpUFs4LQwBOTk5SklJ8V+aN28e7JFQC4grBGRnZysvL89/2b59e7BHQi3gtDAEeL1eeb3eYI+BWsaRCzDCkcvAkSNHtHnzZv/H3377rT7//HOlpqaqRYsWQZwMdYm4DHz22Wfq16+f/+OxY8dKkoYPH665c+cGaSrUNeIycNlll8k5F+wxEGQ85wKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaigz0ATq/DH3PUs0+fKtcdX7VK6tu3DiZCTXDkAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEH38KYdOeXKUXX99f5brdO/5RB9OgpjhyAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIZmz56tVq1aKTY2Vj169NCnn34a7JFQh4jLyMKFCzV27FhNnjxZf/vb33TBBRdo0KBB2rt3b7BHQx05q+Pq37+/pkyZUm77oUOH1L9/f9P7njFjhkaOHKlbb71V5513np599lnFx8frpZdeMr1fhI6zOq7c3Fw9/fTTGjp0qAoLC/3bS0pKtHLlSrP7LSkp0bp16zRgwAD/tsjISA0YMEAff/xxufXFxcXKz88PuCD8ndVxSdKyZcu0e/duXXzxxdq6dWud3Of+/fvl8/nUqFGjgO2NGjXS7t27y63PyclRSkqK/9K8efM6mRO2zvq4GjdurJUrV6pTp07q1q2bcnNzgz1SOdnZ2crLy/Nftm/fHuyRUAuigz2ApYiICEmS1+vVggUL9D//8z8aPHiwxo8fb3q/aWlpioqK0p49ewK279mzRxkZGeXWe71eeb1e05lQ987qI5dzLuDjhx56SPPnz9f06dNN79fj8ahr165avny5f1tpaamWL1+unj17mt43QsdZfeT69ttvlZ6eHrDt2muvVVZWlj777DPT+x47dqyGDx+uiy66SN27d9fMmTNVWFioW2+91fR+ETrO6rhatmxZ4fYOHTqoQ4cOpvd9ww03aN++fZo0aZJ2796tzp0767333iv3IgfOXmd1XMF299136+677w72GAiSs/o5FxBMHLlC2MT/7qM+ffpUuW7VqjS9/6c6GAg1wpELMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBF+/CmEbZ7xqlL+uK7qdbu21ME0qCmOXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghN8VH8LOGftzXdCnT5Xr8latkhbProOJUBMcuQAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUY4cefQtj0d9bpD5uPV7lu16a/18E0qCmOXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaIq5ZNmzZNvXr1Unx8vOrVqxfscRBExFXLSkpKdP3112vUqFHBHgVBFh3sAc42U6ZMkSTNnTs3uIMg6IgrBBQXF6u4uNj/cX5+fhCnQW3htDAE5OTkKCUlxX9p3rx5sEdCLSCuapgwYYIiIiIqvWzcuPGMbz87O1t5eXn+y/bt22txegQLp4XVMG7cOI0YMaLSNW3atDnj2/d6vfJ6vWe8P0ITcVVDenq60tPT6/x+x13ZVX369Kly3apVMfrzb+pgINQIcdWybdu26eDBg9q2bZt8Pp8+//xzSdI555yjxMTE4A6HOkVctWzSpEn6/e9/7/+4S5cukqQVK1bosssuC9JUCAZe0Khlc+fOlXOu3IWwfnyICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzBCXIAR4gKMEBdghLhq2datW3X77berdevWiouLU2ZmpiZPnqySkpJgj4Y6Fh3sAc42GzduVGlpqZ577jmdc845+uKLLzRy5EgVFhbq8ccfD/Z4qEPEVcsGDx6swYMH+z9u06aNvv76a82ZM4e4fmSIqw7k5eUpNTX1tNcXFxeruLjY/3F+fr4kqdBXqPwT+f7tJ0pP6Jr516h9entNHzzdv73QV2gwNX4o4jK2efNmzZo1q9KjVk5OjqZMmVJu+7oj63T00FH5Xl2tiNRE5UZv0Rf7vtCOwh1adniZf90/jvzDZHb8MLygUU0TJkxQREREpZeNGzcG7LNz504NHjxY119/vUaOHHna287OzlZeXp7/sn37dv917rtD8v3lMx2f9Y4yn1qnlvtidF6T88w+T9QejlzVNG7cOI0YMaLSNW3atPH/edeuXerXr5969eql559/vtL9vF6vvF5vhddFNklV9B0DdOJ3y5Vw5Lg676+nK3sPr/H8qHvEVU3p6elKT0+v1tqdO3eqX79+6tq1q15++WVFRv6wE4SoPh0U2bu9UguO6urk+B98e6gbxFXLdu7cqcsuu0wtW7bU448/rn379vmvy8jIqNFtdU3sqt71ev97Q4OK18Ulxp3JqDBGXLVs6dKl2rx5szZv3qxmzZoFXOecq9FtJUQlKDk6uVrrEHo4v6hlI0aMkHOuwgt+XIgLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQl4FrrrlGLVq0UGxsrBo3bqxbbrlFu3btCvZYqGPEZaBfv3569dVX9fXXX+v111/Xli1bdN111wV7LNSx6GAPcDa6//77/X9u2bKlJkyYoKFDh+r48eOKiYkJ4mSoS8Rl7ODBg5o/f7569ep12rCKi4tVXFzs/zg/P7+uxoMhTguNjB8/XgkJCWrQoIG2bdumxYsXn3ZtTk6OUlJS/JfmzZvX4aSwQlzVNGHCBEVERFR62bhxo3/9gw8+qPXr1+v9999XVFSUhg0bJudchbednZ2tvLw8/2X79u119WnBEKeF1TRu3DiNGDGi0jVt2rTx/zktLU1paWlq27at2rdvr+bNm2vNmjXq2bNnuf28Xq+8Xm+57fn5+Tp48GCVs3EaGZqIq5rS09OVnp5+RvuWlpZKUsDzqupYsWKFdu7cWeW6TZs2ndFcsEVcteyTTz7R2rVrdckll6h+/frasmWLHn74YWVmZlZ41KpMdHS0YmNjK13jnNOxY8d+yMgwwnOuWhYfH68//elPuvzyy9WuXTvdfvvtOv/887Vy5coKT/0qExUVJY/Hc9pLdHS08vPz/UdGhBaOXLWsU6dO+uCDD8zvp7S0VAcOHNDx48eVlJRkfn+oOY5cYejksNLS0hQdzdfIUERcYebUsDweT7BHwmkQVxghrPBCXGGCsMIPcYUBwgpPxBXiCCt8EVcIc84RVhgjrhBWUFBAWGGMuEKYz+cjrDBGXCEsKSmJsMIYcYUwfvIivBEXYIS4ACPEFcJO92sBEB6IK4QVFBTwXq0wRlwhzOfz6cCBAwQWpogrhCUlJen48eMEFqaIK4RFR0crLS2NwMIUcYU4j8dDYGGKuMIAgYUn4goTBBZ+iCuMEFh4Ia4wQ2Dhg7jC0KmB8ZMcoYm4wtTJgRUUFAR7HFSAuMJYWWA+ny/Yo6ACxBXmPB4Pv846RBHXWYA3VYYm4gKMEBdghLjOAkVFRcEeARUgrjBXUFBAXCGKuMJYQUGB8vPzFRcXF+xRUAHiClNlYSUnJxNXiCKuMHRyWHyPK3QRV5ghrPBBXGGEsMILcYUJwgo/xBUGCCs8EVeII6zwRVwhrKioiLDCGHGFsKKiIsIKY8QVwuLi4ggrjBFXCOMnL8IbcQFGiAswwvvDQ1DZr0orLCxUXl5elesLCwsD9kNoiHD8jYScb775RpmZmTXeb8uWLWrTpo3BRDgTHLlCUGpqqiRp27ZtSklJ8W/Pz89X8+bNtX37diUnJ/u35+XlqUWLFv79EBqIKwRFRn7/VDglJSUgojLJyckVbi/bD6GBvw3ACHEBRogrBHm9Xk2ePFler/cHbUdw8WohYIQjF2CEuAAjxAUYIS7ACHEFycGDB3XTTTcpNjZWkZGRio6OVrdu3fTpp59q9uzZatWqlWJjY9WjRw99+umnkqRjx45p0KBBioqKUkREhFJSUjR//nwtWrRIWVlZio2NVURERLlL9+7dy20bPHhwkB+BHwGHoBg8eLBr0aKFi4mJcRMmTHAtWrRwmZmZLj4+3nk8HvfSSy+5L7/80o0cOdLVq1fP7dmzxw0dOtRJcnfccYdbtGiRa9q0qZPkoqKi3G9/+1v3j3/8w0lyktyvfvUrt3z5cjdo0CCXkJDgBg4c6L777jv/5eDBg8F+CM56xBUEZRF06NDBjRkzxjnn3LvvvuskuZiYGHfxxRf71/p8PtekSRM3efJkFxER4S688EL/dV999ZWT5Bo1auScc660tNRJcmlpae7OO+90zjl3+PBhFxkZ6S666KI6/AzhnHOcFgbBxx9/rJSUFG3cuFEDBgyQJA0YMECRkZE6fvx4wL9xHBkZqQEDBmjp0qVyzum6667zX5eVlaWIiAj/v3Ly7bffSpKOHj2q3/3ud+revbtef/11paen6+9//7saNmyodu3aadSoUTpw4EAdfsY/TsQVBLt371aDBg3k8/nUqFEjSd//06v16tWTJB05ciRgfaNGjbRnzx5JUqtWrQKuc87p2LFj/tuVpJtvvlkpKSm69tprNXr0aMXGxqpbt25avny5fvOb32jlypW64oor+IfKjRFXLZowYUKFLyicfNm4caP5HK1atVJ0dLTGjx+vX/7yl9q7d6+aNm2qTp06aejQoXrrrbe0du1a5ebmms/yY8ZbTmrRuHHjNGLEiErXtGnTRhkZGTpw4ICioqL8R6QTJ07o8OHDkqTExMSAffbs2aNGjRppy5Yt2rp1a8B1ERERio2NlSRlZGRIkrZu3er/c48ePVRUVKT09PSAGdLS0rR582ZdfvnlZ/rpogocuWpRenq6srKyKr14PB717NlTeXl5ysrK0vLlyyVJH3zwgUpLSxUTE6Po6H9/zSstLdXy5cv1k5/8RBEREXr99df913399ddyzvl/S1Tr1q2VkZGhJUuWqGfPnpKkNWvWSJIuueQS/347duzQgQMH1LhxY/PH5EctyC+o/GgNHjzYtWrVynk8Hjdx4kTXsmVL/0vxXq/XPfHEEy4hIcGde+65rl69em737t3+l+K7dOniXnvtNdesWTMnyUVHR7vHH3/cPfPMMy4rK8tJcg8//LCbOHGii4yMdF6v1+Xm5rpvv/3WLVu2zF144YXu3HPPdceOHQv2w3BWI64gOXDggPvFL37hPB6Pi4iI8L9cvmbNGjdr1izXpEkTJ8mlpKS4NWvWOOecKyoqcvXr1/d/LyspKcm98sor7tVXX3Vt27Z10dHRLjY21kVFRbmIiAgXERHh2rZt63r37u3S09NdTEyMa9mypRs5cqTbvXt3kB+Bsx9vOQGM8JwLMEJcgBHiAowQF2CEuAAjxAUYIS7ACHEBRogLMEJcgBHiAowQV4jbt2+fMjIy9Oijj/q3rV69Wh6Px/92FYQmfnA3DLzzzjsaOnSoVq9erXbt2qlz584aMmSIZsyYEezRUAniChNjxozRsmXLdNFFF2nDhg1au3Yt/6pJiCOuMFFUVKSOHTtq+/btWrdunTp16hTskVAFnnOFiS1btmjXrl0qLS0t93s0EJo4coWBkpISde/eXZ07d1a7du00c+ZMbdiwQQ0bNgz2aKgEcYWBBx98UK+99pr+7//+T4mJierbt69SUlL01ltvBXs0VILTwhCXm5urmTNnat68eUpOTlZkZKTmzZunDz/8UHPmzAn2eKgERy7ACEcuwAhxAUaICzBCXIAR4gKMEBdghLgAI8QFGCEuwAhxAUaICzDy/wCJ3epwyqF+zQAAAABJRU5ErkJggg==\n", "text/plain": [ "