=item UB

Example: UB => [10,10,10], LB => [-10,0,-5]. Box constraints. These have the same shape as the parameter pdl $p. The fit is done with ub forming upper bounds and lb lower bounds on the parameter values. Use, for instance PDL::Fit::Levmar::get_dbl_max() for parameters that you don't want bounded. You can use either linear constraints or box constraints, or both. That is, you may specify A, B, UB, and LB.

=item LB

See C.

=item WGHTS

Penalty weights can be given optionally when box and linear equality constraints are both passed to levmar. See the levmar documenation for how to use this. Note that if C and D are used then the WGHTS must not passed.

=item C

Example: C => [ [ -1, -2, -1, -1], [ -3, -1, -2, 1] ], D => [ -5, -0.4] Linear inequality constraints. Minimize with constraints $C x $p >= $d. The dimensions are C(k2,m), D(m), p(m).

=item D

See C

=item P

Keys P, X, and T can be used to send to the parameters, ordinates and coordinates. Alternatively, you can send them as non-option arguments to levmar before the option arguments.

=item X

See C

=item T

See C

=item DIR

The directory containing files created when compiling C and C fit functions. This defaults to being created by L<File::Temp/tempdir>. The .c, .o, and .so files will be written to this directory. This option actually falls through to levmar_func. Such options should be in separate section, or otherwise noted.

=item GETOPTS

If defined, return a ref to a hash containing the default values of the parameters.

=item COVAR

Send a pdl reference for the output hash element COVAR. You may want to test if this option is more efficient for some problem. But unless the covariance matrix is very large, it probably won't help much. On the other hand it almost certainly won't make levmar() less efficient.

Note that levmar returns a piddle representing the covariance in the output hash. This will be the the same piddle that you give as input via this option. So, if you do the following,

my $covar = PDL->null my $h =levmar(...., COVAR => $covar);

then $covar and $h->{COVAR} are references to the same pdl. The storage for the pdl will not be destroyed until both $covar and $h->{COVAR} become undefined.

=item NOCOVAR

If defined, no covariance matrix is computed.

=item POUT

Send a pdl reference for the output hash element P. Don't confuse this with the option P which can be used to send the initial guess for the parameters (see C).

=item INFO

Send a pdl reference for the output hash element C. (see C)

=item RET

Send a pdl reference for the output hash element C. (see C)

=item MAXITS

Maximum number of iterations to try before giving up. The default is 100.

=item MU

The starting value of the parameter mu in the L-M algorithm.

=item EPS1, EPS2, EPS3

Stopping thresholds for C<||J^T e||_inf>, C<||Dp||_2> and C<||e||_2>. (see the document levmar.pdf by the author of liblevmar and distributed with this module) The algorithm stops when the first threshold is reached (or C is reached). See C for determining which threshold was reached.

Here, C is a the vector of errors between the data and the model function and C

is the vector of parameters. S<||J^T e||_inf> is the gradient of C w.r.t C

at the current estimate of C

; C<||Dp||_2> is the amount by which C

is currently being shifted at each iteration; C<||e||_2> is a measure of the error between the model function at the current estimate for C

and the data.

=item DELTA

This is a step size used in computing numeric derivatives. It is not used if the analytic jacobian is used.

=item MKOBJ

command to compile source into object code. This option is actually set in the Levmar::Func object, but can be given in calls to levmar(). The default value is determined by the perl installation and can be determined by examining the Levmar::Func object returned by new or the output hash of a call to levmar. A typical value is cc -c -O2 -fPIC -o %o %c

=item MKSO

command to convert object code to dynamic library code. This option is actually set in the Levmar::Func object. A typical default value is cc -shared -L/usr/local/lib -fstack-protector %o -o %s

=item CTOP

The value of this string will be written at the top of the c code written by Levmar::Func. This can be used to include headers and so forth. This option is actually set in the Levmar::Func object. This code is also written at the top of c code translated from lpp code.

=item FVERBOSE

If true (eg 1) Print the compiling and linking commands to STDERR when compiling fit functions. This option is actually passed to Levmar::Func. Default is 0.

=item Default values

Here are the default values of some options

