Pulse objective

Objectives for fitting the data generated by a pulse experiment (e.g. HPPT or GITT).

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

Objective for pulse experiments (e.g. GITT, HPPC, ICI). By default, the objective compares the model voltage to the data voltage. However, it can also compute other variables, such as overpotentials, resistances, and ICI features, and these can be selected by passing the appropriate objective variables function.

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: :class:pybamm.BaseModel

  The model to fit. No default is provided, but this option is required (a model must be passed in).

• correct OCV difference: str

  Whether to correct for the difference between the true OCV and the simulated OCV in the objective function. Default is false, but correcting for this difference can improve the fit.

• simulation_kwargs: dict

  Keyword arguments to pass to the simulation (iwp.Simulation). Default is None.

• objective variables: callable

  A function that takes the model or data and returns a dictionary of objective variables. Default is voltage_objective_variables, which returns the voltage. Other useful functions are

  • overpotential_objective_variables, which returns the overpotential

    at various points in the pulses

  • resistances_objective_variables, which returns the resistance at

    various points in the pulses

  • ici_features_objective_variables, which returns the ICI features

    (concentration overpotential and ICI square-root slope)

  • gitt_features_objective_variables, which returns the GITT features

    (concentration overpotential, relaxation time, ohmic voltage drop, GITT and ICI square-root slopes)

• interpolant_atol: float

  Absolute tolerance for the current interpolant. Default is the solver atol if a solver is provided in simulation_kwargs, otherwise 1e-6.

• interpolant_rtol: float

  Relative tolerance for the current interpolant. Default is the solver rtol if a solver is provided in simulation_kwargs, otherwise 1e-4.

• interactive_preprocessing: bool

  Whether to use interactive preprocessing to adjust interpolant_atol and interpolant_rtol based on the current data. Default is False.

• solver_max_save_points: int

  Maximum number of points to save in the solver. Default is 10000.

callbackslist of callable, optional

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.The following default custom parameters are used:

For all models:

• Initial temperature [K]: Function to calculate the initial temperature. Default is iwp.data_fits.custom_parameters.initial_temperature.

• Ambient temperature [K]: Function to calculate the ambient temperature. Default is iwp.data_fits.custom_parameters.initial_temperature.

For full-cell models:

• Initial concentration in negative electrode [mol.m-3]: Function to calculate the initial concentration in the negative electrode for full cells. Default is iwp.data_fits.custom_parameters.initial_concentration_from_voltage(“full”, “negative”).

• Initial concentration in positive electrode [mol.m-3]: Function to calculate the initial concentration in the positive electrode for full cells. Default is iwp.data_fits.custom_parameters.initial_concentration_from_voltage(“full”, “positive”).

For half-cell models:

• Initial concentration in {working_electrode} electrode [mol.m-3]: Function to calculate the initial concentration in the working electrode for half cells. Default is iwp.data_fits.custom_parameters.initial_concentration_from_voltage(“half”, {working_electrode}).

These custom parameters are functions that take parameter_values and data as arguments and return the calculated value. They can be overridden by providing new functions in the custom_parameters dictionary.

See Objective for more details.

Extends: ionworkspipeline.data_fits.objectives.objective.SimulationObjective

calculate_objective_variables(model_or_data)

Calculate the objective variables from the model or data, using the function specified in the option “objective variables”.

Parameters

model_or_datadict or pd.DataFrame

The model or data from which to calculate the objective variables.

ionworkspipeline.objectives.voltage_objective_variables(df)

Simply return the voltage from the data

ionworkspipeline.objectives.overpotentials_objective_variables(df, step_nums=None, dts=None)

Calculate the overpotentials for each on pulse in the Pulse data. The overpotentials are defined as the difference between the voltage at the end of the previous pulse, and the voltage at various points in the current pulse (after 1s, 60s, and at the end of the pulse).

Parameters

dfpandas.DataFrame

Dataframe containing the data or output from the model

step_numslist of int, optional

The step numbers to calculate the overpotentials for. If None, then all step numbers are used. Default is None.

dtslist of int, optional

The times at which to calculate the overpotentials. Default is [1, 60].

ionworkspipeline.objectives.resistances_objective_variables(df, step_nums=None, dts=None)

Calculate the resistance for each on pulse in the Pulse data. The resistances are calculated as the overpotentials divided by the mean current during the step. The overpotentials are defined as the difference between the voltage at the end of the previous pulse, and the voltage at various points in the current pulse (see overpotentials_objective_variables for more details).

Parameters

