diff --git a/episodes/notebooks/0-introduction.ipynb b/episodes/notebooks/0-introduction.ipynb
new file mode 100644
index 00000000..981f59cb
--- /dev/null
+++ b/episodes/notebooks/0-introduction.ipynb
@@ -0,0 +1,80 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "e711a389-fa02-411b-a549-4612172c6a01",
+   "metadata": {},
+   "source": [
+    "# This course is\n",
+    "* Designed for researchers who write Python but lack formal computer science training\n",
+    "* Teaches how to assess where time is spent during the execution of a Python program\n",
+    "* Provides a high-level understanding of how code executes\n",
+    "* Explains how execution maps to performance bottlenecks and highlights good practices"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e2ab7b89-eada-4c43-8259-066cd5ec53ab",
+   "metadata": {},
+   "source": [
+    "# Expected Outcomes: \n",
+    "After this training, participants will be able to:\n",
+    "* Use tools like cProfile and line_profiler to find which functions or lines of code take the most time.\n",
+    "* Check code to understand what slows it down.\n",
+    "* Learn about some common performance problems and apply fixes to make code run faster"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "303b5679-d006-4682-aa54-f818a77dbffb",
+   "metadata": {},
+   "source": [
+    "# Requirements to follow along the course:\n",
+    "1. Create a conda environment using python 3.11 or newer\n",
+    "   In command line, run: \n",
+    "```bash\n",
+    "conda create --name py311_env python=3.11\n",
+    "conda activate py311_env\n",
+    "```\n",
+    "2. Install the required packages:\n",
+    "```bash\n",
+    "pip install pytest snakeviz line_profiler[all] numpy pandas matplotlib\n",
+    "```\n",
+    "\n",
+    "**Note for MacOS users**:\n",
+    "`line_profiler` could also be installed as well using conda:\n",
+    "```bash\n",
+    "conda install -c conda-forge line_profiler\n",
+    "```\n",
+    "\n",
+    "3. Install jupyter lab and register an ipykernel:\n",
+    "```bash\n",
+    "pip install jupyterlab \n",
+    "conda install ipykernel -y\n",
+    "python -m ipykernel install --user --name py311_env --display-name \"py311_env\"\n",
+    "```\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/episodes/notebooks/1-profiling-introduction.ipynb b/episodes/notebooks/1-profiling-introduction.ipynb
new file mode 100644
index 00000000..a9ba2889
--- /dev/null
+++ b/episodes/notebooks/1-profiling-introduction.ipynb
@@ -0,0 +1,188 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a47fdbc2-1d23-4913-9474-49c255ecbcd9",
+   "metadata": {},
+   "source": [
+    "# What is Performance Profiling?\n",
+    "It is the process of analysing and measuring the performance of a running code.\n",
+    "It is a dynamic analysis\n",
+    "\n",
+    "# Why should you profile your code?\n",
+    "##### 1. To assess the performance of you program/code, i.e, identify which operation is taking the longest time to execcute\n",
+    "##### 2. Useful when code grows more complex, making slow parts harder to spot \n",
+    "##### 3. Profiling highlights true bottlenecks, avoiding wasted effort on minor optimisations, and can lead to dramatic speedups.\n",
+    "##### 4. In HPC and beyond, profiling also ensures efficient use of energy and resources.\n",
+    "##### 5. It is a quick and inexpensive process, i.e., you get an instanteneous feedback about your code performance\n",
+    "* If no bottlenecks is identified, then you can be confident your code is performant\n",
+    "* Otherwise, the profiler will identify the piece of code that can benefit from an optimisation.\n",
+    "##### 6. Profiling is for everyone, not only for novices !!!\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "239476f1-1f05-4151-98f8-8586d7872897",
+   "metadata": {},
+   "source": [
+    "## Different types of profilers:\n",
+    "* Manual profiling\n",
+    "* Function-Level Profiling\n",
+    "* Line-Level Profiling, among others"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "849a0bb2-5fd2-4a74-b41b-85cfa9384158",
+   "metadata": {},
+   "source": [
+    "# 1. Manual profiling\n",
+    "* Manually adding timers around sections of code\n",
+    "* It provides a simple way to measure execution time and get a basic form of profiling.\n",
+    "* But it is intrusive to the code as we add plenty of `temporary lines of code`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "d2979752-71b3-4b56-89b2-5f40bce977bb",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "first hello\n",
+      "hello all\n",
+      "A: 0.0003226249828003347 seconds\n",
+      "B: 3.500000457279384e-05 seconds\n",
+      "C: 6.700001540593803e-05 seconds\n",
+      "C: 0.00044095798511989415 seconds\n"
+     ]
+    }
+   ],
+   "source": [
+    "# example of manual profiling:\n",
+    "import time\n",
+    "\n",
+    "# Record timestamps before and after different sections of code using time.monotonic()\n",
+    "t_a = time.monotonic()\n",
+    "print('first hello')\n",
+    "\n",
+    "t_b = time.monotonic()\n",
+    "a = \"hello\"\n",
+    "\n",
+    "t_c = time.monotonic()\n",
+    "c = a + \" all\"\n",
+    "print(c)\n",
+    "\n",
+    "t_d = time.monotonic()\n",
+    "mainTimer_stop = time.monotonic()\n",
+    "\n",
+    "# Calculate the time taken by subtracting the start time from the end time for each block.\n",
+    "print(f\"A: {t_b - t_a} seconds\")\n",
+    "print(f\"B: {t_c - t_b} seconds\")\n",
+    "print(f\"C: {t_d - t_c} seconds\")\n",
+    "print(f\"C: {mainTimer_stop - t_a} seconds\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "cacf5d33-73d3-4d31-9019-929dc6f5813b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "0.7316456299404912"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "0.0003226249828003347/0.00044095798511989415"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b284fa39-1d01-45c4-9346-d5e73fe6f201",
+   "metadata": {},
+   "source": [
+    "### Summary of Manual profiling :\n",
+    "* It is handy for small sections of code\n",
+    "* Increasingly impractical as a project grows in size and complexity\n",
+    "* Also, it is time consuming to be routinely adding and removing these timestamp recordings if they are not relevant as outputs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "db4706da-ddd2-4c5a-acd7-c82889eedba2",
+   "metadata": {},
+   "source": [
+    "# 2. Function-Level Profiling\n",
+    "Software is made up of many functions, including those you write and those from the standard library or third-party packages.\n",
+    "\n",
+    "* `Function-level profiling` measures how much time your program spends in each function, including or excluding time spent in child functions\n",
+    "* Counts how often each function is called\n",
+    "* Helps identify functions that take up the most time, so you can focus on optimizing them.\n",
+    "* `Function-level profiling` may not always give enough detail, especially if a function is particularly complex.\n",
+    "\n",
+    "In this course, we will use `cProfile` for function-level profiling and `snakeviz` to visualize the results."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7649e2fd-5abc-4004-ba53-e74db341d5dc",
+   "metadata": {},
+   "source": [
+    "# 3. Line-Level Profiling\n",
+    "\n",
+    "* `Line-level profiling` looks at how much time is spent on `each individual line of code`.\n",
+    "* This helps identify specific lines that take up a large portion of the total runtime.\n",
+    "* In this course, we will use `line_profiler` for `line-level profiling`.\n",
+    "* `line_profiler` is deterministic, tracking every line of code executed, which could be very expensive\n",
+    "* To avoid it being too costly, the profiling is restricted to methods targeted with the decorator `@profile`.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ebba3060-dccc-483b-bdee-95306246f6a7",
+   "metadata": {},
+   "source": [
+    "## Start Small, Scale Smart\n",
+    "A representative test-case should be profiled, that is large enough to amplify any bottlenecks whilst executing to completion quickly.\n",
+    "\n",
+    "* Profiling slows programs, so use a small, representative test-case.\n",
+    "\n",
+    "* Keep runs short (a few minutes if possible) to avoid huge output data.\n",
+    "\n",
+    "* Start small (e.g., one day of a year-long model) and scale if needed to spot bottlenecks."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/episodes/notebooks/2-profiling-functions.ipynb b/episodes/notebooks/2-profiling-functions.ipynb
new file mode 100644
index 00000000..8fe15365
--- /dev/null
+++ b/episodes/notebooks/2-profiling-functions.ipynb
@@ -0,0 +1,501 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a45fbb65-3542-47af-a57e-076033e1f147",
+   "metadata": {},
+   "source": [
+    "# Function profiling\n",
+    "* When is function level profiling appropriate?\n",
+    "* How can `cProfile` and `snakeviz` tools be used to profile a Python program?\n",
+    "* How are the outputs from function level profiling interpreted?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "26c6f773-6a70-4a19-8ed4-35abd37abc77",
+   "metadata": {},
+   "source": [
+    "### Software is usually made up of a hierarchy of function calls:\n",
+    "* Some written by the developer\n",
+    "\n",
+    "* Others from the standard library or third-party packages\n",
+    "\n",
+    "#### `Function-level profiling` shows where time is being spent in functions.\n",
+    "* It counts how many times each function is called\n",
+    "  \n",
+    "* It measures total time spent in each function, including and excluding child function calls\n",
+    "This helps quickly find functions that take up a large share of the runtime.\n",
+    "\n",
+    "#### In this episode, we will:\n",
+    "\n",
+    "* Use the function-level profiler `cProfile`\n",
+    "\n",
+    "* Visualise the output with `snakeviz`\n",
+    "\n",
+    "* Learn how to interpret the results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "0085d249-088e-47b9-8021-eb0e19a8b285",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ![title](stack.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cb57ed26-da76-4077-a7db-122885bef904",
+   "metadata": {},
+   "source": [
+    "# What is a Call Stack?\n",
+    "* A Last-in-first-out queue\n",
+    "* It keeps track of function calls and their associated variables\n",
+    "* Info is kept as long as the functions are active, i.e., still running\n",
+    "\n",
+    "Example of a function call stack using traceback package"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7a05824c",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "import traceback\n",
+    "\n",
+    "def a():\n",
+    "    b1()\n",
+    "    b2()\n",
+    "    \n",
+    "def b1():\n",
+    "    pass\n",
+    "    \n",
+    "def b2():\n",
+    "    c()\n",
+    "    \n",
+    "def c():\n",
+    "    traceback.print_stack()\n",
+    "\n",
+    "a()\n",
+    "\n",
+    "#  File \"/var/folders/s0/2zsybdkd50s2xdxzyg37j4611m1b1l/T/ipykernel_16681/3225044458.py\", line 16, in <module>\n",
+    "#    a()\n",
+    "#  File \"/var/folders/s0/2zsybdkd50s2xdxzyg37j4611m1b1l/T/ipykernel_16681/3225044458.py\", line 5, in a\n",
+    "#    b2()\n",
+    "#  File \"/var/folders/s0/2zsybdkd50s2xdxzyg37j4611m1b1l/T/ipykernel_16681/3225044458.py\", line 11, in b2\n",
+    "#    c()\n",
+    "#  File \"/var/folders/s0/2zsybdkd50s2xdxzyg37j4611m1b1l/T/ipykernel_16681/3225044458.py\", line 14, in c\n",
+    "#    traceback.print_stack()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "de2c4b5c-7eb5-41ee-8391-484428444e82",
+   "metadata": {},
+   "source": [
+    "The stack trace shows the filename and line number of each function call.\n",
+    "\n",
+    "You may see stack traces like this when an unhandled exception is thrown by your code.\n",
+    "Stack traces are very helpful to identify the source line of the error"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "90218270-5ded-42c2-b5aa-c3c01fb6b199",
+   "metadata": {},
+   "source": [
+    "# `cProfile`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4e71fc96-2f99-4d74-b0b1-1bd222635468",
+   "metadata": {},
+   "source": [
+    "`cProfile` is part of python standard library, i.e., no need to install it.\n",
+    "* you can import it from within your python code\n",
+    "* or run it in command line as follows:\n",
+    "  ``` bash\n",
+    "  python -m cProfile -o <output file.prof> <script name> <arguments>\n",
+    "  ```\n",
+    "\n",
+    "Profiling outputs will be writtin to a file with `.prof` extension if you specify `-o  my_out.prof` argument\n",
+    "Otherwise, it will be written directly to your console output"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "41fb909e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# save it to func_prof.py\n",
+    "import time\n",
+    "\n",
+    "def a_1():\n",
+    "    for i in range(3):\n",
+    "        b_1()\n",
+    "    time.sleep(1)\n",
+    "    b_2()\n",
+    "    \n",
+    "def b_1():\n",
+    "    c_1()\n",
+    "    c_2()\n",
+    "\n",
+    "def b_2():\n",
+    "    time.sleep(1)\n",
+    "    \n",
+    "def c_1():\n",
+    "    time.sleep(0.5)\n",
+    "\n",
+    "def c_2():\n",
+    "    time.sleep(0.3)\n",
+    "    d_1()\n",
+    "\n",
+    "def d_1():\n",
+    "    time.sleep(0.1)\n",
+    "\n",
+    "# Entry Point\n",
+    "a_1()\n",
+    "\n",
+    "# a_1() calls 3 times b_1(), then sleeps for (1s), then calls b_2 (sleeping for 1s) => 2s\n",
+    "# b_1() calls c_1() --> c_1() is called 3 times (sleeping in total 1.5s) => 1.5s\n",
+    "# b_1() calls c_2() --> c_2() is called 3 times (sleeping in total 0.9s) then sleeping 0.1*3=0.3 => total=1.2s\n",
+    "# .sleep() is called: 11 times (1 in a_1(), 3 times in c_1(), 3 times in c_2() and 3 times in d_1() and Once in b_2())\n",
+    "# Total time spend: 4.7s"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "32d841e6-9cf2-47d7-a87e-7f511aaa5d5f",
+   "metadata": {},
+   "source": [
+    "# Run `cProfile` module in command line. \n",
+    "We won't specify the output file for the moment\n",
+    "```bash\n",
+    "python -m cProfile func_prof.py\n",
+    "```\n",
+    "\n",
+    "\n",
+    "```output\n",
+    "         28 function calls in 4.736 seconds\n",
+    "\n",
+    "   Ordered by: cumulative time\n",
+    "\n",
+    "   ncalls  tottime  percall  cumtime  percall filename:lineno(function)\n",
+    "        1    0.000    0.000    4.736    4.736 {built-in method builtins.exec}\n",
+    "        1    0.000    0.000    4.736    4.736 func_prof2.py:1(<module>)\n",
+    "        1    0.000    0.000    4.736    4.736 func_prof2.py:3(a_1)\n",
+    "       11    4.736    0.431    4.736    0.431 {built-in method time.sleep}\n",
+    "        3    0.000    0.000    2.732    0.911 func_prof2.py:9(b_1)\n",
+    "        3    0.000    0.000    1.509    0.503 func_prof2.py:16(c_1)\n",
+    "        3    0.000    0.000    1.223    0.408 func_prof2.py:19(c_2)\n",
+    "        1    0.000    0.000    1.004    1.004 func_prof2.py:13(b_2)\n",
+    "        3    0.000    0.000    0.311    0.104 func_prof2.py:23(d_1)\n",
+    "        1    0.000    0.000    0.000    0.000 {method 'disable' of '_lsprof.Profiler' objects}\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "71451df7-54b8-4326-89a0-c0ed0e3d79b5",
+   "metadata": {},
+   "source": [
+    "* `ncalls`: number of times (in seconds) a function was called\n",
+    "* `tottime`: total time spent in that function, excluding child function\n",
+    "* `percall`: average time spent in that function each time, i.e., `tottime/ncalls`\n",
+    "* `cumtime`: total time spent in that function, including child function calls\n",
+    "* `percall`: The average `cumtime` per function call (`cumtime/ncalls`).\n",
+    "* `filename:lineno(function)`: function name and location "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "36f0419e-5a11-4b87-b04d-543c69d1553a",
+   "metadata": {},
+   "source": [
+    "# Let's visualise the profiling results using `snakeviz`\n",
+    "We should run cProfile and specify an output file:\n",
+    "```bash\n",
+    "python -m cProfile -o out.prof func_prof.py\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5078679c-b872-413a-9993-bbfb19859025",
+   "metadata": {},
+   "source": [
+    "# Install snakeviz if not already done in the setup\n",
+    "\n",
+    "```bash\n",
+    "pip install snakeviz\n",
+    "```\n",
+    "\n",
+    "* verify it is installed by running `snakeviz --version`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c91ab8bc-44d6-4c25-9ac8-85b627b1770f",
+   "metadata": {},
+   "source": [
+    "# Run snakeviz in your command line:\n",
+    "```bash\n",
+    "python -m snakeviz out.prof\n",
+    "```\n",
+    "In consequence this will open out.prof in your browser"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1a080086-3779-4e2b-89ce-0b004eb57036",
+   "metadata": {},
+   "source": [
+    "# Run snakeviz in jupyter notebook:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "a8913674-3ad0-4e74-bf70-1af19474d2e3",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Requirement already satisfied: snakeviz in /opt/anaconda3/envs/py311_env/lib/python3.11/site-packages (2.2.2)\n",
+      "Requirement already satisfied: tornado>=2.0 in /opt/anaconda3/envs/py311_env/lib/python3.11/site-packages (from snakeviz) (6.5.2)\n"
+     ]
+    }
+   ],
+   "source": [
+    "!pip install snakeviz\n",
+    "%load_ext snakeviz"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "d05f4ff6-a553-422c-85d7-18f7683eb27c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# run snakeviz in jupyter notebook\n",
+    "# %snakeviz a_1()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4c6b0af7-68cd-4623-874e-34302a62c6fe",
+   "metadata": {},
+   "source": [
+    "# EXERCISE 1: TRAVELLING SALESPERSON\n",
+    "Download the python code and save it in an accessible folder\n",
+    "```bash\n",
+    "python -m cProfile travellingsales.py <integer, nb of cities>\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ef49bad7-0951-4902-81fe-71026c5567ae",
+   "metadata": {},
+   "source": [
+    "TODO: \n",
+    "analyse the code and provide a summary, explaining the key points of the code.\n",
+    "Running the profiling multiple times with different number of cities to showcase the importance of inputs in catching the bottlenecks, and also showing the tradeoff between choosing the fastest setup to catch the bottlenecks"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "683d61f6-3267-438e-8e80-a81ca62ad2ca",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Script expects 1 positive integer argument, 2 found.\n"
+     ]
+    },
+    {
+     "ename": "SystemExit",
+     "evalue": "",
+     "output_type": "error",
+     "traceback": [
+      "An exception has occurred, use %tb to see the full traceback.\n",
+      "\u001b[31mSystemExit\u001b[39m\n"
+     ]
+    }
+   ],
+   "source": [
+    "# save it as travellingsales.py\n",
+    "\"\"\"\n",
+    "Naive brute force travelling salesperson\n",
+    "python travellingsales.py <cities>\n",
+    "\"\"\"\n",
+    "\n",
+    "import itertools\n",
+    "import math\n",
+    "import random\n",
+    "import sys\n",
+    "\n",
+    "# calculates euclidean distance between two points\n",
+    "def distance(point1, point2):\n",
+    "    return math.sqrt((point2[0] - point1[0])**2 + (point2[1] - point1[1])**2)\n",
+    "\n",
+    "# calculates total distance among a set of points in a specific order\n",
+    "def total_distance(points, order):\n",
+    "    total = 0\n",
+    "    for i in range(len(order) - 1):\n",
+    "        total += distance(points[order[i]], points[order[i + 1]])\n",
+    "    return total + distance(points[order[-1]], points[order[0]])\n",
+    "\n",
+    "# calculates the shortest path to link as set of points\n",
+    "def traveling_salesman_brute_force(points):\n",
+    "    min_distance = float('inf')\n",
+    "    min_path = None\n",
+    "    # create permutations: factorial n!\n",
+    "    for order in itertools.permutations(range(len(points))):\n",
+    "        d = total_distance(points, order)\n",
+    "        if d < min_distance:\n",
+    "            min_distance = d\n",
+    "            min_path = order\n",
+    "    return min_path, min_distance\n",
+    "\n",
+    "# Argument parsing\n",
+    "if len(sys.argv) != 2:\n",
+    "    print(\"Script expects 1 positive integer argument, %u found.\"%(len(sys.argv) - 1))\n",
+    "    sys.exit()\n",
+    "cities_len = int(sys.argv[1])\n",
+    "if cities_len < 1:\n",
+    "    print(\"Script expects 1 positive integer argument, %s converts < 1.\"%(sys.argv[1]))\n",
+    "    sys.exit()\n",
+    "# Define the cities as (x, y) coordinates\n",
+    "random.seed(12) # Fixed random for consistency\n",
+    "cities = [(0,0)]\n",
+    "for i in range(cities_len):\n",
+    "    cities.append((random.uniform(-1, 1), random.uniform(-1, 1)))\n",
+    "\n",
+    "# Find the shortest path\n",
+    "shortest_path, min_distance = traveling_salesman_brute_force(cities)\n",
+    "print(\"Cities:\", cities_len)\n",
+    "print(\"Shortest Path:\", shortest_path)\n",
+    "print(\"Shortest Distance:\", min_distance)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "2bbd6c3c-c427-46a6-b1ef-1ae01c400ae5",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "3628800"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# to calculate the shortest distance between a set of points,\n",
+    "# first, we need to find the number of possible paths: factorial of the number of points (n!)\n",
+    "# Second, calculate the total path for each possible path\n",
+    "# Finally, find the minimum path and return the path and the minimal distance\n",
+    "\n",
+    "# for, 5 points, there are 5*4*3*2*1 = math.factorial(5) = 120 possibilities\n",
+    "# for 10 points, there are 10*9*8*..*5*4*3*2*1 = math.factorial(10) = 3 628 800 possibilities!!!\n",
+    "import math\n",
+    "math.factorial(10)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "86efcc38-eec6-4b7b-b551-ec2c18e4ad97",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 39 916 800   77.465    0.000  201.843    0.000 travellingsales.py:14(total_distance)\n",
+    "# 439 084 800  109.961    0.000  123.194    0.000 travellingsales.py:11(distance)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "28974e50-8f5d-44cb-b7da-0f72ff82f577",
+   "metadata": {},
+   "source": [
+    "### run the cProfile tool on this file\n",
+    "```bash\n",
+    "python -m cprofile -p out2.prof travellingsales.py 1\n",
+    "python -m cprofile -p out2.prof travellingsales.py 5\n",
+    "python -m cprofile -p out2.prof travellingsales.py 10\n",
+    "\n",
+    "# visualise\n",
+    "python -m snakeviz out2.prof \n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ef2ed065-f80c-48ae-b098-dc839cf6dcd2",
+   "metadata": {},
+   "source": [
+    "The hotspot only becomes visible when an argument of 5 or greater is passed.\n",
+    "\n",
+    "You should see that distance() (from `travellingsales.py:11`) becomes the largest box (similarly it’s parent in the call-stack `total_distance()`) showing that it scales poorly with the number of cities. \n",
+    "With 5 cities, `distance()` has a cumulative time of `~35%` the runtime, this increases to `~60% with 9 cities`.\n",
+    "\n",
+    "Other boxes within the diagram correspond to the initialisation of imports, or initialisation of cities. These have constant or linear scaling, so their cost barely increases with the number of cities.\n",
+    "\n",
+    "This highlights the need to profile a realistic test-case expensive enough that initialisation costs are not the most expensive component."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e6e47489-a90a-4220-b6dd-7b14797d31c8",
+   "metadata": {},
+   "source": [
+    "# 15min BREAK NOW"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/episodes/notebooks/3-ex-profiling-lines.ipynb b/episodes/notebooks/3-ex-profiling-lines.ipynb
new file mode 100644
index 00000000..310745f2
--- /dev/null
+++ b/episodes/notebooks/3-ex-profiling-lines.ipynb
@@ -0,0 +1,335 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "e92b22a0-86d9-45ca-a0ae-dd224f9146b1",
+   "metadata": {},
+   "source": [
+    "# Exercice1:\n",
+    "\n",
+    "* Download the python code file (`fizzbuzz.py`)\n",
+    "We want to demonstrate how line_profiler works on a example.\n",
+    "\n",
+    "We start with the below code, defined in the global context.\n",
+    "\n",
+    "The below code loops through the numbers 1 to 100.\n",
+    "For each number:\n",
+    "\n",
+    "* Prints “FizzBuzz” if it’s divisible by both 3 and 5.\n",
+    "* Prints “Fizz” if it’s divisible by 3 only.\n",
+    "* Prints “Buzz” if it’s divisible by 5 only.\n",
+    "* Otherwise, prints the number itself."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "99ac3e7e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#fizzbuzz.py\n",
+    "n = 100\n",
+    "for i in range(1, n + 1):\n",
+    "    if i % 3 == 0 and i % 5 == 0:\n",
+    "        print(\"FizzBuzz\")\n",
+    "    elif i % 3 == 0:\n",
+    "        print(\"Fizz\")\n",
+    "    elif i % 5 == 0:\n",
+    "        print(\"Buzz\")\n",
+    "    else:\n",
+    "        print(i)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f6688cf8-b6b1-4003-8f4d-b058fdb6b220",
+   "metadata": {},
+   "source": [
+    "## To line-profile it, we will have to wrap it up in a function, e.g., `fizzbuzz`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "26247123",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def fizzbuzz(n):\n",
+    "    for i in range(1, n + 1):\n",
+    "        if i % 3 == 0 and i % 5 == 0:\n",
+    "            print(\"FizzBuzz\")\n",
+    "        elif i % 3 == 0:\n",
+    "            print(\"Fizz\")\n",
+    "        elif i % 5 == 0:\n",
+    "            print(\"Buzz\")\n",
+    "        else:\n",
+    "            print(i)\n",
+    "\n",
+    "fizzbuzz(100)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "41e97bcf-2d0e-4892-bf9a-e5fc163f7535",
+   "metadata": {},
+   "source": [
+    "### Let's decorate the function using @profile"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5bc18776",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "# load the required package as follows\n",
+    "!pip install line_profiler\n",
+    "%load_ext line_profiler\n",
+    "\n",
+    "from line_profiler import profile\n",
+    "\n",
+    "@profile\n",
+    "def fizzbuzz(n):\n",
+    "    for i in range(1, n + 1):\n",
+    "        if i % 3 == 0 and i % 5 == 0:\n",
+    "            print(\"FizzBuzz\")\n",
+    "        elif i % 3 == 0:\n",
+    "            print(\"Fizz\")\n",
+    "        elif i % 5 == 0:\n",
+    "            print(\"Buzz\")\n",
+    "        else:\n",
+    "            print(i)\n",
+    "\n",
+    "fizzbuzz(100)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5f26b3f2-867c-412f-9efd-ad5d3d40cfb4",
+   "metadata": {},
+   "source": [
+    "### Trigger the line profiling```bash\n",
+    "python -m kernprof -lvr fizzbuzz.py\n",
+    "```\n",
+    "or in jupyter notebook"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "eb9ca2f3-57de-4087-a670-eca48d42dae4",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "%lprun -f fizzbuzz fizzbuzz(100)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "35c2fe04-d5b8-4718-b797-6f30fd7db8b9",
+   "metadata": {},
+   "source": [
+    "* In 100 iterations, “FizzBuzz” is printed 6 times.\n",
+    "\n",
+    "* Profiling shows it takes 4.5% of runtime, slightly less than the expected 6% because of extra control flow overhead.\n",
+    "\n",
+    "* “Fizz” is printed 27 times, accounting for 22.3% of runtime.\n",
+    "\n",
+    "* “Buzz” is printed 14 times, accounting for 12.% of runtime.\n",
+    "\n",
+    "* Each print statement has a similar per-hit time of about 39–50 microseconds."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a7de249d-0978-4fe1-a776-52773056b9de",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c0502b35-12b0-4486-b298-ade492a0f329",
+   "metadata": {},
+   "source": [
+    "# Exercice 2 - Bubble sort:\n",
+    "* Download `bubblesort.py` from: https://icr-rse-group.github.io/carpentry-pando-python/files/bubblesort/bubblesort.py"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "82952109-82ba-48b5-a877-646d455ebfa0",
+   "metadata": {},
+   "source": [
+    "Here’s what it does step by step:\n",
+    "\n",
+    "* Loops through the array multiple times.\n",
+    "* In each pass, compares adjacent elements arr[j] and arr[j+1].\n",
+    "* If they’re out of order (arr[j] > arr[j+1]), it swaps them.\n",
+    "* Uses a flag swapped to track if any swap happened in the pass.\n",
+    "* If no swaps occur, the array is already sorted, so the loop stops early (this is an optimisation)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "5836b7a6",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Script expects 1 positive integer argument, 2 found.\n"
+     ]
+    },
+    {
+     "ename": "SystemExit",
+     "evalue": "",
+     "output_type": "error",
+     "traceback": [
+      "An exception has occurred, use %tb to see the full traceback.\n",
+      "\u001b[31mSystemExit\u001b[39m\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/opt/anaconda3/envs/py311_env/lib/python3.11/site-packages/IPython/core/interactiveshell.py:3707: UserWarning: To exit: use 'exit', 'quit', or Ctrl-D.\n",
+      "  warn(\"To exit: use 'exit', 'quit', or Ctrl-D.\", stacklevel=1)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Doing the necessary changes to profile the code\n",
+    "# bubblesort.py\n",
+    "import sys\n",
+    "import random\n",
+    "from line_profiler import profile        # Import profile decorator\n",
+    "\n",
+    "@profile                                 # Decorate the function to be profiled\n",
+    "def main():                              # Create a simple function with the code to be profiled\n",
+    "    # Argument parsing\n",
+    "    if len(sys.argv) != 2:\n",
+    "        print(\"Script expects 1 positive integer argument, %u found.\"%(len(sys.argv) - 1))\n",
+    "        sys.exit()\n",
+    "    n = int(sys.argv[1])\n",
+    "    # Init\n",
+    "    random.seed(12)\n",
+    "    arr = [random.random() for i in range(n)]\n",
+    "    print(\"Sorting %d elements\"%(n))\n",
+    "    # Sort\n",
+    "    for i in range(n - 1): \n",
+    "        swapped = False\n",
+    "        for j in range(0, n - i - 1):\n",
+    "            if arr[j] > arr[j + 1]:\n",
+    "                arr[j], arr[j + 1] = arr[j + 1], arr[j]\n",
+    "                swapped = True\n",
+    "        # If no two elements were swapped in the inner loop, the array is sorted\n",
+    "        if not swapped:\n",
+    "            break\n",
+    "    # Validate\n",
+    "    is_sorted = True\n",
+    "    for i in range(n - 1):\n",
+    "        if arr[i] > arr[i+1]:\n",
+    "            is_sorted = False\n",
+    "    print(\"Sorting: %s\"%(\"Passed\" if is_sorted else \"Failed\"))\n",
+    "    \n",
+    "main()                                  # Call the created function"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c851d5dd-9b99-4e48-a807-7bd3eada20aa",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# below is the actual content of the file\n",
+    "import sys\n",
+    "import random\n",
+    "\n",
+    "# Argument parsing\n",
+    "if len(sys.argv) != 2:\n",
+    "    print(\"Script expects 1 positive integer argument, %u found.\"%(len(sys.argv) - 1))\n",
+    "    sys.exit()\n",
+    "n = int(sys.argv[1])\n",
+    "# Init\n",
+    "random.seed(12)\n",
+    "arr = [random.random() for i in range(n)]\n",
+    "print(\"Sorting %d elements\"%(n))\n",
+    "# Sort\n",
+    "for i in range(n - 1): \n",
+    "    swapped = False\n",
+    "    for j in range(0, n - i - 1):\n",
+    "        if arr[j] > arr[j + 1]:\n",
+    "            arr[j], arr[j + 1] = arr[j + 1], arr[j]\n",
+    "            swapped = True\n",
+    "    # If no two elements were swapped in the inner loop, the array is sorted\n",
+    "    if not swapped:\n",
+    "        break\n",
+    "# Validate\n",
+    "is_sorted = True\n",
+    "for i in range(n - 1):\n",
+    "    if arr[i] > arr[i+1]:\n",
+    "        is_sorted = False\n",
+    "print(\"Sorting: %s\"%(\"Passed\" if is_sorted else \"Failed\"))\n",
+    "    "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "71ccb128-5d12-4b49-93c4-cf89c55d2bdc",
+   "metadata": {},
+   "source": [
+    "## To profile the code in command line, where <elements> is an integer>0\n",
+    "First, make sure to add the `@profile` decorator.\n",
+    "\n",
+    "```bash\n",
+    "python -m kernprof -lvr bubblesort.py 100\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8c5b5460-244d-4a77-8346-8b10920bacd8",
+   "metadata": {},
+   "source": [
+    "# Observations:\n",
+    "* From the profiling output we can identify that the `print` statements were the most expensive individual calls (“Per Hit”), \n",
+    "however both were only called once. \n",
+    "* Most execution time was spent at the inner loop (lines 19-22)!!, This part can benefit from some optimisation.\n",
+    "\n",
+    "#### In the following sections we are going to see with Stacy how we can optimise the code now that we know which line is the most expensive one."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/episodes/notebooks/3-profiling-lines.ipynb b/episodes/notebooks/3-profiling-lines.ipynb
new file mode 100644
index 00000000..4aa0fb05
--- /dev/null
+++ b/episodes/notebooks/3-profiling-lines.ipynb
@@ -0,0 +1,284 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "58792c3d-6c7d-44c9-8ada-1d70d74d8e89",
+   "metadata": {},
+   "source": [
+    "# Line-level profiling\n",
+    "\n",
+    "* When is `line level profiling` appropriate?\n",
+    "* What adjustments are required to Python code to profile with line_profiler?\n",
+    "* How can `kernprof` be used to profile a Python program?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "47340303-1ab0-4233-86fc-fbb35a546e52",
+   "metadata": {},
+   "source": [
+    "Sometimes, `function-level profiling` shows that a method is expensive but doesn’t explain why because the method is complex.\n",
+    "\n",
+    "* `Line-level profiling` provides more detail by measuring performance at the level of individual lines of code.\n",
+    "* It records how many times each line is executed and how much time is spent on it.\n",
+    "* Because this level of detail can be costly to collect, it is applied only to specific methods you choose.\n",
+    "* This approach makes it easier to spot individual lines that consume a disproportionate amount of runtime.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8115efc6-cc83-4f42-a469-a5a3938934e6",
+   "metadata": {},
+   "source": [
+    "Make sure to install the package if not already done\n",
+    "\n",
+    "```bash\n",
+    "pip install line_profiler[all]\n",
+    "```\n",
+    "\n",
+    "# For use in jupyter notebooks: \n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "b0931cb3-16a8-44df-826f-f47df9080781",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Requirement already satisfied: line_profiler in /opt/anaconda3/envs/py311_env/lib/python3.11/site-packages (5.0.0)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# load the required package as follows\n",
+    "!pip install line_profiler\n",
+    "%load_ext line_profiler"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "abc7d375",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "True\n"
+     ]
+    }
+   ],
+   "source": [
+    "# save as my_script.py\n",
+    "def is_prime(number):\n",
+    "    if number < 2:\n",
+    "        return False\n",
+    "    for i in range(2, int(number**0.5) + 1):\n",
+    "        if number % i == 0:\n",
+    "            return False\n",
+    "    return True\n",
+    "    \n",
+    "print(is_prime(1087))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9a520915-92fc-4174-981f-ee24455176ed",
+   "metadata": {},
+   "source": [
+    "## update the code to use the decorator\n",
+    "* We will use `line_profiler` for that purpose, and we will `decorate` the function we want to analyse thoroughly.\n",
+    "\n",
+    "This tells `line_profiler` to collect metrics for the lines within the method is_prime(). \n",
+    "You can still execute your code as normal, and these changes will have no effect."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "a613aa11",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "True\n"
+     ]
+    }
+   ],
+   "source": [
+    "# save as my_script.py\n",
+    "from line_profiler import profile\n",
+    "\n",
+    "@profile\n",
+    "def is_prime(number):\n",
+    "    if number < 2:\n",
+    "        return False\n",
+    "    for i in range(2, int(number**0.5) + 1):\n",
+    "        if number % i == 0:\n",
+    "            return False\n",
+    "    return True\n",
+    "    \n",
+    "print(is_prime(1087))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a5bf3c70-40d4-46a5-bc03-be77fd07dd52",
+   "metadata": {},
+   "source": [
+    "## Run the lineprofiler from the command line (Recommended way):\n",
+    "Save your python code into a `.py` file, e.g., `my_script.py`\n",
+    "\n",
+    "`line_profiler` can then be triggered via kernprof module. \n",
+    "\n",
+    "`kernprof` is a convenient script for running either `line_profiler` or the Python standard library's `cProfile` or profile modules, depending on what was imported in the code.\n",
+    "\n",
+    "```bash\n",
+    "python -m kernprof -lvr my_script.py\n",
+    "```\n",
+    "\n",
+    "`kernprof` -lvr options :\n",
+    "\n",
+    "* `-l` → turn on line profiling\n",
+    "* `-v/--view` → show results in the console\n",
+    "* `-r/--run` → run the script\n",
+    "\n",
+    "Note that `line_profiler` generates a binary file (unreadable) with `.py.lprof` extension.\n",
+    "\n",
+    "##### To read it:\n",
+    "```bash\n",
+    "python -m line_profiler -rm my_script.py.lprof\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0e71b0b4-1673-435e-823d-2ef083d5765b",
+   "metadata": {},
+   "source": [
+    "## Analysing the outputs:\n",
+    "* `Line #`: the line number in your code\n",
+    "* `Hits`: the number of time a line was executed, empty if line is not executed\n",
+    "* `Time`: time spent in each line (micro-seconds)\n",
+    "* `Per Hit`: time spent per hit (micro-seconds)\n",
+    "* `% time`: percentage of time spent in each line\n",
+    "* `Line Contents`: the line of code that is being analyses\n",
+    "\n",
+    "Note that one table is generated per decorated function.\n",
+    "\n",
+    "**Important:**\n",
+    "If your code is big block, it is recommended to refactor your code and isolate some line of codes in a separate function that you can profile.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "63042c6a-da72-4cd6-98cf-076f2efb8253",
+   "metadata": {},
+   "source": [
+    "## Alternatively, Run the lineprofiler in jupyter notebook:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "87905d05-a1b8-4f28-a428-0c3a572245bd",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Requirement already satisfied: line_profiler in /opt/anaconda3/envs/py311_env/lib/python3.11/site-packages (5.0.0)\n",
+      "The line_profiler extension is already loaded. To reload it, use:\n",
+      "  %reload_ext line_profiler\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "Timer unit: 1e-09 s\n",
+       "\n",
+       "Total time: 5e-06 s\n",
+       "File: /var/folders/s0/2zsybdkd50s2xdxzyg37j4611m1b1l/T/ipykernel_19560/1357507920.py\n",
+       "Function: is_prime at line 4\n",
+       "\n",
+       "Line #      Hits         Time  Per Hit   % Time  Line Contents\n",
+       "==============================================================\n",
+       "     4                                           @profile\n",
+       "     5                                           def is_prime(number):\n",
+       "     6         1       1000.0   1000.0     20.0      if number < 2:\n",
+       "     7                                                   return False\n",
+       "     8         2       3000.0   1500.0     60.0      for i in range(2, int(number**0.5) + 1):\n",
+       "     9         1       1000.0   1000.0     20.0          if number % i == 0:\n",
+       "    10                                                       return False\n",
+       "    11         1          0.0      0.0      0.0      return True"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "# load the required package as follows\n",
+    "!pip install line_profiler\n",
+    "%load_ext line_profiler\n",
+    "%lprun -f is_prime is_prime(5)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "51a88114-b7d1-4975-9505-d905b470142c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# trying to optimise, but not sure it is\n",
+    "def is_prime_opt(number: int) -> bool:\n",
+    "    if number < 2:\n",
+    "        return False\n",
+    "    if number in (2, 3):\n",
+    "        return True\n",
+    "    if number % 2 == 0 or number % 3 == 0:\n",
+    "        return False\n",
+    "\n",
+    "    # check only numbers of the form 6k ± 1\n",
+    "    limit = int(number**0.5) + 1\n",
+    "    for i in range(5, limit, 6):\n",
+    "        if number % i == 0 or number % (i + 2) == 0:\n",
+    "            return False\n",
+    "    return True\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/episodes/notebooks/optimisation-numpy.ipynb b/episodes/notebooks/optimisation-numpy.ipynb
index 9d6a8edd..ea8e136b 100644
--- a/episodes/notebooks/optimisation-numpy.ipynb
+++ b/episodes/notebooks/optimisation-numpy.ipynb
@@ -1,12 +1,64 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7b1cbecd-8d60-4579-9a50-53b143c39c54",
+   "metadata": {},
+   "source": [
+    "# Using pandas and numpy effectively\n",
+    "Both pandas and numpy have been written in Compiled languages, mostly C: \n",
+    "### NumPy\n",
+    "\n",
+    "* The core array operations (like vectorised math, broadcasting, slicing, etc.) are implemented in C (and some Fortran, especially for linear algebra via BLAS/LAPACK).\n",
+    "\n",
+    "* The Python layer is mostly a wrapper that calls into these fast C routines.\n",
+    "\n",
+    "That’s why NumPy is so much faster than plain Python loops.\n",
+    "\n",
+    "### pandas\n",
+    "\n",
+    "* Built on top of NumPy, so it inherits a lot of that C speed indirectly.\n",
+    "\n",
+    "* Performance-critical parts (like groupby, joins, parsing CSVs) are written in C or Cython (a Python-like language that compiles to C).\n",
+    "\n",
+    "* The higher-level DataFrame/Series API is written in Python."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d05cb503-a144-4fb5-bdbc-81dd26938110",
+   "metadata": {},
+   "source": [
+    "# Using Numpy (effectively) :\n",
+    "1. ### Numpy arrays are static:\n",
+    "* They are fixed in size (unlike Python lists).\n",
+    "\n",
+    "* They don’t automatically resize when you add elements.\n",
+    "\n",
+    "* To append, you must call `resize()` explicitly.\n",
+    "\n",
+    "* Resizing on every append causes `many extra copies and memory allocations`.\n",
+    "\n",
+    "* This makes repeated appends much slower than using Python lists."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "ff046953",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "list_append: 1.20ms\n",
+      "array_resize: 13.18ms\n"
+     ]
+    }
+   ],
    "source": [
+    "# showcasing the drawback of resizing a numpy array\n",
     "from timeit import timeit\n",
     "import numpy\n",
     "\n",
@@ -28,12 +80,269 @@
     "print(f\"array_resize: {timeit(array_resize, number=repeats):.2f}ms\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "e76fba2a-bf85-473f-a1a3-1390398b514e",
+   "metadata": {},
+   "source": [
+    "numpy resizing is 10 times slower than list resizing\n",
+    "\n",
+    "**Conclusion 1: Avoid resizing Numpy arrays**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2bd9e449-6ab6-4902-aa31-fadb518104e7",
+   "metadata": {},
+   "source": [
+    "2. ### NumPy arrays require all elements to have the **same type** (a NumPy `dtype`)\n",
+    "\n",
+    "If you don’t respect this, you lose the performance advantages of NumPy.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "### NumPy Array Architecture\n",
+    "A NumPy array is essentially:\n",
+    "- **A single contiguous block of memory** in RAM, holding raw data,\n",
+    "- Plus a small piece of **metadata** describing how to interpret it.\n",
+    "\n",
+    "That metadata includes:\n",
+    "- **Shape** → number of dimensions and size along each axis  \n",
+    "- **Dtype** → size and type of each element (e.g., `float64` = 8 bytes)  \n",
+    "- **Strides** → how many bytes to move in memory to reach the next element along each axis  \n",
+    "\n",
+    "Because the metadata is **shared across the entire array**, all elements must be of the **same type and size**.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "### Python Lists (contrast)\n",
+    "A Python list is very different:\n",
+    "- It stores **pointers** (addresses) to objects  \n",
+    "- Each object carries its **own metadata** (type, size, etc.)  \n",
+    "- Elements can be **mixed types** (integers, strings, objects…)  \n",
+    "- Accessing elements requires following a pointer → much slower and less memory-efficient  \n",
+    "\n",
+    "---\n",
+    "\n",
+    "✅ **Summary**\n",
+    "- **NumPy array** → compact, contiguous memory, uniform type → fast mathematical operations  \n",
+    "- **Python list** → array of pointers to objects, heterogeneous, flexible but slow  \n"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": null,
-   "id": "614a7d9d",
+   "execution_count": 2,
+   "id": "438b3607-2cf9-49f2-8d15-e61f8afe818d",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "<class 'numpy.float64'>\n",
+      "<class 'numpy.float64'>\n",
+      "<class 'float'> <class 'int'> <class 'dict'>\n"
+     ]
+    }
+   ],
+   "source": [
+    "import numpy as np\n",
+    "a = np.array([0.5, 5])\n",
+    "print(type(a[0]))\n",
+    "print(type(a[1]))\n",
+    "\n",
+    "b = np.array([0.5, 5,{\"foo\":5}])\n",
+    "print(type(b[0]),type(b[1]),type(b[2]))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "710e3aa8-592c-4642-85cd-4aaf33ba10e0",
+   "metadata": {},
+   "source": [
+    "- We will demonstrate now the overhead from mixing Python lists and NumPy functions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "46d6a85b-f1f6-4773-be75-f8029e5746e8",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "List: Time for 1000 runs: 0.24398979201214388 seconds\n",
+      "Numpy: Time for 1000 runs: 0.004132583009777591 seconds\n"
+     ]
+    }
+   ],
+   "source": [
+    "import timeit\n",
+    "import numpy as np\n",
+    "\n",
+    "#python list\n",
+    "ls = list(range(10000))\n",
+    "time = timeit.timeit(lambda: np.random.choice(ls), number=1000)\n",
+    "print(\"List: Time for 1000 runs:\", time, \"seconds\")\n",
+    "\n",
+    "# NumPy array\n",
+    "ar = numpy.arange(10000)\n",
+    "time = timeit.timeit(lambda: np.random.choice(ar), number=1000)\n",
+    "print(\"Numpy: Time for 1000 runs:\", time, \"seconds\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "aaa9464b-acff-493b-ab91-d3ff9166ed3b",
+   "metadata": {},
+   "source": [
+    "**Conclusion2: Passing a Python list to numpy.random.choice() is 65.6x slower than passing a NumPy array.\n",
+    "This is the additional overhead of converting the list to an array.**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "334a0be1-384a-4944-ab4e-779cfc6f08f1",
+   "metadata": {},
+   "source": [
+    "## Numpy and array broadcasting\n",
+    "* NumPy arrays support `broadcasting` many mathematical operations or functions. \n",
+    "\n",
+    "* `broadcasting`: This is a shorthand notation, where the operation/function is applied `element-wise` without having to loop over the array explicitly\n",
+    "\n",
+    "* No need to loop over array, thus optimising the code!\n",
+    "\n",
+    "* This means also that multiple `operations could be applied simultaneously`, rather than sequentially --> significant performance boost"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "d14628c7-c226-4c32-902f-b54cc1dd8b9c",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[0 1 2 3 4 5]\n",
+      "[10 11 12 13 14 15]\n",
+      "[ 0  2  4  6  8 10]\n",
+      "[ 0  1  4  9 16 25]\n",
+      "[  1.           2.71828183   7.3890561   20.08553692  54.59815003\n",
+      " 148.4131591 ]\n",
+      "[ 1  3  5  7  9 11]\n"
+     ]
+    }
+   ],
+   "source": [
+    "import numpy as np\n",
+    "ar = np.arange(6)\n",
+    "print(ar)\n",
+    "print(ar + 10)\n",
+    "print(ar * 2)\n",
+    "print(ar**2)\n",
+    "print(np.exp(ar))\n",
+    "print(ar*2+1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "d8a23beb-4514-499d-8670-b13e0e278b73",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[0, 1, 2, 3, 4, 5, 0, 1, 2, 3, 4, 5]\n"
+     ]
+    },
+    {
+     "ename": "TypeError",
+     "evalue": "can only concatenate list (not \"int\") to list",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[31m---------------------------------------------------------------------------\u001b[39m",
+      "\u001b[31mTypeError\u001b[39m                                 Traceback (most recent call last)",
+      "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[11]\u001b[39m\u001b[32m, line 4\u001b[39m\n\u001b[32m      2\u001b[39m lt = [\u001b[32m0\u001b[39m, \u001b[32m1\u001b[39m, \u001b[32m2\u001b[39m, \u001b[32m3\u001b[39m, \u001b[32m4\u001b[39m, \u001b[32m5\u001b[39m]\n\u001b[32m      3\u001b[39m \u001b[38;5;28mprint\u001b[39m(lt*\u001b[32m2\u001b[39m)\n\u001b[32m----> \u001b[39m\u001b[32m4\u001b[39m \u001b[38;5;28mprint\u001b[39m(\u001b[43mlt\u001b[49m\u001b[43m+\u001b[49m\u001b[32;43m2\u001b[39;49m)\n",
+      "\u001b[31mTypeError\u001b[39m: can only concatenate list (not \"int\") to list"
+     ]
+    }
+   ],
+   "source": [
+    "# lists do not allow broadcasting\n",
+    "lt = [0, 1, 2, 3, 4, 5]\n",
+    "print(lt*2)\n",
+    "print(lt+2)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "id": "e3add66b-f330-4049-9f39-f904bed8b532",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Array size 1: 0.418775 seconds total\n",
+      "Array size 10: 0.381499 seconds total\n",
+      "Array size 100: 0.396316 seconds total\n",
+      "List size 1: 0.090674 seconds total\n",
+      "List size 10: 0.193455 seconds total\n",
+      "List size 100: 1.267181 seconds total\n"
+     ]
+    }
+   ],
+   "source": [
+    "# speed of applying broadcasting is independent from the size of the numpy arrays (comparing to using lists)\n",
+    "import timeit\n",
+    "import numpy as np\n",
+    "\n",
+    "for n in [1, 10, 100]:\n",
+    "    ar = np.arange(n)\n",
+    "    time = timeit.timeit(lambda: ar + 10, number=1_000_000)\n",
+    "    print(f\"Array size {n}: {time:.6f} seconds total\")\n",
+    "\n",
+    "\n",
+    "for n in [1, 10, 100]:\n",
+    "    ls = list(range(n))\n",
+    "    time = timeit.timeit(lambda: [x + 10 for x in ls], number=1_000_000)\n",
+    "    print(f\"List size {n}: {time:.6f} seconds total\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "27b194a9-f740-4add-8579-f73350e3f1be",
    "metadata": {},
    "outputs": [],
+   "source": [
+    "# A final summary code"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "614a7d9d",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "python_sum_list: 23.17ms\n",
+      "python_sum_array: 29.61ms\n",
+      "numpy_sum_array: 0.61ms\n",
+      "numpy_dot_array: 0.29ms\n"
+     ]
+    }
+   ],
    "source": [
     "from timeit import timeit\n",
     "\n",
@@ -42,31 +351,71 @@
     "gen_list = f\"ls = list(range({N}))\"\n",
     "gen_array = f\"import numpy; ar = numpy.arange({N}, dtype=numpy.int64)\"\n",
     "\n",
-    "py_sum_ls = \"sum([i*i for i in ls])\"\n",
-    "py_sum_ar = \"sum(ar*ar)\"\n",
-    "np_sum_ar = \"numpy.sum(ar*ar)\"\n",
-    "np_dot_ar = \"numpy.dot(ar, ar)\"\n",
+    "py_sum_ls = \"sum([i*i for i in ls])\" #list comprehension on a list\n",
+    "py_sum_ar = \"sum(ar*ar)\" # sum of a broadcasting multiplication\n",
+    "np_sum_ar = \"numpy.sum(ar*ar)\" #numpy.sum on a broadcasting multiplication\n",
+    "np_dot_ar = \"numpy.dot(ar, ar)\" # numpy.dot (sum of multiple) on numpy arrays\n",
     "\n",
     "repeats = 1000\n",
     "print(f\"python_sum_list: {timeit(py_sum_ls, setup=gen_list, number=repeats):.2f}ms\")\n",
     "print(f\"python_sum_array: {timeit(py_sum_ar, setup=gen_array, number=repeats):.2f}ms\")\n",
+    "\n",
     "print(f\"numpy_sum_array: {timeit(np_sum_ar, setup=gen_array, number=repeats):.2f}ms\")\n",
-    "print(f\"numpy_dot_array: {timeit(np_dot_ar, setup=gen_array, number=repeats):.2f}ms\")"
+    "print(f\"numpy_dot_array: {timeit(np_dot_ar, setup=gen_array, number=repeats):.2f}ms\")# fastest"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "54f46509-d38e-41ec-862d-ec0cdac291c9",
+   "metadata": {},
+   "source": [
+    "# Pandas :\n",
+    "* Pandas is the most common Python package when working with tabular data (`csv`, `tsv` files).\n",
+    "* Pandas enhances performance if used well, otherwise it can harm performance\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "aae97eea-c5e3-4bdd-b235-a52c27717487",
+   "metadata": {},
+   "source": [
+    "### Pandas methods by default operate on `columns`\n",
+    "* This means that elements of a same column are saved in the same memory space.\n",
+    "* Think of the column as a numpy array, highly suitable for vectorisation.\n",
+    "\n",
+    "* Iterating over DataFrame rows using a Python for loop is slow and not recommended!\n",
+    "\n",
+    "* Prefer Pandas built-in methods that support axis=1 for row-wise operations.\n",
+    "\n",
+    "* If no built-in method exists, use `apply()` to apply a custom function to rows (similar to `map()`)."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 6,
    "id": "f6e557eb",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "for_range: 765.96ms\n",
+      "for_iterrows: 888.91ms\n",
+      "pandas_apply: 235.23ms\n"
+     ]
+    }
+   ],
    "source": [
+    "# comparing iff\n",
     "from timeit import timeit\n",
     "import pandas\n",
     "import numpy\n",
     "\n",
     "N = 100000  # Number of rows in DataFrame\n",
     "\n",
+    "# generate a dataframe\n",
     "def genDataFrame():\n",
     "    numpy.random.seed(12)  # Ensure each dataframe is identical\n",
     "    return pandas.DataFrame(\n",
@@ -76,9 +425,13 @@
     "        # todo some spurious columns\n",
     "    })\n",
     "\n",
+    "# apply pythagoras on a row\n",
     "def pythagoras(row):\n",
     "    return (row[\"f_vertical\"]**2 + row[\"f_horizontal\"]**2)**0.5\n",
-    "    \n",
+    "\n",
+    "# different ways to apply an operation on a row\n",
+    "\n",
+    "# using range\n",
     "def for_range():\n",
     "    rtn = []\n",
     "    df = genDataFrame()\n",
@@ -87,44 +440,87 @@
     "        rtn.append(pythagoras(row))\n",
     "    return pandas.Series(rtn)\n",
     "\n",
+    "#using iterrows\n",
     "def for_iterrows():\n",
     "    rtn = []\n",
     "    df = genDataFrame()\n",
     "    for row_idx, row in df.iterrows():\n",
     "        rtn.append(pythagoras(row))\n",
     "    return pandas.Series(rtn)\n",
-    "    \n",
+    "\n",
+    "#using apply\n",
     "def pandas_apply():\n",
     "    df = genDataFrame()\n",
-    "    return df.apply(pythagoras, axis=1)\n",
+    "    return df.apply(pythagoras, axis=1)# axis=1 means apply to rows\n",
     "\n",
     "repeats = 100\n",
     "gentime = timeit(genDataFrame, number=repeats)\n",
+    "\n",
+    "#Subtract gentime from each and multiply by 10 (for scaling to milliseconds) to get the time spent only on row iteration.\n",
     "print(f\"for_range: {timeit(for_range, number=repeats)*10-gentime:.2f}ms\")\n",
     "print(f\"for_iterrows: {timeit(for_iterrows, number=repeats)*10-gentime:.2f}ms\")\n",
     "print(f\"pandas_apply: {timeit(pandas_apply, number=repeats)*10-gentime:.2f}ms\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "2a97b075-04a3-40a2-a121-d13ff0f53009",
+   "metadata": {},
+   "source": [
+    "**`apply()` is 4x faster than the two for approaches, as it avoids the Python for loop.**\n",
+    "\n",
+    "But, we can do better by profiting from `vectorisation` and `broadcasting` and applying the mathematical operations on columns instead!\n"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 7,
    "id": "003d088d",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "vectorize: -0.01ms\n"
+     ]
+    }
+   ],
    "source": [
+    "# calculating pythagoras directly on the columns using numpy operations\n",
+    "import numpy as np\n",
     "def vectorize():\n",
     "    df = genDataFrame()\n",
-    "    return pandas.Series(numpy.sqrt(numpy.square(df[\"f_vertical\"]) + numpy.square(df[\"f_horizontal\"])))\n",
+    "    return pandas.Series(np.sqrt(np.square(df[\"f_vertical\"]) + np.square(df[\"f_horizontal\"])))\n",
     "    \n",
     "print(f\"vectorize: {timeit(vectorize, number=repeats)-gentime:.2f}ms\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "0440d8ec-2ddd-4740-8ece-906e41b9b0c7",
+   "metadata": {},
+   "source": [
+    "**Ok, we were lucky here and we could profit from vectorisarion but it's not always the case!**\n",
+    "* An alternative approach is `converting your DataFrame` to a `Python dictionary` using `to_dict(orient='index')`.\n",
+    "* This creates a nested dictionary, where each row of the outer dictionary is an internal dictionary.\n",
+    "* This can then be processed via list-comprehension \n"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 20,
    "id": "fd73ffc8",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "to_dict: 80.74ms\n"
+     ]
+    }
+   ],
    "source": [
     "def to_dict():\n",
     "    df = genDataFrame()\n",
@@ -136,11 +532,63 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 9,
+   "id": "4e8d40ff-5e6c-4d1e-b343-4428808d256d",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "   f_vertical  f_horizontal\n",
+      "0           1            10\n",
+      "1           2            20\n",
+      "2          23             3\n",
+      "3           3            30\n",
+      "4           5            50\n",
+      "{0: {'f_vertical': 1, 'f_horizontal': 10}, 1: {'f_vertical': 2, 'f_horizontal': 20}, 2: {'f_vertical': 23, 'f_horizontal': 3}, 3: {'f_vertical': 3, 'f_horizontal': 30}, 4: {'f_vertical': 5, 'f_horizontal': 50}}\n"
+     ]
+    }
+   ],
+   "source": [
+    "# these are details to show the result of the to_dict() operation\n",
+    "df = pandas.DataFrame({\n",
+    "        \"f_vertical\": [1,2,23,3,5],\n",
+    "        \"f_horizontal\": [10,20,3,30,50],\n",
+    "        # todo some spurious columns\n",
+    "    })\n",
+    "df_as_dict = df.to_dict(orient='index')\n",
+    "print(df)\n",
+    "print(df_as_dict)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ac4d0022-8e41-4310-8af1-07d677dd3b65",
+   "metadata": {},
+   "source": [
+    "**Using dictionary (80ms) is slower than using vectorisation but is twice as fast as using `apply`.**\n",
+    "\n",
+    "Note that indexing into (or iterating over) `Pandas Series` (rows) is significantly slower than a `Python dictionary` as we will demonstrate below:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
    "id": "a26495a2",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "series: 128.98ms\n",
+      "dictionary: 2.12ms\n"
+     ]
+    }
+   ],
    "source": [
+    "# to drop\n",
     "from timeit import timeit\n",
     "import pandas as pandas\n",
     "\n",
@@ -165,9 +613,35 @@
     "print(f\"series: {timeit(series, number=repeats):.2f}ms\")\n",
     "print(f\"dictionary: {timeit(dictionary, number=repeats):.2f}ms\")"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6c394d9a-bf11-4295-804a-bc5f82976a86",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
- "metadata": {},
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.8"
+  }
+ },
  "nbformat": 4,
  "nbformat_minor": 5
 }
diff --git a/episodes/notebooks/profiling-functions.ipynb b/episodes/notebooks/profiling-functions.ipynb
deleted file mode 100644
index 66c3fcf5..00000000
--- a/episodes/notebooks/profiling-functions.ipynb
+++ /dev/null
@@ -1,65 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "7a05824c",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import traceback\n",
-    "\n",
-    "def a():\n",
-    "    b1()\n",
-    "    b2()\n",
-    "def b1():\n",
-    "    pass\n",
-    "def b2():\n",
-    "    c()\n",
-    "def c():\n",
-    "    traceback.print_stack()\n",
-    "\n",
-    "a()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "41fb909e",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import time\n",
-    "\n",
-    "def a_1():\n",
-    "    for i in range(3):\n",
-    "        b_1()\n",
-    "    time.sleep(1)\n",
-    "    b_2()\n",
-    "    \n",
-    "def b_1():\n",
-    "    c_1()\n",
-    "    c_2()\n",
-    "\n",
-    "def b_2():\n",
-    "    time.sleep(1)\n",
-    "    \n",
-    "def c_1():\n",
-    "    time.sleep(0.5)\n",
-    "\n",
-    "def c_2():\n",
-    "    time.sleep(0.3)\n",
-    "    d_1()\n",
-    "\n",
-    "def d_1():\n",
-    "    time.sleep(0.1)\n",
-    "\n",
-    "# Entry Point\n",
-    "a_1()"
-   ]
-  }
- ],
- "metadata": {},
- "nbformat": 4,
- "nbformat_minor": 5
-}
diff --git a/episodes/notebooks/profiling-lines.ipynb b/episodes/notebooks/profiling-lines.ipynb
deleted file mode 100644
index 237bf44a..00000000
--- a/episodes/notebooks/profiling-lines.ipynb
+++ /dev/null
@@ -1,187 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "abc7d375",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "def is_prime(number):\n",
-    "    if number < 2:\n",
-    "        return False\n",
-    "    for i in range(2, int(number**0.5) + 1):\n",
-    "        if number % i == 0:\n",
-    "            return False\n",
-    "    return True\n",
-    "    \n",
-    "print(is_prime(1087))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "a613aa11",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from line_profiler import profile\n",
-    "\n",
-    "@profile\n",
-    "def is_prime(number):\n",
-    "    if number < 2:\n",
-    "        return False\n",
-    "    for i in range(2, int(number**0.5) + 1):\n",
-    "        if number % i == 0:\n",
-    "            return False\n",
-    "    return True\n",
-    "    \n",
-    "print(is_prime(1087))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "99ac3e7e",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "n = 100\n",
-    "for i in range(1, n + 1):\n",
-    "    if i % 3 == 0 and i % 5 == 0:\n",
-    "        print(\"FizzBuzz\")\n",
-    "    elif i % 3 == 0:\n",
-    "        print(\"Fizz\")\n",
-    "    elif i % 5 == 0:\n",
-    "        print(\"Buzz\")\n",
-    "    else:\n",
-    "        print(i)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "26247123",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "def fizzbuzz(n):\n",
-    "    for i in range(1, n + 1):\n",
-    "        if i % 3 == 0 and i % 5 == 0:\n",
-    "            print(\"FizzBuzz\")\n",
-    "        elif i % 3 == 0:\n",
-    "            print(\"Fizz\")\n",
-    "        elif i % 5 == 0:\n",
-    "            print(\"Buzz\")\n",
-    "        else:\n",
-    "            print(i)\n",
-    "\n",
-    "fizzbuzz(100)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5bc18776",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from line_profiler import profile\n",
-    "\n",
-    "@profile\n",
-    "def fizzbuzz(n):\n",
-    "    for i in range(1, n + 1):\n",
-    "        if i % 3 == 0 and i % 5 == 0:\n",
-    "            print(\"FizzBuzz\")\n",
-    "        elif i % 3 == 0:\n",
-    "            print(\"Fizz\")\n",
-    "        elif i % 5 == 0:\n",
-    "            print(\"Buzz\")\n",
-    "        else:\n",
-    "            print(i)\n",
-    "\n",
-    "fizzbuzz(100)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5836b7a6",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import sys\n",
-    "import random\n",
-    "from line_profiler import profile        # Import profile decorator\n",
-    "\n",
-    "@profile                                 # Decorate the function to be profiled\n",
-    "def main():                              # Create a simple function with the code to be profiled\n",
-    "    # Argument parsing\n",
-    "    if len(sys.argv) != 2:\n",
-    "        print(\"Script expects 1 positive integer argument, %u found.\"%(len(sys.argv) - 1))\n",
-    "        sys.exit()\n",
-    "    n = int(sys.argv[1])\n",
-    "    # Init\n",
-    "    random.seed(12)\n",
-    "    arr = [random.random() for i in range(n)]\n",
-    "    print(\"Sorting %d elements\"%(n))\n",
-    "    # Sort\n",
-    "    for i in range(n - 1):\n",
-    "        swapped = False\n",
-    "        for j in range(0, n - i - 1):\n",
-    "            if arr[j] > arr[j + 1]:\n",
-    "                arr[j], arr[j + 1] = arr[j + 1], arr[j]\n",
-    "                swapped = True\n",
-    "        # If no two elements were swapped in the inner loop, the array is sorted\n",
-    "        if not swapped:\n",
-    "            break\n",
-    "    # Validate\n",
-    "    is_sorted = True\n",
-    "    for i in range(n - 1):\n",
-    "        if arr[i] > arr[i+1]:\n",
-    "            is_sorted = False\n",
-    "    print(\"Sorting: %s\"%(\"Passed\" if is_sorted else \"Failed\"))\n",
-    "    \n",
-    "main()                                  # Call the created function"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "82c3a8a6",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# line ~1\n",
-    "from line_profiler import profile"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "49a000b0",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# line ~278\n",
-    "    @profile\n",
-    "    def eaten(self, prey_list):"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "930d029a",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "for i in range(len(prey_list)):\n",
-    "                prey = prey_list[i]\n",
-    "                if prey.life < PREY_HUNGER_THRESH:"
-   ]
-  }
- ],
- "metadata": {},
- "nbformat": 4,
- "nbformat_minor": 5
-}