{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Note: the example below requires Cantera 2.5.0a2 or newer\n",
    "\n",
    "If the stable release of 2.5.0 is not yet available, you might consider [building from source](https://cantera.org/install/compiling-install.html). Note also that 2.5.0, once released, is more recent than and supercedes 2.5.0a2, which is an alpha release."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Runnning Cantera version: 2.5.0a2\n"
     ]
    }
   ],
   "source": [
    "import cantera as ct\n",
    "print('Runnning Cantera version: ' + ct.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Lithium Ion Battery Example\n",
    "## Open circuit calculations as a function of anode and cathode lithium content.\n",
    " \n",
    "In this example we will illustrate how to calculate the open circuit voltage (voltage when the external applied current is 0) for a lithium ion battery.  The thermodynamics are based on a graphite anode and a LiCoO2 cathode (the typical/standard active materials for commercial batteries, as of 2019), and are modeled using the 'BinarySolutionTabulatedThermo' class.\n",
    "\n",
    "For the sake of simplicity, we're going to assume that the anode and cathode capacities are perfectly balanced (i.e. if the cathode lithium content is X percent of it's max possible (i.e. its capacity), then we will assume that the anode is at 1-X percent.  Without loss of generality, we will define the anode composition:\n",
    "\n",
    "The routine below returns the cell voltage (in Volt) of a lithium-ion cell for a given cell current and active material lithium stoichiometries.\n",
    "\n",
    "Note that the function 'E_cell' below has even greater capabilities than what we use, here. It calculates the steady state cell voltage, at a given composition and cell current, for a given electrolyte ionic resistance.  This functionality is presented in greater detail in the reference (which also describes the derivation of the BinarySolutionTabulatedThermo class): M. Mayur, S. DeCaluwe, B. L. Kee, W. G. Bessler, \"Modeling thermodynamics and kinetics of intercalation phases for lithium-ion batteries in open source software\", currently under review at _Electrochimica Acta_.  In the future, this example may be developed further to demonstrate simulating charge-discharge of the lithium ion battery.\n",
    "\n",
    "\n",
    "Other than the typical Cantera dependencies, plotting functions require that you have matplotlib installed, and finding the electrode potentials uses Scipy's fsolve. See https://matplotlib.org/ and https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.fsolve.html for additional info.\n",
    "\n",
    "The open circuit (i.e. equilibrium) voltage, here, is calculated via two means: kinetically and thermodynamically.\n",
    "\n",
    "The system here, can be thought of as consisting of two particles--anode and cathode--connected by a liquid electrolyte:\n",
    "\n",
    "<img src=\"images/SingleParticleBattery.png\" alt=\"Cartoon of a Single Particle Battery Model\" style=\"width: 500px;\"/>\n",
    "\n",
    "### Kinetic equilibrium calculations\n",
    "In the kinetic equilibrium problem, steady state is achieved when the faradaic current at each electrode (anode and cathode) surface and the ionic current through the electrolyte are all zero.  There are, essentially, four relevant electric potentials which must be determined:\n",
    "\n",
    "- $\\phi_{\\rm anode}$: electric potential of graphite anode.\n",
    "- $\\phi_{\\rm elyte,\\, anode}$: electric potential of electrolyte at anode interface.\n",
    "- $\\phi_{\\rm elyte,\\, cathode}$: electric potential of electrolyte at cathode interface.\n",
    "- $\\phi_{\\rm cathode}$: electric potential of LCO cathode.\n",
    "\n",
    "Setting one of these four to the reference potential of zero (because it is the difference in electric potential which drives currents, the actual potential values are irrelevant. Let's assume the anode electric potential is zero), there is only one distribution of electric potentials across the cell such that the current is invariant across the cell.  I.e. we want the potentials such that:\n",
    "\n",
    "\\begin{equation}\n",
    "i_{\\rm Far,\\, anode} = i_{\\rm ionic} = i_{\\rm Far,\\,cathode}= i_{\\rm app}\n",
    "\\end{equation}\n",
    "\n",
    "where $i_{\\rm app}$ is the user input for the applied current.  For this example, we assume an applied current of 0, to calculate the equilibrium voltage.\n",
    "\n",
    "#### Faradaic current\n",
    "The Faradaic current for this model is calculated using Butler-Volmer kinetics.  For a Li-ion battery, this is:\n",
    "\n",
    "\\begin{equation}\n",
    "i = S_{\\rm elde}i_\\circ\\left[\\exp\\left(\\frac{F\\beta\\eta}{RT}\\right) - \\exp\\left(-\\frac{F\\beta\\eta}{RT}\\right) \\right]\n",
    "\\end{equation}\n",
    "\n",
    "where $S_{\\rm elde}$ is the specific surface area of the electrode in question, $F$ is Faraday's constant, $\\beta$ is the charge-transfer symmetry parameter, $R$ the universal gas constant, $T$ the temperature, and $\\eta$ the overpotential, which is the electric potential difference between the electrode and electrolyte, $\\Delta \\phi = \\phi_{\\rm elde} - \\phi_{\\rm elyte}$, relative to that at equilibrium, $\\Delta \\phi_{\\rm eq}$:\n",
    "\n",
    "\\begin{equation}\n",
    "\\eta = \\Delta \\phi - \\Delta \\phi_{\\rm eq}\n",
    "\\end{equation}\n",
    "\n",
    "$i_\\circ$ is known as the \"exchange current density,\" which is equal to the rate of the forward and reverse current at equilibrium (which are equal).  $i_\\circ$ and $\\beta$ are provided as user inputs in the cti file.  At any particular state, (user-specified electric potentials, pressure, temperature, and chemical compositions), Cantera calculates $\\eta$ as part of the routine to evaluate reaction rates of progress $\\left(\\dot{q} = \\frac{i_{\\rm Far}}{F}\\right)$. The user simply sets the state values mentioned above.\n",
    "\n",
    "#### Ionic current\n",
    "The electrolyte is modeled as a resistor with user-defined ionic resistance $R_{\\rm io}$, and hence the ionic current is calculated as:\n",
    "\n",
    "\\begin{equation}\n",
    "i_{\\rm ionic} = \\frac{\\phi_{\\rm elyte,\\,ca} - \\phi_{\\rm elyte,\\,an}}{R_{\\rm io}}\n",
    "\\end{equation}\n",
    "\n",
    "where positive current is defined as delivering Li$^+$ to the anode interface.  Given $i_{\\rm app}$, this equation can be inverted, to calculate the electric potential of the electrolyte at the cathode interface, relative to that at the anode interface:\n",
    "\n",
    "\\begin{equation}\n",
    "\\phi_{\\rm elyte,\\,ca} = \\phi_{\\rm elyte,\\,an} + R_{\\rm io}i_{\\rm app} \n",
    "\\end{equation}\n",
    "\n",
    "Again: in this example, $i_{\\rm app} = 0$ and hence the two electric potential values in the electrolyte are equal.\n",
    "\n",
    "#### Numerical routine\n",
    "For the kinetic routine, there are three processes to determine the cell voltage $\\phi_{\\rm cathode} - \\phi_{\\rm anode}$ which corresponds to the user-provided $i_{\\rm app}$:\n",
    "1. Determine the $\\phi_{\\rm elyte,\\,anode}$ value which corresponds to $i_{\\rm app}$, given $X_{\\rm Li, anode}$, the percentage of Li in the anode active material.\n",
    "2. Determine $\\phi_{\\rm elyte,\\,cathode}$, given $\\phi_{\\rm elyte,\\,anode}$ and $i_{\\rm app}$.\n",
    "3. Determine the $\\phi_{\\rm cathode}$ which corresponds to $i_{\\rm app}$, given $phi_{\\rm elyte,\\,cathode}$ and $X_{\\rm Li, anode}$, the percentage of Li in the anode active material.\n",
    "\n",
    "The routines below are written generally such that an interested user may set $i_{\\rm app}$ to any value of interest.\n",
    "\n",
    "#### Import necessary packages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 143,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import division\n",
    "from __future__ import print_function\n",
    "\n",
    "import numpy as np\n",
    "\n",
    "from scipy.optimize import fsolve\n",
    "\n",
    "# Used for timing our calculations:\n",
    "import time\n",
    "\n",
    "# Plotting:\n",
    "import matplotlib.pyplot as plt\n",
    "import matplotlib as mpl\n",
    "\n",
    "plt.rcParams['axes.labelsize'] = 16\n",
    "plt.rcParams['xtick.labelsize'] = 12\n",
    "plt.rcParams['ytick.labelsize'] = 12\n",
    "plt.rcParams['figure.autolayout'] = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define the phases\n",
    "\n",
    "The phase thermodynamics are defined according to experimentally-measured open circuit voltage values, as desscribed in the reference provided above:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "inputCTI = 'lithium_ion_battery.cti'\n",
    "anode = ct.Solution(inputCTI, 'anode');\n",
    "cathode = ct.Solution(inputCTI,'cathode');\n",
    "# The 'elde' electrode phase is needed as a source/sink for electrons:\n",
    "elde = ct.Solution(inputCTI,'electron');\n",
    "elyte = ct.Solution(inputCTI,'electrolyte');\n",
    "anode_interface = ct.Interface(inputCTI, 'edge_anode_electrolyte', [anode, elde, elyte]);\n",
    "cathode_interface = ct.Interface(inputCTI, 'edge_cathode_electrolyte', [cathode, elde, elyte]);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define battery conditions : temperature, pressure, stoichiometry, electrolyte resistance:\n",
    "\n",
    "Inputs are:\n",
    "- Stoichiometries X_Li_ca and X_Li_an [-] (can be vectors)\n",
    "- Temperature T [K]\n",
    "- Pressure P [Pa]\n",
    "- Externally-applied current i_app [A]\n",
    "- Electrolyte resistance R_elyte [Ohm]\n",
    "- Anode total surface area S_an [m^2]\n",
    "- Cathode total surface area S_ca [m^2]\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 131,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Array of lithium mole fractions in the anode:\n",
    "X_Li_an = np.arange(0.005, 0.995, 0.02)\n",
    "# Assume that the cathode and anode capacities are balanced:\n",
    "X_Li_ca = 1. - X_Li_an;\n",
    "\n",
    "# I_app = 0: Open circuit\n",
    "I_app = 0.;\n",
    "\n",
    "# At zero current, electrolyte resistance is irrelevant:\n",
    "R_elyte = 0.;\n",
    "\n",
    "# Temperature and pressure\n",
    "T = 300 # K\n",
    "P = ct.one_atm\n",
    "\n",
    "F = ct.faraday\n",
    "\n",
    "S_ca = 1.1167; # [m^2] Cathode total active material surface area\n",
    "S_an = 0.7824; # [m^2] Anode total active material surface area"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Set phase temperatures and pressures:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 132,
   "metadata": {},
   "outputs": [],
   "source": [
    "phases = [anode, elde, elyte, cathode, anode_interface, cathode_interface];\n",
    "for ph in phases:\n",
    "    ph.TP = T,P\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Helper Functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 133,
   "metadata": {},
   "outputs": [],
   "source": [
    "def anode_curr(phi_l,I_app,phi_s,X_Li_an):\n",
    "\n",
    "    # Set the active material mole fraction\n",
    "    anode.X = 'Li[anode]:'+str(X_Li_an)+', V[anode]:'+str(1-X_Li_an)\n",
    "\n",
    "    # Set the electrode and electrolyte potential\n",
    "    elde.electric_potential = phi_s\n",
    "    elyte.electric_potential = phi_l\n",
    "\n",
    "    # Get the net product rate of electrons in the anode (per m2^ interface)\n",
    "    r_elec = anode_interface.get_net_production_rates(elde)\n",
    "\n",
    "    anCurr = r_elec*ct.faraday*S_an;\n",
    "    diff = I_app + anCurr\n",
    "    \n",
    "    return diff\n",
    "\n",
    "def cathode_curr(phi_s,I_app,phi_l,X_Li_ca):\n",
    "    \n",
    "    # Set the active material mole fractions\n",
    "    cathode.X = 'Li[cathode]:'+str(X_Li_ca)+', V[cathode]:'+str(1-X_Li_ca)\n",
    "\n",
    "    # Set the electrode and electrolyte potential\n",
    "    elde.electric_potential = phi_s\n",
    "    elyte.electric_potential = phi_l\n",
    "    \n",
    "    # Get the net product rate of electrons in the cathode (per m2^ interface)\n",
    "    r_elec = cathode_interface.get_net_production_rates(elde)\n",
    "    \n",
    "    caCurr = r_elec*ct.faraday*S_an;\n",
    "    diff = I_app - caCurr\n",
    "    \n",
    "    return diff"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run the calculations for all stoichiometries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 150,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "49 cell voltages calculated in 0.36 seconds.\n"
     ]
    }
   ],
   "source": [
    "#Tic\n",
    "t0 = time.time()\n",
    "\n",
    "# Initialize array of OCVs:\n",
    "E_cell_kin = np.zeros_like(X_Li_ca)\n",
    "\n",
    "for i,X_an in enumerate(X_Li_an):\n",
    "    #Set anode electrode potential to 0:\n",
    "    phi_s_an = 0\n",
    "    E_init = 3.0\n",
    "   \n",
    "    phi_l_an = fsolve(anode_curr,E_init,args=(I_app,phi_s_an,X_an))\n",
    "    \n",
    "    # Calculate electrolyte potential at cathode interface:\n",
    "    phi_l_ca = phi_l_an + I_app*R_elyte;\n",
    "    \n",
    "    # Calculate cathode electrode potential\n",
    "    phi_s_ca = fsolve(cathode_curr,E_init,args=(I_app,phi_l_ca,X_Li_ca[i]))\n",
    "    \n",
    "    # Calculate cell voltage\n",
    "    E_cell_kin[i] = phi_s_ca - phi_s_an\n",
    "    \n",
    "    \n",
    "#Toc\n",
    "t1 = time.time()\n",
    "print('{:d} cell voltages calculated in {:3.2f} seconds.'.format(i,t1-t0))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot cell voltage, as a function of the cathode stoichiometry:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 152,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "[encoded data, 18828 characters]\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure()\n",
    "plt.plot(100*X_Li_ca, E_cell_kin,color='b',linewidth=2.5)\n",
    "plt.ylim([2.5,4.3])\n",
    "plt.xlabel('Li Fraction in Cathode (%)',fontname='Times New Roman',fontsize=18)\n",
    "plt.ylabel('Open Circuit Potential (V)',fontname='Times New Roman',fontsize=18)\n",
    "\n",
    "ax = plt.gca()\n",
    "\n",
    "for tick in ax.xaxis.get_major_ticks():\n",
    "    tick.label1.set_fontsize(14)\n",
    "    tick.label1.set_fontname('Times New Roman')\n",
    "for tick in ax.yaxis.get_major_ticks():\n",
    "    tick.label1.set_fontsize(14)\n",
    "    tick.label1.set_fontname('Times New Roman')\n",
    "    \n",
    "plt.show()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Thermodynamic Equilibrium Calculation\n",
    "For the I_app = 0 case, we can also calcualte the voltage using thermodynamics.  At equilibrium, the net electrochemical potential change of the reaction must be zero:\n",
    "\n",
    "\\begin{equation}\n",
    "\\sum_k\\nu_k\\tilde{\\mu}_k = 0\n",
    "\\end{equation}\n",
    "\n",
    "where $\\tilde{\\mu}_k = \\mu_k + z_kF\\Phi_k$, where, in turn $\\mu_k = \\frac{\\partial g_k}{\\partial n_k}$ is the chemical potential, $\\nu_k$ the net stoichiometric coefficient, $z_k$ the net elementary charge, and $\\Phi_k$ the phase electric potential for species $k$.\n",
    "\n",
    "From this, we can calculate the equilibrium electric potential difference $\\Delta \\Phi_{\\rm eq} = \\left(\\Phi_{\\rm elde} - \\Phi_{\\rm elyte}\\right)_{\\rm eq}$ as:\n",
    "\n",
    "\\begin{equation}\n",
    "\\Delta \\Phi_{\\rm eq} = -\\frac{\\Delta g_{\\rm rxn}}{n_{\\rm charge}F}\n",
    "\\end{equation}\n",
    "\n",
    "where $\\Delta g_{\\rm rxn} = \\sum_k \\nu_k\\mu_k$ is the chemical potential of the reaction and and $n_{\\rm charge} = \\sum_{k,\\,{\\rm elde}} \\nu_k z_k$ is the net elementary charge transferred from the electrolyte to the electrode."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 154,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "49 cell voltages calculated in 0.01 seconds.\n"
     ]
    }
   ],
   "source": [
    "#Tic\n",
    "t0 = time.time()\n",
    "\n",
    "# Initialize array of OCVs:\n",
    "E_cell_therm = np.zeros_like(X_Li_ca)\n",
    "\n",
    "for i,X_an in enumerate(X_Li_an):\n",
    "    #Set anode electrode potential to 0:\n",
    "    anode.X = 'Li[anode]:'+str(X_an)+', V[anode]:'+str(1-X_an)\n",
    "    dG_an = anode_interface.delta_gibbs[0]\n",
    "    n_charge = -1.\n",
    "    E_eq_an = -dG_an/n_charge/ct.faraday\n",
    "    \n",
    "    cathode.X = 'Li[cathode]:'+str(1.-X_an)+', V[cathode]:'+str(X_an)\n",
    "    dG_ca = cathode_interface.delta_gibbs[0]\n",
    "    n_charge = 1.\n",
    "    E_eq_ca = -dG_ca/n_charge/ct.faraday\n",
    "    \n",
    "    E_cell_therm[i] = E_eq_ca - E_eq_an\n",
    "    \n",
    "#Toc\n",
    "t1 = time.time()\n",
    "print('{:d} cell voltages calculated in {:3.2f} seconds.'.format(i,t1-t0))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot thermodynamic OCV, and compare to results from kinetic method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 166,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "[encoded data, 24028 characters]\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure()\n",
    "plt.plot(100*X_Li_ca, E_cell_therm,color='b',linewidth=2.5)\n",
    "plt.plot(100*X_Li_ca, E_cell_kin,linewidth=0.,marker='o',markerfacecolor='none',markeredgecolor='r')\n",
    "plt.ylim([2.5,4.3])\n",
    "plt.xlabel('Li Fraction in Cathode (%)',fontname='Times New Roman',fontsize=18)\n",
    "plt.ylabel('Open Circuit Potential (V)',fontname='Times New Roman',fontsize=18)\n",
    "plt.legend(['Thermodynamic','Kinetic'])\n",
    "\n",
    "ax = plt.gca()\n",
    "\n",
    "for tick in ax.xaxis.get_major_ticks():\n",
    "    tick.label1.set_fontsize(14)\n",
    "    tick.label1.set_fontname('Times New Roman')\n",
    "for tick in ax.yaxis.get_major_ticks():\n",
    "    tick.label1.set_fontsize(14)\n",
    "    tick.label1.set_fontname('Times New Roman')\n",
    "    \n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As one would expect, the two approaches give identical results.  While both methods are incredibly fast, the thermodynamic method is roughly 30 times faster.\n",
    "\n",
    "A large part of this is that the thermodynamic approach is an analytical approach (i.e. the answer is known from theory), while the kinetic approach relies on the root-finding fzero method to fit the correct voltage.  Note also that the kinetic method, because of the use of Butler-Volmer kinetics, calculates the thermodynamic voltage, in order to calculate the overpotential $\\eta = \\Delta \\Phi - \\Delta \\Phi_{\\rm eq}$.\n",
    "\n",
    "However, it is at last important to note that, while slower, the kinetic method is of course more robust, and can be used to find results away from equilibrium.  The thermodynamic method is only applicable at equilibrium (zero current)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "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": 1
}
