GwyNLFitter: Gwyddion Library Reference Manual

## GwyNLFitter GwyNLFitter — Marquardt-Levenberg nonlinear least square fitter |

## Functions

gdouble | (*GwyNLFitFunc) ()
void | (*GwyNLFitDerFunc) ()
gdouble | (*GwyNLFitIdxFunc) ()
void | (*GwyNLFitIdxDiffFunc) ()
GwyNLFitter * | gwy_nl_fitter_new ()
GwyNLFitter * | gwy_nl_fitter_new_idx ()
void | gwy_nl_fitter_free ()
GwyNLFitter * | gwy_nl_fitter_copy ()
gdouble | gwy_nl_fitter_fit ()
gdouble | gwy_nl_fitter_fit_full ()
gdouble | gwy_nl_fitter_fit_idx ()
gdouble | gwy_nl_fitter_fit_idx_full ()
gint | gwy_nl_fitter_get_max_iterations ()
void | gwy_nl_fitter_set_max_iterations ()
gboolean | gwy_nl_fitter_succeeded ()
gdouble | gwy_nl_fitter_get_dispersion ()
gdouble | gwy_nl_fitter_get_correlations ()
gboolean | gwy_nl_fitter_get_eval ()
const gdouble * | gwy_nl_fitter_get_covar ()
gint | gwy_nl_fitter_get_n_param ()
gdouble | gwy_nl_fitter_get_sigma ()
void | gwy_nl_fitter_set_callbacks ()
void | gwy_nl_fitter_diff ()
void | gwy_nl_fitter_diff_idx ()
gint | gwy_nl_fitter_map_free_params ()

## Types and Values

enum | GwyNLFitParamFlags
struct | GwyNLFitter

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

A new Marquardt-Levenberg nonlinear least square fitter can be created with `gwy_nl_fitter_new()`, specifying the function to fit (as GwyNLFitFunc) and its derivative (as GwyNLFitDerFunc). For functions for whose analytic derivative is not available or very impractical, `gwy_nl_fitter_derive()` (computing the derivative numerically) can be used instead.

A fitter can be then repeatedly used on different data either in `gwy_nl_fitter_fit()`, or `gwy_nl_fitter_fit_full()` when there are some fixed or linked parameters. Arbitrary additional (non-fitting) parameters can be passed to the fited function in `user_data` .

After a successful fit additional fit information can be obtained with `gwy_nl_fitter_get_dispersion()`, `gwy_nl_fitter_get_correlations()`, `gwy_nl_fitter_get_sigma()`. Note these functions may be used only after a successful fit. When a fitter is no longer needed, it should be freed with `gwy_nl_fitter_free()`.

Several common functions are also available as fitting presets that can be fitted with `gwy_nlfit_preset_fit()`. See GwyNLFitPreset for details.

## Functions

### GwyNLFitFunc()

    gdouble
    (*GwyNLFitFunc) (gdouble x,
                     const gdouble *param,
                     gpointer user_data,
                     gboolean *success);

Fitting function type for real-valued independent variables.

#### Parameters

x | The value to compute the function at. |
param | Parameters. |
user_data | User data as passed to `gwy_nl_fitter_fit()`. |
success | Set to `TRUE` if succeeds, `FALSE` on failure. |

#### Returns

The function value at `x` .

### GwyNLFitDerFunc()

    void
    (*GwyNLFitDerFunc) (gdouble x,
                        const gdouble *param,
                        const gboolean *fixed_param,
                        GwyNLFitFunc func,
                        gpointer user_data,
                        gdouble *der,
                        gboolean *success);

Fitting function partial derivative type for real-valued independent variables.

#### Parameters

x | x-data as passed to `gwy_nl_fitter_fit()`. |
param | Parameters. |
fixed_param | Which parameters should be treated as fixed (corresponding entries are set to `TRUE`). |
func | The fitted function. |
user_data | User data as passed to `gwy_nl_fitter_fit()`. |
der | Array where the `nparam` partial derivatives by each parameter are to be stored. Derivatives by fixed parameters are ignored so the function may set corresponding elements or not, whichever is more convenient. |
success | Set to `TRUE` if succeeds, `FALSE` on failure. |

