The `echemsuite.cellcycling.cycles` sub-module

The `HalfCycle` class

class echemsuite.cellcycling.cycles.HalfCycle(time, voltage, current, halfcycle_type, timestamp)

The HalfCycle class stores the data relative to either a charge or a discharge half-cycle and esposes to the user all the relevant derived observables such as accumulated/depleted charge and energy, istantaneous power, total capacity of the cell and total energy stored.

Parameters:

time (pandas.core.series.Series) – pandas Series containing time-step data (in s)
voltage (pandas.core.series.Series) – Series containing voltage data (in V)
current (pandas.core.series.Series) – Series containing current data (in A)
halfcycle_type (str) – Should either be “charge” or “discharge”
timestamp (datetime.datetime) – The timestam indicating the start of the data acquisition process or other time labels useful in indicating the cronological sequence of halfcycles

Raises:

ValueError – if the halfcycle_type does not match any of the accepted values

property Q: Series

Series containing the cumulative charge data points (in mAh) computed at each time-step by the calculate_Q() function.

Returns:: the cumulative charge for each time-step in (mAh)
Return type:: pandas.core.series.Series

property average_power: float

The Average power (in W) for the selected half-cycle.

Returns:: the average power value.
Return type:: float

calculate_Q()

Calculate the capacity C (mAh) of the charge/discharge half-cycle as the accumulated/depleted charge over time. Please notice ho the values are given without any sign.

Returns:

pandas.core.series.Series – the cumulative capacity data points (in mAh) for the half-cycle
float – the total capacity of the cell (last point of the cumulative capacity series)

Return type:

Tuple[Series, float]

calculate_energy()

Calculate the istantaneous power (in W), the instantaneous energy (in mWh) and the total energy E (mWh) of the half-cycle. Please notice ho the values are given without any sign.

Returns:

pandas.core.series.Series – the instantaneous power adsorbed/generated by the cell (in W) at each time-step
pandas.core.series.Series – the instantaneous energy adsorbed/generated by the cell (in mWh) at each time-step
float – the total energy excanged by the cell (last point of the cumulative sum of the energy series)

Return type:

Tuple[Series, Series, float]

property capacity: float

Capacity (in mAh) for the half-cycle object, calculated as the total accumulated charge by the calculate_Q() function.

Returns:: the capacity of the cell observed during the half-cycle
Return type:: float

property current: Series

Series containing the current data points (in A) for the selected half-cycle

Returns:: the current series originally given as argument to the class constructor
Return type:: pandas.core.series.Series

property energy: Series

Series containing the instantaneous energy data points (in mWh) for the selected half-cycle as computed by the calculate_energy() function.

Returns:: the instantaneous energy for each time-step in (mWh)
Return type:: pandas.core.series.Series

property halfcycle_type: str

The type of the half-cycle object

Returns:: a string set to either “charge” or “discharge”
Return type:: str

property power: Series

Series containing the instantaneous power data points (in W) for the selected half-cycle as computed by the calculate_energy() function.

Returns:: the instantaneous power for each time-step in (W)
Return type:: pandas.core.series.Series

property time: Series

pandas Series containing the time data points (in s) for the half-cycle object

Returns:: the time series originally given as argument to the class constructor
Return type:: pandas.core.series.Series

property timestamp: datetime

Timestamp reporting the date and time at which the measurment was collected. (both getter and setter are provided)

Returns:: the datetime object reporting the timestamp associated to the measurment
Return type:: datetime.datetime

property total_energy: float

Total energy (in mWh) for the selected half-cycle, calculated as the total accumulated energy by the calculate_energy() function.

Returns:: the total energy exchanged by the cell in (mWh)
Return type:: float

property voltage: Series

Series containing the voltage data points (in V) for the selected half-cycle

Returns:: the voltage series originally given as argument to the class constructor
Return type:: pandas.core.series.Series

The `Cycle` class

class echemsuite.cellcycling.cycles.Cycle(number, charge=None, discharge=None)

The Cycle class contains both a charge and a discharge half-cycle. The class wraps the properties of the HalfCycle and defines the efficiencies associated to a charge/discharge cycle.

Parameters:

number (int) – a univocal index indicating the number of the charge/discharge cycle
charge (HalfCycle) – the charge half-cycle
discharge (HalfCycle) – the discharge halfcycle

Raises:

TypeError – if either one of the given charge/discharge half-cycles are of the wrong type

property Q: Series

pandas Series containing the accumulated charge data points (in mAh) for the complete cycle

Return type:: pandas.core.series.Series

calculate_efficiencies()

Computes the coulombic and energy efficiency of the cycle as the ratio between the discharge and charge energies, provided they exist.

Returns:: a tuple containing, in order, the coulomb efficiency, the energy efficiency and the voltaic efficiency. If either the charge or discharge capacity is found to be non-positive, the sentinel value o 101 will be returned.
Return type:: Tuple[float or None, float or None, float of None]

property charge: HalfCycle

The charge half-cycle

Return type:: HalfCycle

property coulomb_efficiency: float

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.

Return type:: float

property current: Series

pandas Series containing the current data points (in A) for the complete cycle

Return type:: pandas.core.series.Series

property discharge: HalfCycle

The discharge half-cycle

Return type:: HalfCycle

property energy: Series

pandas Series containing the instantaneous energy data points (in mWh) for the complete cycle

Return type:: pandas.core.series.Series

property energy_efficiency: float

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.

Return type:: float

property number: int

Cycle number

Return type:: int

property power: Series