$Levmar_defaults = { FUNC => undef, # Levmar::Func object, or function def, or ... JFUNC => undef, # must be ref to perl sub MAXITS => 100, # maximum iterations MU => LM_INIT_MU, # These are described in levmar docs EPS1 => LM_STOP_THRESH, EPS2 => LM_STOP_THRESH, EPS3 => LM_STOP_THRESH, DELTA => LM_DIFF_DELTA, DERIVATIVE => 'analytic', FIX => undef, A => undef, B => undef, C => undef, D => undef, UB = undef, LB => undef, X => undef, P => undef, T => undef, WGHTS => undef,

meant to be private

LFUNC => undef, # only Levmar::Func object, made from FUNC };

=back

=head1 OUTPUT

This section describes the contents of the hash that levmar takes as output. Do not confuse these hash keys with the hash keys of the input options. It may be a good idea to change the interface by prepending O to all of the output keys that could be confused with options to levmar().

=over 3

=item P (output)

pdl containing the optimized parameters. It has the same shape as the input parameters.

=item FUNC (output)

ref to the Levmar::Func object. This object may have been created during the call to levmar(). For instance, if you pass a string contiaining an C definition, the compiled object (and associated information) is contained in $outh->{FUNC}. Don't confuse this with the input parameter of the same name.

=item COVAR (output)

a pdl representing covariance matrix.

=item REASON

an integer code representing the reason for terminating the fit. (call levmar_report($outh) for an interpretation. The interpretations are listed here as well (see the liblevmar documentation if you don't find an explanation somewhere here.)

1 stopped by small gradient J^T e 2 stopped by small Dp 3 stopped by itmax 4 singular matrix. Restart from current p with increased \mu 5 no further error reduction is possible. Restart with increased \mu 6 stopped by small ||e||_2

=item ERRI, ERR1, ERR2, ERR3, ERR4

ERRI is C<||e||_2> at the initial paramters. ERR1 through ERR3 are the actual values on termination of the quantities corresponding to the thresholds EPS1 through EPS3 described in the options section. ERR4 is C<mu/max[J^T J]_ii>

=item ITS

Number of iterations performed

=item NFUNC, NJAC, NLS

Number of function evaluations, number of jacobian evaluations and number of linear systems solved.

=item INFO

Array containing ERRI,ERR1, ..., ERR4, ITS, REASON, NFUNC, NJAC, NLS.

=back

=head1 FIT FUNCTIONS

Fit functions, or model functions can be specified in the following ways.

=over 3

=item lpp

It is easier to learn to use C by reading the C section.

C processes a function definition into C code. It writes the opening and closing parts of the function, alters a small number of identifiers if they appear, and wraps some of the code in a loop. C recognizes four directives. They must occur on a line with nothing else, not even comments.

First, the directives are explained, then the substitutions. The directive lines have a strict format. All other lines can contain any C code including comments and B macros. They will be written to a function in C after the substitutions described below.

=over 3

=item C<function, jacobian>

The first line of the fit function definition must be C. The first line of the jacobian definition, if the jacobian is to be defined, is C<jacobian funcname>. The function names can be any valid C function name. The names may also be omitted as they are never needed by the user. The names can be identical. (Note that a numeric suffix will be automatically added to the function name if the .so file already exists. This is because, if another Func object has already loaded the shared library from an .so file, dlopen will use this loaded library for all C objects asking for that .so file, even if the file has been overwritten, causing unexpected behavior)

=item C

The directive C says that all code before C is not in the implicit loop, while all code following C is in the implicit loop. If you omit the directive, then all the code is wrapped in a loop.

=item C

The directive C says that there is no implicit loop anywhere in the function.

=item Out-of-loop substitutions

These substitutions translate C to C in lines that occur before the implied loop (or everywhere if there is no loop.) In every case you can write the translated C code into your function definition yourself and C will leave it untouched.

=over 3

=item pq -> p[q]

where q is a sequence of digits.

=item xq -> x[q]

where q is a sequence of digits. This is applied only in the fit function, not in the jacobian.

=item dq[r] -> d[q+m*r]

(where m == $p->nelem), q and r are sequences of digits. This applies only in the jacobian. You usually will only use the fit functions with one value of m. It would make faster code if you were to explicitly write, say C<d[u]>, for each derivative at each point. Presumably there is a small number of data points since this is outside a loop. Some provisions should be added to C, say C<m=3> to hard code the value of C. But m is only explicitly used in constructions involving this substitution.

=back

=item In-loop substitutions

These substitutions apply inside the implied loop. The loop variables are i in the fit function and i and j in the jacobian.

=over 3

=item t -> t[i]

(literal "i") You can also write t[i] or t[expression involving i] by hand. Example: tt -> t[i]t[i].

=item pq -> p[q]

where q is a sequence of digits. Example p3 -> p[3].

=item x -> x[i]

only in fit function, not in jacobian.

=item (dr or dr[i]) -> d[j++]

where r is a sequence of digits. Note that r and i are ignored. So you are required to list the derivatives in order. An example is

d0 = t*t;  // derivative w.r.t p[0] loop over all points
d1 = t;    

If you write C first and then C, lpp will incorrectly assign the derivative functions.

=back

=back

=item C Code

The jacobian name must start with 'jac' when a pure C function definition is used. To see example of fit functions writen in C, call levmar with lpp code and the option C. This will leave the C source in the directory given by C

p(m); t(n); [o] err(n);
This is the relevant part of the signature of the
routine that does the work.

use PDL::Fit::Levmar::Func;