### GwyNLFitIdxFunc()

    gdouble
    (*GwyNLFitIdxFunc) (guint i,
                        const gdouble *param,
                        gpointer user_data,
                        gboolean *success);

Fitting function type for opaque indexed data.

Note that unlike GwyNLFitFunc which returns just the function value this function must return the difference between the function value and fitted data value (that is function minus data point). When opaque data are fitted the fitter does not know what the data values are.

The function must take care of weighting. The difference should be multiplied by the inverse of the (unsquared) estimated error of the `i` -th data point. Not multiplying by anything correspond to using the default unit weights.

#### Parameters

i | Data index from the set {0, 1, 2, ..., ndata-1}. |
param | Parameters. |
user_data | User data as passed to `gwy_nl_fitter_fit()`. |
success | Set to `TRUE` if succeeds, `FALSE` on failure. |

#### Returns

Difference between the function value and data in the `i` -th data point.

### GwyNLFitIdxDiffFunc()

    void
    (*GwyNLFitIdxDiffFunc) (guint i,
                            const gdouble *param,
                            const gboolean *fixed_param,
                            GwyNLFitIdxFunc func,
                            gpointer user_data,
                            gdouble *der,
                            gboolean *success);

Fitting function partial derivatives type for opaque indexed data.

The function must take care of weighting. The derivatives should be multiplied by the inverse of the (unsquared) estimated error of the `i` -th data point. Not multiplying by anything correspond to using the default unit weights.

#### Parameters

i | Data index from the set {0, 1, 2, ..., ndata-1}. |
param | Parameters. |
fixed_param | Which parameters should be treated as fixed (corresponding entries are set to `TRUE`). It may be `NULL` is no parameters are fixed. The function must set derivatives by fixed parameters to zero. |
func | The fitted function. |
user_data | User data as passed to `gwy_nl_fitter_fit()`. |
der | Array where the `nparam` partial derivatives by each parameter are to be stored. Derivatives by fixed parameters are ignored so the function may set corresponding elements or not, whichever is more convenient. |
success | Set to `TRUE` if succeeds, `FALSE` on failure. |

### gwy_nl_fitter_new()

    GwyNLFitter *
    gwy_nl_fitter_new (GwyNLFitFunc func,
                       GwyNLFitDerFunc diff);

Creates a new Marquardt-Levenberg nonlinear fitter for function with a real-valued independent variable.

See `gwy_nl_fitter_new_idx()` for more complex scenarios.

You can use `gwy_nl_fitter_diff()` computing the derivative numerically, when you do not know the derivatives explicitely. Passing `NULL` as `diff` has the same effect, i.e. the fitter will automatically use numerical differentiation.

#### Parameters

func | The fitted function. | [scope call]
diff | The derivative of fitted function. | [scope call][nullable]

#### Returns

The newly created fitter.

### gwy_nl_fitter_new_idx()

    GwyNLFitter *
    gwy_nl_fitter_new_idx (GwyNLFitIdxFunc func,
                           GwyNLFitIdxDiffFunc diff);

Creates a new Marquardt-Levenberg nonlinear fitter for opaque indexed data.

As only the data index is passed to the functions, using this interface permits fitting more complex functions. The abscissa can be arbitrary, for instance a vector, as it is not seen by the fitter. Similarly, vector-valued functions can be emulated by mapping tuples of indices to the vector components.

You can pass `NULL` as `diff` to use automatically numerical differentiation when you do not know the derivatives explicitely. Note that this means you cannot use weighting. If you want weighting you need to pass your own `diff` function that performs the weighting (it can utilise the `gwy_nl_fitter_diff_idx()` helper).

#### Parameters

func | The fitted function. | [scope call]
diff | The derivative of fitted function. | [scope call][nullable]

#### Returns

The newly created fitter.

### gwy_nl_fitter_free()

    void
    gwy_nl_fitter_free (GwyNLFitter *nlfit);

Completely frees a Marquardt-Levenberg nonlinear fitter.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

### gwy_nl_fitter_copy()

    GwyNLFitter *
    gwy_nl_fitter_copy (GwyNLFitter *nlfit);

Creates a copy of a nonlinear least squares fitter.

This function is mostly usefil for language bindings.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

#### Returns

The newly created fitter.

