Issue 874 simplify thermal

CHANGELOG.md

@@ -13,11 +13,13 @@
 
 ## Bug fixes
 
+-   Reformatted thermal submodels ([#938](https://github.com/pybamm-team/PyBaMM/pull/938)
 -   Reformatted electrolyte submodels ([#927](https://github.com/pybamm-team/PyBaMM/pull/927))
 
 ## Breaking changes
 
 -   Removed some inputs like `T_inf`, `R_g` and activation energies to some of the standard function parameters. This is because each of those inputs is specific to a particular function (e.g. the reference temperature at which the function was measured). To change a property such as the activation energy, users should create a new function, specifying the relevant property as a `Parameter` or `InputParameter` ([#942](https://github.com/pybamm-team/PyBaMM/pull/942))
+-   The thermal option 'xyz-lumped' has been removed. The option 'thermal current collector' has also been removed ([#938](https://github.com/pybamm-team/PyBaMM/pull/938)
 
 # [v0.2.1](https://github.com/pybamm-team/PyBaMM/tree/v0.2.1) - 2020-03-31
 
@@ -46,7 +48,7 @@ New expression tree node types, models, parameter sets and solvers, as well as g
 
 ## Bug fixes
 
--   Filter out discontinuities that occur after solve times 
+-   Filter out discontinuities that occur after solve times
     ([#941](https://github.com/pybamm-team/PyBaMM/pull/945))
 -   Fixed tight layout for QuickPlot in jupyter notebooks ([#930](https://github.com/pybamm-team/PyBaMM/pull/930))
 -   Fixed bug raised if function returns a scalar ([#919](https://github.com/pybamm-team/PyBaMM/pull/919))

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

@@ -4,8 +4,8 @@ Thermal
 .. toctree::
   :maxdepth: 1
 
-  isothermal/index
-  x_full/index
-  x_lumped/index
-  xyz_lumped/index
   base_thermal
+  isothermal
+  lumped
+  x_full
+  pouch_cell/index

docs/source/models/submodels/thermal/lumped.rst

@@ -0,0 +1,5 @@
+Lumped Model
+============
+
+.. autoclass:: pybamm.thermal.lumped.Lumped
+    :members:

docs/source/models/submodels/thermal/pouch_cell/index.rst

@@ -0,0 +1,8 @@
+Pouch Cell
+==========
+
+.. toctree::
+  :maxdepth: 1
+
+  pouch_cell_1D_current_collectors
+  pouch_cell_2D_current_collectors

docs/source/models/submodels/thermal/pouch_cell/pouch_cell_1D_current_collectors.rst

@@ -0,0 +1,5 @@
+Thermal Model for "1+1D" Pouch Cell
+===================================
+
+.. autoclass:: pybamm.thermal.pouch_cell.CurrentCollector1D
+    :members:

docs/source/models/submodels/thermal/pouch_cell/pouch_cell_2D_current_collectors.rst

@@ -0,0 +1,5 @@
+Thermal Model for "2+1D" Pouch Cell
+===================================
+
+.. autoclass:: pybamm.thermal.pouch_cell.CurrentCollector2D
+    :members:

docs/source/models/submodels/thermal/x_full.rst

@@ -0,0 +1,5 @@
+One Dimensional Model
+=====================
+
+.. autoclass:: pybamm.thermal.x_full.OneDimensionalX
+    :members:

examples/scripts/DFN_ambient_temperature.py

@@ -9,7 +9,7 @@
 
 
 # load model
-options = {"thermal": "x-lumped"}
+options = {"thermal": "lumped"}
 model = pybamm.lithium_ion.DFN(options)
 
 # create geometry

examples/scripts/compare_lithium_ion.py

@@ -16,7 +16,7 @@
     pybamm.set_logging_level("INFO")
 
 # load models
-options = {"thermal": "x-lumped"}
+options = {"thermal": "lumped"}
 models = [
     pybamm.lithium_ion.SPM(options),
     pybamm.lithium_ion.SPMe(options),

examples/scripts/drive_cycle.py

@@ -6,7 +6,7 @@
 pybamm.set_logging_level("INFO")
 
 # load model and update parameters so the input current is the US06 drive cycle
-model = pybamm.lithium_ion.SPMe({"thermal": "x-lumped"})
+model = pybamm.lithium_ion.SPMe({"thermal": "lumped"})
 param = model.default_parameter_values
 param["Current function [A]"] = "[current data]US06"
 

pybamm/input/parameters/lithium-ion/anodes/graphite_Kim2011/README.md

@@ -4,4 +4,4 @@ Parameters for a graphite anode, from the paper
 
 > Kim, G. H., Smith, K., Lee, K. J., Santhanagopalan, S., & Pesaran, A. (2011). Multi-domain modeling of lithium-ion batteries encompassing multi-physics in varied length scales. Journal of The Electrochemical Society, 158(8), A955-A969.
 
-Note, only an effective cell volumetric heat capacity is provided in the paper. We therefore used the values for the density and specific heat capacity reported in the Marquis2019 parameter set in each region and multiplied each density by the ratio of the volumetric heat capacity provided in smith to the calculated value. This ensures that the values produce the same effective cell volumetric heat capacity. This works fine for x-lumped thermal models but not for x-full thermal models. We do the same for the planar effective thermal conductivity.
+Note, only an effective cell volumetric heat capacity is provided in the paper. We therefore used the values for the density and specific heat capacity reported in the Marquis2019 parameter set in each region and multiplied each density by the ratio of the volumetric heat capacity provided in smith to the calculated value. This ensures that the values produce the same effective cell volumetric heat capacity. This works fine for thermal models that are averaged over the x-direction but not for full (PDE in x direction) thermal models. We do the same for the planar effective thermal conductivity.

pybamm/input/parameters/lithium-ion/cathodes/nca_Kim2011/README.md

@@ -4,5 +4,4 @@ Parameters for an NCA cathode, from the paper
 
 > Kim, G. H., Smith, K., Lee, K. J., Santhanagopalan, S., & Pesaran, A. (2011). Multi-domain modeling of lithium-ion batteries encompassing multi-physics in varied length scales. Journal of The Electrochemical Society, 158(8), A955-A969.
 
-Note, only an effective cell volumetric heat capacity is provided in the paper. We therefore used the values for the density and specific heat capacity reported in the Marquis2019 parameter set in each region and multiplied each density by the ratio of the volumetric heat capacity provided in smith to the calculated value. This ensures that the values produce the same effective cell volumetric heat capacity. This works fine for x-lumped thermal models but not for x-full thermal models. We do the same for the planar effective thermal conductivity.
-
+Note, only an effective cell volumetric heat capacity is provided in the paper. We therefore used the values for the density and specific heat capacity reported in the Marquis2019 parameter set in each region and multiplied each density by the ratio of the volumetric heat capacity provided in smith to the calculated value. This ensures that the values produce the same effective cell volumetric heat capacity. This works fine for thermal models that are averaged over the x-direction but not for full (PDE in x direction) thermal models. We do the same for the planar effective thermal conductivity.

pybamm/input/parameters/lithium-ion/separators/separator_Kim2011/README.md

@@ -6,4 +6,4 @@ Parameters for the separator in the paper
 
 and references therein.
 
-Note, only an effective cell volumetric heat capacity is provided in the paper. We therefore used the values for the density and specific heat capacity reported in the Marquis2019 parameter set in each region and multiplied each density by the ratio of the volumetric heat capacity provided in smith to the calculated value. This ensures that the values produce the same effective cell volumetric heat capacity. This works fine for x-lumped thermal models but not for x-full thermal models. We do the same for the planar effective thermal conductivity.
+Note, only an effective cell volumetric heat capacity is provided in the paper. We therefore used the values for the density and specific heat capacity reported in the Marquis2019 parameter set in each region and multiplied each density by the ratio of the volumetric heat capacity provided in smith to the calculated value. This ensures that the values produce the same effective cell volumetric heat capacity. This works fine for thermal models that are averaged over the x-direction but not for full (PDE in x direction) thermal models. We do the same for the planar effective thermal conductivity.

pybamm/models/full_battery_models/base_battery_model.py

@@ -41,14 +41,8 @@ class BaseBatteryModel(pybamm.BaseModel):
                 Sets the submodel to use to describe behaviour within the particle.
                 Can be "Fickian diffusion" (default) or "fast diffusion".
             * "thermal" : str, optional
-                Sets the thermal model to use. Can be "isothermal" (default),
-                "x-full", "x-lumped", "xyz-lumped" or "lumped".
-            * "thermal current collector" : bool, optional
-                Whether to include thermal effects in the current collector in
-                one-dimensional models (default is False). Note that this option
-                only takes effect if "dimensionality" is 0. If "dimensionality"
-                is 1 or 2 current collector effects are always included. Must be 'False'
-                for lead-acid models.
+                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
@@ -147,7 +141,6 @@ def options(self, extra_options):
             "current collector": "uniform",
             "particle": "Fickian diffusion",
             "thermal": "isothermal",
-            "thermal current collector": False,
             "external submodels": [],
         }
         options = pybamm.FuzzyDict(default_options)
@@ -203,13 +196,7 @@ def options(self, extra_options):
                     options["dimensionality"]
                 )
             )
-        if options["thermal"] not in [
-            "isothermal",
-            "x-full",
-            "x-lumped",
-            "xyz-lumped",
-            "lumped",
-        ]:
+        if options["thermal"] not in ["isothermal", "lumped", "x-lumped", "x-full"]:
             raise pybamm.OptionError(
                 "Unknown thermal model '{}'".format(options["thermal"])
             )
@@ -231,12 +218,6 @@ def options(self, extra_options):
                     "effects if dimensionality is 0."
                 )
 
-            if options["thermal current collector"] is True:
-                raise pybamm.OptionError(
-                    "Thermal current collector effects are not implemented "
-                    "for lead-acid models."
-                )
-
         self._options = options
 
     def set_standard_output_variables(self):
@@ -453,36 +434,27 @@ def set_thermal_submodel(self):
         if self.options["thermal"] == "isothermal":
             thermal_submodel = pybamm.thermal.isothermal.Isothermal(self.param)
 
+        elif self.options["thermal"] == "lumped":
+            thermal_submodel = pybamm.thermal.Lumped(
+                self.param, self.options["dimensionality"]
+            )
+
         elif self.options["thermal"] == "x-lumped":
             if self.options["dimensionality"] == 0:
-                if self.options["thermal current collector"] is False:
-                    thermal_submodel = pybamm.thermal.x_lumped.NoCurrentCollector(
-                        self.param
-                    )
-                elif self.options["thermal current collector"] is True:
-                    thermal_submodel = pybamm.thermal.x_lumped.CurrentCollector0D(
-                        self.param
-                    )
+                # With 0D current collectors x-lumped is equivalent to lumped
+                thermal_submodel = pybamm.thermal.Lumped(self.param)
             elif self.options["dimensionality"] == 1:
-                thermal_submodel = pybamm.thermal.x_lumped.CurrentCollector1D(
+                thermal_submodel = pybamm.thermal.pouch_cell.CurrentCollector1D(
                     self.param
                 )
             elif self.options["dimensionality"] == 2:
-                thermal_submodel = pybamm.thermal.x_lumped.CurrentCollector2D(
+                thermal_submodel = pybamm.thermal.pouch_cell.CurrentCollector2D(
                     self.param
                 )
 
         elif self.options["thermal"] == "x-full":
             if self.options["dimensionality"] == 0:
-                if self.options["thermal current collector"] is False:
-                    thermal_submodel = pybamm.thermal.x_full.NoCurrentCollector(
-                        self.param
-                    )
-                elif self.options["thermal current collector"] is True:
-                    raise NotImplementedError(
-                        """X-full thermal submodels do
-                    not yet account for current collector"""
-                    )
+                thermal_submodel = pybamm.thermal.OneDimensionalX(self.param)
             elif self.options["dimensionality"] == 1:
                 raise NotImplementedError(
                     """X-full thermal submodels do not
@@ -494,43 +466,6 @@ def set_thermal_submodel(self):
                     not yet support 2D current collectors"""
                 )
 
-        elif self.options["thermal"] == "xyz-lumped":
-            if self.options["dimensionality"] == 0:
-                # note here we will just call the x_lumped model
-                # because it is equivalent
-                if self.options["thermal current collector"] is False:
-                    thermal_submodel = pybamm.thermal.x_lumped.NoCurrentCollector(
-                        self.param
-                    )
-                elif self.options["thermal current collector"] is True:
-                    thermal_submodel = pybamm.thermal.x_lumped.CurrentCollector0D(
-                        self.param
-                    )
-            elif self.options["dimensionality"] == 1:
-                thermal_submodel = pybamm.thermal.xyz_lumped.CurrentCollector1D(
-                    self.param
-                )
-            elif self.options["dimensionality"] == 2:
-                thermal_submodel = pybamm.thermal.xyz_lumped.CurrentCollector2D(
-                    self.param
-                )
-
-        elif self.options["thermal"] == "lumped":
-            # Easy option for returning a single Temperature regardless of choice of
-            # current collector model. Note: Always includes current collector effects
-            if self.options["dimensionality"] == 0:
-                thermal_submodel = pybamm.thermal.x_lumped.CurrentCollector0D(
-                    self.param
-                )
-            elif self.options["dimensionality"] == 1:
-                thermal_submodel = pybamm.thermal.xyz_lumped.CurrentCollector1D(
-                    self.param
-                )
-            elif self.options["dimensionality"] == 2:
-                thermal_submodel = pybamm.thermal.xyz_lumped.CurrentCollector2D(
-                    self.param
-                )
-
         self.submodels["thermal"] = thermal_submodel
 
     def set_current_collector_submodel(self):

pybamm/models/submodels/current_collector/potential_pair.py

@@ -7,12 +7,20 @@
 
 class BasePotentialPair(BaseModel):
     """A submodel for Ohm's law plus conservation of current in the current collectors.
+    For details on the potential pair formulation see [1]_ and [2]_.
 
     Parameters
     ----------
     param : parameter class
         The parameters to use for this submodel
 
+    References
+    ----------
+    .. [1] R Timms, SG Marquis, V Sulzer, CP Please and SJ Chapman. “Asymptotic
+           Reduction of a Lithium-ion Pouch Cell Model”. In preparation, 2020.
+    .. [2] SG Marquis, R Timms, V Sulzer, CP Please and SJ Chapman. “A Suite of
+           Reduced-Order Models of a Single-Layer Lithium-ion Pouch Cell”. In
+           preparation, 2020.
 
     **Extends:** :class:`pybamm.current_collector.BaseModel`
     """

pybamm/models/submodels/thermal/__init__.py

@@ -1,5 +1,5 @@
 from .base_thermal import BaseThermal
-from . import isothermal
-from . import x_full
-from . import x_lumped
-from . import xyz_lumped
+from .isothermal import Isothermal
+from .lumped import Lumped
+from .x_full import OneDimensionalX
+from . import pouch_cell