examples/notebooks/models/SPMe.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Single Particle Model with Electrolyte (SPMe)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dimensionless Model Equations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "i) The SPMe comprises an equation for the lithium concentration in a representative particle in the negative electrode $c_{\\text{s,n}}$, an equation for the lithium concentration in a representative particle in the positive electrode $c_{\\text{s,p}}$, and an equation which governs the behaviour of the first-order correction to the lithium concentration in the electrolyte $c_{\\text{e,k}}$. Here we use a roman subscript $\\text{k} \\in \\text{n, s, p}$ is used to denote the regions negative electrode, separator, and positive electrode, respectively. \n",
    "\n",
    "ii) At the centre of each particle the standard no-flux condition is imposed, and the flux on the surface of the particle is simply the current $I$ divided by the thickness of the electrode $L_{\\text{k}}$, as in the SPM. Since lithium is transferred between the electrolyte and particles, the flux through the particle surface also enters the electrolyte diffusion equation as a source/sink term. There is no transfer of lithium between the electrolyte and current collectors, which leads to no flux boundary conditions on the lithium concentration in the electrolyte $c_{\\text{e,k}}$ at either end of the cell. \n",
    "\n",
    "iii) We must also impose initial conditions which correspond to setting an initial concentration in each particle $c_{\\text{s,k}}(t=0) = c_{\\text{s,k,0}}$, and to having no deviation from the initial (uniform) lithium concentration in the electrolyte $c_{\\text{e,k}}(t=0) = 0$.  \n",
    "\n",
    "\n",
    "The model equations for the SPMe read: \n",
    "\n",
    "\n",
    "#### Particles: \n",
    "\\begin{align}\n",
    "\\mathcal{C}_{\\text{k}} \\frac{\\partial c_{\\text{s,k}}}{\\partial t} &= -\\frac{1}{r_{\\text{k}}^2} \\frac{\\partial}{\\partial r_{\\text{k}}} \\left(r_{\\text{k}}^2 N_{\\text{s,k}}\\right), \\\\\n",
    "N_{\\text{s,k}} &= -D_{\\text{s,k}}(c_{\\text{s,k}}) \\frac{\\partial c_{\\text{s,k}}}{\\partial r_{\\text{k}}}, \\quad \\text{k} \\in \\text{n, p}, \\end{align}\n",
    "$$\n",
    "N_{\\text{s,k}}\\big|_{r_{\\text{k}}=0} = 0, \\quad \\text{k} \\in \\text{n, p}, \\quad \\ \\ - \\frac{a_{R, \\text{k}}\\gamma_{\\text{k}}}{\\mathcal{C}_{\\text{k}}} N_{\\text{s,k}}\\big|_{r_{\\text{k}}=1} = \n",
    "\\begin{cases}\n",
    "\t\t  \\frac{I}{L_{\\text{n}}}, \\quad &\\text{k}=\\text{n}, \\\\ \n",
    "\t\t  -\\frac{I}{L_{\\text{p}}}, \\quad &\\text{k}=\\text{p}, \n",
    "\\end{cases} \\\\\n",
    "c_{\\text{s,k}}(r_{\\text{k}},0) = c_{\\text{s,k,0}}, \\quad \\text{k} \\in \\text{n, p},$$\n",
    "where $D_{\\text{s,k}}$ is the diffusion coefficient in the solid, $N_{\\text{s,k}}$ denotes the flux of lithium ions in the solid particle within the region $\\text{k}$, and $r_{\\text{k}} \\in[0,1]$ is the radial coordinate of the particle in electrode $\\text{k}$. All other relevant parameters are given in the table at the end of this notebook.\n",
    "\n",
    "\n",
    "#### Electrolyte: \n",
    "\\begin{align}\n",
    "\\mathcal{C}_{\\text{e}} \\epsilon_{\\text{k}} \\gamma_{\\text{e}} \\frac{\\partial c_{\\text{e,k}}}{\\partial t} &= -\\gamma_{\\text{e}} \\frac{\\partial N_{\\text{e,k}}}{\\partial x} + \n",
    "\\begin{cases} \n",
    "    \\frac{I}{L_{\\text{n}}}, \\quad &\\text{k}=\\text{n}, \\\\ \n",
    "    0, \\quad &\\text{k}=\\text{s}, \\\\ \n",
    "    -\\frac{I}{L_{\\text{p}}}, \\quad &\\text{k}=\\text{p},\n",
    "\\end{cases} \\\\\n",
    "N_{\\text{e,k}} &= -\\epsilon_{\\text{k}}^{\\text{b}} D_{\\text{e}}(1) \\frac{\\partial c_{\\text{e,k}}}{\\partial x} +    \n",
    "\\begin{cases} \n",
    "\t  \\frac{x t^+I}{\\gamma_{\\text{e}} L_{\\text{n}}}, \\quad &\\text{k}=\\text{n} \\\\ \n",
    "     \\frac{t^+I}{\\gamma_{\\text{e}}}, \\quad &\\text{k}=\\text{s} \\\\ \n",
    "\t \\frac{(1-x)t^+ I}{\\gamma_{\\text{e}} L_{\\text{p}}}, \\quad &\\text{k}=\\text{p}\n",
    "\\end{cases}\n",
    "\\end{align}\n",
    "$$\n",
    "N_{\\text{e,n}}\\big|_{x=0} = 0, \\quad N_{\\text{e,p}}\\big|_{x=1}=0, \\\\\n",
    "c_{\\text{e,k}}(x,0) = 0, \\quad \\text{k} \\in \\text{n, s, p},$$\n",
    "where $D_{\\text{e}}$ is the diffusion coefficient in the solid, $N_{\\text{e,k}}$ denotes the flux of lithium ions in the electrolyte within the region $\\text{k}$, and $x\\in[0,1]$ is the macroscopic through-cell distance. This equation is also solved subject to continuity of concentration and flux at the electrode/separator interfaces.\n",
    "\n",
    "### Voltage Expression\n",
    "The terminal voltage is obtained from the expression: \n",
    "$$ \n",
    "V = U_{\\text{eq}} + \\eta_r + \\eta_c + \\Delta\\Phi_{\\text{Elec}} + \\Delta\\Phi_{\\text{Solid}}\n",
    "$$ \n",
    "where \n",
    "\\begin{align}\n",
    "U_{\\text{eq}} &= U_{\\text{p}}(c_{\\text{p}})\\big|_{r_{\\text{p}}=1} - U_{\\text{n}}(c_{\\text{n}})\\big|_{r_{\\text{n}}=1}, \\\\ \n",
    "\\eta_{r} &= -2\\sinh^{-1}\\left(\\frac{I}{\\bar{j}_{\\text{0,p}} L_{\\text{p}}}\\right) - 2\\sinh^{-1}\\left(\\frac{I}{\\bar{j}_{\\text{0,n}} L_{\\text{n}}}\\right), \\\\\n",
    "\\eta_c &=  2 \\mathcal{C}_{\\text{e}}(1-t^+)\\left(\\bar{c}_{\\text{e,p}} - \\bar{c}_{\\text{e,n}}\\right), \\\\\n",
    "\\bar{j}_{\\text{0,n}} &=  \\frac{1}{L_{\\text{n}}}\\int_0^{L_{\\text{n}}} \\frac{\\gamma_{\\text{n}}}{\\mathcal{C}_{\\text{r,n}}} (c_{\\text{n}})^{1/2}(1-c_{\\text{n}})^{1/2} (1+\\mathcal{C}_{\\text{e}} c_{\\text{e,n}})^{1/2} \\, \\text{d}x,\\\\\n",
    "\\bar{j}_{\\text{0,p}} &=  \\frac{1}{L_{\\text{p}}}\\int_{1-L_{\\text{p}}}^1 \\frac{\\gamma_{\\text{p}}}{\\mathcal{C}_{\\text{r,p}}} (c_{\\text{p}})^{1/2}(1-c_{\\text{p}})^{1/2} (1+\\mathcal{C}_{\\text{e}} c_{\\text{e,p}})^{1/2} \\, \\text{d}x,\\\\\n",
    "\\Delta \\Phi_{\\text{Elec}} &= -\\frac{\\mathcal{C}_{\\text{e}}I}{\\gamma_{\\text{e}} \\kappa_{\\text{e}}(1)} \\left(\\frac{L_{\\text{n}}}{3\\epsilon_{\\text{n}}^{\\text{b}}} + \\frac{L_{\\text{s}}}{\\epsilon_{\\text{s}}^{\\text{b}}} + \\frac{L_{\\text{p}}}{3\\epsilon_{\\text{p}}^{\\text{b}}} \\right), \\\\\n",
    "\\Delta \\Phi_{\\text{Solid}} &=  -\\frac{I}{3}\\left(\\frac{L_{\\text{p}}}{\\sigma_{\\text{p}}} + \\frac{L_{\\text{n}}}{\\sigma_{\\text{n}}} \\right), \n",
    "\\end{align} \n",
    "where\n",
    "\\begin{equation} \n",
    "    \\bar{c}_{\\text{e,n}} =  \\frac{1}{L_{\\text{n}}}\\int_0^{L_{\\text{n}}} c_{\\text{e,n}} \\, \\text{d}x, \\quad\n",
    "    \\bar{c}_{\\text{e,p}} =  \\frac{1}{L_{\\text{p}}}\\int_{1-L_{\\text{p}}}^{1} c_{\\text{e,p}} \\, \\text{d}x.\n",
    "\\end{equation} \n",
    "\n",
    "More details can be found in [[3]](#References)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example solving SPMe using PyBaMM"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below we show how to solve the SPMe model using the `Simulation` class with all the default settings. For a more detailed example, see the notebook on the [SPM](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/models/SPM.ipynb). \n",
    "\n",
    "First we need to import `pybamm`"
   ]
  },
  {
   "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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We then load the SPMe model and create a simulation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load model\n",
    "model = pybamm.lithium_ion.SPMe()\n",
    "\n",
    "# create simulation\n",
    "simulation = pybamm.Simulation(model)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The simulation is now ready to be solved"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<pybamm.solvers.solution.Solution at 0x7f2774bea390>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# solve simulation\n",
    "simulation.solve([0, 3600]) # time interval in seconds"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get a quick overview of the model outputs we can use the built-in `plot` method of the simulation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "6ec4df1500094dbd8efbf9fd7447d7f1",
       "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"
    }
   ],
   "source": [
    "simulation.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dimensionless Parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the table below, we provide the dimensionless parameters in the SPMe in terms of the dimensional parameters in LCO.csv. We use a superscript * to indicate dimensional quantities. \n",
    "\n",
    "| Parameter                 | Expression                              |Interpretation                             |\n",
    "|:--------------------------|:----------------------------------------|:------------------------------------------|\n",
    "| $L_{\\text{k}}$            | $L_{\\text{k}}^*/L^*$                    | Ratio of region thickness to cell thickness|\n",
    "|$\\mathcal{C}_{\\text{k}}$   | $\\tau_{\\text{k}}^*/\\tau_{\\text{d}}^*$   | Ratio of solid diffusion and discharge timescales |\n",
    "|$\\mathcal{C}_{\\text{e}}$   |$\\tau_{\\text{e}}^*/\\tau_{\\text{d}}^*$    |Ratio of electrolyte transport and discharge timescales|\n",
    "|$\\mathcal{C}_{\\text{r,k}}$ |$\\tau_{\\text{r,k}}^*/\\tau_{\\text{d}}^*$  |Ratio of reaction and discharge timescales|\n",
    "|$a_{R, \\text{k}}$             |$a_{\\text{k}}^* R_{\\text{k}}^*$          | Product of particle radius and surface area to volume ratio|\n",
    "|$\\gamma_{\\text{k}}$        |$c_{\\text{k,max}}^*/c_{\\text{n,max}}^*$  |Ratio of maximum lithium concentrations in solid|\n",
    "|$\\gamma_{\\text{e}}$        |$c_{\\text{e,typ}}^*/c_{\\text{n,max}}^*$  |Ratio of maximum lithium concentration in the negative electrode solid and typical electrolyte concentration|\n",
    "\n",
    "Note that the dimensionless parameters $\\epsilon_{\\text{k}}$, $\\text{b}$, and $t^+$ are already provided in the parameter file LCO.csv.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "The relevant papers for this notebook are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "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] 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 (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.9.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}