dfpandas.DataFrame

Dataframe containing the data or output from the model

step_numslist of int, optional

The step numbers to calculate the resistances for. If None, then all step numbers are used. Default is None.

dtslist of int, optional

The times at which to calculate resistances. Default is [1, 60].

ionworkspipeline.objectives.ici_features_objective_variables(df, step_nums=None, r2_threshold=0.95, full_output=False)

Calculate the ICI (Intermittent Current Interruption) features from the Pulse data. The features used in the fit are the potential change and the ICI square-root slope during the slope. See [2] for more details.

The following function is used to obtain the square-root slope and offsets

\[U = U_0 + \frac{d U}{d \sqrt{t}} \sqrt{t - t_0}\]

where $t_0$ refers to the start of the rest phase. The square-root function fitted to the rest phase gives the potential change as $U_0$ and the ICI square-root slope as $frac{d U}{d sqrt{t}}$.

Parameters

dfpandas.DataFrame

Dataframe containing the data or output from the model.

step_numslist of int

The step numbers of the rest (interrupt) steps.

r2_thresholdfloat, optional

The R^2 threshold for the square-root fits. Default is 0.95.

full_outputbool, optional

Whether to return the full time vs overpotential data for the fit segments. Default is False.

References

[2]

Yin, L., Geng, Z., Chien, Y.C., Thiringer, T., Lacey, M.J., Andersson, A.M. and Brandell, D., 2022. Implementing intermittent current interruption into Li-ion cell modelling for improve

ionworkspipeline.objectives.gitt_features_objective_variables(df, step_nums=None, r2_threshold=0.95, full_output=False)

Calculate the GITT features from the Pulse data. The feature used in the fit are the voltage directly after the current has been shut off (concentration overpotential), the relaxation time during the current on pulses, the ohmic voltage drop, and the GITT and ICI (Intermittent Current Interruption) square-root slopes during the current on pulse and rest periods, respectively. See [1] for more details.

The following function is used to obtain the square-root slopes and offsets

\[U = U_0 + \frac{d U}{d \sqrt{t}} \sqrt{t - t_0}\]

where $t_0$ refers to the start of the current on pulse or the start of the rest phase. The square-root function fitted to the current on pulse gives the ohmic voltage drop as $U_0$ and the GITT square-root slope as $frac{d U}{d sqrt{t}}$. The square-root function fitted to the rest phase gives the concentration overpotential as $U_0$ and the ICI square-root slope as $frac{d U}{d sqrt{t}}$. To get the relaxation time $ au$ , we use the following exponential fit function on the current pulse:

\[U = U_0 + \Delta U \exp\left(-\frac{t - t_0}{\tau}\right)\]

where $t_0$ refers to the start of the current pulse.

Parameters

dfpandas.DataFrame

Dataframe containing the data or output from the model

step_numslist of int

The step numbers of the pulse (current on) steps

r2_thresholdfloat, optional

The R^2 threshold for the square-root and exponential fits. Default is 0.95.

full_outputbool, optional

Whether to return the exponential fit parameters $U_$ and $Delta U$ and the full time vs overpotential data for the fit segments. Default is False.

References

[1]

Kuhn, Y., Wolf, H., Latz, A. and Horstmann, B., 2023. Bayesian parameterization of continuum battery models from featurized electrochemical measurements considering noise. Batteries & Supercaps, 6(1), p.e202200374.

ionworkspipeline.objectives.get_pulse_objectives_by_cycle(data, options=None, callbacks=None, custom_parameters=None)

Get a dictionary of ionworkspipeline.objectives.Pulse objectives for each cycle of the pulse data.

Parameters

datadict

Dataframe containing all the data, labelled by cycle number.

optionsdict, optional

A dictionary of options to pass to the objective.

callbackslist of callable, optional

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

custom_parametersdict, optional

A dictionary of parameters to use within each objective.

Returns

dict

A dictionary of objectives, one for each cycle of the pulse data. The keys will match the keys in the input data dictionary.

ionworkspipeline.objectives.calculate_pulse_resistance(electrode, data, step_nums=None, dts=None)

Get a DataFrame of the resistance values for each cycle, duration, step, and stoichiometry.

Parameters

electrodestr

The electrode to calculate the resistance for. Must be “positive” or “negative”.

datapandas.DataFrame

The cycling data.

step_numslist of int, optional

The step numbers to calculate the resistances for. If None, then all step numbers are used. Default is None.

dtslist of int, optional

The times at which to calculate resistances. Default is [1, 60].