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.

Objectives

class ionworkspipeline.objectives.MSMRHalfCell(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

data_inputstr or dict

The data to use for the fit, see Objective.

optionsdict, optional

A dictionary of options to pass to the objective.

• model

  The half-cell OCP model to use for the fit. Default is MSMRHalfCellModel with the electrode specified. The model class is used to specify the species format, direction and capacity function. This model should be a class with methods build, which takes in a parameter values object and the processed data, and solve, which takes in a dictionary of inputs and returns a dictionary of outputs. The solve method should return at least the objective variables.

• voltage limits

  Tuple of voltage limits to use for the fit. If not provided, the range of the data is used.

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

• objective variables

  The variables to use for the objective. Default is [“Capacity [A.h]”, “Differential voltage [V/Ah]”].

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

  The method to use to constrain the Xj values, either “explicit” or “reformulate”. “explicit” adds an equality constraint to the model to ensure that the Xj values sum to 1. “reformulate” reformulates the model by replacing the final Xj parameter, Xj_N, with 1 - sum(Xj_n) for n < N. Default is “explicit”. This option is only used if the species format is “Xj”.

• preserve U0j order

  Whether to preserve the order of the U0j parameters. If True, adds inequality constraints to the model to ensure that the U0j parameters remain in descending order. Default is False. Raises an error if the initial values of the U0j parameters are not in descending order.

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.

• model

  The model to use for the full-cell OCV. Default is MSMRFullCellModel with the negative and positive electrode models specified by MSMRHalfCellModel with the “species format” option set to “Xj”. This model should be a class with methods build, which takes in a parameter values object and the processed data, and solve, which takes in a dictionary of inputs and returns a dictionary of outputs. The solve method should return at least the objective variables.

• 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

Utility functions

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.default_msmr_bounds_function(var, initial_value, Q_total, U_range=0.05)

Default bounds function for the MSMR model parameters. These have been chosen as they work well for a range of data sets, but may need to be adjusted for specific cases.

Parameters

varstr

The variable name.

initial_valuefloat

The initial guess for the parameter.

Q_totalfloat

The total capacity of the electrode.

Returns

tuple

The lower and upper bounds for the parameter.

ionworkspipeline.objectives.get_msmr_capacity_params_for_fit(param_init, electrode, Q_use, bounds_function=<function default_msmr_capacity_bounds_function>, parameter_format=None, direction=None)

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

Parameters

param_initdict

Dictionary of initial guesses for the parameters.

electrodestr

The electrode to fit (“positive” or “negative” or “both”). If “both”, then parameters for both the positive and negative electrodes are returned.

Q_usefloat

The useable capacity of the electrode, i.e. the capacity of the electrode excluding the excess capacities. Generally, this should be the maximum capacity in the data.

bounds_functionfunction, optional

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

parameter_formatstr, optional

The format of the capacity parameters. Can be either “lower excess capacity only”, “upper excess capacity”, or “total capacity”. Default is “upper excess capacity”. If “lower excess capacity only”, then only the lower excess capacity is fitted. If “upper excess capacity”, then the upper excess capacity is fitted and the total capacity is calculated from the lower excess capacity and the useable capacity. If “total capacity”, then the total capacity is fitted and the upper excess capacity is calculated from the lower excess capacity and the useable capacity.

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 “delithation”.

Returns

dict

Dictionary of parameters to fit.

ionworkspipeline.objectives.default_msmr_capacity_bounds_function(var, initial_value, Q_use)

Default bounds function for the MSMR model capacity parameters. These have been chosen as they work well for a range of data sets, but may need to be adjusted for specific cases.

Parameters

varstr

The variable name.

initial_valuefloat

The initial guess for the parameter.

Q_usefloat

The total capacity of the electrode.

Returns

tuple

The lower and upper bounds for the parameter.

ionworkspipeline.objectives.msmr_half_cell_initial_guess(electrode, data, num_reactions, model_options=None, class_kwargs=None, *args, **kwargs)

Generate an initial guess for the MSMR half-cell model.

Parameters

electrodestr

The electrode to get an initial guess for (“positive” or “negative”).

data_inputstr or dict

The data to use for the fit, see Objective.

num_reactionsint

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

class_kwargsdict, optional

Keyword arguments passed to the MSMRHalfCell class.

argstuple

Positional arguments passed to MSMRHalfCell.initial_guess.

kwargsdict

Keyword arguments passed to MSMRHalfCell.initial_guess.

Returns

paramsdict

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

See Also

MSMRHalfCell.initial_guess for a full list of parameters and their descriptions.

ionworkspipeline.objectives.get_initial_capacity_and_lower_excess_capacity(params_Xj, electrode, data, direction=None)

Get initial guesses for the total capacity and lower excess capacity for the MSMR model from the (initial) species parameters and data. The initial guesses are based on evaluating the theta function (see get_theta_half_cell_msmr()) at the minimum and maximum voltages in the data to estimate the stoichiometry window observed in the data.

Parameters

params_Xjdict

The MSMR parameters in Xj format.

electrodestr

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

directionstr, optional

The direction of the lithiation. Default is None, in which case the direction is not specified. Other options are “lithiation” and “delithiation”

Returns

params_Qdict

Initial guesses for the total capacity and lower excess capacity.

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

Returns a function that calculates the extent of lithiation in a half-cell using the MSMR model. If differential is True, the function returns the derivative of the theta function with respect to U.

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.

differentialbool, optional

Whether to return the differential of the theta function with respect to U. Default is False.

ionworkspipeline.objectives.get_q_half_cell_msmr(n_species, electrode, species_format='Xj', direction=None, differential=False)

Returns a function that calculates the extent of lithiation in a half-cell using the MSMR model. If differential is True, the function returns the derivative of the q function with respect to U.

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 “delithiation”. This argument specifies different values of the U0, w and Xj (or Qj) parameters for the lithiation and delithiation directions.

differentialbool, optional

Whether to return the differential of the q function with respect to U. Default is False.

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 separately starting at the lower excess capacity. If True, plot cumulatively (the capacity of each species is added to the sum of the previous species). 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.plot_half_cell_ocp(data, model_output, fig_axes=None, markers=None, colors=None, labels=None)

Plot the half-cell OCP data and fit.

Parameters

datadict

The data to fit to.

model_outputdict

The model output to plot.

fig_axestuple, optional

The figure and axes to plot on. Default is None, in which case a new figure and axes are created.

markersdict, optional

The markers to use for the data and fit. Default is None, in which case the default markers are used.

colorsdict, optional

The colors to use for the data and fit. Default is None, in which case the default colors are used.

labelsdict, optional

The labels to use for the data and fit. Default is None, in which case the default labels are used.

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

Plot the full-cell OCV data and fit.

Parameters

datadict

The data to fit to.

model_outputdict

The model output to plot.

fig_axestuple, optional

The figure and axes to plot on. Default is None, in which case a new figure and axes are created.

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

Callbacks

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.