battery-intelligence-lab / slide Goto Github PK

SLIDE is C++ code that simulates degradation of lithium ion cells. It extends the single particle model with various degradation models from literature. Users can select which degradation models they want to use for a given simulation.

License: Other

MATLAB 10.06% C++ 86.87% CMake 1.56% Python 1.04% TeX 0.47%

battery digital-twin physical-modeling simulation

slide's Introduction

Slide

In this readme.md a summary is given. You may find the detailed documentation here.
If you are affected by the sudden change of master branch, please switch to SLIDE_v2 branch.

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

Slide (simulator for lithium-ion degradation) is a code project mainly written in C++ to do fast simulations of degradation of lithium-ion batteries. Simulating 5000 1C CC cycles should take less than 1 minute; adding a CV phase doubles the calculation time to below 2 minutes. The project uses object oriented programming in C++, see documentation for more details.

The underlying battery model is the Single Particle Model (SPM) with a coupled bulk thermal model. A spectral implementation of the SPM in Matlab was developed by Bizeray and Howey and is available separately on GitHub. Slide adds various degradation models on top of the SPM. The equations were taken from literature and implemented in one large coupled model. Users can easily select which models they want to include in their simulations. They can set the values of the fitting parameters of those degradation models to fit their own data.

Slide is written to behave similarly to a battery tester. It offers functions to load cells with a constant current, a current profile or a constant voltage such that users can program their own degradation procedures. Some standard procedures have already been implemented (for calendar ageing and cycle ageing with regular CCCV cycles or with drive cycles). Also some reference performance tests have already been coded (to simulate a the capacity measurement, OCV curves, pulse discharge, etc.). Users can choose to store data points (current, voltage, temperature) at fixed time intervals during the degradation experiments, similar to how a battery tester stores such data.

The results from the simulations are written to csv files. Users can write their own code to read and plot these results, but MATLAB-scripts are provided for this too.

Detailed documentation is provided in the pdf documents. The code itself is also extensively documented.

If you use Slide in your work, please cite our paper:

J.M. Reniers, G. Mulder, D.A. Howey, "Review and performance comparison of mechanical-chemical degradation models for lithium-ion batteries", Journal of The Electrochemical Society, 166(14), A3189, 2019, DOI 10.1149/2.0281914jes.

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.

For more information and comments, please contact [email protected].

Requirements

You will need a C++ programming environment to edit, compile and run the code. Eclipse is the environment used to develop the code, but other environments should work as well. Your computer must also have a C++ compiler installed. The code has been tested using g++. Extensive guidelines on how to install those programs is provided in the documentation.

To display the results, various Matlab scripts are provided. To run those, you will need to have installed Matlab. The code has been tested using Matlab R2018a, but should work with other releases with no or minor modifications.

To calculate the spatial discretisation, two open-source Matlab functions developped by others are being used. If you don't change the discretisation, you will not need them. If you do change the discretisation, please read the license files attached to those two functions ('license chebdif.txt' and 'lisence cumsummat.txt').

Installation

Option 1 - Downloading a .zip file

Download a .zip file of the code

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][6] 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/Battery-Intelligence-Lab/SLIDE.git

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

Getting started

Detailed instructions on how to get started are in the documentation. You first have to import the code to your programming environment and make sure the settings are correct (e.g. to allow enough memory for the calculation). Then you can open Main.cpp, which implements the main-function. In this function you choose what to simulate by uncommenting the thing you want to do (and commenting all other lines). It is recommended to start with the CCCV-function, which simulates a few CCCV cycles. You will then have to build (or compile) the code, which might take a while the first time you do this. Now you can run the code (either locally in the programming environment or by running the executable which was created by the compiler). While the simulation is running, csv files with the results are written in one or multiple subfolders. When the simulation has finished, you can run the corresponding MATLAB-script (e.g. readCCCV.m) to plot the outcomes.

Much more detailed documentation can be found in the documentation (from '1 Getting started' to '7 appendixes; debugging, basics of C++, object oriented programming'). These guides are mostly independent of each other, so you don't have to read all of them. Also the code itself is extensively commented, so you might not have to read the guides at all.

License

This open-source C++ and Matlab code is published under the BSD 3-clause License, please read LICENSE file for more information.

This software also uses the following external libraries: Two Matlab functions used by the code to produce the spatial discretisation have been developed by others.

DMSUITE: see matlab/license-chebdif.txt for details.
Cumsummat: see matlab/licence-cumsummat.txt for details.

slide's People

Contributors

Stargazers

Watchers

slide's Issues

Discrepancy in cycling data

Hi,
First of all thank you, I have been using SLIDE to simulate degradation data and it has been insightful for our research.
I am using SLIDE in WSL.

I am using the branch SLIDE_v2.
I am only using the following functions in main.cpp (with the default degradation parameter settings and using KokamNMC)

"
estimateOCVparameters();
ProfileAgeing(M, pref, deg, cellType, settings::verbose); // simulates a bunch of drive cycle degradation experiments

In degradation.cpp, I only changed the following parameters from default (in ProfileAgeing - see image below) 1 second for the data. I didnt change anything checkup parameters elsewhere.

