Experiment refactor

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 -   `plot` and `plot2D` now take and return a matplotlib Axis to allow for easier customization ([#1472](https://github.com/pybamm-team/PyBaMM/pull/1472))
 -   `ParameterValues.evaluate` can now return arrays to allow function parameters to be easily evaluated ([#1472](https://github.com/pybamm-team/PyBaMM/pull/1472))
+-   Added option to save only specific cycle numbers when simulating an `Experiment` ([#1459](https://github.com/pybamm-team/PyBaMM/pull/1459))
+-   Added capacity-based termination conditions when simulating an `Experiment` ([#1459](https://github.com/pybamm-team/PyBaMM/pull/1459))
+-   Added "summary variables" to track degradation over several cycles ([#1459](https://github.com/pybamm-team/PyBaMM/pull/1459))
+-   Added `ElectrodeSOH` model for calculating capacities and stoichiometric limits ([#1459](https://github.com/pybamm-team/PyBaMM/pull/1459))
 -   Added Batch Study class ([#1455](https://github.com/pybamm-team/PyBaMM/pull/1455))
 -   Added `ConcatenationVariable`, which is automatically created when variables are concatenated ([#1453](https://github.com/pybamm-team/PyBaMM/pull/1453))
 -   Added "fast with events" mode for the CasADi solver, which solves a model and finds events more efficiently than "safe" mode. As of PR #1450 this feature is still being tested and "safe" mode remains the default ([#1450](https://github.com/pybamm-team/PyBaMM/pull/1450))

examples/notebooks/Getting Started/Tutorial 3 - Basic plotting.ipynb

@@ -455,9 +455,9 @@
        " 'Current collector current density',\n",
        " 'Current collector current density [A.m-2]',\n",
        " 'Leading-order current collector current density',\n",
-       " 'Sei interfacial current density',\n",
-       " 'Sei interfacial current density [A.m-2]',\n",
-       " 'Sei interfacial current density per volume [A.m-3]',\n",
+       " 'SEI interfacial current density',\n",
+       " 'SEI interfacial current density [A.m-2]',\n",
+       " 'SEI interfacial current density per volume [A.m-3]',\n",
        " 'Negative electrode interfacial current density',\n",
        " 'X-averaged negative electrode interfacial current density',\n",
        " 'Negative electrode interfacial current density [A.m-2]',\n",

examples/notebooks/Getting Started/Tutorial 5 - Run experiments.ipynb

@@ -227,7 +227,20 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.4"
+   "version": "3.8.8"
+  },
+  "toc": {
+   "base_numbering": 1,
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": true
   }
  },
  "nbformat": 4,

examples/notebooks/models/SPM.ipynb

@@ -696,6 +696,7 @@
       "\t- Total lithium in negative electrode [mol]\n",
       "\t- Positive particle flux\n",
       "\t- X-averaged positive particle flux\n",
+      "\t- Total lithium in electrolyte [mol]\n",
       "\t- Positive electrode volume-averaged concentration\n",
       "\t- Positive electrode volume-averaged concentration [mol.m-3]\n",
       "\t- Total lithium in positive electrode [mol]\n",
@@ -729,9 +730,9 @@
       "\t- Current collector current density\n",
       "\t- Current collector current density [A.m-2]\n",
       "\t- Leading-order current collector current density\n",
-      "\t- Sei interfacial current density\n",
-      "\t- Sei interfacial current density [A.m-2]\n",
-      "\t- Sei interfacial current density per volume [A.m-3]\n",
+      "\t- SEI interfacial current density\n",
+      "\t- SEI interfacial current density [A.m-2]\n",
+      "\t- SEI interfacial current density per volume [A.m-3]\n",
       "\t- X-averaged negative electrode total interfacial current density\n",
       "\t- X-averaged negative electrode total interfacial current density [A.m-2]\n",
       "\t- X-averaged negative electrode total interfacial current density per volume [A.m-3]\n",

examples/notebooks/submodel_cracking_DFN_or_SPM.ipynb

@@ -0,0 +1,292 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Using crack submodels in PyBaMM\n",
+    "In this notebook we show how to use the crack submodel with battery DFN or SPM models. To see all of the models and submodels available in PyBaMM, please take a look at the documentation [here](https://pybamm.readthedocs.io/en/latest/source/models/index.html)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\u001b[33mWARNING: You are using pip version 21.0.1; however, version 21.1 is available.\n",
+      "You should consider upgrading via the '/Users/vsulzer/Documents/Energy_storage/PyBaMM/.tox/dev/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    # 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": [
+    "Then we load the DFN, SPMe or SPM, by choosing one and commenting the others. \n",
+    "\n",
+    "When you load a model in PyBaMM it builds by default. Building the model sets all of the model variables and sets up any variables which are coupled between different submodels: this is the process which couples the submodels together and allows one submodel to access variables from another. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# model = pybamm.lithium_ion.SPMe(\n",
+    "# model = pybamm.lithium_ion.SPM(\n",
+    "model = pybamm.lithium_ion.DFN(\n",
+    "    options = {\n",
+    "        \"particle\": \"Fickian diffusion\",  \n",
+    "        \"particle cracking\": \"both\", # other options are \"positive\", \"negative\" or \"none\"\n",
+    "    }\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Load the parameter set Ai2020 which contains mechanical parameters. Other sets may not contain mechanical parameters should add them manually. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "chemistry = pybamm.parameter_sets.Ai2020\n",
+    "param = pybamm.ParameterValues(chemistry=chemistry)\n",
+    "## It can update the speed of crack propagation using the commands below:\n",
+    "# param.update({\"Negative electrode Cracking rate\":3.9e-20*10})\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can get the default parameters for the model and update them with the parameters required by the cracking model. Eventually, we would like these to be added to their own chemistry (you might need to adjust the path to the parameters file to your system).\n",
+    "Now the model can be processed and solved in the usual way, and we still have access to model defaults such as the default geometry and default spatial methods"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "f5cc346733024d02b5ca2a4c01a70125",
+       "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": [
+    "sim = pybamm.Simulation(\n",
+    "    model,\n",
+    "    parameter_values=param,\n",
+    "    solver=pybamm.CasadiSolver(dt_max=600),\n",
+    ")\n",
+    "solution = sim.solve(t_eval=[0, 3600], inputs={\"C-rate\": 1})\n",
+    "# plot\n",
+    "quick_plot = pybamm.QuickPlot(solution)\n",
+    "quick_plot.dynamic_plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Plot the results as required."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "04b61fc2edab402b96dd5e364fc7af9f",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "interactive(children=(FloatSlider(value=0.0, description='t', max=3600.0, step=10.0), Output()), _dom_classes=…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "# extract voltage\n",
+    "stress_t_n_surf = solution[\"Negative particle surface tangential stress\"]\n",
+    "x = solution[\"x [m]\"].entries[0:19, 0]\n",
+    "c_s_n = solution['Negative particle concentration']\n",
+    "r_n = solution[\"r_n [m]\"].entries[:, 0, 0]\n",
+    "\n",
+    "# plot\n",
+    "def plot_concentrations(t):\n",
+    "    f, (ax1, ax2, ax3, ax4) = plt.subplots(1, 4 ,figsize=(20,4))\n",
+    "    ax1.plot(x, stress_t_n_surf(t=t,x=x))\n",
+    "    ax1.set_xlabel(r'$x_n$ [m]')\n",
+    "    ax1.set_ylabel('$\\sigma_t/E_n$')\n",
+    "    \n",
+    "    plot_c_n, = ax2.plot(r_n, c_s_n(r=r_n,t=t,x=x[0]))  # can evaluate at arbitrary x (single representative particle)\n",
+    "    ax2.set_ylabel('Negative particle concentration')\n",
+    "    ax2.set_xlabel(r'$r_n$ [m]')\n",
+    "    ax2.set_ylim(0, 1)\n",
+    "    ax2.set_title('Close to current collector')\n",
+    "    ax2.grid()\n",
+    "    \n",
+    "    plot_c_n, = ax3.plot(r_n, c_s_n(r=r_n,t=t,x=x[10]))  # can evaluate at arbitrary x (single representative particle)\n",
+    "    ax3.set_ylabel('Negative particle concentration')\n",
+    "    ax3.set_xlabel(r'$r_n$ [m]')\n",
+    "    ax3.set_ylim(0, 1)  \n",
+    "    ax3.set_title('In the middle')\n",
+    "    ax3.grid()\n",
+    "\n",
+    "    plot_c_n, = ax4.plot(r_n, c_s_n(r=r_n,t=t,x=x[-1]))  # can evaluate at arbitrary x (single representative particle)\n",
+    "    ax4.set_ylabel('Negative particle concentration')\n",
+    "    ax4.set_xlabel(r'$r_n$ [m]')\n",
+    "    ax4.set_ylim(0, 1)  \n",
+    "    ax4.set_title('Close to separator')\n",
+    "    ax4.grid()\n",
+    "    plt.show()\n",
+    "    \n",
+    "import ipywidgets as widgets\n",
+    "widgets.interact(plot_concentrations, t=widgets.FloatSlider(min=0,max=3600,step=10,value=0));"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Plot results using the default functions"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "ab6ce386f2cc4e44adbf072d3db93086",
+       "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": [
+    "label = [\"Crack model\"]\n",
+    "output_variables = [\n",
+    "    \"Negative particle crack length\", \n",
+    "    \"Positive particle crack length\",\n",
+    "    \"X-averaged negative particle crack length\",\n",
+    "    \"X-averaged positive particle crack length\"\n",
+    "]\n",
+    "quick_plot = pybamm.QuickPlot(solution, output_variables, label,variable_limits='tight')\n",
+    "quick_plot.dynamic_plot();\n"
+   ]
+  },
+  {
+   "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] Weilong Ai, Ludwig Kraft, Johannes Sturm, Andreas Jossen, and Billy Wu. Electrochemical thermal-mechanical modelling of stress inhomogeneity in lithium-ion pouch cells. Journal of The Electrochemical Society, 167(1):013512, 2019. doi:10.1149/2.0122001JES.\n",
+      "[2] 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",
+      "[3] Rutooj Deshpande, Mark Verbrugge, Yang-Tse Cheng, John Wang, and Ping Liu. Battery cycle life prediction with coupled chemical degradation and fatigue mechanics. Journal of the Electrochemical Society, 159(10):A1730, 2012. doi:10.1149/2.049210jes.\n",
+      "[4] Marc Doyle, Thomas F. Fuller, and John Newman. Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell. Journal of the Electrochemical society, 140(6):1526–1533, 1993. doi:10.1149/1.2221597.\n",
+      "[5] 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",
+      "[6] 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.8.8"
+  },
+  "toc": {
+   "base_numbering": 1,
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": true
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

examples/scripts/calendar_ageing.py

@@ -47,15 +47,8 @@
         "X-averaged total negative electrode SEI thickness",
         "X-averaged negative electrode SEI concentration [mol.m-3]",
         "Loss of lithium to negative electrode SEI [mol]",
-        [
-            "Negative electrode SEI interfacial current density [A.m-2]",
-            "Negative electrode interfacial current density [A.m-2]",
-        ],
-        [
-            "X-averaged negative electrode SEI interfacial current density [A.m-2]",
-            "X-averaged negative electrode interfacial current density [A.m-2]",
-        ],
         "Sum of x-averaged negative electrode interfacial current densities",
-        "X-averaged electrolyte concentration",
+        "Loss of lithium inventory [%]",
+        ["Total lithium lost [mol]", "Loss of lithium to negative electrode SEI [mol]"],
     ],
 )

examples/scripts/conservation_lithium.py

@@ -25,10 +25,9 @@
 solution = sim.solution
 
 t = solution["Time [s]"].entries
-Ne = solution["Total concentration in electrolyte [mol]"].entries
 Np = solution["Total lithium in positive electrode [mol]"].entries
 Nn = solution["Total lithium in negative electrode [mol]"].entries
-Ntot = Np + Nn + Ne
+Ntot = solution["Total lithium [mol]"].entries
 
 fig, ax = plt.subplots(1, 2, figsize=(12, 5))