Cycle ageing objective

Objectives for fitting the data generated by a cycle ageing experiment.

class ionworkspipeline.objectives.CycleAgeing(data_input, options=None, callbacks=None, custom_parameters=None, constraints=None, penalties=None, parameters=None)

Objective for fitting summary variables to cycling data.

Parameters

data_inputstr or dict

The data to use for the fit, see FittingObjective. A measurement’s stored analysis is the usual platform source for it. Its "Cycle number" column says which cycle each row describes: a cycle of the steps table the experiment was generated from, matched against that table’s "Cycle count", or, for an experiment passed in directly, a 0-based position among its cycles. The cycle a quantity is recorded against is the one it was measured in, so a quantity measured later in the same test occupies its own row rather than sharing the one its test began in. A target column may be sparse: a NaN says the measurement has no value at that cycle, and that row is left out of both the metric and the cost for that variable alone — the cost is handed only the points it can score.

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

• experiment: pybamm.Experiment, “from data”, or DataLoader

  The experiment to use for the simulation. No default is provided, but this option is required (an experiment must be passed in). If set to the string “from data”, the experiment is generated automatically from the step information in the data via ionworks.data.DataLoader.generate_experiment(); this requires data_input to be an ionworks.data.DataLoader (or a dict whose “data” entry is a DataLoader) with steps. If set to a ionworks.data.DataLoader, the experiment is generated from that loader’s steps instead — useful when the fitted data (e.g. a per-cycle summary table) is a different object from the measurement that defines the protocol. Generation happens lazily when the objective is built (at the start of a fit), so step data is only loaded at that point.

• termination: str

  What ends each step of a generated experiment: “duration” (default) replays each step’s measured length, “events” replays the endpoint each step reached in the variable it was controlling, so a capacity disagreement reads as capacity to that endpoint rather than as a residual voltage. See ionworks.data.DataLoader.generate_experiment(). Applies only to a generated experiment; passing it alongside an explicit one raises.

• use_cv: bool

  Emit the constant-voltage steps of a generated experiment as voltage holds rather than as a current interpolant. Default False. During a hold the current is what the cell’s impedance produces, so prescribing the measured current through it asks the model to reproduce that impedance rather than to simulate the hold; with termination=”events” the hold instead ends at its measured final current, as the taper cut-off did. Prefer that pairing: under “duration” the preceding step stops on the clock, and a hold entered below its setpoint draws whatever current closes the gap — many times the nominal rate, and invisible in a voltage-vs-time residual. A taper endpoint drifting with age also gives every hold a distinct step, which costs the model reuse experiment_model_mode="unified" exists for. Same restriction as termination.

• split_cc_cv: bool

  Emit a step the cycler logged as one CC-CV charge as a constant-current step followed by a constant-voltage step, rather than as a current interpolant. Default True. A metric’s step index (step=k, by_cycle(step=k), by_step(steps=[...])) still counts the steps table’s rows, and reads a split row as its two steps joined into one. Rows of zero duration produce no step and are not counted. Same restriction as termination.

• objective variables: list of strings

  The variables to fit. No default is provided, but this option is required (a list of variables must be passed in). The variables must be a subset of the keys in the data.

• metrics: dict of str to BaseMetric

  A dictionary mapping variable names to metric objects that extract values from the simulation solution. Each metric should be created with .by_cycle() to evaluate across cycles. The cycles are set automatically to those the data has a value of that variable for, in row order; an explicit cycles= states them in the data’s own "Cycle number" and has to name exactly those same cycles. Default metrics are provided for “LLI [%]”, “LAM_ne [%]”, and “LAM_pe [%]”. When every metric reads only per-step first/last values (the defaults, or any First/Last .by_cycle() metric), solver_kwargs["store_first_last"] defaults to True so the auto-built solver stores only step endpoints — much more memory-light for long cycling solves. Pass store_first_last explicitly in solver_kwargs to override.

• simulation_kwargs: dict

  Keyword arguments to pass to the simulation (iwp.Simulation). May include solver_kwargs to tune the auto-built solver (e.g. {"options": {"compile": True}} to enable compilation), ignored if an explicit solver is also provided. May also include solve_kwargs forwarded to the runtime solve regardless of the solver; save_at_cycles is derived automatically from the metrics and a value passed here is ignored with a warning (the metrics’ cycles must be kept). experiment_model_mode defaults to "unified" (a single switching model for the whole experiment, much cheaper for repeated cycling) whenever an experiment is supplied; pass it explicitly here to override. Default is None.

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.

See also: CycleAgeing — field-level documentation.

build(parameter_values)

Build the objective.

Parameters

parameter_valuespybamm.ParameterValues

The parameter values to use for the objective.

classmethod default_options() → dict[str, Any]

Return the default options for the CycleAgeing objective.

property fit_data

The targets the cost scores: the rows each variable is measured at.

A variable measured at only some of the cycles its data numbers is scored at those rows alone, so the cost is handed exactly the points it can compare. processed_data keeps every row, NaN included, for the plots and the validation report.

prepare_validation_results(results: dict, summary_stats: list) → tuple[list[dict[str, float]], dict[str, float]]

Prepare validation results for CycleAgeing objective.

Parameters

resultsdict

The raw results from running the objective (keys = variable names, values = arrays per cycle).

summary_statslist

List of summary statistic cost functions to compute.

Returns

tuple[list[dict[str, float]], dict[str, float]]

A tuple of (computed_statistics, validation_result) where computed_statistics is a list of dictionaries with computed metric names and values, and validation_result is a dictionary of validation data (Cycle number and per-variable model/data).

to_config() → dict

Convert the objective back to parser configuration format.

Reports the experiment option as the caller passed it. build() replaces a generated experiment with the pybamm.Experiment it produced, and does so in the options dict this serializes, so without this the config would claim an explicit experiment alongside the termination / use_cv that generated it — a pairing the constructor rejects, since there would be nothing left for them to act on.

Returns

dict

Configuration dictionary for this objective.

validation_x_key: str = 'Cycle number'

Key of the independent variable within validation_result.

validation_x_label: str = 'Cycle number'

Axis label for that variable.