examples/notebooks/Getting Started/Tutorial 2 - Setting Parameter Values.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 2 - Setting Parameter Values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In [Tutorial 1](./Tutorial%201%20-%20How%20to%20run%20a%20model.ipynb), we saw how to run a PyBaMM model with all the default settings. However, PyBaMM also allows you to tweak these settings for your application. In this tutorial, we will see how to build a parameter set in PyBaMM and also how parameter values can be quickly changed temporarily."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pybamm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Build a parameter set"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "PyBaMM allows you to build a full battery parameter set from parameter values for each component of the battery: anode, cathode, etc. The parameters for each component of the cell are stored within `input/parameters/lithium_ion/anode`, `input/parameters/lithium_ion/cathode`, etc. Each component consists of folders of parameter values (e.g. graphite_mcmb2528_Marquis2019). For information on how to add your own folder of parameter values see [Additional Information](#adding_parameters). We select the parameter set to use for each component by creating the following python dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "parameter_options = {\n",
    "    \"chemistry\": \"lithium-ion\",\n",
    "    \"cell\": \"kokam_Marquis2019\",\n",
    "    \"anode\": \"graphite_mcmb2528_Marquis2019\",\n",
    "    \"separator\": \"separator_Marquis2019\",\n",
    "    \"cathode\": \"lico2_Marquis2019\",\n",
    "    \"electrolyte\": \"lipf6_Marquis2019\",\n",
    "    \"experiment\": \"1C_discharge_from_full_Marquis2019\",\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "where the keys (i.e. left of the ':') are the various cell components and the values (i.e. right of the ':') correspond to the parameter sets in each component."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now pass this set of options into a `ParameterValues` object, which builds the full parameter set:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "parameter_values = pybamm.ParameterValues(chemistry=parameter_options)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now perform the same process as in Tutorial 1 but this time we also pass our parameter values when we create the `Simulation`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "051690c8629b4ab3992cfb364c4aa8e1",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=0.9999999999999999, step=0.05), Output()), _…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "model = pybamm.lithium_ion.SPMe()\n",
    "sim = pybamm.Simulation(model, parameter_values=parameter_values)\n",
    "sim.solve()\n",
    "sim.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tweak a parameter value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We often want to quickly change a small number of parameter values to investigate how the behaviour or the battery changes. In such cases, creating and building a full parameter set is not ideal. However, PyBaMM also makes it easy to change parameter values without having to leave the notebook or script you are working in. \n",
    "\n",
    "We begin by loading a model and creating a simulation as we have done before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "model2 = pybamm.lithium_ion.SPMe()\n",
    "sim2 = pybamm.Simulation(model2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now extract the parameter values that have been automatically loaded into our simulation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "parameter_values2 = sim2.parameter_values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The values of the parameters are stored within a python dictionary where the keys correspond to that parameter name (e.g. 'Typical current [A]') and the values correspond to the parameter value (e.g. 0.68). For how to to view the full list of parameters and their values, please see [Additional Information](#viewing_values). In this notebook, we will just tweak the typical current from it's default 1C value (0.68 A) to a 2C rate (1.36 A):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "parameter_values2.update({\"Current function [A]\": 1.36})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now load the updated parameter values into the simulation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim2.specs(parameter_values=parameter_values2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then we can solve and plot our model as before, noticing that the cell now discharges in around half the time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "260a89fad4db4fadbf409bc123a18285",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=0.4852877005347593, step=0.05), Output()), _…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "sim2.solve()\n",
    "sim2.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this tutorial we have seen how to set the parameter values by cell component and how to tweak individual parameter values.\n",
    "\n",
    "In [Tutorial 3](./Tutorial%203%20-%20Basic%20Plotting.ipynb) we introduce some basic plotting functionalities."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Additional Information\n",
    "### Adding your own parameter sets <a name=\"adding_parameters\"></a>\n",
    "The parameters for each component of the cell are stored within `input/parameters/lithium_ion/anode`, `input/parameters/lithium_ion/cathode`, etc. Each component consists of folders of parameter sets (e.g. `graphite_mcmb2528_Marquis2019`) within which there are python functions for any functional dependancies (e.g. the open-circuit potential is a function of lithium concentration) as well as a `.csv` file containing all other parameters. If you wish to add your own parameter values for a particular component of the cell, simply create a new folder (e.g. `my_anode_params`) within the component folder (e.g. `input/parameters/lithium_ion/anode`) and then input the parameter values in the same format as the inbuilt parameter sets (it is probably easiest to just copy across the contents of `graphite_mcmb2528_Marquis2019` into `my_anode_params` and modify the values as you wish). \n",
    "\n",
    "More information on how to add parameter values is provided in our [online documentation](https://pybamm.readthedocs.io/en/latest/tutorials/add-parameter-values.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Viewing the list of parameters <a name=\"viewing_values\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To view the full list of parameters and their associated values, simply type: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{   'Ambient temperature [K]': 298.15,\n",
       "    'C-rate': 1.9981898750543627,\n",
       "    'Cation transference number': 0.4,\n",
       "    'Cell capacity [A.h]': 0.680616,\n",
       "    'Current function [A]': 1.36,\n",
       "    'Electrode height [m]': 0.13699999999999998,\n",
       "    'Electrode width [m]': 0.207,\n",
       "    'Electrolyte conductivity [S.m-1]': <function electrolyte_conductivity_Capiglia1999 at 0x7f42be7f4320>,\n",
       "    'Electrolyte conductivity activation energy [J.mol-1]': 34700.0,\n",
       "    'Electrolyte diffusion activation energy [J.mol-1]': 37040.0,\n",
       "    'Electrolyte diffusivity [m2.s-1]': <function electrolyte_diffusivity_Capiglia1999 at 0x7f42be7f44d0>,\n",
       "    'Heat transfer coefficient [W.m-2.K-1]': 10.0,\n",
       "    'Initial concentration in electrolyte [mol.m-3]': 1000.0,\n",
       "    'Initial concentration in negative electrode [mol.m-3]': 19986.609595075,\n",
       "    'Initial concentration in positive electrode [mol.m-3]': 30730.755438556498,\n",
       "    'Initial temperature [K]': 298.15,\n",
       "    'Lower voltage cut-off [V]': 3.105,\n",
       "    'Maximum concentration in negative electrode [mol.m-3]': 24983.2619938437,\n",
       "    'Maximum concentration in positive electrode [mol.m-3]': 51217.9257309275,\n",
       "    'Negative current collector conductivity [S.m-1]': 59600000.0,\n",
       "    'Negative current collector density [kg.m-3]': 8954.0,\n",
       "    'Negative current collector specific heat capacity [J.kg-1.K-1]': 385.0,\n",
       "    'Negative current collector thermal conductivity [W.m-1.K-1]': 401.0,\n",
       "    'Negative current collector thickness [m]': 2.5e-05,\n",
       "    'Negative electrode Bruggeman coefficient (electrode)': 1.5,\n",
       "    'Negative electrode Bruggeman coefficient (electrolyte)': 1.5,\n",
       "    'Negative electrode OCP [V]': <function graphite_mcmb2528_ocp_Dualfoil1998 at 0x7f42bfb4a8c0>,\n",
       "    'Negative electrode OCP entropic change [V.K-1]': <function graphite_entropic_change_Moura2016 at 0x7f42bfb4ab90>,\n",
       "    'Negative electrode active material volume fraction': 0.7,\n",
       "    'Negative electrode cation signed stoichiometry': -1.0,\n",
       "    'Negative electrode charge transfer coefficient': 0.5,\n",
       "    'Negative electrode conductivity [S.m-1]': 100.0,\n",
       "    'Negative electrode density [kg.m-3]': 1657.0,\n",
       "    'Negative electrode diffusivity [m2.s-1]': <function graphite_mcmb2528_diffusivity_Dualfoil1998 at 0x7f42ebf467a0>,\n",
       "    'Negative electrode double-layer capacity [F.m-2]': 0.2,\n",
       "    'Negative electrode electrons in reaction': 1.0,\n",
       "    'Negative electrode porosity': 0.3,\n",
       "    'Negative electrode reaction rate': <function graphite_electrolyte_reaction_rate_Dualfoil1998 at 0x7f42bfb4a7a0>,\n",
       "    'Negative electrode specific heat capacity [J.kg-1.K-1]': 700.0,\n",
       "    'Negative electrode surface area density [m-1]': 180000.0,\n",
       "    'Negative electrode thermal conductivity [W.m-1.K-1]': 1.7,\n",
       "    'Negative electrode thickness [m]': 0.0001,\n",
       "    'Negative particle distribution in x': 1.0,\n",
       "    'Negative particle radius [m]': 1e-05,\n",
       "    'Negative reaction rate activation energy [J.mol-1]': 37480.0,\n",
       "    'Negative solid diffusion activation energy [J.mol-1]': 42770.0,\n",
       "    'Negative tab centre y-coordinate [m]': 0.06,\n",
       "    'Negative tab centre z-coordinate [m]': 0.13699999999999998,\n",
       "    'Negative tab width [m]': 0.04,\n",
       "    'Number of cells connected in series to make a battery': 1.0,\n",
       "    'Number of electrodes connected in parallel to make a cell': 1.0,\n",
       "    'Positive current collector conductivity [S.m-1]': 35500000.0,\n",
       "    'Positive current collector density [kg.m-3]': 2707.0,\n",
       "    'Positive current collector specific heat capacity [J.kg-1.K-1]': 897.0,\n",
       "    'Positive current collector thermal conductivity [W.m-1.K-1]': 237.0,\n",
       "    'Positive current collector thickness [m]': 2.5e-05,\n",
       "    'Positive electrode Bruggeman coefficient (electrode)': 1.5,\n",
       "    'Positive electrode Bruggeman coefficient (electrolyte)': 1.5,\n",
       "    'Positive electrode OCP [V]': <function lico2_ocp_Dualfoil1998 at 0x7f42bfb4ad40>,\n",
       "    'Positive electrode OCP entropic change [V.K-1]': <function lico2_entropic_change_Moura2016 at 0x7f42be7f40e0>,\n",
       "    'Positive electrode active material volume fraction': 0.7,\n",
       "    'Positive electrode cation signed stoichiometry': -1.0,\n",
       "    'Positive electrode charge transfer coefficient': 0.5,\n",
       "    'Positive electrode conductivity [S.m-1]': 10.0,\n",
       "    'Positive electrode density [kg.m-3]': 3262.0,\n",
       "    'Positive electrode diffusivity [m2.s-1]': <function lico2_diffusivity_Dualfoil1998 at 0x7f42bfb4ac20>,\n",
       "    'Positive electrode double-layer capacity [F.m-2]': 0.2,\n",
       "    'Positive electrode electrons in reaction': 1.0,\n",
       "    'Positive electrode porosity': 0.3,\n",
       "    'Positive electrode reaction rate': <function lico2_electrolyte_reaction_rate_Dualfoil1998 at 0x7f42bfb36710>,\n",
       "    'Positive electrode specific heat capacity [J.kg-1.K-1]': 700.0,\n",
       "    'Positive electrode surface area density [m-1]': 150000.0,\n",
       "    'Positive electrode thermal conductivity [W.m-1.K-1]': 2.1,\n",
       "    'Positive electrode thickness [m]': 0.0001,\n",
       "    'Positive particle distribution in x': 1.0,\n",
       "    'Positive particle radius [m]': 1e-05,\n",
       "    'Positive reaction rate activation energy [J.mol-1]': 39570.0,\n",
       "    'Positive solid diffusion activation energy [J.mol-1]': 18550.0,\n",
       "    'Positive tab centre y-coordinate [m]': 0.147,\n",
       "    'Positive tab centre z-coordinate [m]': 0.13699999999999998,\n",
       "    'Positive tab width [m]': 0.04,\n",
       "    'Reference OCP vs SHE in the negative electrode [V]': nan,\n",
       "    'Reference OCP vs SHE in the positive electrode [V]': nan,\n",
       "    'Reference temperature [K]': 298.15,\n",
       "    'Separator Bruggeman coefficient (electrode)': 1.5,\n",
       "    'Separator Bruggeman coefficient (electrolyte)': 1.5,\n",
       "    'Separator density [kg.m-3]': 397.0,\n",
       "    'Separator porosity': 1.0,\n",
       "    'Separator specific heat capacity [J.kg-1.K-1]': 700.0,\n",
       "    'Separator thermal conductivity [W.m-1.K-1]': 0.16,\n",
       "    'Separator thickness [m]': 2.5e-05,\n",
       "    'Typical current [A]': 0.680616,\n",
       "    'Typical electrolyte concentration [mol.m-3]': 1000.0,\n",
       "    'Upper voltage cut-off [V]': 4.7}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parameter_values2"
   ]
  }
 ],
 "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.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}