nsoli  Newton-Krylov solver, globally convergent solver for f(x) = 0.
 
  Inexact-Newton-Armijo iteration
 
  Eisenstat-Walker forcing term
 
  Parabolic line search via three point interpolation.
 
  C. T. Kelley, April 27, 2001
 
  This code comes with no guarantee or warranty of any kind.
 
  This is a modification by Christophe Gouel of the original file, which can be
  downloaded from:
  http://www4.ncsu.edu/~ctk/newtony.html
  The changes are surrounded above and below by "%% Change CG" % and "%%". They
  only concern the way of handling inputs (particularly options).
 
  INPUT
         function = f
         initial iterate = x
         options = structure whose fields are
                     atol : absolute error tolerances for the nonlinear
                            iteration (default = sqrt(eps))
                     rtol : absolute error tolerances for the nonlinear
                            iteration (default = sqrt(eps))
                     maxit : maximum number of nonlinear iterations (default = 40)
                     lmaxit : maximum number of inner iterations before restart. In
                              GMRES(m), m = maxitl. For iterative methods other
                              than GMRES(m) maxitl is the upper bound on linear
                              iterations (default = 40).
                     showiters : display iteration (default = 0)
                     etamax : Maximum error tolerance for residual in inner
                              iteration. The inner iteration terminates when the
                              relative linear residual is smaller than
                              eta*|F(x_c)|. eta is determined by the modified
                              Eisenstat-Walker formula if etamax > 0.  If etamax <
                              0, then eta = |etamax| for the entire
                              iteration. (default = .9)
                     lmeth : choice of linear iterative method
                             1 (GMRES), 2 GMRES(m),
                             3 (BICGSTAB), 4 (TFQMR)
                             (default = 1 (GMRES, no restarts))
                     restart_limit : max number of restarts for GMRES if lmeth = 2
                                     (default = 20)
 
  OUTPUT
         sol = solution
         it_hist(maxit,3) = l2 norms of nonlinear residuals
             for the iteration, number of function evaluations,
             and number of steplength reductions
         ierr = 0 upon successful termination
         ierr = 1 if after maxit iterations
              the termination criterion is not satsified
         ierr = 2 failure in the line search. The iteration
              is terminated if too many steplength reductions
              are taken.
 
     x_hist = matrix of the entire interation history.
              The columns are the nonlinear iterates. This
              is useful for making movies, for example, but
              can consume way too much storage. This is an
              OPTIONAL argument. Storage is only allocated
              if x_hist is in the output argument list.
 
 
 
  internal parameters:
        alpha = 1.d-4, parameter to measure sufficient decrease
 
        sigma0 = .1, sigma1 = .5, safeguarding bounds for the linesearch
 
        maxarm = 20, maximum number of steplength reductions before
                     failure is reported