About Spectral Li-ion SPM

To cite this code, check the latest release DOI at https://zenodo.org/badge/latestdoi/59030370

Spectral Li-ion SPM is a MATLAB code that solves the so-called lithium-ion battery Single Particle Model (SPM) using spectral numerical methods. The SPM is an electrochemical model describing lithium transport, reaction kinetics and thermodynamics in lithium-ion batteries. Spectral Li-ion SPM consists of the SPM coupled to a bulk thermal model describing the evolution of battery temperature. The SPM is an approximation to the electrochemical pseudo-two dimensional lithium-ion battery model where electrolyte transport limitations are neglected. Therefore the SPM is only valid for relatively low currents, up to 1C or 2C depending on the battery design. The diffusion partial-differential equations of the SPM are discretised in space using an efficient spectral numerical method: Chebyshev orthogonal collocation. This implementation of the SPM is similar to our implementation of the more complex pseudo-two dimensional battery model which is discussed in our paper:

Bizeray A.M., Zhao S., Duncan S. R., and Howey D. A., “Lithium-ion battery thermal-electrochemical model-based state estimation using orthogonal collocation and a modified extended Kalman filter”, Journal of Power Sources, vol. 296, pp. 400-412, 2015. Publisher copy and Open access pre-print.

If you use Spectral Li-ion SPM in your work, please cite our paper and our code using its DOI available at https://zenodo.org/badge/latestdoi/59030370.

This code has been developed at the Department of Engineering Science of the University of Oxford. For information about our lithium-ion battery research, visit the Battery Intelligence Lab website.

Requirements

You will need MATLAB to run this code. This code has been developed and tested in MATLAB R2015b and should work with later versions. Although it has not been tested with earlier MATLAB releases, it should also work with no or minor modifications.

You will also need the MATLAB Differentiation Matrix Suite_ developed by Weideman and Reddy to use our code (see "Installation"). The MATLAB Differentiation Matrix Suite is available for free on the MathWorks website and is used to compute the Chebyshev orthogonal collocation differentiation matrices. More details can be found on their website and paper: JAC Weideman, SC Reddy, A MATLAB differentiation matrix suite, ACM Transactions of Mathematical Software, Vol 26, pp 465-519 (2000).

Installation

Step 1 - Installing Spectral Li-ion SPM

###Option 1 - Downloading a .zip file### Download a .zip file of the code at:

https://github.com/adrienBizeray/Spectral_li-ion_SPM/archive/master.zip

Then, unzip the folder in a chosen directory on your computer.

###Option 2 - Cloning the repository with Git### To clone the repository, you will first need to have Git installed on your computer. Then, navigate to the directory where you want to clone the repository in a terminal, and type:

git clone https://github.com/adrienBizeray/Spectral_li-ion_SPM.git

The folder containing all the files should appear in your chosen directory.

Step 2 - Installing the MATLAB Differentiation Matrix Suite

1. Go to the MathWorks website at http://uk.mathworks.com/matlabcentral/fileexchange/29-dmsuite and download the DMSUITE folder (you may need to register and obtain a Mathworks account, alternatively you can download the chebdif.m file only here).

2. Unzip the DMSUITE folder and put it somewhere on your MATLAB path. We suggest to drop it in the source sub-folder of the Spectral Li-ion SPM code and run the following command to add this sub-folder to the MATLAB path:

addpath(genpath('source'));

Getting started

The best way to get started with Spectral Li-ion SPM is to have a look at the EXAMPLE_constant_current_discharge.m file. This file runs a 1C constant-current discharge simulation for a LCO lithium-ion cell, and also gives some explanation about the single particle model and its MATLAB implementation using Chebyshev orthogonal collocation.

The EXAMPLE_constant_current_discharge.m script was written with MATLAB Publish markups, therefore the best way to read this file is to generate a HTML file by using the MATLAB Publish function instead of simply running the file (this may take a few minutes the first time as pictures will be automatically generated). Alternatively, a PDF version of the file is available in the Spectral Li-ion SPM folder.

License

This open-source MATLAB code is published under the BSD 3-clause License, please read the LICENSE.txt file for more information.