Adding new cost functions

This section describes how to add cost functions to benchmarking in FitBenchmarking

In order to add a new cost function, <cost_func>, you will need to:

  1. Create fitbenchmarking/cost_func/<cost_func>_cost_func.py, which contains a new subclass of CostFunc. Then implement the methods:

    • abstract CostFunc.eval_cost()

      Evaluate the cost function

      Parameters

      params (list) – The parameters to calculate residuals for

      Returns

      evaluated cost function

      Return type

      float

    • abstract CostFunc.jac_res()

      Uses the Jacobian of the model to evaluate the Jacobian of the cost function residual, \(\nabla_p r(x,y,p)\), at the given parameters.

      Parameters

      params (list) – The parameters at which to calculate Jacobians

      Returns

      evaluated Jacobian of the residual at each x, y pair

      Return type

      a list of 1D numpy arrays

    • abstract CostFunc.jac_cost()

      Uses the Jacobian of the model to evaluate the Jacobian of the cost function, \(\nabla_p F(r(x,y,p))\), at the given parameters.

      Parameters

      params (list) – The parameters at which to calculate Jacobians

      Returns

      evaluated Jacobian of the cost function

      Return type

      1D numpy array

    • abstract CostFunc.hes_res()

      Uses the Hessian of the model to evaluate the Hessian of the cost function residual, \(\nabla_p^2 r(x,y,p)\), at the given parameters.

      Parameters

      params (list) – The parameters at which to calculate Hessians

      Returns

      evaluated Hessian and Jacobian of the residual at

      each x, y pair :rtype: tuple(list of 2D numpy arrays, list of 1D numpy arrays)

    • abstract CostFunc.hes_cost()

      Uses the Hessian of the model to evaluate the Hessian of the cost function, \(\nabla_p^2 F(r(x,y,p))\), at the given parameters.

      Parameters

      params (list) – The parameters at which to calculate Hessians

      Returns

      evaluated Hessian of the cost function

      Return type

      2D numpy array

  2. Document the available cost functions by:

  • adding <cost_func> to the cost_func_type option in Fitting Options.

  • updating any example files in the examples directory

  • adding the new cost function to the Cost functions user docs.

  1. Create tests for the cost function in fitbenchmarking/cost_func/tests/test_cost_func.py.

The FittingProblem and CostFunc classes

When adding new cost functions, you will find it helpful to make use of the following members of the FittingProblem class.

class fitbenchmarking.parsing.fitting_problem.FittingProblem(options)

Definition of a fitting problem, which will be populated by a parser from a problem definition file.

Onces populated, this should include the data, the function and any other additional requirements from the data.

data_e

numpy array The errors or weights

data_x

numpy array The x-data

data_y

numpy array The y-data

eval_model(params, **kwargs)

Function evaluation method

Parameters

params (list) – parameter value(s)

Returns

data values evaluated from the function of the problem

Return type

numpy array

You will also find it useful to implement the subclass members of CostFunc, Jacobian and Hessian.

class fitbenchmarking.cost_func.base_cost_func.CostFunc(problem)

Base class for the cost functions.

abstract eval_cost(params, **kwargs)

Evaluate the cost function

Parameters

params (list) – The parameters to calculate residuals for

Returns

evaluated cost function

Return type

float

abstract hes_cost(params, **kwargs)

Uses the Hessian of the model to evaluate the Hessian of the cost function, \(\nabla_p^2 F(r(x,y,p))\), at the given parameters.

Parameters

params (list) – The parameters at which to calculate Hessians

Returns

evaluated Hessian of the cost function

Return type

2D numpy array

abstract hes_res(params, **kwargs)

Uses the Hessian of the model to evaluate the Hessian of the cost function residual, \(\nabla_p^2 r(x,y,p)\), at the given parameters.

Parameters

params (list) – The parameters at which to calculate Hessians

Returns

evaluated Hessian and Jacobian of the residual at

each x, y pair :rtype: tuple(list of 2D numpy arrays, list of 1D numpy arrays)

abstract jac_cost(params, **kwargs)

Uses the Jacobian of the model to evaluate the Jacobian of the cost function, \(\nabla_p F(r(x,y,p))\), at the given parameters.

Parameters

params (list) – The parameters at which to calculate Jacobians

Returns

evaluated Jacobian of the cost function

Return type

1D numpy array

abstract jac_res(params, **kwargs)

Uses the Jacobian of the model to evaluate the Jacobian of the cost function residual, \(\nabla_p r(x,y,p)\), at the given parameters.

Parameters

params (list) – The parameters at which to calculate Jacobians

Returns

evaluated Jacobian of the residual at each x, y pair

Return type

a list of 1D numpy arrays

class fitbenchmarking.jacobian.base_jacobian.Jacobian(problem)

Base class for Jacobian.

abstract eval(params, **kwargs)

Evaluates Jacobian of the model, \(\nabla_p f(x,p)\), at the point given by the parameters.

Parameters

params (list) – The parameter values at which to evaluate the Jacobian

Returns

Computed Jacobian

Return type

numpy array

class fitbenchmarking.hessian.base_hessian.Hessian(problem, jacobian)

Base class for Hessian.

abstract eval(params, **kwargs)

Evaluates Hessian of the model

Parameters

params (list) – The parameter values to find the Hessian at

Returns

Computed Hessian

Return type

3D numpy array