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

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 5 - Run experiments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In [Tutorial 4](./Tutorial%204%20-%20Setting%20parameter%20values.ipynb) we saw how to change the parameters, including the applied current. However, in some cases we might want to prescribe a given voltage, a given power or switch between different conditions to simulate experimental setups. We can use the Experiment class for these simulations."
   ]
  },
  {
   "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 start defining an experiment, which consists on a set of instructions on how to cycle the battery. For example, we can set the following experiment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "experiment = pybamm.Experiment(\n",
    "    [\n",
    "        (\"Discharge at C/10 for 10 hours or until 3.3 V\",\n",
    "        \"Rest for 1 hour\",\n",
    "        \"Charge at 1 A until 4.1 V\",\n",
    "        \"Hold at 4.1 V until 50 mA\",\n",
    "        \"Rest for 1 hour\"),\n",
    "    ] * 3\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A cycle is defined by a tuple of operating instructions. In this case, the experiment consists of a cycle of constant current C/10 discharge, a one hour rest, a constant current (1 A) constant voltage (4.1 V) and another one hour rest, all of it repeated three times (notice the * 3).\n",
    "\n",
    "Then we can choose our model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "model = pybamm.lithium_ion.DFN()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and create our simulation, passing our experiment using a keyword argument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim = pybamm.Simulation(model, experiment=experiment)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We then solve and plot the solution"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "c842009da20b48adad4948737f0c2fca",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=38.86666666666666, step=0.3886666666666666),…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "sim.solve()\n",
    "sim.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we have seen, experiments allow us to define complex simulations using a very simple syntax. The instructions can be of the form \"(Dis)charge at x A/C/W\", \"Rest\", or \"Hold at x V\". The running time should be a time in seconds, minutes or hours, e.g. \"10 seconds\", \"3 minutes\" or \"1 hour\". The stopping conditions should be a circuit state, e.g. \"1 A\", \"C/50\" or \"3 V\". \n",
    "\n",
    "Some examples of experiment instructions are:\n",
    "```python\n",
    "    \"Discharge at 1C for 0.5 hours\",\n",
    "    \"Discharge at C/20 for 0.5 hours\",\n",
    "    \"Charge at 0.5 C for 45 minutes\",\n",
    "    \"Discharge at 1 A for 90 seconds\",\n",
    "    \"Charge at 200mA for 45 minutes (1 minute period)\",\n",
    "    \"Discharge at 1 W for 0.5 hours\",\n",
    "    \"Charge at 200 mW for 45 minutes\",\n",
    "    \"Rest for 10 minutes (5 minute period)\",\n",
    "    \"Hold at 1 V for 20 seconds\",\n",
    "    \"Charge at 1 C until 4.1V\",\n",
    "    \"Hold at 4.1 V until 50 mA\",\n",
    "    \"Hold at 3V until C/50\",\n",
    "```\n",
    "\n",
    "Optionally, each instruction can contain at the end the expression \"(x minute period)\" in which the period at which to record the simulation outputs during that instruction. To change the period for the whole experiment we can pass it as a keyword argument in the experiment.\n",
    "\n",
    "Additionally, we can use the operators `+` and `*` on lists in order to combine and repeat cycles:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('Discharge at 1C for 0.5 hours', 'Discharge at C/20 for 0.5 hours'),\n",
       " ('Discharge at 1C for 0.5 hours', 'Discharge at C/20 for 0.5 hours'),\n",
       " ('Discharge at 1C for 0.5 hours', 'Discharge at C/20 for 0.5 hours'),\n",
       " ('Charge at 0.5 C for 45 minutes',)]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[(\"Discharge at 1C for 0.5 hours\", \"Discharge at C/20 for 0.5 hours\")] * 3 + [(\"Charge at 0.5 C for 45 minutes\",)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this notebook we have seen how to use the Experiment class to run simulations of more complex operating conditions. In [Tutorial 6](./Tutorial%206%20-%20Managing%20simulation%20outputs.ipynb) we will see how to manage the outputs of the simulation."
   ]
  },
  {
   "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] 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",
      "[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). 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
}