Cost Functions

Base Classes

class ionworkspipeline.data_fits.objective_functions.costs.ObjectiveFunction(objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None)

Base class for all objective/cost functions.

Parameters

objective_weightsdict[str, float], optional

Per-objective weights. Keys are objective names, values are weights. Missing objectives default to weight 1.0.

variable_weightsdict[str, float], optional

Per-variable weights. Keys are variable names, values are weights. Missing variables default to weight 1.0.

Extends: ionworkspipeline.controllers.ConfigMixin

__call__(**kwargs)

Call self as a function.

combine(accumulator: ScalarAccumulator | ResidualAccumulator, other: ScalarAccumulator | ResidualAccumulator | float | ndarray[Any, dtype[_ScalarType_co]]) → ScalarAccumulator | ResidualAccumulator

Combine accumulator values.

Parameters

accumulator

The accumulator to add to.

other

Another accumulator, or a raw value to add with weight 1.0.

Returns

Accumulator

The updated accumulator (same object, mutated in place).

finalize_output(accumulator: ScalarAccumulator | ResidualAccumulator) → float | ndarray[Any, dtype[_ScalarType_co]]

Finalize an accumulator to its output value.

get_objective_names(outputs: dict) → list[str]

Get the names of objectives to evaluate over.

property objective_names: list[str] | None

The configured objective names, or None to use all outputs.

objective_weights(name: str, default: float = 1.0) → float

Get the weight for an objective by name.

property residual_scale_factor: float

Scaling factor for regularizer residuals to match scalar semantics.

Regularizers contribute w * f(x)² in scalar mode. In residual mode they output sqrt(w) * f(x), which after scalarization becomes scalarize_factor * w * f(x)² where scalarize_factor is 1.0 for most costs but 0.5 for GaussianLogLikelihood. To preserve the scalar contribution, regularizer residuals are scaled by sqrt(residual_scale_factor) before accumulation, where residual_scale_factor = 1 / scalarize_factor.

scalarize(value: float | ndarray[Any, dtype[_ScalarType_co]], mode: Literal['scalar', 'residuals'] = 'scalar') → float

Convert a cost value to a scalar.

For scalar mode, returns the value unchanged. For residual mode, computes the sum of squares.

set_objective_names(objective_names: list[str]) → None

Set the names of the objectives this cost applies to.

to_config() → dict

Convert the cost function to parser configuration format.

variable_weights(name: str, default: float = 1.0) → float

Get the weight for a variable by name.

class ionworkspipeline.data_fits.objective_functions.costs.ErrorFunction(normalization: Normalization | str | float | None = None, nan_values=None, objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None, *, scale: str | float | None = None)

Base class for error-based cost functions.

Parameters

normalizationNormalization | str | float, optional

How to normalize weights across variables with different magnitudes. Options: “mean” (default), “identity”, “range”, “sum_squares”, “mean_squares”, “root_mean_squares”, or a float constant. Legacy names “sse”, “mse”, “rmse” are mapped to new names.

nan_valuesstr | float, optional

How to handle NaN values in model output. Defaults to 1e10. Options: float value, “mean”, “min”, or “raise”.

objective_weightsdict[str, float], optional

Per-objective weights.

variable_weightsdict[str, float], optional

Per-variable weights.

scalestr | float, optional

Deprecated. Use normalization instead.

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

nan_values(model_value: ndarray[Any, dtype[_ScalarType_co]], data_value: ndarray[Any, dtype[_ScalarType_co]]) → float

Return the scalar fill value implied by the configured NaN policy.

Kept for backward compatibility.

to_config() → dict

Convert the cost function to parser configuration format.

Error Functions

class ionworkspipeline.data_fits.objective_functions.costs.Max(normalization: Normalization | str | float | None = None, nan_values=None, objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None, *, scale: str | float | None = None)

Maximum error cost function.

Returns the maximum absolute difference between model and data: Max = max|model - data|

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ErrorFunction

class ionworkspipeline.data_fits.objective_functions.costs.SSE(normalization: Normalization | str | float | None = None, nan_values=None, objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None, *, scale: str | float | None = None)

Sum-of-squared-errors cost function.

Calculates the sum of squared differences between model and data: SSE = Σ(model - data)²

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ErrorFunction

class ionworkspipeline.data_fits.objective_functions.costs.MSE(normalization: Normalization | str | float | None = None, nan_values=None, objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None, *, scale: str | float | None = None)

Mean-squared-error cost function.

Calculates the mean of squared differences: MSE = Σ(model - data)² / n

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ErrorFunction

class ionworkspipeline.data_fits.objective_functions.costs.RMSE(normalization: Normalization | str | float | None = None, nan_values=None, objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None, *, scale: str | float | None = None)

Root-mean-squared-error cost function.

Calculates the square root of MSE: RMSE = √(Σ(model - data)² / n)

This cost function only supports scalar output.

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ErrorFunction

class ionworkspipeline.data_fits.objective_functions.costs.MAE(normalization: Normalization | str | float | None = None, nan_values=None, objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None, *, scale: str | float | None = None)

Mean-absolute-error cost function.

Calculates the mean of absolute differences: MAE = Σ|model - data| / n

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ErrorFunction

class ionworkspipeline.data_fits.objective_functions.costs.ChiSquare(variable_standard_deviations: dict[str, float], nan_values=None)

Chi-square cost function with per-variable standard deviations.

Calculates chi² = Σ((model - data) / σ)² where σ is the standard deviation for each variable.

Parameters

variable_standard_deviationsdict[str, float]

Dictionary mapping variable names to their standard deviations.

nan_valuesstr | float, optional

How to handle NaN values.

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ErrorFunction

to_config() → dict

Convert the cost function to parser configuration format.

Multi-Cost Functions

class ionworkspipeline.data_fits.objective_functions.costs.MultiCost(costs: dict, normalization: Normalization | str | float | None = None, nan_values=None, objective_weights: dict[str, float] | None = None, variable_weights: dict[str, float] | None = None, *, scale: str | float | None = None)

Cost function combining multiple costs with weights.

Parameters

costsdict[ObjectiveFunction, float]

Dictionary mapping cost functions to their weights.

normalization, nan_values, objective_weights, variable_weights

Passed to ErrorFunction base class.

scalestr | float, optional

Deprecated. Use normalization instead.

Extends: ionworkspipeline.data_fits.objective_functions.costs.costs.ErrorFunction

scalarize(value: float | ndarray[Any, dtype[_ScalarType_co]], mode: Literal['scalar', 'residuals'] = 'scalar') → float

Convert the finalized cost value to a scalar.

Uses the passed-in value directly, which includes any regularization terms added after MultiCost.__call__ returns. This ensures Evaluation.value_scalarized reflects the true total cost.

property supports_residuals: bool

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property supports_scalar: bool

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

Design Functions

class ionworkspipeline.data_fits.objective_functions.costs.DesignFunction(objective_weights: dict[str, float] | None = None)

Cost function for design optimization problems.

Used for optimization objectives where the goal is to maximize or minimize design metrics (energy density, power density, etc.) rather than fit to data.

Parameters

objective_weightsdict[str, float], optional

Per-objective weights.

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

parse_variable_value(value: float | list | tuple | ndarray[Any, dtype[_ScalarType_co]], variable_name: str) → float

Parse a variable value from model output.