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, constraints=None, penalties=None, 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 FittingObjective.

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

• 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, optional

  Maximum number of points to save in the solver. Disabled by default.

callbackslist of callable, optional

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

custom_parametersdict, optional

A dictionary of custom parameters to use for the objective. Deprecated, use parameters instead.

constraintslist[Constraint], optional

A list of equality and inequality constraints to apply to the objective.

penaltieslist[Penalty], optional

A list of penalties to apply to the objective.

parametersdict or pybamm.ParameterValues, optional

Objective-specific parameter values merged into the global parameter values before fitting. Default is None.

Extends: ionworkspipeline.data_fits.objectives.fitting_objective.SimulationObjective

build(parameter_values)

Build the objective.

Parameters

parameter_valuespybamm.ParameterValues

The parameter values to use for the objective.

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, pd.DataFrame, or ionworksdata.DataLoader

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

complete(parameter_values: ParameterValues)

Complete the objective by evaluating custom parameters, merging objective-specific parameter values, building the objective, and applying regularization postfix.

Parameters

parameter_valuespybamm.ParameterValues

The parameter values to use for the objective.

classmethod default_options() → dict[str, Any]

Return the default options for the Pulse objective.

property remove_model_events: bool

Whether to remove the model events during simulation. Default is True.

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, polars.DataFrame, or ionworksdata.DataLoader

DataFrame or DataLoader 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, polars.DataFrame, or ionworksdata.DataLoader

DataFrame or DataLoader 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, polars.DataFrame, or ionworksdata.DataLoader

DataFrame or DataLoader 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, polars.DataFrame, or ionworksdata.DataLoader

DataFrame or DataLoader 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, parameters=None, *, initial_voltage_from_data: bool | None = None)

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

Parameters

datadict, pd.DataFrame, pl.DataFrame, or ionworksdata.DataLoader

Data containing all the data, labelled by cycle number. When a DataLoader is provided, only the steps table is accessed to determine cycles (the time-series data remains lazy and is not loaded).

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

parametersdict, optional

A dictionary of parameters to use within each objective.

initial_voltage_from_databool | None, optional

Whether to use the first voltage in the data as the initial voltage. Default is True.

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, polars.DataFrame, or ionworksdata.DataLoader

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