style(notebooks): 🎨 amendments to markdown and comments to help improve clarity and/or grammar, and addition of some illustrations

Author: amyheather

content/01_sampling.ipynb

@@ -5,22 +5,33 @@
    "id": "50446585-a13f-4c90-9700-58015b670d9c",
    "metadata": {},
    "source": [
-    "# A first look at simpy\n",
+    "# An introduction to SimPy\n",
     "\n",
-    "In this tutorial we will make use of **Free and Open Source Software (FOSS)** for discrete-event simulation called `simpy`. \n",
+    "In this tutorial, we will use **SimPy**, a free and open-source software (FOSS) framework for discrete-event simulation.\n",
     "\n",
-    "## Why FOSS and simpy?\n",
-    "An strength of `simpy` is its simplicity and flexibility.  As it is part of Python, it is often straightforward to use `simpy` to model complex logic and make use of the SciPy stack!  Initially, you will need to write a lot of code (or borrow code from other simulation studies you find online!). But don't worry. As you use `simpy` you will build your own library of reusable code that you can draw on (and build on) for future simulation projects.  As `simpy` is FOSS it is useful for research: the model logic is transparent, can be readily shared with others, and can easily link to other data science tools such as those from Machine Learning (e.g. `sklearn` or `pytorch`). \n"
+    "## 1. Why choose FOSS and SimPy?\n",
+    "\n",
+    "💪 A strength of SimPy is its **simplicity and flexibility**.\n",
+    "\n",
+    "* As it is part of Python, it is often straightforward to use SimPy to model complex logic and make use of the [SciPy stack](https://projects.scipy.org/stackspec.html)!\n",
+    "\n",
+    "📝 You will initially need to **write lots of code** - or borrow code from existing simulation studies online. Do not worry though! As you use SimPy, you will build up your own library of reusable code that you can draw upon and build on for future simulation projects.\n",
+    "\n",
+    "♻️ SimPy is **FOSS** - the benefits of this for research are that:\n",
+    "\n",
+    "* Model logic is **transparent**\n",
+    "* It can be readily **shared** with others\n",
+    "* It can easily **link to other data science tools** (e.g. `sklearn` or `pytorch` for machine learning)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "71ec6d31-c791-4945-83fd-c96670e4b492",
    "metadata": {},
    "source": [
-    "## 1. Imports\n",
+    "## 2. Imports\n",
     "\n",
-    "The first library we will import is `simpy`.  The typical style is to import the whole package as follows:"
+    "For `simpy`, the typical style is to import the whole package as follows:"
    ]
   },
   {
@@ -33,90 +44,75 @@
     "import simpy"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "dda6f531-3e2d-4e65-8ad6-0703f09df810",
-   "metadata": {},
-   "source": [
-    "We will also need a few other packages in our simulation model.   "
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "id": "9f083908-66a9-47ea-af29-c2baaaeef4c4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import numpy as np\n",
-    "import pandas as pd\n",
-    "import matplotlib.pyplot as plt\n",
-    "import itertools\n",
-    "import math"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "968d7a3d-763d-48a0-9915-421631d1f650",
    "metadata": {},
    "source": [
-    "## 2. A first example: a hospital pharmacy\n",
+    "## 3. An example: a hospital pharmacy\n",
     "\n",
-    "In this first example, let's assume (unrealistically) that prescriptions arrive **exactly** 5 minutes apart.  To build this model we need the following components:\n",
+    "In this first example, let's assume (unrealistically) that prescriptions arrive **exactly** 5 minutes apart.\n",
     "\n",
-    "#### **A simpy environment**\n",
+    "![Pharmacy with prescriptions every 5 minutes](../img/pharmacy.png)\n",
+    "\n",
+    "## 4. The model building blocks\n",
+    "\n",
+    "To build our model, we will need the following components...\n",
+    "\n",
+    "### 4.1 A SimPy environment\n",
     "\n",
     "`simpy` has process based worldview.  These processes take place in an environment.  You can create a environment with the following line of code:\n",
     "\n",
     "```python\n",
     "env = simpy.Environment()\n",
     "```\n",
     "\n",
-    "#### **simpy timeouts**\n",
+    "### 4.2 SimPy timeouts\n",
     "\n",
-    "We can introduce **delays** or **activities** into a process.  For example these might be the duration of a stay on a ward, or the duration of a operation.  In this case we are going to introduce a delay between arrivals (inter-arrival time).  In `simpy` you control this with the following method:\n",
+    "We can introduce **delays** or **activities** into a process.  For example these might be the duration of a stay on a ward, or the duration of a operation - or, in this case, a **delay between arrivals (inter-arrival time)**. In `simpy` you control this with the following method:\n",
     "\n",
     "```python\n",
-    "activity_duration = 20\n",
-    "env.timeout(activity_duration)\n",
+    "env.timeout(5.0)\n",
     "```\n",
     "\n",
-    "#### **generators**\n",
+    "### 4.3 Generators\n",
+    "\n",
+    "The events in the DES are modelled and scheduled in `simpy` using python **generators** (i.e. they are the \"event-processing mechanism\"). A generator is a function that behaves like an iterator, meaning it can yield a **sequence of values** when iterated over.\n",
     "\n",
-    "The event process mechanism in `simpy` is implemented using python generators.  A basic generator function that yields a new arrival every 5 minutes looks like this:\n",
+    "For example, below is a basic generator function that yields a new arrival every 5 minutes. It takes the **environment** as a parameter. It then internally calls the `env.timeout()` method in an infinite loop.\n",
     "\n",
     "```python\n",
     "def prescription_arrival_generator(env):\n",
     "    while True:\n",
     "        yield env.timeout(5.0)\n",
     "```\n",
     "\n",
-    "Notice that the generator takes the environment as a parameter.  It then internally calls the `env.timeout()` method in an infinite loop.\n",
-    "\n",
-    "#### **running a `simpy` model**\n",
+    "### 4.4 SimPy process and run\n",
     "\n",
     "Once we have coded the model logic and created an environment instance, there are two remaining instructions we need to code.\n",
     "\n",
-    "1. set the generator up as a simpy process\n",
+    "1. Set the generator up as a **SimPy process** using `env.process()`\n",
     "\n",
     "```python\n",
     "env.process(prescription_arrival_generator(env))\n",
     "```\n",
     "\n",
-    "2. run the environment for a user specified run length\n",
+    "2. Run the environment for a user specified **run length** using `env.run()`\n",
     "\n",
     "```python\n",
     "env.run(until=25)\n",
     "```\n",
     "\n",
     "The run method handle the infinite loop we set up in `prescription_arrival_generator`. The simulation model has an internal concept of time.  It will end execution when its internal clock reaches 25 time units.\n",
     "\n",
+    "## 5. Create the model\n",
+    "\n",
     "**Now that we have covered the basic building blocks, let's code the actual model.**  It makes sense to create our model logic first.  The code below will generate arrivals every 5 minutes.  Note that the function takes an environment object as a parameter."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 2,
    "id": "a6fd524c-7dc4-41c0-876d-3507ce480dfb",
    "metadata": {},
    "outputs": [],
@@ -149,12 +145,14 @@
    "id": "aa6042f3-b7a7-4c3a-a5d8-7eb7f3796bf2",
    "metadata": {},
    "source": [
-    "Now that we have our generator function we can setup the environment, process and call run.  We will create a `RUN_LENGTH` parameter that you can change to run the model for different time lengths.  What would happen if this was set to 50?"
+    "Now that we have our generator function we can setup the environment, process and call run.  We will create a `RUN_LENGTH` parameter that you can change to run the model for different time lengths.\n",
+    "\n",
+    "**Consider:** What would happen if we set `RUN_LENGTH` to 50?"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 3,
    "id": "f6f74ff5-4c95-400e-8494-42e438b18b90",
    "metadata": {},
    "outputs": [
@@ -190,9 +188,11 @@
    "id": "c3aa041b-6b8f-4b15-becc-bd966d0eb794",
    "metadata": {},
    "source": [
-    "## Exercise\n",
+    "## 6. Exercise\n",
+    "\n",
+    "Before we learn anything more about `simpy`, have a go at the [generators exercise](./03a_exercise1.ipynb).\n",
     "\n",
-    "Before we learn anything more about `simpy` have a go at the generators exercise. In the exercise you will need to modify the `prescription_arrival_generator` so that it has random arrivals. This exercise test that you have understood the basics of `simpy` and random sampling in `numpy`\n"
+    "In the exercise you will need to modify the `prescription_arrival_generator` so that it has random arrivals. This exercise tests that you have understood the basics of `simpy` and random sampling in `numpy`\n"
    ]
   }
  ],
@@ -212,7 +212,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "version": "3.1.undefined"
   }
  },
  "nbformat": 4,

content/02_basic_simpy.ipynb

@@ -7,20 +7,20 @@
    "source": [
     "# Generator exercise\n",
     "\n",
-    "To see the solutions please see the [generator exercise solutions notebook](./03b_exercise1_solutions.ipynb)\n"
+    "🧐 For the solutions, please see the [generator exercise solutions notebook](./03b_exercise1_solutions.ipynb)\n"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "c034caf3-6766-4c69-af8f-949f45283b37",
    "metadata": {},
    "source": [
-    "## Imports"
+    "## 1. Imports"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "85fd4a85-bb77-498c-96ee-c14de89994a2",
    "metadata": {},
    "outputs": [],
@@ -34,14 +34,14 @@
    "id": "bfab7f97-9cad-419a-8d75-a2ba190edee8",
    "metadata": {},
    "source": [
-    "## Example code\n",
+    "## 2. Example code\n",
     "\n",
-    "The code below is taken from the simple pharmacy example.  In this code arrivals occur with an IAT of exactly 5 minutes."
+    "The code below is taken from the simple pharmacy example.  In this code arrivals occur with an inter-arrival time (IAT) of exactly 5 minutes."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 2,
    "id": "ee2439f2-0d35-41fd-a5e2-4b95954dd5c5",
    "metadata": {},
    "outputs": [],
@@ -72,10 +72,22 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 3,
    "id": "40c495d5-6f55-4c93-99e3-5bfa6cdff36d",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Prescription arrives at: 5.0\n",
+      "Prescription arrives at: 10.0\n",
+      "Prescription arrives at: 15.0\n",
+      "Prescription arrives at: 20.0\n",
+      "end of run. simulation clock time = 25\n"
+     ]
+    }
+   ],
    "source": [
     "# model parameters\n",
     "RUN_LENGTH = 25\n",
@@ -96,28 +108,29 @@
    "id": "6b1bd501-1614-4891-a876-d07bd40c0496",
    "metadata": {},
    "source": [
-    "### Exercise: modelling a poisson arrival process for prescriptions\n",
+    "## 3. Exercise: Modelling a poisson arrival process for prescriptions\n",
     "\n",
     "**Task:**\n",
     "\n",
-    "* Update `prescription_arrival_generator()` so that inter-arrival times follow an exponential distribution with a mean of 5.0 minutes between arrivals.\n",
-    "* Use a run length of 25 minutes.\n",
+    "Update `prescription_arrival_generator()` so that inter-arrival times follow an **exponential distribution** with a mean of 5.0 minutes between arrivals. Use a run length of 25 minutes.\n",
     "\n",
-    "> **Bonus**: try this initially **without** setting a random seed.  Then update the method choosing an approach to control random sampling.\n",
+    "**Bonus challenge:**\n",
     "\n",
-    "**Hints:**\n",
+    "* First, try implementing this **without** setting a random seed.\n",
+    "* Then, update the method with an approach to control the randomness,\n",
     "\n",
-    "We learnt how to sample using a `numpy` random number generator in the [sampling notebook](./01_sampling.ipynb). The basic form to draw a single sample followed this pattern (note this excludes a random seed).\n",
+    "**Hints:**\n",
     "\n",
-    "```python\n",
-    "rng = np.random.default_rng()\n",
-    "sample = rng.exponential(scale=12.0)\n",
-    "```"
+    "* We learnt how to sample using a `numpy` random number generator in the [sampling notebook](./01_sampling.ipynb). Excluding a random seed, the basic method for drawing a single sample follows this pattern:\n",
+    "    ```python\n",
+    "    rng = np.random.default_rng()\n",
+    "    sample = rng.exponential(scale=12.0)\n",
+    "    ```"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 4,
    "id": "65823eff-8d0f-4eaf-a531-173c8ab6290c",
    "metadata": {},
    "outputs": [],
@@ -142,7 +155,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "version": "3.11.10"
   }
  },
  "nbformat": 4,