# Fitting

Horace comes with a rich and powerful fitting syntax that is common to the methods used to fit functions or models of S(Q,w) to one or more datasets. For an introduction and overview of how to use the following fitting functions, please read Fitting data. For comprehensive help, please use the Matlab documentation for the various fitting functions that can be obtained by using the `doc` command, for example `doc d1d/multifit` (for fitting function like Gaussians to d1d objects) or `doc sqw/multifit_sqw` (fitting models for S(Q,w) to sqw objects). It is strongly recommended that you use `doc`, not `help` to explore how to use these methods, so that you can navigate between the numerous pages of documentation in the Matlab help window.

Several multifit variants are available for sqw and d1d,d2d,...d4d objects. The only substantive difference is the form of the fit functions they require: either they are functions of the numeric values of the plot coordinates, or they are function of wave vector in reciprocal lattice units and energy.

Horace comes with a rich and powerful fitting syntax that is common to the methods used to fit functions or models of S(Q,w) to one or more datasets. For an introduction and overview of how to use the following fitting functions, please read Fitting data. For comprehensive help, please use the Matlab documentation for the various fitting functions that can be obtained by using the `doc` command, for example `doc d1d/multifit` (for fitting function like Gaussians to d1d objects) or `doc sqw/multifit_sqw` (fitting models for S(Q,w) to sqw objects). It is strongly recommended that you use `doc`, not `help` to explore how to use these methods, so that you can navigate between the numerous pages of documentation in the Matlab help window.

Several multifit variants are available for sqw and d1d,d2d,...d4d objects. The only substantive difference is the form of the fit functions they require: either they are functions of the numeric values of the plot coordinates, or they are function of wave vector in reciprocal lattice units and energy.

## multifit

This is identical to `multifit`) The foreground and background functions both are functions of the plot axes x1,x2,...for as many x arrays as there are plot axes:

```y = my_function (x1,x2,... ,xn,pars)
```

or, more generally:

```y = my_function (x1,x2,... ,xn,pars,c1,c2,...)
```

where

• x1,x2,.xn Arrays of x coordinates along each of the n dimensions
• pars Parameters needed by the function
• c1,c2,... Any further constant arguments needed by the function. For example, they could be the filenames of lookup tables

## multifit_sqw

The foreground function(s) are functions of S(Q,w), and the background functions are functions of the plot axes x1,x2,...

The general form of a model for S(Q,w) is:

```weight = sqwfunc (qh,qk,ql,en,p)
```

or, more generally:

```weight = sqwfunc (qh,qk,ql,en,p,c1,c2,..)
```

where qh,qk,ql,en Arrays containing the coordinates of a set of points p Vector of parameters needed by the model e.g. [A,js,gam] as intensity, exchange, lifetime c1,c2,... Other constant parameters e.g. file name for look-up table weight Array containing calculated spectral weight

The form for the background model(s) is the same as is required by `multifit`.

## multifit_sqw_sqw

The foreground and background function(s) are all functions of S(Q,w). The form of these models is the same as is required by `multifit`.

## fit_sqw

```>> [wout, fitdata] = fit_sqw(win, sqwfunc, pin)
>> [wout, fitdata] = fit_sqw(win, sqwfunc, pin, pfree)
>> [wout, fitdata] = fit_sqw(win, sqwfunc, pin, pfree, pbind)
>> [wout, fitdata] = fit_sqw(win, ... , background_func, bp)
>> [wout, fitdata] = fit_sqw(win, ... , background_func, bp, bpfree)
>> [wout, fitdata] = fit_sqw(win, ... , background_func, bp, bpfree, bpbind)
>> [wout, fitdata] = fit_sqw(win, ... , keyword, value, ...)

```

Required inputs are:

• `win` - dnd object or array of dnd objects (all of same dimensionality)
• `sqwfunc` - handle of the function to calculate sqw. The function must have the form

`weight = sqwfunc (qh,qk,ql,en,p,c1,c2,...)`,where qh, qk, ql, and en are arrays containing the coordinates of a set of points in reciprocal space (note difference in form to that used in `fit` - see below). p is a vector of parameters needed by dispersion function (e.g. [A,js,gam] as amplitude, exchange, lifetime). c1, c2, ... are additional, non-fittable, parameters required by the function (e.g. lookup tables for magnetic form factor, etc). weight is an array containing calculated intensity.

