## GwyNLFitPreset

GwyNLFitPreset — NL fitter preset functions

## Synopsis

    #include <libgwyddion/gwyddion.h>

                        GwyNLFitPresetBuiltin;
                        GwyNLFitPreset;
                        GwyNLFitPresetClass;
    gdouble             gwy_nlfit_preset_get_value          (GwyNLFitPreset *preset,
                                                             gdouble x,
                                                             const gdouble *params,
                                                             gboolean *fres);
    const gchar*        gwy_nlfit_preset_get_formula        (GwyNLFitPreset *preset);
    gint                gwy_nlfit_preset_get_nparams        (GwyNLFitPreset *preset);
    const gchar*        gwy_nlfit_preset_get_param_name     (GwyNLFitPreset *preset,
                                                             gint param);
    GwySIUnit*          gwy_nlfit_preset_get_param_units    (GwyNLFitPreset *preset,
                                                             gint param,
                                                             GwySIUnit *siunit_x,
                                                             GwySIUnit *siunit_y);
    void                gwy_nlfit_preset_guess              (GwyNLFitPreset *preset,
                                                             gint n_dat,
                                                             const gdouble *x,
                                                             const gdouble *y,
                                                             gdouble *params,
                                                             gboolean *fres);
    GwyNLFitter*        gwy_nlfit_preset_fit                (GwyNLFitPreset *preset,
                                                             GwyNLFitter *fitter,
                                                             gint n_dat,
                                                             const gdouble *x,
                                                             const gdouble *y,
                                                             gdouble *params,
                                                             gdouble *err,
                                                             const gboolean *fixed_param);
    GwyInventory*       gwy_nlfit_presets                   (void);

## Object Hierarchy

      GObject
       +----GwyResource
             +----GwyNLFitPreset
                   +----GwyFDCurvePreset

## Description

Non-linear fitter presets are predefined fitting functions, with guessing, weighting, etc. to ease fitting of common functions. Most of those currently implemented are related to one-dimensional statistical characteristics of randomly rough surfaces, however, several general-purpose fitting functions are also available.

The presets are identified by name and can be obtained from the corresponding GwyInventory, see `gwy_nlfit_presets()`. All their properties can be queried with methods such as `gwy_nlfit_preset_get_nparams()` or `gwy_nlfit_preset_get_formula()`. A generic method to derive units of fitting parameters from units of fitted data is also available: `gwy_nlfit_preset_get_param_units()`.

As of version 2.7 the defined functions include:

`"Gaussian"`
`"Gaussian (PSDF)"`
`"Gaussian (ACF)"`
`"Gaussian (HHCF)"`
`"Gaussian (RPSDF)"`
`"Exponential"`
`"Exponential (PSDF)"`
`"Exponential (ACF)"`
`"Exponential (HHCF)"`
`"Exponential (RPSDF)"`
`"Polynomial (order 0)"`
`"Polynomial (order 1)"`
`"Polynomial (order 2)"`
`"Polynomial (order 3)"`
`"Square wave"`
`"Power"`
`"Lorentzian"`
`"Sinc"`

The result of the fitting is stored in a normal GwyNLFitter, therefore the typical use is:

    GwyNLFitPreset *preset;
    GwyNLFitter *fitter;
    gdouble *params, *errors;

    preset = gwy_inventory_get_item(gwy_nlfit_presets(), "Gaussian");
    params = g_new(gdouble, gwy_nlfit_preset_get_nparams(preset));
    errors = g_new(gdouble, gwy_nlfit_preset_get_nparams(preset));
    /* Use a priori parameter value information, or: */
    gwy_nlfit_preset_guess(preset, ndata, xdata, ydata, params, &ok);
    fitter = gwy_nlfit_preset_fit(preset, NULL,
                                  ndata, xdata, ydata, params,
                                  params, errors, NULL);

    /* Examine fitting status, parameters and errors... */

    g_free(params);
    g_free(errors);
    gwy_math_nlfit_free(fitter);

## Details

### GwyNLFitPresetBuiltin

    typedef struct _GwyNLFitPresetBuiltin GwyNLFitPresetBuiltin;

### GwyNLFitPreset

    typedef struct _GwyNLFitPreset GwyNLFitPreset;

### GwyNLFitPresetClass

    typedef struct {
        GwyResourceClass parent_class;

        void (*reserved1)(void);
        void (*reserved2)(void);
    } GwyNLFitPresetClass;

