PyBaMM

Python Battery Mathematical Modelling solves continuum models for batteries, using both numerical methods and asymptotic analysis.

How do I use PyBaMM?

PyBaMM comes with a number of detailed examples, hosted here on github. In addition, there is a full API documentation, hosted on Read The Docs.

How can I obtain & install PyBaMM?

You'll need the following requirements:

• Python 3.5+
• Git (git package on Ubuntu distributions)
• Python libraries: venv (python3-venv package on Ubuntu distributions)

The first step is to get the code by cloning this repository

git clone https://github.com/pybamm-team/PyBaMM.git
cd PyBaMM

The safest way to install PyBaMM is to do so within a virtual environment (introduction to virtual environments). To create a virtual environment env within your current directory type:

python3 -m venv env

You can then "activate" the environment using:

source env/bin/activate

Now all the calls to pip described below will install PyBaMM and its dependencies into the environment env. When you are ready to exit the environment and go back to your original system, just type:

deactivate

PyBaMM has the following python libraries as dependencies: numpy, scipy, pandas, matplotlib. These, along with PyBaMM, can easily be installed using pip. First, make sure you have activated your virtual environment as above, and that you have the latest version of pip installed:

pip install --upgrade pip

Then navigate to the path where you downloaded PyBaMM to (you will already be in the correct location if you followed the instructions above), and install both PyBaMM and its dependencies by typing:

pip install .

Or, if you want to install PyBaMM as a developer, use

pip install -e .[dev,docs]

To uninstall again, type

pip uninstall pybamm

Optional dependencies

Intel MKL

I needed to preload the intel mkl libraries like so (see https://software.intel.com/en-us/forums/intel-math-kernel-library/topic/748309)

export LD_PRELOAD=/opt/intel/mkl/lib/intel64/libmkl_def.so:/opt/intel/mkl/lib/intel64/libmkl_avx2.so:/opt/intel/mkl/lib/intel64/libmkl_core.so:/opt/intel/mkl/lib/intel64/libmkl_intel_lp64.so:/opt/intel/mkl/lib/intel64/libmkl_intel_thread.so:/opt/intel/lib/intel64_lin/libiomp5.so

scikits.odes

Users can install scikits.odes in order to use the wrapped SUNDIALS ODE and DAE solvers.

Before installing odes, you need to have installed:

• Python header files (python-dev/python3-dev on Debian/Ubuntu-based distributions)
• C compiler
• Fortran compiler (e.g. gfortran)
• BLAS/LAPACK install (OpenBLAS is recommended by the scikits.odes developers)
• Sundials 3.1.1

To install Sundials 3.1.1, on the command-line type:

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/
make install
rm -r ../sundials-3.1.1

Then install scikits.odes, letting it know the sundials install location:

SUNDIALS_INST=$INSTALL_DIR pip install scikits.odes

After this, you will need to set your LD_LIBRARY_PATH to point to the sundials library:

export LD_LIBRARY_PATH=$INSTALL_DIR/lib:$LD_LIBRARY_PATH

You may wish to put this last line in your .bashrc or virtualenv activate script, which will save you needing to set your LD_LIBRARY_PATH every time you log in. For example, to add this line to your .bashrc you can type:

echo "export LD_LIBRARY_PATH=$INSTALL_DIR/lib:\$LD_LIBRARY_PATH" >> ~/.bashrc

Please see the scikits.odes documentation for more detailed installation instructions.

scikit.fem

Users can install scikit.fem in order to generate meshes and assemble discrete operators for use in the finite element method. At present, the finite element method is only implemented for a small number of submodels in PyBaMM (for example, see the current collector submodel).

Note that scikit-fem requires Python 3.6+. To install scikit-fem, on the command-line type:

pip install scikit-fem

Please see the scikit.fem documentation for more information.

How can I contribute to PyBaMM?

If you'd like to help us develop PyBaMM by adding new methods, writing documentation, or fixing embarrassing bugs, please have a look at these guidelines first.

Licensing

PyBaMM is fully open source. For more information about its license, see LICENSE.