### gwy_nl_fitter_fit()

    gdouble
    gwy_nl_fitter_fit (GwyNLFitter *nlfit,
                       gint ndata,
                       const gdouble *x,
                       const gdouble *y,
                       gint nparam,
                       gdouble *param,
                       gpointer user_data);

Performs a nonlinear fit of simple function on data.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
ndata | The number of data points in `x` , `y` . |
x | Array of independent variable values. |
y | Array of dependent variable values. |
nparam | The nuber of parameters. |
param | Array of parameters (of size `nparam` ). Note the parameters must be initialized to reasonably near values. |
user_data | Pointer that will be passed to the function and derivative as `user_data` . |

#### Returns

The final residual sum, a negative number in the case of failure.

### gwy_nl_fitter_fit_full()

    gdouble
    gwy_nl_fitter_fit_full (GwyNLFitter *nlfit,
                            gint ndata,
                            const gdouble *x,
                            const gdouble *y,
                            const gdouble *weight,
                            gint nparam,
                            gdouble *param,
                            const gboolean *fixed_param,
                            const gint *link_map,
                            gpointer user_data);

Performs a nonlinear fit of simple function on data, allowing some fixed parameters.

Initial values of linked (dependent) parameters are overwritten by master values, their `fixed_param` property is ignored and master's property controls whether all are fixed or all variable.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
ndata | The number of data points in `x` , `y` , `weight` . |
x | Array of independent variable values. |
y | Array of dependent variable values. |
weight | Array of weights associated to each data point (usually equal to inverse squares errors). Can be `NULL`, unit weight is then used for all data. |
nparam | The nuber of parameters. |
param | Array of parameters (of size `nparam` ). Note the parameters must be initialized to reasonably near values. |
fixed_param | Which parameters should be treated as fixed (set corresponding element to `TRUE` for them). May be `NULL` if all parameters are variable. |
link_map | Map of linked parameters. One of linked parameters is master, Values in this array are indices of corresponding master parameter for each parameter (for independent parameters set `link_map` [i] == i). May be `NULL` if all parameter are independent. |
user_data | Pointer that will be passed to the function and derivative |

#### Returns

The final residual sum, a negative number in the case of failure.

### gwy_nl_fitter_fit_idx()

    gdouble
    gwy_nl_fitter_fit_idx (GwyNLFitter *nlfit,
                           guint ndata,
                           guint nparam,
                           gdouble *param,
                           gpointer user_data);

Performs a nonlinear fit of function on opaque indexed data.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
ndata | The number of data points in `x` , `y` , `weight` . |
nparam | The nuber of parameters. |
param | Array of parameters (of size `nparam` ). Note the parameters must be initialized to reasonably near values. |
user_data | Pointer that will be passed to the function and derivative |

#### Returns

The final residual sum, a negative number in the case of failure.

### gwy_nl_fitter_fit_idx_full()

    gdouble
    gwy_nl_fitter_fit_idx_full (GwyNLFitter *nlfit,
                                guint ndata,
                                guint nparam,
                                gdouble *param,
                                const gboolean *fixed_param,
                                const gint *link_map,
                                gpointer user_data);

Performs a nonlinear fit of function on opaque indexed data, allowing some fixed parameters.

Initial values of linked (dependent) parameters are overwritten by master values, their `fixed_param` property is ignored and master's property controls whether all are fixed or all variable.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
ndata | The number of data points in `x` , `y` , `weight` . |
nparam | The nuber of parameters. |
param | Array of parameters (of size `nparam` ). Note the parameters must be initialized to reasonably near values. |
fixed_param | Which parameters should be treated as fixed (set corresponding element to `TRUE` for them). May be `NULL` if all parameters are variable. |
link_map | Map of linked parameters. One of linked parameters is master, Values in this array are indices of corresponding master parameter for each parameter (for independent parameters set `link_map` [i] == i). May be `NULL` if all parameter are independent. |
user_data | Pointer that will be passed to the function and derivative |

#### Returns

The final residual sum, a negative number in the case of failure.

### gwy_nl_fitter_get_max_iterations()

    gint
    gwy_nl_fitter_get_max_iterations (GwyNLFitter *nlfit);

Returns the maximum number of iterations of nonlinear fitter `nlfit` .

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

#### Returns

The maximum number of iterations.

