Merge branch 'develop' into issue-1230-simplify

pybamm-team · Nov 17, 2020 · 00eb9a0 · 00eb9a0
2 parents f4e75c6 + b892e5f
commit 00eb9a0
Show file tree

Hide file tree

Showing 10 changed files with 112 additions and 36 deletions.
diff --git a/docs/source/models/submodels/index.rst b/docs/source/models/submodels/index.rst
@@ -14,6 +14,7 @@ Submodels
     interface/index
     oxygen_diffusion/index
     particle/index
+    particle_cracking/index
     porosity/index
     thermal/index
     tortuosity/index
diff --git a/docs/source/models/submodels/particle_cracking/base_cracking.rst b/docs/source/models/submodels/particle_cracking/base_cracking.rst
@@ -0,0 +1,5 @@
+Base Particle Cracking Model
+============================
+
+.. autoclass:: pybamm.particle_cracking.BaseCracking
+    :members:
diff --git a/docs/source/models/submodels/particle_cracking/crack_propagation.rst b/docs/source/models/submodels/particle_cracking/crack_propagation.rst
@@ -0,0 +1,5 @@
+Crack Propagation Model
+=======================
+
+.. autoclass:: pybamm.particle_cracking.CrackPropagation
+    :members:
diff --git a/docs/source/models/submodels/particle_cracking/index.rst b/docs/source/models/submodels/particle_cracking/index.rst
@@ -0,0 +1,9 @@
+Particle Cracking
+=================
+
+.. toctree::
+  :maxdepth: 1
+
+  base_cracking
+  crack_propagation
+  no_cracking
diff --git a/docs/source/models/submodels/particle_cracking/no_cracking.rst b/docs/source/models/submodels/particle_cracking/no_cracking.rst
@@ -0,0 +1,5 @@
+No Cracking Model
+=================
+
+.. autoclass:: pybamm.particle_cracking.NoCracking
+    :members:
diff --git a/pybamm/CITATIONS.txt b/pybamm/CITATIONS.txt
@@ -24,7 +24,6 @@
 
 }
 