pandas Series containing the instantaneous power data points (in W) for the complete cycle

Return type:: pandas.core.series.Series

property time: Series

pandas Series containing the time data points (in s) for the complete cycle

Return type:: pandas.core.series.Series

property voltage: Series

pandas Series containing the voltage data (in V) points for the complete cycle

Return type:: pandas.core.series.Series

property voltage_efficiency: float

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.

Return type:: float

The `CellCycling` class

class echemsuite.cellcycling.cycles.CellCycling(cycles)

The CellCycling class contains all the cycles associated to a given experiment. The class gives to user the possibility of computing properties describing the behavior of the system capacity/efficiency during multiple charge/discharge cycles. Every cycle can be included or excluded from the computation by toggling its hided/unhided state. The class offers a __getitem__ method returning the cycle corresponding to a given index and an __iter__ method yelding the complete set of not hiddend cycles. The __len__ method is set accordingly by returning the total number of non-hidden cycles.

Parameters:: cycles (List[Cycle]) – list of Cycle objects used to build the cellcycling sequence

reference

index of the cycle to be used as a reference in computing retentions properties

Type:: int

property capacity_fade: float

Percentual of capacity retention lost between two consecutive cycles. Please notice how this does not represent the total capacity fade.

Returns:: the value of capacity fade computing during the fitting operation performed by fit_retention().
Return type:: 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 (by default, first cycle). To change the reference cycle, set the reference property

Return type:: List[float]

property coulomb_efficiencies: List[float]

List of all the coulombic efficiencies associated to non-hidden cycles

Return type:: List[float]

property energy_efficiencies: List[float]

List of all the energy efficiencies associated to non-hidden cycles

Return type:: List[float]

property fit_parameters

Fitting parameters obtained from the linear fit of the capacity retention.

Returns:: fit_parameters – Result is an LinregressResult object with the following attributes: slope intercept rvalue pvalue stderr intercept_stderr
Return type:: LinregressResult instance

fit_retention(start, end)

Fits the currently available retention data with a linear fit. The routine used in the fitting process is the scipy.stats.linregress() function.

Parameters:

start (int) – starting cycle number for the fitting procedure
end (int) – ending cycle number for the fitting procedure

Return type:

None

hide(hide_indices)

Cycle masking/hiding feature. Prevents certain cycles from being used/shown in calculations.

Parameters:: hide_indices (List[int]) – list of indices to mask/hide
Return type:: None

property numbers: List[int]

Returns a list of all the available, not hidden, cycle numbers

Return type:: List[int]

predict_retention(cycle_numbers)

Predicts the retention for a given number of cycles, given the series of fit parameters computed by fit_retention().

Parameters:: cycle_numbers (List[int]) – list containing the cycle numbers for which you want to predict the retention
Returns:: predicted_retentions – list containing the predicted retention values
Return type:: List[float]

retention_threshold(thresholds)

Predicts, based on the linear fit parameters computed by fit_retention(), the cycle numbers for which the capacity retention reaches the threshold specified in the input list.

Parameters:: thresholds (List[float]) – list containing the retention thresholds for which you want to predict the cycle number
Returns:: predicted_thresholds – list containing the predicted cycle numers
Return type:: List[int]

property timestamp: datetime

The timestamp at which the measurement has been started. If the first cycle is complete, the timestamp will be that of its charge halfcycle else the timestamp of the discharge halfcycle will be returned.

Returns:: The timestamp object encoding the start of the measurement.
Return type:: datetime

unhide(unhide_indices)

Cycle unmasking/unhiding feature. Reinstate cycles from being used/shown in calculations.

Parameters:: unhide_indices (List[int]) – list of indices to unmask/unhide
Return type:: None

property voltage_efficiencies: List[float]

List of all the voltaic efficiencies associated to non-hidden cycles

Return type:: List[float]

The `join_HalfCycles` function

echemsuite.cellcycling.cycles.join_HalfCycles(join_list)

Join HalfCycle instances containing partial data into a single complete HalfCycle object following the order specified in the list. The timestamp of the resulting object will match the one associated with the first element of the list. The data are concatenated ignoring the input indeces. As such, the output object will have ordered series with a progressive index series.

Parameters:: join_list (List[HalfCycle]) – list containing all the HalfCycle objects to be joined
Raises:: RuntimeError – if there is a mismatch in the halfcycle_type of the objects in the given list
Returns:: single halfcycle object obtained from the concatenation of the input data. The timestamp of the output object is set according to the first (oldest) dataset.
Return type:: HalfCycle

The `time_adjust` function

echemsuite.cellcycling.cycles.time_adjust(cycle, reverse=False)

Adjust the time-scale of the charge and discharge half-cycles. If the time series of both charge and discharge half-cycles starts with the same value leave them unchanged, else make the charge time-scale start from zero and subtract to the discharge one its last value. If reverse is set to True subtract from the discharge time the last point of the charge time-series and compute the absolute value.

Parameters:

cycle (Cycle) – the cycle to which the charge/discharge half-cycles belong to
reverse (bool) – if True apply the time reversal to the discharge halfcycle

Returns:

The charge and discharge time-series

Return type:

Tuple[pandas.core.series.Series, pandas.core.series.Series]

The echemsuite.cellcycling.cycles sub-module

The HalfCycle class

The Cycle class

The CellCycling class

The join_HalfCycles function

The time_adjust function

The `echemsuite.cellcycling.cycles` sub-module

The `HalfCycle` class

The `Cycle` class

The `CellCycling` class

The `join_HalfCycles` function

The `time_adjust` function