Please use this version of the code, which has many important bug fixes.
-
Now, 24 equivalent circuits are implemented.
-
Optional number of ZARC components (1,2,3)
-
Optional inductance
-
Optional ZARC inductance
-
The warburg element (modelling diffusion resistance) can now be placed either in series with the ZARCs or nested within the resistance branch of the low frequency ZARC. (this is called "warburg_inception".)
-
User manual with drawings of the available equivalent circuits.
-
Video tutorial of how to install and use the software can be found at https://youtu.be/z-xAmvJ4HPE
-
Now supports three file formats.
- mpt files in the format of MPT_example.txt
- txt files in the format of DAHN_TXT_example.txt
- txt files in the format of COLUMBIA_TXT_example.txt with the columns freq, real part (ohm), negative imaginary part (ohm).
- the parameters 'Q warburg' and 'Q inductance' used to be outputted as 1/Q instead. This is now fixed.
- Issues with model configurations and pretrained model not being updated have been solved, with internal testing added before release.
- The W_c Zarc parameters were given in logarithmic scale. Now they are given in the usual scale (rad/s)
- The plots labels used to be mixed up and the plots were too small. This has been fixed.
Analysis of Thousands of Electrochemical Impedance Spectra of Lithium-Ion Cells through a Machine Learning Inverse Model by Sam Buteau and J. R. Dahn
doi: 10.1149/2.1051908jes J. Electrochem. Soc. 2019 volume 166, issue 8, A1611-A1622
This repository was released together with a paper, which explains the approach taken and some of the terminology.
The current version of the software comes with a pretrained model, and can be run on a given Folder. By running the code on a given Folder,
- all the recognised files will be imported into the internal database. (if a user wants to use a different format, only the import function needs to be rewritten to fill the database with the right data format)
- the inverse model will be run all recognised spectra.
- the finetuning will be run on the resulting parameters.
- the fits will be outputted as a png (plot) and as a CSV (for publication quality plotting),
and the circuit parameters extracted by these processes will be outputted to a CSV file
where each row represents a different impedance spectrum. Three sets of parameters are given.
- The parameters produced by the inverse model.
- The parameters produced by finetuning.
- The difference between the two. (this is a proxy for the uncertainty in those fitting parameters.)
the command to be run, from the root of the project: python manage.py eis_main --mode=import_process_output --logdir=OnePercentTraining --input_dir=RealData\EIS --dataset=USER7 --output_dir=OutputData10
this will look in the folder RealData/EIS for the spectra. it will process all the data and record it under a "dataset" called USER7. It will then output the results in a folder called OutputData10
If this command is run on different data with the same option for --dataset, the data will be stored in the same place and outputted all at once.
If you want separate outputs, use different dataset options (i.e. --dataset=USER7 the first time and --dataset=USER8 the second time)
So far, the system knows about 3 file formats:
- MPT (extension .mpt)
- DAHN_TXT (extension .txt)
- COLUMBIA_TXT (extension .txt)
See the various files:
- MPT_example.mpt
- DAHN_TXT_example.txt
- COLUMBIA_TXT_example.txt
To use a specific file_format, for instance COLUMBIA_txt, add --file_format=COLUMBIA_txt.
Furthermore, one can use different versions of the inverse_model. The model itself is contained in a folder. By default, a model which used only one percent of the data to train is provided in OnePercentTraining. To use a different model, replace --logdir=OnePercentTraining with --logdir=TenPercentTraining for instance.
The output contains the original spectra, as well as the fitted versions, but there is the option to represent impedance as a function of either
- Frequency (Hz) or (simply add --no-angular-freq as an option)
- Angular Frequency (rad/s) (simply add --angular-freq as an option)
for instance, to get angular frequency on the previous data: python manage.py eis_main --mode=import_process_output --logdir=OnePercentTraining --angular-freq --output_dir=OutputData10 --input_dir=RealData\EIS --dataset=USER7
For visual reference of the equivalent circuits available, see UserManual/manual.pdf
By default, the equivalent circuit used has 3 ZARC components, and it does not have an inductance nor does it have a zarc inductance. If a different number of ZARC components are desired (e.g. 2), simply add e.g. --num_zarcs=2. this would give python manage.py eis_main --mode=import_process_output --logdir=OnePercentTraining --input_dir=RealData\EIS --dataset=USER7 --output_dir=OutputData10 --num_zarcs=2
-
If an inductance is desired, simply pass --inductance
-
If a zarc inductance is desired, simply pass --zarc-inductance These can both be passed if both components are desired.
-
If the warburg element (modelling diffusion) should be nested within the low frequency ZARC (the ZARC element becoming a parallel circuit of a CPE in parallel with a serial circuit of a resistor with the warburg element in series), simply pass --warburg_inception For instance, if you would like a zarc_inductance, 1 electrochemical ZARC, with the warburg nested inside, you would use: python manage.py eis_main --mode=import_process_output --logdir=OnePercentTraining --input_dir=RealData\EIS --dataset=USER7 --output_dir=OutputData10 --num_zarcs=1 --zarc_inductance --warburg_inception
- OnePercentTraining contains a pretrained model.
- EIS contains code
- EIS/models.py defines how the dataset is stored.
- EIS/management/commands/eis_main.py is where the code functionality is defined
- .gitattributes can be ignored
- .gitignore can be ignored
- db.sqlite3 holds the data provided by the user. The program handles interactions with this file. Please leave alone.
- LICENSE contains the license
- manage.py is the entry point for the program.
- requirements.txt contains the requirements.
First, this requires Python 3.7.4, with 64-bit support, (for windows ) or Python 3.6.8 with 64-bit support (for linux) Then, you can install the required libraries (see next subsections)
to install the required libraries in the recommended configuration, simply run the following on the command line: pip install -r requirements.txt
note that you must first navigate in the command line to be in the directory where this README resides.