From 3eef641f815615549fb5c0719dd7e033afd18183 Mon Sep 17 00:00:00 2001
From: Brady Planden <brady.planden@gmail.com>
Date: Mon, 9 Sep 2024 11:04:09 +0100
Subject: [PATCH] examples: updates to creating_a_model.ipynb

---
 examples/notebooks/creating_a_model.ipynb | 54 +++++++++--------------
 1 file changed, 20 insertions(+), 34 deletions(-)

diff --git a/examples/notebooks/creating_a_model.ipynb b/examples/notebooks/creating_a_model.ipynb
index 7c781e903..2dfe66af7 100644
--- a/examples/notebooks/creating_a_model.ipynb
+++ b/examples/notebooks/creating_a_model.ipynb
@@ -8,11 +8,9 @@
    "source": [
     "## Creating a Model\n",
     "\n",
-    "In this notebook, we create a single particle model. This is achieved using a predefined data set introduced in Marquis et al. [[1]](https://doi.org/10.1149/1945-7111/abbce4) \n",
+    "In this notebook, we create and solve a single particle model (SPM). This is achieved using a predefined parameter set introduced in Marquis et al. [[1]](https://doi.org/10.1149/1945-7111/abbce4) \n",
     "\n",
-    "### Setting up the Environment\n",
-    "\n",
-    "Before we begin, we need to ensure that we have all the necessary tools. We will install PyBOP and upgrade dependencies:"
+    "Before we begin, we need to ensure that we have all the necessary tools. We will install PyBOP and upgrade dependencies."
    ]
   },
   {
@@ -37,29 +35,11 @@
    ],
    "source": [
     "%pip install --upgrade pip ipywidgets -q\n",
-    "%pip install pybop -q"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "jAvD5fk104p0"
-   },
-   "source": [
-    "### Importing Libraries\n",
+    "%pip install pybop -q\n",
     "\n",
-    "With the environment set up, we can now import PyBOP:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "id": "SQdt4brD04p1"
-   },
-   "outputs": [],
-   "source": [
-    "import pybop"
+    "import pybop\n",
+    "\n",
+    "pybop.PlotlyManager().pio.renderers.default = \"notebook_connected\""
    ]
   },
   {
@@ -68,13 +48,11 @@
     "id": "5XU-dMtU04p2"
    },
    "source": [
-    "## Generating Synthetic Data\n",
-    "\n",
-    "To demonstrate parameter estimation, we first need some data. We will generate synthetic data using a forward model, which requires defining a parameter set and the model itself.\n",
+    "## Creating a Model\n",
     "\n",
-    "### Defining Parameters and Model\n",
+    "PyBOP offers the both forward emperical and physics-based forward models. These are provided by PyBaMM, with PyBOP adding wrappers on the underlying classes to reduce complexity and improve stability with parameter inference and design optimisation. Likewise, PyBOP provides a light wrapper on the PyBaMM parameter sets, with user-defined parameters available through the same `pybop.ParameterSet` class.\n",
     "\n",
-    "We start by creating an example parameter set and then instantiate the single-particle model (SPM):"
+    "Let's construct the parameter set and then the single-particle model (SPM):"
    ]
   },
   {
@@ -84,16 +62,22 @@
    "outputs": [],
    "source": [
     "parameter_set = pybop.ParameterSet.pybamm(\"Marquis2019\")\n",
-    "\n",
     "model = pybop.lithium_ion.SPM(parameter_set=parameter_set)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now that the model is constructed with the Maquis parameter set, we can use the `model.predict` method as a light wrapper on the `PyBaMM.Simulation` class. This is the recommended way to generate synthetic data, but not for parameter inference as the performance cost of constructing the `Simulation` class is high. For parameter inference, `model.simulate` and `model.simulateS1` offer a performant way to solve the forward model with and without sensitivities respectively."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Testing the Model\n",
-    "Having the model, we can now have a look at its voltage discharge curve to verify that it is working. The discharge curve is evaluated on the time interval specified by t_eval. "
+    "Having constructed the model, we can now have a look at its voltage discharge curve to verify that it is working. The discharge curve is evaluated on the time interval specified by `t_eval`. `model.predict` returns the `PyBaMM.solution` object with all of its functionality. As we are only working with the forward model, PyBaMM plotting methods will be used; however, when performing parameter inference or design optimisation, PyBOP plotting methods are recommended."
    ]
   },
   {
@@ -124,7 +108,9 @@
    ],
    "source": [
     "t_eval = [0, 3700]\n",
-    "solution = model.predict([], t_eval)\n",
+    "solution = model.predict([], t_eval)  # No inputs i.e []\n",
+    "\n",
+    "# Plot with PyBaMM\n",
     "solution.plot_voltage_components()"
    ]
   }