# fmins

## Purpose

Minimize a function of several variables.

## Synopsis

    x = fmins('function',x0)
    x = fmins('function',x0,options)
    x = fmins('function',x0,options,[],arg1,arg2, ...)
    [x,options] = fmins(...)

## Description

`x = fmins('function',x0)` returns a vector `x` which is a local minimizer of `function(x)` near the starting vector `x0`. `function` is a string containing the name of the objective function to be minimized. `function(x)` is a scalar valued function of a vector variable.

`x = fmins('function',x0,options)` uses a vector of control parameters.

- If `options(1)` is nonzero, intermediate steps in the solution are displayed. The default value of `options(1)` is `0`.
- `options(2)` is the termination tolerance for `x`. The default value is 1.e-4.
- `options(3)` is the termination tolerance for `function(x)`. The default value is 1.e-4.
- `options(14)` is the maximum number of steps. The default value is `500`.
  Only four of the 18 components of options are referenced by `fmins`. Other functions in the Optimization Toolbox reference the other options.

  `x = fmins('function',x0,options,[],arg1,arg2,...)` provides up to 10 additional arguments which are passed to the objective function, `function(x,arg1,arg2, ...)`. The dummy argument in the fourth position is necessary to provide compatibility with `fminu` in the Optimization Toolbox.

  `[x,options] = fmins(...)` returns a count of the number of steps taken in `options(10)`.

  ## Examples

  A classic test example for multidimensional minimization is the Rosenbrock banana function:

  The minimum is at (1,1) and has the value 0. The traditional starting point is (-1.2,1). The M-file `banana.m` defines the function.

      function f = banana(x)
      f = 100*(x(2)-x(1)^2)^2+(1-x(1))^2;

  The statements

      [x,out] = fmins('banana',[-1.2, 1]);
      x
      out(10)

  produce

      x =
          1.0000    1.0000

      ans =
          165

  This indicates that the minimizer was found to at least four decimal places in 165 steps.

  The location of the minimum can be moved to the point`[a,a^2]` by adding a second parameter to `banana.m`.

      function f = banana(x,a)
      if nargin < 2, a = 1; end
      f = 100*(x(2)-x(1)^2)^2+(a-x(1))^2;

  Then the following statement sets the new parameter to `sqrt(2)` and seeks the minimum to an accuracy higher than the default.

      [x,out] = fmins('banana', [-1.2, 1], [0, 1.e-8], [], sqrt(2));

  ## Algorithm

  The algorithm is the Nelder-Mead simplex search described in the two references. It is a direct search method that does not require gradients or other derivative information. If `n` is the length of `x`, a simplex in `n`-dimensional space is characterized by the `n+1` distinct vectors which are its vertices. In two-space, a simplex is a triangle; in three-space, it is a pyramid.

  At each step of the search, a new point in or near the current simplex is generated. The function value at the new point is compared with the function's values at the vertices of the simplex and, usually, one of the vertices is replaced by the new point, giving a new simplex. This step is repeated until the diameter of the simplex is less than the specified tolerance.

  ## See Also

      fmin, foptions, and the Optimization Toolbox

  ## References

  [1] J. A. Nelder and R. Mead, "A Simplex Method for Function Minimization," Computer Journal, vol. 7, p. 308-313.

  [2] J. E. Dennis, Jr. and D. J. Woods, "New Computing Environments: Microcomputers in Large-Scale Computing," edited by A. Wouk, SIAM, pp. 116-122, 1987.

  (c) Copyright 1994 by The MathWorks, Inc.