Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

GwyNLFitPreset (HEAD)

GwyNLFitPreset — NL fitter preset functions

Functions

gdouble gwy_nlfit_preset_get_value ()
const gchar * gwy_nlfit_preset_get_formula ()
gint gwy_nlfit_preset_get_nparams ()
const gchar * gwy_nlfit_preset_get_param_name ()
GwySIUnit * gwy_nlfit_preset_get_param_units ()
void gwy_nlfit_preset_guess ()
GwyNLFitter * gwy_nlfit_preset_create_fitter ()
GwyNLFitter * gwy_nlfit_preset_fit ()
GwyInventory * gwy_nlfit_presets ()

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_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 following presets are available since version 2.40:

"Parabolic step"
"Two Gaussians (PSDF)"

The following presets are available since version 2.41:

"Smooth bent step"
"Smooth slanted step"

The following presets are available since version 2.48:

"K-correlated (PSDF)"

The following presets are available since version 2.49:

"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
17
18
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);

Functions

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_nparams ()

gint
gwy_nlfit_preset_get_nparams (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 param);

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

The name may contain Pango markup.

Parameters

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.

Parameters

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.

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_nparams() 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_math_nlfit_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 .

Since: 2.47

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.

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

Types and Values

GwyNLFitPresetBuiltin

typedef struct _GwyNLFitPresetBuiltin GwyNLFitPresetBuiltin;

struct GwyNLFitPreset

struct GwyNLFitPreset;

struct GwyNLFitPresetClass

struct GwyNLFitPresetClass {
    GwyResourceClass parent_class;
};

See Also

GwyNLFitter

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS