Open-circuit potential objectives with MSMR model

Objectives and utility functions for fitting the open-circuit potential / open-circuit voltage data, using the MSMR model.

class ionworkspipeline.objectives.MSMRHalfCell(electrode, data_input, options=None, callbacks=None, custom_parameters=None)

Objective for the open-circuit potential (OCP) of a half-cell, using the MSMR model.

Parameters

electrodestr

The electrode to fit (“positive” or “negative”).

data_inputstr or dict

The data to use for the fit, see Objective.

optionsdict, optional

A dictionary of options to pass to the objective.

• capacity function

  A function that takes in the voltage and returns the capacity of the electrode. Default in None, in which case the function is constructed using get_q_half_cell_msmr, the electrode, the number of species determined from the parameters, and the direction of the fit.

• dUdQ cutoff

  The cutoff dUdQ value to use for fitting (i.e. ignore large values near the ends that the solver tries to fit to). If “none”, no cutoff is applied. If a float, this is used as the cutoff. If a function, the result of calling the function with the data is used as the cutoff. Default is the function iwp.data_fits.util.calculate_dUdQ_cutoff() with default arguments.

• dQdU cutoff

  The cutoff dQdU value to use for fitting (i.e. ignore large values near the ends that the solver tries to fit to). If “none”, no cutoff is applied. If a float, this is used as the cutoff. If a function, the result of calling the function with the data is used as the cutoff. Default is None.

• voltage limits

  The voltage limits for the electrode. Default is None, in which case the limits are taken from the data. The limits are not used for fitting, but only for plotting.

• species format

  The format of the species, either “Qj” for capacity or “Xj” for mole fraction. Default is “Qj”.

• direction

  The direction of the fit, either None, “delithiation” or “lithiation”. Default is None.

callbacksCallback or list of callbacks

A class with methods that get called at various points during the datafit process

custom_parametersdict, optional

A dictionary of parameters to use within this objective only. See Objective.

Extends: ionworkspipeline.data_fits.objectives.ocp_msmr._BaseMSMR

initial_guess(num_reactions, species_format='Qj', T_ambient=298.15, num_hist_data=100000, init_method='kmeans', num_init=1, seed=0)

Generate initial guess parameters for the Gaussian Mixture Model (GMM) based on the processed data.

Parameters:

num_reactionsint

Number of reactions (components) to fit in the GMM.

species_formatstr, optional

Format of the species, either “Qj” for capacity or “Xj” for mole fraction. Default is “Qj”.

T_ambientfloat, optional

Ambient temperature in Kelvin. Default is 298.15 K.

num_hist_dataint, optional

Number of histogram data points to use for fitting the GMM. Default is 100000.

init_methodstr, optional

Initialization method for the GMM. Default is “kmeans”.

num_initint, optional

Number of runs to perform for the GMM. Default is 1.

seedint, optional

Random seed for reproducibility. Default is 0.

Returns:

paramsdict

Dictionary containing the initial guess parameters for MSMR half-cell OCP fitting.

class ionworkspipeline.objectives.MSMRFullCell(data_input, options=None, callbacks=None, custom_parameters=None)

Objective for the open-circuit potential (OCP) of a full cell, using the MSMR model.

The objective consists of the capacity (as a function of voltage) of the full cell, and the differential voltage (dU/dQ) of the full cell, as recommended in [1].

Parameters

data_inputstr or dict

The data to use for the fit, see Objective.

optionsdict, optional

A dictionary of options to pass to the objective.

• dUdQ cutoff

  The cutoff dUdQ value to use for fitting (i.e. ignore large values near the ends that the solver tries to fit to). If “none”, no cutoff is applied. If a float, this is used as the cutoff. If a function, the result of calling the function with the data is used as the cutoff. Default is the function iwp.data_fits.util.calculate_dUdQ_cutoff() with default arguments.

• negative voltage limits

  Tuple of voltage limits for the negative electrode. This option is required.

• positive voltage limits

  Tuple of voltage limits for the positive electrode. This option is required.

callbacksCallback or list of callbacks

A class with methods that get called at various points during the datafit process

custom_parametersdict, optional

A dictionary of parameters to use within this objective only. See Objective.

References

[1]

Hu, Victor W., and Daniel T. Schwartz. Low error estimation of half-cell thermodynamic parameters from whole-cell Li-ion battery experiments: Physics-based model formulation, experimental demonstration, and an open software tool. Journal of The Electrochemical Society 169.3 (2022): 030539.

Extends: ionworkspipeline.data_fits.objectives.ocp_msmr._BaseMSMR

ionworkspipeline.objectives.plot_half_cell_ocp(data, model_output, fig_axes=None, markers=None, colors=None, labels=None)

ionworkspipeline.objectives.plot_full_cell_ocv(data, model_output, fig_axes=None)

ionworkspipeline.objectives.get_theta_half_cell_msmr(n_species, electrode, species_format='Xj', direction=None)

Returns a function that calculates the extent of lithiation in a half-cell using the MSMR model.

Parameters

n_speciesint

The number of species in the electrode.

electrodestr

The electrode to fit (“positive” or “negative”).

species_formatstr, optional

The format of the species parameters. Can be either “Xj” or “Qj”. Default is “Xj”. If “Xj”, the species parameters are the mole fractions of each species. If “Qj”, then the species parameters are the capacities of each species.

directionstr, optional

The direction of the lithiation, used for fitting lithiation and delithation simultaneously when there is OCV hysteresis. Default is None, in which case the direction is not specified. Other options are “lithiation” and “delithation”. This argument specifies different values of the U0, w and Xj (or Qj) parameters for the lithiation and delithiation directions.

