Adding new Jacobians

FitBenchmarking allows the use of custom methods for evaluating the Jacobian of the model. This section describes how to add further methods within FitBenchmarking

In order to add a new Jacobian evaluation method, <jac_method>, you will need to:

1. Create fitbenchmarking/jacobian/<jac_method>_jacobian.py, which contains a new subclass of Jacobian. Then implement the method:

   • abstract Jacobian.eval()

     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

   The numerical method is set sequentially within loop_over_jacobians() by using the method attribute of the class.

2. Enable the new method as an option in Fitting Options, following the instructions in Adding new Options. Specifically:

   • Amend the VALID_FITTING dictionary so that the element associated with the jac_method key contains the new <jac_method>.

   • Extend the VALID_JACOBIAN dictionary to have a new key <jac_method>, with the associated element being a list of valid options for this Jacobian.

   • Extend the DEFAULT_JACOBIAN dictionary to have a new key <jac_method>, with the associated element being a subset of the valid options added in VALID_JACOBIAN in the previous step.

   • Amend the file fitbenchmarking/utils/tests/test_options_jacobian.py to include tests for the new options.

3. Document the available Jacobians by:

• adding a list of available method options to the docs for Jacobian Options, and including licencing information, if appropriate.

• updating any example files in the examples directory

4. Create tests for the Jacobian evaluation in fitbenchmarking/jacobian/tests/test_jacobians.py.

The FittingProblem class

When adding new Jacobian, 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