From 361d0f3bb5f7d39f50b3163ac99bb0351e86b936 Mon Sep 17 00:00:00 2001 From: Robert Timms Date: Tue, 17 Nov 2020 10:06:21 +0000 Subject: [PATCH 1/2] #1249 docs --- docs/source/models/submodels/index.rst | 1 + .../particle_cracking/base_cracking.rst | 5 ++ .../particle_cracking/crack_propagation.rst | 5 ++ .../submodels/particle_cracking/index.rst | 9 ++++ .../particle_cracking/no_cracking.rst | 5 ++ pybamm/CITATIONS.txt | 29 ++++++++++- .../full_battery_models/base_battery_model.py | 50 +++++++++++-------- .../particle_cracking/base_cracking.py | 23 ++++++--- .../particle_cracking/crack_propagation.py | 18 +++++-- .../particle_cracking/no_cracking.py | 4 +- 10 files changed, 113 insertions(+), 36 deletions(-) create mode 100644 docs/source/models/submodels/particle_cracking/base_cracking.rst create mode 100644 docs/source/models/submodels/particle_cracking/crack_propagation.rst create mode 100644 docs/source/models/submodels/particle_cracking/index.rst create mode 100644 docs/source/models/submodels/particle_cracking/no_cracking.rst diff --git a/docs/source/models/submodels/index.rst b/docs/source/models/submodels/index.rst index a72bfa243f..c6624b516c 100644 --- 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 new file mode 100644 index 0000000000..9cdc3343d6 --- /dev/null +++ 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 new file mode 100644 index 0000000000..82b395df88 --- /dev/null +++ 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 new file mode 100644 index 0000000000..872921c628 --- /dev/null +++ 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 new file mode 100644 index 0000000000..171713a975 --- /dev/null +++ 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 index 89b0a2f420..f05b3bde18 100644 --- 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,30 @@ primaryClass={physics.chem-ph}, pages={A616}, year={2013}, publisher={IOP Publishing} -} \ No newline at end of file +} + +@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}, + abstract = {Whilst extensive research has been conducted on the effects of temperature in lithium-ion batteries, mechanical effects have not received as much attention despite their importance. In this work, the stress response in electrode particles is investigated through a pseudo-2D model with mechanically coupled diffusion physics. This model can predict the voltage, temperature and thickness change for a lithium cobalt oxide-graphite pouch cell agreeing well with experimental results. Simulations show that the stress level is overestimated by up to 50% using the standard pseudo-2D model (without stress enhanced diffusion), and stresses can accelerate the diffusion in solid phases and increase the discharge cell capacity by 5.4%. The evolution of stresses inside electrode particles and the stress inhomogeneity through the battery electrode have been illustrated. The stress level is determined by the gradients of lithium concentration, and large stresses are generated at the electrode-separator interface when high C-rates are applied, e.g. fast charging. The results can explain the experimental results of particle fragmentation close to the separator and provide novel insights to understand the local aging behaviors of battery cells and to inform improved battery control algorithms for longer lifetimes.} +} diff --git a/pybamm/models/full_battery_models/base_battery_model.py b/pybamm/models/full_battery_models/base_battery_model.py index da31e85431..cd6df85048 100644 --- 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 index 79d741208c..f4882556b5 100644 --- 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 index cba7b9ba90..fd96c7cfda 100644 --- 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 index a4b5db1071..8eecfd9cb1 100644 --- 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): From 5cf83dc985efd82f15b9925ba6582bbb59cd4521 Mon Sep 17 00:00:00 2001 From: Robert Timms Date: Tue, 17 Nov 2020 11:14:26 +0000 Subject: [PATCH 2/2] #1249 remove abstract --- pybamm/CITATIONS.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/pybamm/CITATIONS.txt b/pybamm/CITATIONS.txt index f05b3bde18..452d75f9d6 100644 --- a/pybamm/CITATIONS.txt +++ b/pybamm/CITATIONS.txt @@ -273,5 +273,4 @@ primaryClass={physics.chem-ph}, 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}, - abstract = {Whilst extensive research has been conducted on the effects of temperature in lithium-ion batteries, mechanical effects have not received as much attention despite their importance. In this work, the stress response in electrode particles is investigated through a pseudo-2D model with mechanically coupled diffusion physics. This model can predict the voltage, temperature and thickness change for a lithium cobalt oxide-graphite pouch cell agreeing well with experimental results. Simulations show that the stress level is overestimated by up to 50% using the standard pseudo-2D model (without stress enhanced diffusion), and stresses can accelerate the diffusion in solid phases and increase the discharge cell capacity by 5.4%. The evolution of stresses inside electrode particles and the stress inhomogeneity through the battery electrode have been illustrated. The stress level is determined by the gradients of lithium concentration, and large stresses are generated at the electrode-separator interface when high C-rates are applied, e.g. fast charging. The results can explain the experimental results of particle fragmentation close to the separator and provide novel insights to understand the local aging behaviors of battery cells and to inform improved battery control algorithms for longer lifetimes.} }