diff --git a/tests/notebooks/test_modeling_quantum_types_and_variables.py b/tests/notebooks/test_modeling_quantum_types_and_variables.py
new file mode 100644
index 000000000..1bfe6e6d7
--- /dev/null
+++ b/tests/notebooks/test_modeling_quantum_types_and_variables.py
@@ -0,0 +1,19 @@
+from tests.utils_for_testbook import (
+ validate_quantum_program_size,
+ validate_quantum_model,
+ wrap_testbook,
+)
+from testbook.client import TestbookNotebookClient
+
+
+@wrap_testbook("modeling_quantum_types_and_variables", timeout_seconds=60)
+def test_notebook(tb: TestbookNotebookClient) -> None:
+ # test quantum programs
+ validate_quantum_program_size(
+ tb.ref_pydantic("qprog"),
+ expected_width=5,
+ expected_depth=5,
+ )
+
+ # test notebook content
+ pass # Todo
diff --git a/tests/resources/timeouts.yaml b/tests/resources/timeouts.yaml
index abe05a78e..5438cd14a 100644
--- a/tests/resources/timeouts.yaml
+++ b/tests/resources/timeouts.yaml
@@ -186,6 +186,7 @@ min_graph_coloring.qmod: 1800
minimum_2vars_example.qmod: 10
minimum_dominating_set.ipynb: 1000
minimum_dominating_set.qmod: 1000
+modeling_quantum_types_and_variables.ipynb: 20
modular_exp_example.ipynb: 100
modular_exp_example.qmod: 100
modulo_example.ipynb: 30
diff --git a/tutorials/basic_tutorials/modeling/modeling_quantum_types_and_variables.ipynb b/tutorials/basic_tutorials/modeling/modeling_quantum_types_and_variables.ipynb
new file mode 100644
index 000000000..345df26dd
--- /dev/null
+++ b/tutorials/basic_tutorials/modeling/modeling_quantum_types_and_variables.ipynb
@@ -0,0 +1,725 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "0",
+ "metadata": {},
+ "source": [
+ "# Modeling Tutorial: Quantum Types and Variables"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1",
+ "metadata": {},
+ "source": [
+ "This tutorial walks through Qmod quantum types and how to use variables of these types in code.\n",
+ "\n",
+ "It assumes:\n",
+ "\n",
+ "- You already have the Classiq SDK installed.\n",
+ "- You know how to run a synthesized model and inspect measurement results.\n",
+ "\n",
+ "\n",
+ "## Setup\n",
+ "\n",
+ "Through this tutorial, you should import Classiq before using it:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "2",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from classiq import *"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3",
+ "metadata": {},
+ "source": [
+ "\n",
+ "\n",
+ "## 1. Concepts: quantum objects, types, and variables\n",
+ "\n",
+ "Before anything, it is important to know there are three concepts we need to understand:\n",
+ "\n",
+ "### **Quantum object** \n",
+ " The actual state stored on one or more qubits (e.g., a single qubit or an integer encoded in several qubits).\n",
+ "\n",
+ "### **Quantum type** \n",
+ " The combination of the quantum object and classical metadata. Which allows the synthesis engine to know:\n",
+ " - How a set of qubits are used.\n",
+ " - How to interpret their state (e.g., a particular set of qubits represents the number 3,125. How does the quantum algorithm knows this? Answer: By defining the quantum type correctly).\n",
+ " - Any extra attributes, such as signedness or fractional bits for numbers.\n",
+ "\n",
+ "### **Quantum variable** \n",
+ " A named handle that refers to a quantum object of a given type. \n",
+ " Variables are introduced as:\n",
+ " - Function parameters.\n",
+ " - Local quantum variables inside a [Quantum Function](https://docs.classiq.io/latest/qmod-reference/language-reference/functions).\n",
+ "\n",
+ "Once a variable is initialized, it is bound to a specific quantum object.\n",
+ "\n",
+ "| | # of qubits | Interpretation | Example Values |\n",
+ "|----------------------|-------------|--------------------------------------------------------------|------------------------------------------------------------------------------------|\n",
+ "| `QBit` | 1 | Single qubit | Any superposition between $\\vert 0\\rangle$ and $\\vert 1\\rangle$ |\n",
+ "| `QNum[3, SIGNED, 1]` | 3 | Signed number with a fraction digit | States of 3 qubits that represent a signed number with a fraction digit |\n",
+ "| `QArray[QBit, 4]` | 4 | Set of 4 qubits | Any superposition of 4 qubits |\n",
+ "| `QStruct` | | A quantum structure that may contain different quantum types | A single qubit in one field and a quantum number in another field of the `QStruct` |\n",
+ "\n",
+ "## 2. `QBit`: the single-qubit type\n",
+ "\n",
+ "### Declaring and allocating a single qubit"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "4",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@qfunc\n",
+ "def main(q: Output[QBit]):\n",
+ " allocate(q) # q refers to a fresh qubit in |0>\n",
+ " H(q) # put q in superposition"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "5",
+ "metadata": {},
+ "source": [
+ "### Key points:\n",
+ "\n",
+ "- `Output[QBit]` means `q` is uninitialized at the function entry.\n",
+ "- `allocate(q)` binds `q` to a fresh qubit in the $\\vert 0 \\rangle$ state.\n",
+ "- `H(q)` applies a Hadamard gate, creating a superposition of $\\vert 0 \\rangle$ and $\\vert 1 \\rangle$.\n",
+ "\n",
+ "### Exercise 1: Prepare $\\vert + \\rangle$ and inspect results\n",
+ "\n",
+ "**Goal**: Confirm that measuring $\\vert + \\rangle$ yields $\\vert 0 \\rangle$ and $\\vert 1 \\rangle$ with roughly equal probability."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "6",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Quantum program link: https://platform.classiq.io/circuit/35eU2wkn0WFNnmJARQp0udsV7qC\n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " q | \n",
+ " count | \n",
+ " probability | \n",
+ " bitstring | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " 1 | \n",
+ " 1056 | \n",
+ " 0.515625 | \n",
+ " 1 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " 0 | \n",
+ " 992 | \n",
+ " 0.484375 | \n",
+ " 0 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ " Answer
\n",
+ " -1\n",
+ " \n",
+ "2. What number does `a`represents if it is `UNSIGNED`?\n",
+ " \n",
+ " Answer
\n",
+ " 7\n",
+ " \n",
+ "3. Does your measurement output show probabilities close to 50% for 0 and 50% for −1?\n",
+ "\n",
+ "Table of 3-bit signed values:\n",
+ "\n",
+ "| Bits | Signed value |\n",
+ "|------|--------------|\n",
+ "| 000 | 0 |\n",
+ "| 001 | 1 |\n",
+ "| 010 | 2 |\n",
+ "| 011 | 3 |\n",
+ "| 100 | −4 |\n",
+ "| 101 | −3 |\n",
+ "| 110 | −2 |\n",
+ "| 111 | −1 |\n",
+ "\n",
+ "\n",
+ "## 5. Quantum arrays of numbers\n",
+ "\n",
+ "Quantum arrays can store numeric elements:\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "18",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@qfunc\n",
+ "def main(\n",
+ " bits: Output[QArray[QBit, 3]],\n",
+ " nums: Output[QArray[QNum[2, False, 0], 4]],\n",
+ "):\n",
+ " allocate(bits) # 3 qubits total\n",
+ " allocate(nums) # 4 numeric elements, each with 2 qubits"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "19",
+ "metadata": {},
+ "source": [
+ "### Notes:\n",
+ "\n",
+ "- `bits` has 3 elements of type `QBit` → total 3 qubits.\n",
+ "- `nums` has 4 elements of type `QNum[2, False, 0]` → total 4 × 2 = 8 qubits.\n",
+ "- The array length refers to number of elements, not number of qubits.\n",
+ "\n",
+ "You can act on individual elements or subarrays:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "20",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@qfunc\n",
+ "def main(nums: Output[QArray[QNum[4, SIGNED, 0], 2]], x: Output[QBit]):\n",
+ " allocate(nums) # 2 numeric elements\n",
+ " allocate(x)\n",
+ " number_superposition(nums[0]) # superpose the first numeric element\n",
+ " hadamard_transform(nums[1])\n",
+ " x ^= (\n",
+ " nums[0] + nums[1] == 3\n",
+ " ) # Checks whether the sum of distinct elements is equals 3"
+ ]
+ },
+ {
+ "attachments": {
+ "image.png": {
+ "image/png": "iVBORw0KGgoAAAANSUhEUgAAAcsAAADtCAYAAADQgF7YAAAACXBIWXMAAA7DAAAOwwHHb6hkAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAIABJREFUeJzs3Xl8XFX5P/DPc+5MM7mTNi2rLKWlLELZKYsigoL8cGMRDLKK369SZKk2zZybtIrjoLbJPXfSfg2bRURERIgg4ALIIksBARcQyk5btrIKTdtMJpm55/n9kTt1SNNOlyRT4Hm/Xn0199xzzjyz3HnmnnvuvcTMEEJsvCAIfsXMiYkTJ56yePHiU5VSU5l5fwAhMy9QSnmpVOrJAW1OZ+ZjrbVXNDc33z6wT2PMjwB8XCmlm5qaXior/zUzxz3P+1rURyOAyQCWA7jJWus1Nzd3tbW17UNELUR0JICxAJ5j5jme510z8LHa2tp2UEqlABwJYBsA7wJ4iZnvdBznN+WPL8RHjap2AEJ8iHwFQMOSJUv+QkS/YuYDmLkLwGgi+gIz32uM+diANnsDaFBK7TxYh0R0BICGYrE4dsCqE4iowRhzKzNfTUS7AlgBYCsAU5VSNwdBcIFS6h9EdBKAQtRuDyK6OgiCL5V3ZozZVyn1OIBpAGoAPArgPwA+TUSzrbU/3OBXRYgPAUmWQgy9PZj5f3O53DjP87YtFAofA/APAJsR0TeH8HEIwF4ATu7u7h6ntd5KKbU7gHcAHM7MFwK4Vik1SWu9XX19fRLAZQCImb87oK8s+vc8v6O13llrfbTW+uBEIrEFM0+L+hTiIytW7QCE+LCJx+O7TZ8+fVlpedasWW8aYy4BcIW1ds8hfChOJBKTp02btrxU0NTU9EwQBH9i5jMBtGqtZ5bWTZ06tZDNZluttd9G/5Btub0BgJlvKC+M+r5oCGMW4gNJ9iyFGGLTp0/vGlhmrX0OAJRS2w/hQ3F5oiyzOPq/Z+CKpqamlwGE6D8mSYO0yba2tk4cwhiF+FCQPUshRoBSamXpz+F+LGttjojAzIM9FhNRDzPXZTIZSqfTHLW5QCl1ExGd7DjOycaYJeg/bnkvEXWmUqm3hjtuITZlsmcpxAiw1m4y0855kCnwzc3Nt0czdzuY+TkAEwE0ALiImZ8NguCIEQ5TiE2K7FkKsQkgoppqx+B53tMAvgMAra2t4xzH+RSA8wB8npnnAxh0xq4QHwWyZylEFVlr347+HHhKSVW1tLS8p7X+Yy6XOw5AHsBOmUymrtpxCVEtkiyFqK4XAYCZT5w3b96qcynb2trqjTHzmPmgEYiBjDE3GWN2GbiipqZme/Sfd/kOgNwIxCLEJkmGYYWoIqXU7cz8BoBJhULhcWPMQwBqlFJHABgFYCX6z38cbscBOMYYcy8zP0hEy4lovOM4Deg/LzOdTqftCMQhxCZJ9iyFGCLMvAzAe4OtcxwnjNatKC9PpVLdzHwMEb0AYAcAX0N/4vpbGIZ7EdHDAN6L2q/TYxFRPlq32qkjkYFtGcB0AI8B+CwRfQ9AGzOfD2AZEZ3med4la3nqQnzokVwbVojqy2QyKplMTiaizcIwXOR53qvViGPevHlji8XiDgBsTU3Ny2s4j1OIjxxJlkIIIUQFMgwrhBBCVCDJUgghhKhAkqUQQghRgSRLIYQQogJJlkIIIUQFkiyFEEKICiRZCiGEEBVIshRCCCEqkGQphBBCVCDJUgghhKhAkqUQQghRgSRLIYQQogJJlkIIIUQFkiyFEEKICiRZCiGEEBVIshRCCCEqkGQphBBCVBAbqo4ymUzMdd29AXyciHZl5i0BJKN/QgghxHDqBtBNRG8z83OO4zyzYsWKJ9LpdHEoOidm3uDG8+bNG1ssFhustccR0WEARg9FUEIIIcQQWA7gPgA3W2s7m5ubuza0ow1KltlsdrK1thnASQASG/rgQgghxAjJE9F1RNTa1NT0zPo2Xq9kOXfu3O2KxaIB8DUMfrxzIYB/EdEzAN5g5uXrG5AQQgixgeoBfAzAbgD2AzB5kDoWwLXxeFxPnz799XXteF2TJRljzgUwB+8famUA9zHzVcVi8c+zZs16c10fWAghhBhOxpiPAfgyM59BRJ8GQGWrlzNzs+d5l61LXxWTZVtbW73jOL9g5hPKikMA11prW5ubmxeu7xMQQgghRlIQBHsy80wAJ+P9I6OdiUTiW9OmTVvrSOhak6Xv+9sS0W0A9iorflQpdU5TU9M/NiZwIYQQYqRls9kDrbWXADigVEZEj8disS+sbVh2jedZtre3jyeiB/DfRGmZ+Se5XO4QSZRCCCE+iJqamh7N5XKfJKI56D+UCGbep1AoLPB9f/s1tRt0z3LOnDmbx2Kx+wHsHhX1MPPJnufdMhzBCyGEECPN9/0TiOga/PesjoWxWOywxsbGdwfWXW3PsrOz04nFYr/DfxNlN4CjJVEKIYT4MPE870YAnweQi4r2KBaL13d2djoD666WLJcsWfJDAJ+JFgtKqQat9f3DFKsQQghRNVrre4noOAB9UdGRixcvvmBgvfcNw2az2SnW2ocBlLLqd7TWHcMerRBCCFFFQRDMYOZstBg6jnPgjBkz/lVavypZZjIZ5bruQwAOitbdorU+HtEBUCGEEOJDjIwxtwD4crT8UC6XOzSdTlugbBjWdd0G/DdRrojFYudCEqUQQoiPBmbmc4hoZbT8Sdd1v1JaWUqWREQzyxrNbmxsfG3EQhRCCCGqzPO8V5m5rbTMzN9DdNUfBQC+73+GmfeJ1r/LzBePfJhCCCFEdVlrOwAsAwAi2i+bzX4aiJKlUuqMsro/9zxvxciHKIQQQlRXdBuvn5eWrbVnAIBDRLF4PP5LADUAoJSaesghh7xdjSCFEEKIaluwYMEbRHROtLjj0qVLA1VbW3sAgDFR4cKmpqanqhSfEEIIUXXNzc1PAHg2Whz38ssv76+I6DOlCkT016pEJoQQQmxa7i79EYbhZxSAPctWPjTy8QghhBCbFmZ+oPS3UmovBeDjZSufqUpUQgghxKalNAwLZt5VMfN2pYIwDBdXJyYhhBBi0zEgH26vlFKjowXeaaed1nqnaCGEEOKjoK+vr6tscbRiZjda6G1oaAirEZQQQgixKUmn00UA+WixTuG/l7yz1QlJCCGE2CSV8qJa7X6WQgghhHg/SZZCCCFEBZIshRBCiAokWQohhBAVSLIUQgghKpBkKYQQQlQgyVIIIYSoQJKlEEIIUYEkSyGEEKICSZZCCCFEBZIshRBCiAokWQohhBAVSLIUQgghKpBkKYQQQlQgyVIIIYSoQJKlEEIIUYEkSyGEEKICSZZCCCFEBZIshRBCiAokWQohhBAVSLIUQgghKpBkKYQQQlQgyVIIIYSoQJKlEEIIUUGs2gGI4ZPJZEa5rntcaZmIXk6lUg8PUk+l02k7sNwYsz+AnUrLuVzu1nQ6vXLYAhbiI8QYsy+AXUrLzHyb53kr1qXtum7bYuhIsvwQGzVq1GgA1wP4G4CV1tq7AazaoHzfP5+IWlzX3c4Y8xYzz/M8b05pPREdyszHAKgB8GnXdXcGIMlSiKHxDQCnAPg3AMRisb8BeF+yNMZ8GsBlWus9yss322yzRD6fnxot7s7M9wI4bdgj/giTZPkRQERnpVKpJ8vLjDENRDQPQKO19m7HcT4B4OIgCN5JpVKXA0AqlfopgJ/6vr89Eb1ShdCF+FAjogWpVOrEgeVBEHwGwOEAzgKw2cD106ZNWw7gKAAwxlwGYPTwRiokWW6EbDY7oVgsLsvn84VkMnkQgHFEdH9TU9M7pTrGmI8RkU2lUm+VyjKZTF1NTc1WLS0tiwYuB0GwJ4C9AbxYGlZpbW3d2XGcAwEs1VrfB4DL42hra9vHcZxJzPyutfax5ubmrnUI/7sAbtFad0TLC33f/ySA6QAu3/BXRYjq6+joGNPd3b1ZS0vLktbW1klKqf2VUq+lUqmHSnUymcyompqa7Xt7e19Np9N9pfL29vbxfX19K1taWt4rX+7t7e1NJpNHAqgtFot3tLS0vJfJZEYlEonPKqXGxGKxBxsbG18rj6O1tXWcUmp/AElmfrG5uXnhusTPzBMBbEtEi5l5tWQpRp5M8NkI1tqHlVJXua77LDP/kZk7rbVPZ7PZ3cqqXcbM88rbJZPJYx3Heb5s+XjHcZ43xlzOzI8z83xm/lsQBK3GGOM4zjNENB/APcaYX5faZTKZOmPMPUqp+wGkieiPSqk3oqGbSvYnovsGlN0LYHIQBMn1fzWE2HT09vae4jjOQmPMlY7jPK+UupKZHzTGXFqqk0gkdncc58W6urqdy9uGYfgXpdR3y5bvcBznN67rPsXM1zLztY7jPOX7/gmu6z6mlLoJwDXFYvHpbDZ7YKmdMeZrjuO8RESXEtFcpdQTQRDcti7xa61/qbU+m5l/MwQvhxgCkiw33k5EdMbEiRPriWhbAD3W2sYN6EcR0XvFYnErrfVoAFlmbgawXRiGO6dSqdFENBXAqa2trTsDQG1t7XkAdrbWjk+lUvt2d3fXM/MpGHDcY6C2trZ6ALUA3iovJ6I3AaBYLG69AfELsalJAHhDKbV1KpUazcwtAM5ub28fv74dMfMkIvrfiRMn1sdisR0A1BDRJQB+lEgkxjLz5gBeKW37nZ2dDoD5AH6std5Va71TPB7fjplvHsLnJ0aQDMNuvJ+nUql7or/fCoLgbmbeZW0N1iBMpVJeaUEpdYu1tgnABS0tLUsAoFAo3BSLxeY7jrMzgBeIaCyAhOM4EwD8O5rRelOlB2LmcQBgrc0NWNUTPfZmABZtwHMQYlOyUms9s7TAzNcSUau1dhcA63UMXin1m1QqdXe0+Jox5h8A3tJaXxuV9Rpj7gLwSQB49dVXRwFwiWh8JpNx0+l0bvr06a8DuHT13sUHgSTLIcbMy4moZmP7sdauBADHcZxSWSKRWFksFlHqPwzDn8Visa8y8+O+7z9HRI8AuFpr/Ze19Z1IJJYVCgUopRIDVtVGj/3uxsYvxKaGmVcAwFBsnwC6ATiDlI0CgMbGxp4gCH7IzJlkMvkNY8w/iOivhULhopkzZ/5nCB5fjDAZhh1izMyDlA3cqIZES0vLkgkTJuxGREcqpX4FYDcAtwdB8JW1tZs+ffoyAL3MvOWAOLcGgN7e3jeGI14hqimRSKy2bQJAsVjckO1ztb6I6H1lqVTqJ8w80Vp7PjO/wMwzYrHYXwHQBjyeqDLZsxxmRLSMmXcsL2PmgXt0GySTySTS6XQewN3Rv58YY55k5sMB/L5C83+if2p6aTYsiOgwAM+k0+mBw7NCfBi9BwBE9DEATwD9F+hwXXfUxnacyWRiAJBOp18FcBWAq3zf/zMR3ZDNZjcvnzEvPhgkWQ4zZn6QiE4LgmAGgGettUcQ0blD0bfruhcbY/qY+cZYLPaStXZ/AJOY+Z51aN4B4Grf988F8FcAnyCiM5h5xlDEJsSmbtKkSa8tWbLkZSLKBEEwylq7leu65wLYsWLjCmpqarZ3HOdWY0wWwN8dxyEiOh3Ak+uSKNva2vZwHGcbZt6NiFQQBJ8DgO7u7gflx2x1yDDsxvl3aQZpSXTy/rOl5fr6+iuZ+SpmvpCZb4x+xZ4D4B9lbf6D/j29VZRSOQD/KBQK+VJZLBazAP7BzMuiot8z82QiujYMwyeY+QIimuZ5XsVJPlrra4koRUTfI6KniKgVwIWe58kEBPGBZ619m5kfKy/r6+sLAfyjWCx2AUBDQ0NorT0NwDhm/iMRXRCd5nWjUur1UjsiWghg6YCHeBHA4gGPuZSZnwKA3t7edwDcBaAFwMNhGN4BoKiU+vK6xE9EDczcSkSfAvAkM7cyc+vo0aM3X4+XQQwh8n2/NM6e01rL+XXDJJPJKAAY7Bqsw2XOnDmbx2Kxd4hor4FX8Ck3f/78+NSpUwtrWl92BZ+dtdYvDkuwQlRRJpOJpdPp4kg+pjFmHhGNH+wKPuvZz2UARmut5XJ3Q8wY0w3ABWQYdsSMZJIcyFr7VWPMIUT0Qtn091XWlCjb2toOVUpNBjBu2IMUoopGOlGWWGt3NMZMBYB4PH59NPmuokwmk3Bd9+sAwMy7E9GrwxmnkGT5oRaPx/PMPJ+ItgGwDYBwfdo7jrMDM08hIgCYXywWlw9HnEJ8RD1ERLUApgBAoVC4ZV0bJpNJh5mnAAARPROdNiaGkQzDCiGEEIMoH4aVCT5CCCFEBZIshRBCiAokWQohhBAVSLIUQgghKpBkKYQQQlQgyVIIIYSoQJKlEEIIUYEkSyGEEKICSZZCCCFEBRt9uTvf948CUD8EsQjxgWetfaylpeWFascBAL7vbwvgkGrHIcSmQClVSKVSN29o+41OlkTUDmDPje1HiA8Dx3GmA/i/ascROYiIOqsdhBCbAmZeAWDMhraXYVghhBCigqG+68hlAHqHuE8hNmlENIWZD612HGtDRI8z8z3VjkOIKjgHwKiN7WRIk2UYhrNaWlreG8o+hdjU+b6viWiTTpbMvEBrPb3acQgx0owx/4shSJYyDCuEEEJUIMlSCCGEqECSpRBCCFGBJMthEATBwcaY/cvLjDGHZ7PZyRvSn+/7B/m+f+zQRLd2xphbR+JxhKiGzs5OxxgztbwsCIKkMebrG9pnEATTs9nsFhsf3dr5vn9aEASnD/fjiMFJshwGzHwCEX2pvIyIzrTWHr6BXdYT0VZDENq6OHKEHkeIEffUU0/FAfysvMxaOw5AdkP7ZOaJjuPENza2SohoR2aeNNyPIwY31KeOiHVgjDmRiJ5n5iOZeQdm/mVzc/PjANDW1raXUuokIooDeCiVSt2slHqTmams/acAnEhE/2Hmtx3HuXXGjBmvBEHwTWvtg0qpEwDUF4vFS1paWpYAQEdHx5h8Pj+VmccDuNfzvBuj7igIglOY+RPM/BQRQYiPqtmzZ28dj8ePBrCYmY9XSr00ZsyYS6dOnVrIZDKjksnkGcy8B4CljuNcN2PGjFcAPNvV1bUCADKZjOu67tkAdmTmfymlelOp1G/a29t3tdbuzswhMx9JRI9rra8CwAAQBMFnmPlLAHLxePyy6dOnvw4AbW1tOyilziKiGgDbAXi2Gq+LkD3LajmTma8BUCSiN5VSt2UymVFBEOzoOM6NRLQQwD+Z+WsAwMwHATgeAIwxXwRwBRE9Yq19GcD3mHnHqF4jEV3OzG9bax3HcW4AgI6Ojpp8Pn83EXUxcycRnR1Np4Yx5kJmPhPAvUqpUQAkW4qPrEQisS36zxf/RnRu6sldXV3nA4DruvOstQcT0V0AVLFY/FzUrLm2tnZMJpNRyWTydgDjmflOpdQBzDwVAIrF4p7MfFWUKP8FYJbv+8cB/cOrzDxTKfUHAIsLhcLdHR0dNXPmzNlSKXU/Eb3HzA8D2GakXw/xX7JnWSXW2lRzc/PtAGCM+ZbruuOZeXsADhE9mUqlngRw/SBNpyulGpuamm6N2r7vWIvjOP87Y8aM5zo7O50lS5Z0ZzKZWDKZPA7AK0T0z1gsBma+nplPzGQyv3Rd9/wwDCeVzo81xgTD+8yF2OQ9obX+JgAEQVCM9vgA4OMAHgBwj9b6TwMbJZPJA5m5Vms9AwDa2treUUrNLqtym+d5jVG/4wEcCOAmImohohYA3UqpJ6y1y3p6evZzHOfTAG5IpVLtAGCM2R2yg1M18sIPj7y19n3HMJh5FDPnBqtMRCuZeVQul7ufiK5g5uuMMW8aY9oGqb49gJcqBdDQ0BCi/2pKMWvtBADbMHMDMzcA2AXAn+vr67dm5h65kIT4qJg8eXIBQHH+/Pmrtk+lVBxAzxqadBPRKACw1k4nor2Z+SVjzMPt7e37lVe01o4HsGQdQ+mODrUAwA7W2iNK2ycR3es4zjIimgTg+fV5fmL4SLIcHi8qpfYoLyCiPYlo0doaTZ48mVKp1E+01nvEYrH9AXzDGLNLeR1mXsTMewNAJpNRAJLrEg+ArlQq1VL6l8vlLnVd9x0iGtPR0VG6uLAMwYoPtYaGhpCIlnR1da3aPq21e6F/G1mrSZMmPaW1Pj6Xy21FRH8Ow7C5fH20fe8ZbZdQStWtS0xEtJiZf1++fa5cufI5AK8T0Y5l9WT7rCIZhh0GsViss1gsthhjLgfwT/TPMF05ceLEB9fW7qWXXjoxCIIGZr4dwFYA/pPL5V5xXXdVHWZutdZeb4z5muu62wKYUCwW7dr67enpuSWZTDYaY35NRPdba3d1Xbdu6tSpZxtjrsnn8zf4vn8nER0BSZjiQ85a+2OlVGcQBJdaa+NENI2IzqvUbsmSJbcaYxa4rvtqdC3gG8vXa63/GQTBQtd1HzHGvIn+UaB3K/XLzN9XSl1ljPkZgAKALySTyVSxWPy14zgP+b6fQ/+M+JMBXLpBT1psNNmzHAaNjY09uVzuAGZeAGBzIro+l8t9JhoaBYA2pdTjpfrWWl1bW/taTU3Nzdbaq5m5nojeDsPwU+l0Oh9NKPg5ADQ3Ny8Iw3Afa62JZu29wsxLo36aisXi66V+mfnMyZMnF9LpdHHChAmfYebfMfNoAI8Vi8XvA0AulzsPwNVE1KeUmgrg5BF5kYSoEs/zriKik5lZRZ/7z5Xuc6iUWszMs0p1rbWPAmgHgDAMz2Xmt5h5HIAfa60vBQAiOi8ej78HAN3d3Q2O45xFRM1ENAvAUgCIx+MPM/O8Ur/M/CcAvwYArfUfwzA8moi6iIgB/Ki7u/vJlpaWRUqpzxJRTil1n7X2c0qp343IiyRWQ77vc/R3Tmu9LkN672OMeQLR/SzDMNxMjn8Nr7a2tr0cxzneWruIiPYG8Emt9eGIpqCLkRddSN2PFqdrrTeJ+1n6vn88Ef0+WrxYa31+VQP6CDDGNALoZuaCUuq7zNyitb6t2nF9lBljlgMYDWCF1nq97mdpjOkG4AKyZ/mBE4bhW9baPqXUHkT0QiwWOxqSKIXYJBDRc8y8AxFtZ62dKonyw0OOWX7AzJo1600Ag82SFUJUWSqV+hOA1U4rER98smcphBBCVCB7loPIZDJq9OjRO+fz+a5oT25QQRAk0T8hZnRNTc2l06ZN6x3KONrb28cT0TuNjY1rOgdsg82bN29soVA4Umt9QyaTcceMGTOusbHxtQpttunq6lqRTqdXDnU8Qqyrjo6OMblcbvy4ceOemzp1amFN9YIgOBjAp5j5Ua31/UMZQxAESWttved5S4ey3xLf949USi1KpVKL586du93y5cvfS6fTg56nDQCZTCaRSCS2am5ufnk44hGyZ7mabDa7heu6T4RheFE8Hr/TGHPZmupaazuttXsDQLFY3OjX0hjzYOkcLQAIw/CKvr6+/dbWZkP19fVtQ0QXAEAymTykWCxeVKlNoVAwtbW1n4tivXTgSdlCDDdjzHn5fP5xImrr6up6wRiz72D1giA42Fr7K2butda6g9VZz8f9ujHmnNIyER1GRPPW1mZjENE3rbVTAKBYLF5cW1v7ybXVr6ur24OIrgaAtra2fdb2vSU2jOxZDmCtnQrgLq31dzo6Omp6e3ufzGazuzU1NT1TXi+64PKnwjA8n4hyYRiq2bNnbz1r1qw3jTEfSyQS761cuXKMUmoXpRQlEoknpk2btrzUvqOjo6anp2cvpVRfd3f3k8lkcgsAU2pqaia1trbalpaWxbFY7H9isdg7pTbRRZV3VEotbGpqegcAfN8f7ThOTaFQCOPx+F7M/EwqlXprTc+vvb19vLV2J2buK5V1d3cvqK+vX1hazmQysdra2v0dxwkBvBSGYa/neSsKhUJToVBYEV3EYJ8wDHdtbW3tqqmpeb2xsbEnim+C4zhLogtMCzFk5s6dWwvgB8y8n+d5S33f/5/o9IyTyutFV+f5ChH9IQzDW5PJ5GvR3tnbm222GeXz+XG5XO6durq6XZn5Y0S0dOD2PXfu3O2KxeJEpdSzK1euXJZMJiczc11ra+ukmpqaZUqpe6y1/yrVj74r9lVK9a1YseLxdDptgf5tNp/PL00mk5OttQnP8x7FGibkZTKZUbW1tfsTUb78xgnxePycrq6uVWcZzJs3b5u+vr7dlFILwzBMNDc3v7xy5conamtrTwMAx3EmMfM+ra2tk5RSec/zlkbfN/sAsLW1tU8M9SjYR4HsWQ5ARIcB+AsATJs2rZeZ72Pm1W6tFYvFTgeQdBynFcA3rLVHxePxPxhjHgLwYD6fPzIWi10fnfB8dj6fX9jW1rYPAPi+v3s+n3+MiGYwc5vrujdYa0/q7zY2x3Gc1vnz58eKxeLv+vr69gQAY8x3owstnxKG4QNtbW1HA4BS6mRr7f2O49xurU0x81PZbHbCYM/NGHNeGIZ/BfC/SqlVpze4rntwoVC4Cugf4nJd929EdEEYhilr7VNKqZMAYNSoUZckk8kje3t7DwKwE4CzHcdpDcNwpyAIvhedA/b1MAz/aIw5cWjeESH6FQqFvQAsLQ19xuPxvwBYbdvs7u7eipmPAXC04zit+Xx+h2KxeLPruj/L5/PPA/iV67pfCcPwUmvtqdbaXwRB8KtS+yAIZodh+CcAU621f3Nd9/PM/AUAR0Sf9y8WCoVDmfnnADBnzpwte3t7H2bm88MwvNB13VszmUwMAJRS99fW1t5lrW0loquMMYOeVjR37tzNXNd9lIi+F/37fNnz/lVdXd1BAOD7/pmFQuF+Ivo6gBuUUg8CQCKR2IWI/gAAzHwagEnRd9O3582bt00+n3+UiL5DRC35fH7BRr8ZH0GSLAew1m5lrV1WVvQe+q+m8z49PT1zARS01idprVuj4nihUDheaz1Ja/1nrfVnPc87pVAoNBHRtaWkAyBLRD/SWp+qtf4CgHM8z7sIQKG7u/trWuuTyo/FzJkzZ3MALYlE4tNa628rpRqUUh1l4SzM5XKf0FofC+DmMAzfdy/Nsj4uKBaLB6dSqa8z86A3u83n89MB3Ke1PsbzvFMA3DCwTiqVuhPAkwDSWuuTUqnUk8w8lYi+pbU+S2u9LzP/ZY0vshAbILqn66o9rOXLl78HYIvOzk6nvF5jY+Nr0d11fhttn88DQHTscget9f/TWnd6Plv9AAAgAElEQVR6nnd4PB6fFobhqcx8/Ny5c2t93z+Amb8yZsyYA7XWZyYSiT3CMHwAwDUAbog+778uf7x4PN5krb1Ja32G1voYIlpeW1t7Slnc3/U874uxWOxzAE7BIIrFogbwZ631MalUqgHAajdhnzt3bi0R+cx8mNb6fwqFwglreKnmAliotT7J87wfFAqFowAs0lqfrrX+aiKRkHvWbgAZhh2AiPJEtGrjY+Y4M+fXpS0zP1eaEBTd9eNCAF+OxWJLmXlLZn4geowpfX19/1Nqp7V+Y239xmKx3QC8WBrGTaVS/w6CYJtoghGI6M3SsA+ApUS02om3sVhsTwBPz5w58z8Vnsa+RHTVujzfAS5n5r8aY+4HcFdPT8/PKrYQYj1Ew5OrvrMSiUQcQF/ZlbHWiplXTfIJgmBvABczc8xxnNcAONbapFJqirX2/tKP1Wi4stcYs7au92XmuWXLDxHRfgCujpbfAIDGxsalxpg1nRR/ABHNWduD9PX17ayUenN9JxUx891ENNMY8wQR3aeU+jmAf1VsKN5H9iwHYOZXmHmH0jIRjVdKrffxt5dffvn/AfhsIpE4SGv9hdKQTfQYy2pqasYN9vAY5D2x1i4HUF9azmQyCWZWEyZMWC2JM/Ogx0OYuRfrdtH1FQC2WId6rJRadVxFa/3jeDy+E4D5AE5zXXfGOvQhxDojolcBjC8tO44zPipbb8z8MwDtWutPaq2/imiPlZmXKaVW2zaj7WrQ70trbZfjOPVly2OJqGuwh11LPL3MvNaJSLFYbDmAzVDh+s3W2vfF6nneq1rryUR0CjMvDsPwnkwmk1hbH2J1smc5ABFdDyDV3t5+TxiGEwF8sqam5hvr20+UnEbn8/ntgyDYgohOYuYnSo9hrZ3d3t7+3WKxWAfgcM/zLgPwmuu6/88Y82wul1tcuoD6pEmTnlqyZAmCIDi1pqbmj67rNgO4uaGhIQyCdbv9ZDwef7xQKGxvjDnRWvuMUuqcNVS9lpkvMsaERLQdgBMA/H2Qeq8x82fnzp37Yl9f30qlVArAr5RSj1hrFzLzGqf0C7EhmpqangmCoMv3/TOVUrcCSFlrr9vA7vIAxmez2QnM/HlEPxCVUndZa9uDIDimUCj8LRaLHUFET0dJ+fO+7287SF+dzNzk+/4Cx3HGEtHpAI5dn2CI6A4A3/V9/3ml1K4ADsGAC7U3NTW9FATBS0EQXGStfSQWix0/WF/RtaI/3traujOAouM4exKRUywW73Mc524AKQBrvfmCWJ3sWQ6gtb6RmW8Mw/AaZm4mohPKZ7GWpNNpRtmH2XGc14job6XlVCp1NzPfAOA6a+10AL8H8BgA1NfXX8jMD4dheBURtSullgEAEX0bwAwiuhj9783dhULhvYaGhtBa+yVm/mI+n7+DmesSicS3AcBau4iZVw2pENFCZn7fzD6g/+LuSqkTAZyjlJoL4DFmvgMAlFJvA7gvev63ATgfwB7W2qUAbrPWln51P0REpSGgC5l5n2KxeA2A7YkoD+BSa+1NzPza2LFjf7ohr78QaxPdeePzzHyLtfY/8Xj8J2uot9Ba+3TZ8p0AVu3tWWvPB/BFa+21AGoBXB2GYW9TU9M71trPW2tPjcVivwfwWWZ+K5FI3AjgaaXUdUT0OaXUm0S0AAA8z/sdgCsBXGutnaeUOi+6eTsA/Ckej5ePAK02BwAA6uvrLwHwTyK6ylr7OSK6EsCrUez3hWH4NgAUi8UvM/NrRLQzM18CYBkAxOPx5VHCRUtLyxIiaovFYlfGYrFvE9HLzHyS4zi3AriAiL6STqf7BotDrJlcSF28TxAESSKavHLlyoV1dXUTo+R3hOd5GzTc9VEgF1IXIyUIgr2tte8qpd4DkGLmrbXW51Y7rk3ZUF1IXYZhxfsQUa211k8mk9tba18FMEMSpRCbBmY+nIimRlMTFoRhOKtSGzE0JFmK94kudvDZaschhFid1roDQEfFimLIyTFLIYQQogJJlkIIIUQFkiyFEEKICiRZCiGEEBVIshRCCCEqkGQphBBCVCDJUgghhKhAkqUQQghRwUZflICZRxH1XwTfcZyf+L4vd+AWHylElKt2DJUw86G+78+tXFOIDw+l1GrXyd5QG50siWhU2eI5pcQpxEcFM1+0qX/uiWgfAPtUOw4hRlLpZhFDQYZhhRBCiAqG4tqw5bef+R8A3UPQ50g5HMB5AEBEv2fma6scz4ZqBjCl7O/FVYxlY3kADgAAImph5kVVjqcipdTkNdxze5PBzLcT0RXVjmN9MHMHEW0NAER02gfxHqnMPLHsjjT/BNBazXg20gQABgCY+V9ENKfK8ayLNwD8aSg6GopkWSz9EYbhzR+kW3QZY2oRJUsAz2itO6sZz4YyxpyB/ybLO7XW/6xmPBvDGHN66W8iujOVSv2jmvGsi+gWXdUOY62I6IUP2ufbGDMHwNYA0N3dfWM6nc5XaLLJMcbsW/qbmV/3PO8D9R6Ua2tr20ep/sFIInr9g/J5MsYMST8yDCuEEEJUIMlSCCGEqECSpRBCCFGBJEshhBCiAkmWQgghRAWSLIUQQogKJFkKIYQQFUiyFEIIISqQZCmEEEJUIMlSCCGEqECSpRBCCFGBJEshhBCiAkmWQgghRAVDcdeRjTJv3ryxfX19dT09PW+k0+li5RabhiAIDrbWfoGIxhDR09ba33qet6Js/cnMPAYAmLkbwPOe5z0KgAHA9/0zADzred4jHR0dY1asWFE7a9asN6vyZMrMnTu3tre3d+ve3t43Pkh3eWhtbZ3kOM5XAXwMwFLHca6bMWPGK6X1QRB8hpl3BQBm7lVKvVZTU3P/tGnTeqP1R1hrx3qed2MmkxlVV1e3TVNT00vVeTabhkwmExs9evQ2hUJheXNzc1e141lXvu+PVkqdzMy7M/NypdStqVTq4dL61tbWnR3HOSJatMz8ThiG98+cOfM/ABAEwY7W2hM8z8sCQDabnTBq1Kg3Sp+Vapo3b942uVzObgrfFeuqs7PTeemll44F8Enu90BPT88f0+m0BYBMJlPnuu6ppfpEtKxYLP69paVlEQDMnz8/vmzZshlEdJXW+o3Zs2dv7ThOfqQ/k1VLlsaY/QFcBGAKES13XdcJgmBud3f3T0ovYhAEjzHzDlETS0RPA0iVPvjGmL8DuEZrPdcY83lm3qP0AR/m2AMA3wJwJYC3mflUIvqB7/uf8zzvWQBg5h8DeB7Ay0qpGmZu933/t57nfRcAiGg3Zu4CgJ6entPj8fhRAL4y3LGvyZw5c7aMx+OXMPOxjuO867ruOGPMddba75Q+lMaYnwFoKGv2CjMHnuddHa2fB2B7rfVXoy+cmZ7nTR3u2I0xX3Mc55cArmfmp4hovzAMLwyC4JRUKnVzVO0bAPYB8AgRKWY+NJ/PL+/s7DykoaEhZObtEd0OKplM7matvQvAlsMd+6aos7PTWbx4cdp13WlhGBaVUmOCIHgkDMNzm5ubnwD6X3MAl5Y1Ww7gd7lcriWdTheNMV8koutSqdToqP7lSqkfD/cPkPb29l2J6G5mfgHAXwBsycy3+75/hed5TQAQi8UOYuafALgRAIhop1gsdoXv+4d4nvdsGIZjlFL7lfoMw/Chvr6+YwBU7XZxxphTAMwBsNmoUaMoCII3rLXa87ybAKC1tXWi4zjlt+brJaIFhULh3JkzZ77d1tZWr5RaZq3dt7m5+XFjTMpa+0Rzc/Ptwxl3JpNxXdf9C4DNAfwOAIgocF23ce7cuV9sbGzsqaur29xa+zMAv0D/LR83cxznSmPM17XWN/T29ioimhKGYScAxOPxDiJaAOCnwxn7QFUZhvV9f1sAdwC4N5FIjNFab6mUOpqZv1VbW/uDUj1mrldKnVZfX781EU221v6dmX9ZWh+LxY6z1v4iWtyFiD45ArEfBeA8pdQnPM9r1FrP1lofAeBupdTPB1S/WGt9diqV+gYRfYuIVv16CsPwSsdxHsxkMgkiGg9gbDabndLe3r4fRlgmk1GxWOyPzOwWi8VttdbbxOPxHZl5olLqd2VVk9Fz2jwWi+3MzD4RXZXNZrcAgGKx+KNCoXAeADDzOCI6ZrhjnzNnzpYAriCis7TWZ3qe16a1Po2IGpn5qra2tvqy6rdprc/WWp9VLBYPBXDQ4sWLdwaAeDx+h+M41wOAtXZXALFsNjslm81OyWQy7nA/j03J4sWLM0R0uuM4R2itt0wkEmOY+WGl1N2zZ8/eOqpWA+AFrfVmzDwBwPEAzkgmkycBQC6Xu6dYLO5V1u2xxWJx7HDHXiwWLwdwl9b6s1rr2Z7nNSqlPkFE57a1tR1dqsfMr0SfhbO11p8DsEgpdTQAOI7zQumGzUEQ7EhEcWbePZvNTjHGfGy4n8NA2Wz2CwAuZ+ZULpcb293dXQ8gQ0TXBkHwmaiaAjAukUhsE4vFtgvD8JPMvHU8Hv8hAOTz+RVhGO6Uz+efjuofopTaebhjTyaT3wcwJpfLHai1vkBrfQEzTwGwdaFQmFleN5fLTYu+LxuYeT6ArwFAtEffmkwmX4u293HMPD6bzU5pbW0d9udQUq1jlt8G8LzWemZpaKOpqelRZm4kohmZTCZRXnnq1KmFVCr1FoAHADil8jAMZymlPm2M2QmABnCEMebvvu/fO1yBE9GpRHRdU1PTM2XFHIZhhpkPzWazEwa2yWQyipkPYeY7S2VKqZ8y83GjR4/eEv1fNHtYa1uLxeKPhiv2NUkkEkcB2C0Wi51RGoqaPn3667FY7HQAn/Z9/6ABTbixsfFdIroLgHUcJw4A8Xj8hHg8flZU51IAmxtj/h7922U4Yo/FYscBWJpKpa4pL58wYcLPAawkoi8P1s5xnE8x83M9PT0vAUChUPimtfYHAEBEZwFIWmtbrbWtNTU12w5H7JuiIAiSRDSdiKbNmDHjX0D/l5XWWjPzK6NGjVptpMDzvBVa68eI6HVrrQMAiURiJ6XURcCqmzhvppT6TbR9njEcsbe3t48nosMAXIjocAcANDU1PUNE1ymlTl1TOwBbEtEDAEBEk5n5zwBgrT0ZwGhmnmatbSWizwxH7GvDzLOI6Kee5/0unU7bdDptU6nUrwFcAaBlYP3GxsaelpaWJUT0BDM7AJBOp63jOL+Nx+PjolGBzwLwovdj2EbjmPk0AEE6nV5ZKosOV7WX7zyUy2QyLhHtR0R3lBU/2Nvbu208Hv8EgL0AHGOtbXUc58zhin2gqgzDEtGnmPm2geVKqduZua6urm4vAI8CADM3+L6/N4Bk9OKuenGYeRdmfqSnp+eV2traXxDRwWEYngfADmP4uzDzLQMLW1paFhtjcmEY7gygNNR0uTEmn0wmt2DmGBGdM7DdjBkzXvF9v4OIjtJaV2UYVil1CIBHGxsb3x0YmzFmYbT+kaj4EN/3m4nIAXACEc2YPn3669G6bZl5OwAgoguZ+cowDE8CgN7e3leHKfxdADyNsi9HAGhoaAiNMc8M+PX8bWPMSQDGEtFmAAb9kiAizcx3aa2PGqaYN1nMvC+A2u7u7jsGrlJK3cbMh5SVbeP7fnP09/5EtGTs2LG/BQAiShLRXtHfc5n5LCLyisXi04lE4l0MA2vtLgDyWutFg6xbSESrti8immyMeRGAC2ALAPcAeGdgO8/z5vi+P81xnHObmppGfBi2s7PTYeaDAXx/kNW3MfNvygt6e3tTvu8XAWxLRIcVi8Ujylbvn0gkRsXj8Vvz+fwjAB4Iw/DXjuPkhiP2jo6OGgA7MPNTA9cR0UJm3jGTycTq6uoAAK7rPmmMibuuuwWA1wA8ObBdKpX6gzHmPiJakEqlPvzDsADqMcgHM5VKdQPIMfPoUhkz1ymlxhFRDYBnAVw7cC8lnU73EdF/AHS3tLQsamlpWTJcgRMRl36tlctkMgRAMXNvWd3GMAz3t9Z+nIi+BOBCY8ywH8PbAIO+HwBARG+XJipFy4no/RhDRE8x8w+DIFhtuJWZXwcQRu/HonQ63Tccga/p/Yi87/1g5l+GYXgAEe3uOM7+AA5wXfdnwxHXB5VSagyArsHeL2Z+m4jGlC07Sqlx0b93AEzp6uqaPbBdNCoUhmH4aktLy6Lp06cvG6bwLQCKtsWBFIDyCTrPhmF4QBiGk5l5T2b+t7X23oGjWtW2ePFiF0BcKfX2wHXM/BaAZCaTUWVlY6PtMySiMBaLXR8lrVWmTZu2HEA3gP+0tLQs0lq/MRyxv/vuuwwASqnVts8wDB30H59ctWPDzIeGYbi3Umo3ALOZ+Y5sNjt5OGLbEFXZs2Tmt4hou4Hlra2t4xzHSVprS3sqUEpd2dTUdGtp2RjzWwBN6B/KHXHM/AyAvQeW19bWfhxAPAzD58vqrmxpaXkPwHsAlhpjriOiowDMH6TrwTbwkfIWEU0ZbAUzb09Er5ct3621vqC0bIyZxsxzAPxhBOIcLL5niOjkzs5Op6GhISyVz58/Pw5gMjOv+vVJRPno/QCAt3zfnwfgkhEOeVP3FoBxQRAkox+vq0SfhaWlZSJ6NZVKrRoGbG9v/78wDJ/xff//RjDeVWKx2LOFQqGmrq5uNwDv25shon3QPwIBAGDmsOyz8N7cuXO/XywWG5PJ5K4jGHJFPT093a7r5qy122PAcwKwPTO/mU6nbWtrKwAgkUh8v3RoK5PJjHJdd1Fvb+9XAPx2ZCPv34kxxixi5n0APFy+joj2BvBsOp222Wz/AE9PT8+ydDqdQ//35S+MMedZaw/H6s+7KqqyZ6mUuhPASdEX2iqO45wK4MWenp5n19L8XZQdtyxh5nCw8qFmrb2KiE70ff8TpbL58+fHiWg2Ed28pindmUwmxswHRcl2oG70791VBTPfycwHDzxYHk02+rhSarUh87K2g74f1toReT/i8fhNAMYsWbLk/PLyZcuWpQD09fT0/HlNbZVShxDRap+16FSfZCaTqfqpVSNt9OjR/wbwVnSsaZWOjo4aIvqqtXaNr2f0WSBmHux7xQ62hzGUosMBt1lrZ5d/t0TH3E9QSl2xpraFQuEQAAVr7eKB65RS3cxcle0zOjPgbgCnDVynlDoNwBrfj2h0YCUG/5630aGU4XYlAC+amAMAmD179tbRoY7BdhoA9J8iA2DHwbZPIsqhCt+XVfky6O7unu+67re6urpuymazPywUCm87jvMFALOJ6PTSqSMAYK3dOZvNHhiG4VgiOpCIzgjD8AsD+ySiJQAOzGazuxWLRae5uXnhcMTe3Ny8wBjzAyK6y/f9W9C/V3YEgDwRvS8uImo2xnwdwGjXdfcC8Bwz+wP7tNbe7zjOJcaYywGEWusR3Wv2PO8R3/dvcBznj21tbd8looXoPwb1f0Rkys9XZOZtstnslOjLYyci+gEzzxvYp7X2VaXUWN/3jyKiRblc7s3yg/xDZfr06cva2tpOUUpdb4z5IoCFAPaJTs05bsBw4vHRZLBa9G+INdba4wf2mcvlXnJd99Xa2tqbjDFLAMzVWr841LFviqZOnVrwfb+FiP7PGAOl1O1hGG5NRD8C8FptbW35MbJkNpudAiAZhuFWRHQ+gL80Nze/HM14L7cYwHHt7e1vE5FtbGx8bTjij46N3t7V1fVP3/fvJqItiehLzDy9/JgjEe1ojLke/d+BWxHRZCL6ptZ6RWlPp6zPOwHM833/LqXUfalU6vfDEfuaWGu/7zjOgiAIXieiXwJQ1tqpAD7lOM7B5XV7e3v3b2trI6XUWCL6KgC3UCgMdnrIYmvt/2tra7tJKRUfrs93LpfzXdc9IBaL/dsYcwszUzwePxbAHzzPu7i8bjKZvNoYE6L/NJMpzHyF1vruQbq9MzoVbzMASz3PM8MR+0BV2bNMp9MrlVKHEdEiZv6N4zj/BhAAODaVSpUP5z0A4Fhr7WwimgFgAjMf3tzcvCBa/y8ASwEgl8vdBuAma+1NpVl4w0Vr3RqG4T5EtICIQgA71tfXH9LU1LTquJ9Salo0BNiplPqpUupzWusjShcuIKI56P/FiJaWlkVKqSnon9R013DGviZjx479OoBfOo7TRkSPE9HNAOalUqnvleow80IimmCtbWXmmcx8GBGd73leOwBYaxdR/7mwmDlz5n+Y+TtE1A7gxpqamq2GK/bm5ubbi8XiJADXMvObAA5h5q94nvf3Uh0iuhjADwB0MvPlSqkzu7u7dy/9qGLmG5j5UgBIp9PFaK/zRmZ+NDo29JHhed6VRHQGM59mrX2E+s9p62Lmo0tDfNEx6aXRjOELiOhkIropl8uVJtF0AShtp2DmGQCOKhaLd0an7QxX7K/W19fvy8zfI6LXAOwBwHied1mpThiGCwBMBdAJ4BoAzdbaHaMZplBKvYiywzy5XG4agIxS6plisfjEcMW+Js3NzY+HYXgogF2stXdZa/8O4IgwDD9ROm81kUj0oD+JXKiUykTxvxGPxw8uzXAHcFdvb28eAOLxeDsRWaXUX9F/zviwSKfTfVrr4wF8lYieJaKtAfxLa30Wokl5K1eufBvAScz8WwCdRPQjZp5cOi82chr6DxEglUr9mohOIqLnmPmB4Yp9IPJ9vzSLMKe1Tq5vB8aYJwDsCQBhGG5WdhxgnbW3t48Pw3ARgINzudy/x4wZM2bgzMzhEO31XQX0J69UKjVrffvIZDIJ13WfBXAfMz9GRE9orf8y1LGujTHmFgClSTZTtNb/XFv9dexzCYA2rfVlQRBsGU3SGHbGmJsBHAsASqkDNmQGojHmRiLakplvBLBCaz3w/Nch5fu+pui8PADTtdZVOWY3kO/7xxNRaS/oYq31+WttsAbRxSjG5XK505PJ5NgR/Cy8AGAnAMjlcrUbckWpIAjOZuYfMPM8Ihqrtf5e5VZDxxizL/p/1IOZ/+R53qCnMq2P6NSb74dheEhfX18vABsd6xtWbW1t+yilHosW/6y1/tL69hG9Hg8AaEf/hROuSaVSqw19DyVjzHIAo9H/XTCmUv0BbbvRP2N607g27IwZM15h5u8DuN913UIYhqdXO6Z1lU6n80qpw5j5JSLayVo77B/aEXIugB8YY6y1tqPawayPXC73dWa+GcBuRPSBuWTfpspa+xMAk1zX7WXm56odz/pIpVLzAaSIaAI2ke+7jdXT03OdUurJWCz2huu677muu0lNSlobrfVj1tqjmbkOwBbW2qpfQnBdbTITGDzPa8tkMgbAqA/SNUkBIBoKGew8qA8srfWfAWyTyWTckfjVOpSiY6NBteP4sGhubn4ZwAEfxM8CANZaXwvg2moHMlSi4/AnZjKZUejfq/zAXFMb6J/38f/bu5sQN+owjuO/Z7K73ZfWilitFUUEa1FspUJ9wxda8KSgQrFKUQ8ePFhYbJKFHgw5yNJJoaHxIHgSqwii4kEEKaWyagUPgiBWBVEQau2itt3dlCabx0Mn3TSknd1mk8mu3w8E5j//mdkHNsmPmSTzqOES/VLRM2EpXfjm15IKyuVuCb45okN4LvSWTv12Ga0ti8sSAAB0EmEJAEAMwhIAgBiEJQAAMQhLAABiEJYAAMQgLAEAiEFYAgAQg7AEACAGYQkAQAzCEgCAGIQlAAAxFrWfpbt/amaVxSyww1ZJuk6SzOwfd+94D80OWStpRJLc/Q8zWzJtb1q4W3P/k2/c/XTC9czHbTrfZFjq3X6Wv0r6Psl6FsrMbnL3gWj5V3f3uH16jZkNuPtN0XBa0p9J1tOmVZLuj5YnJbXdN7dLHtf5piFt9bNc1K4jZrbgZqC9Ygm+Dlsys7uSrmGxuPvWpGtYRm6NHktG42vS3Zfk83q5vK+0cHP0+N/gMiwAADHaPrOs1Wo7+vr6hhejGGCpc/ffk66hbmBg4Mjs7OyWpOsAekGtVpttZ/+2w3JsbOyHdo8BYPGNjo7+K+nbpOsAlgMuwwIAEIOwBAAgBmEJAEAMwhIAgBiEJQAAMQhLAABiEJYAAMQgLAEAiEFYAgAQg7AEACAGYQkAQAzCEgCAGIQlAAAxCEsAAGIQlgAAxCAsAQCIQVgCABAjkHQ2Wh6UZAnWAgBArzCdz0VJmgkknYkGQT6fH0qmJgAAekcYhis1d/X1TCBpsj45PDx8YyJVAQDQW9Y1LE8Gkn6pj8xsfffrAQCg59zesPxzYGY/1kfufk8CBQEA0Gs21xfM7FhQq9W+bph8tPv1AADQW4Ig2FZfdvcvA3f/QtJstO6B/fv3X5NMaQAAJG98fHyNu98bDavuPhGMjY2dknQkWrmiWq0+k0x5AAAkL5VKPSOpPxoezmazZwJJcvd3GrZ7WfzeEgDwP5TP5wMze7k+dveDUvQbknK5/KGkv6O5jWEYPtH9EgEASNbQ0NCTku6MhpNBEHwkRWGZy+WmzOxAw/aFUqm0oss1AgCQmHw+P2Bmr9fHZlZMp9PTUsO9YavV6gFFNygws/XlcvnVrlcKAEBCRkZGMpI2RMO/Zmdn36jPmbtf2LBQKLwk6a1oWDGzR9Lp9NGuVQoAQALCMNxiZhOSBiTJ3V/MZrNv1+cvCktJVigUDknaGo1/6+/vf2B0dPR41yoGAKCLwjBcZ2ZHJd0crTqUyWQek3QhIJtbdHl/f/9OSSei8S3VavWzYrF4defLBQCgu4rF4tVm9pmioHT345VKZacaglJq0c8yOovcrqh1l7tvqlarR4rF4g2dLxsAgO4Iw3BdpVL5QtLGaFXZzLbv2bPnRPO2LZs/ZzKZCTN7TtGdfdx9U6VSORqG4ZaOVQ0AQJeEYXhfdOm1HpRVd9+RyWS+arV982eWF9m3b99T7v6e5hpgnpOUn5mZ2ZfL5c4tZuEAAHRaqVRacfbs2Yyk1zR3l56ymT2bTqc/udR+lw1LSSoUCg9J+kDS9Q2rj5nZnunp6U9yuVytzdoBAOiofD4fRDccGG9sR+nux81s+6XOKOtiw1KSCoXCWkkHJW1rmvrB3T7BV88AAAEKSURBVN9MpVLv7969e7LFrgAAJGZ8fHxNX1/fDp2/lesdTdOfVyqV51t9RtlsXmFZ37ZQKLwgaa+k65rmKpK+cffDQRB8V6vVjg0NDR3ftWvX6fkeHACAdpRKpavK5fINQRBscPfNZrY16h7S37TpCXfPZLPZg2r61uulLCQsJUl79+5dnUqlXnH3UUnXzmOXU5K4VAsA6JRA0up5bHdSUnFwcPCNhZ7MLTgs6/L5/PDIyMjTkna6+zZJfVd0IAAAOqfi7ockvVsulz/O5XIzV3KQKw7LRmEYrgqC4GFJD7r7BknrJa2RtFLScNt/AACAy5uRNCXppJn9JOknM5uYmpqayOVyU+0e/D+CUoG+F9RSwQAAAABJRU5ErkJggg=="
+ }
+ },
+ "cell_type": "markdown",
+ "id": "21",
+ "metadata": {},
+ "source": [
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "## 6. `QStruct`: struct-like quantum types\n",
+ "\n",
+ "A `QStruct` groups named quantum fields into a single type, similar to a classical struct.\n",
+ "\n",
+ "Example:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "22",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class MyState(QStruct):\n",
+ " reg: QArray[QBit, 3]\n",
+ " num: QNum[3, True, 1]\n",
+ " flag: QBit"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "23",
+ "metadata": {},
+ "source": [
+ "### Allocating and accessing struct fields"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "24",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@qfunc\n",
+ "def struct_demo(state: Output[MyState]):\n",
+ " allocate(state) # allocate all fields at once\n",
+ "\n",
+ " hadamard_transform(state.reg) # operate on the qubit array field\n",
+ " hadamard_transform(state.num) # operate on the numeric field\n",
+ "\n",
+ " # Example: compare numeric field and write to bit field\n",
+ " state.flag ^= state.num < 0"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "25",
+ "metadata": {},
+ "source": [
+ "Key points:\n",
+ "\n",
+ "- `allocate(state)` uses the type definition to allocate all fields.\n",
+ "- Access fields with `state.`.\n",
+ "- A struct is a single composite quantum object; fields are not re-bound individually.\n",
+ "\n",
+ "### Exercise 4: Portfolio-like struct\n",
+ "\n",
+ "**Goal**: Create a simple struct for a financial-style example with:\n",
+ "\n",
+ "- `reg`: 2-qubit register representing “asset ID”.\n",
+ "- `price`: 4-bit unsigned integer.\n",
+ "- `is_in_the_money`: one `QBit`.\n",
+ "\n",
+ "**Tasks**\n",
+ "\n",
+ "1. Define the struct type:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "26",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class PortfolioState(QStruct):\n",
+ " reg: QArray[QBit, 2]\n",
+ " price: QNum[4, False, 0] # 4-qbit unsigned integer\n",
+ " is_in_the_money: QBit"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "27",
+ "metadata": {},
+ "source": [
+ "2. Allocate and initialize in a `@qfunc`:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "28",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@qfunc\n",
+ "def portfolio_demo(state: Output[PortfolioState]):\n",
+ " allocate(state)\n",
+ "\n",
+ " # Put all asset IDs in superposition\n",
+ " hadamard_transform(state.reg)\n",
+ "\n",
+ " # Example: simple payoff rule, e.g. flag set if price > 5\n",
+ " state.is_in_the_money ^= state.price > 5"
+ ]
+ },
+ {
+ "attachments": {
+ "image-2.png": {
+ "image/png": "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"
+ }
+ },
+ "cell_type": "markdown",
+ "id": "29",
+ "metadata": {},
+ "source": [
+ "3. Synthesize and sample.\n",
+ "4. Observe how the `is_in_the_money` flag correlates with the encoded `price`.\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "## 8. Learning checklist\n",
+ "\n",
+ "After completing this tutorial, you should be comfortable with:\n",
+ "\n",
+ "- Distinguishing between quantum objects, types, and variables.\n",
+ "- Declaring and using:\n",
+ " - `QBit` and `QArray[QBit]` with indexing and slicing.\n",
+ " - `QNum` with explicit numeric attributes and numeric assignments.\n",
+ " - `QArray[QNum]` and reasoning about element count vs qubit count.\n",
+ " - `QStruct` for grouping heterogeneous quantum fields.\n",
+ "- Reading synthesized circuits and relating them to Qmod type declarations.\n",
+ "\n",
+ "## Learn more\n",
+ "\n",
+ "- If you want to see another examples of usage, take a look at the [Modeling Guide](https://docs.classiq.io/latest/user-guide/)\n",
+ "- For a technical, complete explanation of quantum types and variables, see the language reference pages [Quantum Types](https://docs.classiq.io/latest/qmod-reference/language-reference/quantum-types/) and [Quantum Variables](https://docs.classiq.io/latest/qmod-reference/language-reference/quantum-variables/).\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "venv",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.11.14"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 9
+}