Merge branch 'master' into issue-684-casadi-events

pybamm-team · Nov 1, 2019 · f4bcce7 · f4bcce7
2 parents 5a35536 + 44614d1
commit f4bcce7
Show file tree

Hide file tree

Showing 47 changed files with 1,237 additions and 70 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## Features
 
+-   Added Simulation class ([#693](https://github.com/pybamm-team/PyBaMM/pull/693))
 -   Add interface to CasADi solver ([#687](https://github.com/pybamm-team/PyBaMM/pull/687))
 -   Add option to use CasADi's Algorithmic Differentiation framework to calculate Jacobians ([#687](https://github.com/pybamm-team/PyBaMM/pull/687))
 -   Add method to evaluate parameters more easily ([#669](https://github.com/pybamm-team/PyBaMM/pull/669))
@@ -10,6 +11,7 @@
 -   Added interface (via pybind11) to sundials with the IDA KLU sparse linear solver ([#657](https://github.com/pybamm-team/PyBaMM/pull/657))
 -   Allow parameters to be set by material or by specifying a particular paper ([#647](https://github.com/pybamm-team/PyBaMM/pull/647))
 -   Set relative and absolute tolerances independently in solvers ([#645](https://github.com/pybamm-team/PyBaMM/pull/645))
+-   Add basic method to allow (a part of) the State Vector to be updated with results obtained from another solution or package ([#624](https://github.com/pybamm-team/PyBaMM/pull/624))
 -   Add some non-uniform meshes in 1D and 2D ([#617](https://github.com/pybamm-team/PyBaMM/pull/617))
 
 ## Optimizations
@@ -20,7 +22,7 @@
 ## Bug fixes
 
 -   Fix differentiation of functions that have more than one argument ([#687](https://github.com/pybamm-team/PyBaMM/pull/687))
--   Add warning if `ProcessedVariable` is called outisde its interpolation range ([#681](https://github.com/pybamm-team/PyBaMM/pull/681))
+-   Add warning if `ProcessedVariable` is called outside its interpolation range ([#681](https://github.com/pybamm-team/PyBaMM/pull/681))
 -   Improve the way `ProcessedVariable` objects are created in higher dimensions ([#581](https://github.com/pybamm-team/PyBaMM/pull/581))
 
 # [v0.1.0](https://github.com/pybamm-team/PyBaMM/tree/v0.1.0) - 2019-10-08

diff --git a/INSTALL-WINDOWS.md b/INSTALL-WINDOWS.md
@@ -21,7 +21,14 @@ typing
 $ sudo apt install git-core
 ```
 
-Now use git to clone the PyBaMM repository:
+For easier integration with WSL, we recommend that you install PyBaMM in your *Windows* 
+Documents folder, for example by first navigating to
+
+```bash
+$ cd /mnt/c/Users/USER_NAME/Documents
+```
+
+where USER_NAME is your username. Exact path to Windows documents may vary. Now use git to clone the PyBaMM repository:
 
 ```bash
 $ git clone https://github.com/pybamm-team/PyBaMM.git

diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,4 +1,4 @@
-Copyright (c) 2017-2018, University of Oxford (University of Oxford means the Chancellor, Masters and Scholars of the University of Oxford, having an administrative office at Wellington Square, Oxford OX1 2JD, UK).
+Copyright (c) 2017-2019, University of Oxford (University of Oxford means the Chancellor, Masters and Scholars of the University of Oxford, having an administrative office at Wellington Square, Oxford OX1 2JD, UK).
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

diff --git a/README.md b/README.md
@@ -11,7 +11,17 @@ Python Battery Mathematical Modelling solves continuum models for batteries, usi
 
 ## How do I use PyBaMM?
 
-PyBaMM comes with a number of [detailed examples](examples/notebooks/README.md), hosted here on
+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
+import pybamm
+model = pybamm.lithium_ion.DFN() # Doyle-Fuller-Newman model
+sim = pybamm.Simulation(model)
+sim.solve()
+sim.plot()
+```
+However, much greater customisation is available. It is possible to change the physics, parameter values, geometry, submesh type,  number of submesh points, methods for spatial discretisation and solver for integration (see DFN [script](examples/scripts/DFN.py) or [notebook](examples/notebooks/models/dfn.ipynb)).
+
+Further details can be found in a number of [detailed examples](examples/notebooks/README.md), hosted here on
 github. In addition, there is a [full API documentation](http://pybamm.readthedocs.io/),
 hosted on [Read The Docs](readthedocs.io). A set of slides giving an overview of PyBaMM
 can be found

diff --git a/docs/index.rst b/docs/index.rst
@@ -32,6 +32,7 @@ Contents
     source/solvers/index
     source/processed_variable
     source/util
+    source/simulation
 
 Examples
 ========

diff --git a/docs/source/models/submodels/current_collector/index.rst b/docs/source/models/submodels/current_collector/index.rst
@@ -11,5 +11,4 @@ Current Collector
   potential_pair
   quite_conductive_potential_pair
   single_particle_potential_pair
-
-
+  set_potential_single_particle
diff --git a/docs/source/models/submodels/current_collector/set_potential_single_particle.rst b/docs/source/models/submodels/current_collector/set_potential_single_particle.rst
@@ -0,0 +1,11 @@
+Set Potential Single Particle Models
+====================================
+
+.. autoclass:: pybamm.current_collector.BaseSetPotentialSingleParticle
+    :members:
+
+.. autoclass:: pybamm.current_collector.SetPotentialSingleParticle1plus1D
+    :members:
+
+.. autoclass:: pybamm.current_collector.SetPotentialSingleParticle2plus1D
+    :members:
diff --git a/docs/source/models/submodels/thermal/x_lumped/index.rst b/docs/source/models/submodels/thermal/x_lumped/index.rst
@@ -9,3 +9,4 @@ X-lumped
   x_lumped_0D_current_collector
   x_lumped_1D_current_collector
   x_lumped_2D_current_collector
+  x_lumped_1D_set_temperature
diff --git a/docs/source/models/submodels/thermal/x_lumped/x_lumped_1D_set_temperature.rst b/docs/source/models/submodels/thermal/x_lumped/x_lumped_1D_set_temperature.rst
@@ -0,0 +1,5 @@
+Set Temperature 1D current collector
+====================================
+
+.. autoclass:: pybamm.thermal.x_lumped.SetTemperature1D
+    :members:
diff --git a/docs/source/simulation.rst b/docs/source/simulation.rst
@@ -0,0 +1,5 @@
+Simulation
+==========
+
+.. autoclass:: pybamm.Simulation
+  :members:
diff --git a/examples/notebooks/models/compare-lithium-ion.ipynb b/examples/notebooks/models/compare-lithium-ion.ipynb
@@ -463,7 +463,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.8"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,

diff --git a/examples/notebooks/parameter-values.ipynb b/examples/notebooks/parameter-values.ipynb
@@ -482,7 +482,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.8"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,

diff --git a/examples/scripts/run_simulation.py b/examples/scripts/run_simulation.py
@@ -0,0 +1,7 @@
+import pybamm
+
+model = pybamm.lithium_ion.SPM()
+
+sim = pybamm.Simulation(model)
+sim.solve()
+sim.plot()
diff --git a/pybamm/__init__.py b/pybamm/__init__.py
@@ -268,7 +268,6 @@ def version(formatted=False):
 from .solvers.scipy_solver import ScipySolver
 from .solvers.idaklu_solver import IDAKLUSolver, have_idaklu
 
-
 #
 # Current profiles
 #
@@ -285,6 +284,8 @@ def version(formatted=False):
 from .processed_variable import post_process_variables, ProcessedVariable
 from .quick_plot import QuickPlot, ax_min, ax_max
 
+from .simulation import Simulation
+
 #
 # Remove any imported modules, so we don't expose them as part of pybamm
 #

diff --git a/pybamm/discretisations/discretisation.py b/pybamm/discretisations/discretisation.py
@@ -122,8 +122,8 @@ def process_model(self, model, inplace=True):
             # since they point to the same object
             model_disc = model
         else:
-            # create a blank model so that original model is unchanged
-            model_disc = pybamm.BaseModel()
+            # create a model of the same class as the original model
+            model_disc = model.__class__(model.options)
             model_disc.name = model.name
             model_disc.options = model.options
             model_disc.use_jacobian = model.use_jacobian

diff --git a/pybamm/models/full_battery_models/base_battery_model.py b/pybamm/models/full_battery_models/base_battery_model.py
@@ -37,15 +37,20 @@ class BaseBatteryModel(pybamm.BaseModel):
                 (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", "potential pair quite conductive" or "single particle
-                potential pair".
+                "potential pair", "potential pair quite conductive", "single particle
+                potential pair" or "set external potential". The submodel
+                "single particle potential pair" can only be used with lithium-ion
+                single particle models. The submodel "set external potential" can only
+                be used with the SPM.
             * "particle" : str, optional
                 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". Must be "isothermal" for
-                lead-acid models.
+                "x-full", "x-lumped", "xyz-lumped", "lumped" or "set external
+                temperature". Must be "isothermal" for lead-acid models. If the
+                option "set external temperature" is selected then "dimensionality"
+                must be 1.
             * "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
@@ -184,6 +189,7 @@ def options(self, extra_options):
             "potential pair",
             "potential pair quite conductive",
             "single particle potential pair",
+            "set external potential",
         ]:
             raise pybamm.OptionError(
                 "current collector model '{}' not recognised".format(
@@ -202,6 +208,7 @@ def options(self, extra_options):
             "x-lumped",
             "xyz-lumped",
             "lumped",
+            "set external temperature",
         ]:
             raise pybamm.OptionError(
                 "Unknown thermal model '{}'".format(options["thermal"])
@@ -230,6 +237,25 @@ def options(self, extra_options):
                 raise pybamm.OptionError(
                     "thermal effects not implemented for lead-acid models"
                 )
+        if options[
+            "current collector"
+        ] == "single particle potential pair" and not isinstance(
+            self, (pybamm.lithium_ion.SPM, pybamm.lithium_ion.SPMe)
+        ):
+            raise pybamm.OptionError(
+                "option {} only compatible with SPM or SPMe".format(
+                    options["current collector"]
+                )
+            )
+        if options["current collector"] == "set external potential" and not isinstance(
+            self, pybamm.lithium_ion.SPM
+        ):
+            raise pybamm.OptionError(
+                "option {} only compatible with SPM".format(
+                    options["current collector"]
+                )
+            )
+
         self._options = options
 
     def set_standard_output_variables(self):
@@ -555,6 +581,14 @@ def set_thermal_submodel(self):
                     self.param
                 )
 
+        elif self.options["thermal"] == "set external temperature":
+            if self.options["dimensionality"] == 1:
+                thermal_submodel = pybamm.thermal.x_lumped.SetTemperature1D(self.param)
+            elif self.options["dimensionality"] in [0, 2]:
+                raise NotImplementedError(
+                    """Set temperature model only implemented for 1D current
+                    collectors"""
+                )
         self.submodels["thermal"] = thermal_submodel
 
     def set_current_collector_submodel(self):
@@ -568,7 +602,20 @@ def set_current_collector_submodel(self):
                 submodel = pybamm.current_collector.PotentialPair2plus1D(self.param)
         elif self.options["current collector"] == "single particle potential pair":
             submodel = pybamm.current_collector.SingleParticlePotentialPair(self.param)
-
+        elif self.options["current collector"] == "set external potential":
+            if self.options["dimensionality"] == 1:
+                submodel = pybamm.current_collector.SetPotentialSingleParticle1plus1D(
+                    self.param
+                )
+            elif self.options["dimensionality"] == 2:
+                submodel = pybamm.current_collector.SetPotentialSingleParticle2plus1D(
+                    self.param
+                )
+            elif self.options["dimensionality"] == 0:
+                raise NotImplementedError(
+                    """Set potential model only implemented for 1D or 2D current
+                    collectors"""
+                )
         self.submodels["current collector"] = submodel
 
     def set_voltage_variables(self):

diff --git a/pybamm/models/full_battery_models/lithium_ion/spm.py b/pybamm/models/full_battery_models/lithium_ion/spm.py
@@ -87,8 +87,14 @@ def set_negative_electrode_submodel(self):
 
     def set_positive_electrode_submodel(self):
 
+        if self.options["current collector"] == "set external potential":
+            # Potentials are set by external model
+            set_positive_potential = False
+        else:
+            # Potential determined by 1D model
+            set_positive_potential = True
         self.submodels["positive electrode"] = pybamm.electrode.ohm.LeadingOrder(
-            self.param, "Positive"
+            self.param, "Positive", set_positive_potential=set_positive_potential
         )
 
     def set_electrolyte_submodel(self):

diff --git a/pybamm/models/submodels/current_collector/__init__.py b/pybamm/models/submodels/current_collector/__init__.py
@@ -18,3 +18,8 @@
     QuiteConductivePotentialPair1plus1D,
     QuiteConductivePotentialPair2plus1D,
 )
+from .set_potential_single_particle import (
+    BaseSetPotentialSingleParticle,
+    SetPotentialSingleParticle1plus1D,
+    SetPotentialSingleParticle2plus1D,
+)
diff --git a/pybamm/models/submodels/current_collector/base_current_collector.py b/pybamm/models/submodels/current_collector/base_current_collector.py
@@ -74,12 +74,15 @@ def _get_standard_potential_variables(self, phi_s_cn, phi_s_cp):
         pot_scale = self.param.potential_scale
         U_ref = self.param.U_p_ref - self.param.U_n_ref
 
-        # add more to this
+        # Local potential difference
+        V_cc = phi_s_cp - phi_s_cn
+
         variables = {
             "Positive current collector potential": phi_s_cp,
             "Positive current collector potential [V]": U_ref + phi_s_cp * pot_scale,
-            "Local potential difference": phi_s_cp - phi_s_cn,
-            "Local potential difference [V]": U_ref + (phi_s_cp - phi_s_cn) * pot_scale,
+            "Local current collector potential difference": V_cc,
+            "Local current collector potential difference [V]": U_ref
+            + V_cc * pot_scale,
         }
         variables.update(self._get_standard_negative_potential_variables(phi_s_cn))
 

diff --git a/pybamm/models/submodels/current_collector/composite_potential_pair.py b/pybamm/models/submodels/current_collector/composite_potential_pair.py
@@ -1,5 +1,5 @@
 #
-# Class for two-dimensional current collectors - composite models
+# Class for one- and two-dimensional composite potential pair current collector models
 #
 import pybamm
 from .potential_pair import (

diff --git a/pybamm/models/submodels/current_collector/potential_pair.py b/pybamm/models/submodels/current_collector/potential_pair.py
@@ -1,5 +1,5 @@
 #
-# Class for two-dimensional current collectors
+# Class for one- and two-dimensional potential pair current collector models
 #
 import pybamm
 from .base_current_collector import BaseModel
@@ -73,7 +73,7 @@ def set_initial_conditions(self, variables):
 
 
 class PotentialPair1plus1D(BasePotentialPair):
-    "Base class for a 1+1D potential pair model"
+    "Base class for a 1+1D potential pair model."
 
     def __init__(self, param):
         super().__init__(param)
@@ -154,7 +154,7 @@ def set_boundary_conditions(self, variables):
         # giving the zero Dirichlet condition on phi_s_cn. Elsewhere, the boundary
         # is insulated, giving no flux conditions on phi_s_cn. This is automatically
         # applied everywhere, apart from the region corresponding to the projection
-        # of the positive tab, so we need to explititly apply a zero-flux boundary
+        # of the positive tab, so we need to explitly apply a zero-flux boundary
         # condition on the region "positive tab" for phi_s_cn.
         # A current is drawn from the positive tab, giving the non-zero Neumann
         # boundary condition on phi_s_cp at "positive tab". Elsewhere, the boundary is

diff --git a/pybamm/models/submodels/current_collector/quite_conductive_potential_pair.py b/pybamm/models/submodels/current_collector/quite_conductive_potential_pair.py
@@ -1,5 +1,6 @@
 #
-# Class for two-dimensional current collectors
+# Class for one- and two-dimensional potential pair "quite conductive"
+# current collector models
 #
 import pybamm
 from .potential_pair import (