Objectives

The base class for all objectives is BaseObjective.

class ionworkspipeline.data_fits.objectives.BaseObjective(options=None, callbacks=None, custom_parameters=None, cost=None, constraints=None, penalties=None, parameters=None)

A pipeline element that constructs an objective function for either fitting or design optimization.

Parameters

optionsdict, optional

A dictionary of options to pass to the data fit.

callbacksionworkspipeline.callbacks.Callback or list of callbacks

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

custom_parametersdict, optional

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

costionworkspipeline.costs.ObjectiveFunction or str, optional

The cost function to use for the objective. If not provided, the default cost function will be used.

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.controllers.ConfigMixin

build(parameter_values: ParameterValues)

Build the objective.

Parameters

parameter_valuespybamm.ParameterValues

The parameter values to use for the objective.

property can_calculate_initial_state_of_charge: bool

Whether the objective can calculate the initial state of charge using self._get_initial_state_of_charge(inputs).

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.

create_validation_plots(validation_result: dict, plots: list[str] | None = None, include_bokehjs: str | bool = 'cdn', include_plotlyjs: str | bool = 'cdn', backend: str = 'bokeh', **plot_kwargs) → list[str]

Create validation plots for this objective in HTML format.

Parameters

validation_resultdict

The validation results data.

plotslist[str] | None

List of plot types to create.

include_bokehjsstr | bool

Whether to include bokeh.js in the output (for bokeh backend).

include_plotlyjsstr | bool

Whether to include plotly.js in the output (for plotly backend).

backendstr

Plotting backend to use: “bokeh” (default) or “plotly”.

**plot_kwargs

Additional keyword arguments for plotting.

Returns

list[str]

List of HTML strings for each plot.

create_validation_plots_json(validation_result: dict, plots: list[str] | None = None, backend: str = 'bokeh', **plot_kwargs) → list[dict]

Create validation plots for this objective in JSON format.

Parameters

validation_resultdict

The validation results data.

plotslist[str] | None

List of plot types to create.

backendstr

Plotting backend to use: “bokeh” (default) or “plotly”.

plot_kwargs

Additional keyword arguments for plotting.

Returns

list[dict]

List of dictionaries containing plot information:

• “type”: plot type name

• “figure”: JSON string representation of the figure. For bokeh backend, can be embedded with Bokeh.embed.json_item(). For plotly backend, can be loaded with plotly.io.from_json().

property default_on_failure: str

Default solver.on_failure mode. Returns "ignore" when no experiment is set. If on_failure is set to “ignore”, the solver will terminate due to hitting the final time or return a partial solution on error.

Returns

str

The default on failure mode.

classmethod default_options() → dict[str, Any]

Return the default options for this objective class.

default_validation_plot_types: list[str] | None = None

Default list of validation plot type names for this objective.

Subclasses that support validation should override. Return None to use the pipeline fallback (e.g. ["model data", "error"]); return [] for no plots.

property has_simulation_experiment: bool

Whether the simulation kwargs contain a pybamm Experiment.

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

Prepare validation results for this objective.

Parameters

resultsdict

The raw results from running the objective.

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

• validation_result is a dictionary of validation data

Raises

NotImplementedError

If the objective does not support validation.

property remove_model_events: bool

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

reset_callbacks()

Reset the callbacks to the original state using a deepcopy of the original callbacks. This is used with multiprocessing to make the Objective reusable for different DataFit jobs.

to_config() → dict

Convert the objective back to parser configuration format.

Returns

dict

Configuration dictionary for this objective

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

A pipeline element that constructs an objective function used to fit a model to data. SimulationObjective is a subclass of Objective that intended for use with objectives that run a pybamm simulation.

Parameters

data_inputstr, dict, pd.DataFrame, or ionworksdata.DataLoader

The data to use for the fit. Can be a string giving the path to the data, a pandas DataFrame, an ionworksdata DataLoader, or a dictionary with keys “data” and “metadata”. “data” should be a DataFrame or DataLoader that supplies the raw data, and “metadata” should be a dictionary that supplies metadata about the data.

