Merge pull request #677 from pybamm-team/issue-674-options-notebook

#674 options notebook

examples/notebooks/README.md

@@ -21,6 +21,7 @@ The easiest way to start with PyBaMM is by running and comparing some of the inb
 It is also easy to add new models or change the setting that are used:
 - [Add a model (documentation)](https://pybamm.readthedocs.io/en/latest/tutorials/add-model.html)
 - [Add a model (example)](./create-model.ipynb)
+- [Change model options](./using-model-options_thermal-example.ipynb)
 - [Using submodels](./using-submodels.ipynb)
 - [Change the settings](./change-settings.ipynb) (parameters, spatial method or solver)
 - [Change the applied current](./change-input-current.ipynb)

examples/notebooks/using-model-options_thermal-example.ipynb

@@ -0,0 +1,212 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Using model options in PyBaMM\n",
+    "In this notebook we show how to pass options to models. This allows users to do things such as include extra physics (e.g. thermal effects) or change the macroscopic dimension of the problem (e.g. change from a 1D model to a 2+1D pouch cell model). To see all of the options currently available in PyBaMM, please take a look at the documentation [here](https://pybamm.readthedocs.io/en/latest/source/models/base_models/base_battery_model.html). For more information on combining submodels explicitly to create your own custom model, please see the [Using Submodels notebook](./using-submodels.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example: Solving the SPMe with a lumped thermal model\n",
+    "PyBaMM is designed to be a flexible modelling package that allows users to easily include different physics within a model without having to start from scratch. In this example, we show how to pass model options to include thermal effects in the SPMe (for more information on the SPMe see [here](./models/SPMe.ipynb)). First we import PyBaMM and any other packages we need"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pybamm\n",
+    "import os\n",
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "os.chdir(pybamm.__path__[0]+'/..')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We then choose out model options, which a set as a dictionary. We choose to model the behaviour in the particle using Fickian diffusion (this is the default behaviour, but we pass the option explicitly here just to demonstrate the functionality of options). We also choose a lumped thermal model (note that this is fully-coupled, i.e. parameters can depend on temperature)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "options = {\"particle\": \"Fickian diffusion\", \"thermal\": \"lumped\"}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We then pass our options to the model "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model = pybamm.lithium_ion.SPMe(options)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We choose to use the parameters from [1]. We then update the heat transfer coefficient to be 0.1 [W/m^2/K] (see the [Parameter Values notebook](./parameter-values.ipynb) for more details)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "param = pybamm.ParameterValues(chemistry=pybamm.parameter_sets.Marquis2019)\n",
+    "param.update({\"Heat transfer coefficient [W.m-2.K-1]\": 0.1})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We then use the default geometry, mesh and discretisation (see the [SPM notebook](./models/SPM.ipynb) for more details)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# create geometry\n",
+    "geometry = model.default_geometry\n",
+    "\n",
+    "# process model and geometry\n",
+    "param.process_model(model)\n",
+    "param.process_geometry(geometry)\n",
+    "\n",
+    "# set mesh\n",
+    "mesh = pybamm.Mesh(geometry, model.default_submesh_types, model.default_var_pts)\n",
+    "\n",
+    "# discretise model\n",
+    "disc = pybamm.Discretisation(mesh, model.default_spatial_methods)\n",
+    "disc.process_model(model);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We then solve using the default ODE solver for the SPMe"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# solve model\n",
+    "solver = model.default_solver\n",
+    "t_eval = np.linspace(0, 1, 250)\n",
+    "solution = solver.solve(model, t_eval)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally we plot the terminal voltage and the cell temperature using PyBaMM's `QuickPlot` functionality. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "321d32d08b3f417caa1062450f00732c",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.05), Output()), _dom_classes=('w…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "# plot\n",
+    "output_variables = [\n",
+    "    \"Terminal voltage [V]\",\n",
+    "    \"X-averaged cell temperature [K]\",\n",
+    "    \"Cell temperature [K]\",\n",
+    "]\n",
+    "quick_plot = pybamm.QuickPlot(model, mesh, solution, output_variables)\n",
+    "\n",
+    "import ipywidgets as widgets\n",
+    "widgets.interact(quick_plot.plot, t=widgets.FloatSlider(min=0,max=1,step=0.05,value=0));"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that the variable \"X-averaged cell temperature [K]\" is the scalar-valued lumped temperature, whereas the variable \"Cell temperature [K]\" is the value of the lumped temperature broadcasted across the whole cell domain. This type of behaviour is purposefully designed to allow easy comparison of different models and settings. For instance we may wish to compare a simulation that uses a lumped thermal model with a simulation that uses a full thermal model (i.e. one that solves the heat equation in the x-direction). When comparing these two model we could then plot the same variable \"Cell temperature [K]\" to compare the temperature throughout the cell. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## References\n",
+    "[1] SG Marquis, V Sulzer, R Timms, CP Please and SJ Chapman. “An asymptotic derivation of a single particle model with electrolyte”. In: arXiv preprint arXiv:1905.12553 (2019)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.6.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

examples/scripts/SPM_compare_particle_grid.py

@@ -25,7 +25,6 @@
 
 # load parameter values and process models and geometry
 param = models[0].default_parameter_values
-param["Typical current [A]"] = 1.0
 for model in models:
     param.process_model(model)
 

examples/scripts/compare_SPM_diffusion_models.py

@@ -23,7 +23,7 @@
 
 # load parameter values and process models and geometry
 param = models[0].default_parameter_values
-param["Typical current [A]"] = 1.0
+param.update({"Typical current [A]": 1})
 for model in models:
     param.process_model(model)
 

results/2plus1D/compare_lead_acid_1plus1D.py

@@ -13,8 +13,7 @@
     pybamm.lead_acid.Composite(name="1D composite"),
     pybamm.lead_acid.LOQS(name="1D LOQS"),
     pybamm.lead_acid.Full(
-        {"current collector": "potential pair", "dimensionality": 1},
-        name="1+1D Full",
+        {"current collector": "potential pair", "dimensionality": 1}, name="1+1D Full"
     ),
     pybamm.lead_acid.Composite(
         {"current collector": "potential pair", "dimensionality": 1},

results/2plus1D/compare_lithium_ion_2plus1D.py

@@ -28,8 +28,12 @@
 C_rate = 1
 param.update({"C-rate": C_rate})
 # make current collectors not so conductive, just for illustrative purposes
-param["Negative current collector conductivity [S.m-1]"] = 5.96e6
-param["Positive current collector conductivity [S.m-1]"] = 3.55e6
+param.update(
+    {
+        "Negative current collector conductivity [S.m-1]": 5.96e6,
+        "Positive current collector conductivity [S.m-1]": 3.55e6,
+    }
+)
 
 # process models
 for model in models:

results/2plus1D/spm_2plus1D_tab_grid.py

@@ -19,11 +19,6 @@
 
 # load parameter values and process model and geometry
 param = model.default_parameter_values
-# adjust current to correspond to a typical current density of 24 [A.m-2]
-C_rate = 1
-param["Typical current [A]"] = (
-    C_rate * 24 * param.evaluate(pybamm.geometric_parameters.A_cc)
-)
 param.process_model(model)
 param.process_geometry(geometry)
 

results/2plus1D/spmecc.py

@@ -14,8 +14,12 @@
 param = cell_model.default_parameter_values
 
 # make current collectors not so conductive, just for illustrative purposes
-param["Negative current collector conductivity [S.m-1]"] = 5.96e5
-param["Positive current collector conductivity [S.m-1]"] = 3.55e5
+param.update(
+    {
+        "Negative current collector conductivity [S.m-1]": 5.96e6,
+        "Positive current collector conductivity [S.m-1]": 3.55e6,
+    }
+)
 
 # process model and geometry, and discretise
 for model in models: