Merge pull request pybamm-team#1095 from pybamm-team/develop

v0.2.3 release

CHANGELOG.md

@@ -1,3 +1,39 @@
+# [v0.2.3](https://github.com/pybamm-team/PyBaMM/tree/v0.2.3) - 2020-07-01
+
+This release enables the use of [Google Colab](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/master/) for running example notebooks, and adds some small new features and bug fixes.
+
+## Features
+
+-   Reformatted Getting Started notebooks ([#1083](https://github.com/pybamm-team/PyBaMM/pull/1083))
+-   Reformatted Landesfeind electrolytes ([#1064](https://github.com/pybamm-team/PyBaMM/pull/1064))
+-   Adapted examples to be run in Google Colab ([#1061](https://github.com/pybamm-team/PyBaMM/pull/1061))
+-   Added some new solvers for algebraic models ([#1059](https://github.com/pybamm-team/PyBaMM/pull/1059))
+-   Added `length_scales` attribute to models ([#1058](https://github.com/pybamm-team/PyBaMM/pull/1058))
+-   Added averaging in secondary dimensions ([#1057](https://github.com/pybamm-team/PyBaMM/pull/1057))
+-   Added SEI reaction based on Yang et. al. 2017 and reduction in porosity ([#1009](https://github.com/pybamm-team/PyBaMM/issues/1009))
+
+## Optimizations
+
+-   Reformatted CasADi "safe" mode to deal with events better ([#1089](https://github.com/pybamm-team/PyBaMM/pull/1089))
+
+## Bug fixes
+
+-   Fixed a bug in `InterstitialDiffusionLimited` ([#1097](https://github.com/pybamm-team/PyBaMM/pull/1097))
+-   Fixed `Simulation` to keep different copies of the model so that parameters can be changed between simulations ([#1090](https://github.com/pybamm-team/PyBaMM/pull/1090))
+-   Fixed `model.new_copy()` to keep custom submodels ([#1090](https://github.com/pybamm-team/PyBaMM/pull/1090))
+-   2D processed variables can now be evaluated at the domain boundaries ([#1088](https://github.com/pybamm-team/PyBaMM/pull/1088))
+-   Update the default variable points to better capture behaviour in the solid particles in li-ion models ([#1081](https://github.com/pybamm-team/PyBaMM/pull/1081))
+-   Fix `QuickPlot` to display variables discretised by FEM (in y-z) properly ([#1078](https://github.com/pybamm-team/PyBaMM/pull/1078))
+-   Add length scales to `EffectiveResistance` models ([#1071](https://github.com/pybamm-team/PyBaMM/pull/1071))
+-   Allowed for pybamm functions exp, sin, cos, sqrt to be used in expression trees that
+    are converted to casadi format ([#1067](https://github.com/pybamm-team/PyBaMM/pull/1067))
+-   Fix a bug where variables that depend on y and z were transposed in `QuickPlot` ([#1055](https://github.com/pybamm-team/PyBaMM/pull/1055))
+
+## Breaking changes
+
+-   `Simulation.specs` and `Simulation.set_defaults` have been deprecated. Users should create a new `Simulation` object for each different case instead ([#1090](https://github.com/pybamm-team/PyBaMM/pull/1090))
+-  The solution times `t_eval` must now be provided to `Simulation.solve()` when not using an experiment or prescribing the current using drive cycle data ([#1086](https://github.com/pybamm-team/PyBaMM/pull/1086))
+
 # [v0.2.2](https://github.com/pybamm-team/PyBaMM/tree/v0.2.2) - 2020-06-01
 
 New SEI models, simplification of submodel structure, as well as optimisations and general bug fixes.

CONTRIBUTING.md

@@ -296,6 +296,25 @@ All example notebooks should be listed in [examples/README.md](https://github.co
 
 Where possible, notebooks are tested daily. A list of slow notebooks (which time-out and fail tests) is maintained in `.slow-books`, these notebooks will be excluded from daily testing.
 
+## Citations
+
+We aim to recognize all contributions by automatically generating citations to the relevant papers on which different parts of the code are built. 
+These will change depending on what models and solvers you use.
+Adding the command
+
+```python3
+pybamm.print_citations()
+```
+
+to the end of a script will print all citations that were used by that script. This will print bibtex information to the terminal; passing a filename to `print_citations` will print the bibtex information to the specified file instead.
+
+When you contribute code to PyBaMM, you can add your own papers that you would like to be cited if that code is used. First, add the bibtex for your paper to [CITATIONS.txt](pybamm/CITATIONS.txt). Then, add the line
+
+```python3
+pybamm.citations.register("your_paper_bibtex_identifier")
+```
+
+wherever code is called that uses that citation (for example, in functions or in the `__init__` method of a class such as a model or solver).
 
 ## Infrastructure
 

README.md

@@ -3,7 +3,7 @@
 [![Build](https://github.com/pybamm-team/PyBaMM/workflows/PyBaMM/badge.svg)](https://github.com/pybamm-team/PyBaMM/actions?query=workflow%3APyBaMM+branch%3Adevelop)
 [![readthedocs](https://readthedocs.org/projects/pybamm/badge/?version=latest)](https://pybamm.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/pybamm-team/PyBaMM/branch/master/graph/badge.svg)](https://codecov.io/gh/pybamm-team/PyBaMM)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pybamm-team/PyBaMM/master?filepath=examples%2Fnotebooks)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/master/)
 [![black_code_style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 PyBaMM (Python Battery Mathematical Modelling) solves physics-based electrochemical DAE models by using state-of-the-art automatic differentiation and numerical solvers. The Doyle-Fuller-Newman model can be solved in under 0.1 seconds, while the reduced-order Single Particle Model and Single Particle Model with electrolyte can be solved in just a few milliseconds. Additional physics can easily be included such as thermal effects, fast particle diffusion, 3D effects, and more. All models are implemented in a flexible manner, and a wide range of models and parameter sets (NCA, NMC, LiCoO2, ...) are available. There is also functionality to simulate any set of experimental instructions, such as CCCV or GITT, or specify drive cycles.
@@ -13,9 +13,9 @@ PyBaMM (Python Battery Mathematical Modelling) solves physics-based electrochemi
 The easiest way to use PyBaMM is to run a 1C constant-current discharge with a model of your choice with all the default settings:
 ```python3
 import pybamm
-model = pybamm.lithium_ion.DFN() # Doyle-Fuller-Newman model
+model = pybamm.lithium_ion.DFN()  # Doyle-Fuller-Newman model
 sim = pybamm.Simulation(model)
-sim.solve()
+sim.solve([0, 3600])  # solve for 1 hour
 sim.plot()
 ```
 or simulate an experiment such as CCCV:
@@ -42,7 +42,7 @@ For new users we recommend the [Getting Started](examples/notebooks/Getting%20St
 
 Further details can be found in a number of [detailed examples](examples/notebooks/README.md), hosted here on
 github. In addition, there is a [full API documentation](http://pybamm.readthedocs.io/),
-hosted on [Read The Docs](readthedocs.io). 
+hosted on [Read The Docs](readthedocs.io).
 Additional supporting material can be found
 [here](https://github.com/pybamm-team/pybamm-supporting-material/).
 
@@ -92,6 +92,7 @@ pybamm.print_citations()
 ```
 
 to the end of your script. This will print bibtex information to the terminal; passing a filename to `print_citations` will print the bibtex information to the specified file instead. A list of all citations can also be found in the [citations file](pybamm/CITATIONS.txt). In particular, PyBaMM relies heavily on [CasADi](https://web.casadi.org/publications/).
+See [CONTRIBUTING.md](CONTRIBUTING.md#citations) for information on how to add your own citations when you contribute.
 
 ## How can I contribute to PyBaMM?
 

docs/conf.py

@@ -28,7 +28,7 @@
 # The short X.Y version
 version = "0.2"
 # The full version, including alpha/beta/rc tags
-release = "0.2.2"
+release = "0.2.3"
 
 
 # -- General configuration ---------------------------------------------------

docs/install/GNU-linux.rst

@@ -46,12 +46,13 @@ User install
 ------------
 
 We recommend to install PyBaMM within a virtual environment, in order
-not to alter any distribution python files. To create a virtual
-environment ``env`` within your current directory type:
+not to alter any distribution python files. 
+First, make sure you are using python 3.6 or 3.7. 
+To create a virtual environment ``env`` within your current directory type:
 
 .. code:: bash
 
-   python3 -m venv env
+   virtualenv env
 
 You can then “activate” the environment using:
 

docs/source/models/submodels/external_circuit/experiment_events.rst

@@ -0,0 +1,5 @@
+Experiment events
+=================================
+
+.. autoclass:: pybamm.external_circuit.ExperimentEvents
+    :members:

docs/source/models/submodels/external_circuit/index.rst

@@ -13,3 +13,4 @@ variable to be constant.
 
   current_control_external_circuit
   function_control_external_circuit
+  experiment_events

docs/source/models/submodels/interface/sei.rst

@@ -20,4 +20,7 @@ SEI models
     :members:
 
 .. autoclass:: pybamm.sei.SolventDiffusionLimited
+    :members:
+
+.. autoclass:: pybamm.sei.EcReactionLimited
     :members:

examples/notebooks/Creating Models/1-an-ode-model.ipynb

@@ -29,6 +29,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "%pip install pybamm -q    # install PyBaMM if it is not installed\n",
     "import pybamm\n",
     "import numpy as np\n",
     "import matplotlib.pyplot as plt"
@@ -278,7 +279,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.9"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/notebooks/Creating Models/2-a-pde-model.ipynb

@@ -31,6 +31,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "%pip install pybamm -q    # install PyBaMM if it is not installed\n",
     "import pybamm\n",
     "import numpy as np\n",
     "import matplotlib.pyplot as plt"
@@ -308,7 +309,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.7"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/notebooks/Creating Models/3-negative-particle-problem.ipynb

@@ -54,6 +54,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "%pip install pybamm -q    # install PyBaMM if it is not installed\n",
     "import pybamm\n",
     "import numpy as np\n",
     "import matplotlib.pyplot as plt\n",
@@ -330,7 +331,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.7"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/notebooks/Creating Models/4-comparing-full-and-reduced-order-models.ipynb

@@ -49,6 +49,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "%pip install pybamm -q    # install PyBaMM if it is not installed\n",
     "import pybamm\n",
     "import numpy as np\n",
     "import matplotlib.pyplot as plt\n",
@@ -390,7 +391,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.7"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/notebooks/Creating Models/5-a-simple-SEI-model.ipynb

@@ -178,6 +178,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "%pip install pybamm -q    # install PyBaMM if it is not installed\n",
     "import pybamm\n",
     "import numpy as np\n",
     "import os\n",
@@ -669,7 +670,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.7"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/notebooks/Getting Started/Tutorial 1 - How to run a model.ipynb

@@ -22,16 +22,25 @@
    "cell_type": "code",
    "execution_count": 1,
    "metadata": {},
-   "outputs": [],
+   "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 now load the model that we wish to run. For this notebook, we choose the single particle model with electrolyte (SPMe):"
+    "We now load the model that we wish to run. For this notebook, we choose the Doyle-Fuller-Newman (DFN) model:"
    ]
   },
   {
@@ -40,7 +49,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "model = pybamm.lithium_ion.SPMe()"
+    "model = pybamm.lithium_ion.DFN()"
    ]
   },
   {
@@ -63,16 +72,27 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can then call 'solve' on our simulation object to solve the model (by default the the model is solved for a 1C constant current discharge):"
+    "We can then call 'solve' on our simulation object to solve the model, passing the window of time to solve for in seconds (here 1 hour):"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 4,
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<pybamm.solvers.solution.Solution at 0x7f09715ea9b0>"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
-    "sim.solve()"
+    "sim.solve([0, 3600])"
    ]
   },
   {
@@ -90,12 +110,12 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "089df7a7f1f24690b734df6cf83bd550",
+       "model_id": "06ae219fb8b94fa3aad3b8907a41ed27",
        "version_major": 2,
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(FloatSlider(value=0.0, description='t', max=0.9999999999999999, step=0.05), Output()), _…"
+       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
       ]
      },
      "metadata": {},
@@ -112,15 +132,8 @@
    "source": [
     "In this tutorial, we have solved a model with the inbuilt default settings. However, PyBaMM is designed to be highly customisable. Over the course of the getting started tutorials, we will see how various settings can be changed so that the model is appropriate for your situation. \n",
     "\n",
-    "In [Tutorial 2](./Tutorial%202%20-%20Setting%20Parameter%20Values.ipynb) we cover setting and changing parameter values."
+    "In [Tutorial 2](./Tutorial%202%20-%20Compare%20models.ipynb) we cover how to simulate and compare different models."
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {