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:

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
  
  Return type:
  
  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
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.

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
Return type:: 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

Adding new cost functions

The FittingProblem and CostFunc classes

The `FittingProblem` and `CostFunc` classes