#646 merge master and update optionality

pybamm-team · Nov 7, 2019 · ab4c22e · ab4c22e
2 parents e0290a7 + 8829213
commit ab4c22e
Show file tree

Hide file tree

Showing 186 changed files with 3,875 additions and 1,610 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,7 @@
 *.tmp
 *.png
 /local/
+*.DS_Store
 
 # don't ignore important .txt files
 !requirements*

diff --git a/.requirements-docs.txt b/.requirements-docs.txt
@@ -5,5 +5,6 @@ pandas>=0.23
 anytree>=2.4.3
 autograd>=1.2
 scikit-fem>=0.2.0
+casadi>=3.5.0
 guzzle-sphinx-theme
 sphinx>=1.5
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,23 +2,32 @@
 
 ## Features
 
+-   Added Simulation class ([#693](https://github.com/pybamm-team/PyBaMM/pull/693))
+-   Added interface to CasADi solver ([#687](https://github.com/pybamm-team/PyBaMM/pull/687), [#691](https://github.com/pybamm-team/PyBaMM/pull/691), [#714](https://github.com/pybamm-team/PyBaMM/pull/714)). This makes the SUNDIALS DAE solvers (Scikits and KLU) truly optional (though IDA KLU is recommended for solving the DFN).
+-   Added option to use CasADi's Algorithmic Differentiation framework to calculate Jacobians ([#687](https://github.com/pybamm-team/PyBaMM/pull/687))
+-   Added method to evaluate parameters more easily ([#669](https://github.com/pybamm-team/PyBaMM/pull/669))
+-   Added `Jacobian` class to reuse known Jacobians of expressions ([#665](https://github.com/pybamm-team/PyBaMM/pull/670))
+-   Added `Interpolant` class to interpolate experimental data (e.g. OCP curves) ([#661](https://github.com/pybamm-team/PyBaMM/pull/661))
 -   Added interface (via pybind11) to sundials with the IDA KLU sparse linear solver ([#657](https://github.com/pybamm-team/PyBaMM/pull/657))
--   Add method to evaluate parameters more easily ([#669](https://github.com/pybamm-team/PyBaMM/pull/669))
--   Add `Jacobian` class to reuse known Jacobians of expressions ([#665](https://github.com/pybamm-team/PyBaMM/pull/670))
--   Add `Interpolant` class to interpolate experimental data (e.g. OCP curves) ([#661](https://github.com/pybamm-team/PyBaMM/pull/661))
--   Allow parameters to be set by material or by specifying a particular paper ([#647](https://github.com/pybamm-team/PyBaMM/pull/647))
+-   Allowed 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 some non-uniform meshes in 1D and 2D ([#617](https://github.com/pybamm-team/PyBaMM/pull/617))
+-   Added 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))
+-   Added some non-uniform meshes in 1D and 2D ([#617](https://github.com/pybamm-team/PyBaMM/pull/617))
 
 ## Optimizations
 
+-   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
 
--   Add warning if `ProcessedVariable` is called outisde 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))
+-   Corrected a sign error in Dirichlet boundary conditions in the Finite Element Method ([#706](https://github.com/pybamm-team/PyBaMM/pull/706))
+-   Passed the correct dimensional temperature to open circuit potential ([#702](https://github.com/pybamm-team/PyBaMM/pull/702))
+-   Added missing temperature dependence in electrolyte and interface submodels ([#698](https://github.com/pybamm-team/PyBaMM/pull/698))
+-   Fixed differentiation of functions that have more than one argument ([#687](https://github.com/pybamm-team/PyBaMM/pull/687))
+-   Added warning if `ProcessedVariable` is called outside its interpolation range ([#681](https://github.com/pybamm-team/PyBaMM/pull/681))
+-   Improved 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-LINUX-MAC.md b/INSTALL-LINUX-MAC.md
@@ -97,18 +97,19 @@ pip uninstall pybamm
 
 ## Optional dependencies
 
-Two DAE solvers (`scikits.odes` and `KLU`) can be optionally installed in PyBaMM. At least one of these is required to solve DAE models, such as the DFN, but you can install both if you like.
-
-### [scikits.odes](https://github.com/bmcage/odes)
-
-A python wrapper for the SUNDIALS ODE and DAE integrators. [Installation instructions](INSTALL-SCIKITS.md).
+CasADi's DAE solvers are included by default in PyBaMM, but two additional DAE solvers (`scikits.odes` and `KLU`) can be optionally installed as well. 
+In particular, the [KLU sparse solver](INSTALL-KLU.md) is recommended for solving the DFN.
 
 ### Sundials with KLU sparse solver
 
 If you wish so simulate large systems such as the 2+1D models, we recommend employing a
 sparse solver. PyBaMM currently offers a direct interface to the sparse KLU solver within Sundials.
 [Installation instructions](INSTALL-KLU.md).
 
+### [scikits.odes](https://github.com/bmcage/odes)
+
+A python wrapper for the SUNDIALS ODE and DAE integrators. [Installation instructions](INSTALL-SCIKITS.md).
+
 ## Troubleshooting
 
 **Problem:** I've made edits to source files in PyBaMM, but these are not being used

diff --git a/INSTALL-SCIKITS.md b/INSTALL-SCIKITS.md
@@ -7,7 +7,6 @@ This file provides installation instructions for either Ubuntu-based distributio
 
 ---
 
-
 Users can install [scikits.odes](https://github.com/bmcage/odes) in order to use the
 wrapped SUNDIALS ODE and DAE
 [solvers](https://pybamm.readthedocs.io/en/latest/source/solvers/scikits_solvers.html).
@@ -20,7 +19,7 @@ Before installing scikits.odes, you need to have installed:
 - Fortran compiler (e.g. gfortran, comes with gcc in brew)
 - BLAS/LAPACK install (OpenBLAS is recommended by the scikits.odes developers)
 - CMake (for building Sundials)
-- Sundials 3.1.1 (see instructions below)
+- Sundials 4.1.0 (see instructions below)
 
 You can install these on Ubuntu or Debian using apt-get:
 
@@ -48,18 +47,17 @@ If this works, skip to [the final section](#setting-library-path). Otherwise, tr
 
 ## Option 2: install manually
 
-
-To install SUNDIALS 3.1.1 manually, on the command-line type:
+To install SUNDIALS 4.1.0 manually, on the command-line type:
 
 ```bash
 INSTALL_DIR=`pwd`/sundials
-wget https://computation.llnl.gov/projects/sundials/download/sundials-3.1.1.tar.gz
-tar -xvf sundials-3.1.1.tar.gz
-mkdir build-sundials-3.1.1
-cd build-sundials-3.1.1/
-cmake -DLAPACK_ENABLE=ON -DSUNDIALS_INDEX_TYPE=int32_t -DBUILD_ARKODE:BOOL=OFF -DEXAMPLES_ENABLE:BOOL=OFF -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR ../sundials-3.1.1/
+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/
 make install
-rm -r ../sundials-3.1.1
+rm -r ../sundials-4.1.0
 ```
 
 Then install [scikits.odes](https://github.com/bmcage/odes), letting it know the sundials install location:

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/expression_tree/index.rst b/docs/source/expression_tree/index.rst
@@ -17,6 +17,4 @@ Expression Tree
   broadcasts
   functions
   interpolant
-  evaluate
-  simplify
-  jacobian
+  operations/index
diff --git a/docs/source/expression_tree/operations/convert_to_casadi.rst b/docs/source/expression_tree/operations/convert_to_casadi.rst
@@ -0,0 +1,5 @@
+Convert to CasADi
+=================
+
+.. autoclass:: pybamm.CasadiConverter
+  :members:
diff --git a/docs/source/expression_tree/evaluate.rst → ...e/expression_tree/operations/evaluate.rst b/docs/source/expression_tree/evaluate.rst → ...e/expression_tree/operations/evaluate.rst
diff --git a/docs/source/expression_tree/operations/index.rst b/docs/source/expression_tree/operations/index.rst
@@ -0,0 +1,11 @@
+Operations on expression trees
+==============================
+
+Classes and functions that operate on the expression tree
+
+.. toctree::
+
+  simplify
+  evaluate
+  jacobian
+  convert_to_casadi
diff --git a/docs/source/expression_tree/jacobian.rst → ...e/expression_tree/operations/jacobian.rst b/docs/source/expression_tree/jacobian.rst → ...e/expression_tree/operations/jacobian.rst
diff --git a/docs/source/expression_tree/simplify.rst → ...e/expression_tree/operations/simplify.rst b/docs/source/expression_tree/simplify.rst → ...e/expression_tree/operations/simplify.rst
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/docs/source/solvers/casadi_solver.rst b/docs/source/solvers/casadi_solver.rst
@@ -0,0 +1,5 @@
+Casadi Solver
+=============
+
+.. autoclass:: pybamm.CasadiSolver
+  :members:
diff --git a/docs/source/solvers/index.rst b/docs/source/solvers/index.rst
@@ -7,4 +7,5 @@ Solvers
   base_solvers
   scipy_solver
   scikits_solvers
+  casadi_solver
   solution