fitbenchmarking.controllers.base_controller module

Implements the base class for the fitting software controllers.

class fitbenchmarking.controllers.base_controller.Controller(cost_func)

Bases: object

Base class for all fitting software controllers. These controllers are intended to be the only interface into the fitting software, and should do so by implementing the abstract classes defined here.

VALID_FLAGS = [0, 1, 2, 3, 4, 5, 6, 7]
algorithm_check = {'all': [], 'bfgs': [], 'conjugate_gradient': [], 'deriv_free': [], 'gauss_newton': [], 'general': [], 'global_optimization': [], 'levenberg-marquardt': [], 'ls': [], 'simplex': [], 'steepest_descent': [], 'trust_region': []}

Within the controller class, you must initialize a dictionary, algorithm_check, such that the keys are given by:

  • all - all minimizers

  • ls - least-squares fitting algorithms

  • deriv_free - derivative free algorithms (these are algorithms that cannot use information about derivatives – e.g., the Simplex method in Mantid)

  • general - minimizers which solve a generic min f(x)

  • simplex - derivative free simplex based algorithms e.g. Nelder-Mead

  • trust_region - algorithms which emply a trust region approach

  • levenberg-marquardt - minimizers that use the Levenberg-Marquardt algorithm

  • gauss_newton - minimizers that use the Gauss Newton algorithm

  • bfgs - minimizers that use the BFGS algorithm

  • conjugate_gradient - Conjugate Gradient algorithms

  • steepest_descent - Steepest Descent algorithms

  • global_optimization - Global Optimization algorithms

The values of the dictionary are given as a list of minimizers for that specific controller that fit into each of the above categories. See for example the GSL controller.

check_attributes()

A helper function which checks all required attributes are set in software controllers

check_bounds_respected()

Check whether the selected minimizer has respected parameter bounds

check_minimizer_bounds(minimizer)

Helper function which checks whether the selected minimizer from the options (options.minimizer) supports problems with parameter bounds

Parameters

minimizer (str) – string of minimizers selected from the options

abstract cleanup()

Retrieve the result as a numpy array and store results.

Convert the fitted parameters into a numpy array, saved to self.final_params, and store the error flag as self.flag.

The flag corresponds to the following messages:

flag()
0: Successfully converged
1: Software reported maximum number of iterations exceeded
2: Software run but didn’t converge to solution
3: Software raised an exception
4: Solver doesn’t support bounded problems
5: Solution doesn’t respect parameter bounds
6: Solver has exceeded maximum allowed runtime
7: Validation of the provided options failed
controller_name = None

A name to be used in tables. If this is set to None it will be inferred from the class name.

eval_chisq(params, x=None, y=None, e=None)

Computes the chisq value

Parameters

  • params (list) – The parameters to calculate residuals for

  • x (numpy array, optional) – x data points, defaults to self.data_x

  • y (numpy array, optional) – y data points, defaults to self.data_y

  • e (numpy array, optional) – error at each data point, defaults to self.data_e

Returns

The sum of squares of residuals for the datapoints at the given parameters

Return type

numpy array

execute()

Starts and stops the timer used to check if the fit reaches the ‘max_runtime’. In the middle, it calls self.fit().

abstract fit()

Run the fitting.

This will be timed so should include only what is needed to fit the data.

property flag
0: Successfully converged
1: Software reported maximum number of iterations exceeded
2: Software run but didn’t converge to solution
3: Software raised an exception
4: Solver doesn’t support bounded problems
5: Solution doesn’t respect parameter bounds
6: Solver has exceeded maximum allowed runtime
7: Validation of the provided options failed
hessian_enabled_solvers = []

Within the controller class, you must define the list hessian_enabled_solvers if any of the minimizers for the specific software are able to use hessian information.

  • hessian_enabled_solvers: a list of minimizers in a specific

software that allow Hessian information to be passed into the fitting algorithm

incompatible_problems = []

A list of incompatible problem formats for this controller.

jacobian_enabled_solvers = []

Within the controller class, you must define the list jacobian_enabled_solvers if any of the minimizers for the specific software are able to use jacobian information.

  • jacobian_enabled_solvers: a list of minimizers in a specific

software that allow Jacobian information to be passed into the fitting algorithm

prepare()

Check that function and minimizer have been set. If both have been set, run self.setup().

record_alg_type(minimizer, algorithm_type)

Helper function which records the algorithm types of the selected minimizer that match those chosen in options

Parameters

  • minimizer (str) – string of minimizers selected from the options

  • algorithm_type (list) – the algorithm type selected from the options

abstract setup()

Setup the specifics of the fitting.

Anything needed for “fit” that can only be done after knowing the minimizer to use and the function to fit should be done here. Any variables needed should be saved to self (as class attributes).

If a solver supports bounded problems, then this is where value_ranges should be set up for that specific solver. The default format is a list of tuples containing the lower and upper bounds for each parameter e.g. [(p1_lb, p2_ub), (p2_lb, p2_ub),…]

property software

Return the name of the software.

This assumes the class is named ‘<software>Controller’

validate() → None

Validates that the provided options are compatible with each other. If there are some invalid options, the relevant exception is raised.

validate_minimizer(minimizer, algorithm_type)

Helper function which checks that the selected minimizer from the options (options.minimizer) exists and whether the minimizer is in self.algorithm_check[options.algorithm_type] (this is a list set in the controller)

Parameters

  • minimizer (str) – string of minimizers selected from the options

  • algorithm_type (list) – the algorithm type selected from the options