Objective functions

class ionworkspipeline.data_fits.ObjectiveFunction(evaluate_inputs_and_outputs: callable, cost: Cost, eq_constraints: EqualityConstraintSet | None = None, ineq_constraints: InequalityConstraintSet | None = None, penalties: PenaltySet | None = None, priors: PriorSet | None = None)

A class that defines an objective function for optimization as the sum of a likelihood term and optional regularization terms.

The objective function has the general form:

Objective = Likelihood + Equality Constraints + Inequality Constraints + Penalties + Priors

where: - Likelihood: The main data fitting term that measures how well the model fits the data - Equality Constraints: Terms that enforce equality constraints (should evaluate to zero) - Inequality Constraints: Terms that enforce inequality constraints (should evaluate to greater than zero) - Penalties: Additional penalty terms to guide the optimization - Priors: Prior probability distributions on parameters (for Bayesian approaches)

All terms are combined using the provided cost function’s combine method, which determines whether the output is a scalar or vector value.

Parameters

evaluate_inputs_and_outputscallable

The function to evaluate the inputs and outputs.

costionworkspipeline.costs.Cost

The cost function that defines how to combine and process objective values.

eq_constraintsionworkspipeline.constraints.EqualityConstraintSet, optional

Equality constraints that should evaluate to zero.

ineq_constraintsionworkspipeline.constraints.InequalityConstraintSet, optional

Inequality constraints that should evaluate to greater than zero.

penaltiesionworkspipeline.penalties.PenaltySet, optional

Additional penalty terms to add to the objective.

priorsionworkspipeline.regularizers.PriorSet, optional

Prior probability distributions on parameters.

Notes

The objective function combines the likelihood with optional regularization terms (constraints, penalties, and priors) using the provided cost function’s combine method. The final output matches the cost function’s scalar_output property.

add_regularization(value, x)

Add all regularization terms to the output.

combine(value: float | list, value_new: ndarray, scalar_output: bool | None = None) float | list

Combine a new value with the current output using the cost function.

Parameters

valuefloat or list

Current accumulated cost value

value_newnumpy.ndarray

New value to combine with the current cost

scalar_outputbool | None

Whether the cost function returns scalar values

Returns

float or list

Updated cost value after combining with the new value

property cost: Cost

The cost function used to combine and process objective values.

property eq_constraints: EqualityConstraintSet | None

The equality constraints, if any.

evaluate_full(x: ndarray) Evaluation

Evaluate the complete objective function: likelihood + all regularization terms.

Parameters

xnp.ndarray

Parameter vector to evaluate.

Returns

inputsdict

Inputs to evaluate.

outputsdict

Outputs to evaluate.

valuefloat | np.ndarray

The combined objective value (scalar or array depending on cost function).

value_scalarizedfloat | np.ndarray

The scalarized objective value.

property evaluate_inputs_and_outputs: callable

The function to evaluate the inputs and outputs.

finalize_output(value: float | list, scalar_output: bool | None = None) float | ndarray

Process the final output using the cost function.

Parameters

valuefloat or list

The accumulated cost value to finalize

Returns

float or numpy.ndarray

The finalized cost value, which may be a scalar or array depending on the cost function type

scalar_outputbool | None

Whether the cost function returns scalar values

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

Compute the gradient of the objective function.

Parameters

xnp.ndarray

The parameter vector to evaluate.

costCost | None

The cost function to use. By default, the current cost is used.

optionsdict | None

The options for the numdifftools finite difference method.

Returns

np.ndarray

The gradient of the objective function.

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

Compute the Hessian matrix of the objective function.

Parameters

xnp.ndarray

The parameter vector to evaluate.

costCost | None

The cost function to use. If None, uses the current cost function.

gauss_newtonbool | None

Whether to use the Gauss-Newton method. If None, the Gauss-Newton method is not used and the Hessian is computed using finite differences.

optionsdict | None

The options for the numdifftools finite difference method.

Returns

np.ndarray

The Hessian matrix of the objective function.

Raises

ValueError

If the cost function does not support array outputs.

property ineq_constraints: InequalityConstraintSet | None

The inequality constraints, if any.

initialize_output(scalar_output: bool | None = None) float | list

Initialize the output container based on the cost function.

Returns

float or list

An empty container appropriate for the cost function type. For scalar costs, returns 0.0. For vector costs, returns an empty list.

scalar_outputbool | None

Whether the cost function returns scalar values

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

Compute the Jacobian matrix of the objective function.

Parameters

xnp.ndarray

The parameter vector to evaluate.

costCost | None

The cost function to use. If None, uses the current cost function.

optionsdict | None

The options for the numdifftools finite difference method.

Returns

np.ndarray

The Jacobian matrix of the objective function.

Raises

ValueError

If the cost function does not support array outputs.

likelihood(outputs)

Add the likelihood term to the output.

property penalties: PenaltySet | None

The penalty terms, if any.

property priors: PriorSet | None

The prior terms, if any.

residuals(x: ndarray, cost: Cost | None = None) ndarray

Compute the gradient of the objective function.

Parameters

xnp.ndarray

The parameter vector to evaluate.

costCost | None

The cost function to use. By default, the current cost is used.

Returns

np.ndarray: The residuals of the objective function.

property scalar_output: bool

Whether the objective function returns scalar values.

scalarize(value: float | ndarray) float

Scalarize the value.

set_cost(cost: Cost, reset_scalar_output: bool = True)

Set the cost function.

Parameters

costionworkspipeline.costs.Cost

The cost function to set.

reset_scalar_outputbool

Whether to reset the scalar_output flag to the cost’s scalar_output flag. If False, the scalar_output flag will be left unchanged. Default is True.

set_eq_constraints(eq_constraints: EqualityConstraintSet | None = None)

Set the equality constraints.

set_evaluate_inputs_and_outputs(evaluate_inputs_and_outputs: Callable)

Set the function to evaluate the inputs and outputs.

set_ineq_constraints(ineq_constraints: InequalityConstraintSet | None = None)

Set the inequality constraints.

set_penalties(penalties: PenaltySet | None = None)

Set the penalty terms.

set_priors(priors: PriorSet | None = None)

Set the prior terms.

set_scalar_output(scalar_output: bool)

Set the scalar output flag.