### gwy_nl_fitter_set_max_iterations()

    void
    gwy_nl_fitter_set_max_iterations (GwyNLFitter *nlfit,
                                      gint maxiter);

Sets the maximum number of iterations for nonlinear fitter `nlfit` .

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
maxiter | The maximum number of iterations. |

### gwy_nl_fitter_succeeded()

    gboolean
    gwy_nl_fitter_succeeded (GwyNLFitter *nlfit);

Obtains the status of the last fitting.

Fitting failure can be (and usually should be) also determined by checking for negative return value of `gwy_nl_fitter_fit()` or `gwy_nl_fitter_fit_full()`. This function allows to test it later.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

#### Returns

`TRUE` if the last fitting suceeded, `FALSE` if it failed.

### gwy_nl_fitter_get_dispersion()

    gdouble
    gwy_nl_fitter_get_dispersion (GwyNLFitter *nlfit);

Returns the residual sum divided by the number of degrees of freedom.

This function can be used only after a successful fit.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

#### Returns

The dispersion.

### gwy_nl_fitter_get_correlations()

    gdouble
    gwy_nl_fitter_get_correlations (GwyNLFitter *nlfit,
                                    gint par1,
                                    gint par2);

Returns the correlation coefficient between `par1` -th and `par2` -th parameter.

This function can be used only after a successful fit.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
par1 | First parameter index. |
par2 | Second parameter index. |

#### Returns

The correlation coefficient.

### gwy_nl_fitter_get_eval()

    gboolean
    gwy_nl_fitter_get_eval (GwyNLFitter *nlfit);

Gets the state of a nonlinear fitter.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

#### Returns

`TRUE` if the last fit succeeded, `FALSE` if it failed.

### gwy_nl_fitter_get_covar()

    const gdouble *
    gwy_nl_fitter_get_covar (GwyNLFitter *nlfit);

Gets the covariance matrix of a nonlinear fitter.

The returned matrix may be only used between fits. Any fitting can free and reallocate it.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

#### Returns

The covariance matrix, as lower triangular matrix, owned by the fitter. The return value will be `NULL` if the last fit did not succeed.

### gwy_nl_fitter_get_n_param()

    gint
    gwy_nl_fitter_get_n_param (GwyNLFitter *nlfit);

Gets the number of parameters of a nonlinear fitter.

The number of parameters determines the size of covariance matrix obtained by `gwy_nl_fitter_get_covar()` and valid arguments for `gwy_nl_fitter_get_correlations()`.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |

#### Returns

The number of parameters for the last fit. If the last fit was not successful zero is returned.

### gwy_nl_fitter_get_sigma()

    gdouble
    gwy_nl_fitter_get_sigma (GwyNLFitter *nlfit,
                             gint par);

Returns the standard deviation of parameter number `par` .

This function makes sense only after a successful fit and for a free parameter.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
par | Parameter index. |

#### Returns

The SD of `par` -th parameter.

### gwy_nl_fitter_set_callbacks()

    void
    gwy_nl_fitter_set_callbacks (GwyNLFitter *nlfit,
                                 GwySetFractionFunc set_fraction,
                                 GwySetMessageFunc set_message);

Sets callbacks reporting a non-linear least squares fitter progress.

#### Parameters

nlfit | A Marquardt-Levenberg nonlinear fitter. |
set_fraction | Function that sets fraction to output (or `NULL`). | [scope call][nullable]
set_message | Function that sets message to output (or `NULL`). | [scope call][nullable]

### gwy_nl_fitter_diff()

    void
    gwy_nl_fitter_diff (gdouble x,
                        gint nparam,
                        const gdouble *param,
                        const gboolean *fixed_param,
                        GwyNLFitFunc func,
                        gpointer user_data,
                        gdouble *der,
                        gboolean *success);

Numerically computes the partial derivatives of a function.

#### Parameters

x | The value to compute the derivative at. |
nparam | The nuber of parameters. |
param | Array of parameters (of size `nparam` ). | [array length=nparam]
fixed_param | Which parameters should be treated as fixed (corresponding entries are set to `TRUE`). | [array length=nparam]
func | The fitted function. | [scope call]
user_data | User data to be passed to `func` . |
der | Array where the put the result to. |
success | Set to `TRUE` if succeeds, `FALSE` on failure. |

