Optimagic

class sherpa.optmethods.optoptimagic.Optimagic(name: str | None = None, **kwargs)[source] [edit on github]

Bases: OptMethod

Optimizer using the optimagic library.

This class is a wrapper around the optimagic optimization methods. It provides a common interface for all optimizers in the optimagic library. See the very useful and extensive optimagic documentation for general information on optimizations and all the algorithms available.

Sherpa will automatically convert statistics functions, input values, parameter limits etc. to the format required by the scipy function. The following attributes of optimagic.minimize can be set as attributes of this class.

Some optimizers in optimagic are designed tobwork with explicitly with least-squares or likelihood functions and can converge faster if the optimizer is given the full array of per-bin values. Sherpa will automatically detect if the optimizer is one of those and return the statistic values in the correct format. However, it is up to user to make sure that statistic and the optimizer are compatible. For example, one can feed a LeastSq statistic into the optimagic.algos.bhhh optimizer (which expects a likelihood), but the fit might take much longer or may not converge at all and the results could be wrong.

algorithm: The optimization algorithm to use, see https://optimagic.readthedocs.io/en/latest/algorithms.html for list of optimizers and their dependencies. Can be a string, subclass of optimagic.algorithm.Algorithm or an instance of a subclass of optimagic.algorithm.Algorithm.

algo_options

A dictionary of options for the algorithm. The options depend on the algorithm used. See https://optimagic.readthedocs.io/en/latest/algorithms.html for a list of algorithms and their options.

Type:: dict

numdiff_options

Options for numerical differentiation.

Type:: dict or optimagic.differentiation.numdiff_options.NumdiffOptions

error_handling

Set what to do if an error (e.g. a NaN) occurs during the optimization. Default is “raise”, which will stop the optimization. Alternatively, this can be set to “continue”, which will employ a penalty function to guide the optimizer back to values that can be evaluated.

Type:: str

error_penalty

Dictionary with keys “slope” and “constant” that influences the magnitude of the penalty values. Both number should be positive.

Type:: dict

scaling: If None or False, the parameter space is not rescaled. If True, a heuristic is used to improve the conditioning of the optimization problem. To choose which heuristic is used and to customize the scaling, provide a dictionary or an instance of optimagic.parameters.scaling.ScalingOptions.

Example

In this example, we fit a Gaussian and a constant to some data:

>>> import numpy as np
>>> from sherpa.data import Data1D
>>> from sherpa.models import Const1D, Gauss1D
>>> from sherpa.stats import Chi2
>>> from sherpa.optmethods import Optimagic
>>> from sherpa.fit import Fit
>>> data = Data1D('data1', x=np.arange(10),
...              y=[34.5, 23.4, 22.3, 45.6, 56.7, 67.8, 58.9, 43.0, 30.1, 25.2],
...              staterror=5 * np.ones(10))
>>> const = Const1D(name='const')
>>> gauss = Gauss1D(name='gauss')
>>> gauss.pos = 5.0  # start not too far from the data
>>> model = const + gauss

When we create the optimizer, we always have to set the algorithm before we can use the optimizer in a fit. Optimagic has numerous optional dependencies, but only scipy is required, so for this example we will use one of the scipy algorithms.

>>> optimizer = Optimagic()
>>> optimizer.algorithm = 'scipy_bfgs'

To make the notation more concise, it is also possible to use a keyword argument when the optimizer is created:

>>> optimizer = Optimagic(algorithm='scipy_bfgs')

Next, we use the optimizer in a fit.

>>> fit = Fit(data=data, model=model, stat=Chi2(), method=optimizer)
>>> result = fit.fit()
>>> print(result)
datasets       = None
itermethodname = none
methodname     = optimagic
statname       = chi2
succeeded      = True
parnames       = ('const.c0', 'gauss.fwhm', 'gauss.pos', 'gauss.ampl')
parvals        = (26.067327420836456, 3.285600683850382, 5.042514578467134, 42.005725690386164)
statval        = 6.879954370635533
istatval       = 700.2311623262916
dstatval       = 693.351207955656
numpoints      = 10
dof            = 6
qval           = 0.33209186143330294
rstat          = 1.1466590617725887
message        = Optimization terminated successfully.
nfev           = None

The last element of the fit output is a dictionary which holds the output from optimagic in an optimagic.optimization.optimize_result.OptimizeResult object, which can provide further information about the optimization process:

>>> out = result.extra_output['optimagic result'].convergence_report['five_steps']
>>> print(out.keys())
dict_keys(['relative_criterion_change', 'relative_params_change', 'absolute_criterion_change', 'absolute_params_change'])

Attributes Summary

default_config

The default settings for the optimiser.

Methods Summary

fit(statfunc, pars, parmins, parmaxes[, ...])

Run the optimiser.

Attributes Documentation

default_config: The default settings for the optimiser.

Methods Documentation

fit(statfunc: Callable[[Sequence[float] | ndarray], tuple[float, ndarray]], pars: Sequence[float] | ndarray, parmins: Sequence[float] | ndarray, parmaxes: Sequence[float] | ndarray, statargs: Any | None = None, statkwargs: Any | None = None) → tuple[bool, ndarray, float, str, dict[str, Any]] [edit on github]

Run the optimiser.

Changed in version 4.18.0: The statargs and statkwargs arguments are now ignored.

Changed in version 4.16.0: The statkwargs argument now defaults to None rather than {}.

Parameters:

statfunc (function) – Given a list of parameter values as the first argument and, as the remaining positional arguments, statargs and statkwargs as keyword arguments, return the statistic value.
pars (sequence) – The start position of the model parameter values.
parmins (sequence) – The minimum allowed values for each model parameter. This must match the length of pars.
parmaxes (sequence) – The maximum allowed values for each model parameter. This must match the length of pars.
statargs (optional) – This is currently unused.
statkwargs (dict, optional) – This is currently unused.

Returns:

newpars – The tuple contains: boolean indicating whether the optimization succeeded or not, the best fit parameters as a NumPy array, the statistic value at the best-fit location, a string message indicating the status, and a dictionary containing information about the optimisation (this depends on the optimiser).

Return type:

tuple