Welcome to BCLS!

[x, g, info] = bcls( A, b, bl, bu, x, c, damp, options )

or

[x, g, info] = bcls( Aprod, b, bl, bu, x, c, damp, options )

Solves the bound-constrained linear least-squares problem

  minimize   || ( A    )     (b) ||
             || (      ) x - ( ) ||  +  c'x  s.t.  bl <= x <= bu,
     x       || (damp I)     (0) ||

where

A        is an  m x n  dense or sparse matrix.

Aprod    is a function with the prototype

         [r] = Aprod( mode, ix, z )

         where  r = y + A(:,ix) * z(ix)  if  mode == 1
         and    r = x + A' * z           if  mode == 2.

         Here, ix is a vector that holds a subset of indices of
         1:n.  In the case where mode == 2, only the components of
         r(ix) will be used; the other components will be ignored.

b        is the RHS vector (length m).

bl, bu   (optional) are n-vectors of lower and upper bounds on
         x .  If these are empty or missing, then they will be
         substitued with -inf and +inf, respectively.

x        (optional) is an n-vector that gives an estimate of the
         solution.  If x is empty or missing, then x = 0 is the
         default.

c        (optional) is an n-vector that defines the linear term.
         If c is empty or missing, then c = 0 is the default.

damp     (optional) is a scalar regularization term.  If damp is
         empty or missing, then damp = 0 is used.

options  (optional) is a structure with optional parameters that
          control the bcls algorithm.  The special call

         [options] = bcls();

         returns an empty structure with valid option fields:

         .n                number of columns in A
         .print_level      0 = (none) ... = 6 (most)
         .proj_search      0 = first exact min along projected path
                               (default)
                           1 = projected backtrack
         .newton_step      0 = LSQR (default), 1 = CGLS
         .opt_tol          default is 1e-6
         .major_itns       default is  5 * n
         .minor_itns       default is 10 * n
         .Usolve           function handle to preconditioning routine.

 The (optional) preconditioning routine Usolve must have the prototype

         z = Usolve( mode, ix, q )

 where   z  solves  U z = q  if  mode == 1
 and     z  solves  U'z = q  if  mode == 2.

As is the case with Aprod, ix is a vector that holds a subset of
"participating" indices in 1:n.


OUTPUTS

x        is a solution (if all went well!).

g        is the gradient of the objective at x.

info     is a structure that describes the status of the BCLS solve,
         and has fields

         .dInf             the largest gradient among the free vars
         .jInf             the variable index with the largest gradient
         .major_itns       number of major iterations
         .minor_itns       total number of minor (CG) iterations
         .exit             exit status
                           0 = converged
                           1 = too many major iterations
                           2 = too many minor iterations
                           3 = undefined exit (bug?)
                           4 = exit with direction of inifinite descent
                           5 = bounds are inconsistent
                           6 = linesearch failure
                           These are exits requested by the user's routines:
                           100 = Aprod
                           110 = Usolve
         .message          string with BCLS's exit status
         .time             total solution time (seconds).
Matlab interface