-
 @article{doyle1993modeling,
   title={Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell},
   author={Doyle, M and Fuller, TF and Newman, J},
@@ -249,4 +248,29 @@ primaryClass={physics.chem-ph},
   pages={A616},
   year={2013},
   publisher={IOP Publishing}
-}
+}
+
+@article{deshpande2012battery,
+  title={Battery cycle life prediction with coupled chemical degradation and fatigue mechanics},
+  author={Deshpande, Rutooj and Verbrugge, Mark and Cheng, Yang-Tse and Wang, John and Liu, Ping},
+  journal={Journal of the Electrochemical Society},
+  volume={159},
+  number={10},
+  pages={A1730},
+  year={2012},
+  publisher={IOP Publishing}
+}
+
+@article{Ai_2019,
+	doi = {10.1149/2.0122001jes},
+	url = {https://doi.org/10.1149%2F2.0122001jes},
+	year = 2019,
+	month = {oct},
+	publisher = {The Electrochemical Society},
+	volume = {167},
+	number = {1},
+	pages = {013512},
+	author = {Weilong Ai and Ludwig Kraft and Johannes Sturm and Andreas Jossen and Billy Wu},
+	title = {Electrochemical Thermal-Mechanical Modelling of Stress Inhomogeneity in Lithium-Ion Pouch Cells},
+	journal = {Journal of The Electrochemical Society},
+}
diff --git a/pybamm/models/full_battery_models/base_battery_model.py b/pybamm/models/full_battery_models/base_battery_model.py
@@ -24,26 +24,24 @@ class BaseBatteryModel(pybamm.BaseModel):
                 model with prescribed cell volume and cross-sectional area, and
                 (if thermal effects are included) solves a lumped thermal model
                 with prescribed surface area for cooling.
-            * "dimensionality" : int, optional
-                Sets the dimension of the current collector problem. Can be 0
-                (default), 1 or 2.
-            * "surface form" : bool or str, optional
-                Whether to use the surface formulation of the problem. Can be False
-                (default), "differential" or "algebraic".
             * "convection" : bool or str, optional
                 Whether to include the effects of convection in the model. Can be
                 False (default), "differential" or "algebraic". Must be 'False' for
                 lithium-ion models.
-            * "side reactions" : list, optional
-                Contains a list of any side reactions to include. Default is []. If this
-                list is not empty (i.e. side reactions are included in the model), then
-                "surface form" cannot be 'False'.
-            * "interfacial surface area" : str, optional
-                Sets the model for the interfacial surface area. Can be "constant"
-                (default) or "varying". Not currently implemented in any of the models.
             * "current collector" : str, optional
                 Sets the current collector model to use. Can be "uniform" (default),
                 "potential pair" or "potential pair quite conductive".
+            * "dimensionality" : int, optional
+                Sets the dimension of the current collector problem. Can be 0
+                (default), 1 or 2.
+            * "external submodels" : list
+                A list of the submodels that you would like to supply an external
+                variable for instead of solving in PyBaMM. The entries of the lists
+                are strings that correspond to the submodel names in the keys
+                of `self.submodels`.
+            * "interfacial surface area" : str, optional
+                Sets the model for the interfacial surface area. Can be "constant"
+                (default) or "varying". Not currently implemented in any of the models.
             * "particle" : str, optional
                 Sets the submodel to use to describe behaviour within the particle.
                 Can be "Fickian diffusion" (default), "uniform profile",
@@ -54,14 +52,14 @@ class BaseBatteryModel(pybamm.BaseModel):
                 (default) or "user". For the "user" option the surface area per
                 unit volume can be passed as a parameter, and is therefore not
                 necessarily consistent with the particle shape.
-            * "thermal" : str, optional
-                Sets the thermal model to use. Can be "isothermal" (default), "lumped",
-                "x-lumped", or "x-full".
-            * "external submodels" : list
-                A list of the submodels that you would like to supply an external
-                variable for instead of solving in PyBaMM. The entries of the lists
-                are strings that correspond to the submodel names in the keys
-                of `self.submodels`.
+            * "particle cracking" : str, optional
+                Sets the model to account for mechanical effects and particle
+                cracking. Can be None, "no cracking", "anode", "cathode" or "both".
+                All options other than None account for the effects of swelling
+                of electrode particles, cell thickness change, and stress-assisted
+                diffusion. The options "anode", "cathode" or "both" additionally account
+                for crack propagation in the anode, cathode or both electrodes,
+                respectively.
             * "sei" : str
                 Set the sei submodel to be used. Options are:
 
@@ -103,6 +101,16 @@ class BaseBatteryModel(pybamm.BaseModel):
                         * (\\phi_s - \\phi_e - U - R_{sei} * L_{sei} * \\frac{I}{aL})
             * "sei porosity change" : bool
                 Whether to include porosity change due to SEI formation (default False)
+            * "side reactions" : list, optional
+                Contains a list of any side reactions to include. Default is []. If this
+                list is not empty (i.e. side reactions are included in the model), then
+                "surface form" cannot be 'False'.
+            * "surface form" : bool or str, optional
+                Whether to use the surface formulation of the problem. Can be False
+                (default), "differential" or "algebraic".
+            * "thermal" : str, optional
+                Sets the thermal model to use. Can be "isothermal" (default), "lumped",
+                "x-lumped", or "x-full".
 
     **Extends:** :class:`pybamm.BaseModel`
     """

diff --git a/pybamm/models/submodels/particle_cracking/base_cracking.py b/pybamm/models/submodels/particle_cracking/base_cracking.py
@@ -5,25 +5,36 @@
 
 
 class BaseCracking(pybamm.BaseSubModel):
-    """Base class for particle cracking models.
+    """
+    Base class for particle cracking models. See [1]_ for mechanical model (thickness
+    change) and [2]_ for cracking model.
+
     Parameters
     ----------
     param : parameter class
         The parameters to use for this submodel
     domain : dict, optional
         Dictionary of either the electrode for "Positive" or "Nagative"
-    **Extends:** :class:`pybamm.BaseSubModel`
 
-    Reference
-    Ai, W., Kraft, L., Sturm, J., Jossen, A., & Wu, B. (2019). Electrochemical
-    Thermal-Mechanical Modelling of Stress Inhomogeneity in Lithium-Ion Pouch
-    Cells. Journal of The Electrochemical Society, 167(1), 013512.
+    References
+    ----------
+    .. [1] Ai, W., Kraft, L., Sturm, J., Jossen, A., & Wu, B. (2019). Electrochemical
+           Thermal-Mechanical Modelling of Stress Inhomogeneity in Lithium-Ion Pouch
+           Cells. Journal of The Electrochemical Society, 167(1), 013512.
+    .. [2] Deshpande, R., Verbrugge, M., Cheng, Y. T., Wang, J., & Liu, P. (2012).
+           Battery cycle life prediction with coupled chemical degradation and
+           fatigue mechanics. Journal of the Electrochemical Society, 159(10), A1730.
+
+    **Extends:** :class:`pybamm.BaseSubModel`
     """
 
     def __init__(self, param, domain):
         self.domain = domain
         super().__init__(param)
 
+        pybamm.citations.register("Ai_2019")
+        pybamm.citations.register("deshpande2012battery")
+
     def _get_standard_variables(self, l_cr):
         domain = self.domain.lower() + " particle"
         if self.domain == "Positive":

diff --git a/pybamm/models/submodels/particle_cracking/crack_propagation.py b/pybamm/models/submodels/particle_cracking/crack_propagation.py
@@ -1,10 +1,15 @@
+#
+# Class for cracking
+#
 import pybamm
 from .base_cracking import BaseCracking
 import numpy as np
 
 
 class CrackPropagation(BaseCracking):
-    """cracking behaviour in electrode particles.
+    """
+    Cracking behaviour in electrode particles, from [1]_.
+
     Parameters
     ----------
     param : parameter class
@@ -13,10 +18,13 @@ class CrackPropagation(BaseCracking):
         The domain of the model either 'Negative' or 'Positive'
     requiring the radius, average concantration, surface concantration
 
-    Ref for the crack model: Deshpande, R., Verbrugge, M., Cheng, Y. T.,
-    Wang, J., & Liu, P. (2012). Battery cycle life prediction with coupled
-    chemical degradation and fatigue mechanics. Journal of the Electrochemical
-    Society, 159(10), A1730.
+    References
+    ----------
+    .. [1] Deshpande, R., Verbrugge, M., Cheng, Y. T., Wang, J., & Liu, P. (2012).
+           Battery cycle life prediction with coupled chemical degradation and
+           fatigue mechanics. Journal of the Electrochemical Society, 159(10), A1730.
+
+    **Extends:** :class:`pybamm.particle_cracking.BaseCracking`
     """
 
     def __init__(self, param, domain):

diff --git a/pybamm/models/submodels/particle_cracking/no_cracking.py b/pybamm/models/submodels/particle_cracking/no_cracking.py
@@ -1,5 +1,5 @@
 #
-# Class for cracking
+# Class for no cracking
 #
 import pybamm
 from .base_cracking import BaseCracking
@@ -16,7 +16,7 @@ class NoCracking(BaseCracking):
     domain : str
         The domain of the model either 'Negative' or 'Positive'
 
-    **Extends:** :class:`pybamm.BaseSubModel`
+    **Extends:** :class:`pybamm.particle_cracking.BaseCracking`
     """
 
     def __init__(self, param, domain):