### gwy_nlfit_preset_get_value ()

    gdouble             gwy_nlfit_preset_get_value          (GwyNLFitPreset *preset,
                                                             gdouble x,
                                                             const gdouble *params,
                                                             gboolean *fres);

Calculates preset function value in a single point with given parameters.

`preset` : | A NL fitter function preset.
`x` : | The point to compute value at.
`params` : | Preset parameter values.
`fres` : | Set to `TRUE` if succeeds, `FALSE` on failure.
Returns : | The function value.

### gwy_nlfit_preset_get_formula ()

    const gchar*        gwy_nlfit_preset_get_formula        (GwyNLFitPreset *preset);

Gets function formula of `preset` (with Pango markup).

`preset` : | A NL fitter function preset.
Returns : | The preset function formula.

### gwy_nlfit_preset_get_nparams ()

    gint                gwy_nlfit_preset_get_nparams        (GwyNLFitPreset *preset);

Return the number of parameters of `preset`.

`preset` : | A NL fitter function preset.
Returns : | The number of function parameters.

### gwy_nlfit_preset_get_param_name ()

    const gchar*        gwy_nlfit_preset_get_param_name     (GwyNLFitPreset *preset,
                                                             gint param);

Gets the name of a fitting parameter of a fitter preset.

The name may contain Pango markup.

`preset` : | A NL fitter function preset.
`param` : | A parameter number.
Returns : | The name of parameter `param`.

### gwy_nlfit_preset_get_param_units ()

    GwySIUnit*          gwy_nlfit_preset_get_param_units    (GwyNLFitPreset *preset,
                                                             gint param,
                                                             GwySIUnit *siunit_x,
                                                             GwySIUnit *siunit_y);

Derives the SI unit of a fitting parameter from the units of abscissa and ordinate.

`preset` : | A NL fitter function preset.
`param` : | A parameter number.
`siunit_x` : | SI unit of abscissa.
`siunit_y` : | SI unit of ordinate.
Returns : | A newly created GwySIUnit with the units of the parameter `param`. If the units of `param` are not representable as GwySIUnit, the result is unitless (i.e. it will be presented as a mere number).

Since 2.5

### gwy_nlfit_preset_guess ()

    void                gwy_nlfit_preset_guess              (GwyNLFitPreset *preset,
                                                             gint n_dat,
                                                             const gdouble *x,
                                                             const gdouble *y,
                                                             gdouble *params,
                                                             gboolean *fres);

Performs initial parameter estimate for a NL fitter.

The initial estimate method depends on the function used. There is no absolute guarantee of quality, however if the data points approximately match the fitted function the fit will typically converge from the returned estimate.

`preset` : | A NL fitter function preset.
`n_dat` : | The number of data points (number of items in `x` and `y`).
`x` : | Abscissa points.
`y` : | Ordinate points.
`params` : | The array to fill with estimated parameter values. It has to be at least `gwy_nlfit_preset_get_nparams()` long.
`fres` : | Set to `TRUE` if succeeds, `FALSE` on failure.

### gwy_nlfit_preset_fit ()

    GwyNLFitter*        gwy_nlfit_preset_fit                (GwyNLFitPreset *preset,
                                                             GwyNLFitter *fitter,
                                                             gint n_dat,
                                                             const gdouble *x,
                                                             const gdouble *y,
                                                             gdouble *params,
                                                             gdouble *err,
                                                             const gboolean *fixed_param);

Performs a nonlinear fit with a preset.

See `gwy_math_nlfit_fit_full()` for details.

`preset` : | A NL fitter function preset.
`fitter` : | A Marquardt-Levenberg nonlinear fitter already initialized for `preset`'s function, or `NULL`.
`n_dat` : | The number of data points (number of items in `x` and `y`).
`x` : | Abscissa points.
`y` : | Ordinate points.
`params` : | Initial parameter estimate (the number of parameters depends on the fitted preset and it can be obtained with `gwy_nlfit_preset_get_nparams()`).
`err` : | Array to store parameter errros to, may be `NULL`.
`fixed_param` : | Which parameters should be treated as fixed (set corresponding element to `TRUE` for them). May be `NULL` if all parameters are variable.
Returns : | Either `fitter` itself, or a newly created fitter if it was `NULL`.

### gwy_nlfit_presets ()

    GwyInventory*       gwy_nlfit_presets                   (void);

Gets inventory with all the NLFit presets.

Returns : | NLFit preset inventory.

## See Also

GwyNLFitter