#546 merge master

.gitignore

@@ -4,6 +4,7 @@
 *.png
 /local/
 *.DS_Store
+*.mat
 
 # don't ignore important .txt files
 !requirements*

.requirements-docs.txt

@@ -8,3 +8,4 @@ scikit-fem>=0.2.0
 casadi>=3.5.0
 guzzle-sphinx-theme
 sphinx>=1.5
+python-Levenshtein>=0.12.0

.travis.yml

@@ -79,7 +79,8 @@ matrix:
           env:
             - PYBAMM_UNIT=true
             - PYBAMM_SCIKITS_ODES=true
-        # Unit testing on Python3.7 on Ubuntu without scikit odes
+            - PYBAMM_KLU=true
+        # Unit and example testing on Python3.7 on Ubuntu without optional dependencies
         - python: "3.7"
           addons:
             apt:
@@ -95,6 +96,7 @@ matrix:
                 - libsuitesparse-dev
           env:
             - PYBAMM_UNIT=true
+            - PYBAMM_EXAMPLES=true
           if: type != cron
         # Cover, docs and style checking, latest Python version only
         - python: "3.7"

CHANGELOG.md

@@ -2,7 +2,18 @@
 
 ## Features
 
+-   Added fuzzy string matching for parameters and variables ([#796](https://github.com/pybamm-team/PyBaMM/pull/796))
+-   Changed ParameterValues to raise an error when a parameter that wasn't previously defined is updated ([#796](https://github.com/pybamm-team/PyBaMM/pull/796))
+-   Added some basic models (BasicSPM and BasicDFN) in order to clearly demonstrate the PyBaMM model structure for battery models ([#795](https://github.com/pybamm-team/PyBaMM/pull/795))
+-   Added the harmonic mean to the Finite Volume method, which is now used when computing fluxes ([#783](https://github.com/pybamm-team/PyBaMM/pull/783))
+-   Refactored `Solution` to make it a dictionary that contains all of the solution variables. This automatically creates `ProcessedVariable` objects when required, so that the solution can be obtained much more easily. ([#781](https://github.com/pybamm-team/PyBaMM/pull/781))
+-   Added notebook to explain broadcasts ([#776](https://github.com/pybamm-team/PyBaMM/pull/776))
+-   Added a step to discretisation that automatically compute the inverse of the mass matrix of the differential part of the problem so that the underlying DAEs can be provided in semi-explicit form, as required by the CasADi solver ([#769](https://github.com/pybamm-team/PyBaMM/pull/769))
+-   Added the gradient operation for the Finite Element Method ([#767](https://github.com/pybamm-team/PyBaMM/pull/767))
 -   Added `InputParameter` node for quickly changing parameter values ([#752](https://github.com/pybamm-team/PyBaMM/pull/752))
+-   Added submodels for operating modes other than current-controlled ([#751](https://github.com/pybamm-team/PyBaMM/pull/751))
+-   Changed finite volume discretisation to use exact values provided by Neumann boundary conditions when computing the gradient instead of adding ghost nodes([#748](https://github.com/pybamm-team/PyBaMM/pull/748))
+-   Added optional R(x) distribution in particle models ([#745](https://github.com/pybamm-team/PyBaMM/pull/745))
 -   Generalized importing of external variables ([#728](https://github.com/pybamm-team/PyBaMM/pull/728))
 -   Separated active and inactive material volume fractions ([#726](https://github.com/pybamm-team/PyBaMM/pull/726))
 -   Added submodels for tortuosity ([#726](https://github.com/pybamm-team/PyBaMM/pull/726))
@@ -25,13 +36,20 @@
 
 ## Optimizations
 
+-   Simplified solver interface ([#800](https://github.com/pybamm-team/PyBaMM/pull/800))
+-   Added caching for shape evaluation, used during discretisation ([#780](https://github.com/pybamm-team/PyBaMM/pull/780))
 -   Added an option to skip model checks during discretisation, which could be slow for large models ([#739](https://github.com/pybamm-team/PyBaMM/pull/739))
 -   Use CasADi's automatic differentation algorithms by default when solving a model ([#714](https://github.com/pybamm-team/PyBaMM/pull/714))
 -   Avoid re-checking size when making a copy of an `Index` object ([#656](https://github.com/pybamm-team/PyBaMM/pull/656))
 -   Avoid recalculating `_evaluation_array` when making a copy of a `StateVector` object ([#653](https://github.com/pybamm-team/PyBaMM/pull/653))
 
 ## Bug fixes
 
+-   Fixed examples to run with basic pip installation ([#800](https://github.com/pybamm-team/PyBaMM/pull/800))
+-   Added events for CasADi solver when stepping ([#800](https://github.com/pybamm-team/PyBaMM/pull/800))
+-   Improved implementation of broadcasts ([#776](https://github.com/pybamm-team/PyBaMM/pull/776))
+-   Fixed a bug which meant that the Ohmic heating in the current collectors was incorrect if using the Finite Element Method ([#767](https://github.com/pybamm-team/PyBaMM/pull/767))
+-   Improved automatic broadcasting ([#747](https://github.com/pybamm-team/PyBaMM/pull/747))
 -   Fixed bug with wrong temperature in initial conditions ([#737](https://github.com/pybamm-team/PyBaMM/pull/737))
 -   Improved flexibility of parameter values so that parameters (such as diffusivity or current) can be set as functions or scalars ([#723](https://github.com/pybamm-team/PyBaMM/pull/723))
 -   Fixed a bug where boundary conditions were sometimes handled incorrectly in 1+1D models ([#713](https://github.com/pybamm-team/PyBaMM/pull/713))
@@ -44,10 +62,12 @@
 
 ## Breaking changes
 
+-   Removed `Outer` and `Kron` nodes as no longer used ([#777](https://github.com/pybamm-team/PyBaMM/pull/777))
 -   Moved `results` to separate repositories ([#761](https://github.com/pybamm-team/PyBaMM/pull/761))
 -   The parameters "Bruggeman coefficient" must now be specified separately as "Bruggeman coefficient (electrolyte)" and "Bruggeman coefficient (electrode)"
 -   The current classes (`GetConstantCurrent`, `GetUserCurrent` and `GetUserData`) have now been removed. Please refer to the [`change-input-current` notebook](https://github.com/pybamm-team/PyBaMM/blob/master/examples/notebooks/change-input-current.ipynb) for information on how to specify an input current
 -   Parameter functions must now use pybamm functions instead of numpy functions (e.g. `pybamm.exp` instead of `numpy.exp`), as these are then used to construct the expression tree directly. Generally, pybamm syntax follows numpy syntax; please get in touch if a function you need is missing.
+-   The current must now be updated by changing "Current function [A]" or "C-rate" instead of "Typical current [A]"
 
 
 # [v0.1.0](https://github.com/pybamm-team/PyBaMM/tree/v0.1.0) - 2019-10-08

INSTALL-LINUX.md

@@ -94,25 +94,25 @@ Before installing scikits.odes, you need to have installed:
 - Fortran compiler (e.g. gfortran)
 - BLAS/LAPACK install (OpenBLAS is recommended by the scikits.odes developers)
 - CMake (for building Sundials)
-- Sundials 4.1.0
+- Sundials 5.0.0
 
 You can install these on Ubuntu or Debian using apt-get:
 
 ```bash
 sudo apt-get install python3-dev gfortran gcc cmake libopenblas-dev
 ```
 
-To install Sundials 4.1.0, on the command-line type:
+To install Sundials 5.0.0, on the command-line type:
 
 ```bash
 INSTALL_DIR=`pwd`/sundials
-wget https://computation.llnl.gov/projects/sundials/download/sundials-4.1.0.tar.gz
-tar -xvf sundials-4.1.0.tar.gz
-mkdir build-sundials-4.1.0
-cd build-sundials-4.1.0/
-cmake -DLAPACK_ENABLE=ON -DSUNDIALS_INDEX_TYPE=int32_t -DBUILD_ARKODE:BOOL=OFF -DEXAMPLES_ENABLE:BOOL=OFF -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR ../sundials-4.1.0/
+wget https://computation.llnl.gov/projects/sundials/download/sundials-5.0.0.tar.gz
+tar -xvf sundials-5.0.0.tar.gz
+mkdir build-sundials-5.0.0
+cd build-sundials-5.0.0/
+cmake -DLAPACK_ENABLE=ON -DSUNDIALS_INDEX_TYPE=int32_t -DBUILD_ARKODE:BOOL=OFF -DEXAMPLES_ENABLE:BOOL=OFF -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR ../sundials-5.0.0/
 make install
-rm -r ../sundials-4.1.0
+rm -r ../sundials-5.0.0
 ```
 
 Then install [scikits.odes](https://github.com/bmcage/odes), letting it know the sundials install location:

LICENSE.txt

@@ -1,4 +1,4 @@
-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).
+Copyright (c) 2018-2020, 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

docs/source/expression_tree/binary_operator.rst

@@ -25,15 +25,7 @@ Binary Operators
 .. autoclass:: pybamm.Inner
   :members:
 
-.. autoclass:: pybamm.Outer
-  :members:
-
-.. autoclass:: pybamm.Kron
-  :members:
-
 .. autoclass:: pybamm.Heaviside
   :members:
 
-.. autofunction:: pybamm.outer
-
 .. autofunction:: pybamm.source

docs/source/expression_tree/broadcasts.rst

@@ -9,3 +9,6 @@ Broadcasting Operators
 
 .. autoclass:: pybamm.PrimaryBroadcast
   :members:
+
+.. autoclass:: pybamm.SecondaryBroadcast
+  :members:

docs/source/expression_tree/variable.rst

@@ -3,3 +3,6 @@ Variable
 
 .. autoclass:: pybamm.Variable
   :members:
+
+.. autoclass:: pybamm.ExternalVariable
+  :members:

docs/source/models/lithium_ion/dfn.rst

@@ -3,3 +3,6 @@ Doyle-Fuller-Newman (DFN)
 
 .. autoclass:: pybamm.lithium_ion.DFN
     :members:
+
+.. autoclass:: pybamm.lithium_ion.BasicDFN
+    :members:

docs/source/models/lithium_ion/spm.rst

@@ -3,3 +3,6 @@ Single Particle Model (SPM)
 
 .. autoclass:: pybamm.lithium_ion.SPM
     :members:
+
+.. autoclass:: pybamm.lithium_ion.BasicSPM
+    :members:

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

@@ -10,5 +10,4 @@ Current Collector
   homogeneous_current_collector
   potential_pair
   quite_conductive_potential_pair
-  single_particle_potential_pair
   set_potential_single_particle

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

@@ -0,0 +1,6 @@
+Current control external circuit
+================================
+
+.. autoclass:: pybamm.external_circuit.CurrentControl
+    :members:
+

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

@@ -0,0 +1,11 @@
+Function control external circuit
+=================================
+
+.. autoclass:: pybamm.external_circuit.FunctionControl
+    :members:
+
+.. autoclass:: pybamm.external_circuit.VoltageFunctionControl
+    :members:
+
+.. autoclass:: pybamm.external_circuit.PowerFunctionControl
+    :members:

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

@@ -0,0 +1,15 @@
+External circuit
+================
+
+Models to enforce different boundary conditions (as imposed by an imaginary external
+circuit) such as constant current, constant voltage, constant power, or any other
+relationship between the current and voltage. "Current control" enforces these directly
+through boundary conditions, while "Function control"
+submodels add an algebraic equation (for the current) and hence can be used to set any
+variable to be constant.
+
+.. toctree::
+  :maxdepth: 1
+
+  current_control_external_circuit
+  function_control_external_circuit

docs/source/models/submodels/index.rst

@@ -9,6 +9,7 @@ Submodels
     convection/index
     electrode/index
     electrolyte/index
+    external_circuit/index
     interface/index
     oxygen_diffusion/index
     particle/index

docs/source/processed_variable.rst

@@ -1,7 +1,5 @@
 Post-Process Variables
 ======================
 
-.. autofunction:: pybamm.post_process_variables
-
 .. autoclass:: pybamm.ProcessedVariable
   :members:

docs/source/solvers/base_solvers.rst

@@ -3,9 +3,3 @@ Base Solvers
 
 .. autoclass:: pybamm.BaseSolver
   :members:
-
-.. autoclass:: pybamm.OdeSolver
-  :members:
-
-.. autoclass:: pybamm.DaeSolver
-  :members:

docs/tutorials/add-solver.rst

@@ -27,29 +27,29 @@ The role of solvers is to solve a model at a given set of time points, returning
 Base solver classes vs specific solver classes
 ----------------------------------------------
 
-There is one general base solver class, :class:`pybamm.BaseSolver`, and two specialised base classes, :class:`pybamm.OdeSolver` and :class:`pybamm.DaeSolver`. The general base class simply sets up some useful solver properties such as tolerances. The specialised base classes implement a method :meth:`self.solve()` that solves a model at a given set of time points.
+There is one general base solver class, :class:`pybamm.BaseSolver`, which sets up some useful solver properties such as tolerances and implement a method :meth:`self.solve()` that solves a model at a given set of time points.
 
 The ``solve`` method unpacks the model, simplifies it by removing extraneous operations, (optionally) creates or calls the mass matrix and/or jacobian, and passes the appropriate attributes to another method, called ``integrate``, which does the time-stepping. The role of specific solver classes is simply to implement this ``integrate`` method for an arbitrary set of derivative function, initial conditions etc.
 
-The base DAE solver class also computes a consistent set of initial conditions for the algebraic equations, using ``model.concatenated_initial_conditions`` as an initial guess.
+The base solver class also computes a consistent set of initial conditions for the algebraic equations, using ``model.concatenated_initial_conditions`` as an initial guess.
 
 Implementing a new solver
 -------------------------
 
 To add a new solver (e.g. My Fast DAE Solver), first create a new file (``my_fast_dae_solver.py``) in ``pybamm/solvers/``,
-with a single class that inherits from either :class:`pybamm.OdeSolver` or :class:`pybamm.DaeSolver`, depending on whether the new solver can solve DAE systems. For example:
+with a single class that inherits from :class:`pybamm.BaseSolver`. For example:
 
 .. code-block:: python
 
-    def MyFastDaeSolver(pybamm.DaeSolver):
+    def MyFastDaeSolver(pybamm.BaseSolver):
 
 Also add the class to ``pybamm/__init__.py``:
 
 .. code-block:: python
 
     from .solvers.my_fast_dae_solver import MyFastDaeSolver
 
-You can then start implementing the solver by adding the ``integrate`` function to the class (the interfaces are slightly different for an ODE Solver and a DAE Solver, see :meth:`pybamm.OdeSolver.integrate` vs :meth:`pybamm.DaeSolver.integrate`)
+You can then start implementing the solver by adding the ``integrate`` function to the class.
 
 For an example of an existing solver implementation, see the Scikits DAE solver
 `API docs <https://pybamm.readthedocs.io/en/latest/source/solvers/scikits_solvers.html>`_

examples/notebooks/Getting Started/Tutorial 3 - Basic Plotting.ipynb

@@ -340,8 +340,8 @@
        " 'Volume-averaged total heating',\n",
        " 'Volume-averaged total heating [W.m-3]',\n",
        " 'Positive current collector potential [V]',\n",
-       " 'Local current collector potential difference',\n",
-       " 'Local current collector potential difference [V]',\n",
+       " 'Local voltage',\n",
+       " 'Local voltage [V]',\n",
        " 'X-averaged open circuit voltage',\n",
        " 'Measured open circuit voltage',\n",
        " 'X-averaged open circuit voltage [V]',\n",

examples/notebooks/README.md

@@ -40,14 +40,17 @@ For more advanced usage, new sets of parameters, spatial methods and solvers can
 ## Expression tree structure
 
 PyBaMM is built around an expression tree structure.
-[This](expression_tree/expression-tree.ipynb) notebook explains how this works, from
-model creation to solution. 
+
+- [The expression tree notebook](expression_tree/expression-tree.ipynb) explains how this works, from model creation to solution. 
+- [The broadcast notebook](expression_tree/broadcasts.ipynb) explains the different types of broadcast. 
 
 The following notebooks are specific to different stages of the PyBaMM pipeline, such as choosing a model, spatial method, or solver.
 
 ### Models
 
-The following models are implemented and can easily be used or [compared](./models/lead-acid.ipynb). We always welcome [new models](https://pybamm.readthedocs.io/en/latest/tutorials/add-model.html)!
+Several battery models are implemented and can easily be used or [compared](./models/lead-acid.ipynb). The notebooks below show the solution of each individual model. We always welcome [new models](https://pybamm.readthedocs.io/en/latest/tutorials/add-model.html)!
+
+Once you are comfortable with the expression tree structure, a good starting point to understand the models in PyBaMM is to take a look at the [basic SPM](https://github.com/pybamm-team/PyBaMM/blob/master/pybamm/models/full_battery_models/lithium_ion/basic_spm.py) and [basic DFN](https://github.com/pybamm-team/PyBaMM/blob/master/pybamm/models/full_battery_models/lithium_ion/basic_dfn.py), since these define the entire model (variables, equations, initial and boundary conditions, events) in a single class and so are easier to understand. However, we recommend that you subsequently use the full models as they offer much greater flexibility for coupling different physical effects and visualising a greater range of variables.
 
 #### Lithium-ion models
 
@@ -71,10 +74,9 @@ See [here](https://pybamm.readthedocs.io/en/latest/tutorials/add-spatial-method.
 
 ### Solvers
 
-The following solvers are implemented
-- Scipy ODE solver
-- [Scikits ODE solver](./solvers/scikits-ode-solver.ipynb)
-- [Scikits DAE solver](./solvers/scikits-dae-solver.ipynb)
-- CasADi DAE solver
+The following notebooks show examples for generic ODE and DAE solvers. Several solvers are implemented in PyBaMM and we encourage users to try different ones to find the most appropriate one for their models.
+
+- [ODE solver](./solvers/ode-solver.ipynb)
+- [DAE solver](./solvers/dae-solver.ipynb)
 
 See [here](https://pybamm.readthedocs.io/en/latest/tutorials/add-solver.html) for instructions on adding new solvers.