% -*- texinfo -*-
% @deftypefn {Function File} {[@var{x}, @var{obj}, @var{info}, @var{iter}, @var{nf}, @var{lambda}] =} sqp (@var{x}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}, @var{maxiter}, @var{tolerance})
% Solve the nonlinear program
% @tex
% $$
% \min_x \phi (x)
% $$
% @end tex
% @ifnottex
%
% @example
% @group
% min phi (x)
% x
% @end group
% @end example
%
% @end ifnottex
% subject to
% @tex
% $$
% g(x) = 0 \qquad h(x) \geq 0 \qquad lb \leq x \leq ub
% $$
% @end tex
% @ifnottex
%
% @example
% @group
% g(x) = 0
% h(x) >= 0
% lb <= x <= ub
% @end group
% @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:
%
% @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
% @ifnottex
% @example
% @group
% [ d f(x) d f(x) d f(x) ]
% transpose ( [ ------ ----- ... ------ ] )
% [ dx_1 dx_2 dx_N ]
% @end group
% @end example
% @end ifnottex
%
% The fifth and sixth arguments are vectors containing lower and upper bounds
% on @var{x}. These must be consistent with equality and inequality
% constraints @var{g} and @var{h}. If the bounds are not specified, or are
% empty, they are set to -@var{realmax} and @var{realmax} by default.
%
% The seventh argument is max. number of iterations. If not specified,
% the default value is 100.
%
% The eighth argument is tolerance for stopping criteria. If not specified,
% the default value is @var{eps}.
%
% 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 ];
%
%
% function obj = phi (x)
% obj = exp(prod(x)) - 0.5*(x(1)^3+x(2)^3+1)^2;
%
%
% 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