{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6faa6b8c",
   "metadata": {},
   "source": [
    "# Random Boolean network generation\n",
    "\n",
    "This tutorial demonstrates how to generate **random Boolean networks with\n",
    "controlled structural and functional properties** using BoolForge.\n",
    "This ability enables ensemble studies, which are exemplified in the next tutorial.\n",
    "\n",
    "## What you will learn\n",
    "In this tutorial you will learn how to generate random Boolean networks with\n",
    "\n",
    "- prescribed structural properties (e.g., degree, degree distribution, strongly connected),\n",
    "- prescribed functional properties (e.g., canalization, bias),\n",
    "\n",
    "It is strongly recommended to complete Tutorials 4 and 5 on random function generation first.\n",
    "\n",
    "## Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "59ade921",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:32.143465Z",
     "iopub.status.busy": "2026-03-14T21:20:32.143085Z",
     "iopub.status.idle": "2026-03-14T21:20:33.234507Z",
     "shell.execute_reply": "2026-03-14T21:20:33.234151Z"
    }
   },
   "outputs": [],
   "source": [
    "import boolforge as bf\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8191f01d",
   "metadata": {},
   "source": [
    "## Generating random wiring diagrams\n",
    "\n",
    "The function `random_network(N, n, *args)` generates a random $N$-node\n",
    "Boolean network with degree parameter `n`. \n",
    "The generation follows a two-step process:\n",
    "\n",
    "- A random wiring diagram is created using `random_wiring_diagram(N, n, *args)`.\n",
    "- Random Boolean functions with prescribed properties are generated using \n",
    "  `random_function(n, *args)`, which was discussed in depth in Tutorials 4 and 5.\n",
    "\n",
    "We first consider only the structural parameters that concern the generation of\n",
    "the random wiring diagram. In the absence of optional arguments,\n",
    "the in-degree distribution is assumed to be constant. That is, each node in the \n",
    "network is regulated by `n` nodes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "925b7682",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.236579Z",
     "iopub.status.busy": "2026-03-14T21:20:33.236373Z",
     "iopub.status.idle": "2026-03-14T21:20:33.303128Z",
     "shell.execute_reply": "2026-03-14T21:20:33.302825Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 400x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 5\n",
    "n = 2\n",
    "\n",
    "W = bf.random_wiring_diagram(N, n, rng=2)\n",
    "\n",
    "W.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "031939cd",
   "metadata": {},
   "source": [
    "The argument `rng` seeds the random number generator, ensuring reproducible results.\n",
    "\n",
    "The rest of this tutorial describes the various constraints / optional arguments. \n",
    "Each optional argument restricts the family of networks from which\n",
    "`random_wiring_diagram()` and `random_network()` samples.\n",
    "\n",
    "### Allowing self-regulation\n",
    "\n",
    "BoolForge selects the `n` regulators of each node uniformly at random\n",
    "from the set of all other nodes. Thus, self-regulation is disallowed by default.\n",
    "Setting `allow_self_loops=True` allows nodes to regulate themselves."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "d125aeab",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.304586Z",
     "iopub.status.busy": "2026-03-14T21:20:33.304465Z",
     "iopub.status.idle": "2026-03-14T21:20:33.347533Z",
     "shell.execute_reply": "2026-03-14T21:20:33.347256Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 400x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 5\n",
    "n = 2\n",
    "\n",
    "W = bf.random_wiring_diagram(N,n,allow_self_loops=True,rng = 2)\n",
    "\n",
    "W.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e1022dd",
   "metadata": {},
   "source": [
    "### Poisson in-degree distributions\n",
    "\n",
    "Classical random Boolean network theory (NK Kauffman models) assume a fixed in-degree,\n",
    "the default in BoolForge. However, this is a strong assumption since the in-degree\n",
    "in curated biological Boolean network models often appears approximately\n",
    "Poisson distributed.\n",
    "BoolForge provides the option to generate random wiring diagrams with Poisson distributed\n",
    "in-degree, using the optional parameter `indegree_distribution`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "e5a57874",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.348986Z",
     "iopub.status.busy": "2026-03-14T21:20:33.348869Z",
     "iopub.status.idle": "2026-03-14T21:20:33.392849Z",
     "shell.execute_reply": "2026-03-14T21:20:33.392598Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYYAAAGGCAYAAAB/gCblAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjUsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvWftoOwAAAAlwSFlzAAAPYQAAD2EBqD+naQAAXahJREFUeJztnQd8jff3x48ZI6gYpUYURc1aVZsa1Z+9a9aoolZRq7Ro7VJ71qhRqzb927QoSu3Ye8QeEUQQvv/X58ST3hsJGffeZ53365UXSW7u/d7xPJ/ne875nBNHKaVIEARBEF4SV/uPIAiCIAARBkEQBMEJEQZBEATBCREGQRAEwQkRBkEQBMEJEQZBEATBCREGQRAEwQkRBkEQBMEJEQZBEATBCREGwdasW7eOPvjgA0qUKBHFiROHAgICYnxfLVq0oCxZsrh0fYKgByIMQow5cuQI1atXj3x9ffnEmiFDBqpUqRKNHz/+lds+f/6cZs2aReXKlSMfHx/y8vLik2jLli3p33//feX2Z8+epbZt21LWrFn5vpMnT04lS5aksWPH0uPHj12y/jt37lCDBg0oceLENHHiRJo7dy4lTZqUzATECIIW/itXrlx6L00wMXGkV5IQE3bu3Enly5enzJkz0+eff07p0qWjy5cv0+7du/mkfubMmbDb4kRep04dvjovU6YMVa9encXhwoULtHjxYjp16hRdunSJMmbMyLf/448/qH79+iwezZs3p7x589LTp09px44dtHTpUj4ZTps2LdbPAev59NNPaePGjVSxYsVY39+zZ8/oxYsXvG5Pgddi4cKFNH36dKefp0iRgl9nQYgJ8WP0V4LtGTx4MJ989u7dS2+99ZbT727evOn0fY8ePfgkPHr0aPr666+dfte/f3/+ucb58+fps88+413Ili1bKH369GG/69ChAwsOhMMVaOsMv/6YkiBBAtKD+PHjU9OmTXV5bMGiYMcgCNElZ86cqly5cm+83eXLl1X8+PFVpUqVonS/7dq1ww5W/f3337Fa3+LFi1WhQoVUokSJVKpUqVSTJk3UlStXwn5ftmxZfhzHr88//zzS+wsMDFRdunRRvr6+KmHChCpNmjSqYsWKat++fWG3wd/j9697DO1r1qxZYbe7d+8e33fGjBn5vrNly6aGDRumnj9//sbnicdMmjSpCgkJUffv34/hqyUI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",
      "text/plain": [
       "<Figure size 400x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 5\n",
    "n = 2\n",
    "\n",
    "W = bf.random_wiring_diagram(N,n,indegree_distribution='poisson',rng = 5)\n",
    "\n",
    "W.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "933ce2fd",
   "metadata": {},
   "source": [
    "We see that some nodes ($x_1$ and $x_3$) are only regulated by one node,\n",
    "while others ($x_0$ and $x_4$) possess three regulators each.\n",
    "\n",
    "When using a Poisson-distributed in-degree, the in-degree of every node \n",
    "is always at least 1. This avoids the artificial creation of identity nodes\n",
    "(with in-degree 0).\n",
    "\n",
    "### Avoiding output nodes\n",
    "\n",
    "In general, it is possible that some nodes in a generated Boolean network \n",
    "will not regulate other nodes. By setting `min_out_degree_one=True`, we can\n",
    "force every node to regulate at least one node. That is, output nodes can be disallowed.\n",
    "\n",
    "### Strong connectedness\n",
    "\n",
    "The wiring diagram of the generated Boolean network may or may not be strongly\n",
    "connected. Setting `strongly_connected=True` (default False) forces strong\n",
    "connectedness. Uniform sampling among strongly connected networks cannot be achieved by\n",
    "a simple construction method. BoolForge therefore generates candidate\n",
    "networks and rejects them until a strongly connected network is obtained.\n",
    "\n",
    "Careful: When the number of nodes `N` is large and the degree `n` is small, this may take a\n",
    "long time. The number of unsuccessful attempts before raising an error is controlled\n",
    "by the optional parameter `max_strong_connectivity_attempts`. \n",
    "\n",
    "### Fixed wiring diagrams\n",
    "\n",
    "All optional parameters discussed thus far describe properties of the wiring diagram.\n",
    "Instead of generating a new wiring diagram, an existing one (e.g., from a curated\n",
    "biological network model) can be passed directly to `random_network`.\n",
    "\n",
    "In that case, `random_network(I, *args)` does not require `N` and `n`, because\n",
    "these quantities are inferred from the wiring diagram, provided via optional parameter `I`.\n",
    "As described in detail in Tutorial 6, `I` can be either a `WiringDiagram` object \n",
    "or a list of lists describing the regulators of each node.\n",
    "\n",
    "For example, using the previously generated wiring diagram, we can write"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "3a68b4ef",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.394291Z",
     "iopub.status.busy": "2026-03-14T21:20:33.394188Z",
     "iopub.status.idle": "2026-03-14T21:20:33.777845Z",
     "shell.execute_reply": "2026-03-14T21:20:33.777482Z"
    }
   },
   "outputs": [],
   "source": [
    "bn = bf.random_network(I=W)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b16a659b",
   "metadata": {},
   "source": [
    "This feature allows multiple Boolean networks with different update functions\n",
    "to be generated on the same wiring diagram.\n",
    "\n",
    "## Specifying functional constraints\n",
    "\n",
    "Once the wiring diagram is generated, the number of nodes `N` and the in-degree of each node are determined.\n",
    "In step 2, `random_network` now repeatedly calls `random_function` to generate \n",
    "the random Boolean functions. The optional parameters regulating the functional constraints\n",
    "are practically identical to the ones discussed in depth in Tutorial 4, with one\n",
    "important distinction: Most parameters can be sequences of length `N`, in order to\n",
    "specify distinct functional behavior for the different nodes.\n",
    "\n",
    "In the following, we summarize the key concepts.\n",
    "\n",
    "### Parity functions\n",
    "If `parity=True` (default False), parity functions (also known as linear functions)\n",
    "are chosen for all nodes. Note that for any degree `n`, there are only two parity functions.\n",
    "\n",
    "### Canalizing functions\n",
    "If a specific `layer_structure` is provided, all functions possess at least these\n",
    "canalizing layers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "a2e3adc1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.779736Z",
     "iopub.status.busy": "2026-03-14T21:20:33.779518Z",
     "iopub.status.idle": "2026-03-14T21:20:33.782869Z",
     "shell.execute_reply": "2026-03-14T21:20:33.782596Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0 1 1 0 0 0 0 0] [1]\n",
      "[0 0 1 1 0 1 1 1] [1, 2]\n",
      "[0 0 0 0 0 0 0 1] [3]\n",
      "[1 1 1 0 1 1 1 1] [3]\n"
     ]
    }
   ],
   "source": [
    "bn = bf.random_network(N=4,n=3,layer_structure=[1],rng = 2)\n",
    "for f in bn.F:\n",
    "    print(f,f.get_layer_structure()['LayerStructure'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e149dd3",
   "metadata": {},
   "source": [
    "As we see, it is however possible for some functions to randomly possess more canalizing\n",
    "variables in a larger and/or more layers. To ensure `layer_structure` is interpreted\n",
    "as exact layer structure, set `exact_depth=True`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "e78cc670",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.784135Z",
     "iopub.status.busy": "2026-03-14T21:20:33.784040Z",
     "iopub.status.idle": "2026-03-14T21:20:33.787293Z",
     "shell.execute_reply": "2026-03-14T21:20:33.787049Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0 1 1 0 0 0 0 0] [1]\n",
      "[1 0 1 1 0 1 1 1] [1]\n",
      "[1 1 0 1 0 1 1 1] [1]\n",
      "[0 1 1 0 1 1 1 1] [1]\n"
     ]
    }
   ],
   "source": [
    "bn = bf.random_network(N=4,n=3,layer_structure=[1],exact_depth=True,rng = 2)\n",
    "for f in bn.F:\n",
    "    print(f,f.get_layer_structure()['LayerStructure'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8bcdd63",
   "metadata": {},
   "source": [
    "Rather than specifying the exact layer structure, we can also describe the desired\n",
    "*canalizing depth* (i.e., the number of conditionally canalizing variables) via `depth`. \n",
    "As before, the optional argument `exact_depth` (default False) determines if \n",
    "`depth` is interpreted as exact canalizing depth, or as minimum canalizing depth."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "2825efc1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.788597Z",
     "iopub.status.busy": "2026-03-14T21:20:33.788516Z",
     "iopub.status.idle": "2026-03-14T21:20:33.792905Z",
     "shell.execute_reply": "2026-03-14T21:20:33.792682Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 [0 1 1 0 0 0 0 0]\n",
      "3 [0 0 0 0 0 0 1 0]\n",
      "3 [1 1 0 0 1 1 1 0]\n",
      "3 [0 1 1 1 0 0 0 0]\n",
      "\n",
      "1 [0 1 1 0 0 0 0 0]\n",
      "1 [1 0 0 0 0 0 1 0]\n",
      "1 [1 1 0 1 0 1 1 1]\n",
      "1 [0 0 1 0 1 0 0 0]\n"
     ]
    }
   ],
   "source": [
    "#Boolean network whose rules all have minimal canalizing depth 1\n",
    "bn1 = bf.random_network(N=4,n=3,depth=1,exact_depth=False,rng = 2)\n",
    "for f in bn1.F:\n",
    "    print(f.get_canalizing_depth(),f) \n",
    "print()    \n",
    "\n",
    "#Boolean network whose rules all have exact canalizing depth 1\n",
    "bn2 = bf.random_network(N=4,n=3,depth=1,exact_depth=True,rng = 2)\n",
    "for f in bn2.F:\n",
    "    print(f.get_canalizing_depth(),f) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "331b7097",
   "metadata": {},
   "source": [
    "Most optional parameters (e.g., `n`, `depth`, `layer_structure`, `bias`, `absolute_bias`) \n",
    "can also be specified as sequences of length `N`.\n",
    "In that case, each entry applies to one node in the network, allowing\n",
    "different functional constraints for different nodes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "6a6445e6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.794167Z",
     "iopub.status.busy": "2026-03-14T21:20:33.794075Z",
     "iopub.status.idle": "2026-03-14T21:20:33.796919Z",
     "shell.execute_reply": "2026-03-14T21:20:33.796687Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3 [1 1 1 1 0 1 1 1]\n",
      "1 [1 1 0 1 0 1 1 1]\n",
      "2 [1 1 0 1]\n",
      "0 [0 1 1 0]\n"
     ]
    }
   ],
   "source": [
    "bn = bf.random_network(\n",
    "    N=4,\n",
    "    n=[3,3,2,2],\n",
    "    depth=[3,1,2,0],\n",
    "    exact_depth=True,\n",
    "    rng=2\n",
    ")\n",
    "\n",
    "for f in bn.F:\n",
    "    print(f.get_canalizing_depth(),f) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0716e98c",
   "metadata": {},
   "source": [
    "### Biased functions\n",
    "When `parity=False` and all canalization parameters are also at their default values,\n",
    "`random_network` generates each update function with a specified *bias*, i.e.\n",
    "\n",
    "  - probability of output 1: `bias`\n",
    "  - probability of output 0: `1-bias`\n",
    "\n",
    "The unbiased case (`bias=0.5`) is the default. Instead of the bias, users can\n",
    "also specify the absolute bias to generate functions with a bimodal Hamming weight\n",
    "distribution. For BoolForge to use the parameter provided via `absolute_bias`, \n",
    "`use_absolute_bias=True` is required. The default is `use_absolute_bias=False`, \n",
    "i.e., by default `bias` is used, resulting in a unimodal Hamming weight distribution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "46072d01",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-14T21:20:33.798138Z",
     "iopub.status.busy": "2026-03-14T21:20:33.798043Z",
     "iopub.status.idle": "2026-03-14T21:20:33.957366Z",
     "shell.execute_reply": "2026-03-14T21:20:33.957063Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAkAAAAGwCAYAAABB4NqyAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjUsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvWftoOwAAAAlwSFlzAAAPYQAAD2EBqD+naQAASIFJREFUeJzt3Qm8jOX///GPfSdl39ck2ZcS0Td+1kR8S6s1lW9KkeL7zZZEi6WilDaKaNFGsn2liAgVWUKE7Apl58z/8b5+/5nfnGPOsc2cmTP36/l43Mx9zz33fd1z5sz9Odf1ua4rnc/n8xkAAICHpI92AQAAAFIbARAAAPAcAiAAAOA5BEAAAMBzCIAAAIDnEAABAADPIQACAACekzHaBYhFCQkJtmPHDsuVK5elS5cu2sUBAADnQEMb/vXXX1akSBFLnz7lOh4CoBAU/BQvXjzaxQAAABdg27ZtVqxYsRT3IQAKQTU//jcwd+7c0S4OAAA4B4cOHXIVGP77eEoIgELwN3sp+CEAAgAgbTmX9BWSoAEAgOcQAAEAAM8hAAIAAJ5DAAQAADyHAAgAAHgOARAAAPAcAiAAAOA5BEAAAMBzCIAAAIDnEAABAADPIQACAACew1xgYVSq74xUO9eW4S3Pa//rr7/eqlWrZqNHj052n1KlStnDDz/sFgAA4hk1QAhYtmyZ3XvvvRarfD6fDRgwwAoXLmzZsmWzxo0b24YNG1J8jYI6TYqXdHnggQcSBYdJn7///vtT4YoAANFCAISA/PnzW/bs2S1WPfvss/biiy/auHHj7LvvvrMcOXJY06ZN7dixYykGdTt37gwsc+bMcdtvueWWRPt169Yt0X46FwAgfhEAecipU6esR48elidPHsuXL5/179/f1aoE15YEN5GNHDnSKleu7AKN4sWL27/+9S/7+++/A8//9ttv1qpVK8ubN6/bp1KlSvbFF19EpOwqp8r2xBNPWOvWra1KlSo2ceJE27Fjh33yyScpBnWFChUKLNOnT7eyZctaw4YNE+2nwC94v9y5c0fkOgAAsYEcIA+ZMGGCde3a1ZYuXWrff/+9a+4qUaKEq/0IJX369K7GpXTp0vbrr7+6AOixxx6zl19+2T2vZqQTJ07Y119/7QKgNWvWWM6cOZM9v5qV3n333RTLGBxgBdu8ebPt2rXLNXv5KZC7+uqrbfHixXbbbbed9fpVVp2/V69erpkr2KRJk9xzCn4U1Ck4jOXaMCBecyXPN78RuFAEQB6iWpxRo0a5m3+FChVs1apVbj25ACg4GVq1Q0899ZQLYvwB0NatW61du3aulkjKlCmT4vmffPJJe/TRRy+o7Ap+pGDBgom2a93/3NmopujAgQPWqVOnRNvvuOMOK1mypBUpUsR++ukne/zxx239+vU2bdq0CyorACD2EQB5yDXXXJOo5qNu3bo2YsQIO336tGXIkOGM/efOnWvDhg2zdevW2aFDh1wTmvJtjhw54mpHHnroIevevbvNnj3b1cwoGFLTVHIKFCjglmh54403rHnz5i7QCRac+K1gTknWjRo1sk2bNrnmMgBA/CEHCCFt2bLFbrzxRhfQfPTRR7Z8+XIbO3ZsoClJ7rnnHtc0dvfdd7vapFq1atlLL72U7DFVe6QmspSW5KhpSnbv3p1ou9b9z6VE+UoK6FTms1GzmmzcuPGs+wIA0iZqgDxEPaeCLVmyxMqXLx+y9kcBT0JCgqshUi6QvP/++yGb1RTYaOnXr5+NHz/eHnzwwbA3gSkPSYHOvHnz3HhGolopXZNqoc7mrbfecrVPLVuePb/ghx9+cP+rJggAEJ8IgDxEOTtKAL7vvvtsxYoVrrZGAU4o5cqVs5MnT7p9lBS8aNEi1/08aY6QmpQuv/xy+/PPP23+/PlWsWLFiDSBqelO51MekoI2BURKVFZzVps2bQL7qenq5ptvdr3d/BTIKQDq2LGjZcyY+COvZq7JkydbixYt7LLLLnM5QI888og1aNAgxeY8AEDaRgAURrHee6FDhw529OhRq1Onjqv16dmzZ7IDH1atWtV1g3/mmWdczY4CAuUD6Rh+yh1ST7Dt27e7buPNmjVzSdWRoh5ohw8fdmVWMnP9+vXtyy+/tKxZsyYKaPbt25fodWr6UvDXpUuXM46ZOXNm97y62OvYqtFSLpO62wNIu+hthrNJ5wseCAaBphV1sT548CDjwQBAGgxMCIC86dB53L9JggYAAJ5DAAQAADyHAAgAAHgOARAAAPAcAiAAAOA5BEAAAMBzCIAAAIDnEAABAADPIQBCYPJTTTfhnwcrEjp16pRo2orUdC7nvv766910GwCA+MdUGOE0KE8qnuugeYGCso8//jhVAqdp06ZZpkyZLJaNHTvWnnvuOdu1a5ebrkRztWlqk+S8/fbb1rlz50TbsmTJYseOHUuF0gJA7KIGCPj/Lr30UsuVK5fFqqlTp7rJbAcOHOgms1UA1LRpU9uzZ0+Kr9Nw8Dt37gwsv/32W6qVGQBiFQGQR2jSUE0eeskll7hZz2+88UY3cWhS69ats2uvvdZNMHrVVVfZggULAs9pxvc777zT8ufPb9myZXOzsmuWdb9Vq1bZDTfc4J7TOTRp6d9//51smUqVKuUmIQ1WrVo1GzRoUOB50ezuqgnyr8unn35qNWrUcOUsU6aMDR482E6dOnXW90H7qfwKCu6//347ceJEsk1g77zzjtWqVcsFRYUKFbI77rgjUbBxtvcj3DQ5bbdu3VyNzpVXXmnjxo2z7Nmz25tvvpni6/Teqfz+pWDBghErIwCkFQRAHqGZzlV78P3339u8efMsffr0LrBISEhItF+fPn2sd+/etnLlSqtbt661atXK9u/f757r37+/rVmzxmbOnGlr1661V155xfLlyxc4vmoj8ubNa8uWLbMPPvjAzbLeo0ePCy6zjiMKKlRz4V//5ptv3Kz0ms1e5Xn11VddU8/QoUNTPJ6uW+X+6quv7L333nNNXgqIknPy5EkbMmSI/fjjj/bJJ5+4PCnlEvml9H6E8vTTT1vOnDlTXDRrfSgK1JYvX26NGzcObNPPUOuLFy9O8boVhJYsWdLNdN+6dWv7+eefU9wfALyAHCCPaNeuXaJ11Rqo5kI3cNX0+Clg8e+rG7pqjt544w177LHH3M25evXqrlZEgmtkJk+e7PJKJk6caDly5HDbxowZ4wKoZ5555oJqHVQ+Ua2Vai78FLT07dvXOnbs6NZVA6RARWVU81ByMmfO7K5btSaVKlWyJ5980gV8eq2CiaS6dOkSeKxzvPjii1a7dm0XUPiDleTej1BU43TrrbemuE+RIkVCbt+3b5+dPn36jPdR66q1S06FChXcNVepUsXNjvz888+7Gj4FQcWKFUuxLAAQzwiAPGLDhg02YMAA++6779zN1F/zo5t4cACkWh+/jBkzupu7ajeke/fuLjhS/kmTJk1cYrJupqJ9lJPiD36kXr167jzr168Pa7OLamQWLVqUqMZHwYECsCNHjrgAJxSVL/g5XauCmW3btrkakqRU46LmOJ1PzV3B75maoFJ6P5LLMdKSmnSNwT9Tla9ixYqu1kyBHwB4FU1gHqGamD/++MPGjx/vgiAtEpwDczbNmzd3CbSPPPKI7dixwxo1amSPPvroBZdJtS4+n++MZqezUdCiWiB12fcvyj9SkKecoHDwN+kpV2jSpEmu+U290YLfs/N9Py6mCUxNaxkyZLDdu3cn2q714Nqxs1EvN9Vabdy48ZxfAwDxiADIA5TDo1qYJ554wt2kVQOgGo1QlixZEnispGLVgmj/4GYpNT29++67LoH5tddec9u1j2pKFDj4qZZGQY6aYULRsZTb43fo0CHbvHnzGTds1e4EU/KzrqdcuXJnLKGasvxUvqNHjya6VgUdyo1JSs1Ket+GDx9u1113nV1xxRUhe1sl934k1wQWHLSFWpJrAlPzXc2aNV0ek59qpLQeXMNzNnovFSwWLlz4nF8DAPGIJjAPUGKyemXp5qwbn2oZlEOT3Dgz6s2kgGbUqFEuUPLnwqgJTTdh5c8cP37cpk+fHgiO1BtK+TcKBtRstHfvXnvwwQft7rvvTrb5Sz3GlLys2inl+ej4quUIprwa3eTVnKbxa3Qt2k+92EqUKGH//Oc/XdCj4Gb16tX21FNPJfs+qOama9euLhBUQrPKq5ynUEGTjq2gQ+PsKHDRsZM2GaX0fkSiCUxJ7Hp/1SypsX8UcCngDB7nR8nhRYsWtWHDhrl15Tldc801Ljg8cOCAG0NItVb33HPPBZcDAOIBNUAeoBv8lClTXG2O8n3UZKMbYSiq8dCifJmFCxfaZ599FujZpICgX79+LqG2QYMGLljRcUW5NbNmzXLNbEoUVmCi2iYlQidHx2rYsKELZlq2bOlyaMqWLZtonxEjRticOXNcLY2abkRNUwo2Zs+e7c6lG7yCtVB5PMFUHgV3Knv79u3tpptuCnS5D1Wzo+BMvdmU76P3RAnEwVJ6PyJBZVYZFHhpuADVGClJPTjAVHAbXKumAFZd5xWYtWjRwtWyffvtt+6aAMDL0vmSJmHA3STy5Mnjes0oBwQAEB6l+s5I8fktw1umqfMg7d6/qQECAACeQwAEAAA8hwAIAAB4DgEQAADwHAIgAADgOQRAAADAcwiAAACA5xAAAQAAzyEAAgAAnkMABAAAPIfJUMOo8oTKqXauVR1Xndf+119/vZs/ShNoJkcTjz788MNu8TpNnKr5siZOnGjXXnutmzy1dOnStnLlSvc+XqhOnTq5SUk/+eQTi2VfffWV/eMf/3BziWmiWs05pgl0V6xYEXLyWABIa/gmQ8CyZcvs3nvvtVilaes0EahmtM+WLZs1btzYNmzYkOJrNNlpunTpEi1XXHHFWc81btw4F/Ao+IFZs2bNLFOmTDZp0qRoFwUAwoIACIlmQNes7rHq2WeftRdffNEFJ999953lyJHDzQx/7NixFF9XqVIlN0O6f9Es92cLtDSLfdeuXcN8BWmbaq/0/gNAPCAA8pBTp05Zjx493Ey5+fLls/79+7ubfXATWHAT2ciRI61y5cou0ChevLj961//sr///jvw/G+//WatWrWyvHnzun0UaHzxxRcRKbvKqbI98cQT1rp1a6tSpYprntqxY8dZm5MyZsxohQoVCiy69pQsX77cNm3aZC1bnjlb9Lp161ytUNasWe2qq66yBQsWBJ47ffq0C5pUc6QaqgoVKtgLL7yQ4rnUtFS/fn3XzHTZZZfZjTfe6M7tp6Y31VpNmzbNNUkpQK1ataotXrw40XEWLVrkmjn1vH4eCgzVfCUJCQk2bNiwQLn0+g8//DDR6/Vzu/zyy93zOo/Om5R+1t9//32i8gFAWkUA5CETJkxwwcDSpUvdjVkBzuuvv57s/sr10F/8P//8s3vtf//7X3vssccCzz/wwAN2/Phx+/rrr23VqlX2zDPPWM6cOZM93v333++eT2lJzubNm23Xrl2u2ctPgdzVV199RjCQlJrJihQpYmXKlLE777zTtm7dmuL+33zzjQsGcuXKdcZzffr0sd69e7tcoLp167qgYP/+/YFAo1ixYvbBBx/YmjVrXHPdv//9b3v//feTPdfhw4etV69eLrCYN2+ee89vvvlmd6xg//nPf+zRRx+1H374wZXt9ttvdwGtaFujRo1czpLeC9VwqVwKyETBj4JF1ZzpZ/nII4/YXXfdFQjetm3bZm3btnWv0bHuuecel++TVIkSJaxgwYLu/QGAtI4kaA9RLc6oUaNcjYJqJxS0aL1bt24h9w9Ohlbt0FNPPeWCmJdfftltUyDRrl07V0skCjBS8uSTT7qb+IVQ8CO6AQfTuv+5UBQgvf322+561fw1ePBgu+6662z16tUhAxx/zZYCplBUg6ZrlldeecXV4LzxxhsuMFSOjI7vpxoXBSQKgG699daQx/Mfy+/NN990TZEKoFTD5Kf3zV8jpXOotm3jxo0un0lNg7Vq1Qr8XETPiwLUp59+2ubOnesCNv/PSUHSq6++ag0bNnTXUbZsWRsxYoR73v/ZUECblN4XvT8AkNYRAHnINddc44IfP90QddNTTUGGDBnO2F83TdUeqNnn0KFDrsZB+TZHjhxxTS0PPfSQde/e3WbPnu1qZnQzV9NUcgoUKOCW1NS8efPAY5VNAVHJkiVdUJJcjs/Ro0ddE1co/iBCVJumwGPt2rWBbWPHjnVBjIJDHUe9yVLqNabaKdUUKadp3759gZofvT44AAp+X5UELnv27HEBkGptbrnllpDHV5Ckn9f//M//JNquclWvXt09Vvn1viR3ncHURKbjAUBaRxMYQlIOiPJRdOP96KOPXF6Mbu7+m6eoqeTXX3+1u+++29UYKBh46aWXItIEptwd2b17d6LtWvc/dy6Ua6MmJAUGyVGOkD9/5nxMmTLF1dQosFJQqMCkc+fOgfcrFDU7/fHHHzZ+/HgXBGmRpK9R7ZKfP4j1B0sKSpLjz9maMWOGK49/UQ1T0jygc6GyqoYKANI6AiAP8d9c/ZYsWWLly5cPWfujgEc3WNUQqeZIQYMSjkM1qymwUZKucmN0I0+pCSz4JhxqSY6akxToKE/GT7VSuqbkaiuSCwiUxOuvRQlFNSOq9QpOEA9+z/xUI6b3qWLFioFEZCVIK1lcxyhXrlyKCcPKHVq/fr1L7FYOj45zIYGXgtTg9yWY8oKyZMniapRUnuBFPzvReZUXltx1+qn2T9fjrzkCgLQsJgIg1Swox0TNDqqKT/plHEw3WOVwqKeLFjW9JN3/QsaL8QLdBJVwq5vue++952prevbsGXJf3SBPnjzp9lEtzzvvvOOSaJPmCM2aNcslKGuAvPnz5weCgVDU/JX0Jpx0SY5qPXQ+5SF99tlnrsapQ4cOLielTZs2gf0USKgLu59qZJTsqxqtb7/91iUYK+BTEnFy1AtKgZIShkN9Vj/++GMXICkJXAFLly5d3HMKJpXMrPfkl19+cb3sNLZScvT5Vc+v1157zdVIKclcP5/z1a9fP3ceBV4//fSTK5vyetSkpjwnvQdKfFYiuwIY/az0c9W6KIDV74cSvPXZmDx5ssubSkpBkYKp8wk4ASBWRT0HaOrUqe5LXzdXBT/q6qwuvPoiDpUvohFqdfPyd0VWomaTJk3czapo0aKJxovRF7xqDnQj0jFV7Z9cbkc0RmdObQoYlJdSp04dFwQo+Elu4EN1lVYvMb2/usE2aNDA5QPpGH7KHVIQsH37dsudO7cbLE9J1ZGiRGP1mlKZNZqyuo8rCTn4Z6obvG78fiqbPi+qbVHTjV6jG3lKzTgKShQoadA/XXOw4cOHu0W1VQrYFIz5u9Xfd999rndY+/btXcCm8yoomTlzZsjzqMeXms2US6V8HyUf63Or7uznQ7VzanJTjzP9bBX063fJH+QNGTLEXa+uRcGsmgFr1Kjh9vf37lIzp4IkBUY6hhKn/YGdn4Jm9aKL5bGiAOBcpfOFqudPRfqirl27duCvdjW7qGr+wQcfDNkVNyndhPWXtF6vm7MuR7UCao7x9zg6ePCg6y2kv2pvu+22sx5TTSvqYq3X6cYO71FNihKHFVCllJvkFQoqFaCphkt/VAAXqlTfGSk+v2V4yzR1HsSW87l/R7UJTImeyqEIHttFfxVr/Wxju/ipR4qaai699NILHi9GXYX1pgUv8Dbl1aj2S58n/G9SvLrZE/wAiBcZo/1XpWpwQo3tojyGc/H444+7Gh9/wHMh48WoaSB4/BbAP/UD/pd6+GkBgHgRE0nQF0q5GMqhUFLqxeT2KMdF1WX+RSPjAgCA+BXVGiAljyoZ90LGdnn++eddAKTB+oIHiQseLya4q7PWkxuQTj1btAAAAG+Iag1Q5syZrWbNmonGMFEStNZT6mqrXl7q2aIeQEmr5cM1XgwAAIhfUe8Gry7wHTt2dIGMut+qG7y6OmsEXVHPLnVv93dHVmKqxvjRWCUaO8if1+MfSTh4vBiNy+LvBp90vBgAAOBdUQ+ANGbK3r17XVCjYEbNVKrZ8Scxa/A+9Qzz0wBv6j32z3/+M9FxBg4caIMGDTrn8WIAAIB3RX0coFjEOEAAEBmMA4RYuX9HvQYIAKKt8oTKaXqUdwAe6wYPAABwIQiAAACA5xAAAQAAzyEAAgAAnkMABAAAPOe8AyCNp7Nw4cLA+tixY93YPXfccYf9+eef4S4fAABA9AOgPn36uH72smrVKuvdu7e1aNHCNm/e7EZ1BgAAiHXnPQ6QAp0rr7zSPf7oo4/sxhtvtKefftpWrFjhAiEAQPIYcwhIozVAmsD0yJEj7rFmYm/SpIl7fOmllwZqhgAAAOKqBkjzaqmpq169erZ06VKbOnWq2/7LL79YsWLFIlFGAACA6NYAjRkzxjJmzGgffvihm5hUM7XLzJkzrVmzZuEtHQAAQCzUAJUoUcKmT59+xvZRo0aFq0wAAAARdUGToSYkJNjGjRttz5497nGwBg0ahKtsAAAAsREALVmyxI3589tvv5nP50v0XLp06ez06dPhLB8AAED0A6D777/fatWqZTNmzLDChQu7oAcAACCuA6ANGza4BOhy5cpFpkQAAACx1gvs6quvdvk/AAAAnqkBevDBB930F7t27bLKlStbpkyZEj1fpUqVcJYPABBhpfrOSPH5LcNbplpZgJgNgNq1a+f+79KlS2Cb8oCUEE0SNAAAiNu5wAAAADwVAJUsWTIyJQEAAIjlgRA3bdpko0ePtrVr17p1zQ7fs2dPK1u2bLjLBwAAEP1eYLNmzXIBjyZCVcKzlu+++84qVapkc+bMCX8JAQAAol0D1LdvX3vkkUds+PDhZ2x//PHH7X/+53/CWT4AAIDo1wCp2atr165nbFevsDVr1oSrXAAAALETAOXPn99++OGHM7ZrW4ECBcJVLgAAgNhpAuvWrZvde++99uuvv9q1117rti1atMieeeYZ69WrVyTKCAAAEN0AqH///pYrVy4bMWKE9evXz20rUqSIDRo0yB566KHwlg4AACAWAiCN9qwkaC1//fWX26aACAAAIK7HAfIj8AEAAHEbANWoUcPmzZtnefPmterVq7taoOSsWLEinOUDAACITgDUunVry5IlS+BxSgEQAIRD5QmVU3x+VcdVqVYWAB4NgAYOHBh4rGRnAAAAT40DVKZMGdu/f/8Z2w8cOOCeAwAAiLsAaMuWLXb69Okzth8/fty2b98ernIBAABEvxfYZ599lmhC1Dx58gTWFRApSbp06dLhLyEAAEC0AqA2bdq4/5UA3bFjx0TPZcqUyUqVKuUGRwQAAIibACghIcH9r1qeZcuWWb58+SJZLgAAgNgZCHHz5s2RKQkAAECsJkFrvq8XX3zxjO1jxoyxhx9+OFzlAgAAiJ0A6KOPPrJ69eqdsV0zw3/44YfhKhcAAEDsBEAaAyi4B5hf7ty5bd++feEqFwAAQOwEQOXKlbMvv/zyjO0zZ85kIEQAABCfSdC9evWyHj162N69e+2GG25w2zQGkLrAjx49OhJlBAAAiG4A1KVLFzfq89ChQ23IkCFum8YAeuWVV6xDhw7hLR0AAEAsBEDSvXt3t6gWKFu2bJYzZ87wlwwAACCWAiC//Pnzh68kAAAAsZoEvXv3brv77rutSJEiljFjRsuQIUOiBQAAIO5qgDp16mRbt261/v37W+HChd3cYAAAAHEdAC1cuNC++eYbq1atWmRKBAAAEGtNYMWLFzefzxeZ0gAAAMRiAKSxfvr27WtbtmyJTIkAAABirQmsffv2duTIEStbtqxlz57dMmXKlOj5P/74I5zlAwAAiH4AxGjPAADAcwFQx44dI1MSAACAWA2A1AU+JSVKlLiY8gAAAMReAKR5v1Ia++f06dMXWyYAAIDYCoBWrlyZaP3kyZNu28iRI90EqQAAAHEXAFWtWvWMbbVq1XJTYzz33HPWtm3bcJUNAAAgNsYBSk6FChVs2bJl4TocAABA7NQAHTp0KNG6RoXeuXOnDRo0yMqXLx/OsgEAAMRGAHTJJZeckQStIEhTZEyZMiWcZQMAAIiNAGj+/PmJ1tOnT2/58+e3cuXKWcaM5304AACA2MwBqlGjhv3555/u8YIFC6x27drWsGFDt1x33XV2xRVXXHDwM3bsWNe1PmvWrHb11Vfb0qVLk933559/tnbt2gW64ocalVpNcXoueFH5AAAAzisAWrt2rR0+fNg9Hjx4cODxxZo6dar16tXLBg4caCtWrHA9zJo2bWp79uwJub/mICtTpowNHz7cChUqlOxxK1Wq5PKS/MvChQvDUl4AABAfzqnaplq1ata5c2erX7++y/dRd/ecOXOG3HfAgAHnfHKNHdStWzd3bBk3bpzNmDHD3nzzTTfjfFKqedIioZ73U21USgESAADwtnMKgN5++21XSzN9+nTXpDRz5syQTV567lwDoBMnTtjy5cutX79+ifKJGjdubIsXL7aLsWHDBjcukZrV6tata8OGDUtxio7jx4+7JbmebgAAwIMBkMb48ffwUpAyb948K1CgwEWdeN++fW7ajIIFCybarvV169Zd8HGVR6SATWVW85ea7JSntHr1asuVK1fI1yhA0n4AAMAbznsgxISEhIsOfiKpefPmdsstt1iVKlVcPtEXX3xhBw4csPfffz/Z16gW6uDBg4Fl27ZtqVpmAACQuqLWbz1fvnyWIUMG2717d6LtWg9n/o7GLbr88stt48aNye6TJUsWtwAAAG8I21QY5ytz5sxWs2ZN15wWXLukdeXthMvff/9tmzZtssKFC4ftmAAAIG2L6siF6gLfsWNHN5lqnTp13Lg+6mLv7xXWoUMHK1q0qMvR8SdOr1mzJvD4999/tx9++MH1SNNAjPLoo49aq1atrGTJkrZjxw6XvK2apttvvz2KVwoAAGJJVAOg9u3b2969e13PsV27drnu9l9++WUgMXrr1q0u6dpPAU316tUD688//7xbNCDjV1995bZt377dBTv79+93I1Sr6/6SJUvcYwAAgAsOgJRU/OGHH7qmpT59+till17qBjJU4KIam/PRo0cPt4TiD2r8NAK0xiFKCfORAQCAsAdAP/30kxurJ0+ePLZlyxY3kKECoGnTprkam4kTJ57vIQEAAGI7CVp5O506dXKDDWqgQb8WLVrY119/He7yAQAARD8AWrZsmd13331nbFfTl/J4AAAA4i4A0ng5oaaK+OWXX0g0BgAA8RkA3XTTTfbkk0/ayZMnA/N/Kffn8ccft3bt2kWijAAAANENgEaMGOEGF9R0GEePHnVd0DUGj+bZGjp0aHhLBwAAEAu9wNT7a86cObZo0SL78ccfXTBUo0YN1zMMAAAgLgMgdXPXAIb16tVzi59GZtYYPBq9GQAAIK6awDRNhWZMT+qvv/4KTGEBAAAQVwGQRmJW4nNSmoJCzWMAAABx0wSmObgU+Ghp1KiRZcz4fy89ffq0bd682Zo1axapcgIAAKR+ANSmTRv3v2Zfb9q0qZuB3S9z5sxuni66wQMAgLgKgAYOHOj+V6CjJOjgaTAAAADiuhdYx44dI1MSAACAWA2AlO8zatQoe//9990I0Or+HuyPP/4IZ/kAAACi3wts8ODBNnLkSNcMpu7wmh2+bdu2lj59ehs0aFD4SwgAABDtAGjSpEk2fvx46927t+sJdvvtt9vrr79uAwYMsCVLloS7fAAAANEPgHbt2mWVK1d2j9UTzD8o4o033mgzZswIfwkBAACiHQAVK1bMdu7c6R6XLVvWZs+e7R4vW7bMsmTJEu7yAQAARD8Auvnmm23evHnu8YMPPmj9+/e38uXLuznAunTpEv4SAgAARLsX2PDhwwOPlQhdokQJW7x4sQuCWrVqFe7yAYgxlSf8bxN4clZ1XJVqZQGAVAuAkqpbt65bAAAA4ioA+uyzz875gDfddNPFlAcAACA2AiD/PGB+mhBVs8In3eYfKBEAACDNJ0EnJCQEFvX6qlatms2cOdMOHDjgFj2uUaOGffnll5EvMQAAQGrnAD388MM2btw4q1+/fmCbZofPnj273XvvvbZ27dqLLRMAAEBsdYPftGmTXXLJJWdsz5Mnj23ZsiVc5QIAAIidAKh27dpu/q/du3cHtulxnz59rE6dOuEuHwAAQPQDoDfffNONBK3xf8qVK+cWPf7999/tjTfeCH8JAQAAop0DpIDnp59+sjlz5ti6devctooVK1rjxo0DPcEAAADibiBEBTpNmjRxCwAAgCcCIM0FNmrUqECPL9UAqXeYaoEAzxiU5yzPH0ytkgAAIp0D9PLLL1uzZs0sV65c1rNnT7fkzp3bWrRoYWPHjj3fwwEAAMR+DdDTTz/tan969OgR2PbQQw9ZvXr13HMPPPBAuMsIAAAQ3RogjfysGqCklA908CBV/gAAIA4DIE12+vHHH5+x/dNPP7Ubb7wxXOUCAACInSawK6+80oYOHWpfffWV1a1b121bsmSJLVq0yHr37m0vvvhioqYxAACANB8AabDDvHnz2po1a9zip+kxggdCVFd5AiAAABAXAdDmzZsjUxIAAFILw1h43nnnAAEAAHiuBqhLly5nnSsMAAAgrgKgP//8M9H6yZMnbfXq1a57/A033BDOsgEAAMRGABSqC3xCQoJ1797dypYtG65yAQAAxHYOUPr06a1Xr15uhGgAAIC4nAw1lE2bNtmpU6fCdTgAwEWoPKFyis+v6rjKYhK9sxCrAZBqeoL5fD7buXOnzZgxwzp27BjOsgEAAMRGALRy5cozmr/y589vI0aMOGsPMQAAgDQZAM2fPz8yJQEAAEglDIQIAAA8J2xJ0ACA8CnVd0aKz28Z3jLVygLEI2qAAACA5xAAAQAAzzmnAOjSSy+1ffv2ucfq6fXXX39FulwAAADRDYBOnDhhhw4dco8nTJhgx44di1yJAAAAYiEJum7dutamTRurWbOmG/jwoYcesmzZsoXcl9ngAQBAXARA7777rpvnS9NdpEuXzg4ePEgtEAAAiO8AqGDBgjZ8+HD3uHTp0vbOO+/YZZddFumyAQAAxMY4QJs3b45MSQAAAGK5G/yCBQusVatWVq5cObfcdNNN9s0334S/dAAAALEQACkfqHHjxpY9e3aXDO1PiG7UqJFNnjw5EmUEAACIbhPY0KFD7dlnn7VHHnkksE1B0MiRI23IkCF2xx13hLeEAAAA0a4B+vXXX13zV1JqBiM/CAAAxGUAVLx4cZs3b94Z2+fOneueAwAAiLsmsN69e7smrx9++MGuvfZat23RokX29ttv2wsvvBCJMgIAAEQ3AOrevbsVKlTIRowYYe+//77bVrFiRZs6daq1bt06vKUDAETfoDxnef5gapUEiG43+JtvvtkWLlxo+/fvd4seX2jwM3bsWCtVqpRlzZrVrr76alu6dGmy+/7888/Wrl07t79GpB49evRFHxMAAHjPBQVA4aJao169etnAgQNtxYoVVrVqVWvatKnt2bMn5P5HjhyxMmXKuFGpVQsVjmMCAADviWoApK7z3bp1s86dO9uVV15p48aNc+MLJTehau3ate25556z2267zbJkyRKWY8rx48fdbPfBCwAAiF9RC4BOnDhhy5cvd4MqBgqTPr1bX7x4caoec9iwYZYnT57AQm82AADiW9QCoH379tnp06fdRKvBtL5r165UPWa/fv3cDPf+Zdu2bRd0fgAAEKe9wOKRmtOSa1IDAADx57wDINWwaMwfDYaoxOKEhIREz//3v/89p+Pky5fPMmTIYLt37060XevJJThH45gAACD+nHcTWM+ePd2iQOiqq65yvayCl3OVOXNmq1mzZqJRpRVMab1u3brnW6yIHRMAAMSf864BmjJlihsAsUWLFhd9cnVX79ixo9WqVcvq1KnjxvU5fPiw68ElHTp0sKJFi7okZX+S85o1awKPf//9dzcidc6cOa1cuXLndEwAAICMF1LL4g82Llb79u1t7969NmDAAJekXK1aNfvyyy8DScxbt251vbj8duzYYdWrVw+sP//8825p2LChffXVV+d0TAAAgAuaC0xzfo0ZM8aNxnyxevTo4ZZQ/EGNn0Z39vl8F3VMAACA8w6ANO3F/PnzbebMmVapUiXLlClTouenTZsWzvIB5495iwAA4Q6ALrnkEjcXGAAAgGcCoLfeeisyJQEAAIj1gRCVaLx+/Xr3uEKFCpY/f/5wlgsAACB2xgFSl/IuXbpY4cKFrUGDBm4pUqSIde3a1c3WDgAAEHcBkMbZWbBggX3++ed24MABt3z66adum3qIAQAAxF0T2EcffWQffvihXX/99YFtGhQxW7Zsduutt9orr7wS7jICABCzSvWdkeLzW4a3TLWyIII1QGrmCjWoYIECBWgCAwAA8RkAaU6tgQMH2rFjxwLbjh49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BEAAAMBzYiIAGjt2rJUqVcqyZs1qV199tS1dujTF/T/44AO74oor3P6VK1e2L774ItHzPp/PBgwYYIULF7Zs2bJZ48aNbcOGDRG+CgAAkFZEPQCaOnWq9erVywYOHGgrVqywqlWrWtOmTW3Pnj0h9//222/t9ttvt65du9rKlSutTZs2blm9enVgn2effdZefPFFGzdunH333XeWI0cOd8xjx46l4pUBAIBYFfVeYCNHjrRu3bpZ586d3bqClhkzZtibb75pffv2PWP/F154wZo1a2Z9+vRx60OGDLE5c+bYmDFj3GtV+zN69Gh74oknrHXr1m6fiRMnWsGCBe2TTz6x2267LZWvEDg7Bg0EAA8FQCdOnLDly5dbv379AtvSp0/vmqwWL14c8jXarhqjYKrdUXAjmzdvtl27drlj+OXJk8c1rem1oQKg48ePu8Xv4MGD7v9Dhw5ZXDvuS/n5cF5/DJ3r9NHTZynKoVQ/T8LxIynvmy6VrimM15Wa1xSP54rHa0rNc8XjNYXjXGH9ro1B/vdKlSFn5Yui33//XSX0ffvtt4m29+nTx1enTp2Qr8mUKZNv8uTJibaNHTvWV6BAAfd40aJF7pg7duxItM8tt9ziu/XWW0Mec+DAge41LCwsLCwsLJbml23btp01Bol6E1gsUA1UcK1SQkKC/fHHH3bZZZdZunTpoh7NFi9e3LZt22a5c+dO8+eJ13PF4zWl5rni8ZpS81zxeE2pea54vKbUPNehVLyms1HNz19//WVFihQ5675RDYDy5ctnGTJksN27dyfarvVChQqFfI22p7S//39tUy+w4H2qVasW8phZsmRxS7BLLrnEYok+VKnxwUqt88TrueLxmlLzXPF4Tal5rni8ptQ8VzxeU2qeK3cqXlNKlPYS873AMmfObDVr1rR58+Ylqn3Ret26dUO+RtuD9xclQfv3L126tAuCgvdRdKreYMkdEwAAeEvUm8DU9NSxY0erVauW1alTx/XgOnz4cKBXWIcOHaxo0aI2bNgwt96zZ09r2LChjRgxwlq2bGlTpkyx77//3l577TX3vJqsHn74YXvqqaesfPnyLiDq37+/qw5Td3kAAICoB0Dt27e3vXv3uoEL1XtLzVRffvml67YuW7dudT3D/K699lqbPHmy6+b+73//2wU56gF21VVXBfZ57LHHXBB177332oEDB6x+/frumBo4Ma1R05zGSEraRJdWzxOv54rHa0rNc8XjNaXmueLxmlLzXPF4Tal5riypeE3hlE6Z0NEuBAAAgKdGggYAAEhtBEAAAMBzCIAAAIDnEAABAADPIQCKYWPHjrVSpUq53muay2zp0qVhP8fXX39trVq1csMEaAgB/5xqkaChDGrXrm25cuWyAgUKuGEJ1q9fH/bzvPLKK1alSpXAoFwa/2nmzJmWGoYPHx4YiiHcBg0a5I4dvFxxxRUWCb///rvdddddbjT0bNmyWeXKld1wE+Gmz3fSa9LywAMPhP1cp0+fdkNiaGgMXVPZsmXdZMqR6AeikWj1GShZsqQ7l3qvLlu2LOK/r7oW9ajVILA6r+ZE3LBhQ0TONW3aNGvSpElgxPwffvghItd18uRJe/zxx91nMEeOHG4fDY+yY8eOsF+Tfsf0O6Xz5M2b171/GkMu3NeU1P333+/20TAwkThXp06dzvgda9asWUSuae3atXbTTTe5wQj1Puo7X725YxEBUIyaOnWqGyNJXQtXrFhhVatWdZO+7tmzJ6zn0XABOraCrUhbsGCBu7EtWbLEDV6pLzZ9gaoM4VSsWDEXiGiiXd20b7jhBmvdurX9/PPPFkm6wb366qsu+IqUSpUq2c6dOwPLwoULw36OP//80+rVq2eZMmVygeOaNWvcuFu6IUTiPQu+Hn0u5JZbbgn7uZ555hkXHI8ZM8Z9SWv92WeftZdeeins57rnnnvctbzzzju2atUq9znXzVSBZSR/X3U9L774oo0bN87duHUD0vfGsWPHwn4uPa8hRvQ+XqyUznXkyBH3HajgVf8r8NIfTrrJhvM8cvnll7vPh35m+t1SgK6fnYZqCfe5/D7++GP3nXguUzdczLkU8AT/rr333nthP8+mTZvcZ0JB5FdffWU//fST+7nF7BA0Z50tDFGhyWAfeOCBwPrp06d9RYoU8Q0bNixi59TH4eOPP/allj179rhzLliwIOLnyps3r+/111+P2PH/+usvX/ny5X1z5szxNWzY0NezZ8+wn0OT9latWtUXaY8//rivfv36vmjQ+1a2bFlfQkJC2I/dsmVLX5cuXRJta9u2re/OO+8M63mOHDniy5Ahg2/69OmJtteoUcP3n//8J2K/r3rPChUq5HvuuecC2w4cOODLkiWL77333gvruYJt3rzZPb9y5cqLOse5nMtv6dKlbr/ffvstouc5ePCg22/u3LkXfJ6UzrV9+3Zf0aJFfatXr/aVLFnSN2rUqIs6T3Ln6tixo69169YXfeyznad9+/a+u+66y5dWUAMUg06cOOFqL/QXo58Gg9T64sWLLV4cPHjQ/X/ppZdG7Bxq9tBo4frLJZJToahmSyOTB//MIkHNGfpLsUyZMnbnnXdGpGr5s88+cyOzqxZGTZXVq1e38ePHW2p87t99913r0qVLRCYhVjOUpsj55Zdf3PqPP/7o/spv3rx5WM9z6tQp97lL+levmqQiUWPnt3nzZjeYbPBnUM0Qaj6Pp+8N/3eHPiORnLNRn0fNMKD3ULUe4aZpn+6++27r06ePq9mNNNXI6Pe5QoUK1r17d9u/f3/Yr2fGjBmuFk21jjqXPnuRTKu4WARAMWjfvn3uC9Q/Graf1vUFFw/0y6IcCTW1BI/iHS6qws6ZM6cbmVTt66pmvvLKKy0SFGCpat4/XUuk6Mvk7bffdqOaqylHN7zrrrvO5ZuE06+//uqOr1HWZ82a5b4sH3roIZswYYJFkr4oNXK78hUioW/fvnbbbbe56nk17ymw02dQgWQ4KcdNwbbyi5Snot9lBXYKQtT0ECn+74Z4/t4QNecpJ+j222+PyMSb06dPd98dCmBHjRrlmjI1cXe4qekwY8aM7ncr0tT8NXHiRPcHgM6rdITmzZu7z2a4KD3j77//dukHOt/s2bPt5ptvtrZt27rzxaKoT4UBb1KNyerVqyP2F7H+ylFSpv5S/PDDD918c/olDHcQtG3bNjc/nb4kI93OHVxToTwjBURKsn3//feta9euYQ1OVQP09NNPu3UFCvpZKa9E72OkvPHGG+4aLyYXIiV6nyZNmuSm0tFf3Pp8KADS+cJ9Xcr9UU2W5jHMkCGD1ahRw92wVbOLC6e8wVtvvdUleytIj4R//OMf7rOhP0RV86nzKZ9KNRrhos/BCy+84P5wikRtZ1IK/P2UTK7vj7Jly7paoUaNGoXte0OUb/nII4+4x5ra6ttvv3XfHZrDM9ZQAxSD9NeGvjR3796daLvWNdN9WtejRw/3V9b8+fNdwnIkZM6c2cqVK2c1a9Z0NTOqwtYXTrjpi0x/+egGp7/mtCjQUiKqHofzL6ykVP2v6uaNGzeG9bjqQZQ0UKxYsWJEe3L89ttvNnfuXJc8HClqavDXAukmoOYHfVFHouZONxd9DvQXsYJk9eDUzVtNl5Hi/26I1+8Nf/Cjz4r+4IhE7Y8ocVzfHddcc40LyvV7rP/D6ZtvvnHfGyVKlAh8b+i6evfu7RKvI02fw3z58oX1u0PH03Wk9nfHxSAAikG6eevGrerK4Oha65HMY4k0/dWm4EfNUf/9739dd+TUovfv+PHjYT+u/npSc5v+YvQvqj1Rs4oeK5CNFN1c1etCAUs4qVky6fAEyptRbVOkvPXWW+4vbOVRRYp6EwVPrCz6+fj/co3UzVQ/H/WsU3Oi/jqOFP0+KdAJ/t44dOiQq71Iy98bwcGPcuAUKKvrfVr+7lDwrR5Swd8bqolUkK7PSaRt377d5QCF87tD9y11eU/t746LQRNYjFIXeFXL62Zap04dNz6EEnk7d+4c9pto8F8ByivRL6MSk/XXSbibvdT88Omnn7o8CX9egpIMlSAaLv369XNNKSq/8mN0TlX1RuKLRdeRNIdJNz19QYc7t+nRRx91Y3Doy0S5JRoiQTdwNa2Ek2pFlDCsJjDddFR7oWRQLZG6wSgA0uddf0FGit67oUOHus+FmsBWrlxpI0eOdE1V4abPmgJ+NcXq90s3NuUeXezv79l+X9Wk99RTT7n8LQVE6oKsG6vG3Ar3uf744w/3l71/PB7/jU9B2PnWOKV0Lt2k//nPf7rmItUcq1bV/92h53XjDcd59Durz4e61+ucagJTd28NXXAhwzKc7f1LGsQpL03vmz4z4TyXlsGDB1u7du3c8fVH02OPPeZquZSsHM5r0ue8ffv21qBBA9eUqHzFzz//3H3/xqRod0ND8l566SVfiRIlfJkzZ3bd4pcsWRL2c8yfP991Z0y6qNtkuIU6j5a33norrOdRV2d1KdX7lj9/fl+jRo18s2fP9qWWSHWDVxfTwoULu+tS11mtb9y40RcJn3/+ue+qq65yXaivuOIK32uvveaLlFmzZrnPwfr1632RdOjQIfdz0e9U1qxZfWXKlHHd0o8fPx72c02dOtUdXz8rdU3XkBbqkh7p31d1he/fv7+vYMGC7menz/6Fvq9nO5d+b0M9r+Eawnkufzf7UIteF67zHD161HfzzTe74Ub0c9Pv2k033eS63KfGd+vFdINP6VwalqFJkybuuzBTpkzuPN26dfPt2rUrItf0xhtv+MqVK+d+xzRsxyeffOKLVen0T7SDMAAAgNREDhAAAPAcAiAAAOA5BEAAAMBzCIAAAIDnEAABAADPIQACAACeQwAEAAA8hwAIAAB4DgEQgDTv+uuvd9NApDWaCfyTTz455/01pYBec+DAgYiWC/ACAiAAAZ06dQo5b1Ss33inTZtmQ4YMsbRm586dbt66cBo0aJBVq1YtrMcE4hGToQJI8zQZY1p0vpOGAggfaoAAnLf9+/e7WeiLFi1q2bNnt8qVK9t77713RrPUgw8+6Jqm8ubNawULFrTx48fb4cOH3azouXLlcjNSz5w584yaJs2mXr16dcuWLZvdcMMNtmfPHrdfxYoVLXfu3HbHHXfYkSNHkm0CK1WqlJvNXjO96zyaqTrpbPbffvutqynJmjWr1apVyzVF6dya3TqUMWPG2FVXXRVY9+8/bty4wLbGjRvbE088EVj/9NNPrUaNGu4cZcqUcbNynzp1KtkmsHMt0/Lly93zeu+vvfbawEzsb7/9tjvHjz/+6F6nRdsAnIkACMB5O3bsmNWsWdNmzJhhq1evtnvvvdfuvvtuW7p0aaL9JkyYYPny5XPbFQx1797dbrnlFnfTXrFihTVp0sS9LjiY8TfjKOBQQLBt2za79dZbbfTo0TZ58mR3ztmzZ9tLL72UYhlHjBjhgoSVK1fav/71L3duf6Bw6NAha9WqlQvcVA41nz3++OMpHq9hw4a2Zs0a27t3r1tfsGCBuzYFbXLy5ElbvHixC8bkm2++sQ4dOljPnj3d61599VUXjAwdOjTk8c+nTP/5z3/c9X3//feWMWNGF+hJ+/btrXfv3lapUiXXvKZF2wCEEO3p6AHEjo4dO/oyZMjgy5EjR6Ila9asPn1d/Pnnn8m+tmXLlr7evXsH1hs2bOirX79+YP3UqVPuWHfffXdg286dO91xFy9e7Nbnz5/v1ufOnRvYZ9iwYW7bpk2bAtvuu+8+X9OmTROdq2fPnoH1kiVL+u66667AekJCgq9AgQK+V155xa3r/8suu8x39OjRwD7jx49351m5cmXI69Mx9JoPPvjArVerVs2VrVChQm594cKFvkyZMvkOHz7s1hs1auR7+umnEx3jnXfe8RUuXDiwrvN9/PHH51ymUO/PjBkz3Db/6wYOHOirWrVqyGsA8H+oAQKQyD/+8Q/X5BK8vP7664n2OX36tKuhUG2F8m9y5szpmq22bt2aaL8qVaoEHmfIkMEuu+wy9xo/NYuJmriSe532UVOPmpCCtyV9TVLBx1BTkPJt/K9RTZCeV1OTX506dVI8no7RoEEDV+OjZHDV6qhm6fjx47Zu3TpXI1S7dm1XVlEz1JNPPuneG//SrVs3VyuTtMbrfMsUfG2FCxd2/5/t/QCQGEnQABLJkSOHy80Jtn379kTrzz33nL3wwguuWUoBjV6jHJwTJ04k2i9TpkxnBBHB27QuCQkJyb4u6Wv825K+JqkLec3ZqHlLuURq3lKOkvKR/EGRAiA1k/n9/fffLh+nbdu2ZxwnOMi5EOfyHgJIGTVAAM7bokWLrHXr1nbXXXdZ1apVXe3ML7/8YmlFhQoVbNWqVa72xm/ZsmVnfZ0/D+iDDz4I5Pro/7lz57r3xL9NlPysWh0Fk0mX9OnTh61MSWXOnNnV0AFIGQEQgPNWvnx5mzNnjktSXrt2rd133322e/duSyvUi0w1JkreVvnVfPf8888nqlFJrulJPdqUjB0cAKm3lgKXevXqBfYdMGCATZw40dUC/fzzz+48U6ZMSdRLLBxlSko94DZv3uyaLvft25cooALwfwiAAJw33cRVw9G0aVMXACi/JtQAirFKTVeff/65CxLU7Vy9qhSwnK15SoHIdddd5/6vX79+ICjS8dTjTE2Bfnpvpk+f7nqsKTfommuusVGjRlnJkiXDWqak2rVrZ82aNXO5XPnz5z9jeAIA/yudMqH//2MA8KxJkya58YkOHjzoxh+KBbFYJiBekAQNwJPUPKXcJQ3mqB5bGnNH4w1FM9CIxTIB8YoACIAn7dq1yzUx6X91JdcAjckNUujlMgHxiiYwAADgOSRBAwAAzyEAAgAAnkMABAAAPIcACAAAeA4BEAAA8BwCIAAA4DkEQAAAwHMIgAAAgHnN/wP0QEOkqpZIUwAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 1000 #network size\n",
    "n = 4   #constant in-degree\n",
    "\n",
    "bn1 = bf.random_network(N=N,n=n,bias=0.75)\n",
    "bn2 = bf.random_network(N=N,n=n,absolute_bias=0.5,use_absolute_bias=True)\n",
    "bn3 = bf.random_network(N=N,n=n,absolute_bias=0.5)\n",
    "bns = [bn1,bn2,bn3]\n",
    "\n",
    "labels = [\"bias = 0.75\", \"absolute bias = 0.5\", \"bias = 0.5 (balanced)\"]\n",
    "possible_hamming_weights = np.arange(2**n + 1)\n",
    "width = 0.3\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "for i,bn in enumerate(bns):\n",
    "    count = np.zeros(2**n + 1)\n",
    "    for f in bn.F:\n",
    "        count[f.hamming_weight] += 1\n",
    "    ax.bar(possible_hamming_weights - width + i * width, \n",
    "           count / N, \n",
    "           width=width, label=labels[i])\n",
    "\n",
    "ax.legend(frameon=False)\n",
    "ax.set_xticks(possible_hamming_weights)\n",
    "ax.set_xlabel(\"Hamming weight\")\n",
    "ax.set_ylabel(\"Proportion of update functions\");"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20dfb72d",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this tutorial you learned how to:\n",
    "\n",
    "- generate random wiring diagrams with prescribed structural constraints,\n",
    "- generate, for each node in a wiring diagram, random update functions \n",
    "  with prescribed functional constraints.\n",
    "\n",
    "In the next tutorial, we will explore several situations, in which the ability\n",
    "to generate large ensembles of controlled random Boolean networks is very useful. "
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "python",
   "notebook_metadata_filter": "-all"
  },
  "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.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}