After simulating, obtaining results, if I just look at the few discharge cycles data (UDDS 0-100 @ 25), especially current, I integrate them considering nominal capacity, I obtain SoC which seems perfect as below:

However, if I look into whole data, discharge, charge and checkup, I have trouble obtaining SoC, which shows I might have some issues in currents when I integrate them assuming time steps as one seconds. See below, the first 2.5e5 samples.

So my question is, where does this discrepancy comes from ? my assumption of one second ? if yes then what sample time shall I use, or where can I change the sample time for every other entities (checkup, charging) to make sure the SoC is respected.

Or there is something entirely different than onesecond assumption?

Kind regards,
Taranjit

Code coverage is missing.

We currently don't know how much our tests cover the code. They will be added soon.

Python interface

An interface users can use to run SLIDE from Python is required.

Combining functions

Hello,

I would like to simulate battery degradation where both cyclic and calendar ageing are being taken into consideration at the same time. Right now, those two functions are running separately and not dependent of one another. In other words, I would like to receive an output file with data that has taken into consideration both calendar and cyclic ageing. Is this possible?

Best regards,
Elsa

High order integration

Currently only Forward Euler scheme is implemented. Higher order integration (such as Runge-Kutta 4) functions and integration with adaptive time step are needed.

Can't find `cycling.cpp` file to edit `followCurrent`

The documentation refers to the cycling.cpp file where I should be able to use the followCurrent function to specify a user defined current profile. Although I seem unable to find it in the repository. Is this file part of an older version of SLIDE or on a different branch?

Thank you!

Matlab plot titles and legends render underscore as subscript

Titles, legends, and other labels in the Matlab figures render the IDs as a subscript because the text contains an _ underscore. For example, the following

https://github.com/davidhowey/SLIDE/blob/ecd87fabed345ed366c4ae84144b610f21d3ae13/scipts/readAgeing_cyclingData.m#L129

should be changed to something like

title(strcat('cell temperature of ', IDs{i}))  
title(['cell temperature of ', IDs{I}], 'Interpreter', 'none')

Also, the scipts folder is mispelled; it should be scripts.

Current profile

Hi,

I have two questions;

Is it possible to run cyclicAgeing with my own current profile? I want to run my own .csv-file as in FollowCurrent. I cannot find where in the cyclicAgeing the current can be changed.
In FollowCurrent, the boolean blockdegradation can be changed to take degradation into consideration when cycling. What kind of degradation does the function take into consideration? Is it connected to the functions cycligAgeing and calendarAgeing?

Best regards,
Elsa

Compiling and running on Ubuntu 20.04

Hello,

I'm trying to compile the current master branch on my Ubuntu 20.04 machine. Some important package information:

cmake version 3.26.0
gcc (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0
g++ (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0

I'm following the installation instructions found here, but the last steps fails when I run cmake --build .:

...
[ 97%] Building CXX object tests/unit/CMakeFiles/unit_test_Module_p.dir/Module_p_test.cpp.o
[100%] Linking CXX executable /mnt/localdata/ProgrammingProjects/SLIDE/bin/Release/unit_test_Module_p
/usr/bin/ld: /tmp/unit_test_Module_p.ebGB4w.ltrans1.ltrans.o: in function `slide::Module_p::timeStep_CC(double, int)':
<artificial>:(.text+0x43be): undefined reference to `pthread_create'
/usr/bin/ld: <artificial>:(.text+0x448f): undefined reference to `pthread_create'
/usr/bin/ld: /tmp/unit_test_Module_p.ebGB4w.ltrans1.ltrans.o: in function `slide::Module_s::timeStep_CC(double, int)':
<artificial>:(.text+0x4bfe): undefined reference to `pthread_create'
/usr/bin/ld: <artificial>:(.text+0x4ccf): undefined reference to `pthread_create'
collect2: error: ld returned 1 exit status
make[2]: *** [tests/unit/CMakeFiles/unit_test_Module_p.dir/build.make:106: /mnt/localdata/ProgrammingProjects/SLIDE/bin/Release/unit_test_Module_p] Error 1
make[1]: *** [CMakeFiles/Makefile2:723: tests/unit/CMakeFiles/unit_test_Module_p.dir/all] Error 2
make: *** [Makefile:146: all] Error 2

I'm not familiar with cmake, so I'm not sure how to fix the pthread_create problem.

Can you help me?

Kind regards,

Joris

cd ~/SLIDE/src
in determineCharacterisation.cpp change line 676 to constexpr int nCCCV = 5;
in determineOCV.h add #include <iostream> before using namespace std;
in Model.cpp add parent directory to all file locations such as "../Cheb_Nodes.csv"
compile with $ clang++ -std=c++11 *.cpp -o main
run the program with ./main

I get the following error:

zsh: segmentation fault  ./main

Any suggestions on how I can get this code to run on a Mac?

MATLAB interface

An interface users can use to run SLIDE from MATLAB is required.

Create a log file

We can write the errors/warnings into a log file by which users can investigate errors if they encounter any problems afterwards. We can also put more information into the log file.