ionworkspipeline.objectives.get_msmr_params_for_fit(param_init, electrode, Q_total=None, bounds_function=<function default_msmr_bounds_function>, species_format='Qj', hysteresis=False)

Construct a dictionary of parameters to fit for the MSMR model.

Parameters

param_initdict

Dictionary of initial guesses for the parameters.

electrodestr

The electrode to fit (“positive” or “negative”).

Q_totalfloat, optional

(A guess for) the total capacity of the electrode. A reasonable guess is the maximum capacity in the data. If not provided, the total capacity is estimated from the sum of the Qj parameters for species_format=”Qj”, or from the parameter “{Electrode} electrode capacity [A.h]” for species_format=”Xj”.

bounds_functionfunction, optional

A function that takes a variable name, initial value, and Q_total, and returns the bounds for that variable.

species_formatstr, optional

The format of the species parameters. Can be either “Xj” or “Qj”. Default is “Qj”. If “Xj”, the species parameters are the mole fractions of each species, and the parameters are constrained to sum to 1. If “Qj”, then the species parameters are the capacities of each species, and the parameters are not constrained. If “Qj”, we still construct the lithiation function using mole fractions, but the mole fractions are specified as Qj/Qtot where Qtot is the sum of all the Qj parameters.

hysteresisbool, optional

Whether to return separate parameters for lithiation and delithiation. Default is False. If True, the parameters Xj, U0j and wj are given suffixes of “d” and “l” for delithiation and lithiation respectively. The total capacity is the same in both directions. The species_format must be “Xj” if hysteresis is True. The same initial values are used for the parameters Xj, U0j and wj in the lithiation and delithiation directions.

Returns

dict

Dictionary of parameters to fit.

ionworkspipeline.objectives.plot_each_species_msmr(data, params, electrode, voltage_limits=None, cumulative=False, direction=None)

Helper function to plot each individual species in the MSMR model. This can be used to manually find good initial guesses for the parameters by aligning the peaks.

Parameters

datadict

The data to fit to.

paramsdict

The parameter values to use for the MSMR model.

electrodestr

The electrode to fit (“positive” or “negative”).

voltage_limitstuple, optional

The voltage limits for the electrode. Default is None, in which case the limits are taken from the data.

cumulativebool, optional

If False, plot each species starting at 0. If True, plot cumulatively (each species adds on to the last one). Default is False. If True, the parameters must be sorted in decreasing value of U0.

directionstr, optional

The direction of the lithiation, used for fitting lithiation and delithiation simultaneously when there is OCV hysteresis. Default is None, in which case the direction is not specified. Other options are “lithiation” and “delithiation”.

ionworkspipeline.objectives.msmr_Qj_to_Xj(params_Qj, electrode, direction=None)

Convert parameters from Qj to Xj species format.

Parameters

params_Qjdict

The parameters in Qj format.

electrodestr

The electrode to convert (“positive” or “negative” or “both”).

directionstr, optional

The direction of the lithiation, used for fitting lithiation and delithiation simultaneously when there is OCV hysteresis. Default is None, in which case the direction is not specified. Other options are “lithiation” and “delithiation”.

Returns

dict

The parameters in Xj format.

ionworkspipeline.objectives.msmr_Xj_to_Qj(params_Xj, electrode, direction=None)

Convert parameters from Xj to Qj species format.

Parameters

params_Xjdict

The parameters in Xj format.

electrodestr

The electrode to convert (“positive” or “negative” or “both”).

directionstr, optional

The direction of the lithiation, used for fitting lithiation and delithiation simultaneously when there is OCV hysteresis. Default is None, in which case the direction is not specified. Other options are “lithiation” and “delithiation”.

Returns

dict

The parameters in Qj format.

ionworkspipeline.objectives.msmr_sort_params(params, sort_by, order='ascending')

Sorts the parameters dictionary based on a specified parameter and order.

Parameters

paramsdict

A dictionary containing the parameters to be sorted.

sort_bystr

The parameter to sort by. Parameters will be sorted based on the value of the parameters starting with this string (e.g. “U0_n”)

orderstr, optional

The order in which to sort the parameters. Default is “ascending”.

Returns

dict

A new dictionary with the sorted parameters.

Raises

ValueError

If no parameters starting with ‘sort_by’ are found.

ValueError

If ‘order’ is not recognized. Should be ‘ascending’ or ‘descending’.

class ionworkspipeline.objectives.OpenCircuitHalfCellHysteresisCallback(folder=None)

A callback to plot the results of both the delithiation and lithiation fits on a single plot.

Parameters

folderstr, optional

If provided, results are saved to this folder.

Extends: ionworkspipeline.data_fits.callbacks.SaveResultsCallback

on_datafit_finish(logs)

Called at the end of the DataFit.

Objectives in the ionworkspipeline library will pass logs containing

• “inputs”: the current values of the parameters (dict)

• “outputs”: the current values of the variables, including but not limited to

  those used in the objective (dict)

Custom objective may pass different logs.

on_objective_build(logs)

Called after the objective has been set up.

Objectives in the ionworkspipeline library will pass logs containing

• “options”: the options to be used in the data fit (dict)

• “data”: the variables in the data, including but not limited to those used in

  the objective (dict)

Custom objective may pass different logs.

plot_fit_results(split_by_direction=False)

Plot the fit results.

Parameters

split_by_directionbool, optional

If True, the results are split onto different plots by direction (delithiation and lithiation). Default is False.