controllers.rst

Adding Fitting Software

Controllers are used to interface FitBenchmarking with the various fitting packages. Controllers are responsible for converting the problem into a format that the fitting software can use, and converting the result back to a standardised format (numpy arrays). As well as this, the controller must be written so that the fitting is separated from the preparation wherever possible in order to give accurate timings for the fitting. Supported controllers are found in fitbenchmarking/controllers/.

In order to add a new controller, you will need to:

1. Give the software a name <software_name>. This will be used by users when selecting this software.

2. Create fitbenchmarking/controllers/<software_name>_controller.py which contains a new subclass of ~fitbenchmarking.controllers.base_controller.Controller.

   Note

   Please note that if the fitting package being added uses Matlab, then the new controller should also inherit from the mixin class ~fitbenchmarking.controllers.matlab_mixin.MatlabMixin.

   fitbenchmarking.controllers.matlab_mixin.MatlabMixin

   The new controller should implement four functions, as well as initializing the dictionary algorithm_check:

• fitbenchmarking.controllers.base_controller.Controller.algorithm_check

• fitbenchmarking.controllers.base_controller.Controller.__init__()

• fitbenchmarking.controllers.base_controller.Controller.setup()

• fitbenchmarking.controllers.base_controller.Controller.fit()

• fitbenchmarking.controllers.base_controller.Controller.cleanup()

By default, a controller does not accept Jacobian or Hessian information. If the controller being added can use hessians and/or jacobians, then the following controller attributes should be set:

• fitbenchmarking.controllers.base_controller.Controller.jacobian_enabled_solvers()

• fitbenchmarking.controllers.base_controller.Controller.hessian_enabled_solvers()

3. Add the new software to the default options, following the instructions in options_extend.

Your new software is now fully hooked in with FitBenchmarking, and you can compare it with the current software. You are encouraged to contribute this to the repository so that other can use this package. To do this need to follow our guidelines and our workflow, and you'll also need to

4. Document the available minimizers (see fitting_option, minimizer_option), including licencing information, if appropriate. Note: make sure that you use <software_name> in these places so that the software links in the HTML tables link correctly to the documentation. Add the software to examples/all_software.ini.

   You should also ensure that the available minimizers are catagorised correctly in self.algorithm_check using the algorithm type <algorithm_type> options. Please refer to the algorithms page for more information about each algorithm type.

5. Create tests for the software in fitbenchmarking/controllers/tests/test_controllers.py. If the package is pip installable then add the tests to the DefaultControllerTests class and if not add to the ExternalControllerTests class. Unless the new controller is more complicated than the currently available controllers, this can be done by following the example of the others.
6. If the software is deterministic, add the software to the regression tests in fitbenchmarking/systests/test_regression.py.
7. If pip installable add to install_requires in setup.py and add to the installation step in .github/workflows/release.yml. If not, document the installation procedure in external-instructions and update the FullInstall Docker Container -- the main developers will help you with this.

Note

For ease of maintenance, please add new controllers to a list of software in alphabetical order.

The ~fitbenchmarking.parsing.fitting_problem.FittingProblem, ~fitbenchmarking.cost_func.base_cost_func.CostFunc and ~fitbenchmarking.jacobian.base_jacobian.Jacobian classes

When adding new minimizers, you will find it helpful to make use of the following members of the ~fitbenchmarking.parsing.fitting_problem.FittingProblem, subclasses of ~fitbenchmarking.cost_func.base_cost_func.CostFunc and subclasses of ~fitbenchmarking.jacobian.base_jacobian.Jacobian classes:

fitbenchmarking.parsing.fitting_problem

fitbenchmarking.parsing.fitting_problem.FittingProblem

fitbenchmarking.cost_func.base_cost_func

fitbenchmarking.cost_func.base_cost_func.CostFunc

fitbenchmarking.jacobian.base_jacobian

fitbenchmarking.jacobian.base_jacobian.Jacobian