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 compute_surrogate_target: bool

Whether evaluate_full also computes value_for_surrogate.

property cost: ObjectiveFunction

The cost function.

property eq_constraints: ConstraintSet | None

Equality constraints, if any.

evaluate_for_surrogate(x: ndarray, outputs: dict, inputs: dict | None = None) → float

Evaluate a constraint-free surrogate target.

Parameters

xnp.ndarray

Parameter vector.

outputsdict

Pre-computed model outputs.

inputsdict, optional

Current parameter values for cost functions that need them.

Returns

float

Scalarized objective with action-constraint penalties removed.

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 objective and return full evaluation data.

Parameters

xnp.ndarray

Parameter vector to evaluate.

Returns

Evaluation

Value, scalarized value, inputs, outputs, and optional value_for_surrogate.

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.

Uses the analytic cost gradient when available (see _analytic_derivative()); otherwise falls back to a numdifftools finite difference.

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.

Uses the analytic cost residual Jacobian when available (see _analytic_derivative()); otherwise falls back to a numdifftools finite difference.

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_param_jacobian_provider(provider: Callable | None)

Register the input-vs-x parameter Jacobian provider for analytic mode.

Parameters

providercallable | None

provider(x) -> (input_names, dinput_dx) where input_names is the flattened input-parameter column order matching the cost’s analytic derivative, and dinput_dx is the diagonal d(input)/dx (one entry per input; x_to_inputs is input_i = x_i * scale_i). Passing None disables the analytic path (finite-difference fallback).

set_penalties(penalties: PenaltySet | None = None)

Set penalty terms.

set_priors(priors: PriorSet | None = None)

Set prior terms.

Submodules