### gwy_nl_fitter_diff_idx()

    void
    gwy_nl_fitter_diff_idx (guint i,
                            gint nparam,
                            const gdouble *param,
                            const gboolean *fixed_param,
                            GwyNLFitIdxFunc func,
                            gpointer user_data,
                            gdouble *der,
                            gboolean *success);

Numerically computes the partial derivatives of an opaque function.

This function cannot be passed as derivative calculation function to `gwy_nl_fitter_new_idx()` because it is not of the GwyNLFitIdxDiffFunc type. Just pass `NULL` to `gwy_nl_fitter_new_idx()` if you want automatic numerical derivatives.

You can employ this function in your own GwyNLFitIdxDiffFunc function if you need to modify the derivatives somehow, for instance to apply weighting.

#### Parameters

i | Data index from the set {0, 1, 2, ..., ndata-1}. |
nparam | The nuber of parameters. |
param | Array of parameters (of size `nparam` ). | [array length=nparam]
fixed_param | Which parameters should be treated as fixed (corresponding entries are set to `TRUE`). | [array length=nparam]
func | The fitted function. | [scope call]
user_data | User data to be passed to `func` . |
der | Array where the put the result to. |
success | Set to `TRUE` if succeeds, `FALSE` on failure. |

### gwy_nl_fitter_map_free_params()

    gint
    gwy_nl_fitter_map_free_params (const gboolean *fixed_param,
                                   gint n,
                                   gint *id_map);

Creates a map from free parameter ids to all-parameter ids.

This is a helper function for reduction of full parameter vectors and covariance matrices to only free parameters.

The array `id_map` must at least as many elements as there are free parameters. However, it is usually better to just pass an array of size `n` because the number of free parameters is what this function calculates.

#### Parameters

fixed_param | Which parameters are fixed. |
n | Length of `fixed_param` array. |
id_map | Parameter id map to fill. |

#### Returns

The number of free parameters. This is the number of ids filled in `id_map` .

## Types and Values

### enum GwyNLFitParamFlags

Type of fitting parameter properties.

#### Members

GWY_NLFIT_PARAM_ANGLE | Parameter is an angle. It is defined in radians and unitless but you may wish to convert it from/to degrees in the user interface. It is consdered periodic and always reduced to the range [0, 2π). |
GWY_NLFIT_PARAM_ABSVAL | Parameter is a width or distance that is by definition positive. Only its absolute value matters and it is always made non-negative. |

### struct GwyNLFitter

    struct GwyNLFitter {
        GwyNLFitFunc fmarq;  /* fitting function */
        GwyNLFitDerFunc dmarq;  /* fitting function derivations */
        gint maxiter;  /* max number of iterations */
        gboolean eval;  /* success? */
        gdouble *covar; /* covariance matrix  */
        gdouble dispersion; /* dispersion */
        gdouble mfi;    /* fitting parameters --
                           fi, decrease, increase of lambda, minimum lambda */
        gdouble mdec;
        gdouble minc;
        gdouble mtol;
    };

Non-linear least-squares fitter.

The fields should be considered private.

Use `gwy_nl_fitter_get_eval()`, `gwy_nl_fitter_get_covar()` and `gwy_nl_fitter_get_dispersion()` and `gwy_nl_fitter_succeeded()` to examine the fitter state.

Use `gwy_nl_fitter_set_max_iterations()` to set the maximum iteration.

In rare occasions you might want modify `mdec` or `minc` . The rest is better left untouched.

#### Members

GwyNLFitFunc `fmarq`; | Evaluates the fitted function. |
GwyNLFitDerFunc `dmarq`; | Evaluates derivatives of the fitted function. |
gint `maxiter`; | Maximum number of iteration. |
gboolean `eval`; | `TRUE` if last evaluation succeeded. |
gdouble *`covar`; | Covariance matrix (set upon successful fit). |
gdouble `dispersion`; | Mean residual sum of squares per point, set to -1 on failure. |
gdouble `mfi`; | Lambda parameter is multiplied by it. Probably keep at 1. |
gdouble `mdec`; | Decrease of lambda parameter after an unsuccessful step. |
gdouble `minc`; | Increase of lambda parameter after a successful step. |
gdouble `mtol`; | If lambda parameter becomes zero it is set to this value. |

## See Also

GwyNLFitPreset