COBRAPRO: A MATLAB toolbox for Physics-based Battery Modeling and Co-simulation Parameter Optimization

COBRAPRO (Co-simulation Battery Modeling for Accelerated Parameter Optimization) is a MATLAB software for physics-based modeling of lithium-ion batteries (LIB) with an embedded parameter identification routine. We aim to provide the battery modeling community with a versatile toolbox for calibrating battery models, a crucial process to achieve accurate simulation results for predicting real-world battery responses under various operating conditions.

Table of contents

• What is COBRAPRO?
• Why COBRAPRO?
• Accompanying papers
• System requirements
• Installation
• Testing
• Examples
• API Documentation
• Contributing
• Known issues
• How to cite this code
• Contributors

What is COBRAPRO?

COBRAPRO implements the Dolye-Fuller-Newman (DFN) model, also known as the pseudo-two-dimensional (P2D) model, which is a high-fidelity LIB model considering the lithium-ion mass and charge conservation in the liquid electrolyte and solid electrodes, and Butler-Volmer kinetics. Parameter calibration, or identification, is a primary challenge in implementing the DFN model since the parameters such as geometric, transport, kinetic, concentration, and stoichiometric are often not known a prioi.

In response to this challenge, COBRAPRO allows users to identify parameters of any battery cells based on their experimental current-voltage profiles. COBRAPRO solves an optimization problem that minimizes the error between the experimental and simulated voltage and state-of-charge curves to identify the parameters of interest. Although the software employs particle swarm optimization (PSO) by default, users have the flexibility modify the code to implement other MATLAB optimization algorithms such as ga, fmincon, patternsearch, and more.

Why COBRAPRO?

Compared to existing open-source DFN packages like PyBaMM, LIONSIMBA, PETION, fastDFN, and MPET, only COBRAPRO and DEARLIBS include an integrated identification routine. COBRAPRO further distinguishes itself by enabling parameter identifiability analysis, allowing users to identify which parameters can be optimized based on the given data. Efficient computation is critical for parameter optimization, which requires numerous model simulations. COBRAPRO addresses this challenge with a fast solver and PSO parallel computing, offering model simulations up to three orders of magnitude faster than DEARLIBS and enhanced PSO performance through multicore processing.

Accompanying papers

For a comprehensive dive into the numerical methods, determination of consistent initial condition, and parameter optimization pipeline proposed in CORBAPRO, users are encouraged to check out our JES paper:

[1] S. Ha and S. Onori, “COBRAPRO: An Open-Source Software for the Doyle-Fuller-Newman Model with Co-Simulation Parameter Optimization Framework,” J. Electrochem. Soc., vol. 171, no. 9, p. 090522, Sep. 2024, doi: 10.1149/1945-7111/ad7292.

Our JOSS paper can also be viewed for additional information:

[2] S. Ha and S. Onori, “COBRAPRO: A MATLAB toolbox for Physics-based Battery Modeling and Co-simulation Parameter Optimization,” Apr. 16, 2024, arXiv: arXiv:2404.10022.

Software dependencies

• MATLAB 2016a and later
• MATLAB Global Optimization Toolbox
• MATLAB Parallel Computing Toolbox
• SUNDIALS 2.6.2
• CasADi (MATLAB version)
• Xcode (for macOS users only)
• MinGW (for Window users only)

Installation section below shows how to install the required software.

Installation

1. Download COBRAPRO by downloading the zip file or cloning this repository by typing in Terminal:

   git clone https://github.com/COBRAPROsimulator/COBRAPRO.git
   

2. Download MATLAB if not installed already. Make sure to select both the Global Optimization Toolbox and Parallel Computing Toolbox during the installation process.

3. Download SUNDIALS 2.6.2 and unzip the folder. Relocate the sundials-2.6.2 folder inside the COBRAPRO folder.

