#1477 merge in develop

Author: martinjrobins

.all-contributorsrc

@@ -4,6 +4,7 @@
   ],
   "imageSize": 100,
   "commit": false,
+  "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg)](#-contributors)",
   "contributors": [
     {
       "login": "tinosulzer",
@@ -365,6 +366,27 @@
         "code",
         "test"
       ]
+    },
+    {
+      "login": "molel-gt",
+      "name": "Leshinka Molel",
+      "avatar_url": "https://avatars.githubusercontent.com/u/81125862?v=4",
+      "profile": "https://github.com/molel-gt",
+      "contributions": [
+        "code",
+        "ideas"
+      ]
+    },
+    {
+      "login": "tobykirk",
+      "name": "tobykirk",
+      "avatar_url": "https://avatars.githubusercontent.com/u/42966045?v=4",
+      "profile": "https://github.com/tobykirk",
+      "contributions": [
+        "ideas",
+        "code",
+        "test"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.github/release_checklist.md

@@ -1,4 +1,5 @@
-- Increment version number in `version`	
-- Increment version number in `docs/conf.py`	
-- Update CHANGELOG.md with a summary of the release	
-- Update (and pin) jax and jaxlib to latest version and fix any bugs that arise	
+- Increment version number in `version`
+- Increment version number in `docs/conf.py`
+- Increment version number in `CITATION.cff`
+- Update CHANGELOG.md with a summary of the release
+- Update (and pin) jax and jaxlib to latest version and fix any bugs that arise

.github/workflows/test_on_push.yml

@@ -45,6 +45,7 @@ jobs:
       if: matrix.os == 'ubuntu-latest'
       run: |
         sudo apt install gfortran gcc libopenblas-dev graphviz
+        sudo apt install texlive-full
     
     - name: Install MacOS system dependencies
       if: matrix.os == 'macos-latest'

.github/workflows/update_parameter_sets_doc.yml

@@ -5,8 +5,8 @@ on:
     branches:
     - develop
     paths:
-    - 'pybamm/parameters/parameter_sets.py'
-    - 'pybamm/parameters/CITATIONS.txt'
+    - pybamm/parameters/parameter_sets.py
+    - pybamm/CITATIONS.txt
 
 jobs:
   build:

CHANGELOG.md

@@ -3,6 +3,13 @@
 ## Features
 
 -   `pybamm.base_solver.solve` function can take a list of input parameters to calculate the sensitivities of the solution with respect to. Alternatively, it can be set  to `True` to calculate the sensitivities for all input parameters ([#1552](https://github.com/pybamm-team/PyBaMM/pull/1552))
+-   Addes UDDS and WLTC drive cycles  ([#1601](https://github.com/pybamm-team/PyBaMM/pull/1601))
+-   Added capability for `quaternary` domains (in addition to `primary`, `secondary` and `tertiary`), increasing the maximum number of domains that a `Symbol` can have to 4. ([#1580](https://github.com/pybamm-team/PyBaMM/pull/1580))
+-   Tabs can now be placed at the bottom of the cell in 1+1D thermal models ([#1581](https://github.com/pybamm-team/PyBaMM/pull/1581)) 
+-   Added temperature dependence on electrode electronic conductivity ([#1570](https://github.com/pybamm-team/PyBaMM/pull/1570))
+-   Added a new lithium-ion model `MPM` or Many-Particle Model, with a distribution of particle sizes in each electrode. ([#1529](https://github.com/pybamm-team/PyBaMM/pull/1529))
+-   Added 2 new submodels for lithium transport in a size distribution of electrode particles: Fickian diffusion (`FickianSingleSizeDistribution`) and uniform concentration profile (`FastSingleSizeDistribution`). ([#1529](https://github.com/pybamm-team/PyBaMM/pull/1529))
+-   Added a "particle size" domain to the default lithium-ion geometry, including plotting capabilities (`QuickPlot`) and processing of variables (`ProcessedVariable`). ([#1529](https://github.com/pybamm-team/PyBaMM/pull/1529))
 -   Added fitted expressions for OCPs for the Chen2020 parameter set ([#1526](https://github.com/pybamm-team/PyBaMM/pull/1497))
 -   Added `initial_soc` argument to `Simualtion.solve` for specifying the initial SOC when solving a model ([#1512](https://github.com/pybamm-team/PyBaMM/pull/1512))
 -   Added `print_name` to some symbols ([#1495](https://github.com/pybamm-team/PyBaMM/pull/1495), [#1497](https://github.com/pybamm-team/PyBaMM/pull/1497))
@@ -28,12 +35,15 @@
 
 ## Bug fixes
 
+-   Fixed a bug where the order of the indexing for the entries of variables discretised using FEM was incorrect ([#1556](https://github.com/pybamm-team/PyBaMM/pull/1556))
+-   Fix broken module import for spyder when running a script twice ([#1555](https://github.com/pybamm-team/PyBaMM/pull/1555))
 -   Fixed ElectrodeSOH model for multi-dimensional simulations ([#1548](https://github.com/pybamm-team/PyBaMM/pull/1548))
 -   Removed the overly-restrictive check "each variable in the algebraic eqn keys must appear in the eqn" ([#1510](https://github.com/pybamm-team/PyBaMM/pull/1510))
 -   Made parameters importable through pybamm ([#1475](https://github.com/pybamm-team/PyBaMM/pull/1475))
 
 ## Breaking changes
 
+-   The `Yang2017` parameter set has been removed as the complete parameter set is not publicly available in the literature ([#1577](https://github.com/pybamm-team/PyBaMM/pull/1577))
 -   Changed how options are specified for the "loss of active material" and "particle cracking" submodels. "loss of active material" can now be one of "none", "stress-driven", or "reaction-driven", or a 2-tuple for different options in negative and positive electrode. Similarly "particle cracking" (now called "particle mechanics") can now be "none", "swelling only", "swelling and cracking", or a 2-tuple ([#1490](https://github.com/pybamm-team/PyBaMM/pull/1490))
 -   Changed the variable in the full diffusion model from "Electrolyte concentration" to "Porosity times concentration" ([#1476](https://github.com/pybamm-team/PyBaMM/pull/1476))
 -   Renamed `lithium-ion` folder to `lithium_ion` and `lead-acid` folder to `lead_acid` in parameters ([#1464](https://github.com/pybamm-team/PyBaMM/pull/1464))

CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.1.0
+message: "If you use PyBaMM, please cite it as below."
+authors: 
+- family-names: Sulzer
+  given-names: Valentin
+  orcid: "https://orcid.org/0000-0002-8687-327X"
+- family-names: Marquis
+  given-names: Scott G.
+  orcid: "https://orcid.org/0000-0002-6895-990X"
+- family-names: Timms
+  given-names: Robert
+  orcid: "https://orcid.org/0000-0002-8858-4818"
+- family-names: Robinson
+  given-names: Martin
+  orcid: "https://orcid.org/0000-0002-1572-6782"
+- family-names: Chapman
+  given-names: S. Jon
+  orcid: "https://orcid.org/0000-0003-3347-6024"
+journal: "Journal of Open Research Software"
+date-released: 2021-06-08
+doi: 10.5334/jors.309
+keywords: 
+  - "battery modelling"
+  - "expression tree"
+  - "python"
+  - "symbolic differentiation"
+version: 0.4.0
+repository-code: "https://github.com/pybamm-team/PyBaMM"
+title: "Python Battery Mathematical Modelling (PyBaMM)"

README.md

@@ -1,19 +1,26 @@
 ![PyBaMM_logo](https://user-images.githubusercontent.com/20817509/107091287-8ad46a80-67cf-11eb-86f5-7ebef7c72a1e.png)
 
-# PyBaMM
+#
+<div align="center">
 
 [![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/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)
+[![DOI](https://zenodo.org/badge/DOI/10.5334/jors.309.svg)](https://doi.org/10.5334/jors.309)
+[![release](https://img.shields.io/github/v/release/pybamm-team/PyBaMM?color=yellow)](https://github.com/pybamm-team/PyBaMM/releases)
+[![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 -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-31-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-33-orange.svg)](#-contributors)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
+</div>
+
+# PyBaMM
+
 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.
 
-## How do I use PyBaMM?
+## 💻 Using PyBaMM
 
 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
@@ -51,9 +58,12 @@ hosted on [Read The Docs](https://readthedocs.org/).
 Additional supporting material can be found
 [here](https://github.com/pybamm-team/pybamm-supporting-material/).
 
-For further examples, see the list of repositories that use PyBaMM [here](https://github.com/pybamm-team/pybamm-example-results)
+Note that the examples on the default `develop` branch are tested on the latest `develop` commit. This may sometimes cause errors when running the examples on the pybamm pip package, which is synced to the `main` branch. You can switch to the `main` branch on github to see the version of the examples that is compatible with the latest pip release.
+
+<!-- For further examples, see the list of repositories that use PyBaMM [here](https://github.com/pybamm-team/pybamm-example-results). -->
+
+## 🚀 Installing PyBaMM
 
-## How can I install PyBaMM?
 PyBaMM is available on GNU/Linux, MacOS and Windows.
 We strongly recommend to install PyBaMM within a python virtual environment, in order not to alter any distribution python files.
 For instructions on how to create a virtual environment for PyBaMM, see [the documentation](https://pybamm.readthedocs.io/en/latest/install/GNU-linux.html#user-install).
@@ -72,21 +82,25 @@ conda install -c conda-forge pybamm
 ### Optional solvers
 On GNU/Linux and MacOS, an optional [scikits.odes](https://scikits-odes.readthedocs.io/en/latest/)-based solver is available, see [the documentation](https://pybamm.readthedocs.io/en/latest/install/GNU-linux.html#scikits-odes-label).
 
-## Citing PyBaMM
+## 📖 Citing PyBaMM
 
 If you use PyBaMM in your work, please cite our paper
 
-> Sulzer, V., Marquis, S. G., Timms, R., Robinson, M., & Chapman, S. J. (2020). Python Battery Mathematical Modelling (PyBaMM). _ECSarXiv. February, 7_.
+> Sulzer, V., Marquis, S. G., Timms, R., Robinson, M., & Chapman, S. J. (2021). Python Battery Mathematical Modelling (PyBaMM). _Journal of Open Research Software, 9(1)_.
 
 You can use the bibtex
 
 ```
-@article{sulzer2020python,
-  title={Python Battery Mathematical Modelling (PyBaMM)},
-  author={Sulzer, Valentin and Marquis, Scott G and Timms, Robert and Robinson, Martin and Chapman, S Jon},
-  journal={ECSarXiv. February},
-  volume={7},
-  year={2020}
+@article{Sulzer2021,
+  title = {{Python Battery Mathematical Modelling (PyBaMM)}},
+  author = {Sulzer, Valentin and Marquis, Scott G. and Timms, Robert and Robinson, Martin and Chapman, S. Jon},
+  doi = {10.5334/jors.309},
+  journal = {Journal of Open Research Software},
+  publisher = {Software Sustainability Institute},
+  volume = {9},
+  number = {1},
+  pages = {14},
+  year = {2021}
 }
 ```
 
@@ -99,15 +113,19 @@ 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](https://github.com/pybamm-team/PyBaMM/blob/develop/pybamm/CITATIONS.txt). In particular, PyBaMM relies heavily on [CasADi](https://web.casadi.org/publications/).
 See [CONTRIBUTING.md](https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md#citations) for information on how to add your own citations when you contribute.
 
-## How can I contribute to PyBaMM?
+## 🛠️ Contributing to PyBaMM
 
 If you'd like to help us develop PyBaMM by adding new methods, writing documentation, or fixing embarrassing bugs, please have a look at these [guidelines](https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md) first.
 
-## Licensing
+## 📫 Get in touch
+
+For any questions, comments, suggestions or bug reports, please see the [contact page](https://www.pybamm.org/contact).
+
+## 📃 License
 
 PyBaMM is fully open source. For more information about its license, see [LICENSE](https://github.com/pybamm-team/PyBaMM/blob/develop/LICENSE.txt).
 
-## Contributors ✨
+## ✨ Contributors
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
 
@@ -155,6 +173,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="https://github.com/asinghgaba"><img src="https://avatars.githubusercontent.com/u/77078706?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Amarjit Singh Gaba</b></sub></a><br /><a href="https://github.com/pybamm-team/PyBaMM/commits?author=asinghgaba" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/KennethNwanoro"><img src="https://avatars.githubusercontent.com/u/78538806?v=4?s=100" width="100px;" alt=""/><br /><sub><b>KennethNwanoro</b></sub></a><br /><a href="https://github.com/pybamm-team/PyBaMM/commits?author=KennethNwanoro" title="Code">💻</a> <a href="https://github.com/pybamm-team/PyBaMM/commits?author=KennethNwanoro" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://github.com/alibh95"><img src="https://avatars.githubusercontent.com/u/65511923?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ali Hussain Umar Bhatti</b></sub></a><br /><a href="https://github.com/pybamm-team/PyBaMM/commits?author=alibh95" title="Code">💻</a> <a href="https://github.com/pybamm-team/PyBaMM/commits?author=alibh95" title="Tests">⚠️</a></td>
+    <td align="center"><a href="https://github.com/molel-gt"><img src="https://avatars.githubusercontent.com/u/81125862?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Leshinka Molel</b></sub></a><br /><a href="https://github.com/pybamm-team/PyBaMM/commits?author=molel-gt" title="Code">💻</a> <a href="#ideas-molel-gt" title="Ideas, Planning, & Feedback">🤔</a></td>
+    <td align="center"><a href="https://github.com/tobykirk"><img src="https://avatars.githubusercontent.com/u/42966045?v=4?s=100" width="100px;" alt=""/><br /><sub><b>tobykirk</b></sub></a><br /><a href="#ideas-tobykirk" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/pybamm-team/PyBaMM/commits?author=tobykirk" title="Code">💻</a> <a href="https://github.com/pybamm-team/PyBaMM/commits?author=tobykirk" title="Tests">⚠️</a></td>
   </tr>
 </table>
 

docs/conf.py

@@ -206,9 +206,9 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/", None),
-    "sphinx": ("http://www.sphinx-doc.org/en/stable/", None),
-    "numpy": ("http://docs.scipy.org/doc/numpy/", None),
-    "scipy": ("http://docs.scipy.org/doc/scipy/reference", None),
-    "matplotlib": ("http://matplotlib.org", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    # "scipy": ("http://docs.scipy.org/doc/scipy/reference", None),
+    "matplotlib": ("https://matplotlib.org", None),
 }

docs/source/expression_tree/unary_operator.rst

@@ -81,6 +81,8 @@ Unary Operators
 
 .. autofunction:: pybamm.r_average
 
+.. autofunction:: pybamm.size_average
+
 .. autofunction:: pybamm.z_average
 
 .. autofunction:: pybamm.yz_average

docs/source/models/lithium_ion/index.rst

@@ -6,6 +6,7 @@ Lithium-ion Models
   base_lithium_ion_model
   spm
   spme
+  mpm
   dfn
   newman_tobias
   yang2017

docs/source/models/lithium_ion/mpm.rst

@@ -0,0 +1,5 @@
+Many Particle Model (MPM)
+===========================
+
+.. autoclass:: pybamm.lithium_ion.MPM
+    :members:

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

@@ -8,4 +8,7 @@ Function control external circuit
     :members:
 
 .. autoclass:: pybamm.external_circuit.PowerFunctionControl
+    :members:
+
+.. autoclass:: pybamm.external_circuit.CCCVFunctionControl
     :members:

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

@@ -9,3 +9,4 @@ Particle
   fickian_many_particles
   polynomial_single_particle
   polynomial_many_particles
+  size_distribution/index

docs/source/models/submodels/particle/size_distribution/base_distribution.rst

@@ -0,0 +1,6 @@
+Particle Size Distribution Base Model
+=====================================
+
+.. autoclass:: pybamm.particle.BaseSizeDistribution
+    :members:
+

docs/source/models/submodels/particle/size_distribution/fast_single_distribution.rst

@@ -0,0 +1,5 @@
+Fast Single Size Distribution
+=============================
+
+.. autoclass:: pybamm.particle.FastSingleSizeDistribution
+    :members:

docs/source/models/submodels/particle/size_distribution/fickian_single_distribution.rst

@@ -0,0 +1,6 @@
+Fickian Single Size Distribution
+================================
+
+.. autoclass:: pybamm.particle.FickianSingleSizeDistribution
+    :members:
+

docs/source/models/submodels/particle/size_distribution/index.rst

@@ -0,0 +1,9 @@
+Particle Size Distribution
+==========================
+
+.. toctree::
+  :maxdepth: 1
+
+  base_distribution
+  fickian_single_distribution
+  fast_single_distribution