

   nnoonn--lliinneeaarr mmiinniimmiizzaattiioonn

        nlm(f, p, hessian = FALSE, typsize=rep(1, length(p)), fscale=1,
            print.level = 0, ndigit=12, gradtol = 1e-6,
            stepmax = max(1000 * sqrt(sum((p/typsize)^2)), 1000),
            steptol = 1e-6, iterlim = 100)

   AArrgguummeennttss::

          f: the function to be minimized.

          p: starting parameter values for the minimization.

    hessian: if `TRUE', the hessian of `f' at the minimum is
             returned.

    typsize: an estimate of the size of each parameter at the
             minimum.

     fscale: an estimate of the size of `f' at the minimum.

   print.level: this argument determines the level of printing
             which is done during the minimization process.
             The default value of `0' means that no printing
             occurs, a value of `1' means that initial and
             final details are printed and a value of 2 means
             that full tracing information is printed.

     ndigit: the number of significant digits in the function
             `f'.

    gradtol: a positive scalar giving the tolerance at which
             the scaled gradient is considered close enough to
             zero to terminate the algorithm.  The scaled gra-
             dient is a measure of the relative change in `f'
             in each direction `p[i]' divided by the relative
             change in `p[i]'.

    stepmax: a positive scalar which gives the maximum allow-
             able scaled step length.  `stepmax' is used to
             prevent steps which would cause the optimization
             function to overflow, to prevent the algorithm
             from leaving the area of interest in parameter
             space, or to detect divergence in the algorithm.
             `stepmax' would be chosen small enough to prevent
             the first two of these occurrences, but should be
             larger than any anticipated reasonable step.

    steptol: A positive scalar providing the minimum allowable
             relative step length.

    iterlim: a positive integer specifying the maximum number
             of iterations to be performed before the program
             is terminated.

   DDeessccrriippttiioonn::

        This function carries out a minimization of the func-
        tion `f' using a Newton-type algorithm.  See the refer-
        ences for details.

        This is a preliminary version of this function and it
        will probably change.

   VVaalluuee::

        A list containing the following components:

    minimum: the value of the estimated minimum of `f'.

   estimate: the point at which the mininum value of `f' is
             obtained.

   gradient: the gradient at the estimated minimum of `f'.

    hessian: the hessian at the estimated minimum of `f' (if
             requested).

       code: an integer indicating why the optimization process
             terminated.

             1: relative gradient is close to zero, current
             iterate is probably solution.

             2: successive iterates within tolerance, current
             iterate is probably solution.

             3: last global step failed to locate a point lower
             than `estimate'.  Either `estimate' is an approxi-
             mate local minimum of the function or `steptol' is
             too small.

             4: iteration limit exceeded.

             5: maximum step size `stepmax' exceeded five con-
             secutive times.  Either the function is unbounded
             below, becomes asymptotic to a finite value from
             above in some direction, of `stepmax' is too
             small.

   RReeffeerreenncceess::

        Dennis, J. E. and Schnabel, R. B. (1983) Numerical
        Methods for Unconstrained Optimization and Nonlinear
        Equations, Prentice-Hall, Englewood Cliffs, NJ.

        Schnabel, R. B., Koontz, J. E. and Weiss, B. E. (1985)
        A modular system of algorithms for unconstrained mini-
        mization, ACM Trans. Math. Software, 11, 419-440.

   SSeeee AAllssoo::

        `optimize' for one-dimensional minimization and `uni-
        root' for root finding.  `demo(nlm)' for more examples.

   EExxaammpplleess::

        f <- function(x) sum((x-1:length(x))^2)
        nlm(f, c(10,10))
        nlm(f, c(10,10), print.level = 2)
        str(nlm(f, c(5), hessian = TRUE))

