@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 2007 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Optimization
@chapter Optimization

Octave comes with support for solving various kinds of optimization
problems. Specifically Octave can solve problems in Linear Programming,
Quadratic Programming, Nonlinear Programming, and Linear Least Squares
Minimization.

@menu
* Linear Programming::       
* Quadratic Programming::       
* Nonlinear Programming::       
* Linear Least Squares::        
@end menu

@c @cindex linear programming
@cindex quadratic programming
@cindex nonlinear programming
@cindex optimization
@cindex LP
@cindex QP
@cindex NLP

@node Linear Programming
@section Linear Programming

Octave can solve Linear Programming problems using the @code{glpk}
function.  That is, Octave can solve

@iftex
@tex
$$
  \min_x c^T x
$$
@end tex
@end iftex
@ifnottex
@example
min C'*x
@end example
@end ifnottex
subject to the linear constraints
@iftex
@tex
$Ax = b$ where $x \geq 0$.
@end tex
@end iftex
@ifnottex
@math{A*x = b} where @math{x >= 0}.
@end ifnottex

@noindent
The @code{glpk} function also supports variations of this problem.

@anchor{doc-glpk}
@deftypefn {Function File} {[@var{xopt}, @var{fmin}, @var{status}, @var{extra}] =} glpk (@var{c}, @var{a}, @var{b}, @var{lb}, @var{ub}, @var{ctype}, @var{vartype}, @var{sense}, @var{param})
Solve a linear program using the GNU GLPK library.  Given three
arguments, @code{glpk} solves the following standard LP:

@iftex
@tex
$$
  \min_x C^T x
$$
@end tex
@end iftex
@ifnottex
@example
min C'*x
@end example
@end ifnottex

subject to

@iftex
@tex
$$
  Ax = b \qquad x \geq 0
$$
@end tex
@end iftex
@ifnottex
@example
@group
A*x  = b
  x >= 0
@end group
@end example
@end ifnottex

but may also solve problems of the form

@iftex
@tex
$$
  [ \min_x | \max_x ] C^T x
$$
@end tex
@end iftex
@ifnottex
@example
[ min | max ] C'*x
@end example
@end ifnottex

subject to

@iftex
@tex
$$
 Ax [ = | \leq | \geq ] b \qquad  LB \leq x \leq UB
$$
@end tex
@end iftex
@ifnottex
@example
@group
A*x [ "=" | "<=" | ">=" ] b
  x >= LB
  x <= UB
@end group
@end example
@end ifnottex

Input arguments:

@table @var
@item c
A column array containing the objective function coefficients.

@item a
A matrix containing the constraints coefficients.

@item b
A column array containing the right-hand side value for each constraint
in the constraint matrix.

@item lb
An array containing the lower bound on each of the variables.  If
@var{lb} is not supplied, the default lower bound for the variables is
zero.

@item ub
An array containing the upper bound on each of the variables.  If
@var{ub} is not supplied, the default upper bound is assumed to be
infinite.

