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, and the number of species determined from the parameters.

• 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” iwp.data_fits.util.calculate_dQdU_cutoff() with default arguments.

• 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.

• constrain_Xj

  Whether to constrain the X_j values to sum to 1. Default is “true”. Depending on how the parameters are specified this may not be necessary.

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.

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

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

  The voltage limits for the negative electrode.

• positive voltage limits

  The voltage limits for the positive electrode.

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_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 and w parameters for the lithiation and delithation directions, but the same values of the Xj or Qj parameters.

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.

Returns

dict

Dictionary of parameters to fit.

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

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.

ionworkspipeline.objectives.msmr_Qj_to_Xj(params_Qj, electrode)

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”).

Returns

dict

The parameters in Xj format.

ionworkspipeline.objectives.msmr_Xj_to_Qj(params_Xj, electrode)

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”).

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’.