<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>lmfit: a self-contained C library for Levenberg-Marquardt least-squares minimization and curve fitting</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body>
<link rel="stylesheet" href="podstyle.css" type="text/css" />
<h1 id="NAME">NAME</h1>
<p>lmmin - Levenberg-Marquardt least-squares minimization</p>
<h1 id="SYNOPSIS">SYNOPSIS</h1>
<p><b>#include <lmmin.h</b>></p>
<p><b>void lmmin( const int</b> <i>n_par</i><b>, double *</b><i>par</i><b>, const int</b> <i>m_dat</i><b>, const<span style="white-space: nowrap;"> </span>void *</b><i>data</i><b>, void *</b><i>evaluate</i><b>( const<span style="white-space: nowrap;"> </span>double *</b><i>par</i><b>, const int </b><i>m_dat</i><b>, const<span style="white-space: nowrap;"> </span>void *</b><i>data</i><b>, double *</b><i>fvec</i><b>, int *</b><i>userbreak</i><b>), const<span style="white-space: nowrap;"> </span>lm_control_struct *</b><i>control</i><b>, lm_status_struct *</b><i>status</i><b> );</b></p>
<p><b>extern const lm_control_struct lm_control_double;</b></p>
<p><b>extern const lm_control_struct lm_control_float;</b></p>
<p><b>extern const char *lm_infmsg[];</b></p>
<p><b>extern const char *lm_shortmsg[];</b></p>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<p><b>lmmin()</b> determines a vector <i>par</i> that minimizes the sum of squared elements of a vector <i>fvec</i> that is computed by a user-supplied function <i>evaluate</i>(). On success, <i>par</i> represents a local minimum, not necessarily a global one; it may depend on its starting value.</p>
<p>For applications in curve fitting, the wrapper function <b>lmcurve(3)</b> offers a simplified API.</p>
<p>The Levenberg-Marquardt minimization starts with a steepest-descent exploration of the parameter space, and achieves rapid convergence by crossing over into the Newton-Gauss method.</p>
<p>Function arguments:</p>
<dl>
<dt id="n_par"><i>n_par</i></dt>
<dd>
<p>Number of free variables. Length of parameter vector <i>par</i>.</p>
</dd>
<dt id="par"><i>par</i></dt>
<dd>
<p>Parameter vector. On input, it must contain a reasonable guess. On output, it contains the solution found to minimize ||<i>fvec</i>||.</p>
</dd>
<dt id="m_dat"><i>m_dat</i></dt>
<dd>
<p>Length of vector <i>fvec</i>. Must statisfy <i>n_par</i> <= <i>m_dat</i>.</p>
</dd>
<dt id="data"><i>data</i></dt>
<dd>
<p>This pointer is ignored by the fit algorithm, except for appearing as an argument in all calls to the user-supplied routine <i>evaluate</i>.</p>
</dd>
<dt id="evaluate"><i>evaluate</i></dt>
<dd>
<p>Pointer to a user-supplied function that computes <i>m_dat</i> elements of vector <i>fvec</i> for a given parameter vector <i>par</i>. If <i>evaluate</i> return with *<i>userbreak</i> set to a negative value, <b>lmmin()</b> will interrupt the fitting and terminate.</p>
</dd>
<dt id="control"><i>control</i></dt>
<dd>
<p>Parameter collection for tuning the fit procedure. In most cases, the default &<i>lm_control_double</i> is adequate. If <i>f</i> is only computed with single-precision accuracy, <i>&lm_control_float</i> should be used. See also below, NOTES on initializing parameter records.</p>
<p><i>control</i> has the following members (for more details, see the source file <i>lmstruct.h</i>):</p>
<dl>
<dt id="double-control.ftol"><b>double</b> <i>control.ftol</i></dt>
<dd>
<p>Relative error desired in the sum of squares. Recommended setting: somewhat above machine precision; less if <i>fvec</i> is computed with reduced accuracy.</p>
</dd>
<dt id="double-control.xtol"><b>double</b> <i>control.xtol</i></dt>
<dd>
<p>Relative error between last two approximations. Recommended setting: as <i>ftol</i>.</p>
</dd>
<dt id="double-control.gtol"><b>double</b> <i>control.gtol</i></dt>
<dd>
<p>A measure for degeneracy. Recommended setting: as <i>ftol</i>.</p>
</dd>
<dt id="double-control.epsilon"><b>double</b> <i>control.epsilon</i></dt>
<dd>
<p>Step used to calculate the Jacobian. Recommended setting: as <i>ftol</i>, but definitely less than the accuracy of <i>fvec</i>.</p>
</dd>
<dt id="double-control.stepbound"><b>double</b> <i>control.stepbound</i></dt>
<dd>
<p>Initial bound to steps in the outer loop, generally between 0.01 and 100; recommended value is 100.</p>
</dd>
<dt id="int-control.patience"><b>int</b> <i>control.patience</i></dt>
<dd>
<p>Used to set the maximum number of function evaluations to patience*n_par.</p>
</dd>
<dt id="int-control.scale_diag"><b>int</b> <i>control.scale_diag</i></dt>
<dd>
<p>Logical switch (0 or 1). If 1, then scale parameters to their initial value. This is the recommended setting.</p>
</dd>
<dt id="FILE-control.msgfile"><b>FILE*</b> <i>control.msgfile</i></dt>
<dd>
<p>Progress messages will be written to this file. Typically <i>stdout</i> or <i>stderr</i>. The value <i>NULL</i> will be interpreted as <i>stdout</i>.</p>
</dd>
<dt id="int-control.verbosity"><b>int</b> <i>control.verbosity</i></dt>
<dd>
<p>If nonzero, some progress information from within the LM algorithm is written to control.stream.</p>
</dd>
<dt id="int-control.n_maxpri"><b>int</b> <i>control.n_maxpri</i></dt>
<dd>
<p>-1, or maximum number of parameters to print.</p>
</dd>
<dt id="int-control.m_maxpri"><b>int</b> <i>control.m_maxpri</i></dt>
<dd>
<p>-1, or maximum number of residuals to print.</p>
</dd>
</dl>
</dd>
<dt id="status"><i>status</i></dt>
<dd>
<p>A record used to return information about the minimization process:</p>
<dl>
<dt id="double-status.fnorm"><b>double</b> <i>status.fnorm</i></dt>
<dd>
<p>Norm of the vector <i>fvec</i>;</p>
</dd>
<dt id="int-status.nfev"><b>int</b> <i>status.nfev</i></dt>
<dd>
<p>Actual number of iterations;</p>
</dd>
<dt id="int-status.outcome"><b>int</b> <i>status.outcome</i></dt>
<dd>
<p>Status of minimization; for the corresponding text message, print <i>lm_infmsg</i><b>[</b><i>status.outcome</i><b>]</b>; for a short code, print <i>lm_shortmsg</i><b>[</b><i>status.outcome</i><b>]</b>.</p>
</dd>
<dt id="int-status.userbreak"><b>int</b> <i>status.userbreak</i></dt>
<dd>
<p>Set when termination has been forced by the user-supplied routine <i>evaluate</i>.</p>
</dd>
</dl>
</dd>
</dl>
<h1 id="NOTES">NOTES</h1>
<h2 id="Initializing-parameter-records">Initializing parameter records.</h2>
<p>The parameter record <i>control</i> should always be initialized from supplied default records:</p>
<pre><code> lm_control_struct control = lm_control_double; /* or _float */</code></pre>
<p>After this, parameters may be overwritten:</p>
<pre><code> control.patience = 500; /* allow more iterations */
control.verbosity = 15; /* for verbose monitoring */</code></pre>
<p>An application written this way is guaranteed to work even if new parameters are added to <i>lm_control_struct</i>.</p>
<p>Conversely, addition of parameters is not considered an API change; it may happen without increment of the major version number.</p>
<h1 id="EXAMPLES">EXAMPLES</h1>
<h2 id="Fitting-a-surface">Fitting a surface</h2>
<p>Fit a data set y(t) by a function f(t;p) where t is a two-dimensional vector:</p>
<pre><code> #include "lmmin.h"
#include <stdio.h>
/* fit model: a plane p0 + p1*tx + p2*tz */
double f( double tx, double tz, const double *p )
{
return p[0] + p[1]*tx + p[2]*tz;
}
/* data structure to transmit data arays and fit model */
typedef struct {
double *tx, *tz;
double *y;
double (*f)( double tx, double tz, const double *p );
} data_struct;
/* function evaluation, determination of residues */
void evaluate_surface( const double *par, int m_dat,
const void *data, double *fvec, int *userbreak )
{
/* for readability, explicit type conversion */
data_struct *D;
D = (data_struct*)data;
int i;
for ( i = 0; i < m_dat; i++ )
fvec[i] = D->y[i] - D->f( D->tx[i], D->tz[i], par );
}
int main()
{
/* parameter vector */
int n_par = 3; /* number of parameters in model function f */
double par[3] = { -1, 0, 1 }; /* arbitrary starting value */
/* data points */
int m_dat = 4;
double tx[4] = { -1, -1, 1, 1 };
double tz[4] = { -1, 1, -1, 1 };
double y[4] = { 0, 1, 1, 2 };
data_struct data = { tx, tz, y, f };
/* auxiliary parameters */
lm_status_struct status;
lm_control_struct control = lm_control_double;
control.verbosity = 3;
/* perform the fit */
printf( "Fitting:\n" );
lmmin( n_par, par, m_dat, (const void*) &data, evaluate_surface,
&control, &status );
/* print results */
printf( "\nResults:\n" );
printf( "status after %d function evaluations:\n %s\n",
status.nfev, lm_infmsg[status.outcome] );
printf("obtained parameters:\n");
int i;
for ( i=0; i<n_par; ++i )
printf(" par[%i] = %12g\n", i, par[i]);
printf("obtained norm:\n %12g\n", status.fnorm );
printf("fitting data as follows:\n");
double ff;
for ( i=0; i<m_dat; ++i ){
ff = f(tx[i], tz[i], par);
printf( " t[%2d]=%12g,%12g y=%12g fit=%12g residue=%12g\n",
i, tx[i], tz[i], y[i], ff, y[i] - ff );
}
return 0;
}</code></pre>
<h2 id="More-examples">More examples</h2>
<p>For more examples, see the homepage and directories demo/ and test/ in the source distribution.</p>
<h1 id="COPYING">COPYING</h1>
<p>Copyright (C): 1980-1999 University of Chicago 2004-2015 Joachim Wuttke, Forschungszentrum Juelich GmbH</p>
<p>Software: FreeBSD License</p>
<p>Documentation: Creative Commons Attribution Share Alike</p>
<h1 id="SEE-ALSO">SEE ALSO</h1>
<a href="http://apps.jcns.fz-juelich.de/man/lmcurve.html"><b>lmcurve</b>(3)</a>
<p>Homepage: http://apps.jcns.fz-juelich.de/lmfit</p>
<h1 id="BUGS">BUGS</h1>
<p>Please send bug reports and suggestions to the author <j.wuttke@fz-juelich.de>.</p>
</body>
</html>