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)¶
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.
- apply_weights(value, weight)¶
Apply the weights to the value
- combine(cost, value)¶
Update the cost with a new value. Must be implemented by subclasses.
- static combined_weights(objective_weight, variable_weight, scale)¶
Combine the objective and variable weights
- finalize_output(cost)¶
Finalize the cost computation. Must be implemented by subclasses.
- initialize_output()¶
Initialize the cost value. Must be implemented by subclasses.
- nan_values(model_value, data_value)¶
How to deal with nan values
- objective_weights(name, default=None)¶
How to weight the output objectives
- property scalar_output¶
The type of the cost function output
- static scalarize(cost) 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
- variable_weights(name, default=None)¶
How to weight the output variables
- class ionworkspipeline.costs.ScalarCost(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Cost function that returns a scalar value
Extends:
ionworkspipeline.data_fits.costs.costs.Cost- combine(cost: float, value: float) 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
- finalize_output(cost: float) float¶
Finalize the scalar cost computation.
Parameters¶
- costfloat
Final accumulated cost value
Returns¶
- float
The final cost value
- initialize_output()¶
Initialize the cost value for scalar costs.
Returns¶
- float
Initial cost value of 0.0
- property scalar_output¶
The type of the cost function output
- static scalarize(cost) float64¶
Convert the cost to a scalar value. Scalar costs are already scalar, so this is the value itself.
- class ionworkspipeline.costs.ArrayCost(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Cost function that returns an array value
Extends:
ionworkspipeline.data_fits.costs.costs.Cost- apply_weights(value, weight)¶
Apply the weights to the value
- combine(cost: list, value: ndarray) list¶
Update the array cost by appending a new value.
Parameters¶
- costlist
Current list of cost values
- valuearray-like
New value to append to the cost list
Returns¶
- list
Updated cost list
- finalize_output(cost: list) ndarray¶
Finalize the array cost by concatenating all values.
Parameters¶
- costlist
List of cost arrays to concatenate
Returns¶
- numpy.ndarray
Concatenated array of all cost values
- initialize_output()¶
Initialize the cost array for array-based costs.
Returns¶
- list
Empty list to store cost values
- property scalar_output¶
The type of the cost function output
- 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.
Extends:
ionworkspipeline.data_fits.costs.costs.Cost- apply_weights(value, weight)¶
Apply the weights to the value
- combine(cost, value)¶
Update the array cost by appending a new value.
Parameters¶
- costlist
Current list of cost values
- valuearray-like
New value to append to the cost list
Returns¶
- list
Updated cost list
- finalize_output(cost)¶
Finalize the array cost by concatenating all values.
Parameters¶
- costlist
List of cost arrays to concatenate
Returns¶
- numpy.ndarray
Concatenated array of all cost values
- initialize_output()¶
Initialize the cost array for array-based costs.
Returns¶
- list
Empty list to store cost values
- property scalar_output¶
The type of the cost function output
- scalarize(cost: 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.
- class ionworkspipeline.costs.Difference(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Cost function consisting of the difference between the model and the data.
- class ionworkspipeline.costs.AbsoluteDifference(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Cost function consisting of the absolute difference between the model and the data.
- class ionworkspipeline.costs.SquaredDifference(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Cost function consisting of the squared difference between the model and the data.
- 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. If there are multiple outputs, adds them together.
- class ionworkspipeline.costs.SSE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Sum-square-error cost function.
- class ionworkspipeline.costs.MSE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Mean-square-error cost function
- class ionworkspipeline.costs.RMSE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Root-mean-square-error cost function
- class ionworkspipeline.costs.MAE(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Mean-absolute-error cost function
- 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.ScalarCost- scale(model_value, data_value)¶
How to scale the data for comparison across multiple variables / cases
- class ionworkspipeline.costs.Wasserstein(scale=None, nan_values=None, objective_weights=None, variable_weights=None)¶
Wasserstein (or earth mover’s) distance