4. Download the latest version of CasADi (MATLAB version) corresponding to your operating system. Unzip and move your CasADi folder inside the COBRAPRO folder. Your COBRAPRO folder should now contain the sundials-2.6.2 and CasADi folders.

   • IMPORTANT NOTE: For Mac Apple Silicon users using the Apple Silicon version of MATLAB, note that you will need to download the Mac M1 version for CasADi (MATLAB version). However, please download the "R2018b or later", NOT the the "R2020b or later" for the Mac M1 version. We noticed that CasADi's "R2018b or later" of the Mac M1 version is not compatible with Apple Silicon version of MATLAB. This comment is valid as of CasADi v3.6.6.

5. Before we can install SUNDIALS, the following software are required to compile the mex files that will interface with the SUNDIALS IDA solver:

   • Mac users: Download Xcode application (can be downloaded from Apple’s App Store). Once Xcode¹ is installed, proceed to accept the license agreement. This can be done by opening the Xcode application, which will launch a license agreement window and click the “Agree” icon, or type

     sudo xcodebuild -license accept
     

     in Terminal. If the license is not accepted, MATLAB may give an error such as “Xcode is installed, but its license has not been accepted”.
   • Window users: Download MinGW

6. Now you are ready to run install_COBRAPRO.m, which is located in the main COBRAPRO folder. install_COBRAPRO.m will install SUNDIALS by calling the sundials-2.6.2/sundialsTB/install_STB.m file and automatically add the required folders to your MATLAB path. Run install_COBRAPRO.m and respond to the prompts displayed in the Command Window in the following manner:

MEX files will be compiled and built using the above options
   Proceed? (y/n)

→ Type y and hit enter

Compile CVODES interface? (y/n)

→ Type n and hit enter

Compile IDAS  interface? (y/n)

→ Type y and hit enter

Compile KINSOL  interface? (y/n)

→ Type n and hit enter

MEX files were successfully created.
    Install toolbox? (y/n) 

→ Type y and hit enter

Specify the location where you wish to install the toolbox.
The toolbox will be installed in a subdirectory "sundialsTB".
Enter return to cancel the installation.
Installation directory:

→ Just hit enter

Type the name of your CasADi folder (case-sensitive):

→ Type the name of the CasADi folder exactly as it appears and hit enter

7. Successful installation will output to the Command Window:

COBRAPRO installed successfully! To get started, try running scripts in the Examples folder.

Testing

Automated test codes are provided in test folder:

• test_1_casadiCheck.m checks that CasADi is installed and working properly. Successful run will output to Command Window:

test_1 successful: CasADi is working properly!

• test_2_comsolValidation.m validates COBRAPRO against results generated from COMSOL Multiphysics² as a benchmark. This ensures that COBRAPRO is installed properly and that the SUNDIALS IDA solver is working as expected. Successful validation will output to Command Window:

test_2 successful: COBRAPRO is working as expected! Results validated against COMSOL.

• test_3_psoCheck.m ensures that MATLAB's Global Optimization Toolbox and Parallel Computing Toolbox are installed, and makes sure that the PSO in parallel (required for parameter identification) is working correctly. Successful run will output to Command Window:

test_3 successful: PSO in parallel is working as expected!

Examples

In the Examples folder, you will find example codes that will help you get started.

• Examples/Cycling: examples showing how to perform battery cycling simulations using experimentally identified parameters
  • Examples/Cycling/cycle_CC.m: simulating constant current (CC) cycling experiments and result visualization (voltage, state-of-charge, internal variable curves)
  • Examples/Cycling/cycle_HPPC.m: simulating hybrid pulse power characterization (HPPC) profile and result visualization (voltage, state-of-charge, internal variable curves)
  • Examples/Cycling/cycle_UDDS.m: simulating driving cycle profile and result visualization (voltage, state-of-charge, internal variable curves)
