Objective Functions

The objective functions module provides a comprehensive framework for defining optimization objectives in data fitting and design optimization problems.

Main Class

class ionworkspipeline.data_fits.objective_functions.AugmentedObjectiveFunction(evaluate_inputs_and_outputs: callable, cost: ObjectiveFunction, mode: Literal['scalar', 'residuals'] = 'scalar', eq_constraints: ConstraintSet | None = None, ineq_constraints: ConstraintSet | None = None, penalties: PenaltySet | None = None, priors: PriorSet | None = None)

Objective function combining likelihood with regularization terms.

The objective function has the general form: Objective = Likelihood + Equality Constraints + Inequality Constraints + Penalties + Priors

Parameters

evaluate_inputs_and_outputscallable

Function to evaluate model inputs and outputs.

costObjectiveFunction

The cost function that defines how to compute the likelihood.

modeOutputMode

Output mode: “scalar” for scalar optimizers, “residuals” for least-squares.

eq_constraintsConstraintSet, optional

Equality constraints (should evaluate to zero).

ineq_constraintsConstraintSet, optional

Inequality constraints (should evaluate to >= 0).

penaltiesPenaltySet, optional

Additional penalty terms.

priorsPriorSet, optional

Prior probability distributions on parameters.

add_regularization(accumulator, x: ndarray)

Add all regularization terms to the accumulator.

Parameters

accumulatorAccumulator

Current accumulated value.

xnp.ndarray

Parameter vector.

Returns

Accumulator

Updated accumulator with regularization terms.

property cost: ObjectiveFunction

The cost function.

property eq_constraints: ConstraintSet | None

Equality constraints, if any.

evaluate_from_outputs(x: ndarray, outputs: dict, inputs: dict | None = None) → tuple[float | ndarray, float]

Evaluate objective function from pre-computed outputs.

Parameters

xnp.ndarray

Parameter vector.

outputsdict

Pre-computed model outputs.

inputsdict, optional

Current parameter values for cost functions that need them.

Returns

tuple[float | np.ndarray, float]

(value, scalarized_value)

evaluate_full(x: ndarray) → Evaluation

Evaluate the complete objective function with full details.

Parameters

xnp.ndarray

Parameter vector to evaluate.

Returns

Evaluation

Contains value, scalarized value, inputs, and outputs.

property evaluate_inputs_and_outputs: callable

Function to evaluate inputs and outputs.

finalize_output(accumulator) → float | ndarray

Finalize the accumulator to its output value.

gradient(x: ndarray, cost: ObjectiveFunction | None = None, options: dict | None = None) → ndarray

Compute gradient of the objective function.

Parameters

xnp.ndarray

Parameter vector.

costObjectiveFunction, optional

Cost function to use.

optionsdict, optional

Options for numdifftools finite difference.

Returns

np.ndarray

Gradient of the objective function.

hessian(x: ndarray, cost: ObjectiveFunction | None = None, gauss_newton: bool | None = None, options: dict | None = None) → ndarray

Compute Hessian matrix of the objective function.

Parameters

xnp.ndarray

Parameter vector.

costObjectiveFunction, optional

Cost function to use.

gauss_newtonbool, optional

Use Gauss-Newton approximation. Default False.

optionsdict, optional

Options for numdifftools finite difference.

Returns

np.ndarray

Hessian matrix.

property ineq_constraints: ConstraintSet | None

Inequality constraints, if any.

jacobian(x: ndarray, cost: ObjectiveFunction | None = None, options: dict | None = None) → ndarray

Compute Jacobian matrix of the objective function.

Parameters

xnp.ndarray

Parameter vector.

costObjectiveFunction, optional

Cost function to use.

optionsdict, optional

Options for numdifftools finite difference.

Returns

np.ndarray

Jacobian matrix.

likelihood(outputs: dict, inputs: dict | None = None)

Compute the likelihood term.

Parameters

outputsdict

Model outputs.

inputsdict, optional

Current parameter values.

Returns

Accumulator

Unfinalized accumulator for composition with regularizers.

property mode: Literal['scalar', 'residuals']

The output mode: “scalar” or “residuals”.

property penalties: PenaltySet | None

Penalty terms, if any.

property priors: PriorSet | None

Prior terms, if any.

residuals(x: ndarray, cost: ObjectiveFunction | None = None) → ndarray

Compute residuals of the objective function.

Parameters

xnp.ndarray

Parameter vector.

costObjectiveFunction, optional

Cost function to use.

Returns

np.ndarray

Residuals of the objective function.

scalarize(value: float | ndarray) → float

Convert value to scalar.

set_cost(cost: ObjectiveFunction)

Set the cost function.

Parameters

costObjectiveFunction

The cost function to set.

set_eq_constraints(eq_constraints: ConstraintSet | None = None)

Set equality constraints.

set_evaluate_inputs_and_outputs(evaluate_inputs_and_outputs: Callable)

Set the evaluation function.

set_ineq_constraints(ineq_constraints: ConstraintSet | None = None)

Set inequality constraints.

set_penalties(penalties: PenaltySet | None = None)

Set penalty terms.

set_priors(priors: PriorSet | None = None)

Set prior terms.

Submodules