![]() |
![]() |
Gwyddion Library Reference Manual | ![]() |
|
---|---|---|---|---|
gdouble (*GwyNLFitFunc) (gdouble x, gint n_param, const gdouble *param, gpointer user_data, gboolean *fres); void (*GwyNLFitDerFunc) (gint i, const gdouble *x, gint n_param, gdouble *param, GwyNLFitFunc fmarq, gpointer user_data, gdouble *deriv, gboolean *dres); void (*GwyNLFitGuessFunc) (gdouble *x, gdouble *y, gint n_dat, gdouble *param, gpointer user_data, gboolean *fres); void (*GwyNLFitParamScaleFunc) (gdouble *param, gdouble xscale, gdouble yscale, gint dir); void (*GwyNLFitWeightFunc) (gdouble *x, gdouble *y, gint n_dat, gdouble *weight, gpointer user_data); GwyNLFitter; GwyNLFitPreset; GwyNLFitParam; GwyNLFitter* gwy_math_nlfit_new (GwyNLFitFunc ff, GwyNLFitDerFunc df); void gwy_math_nlfit_free (GwyNLFitter *nlfit); gdouble gwy_math_nlfit_fit (GwyNLFitter *nlfit, gint n_dat, const gdouble *x, const gdouble *y, const gdouble *weight, gint n_param, gdouble *param, gpointer user_data); gdouble gwy_math_nlfit_fit_with_fixed (GwyNLFitter *nlfit, gint n_dat, const gdouble *x, const gdouble *y, const gdouble *weight, gint n_param, gdouble *param, const gboolean *fixed_param, gpointer user_data); gint gwy_math_nlfit_get_max_iterations (GwyNLFitter *nlfit); void gwy_math_nlfit_set_max_iterations (GwyNLFitter *nlfit, gint maxiter); gdouble gwy_math_nlfit_get_dispersion (GwyNLFitter *nlfit); gdouble gwy_math_nlfit_get_correlations (GwyNLFitter *nlfit, gint par1, gint par2); gdouble gwy_math_nlfit_get_sigma (GwyNLFitter *nlfit, gint par); void gwy_math_nlfit_derive (gint i, const gdouble *x, gint n_param, gdouble *param, GwyNLFitFunc ff, gpointer user_data, gdouble *deriv, gboolean *dres); gint gwy_math_nlfit_get_npresets (void); GwyNLFitPreset* gwy_math_nlfit_get_preset (gint preset_id); GwyNLFitPreset* gwy_math_nlfit_get_preset_by_name (const gchar *name); gint gwy_math_nlfit_get_preset_id (const GwyNLFitPreset *preset); gdouble gwy_math_nlfit_get_preset_value (const GwyNLFitPreset *preset, gdouble *params, gdouble x); gchar* gwy_math_nlfit_get_preset_name (const GwyNLFitPreset *preset); gchar* gwy_math_nlfit_get_preset_formula (const GwyNLFitPreset *preset); gchar* gwy_math_nlfit_get_preset_param_name (const GwyNLFitPreset *preset, gint param); gdouble gwy_math_nlfit_get_preset_param_default (const GwyNLFitPreset *preset, gint param); gint gwy_math_nlfit_get_preset_nparams (const GwyNLFitPreset *preset); GwyNLFitter* gwy_math_nlfit_fit_preset (const GwyNLFitPreset *preset, gint n_dat, const gdouble *x, const gdouble *y, gint n_param, gdouble *param, gdouble *err, const gboolean *fixed_param, gpointer user_data);
A new Marquardt-Levenberg nonlinear least square fitter can be created with
gwy_math_nlfit_new()
,
specifying the function to fit (as
GwyNLFitFunc) and its derivation
(as GwyNLFitDerFunc).
For functions for whose analytic derivation is not available or very
impractical,
gwy_math_nlfit_derive()
(computing the derivation numerically) can be used instead.
A fitter can be then repeatedly used on different data either
in gwy_math_nlfit_fit()
,
or gwy_math_nlfit_fit_with_fixed()
when there are some fixed parameters. Arbitrary additional (non-fitting)
parameters can be passed to the fited function in
user_data
.
After a successfull fit additional fit information can be obtained
with gwy_math_nlfit_get_dispersion()
,
gwy_math_nlfit_get_correlations()
,
gwy_math_nlfit_get_sigma()
.
Note these functions may be used only after a successfull fit.
When a fitter is no longer needed, it should be freed with
gwy_math_nlfit_free()
.
Several common functions are also available as fitting presets that can be
fitted with
gwy_math_nlfit_fit_preset()
.
Each one can be identified by a unique name or a numeric id (the latter one
may however change between releases) the number of presets can be obtained
with gwy_math_nlfit_get_npresets()
.
Preset properties can be obtained with functions like
gwy_math_nlfit_get_preset_nparams()
or gwy_math_nlfit_get_preset_formula()
.
gdouble (*GwyNLFitFunc) (gdouble x, gint n_param, const gdouble *param, gpointer user_data, gboolean *fres);
Fitting function type.
x : |
The value to compute the function in. |
n_param : |
The number of parameters (size of param ).
|
param : |
Parameters. |
user_data : |
User data as passed to gwy_math_nlfit_fit() .
|
fres : |
Set to TRUE if succeeds, FALSE on failure.
|
Returns : | The value at x .
|
void (*GwyNLFitDerFunc) (gint i, const gdouble *x, gint n_param, gdouble *param, GwyNLFitFunc fmarq, gpointer user_data, gdouble *deriv, gboolean *dres);
Fitting function partial derivation type.
i : |
The index of the value in x to compute the derivation in.
|
x : |
x-data as passed to gwy_math_nlfit_fit() .
|
n_param : |
The number of parameters (size of param ).
|
param : |
Parameters. |
fmarq : |
The fitting function. |
user_data : |
User data as passed to gwy_math_nlfit_fit() .
|
deriv : |
Array where the n_param partial derivations by each parameter are
to be stored.
|
dres : |
Set to TRUE if succeeds, FALSE on failure.
|
void (*GwyNLFitGuessFunc) (gdouble *x, gdouble *y, gint n_dat, gdouble *param, gpointer user_data, gboolean *fres);
x : |
|
y : |
|
n_dat : |
|
param : |
|
user_data : |
|
fres : |
void (*GwyNLFitParamScaleFunc) (gdouble *param, gdouble xscale, gdouble yscale, gint dir);
param : |
|
xscale : |
|
yscale : |
|
dir : |
void (*GwyNLFitWeightFunc) (gdouble *x, gdouble *y, gint n_dat, gdouble *weight, gpointer user_data);
x : |
|
y : |
|
n_dat : |
|
weight : |
|
user_data : |
typedef struct { 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, snizeni, zvyseni lambda, minimalni lambda */ gdouble mdec; gdouble minc; gdouble mtol; } GwyNLFitter;
typedef struct { const gchar *function_name; const gchar *group_name; const gchar *function_formula; GwyNLFitFunc function; GwyNLFitDerFunc function_derivation; GwyNLFitGuessFunc function_guess; GwyNLFitParamScaleFunc parameter_scale; GwyNLFitWeightFunc set_default_weights; gint nparams; const GwyNLFitParam *param; gpointer _reserved1; } GwyNLFitPreset;
GwyNLFitter* gwy_math_nlfit_new (GwyNLFitFunc ff, GwyNLFitDerFunc df);
Creates a new Marquardt-Levenberg nonlinear fitter for function ff
.
ff : |
The fitted function. |
df : |
The derivation of fitted function. You can use gwy_math_nlfit_derive()
computing the derivation numerically, when you don't know the
derivation explicitely.
|
Returns : | The newly created fitter. |
Since 1.1.
void gwy_math_nlfit_free (GwyNLFitter *nlfit);
Completely frees a Marquardt-Levenberg nonlinear fitter.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
Since 1.1.
gdouble gwy_math_nlfit_fit (GwyNLFitter *nlfit, gint n_dat, const gdouble *x, const gdouble *y, const gdouble *weight, gint n_param, gdouble *param, gpointer user_data);
Performs a nonlinear fit of nlfit
function on (x
,y
) data.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
n_dat : |
The number of data points in x , y , w .
|
x : |
Array of independent variable values. |
y : |
Array of dependent variable values. |
weight : |
Array of weights associated to each data point. Since 1.2 it can
be NULL , weight of 1 is then used for all data.
|
n_param : |
The nuber of parameters. |
param : |
Array of parameters (of size n_param ). Note the parameters must
be initialized to reasonably near values.
|
user_data : |
Any pointer that will be passed to the function and derivation
as user_data .
|
Returns : | The final residual sum, a negative number in the case of failure. |
Since 1.1.
gdouble gwy_math_nlfit_fit_with_fixed (GwyNLFitter *nlfit, gint n_dat, const gdouble *x, const gdouble *y, const gdouble *weight, gint n_param, gdouble *param, const gboolean *fixed_param, gpointer user_data);
Performs a nonlinear fit of nlfit
function on (x
,y
) data, allowing
some fixed parameters.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
n_dat : |
The number of data points in x , y , w .
|
x : |
Array of independent variable values. |
y : |
Array of dependent variable values. |
weight : |
Array of weights associated to each data point. Can be NULL ,
weight of 1 is then used for all data.
|
n_param : |
The nuber of parameters. |
param : |
Array of parameters (of size n_param ). 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).
|
user_data : |
Any pointer that will be passed to the function and derivation |
Returns : | The final residual sum, a negative number in the case of failure. |
Since 1.2.
gint gwy_math_nlfit_get_max_iterations (GwyNLFitter *nlfit);
Returns the maximum number of iterations of nonlinear fitter nlfit
.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
Returns : | The maximum number of iterations. |
Since 1.1.
void gwy_math_nlfit_set_max_iterations (GwyNLFitter *nlfit, gint maxiter);
Sets the maximum number of iterations for nonlinear fitter nlfit
.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
maxiter : |
The maximum number of iterations. |
Since 1.1.
gdouble gwy_math_nlfit_get_dispersion (GwyNLFitter *nlfit);
Returns the residual sum divided by the number of degrees of freedom.
This function makes sense only after a successful fit.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
Returns : | The dispersion. |
Since 1.1.
gdouble gwy_math_nlfit_get_correlations (GwyNLFitter *nlfit, gint par1, gint par2);
Returns the correlation coefficient between par1
-th and par2
-th parameter.
This function makes sense only after a successful fit.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
par1 : |
First parameter index. |
par2 : |
Second parameter index. |
Returns : | The correlation coefficient. |
Since 1.1.
gdouble gwy_math_nlfit_get_sigma (GwyNLFitter *nlfit, gint par);
Returns the standard deviation of parameter number par
.
This function makes sense only after a successful fit.
nlfit : |
A Marquardt-Levenberg nonlinear fitter. |
par : |
Parameter index. |
Returns : | The SD of par -th parameter.
|
Since 1.1.
void gwy_math_nlfit_derive (gint i, const gdouble *x, gint n_param, gdouble *param, GwyNLFitFunc ff, gpointer user_data, gdouble *deriv, gboolean *dres);
Numerically computes the partial derivations of ff
i : |
Index in data_x where to compute the derivation.
|
x : |
x-data as passed to gwy_math_nlfit_fit() .
|
n_param : |
The nuber of parameters. |
param : |
Array of parameters (of size n_param ).
|
ff : |
The fitted function. |
user_data : |
User data as passed to gwy_math_nlfit_fit() .
|
deriv : |
Array where the put the result to. |
dres : |
Set to TRUE if succeeds, FALSE on failure.
|
Since 1.1.
gint gwy_math_nlfit_get_npresets (void);
Returns the number of available NL fitter presets.
Returns : | The number of presets. |
Since 1.2.
GwyNLFitPreset* gwy_math_nlfit_get_preset (gint preset_id);
Returns NL fitter preset number preset_id
.
Presets are numbered sequentially from 0 to gwy_math_nlfit_get_npresets()
-1.
The numbers are not guaranteed to be constants, use preset names as unique
identifiers.
preset_id : |
NL fitter preset number. |
Returns : | Preset number preset_id . Note the returned value must not be
modified or freed.
|
Since 1.2.
GwyNLFitPreset* gwy_math_nlfit_get_preset_by_name (const gchar *name);
Returns NL fitter preset whose name is name
.
name : |
NL fitter preset name. |
Returns : | Preset name , NULL if not found. Note the returned value must
not be modified or freed.
|
Since 1.2.
gint gwy_math_nlfit_get_preset_id (const GwyNLFitPreset *preset);
Returns the id of a NL fitter preset.
preset : |
A NL fitter function preset. |
Returns : | The preset number. |
Since 1.2.
gdouble gwy_math_nlfit_get_preset_value (const GwyNLFitPreset *preset, gdouble *params, gdouble x);
Return preset function value in point x
with parameters params
.
preset : |
A NL fitter function preset. |
params : |
Preset parameter values. |
x : |
The point to compute value at. |
Returns : | The function value. |
Since 1.2.
gchar* gwy_math_nlfit_get_preset_name (const GwyNLFitPreset *preset);
Return preset name (its unique identifier).
preset : |
A NL fitter function preset. |
Returns : | The preset name. |
Since 1.2.
gchar* gwy_math_nlfit_get_preset_formula (const GwyNLFitPreset *preset);
Returns function formula of preset
(with Pango markup).
preset : |
A NL fitter function preset. |
Returns : | The preset function formula. |
Since 1.2.
gchar* gwy_math_nlfit_get_preset_param_name (const GwyNLFitPreset *preset, gint param);
Returns the name of parameter number param
of preset preset
.
The name may contain Pango markup.
preset : |
A NL fitter function preset. |
param : |
A parameter number. |
Returns : | The name of parameter param .
|
Since 1.2.
gdouble gwy_math_nlfit_get_preset_param_default (const GwyNLFitPreset *preset, gint param);
Returns a suitable constant default parameter value.
It is usually better to do an educated guess of initial parameter value.
preset : |
A NL fitter function preset. |
param : |
A parameter number. |
Returns : | The default parameter value. |
Since 1.2.
gint gwy_math_nlfit_get_preset_nparams (const GwyNLFitPreset *preset);
Return the number of parameters of preset
.
preset : |
A NL fitter function preset. |
Returns : | The number of function parameters. |
Since 1.2.
GwyNLFitter* gwy_math_nlfit_fit_preset (const GwyNLFitPreset *preset, gint n_dat, const gdouble *x, const gdouble *y, gint n_param, gdouble *param, gdouble *err, const gboolean *fixed_param, gpointer user_data);
preset : |
|
n_dat : |
|
x : |
|
y : |
|
n_param : |
|
param : |
|
err : |
|
fixed_param : |
|
user_data : |
|
Returns : |
Since 1.2.