Cost Functions

Base Classes

class ionworkspipeline.data_fits.objective_functions.costs.ObjectiveFunction(objective_weights, variable_weights)

A base cost class.

Extends: ionworkspipeline.controllers.ConfigMixin

__call__(**kwargs)

Call self as a function.

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

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

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

property scalar_output: bool

Whether the cost function supports scalar output

scalarize(value: ndarray[Any, dtype[_ScalarType_co]] | 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.

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

to_config() → dict

Convert the cost function back to parser configuration format.

Returns

dict

Configuration dictionary for this cost function

variable_weights(name, default=None)

How to weight the output variables

class ionworkspipeline.data_fits.objective_functions.costs.ErrorFunction(scale='mean', nan_values=None, objective_weights=None, variable_weights=None)

A base class for error measures (also known as distance functions)

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.

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ObjectiveFunction

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.

initialize_output(scalar_output: bool | None = None)

Initialize the cost value for scalar costs.

Returns

float

Initial cost value of 0.0

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.

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

to_config() → dict

Convert the cost function back to parser configuration format.

Returns

dict

Configuration dictionary for this cost function

Error Functions

class ionworkspipeline.data_fits.objective_functions.costs.MLE(*args, **kwargs)

Sum-of-squared-errors cost function (legacy name).

Deprecated since version This: class computes sum of squared errors, not a proper maximum-likelihood estimate. Use ionworkspipeline.costs.SSE for sum-of-squared-errors, or ionworkspipeline.costs.GaussianLogLikelihood for a proper Gaussian log-likelihood.

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.SSE

class ionworkspipeline.data_fits.objective_functions.costs.Max(scale='mean', 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.objective_functions.costs.costs.ErrorFunction

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.data_fits.objective_functions.costs.SSE(scale='mean', nan_values=None, objective_weights=None, variable_weights=None)

Sum-of-squared-errors cost function.

Calculates the sum of squared differences 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.objective_functions.costs.costs.ErrorFunction

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.data_fits.objective_functions.costs.MSE(scale='mean', 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.objective_functions.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.data_fits.objective_functions.costs.RMSE(scale='mean', 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.objective_functions.costs.costs.ErrorFunction

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.data_fits.objective_functions.costs.MAE(scale='mean', 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.objective_functions.costs.costs.SSE

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.data_fits.objective_functions.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.objective_functions.costs.costs.SSE

scale(model_value, data_value)

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

to_config() → dict

Convert the cost function back to parser configuration format.

Returns

dict

Configuration dictionary for this cost function

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

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

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

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.SSE

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.

Multi-Cost Functions

class ionworkspipeline.data_fits.objective_functions.costs.MultiCost(costs, accumulator=<built-in function sum>, scale='mean', nan_values=None, objective_weights=None, variable_weights=None)

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.objective_functions.costs.costs.ErrorFunction

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

Design Functions

class ionworkspipeline.data_fits.objective_functions.costs.DesignFunction(objective_weights=None)

A generalized design cost function for optimization problems.

This class serves as a base for design optimization objectives where the goal is to maximize (or minimize) certain design metrics like energy density, power density, etc.

Parameters

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.

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ObjectiveFunction

parse_variable_value(value: float | list | tuple | ndarray, variable_name: str) → float

Parse a variable value from the model output.

Parameters

valuefloat | list | tuple | np.ndarray

Value to parse.

variable_namestr

Name of the variable to extract.

Returns

float

The parsed variable value.

Raises

ValueError

If the variable value is not a valid number.

property supports_array_output: bool

Design functions typically don’t support array output.

property supports_scalar_output: bool

Design functions support scalar output for optimization.