The echemsuite.cellcycling.experiments sub-module

The RateExperiment class

class echemsuite.cellcycling.experiments.RateExperiment(current_steps=None, cellcycling_steps=None)

The RateExperiment class provides a simple interface to charge rate experiments in which a cell is charged and discharged at different constant current values and the voltage and charge time are recorded and monitored. The class can be constructed manually, using the default __init__ method, providing the list of single current steps and the list of cell-cycling experiments carried out at a given current. The class can also be constructed using the from_Biologic_battery_module classmethod that is setup to be able to directly parse Biologic modules sequences.

Parameters:

• current_steps (List[float]) – The list of current steps associated to each cell-cycling sequence.

• cellcycling_steps (List[CellCycling]) – The list of cellcycling object encoding the electrochemical data collected at various current steps.

Raises:

RuntimeError – Exception raised if a mismatch between the length fo the two lists has been detected.

append(object_rate_exp)

Concatenate to the current object the rate experiments datapoints provided by a second RateExperiment object

Parameters:

• object (RateExperiment) – The rate experiment object providing the data to be included in the current experiment dataset

• object_rate_exp (RateExperiment) –

Return type:

None

property average_power: List[float]

The Average power (in W) for the discharge half-cycle of all the cycles in the experiment.

Returns:

the average power value for all the discharge half-cycles.

Return type:

List[float]

property capacity: List[float]

List of all the capacities (in mAh) for the discharge half-cycle objects of all the cycles in the experiment.

Returns:

the discharge capacity of the cell observed during all the half-cycle in the experiment.

Return type:

List[float]

property capacity_retention: List[float]

List of capacity retentions calculated as the ratios between the discharge capacity at cycle n and the discharge capacity of the reference cycle. To change the reference cycle, set the reference property.

Returns:

The list of float values encoding the capacity retention of each step in the experiment in respect to the selected reference datapoint.

Return type:

List[float]

property coulomb_efficiencies: List[float]

List of all the coulombic efficiencies associated to the experimental datapoints. The list contains all the steps contained in all the cell-cycling experiments. Coulombic efficiency of the cycle computed according to \(100 \cdot Q_{\mathrm{discharge}}/ Q_{\mathrm{charge}}\) where \(Q_{\mathrm{charge}}\) and \(Q_{\mathrm{discharge}}\) represent the capacity of the charge and discharge cycle respectively.

Returns:

List of all the columbic efficiencies values associated to each datapoints of the experiment.

Return type:

List[float]

property current_steps: List[float]

Returns an array containing the current values associated with each cycle in the experiment

Returns:

A simple array with a progressive number for all datapoints.

Return type:

List[float]

property cycles: List[Cycle]

Returns the array containing all the cycles object associated to each current step

Returns:

A simple array containing the sequece of Cycle objects associated to each explored current value

Return type:

List[Cycle]

dump_to_excel(path, volume, area)

Dump an excel report containing all the information associated with the experiment.

Parameters:

• path (str) – The path in which the .xlsx file will be saved.

• volume (float) – The electrolyte volume to be used in computing the volumetric densities.

• area (float) – The electrode area to be used in the calculatrion of densities values.

Return type:

None

property energy_efficiencies: List[float]

List of all the energy efficiencies associated to the experimental datapoints. The list contains all the steps contained in all the cell-cycling experiments. Energy efficiency of the cycle computed according to \(100 \cdot E_{\mathrm{discharge}}/ E_{\mathrm{charge}}\) where \(E_{\mathrm{charge}}\) and \(E_{\mathrm{discharge}}\) represent the total energy associated to the charge and discharge cycle respectively.

Returns:

List of all the energy efficiencies values associated to each datapoints of the experiment.

Return type:

List[float]

classmethod from_ARBIN_csv_file(csv_path, variation_threshold=1.0, current_digits=3)

Classmethod dedicated to the construction of a RateExperiment object starting from a ARBIN csv file. Please notice that the ARBIN .csv files do not specify the current associated to each step explicitly, as such the average current per halfcycle will be used in the definition of the various rate steps. The division of the cell-cyclicing objects in different rate steps is generated automatically by the method using a fixed percentage threshold value. When the percentage variation threshold is exceeded the cell-cycling object is moved to a new current step. The current steps of the experiments are computed automatically as averages and rounded to a user specified number of digits (default: 3)

Parameters:

• csv_path (str) – The path to the .csv file generated from the ARBIN battery cycler.

• variation_threshold (float) – The threshold (in percentage) to be used in the indetification of a new current step (default: 1%).

• current_digits (int) – Number of digits to be kept in saving the average current values computed form the data-files (default: 3).

Raises:

ValueError – Exception raised if the sepcified path to the datafile is invalid.

Return type:

RateExperiment

classmethod from_Biologic_battery_module(path)

Classmethod dedicated to the construction of a RateExperiment object starting from a Biologic battery module file.

Parameters:

path (str) – The path to the Biologic battery module file.

Raises:

ValueError – Exception raised if the sepcified path to the datafile is invalid.

Return type:

RateExperiment

classmethod from_GAMRY_folder_tree(basefolder, current_digits=3)

Classmethod dedicated to the construction of a RateExperiment object starting from a folder tree generated by GAMRY instruments during multi-step cycling experiments. The folder structure expected is the following: a basefolder containing a set of step data-folders (with variable names) each of which contains a CHARGE_DISCHARGE folder containing the desired .DTA files encoding the charge/discharge cell-cycling at a given current. The current steps of the experiments are computed automatically as averages and rounded to a user specified number of digits (default: 3)

Parameters:

• basefolder (str) – The path to the basefolder containing the data-folders for each step.

• current_digits (int) – Number of digits to be kept in saving the average current values computed form the data-files (default: 3).

Raises:

• ValueError – Exception raised if the specified basefolder does not exist

• RuntimeError – Exception raised if no cell-cycing data is found in the specified path.

Return type:

RateExperiment

property numbers: List[int]

Returns a simple array with a progressive number for all datapoints.

Returns:

A simple array with a progressive number for all datapoints.

Return type:

List[int]

property reference: Tuple[int, int]

The reference datapoint in respect to which the capacity retention will be computed.

Returns:

The tuple of two integer values the first of which indicates the cell-cycing experiment to which the datapoint belongs to, while the second one represents the point within the selected cell-cycling sequence.

Return type:

Tuple[int, int]

property total_energy: List[float]

List of all the energies values (in mWh) for the discharge half-cycle objects of all the cycles in the experiment.

Returns:

the discharge energy of the cell observed during all the half-cycle in the experiment.

Return type:

List[float]

property voltage_efficiency: List[float]

List of all the voltaic efficiencies associated to the experimental datapoints. The list contains all the steps contained in all the cell-cycling experiments. Voltaic efficiency of the cycle computed according to \(\eta_{E}/\eta_{Q}\) where \(\eta_{E}\) represents the energy efficiency of the cycle while \(\eta_{Q}\) represent the correspondent coulombic efficiency.

Returns:

List of all the voltaic efficiencies values associated to each datapoints of the experiment.

Return type:

List[float]