Merge branch 'master' into issue-617-nonuniform-mesh

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,11 +6,11 @@ Fixes # (issue)
 
 ## Type of change
 
-Please delete options that are not relevant.
+Please add a line in the relevant section of [CHANGELOG.md](https://github.com/pybamm-team/PyBaMM/blob/master/CHANGELOG.md) to document the change (include PR #) - note reverse order of PR #s.
 
-- [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Optimization (back-end change that speeds up the code)
+- [ ] Bug fix (non-breaking change which fixes an issue)
 
 
 # Key checklist:
@@ -21,8 +21,7 @@ Please delete options that are not relevant.
 
 You can run all three at once, using `$ python run-tests.py --quick`.
 
-## Further checks: 
+## Further checks:
 
 - [ ] Code is commented, particularly in hard-to-understand areas
 - [ ] Tests added that prove fix is effective or that feature works
-- [ ] Any dependent changes have been merged and published in downstream modules

.gitignore

@@ -55,7 +55,6 @@ pyproject.toml
 # virtual enviroment
 venv/
 venv3.5/
-PyBaMM-env/
 bin/
 etc/
 lib/

CHANGELOG.md

@@ -0,0 +1,61 @@
+# [Unreleased](https://github.com/pybamm-team/PyBaMM)
+
+## Features
+
+- Add `Interpolant` class to interpolate experimental data (e.g. OCP curves) (#661)
+- Allow parameters to be set by material or by specifying a particular paper (#647)
+- Set relative and absolute tolerances independently in solvers (#645)
+
+## Optimizations
+
+- Avoid re-checking size when making a copy of an `Index` object (#656)
+- Avoid recalculating `_evaluation_array` when making a copy of a `StateVector` object (#653)
+
+## Bug fixes
+
+# [v0.1.0](https://github.com/pybamm-team/PyBaMM/tree/v0.1.0) - 2019-10-08
+
+This is the first official version of PyBaMM.
+Please note that PyBaMM in still under active development, and so the API may change in the future.
+
+## Features
+
+### Models
+
+#### Lithium-ion
+
+- Single Particle Model (SPM)
+- Single Particle Model with electrolyte (SPMe)
+- Doyle-Fuller-Newman (DFN) model
+
+with the following optional physics:
+
+- Thermal effects
+- Fast diffusion in particles
+- 2+1D (pouch cell)
+
+#### Lead-acid
+
+- Leading-Order Quasi-Static model
+- First-Order Quasi-Static model
+- Composite model
+- Full model
+
+with the following optional physics:
+
+- Hydrolysis side reaction
+- Capacitance effects
+- 2+1D
+
+
+### Spatial discretisations
+
+- Finite Volume (1D only)
+- Finite Element (scikit, 2D only)
+
+### Solvers
+
+- Scipy
+- Scikits ODE
+- Scikits DAE
+- Algebraic (root-finding)

docs/source/expression_tree/index.rst

@@ -17,4 +17,5 @@ Expression Tree
   broadcasts
   simplify
   functions
+  interpolant
   evaluate

docs/source/expression_tree/interpolant.rst

@@ -0,0 +1,5 @@
+Interpolant
+===========
+
+.. autoclass:: pybamm.Interpolant
+  :members:

docs/source/parameters/index.rst

@@ -10,3 +10,4 @@ Parameters
   standard_parameters_lithium_ion
   standard_parameters_lead_acid
   print_parameters
+  parameter_sets

docs/source/parameters/parameter_sets.rst

@@ -0,0 +1,4 @@
+Parameters Sets
+===============
+
+.. automodule:: pybamm.parameters.parameter_sets

docs/tutorials/add-parameter-values.rst

@@ -16,32 +16,61 @@ At the stage of creating a model, we use :class:`pybamm.Parameter` and :class:`p
 We then create a :class:`ParameterValues` class, using a specific set of parameters, to iterate through the model and replace any :class:`pybamm.Parameter` objects with a :class:`pybamm.Scalar` and any :class:`pybamm.FunctionParameter` objects with a :class:`pybamm.Function`.
 
 For an example of how the parameter values work, see the
-`parameter values notebook <https://github.com/pybamm-team/PyBaMM/blob/master/examples/notebooks/spatial_methods/finite-volumes.ipynb>`_.
+`parameter values notebook <https://github.com/pybamm-team/PyBaMM/blob/master/examples/notebooks/parameter-values.ipynb>`_.
 
 Adding a set of parameters values
 ---------------------------------
 
-Parameter sets should be added as csv files in the appropriate chemistry folder in ``input/parameters/`` (add a new folder if no parameters exist for that chemistry yet).
+There are two ways to add parameter sets:
+
+1. **Complete parameter file**: Parameter sets should be added as csv files in the appropriate chemistry folder in ``input/parameters/`` (add a new folder if no parameters exist for that chemistry yet).
 The expected structure of the csv file is
 
-+------------+------------+-----------+-------------+-------------+
-| Name       | Value      | Units     | Reference   | Notes       |
-+============+============+===========+=============+=============+
-| Example    | 13         | m.s-2     | bloggs2019  | an example  |
-+------------+------------+-----------+-------------+-------------+
++-------------------------+----------------------+-----------------------+-------------+
+| Name [Units]            | Value                | Reference             | Notes       |
++=========================+======================+=======================+=============+
+| Example [m]             | 13                   | bloggs2019            | an example  |
++-------------------------+----------------------+-----------------------+-------------+
 
 Empty lines, and lines starting with ``#``, will be ignored.
 
+2. **Parameters for a single material**: It's possible to add parameters for a single material (e.g. anode) and then re-use existing parameters for the other materials. To do this, add a new subfolder with a ``README.md`` for references and csv file of parameters (e.g. ``input/parameters/lithium-ion/anodes/new_anode_chemistry_Bloggs2019/``). Then this file can be referenced using the ``chemistry`` option in ``ParameterValues``, e.g.
+
+.. code-block:: python
+
+    param = pybamm.ParameterValues(
+        chemistry={
+            "chemistry": "lithium-ion",
+            "cell": "kokam_Marquis2019",
+            "anode": "new_anode_chemistry_Bloggs2019",
+            "separator": "separator_Marquis2019",
+            "cathode": "lico2_Marquis2019",
+            "electrolyte": "lipf6_Marquis2019",
+            "experiment": "1C_discharge_from_full_Marquis2019",
+        }
+    )
+
+or, equivalently in this case (since the only difference from the standard parameters from Marquis et al. is the set of anode parameters),
+
+.. code-block:: python
+
+    param = pybamm.ParameterValues(
+        chemistry={
+            **pybamm.parameter_sets.Marquis2019,
+            "anode": "new_anode_chemistry_Bloggs2019",
+        }
+    )
+
 Adding a function
 -----------------
 
 Functions should be added as Python functions under a file with the same name in the appropriate chemistry folder in ``input/parameters/``.
 These Python functions should be documented with references explaining where they were obtained.
-For example, we would put the following Python function in a file ``input/parameters/lead-acid/electrolyte_diffusivity_Bloggs2019.py``
+For example, we would put the following Python function in a file ``input/parameters/lead-acid/diffusivity_Bloggs2019.py``
 
 .. code-block:: python
 
-    def electrolyte_diffusivity_Bloggs2019(c_e):
+    def diffusivity_Bloggs2019(c_e):
         """
         Dimensional Fickian diffusivity in the electrolyte [m2.s-1], from [1]_, as a
         function of the electrolyte concentration c_e [mol.m-3].
@@ -54,6 +83,17 @@ For example, we would put the following Python function in a file ``input/parame
         """
         return (1.75 + 260e-6 * c_e) * 1e-9
 
+Then, these functions should be added to the parameter file from which they will be
+called (must be in the same folder), with the tag ``[function]``, for example:
+
++---------------------+--------------------------------------+--------------+-------------+
+| Name [Units]        | Value                                |  Reference   | Notes       |
++=====================+======================================+==============+=============+
+| Example [m2.s-1]    | [function]diffusivity_Bloggs2019     | bloggs2019   | a function  |
++---------------------+--------------------------------------+--------------+-------------+
+
+
+
 Unit tests for the new class
 ----------------------------
 
@@ -71,23 +111,7 @@ To test this, add something like the following test to one of the model test fil
 
     def test_my_new_parameters(self):
         model = pybamm.lithium_ion.DFN()
-        input_path = os.path.join(os.getcwd(), "path", "to", "functions")
-        parameter_values = pybamm.ParameterValues(
-            "path/to/parameter/file.csv",
-            {
-                "Typical current [A]": 1,
-                "Current function": os.path.join(
-                    os.getcwd(),
-                    "pybamm",
-                    "parameters",
-                    "standard_current_functions",
-                    "constant_current.py",
-                ),
-                "First function": os.path.join(input_path, "first_function.py"),
-                "Second function": os.path.join(input_path, "second_function.py"),
-            },
-        )
-
+        parameter_values = pybamm.ParameterValues("path/to/parameter/file.csv")
         modeltest = tests.StandardModelTest(model, parameter_values=parameter_values)
         modeltest.test_all()
 

examples/notebooks/README.md

@@ -16,10 +16,14 @@ from your local PyBaMM repository, or used online through [Binder](https://mybin
 The easiest way to start with PyBaMM is by running and comparing some of the inbuilt models:
 - [Run the Single Particle Model (SPM)](./models/SPM.ipynb)
 - [Compare models](./models/lead-acid.ipynb)
+- [Comparison with COMSOL](./compare-comsol-discharge-curve.ipynb)
 
-It is also easy to new models or change the setting that are used:
-- [Add a model](https://pybamm.readthedocs.io/en/latest/tutorials/add-model.html)
+It is also easy to add new models or change the setting that are used:
+- [Add a model (documentation)](https://pybamm.readthedocs.io/en/latest/tutorials/add-model.html)
+- [Add a model (example)](./create-model.ipynb)
+- [Using submodels](./using-submodels.ipynb)
 - [Change the settings](./change-settings.ipynb) (parameters, spatial method or solver)
+- [Change the applied current](./change-input-current.ipynb)
 
 For more advanced usage, new sets of parameters, spatial methods and solvers can be added:
 - [Add parameters](https://pybamm.readthedocs.io/en/latest/tutorials/add-parameter-values.html)
@@ -50,8 +54,9 @@ The following models are implemented and can easily be used or [compared](./mode
 
 ### Spatial Methods
 
-The following spatial method is implemented
+The following spatial methods are implemented
 - [Finite Volumes](./spatial_methods/finite-volumes.ipynb)
+- Finite Elements (only for 2D current collector domains)
 
 See [here](https://pybamm.readthedocs.io/en/latest/tutorials/add-spatial-method.html) for instructions on adding new spatial methods.
 

examples/notebooks/models/DFN.ipynb

@@ -284,7 +284,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.7"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/notebooks/models/SPMe.ipynb

@@ -273,7 +273,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.7"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/notebooks/models/compare-lithium-ion.ipynb

@@ -13,7 +13,7 @@
    "source": [
     "We compare three one-dimensional lithium-ion battery models: [the Doyle-Fuller-Newman (DFN) model](./DFN.ipynb), [the single particle model (SPM)](./SPM.ipynb), and [the single particle model with electrolyte (SPMe)](./SPMe.ipynb). Further details on these models can be found in [[1]](#ref).\n",
     "\n",
-    "<a name=\"ref\">[1]</a> Marquis, Scott G., Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. \"An asymptotic derivation of a single particle model with electrolyte.\" arXiv preprint arXiv:1905.12553 (2019).\n"
+    "<a name=\"ref\">[1]</a> Scott G. Marquis, Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. \"An asymptotic derivation of a single particle model with electrolyte.\" arXiv preprint arXiv:1905.12553 (2019).\n"
    ]
   },
   {