Workflows

Collections of pre-defined workflows for common tasks. All of the workflows implement a fit_plot_save function which typically takes in the data, initial guesses for parameters, and other optional arguments, and saves the fitted parameters and plots of the fit.

ionworkspipeline.workflows.half_cell_ocp.fit_plot_save(electrode, data, params_to_fit, known_params, save_dir=None, filename=None, objective=<class 'ionworkspipeline.data_fits.objectives.ocp_msmr.MSMRHalfCell'>, objective_kwargs=None, datafit_kwargs=None, show_plot=False)

A workflow to fit the MSMR model to OCP data and plot and save the results. The function uses sets up the objective and data fit and runs the fit. The fitted parameters are saved to a JSON file and the OCP data is saved to a CSV file. If there is more than one dataset, a CSV file is saved for each dataset, but only one JSON file is saved since the fitted parameters are the same for all datasets.

Parameters

electrodestr

The electrode to fit the MSMR model to. Must be either “positive” or “negative”.

datadict or pandas.DataFrame

The OCP data to fit the MSMR model to. Each dataset should be a dataframe with columns “Voltage [V]” and “Capacity [A.h]”.

params_to_fitdict

The parameters to fit. Should be a dictionary of the form {parameter_name: ionworkspipeline.Parameter}.

known_paramsdict

The known parameters. Should be a dictionary of the form {parameter_name: value} and contain “Ambient temperature [K]” (the temperature at which the data was collected).

save_dirstr, optional

The directory to save the fit results and plots to. If not provided, the results are not saved.

filenamestr, optional

The filename to save the fit results and plots to. If not provided, the filename is “ocp_msmr_{electrode}”. If there is more than one dataset, a suffix corresponding to the objective name is added to the filename for the OCP data.

objectiveionworkspipeline.objectives.Objective, optional

The objective to use for the fit. Default is ionworkspipeline.objectives.MSMRHalfCell.

objective_kwargsdict, optional

Additional keyword arguments for the objective function. If the keys match the keys of the data, then each item should be a dictionary of objective_kwargs to use for that dataset. Otherwise, the same objective_kwargs are used for all datasets.

datafit_kwargsdict, optional

Additional keyword arguments to pass to the data fit object.

show_plotbool, optional

Whether to show the plot. Default is False.

Returns

resionworkspipeline.Result

The results of the fit.

all_fig_axesdict

A dictionary with keys “fit” and “trace” containing the figure and axes objects for the fit and parameter trace plots.

ionworkspipeline.workflows.full_cell_ocv.fit_plot_save(data, params_to_fit, known_params, save_dir=None, filename=None, objective=<class 'ionworkspipeline.data_fits.objectives.ocp_msmr.MSMRFullCell'>, objective_kwargs=None, datafit_kwargs=None, show_plot=False)

A workflow to fit the MSMR model to full-cell OCV data and plot and save the results. The function sets up the objective and data fit and runs the fit. The fitted parameters are saved to a JSON file.

Parameters

datadict or pandas.DataFrame

The full-cell OCV data to fit the MSMR model to. Each dataset should be a dataframe with columns “Voltage [V]” and “Capacity [A.h]”.

params_to_fitdict

The parameters to fit. Should be a dictionary of the form {parameter_name: ionworkspipeline.Parameter}.

known_paramsdict

The known parameters. Should be a dictionary of the form {parameter_name: value} and contain the MSMR parameters for each half-cell and “Ambient temperature [K]” (the temperature at which the data was collected).

save_dirstr, optional

The directory to save the fit results and plots to. If not provided, the results are not saved.

filenamestr, optional

The filename to save the fit results and plots to. If not provided, the filename is “ocv_msmr_full_cell”.

objectiveionworkspipeline.objectives.Objective, optional

The objective to use for the fit. Default is ionworkspipeline.objectives.MSMRFullCell.

objective_kwargsdict, optional

Additional keyword arguments for the objective function. If the keys match the keys of the data, then each item should be a dictionary of objective_kwargs to use for that dataset. Otherwise, the same objective_kwargs are used for all datasets.

