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?
• System requirements
• Installation
• Testing
• Examples
• Contributing
• Known issues

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 currently available DFN open-source packages such as PyBaMM, DEARLIBS, LIONSIMBA, PETION, fastDFN, and MPET, DEARLIBS and COBRAPRO are the only codes with an integrated identification routine. Given the need for numerous model simulations during parameter optimization, achieving efficient computation time is critical. COBRAPRO addresses this need with a fast solver and PSO parallel computing, resulting in model simulations up to three orders of magnitude faster than DEARLIBS and accelerated PSO through multicore processing.

Software dependencies

• MATLAB 2018b and later
• MATLAB Global Optimization Toolbox
• MATLAB Parallel Computing Toolbox
• SUNDIALS 2.6.2
• CasADi
• 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 SUNDIALS 2.6.2 and unzip the folder. Relocate the sundials-2.6.2 folder inside the COBRAPRO folder.

3. Download the latest version of CasADi 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.

4. 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

5. Now you are ready to run install_COBRAPRO.m² located inside the COBRAPRO folder. Run install_COBRAPRO.m in MATLAB 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

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

6. 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.

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
  • 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
• 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/Local_Sensitivity_Analysis: examples showing how to perform local sensitivity analysis (LSA)
  • Examples/Local_Sensitivity_Analysis/DFN_LSA_Corr_CC.m: LSA and correlation analysis on CC profile
  • Examples/Local_Sensitivity_Analysis/DFN_LSA_Corr_HPPC.m: LSA and correlation analysis on HPPC profile

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 (sungyeon.sara.ha@stanford.edu).

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 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. 

Footnotes

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

2. This function will install SUNDIALS by calling the sundials-2.6.2/ sundialsTB/install_STB.m file and automatically adds the required folders to your MATLAB path. ↩

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