diffthermo

diffthermo is a python library for fitting thermodynamically consistent OCV models. It takes OCV and SoC as input, automatically does all the fitting and returns OCV models in PyBaMM and Matlab formats.

Installation

Install the environment first bash conda create -n diffthermo python=3.11 torch=2.0.0 numpy=1.24 matplotlib pandas After succesfully installed the environment, bash conda activate diffthermo download the github repo bash git clone https://github.com/BattModels/Diffthermo_OCV_paper.git bash cd Diffthermo_OCV_paper and then install the package bash pip install .

Usage

It's as simple as only 3 lines of commands! ```python from diffthermo.utils import train, writeocvfunctions

fit the OCV function

paramslist = train(datafilename='graphite.csv', numberofOmegas=6, learningrate = 1000.0, totaltrainingepochs = 8000, lossthreshold = 0.01, G0randrange=[-105000,-55000], Omegasrandrange=[-10100,10100])

write the fitted OCV function in PyBaMM OCV function format

writeocvfunctions(paramslist) `` After the fitting, you can find your fitted PyBaMM OCV function in the filefittedocvfunctions.py, and the MATLAB OCV function in the filefittedocv_functions.m`, or directly find them in the terminal where you executed the fitting code. Copy and paste them into your own projects and that's it! Incredibly easy, isn't it?

See example_graphite_OCV.ipynb and example_LFP_OCV.ipynb under folder examples as two quick examples on how to fit OCV for graphite and LFP, and what do all the parameters for train function means.

Some quick notes:

2. If your fitted results does not look good, TRY adjusting G0_rand_range and Omegas_rand_range in train function. These two parameters control the initial guess of G0 and Omegas. Usually for an anode material, G0_rand_range=[-10*5000,-5*5000], Omegas_rand_range=[-10*100,10*100] work well, and for cathode material, G0_rand_range=[-100*5000,-50*5000], Omegas_rand_range=[-100*100,100*100] work.

3. For number_of_Omegas, usually for a phase-separating material that has n phase separating regions, set numberofOmegas to be 2n to 4n should work fine for most cases (e.g. for LFP which has one (n=1) phase separation region, numberofOmegas=4 gives a good fit)

4. If the fitted OCV function has a loss value or RMSE, try to initialize train function for mutiple times, as the Omegas and G0 are randomly initialized each time when you call train function, and some initialization will lead to bad fittings

5. If after trying to adjust G0_rand_range and Omegas_rand_range and initializing train for multiple times you still get a large RMSE, then try to increase number_of_Omegas. As shown in Figure 4 of the paper, sometimes it does need 20+ parameters to get a good fit.

If you want to know why exactly this fitting works, please refer to the paper "Open-Circuit Voltage Models Should Be Thermodynamically Consistent", or the code walk-through recording.

Folders In This Repo

diffthermo: the source code.

examples: examples on how to fit a thermodynamically consistent OCV functions.

dataformanuscripts: contains all source code & run results for the paper "Open-Circuit Voltage Models Should Be Thermodynamically Consistent", as well as the Legendre/Chebyshev version of OCV models.

pybammOCVfunctions: contains all the fitted thermodynamically consistent OCV functions, implemented in PyBamm. You can get your OCV model in Matlab by running the fitting process and check the output file fitted_ocv_functions.m.

Cite this work

If you find this repo useful in your research, please cite this work as follows (BibTex Format): @article{doi:10.1021/acs.jpclett.3c03129, author = {Yao, Archie Mingze and Viswanathan, Venkatasubramanian}, title = {Open-Circuit Voltage Models Should Be Thermodynamically Consistent}, journal = {The Journal of Physical Chemistry Letters}, volume = {0}, number = {0}, pages = {1143-1151}, year = {0}, doi = {10.1021/acs.jpclett.3c03129}, URL = { https://doi.org/10.1021/acs.jpclett.3c03129 }, eprint = { https://doi.org/10.1021/acs.jpclett.3c03129 } }