Merge branch 'develop' into issue-1082-events

.github/workflows/build_wheels.yml

@@ -2,7 +2,7 @@ name: Build
 
 on:
   push:
-    branches: master
+    branches: main
   workflow_dispatch:
     inputs:
       target:

CHANGELOG.md

@@ -1,4 +1,12 @@
-# [Unreleased](https://github.com/pybamm-team/PyBaMM)
+# [v0.4.0](https://github.com/pybamm-team/PyBaMM/tree/v0.4.0) - 2021-03-27
+
+This release introduces:
+- several new models, including reversible and irreversible plating submodels, submodels for loss of active material, Yang et al.'s (2017) coupled SEI/plating/pore clogging model, and the Newman-Tobias model
+- internal optimizations for solving models, particularly for simulating experiments, with more accurate event detection and more efficient numerical methods and post-processing
+- parallel solutions of a model with different inputs
+- a cleaner installation process for Mac when installing from PyPI, no longer requiring a Homebrew installation of Sundials
+- improved plotting functionality, including adding a new 'voltage component' plot
+- several other new features, optimizations, and bug fixes, summarized below
 
 ## Features
 -   Added `NewmanTobias` li-ion battery model ([#1423](https://github.com/pybamm-team/PyBaMM/pull/1423))
@@ -59,7 +67,7 @@
 -   Operations such as `1*x` and `0+x` now directly return `x`. This can be bypassed by explicitly creating the binary operators, e.g. `pybamm.Multiplication(1, x)` ([#1252](https://github.com/pybamm-team/PyBaMM/pull/1252))
 -   `'Cell capacity [A.h]'` has been renamed to `'Nominal cell capacity [A.h]'`. `'Cell capacity [A.h]'` will be deprecated in the next release. ([#1352](https://github.com/pybamm-team/PyBaMM/pull/1352))
 
-# [v0.3.0](https://github.com/pybamm-team/PyBaMM) - 2020-11-22
+# [v0.3.0](https://github.com/pybamm-team/PyBaMM/tree/v0.3.0) - 2020-12-01
 
 This release introduces a new aging model for particle swelling and cracking, a new reduced-order model (TSPMe), and a parameter set for A123 LFP cells. Additionally, there have been several backend optimizations to speed up model creation and solving, and other minor features and bug fixes.
 
@@ -135,7 +143,7 @@ This release adds new operators for more complex models, some basic sensitivity
 
 # [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.
+This release enables the use of [Google Colab](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/main/) for running example notebooks, and adds some small new features and bug fixes.
 
 ## Features
 
@@ -364,7 +372,7 @@ This release introduces many new features and optimizations. All models can now
 -   Removed `Outer` and `Kron` nodes as no longer used ([#777](https://github.com/pybamm-team/PyBaMM/pull/777))
 -   Moved `results` to separate repositories ([#761](https://github.com/pybamm-team/PyBaMM/pull/761))
 -   The parameters "Bruggeman coefficient" must now be specified separately as "Bruggeman coefficient (electrolyte)" and "Bruggeman coefficient (electrode)"
--   The current classes (`GetConstantCurrent`, `GetUserCurrent` and `GetUserData`) have now been removed. Please refer to the [`change-input-current` notebook](https://github.com/pybamm-team/PyBaMM/blob/master/examples/notebooks/change-input-current.ipynb) for information on how to specify an input current
+-   The current classes (`GetConstantCurrent`, `GetUserCurrent` and `GetUserData`) have now been removed. Please refer to the [`change-input-current` notebook](https://github.com/pybamm-team/PyBaMM/blob/main/examples/notebooks/change-input-current.ipynb) for information on how to specify an input current
 -   Parameter functions must now use pybamm functions instead of numpy functions (e.g. `pybamm.exp` instead of `numpy.exp`), as these are then used to construct the expression tree directly. Generally, pybamm syntax follows numpy syntax; please get in touch if a function you need is missing.
 -   The current must now be updated by changing "Current function [A]" or "C-rate" instead of "Typical current [A]"
 

CONTRIBUTING.md

@@ -39,7 +39,7 @@ You now have everything you need to start making changes!
 10. PyBaMM has online documentation at http://pybamm.readthedocs.io/. To make sure any new methods or classes you added show up there, please read the [documentation](#documentation) section.
 11. If you added a major new feature, perhaps it should be showcased in an [example notebook](#example-notebooks).
 12. When you feel your code is finished, or at least warrants serious discussion, run the [pre-commit checks](#pre-commit-checks) and then create a [pull request](https://help.github.com/articles/about-pull-requests/) (PR) on [PyBaMM's GitHub page](https://github.com/pybamm-team/PyBaMM).
-13. Once a PR has been created, it will be reviewed by any member of the community. Changes might be suggested which you can make by simply adding new commits to the branch. When everything's finished, someone with the right GitHub permissions will merge your changes into PyBaMM master repository.
+13. Once a PR has been created, it will be reviewed by any member of the community. Changes might be suggested which you can make by simply adding new commits to the branch. When everything's finished, someone with the right GitHub permissions will merge your changes into PyBaMM main repository.
 
 Finally, if you really, really, _really_ love developing PyBaMM, have a look at the current [project infrastructure](#infrastructure).
 

README.md

@@ -4,7 +4,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)
+[![codecov](https://codecov.io/gh/pybamm-team/PyBaMM/branch/main/graph/badge.svg)](https://codecov.io/gh/pybamm-team/PyBaMM)
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop/)
 [![black_code_style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

docs/conf.py

@@ -26,9 +26,9 @@
 author = "The PyBaMM Team"
 
 # The short X.Y version
-version = "0.3"
+version = "0.4"
 # The full version, including alpha/beta/rc tags
-release = "0.3.0-beta"
+release = "0.4.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -66,8 +66,8 @@
 # source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 
-# The master toctree document.
-master_doc = "index"
+# The main toctree document.
+main_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -155,15 +155,15 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "PyBaMM.tex", "PyBaMM Documentation", "Valentin Sulzer", "manual")
+    (main_doc, "PyBaMM.tex", "PyBaMM Documentation", "Valentin Sulzer", "manual")
 ]
 
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "pybamm", "PyBaMM Documentation", [author], 1)]
+man_pages = [(main_doc, "pybamm", "PyBaMM Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -173,7 +173,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (
-        master_doc,
+        main_doc,
         "PyBaMM",
         "PyBaMM Documentation",
         author,

docs/index.rst

@@ -85,7 +85,7 @@ Examples
 ========
 
 Detailed examples can be viewed on the
-`GitHub examples page <https://github.com/pybamm-team/PyBaMM/tree/master/examples/notebooks>`_,
+`GitHub examples page <https://github.com/pybamm-team/PyBaMM/tree/main/examples/notebooks>`_,
 and run locally using ``jupyter notebook``, or online through
 `Google Colab <https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop/>`_.
 

docs/source/models/index.rst

@@ -5,7 +5,7 @@ Below is an overview of all the battery models included in PyBaMM.
 Each of the pre-built models contains a reference to the paper in which it is derived.
 
 The models can be customised using the `options` dictionary defined in the :class:`pybamm.BaseBatteryModel` (which also provides information on which options and models are compatible)
-Visit our `examples page <https://github.com/pybamm-team/PyBaMM/tree/master/examples/notebooks/models>`_
+Visit our `examples page <https://github.com/pybamm-team/PyBaMM/tree/main/examples/notebooks/models>`_
 to see how these models can be solved, and compared, using PyBaMM.
 
 .. toctree::

docs/tutorials/add-model.rst

@@ -8,7 +8,7 @@ Adding a Model
 As with any contribution to PyBaMM, please follow the workflow in CONTRIBUTING.md_.
 In particular, start by creating an issue to discuss what you want to do - this is a good way to avoid wasted coding hours!
 
-We aim here to provide an overview of how a new model is entered into PyBaMM in a form which can be eventually merged into the master branch of the PyBaMM project. However, we recommend that you first read through the notebook: `create a model <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Creating%20Models>`_, which goes step-by-step through the procedure for creating a model. Once you understand that procedure, you can then formalise your model following the outline provided here.
+We aim here to provide an overview of how a new model is entered into PyBaMM in a form which can be eventually merged into the main branch of the PyBaMM project. However, we recommend that you first read through the notebook: `create a model <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Creating%20Models>`_, which goes step-by-step through the procedure for creating a model. Once you understand that procedure, you can then formalise your model following the outline provided here.
 
 The role of models
 ------------------

examples/notebooks/Getting Started/Tutorial 4 - Setting parameter values.ipynb

@@ -96,7 +96,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "More details on each subset can be found [here](https://github.com/pybamm-team/PyBaMM/tree/master/pybamm/input/parameters).\n",
+    "More details on each subset can be found [here](https://github.com/pybamm-team/PyBaMM/tree/main/pybamm/input/parameters).\n",
     "\n",
     "Now we can pass `'chemistry'` into `ParameterValues` to create the dictionary of parameter values"
    ]

examples/scripts/cycling_ageing_yang.py

@@ -1,16 +1,15 @@
 import pybamm as pb
 
-pb.set_logging_level("INFO")
-options = {"SEI": "ec reaction limited", "SEI porosity change": "true"}
-param = pb.ParameterValues(chemistry=pb.parameter_sets.Ramadass2004)
-model = pb.lithium_ion.DFN(options)
+pb.set_logging_level("NOTICE")
+model = pb.lithium_ion.Yang2017()
+
 experiment = pb.Experiment(
     [
         (
             "Charge at 1 C until 4.2 V",
             "Hold at 4.2 V until C/10",
             "Rest for 5 minutes",
-            "Discharge at 2 C until 2.8 V",
+            "Discharge at 1 C until 2.8 V",
             "Rest for 5 minutes",
         )
     ]
@@ -28,22 +27,22 @@
             "Rest for 30 minutes",
             "Discharge at 1 C until 2.8 V",
         ),
-        (
-            "Charge at 1 C until 4.2 V",
-            "Hold at 4.2 V until C/20",
-            "Rest for 30 minutes",
-            "Discharge at 2 C until 2.8 V",
-        ),
-        (
-            "Charge at 1 C until 4.2 V",
-            "Hold at 4.2 V until C/20",
-            "Rest for 30 minutes",
-            "Discharge at 3 C until 2.8 V",
-        ),
+        # (
+        #     "Charge at 1 C until 4.2 V",
+        #     "Hold at 4.2 V until C/20",
+        #     "Rest for 30 minutes",
+        #     "Discharge at 2 C until 2.8 V",
+        # ),
+        # (
+        #     "Charge at 1 C until 4.2 V",
+        #     "Hold at 4.2 V until C/20",
+        #     "Rest for 30 minutes",
+        #     "Discharge at 3 C until 2.8 V",
+        # ),
     ]
 )
-sim = pb.Simulation(model, experiment=experiment, parameter_values=param)
-sim.solve(solver=pb.CasadiSolver(mode="safe", dt_max=120))
+sim = pb.Simulation(model, experiment=experiment)
+sim.solve(solver=pb.CasadiSolver(mode="safe"))
 sim.plot(
     [
         "Current [A]",

examples/scripts/print_parameters.py

@@ -0,0 +1,9 @@
+#
+# Example for printing the (dimensional and dimensionless) parameters of a parameter set
+#
+import pybamm
+
+parameters = pybamm.LithiumIonParameters()
+parameter_values = pybamm.ParameterValues(chemistry=pybamm.parameter_sets.Yang2017)
+output_file = "lithium_ion_parameters.txt"
+parameter_values.print_parameters(parameters, output_file)

pybamm/input/parameters/lead-acid/separators/agm_Sulzer2019/parameters.csv

@@ -3,7 +3,6 @@ Name [units],Value,Reference,Notes
 ,,,
 Maximum porosity of separator,0.92,,
 Separator Bruggeman coefficient (electrolyte),1.5,,
-Separator Bruggeman coefficient (electrode),1.5,,
 Separator density [kg.m-3],1680, Bulk density from Gigova 2006,
 Separator specific heat capacity [J.kg-1.K-1],700, Electronics Cooling (fiberglass),
 Separator thermal conductivity [W.m-1.K-1],0.04, University Physics Sears et al. 1999 (fiberglass),

pybamm/input/parameters/lithium-ion/cells/Yang2017/parameters.csv

@@ -29,6 +29,6 @@ Negative current collector thermal conductivity [W.m-1.K-1],401,,,,
 Positive current collector thermal conductivity [W.m-1.K-1],237,,,,
 ,,,,,
 # Electrical,,,,,
-Nominal cell capacity [A.h],12.4,Yang2017,,,
-Typical current [A],12.4,,1C current,,
-Current function [A],12.4,default current function,,,
+Nominal cell capacity [A.h],2.4,Yang2017,,,
+Typical current [A],2.4,,1C current,,
+Current function [A],2.4,default current function,,,

pybamm/input/parameters/lithium-ion/lithium_platings/okane2020_Li_plating/parameters.csv

@@ -3,6 +3,7 @@ Name [units],Value,Reference,Notes
 ,,,
 # Lithium plating parameters,,,
 Lithium metal partial molar volume [m3.mol-1],1.30E-05,Yang2017,
+Lithium plating kinetic rate constant [m.s-1],1E-10,,
 Exchange-current density for plating [A.m-2],[function]plating_exchange_current_density_OKane2020,,
 Exchange-current density for stripping [A.m-2],[function]stripping_exchange_current_density_OKane2020,,
 Initial plated lithium concentration [mol.m-3],0.00E+00,,

pybamm/input/parameters/lithium-ion/lithium_platings/okane2020_Li_plating/plating_exchange_current_density_OKane2020.py

@@ -1,4 +1,4 @@
-from pybamm import constants
+from pybamm import constants, Parameter
 
 
 def plating_exchange_current_density_OKane2020(c_e, c_Li, T):
@@ -24,6 +24,6 @@ def plating_exchange_current_density_OKane2020(c_e, c_Li, T):
         Exchange-current density [A.m-2]
     """
 
-    k_plating = 1e-10
+    k_plating = Parameter("Lithium plating kinetic rate constant [m.s-1]")
 
     return constants.F * k_plating * c_e

pybamm/input/parameters/lithium-ion/lithium_platings/okane2020_Li_plating/stripping_exchange_current_density_OKane2020.py

@@ -1,4 +1,4 @@
-from pybamm import constants
+from pybamm import constants, Parameter
 
 
 def stripping_exchange_current_density_OKane2020(c_e, c_Li, T):
@@ -30,6 +30,6 @@ def stripping_exchange_current_density_OKane2020(c_e, c_Li, T):
         Exchange-current density [A.m-2]
     """
 
-    k_plating = 1e-10
+    k_plating = Parameter("Lithium plating kinetic rate constant [m.s-1]")
 
     return constants.F * k_plating * c_Li

pybamm/input/parameters/lithium-ion/lithium_platings/yang2017_Li_plating/parameters.csv

@@ -2,6 +2,6 @@ Name [units],Value,Reference,Notes
 ,,,
 ,,,
 # Lithium plating parameters,,,
-Lithium metal partial molar volume [m3.mol-1],1.30E-05,Yang2017,
+Lithium metal partial molar volume [m3.mol-1],1.30E-05,Yang2017,6.94e-3/534
 Exchange-current density for plating [A.m-2],0.001,,
 Initial plated lithium concentration [mol.m-3],0.00E+00,,

pybamm/input/parameters/lithium-ion/seis/yang2017_sei/README.md

@@ -1,11 +1,7 @@
 # SEI parameters
 
-Some example parameters for SEI growth from the papers:
+Some example parameters for SEI growth from the paper:
 
-> Ramadass, P., Haran, B., Gomadam, P. M., White, R., & Popov, B. N. (2004). Development of first principles capacity fade model for Li-ion cells. Journal of the Electrochemical Society, 151(2), A196-A203.
-> Ploehn, H. J., Ramadass, P., & White, R. E. (2004). Solvent diffusion model for aging of lithium-ion battery cells. Journal of The Electrochemical Society, 151(3), A456-A462.
-> Single, F., Latz, A., & Horstmann, B. (2018). Identifying the mechanism of continued growth of the solid–electrolyte interphase. ChemSusChem, 11(12), 1950-1955.
-> Safari, M., Morcrette, M., Teyssot, A., & Delacour, C. (2009). Multimodal Physics-Based Aging Model for Life Prediction of Li-Ion Batteries. Journal of The Electrochemical Society, 156(3), 
 > Yang, X., Leng, Y., Zhang, G., Ge, S., Wang, C. (2017). Modeling of lithium plating induced aging of lithium-ion batteries: Transition from linear to nonlinear aging. Journal of Power Sources, 360, 28-40.
 
-Note: this parameter set does not claim to be representative of the true parameter values. Instead these are parameter values that were used to fit SEI models to observed experimental data in the referenced papers.
+and references therein

pybamm/input/parameters/lithium-ion/seis/yang2017_sei/parameters.csv

@@ -2,22 +2,12 @@ Name [units],Value,Reference,Notes
 # Empty rows and rows starting with ‘#’ will be ignored,,,
 ,,,
 # SEI properties,,,
-Inner SEI reaction proportion,0.5,,
-Inner SEI partial molar volume [m3.mol-1],9.47E-05, Safari paper,
-Outer SEI partial molar volume [m3.mol-1],9.47E-05, Safari paper,
-SEI reaction exchange current density [A.m-2],1.50E-07, Guess,
-SEI resistivity [Ohm.m],5.00E+06, Safari paper,
-Outer SEI solvent diffusivity [m2.s-1],2.50E-22, Single paper,
-Bulk solvent concentration [mol.m-3],2.64E+03, Ploehn paper,
-Ratio of inner and outer SEI exchange current densities,1, Assume same,
-Inner SEI open-circuit potential [V],0.1,,
-Outer SEI open-circuit potential [V],0.8,,
-Inner SEI electron conductivity [S.m-1],8.95E-14, Single paper,
-Inner SEI lithium interstitial diffusivity [m2.s-1],1.00E-20, Guess,
-Lithium interstitial reference concentration [mol.m-3],15, Single paper,
-Initial inner SEI thickness [m],2.50E-09, 2.5E-9 1/2 of initial thickness in Safari paper,
-Initial outer SEI thickness [m],2.50E-09, 1/2 of initial thickness in Safari paper,
-EC initial concentration in electrolyte [mol.m-3],4.54E+03, Safari paper,
+Inner SEI partial molar volume [m3.mol-1],9.586E-05, Safari paper, 0.162/1690
+Outer SEI partial molar volume [m3.mol-1],9.586E-05, Safari paper, 0.162/1690
+SEI resistivity [Ohm.m],2.00E+06, Safari paper (1/5e-6),
+Initial inner SEI thickness [m],0,,
+Initial outer SEI thickness [m],5E-09,,
+EC initial concentration in electrolyte [mol.m-3],4.541E+03, Safari paper,
 EC diffusivity [m2.s-1],2.00E-18, adjusted parameter in Yang paper,
 SEI kinetic rate constant [m.s-1],1.00E-12, adjusted parameter in Yang paper,
 SEI open-circuit potential [V],0.4, Safari paper,

pybamm/input/parameters/lithium-ion/separators/separator_Ai2020/parameters.csv

@@ -3,7 +3,6 @@ Name [units],Value,Reference,Notes
 ,,,
 Separator porosity,0.5,Ai 2020,
 Separator Bruggeman coefficient (electrolyte),1.5,Ai 2020,theoretical
-Separator Bruggeman coefficient (electrode),0,default,
 Separator density [kg.m-3],2470,default,cell parameter
 Separator specific heat capacity [J.kg-1.K-1],1080.2,default,cell parameter
 Separator thermal conductivity [W.m-1.K-1],0.334,default,cell parameter 

pybamm/input/parameters/lithium-ion/separators/separator_Chen2020/parameters.csv

@@ -3,7 +3,6 @@ Name [units],Value,Reference,Notes
 ,,,
 Separator porosity,0.47,Chen 2020,
 Separator Bruggeman coefficient (electrolyte),1.5,Chen 2020,theoretical
-Separator Bruggeman coefficient (electrode),1.5,default,
 Separator density [kg.m-3],397,default,
 Separator specific heat capacity [J.kg-1.K-1],700,default,
 Separator thermal conductivity [W.m-1.K-1],0.16,default,

pybamm/input/parameters/lithium-ion/separators/separator_Ecker2015/parameters.csv

@@ -3,7 +3,6 @@ Name [units],Value,Reference,Notes
 ,,,
 Separator porosity,0.508,,
 Separator Bruggeman coefficient (electrolyte),1.9804586773134942, Solve for permeability factor B=0.304=eps^b,
-Separator Bruggeman coefficient (electrode),0,No Bruggeman correction to solid conductivity,
 Separator density [kg.m-3],397,default,
 Separator specific heat capacity [J.kg-1.K-1],700,default,
 Separator thermal conductivity [W.m-1.K-1],0.16,default,

pybamm/input/parameters/lithium-ion/separators/separator_Kim2011/parameters.csv

@@ -3,7 +3,6 @@ Name [units],Value,Reference,Notes
 ,,,
 Separator porosity,0.4,,
 Separator Bruggeman coefficient (electrolyte),2,,
-Separator Bruggeman coefficient (electrode),2,,
 Separator density [kg.m-3],511.86798,397 * 1.28934,
 Separator specific heat capacity [J.kg-1.K-1],700,,
 Separator thermal conductivity [W.m-1.K-1],0.10672, 0.16 * 0.667,