exploring_dimensionality.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Model dimensionality\n",
    "PyBaMM currently supports three types of model dimensions for the current collectors: 0D, 1D and 2D. These can be configured using the \"dimensionality\" model option.\n",
    "\n",
    "\n",
    "If this notebook is running on Google Colab, we first need to install PyBaMM (you can skip if not using Google Colab)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[33mWARNING: You are using pip version 21.3.1; however, version 22.1.2 is available.\n",
      "You should consider upgrading via the '/home/ferranbrosa/continuum-model-review/env/bin/python -m pip install --upgrade pip' command.\u001b[0m\n",
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "%pip install pybamm -q"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start importing the relevant packages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "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 now define the model of interest, in this case we set a 0D model for the current collectors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_0D = pybamm.lithium_ion.SPMe({\"dimensionality\": 0})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we import the parameters, and we modify the values of all heat transfer coefficients"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "param = pybamm.ParameterValues(chemistry=pybamm.parameter_sets.Marquis2019)\n",
    "for p in param.keys():\n",
    "    if 'heat transfer coefficient' in p:\n",
    "        param.update({p:1.0})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can check that the parameter values were indeed updated"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Edge heat transfer coefficient [W.m-2.K-1]\t1.0\n",
      "Negative current collector surface heat transfer coefficient [W.m-2.K-1]\t1.0\n",
      "Negative tab heat transfer coefficient [W.m-2.K-1]\t1.0\n",
      "Positive current collector surface heat transfer coefficient [W.m-2.K-1]\t1.0\n",
      "Positive tab heat transfer coefficient [W.m-2.K-1]\t1.0\n",
      "Total heat transfer coefficient [W.m-2.K-1]\t1.0\n"
     ]
    }
   ],
   "source": [
    "param.search('heat transfer coefficient')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally we can solve and plot the simulation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<pybamm.solvers.solution.Solution at 0x7ff5d6138310>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sim_0D = pybamm.Simulation(model_0D, parameter_values=param)\n",
    "sim_0D.solve([0, 3600])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "1908d3d618714be3936673e50289badb",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.plotting.quick_plot.QuickPlot at 0x7ff5d59c2dd0>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sim_0D.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default dimensionality for the current collectors is 0 but has been specified above for demonstration purposes. With this option the Ohmic losses in the current collectors are assumed to be negligible meaning that the entire current collector is held at the same potential. This may be a good approximation for smaller pouch cells or even larger ones at low C-rates. However, for cells with larger aspect ratios the Ohmic losses in the current collectors become more important and regions of the cell may discharge or charge at different rates depending on their proximity to a tab. \n",
    "\n",
    "We can repeat the simulation but now with a 1D model for the current collectors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "a64b5a3160c348708e8ef20e54bec617",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.plotting.quick_plot.QuickPlot at 0x7ff5d2b9f5d0>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model_1D = pybamm.lithium_ion.SPMe({\"dimensionality\": 1,\n",
    "                                    \"current collector\": \"potential pair\"})\n",
    "sim_1D = pybamm.Simulation(model_1D, parameter_values=param)\n",
    "sim_1D.solve([0, 3600])\n",
    "sim_1D.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can observe the effects of dimensionality on a thermal model. In this case, we choose a lumped thermal model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<pybamm.solvers.solution.Solution at 0x7ff5d0080b10>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model_1D_lumped = pybamm.lithium_ion.SPMe({\"dimensionality\": 1,\n",
    "                                           \"current collector\": \"potential pair\",\n",
    "                                           \"thermal\": \"lumped\"})\n",
    "sim_1D_lumped = pybamm.Simulation(model_1D_lumped, parameter_values=param)\n",
    "sim_1D_lumped.solve([0, 3600])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "fe12f6c7d0744dc6a88456e6c4f2feac",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.plotting.quick_plot.QuickPlot at 0x7ff5caf71990>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "temp = sim_1D_lumped.solution[\"Cell temperature [K]\"].entries\n",
    "t_min = temp.min()\n",
    "t_max = temp.max()\n",
    "variable_limits = {\"X-averaged cell temperature [K]\": (t_min, t_max),\n",
    "                   \"Cell temperature [K]\": (t_min, t_max),\n",
    "                   \"Volume-averaged cell temperature [K]\": (t_min, t_max)}\n",
    "\n",
    "sim_1D_lumped.plot([\n",
    "    #\"Terminal voltage [V]\",\n",
    "                    \"X-averaged cell temperature [K]\",\n",
    "                    \"Cell temperature [K]\",\n",
    "                    \"Volume-averaged cell temperature [K]\"], variable_limits=variable_limits)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And we can proceed similarly but with an `x-lumped` thermal model instead (more details can be found in the [PyBaMM documentation](https://pybamm.readthedocs.io/en/latest/source/models/submodels/thermal/index.html))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<pybamm.solvers.solution.Solution at 0x7ff5c487f650>"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model_1D_x_lumped = pybamm.lithium_ion.SPMe({\"dimensionality\": 1,\n",
    "                                             \"current collector\": \"potential pair\",\n",
    "                                             \"thermal\": \"x-lumped\"})\n",
    "sim_1D_x_lumped = pybamm.Simulation(model_1D_x_lumped, parameter_values=param)\n",
    "sim_1D_x_lumped.solve([0, 3600])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "d2303624dfb440c990e0b526be369b06",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.plotting.quick_plot.QuickPlot at 0x7ff5c47cebd0>"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "temp = sim_1D_x_lumped.solution[\"Cell temperature [K]\"].entries\n",
    "t_min = temp.min()\n",
    "t_max = temp.max()\n",
    "variable_limits = {\"X-averaged cell temperature [K]\": (t_min, t_max),\n",
    "                   \"Cell temperature [K]\": (t_min, t_max),\n",
    "                   \"Volume-averaged cell temperature [K]\": (t_min, t_max)}\n",
    "sim_1D_x_lumped.plot([\"X-averaged cell temperature [K]\",\n",
    "                      \"Cell temperature [K]\",\n",
    "                      \"Volume-averaged cell temperature [K]\"],\n",
    "                     #variable_limits=variable_limits,\n",
    "                     variable_limits='tight',\n",
    "                    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally we can solve the model with a 2D current collector model, which captures the effects of the current collectors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The history saving thread hit an unexpected error (OperationalError('disk I/O error')).History will not be written to the database.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.solvers.solution.Solution at 0x7ff5c17bedd0>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model_2D = pybamm.lithium_ion.SPMe({\"dimensionality\": 2,\n",
    "                                    \"current collector\": \"potential pair\"})\n",
    "sim_2D = pybamm.Simulation(model_2D, parameter_values=param)\n",
    "sim_2D.solve([0, 3600])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "ee792b74150142748c71e8af5ba76aa6",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.plotting.quick_plot.QuickPlot at 0x7ff5c17975d0>"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sim_2D.plot([\"Negative current collector potential [V]\",\n",
    "             \"Positive current collector potential [V]\",\n",
    "             \"Current collector current density [A.m-2]\",\n",
    "             \"Local voltage [V]\"], variable_limits=\"tight\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The articles that contributed to this notebook are"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "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] Tom Gustafsson and Geordie D. McBain. scikit-fem: A Python package for finite element assembly. Journal of Open Source Software, 5(52):2369, 2020. doi:10.21105/joss.02369.\n",
      "[3] 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",
      "[4] 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",
      "[5] Valentin Sulzer, Scott G. Marquis, Robert Timms, Martin Robinson, and S. Jon Chapman. Python Battery Mathematical Modelling (PyBaMM). Journal of Open Research Software, 9(1):14, 2021. doi:10.5334/jors.309.\n",
      "[6] Robert Timms, Scott G Marquis, Valentin Sulzer, Colin P. Please, and S Jonathan Chapman. Asymptotic Reduction of a Lithium-ion Pouch Cell Model. SIAM Journal on Applied Mathematics, 81(3):765–788, 2021. doi:10.1137/20M1336898.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "pybamm.print_citations()"
   ]
  },
  {
   "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.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}