Cost Functions

class ionworkspipeline.costs.Cost(scale=None, nan_values=None, objective_weights=None, variable_weights=None)

Base cost function class

Parameters

scalestring or float, optional

How to scale the model and data, for each variable in the cost function. The options are - “mean” (default): uses the mean of the data. - “range”: uses the range of the data. - “sse”: uses the sum of squares of the data. - “mse”: uses the mean of the sum of squares of the data. - “rmse”: uses the root mean square of the sum of squares of the data. - “identity”: uses 1. - float: uses the value of the float.

nan_valuesstring or float, optional

How to deal with any NaN values in the model output. If “mean”, uses the mean of the non-NaN model output values. If “min”, uses the min of the non-NaN model output values. If a float, uses the float value.

objective_weightsdict, optional

Dictionary of {name: weight} pairs for each objective in the cost function. If None, all objectives are weighted equally. If a name is not in the dictionary, it is given a weight of 1.

variable_weightsdict, optional

Dictionary of {name: weight} pairs for each variable in the cost function. If None, all variables are weighted equally. If a name is not in the dictionary, it is given a weight of 1.

__call__(outputs, finalize=True, scalar_output: bool | None = None)

Returns the cost function evaluated over all the outputs

Parameters

outputsdict

Dict of outputs for which to compute the cost function. Each value in the dict should be a tuple (model, data) corresponding to one case; having multiple items allows for multi-objective optimization, for example optimizing simultaneously over multiple C-rates. The keys of the dict are the names of the objective optimized. For each (model, data) tuple, both model and data should be a dictionary of {name: value} pairs for variables being optimized over. ‘name’ should be a string and ‘value’ should be a numpy array.

finalizebool, optional

Whether to finalize the cost function. If True, calls the finalize_output method.

apply_weights(value: ndarray | float64, weight: float, scalar_output: bool | None = None) → ndarray | float64

Apply the weights to the value

property array_output: bool

Whether the cost function supports array output

combine(cost: float, value: float, scalar_output: bool | None = None) → float

Update the scalar cost by adding a new value.

Parameters

costfloat

Current accumulated cost

valuefloat

New value to add to the cost

Returns

float

Updated cost value

combined_weights(objective_weight: float, variable_weight: float, scale: float) → float

Combine the objective and variable weights

static evaluate_to_array(model_value: ndarray, data_value: ndarray) → ndarray

Evaluate the cost function for an array of residuals.

static evaluate_to_scalar(model_value: ndarray, data_value: ndarray) → float64

Evaluate the cost function for a scalar value.

finalize_output(cost: float, scalar_output: bool | None = None) → float

Finalize the scalar cost computation.

Parameters

costfloat

Final accumulated cost value

Returns

float

The final cost value

get_objective_names(outputs: dict) → list[str]

Get the names of the objectives

initialize_output(scalar_output: bool | None = None)

Initialize the cost value for scalar costs.

Returns

float

Initial cost value of 0.0

nan_values(model_value, data_value)

How to deal with nan values

property objective_names: list[str]

The names of the objectives

objective_weights(name, default=None)

How to weight the output objectives

static residuals_to_scalar(residuals: ndarray) → float64

Scalarize the residuals to a single value. The canonical scalarization is the sum of squares of the residuals.

property scalar_output: bool

Whether the cost function supports scalar output

scalarize(value: ndarray | float) → float64

Convert the cost to a scalar value. For a scalar cost, this is the value itself. For an array cost, this is the sum of squares of the array.

scale(model_value, data_value)

How to scale the data for comparison across multiple variables / cases

set_objective_names(objective_names: list[str])

Set the names of the objectives

set_scalar_output(scalar_output: bool)

Set the type of the cost function output. If True, the cost function will return a scalar value. If False, the cost function will return an array value.

property supports_array_output: bool

Whether the cost function supports array output

property supports_scalar_output: bool

Whether the cost function supports scalar output

variable_weights(name, default=None)

How to weight the output variables

class ionworkspipeline.costs.MultiCost(costs, accumulator=<built-in function sum>)

Cost function that is a combination of multiple costs

Parameters

costsdict of {cost: weight}

Dict of costs and their weights.

accumulatorfunction, optional

The function to use to combine the costs. Default is sum.

Examples

Create a combined cost that uses both MSE and MAE with different weights:

>>> mse_cost = MSE()
>>> mae_cost = MAE()
>>> combined_cost = MultiCost({mse_cost: 2.0, mae_cost: 0.5})

Notes

The scalar_output and array_output settings are propagated to all constituent cost functions. All costs must support the selected output type. The default accumulator (sum) combines the weighted costs by addition.

Extends: ionworkspipeline.data_fits.costs.costs.Cost

set_scalar_output(scalar_output: bool)

Set the scalar output of the cost function

property supports_array_output: bool

Whether the cost function supports array output

property supports_scalar_output: bool

Whether the cost function supports scalar output

class ionworkspipeline.costs.MLE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)

