# objeval.m

Objective function evaluation. Call and collect the required outputs from an objective function.

## Syntax

    [data,fx,grad,hess]=objeval(x,obj_fun_handle, data)


## Description

This function is used by fminnewton.m and fminsimplex.m to request the correct amount of arguments from an objective function. For example: a simplex method will only ever require the objective function value; the Newton-Raphson method does not require a Hessian matrix during a line-search; a backtracking line-search does not require a gradient evaluation. This function ensures that the only objective function calculations performed are those required.

## Arguments

    x                  - objective at this iterate (waveform)

obj_fun_handle     - function handle to the objective function (e.g. @obj_fun_name).

data               - data structure inherited from fminnewton.m or fminsimplex.m.


## Returns

    data               - modified data structure with diagnostics from the objective.

fx                 - objective function value at x.

required for gradient based optimisation in fminnewton.m.

hess               - Hessian of the objective function at x.
required for Newton-Raphson optimisation in fminnewton.m.


## Notes

This function also allows the objective function value to be returned as a vector, where the first element is the objective value to display (i.e. the true fidelity from GRAPE), and further elements are penalties to the objective function included in the optimisation. Must set optim.npen > 0 in the options for fminnewton.m/fminsimplex.m