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) → 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

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) → 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

property ineq_constraints: InequalityConstraintSet | None

The inequality constraints, if any.

initialize_output() → 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.

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.

property scalar_output: bool

Whether the objective function returns scalar values.

set_cost(cost: Cost)

Set the cost function.

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.