From bfe080ddee154c63d3f6a75797f9698da0928837 Mon Sep 17 00:00:00 2001
From: dnorthcote <42978178+dnorthcote@users.noreply.github.com>
Date: Fri, 19 May 2023 16:02:36 +0100
Subject: [PATCH 01/23] Update README.md for ZCU208 and ZCU216
---
README.md | 13 +++++++++----
1 file changed, 9 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index 8f22f2e..ad8799f 100644
--- a/README.md
+++ b/README.md
@@ -14,11 +14,16 @@ To begin installing the Jupyter Notebooks on your system, click-on one of the op
* [Notebook Installation](#notebook-installation)
## RFSoC Setup
-This repository is currently only compatible with [RFSoC-PYNQ v2.7](https://github.com/Xilinx/PYNQ/releases). Follow the steps below to setup the RFSoC platform for installing the companion Jupyter Notebooks.
+This repository is currently only compatible with [RFSoC-PYNQ v2.7](https://github.com/Xilinx/PYNQ/releases) and greater. Follow the steps below to setup the RFSoC platform for installing the companion Jupyter Notebooks.
-1. Currently, there are only 3 compatible RFSoC platforms. These are the [RFSoC4x2](http://rfsoc-pynq.io/), [ZCU111](https://www.xilinx.com/products/boards-and-kits/zcu111.html), and [RFSoC2x2](http://rfsoc-pynq.io/).
+1. Currently, there are 5 compatible RFSoC platforms. These are listed as follows:
+* [ZCU208](https://www.xilinx.com/products/boards-and-kits/zcu208.html),
+* [ZCU216](https://www.xilinx.com/products/boards-and-kits/zcu216.html),
+* [ZCU111](https://www.xilinx.com/products/boards-and-kits/zcu111.html),
+* [RFSoC4x2](http://rfsoc-pynq.io/),
+* [RFSoC2x2](http://rfsoc-pynq.io/).
-2. Install PYNQ v2.7 onto an SD card and plug it in to your RFSoC platform.
+2. Install PYNQ v2.7 or greater onto an SD card and plug it in to your RFSoC platform.
3. Your RFSoC platform requires internet access to install the companion Jupyter Notebooks. Follow the instructions [here](https://pynq.readthedocs.io/en/v3.0.0/getting_started/network_connection.html?highlight=internet) that assist with internet access.
@@ -42,7 +47,7 @@ The companion Jupyter Notebooks can be installed on a computer or RFSoC platform
3. Install the RFSoC Book notebooks through PIP by executing the following command in the terminal.
```sh
-pip install https://github.com/strath-sdr/RFSoC-Book/archive/v1.0.1.tar.gz
+pip install https://github.com/strath-sdr/RFSoC-Book/archive/v1.1.0.tar.gz
```
4. Run the following command in the Jupyter terminal window to install the notebooks and dependencies.
From b442435bb7f5c9b4adb559d4ef15aa0a25f75e6a Mon Sep 17 00:00:00 2001
From: dnorthcote <42978178+dnorthcote@users.noreply.github.com>
Date: Fri, 19 May 2023 16:02:59 +0100
Subject: [PATCH 02/23] Modify __main__.py to include ZCU2xx and notebook
checks
---
rfsoc_book/__main__.py | 29 ++++++++++++++++++-----------
1 file changed, 18 insertions(+), 11 deletions(-)
diff --git a/rfsoc_book/__main__.py b/rfsoc_book/__main__.py
index 8ed337c..1ccae66 100644
--- a/rfsoc_book/__main__.py
+++ b/rfsoc_book/__main__.py
@@ -7,7 +7,7 @@
# variables
package_name = 'rfsoc_book'
-board_list = ['ZCU111', 'RFSoC2x2', 'RFSoC4x2']
+board_list = ['ZCU111', 'RFSoC2x2', 'RFSoC4x2', 'ZCU208', 'ZCU216']
# dialogue
help_dialogue = ''.join(['\r\nThe rfsoc_book module accepts one of the following arguments:', '\r\n',
@@ -43,6 +43,7 @@ def install_notebooks():
f.write(dst)
def install_packages():
+ board = os.environ['BOARD']
dst = os.path.abspath(os.path.join(os.path.realpath(__file__), '..', 'package_list.txt'))
if not os.path.exists(dst):
raise RuntimeError(error_dialogue)
@@ -50,11 +51,14 @@ def install_packages():
package_list = f.readlines()
for package in package_list:
package_name, package_src = package.split(' ')
- print(''.join(['***** Installing ', package_name, ' *****\r\n']))
- status = subprocess.check_call(["pip3", "install", package_src])
- print('\r\n') # Pip is not playing nice
- if status != 0:
- raise RuntimeError(''.join(['Package ', package_src, ' failed to install.\r\n']))
+ if package_name == 'rfsoc_sam' and board == 'ZCU216':
+ pass
+ else:
+ print(''.join(['***** Installing ', package_name, ' *****\r\n']))
+ status = subprocess.check_call(["pip3", "install", package_src])
+ print('\r\n') # Pip is not playing nice
+ if status != 0:
+ raise RuntimeError(''.join(['Package ', package_src, ' failed to install.\r\n']))
def uninstall_notebooks():
print('\r\n***** Uninstalling Notebooks *****\r\n')
@@ -98,11 +102,14 @@ def unpackage_notebooks():
for file in os.listdir(notebookdir):
file_split = file.split('_')
if board in file_split:
- file_split.remove(board)
- file_name = '_'.join(file_split)
- src = os.path.join(notebookdir, file)
- dst = os.path.join(notebookdir, '..', file_name)
- shutil.copy(src, dst)
+ unpack_board = board
+ else:
+ unpack_board = 'RFSoC4x2'
+ file_split.remove(unpack_board)
+ file_name = '_'.join(file_split)
+ src = os.path.join(notebookdir, file)
+ dst = os.path.join(notebookdir, '..', file_name)
+ shutil.copy(src, dst)
def clean_notebooks():
print('\r\n***** Cleaning Notebooks *****\r\n')
From e8b6850151b9cde6c8eb5a8dfdb4e4789e17fc90 Mon Sep 17 00:00:00 2001
From: dnorthcote <42978178+dnorthcote@users.noreply.github.com>
Date: Fri, 19 May 2023 16:04:12 +0100
Subject: [PATCH 03/23] Update Set A for New Boards
Remove RFSoC2x2 notebook (which will now default to the RFSoC4x2 notebook)
Add ZCU216 notebook as this and ZCU111 require QPSK overlay
---
...pynb => ZCU216_03_pynq_introduction.ipynb} | 30 +++++++++++--------
1 file changed, 17 insertions(+), 13 deletions(-)
rename rfsoc_book/notebooks/notebook_A/boards/{RFSoC2x2_03_pynq_introduction.ipynb => ZCU216_03_pynq_introduction.ipynb} (89%)
diff --git a/rfsoc_book/notebooks/notebook_A/boards/RFSoC2x2_03_pynq_introduction.ipynb b/rfsoc_book/notebooks/notebook_A/boards/ZCU216_03_pynq_introduction.ipynb
similarity index 89%
rename from rfsoc_book/notebooks/notebook_A/boards/RFSoC2x2_03_pynq_introduction.ipynb
rename to rfsoc_book/notebooks/notebook_A/boards/ZCU216_03_pynq_introduction.ipynb
index 21d24a9..5091f33 100644
--- a/rfsoc_book/notebooks/notebook_A/boards/RFSoC2x2_03_pynq_introduction.ipynb
+++ b/rfsoc_book/notebooks/notebook_A/boards/ZCU216_03_pynq_introduction.ipynb
@@ -1,6 +1,7 @@
{
"cells": [
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -8,6 +9,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -34,12 +36,13 @@
"* [5. Conclusion](#conclusion)\n",
"\n",
"## Revision\n",
- "* **v1.0** | 23/01/23 | *First Revision*\n",
+ "* **v1.0** | 19/05/23 | *First Revision*\n",
"\n",
"---\n"
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -56,6 +59,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -80,6 +84,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -97,6 +102,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -116,6 +122,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -135,13 +142,14 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"## 4. PYNQ Overlays Note: \n",
" This Jupyter notebook is not compatible with the ZCU216 development board as the RFSoC-SAM module does not support this platform. \n",
" \n",
"\n",
"\n",
@@ -69,11 +73,13 @@
"\n",
"## Revision\n",
"* **v1.0** | 17/01/23 | *First Revision*\n",
+ "* **v1.1** | 19/05/23 | *Minor changes for new development boards (ZCU208 & ZCU216)*\n",
"\n",
"---\n"
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {
"extensions": {
@@ -101,6 +107,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {
"extensions": {
@@ -160,6 +167,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {
"extensions": {
@@ -206,6 +214,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {
"extensions": {
@@ -241,6 +250,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {
"extensions": {
@@ -266,6 +276,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {
"extensions": {
diff --git a/rfsoc_book/notebooks/notebook_C/boards/RFSoC4x2_01_exploring_the_spectrum.ipynb b/rfsoc_book/notebooks/notebook_C/boards/RFSoC4x2_01_exploring_the_spectrum.ipynb
index 5902979..794ba0e 100644
--- a/rfsoc_book/notebooks/notebook_C/boards/RFSoC4x2_01_exploring_the_spectrum.ipynb
+++ b/rfsoc_book/notebooks/notebook_C/boards/RFSoC4x2_01_exploring_the_spectrum.ipynb
@@ -1,6 +1,7 @@
{
"cells": [
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -8,6 +9,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -16,6 +18,8 @@
" Note: \n",
" This Jupyter notebook is not compatible with the ZCU216 development board as the RFSoC-SAM module does not support this platform. \n",
" \n",
"\n",
"\n",
@@ -47,11 +51,13 @@
"\n",
"## Revision\n",
"* **v1.0** | 16/01/23 | *First Revision*\n",
+ "* **v1.1** | 19/05/23 | *Minor changes for new development boards (ZCU208 & ZCU216)*\n",
"\n",
"---\n"
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -60,6 +66,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -80,6 +87,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -103,6 +111,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -119,6 +128,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -136,6 +146,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -154,6 +165,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -161,6 +173,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -169,6 +182,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -205,6 +219,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -212,6 +227,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -230,6 +246,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -242,6 +259,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -262,6 +280,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -269,6 +288,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -279,6 +299,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -298,6 +319,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -310,6 +332,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -328,6 +351,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -352,6 +376,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -364,6 +389,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -374,6 +400,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -384,6 +411,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
From b9abcea4827635811b516cac9f1ac75318cca9af Mon Sep 17 00:00:00 2001
From: dnorthcote <42978178+dnorthcote@users.noreply.github.com>
Date: Fri, 19 May 2023 16:09:22 +0100
Subject: [PATCH 05/23] Update Set G for New Boards
Add new notebooks for ZCU216 and ZCU208 and update previous notebooks with table information on LMK clocks.
---
.../RFSoC2x2_01_rfsoc_radio_system.ipynb | 29 +-
.../RFSoC4x2_01_rfsoc_radio_system.ipynb | 29 +-
.../boards/ZCU111_01_rfsoc_radio_system.ipynb | 29 +-
.../boards/ZCU208_01_rfsoc_radio_system.ipynb | 520 ++++++++++++++++++
.../boards/ZCU216_01_rfsoc_radio_system.ipynb | 520 ++++++++++++++++++
.../notebook_G/images/clk104_setup.jpg | Bin 0 -> 164085 bytes
.../images/multiboard_setup_rfsoc2x2.png | Bin 2922365 -> 0 bytes
.../images/multiboard_setup_rfsoc4x2.png | Bin 324108 -> 0 bytes
.../images/multiboard_setup_zcu111.png | Bin 6431340 -> 0 bytes
.../multiboard_setup_zcu111_rfsoc2x2.png | Bin 4791673 -> 0 bytes
.../notebook_G/images/zcu2xx_adc_setup.jpg | Bin 0 -> 213085 bytes
.../notebook_G/images/zcu2xx_dac_setup.jpg | Bin 0 -> 204881 bytes
.../notebook_G/images/zcu2xx_sma_conn.jpg | Bin 0 -> 120518 bytes
13 files changed, 1124 insertions(+), 3 deletions(-)
create mode 100644 rfsoc_book/notebooks/notebook_G/boards/ZCU208_01_rfsoc_radio_system.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/boards/ZCU216_01_rfsoc_radio_system.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/images/clk104_setup.jpg
delete mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_rfsoc2x2.png
delete mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_rfsoc4x2.png
delete mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_zcu111.png
delete mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_zcu111_rfsoc2x2.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/zcu2xx_adc_setup.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/zcu2xx_dac_setup.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/zcu2xx_sma_conn.jpg
diff --git a/rfsoc_book/notebooks/notebook_G/boards/RFSoC2x2_01_rfsoc_radio_system.ipynb b/rfsoc_book/notebooks/notebook_G/boards/RFSoC2x2_01_rfsoc_radio_system.ipynb
index 3d26578..5fb41a1 100644
--- a/rfsoc_book/notebooks/notebook_G/boards/RFSoC2x2_01_rfsoc_radio_system.ipynb
+++ b/rfsoc_book/notebooks/notebook_G/boards/RFSoC2x2_01_rfsoc_radio_system.ipynb
@@ -1,6 +1,7 @@
{
"cells": [
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -8,6 +9,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -47,11 +49,13 @@
"\n",
"## Revision\n",
"* **v1.0** | 05/12/22 | *First Revision*\n",
+ "* **v1.1** | 19/05/23 | *Minor changes for new development boards (ZCU208 & ZCU216)*\n",
"\n",
"---\n"
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -93,6 +97,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -109,6 +114,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -135,6 +141,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -148,18 +155,24 @@
" ZCU111 \n",
" RFSoC2x2 \n",
+ " ZCU208 \n",
+ " ZCU216 \n",
" RFSoC4x2 \n",
" \n",
" LMX Device LMX2594 \n",
" LMX2594 \n",
" LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
" \n",
" \n",
" LMK Device LMK04208 (default frequency is 122.88) \n",
" LMK04832 (default frequency is 122.88) \n",
" LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
" \n",
" \n",
"\n",
@@ -182,6 +195,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -196,7 +210,7 @@
"source": [
"if xrfclk.board in ['ZCU111', 'RFSoC2x2']:\n",
" lmk_freq = 122.88\n",
- "elif xrfclk.board in ['RFSoC4x2']:\n",
+ "elif xrfclk.board in ['RFSoC4x2', 'ZCU208', 'ZCU216']:\n",
" lmk_freq = 245.76\n",
"else:\n",
" raise RuntimeError('Platform not supported.')\n",
@@ -205,6 +219,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -212,6 +227,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -229,6 +245,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -246,6 +263,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -263,6 +281,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -283,6 +302,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -302,6 +322,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -330,6 +351,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -339,6 +361,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -366,6 +389,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -375,6 +399,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -404,6 +429,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -414,6 +440,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
diff --git a/rfsoc_book/notebooks/notebook_G/boards/RFSoC4x2_01_rfsoc_radio_system.ipynb b/rfsoc_book/notebooks/notebook_G/boards/RFSoC4x2_01_rfsoc_radio_system.ipynb
index c1b6a56..a133ae0 100644
--- a/rfsoc_book/notebooks/notebook_G/boards/RFSoC4x2_01_rfsoc_radio_system.ipynb
+++ b/rfsoc_book/notebooks/notebook_G/boards/RFSoC4x2_01_rfsoc_radio_system.ipynb
@@ -1,6 +1,7 @@
{
"cells": [
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -8,6 +9,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -47,11 +49,13 @@
"\n",
"## Revision\n",
"* **v1.0** | 05/12/22 | *First Revision*\n",
+ "* **v1.1** | 19/05/23 | *Minor changes for new development boards (ZCU208 & ZCU216)*\n",
"\n",
"---\n"
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -92,6 +96,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -108,6 +113,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -134,6 +140,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -147,18 +154,24 @@
" ZCU111 \n",
" RFSoC2x2 \n",
+ " ZCU208 \n",
+ " ZCU216 \n",
" RFSoC4x2 \n",
" \n",
" LMX Device LMX2594 \n",
" LMX2594 \n",
" LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
" \n",
" \n",
" LMK Device LMK04208 (default frequency is 122.88) \n",
" LMK04832 (default frequency is 122.88) \n",
" LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
" \n",
" \n",
"\n",
@@ -181,6 +194,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -195,7 +209,7 @@
"source": [
"if xrfclk.board in ['ZCU111', 'RFSoC2x2']:\n",
" lmk_freq = 122.88\n",
- "elif xrfclk.board in ['RFSoC4x2']:\n",
+ "elif xrfclk.board in ['RFSoC4x2', 'ZCU208', 'ZCU216']:\n",
" lmk_freq = 245.76\n",
"else:\n",
" raise RuntimeError('Platform not supported.')\n",
@@ -204,6 +218,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -211,6 +226,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -228,6 +244,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -245,6 +262,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -262,6 +280,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -282,6 +301,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -301,6 +321,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -329,6 +350,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -338,6 +360,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -365,6 +388,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -374,6 +398,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -403,6 +428,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -413,6 +439,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
diff --git a/rfsoc_book/notebooks/notebook_G/boards/ZCU111_01_rfsoc_radio_system.ipynb b/rfsoc_book/notebooks/notebook_G/boards/ZCU111_01_rfsoc_radio_system.ipynb
index 2f5a80f..3e61753 100644
--- a/rfsoc_book/notebooks/notebook_G/boards/ZCU111_01_rfsoc_radio_system.ipynb
+++ b/rfsoc_book/notebooks/notebook_G/boards/ZCU111_01_rfsoc_radio_system.ipynb
@@ -1,6 +1,7 @@
{
"cells": [
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -8,6 +9,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -47,11 +49,13 @@
"\n",
"## Revision\n",
"* **v1.0** | 05/12/22 | *First Revision*\n",
+ "* **v1.1** | 19/05/23 | *Minor changes for new development boards (ZCU208 & ZCU216)*\n",
"\n",
"---\n"
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -93,6 +97,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -109,6 +114,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -135,6 +141,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -148,18 +155,24 @@
" ZCU111 \n",
" RFSoC2x2 \n",
+ " ZCU208 \n",
+ " ZCU216 \n",
" RFSoC4x2 \n",
" \n",
" LMX Device LMX2594 \n",
" LMX2594 \n",
" LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
" \n",
" \n",
" LMK Device LMK04208 (default frequency is 122.88) \n",
" LMK04832 (default frequency is 122.88) \n",
" LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
" \n",
" \n",
"\n",
@@ -182,6 +195,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -196,7 +210,7 @@
"source": [
"if xrfclk.board in ['ZCU111', 'RFSoC2x2']:\n",
" lmk_freq = 122.88\n",
- "elif xrfclk.board in ['RFSoC4x2']:\n",
+ "elif xrfclk.board in ['RFSoC4x2', 'ZCU208', 'ZCU216']:\n",
" lmk_freq = 245.76\n",
"else:\n",
" raise RuntimeError('Platform not supported.')\n",
@@ -205,6 +219,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -212,6 +227,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -229,6 +245,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -246,6 +263,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -263,6 +281,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -283,6 +302,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -302,6 +322,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -330,6 +351,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -339,6 +361,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -366,6 +389,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -375,6 +399,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -404,6 +429,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
@@ -414,6 +440,7 @@
]
},
{
+ "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
diff --git a/rfsoc_book/notebooks/notebook_G/boards/ZCU208_01_rfsoc_radio_system.ipynb b/rfsoc_book/notebooks/notebook_G/boards/ZCU208_01_rfsoc_radio_system.ipynb
new file mode 100644
index 0000000..76cd155
--- /dev/null
+++ b/rfsoc_book/notebooks/notebook_G/boards/ZCU208_01_rfsoc_radio_system.ipynb
@@ -0,0 +1,520 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "\n",
+ "
\n",
+ " Note: \n",
+ "
\n",
+ "
\n",
+ "Figure 1: Setup of the clk104 add-on board on the ZCU208. \n",
+ "\n",
+ "Ensure that the clocks above are connected as follows:\n",
+ "* DAC_229_CLK to DAC_RFCLK_B (P & N).\n",
+ "* ADC_225_CLK to ADC_RFCLK_B (P & N).\n",
+ "\n",
+ "If you do not make the correct connection, the demonstration will not operate correctly.\n",
+ "\n",
+ "#### 1.1.2. ADC Setup \n",
+ "Figure 2: Setting-up the ADC on the HW_XM_655 card. \n",
+ "\n",
+ "Ensure that the ADC connections are setup as follows:\n",
+ "* JHC5 P0_255 to J18\n",
+ "* JHC5 N01_255 to J16\n",
+ "\n",
+ "This step is a little difficult as there are many small wires. Please take your time setting up the ADC to prevent errors.\n",
+ "\n",
+ "#### 1.1.3. DAC Setup \n",
+ "Figure 3: Setting-up the DAC on the HW_XM_655 card. \n",
+ "\n",
+ "Ensure that the DAC connections are setup as follows:\n",
+ "* JHC3 P0_230 to J39\n",
+ "* JHC3 N0_230 to J37\n",
+ "\n",
+ "Take your time with this step to prevent errors during the demonstration.\n",
+ "\n",
+ "#### 1.1.4. Loopback Setup \n",
+ "Figure 4: Connecting the ADC to the DAC in loopback mode on the HW_XM_655 card. \n",
+ " \n",
+ "The connection shown in the image above is the following:\n",
+ "* J17 (LFB_ADC_02) to J38 (LFB_DAC_01)\n",
+ "\n",
+ "Your ZCU208 development board is now ready for the demonstration."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "\n",
+ "Caution: \n",
+ " In this demonstration, we generate signals using the RFSoC development board. Your device should be setup in loopback mode. You should understand that the RFSoC platform can also transmit RF signals wirelessly. Remember that unlicensed wireless transmission of RF signals may be illegal in your geographical location. Radio signals may also interfere with nearby devices, such as pacemakers and emergency radio equipment. Note that it is also illegal to intercept and decode particular RF signals. If you are unsure, please seek professional support.\n",
+ "
\n",
+ "\n",
+ "### 1.2. Software Setup \n",
+ " Table 1: LMK and LMX devices on each supported RFSoC platform. \n",
+ " ZCU111 \n",
+ " RFSoC2x2 \n",
+ " ZCU208 \n",
+ " ZCU216 \n",
+ " RFSoC4x2 \n",
+ " \n",
+ " LMX Device LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
+ " \n",
+ " \n",
+ " LMK Device LMK04208 (default frequency is 122.88) \n",
+ " LMK04832 (default frequency is 122.88) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " \n",
+ "
\n",
+ " \n",
+ " \n",
+ "We cannot use any arbitrary frequency to program the LMK and LMX devices. There are a set of clock files provided for configuring these devices to a particular frequency. These files are found in the xrfclk module. We can print the available files using the code cell below."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "files = sorted(os.listdir('/usr/local/share/pynq-venv/lib/python3.8/site-packages/xrfclk'))\n",
+ "for file in files:\n",
+ " if 'LMK' in file or 'LMX' in file:\n",
+ " print(file)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "You should be able to match the LMK device on your RFSoC platform with a clock file given above. We require the LMX device to be set to a frequency of 409.6MHz for this RFSoC radio system."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "if xrfclk.board in ['ZCU111', 'RFSoC2x2']:\n",
+ " lmk_freq = 122.88\n",
+ "elif xrfclk.board in ['RFSoC4x2', 'ZCU208', 'ZCU216']:\n",
+ " lmk_freq = 245.76\n",
+ "else:\n",
+ " raise RuntimeError('Platform not supported.')\n",
+ "\n",
+ "xrfclk.set_ref_clks(lmk_freq, 409.6)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Further information about the xrfclk module can be found in [4]."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 2.2. The xrfdc Module Figure 5: Overview of the radio demonstration system on RFSoC and PYNQ. \n",
+ "\n",
+ "A DMA controller is provided to transfer data from Jupyter Labs to the transmitter. Another DMA is provided to transfer data from the receiver to Jupyter Labs. Jupyter will be used to control the hardware accelerators and inspect the transmitter's data generation stages and receiver's synchronisation stages.\n",
+ "\n",
+ "### 3.1. Controlling the System \n",
+ "Figure 6: Data frame structure for transmit and receive packets. \n",
+ "\n",
+ "As shown, the data frame is exactly 64 bytes long. If the data frame uses less than 44 bytes of data for the payload, it is zero padded as required. Each of the data frame entries shown are used in this demonstration system."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 5. Conclusion \n",
+ "
\n",
+ " Note: \n",
+ "
\n",
+ "
\n",
+ "Figure 1: Setup of the clk104 add-on board on the ZCU216. \n",
+ "\n",
+ "Ensure that the clocks above are connected as follows:\n",
+ "* DAC_229_CLK to DAC_RFCLK_B (P & N).\n",
+ "* ADC_225_CLK to ADC_RFCLK_B (P & N).\n",
+ "\n",
+ "If you do not make the correct connection, the demonstration will not operate correctly.\n",
+ "\n",
+ "#### 1.1.2. ADC Setup \n",
+ "Figure 2: Setting-up the ADC on the HW_XM_655 card. \n",
+ "\n",
+ "Ensure that the ADC connections are setup as follows:\n",
+ "* JHC5 P0_255 to J18\n",
+ "* JHC5 N01_255 to J16\n",
+ "\n",
+ "This step is a little difficult as there are many small wires. Please take your time setting up the ADC to prevent errors.\n",
+ "\n",
+ "#### 1.1.3. DAC Setup \n",
+ "Figure 3: Setting-up the DAC on the HW_XM_655 card. \n",
+ "\n",
+ "Ensure that the DAC connections are setup as follows:\n",
+ "* JHC3 P0_230 to J39\n",
+ "* JHC3 N0_230 to J37\n",
+ "\n",
+ "Take your time with this step to prevent errors during the demonstration.\n",
+ "\n",
+ "#### 1.1.4. Loopback Setup \n",
+ "Figure 4: Connecting the ADC to the DAC in loopback mode on the HW_XM_655 card. \n",
+ " \n",
+ "The connection shown in the image above is the following:\n",
+ "* J17 (LFB_ADC_02) to J38 (LFB_DAC_01)\n",
+ "\n",
+ "Your ZCU216 development board is now ready for the demonstration."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "\n",
+ "Caution: \n",
+ " In this demonstration, we generate signals using the RFSoC development board. Your device should be setup in loopback mode. You should understand that the RFSoC platform can also transmit RF signals wirelessly. Remember that unlicensed wireless transmission of RF signals may be illegal in your geographical location. Radio signals may also interfere with nearby devices, such as pacemakers and emergency radio equipment. Note that it is also illegal to intercept and decode particular RF signals. If you are unsure, please seek professional support.\n",
+ "
\n",
+ "\n",
+ "### 1.2. Software Setup \n",
+ " Table 1: LMK and LMX devices on each supported RFSoC platform. \n",
+ " ZCU111 \n",
+ " RFSoC2x2 \n",
+ " ZCU208 \n",
+ " ZCU216 \n",
+ " RFSoC4x2 \n",
+ " \n",
+ " LMX Device LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
+ " LMX2594 \n",
+ " \n",
+ " \n",
+ " LMK Device LMK04208 (default frequency is 122.88) \n",
+ " LMK04832 (default frequency is 122.88) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " LMK04828 (default frequency is 245.76) \n",
+ " \n",
+ "
\n",
+ " \n",
+ " \n",
+ "We cannot use any arbitrary frequency to program the LMK and LMX devices. There are a set of clock files provided for configuring these devices to a particular frequency. These files are found in the xrfclk module. We can print the available files using the code cell below."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "\n",
+ "files = sorted(os.listdir('/usr/local/share/pynq-venv/lib/python3.8/site-packages/xrfclk'))\n",
+ "for file in files:\n",
+ " if 'LMK' in file or 'LMX' in file:\n",
+ " print(file)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "You should be able to match the LMK device on your RFSoC platform with a clock file given above. We require the LMX device to be set to a frequency of 409.6MHz for this RFSoC radio system."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "if xrfclk.board in ['ZCU111', 'RFSoC2x2']:\n",
+ " lmk_freq = 122.88\n",
+ "elif xrfclk.board in ['RFSoC4x2', 'ZCU208', 'ZCU216']:\n",
+ " lmk_freq = 245.76\n",
+ "else:\n",
+ " raise RuntimeError('Platform not supported.')\n",
+ "\n",
+ "xrfclk.set_ref_clks(lmk_freq, 409.6)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Further information about the xrfclk module can be found in [4]."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 2.2. The xrfdc Module Figure 5: Overview of the radio demonstration system on RFSoC and PYNQ. \n",
+ "\n",
+ "A DMA controller is provided to transfer data from Jupyter Labs to the transmitter. Another DMA is provided to transfer data from the receiver to Jupyter Labs. Jupyter will be used to control the hardware accelerators and inspect the transmitter's data generation stages and receiver's synchronisation stages.\n",
+ "\n",
+ "### 3.1. Controlling the System \n",
+ "Figure 6: Data frame structure for transmit and receive packets. \n",
+ "\n",
+ "As shown, the data frame is exactly 64 bytes long. If the data frame uses less than 44 bytes of data for the payload, it is zero padded as required. Each of the data frame entries shown are used in this demonstration system."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 5. Conclusion 5Sb;O_0F&du6f!3#j2(AD8CV)IWmskAwtT=^yWcY64qj`bTCeXwzWw>bLyR{R6vT`deB6)DK`+Rd#>VpFHiz6!tH^
zH2ve5a0;>jfGOf{IvfYo?xqO8G1LoT?^SUAV+Z{|d-rK|p3M1VE9hKsNJf9W8eT(E
z8DK>Do6ZEKqZ@Jk#;_bu{M`SAg??kGP2u>AKKvJ5^$+HH;#d2Pp)$aU8L9uq&{zQ{
zYorN)t||cLm4LUJk=9?Ez#3`)=6RAw)oAQD#)V=n6W!nV85CRFWB$e@Q2fdMPb}hw
z;uQNo@-sm3s6F0q9;n^mF6{|_W9XRhi1tK(F`7N`-+2M{&wtaQa>8TVzxqQ*_y_>l
z>;I-hWrcrkZ}4Z`p>hN4KmDe|DnPM`>EFI|CT71eG&aJsnVA2^Q2W61KlM@OP*PXs
z;$-DvXW`&t;ot!%JKNZ}1K4>4_>4I?jk%54`Az$XB
z&IOSED8R?d{bvYA0CXd9vT?F;@BzeCJ}Lr~fyOq*f|N3El)U7DCVJuyKu22>C+JT-
zH3tJbJ7WhyN<}$lN-j1o0J{(imk@^#bOcHcc1kXGN&pWx2PFp=Hzgk@4<$fBQ9%+Q
zW8^@o>}23%Oet>wG&8p`1{fLuEm=HlZLL|LVOZ}8066*iS$TPcDF3vae*nJ#pAaR0
zpNEHwgPV(8fQyfhi;r7~@*e^ZCoc~_7cbXe0xypMmjD+JlmK|)_%xxQovq_bK}t?R
zE>=G7r@{XR_-AN#e)d1*kG#KyW*4IT^Lfe?dX7AnX4ael0akWa4o+4+P5>tqadEJ6
z0617Vp`YIi^t4F73p)oNFF%y@KU?T}{@IW4N&?Wwu>WKVXmtIzCk!(bJ;f-Le>i`8
z2$U1*eNV9xsUG_MwBumapkL5E`7eD8ik^1l?_CLvZclV5M*0bz<6oX*0Lkwev7ng{
z89?@X9H?g^6Fm(DEzlJAyZ_V1g8?9tIspI-&>ir1=VSh%ce(zi!|;QlB0a^`r|kVS
zFEq0JZfT!dab*cvXg~o-NWOa~`vw}w|7KJu5vm`|zc~RKzy9~kkDTkPBe{<|1N+%)c1sRp#Hk1UUXZKai8UzLf
z1qB@qod^Sih?9zxiu3=vJhlUHkO69dOgI=S04xp+91hH5H-G|a7=)*k1Wii+6zIVK
z9sv;v83h#$%1{FhSTJyKu<&pQ2=MSwZttgq13V4_E)|D3;Kd9rBV!X&
zGjj_^CubK|H+PSKz@Xre(6G;-xG(VuiAi6Rv$At?^YRM{iz=(CYijH28yY*ix_f&2
z`UeIlCa0!nX6NP?);GYLTiZK7clSM
zgGYMO3kKE|TH$cu5vVv2am7C%8Q4Fg=JZ3xdma0&q63A7OX(Qj&|w^vfR=lm?&L|e
z-AEd+0tO=_zyfPK0AbS%
zB@aLOYJ$Y$mby4EKUJ@**c!fP=1}K
zuWg}ZHksmF>+cpal4T^;)B8%;?-SOR4tacm23?8kQagW;J*(w(!R@sfnzY+
zb0fWVRCG*FjVC^1X_~WgsjZadKG7SIpoHb1SKoSj7f?WH8jyN25yl;EnZ_x^!JI2P
z=Hm|F#nsdBX{c#f9Mww*=i7NM}ky&c%XhYL{_niM|Y&fLgchg
z2$A#9cP8$#Mgo`$*MNu3q~)r{hb#m+<7Jzw+sYO9GjEaS<`k}Q`YUPaR@Um0V9fFB
zJWb*4JW_9_v(2KSDN@khoHT#?KpjyPPm@U*#qQvCSFEL>LDZ?>Xx-%VW?W~^yF}}H
zOwyh0$eBs%f6brkarB*08H9cWi&j;CTE8e<24oVEt^B-3D13x3jw!TL>I@njX7&dkGG^NgNs0FssT7R(})pg6u)=w9hx=KEmEMB|@
zj!TwSN0PM+2@OUBFvGz%gRj-Z3;UX0WjwTuo|bS>7#$3mY`rX}&RQaw8+S&lb|1jHd_I32-YnRU^X$QwL
zKJ5|2rJDom4d@P{m%OnDv!b0@Ev*@I>hr5QNzJ
zTA)3<{In@k@}XThl~?fM!TqPDqTEFO=fM?AwP1RV$i0*Mt*I!NO}Zn(GU#3{HwWpyS`Z&Cw*X)0sIZvEI^Ba7Ul*ZQBBE+E
z0M_i>e|n-%Dlxk84;RQU^|zeh&AJRx)^WI-SEMh+?k+{u-#G7nR95ABEs%t9H)wJl
zj5JBKBl4nVBy@cp-|$>5T`5qm@I$T`(_40mS~$#CM^We6OZ^LJ-Q&Z|AJQr$Ng5Lu
zU;w1#ZbTf)KE3B;q(x@$c@ij>iJQY?y}CRWKxn|uPU
zCwu{;6;JYoF>cCVz|cM}-BY!8tTVze`v+8h-6lV0p>RJB`byqSlCWG=j?E~US91c3
z{n{Y!V%){I4VLjzlCR2C2JCwgWsXKfB6+eK5~x#)%xaCB_R~aJ49!gHo1zrCdubwJ
zrBI|^39RYI3!j7eJ9s9vIIs^fi8a1{i2$3^MzwY;C+z6p8^xE17f16+P7wmOXFdcx
ztd~DOLGPUWP+wPP4lqnNtoW(&s_){?yC9s=a#eBmoFq%Tk88k`Itv=AFa>CRFRHFp
znlQ*82xA6pB->aXOp|bA7B2^c80tDY?_?2QeKc@hBZ^R
zC+NhNa5*w8miV0hS7m|H$LKGvBSOxLvT60ww?mxX3KPyzM7HWOZ9eK(Mdj~5!gQ+_L50y6YU
z^^Vi3^mYZ47u;Q8T$(=<@R0%Fw);ns3Ph^fhi%8UzA;JlPqzeHdWyR`K9@|9S>bgS
z4>^O;tLNw-KE%o#ku_YA%68is&=ZuUW@$4`ctx8^da=`joD517$#8(5II!74ZTwhS
zg+B^tD)+pYe>QW)W??aln(xLHCVv%-9rK%Jq_Ve&gY_e@#GW$(BVv)#@Y`S(|GwR`THw$Ghmi}yAB7^n$<+)S7b+=!J
z7PJH#BLlZm3d`>NwZy47bhCN#*Us4$t4WxKA5kBzQ^$kK=vY6Q(D0))r}NLF%wwBks;jhktR#=jFs$-g@^MJ!6e-y;0wg`6Dinr&?TsSjr{)JlII<}
zG-)DNigzXHb*NpMKtBzVkd$b;e)#qyM>fPA~nA%2>nI<@q+_?-x?ARa_zo@VL
z{hR0+nu`RZhzZ}{HW@{+L~y0QUi-Y&V~*#kVPvxZ*489~%Mo?K9pQ|#9p`&fe2R_e
z@fAz2gtq5o!!HOHwcpGK-WG{GJ3r$t)
zPS6FdCPZ_ybhG$IajS#heOZiaC<v`7$ijEf}Gs=veSGkz8Ra+8Y!G?*@OGy$y#h
zxcLa6{H64Tj?Q%3Z0{yFs&H*sX?t)_z<}UanOcz%FkU!dR68`+S(A1cC2^=
zG$R2XzKlCSVjZPgGNkQ=Co?FIfA$5OleY-^GVUKZ-?MH{=gY-ah#Qs@qXX`RJf`u2
zcV`>fBA5?L*kB@L#Qhb)LBV#bx(d?Y`mAOt+;c57MT>dkTyYa5Idj6VbOaBTf7@_K(5Rz%`AEbO?CPE8-3<5kIErrFkGG}W@Yiz#{(lUwwv
z>{z!9J+~>wj5eiJC9vyZ(r+#TET54Y!HmGrlv=E;$QJB!Njs8-qbQrEel-cOTd!R^
z72y=~f+4}M0XWG((H@yE#c1ydWEg#&9Hnn^@t2xUboEKS15G
zm_*o!9O=j+jhm#vWWn@r!h9~~W=A{dnCc-*g8nG|L^N|}0lRN?M#PK@JjP
zt}NuGxVa)A5~@TCZ~4JpPe1>9$tjB#W(~*0%Ga-e=dCEN15e;OJ3GV?TP_UINHEe4
zp+hY?`>DWtGPxMI67ZQ%SSUYt>ZY{evz&l@BX(SZImxziJqX5n(Q(WNwh>KU>{p@|
zT}v1c#7W#hBDD?@eAYf9f`P3`?><*_s(pUYrWJ4M6#m{)$8Y+QQNGPgsY8nv80#;6
z-SaV)_&GZarM^#AweaAavvi`?(r1kX?k`m^sle4Zwd@weUIZf;avR50GNiVZLYFOF
zHqR+CXlHrp*i5_$lywHZK(3&rZ5~TUmgU-sq4>?0@ZU!r-1>A=FD`Qu_O3pr8|2W=
zT4Bz!qE8?L4LLr+Y=UXFh=|E+$|XP!$y-&G`%`6JEX7)~d~vP_NzA-xo(U*4K#;3`
z1f0LeP6YXMsjxs1NvbT~YyF_)b=G;UZ%n=G8D+?QJ4#D6W8))n<^uco?u4aYyy1D?
zm3va4pE63)XX+fcxvwbiJui#Rv!$(V$@4{3hq0@g>o8vt8$`DZSn(1P3#Udn%FpfO
zzMM|`Qc|bMcFO6Lfw2e5oK`8#avwRzwOu9>p!ClVSaK!rEs7l-ps3!vMtaP
z^$~&V-m1>*WcMG`4{5y&E_Th=Tlz7vkVQ7GBUiUg3}*Q$Z80XOQp|R9ySBPQ2r|8%
zCRbn}R*h7{FCw_@Dkdu}{UI3i%bYr`BhPgcmtUxtpR7-FBtRy0&}E+s39S!Z%DeL6
zi$=8vcS;%$!!%;9alu^h)W)<;vNnD^7(wS-KQmWcsy?aHzS=Kt;&Se-X@zoEMk*s&
zjVYr`)VDkF%e~%BQ+K>?R0A~2>Q;|f#j{p?jTMCjd$#*mEqje3$Vzeu2DER1ZD-|3
zLC?1-Pb{t?8J5-Wrj}Eq7Tt*kz#@!aQiMxcC|m@KAJTr@t94u@OoW`3*}N5e*nA5g
zBGQX@bMril`7k$mn>x{MY2igIiw&L91nVzjb?Phfc+%6Vv7;bH8;&N~2feTc_^U~-
z@HA2N&4nDUcjd9Wv8!a!V;fEKNV1kpB;f-~vW{+_DwJeCehB=K@k(*$7bAy~&q(jJ
z2%~+sY$5&CZq+PE$=Z}KKAR~mnLvDj`)4L9y=4&rQy5D4t@E}_Oh7p
zR2%TTG8pw2y_|~RsG4kRHm9Akja+2;dD{nRYvXU~d+c32%Ms7ys?1Haj|DN?re;78
zhOUSJK_i1vZ6U0ErImbdLHkWLX)?N?ptf)xvKIo?lV0tJ6Y6hP-gogTUZu>|$&jgItMf$@dclu2%7_}Zlivm#w_PVeG#O~i*KzP7`E@$I8d6Ah>oh;^BioiRMY~
zWn!4mJWjXu2!Jmv5n?8ASy84nAdW{7HeMteBI}2qaO*3}~a!?6LCJ;TeK&
zqOvaM6H8=@fQe~8OAgl3_*EJ?T*Nguz@6Da63-ED^Y(xyDg-I2{z&PHF)IQT5r0Sk
zqB2eu7V@qp-Q4=U_UrE@8@#e~LP?~sulg@XWco#<7)@DqVh6%H
zC$6l`j?PX=oo=0y?N-g+M=7Tac)_>Z;V!lD8#7Sn4r)sv^k0
z_8|tkG>fopX(r=7BZX)ub^St@ChoPrDBEa18v7>fTSQ&i-D+X6!zwSU)Lq@!cOjh7
zom?f$1U~YR0l#weBpMh|VORK<~eWczL9nQaofj$Jy(QXofEi
zvf3;@AXS+0%H4+qgm!ETQL)i1uC?q2)D)k!qB1&n23TRpyfYZ{Xm+%x65piQ3C
z*!BtcexOvpk_4^{G11W|+(d14amd%Usvo_kAVXbOorz!KvA-PsIWE?=lTEn-0=DCt
zQ|dPP-q-Zhe3jG>CZG$Y3O%DBM*7yvDR!?iBJAel@vK)~$%8z{UT7ntBwx%
zI*-X(sm2K~jx46+k6S-VUbJJyg8iGZE9#PLBtiyTh+$e^@b=kwo^#j$`~W#00>1zp
zjj+oIQ)^At@o>+St4r08HRB*}@hRFNIL|XGJ^opISmA}oXngfS*?kmSH^|~-|0XCQ
z{j$xJ)AWGZ!NE=)VPF$inx;lR)BO8x?KThHmdi5p@Ksui;{Jo9_^gQ~>o@r1cO!)_
zV<`q~m(wzjxtj9rbyyR))*<%yy$>dpWi4H#=;fh$>-QhF#?0h^xh%~l#00*{TgFN*
zUaQXT=U^A#o3XqAdo&nJktvR|z}_`X_g=UCzPCSx>v(=lmqn|M-*I?)=bEotpGe+~
zBU3y1&*K7$tFa?LxkfErlnwU1tEfh+0r(#A(fVdssq%@0dc8O)4s49>A*XE$wNmFn
z$>9_LAgIDo){#jqxekzSes&Gwk@b=&@7Ls2wk7;RXjl}~Hwe%L^zaP%awR5YyWa8%
z*;aA}oTjILX%)9kv=!MKpKw22Dou>OFc)qhL+T%R-oSPWBvMQ{Jug^mtE-)H?UyUI
z9eha=x@kw`%K<^f+1g;u^%*^vR(LyQrz=XbOz-y}2&Mm&r1Wv(Bv_VtZyjMmn0Q_X*P_Cnok0
z@aOueu@#@B&44LKt?cmmkB(oaYZ`f3TItQk%`az;%zZRz8CRQL
zqb&6Ww2c?F^mVh4JH{cLrUJJjr5{G$?d2^|X3rCw_B@AKF^+z3*tK;(VgCq-o*Dv2
zqUc90pWl83z8_rtg0ZKO1b1fd|I6*-vWT;!NS;;8SC85h5|qlRcDR8%x{XhA~3#KJ(we8Ru)QlPz`dO<(v
z$VkXf9RGLa_gxB%A8ace4E6timjbBy|NLFb>F9zGSRwu-@Ul{`<@awUSyDM4iK{xuwX}&kBD4vpu7awagqS`#xSn
zoZtA>&<#6CYJm8xV@u)CCp&M#2Xjxa+BMMY)d~qDa>MUF4v$kLKkSg4$ud6W*91cB
z%$Ik3%?lf$vZsgg|JY+w~NGO9>Hp6^GC4S8?>
zA$i%t<873VW@;+K%hzgE+wlhz3*{=F*XcaB`ew?$?W?}eqFr)DcSSgT(UqM9s$qTgeh#-m*t(qz3H5{D9qyqZ@EF$F9!q|
z9Ax{5gcLnaDFPn>7|s;_V$Uu{@ywEg&Mb6cWDXA^M?*|v(MAo=@EauU^dnza5-^L4
zu`gxLes|lsoQ1@%n>7oZDBXZxdmEm~$s_$j>YC8f2sfuou&WQBKds7%(bd6DQ?K>m#Zl;cJz>l{0E58t*~1(IC8pue7!De
zV%2nk^>7=fgQTI8Ro$ow+YXO_7L%Px>oVs)*I98Pyl)&5pfXwABD%3MZQV`qapaud^-qOuk`h}*TJ
z+vS}o+1Q?69+St>4wf{cjNz>BvKCguT0fe1?OoxYE))Kc4H10=Xigr+^v}uxcPMMa
z2W5>T{648H1@!N6Ma)jM(%e^i5wD{SvyP1HYtOKFv037`OgKQD{d^ziqvbrg%`A7U<#`JrYrYyW%G}PuJHW<8+;d#&^UEPIhL;W5w+p>?<^|1AwSXhm890A(Z+zr
z6X2kaB}IhWVjcUFyVoZNy1Tcc4-+1G9npd0d{y<$kvx&I*y>uLJNID5@2V>qFG->q
z??|y7n`rX1C{m15qo0F6EMUlrSVOHIX>*XT#6okaIe9UxrB*S~Y@fYip@}htZK1kq
z0um@qkPd=Rk);jd!y%vnVCLXdUq&9!zK2A+v?9;cupP*W!ITgryJTmX@7h)54jyUH
z+Q$E|z=s2ujX;>~T5)|l#1AhrNHupGN7B}ZvEEIy>c=UyMiGA#Sf}4yi*^l*PivEVi*(4
z9(w!GpnaLNPav-ERG5%&0h)^_d+JCJf@^GpH0!zqYNF9Ce5iF4ba)Qib_-UsY?R~4+uCwd$+mLIOr|M~5Yw0f4E&LE
zM;u%6#X9RJj`a@Ed~bE!if#^dL?>n2CJzqsY`=d?Hdo*Cuye1)mW%&Pd+p92)q*>u
zeuBH??FYJKA`{)>LF3kvL@jg9;p`>C=tefs2q6EliH-W{;_bvz5x*7bVqu`trK(rc
zs@#!F9N110OHzrb1{K~ue^OzQ;_c~Y;_C2WW&Tiq9X2|KMhn(=Ry%zd~X
z`cAktZSt+%-3zPCCuFQ_@+@nRRg?kvW+@hj3)*LXey-h(%cowX)7+4AGB<5Y)d?-+
zjY%6{=SKi8^1&4L`@^0oV>nYHWD#|#=e
zG`&4V2GisNXD3={G{>7I*UJOhcLk#&i_FjTEXB+}*4LPYm%NWhhtmgNmGGaJG4Jvr
zhd+b}o-el2jMzs{J=9cNTT-NNud2tJ4VGxe$9ZTD@7Gi>Z7)oyvz8l0?PlJu9^qBl
z)Gw(8+#ja(wed*ZT(8xBR^N#-PU_dC6YlWmXo_+W^hEu|b|=QwA%T7eaPxI{_
zi@f)HnHLIovUQV$u`@=uiArO9*vps9ys1F68U?|tQ9S;pWuLUqT{Fsg>ncn+7hVgs
zvtV0ETdoP{foL_D%kAv_EOE_OgE)y`q5AyV>xgVdSylA<1zDt4X}B8CJukQu(giEc
zptf#X>Km|XZAAjQO|n2#FQ9C|0=UNV}$hn)bD
zwPhxkD{#hs|HZ2AE3u6_BBxBw!)Y7qPHY*`iX834yF()fW7>wj;kc#EvwgknRkWH=
zA1+DbqGbq)97u@xz-cH=iR7{xgb;8C(
zRU(q(>axPv6tN`9({x`Z0Ca0rWclR(N>fnOVgOk%2vmYBgC%cUOdYQhtBZIa_+b
zm%`V=+Oi{~x-HD0F0$;~achICB}!uo8>gf@cZ3lodcv0>28kgsgIT%KJ*dsR=_q^!
z|KupR#%%leFcK@o+FJJk$sD>!Rv(@X-u9%iERp2{2uD02V%?+ji5o6;Ck#D;fh%w)
zMh+I5HPh{|y|Q?=39176s8{Q4;j{r0O{;T`>$csBf$3r=+;yd%YeL1th$hud)1|zN
z%bb-jvr4DJjP{pmo)jvo{F>_SgS={*O&PBqhHsps18HViyqMe{0VpoH
zp4Kdb67KmT1wkwZ^>#2`cN6`C0YvcMg^ivcXDnD=Hq3aDomBObV^`GhX-dTv4&;5M
zs|hCFu{7ruK)}XVW;Tj)AOu7N=xMq64|QX$A8`MyfGBp$bGxcuJ)dssu`*Uk&|~>T
zS1EHkNfL^HC9a2j=Kj+QQbgMDj{?id=QqnN3xrny_>RL4rQs+*pr4KOavHT!)I
z>iiP?j(v|E0~!`9qdOR;ZLGb3MRKOL-xl^U%xFM61Ig}G*zaCn(p*&(Zjvhqs(pUw
zqQGi)&b(8dp$U58UB;8R~I&&42{5Ute%pW5hMtDB%75!
zb}7x8-y6=-87LkQjpLhJPcV(cDei4Ry80j)(+3ZnC`vO##r>yb-iFTJKJQ5d@IL~y&z?nb$~g=0
zXH-TNmbe9gXJT^}AX)qJ$s2=L@|-L0REfYK;=ov32?HIS8z)x5=T~eI6bP;4clwZM
zw$E87!8MsF!@QjfS}(aL1*&;3?X==ouzolaLa%l4N8I?<_=0?pyqlH>@70h;k~!BeQmL!1Q1jImiui1mjsmBJarip)
zf_Wcaj9-jm?aLPGi04=Kz8gD3Yx_#Vgwb9QS?Rlzb&vIu;XraDoJlq4@;K8=1BCxJ7latPmPPJ2>`BTz$)@A
zWgN#@MA8}|`%Oe45pN!fws6hOidf~tZ|tk)q&BwR^N5LhX{4$Apa~hYAHjRxs6C)1
zH#nZq*i@BqV%x)_)!SGb>qu83XtW?;8n!0J!TK>S^;oJST4FNYQggOjFuL28Y%g&k
zFvFs)e!`io=Obf-yr>mfwqGi)9S6wmCzG8UNqafB?}?fYsHxGU2w3Gt(}my-URWteM*N9=<^YZ8rc{j$qmNn6-XPWy`JKA!MLMx>_r*^dCZPn
zJpxdhjc=K}H0n+ggD$)=_vIk5-t@W7dD^chbTr-hIxcO9s5HP-uIxk@lO!SYtCd&&
z&SFS+uLL8f#&`Ff^H55)+?^ALB^Zm{t&o-Bxhj^&030B$EnfsM^aK@hocK`>6B2z(
zp?*Akw)=kXDq)xq
z?2TzKKYC@YG4hVrU{LPxkY(MaYN_*?aNS16uQTvyXktQRLR_I+@#|xoX7%}nC1Eyq
z_bpTRkAAPIi)Gr`mk`0D^xqGB2!B2TV69oRYy5ysAVtQFQ`K9Qr86TxB7PHdG<^V<
zza6I?(=Hay?kq*+Yye@qi$`Ae#u1riWaZI^(|FVCelzP*Fe&x5=^@^V;XXdgSo2{$wTOOA0gj9FB;yOOx?ieS$A(^LV_k1_=)!C_8}93c
z_=~9Yo2a<_&Ip5G$|3zW<7GP4LLg^Jn1q0I+82cd_i;B_|i4{
zi%axMBk9Pu<1E{-I&%IQo>IPBc`GOUrU|ThR_c&LqP%Dk`=z7^RgH7JS;sxwD-jR+sOWzV}yG`s(zE9~^CEz{I
z8RDG-pOza|D-BGV)tyd8)Sfg=MYrZl;bj(1s>+%*QG{(f=c+n5xW>uXuC%u1vHgla
z8T}ZrVf#s#t#I#qd7x8^F)MWxcnEuuU^Rgy0?auOqabQ)BjmfVdilB)60~+iy4tm2
zi{5AI&9<0{s|yP!W%w$8o67CA+tujXYws+O?+Rd1<<$bRNgwdQZ*?JGPOGU0gaI0=
zk+Y5<=-f1lg+xz;4rGrGIS$Ufb;!pb_T|dF|LkkTA}PvJ)=;qjoW$(r1xH(A0iyd>
ztcoi4=xew_mUaXgq$rWT2UPrZF^IGme&&x#jm455ETz`KuNt31WwhgwJ~e?Ujv24B
zwnreHpKGr^q-B4RQd$rW%*%t^&KR@qtUkf1~0m)X1;IXB2r8Rwl+0G
zWLVPmTtCJh0VdMG+{GT6?`Zy|G>tnCNu+j5n{#dy;`I=$VmFMa6q{DMx@Pkl6t+2W
zQ{HT+(@HS>#=K3i^a+~jZt^MPWOrk9e6f!AvSLkp--~>4sgh^$Y3KWs$Nc5by@-zG
zqdyD7YW3r!7RV_+zU(rlxzrKZ$^Yf}v
z@_vc%SxCJ}oYH9>Bbd42v`^T7{z$h8jCh5CRkjjM$;
zE0*tZMW&OmDSf(y?H>eQat#2vUG(|(Hj7=7Pgz?F!)$12y>4Pf%SxS!F7zy>qBEina1Y=)>CHE14RITbU)(A~T{{_3P&D}EQ(s=+
z%5|q6y}lC!oGP7>f4zTz(_<04#1rQA7BR#Tqj?_(WX=%7EX0X|M7zVR
z=9ikjWWTRVc!ECD_Fb=At|pF8*`n?x?V>9&S~wnX&y|V&VyDzSI=~0s!iV!Dz&znH
zQPaN!_uYVPjjlL3KSDhc%_{jl)1)xcT5sGXB_uL;UaO^BY_X~|>x4N7|NPFY{g(}=
z1E(OE(y>M{sFGj7E`b%p>JhL;@nS)eHP;cpsIOtuih8GzXyBaGm+_)JWEQDI6s2L}
z=-2u*!Hu##w?o~aO00MUOmyPrXse<{@p^fH$5p_23dxWT!N%U+?r7?!v9;$K)_ZB~
zHSlCvUFaRzhMZ*zMa9oE?*wBex*;l+2)Me#a&Y95Q=hJ=M}FI3##p_eOf(q^hfpkj-VqLTR~UgGlpL9doHYPWnKsti%Ax$Fp|i
zeA-W#tAT6t$GtBWu#boG7P%g-uB>+Cn>Sub!KGrRVItbeI|)jqxidsvkc4YF)z!uI
zKIa~&Q;NH?!ibTU#c{3mS|On=Cwkq@>4~>nASoq8k!V=;y#AL~k18bh$_%9EAU)z+
zrx@gP4`U-NX-hV-Vv$^1WP}K;CfaF^z=!(;+un?C72^?|(CR!U`ogX9szXpydP81A
zg+|LMe55ad{S|=MM|oS|lC|3?U3B>Vdn=*E3itTJqST~OLu0h|v~iMFx6$c@P~@8`
z_Ks^6JB2HW{=wL@+3ppRs78jhXG<4H?u-5T7dX&Nfm^7jgUL02w3LaVlFX
z(BO#HTkDp_>)FJe%B{dIxlnVm<*?FhUqZ6DzXsgmC|tE<{CM2<9=M#wAJ5cPt{fuv
z@dPUveEjeYS8Mm`c~lZznBZP9}RF>fMmbYG$F=#zxe7NO&uk$zbm6MeSiX4!MPD(CJj63TiSc%!%|iV2q(yA!0qkp9
zBX5Nh4I)tvN^_X~DSVpka@dpEgRm2|Zo#ykZXdoAl_vSn1ri-8OSdnKLHx*Ti2MV6
zXTwgDanfIdMqlVt{n}31b{)Gxdq9iMvpx~)x&@O))Dg^nkJrBI(WK^-7PvlH4K|3f
z?Dy3l_?FSD8OVhFF^cMJLo{KH+UC)_omG
zimSKWG7!w^_({8BPxf+@jQ{Eg!cY!+dS}4W)@(dUN0RD%e=f#X=5a4j&c^TB`O&gs
zx(o8tkUttrlSH6=uy2Mp;WKONC12Fn^Y&gb#_|m`mw=JQ-i>;)UadM`1-DWi(N#Y7
zL%qiOb_&2sQ)s89MeH8
z-F;UN`(b%T%mPxLTQ>i(ESk7?1MlI%KBF9$j=axyH{Ggz@T}X)35p;a|(S`;v-+^f$lWG&IzWzi?v&zJ`J4&q=Cdq;g6k@w7*J$8Y+;LfCGdg9kO4x6%GAn9~B
zOK@w$aZ@MuuAo(E-rT|-OR)sAU3^1LvX)fM3aQsn4QY%AB4uiXT8^9R<(K9YtZwK9
zhpvkyck{zUIvTB%1|31HX7?>U7V$zw!EN@@Py_+daU|P^Xf+JscbAt3_T0pFUc-Yw
zvJ`T|ggycph}-w%t=!)9LI1^!{9wHIb5Z#e%ughWMDmN};Nk<4M(NFl)84Io~E$z>Y=Tt6ec9Kx@<5MIu(G$FR1gOKHmv(3~-i^}EH!M{4Mdpy(
zjrKZ@PM()rHA9^9F&x`nR_DGaOqE8?M@afUBoR!Yka#8y#O=6>{ag!DuHMw2eUm+P
zcADx!UrmQ{JMb1mXJL3sQJ(DZ;i&!R`WW{$clp8#@$Ar2r`s3c>PV+0628w9TYPcb
z6{;lKiAw8>=o~RvsXmi9^kKLBUIJ%UUKt0)>ZbmiTG$hPcxc=DCAr9)Zx!AmSz&%I
zZhC7QbVFX1?{>2>DG^rcltiOmM{-{~dP%&=hJAVkFnJT>osC?;3u-^aS-hhj+pIfA
zCwwlvVp8gCbSA9mQR-|l9uiN=Z7j!S3KZ`hTlEYk`k3$8V|67uiIudH!6UsxJP&2)tR!nWiY
zMg$8h@(c>i>X4X_^v)G`6b9ODX<(EP5Vk^{q=_aPKSe51%#uZAVY1QXw%QcQkhY;&
zMUMldhW1cw10$MqF{+ECJeliFDz=vXyf!!AQjI{DaqKh1M=sPxbB{OrDpmq7L|@E@
zZ)MK7-#FUEZV=1Q>`G16+d^|)VOH_lsHBorbQg>?ncjW5-MTy7ERZ+44!!EOELnJd
z7_KT)lGN9b;4L~K(=GWiA&LX-*BU-m;<0s-)zq~|hSLFgE
zlMh#95@x^$uJ7acl4$rju1mD2g4OtmN^PIt0gt1q)@~1^R=ag6%nrPyvx~HHSCYG#
z*-&iRt~7cFjIM|5KKNN@&O8jiSp4>DZC`(PHnnizY(Z{XSCi?|zBYMx`$PDp+wq`9
zI_2b@$hy!G+Nxfc=l=oXKpnr~`L1;xd(E`6p8g3{8L@J~)tc@gq(~`9VNLEQ$DfzsK7n6WzBMrNi@fH4wb>VAx
z^!-aky3{AtZ}pIn{f22^R?^;G`(a=8h}%ghNMj=89tiXgjCyU4fV=~3eF>W0;yq5n
z0`antW1jLjq#IZjI+I&(Z5;W#oKI@$2FbfqZ?f
z>vnN?W^WJpgG*)7w7Y!*SWchjMRholr7Vc}WoW{XKZge(3i-?9$HcD?cvIv50E#pl
zKd|Zgc9SbZW%D!$i13vT
z`A|0Tw;TdHV-@5-8+5q!@7g2c6xRytaGoO6L&lN@*#7`(VbtSyR>2s~-@t7;m(cm%
z70O}t%C&2#%3U3j()wtXuhRXD*gS9ImDIMbq()0m_e*&k%FfcPZ*L2Q>-UwE<$CeR;MBLt3D@Cm%ko+b7C6q_@-fFwc?Z37y14%U
zK(O2yLqtg|09MX99@xcXkI;UhhyF9-Yd-yi7qXi2=?X+
zCAX6~UaZS0UV|Y9N#{LhhyEL12|QaI+O_-3;Tesgxzpj6OMf%UnnGnHt40*YV>}iP
z=Yj(o=6~Rt9~Ytc1@PD5?}{$ry8A3%F!2<33j*#h8-0=j7oT!K?od`lgz^^0j98J|tQoNtBfaDWI>9jLp;
z)Y%^(4htL+xC-6I`m?~J#1t^eP;!%$Rh_n0y6>a%^k>!A-XXlT)N~8|H$gI3KBaVT
z87yuS?Fk*c{{XpQ*>V^CND}sB
z*yD151Z7k!kjEpbQY+-UpWAE2R(f5dN2T~(zRPnh;{O1mKK5xm(&389oNko#AmLOJ
zan8TNkK2FD)Ni!k7%r7#rMx#%S>5S+OEtxu<;z5>yY`6kSdeqLWl6y}Ql}%c2gNul
z)4P+3wVyVd^6Itnew&|3_;
zlBcGBk33(mX}Uj%?xEA#)vRPO;UsT`+07
zbas}GVk$)B{{R^vgDy8SaIL^>6))Mn&Pnk$4p*ZZk7uh^S}irdRNlvTC%Z01OjrtsXYhW;$-x|d9I>VAT_>v^NQn{;f4D~xW&GtM*Df-ozlDE!AT
zsV7}j>u5jxmM7F7vDDgpU$e!&n_~*Wd8hcI8|$`oZRsq!cBF_y78{ppNAmD~@H`P+
zWuA%ssqi1fO&*VZB++Q)e%5dQ0MYGs_%mGiAAqx+e8&8S;&wmC!qfKiN^193w~~JgN3{5c
z{wseQ+8MO{PR=-Wn}m%nZzY)AZnC;f=-XHnAiIF1g;Wcb#utga&||gn8sAT$>6bCj
zs@;hmMh`Sho+Y&;xDl2lp%DYPmRU~=g01qU*Tqj3K(6KW1MVS>0){!*MR7H;Ev=GptP`v{72ar(VjKKu4IN{Kjaw+!QD|bDs0z
zmbEvBEIc`Vcc3?R@^#1@2!!&S7eRrnYOkvHebKs4jmLfz4j4Mm&&2*N(
z7bVbb{7Aa&B27a>(;%JYS9uop|BU*9RNodk``L(UC
zc5rw{M`5g7N8#TD&e~M=aLpWP8FKS#R~7^y^1fn^Z@i8PS6pyKWBBIRO89s1`$yKM
z@Q;P%wbkuxuA?^IOE4EnJB2^H8D#Qs-i4HcdBt0A6HRULQ^W0VrRcJKuTHtTlH2Td
z%^au9uxu_R*nfE=l_ZP?L;NI+*{<#3@K=c}+exvWD<2P{M<}z6XH;mf2!HjN3$?j|D4;pGF
z-@{gS5$GCBbH}M^){0@Vi2+f6Xxq05d$f`Rz&|W~KJoG|+P3RMz4*OnCFINDwQUyK
zM}oq~d}W?{mS)-?QOHre-z
z^4QNGPx5~{?mhua9R57MM)LAJH?89z#kWelJdFK%0meNmmy1mBEJcU>CAW&JA4bw&
zKDhh;0L7oBb>9xH{4?MfwNDUR>spqevuN6_mA$w2c}9`$EoQVs_p%esxKWZZ!vV-3
zd6A8s&q{_4YNB^qd82DkxzoIR;mb`PZx(71={lx`9-n-`#T>Q)tZ!nKSAa-CBd_<5
zm~dH`8u{b)diW8g{3Q6bXW_j!#2zN`x5M2cV{xQtb1GUp-rQTnX7gl>43(XBZX@MY
zETE7<>-Eou{vhz~k0s^Bi!FpxPXU+CPnn^fC}vy+Co3fJuK?$EKqH#aoRVwe58E^12EFk|UDdQ*HZ_kY?K;GV{a==T&k=p3HGJ%(3
z2WK(Y{iJ?5>z*p{EIMYD9oDhqj}=Sh*jvKEoi~5WbJ!>YAh*gkvl0UH$M|dE2Z}Tu
z9roJlT9&PMBxZZD1dL>nplgWLGm=!rx<5!j{m@F*)rZT0~YL~w)_ooN8i%B)2_+z3d{CD_qVc-uI>AGEn3l+Nf
zb3(af3O79R=@ydBDfMQR*@?#`&V4G!!-+3^JE;k+ZmulnWC$m>oW~#;UI|hO=N<
zYtud}_$Ng8rQ%y1N^N^s)1}iqKcv{|wzB9_v9XrdOt*!DxFC?;LpaFkgUv*r2<>3e
ztTjIl>L1%ycMW)j{>W{f*jvR6k}(W%fU^UiP)A&6@1=A3vlZ~Q!#*ngm~?*w>em)C>ro_{w3ZRFwdLF^8{aG_%a)JL
zMcBAMBS=XklBea#{u}Gw8II+yw2P}*H1i?4^KIMrTN*TwzZ`98qf^ssN~0i}_p3b;
z`{94=r*(OArPx^bn$|d{hf|it(^0eAsK*(Np9CoiskE^HqnXngjArQ3lUHYtM;5Tv
zWzQDv7T%Z9ey?O>_@_Yd*TqkRo-WiZye8fl)Vw1+fh0>~1Xn1RkXscSi1R~=D%Byx+&4vgI8A4^x0PB!X$R_w7J->+f_q0TL9$sYz|tx?}r~Bw13(c_Knl^NMq78x6)fp
zoLX7j1#=Cx{4+b2Y;Thr`!5?tIHyAiI&1f`=JV6;I={EDxrKE+4jxfX%i(s>JHBm~
z-dFg+@ksa&_C}k=mRgpy+TEO%fv%o)XqjI2C}hNV+sdt~hJGOYW$@m;cc!!dpxjH?qwZ=4Nj%lf7GxMn4L{(!Mn=v->UHc-Aivc#$=0cIkkpe$N^&hd*X}j|M|;rL@|GjQ5vw2}?8GT*~(n!4eJwA##dI+6sf5aZ}5P
zy47?HL(0`TS}yjLwd>RFK3&rP0BKEoSh#B)UB9(7+pX&?D3Qd@NFZUAa=2m$a13n(x>fRgIKePNyFRk>&@gb5~2bC+u3S1ca0CG+?uWV%G*C+cs{2X70wmPr;
zB@1t&OLeO0`hB(8jV|Yr99*+o#gM=>jT|7c;XnlEZ#)lyz2Dz=;P7S{U5Q1Cs~ygGv1tfJpj3xhq(R}vrfeM`ol
zH(iUjp*8P682$k2t?+HUKjHgkxLrG5pH9<*k>*`n!7bdxmu3nGW|u0Xkf7(56y*-*
zZ0h2$@RTFe`Oo4uso@(x259;phGEqwYa5H3>x=D05X~b=I&<~Z_?7Tm#9s?+ZFLQD#jJ**F-vdXuF~oT;e|Y4IPJ&h
zT<(dbNi^`tcI}LC0W2i;Zr!~`(}f8uR*CZRF7wiB>v3M*}F
zjxdSWIodksjwVQ%R|_9dxFBSlXMxw;V>sv9xs7u|nrrYOcJlu5Y=5jL9C7qG{4258
z_}ms@h=Wn5QN=5@^WX11^7Hoj@pSUT40awJ{n^VOu=4$ePVU~rvFqQW@DJ^yec~-f
z>}%J49no#=EuLszEhXh^sfKpM!C3X`Td)LRWLL_XZkIeVv$LO=bSLJ1a(ZO+Cm1;C
z?^-&wyEU`zVvNdmw=5&$kIU;*WP4Qe?7|aYzj9u##_z>{iCUk=2&RfT72QaGRG`-*GTFH-KHh;
zSLNCnixHE_9%J$IS+((B#JkJe8-%!yNG-ïm-0xrboI8qr$UX_evuBX>xGew7{
zr%9&neF3O^Lxq2ynRmYJI>4mZdLxvm6`K5kROCC#SZ_j@ed@HSd
zGt~6elV68gy3{TH*ppdEWD65HO}}>vPRy0$XVi?>6KwYndK5D%W8_qQ%D*Vac>}M%
zJoh;kF639Xg=Bc$p&+7}8_Qg00dhWW=bkb@En^h6JdA#IQxg>#Zo4x}!yZ4^{4uC#
z(Aw)-owlBramvMbM=_|6kbYbP$6utpBd5b_uH2(GpxTz9bD%>3pHq*0
z$%<$eL_#Du*}z5wZHy=&VB_XHNL8RuGjjZZm1C7-&mWEf=suO+d^YgZhUddKRyHu|
z6I<)(8r;6f*zbeOW^PLEVU5I-`sO5y%X4YME{wIm;C&sXX?NCBTwPkjtwz#o5ym96
zx>6$tRJaBS7aLhJbH9<2LBQ+rez&JRwZ+25iwBcA-XlWW^SE+Ga7jIhJ%AtqUte0=
zYqwC`TrQtuv}=h9&js0OBX-o0LLJ%N8QfQljPA)9+TSVM&AR@3jgi@}oLm9bIc#<0
zkVZH;>ygD>J&g0oT|uuilGk+D?X8jD%$Z%vv5z@XgY0_@<0FjcB#~c1f5APiqi-MT
zD->*sH1>5yB<;-c61eu@^Ux90X1p`RmR@`jZB~*+-GZkXZU=q```q>PB-g!uz{~c3
ziPv&8iM{mlhi-hfK5904a(ic|e_Z+5vi|^MsK2_;Q-SI~?Tjb=e2V+pKD@9Sbp~L|
zxj-i;1wNkrYKFNE1AXtimE`e&IM2TvbNJSbTW7!XKJ0{KoF1T){(iJ;a7L`HwSM*+
z9Dp)8_OHu%v_G*U@f`1nqx1YXCU))l#zKsPhUuF4TmA|aX(XQ(G!?h=qi^hC^O2p(
zE+rlDkHhilUwQbF-Z=CoW@Yl#Bz$D_BaCy7ze@NQ{t88ObdQOCA0Btv<&#PwWD{*x
zRi0j%AoG#ioO94uuaMvC(e!_juIhC4f$wC3|7
z`!XaBjEq4HS#nepjjfy>1rHeh-2M^xPvF@u{vP~FnLJUfYIf$}2fe(IT1J;+mb%`c
zF8DFGX$O7*Q<~>>%{yK3jrG;Wp|4L3^~K4a?nq-!y@*C%l#0$7?on}Cu
zPEJ=6Aq|iYU!D}73I70smrCEXx5FI|Lhwzmj&&QWJz4JMd!G);X&thx1~p>r**ltM
z7#SmOcmx*p>wSLe%f}krcMo|!mt=^@q8@{43;?Q0V8zJaN7gDu`<@Va#7{S0h_L4arv;8{P>&AtmYa0ImihKd5F24)ie`a5sFuI_QNRjL!
ziZ)DI?txrJHZT$wA=yYjJ6E=;dnSCQBOt-is^dZlUzhNbYpUvu9|`<*(r$DQi_%|e
z2)d7oTIDSnt!|k-rAb6cxOUjYx~W+S3I|*a7Hj_i7<8MBSK+KSnx&gq==MtYsuMND9~jLQ8Js{LJH8
zdtdMf<+Rjx{QA!S0L|b0jNcLbSI~8I_`7hPA&wT-EUjVF8D+i=Axj5=fp*D|?_e=7
z8P4If3|EZ))uwBYi}HCg!}fSIeIDOyugqR8HrhAs#vMughidnYI^yEzPWY&|8nwN>
z=|Ku@)h$);7Ck;_-B^f^p4ltBCe|`xiQG4@9q|iR@c#geFMNM-sd!6DNqjnwWgY6?
z&lIxV34YBJ1>doX;K)~R%(1ZPoHvQ7Z5hRk$?)~4^3+P)&GlN|P4#}K&e~0t_0F%S
z?wZ~tlHnK4cPD0BuK?%21Nv9qkFUA5@kWNX-Wyo;5ABTIP85`6v#^a!EM_}loXVva
zEI>pbC{_dE{{RRiPvb2)t}cbWymu(l+&UQoF5!|#d~$K$k>0-K@c#hq0pXon#X8lj
zo+R*%vT7gNQD*YuE0m18*!|Y?2m(#7jijmt927zX)5TPh_nDqcmEh=ea;{t3uWR|9
zOZ#p3L+rX1wc@Kk5NP+8o-5Y{t<{yfc|yrx`$`9p2RzDR56}$m?O!LIHu4WPMUpgU
zI~BKmzzHY#eLtVlzL@=@?erZ-z#b^pG<`(Tu7sYmYnFJOZpRcomv#
ze`h^Q!ts5h!v6pep}&UCNj61uZ1K%6HdVpcH_l!hNRRAdo?GHJzKqx1@VTa{Fk
zget49mVc@-{{Un=TdgnPH^ALZ^$S~FJv?u$Ts*VPsTH^v_M>}s+M^uq&IV0-x5qEq
zuf(1e_@}Hx;hz&MJ|B(L*(@?!UPge#q^imj464lI9OD={IVX$wS#RNg7<_E-FT{&O-S6o1E)UuJMfl0${Y7<4{c_Us9X~-ZrKAfg$g=5njK#|jml^6#GJBDVk4gQ6
zd@pq`h(5>SFBV=+qRu5qmqTFp7UDQuug$e%llQ6sW6nXwGHcVM@b;6VctidYOQ)K~
z^4`x+yGW$4jc#5GEjrBH#7yz-^B3$=u#7gt#!d@WZ-qY|ydm)`#w}xEW|lYi*6c^y
zbo+Eq-COX0hYE*3ypqf6DHnmg-FZtd>WX_2zpg___(1hMjV
zmIQ4Lf_j0|p4ES7KLF}pBGa{tsPiShk#g4%MW!@lY7H%`i6cH?3ha=u-UtDK+(>+?
zv=Nb>91{-&^
z3~-|ZlekrgzhTWPJw|BPS6Jh>mLa?QBH(5D@&FXCQaK9DHk__y*$6&he~t`>j%K
zKJm8OnA+an3(UA1W%=W6w+eU!g^%Ux;WVS8JE_A5S`Muj2Nmb!_t!^r&-`zrU3@9<
zHTAu!_-DkHeg|P^Vl^KQNZw=;%N+XyyoG~#w~{bd$K7+r0@s(#`$^wD$c*?ez-co+
z!~;niU9*r6KPwE74so8oquBmBT}7(?&weD;v}kNK2z6b3WJ!!~4k1x)KJ&_XS%%H0
zDi<47M$CN2JU6y0y8744g@Z0t)w$z8bn(=6U_@;VlnhFF;q3B%X=+V
zuGWt2trE4KhoJmTzJ~M1*NYvkzMjnmtIKZ^ZAj#6Sef|uW+xt`)*38qzdVhM5J~Nx
zzm`Db^{U?xwJ9a>_OUOVpJ-dAhBsq{m?y|oobW(U17`=OI#fDWifu1#Ki5MXj5ad6
z095xM{c7l@^t0UfoZ|&AtkkPV-iwsIQ@+mM@Xc&3{*Kpn(nGmd%oqc%GEGaM_#ST-
zcN6&#Zugc|AJ+0Q#$U;C0M5zZLZ8
zU(1nXx4Z>28Qu-Nzc24TPI&+yUOB}TIa<5(Ir5lS`phXSr71@Gc7AKk{-#U*&z?5$
z65Hz$*`Jn>ln
z0BI)cV5o>sGG;O5<hR<#B(&
zEy%zl&3sqlOMm!HbQ_@7zhb=6WReUeqfYUtvPEggI|~^3JIKLOImyQisx8_31{a4_
zxgpG>Ydw6^{$IqW;SU)v!QC_M+V-Jwpj~S=Zxx0U%-o-U%^MZ_v}Xrt0Z(IEn*RXp
zfuZ=@#oG3v9j}CDhhDL}v+}397GlNchSnh@YU!QIEq8)C`MBe5Psx9@&&1!ic#BVt
zHgqdsrPRiVikOv-XEYJG0PJ6&SY78|KEv59pggaSMOFn2LH!ivz*e`=dO
z9>+_X&8%bAE%kfb*1C^Tv6l&Sw`kxFHyxA4IZ(MmaJd-x7Cm!Pl2FjwNjI3Au$+*C
zXvqNlx!$~=UOHyIJK?XvKO6Y7!(&*F!#`@U)vaQZ%2_VbBA>lSGHuA*3U6Jc5A~VP
z7&*$kV6P*q4U^+4%G9HOPnVZ_A6;p`v<{PP;sv(1(_xECwea-1WvnTAr@WC#FOXY1
zh*pm=%Go1!Wg`F+ohJC@9<`)+g4wj`mK{Sww9)OEF0A~-7V%w1h48}w`N}vX?GMo6
zzdZgUXg(+SW#U%Tb*(n;8|bW(^_nuWA%ic6+@ydqj(PMoho*c}X>MCSW1YAwyX6N1
zK7e)h@ARkbQ`HKlSBj?XC1=}DPRHrTjlMp|tJrGScA6dZ8uqcQ>H3cEGQ>qFw`f}*
zEALZ;kSIKU@MQ9F^Uv)S@rvWbpBlC6%ZOIaNxsapM*Dao6bp|p|9$xwRabJrN_S=RTX
zV(_>+)n#d~%ly30qdo_Cu1#OZcCg#EywfytItI1-LV{JY#R&t2JF?AyewEtm9}<>N
z2i!u*J(9_Dc;e342G}>>TPP6WkM4;KiU8rnyte|p3&lUQ6_V>ZPN*#Ht!^~^GHG1H
zZ4I&^ks#c}ET1;ll1wPUDp5e>?csby<3AQfBG|~+g4*i#=El|oaUKkxYmFW?!);tk
z<(@FS?%-seSjNY>Pc7tDKS*>x5nKF7)2(z>T~hMq@5CCMv0x9f`B7`uFEL}hvdXcR
zBy9n=uQ@?pY5Q}0T9W(XX008>W*s|2@~q+g;M&MhT(I{f;E!0;^)<==0Kp}^N#ak5
zKN|c+s_S~a#m1B2J4@*`UR5@h^`X;ufWGabtO^UtDRrD;selEsyqf
z(@PYJ%0O9B;Eb>*U^fJgE7@0BxE}~~=vTxVgL!vWGRJ8ZnhS_r_%}X!Ib6GtLMrwB
z-tMiszG1Qbrls)D?DwMS+76-i8;EsFo0QX~k(@^b!d)cs`DJ{wAD1|fCoFfk7z%4Y
zLH(h8Y2s@=Kf|l4Ml9yMiaU73BV-c&h-uNuoNgGm3ZUnx4b)fZPqIHAtglm3=zoje
zD`>yrJZSYu{6l@IS?RAW!)fmi-qY=*l0m|%D=W&NFftvBlFY!hpV@ZiJKuxeB89Fl
zqmJK8*QaRVkIY947MRiRIQbMx6}NGN8sPDR;yU(=sd(1=RMhp45@^xt32|$s%@VOy
zl@(x)A_QxEh^sYPi@i7H1X-qs@s4i
z074jGoZ}hmQ5AQo#fYZjoZ3FN_`C5g^HkFOSv+^wziZNTyW1$5OE0tBNefA&EUP?t
zJ6Oc>DJ_Hhv{RM?JNn@joR9~
z{{UAc`03#3H6PgP!WNo5GF@s5tErRh@%hq3v0qNxK26?H@yy
z;nAB-no^@E!Y3iXX9&y~?;MQqbI*J6%j0&Bu3Bg$c>MV%
zQMt)%xwRpP9LD1tLX)I0_uZVeJV3(XXiAJ?uM5R1?`^H*?O~F9GPTma7kozXCcSK1
zNo&~e^mKxM;e%8AESU;;LbJ;nft`@mr*^w(Z#%+T0Giy|Yq&&MBqe=zb*d{{V=j)E7tbCC-tg2epUKdu97?+E}b>
z+hh`)4*YNlHS`v>r1)RrC&e8bUW(2+*TS-DP}yfic%eFsuqMbC=HA6EOwt@-bLIWw
zab9jO2~*l$4^Knuct1YN>)<0(6$IrgX?wM1@7sO+k>uJpfb@R}c!$T9z8Qk|PZ8)T
zs(kXtCfLE4NpHSj$M=pRZHh8g7=kbZcvr%|4e35C@UMxrtz%HsEUf%Kkx0VQ+s$bM
zhb^3ujBFgAUc7Vl_JM8T{{V^~7w@IgtY(hhZ2-V^X_M@B@ktbsv;3cYDkbHt#F7XM
z!vx?CXW)m!O#}9O@b0-JdWDaOEPO$x+22Jp(Z{A=*+o)P__^=&foV1(MJ}QF6EMfaCoxCk2!muc~!t;g6B;$~Klb(J5
z08BJLjCa>xwZ^xgn+s;M@Sdf8s6ldw!r_^&3}+-Z(~q>d7#Yf_Cj$ra-uq6~^$kWd
zcW-Y9`iZJPH`nJwXwqeX8yP>=!s
zAsUm(=W(uY;uq|8x?S&wVepol4ZXeQn`XBz_XiW+-A?hKUEOzWX5e8$5^zfA(Y`9`
z+E0W$RifU1X6n8nvsmYhX__;KjsVOhNf-q?6@Z+9#{r1St5=f#)PJ>A_r*^ecz)|i
z({)b<+34C;y}i5(BSkIN$7x}dfsOz%l|1q?I*Q`LQL3>Ln|gLU?ljHvspTHWmi08%
zEnm;mxi^NtVxJgzpGdR5U$DTJk(po@4(iPrED^rxA2~)VoDv2{QJ*{bqwucp;oanL
z-`rT-`Oh+=T0fZ^c~Z1Yz~BN4D`1T01Ey=K_&@QtO||g#)waFjoo2@B8;o1RTH&urt(UZ8ibZ^iySy}a=Kj-L+8TU{eT`l=
z@=C6wr_2G*-C{BaGsV#daSKyk|FuwJ5J+6EqUYpJ=xX7wt%_314jU$mC?>y-n~Zz;+%f_^G7n`mMUj
zV=-l9GWlh~qmT;^x;H2U=L6VRqWpUJNu>BI!}j-DO{&7Tm$OA18>uGTip&^p+85;|
zK*k#bBxg8VZgu@#`zMH}(fVKCUj9`0{
z?ceZE_E|nA?Lg}n*x%)qRI-rDdgDC+JYZuScCQJzYng*bBr_8+~P;;ZUw-isAxTzhr{i^=}21I3t
zAH)Z9)BG_>t=f5>Vyd^ydXvy&)2Bb(d`f{P_O>f|||tPa1e>yyS&m(q3>FgS>I{>G@Zykvn7I=>GsC$>J4!x~HoA(TlI?
zQQ0N5f9T>I9i%F=G06+S=OZ0)-=`wJ*VT24YbfT_By2;uBayc5=-FSFlb@LWeEWRS
z;osSVUh%z-tE@Jm;Qbyw78I6CJFRjk=D1LW%EEH$%)yA-PEmo}RGRlM8GL#0-JYP<
zdZ&l{O|sW)jpXWfSMhGztTOQVk&?U-hTwos2sQdWMSCBO{c4KQ$r0*)9o0NT;tf(5
zB{9Qs5=JJPBHKwZoPgO@RzOD^K*{^vou?V0_=6Rl#C~Lu+N#AoWBpr{EO=G#hw4WF
z06FHYf3=^3T1g^p55*DfI2e{6L5%UwBl0G!C+#or;^JX3@c#gdq`G24GK*$%*b07b
z2*@2l4lE+cHATbiOfm%|T{owh7Z5-fZAn{*K{@i{jwfOVkiz^QZ={n>srrtH(
z(9{fT7y>eifTm7&Gj%xUuUh!W!ae};cBT75_Uf!bv2wfvUrwl7WVt?Yb0^ZlDaYS6nUOe
z01)1wj0~=SPrMVZ+)w*$U-)*<#y$a>*WtE`E$wfvd`Ew4YjkC_%8k-TC)w}_OaN7i
z5zYy(ihpCv-xYim@h*#f;)rd0Nn@w#?XS9|w4JY7*XP-Xgj(c~^mLHsV;6#Omm|L}nO~a6!mj$UZRq
z2k`HK{14$(_{e9p@9ORI
zC8ge%-?ww0gZ7HIzSVqL1;&wm_J0;lbs!0!-3Tv-U!fH1~F#~=(cjM(180|lFkBT?C=
zd~~r*(w8&Wr_T5Oyw5gJme>24O8~><2dMPPvlri4-;pgU=w3PI7&za@yyfjcINs
znZ#=!%-sMah8;8c@sDv)#k>_*_k8#O51FzsM_z;c@lCdGGcAIM*cf*saL4rHu;31z
z<}o&Lh}Y%Z0m$4*<3FDtT8?1qPvKya+sMIu$C6iXsNGtUL$c!^H%yU^RAUFXy;Jap
znQ?pqTfuWQk}&7y=&glp
zaHR8JO&chreocv|Ql)B>if>o4^F5>X7rnUf^_Pqzy_Y2#dyuNr_!ToZy0Fn#OVehnQ9xxKYB1YU=^~dW$!m_kGkQE$_|V$YKohRmaVHR
zySrUId#w(q#a;ok_~-jt_=`=|+<2M|6GVyZ()#o4;zGtI0J`~Md7bb#V3rwfa6IzQ
z_CfIeyRTeBb+23aXtnT-tz|JxY)ju8ZzDcwk^H4OEb24mp1IsR-D|O)D#_
zHjXpkr^9-2W5wDP
zkB7WXHP(})tal5eTSYkg8MkZ68aWT}#PrHrXVNqqa+3p{eb6w~cMmBMi3@NLDpK
z3eO~c6qWuHoDwTJ)zMBpPg{oaN_DDF1yORvE526x@~*3{uXo!0zDn@N#IK8*SA#rB
z;r(O69wgR2-R8ZV?>E{bgg%?7+U?6X1j}^+IQ|gFoDA`Q3_M-&7vYq*vTGjMW>TTaT$TB-4hX?D`aN$Qqp;g+7%V@9N3XD?yS2BGRb+-XRUB?w
z%iGlMeMEQtSCmV@VfEz}a@NwoVF#8UWPEMBONEG(?j{_$9cQsZj{BmfD>
z`*K?wVJ75)9l(6QDEWE%Ra=`2Re_WZyKodL@OtMb^2g)SrQ#|#xuze2a@sQHhc?PP
z^jmc3eti5__~oi<-xNGMs!8zkREo~p2tM5%wt!)ea$HDG^j2WUVN9L>05(5|Ja-=r
ze{2r`_}=;rKKnz{(&{_xTr2oyKlHa>vdTQbk};11&WjNz-H?_9u_NpQVF>dV%T`rJ
zAxO_`kLmva*RRQ65qwV2yes=}UM{Wsoh7_eaBn4B816C`VI`HYTOMi0InH|E6LG{&
z={9iVI7b17Q^eD~-`gkQzKv<&*kcUP=sNzRsS>($OpOf5c#&;PjOAsv8%_u@o(9EZ=f4%cGU&RW
zz|S7&)_-n>>&2chlJ*O4vqT|#Z#`xKm@#D_#yDS;?)gattE-vyJ}&~Wc#7(plDl@(
zrj}OIzxf^|@e{>!d`R*3t*I88*H6?h=f1YF&cuNvk=!ee0}-FkraSSTAozpfe+x50
z_mHHK$(B_c+ar<)&wS_b{A&l}X1jF@XfZEo#tWV@143fn>#F6`%&P&h5v
zXSk@pV{d>^e0b5mDtLnXSki8+{vYUTeWPjGq|(?~>rBn|Z!slO85lWI20mtR2~3ky
zDOmki4TGgd9?q0hSCa3$IS(2B)Y`v=ro6bd(QGd?zdvkuaa=p&oPhlbx!|7M;8Z$)
z?c*e|t1pLRYmKT4CZOua18E#CaB@Zo!32)xn{6h84~o1uqs4C1NvPY&rfae!%JAPg
zZ{4s`epXEKa!<-S5KTM7{{RSlEAR&PTkT3{_3dF?{hHXSymraB;h9hI3=U7P0*l<%
zRMpQ=_!aSIUig=*-0By89y(r?C9^NvWW8;nj$7mm22hr4k-#i_j8)GQ{9y3*hY#89
z#m1o`MiEve-~u_xCj~liGt#`1#6K4GZy1J->S-aj-Ji3@N=Bh@G6x+y^gpI~ZC}SW
zdSv1oHEX9soS67v0XQ7)Jd^31W}I!*n@41iOoQT8z3sw0-W}4UX%t4eh^Y!j-MpOR
zZy5uQ)dk0lA-I|;o5KDT{mW&`NbBaDWRvoo00241VaKPAYd$*FFD==U-e@C{y0ADM
zx}T?SQ&=zJi6^)}YWqdQG5Lmadt<5Z`BCnZ%8!1R06#3{k64C2SB-Ev@0yh>j#c1_oE41EK53t$f?2
zc+*TzwRw;-v|t#L;IlNRDhL}u3yiTOo`csFt#9!*#tTBpZD$;SCPiyE*NF>Cdfh
z+x&I#&E0~-eWiS=+geL|#>ppw+gT4Aay@Z@^r+K{Rw8Si-g^3;>7e*t$5Fb5L*cu2
zSc!@$BGnc}NU@HX$vk!JIp()?kJ{^T|7xDA_!1;GB%`F-6D_O`9)eb$QcCj*BuUhxUTzKZ5QG{hHP|wdd|;L(b88Y>0$!y0~61f
zzk3QeACc);&kq;ym!avu@J>$&pN0Pb@J}BZ>k>!iYySWdwTU!{f=Wcs3~C^LNY3c@
zT*<)X4EL{R8&!H?@_7vSt`q1aL43Rv^FK9RMdm*uLXE@H&4T
z-F!~?7@BOJ0lc}^yep>tvfj!_qr)pqj|;O#{Hqjp=Ylt$hbFmiwcdO_@TZ0~FA-^W
zC&kuwPo_d(8%W)CB;I|?7dz!t#`TaY-@w3aEV&yT2EiX*xv#F|?tBNbjfh`VZBs|QzPOq@xh{M|Z~Mrj
zmPo@95o9fu`;5+qkDCW>K3s8M5_Lv{#FtjFsw{EpbL|^h8IP3@I3%2&IL21Jd4NKm-9EexF$U
z5%?2z@RP>TYtm~D(|CF_b8!K*WE0z!oJg#}iP}~hgkk|8BlNGGz7gn6sQ4l@Pc&VB
z!XSz3
zeWBC|2~EK!`=y^U4mbesPe)_nGYmB=^YZGo`Re}wLubT4vs3E&_PMH0s(qb|l4^HR
zeU?cU2qcnYxHvg*q8W36$Cla0TIGM?UwCrn^UGftS%${#-(sCpq3Usr;CHWZu=sUl
zKZv|VYikqgg|x^f(&3KY2xPc~wcxmo2yh~K3d#cyoSC{DC^*5-vc-QM@-ZM(g>WV?PV
zW1IL9@aIpG`t5D?s|`{+XNKnfHHK};Xy!{P7ytodo7KYP0yhG1O?p?uZ6EtH!E#x~
zw@(rA#-Nt*#!aM6yGfMB5E5E9DYRwV<>Mo8Aag!9&?fj_2aFT@7fRDFq3~=M7nXin
zG&5W_yJ%eOQgac?gy-%B7*Yz3E5jePCAOE~-y>4d&E}$Yi=9Q20y|GF^z&+wY|jI6
z`G^~~j;A=G#_H(X501lNDnf;I$kM)v+pd;wPUpKr;hPT+>YgdnEhCcF-p!ap9qr6#O^WbWhpi`x-dyTU^ua;*wibx{gMW%(q(;<-(|W
zg7MH`jJ63p55}L`Gf()2^R|+MRMKleMVQs3cfAj
zaOpZ~?aNiZ-4?g}4;=lhw7p})f39
zI^y!;`Z#<);@uAZXr;DgF~%Y@vES71U92Mj5sosuajmHMZ~I5Y{wuzVTJe>b)jU2@
z*4b=#L1z=e8Z3z!Y{EyAA>O;B+42GlG?Yu>O2L7l3F7NjScxXx?46Rm`fJ+V4?Xx}
zZCE4gc8nb(dEYj;!(^??t*7FHDknjvJd1QtIGAUrgaIYKqljFHOAMwEW
z%F5>6^HS6!T}J7Qc(+L|B0gkFxd&>8D}#c)GDzKCq46K!)}?Ro!&K93ZoF~gtwD9@
zZf5?}k3ZSS5@ZRU33oRLFfu++08pTxp8Qwgn~e_oeK%2s>~7+4C5l0ZOn}%RpF`jO
z0IgL`D;@_FVyn`crFST+K4*L0?@R5cO)hqR8U3m}O=+jSy@Zw##|eO=C9G=Lj@|83
zo}_GZ@|=KA01S%aJ~MdFQuwptM%DExEluRf96KRF5~OjWMxZG9Mioc4NySmKvxiTG
zql~Ft-!J=TpU0r@>E5$^M{_K8az>?=P&i^o9WoC--%oy(Rz6}_%JmY2rrdfa+eR*!
zCASlKz&G#-6!3B}>-Fc@eQA6oo312vZOX)wPB
z{{Wv}l`n?N$u{MYj?=$rIaxb%p1k9y9qKzCjh`g`M(w|d;qdQ>Z1pRPIQ1y(F5|hD
z)>DmrOI(CM}Jvp0jX!mDfUZ0LR9sd9it!MbIaF=_0uPwKgAh+>g9!F!q{0F(Ec5MZG
zMf%+Dzh+;CIxobJAKcmNmlsj#*4A%ye1{P>cdCL5@Yq%?M^Y5yrF!Ot`z-iQFAg0-
zOWUo@r?un;E6AlXGe%i_*zg%wBN$Lf1vw`*;{O1$?~UU4d+{Jibt#T3n>ir!8t7Z9
z;gx}RBcNpj00Ad&BPSn4cst@;J~;5$@b#_LjokKnOtu#AN35)gaUg}V-bsuwPy=OE
zfjI5J88+^Hh7L5H3r!~VIe&^Dv%Zbsj|FNvy|vu(OJf?1jdcu>DPlH)Q>iP|0Jth}
zPDVJ7+0DE?;|)Vqvea}vYgW2nv(IZSj50_qqFD)@ofnb_C^{3#!5zMV@eht0MDX>U
z*NOb7R%@#W?j)Y>-^)mnEY;qzoIC(6y7NT6^#k8#-l
z0Fzg48Kk;>j>_BHl0xKUFhAMJrI7u)0`%nJ>N=Mky!X}aq_+WCpoP+-W)--F|e8|tts$ENl
z7(F_lr8zD3-a~>*34ZArXU<3Y`h6+>B}GNrtjA~_4>{m}j~>wv#@~e_JPmMfP{0qE6RLP
z_>2Dl3mSbQM$_zc{{ZYgCf7&Bx&ZTt6e*TMKJzmZ&NvttI3)6kr*DCNPv1xKrVc`Z
zjijEr>Uck;euC<>?GyPPwq;q=yk+V9r4z?zX*8KK}h`N@Q;QTVHsa7ZttVPzi8~{jPZJ+C;Ym5;rgyUWeu%Sc|Uk1y06JL4PmhK>$($^+cBd*{$
z1Y;dXIODD=6{eoVQLBreyG_aZA3^B;A@F_M+%tGT!|KvD$CzDTN4s$95888{I`+uy
zGg|s4qu}2S_{UE1Wv_#LHvS>erAh2>WtQ${w~=tkjq@Hs=RLsZgI^%%zqRIv6q7+M
zzPAjQ5{3wDnL$D@4?T_#L-};AeM9!U@ZX0mZSHR@waq>Wu#pzCVzaYnYJ9kipHMw*RC$@$y<0rW4yZ-i~)UyT|)y_nH&8b^{*9;>ulvMfeM^BKn7
zxDCr>FX4*ytuOX|_=g9N{ytqv@Souo%zD+CgF&?xR)QJK);ry-Q+Uk2Xi|YmB23^G
zI38E~8~8U<_?zM{4tS?av9>x5=bq4A>nN*aB#sAi9KRce3Fo@{jMvcGPl8X8(;m!T_>-hXF1>}~%LZua!Z9fj9dQZv_Nl=M}Bq%sp`TUQt;XFJehLfup-<$1k
zviuJ_oAz_@=DF~j;J%R`!%u{=P5rlPdEy(tuv)CzYRzcw@lJPTU@laEz>Ug>I3U+c
z;eXlB##a9TwLit1yWfPr2HQ_(H|>q~j}=_Sac;M8#_-2HkzJkt04#gKRV6@G4}t&$bsik}gYnw$
z#$OveMSbCaguh|7wTdqeSQ#SwJo3G&v&&_+eEE$claTpY8cu|eD^9mQr`b_|W|{H7
z#edl&;wH2I00i*x4v%Z_x4{1Z@RD9@_WuBHI&?|>y=JG+MiQ}?%~;BmEx2QFh-3~c
z%l;btIMw`fEuNoa6gOIgR$}IMo^LHxVvM}3?A$7V7?OD7-oElCxz1O}kMq!!lwF_H2
zi?w5LW0GQ#67g;rEY6_d9A}}&TFy4}K0Ar9bgE(~(SnS5oxR&zSJ%wt{5$(0_}zuW
ze`Z6yuKblla~YCPGT2?mw1fOmklY@*UKjyf-;RD8YTpR_SAC%C*56^)EF~*6JC(U%
z<|76f>Z}OQbg1GWY}n@UN?nIA8kW%Te>
z9SwPx+(IIZ$r`WsLHU5ngN~eb!0GwZk=_Q{%1%?}#~D(2Kad|>REZA6V$Hd*2?UG*
zj-24|d;9yEbaA|qGAtpMF^IyZ6am{keg6OhS={k$sk!ib#S?f2eLqyUSf-xNMrDp+
zx;6*zD`0|hq>iADpo4>5{*C)U>Q??Y)U~#=)2?LHA$Yu>oneR@#<|LXAYBG832>d?2mGu|wYw(*%@!x{AX|-(^P1hN&BZe22Io<8f(}KQI
zF>Jdp$VglQNyi82C1o3*o#j!*;xQ7!;p%eT$?Lb|`y-9gejr=;4(d-I=zbH{JoUMi
zW|n4YwCixuuq?9>WLdYewpobzy>VNgv;P3?sj6#tlj!~+mrc{+)HHFUY5I=GiFDZ_
zf<=O6Daa;yOSGUCLh=#80CnFNeji)u-w1qPrRhEux`$ZPb&F}NY;^cZy7;JVWE>v+7WFUs0!@oj=OE<|gEEZcrw&4G;fYUi&P
zRyIfK94nCH=~iwv5{g=+tel%^^k2%p{+k~_{2KV3Z=g1{rTF8;+JB56#Mc+8qDQ5{
zXB%ixgx_vm;00Y{Re1c#51Q+6-GdPfI_`txj}U5J3b?h_Ehq6MmZ7BSdW>^IZDqJ?
zcL?CN2~m-`a0%>B2EI-355(^ncw_eD_;cZPzHMv6o+1}f>XrjVwUNXr7%w8ov3ZI@
zx&AC+0XP}2tv_ttKSB5_`#X3y#JX38{L5byYEnhv-A3zBx0)#y<6)KwAq~1+@xWu-
zAUHBG+!&1bUr|(fV78Cy&)1$ZtEWb!#R+R2jb##u5yM9IlZ7p6QuKxhRJH8J1>%>xO8mEMem)DnXbu8a+xmIZ<
zE4_dc05i3C7#wu(Ue7xRjk@&6`cmo9G}pGu*&bwyGDdOFr{z-jxigGpxn!=7$3NQx
z!j}I41%GRq{6FFN?lk=+UfM*oYq=&6hgEHx+b!IT7ULa7dhd&tU-(39BxP@zGA3Qx_kQ*h@8jE;HruSoH2x7d6UrHLcj
z%blcfP9tULJ8|0?!St@|KG#1l&myU2*l1IZj(s{={{Tqv--VtsU)n3d*UL4%qH0=Q
z;cv45cKKvsPjiAYq~oX`O7$<=W5AyZ?tf>Ghb`faTjC}E0K^Rpt+n@sf3nH3)1ltd
z`D;GW8!r4E+nJ7Y#xOoB_#xvRf5G1p?IiH(n~VF&e1^8$x;v#Om0^+cjAuOtGt$1C
z_|@^|`@;4MVP>}W+Qq~`T}uNJw#0$CQ1va;WPyM))QZyStxvv7p3OBlbi?q^8a
zJ4+NI
zJmHVc0_5Y6Gsz>?wzzJ0pR>=0wLNAN;*Dd(QEQrYsl}8_0gn=cw7F(gI8(sJa!+0{
zT^Eh~RU7IJDGbs|%;zcw!;A$S7Of*{cM1mRihvxG@*HRGgYxr}!R`1|$l5W`^Ph@74z!ZxwM{ljEp;O1
zM=PHyUWYyZ0E>Cge2UQcE&E4ZXg*$>tVcZdC{X?1o*k!xI&K{X5BP&m#TRU_ZO4(h
z&gi&4i^2XO!RPsAxE(^#C%yAS`7DEXnVevE`qp>U&RR31p^$Kekg&H`RqG?Q*734mYP)8ftE|8c}~LE@3ai|$vptBVW+O>W$ETSmG05CUjgE`uG1E+fMpNl^mqxg%eSZO+JD{rFMNE#&D
z_sAGt-7p6Pb^6vWHr&zFO!g0nz7D_fM~kd%bcSGMtgHfsTJn4F3RyamjnvJe1%G#(J>kRqxLY#te&%mD#yfJyI+=(siF0K`2F-IhEGpT%T+mHy(J9=~5750zp
zui{xe6YvV_P1IHxuI{{7YcxX8!S;o7x
zE#BYO=hRSWi>Ye&8Vl+ZeW%2R*57r!aRX=~Yq=C}F%pN&Tb;y%Cg7)`TF_xqK3n__E*a8eYFN)6ANk
z!x)QN-UbZQ9pHu~3kE93ZUEc@XlXwdJU^#=NVA$vYStCKwY-ioCaUdkGraLWN6-wF|vl!x1_i
zXH-cfwzONDd)(~`Snm5fC{dBPx!{JcDbzn>?-W62aVu(G6_Va5V@Gt<3kezLFep*8
zC+A!eK;VpLHS{&Fk94O%}F=(f5&snh=e(P7orS)8rY?+z9{`&54OXlGUVPXN9tN_Vm4;y8aP
zuHz{^ZEGnltlxf*{EwS_cl#{(m*K^|{mtZ>4Z~R8+u0;AUYQ>1d6p835ZVL(0Ipu(
z@Za69X7De>TZ``tctc#XyuP!zhey$L@cUFb5nbNfkP{>~%M-B9;uTMFNZR|WfC*}%3R|N2?e5c^O+Q>W=rrc^5HkxaA
zY+k>YBv30%n)S*nF_07cw0Doi}p56Wwnh!LpH2!Y;79i
zAG5-S7q&Z4ub2pgGUFYA%s39Y8OBH?ZejF3^zGc>
zt(eCOqUpz3#XH?C?{1F!x8#0-$2Oq;Bk=}wxYd_ZjqXrJ%p*wPfwqT9gDzWP+)H!^
zfC*2F{{U$1d@seldg4oTw~6kV{JpzMjtb-)h2V^ixftNr6h0v9&?wt=c(BI)V=79)
zS;z`ljGjoqB>g$*SlZUFcdA@m8G}tEj?W`Ioy>c)f3#1pT2ayJaON45vDB0~ZLR(!
z_PXr5{{X-@^qoyLNV2iCYIdAs034p25A*odEpj(iW`8r~f0@ACc>ojZ`Bc6Mhh>b?
zXLpvwZUp3!p8R(2)~$GfmfFd@&zquS0|&lw-@i{&R~@d;0;E)G@<(f&o{?zRF|)F$
zEKl&{437Oz0QUTFDo+X8nU-zaO6*d&(s8|yP1JFPM7tt~inNT|jji&eXRb06
zJY;9CGwb~8oQFxbeHuh&^D~@$p1>R&4o6SKbQ!Ng@g12ueZ%33=awp0cWzH4_QpMZ
zx#aY?oN01=p%)n#Bk{-o09&>`v^8xC!Qwx5{ZR*m^yN)I%VuU!qiG7ngMt7ZxF3g3
z;}x6Yy)`6{bFq0Dhku?$>4Cri0K{Nq;Qn2YgbK~4eBoJkE2wd`&j6p-q4vf(sy-!v
zBCfA6k@^u62E7tWPTLayEV$lJ0!SzFIKa2m(A{;|+}T$zevwPPUfM_W$Mif{%#UcToXeJktFh}y=L@b^w#V^EH3=xzK>c^$+NJaV^?WxE?fGKB&B$1Hao
zk8n1wT@QN$iS~|8QnHIp`W|cXH^7#9exCQ2S}va~nwFs@q_<5B8=2S5IZ_x&kP<#z
z07+rM#e7+=_{B6$LQ7I+c2<%w%Y_mZ3R{flqc10qn-%s~iatGQKNGbLA4#!>_*~7e
zeWa|b7nQM|LaNN9$+&OnyKfoBNzcT867E@iQE#SAYcz2~dvQBUfUMqNfp!9U1OyzO
zGQ*}bS<6is^_e{iIJ&o5#OS;wDR=7vj%)h3r}xd`4^J4gVLi~>mq9}{?*$p)3SHAv*(
zut@&s&sM+V*WaEN(!3ww4~4%D{6pexYVHxK>7Gl=JP)W`Fp-_6P)6XXvR$Dz
z^xQ}-lTpm0sqE$%Ej<)vXx%ow1K}6LUk&(&!xL+9_9mS>Jf6BeAlLnM?fcSb%n;CPwV!4Wxy}a&v+`WA-%hMd!rd+FIkpI)0aZ
zH-{|lZlZlp>@5wfO!2siFvpGGI{cuL123_!l|Cu{%Dy4^z3~b&p)IpVdn~gpk&$3n
z%Qo$b&GO(3<0q#>)K}CWvcJI%L&6^wd?}*%i&Tb7i#a2?Z97lDYnyv1VjGnkZX@1a
zH7&Py9a|)Y!!T2Ld9Nq=9h@_U$=zx-r#o7tT1$Rwq_@{rk@q#kAta3MTq~~Z{{X#{
z{vTSgt=oN}o<(DT26mpn=byxO^rGctGqXm$)DC?yjCTJ3CZ^SaFmT+mWpa2@a8KYd
z_N@^EiTyg%V+TiODfeS_+D_Bc^8WxLzcfGKv=MoB-T_9D5msC6rbEUG+jr~F<;8lL
z9+{0VpZ=218;K))vaiek07^%z=vEVW!$rBd(c*1F3wS=!Jod5q$rMY~*se~|lahEG
zbLiV`DoJHkk92I&fKdFP0(s6r&piHB^wxp!>Td=7AH>=%#+uq^hTzmK;Hm!X-c3HGi0bDzHF9ZZHWs0PL
z)czfKI___Po*>ojWVJ=Lo=bVAcDwV8Q$(>cLL)v|-m;W!>y55U5TsY)Ozq1y!w$}PwdR({Z^L?UJ)Fx#%
z`NT@$WJGs^8m8O3%2qO`g
zT*yvF;s+oA2OShzwU4FYww<);`m>d}xxKZLYk8uQ6_P<2Lg4LjxMil
zJ5%_1WAP6A;qHT}+fO#1bE(^#wT^!v%CXu=a$KMGGsh?91D>8OH-+^`)h`!R(q?ZZ
z-5OXYD!IVG{qA%3LB>Z5l52nC6^Dtm?Ki;kYI>!-%DTO@mg7ybk!H4$5SZOuyOsk4
zoM7+>&oxquKFL`pbbhsHU$ftbJTI*HPr;gP`sw;j?Y*X@XBMO4DQs-*p5yH@NqHoN
zUA{(+IPzD3Ny#;a{ym5L2gllzYF-_aPWXSQ%cf2f;#7t$MdP{=%+~v@2bjBx%as`@
zcXi^oKV{uQ`{Me1I`J>WEla~U9w*nV8rtVe*CCTdx6$o<(CKsgvl!c%WGV*Hk`!?p
z1&>nrQ}6=!;5Ut8icJpB!up1>J|hbG5g2XFT$~
z`dH$jm*J~(PH~m*rIB9N>r&QyN8sH*`&UPj^WsumJ-fHW?Xy`ZVDgE_*#jcJ{ouC^
zf_ofB+TN|Df5Lla+UAvSAHzX4)zol&QG~~S%Z6ov#i&UnbyaPd-b#faFaUb=e+&Ky
z>E9MU4Yr}C_%(ItEbe2|ZQ}7Gh~5bVaI;<~o=h(qD!D2GvdY*bp~oUV2L8|E!`~i_
zvv^+fMAREli(I&q#I3%{f0`gHBr^dz#F=mjW^@1$S(ym$(%;v}=#Eo_z0#5Ae-r*I
zYrg`#2jQO@Ug{c^<+sEMB({kxz9U5?^0Q$ZdVQQoL&n+201?9xk)Bufb?}~(r+(2s
zDznuWQjf#BTvxG6c!SQCz(*kp?}76I$f|IoJNjn;cK-mizrino*8czpJ`TeUv1ugM
zHjO@!7L%?0w&vi%kwm8AIU5mtrDPaTSxke5RnLihPVru`@bBZNk1aII(QdkyrGH~^
zjT*`4Ms7=BZc;jhV0bE5AdFEZrR03Bc}f^Mu&Yk~>rY+JT>YtkWo-w?@22>V!P?HX
zf8s4N#(gSXH7sO~JO2Q)-tCe?t`(znl66MGVVKvDH!%5DZ35%MvPq}v3HEEvK1m?C
zftgChA~P!kjQ;=1%6H1#0Hfz)^56`i#z6+Otwlzf
zluw+@@pbVyiBzoyo|@Xp-{$o>q?a<4k#{PQw3QsMVUOYI`gEwS+(Q(|B2ucX2`Z@0y14Hj>JDq*)qRxAX&Pz~o?ij(&&fT+!U}
z+GXDYX;&UE)oirOId;!~JT|cT>=jj*g#eJ)9Gdz=_G<87j{FCz-f22~S`MKM&jsN+
zfxWd=4SH;oC<+yIk%Mh@$^sjP8&87#5BMdo{?L9egTuNn*;i1wib>;notD-=Eenyo
z6!U?M0C_$7*VEn$_!F&oci?~ar-&_Py40>0QJl>M%#AI?uVmM@svB~ZD{#A-GK4gN
za859OkD4tcney2_Rfy)Ph*YI@CuuDeyKMXReob3lZ;O8o+r;{Rh;Oy&H3)oBqFB%3
z3%frLUfk?4qG~V`8@y7peBZ*~AQ7-TR3VR(Kd`TZ{yg}9{t_!68fsHsSg6ybYkv<-
zbq1Sot084(2Mk7EA2vA1>&?&EpZ1mTzr(K(>VMgGy5yHyfxEJ^y_t7MrzEo|wOJZT
z3akshaK(>F8#&ErPy2rOgZ5SU^Qd@#;mz-cw7(B(mk?dXklWj{PO_q%@`zl<&PUFq
zu1c`$-qf1+M*2?cqbUf$4pR*Tgg;|wUoDPe|IDyWaStT!GjZ($pME4y8XI8V*dacc)Ii9YiZ|2)qL+5>6f>bx^AG8
zNv5HjEgZ-Kv}6bL1CE0SZ=!ru{iyCVU)p-!7x4#$bxV&OTgua1T-_`ZBp+spptd(3
zH+3`h(#vMmR@U_L5+kYLsrT+k*adUHVB2KKpyIeeN9FM!@
z*^ED~8o27m+Dn>8(pJwtr%r0$7Mpip*UZ@crTkH-cw@r94{x*|5O|i?PrkAiO>Mbt
zR^6>F?V}j-_Q*>Y+`-woIN)Nvi@-ONYMubm?yd~eUR+qgB+nxcGFCAmEXO@qka;=h
z@jhGelfi!%KWN);3|rjzCeF>gJ?12mT3^7?%PfluvBOGsg%KtfoDMR0HRzuWE+m)X
z=7`HAZ6DaJ&d_*ajk%Qc$8Yiv=TwiSdy@-=GJLyw^bAEKN)gzv?(@OH
zF8%ejs==hM9*GFEj2^SQkbHDg6k*Vg#?U1d_chaE@t6;9>U
zN%H*@u&dr4XSvrbV~tgr=8P^6a=;Gb`HBGill`yEUNilXvhtgKdjQWQI+Ww;|DU_jcrWDn0AZ
zHBSTSzZ1W1uMkObVR<{jtzQ`;hES&D+gsdRs6tLRGNYz2a!yD0PpW)L)^wdi;g^T(
zH02ORZS3TdBD*s>q~3Fu+(R?8o3{X?U_~P-mhHo*%c1%9XsG`HYvI*h+@CM1)cA+s
zcY{CSN&Gy%@s_U-+4Y;|`zDcZI*{lHJD(n>-=c&4>f&|Hc1b0g^6E(^nn&L3$0kNS
z{{RzRZ|wu|CB7j1LYZJJx^9-n+Sy8h-wyr$^A5g%SCe?FS^Hh{BA?wrKu|c`dz1b?
z)o;l9nLfjBHCZk$jIuKM(s3AO$U)P0`Sc|F>1a1|Y0=3N>)KoiA>RArXDrzVpOBuT
zK8NwF?+?6o)2lY7wmxSKBS2&e$2kKe`gE?}!rnDHO}pE#jkNn4IUI)FqIt~9c*q40
z0|O%<^WU1d`I(eq@g>w>ES@LPc7`%3YcDf<90Q!ik&syP$F+Np>~rIhsb6Z^71pz*
z-%B(i^3p44KF#GcWQj9`P}x(F)cm#M*ZS(b_+J@#cIj2}8FYq4I4gsXEBbald+U5T
z@yGlj9}{$)Qg0M^YIxzDO~S!q>%JV2>%=1)lOSW)2OYHBxajVEQQ}P~U)ss@VWS;6
z#(yvK`B%@s7`#40NiP2Y^@I{IPbWN|<#?sQ93e8=J|E&GRkxE}p^s-6$MXSrBf`$w~l
zm|{!Iec=Xr@Tb>4xCXi}5?F|&Z@atH9E^Qyn$sW_y0K{%7q?TKU^Yn~k4*NVXma&C
zzYgiQdWNlTA=ErKsY3D#a4od7V=fO+tq{&nuQ<;Y^v8sJDG$Q$1^)nN`D-4fr~`3!
zv7kW_ZhX8Bm?tE3=sODF{{UnUhJ#f@;_XTZNp^T$nA{d(2DAO
zWvY5=Q!iJu7|{Wg`S-R(%a0;Zx>^kKwl+>09*r{;2z$Gn)4lJ
zQS;G!#Y4FOByu?ZUtDJ%^$u5MN>)V=5b7%Vkd)lOa(K==WALtjOlhvK{?!hlq(rf>
zA}h1I%p;yusRVs^r)u)Pr9YD#mg-n#jME7Au18XT&syEl^i!w(pUm*@gmnQLmt}oe
zF7OEiJ|-OG;9~~>dJ|16ocA9miuEfmE#bWI3~b2GvcqK(v_HGS84+X>F~&OArg$3G
z*7M;Mo-no4^x)Qa@#)&Wn-t2@LhcNyD#k!QQw5L%{3S~C0=&*|3*22?%&~Y^!Yb1<
zMynpK2~+oSKhix}aC@Hk$Pn93d^fB|b!*{$78xU8s;jD&1OQcm{prfLQ}2vmXEsvM
z_nia8ep9CCR^rzAPC*5hNQlELaqs?f&w+eo_)Gr)3diDgqFJ)Zqw3Bku$1&wVgZbk
z{76na@Imihf#6M1^y~DoSzGLP#5JHUvIRNi3w_gu7&z7L)?-l278;?J}E(c9`)=w(G5V|y}&
z^}zuBSJJqx20uRMem6qFfnW$5yMfPKbC0cgviOfTF!&|teUKAsp
zm9C+215F*tXzh|XZlxh&^6-+b{FZINhfYA|KcT!wrb%`2D?+up)US+pz9+i4Sk~-*
z;wHG9i4){h-pb5Xm~IWi1^IyZci_*A^`8t$Zylbes9MKsDVp9Ck(xNAAfa%)sA7!6
zb~Da1Ug2Z$bHw_U?Vh1^u4-3$m5iQz6VEY{M16?6w=v6nv4!U&uN<89QI4nO`L1A=xUL89AXx`snof9)NO&CaS*FU|BaXVuJEx#lJS#SvKtf7KG
zi?QEX%{A4<-L?F(nJ-krt>)XH0}%+*3Ua}fNn+XDPd^fPFXQKpG|eu~6!8`J{7Pq%
zTSkzqo?MI{b9}&)pEdgb0C@D`zNFRuB@Rbf~#i*``C8tj2Xcgc{^(_kG@$)&Br1`^&KE5U0V7YT0Lk8La#;
zu`RdS<9w48g_&1w1093q5)*~V8S8K2w}@?YJNXfWD{l&E{{U%`u3=GQ5S7~u-dH~|
z+%~e~=NyneUm~>lhpgWCds?-)_;2FqZ13&W?{2#jTv~jwryz`-WoJR>l!O3hWVn^Ko
zllO*5*rL47Yd9LuX&zb-RH%%MoM-dv`1FPM>Ir?a}KR=!#b=*})vPpR*u-#WoRI`xB81pg0kQ*Fhr}M>e
zrr&MV#@0|&?Hikc*Qextx%?}>zKPb!mA111xHfrXh0i$Sr(b_+;b)9nw2>XsWq44*
zx%@hh@cPn{JF>|>X(ia+@Kvh|89cqr7z|?>T;${QJ!*dwSb6$m7FACzNl*?BPearB
zepLSe1D`S(6_tZ9$KL8e?mBks@ARvB{k)55{{Sr6mz6`#NZ^cPzIqSoQyoyTRV|2;
z^EoREbt85c0SNlk&OB6(fKLZifSoeQ4;9N~=mWJs0MK#gTcMUe?1i
zAS|1{Uc8_FxAW;-u9FAaZSE8mX4+Wv#twPo=z8P&*J7F?K4AN_yN>z^2WGt+!;tzTPTSn67w6KXQbEg-vfh1lw5BJKOn-LY0>QmUf@M)|T?
zepk`7&$C;ys}*9$0k~Dk1I!}TdtomDGaO&?ufbLWp1d@s^`De=?5V@uO+^w~8HLLoF#&SW9Q
z=axotdSDEU1B`V9pDCO6Bh|Ifh-r1NrlF?Wi?cetxrX7ks(io={{Sg18mP!4EJ@*c
z`pd+39s$%mN2lsiYkD=q=rOW?qG^Ykl?Z^w|oY{#?nreo}qa^!ApBT7+q>9E|;sF2THRq3^0wc
zz)-o{o>pRd@CI?qS7G}VXg3;;wX9oN-ASR@H1;+jqPG(HvdK7*pczmD#SF{1kO3n-
zO?oHCf7pWe_OS64j;-Op6zO_~o22WygtwAF2uM|=h^mC>(<+3|LGs{q=PKORvObbH
zc+{FzUWX^~ANC^9^nU}`-DzGf({6QJmx3mWTgZ%iWpN(RLIS@#uTzW$JXetTr@~iX
z4g5^nJ^a38&k9PWHF)#5WDTq`ryPzCU&6lH_@VIM;m^b0gb71b_~SLzo}q86+xamdxr~ytw$YXkz&!QB
zs3#Z$2Qz`GQ9D%J`EEYSa52NWxMcKK*S@9C*~`HiZ^SQ&_Bw8*YbC{v#Bvi3?<;d6
zlk+x4FaamAAaF)O?7kjp7M>RUsx9p8V_0qNH7AB13gt%NF}tAWI6k%IUIy{Tr||d2
zHuqLh+x?+a$tGy`DN+iMd-TBI{{T>X{{VwtB%fdS?V{>BgGSd^*T`E4p%l3s0l*k1
zrvL%QdRKNg_%r_i3qLQ&@f3Z&8kN2O0BaY2?%ipBUWeMQ37K1gmQo2nQS0mcs(ohM
z8#49`x|3DXA<|Xh4{mL(ViTxPs{32zxRe0g
z0;zyDfnG9W^X?>A*_bO}C>w(X
zgO0gwoD=u|0EYZ4tlfMY({#1hJVk3~;%!D7Mv1LewBBxHRZ!X8<_1=fg~FYx4 
\n",
+ " ![\"University](\"../common/rfsoc_book_banner.jpg\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "
\n",
+ " 
\n",
+ " 
\n",
+ " ![](\"images/system_overview.png\")
\n",
+ " ![](\"images/data_frame.png\")
\n",
+ "