• Examples/Parameter_Identification_Routines: examples showing how to perform parameter identification using PSO → NOTE: In general, these scripts take a while to run. Using a processor with multiple cores, e.g., 12 or 24 cores, will significantly speed up the PSO. Also, PSO particle size and PSO exit conditions affect the PSO convergence accuracy and time.)
  • Examples/Parameter_Identification_Routines/DFN_pso_0_05C.m: parameter identification using C/20 discharge data
  • Examples/Parameter_Identification_Routines/DFN_pso_HPPC.m: parameter identification using HPPC data (given same number of PSO particles and PSO exit conditions, takes longer to run than DFN_pso_0_05C.m since HPPC takes much longer to run than C/20 discharge)
• Examples/Parameter_Identification_Results: examples showing parameter identification results
  • Examples/Parameter_Identification_Results/DFN_pso_0_05C_identification.m: parameter identification results using C/20 discharge data
  • Examples/Parameter_Identification_Results/DFN_pso_HPPC_identification.m: parameter identification results using HPPC data
  • Examples/Parameter_Identification_Results/DFN_pso_UDDS_validation.m: parameter identification validation using UDDS data
• Examples/Parameter_Identifiability_Analysis: examples showing how to perform LSA and correlation analysis to determine a subset of identifiable parameters for the given data
  • Examples/Parameter_Identifiability_Analysis/DFN_LSA_Corr_CC.m: LSA and correlation analysis on CC profile
  • Examples/Parameter_Identifiability_Analysis/DFN_LSA_Corr_HPPC.m: LSA and correlation analysis on HPPC profile

Examples

Refer to our API documentation page for a list of all the functions as scripts in CORBAPRO.

Contributing

We welcome contributions from the community to improve COBRAPRO!

• To report bugs, ask questions, and get help, please open a new issue through the Github issues page. Be as specific as possible (including screenshots, sample codes) for efficient communication.
• To make changes to the code or add new functions, 1) fork the repo and create your branch from main, 2) make your changes to the code, and 3) open a Pull request. Once approved, your contribution will be merged into the master branch.
• For general discussions and project ideas, open a new Discussions through the Github issues page. You can also contact Sara Ha ([email protected]).

Known issues

1. To run COBRAPRO, only the SUNDIALS IDAS interface is required. In Installation step 4, if you install the KINSOL interface, you may run into the following issue:

Error using mex
COBRAPRO/sundials-2.6.2/sundialsTB/kinsol/kim/src/kim.c:687:24: error: non-void function 'KIM_Stats' should return a value [-Wreturn-type]
if (kimData == NULL) return;
COBRAPRO/sundials-2.6.2/sundialsTB/kinsol/kim/src/kim.c:687:24: error: non-void function 'KIM_Free' should return a value [-Wreturn-type]
return;
2 errors generated.

To fix this issue, please go to sundials-2.6.2/sundialsTB/kinsol/kim/src/kim.c and modify line 687 to

if (kimData == NULL) return NULL;

and modify line 815 to

return NULL;

2. If you happen to run into the following error when installing/running COBRAPRO:

Error using mex
'idm.mexmaca64' locked by mexLock API.

This seems to occur when MATLAB is trying to compile the mex files and mexLock is triggered. To resolve the issue, please restart MATLAB. 

How to cite this code

If you use this code in your research, please cite our accompanying JES and JOSS papers:

@article{cobrapro_jes_2024,
   author = {Ha, Sara and Onori, Simona},
   doi = {10.1149/1945-7111/ad7292},
   journal = {Journal of The Electrochemical Society},
   year = {2024},
   title = {{COBRAPRO: An Open-Source Software for the Doyle-Fuller-Newman Model with Co-Simulation Parameter Optimization Framework}},
} 

@article{cobrapro_joss_2024,
   author = {Ha, Sara and Onori, Simona},
   doi = {arXiv:2404.10022},
   journal = {Journal of Open Source Software},
   year = {2024},
   title = {{COBRAPRO: A MATLAB toolbox for Physics-based Battery Modeling and Co-simulation Parameter Optimization}},
}

Contributors

Footnotes

1. Note that Xcode requires ~3.4 GB of storage space. ↩

2. COMSOL Multiphsyics is a commerically available finite element analysis software. ↩