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

{
 "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": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "%pip install pybamm -q    # install PyBaMM if it is not installed\n",
    "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 by assuming the concentration profile is quadratic within the particle. We also choose a lumped thermal model (note that this is fully-coupled, i.e. parameters can depend on temperature). For an in-depth look at the thermal models see the [thermal models notebook](models/thermal-models.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "options = {\"particle\": \"quadratic profile\", \"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 [[3]](#References). We then update the heat transfer coefficient and increase the current to approximately 3C (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(\n",
    "    {\n",
    "        \"Total heat transfer coefficient [W.m-2.K-1]\": 1.0,\n",
    "        \"Current function [A]\": 3*0.68\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We then create and solve a simulation, making sure we pass in our updated parameter values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<pybamm.solvers.solution.Solution at 0x7f6169de4690>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "simulation = pybamm.Simulation(model, parameter_values=param)\n",
    "simulation.solve([0, 3600])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally we plot the terminal voltage and the cell temperature "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "449fc9b518774804bf0d4367bb914744",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1163.6363636363637, step=11.636363636363637)…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "simulation.plot([\n",
    "    \"Terminal voltage [V]\",\n",
    "    \"X-averaged cell temperature [K]\",\n",
    "    \"Cell temperature [K]\",\n",
    "])"
   ]
  },
  {
   "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",
    "\n",
    "The relevant papers for this notebook are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1] Joel A. E. Andersson, Joris Gillis, Greg Horn, James B. Rawlings, and Moritz Diehl. CasADi – A software framework for nonlinear optimization and optimal control. Mathematical Programming Computation, 11(1):1–36, 2019. doi:10.1007/s12532-018-0139-4.\n",
      "[2] Charles R. Harris, K. Jarrod Millman, Stéfan J. van der Walt, Ralf Gommers, Pauli Virtanen, David Cournapeau, Eric Wieser, Julian Taylor, Sebastian Berg, Nathaniel J. Smith, and others. Array programming with NumPy. Nature, 585(7825):357–362, 2020. doi:10.1038/s41586-020-2649-2.\n",
      "[3] Scott G. Marquis, Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society, 166(15):A3693–A3706, 2019. doi:10.1149/2.0341915jes.\n",
      "[4] Venkat R. Subramanian, Vinten D. Diwakar, and Deepak Tapriyal. Efficient macro-micro scale coupled modeling of batteries. Journal of The Electrochemical Society, 152(10):A2002, 2005. doi:10.1149/1.2032427.\n",
      "[5] Valentin Sulzer, Scott G. Marquis, Robert Timms, Martin Robinson, and S. Jon Chapman. Python Battery Mathematical Modelling (PyBaMM). ECSarXiv. February, 2020. doi:10.1149/osf.io/67ckj.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "pybamm.print_citations()"
   ]
  }
 ],
 "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.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}