Scilab Function

leastsq - Solves non-linear least squaresproblems

### Calling Sequence

  `[f,xopt]=leastsq([imp,] fun [,Dfun],x0)`
  `[f,[xopt,[gradopt]]]=leastsq(fun [,Dfun],[contr],x0,['algo'],[df0,[mem]],`
  `,[stop],['in'])`

### Parameters

- `imp` : scalar argument used to set the trace mode. `imp=0` nothing (execpt errors) is reported, `imp=1` initial and final reports, `imp=2` adds a report per iteration, `imp>2` add reports on linear search. Warning, most of these reports are written on the Scilab standard output.
- `fun` : external, i.e Scilab function or string (`fun` is the function defining the least square probleme: see below.
- `x0` : real vector (initial value of variable to be minimized).
- `f` : value of optimal least square value.
- `xopt` : best value of `x` found.
- `contr` : `'b',binf,bsup` with `binf` and `bsup` real vectors with same dimension as `x0`. `binf` and `bsup` are lower and upper bounds on `x`.
- `algo` : A string with possible values :`'qn'` or `'gc'` or `'nd'` . This string stands for quasi-Newton (default), conjugate gradient or non-differentiable respectively. Note that `'nd'` does not accept bounds on `x` ).
- `df0` : real scalar. Guessed decreasing of `f` at first iteration. (`df0=1` is the default value).
- `mem` : integer, number of variables used to approximate the Hessian, (`algo='gc' or 'nd'`). Default value is around 6.
- `stop` : sequence of optional parameters controlling the convergence of the algorithm.

  `stop= 'ar',nap, [iter [,epsg [,epsf [,epsx]]]]`
  - `"ar"` : reserved keyword for stopping rule selection defined as follows:
  - `nap` : maximum number of calls to `fun` allowed.
  - `iter` : maximum number of iterations allowed.
  - `epsg` : threshold on gradient norm.
  - `epsf` : threshold controlling decreasing of `f`
  - `epsx` : threshold controlling variation of `x`. This vector (possibly matrix) of same size as `x0` can be used to scale `x`.
- `"in"` : reserved keyword for initialization of parameters used when `fun` in given as a Fortran routine (see below).
- `gradopt` : gradient of `fun` at `xopt`

### Description

Non-linear optimization routine for programs without constraints or with bound constraints:

`min sum(f(x)).^2` w.r.t `x`, Here, `f` is a function from R^n to R^m which returns `f(x)`, a real vector ( value of function at `x`).
- fun gives the definition of the function `f(x)`. It is an "external" i.e function, or list or C or Fortran routine (see "external").

  This external must return a vector `y` such as (`y(j)=f(x)`) for a given `x`.
- If `fun` is a Scilab function, the calling sequence for `fun` must be:

  `y=fun(x, [optional parameters])`
- If `fun` is defined by a Fortran or C routine first argument must be a list:

  `list(fun_name,m,p1,..pl)`

  `fun_name` is then a character string, it refers to the name of the routine which must be linked to Scilab. Here, the generic calling sequences are:

  In Fortran

                subroutine fun(n,m,x,td,y)
                integer n,m
                double precision x(n), td(*), y(m)

  In C

                void fun(int *n,int *m, double *x,double *params, double *y)

  `n` is the dimension of vector `x` , `m` is the dimension of vector`y`, `td` is a vector which contains the parameters `p1,..pl`
- Dfun Gives the definition of the function `df(x)/dx`. It is an "external".This external must return a matrix `g` such as (`g(i,j)=dfi/dxj`) for a given `x`.
- If `Dfun` is a function, the calling sequence for `fun` must be:

  `g=Dfun(x, [optional parameters])` .
- If `Dfun` is defined by a Fortran or C routine first argument must be a list:

  `list(fun_name,m,...)` `fun_name` is a character string, it refers to the name of the routine which must be linked to Scilab. This function has the same calling sequence as `fun`

### Examples

    a=rand(3,2);b=[1;1;1];x0=[1;-1];
    deff('f=fun(x,a,b)','f=a*x-b');
    deff('g=dfun(x,a,b)','g=a');

    [f,xopt]=leastsq(fun,x0)      //Simplest call
    xopt-a\b  //compare with linear algebra solution

    [f,xopt]=leastsq(fun,dfun,x0)      //specify gradient

    [f,xopt]=leastsq(list(fun,[1 2;3 4],[1;2]),x0)

    deff('f=fun(x,a,b)','f=exp(a*x)-b');
    deff('g=dfun(x,a,b)','g=a.*(exp(a*x)*ones(1,size(a,2)))');

    [f,xopt]=leastsq(list(fun,[1 2;3 4],[1;2]),x0)

### See Also

`external` `quapro` `linpro`