@item ctype
An array of characters containing the sense of each constraint in the
constraint matrix.  Each element of the array may be one of the
following values
@table @code
@item "F"
Free (unbounded) variable (the constraint is ignored).
@item "U"
Variable with upper bound (@code{A(i,:)*x <= b(i)}).
@item "S"
Fixed Variable (@code{A(i,:)*x = b(i)}).
@item "L"
Variable with lower bound (@code{A(i,:)*x >= b(i)}).
@item "D"
Double-bounded variable (@code{A(i,:)*x >= -b(i)} @emph{and}
(@code{A(i,:)*x <= b(i)}).
@end table

@item vartype
A column array containing the types of the variables.
@table @code
@item "F"
"C"
Continuous variable.
"I"
Integer variable
@end table

@item sense
If @var{sense} is 1, the problem is a minimization.  If @var{sense} is
-1, the problem is a maximization.  The default value is 1.

@item param
A structure containing the following parameters used to define the
behavior of solver.  Missing elements in the structure take on default
values, so you only need to set the elements that you wish to change
from the default.

Integer parameters:

@table @code
@item msglev (@code{LPX_K_MSGLEV}, default: 1)
Level of messages output by solver routines:
@table @asis
@item 0
No output.
@item 1
Error messages only.
@item 2
Normal output .
@item 3
Full output (includes informational messages).
@end table

@item scale (@code{LPX_K_SCALE}, default: 1)
Scaling option: 
@table @asis
@item 0
No scaling.
@item 1
Equilibration scaling.
@item 2
Geometric mean scaling, then equilibration scaling.
@end table

@item dual	 (@code{LPX_K_DUAL}, default: 0)
Dual simplex option:
@table @asis
@item 0
Do not use the dual simplex.
@item 1
If initial basic solution is dual feasible, use the dual simplex.
@end table

@item price	 (@code{LPX_K_PRICE}, default: 1)
Pricing option (for both primal and dual simplex):
@table @asis
@item 0
Textbook pricing.
@item 1
Steepest edge pricing.
@end table
  
@item round	 (@code{LPX_K_ROUND}, default: 0)
Solution rounding option:
@table @asis
@item 0
Report all primal and dual values "as is".
@item 1
Replace tiny primal and dual values by exact zero.
@end table

@item itlim	 (@code{LPX_K_ITLIM}, default: -1)
Simplex iterations limit.  If this value is positive, it is decreased by
one each time when one simplex iteration has been performed, and
reaching zero value signals the solver to stop the search.  Negative
value means no iterations limit.

@item itcnt (@code{LPX_K_OUTFRQ}, default: 200)
Output frequency, in iterations.  This parameter specifies how
frequently the solver sends information about the solution to the
standard output.

@item branch (@code{LPX_K_BRANCH}, default: 2)
Branching heuristic option (for MIP only):
@table @asis
@item 0
Branch on the first variable.
@item 1
Branch on the last variable.
@item 2
Branch using a heuristic by Driebeck and Tomlin.
@end table

@item btrack (@code{LPX_K_BTRACK}, default: 2)
Backtracking heuristic option (for MIP only):
@table @asis
@item 0
Depth first search.
@item 1
Breadth first search.
@item 2
Backtrack using the best projection heuristic.
@end table        

@item presol (@code{LPX_K_PRESOL}, default: 1)
If this flag is set, the routine lpx_simplex solves the problem using
the built-in LP presolver.  Otherwise the LP presolver is not used.

@item lpsolver (default: 1)
Select which solver to use.  If the problem is a MIP problem this flag
will be ignored.
@table @asis
@item 1
Revised simplex method.
@item 2
Interior point method.
@end table
@item save (default: 0)
If this parameter is nonzero, save a copy of the problem in
CPLEX LP format to the file @file{"outpb.lp"}.  There is currently no
way to change the name of the output file.
@end table

Real parameters:

@table @code
@item relax (@code{LPX_K_RELAX}, default: 0.07)
Relaxation parameter used in the ratio test. If it is zero, the textbook
ratio test is used. If it is non-zero (should be positive), Harris'
two-pass ratio test is used. In the latter case on the first pass of the
ratio test basic variables (in the case of primal simplex) or reduced
costs of non-basic variables (in the case of dual simplex) are allowed
to slightly violate their bounds, but not more than
@code{relax*tolbnd} or @code{relax*toldj (thus, @code{relax} is a
percentage of @code{tolbnd} or @code{toldj}}.

@item tolbnd (@code{LPX_K_TOLBND}, default: 10e-7)
Relative tolerance used to check if the current basic solution is primal
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item toldj (@code{LPX_K_TOLDJ}, default: 10e-7)
Absolute tolerance used to check if the current basic solution is dual
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item tolpiv (@code{LPX_K_TOLPIV}, default: 10e-9)
Relative tolerance used to choose eligible pivotal elements of the
simplex table.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item objll (@code{LPX_K_OBJLL}, default: -DBL_MAX)
Lower limit of the objective function.  If on the phase II the objective
function reaches this limit and continues decreasing, the solver stops
the search.  This parameter is used in the dual simplex method only.

@item objul (@code{LPX_K_OBJUL}, default: +DBL_MAX)
Upper limit of the objective function. If on the phase II the objective
function reaches this limit and continues increasing, the solver stops
the search.  This parameter is used in the dual simplex only.

@item tmlim (@code{LPX_K_TMLIM}, default: -1.0)
Searching time limit, in seconds. If this value is positive, it is
decreased each time when one simplex iteration has been performed by the
amount of time spent for the iteration, and reaching zero value signals
the solver to stop the search.  Negative value means no time limit.

@item outdly (@code{LPX_K_OUTDLY}, default: 0.0)
Output delay, in seconds. This parameter specifies how long the solver
should delay sending information about the solution to the standard
output. Non-positive value means no delay.

@item tolint (@code{LPX_K_TOLINT}, default: 10e-5)
Relative tolerance used to check if the current basic solution is integer
feasible.  It is not recommended that you change this parameter unless
you have a detailed understanding of its purpose.

@item tolobj (@code{LPX_K_TOLOBJ}, default: 10e-7)
Relative tolerance used to check if the value of the objective function
is not better than in the best known integer feasible solution.  It is
not recommended that you change this parameter unless you have a
detailed understanding of its purpose.
@end table
@end table

Output values:

@table @var
@item xopt
The optimizer (the value of the decision variables at the optimum).
@item fopt
The optimum value of the objective function.
@item status
Status of the optimization.

Simplex Method:
@table @asis
@item 180 (@code{LPX_OPT})
Solution is optimal.
@item 181 (@code{LPX_FEAS})
Solution is feasible.
@item 182 (@code{LPX_INFEAS})
Solution is infeasible.
@item 183 (@code{LPX_NOFEAS})
Problem has no feasible solution.
@item 184 (@code{LPX_UNBND})
Problem has no unbounded solution.
@item 185 (@code{LPX_UNDEF})
Solution status is undefined.
@end table
Interior Point Method:
@table @asis
@item 150 (@code{LPX_T_UNDEF})
The interior point method is undefined.
@item 151 (@code{LPX_T_OPT})
The interior point method is optimal.
@end table
Mixed Integer Method:
@table @asis
@item 170 (@code{LPX_I_UNDEF})
The status is undefined.
@item 171 (@code{LPX_I_OPT})
The solution is integer optimal.
@item 172 (@code{LPX_I_FEAS})
Solution integer feasible but its optimality has not been proven
@item 173 (@code{LPX_I_NOFEAS})
No integer feasible solution.
@end table
@noindent
If an error occurs, @var{status} will contain one of the following
codes:

@table @asis
@item 204 (@code{LPX_E_FAULT})
Unable to start the search.
@item 205 (@code{LPX_E_OBJLL})
Objective function lower limit reached.
@item 206 (@code{LPX_E_OBJUL})
Objective function upper limit reached.
@item 207 (@code{LPX_E_ITLIM})
Iterations limit exhausted.
@item 208 (@code{LPX_E_TMLIM})
Time limit exhausted.
@item 209 (@code{LPX_E_NOFEAS})
No feasible solution.
@item 210 (@code{LPX_E_INSTAB})
Numerical instability.
@item 211 (@code{LPX_E_SING})
Problems with basis matrix.
@item 212 (@code{LPX_E_NOCONV})
No convergence (interior).
@item 213 (@code{LPX_E_NOPFS})
No primal feasible solution (LP presolver).
@item 214 (@code{LPX_E_NODFS})
No dual feasible solution (LP presolver).
@end table
@item extra
A data structure containing the following fields:
@table @code
@item lambda
Dual variables.
@item redcosts
Reduced Costs.
@item time
Time (in seconds) used for solving LP/MIP problem.
@item mem
Memory (in bytes) used for solving LP/MIP problem (this is not 
available if the version of GLPK is 4.15 or later).
@end table
@end table

Example:

@example
@group
c = [10, 6, 4]';
a = [ 1, 1, 1;
     10, 4, 5;
      2, 2, 6];
b = [100, 600, 300]';
lb = [0, 0, 0]';
ub = [];
ctype = "UUU";
vartype = "CCC";
s = -1;

param.msglev = 1;
param.itlim = 100;

[xmin, fmin, status, extra] = ...
   glpk (c, a, b, lb, ub, ctype, vartype, s, param);
@end group
@end example
@end deftypefn


@node Quadratic Programming
@section Quadratic Programming

Octave can also solve Quadratic Programming problems, this is
@iftex
@tex
$$
 \min_x {1 \over 2} x^T H x + x^T q
$$
@end tex
@end iftex
@ifnottex
@example
min 0.5 x'*H*x + x'*q
@end example
@end ifnottex
subject to
@iftex
@tex
$$
 Ax = b \qquad lb \leq x \leq ub \qquad A_{lb} \leq A_{in} \leq A_{ub}
$$
@end tex
@end iftex
@ifnottex
@example
     A*x = b
     lb <= x <= ub
     A_lb <= A_in*x <= A_ub
@end example
@end ifnottex

@anchor{doc-qp}
@deftypefn {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, @var{A_in}, @var{A_ub})
Solve the quadratic program
@iftex
@tex
$$
 \min_x {1 \over 2} x^T H x + x^T q
$$
@end tex
@end iftex
@ifnottex

@example
     min 0.5 x'*H*x + x'*q
      x
@end example

@end ifnottex
subject to
@iftex
@tex
$$
 Ax = b \qquad lb \leq x \leq ub \qquad A_{lb} \leq A_{in} \leq A_{ub}
$$
@end tex
@end iftex
@ifnottex

@example
     A*x = b
     lb <= x <= ub
     A_lb <= A_in*x <= A_ub
@end example
@end ifnottex

@noindent
using a null-space active-set method.

Any bound (@var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb},
@var{A_ub}) may be set to the empty matrix (@code{[]}) if not
present.  If the initial guess is feasible the algorithm is faster.

The value @var{info} is a structure with the following fields:
@table @code
@item solveiter
The number of iterations required to find the solution.
@item info
An integer indicating the status of the solution, as follows:
@table @asis
@item 0
The problem is feasible and convex.  Global solution found.
@item 1
The problem is not convex.  Local solution found.
@item 2
The problem is not convex and unbounded.
@item 3
Maximum number of iterations reached.
@item 6
The problem is infeasible.
@end table
@end table
@end deftypefn


@node Nonlinear Programming
@section Nonlinear Programming

Octave can also perform general nonlinear minimization using a
successive quadratic programming solver.

@anchor{doc-sqp}
@deftypefn {Function File} {[@var{x}, @var{obj}, @var{info}, @var{iter}, @var{nf}, @var{lambda}] =} sqp (@var{x}, @var{phi}, @var{g}, @var{h})
Solve the nonlinear program
@iftex
@tex
$$
\min_x \phi (x)
$$
@end tex
@end iftex
@ifnottex

@example
     min phi (x)
      x
@end example

@end ifnottex
subject to
@iftex
@tex
$$
 g(x) = 0 \qquad h(x) \geq 0
$$
@end tex
@end iftex
@ifnottex

@example
     g(x)  = 0
     h(x) >= 0
@end example
@end ifnottex

@noindent
using a successive quadratic programming method.

The first argument is the initial guess for the vector @var{x}.

The second argument is a function handle pointing to the objective
function.  The objective function must be of the form

@example
     y = phi (x)
@end example

@noindent
in which @var{x} is a vector and @var{y} is a scalar.

The second argument may also be a 2- or 3-element cell array of
function handles.  The first element should point to the objective
function, the second should point to a function that computes the
gradient of the objective function, and the third should point to a
function to compute the hessian of the objective function.  If the
gradient function is not supplied, the gradient is computed by finite
differences.  If the hessian function is not supplied, a BFGS update
formula is used to approximate the hessian.

If supplied, the gradient function must be of the form

@example
     g = gradient (x)
@end example

@noindent
in which @var{x} is a vector and @var{g} is a vector.

If supplied, the hessian function must be of the form

@example
     h = hessian (x)
@end example

@noindent
in which @var{x} is a vector and @var{h} is a matrix.

The third and fourth arguments are function handles pointing to
functions that compute the equality constraints and the inequality
constraints, respectively.

If your problem does not have equality (or inequality) constraints,
you may pass an empty matrix for @var{cef} (or @var{cif}).

If supplied, the equality and inequality constraint functions must be
of the form

@example
     r = f (x)
@end example

@noindent
in which @var{x} is a vector and @var{r} is a vector.

The third and fourth arguments may also be 2-element cell arrays of
function handles.  The first element should point to the constraint
function and the second should point to a function that computes the
gradient of the constraint function:

@iftex
@tex
$$
 \Bigg( {\partial f(x) \over \partial x_1}, 
        {\partial f(x) \over \partial x_2}, \ldots,
        {\partial f(x) \over \partial x_N} \Bigg)^T
$$
@end tex
@end iftex
@ifnottex
@example
                [ d f(x)   d f(x)        d f(x) ]
    transpose ( [ ------   -----   ...   ------ ] )
                [  dx_1     dx_2          dx_N  ]
@end example
@end ifnottex

Here is an example of calling @code{sqp}:

@example
     function r = g (x)
       r = [ sumsq(x)-10; x(2)*x(3)-5*x(4)*x(5); x(1)^3+x(2)^3+1];
     endfunction

     function obj = phi (x)
       obj = exp(prod(x)) - 0.5*(x(1)^3+x(2)^3+1)^2;
     endfunction

     x0 = [-1.8; 1.7; 1.9; -0.8; -0.8];

     [x, obj, info, iter, nf, lambda] = sqp (x0, @@phi, @@g, [])

     x =
     
       -1.71714
        1.59571
        1.82725
       -0.76364
       -0.76364
     
     obj = 0.053950
     info = 101
     iter = 8
     nf = 10
     lambda =
     
       -0.0401627
        0.0379578
       -0.0052227
@end example

The value returned in @var{info} may be one of the following:
@table @asis
@item 101
The algorithm terminated because the norm of the last step was less
than @code{tol * norm (x))} (the value of tol is currently fixed at
@code{sqrt (eps)}---edit @file{sqp.m} to modify this value.
@item 102
The BFGS update failed.
@item 103
The maximum number of iterations was reached (the maximum number of
allowed iterations is currently fixed at 100---edit @file{sqp.m} to
increase this value).
@end table
@seealso{qp}
@end deftypefn


@node Linear Least Squares
@section Linear Least Squares

Octave also supports linear least squares minimization.  That is,
Octave can find the parameter @math{b} such that the model
@iftex
@tex
$y = xb$
@end tex
@end iftex
@ifnottex
@math{y = x*b}
@end ifnottex
fits data @math{(x,y)} as good as possible, assuming zero-mean
Gaussian noise.  If the noise is assumed to be isotropic the problem
can be solved using the @samp{\} or @samp{/} operators, or the @code{ols}
function.  In the general case where the noise is assumed to be anisotropic
the @code{gls} is needed.

@anchor{doc-ols}
@deftypefn {Function File} {[@var{beta}, @var{sigma}, @var{r}] =} ols (@var{y}, @var{x})
Ordinary least squares estimation for the multivariate model
@iftex
@tex
$y = x b + e$
with
$\bar{e} = 0$, and cov(vec($e$)) = kron ($s, I$)
@end tex
@end iftex
@ifinfo
@math{y = x b + e} with
@math{mean (e) = 0} and @math{cov (vec (e)) = kron (s, I)}.
@end ifinfo
 where
@iftex
@tex
$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix,
$b$ is a $k \times p$ matrix, and $e$ is a $t \times p$ matrix.
@end tex
@end iftex
@ifinfo
@math{y} is a @math{t} by @math{p} matrix, @math{x} is a @math{t} by
@math{k} matrix, @math{b} is a @math{k} by @math{p} matrix, and
@math{e} is a @math{t} by @math{p} matrix.
@end ifinfo

Each row of @var{y} and @var{x} is an observation and each column a
variable.

The return values @var{beta}, @var{sigma}, and @var{r} are defined as
follows.

@table @var
@item beta
The OLS estimator for @var{b}, @code{@var{beta} = pinv (@var{x}) *
@var{y}}, where @code{pinv (@var{x})} denotes the pseudoinverse of
@var{x}.

@item sigma
The OLS estimator for the matrix @var{s},

@example
@group
@var{sigma} = (@var{y}-@var{x}*@var{beta})'
  * (@var{y}-@var{x}*@var{beta})
  / (@var{t}-rank(@var{x}))
@end group
@end example

@item r
The matrix of OLS residuals, @code{@var{r} = @var{y} - @var{x} *
@var{beta}}.
@end table
@end deftypefn


@anchor{doc-gls}
@deftypefn {Function File} {[@var{beta}, @var{v}, @var{r}] =} gls (@var{y}, @var{x}, @var{o})
Generalized least squares estimation for the multivariate model
@iftex
@tex
$y = x b + e$
with $\bar{e} = 0$ and cov(vec($e$)) = $(s^2)o$,
@end tex
@end iftex
@ifinfo
@math{y = x b + e} with @math{mean (e) = 0} and
@math{cov (vec (e)) = (s^2) o},
@end ifinfo
 where
@iftex
@tex
$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix, $b$ is a $k
\times p$ matrix, $e$ is a $t \times p$ matrix, and $o$ is a $tp \times
tp$ matrix.
@end tex
@end iftex
@ifinfo
@math{y} is a @math{t} by @math{p} matrix, @math{x} is a @math{t} by
@math{k} matrix, @math{b} is a @math{k} by @math{p} matrix, @math{e}
is a @math{t} by @math{p} matrix, and @math{o} is a @math{t p} by
@math{t p} matrix.
@end ifinfo

@noindent
Each row of @var{y} and @var{x} is an observation and each column a
variable.  The return values @var{beta}, @var{v}, and @var{r} are
defined as follows.

@table @var
@item beta
The GLS estimator for @math{b}.

@item v
The GLS estimator for @math{s^2}.

@item r
The matrix of GLS residuals, @math{r = y - x beta}.
@end table
@end deftypefn