Cost function that reports the maximum likelihood estimate of the difference between the model and the data.

This cost uses the sum of squared residuals between model and data values. For scalar output, it returns the sum of squares of residuals. For array output, it returns the direct residuals (model - data).

Extends: ionworkspipeline.data_fits.costs.costs.Cost

static evaluate_to_array(model_value: ndarray, data_value: ndarray) → ndarray

Evaluate the cost function for an array of residuals.

static evaluate_to_scalar(model_value: ndarray, data_value: ndarray) → float64

Evaluate the cost function for a scalar value.

property supports_array_output: bool

Whether the cost function supports array output

property supports_scalar_output: bool

Whether the cost function supports scalar output

class ionworkspipeline.costs.Max(scale=None, nan_values=None, objective_weights=None, variable_weights=None)

Cost function that reports the maximum error between the model and the data.

For scalar output, it returns the maximum absolute value of any residual. For array output, it returns a single-element array containing the square root of the maximum error.

Useful when you want to minimize the worst-case error rather than an average.

Extends: ionworkspipeline.data_fits.costs.costs.Cost

static evaluate_to_array(model_value: ndarray, data_value: ndarray) → ndarray

Evaluate the cost function for an array of residuals.

static evaluate_to_scalar(model_value: ndarray, data_value: ndarray) → float64

Evaluate the cost function for a scalar value.

property supports_array_output: bool

Whether the cost function supports array output

property supports_scalar_output: bool

Whether the cost function supports scalar output

class ionworkspipeline.costs.SSE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)

Sum-square-error cost function. This is an alias for the MLE cost function.

This cost function calculates the sum of squared differences between model and data values. Mathematically equivalent to the MLE cost function, but provided for clarity in code.

Extends: ionworkspipeline.data_fits.costs.costs.MLE

class ionworkspipeline.costs.MSE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)

Mean-square-error cost function.

Similar to SSE, but normalizes by the number of data points. This makes the cost independent of the number of data points.

For scalar output, it returns the sum of squared residuals divided by the number of points. For array output, it returns the SSE residuals divided by the square root of the number of points.

Extends: ionworkspipeline.data_fits.costs.costs.SSE

static evaluate_to_array(model_value, data_value) → ndarray

Evaluate the cost function for an array of residuals.

static evaluate_to_scalar(model_value, data_value)

Evaluate the cost function for a scalar value.

class ionworkspipeline.costs.RMSE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)

Root-mean-square-error cost function.

Takes the square root of the MSE to provide a value in the same units as the original data. This is often used in scientific and engineering applications when the magnitude of error in the original units is important.

This cost function only supports scalar output.

Extends: ionworkspipeline.data_fits.costs.costs.Cost

static evaluate_to_scalar(model_value, data_value)

Evaluate the cost function for a scalar value.

property supports_array_output: bool

Whether the cost function supports array output

property supports_scalar_output: bool

Whether the cost function supports scalar output

class ionworkspipeline.costs.MAE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)

Mean-absolute-error cost function.

Instead of squaring residuals, this cost function uses the absolute values, which makes it less sensitive to outliers compared to squared-error metrics.

For scalar output, it returns the sum of absolute residuals divided by the number of points. For array output, it returns the signed square root of the absolute residuals, normalized by the square root of the number of points.

Extends: ionworkspipeline.data_fits.costs.costs.MLE

static evaluate_to_array(model_value: ndarray, data_value: ndarray) → ndarray

Compute the signed square root of the residuals.

static evaluate_to_scalar(model_value: ndarray, data_value: ndarray) → float64

Evaluate the cost function for a scalar value.

class ionworkspipeline.costs.ChiSquare(variable_standard_deviations, nan_values=None)

Chi-square cost function that measures the weighted sum of squared differences between observed and expected values, normalized by their standard deviations.

The chi-square statistic is calculated as: chi2 = sum((observed - expected) / sigma)**2 where sigma is the standard deviation for each variable.

Parameters

variable_standard_deviationsdict

Dictionary mapping variable names to their standard deviations. For example: {“a”: 0.5, “b”: 0.3} means variable “a” has sigma=0.5 and variable “b” has sigma=0.3.

Notes

For a dataset with N points, if the model fits the data well and the errors are normally distributed, the chi-square value should be approximately N (the number of degrees of freedom).

Extends: ionworkspipeline.data_fits.costs.costs.MLE

scale(model_value, data_value)

How to scale the data for comparison across multiple variables / cases

class ionworkspipeline.costs.Difference(*args, **kwargs)

Cost function consisting of the difference between the model and the data. This is an alias for the MLE cost function, except that the weights are squared for backwards compatibility.

Deprecated since version This: class is deprecated. Please use MLE instead.

Extends: ionworkspipeline.data_fits.costs.costs.MLE

combined_weights(objective_weight: float, variable_weight: float, scale: float) → float

Combine the objective and variable weights. For backwards compatability, we return the squared weight to match the former behavior.