Supercap-analysis 2.3

A python library for GCD analysis of supercapacitors

Table of content

• Introduction
• Installation
• Documentations

---

Introduction

This is a Python library for analysis for the Galvanostatic Charge Discharge (GCD) curves as well as the Cyclic Voltammetry (CV) curves of two-electrode, symmetrical supercapacitors. It provides an easy and standardised way to quickly extract useful information from the GCD and CV data, including the capacitance and the ESR of the supercapacitor and how they evolve over cycles, with multiple options offered to suit the need of scientific investigations of supercapacitors.

For GCD analysis, the capacitance is calculated via linear fitting the second half of the discharging slope in each charging/discharging cycle. For gravimetric capacitance ():

For non-gravimetric capacitance (F):

The ESR (Ω) is calculated using the voltage drop:

An illustration of how the GCD data is analysed is shown below:

For CV analysis, the capacitance is calculated via integration of the area enclosed by current as the voltage scanned across the potential window. For gravimetric capacitance ():

An illustration of how the CV data is analysed is shown below:

image to be added

---

Installation

Please follow the instruction under the 'code' tab.

Alternatively, use(https://pypi.org/project/Supercap-analysis/):

pip install Supercap-analysis

---

Documentations

This python library offers means to analyse GCD data in the format of text files, which can be directlt exported from electrochemistry software such as EC Labs. The file has to have two and only two coloumns of data, with the first coloumn being time (s), and the second coloumn being Voltage (V). (It is intended to extended the code to enable loading from csv files and/or files with multiple coloumns of data). The documentation includes two parts: means for loading data into the Supercap class and methods within the Superclass.

GCD analysis

Loading data

• Load_capacitor
• Glob_analysis

Supercap class

• init
• repr
• ESR_method_change
• Show_dV2
• Cap_vs_cycles
• Get_info
• Check_analysis

CV analysis

• CV_analysis

---

---

Load_capacitor(pathway, t_set = False, V_set = False, delimiter = False, mass_ls = False, current = False, row_skip = False, ESR_method = True, setting = False, cap_method = False, cap_grav = True)

This function loads the txt/csv file specified on the pathway into the Supercap class ,where capacitance and ESR analysis will be carried out. All relevant information can be extracted from the init function.

Notes

---

This function supports electrochemical data in either txt or csv format. In a txt file, it is by default that the first coloumn of the file is assumed to be time (s), and the second coloumn is assumed to be Voltage (V) for the GCD analysis. The two coloumns are assumed to be seperated by space. However, the optional arguments, t_set, V_set, delimeter and row_skip, offers flexibility in dealing with more complex data files.

Parameters

---

Arguments

1. pathway : file, str, or pathlib.Path
   File, filename of the text file to read. Note that if the library is not allocated in the same directory as the file, the pathway to the file has to be given. For current=False, current will be directly read from the filename (i.e. the fielname has to include the current followed by 'mA' and seperated by '', '/' or it is the first component of the filename). If current information cannot be obtained from the filename, the current has be specified via the current argument. For more details, refer to the Examples section. This function currently only supports data in the format of txt or csv.

2. t_set : int/str(csv files only), optional
   An integer specifying the coloumn index for time(s) data, with the first coloumn being coloumn 0 starting from left. If t_set = False, column 0 will be used as time(s); if t_set = False, there will be prompt asking for time coloumn index to be entered.For csv files, the coloumn index can also be the name of the coloumn (e.g. t_set = 'time(s)').

3. V_set : int/str(csv files only), optional
   An integer specifying the coloumn index for voltage(V) data, with the first coloumn being coloumn 0 starting from left. If V_set = False, column 1 will be used as Voltage(V); if t_set = False, there will be prompt asking for voltage coloumn index to be entered. For csv files, the coloumn index can also be the name of the coloumn (e.g. V_set = 'voltage(V)').

4. delimiter : str, optional
   A string which is used to seperate the data coloumns in the data file. If delimiter = False, the delimiter is assumed to be space ' '.

5. mass_ls : list, [[measurements of m1], [measurements of m2]], optional
   A list specifying the mass of each electrode in the format as shwon above. Multiple measurements for each electrode should be included for calculation of the uncertainty of the data. All masses should be recorded in mg. If mass_ls = False, a non-gravimetric capacitanc will be calculated and the function returns [[False, False], [False, False]] for the .masses method in the resulting Supercap entity (more details for extracting data from the Supercap class in Supercap class>>init

6. current : float, optional
   If current = False, the current value will be directly read from the filename given that it is supplied in the format as specified above in the pathway section. If the current is not included the filename, it should be specified in the form of current =specified_current

7. row_skip : int, optional
   Number of the rows of headers to skip in the txt files. If row_skip = False, row_skip = 1; if row_skip = True, a prompt will ask for rows to skip for the file. Enter row_skip = 0 if no rows need to be skipped.

8. ESR_method : int, optional
   The method for ESR analysis. It is by default (ESR_method = True) that the ESR analysis will be carried out using method 2 (constant derivative). For all methods available please refer to the next session ESR_method table. ESR_setting = False will return .esr_ls as False in the Supercap class. Available ESR_methods are: ESR_methods = True, False, 1, 101, 2, 201.

9. setting : float, optional
   For ESR_methods = True, 1, or 2 , setting = False. For ESR_methods = 101 or 201 , setting is required as the number of points n/second derivative cut off point needed for the constant point method and the constant derivative method, respectively. If ESR_methods = 101 or 201 but setting = False, the function will promt the user to choose a specific value for the ESR analysis before proceeding.

10. cap_method : int, optional
    The method for capacitance analysis which determines whether the upper (cap_method = 2) or lower (cap_method = 1) half of the voltage range of the discharging curve will be used. By default cap_set = False and the program uses the lower half of the discharging curve. For detailed information please refer to the cap_method table below.

11. cap_grav : bool, optional
    It is by default that the gravimetric capacitance is calculated. By using cap_grav = False or mass_ls = False , a non-gravimetric capacitance will be calculated.

ESR_method

Method	Description
True	Default Method 2
False	Returning ESR = False (no ESR calculation)
1	Default Method 1. dV is calculatied using the voltage difference between the peak voltage and the fourth data point taken after the peak voltage is reached
101	This method prompts the user to enter an interger n, where dV is determined between the peak voltage and the voltage of the nth points after the peak voltage
2	Default Method 2. dV is calculatied using the voltage difference between the peak voltage and the smallest data point where the second derivative greater than 0.01 (the second derivative decreases during teh discharging process)
201	This method prompts the user to enter a float x, where dV is determined between the peak voltage and the voltage of the smallest data point with second derivative over x

cap_method

Method	Description
False/1	Default Method. The lower half of the discharging curve is fitted for capacitance calculation.
2	The upper half of the discharging curve is fitted for capacitance calculation.

Returns

out: Supercap

A Supercap entity generated from the text file

Examples

---

>>>Load_capacitor('./GCD/3.0_mA_1.0V_010120.txt', ESR_method = 201)
Please enter the number of header row(s) in this file:
>>>0
Please specify a cut-off derivative (the default value is 0.01)
>>>0.1
<Class_Supercap: 3.0 mA, 1.0 V, 5 cycles, ESR method 201>

>>>Load_capacitor('./GCD/3.0_1.0V_010120.txt', t_set = 1, V_set = 3, mass_ls = [[12,13,12.2], [11, 10.5, 11.6]], current = 3, ESR_method = 2, setting = 0.1)
<Class_Supercap: 3.0 mA, 1.0 V, 5 cycles, ESR method 2>

---

---

Glob_analysis(path, t_set = False, V_set = False, delimiter = False, mass_ls = False, row_skip = False, ESR_method = True, setting = False, cap_method = False, plot_set = False, plot_save = True)

Loading all txt/csv files in the folder as specified in path. Good for analysing how capacitance changes with current density.

Notes

---

1. Capacitance and ESR analysis for one supercapacitor under different currents.
2. Error bars are calculated from the mass errors of the electrodoes as other errors are insignificant compared to that caused by mass.
3. The masses in mass_ls is in mg.
4. It is assumed that all data files in the folder are measured from the same capacitor, hence they all have the same mass_ls.
5. The current has to be included in the file name in the current format as specified under Parameters >> path

Parameters

---

Arguments

1. path : file, str, or pathlib.Path
   File, filename of the text file to read. Note that if the library is not allocated in the same directory as the file, the pathway to the file has to be given. For current=False, current will be directly read from the filename (i.e. the fielname has to include the current followed by 'mA' and seperated by '', '/' or it is the first component of the filename). For more details, refer to the Examples section.

2. t_set : int/str(csv files only), optional
   An integer specifying the coloumn index for time(s) data, with the first coloumn being coloumn 0 starting from left. If t_set = False, column 0 will be used as time(s); if t_set = True, there will be prompt asking for time coloumn index to be entered.For csv files, the coloumn index can also be the name of the coloumn (e.g. t_set = 'time(s)').

3. V_set : int/str(csv files only), optional
   An integer specifying the coloumn index for voltage(V) data, with the first coloumn being coloumn 0 starting from left. If V_set = False, column 1 will be used as Voltage(V); if t_set = True, there will be prompt asking for voltage coloumn index to be entered. For csv files, the coloumn index can also be the name of the coloumn (e.g. V_set = 'voltage(V)').

4. delimiter : str, optional
   A string which is used to seperate the data coloumns in the data file. If delimiter = False, the delimiter is assumed to be space ' '.

5. mass_ls : list, [[measurements of m1], [measurements of m2]], optional
   A list specifying the mass of each electrode in the format as shwon above. Multiple measurements for each electrode should be included for calculation of the uncertainty of the data. All masses should be recorded in mg. If mass_ls = False, a non-gravimetric capacitanc will be calculated and the function returns [[False, False], [False, False]] for the .masses method in the resulting Supercap entity (more details for extracting data from the Supercap class in Supercap class >> init

6. row_skip : int, optional
   Number of the rows of headers to skip in the txt files. If row_skip = False, row_skip = 1; if row_skip = True, a prompt will ask for rows to skip for the file. Enter row_skip = 0 if no rows need to be skipped.

7. ESR_method : int, optional
   The method for ESR analysis. It is by default (ESR_method = True) that the ESR analysis will be carried out using method 2 (constant derivative). For all methods available please refer to the next session ESR_method. ESR_setting = False will return .esr_ls as False in the Supercap class. Available ESR_methods are: ESR_methods = True, False, 1, 101, 2, 201.

8. setting : float, optional
   For ESR_methods = True, 1, or 2 , setting = False. For ESR_methods = 101 or 201 , setting is required as the number of points n/second derivative cut off point needed for the constant point method and the constant derivative method, respectively. If ESR_methods = 101 or 201 but setting = False, the function will promt the user to choose a specific value for the ESR analysis before proceeding.

9. cap_method : bool, optional
   The method for capacitance analysis which determines whether the upper (cap_method = 2) or lower (cap_method = 1) half of the voltage range of the discharging curve will be used. By default cap_set = False and the program uses the lower half of the discharging curve. For detailed information please refer to the cap_method table below.

10. plot_set : bool, optional
    Figure parameters for plotting. If plot_set = False, the defualt settings will be used. If plot_set = True, there will be prompts to allow customised settings for plotting.

11. plot_save : bool, optional
    This argument determines whether the capacitance vs. current density plot will be plotted and saved. It is by default that plotting = True , and the figure will be plotted and saved as 'Gravimetric specific capacitance vs. current density [datetime].png'. If plotting = False , the figure will not be plotted and saved.

ESR_method

Method	Description
True	Default Method 2
False	Returning ESR = False (no ESR calculation)
1	Default Method 1. dV is calculatied using the voltage difference between the peak voltage and the fourth data point taken after the peak voltage is reached
101	This method prompts the user to enter an interger n, where dV is determined between the peak voltage and the voltage of the nth points after the peak voltage
2	Default Method 2. dV is calculatied using the voltage difference between the peak voltage and the smallest data point where the second derivative greater than 0.01 (the second derivative decreases during teh discharging process)
201	This method prompts the user to enter a float x, where dV is determined between the peak voltage and the voltage of the smallest data point with second derivative over x

Returns

out: list

[[list of current density],[list of Supercap objects]]

Examples

---

>>>Glob_analysis('./various_mA_folder/*.txt', mass_ls = [[12,13,12.2], [11, 10.5, 11.6]], row_skip = 1, ESR_method = 2, plotting = False)
[[0.001, 0.003, 0.005],
[<Class_Supercap: 1.0 mA, 1.0 V, 5 cycles, ESR method 2>,
 <Class_Supercap: 2.0 mA, 1.0 V, 7 cycles, ESR method 2>,
 <Class_Supercap: 3.0 mA, 1.0 V, 5 cycles, ESR method 2>,]]

---

---

init(self, current, t_V_ls, masses, cap_ls, esr_ls, extrema, cycle_n, m_error, ESR_method, cap_method, faulty_cycles)

Initialize a :class:.Supercap.

Notes

---

Stores all relevant information for the capacitance/ESR analysis of the supercapacitor. All current values are in mA and mass values are in mg.

Available parameters that can be extracted include:

1. .current
2. .masses
3. .t_ls
4. .V_ls
5. .cap_ls
6. .esr_ls
7. .cycle_n
8. .error
9. .peaks
10. .troughs
11. .esr_method
12. .cap_method
13. .faulty_cycles

The above method follows the name of the Supercap variable. More details in the example section.

Parameters

---

Arguments

1. current : float
   Current at which the GCD analysis is undertaken. The current is in mA.

2. t_V_ls : list, [[list of time readings], [list of voltage readings]]
   The raw data of the GCD analysis.

3. masses : list, [[average mass of m1, std of m1], [average mass of m2, std of m2]]
   The mass measurements for the two electrodes. The mass is in mg.

4. cap_ls : list, [list of calculated capacitance for each cycle]
   The calculated capacitance for each cycle.

5. esr_ls : list, [list of calculated ESR value for each cycle]
   The calculated ESR values for each cycle.

6. extrema : list, [[peak indices], [trough indices]]
   The indices for the peaks and troughs of the voltage readings.

7. cycle_n : int
   The indices for the peaks and troughs of the voltage readings.

8. m_error : list, [list of uncertainties]
   The uncertainty for each calculated capacitance value.

9. ESR_method : int
   The method for ESR analysis. ESR_method = 1/102/2/202

10. cap_method : int
    The method for capacitance analysis. cap_method = 1/2

11. faulty_cycles : list, [list of faulty cycle numbers]
    A list of cycle numbers for the faulty cycles.

Examples

---

>>>supercap1.current #supercap1 is a Supercap class variable.
0.5
>>>supercap1.masses 
[[10.2, 0.0912], [12.1, 0.0853]]

repr(self)

Initialize a :class:.Supercap.

Returns

---

Returns a string which state the current, maximum voltage and number of cycle analysed in the Supercap class.

Examples

---

>>>Supercap1
<Class_Supercap: 3.0 mA, 1.0 V, 5 cycles, ESR method 2>

---

---

ESR_method_change(self, ESR_method = True, setting = False)

Initialize from a :class:.Supercap.

Notes

---

Changing the ESR analysis method used for calculating esr_ls.

Parameters

---

Arguments

1. ESR_method : int, optional
   The method for ESR analysis. It is by default (ESR_method = True) that the ESR analysis will be carried out using method 2 (constant derivative). For all methods available please refer to the next session ESR_method. ESR_setting = False will return .esr_ls as False in the Supercap class. Available ESR_methods are: ESR_methods = True, False, 1, 101, 2, 201.

2. setting : float, optional
   For ESR_methods = True, 1, or 2 , setting = False. For ESR_methods = 101 or 201 , setting is required as the number of points n/second derivative cut off point needed for the constant point method and the constant derivative method, respectively. If ESR_methods = 101 or 201 but setting = False, the function will promt the user to choose a specific value for the ESR analysis before proceeding.

ESR_method

Method	Description
True	Default Method 2
False	Returning ESR = False (no ESR calculation)
1	Default Method 1. dV is calculatied using the voltage difference between the peak voltage and the fourth data point taken after the peak voltage is reached
101	This method prompts the user to enter an interger n, where dV is determined between the peak voltage and the voltage of the nth points after the peak voltage
2	Default Method 2. dV is calculatied using the voltage difference between the peak voltage and the smallest data point where the second derivative greater than 0.01 (the second derivative decreases during teh discharging process)
201	This method prompts the user to enter a float x, where dV is determined between the peak voltage and the voltage of the smallest data point with second derivative over x

Returns

out: :class:.Supercap

self.esr_ls

Examples

---

>>>Supercap1
<Class_Supercap: 1.0 mA, 1.0 V, 5 cycles, ESR method 2>

>>>Supercap1.ESR_method_change(ESR_method = 101, setting = 201, setting =1)
>>>Supercap1
<Class_Supercap: 1.0 mA, 1.0 V, 5 cycles, ESR method 201>

---

---

Show_dV2(self, cycle_check = False)

Initialize from a :class:.Supercap.

Notes

---

Visualising the second derivative and the charge/discharge curve of a specified cycle with the option of changing the ESR analysis method used for calculating esr_ls. It is assumed that ESR_method = 201 is used in this function.

Parameters

---

Arguments

1. Cycle_check : int, optional
   The method for ESR analysis. Specify the cycle of the charge/discharge curve and the second derivative to be plotted on the same axes.If Cycle_check = False, the user will be prompted to select a cycle on the CD curve to view as the reference for adjusting the cut off point.

Returns

1. A plot of charge discharge curve and the corresponding second derivative
   
2. :class:.Supercap, optional

self.esr_ls

Examples

---

>>>Supercap1
<Class_Supercap: 3.0 mA, 1.0 V, 5 cycles, ESR method 2>
>>>Supercap1.Show_dV2()
Of which cycle would you like to see the second derivative? enter a number between 0 and 9
>>>0
The cut off second derivative currently being used is 0.002

Are you happy with the cut off point? (yes/no)
>>>no
Please input the value of desired cut off second derivative.
>>>1

Are you happy with the cut off point? (yes/no)
>>>yes
Do you wish to change the cut off point to the current value? (setting =1.0)[yes/no]
>>>yes
>>>Supercap1
<Class_Supercap: 3.0 mA, 1.0 V, 5 cycles, ESR method 201>

---

---

Cap_vs_cycles(self, set_fig=False, save_fig=False)

Initialize from a :class:.Supercap.

Notes

---

Plotting capacitance against cycle and saving it as 'current mA_cap_vs_cycles_datetime.png'

Parameters

---

Arguments

1. set_fig : bool, optional
   If set_fig = True, the user will be prompted to change the setting of the figure.

2. save_fig : bool, optional
   If save_fig = True, the figure will be saved under the name '[current] mA_cap_vs_cycles_Date[d/m]_Time[h/m].png'

Returns

A figure of capacitance over cycle number

Examples

---

>>>Supercap1.Cap_vs_cycles(set_fig = True)
Please input length for the figure:
>>>30
Please input width for the figure:
>>>20
Please input the font size for the figure:
>>>45
Please input the line width for the figure:
>>>7
Please input the line colour for the figure:
>>>'black'

---

---

Get_info(self)

Initialize from a :class:.Supercap.

Notes

---

Printing the basic information of the Supercap class

Parameters

---

Arguments

None

Returns

out::class:string, optional

The number of cycles, the average capacitance, the std of capacitance, the average ESR and its std, the ESR_method and cap_method used.

Examples

---

>>>Supercap1.Get_info()
'The number of cycle(s) analysed is 9'
'The average capacitance is 24.028444381438409'
'The standard deviation of the average is 0.553348977252065'
'The average ESRs is 11.724686851851855'
'The standard deviation of the ESRs is 0.023315957315381737'
'Lower half of the voltage range in the discharge curve was used for capacitance calculations'
'Constant second derivative method was used for ESR calculations'

---

---

Check_analysis(self, begin = False, end = False, set_fig = False, save_fig = False)

Initialize from a :class:.Supercap.

Notes

---

Plotting the charge/discharge curve and visualising how the data is analysed (indicate the slope fitting for capacitance and the voltage drop for ESR).

Parameters

---

Arguments

1. begin : int, optional
   

   The first cycle to be visualised. For begin = False , the user will be prompted to choose the first cycle to be visualised.

2. end : int, optional
   

   The last cycle to be visualised. For end = False , the user will be prompted to choose the last cycle to be visualised.

3. set_fig : bool, optional
   If set_fig = True, the user will be prompted to change the setting of the figure.

4. save_fig : string, optional
   

   For save_fig=False, the plot will not be saved.

   For save_fig=True, the plot will be saved as 'Check_analysis_[datetime].png'.

Returns

A plot of the charge/discharge curve with liniearly fitted slope and voltage drop.

Examples

>>>Supercap1.Check_analysis(begin = 0, end = 4, save_fig = False)

---

---

CV_analysis(pathway, m1, m2, scan_r = False, row_skip = False, x_name = False, y_name = False, delimiter = False, int_method = False)

Under construction...coming soon! This function loads the txt/csv file specified on the pathway, where capacitance analysis on the Cyclic Voltammetry will be carried out. The function returns a list of capacitance calculated from each CV cycle.

Notes

---

This function supports electrochemical data in either txt or csv format. In a txt file, it is by default that the first coloumn of the file is assumed to be voltage (V), and the second coloumn is assumed to be current (mA) for the GCD analysis. The two coloumns are assumed to be seperated by space. However, the optional arguments, x_name, y_name, delimeter and row_skip, offers flexibility in dealing with more complex data files.

Parameters

---

Arguments

1. pathway : file, str, or pathlib.Path
   File, filename of the text file to read. Note that if the library is not allocated in the same directory as the file, the pathway to the file has to be given. For scan_r=False, current will be directly read from the filename (i.e. the fielname has to include the current followed by 'mvs' and seperated by '', '/' or it is the first component of the filename). If scan rate information cannot be obtained from the filename, the scan rate has to be specified via the current argument. For more details, refer to the Examples section. This function currently only supports data in the format of txt or csv.

2. m1 : float, optional
   The mass of electrode 1 of the supercapacitor. The mass is in mg.

3. m2 : float, optional
   The mass of electrode 2 of the supercapacitor. The mass is in mg.

4. scan_r : float, optional
   If scan_r = False, the scan rate value (mV/s) will be directly read from the filename given that it is supplied in the format as specified above in the pathway section. If the current is not included the filename, it should be specified in the form of scan_r =specified_scan_rate

5. row_skip : int, optional
   Number of the rows of headers to skip in the txt files. If row_skip = False, row_skip = 1; if row_skip = True, a prompt will ask for rows to skip for the file. Enter row_skip = 0 if no rows need to be skipped.

6. x_name : int/str(csv files only), optional
   An integer specifying the coloumn index for voltage(V) data, with the first coloumn being coloumn 0 starting from left. If x_name = False, column 0 will be used as voltage(V); if x_name = True, there will be prompt asking for scan rate coloumn index to be entered.For csv files, the coloumn index can also be the name of the coloumn (e.g. x_name = 'voltage(V)').

7. y_name : int/str(csv files only), optional
   An integer specifying the coloumn index for voltage(V) data, with the first coloumn being coloumn 0 starting from left. If y_name = False, column 1 will be used as current(mA); if y_name = True, there will be prompt asking for current coloumn index to be entered. For csv files, the coloumn index can also be the name of the coloumn (e.g. y_name = 'current(mA)').

8. delimiter : str, optional
   A string which is used to seperate the data coloumns in the data file. If delimiter = False, the delimiter is assumed to be space ' '.

5. int_method : int, optional
   The method for integration of the enclosed area. It is by default (int_method = False) that the ESR analysis will be carried out using method 2 (constant derivative). For all methods available please refer to the next session int_method table.

int_method

Method	Description
False or 1	Default method. Integration using the trapezoidal rule and integrates over discharging curve only.
101	Integration using the trapezoidal rule and integrates over both the charging and discharging curves.
2	Integration using the Simpson's rule and integrates over discharging curve only.
202	Integration using the Simpson's rule and integrates over both the charging and discharging curves.

Returns

out: [list of calculated gravimetric capacitance]

Examples

---

>>>Load_capacitor('../cell1_CV/1.2V_CA2.csv', m1=10, m2=9, scan_r=1, x_name = 'voltage', y_name ='current',delimeter=',', int_method=1)
4  CV cycles are being analysed using integration method 1
[86.30233646681373, 88.433682993075, 89.45296144982, 90.0191569583757]