datafit_kwargsdict, optional

Additional keyword arguments to pass to the data fit object.

show_plotbool, optional

Whether to show the plot. Default is False.

Returns

resionworkspipeline.Result

The results of the fit.

all_fig_axesdict

A dictionary with keys “fit” and “trace” containing the figure and axes objects for the fit and parameter trace plots.

ionworkspipeline.workflows.current_driven.fit_plot_save(data, params_to_fit, known_params, save_dir=None, filename='', objective_kwargs=None, datafit_kwargs=None, show_plot=False)

Fit parameters to current-driven data, plot results, and save outputs.

This function performs the following steps: 1. Sets up objectives and callbacks for current-driven experiments 2. Fits model parameters to the provided data 3. Plots the results 4. Saves the fitted parameters and plots (if a save directory is provided)

Parameters

datadict or pandas.DataFrame

Experimental data to fit

params_to_fitdict

Parameters to be fitted

known_paramsiwp.ParameterValues

Known parameter values

save_dirstr or pathlib.Path, optional

Directory to save outputs. If None, outputs are not saved.

filenamestr, optional

Base filename for saved outputs. Default is “”.

objective_kwargsdict, optional

Additional keyword arguments for the objective function. If the keys match the keys of the data, then each item should be a dictionary of objective_kwargs to use for that dataset. Otherwise, the same objective_kwargs are used for all datasets.

datafit_kwargsdict, optional

Additional keyword arguments for the DataFit object

show_plotbool, optional

If True, display the plot. Default is False.

Returns

iwp.Result

Object containing fitted parameters, optimizer results, and callback results

dict

Dictionary of figure and axes objects for the generated plots

The workflows call the following common methods, which can be used to create new workflows:

ionworkspipeline.workflows.common.get_objective_and_callbacks(data, objective, save_dir=None, objective_kwargs=None)

Get objective and callbacks for a workflow.

This function creates objectives and save callbacks for each dataset provided. It handles both single DataFrame inputs and dictionaries of DataFrames.

Parameters:

datapd.DataFrame or dict

The input data. Can be a single DataFrame or a dictionary of DataFrames.

objectiveclass or partial

The objective class or partial function to be used.

save_dirstr or Path, optional

The directory to save results. If None, results won’t be saved.

objective_kwargsdict, optional

Additional keyword arguments for the objective. If the keys match the keys of the data, then each item should be a dictionary of objective_kwargs to use for that dataset. Otherwise, the same objective_kwargs are used for all datasets.

Returns:

tuple

A tuple containing:

• objectives: dict

  A dictionary of objective instances for each dataset.

• save_callbacks: dict

  A dictionary of SaveResultsCallback instances for each dataset.

ionworkspipeline.workflows.common.process_filename(filename)

Process the filename for saving results.

This function removes the file extension if present and adds an underscore to the end of the filename if it’s not empty. This ensures consistent filename formatting for saving results.

Parameters:

filenamestr

The input filename to process.

Returns:

str

The processed filename.

Examples:

>>> process_filename("data.csv")
'data'
>>> process_filename("results")
'results'

ionworkspipeline.workflows.common.plot(data_fit, save_dir=None, filename='', show_plot=False)

Plot the results of the data fit for all objectives.

This function generates plots for the parameter trace and for each objective’s fit results. It saves the plots if a save directory is provided and displays them if show_plot is True.

Parameters:

objectivesdict

A dictionary of objective functions, where keys are objective names and values are objective instances.

data_fitiwp.DataFit

The DataFit object containing the fit results.

save_dirstr or Path, optional

The directory to save the plots. If None, plots are not saved.

filenamestr, optional

The base filename to use when saving plots. This should already be processed by the process_filename function. Default is “”.

show_plotbool, optional

If True, display the plots using plt.show(). Default is False.

Returns:

dict

A dictionary containing all generated figure and axes objects, with keys corresponding to the plot types (e.g., ‘trace’, objective names).