• `pin` gives the initial function parameter values. It either takes the form of a vector [pin(1), pin(2)...], or a cell array, where the first element is a vector of fittable parameters.
• `pfree` indicates which are the free parameters in the fit (e.g. [1,0,1,0,0] indicates first and third are free). The default (if `pfree` is not specified) is that all are free.
• `pbind` indicates which parameters are bound, i.e. parameters that are a fixed ratio to one another. This argument is specified as a cell array as in the following examples:
• `pbind={1,3}` - parameter 1 is bound to parameter 3.
• `pbind={{1,3},{4,3},{5,6}}` - parameter 1 bound to 3, 4 bound to 3, and 5 bound to 6. In this case, parmaeters 1,3,4,5,6 must all be free in `pfree`.
• To explicity give the ratio, ignoring that determined from `pin`:
• `pbind=(1,3,0,7.4)` - parameter 1 is bound to parameter 3, ratio 7.4 (the extra '0' is required)
• `pbind={{1,3,0,7.4},{4,3,0,0.023},{5,6}}`. Multiple bindings.
• `background_func` is a handle to a function that specifies the background. This argument is optional - you can include the background in your `sqw_func` if you wish. However if you think you might want to use `multifit` later it is probably worth keeping the background function and the spectral function separate.
• `bpin` is a vector or cell array specifying the inputs to the background function. Defined the same as for the global input parameters `pin`.
• `bpfree` is defined the same as `pfree`, but refers to the background parameters.
• `bpbind` defines the bindings for the background. Examples are as follows:
• `bpbind={1,4}` - background parameter 4 is bound to background parameter 1 in the ratio set by `bpin`;
• `bpbind={5,11,0}` - background parameter 5 is bound to parameter 11 of the global function, in the ratio determined by `bpin` and `pin`;
• `bpbind={1,4,1}` - background parameter 1 is bound to background parameter 4, in the ratio determined by `bpin`;
• `bpbind={5,11,0,0.013}` - background parameter 5 is bound to parameter 11 of the global function, in the ratio 0.013;
• `bpbind={1,4,1,14.14}` - background parameter 1 is bound to background parameter 4, in the ratio 14.14;
• `bpbind={{1,3},{2,4,0,1.2},{5,11,1}}` - multiple bindings of the background.

Optional keywords are :

• `'list'` - a numeric code to control output to Matlab command window to monitor status of fit

=0 for no printing to command window; =1 prints iteration summary to command window; =2 additionally prints parameter values at each iteration

• `'fit'` - array of fit control parameters.

fcp(1) is the relative step length for calculation of partial derivatives; fcp(2) is the maximum number of iterations; fcp(3) is the stopping criterion: relative change in chi-squared (i.e. stops if chisqr_new-chisqr_old < fcp(3)*chisqr_old).

• `'keep'` - ranges of data to retain for fitting. A range is specified by a pair of numbers which define the lower and upper bounds, i.e. [xlo,xhi]. Several ranges can be given by making an (m x 2) array such as [x1_lo, x1_hi; x2_lo, x2_hi; ...].
• `'remove'` - ranges to remove from fitting. Follows the same format as 'keep'.
• `'mask'` - array of ones and zeros, with the same number of elements as the data array, that indicates which of the data points are to be retained for fitting
• `'select'` - calculates the returned function values, yout, only at the pointsthat were selected for fitting by 'keep' and 'remove'; all other points are set to NaN. This is useful for plotting the output, as only those points that contributed to the fit will be plotted.
• `'all'` - requests that the calculated function be returned over the whole of the domain of the input dataset. If not given, then the function will be returned only at those points of the dataset that contain data.

The outputs are:

• `wout` - n-D dataset object containing the evaluation of the function for the fitted parameter values.
• `fitdata` - the result of fit for each dataset. It is a structure array with fields:
• fitdata.p - parameter values
• fitdata.sig - estimated errors (=0 for fixed parameters)
• fitdata.bp - background parameter values
• fitdata.bsig - errors for the background parameters
• fitdata.chisq - reduced Chi^2 of fit (i.e. divided by (no. of data points) - (no. free parameters))
• fitdata.pnames - parameter names (if the sqw function is an mfit function; otherwise named 'p1','p2',...).
• fitdata.bpnames - background parameter names.

## fit_func

```>> [wout, fitdata] = fit_func(win, func, pin)
>> [wout, fitdata] = fit_func(win, func, pin,....)
```

The input and output arguments are the same as those used for `fit_sqw`. The only exception is the functional form of the fitting function `func`. This has the form:

• `func` - handle of the function to calculate the intensity. The function must have the form

`y = func (x1,x2,...,p,c1,c2,...)`,where x1, x2,... are arrays containing the coordinates of the points in the dataset. This means that for a d2d then only 2 arrays need to be supplied, whereas for a d4d 4 are required, and so on. p is a vector of parameters needed by dispersion function (e.g. [A,js,gam] as amplitude, exchange, lifetime). c1, c2, ... are additional, non-fittable, parameters required by the function (e.g. lookup tables for magnetic form factor, etc). weight is an array containing calculated intensity.