optionsdict, optional

A dictionary of options to pass to the data fit.

callbacksionworkspipeline.callbacks.Callback or list of callbacks

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

property can_calculate_initial_state_of_charge: bool

Whether the objective can calculate the initial state of charge using self._get_initial_state_of_charge(inputs).

For the objectives that are implemented in the pipeline, see the following sections.

• Open-circuit potential objectives
  • OCPHalfCell
    • OCPHalfCell.build()
    • OCPHalfCell.default_options()
  • ElectrodeBalancingHalfCell
    • ElectrodeBalancingHalfCell.build()
    • ElectrodeBalancingHalfCell.default_options()
  • ElectrodeBalancing
    • ElectrodeBalancing.build()
    • ElectrodeBalancing.default_options()
  • get_U_half_cell()
• Open-circuit potential objectives with MSMR model
  • Objectives
    • MSMRHalfCell
      • MSMRHalfCell.build()
      • MSMRHalfCell.default_options()
      • MSMRHalfCell.initial_guess()
    • MSMRFullCell
      • MSMRFullCell.build()
      • MSMRFullCell.default_options()
  • Utility functions
    • get_msmr_params_for_fit()
    • default_msmr_bounds_function()
    • get_msmr_capacity_params_for_fit()
    • default_msmr_capacity_bounds_function()
    • msmr_half_cell_initial_guess()
    • get_initial_capacity_and_lower_excess_capacity()
    • get_theta_half_cell_msmr()
    • get_q_half_cell_msmr()
    • plot_each_species_msmr()
    • plot_half_cell_ocp()
    • plot_full_cell_ocv()
    • msmr_Qj_to_Xj()
    • msmr_Xj_to_Qj()
    • msmr_sort_params()
  • Callbacks
    • OpenCircuitHalfCellHysteresisCallback
      • OpenCircuitHalfCellHysteresisCallback.on_datafit_finish()
      • OpenCircuitHalfCellHysteresisCallback.on_objective_build()
      • OpenCircuitHalfCellHysteresisCallback.plot_fit_results()
• Resistance objective
  • Resistance
    • Resistance.build()
    • Resistance.default_options()
  • HalfCellResistanceModel
  • FullCellResistanceModel
  • ContactResistanceModel
    • ContactResistanceModel.build()
  • ChargeTransferResistanceModel
    • ChargeTransferResistanceModel.build()
  • ElectrolyteOhmicResistanceModel
    • ElectrolyteOhmicResistanceModel.build()
  • SumResistanceModel
    • SumResistanceModel.build()
  • ResistanceModel
    • ResistanceModel.build()
    • ResistanceModel.solve()
    • ResistanceModel.solve_full()
• Pulse objective
  • Pulse
    • Pulse.build()
    • Pulse.calculate_objective_variables()
    • Pulse.complete()
    • Pulse.default_options()
    • Pulse.remove_model_events
  • voltage_objective_variables()
  • overpotentials_objective_variables()
  • resistances_objective_variables()
  • ici_features_objective_variables()
  • gitt_features_objective_variables()
  • get_pulse_objectives_by_cycle()
  • calculate_pulse_resistance()
• Current-driven objective
  • CurrentDriven
    • CurrentDriven.build()
    • CurrentDriven.complete()
    • CurrentDriven.default_options()
    • CurrentDriven.default_validation_plot_types
    • CurrentDriven.prepare_validation_results()
    • CurrentDriven.remove_model_events
• EIS objective
  • EIS
    • EIS.build()
    • EIS.default_options()
    • EIS.prepare_validation_results()
• Calendar ageing objective
  • CalendarAgeing
    • CalendarAgeing.build()
    • CalendarAgeing.default_options()
    • CalendarAgeing.remove_model_events
• Cycle ageing objective
  • CycleAgeing
    • CycleAgeing.build()
    • CycleAgeing.default_options()
    • CycleAgeing.default_validation_plot_types
    • CycleAgeing.prepare_validation_results()