LMMIN(3)

📦
version 10.0 · 2 versions
, in fedora 44

👑 NAME 👑

hi bestie 💖 welcome to lmmin(3), straight outta the lmfit manual. this one is the Levenberg-Marquardt least-squares minimization routine — specifically the simple/legacy API without error estimates. yes, legacy. yes, iconic. no cap.

✨ SYNOPSIS ✨

okay so this is literally the whole shape of it, look:

#include <lmmin.h>

void lmmin( const int n_par, double *par, const int m_dat,
            const void *y, const void *data,
            void *evaluate(
                 const double *par, const int m_dat,
                 const void *data, double *fvec, int *userbreak),
            const lm_control_struct *control,
            lm_status_struct *status );

extern const lm_control_struct lm_control_double;

extern const lm_control_struct lm_control_float;

extern const char *lm_infmsg[];

extern const char *lm_shortmsg[];

two default control records, two message tables, one function that does the whole vibe.</p> slay. 🫶

🦋 DESCRIPTION 🦋

so lmmin() figures out a vector par that minimizes the sum of squared elements of fvec-y. the vector fvec gets computed by a function you supply, called evaluate(); the vector y holds values you provide. and listen — on success, par is a local minimum, not necessarily a global one 😭. it can totally depend on whatever starting value you gave it. no notes.

this is just a simple wrapper around lmmin2(3), which also hands you error estimates. and going the other direction, lmcurve(3) is an even simpler wrapper, made for curve fitting. it's giving nested wrappers. it's giving matryoshka. 💅

the Levenberg-Marquardt minimization kicks off with a steepest-descent exploration of the parameter space, and then gets that rapid convergence by crossing over into the Newton-Gauss method. character development, honestly.

🫶 Function arguments 🫶

  • n_par — the number of free variables. i.e. the length of the parameter vector par.
  • par — the parameter vector. on input it's gotta hold a reasonable guess. on output it holds the solution found to minimize ||fvec||. glow-up. ✨
  • m_dat — the length of vector fvec. it must satisfy n_par <= m_dat.
  • y — input vector of length m_dat. it can also be the null pointer! in that case, lmmin() minimizes the squared sum of fvec instead of fvec-y. flexible queen.
  • data — this pointer gets ignored by the fit algorithm, except that it shows up as an argument in every single call to your user-supplied routine evaluate. it's just there to be passed along. a little courier. 🎀
  • evaluate — pointer to a user-supplied function that computes m_dat elements of vector fvec for a given parameter vector par. and heads up: if evaluate returns with *userbreak set to a negative value, lmmin() will interrupt the fitting and terminate. dramatic exit, valid.
  • control — the parameter collection for tuning the fit procedure. in most cases the default &lm_control_double is plenty. if f is only computed with single-precision accuracy, you should use &lm_control_float instead. also see below, in NOTES, about initializing parameter records.

control has the following members (for more details, see the source file lmstruct.h):

  • double control.ftol — relative error desired in the sum of squares. recommended setting: somewhat above machine precision; less if fvec is computed with reduced accuracy.
  • double control.xtol — relative error between the last two approximations. recommended setting: as ftol.
  • double control.gtol — a measure for degeneracy. recommended setting: as ftol.
  • double control.epsilon — step used to calculate the Jacobian. recommended setting: as ftol, but definitely less than the accuracy of fvec.
  • double control.stepbound — initial bound to steps in the outer loop, generally between 0.01 and 100; the recommended value is 100.
  • int control.patience — used to set the maximum number of function evaluations to patience*n_par.
  • int control.scale_diag — logical switch (0 or 1). if 1, then scale parameters to their initial value. this is the recommended setting. 💯
  • FILE* control.msgfile — progress messages get written to this file. typically stdout or stderr. the value NULL will be interpreted as stdout.
  • int control.verbosity — if nonzero, some progress information from within the LM algorithm is written to control.stream.
  • int control.n_maxpri — -1, or the maximum number of parameters to print.
  • int control.m_maxpri — -1, or the maximum number of residuals to print.
  • status — a record used to return information about the minimization process:
    • double status.fnorm — norm of the vector fvec;
    • int status.nfev — actual number of iterations;
    • int status.outcome — status of minimization; for the corresponding text message, print lm_infmsg[status.outcome]; for a short code, print lm_shortmsg[status.outcome].
    • int status.userbreak — set when termination has been forced by the user-supplied routine evaluate.

🎀 NOTES 🎀

🌸 Initializing parameter records. 🌸

the parameter record control should always be initialized from the supplied default records:

lm_control_struct control = lm_control_double; /* or _float */

after that, parameters may be overwritten:

control.patience = 500; /* allow more iterations */
control.verbosity = 15; /* for verbose monitoring */

an application written this way is guaranteed to work even if new parameters get added to lm_control_struct. that's the promise, bestie, and we hold it. 🫶

conversely — and this is important — the addition of parameters is not considered an API change. it may happen without the major version number going up. so don't come for us. 😭

🌈 EXAMPLES 🌈

🧚 Fitting a surface 🧚

fit a data set y(t) by a function f(t;p) where t is a two-dimensional vector:

#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;
}

ate that example up fr fr 🔥

💜 More examples 💜

want more? for more examples, go look at the homepage and the demo/ and test/ directories in the source distribution. they're there. they're waiting. 👑

🍓 COPYING 🍓

Copyright (C):

1980-1999 University of Chicago
2004-2018 Joachim Wuttke, Forschungszentrum Juelich GmbH

Software: FreeBSD License

Documentation: Creative Commons Attribution Share Alike

(giving legal-cute, giving licensed-and-thriving ✨)

⭐ SEE ALSO ⭐

💀 BUGS 💀

please send bug reports and suggestions to the author <j.wuttke@fz-juelich.de>. he wants them. he's asking. don't be shy. 🙈

and that's a wrap, bestie 🎀 this page came to you from the lmfit manual, generated by perl v5.42.0 on 2026-01-16 💖 go forth and minimize them squares ✨

📦 where this page comes from