GwyNLFitPreset: Gwyddion Library Reference Manual

## GwyNLFitPreset GwyNLFitPreset — NL fitter preset functions |

## Functions

GwyInventory * | gwy_nlfit_presets ()
gdouble | gwy_nlfit_preset_get_value ()
const gchar * | gwy_nlfit_preset_get_formula ()
gint | gwy_nlfit_preset_get_n_params ()
const gchar * | gwy_nlfit_preset_get_param_name ()
GwyUnit * | gwy_nlfit_preset_get_param_units ()
gint | gwy_nlfit_preset_get_param_power_x ()
gint | gwy_nlfit_preset_get_param_power_y ()
void | gwy_nlfit_preset_guess ()
GwyNLFitter * | gwy_nlfit_preset_create_fitter ()
GwyNLFitter * | gwy_nlfit_preset_fit ()

## Types and Values

| GwyNLFitPresetBuiltin
struct | GwyNLFitPreset
struct | GwyNLFitPresetClass

## Object Hierarchy

        GObject
        ╰── GwyResource
            ╰── GwyNLFitPreset
                ╰── GwyFDCurvePreset

## Includes

    #include <libgwyddion/gwyddion.h>

## 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_n_params()` 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()`.

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"`
`"Parabolic step"`
`"Two Gaussians (PSDF)"`
`"Smooth bent step"`
`"Smooth slanted step"`
`"K-correlated (PSDF)"`
`"Boltzmann bent step"`

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    GwyNLFitPreset *preset;
    GwyNLFitter *fitter;
    gdouble *params, *errors;

    preset = gwy_inventory_get_item(gwy_nlfit_presets(), "Gaussian");
    params = g_new(gdouble, gwy_nlfit_preset_get_n_params(preset));
    errors = g_new(gdouble, gwy_nlfit_preset_get_n_params(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_nl_fitter_free(fitter);

## Functions

### gwy_nlfit_presets()

    GwyInventory *
    gwy_nlfit_presets (void);

Gets inventory with all the NLFit presets.

#### Returns

NLFit preset inventory.

[transfer none]

### 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.

#### Parameters

x | The point to compute value at. |
preset | A NL fitter function preset. |
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).

#### Parameters

preset | A NL fitter function preset. |

#### Returns

The preset function formula.

### gwy_nlfit_preset_get_n_params()

    gint
    gwy_nlfit_preset_get_n_params (GwyNLFitPreset *preset);

Return the number of parameters of `preset` .

#### Parameters

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 i);

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

The name may contain Pango markup.

#### Parameters

preset | A NL fitter function preset. |
i | Parameter index. |

#### Returns

The name of `i` -th parameter.

### gwy_nlfit_preset_get_param_units()

    GwyUnit *
    gwy_nlfit_preset_get_param_units (GwyNLFitPreset *preset,
                                      gint i,
                                      GwyUnit *unit_x,
                                      GwyUnit *unit_y);

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

#### Parameters

preset | A NL fitter function preset. |
i | Parameter index. |
unit_x | SI unit of abscissa. |
unit_y | SI unit of ordinate. |

#### Returns

A newly created GwyUnit with the units of the `i` -th parameter. If the units are not representable as GwyUnit, the result is unitless (i.e. it will be presented as a mere number).

### gwy_nlfit_preset_get_param_power_x()

    gint
    gwy_nlfit_preset_get_param_power_x (GwyNLFitPreset *preset,
                                        gint i);

Gets the power of abscissa units in a fitting parameter.

Usually it is easier to let `gwy_nlfit_preset_get_param_units()` derive the parameter units.

#### Parameters

preset | A NL fitter function preset. |
i | Parameter index. |

#### Returns

The power of abscissa in the parameter.

### gwy_nlfit_preset_get_param_power_y()

    gint
    gwy_nlfit_preset_get_param_power_y (GwyNLFitPreset *preset,
                                        gint i);

Gets the power of ordinate units in a fitting parameter.

Usually it is easier to let `gwy_nlfit_preset_get_param_units()` derive the parameter units.

#### Parameters

preset | A NL fitter function preset. |
i | Parameter index. |

#### Returns

The power of ordinate in the parameter.

### 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.

The parameters are filled also on failure, though just with some neutral values that should not give raise to NaNs and infinities.

#### Parameters

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_n_params()` long. |
fres | Set to `TRUE` if succeeds, `FALSE` on failure. |

### gwy_nlfit_preset_create_fitter()

    GwyNLFitter *
    gwy_nlfit_preset_create_fitter (GwyNLFitPreset *preset);

Creates a non-linear least-squares fitter for a preset function.

The created fitter will be of the function data type, as created with `gwy_nl_fitter_new()`.

If you do not need to modify the fitter settings you can use `gwy_nlfit_preset_fit()` directly with `NULL` fitter.

#### Parameters

preset | A NL fitter function preset. |

#### Returns

A newly created fitter for `preset` .

[transfer none]

### 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_nl_fitter_fit_full()` for details.

#### Parameters

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_n_params()`). |
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`.

## Types and Values

### GwyNLFitPresetBuiltin

    typedef struct _GwyNLFitPresetBuiltin GwyNLFitPresetBuiltin;

### struct GwyNLFitPreset

    struct GwyNLFitPreset;

### struct GwyNLFitPresetClass

    struct GwyNLFitPresetClass {
        GwyResourceClass parent_class;
    };

## See Also

GwyNLFitter