parameters: (F, x0, jacobian='krylov', iter=None, verbose=False,
                   maxiter=None, f_tol=None, f_rtol=None, x_tol=None, x_rtol=None,
                   tol_norm=None, line_search='armijo', callback=None,
                   full_output=False, raise_exception=True)
docstring: Find a root of a function, in a way suitable for large-scale problems.
  
      Parameters
      ----------
      %(params_basic)s
      jacobian : Jacobian
          A Jacobian approximation: `Jacobian` object or something that
          `asjacobian` can transform to one. Alternatively, a string specifying
          which of the builtin Jacobian approximations to use:
  
              krylov, broyden1, broyden2, anderson
              diagbroyden, linearmixing, excitingmixing
  
      %(params_extra)s
      full_output : bool
          If true, returns a dictionary `info` containing convergence
          information.
      raise_exception : bool
          If True, a `NoConvergence` exception is raise if no solution is found.
  
      See Also
      --------
      asjacobian, Jacobian
  
      Notes
      -----
      This algorithm implements the inexact Newton method, with
      backtracking or full line searches. Several Jacobian
      approximations are available, including Krylov and Quasi-Newton
      methods.
  
      References
      ----------
      .. [KIM] C. T. Kelley, \"Iterative Methods for Linear and Nonlinear
         Equations\". Society for Industrial and Applied Mathematics. (1995)
         http://www.siam.org/books/kelley/
docstring_summary: Find a root of a function, in a way suitable for large-scale problems.
docstring_tokens: Find a root of a function in a way suitable for large - scale problems .
function: def nonlin_solve(F, x0, jacobian='krylov', iter=None, verbose=False,
                   maxiter=None, f_tol=None, f_rtol=None, x_tol=None, x_rtol=None,
                   tol_norm=None, line_search='armijo', callback=None,
                   full_output=False, raise_exception=True):
      """
      Find a root of a function, in a way suitable for large-scale problems.
  
      Parameters
      ----------
      %(params_basic)s
      jacobian : Jacobian
          A Jacobian approximation: `Jacobian` object or something that
          `asjacobian` can transform to one. Alternatively, a string specifying
          which of the builtin Jacobian approximations to use:
  
              krylov, broyden1, broyden2, anderson
              diagbroyden, linearmixing, excitingmixing
  
      %(params_extra)s
      full_output : bool
          If true, returns a dictionary `info` containing convergence
          information.
      raise_exception : bool
          If True, a `NoConvergence` exception is raise if no solution is found.
  
      See Also
      --------
      asjacobian, Jacobian
  
      Notes
      -----
      This algorithm implements the inexact Newton method, with
      backtracking or full line searches. Several Jacobian
      approximations are available, including Krylov and Quasi-Newton
      methods.
  
      References
      ----------
      .. [KIM] C. T. Kelley, \"Iterative Methods for Linear and Nonlinear
         Equations\". Society for Industrial and Applied Mathematics. (1995)
         http://www.siam.org/books/kelley/
  
      """
  
      condition = TerminationCondition(f_tol=f_tol, f_rtol=f_rtol,
                                       x_tol=x_tol, x_rtol=x_rtol,
                                       iter=iter, norm=tol_norm)
  
      x0 = _as_inexact(x0)
      func = lambda z: _as_inexact(F(_array_like(z, x0))).flatten()
      x = x0.flatten()
  
      dx = np.inf
      Fx = func(x)
      Fx_norm = norm(Fx)
  
      jacobian = asjacobian(jacobian)
      jacobian.setup(x.copy(), Fx, func)
  
      if maxiter is None:
          if iter is not None:
              maxiter = iter + 1
          else:
              maxiter = 100*(x.size+1)
  
      if line_search is True:
          line_search = 'armijo'
      elif line_search is False:
          line_search = None
  
      if line_search not in (None, 'armijo', 'wolfe'):
          raise ValueError("Invalid line search")
  
      # Solver tolerance selection
      gamma = 0.9
      eta_max = 0.9999
      eta_treshold = 0.1
      eta = 1e-3
  
      for n in xrange(maxiter):
          status = condition.check(Fx, x, dx)
          if status:
              break
  
          # The tolerance, as computed for scipy.sparse.linalg.* routines
          tol = min(eta, eta*Fx_norm)
          dx = -jacobian.solve(Fx, tol=tol)
  
          if norm(dx) == 0:
              raise ValueError("Jacobian inversion yielded zero vector. "
                               "This indicates a bug in the Jacobian "
                               "approximation.")
  
          # Line search, or Newton step
          if line_search:
              s, x, Fx, Fx_norm_new = _nonlin_line_search(func, x, Fx, dx,
                                                          line_search)
          else:
              s = 1.0
              x = x + dx
              Fx = func(x)
              Fx_norm_new = norm(Fx)
  
          jacobian.update(x.copy(), Fx)
  
          if callback:
              callback(x, Fx)
  
          # Adjust forcing parameters for inexact methods
          eta_A = gamma * Fx_norm_new**2 / Fx_norm**2
          if gamma * eta**2 < eta_treshold:
              eta = min(eta_max, eta_A)
          else:
              eta = min(eta_max, max(eta_A, gamma*eta**2))
  
          Fx_norm = Fx_norm_new
  
          # Print status
          if verbose:
              sys.stdout.write("%d:  |F(x)| = %g; step %g; tol %g\n" % (
                  n, norm(Fx), s, eta))
              sys.stdout.flush()
      else:
          if raise_exception:
              raise NoConvergence(_array_like(x, x0))
          else:
              status = 2
  
      if full_output:
          info = {'nit': condition.iteration,
                  'fun': Fx,
                  'status': status,
                  'success': status == 1,
                  'message': {1: 'A solution was found at the specified '
                                 'tolerance.',
                              2: 'The maximum number of iterations allowed '
                                 'has been reached.'
                              }[status]
                  }
          return _array_like(x, x0), info
      else:
          return _array_like(x, x0)
function_tokens: def nonlin_solve ( F , x0 , jacobian = 'krylov' , iter = None , verbose = False , maxiter = None , f_tol = None , f_rtol = None , x_tol = None , x_rtol = None , tol_norm = None , line_search = 'armijo' , callback = None , full_output = False , raise_exception = True ) : condition = TerminationCondition ( f_tol = f_tol , f_rtol = f_rtol , x_tol = x_tol , x_rtol = x_rtol , iter = iter , norm = tol_norm ) x0 = _as_inexact ( x0 ) func = lambda z : _as_inexact ( F ( _array_like ( z , x0 ) ) ) . flatten ( ) x = x0 . flatten ( ) dx = np . inf Fx = func ( x ) Fx_norm = norm ( Fx ) jacobian = asjacobian ( jacobian ) jacobian . setup ( x . copy ( ) , Fx , func ) if maxiter is None : if iter is not None : maxiter = iter + 1 else : maxiter = 100 * ( x . size + 1 ) if line_search is True : line_search = 'armijo' elif line_search is False : line_search = None if line_search not in ( None , 'armijo' , 'wolfe' ) : raise ValueError ( "Invalid line search" ) # Solver tolerance selection gamma = 0.9 eta_max = 0.9999 eta_treshold = 0.1 eta = 1e-3 for n in xrange ( maxiter ) : status = condition . check ( Fx , x , dx ) if status : break # The tolerance, as computed for scipy.sparse.linalg.* routines tol = min ( eta , eta * Fx_norm ) dx = - jacobian . solve ( Fx , tol = tol ) if norm ( dx ) == 0 : raise ValueError ( "Jacobian inversion yielded zero vector. " "This indicates a bug in the Jacobian " "approximation." ) # Line search, or Newton step if line_search : s , x , Fx , Fx_norm_new = _nonlin_line_search ( func , x , Fx , dx , line_search ) else : s = 1.0 x = x + dx Fx = func ( x ) Fx_norm_new = norm ( Fx ) jacobian . update ( x . copy ( ) , Fx ) if callback : callback ( x , Fx ) # Adjust forcing parameters for inexact methods eta_A = gamma * Fx_norm_new ** 2 / Fx_norm ** 2 if gamma * eta ** 2 < eta_treshold : eta = min ( eta_max , eta_A ) else : eta = min ( eta_max , max ( eta_A , gamma * eta ** 2 ) ) Fx_norm = Fx_norm_new # Print status if verbose : sys . stdout . write ( "%d:  |F(x)| = %g; step %g; tol %g\n" % ( n , norm ( Fx ) , s , eta ) ) sys . stdout . flush ( ) else : if raise_exception : raise NoConvergence ( _array_like ( x , x0 ) ) else : status = 2 if full_output : info = { 'nit' : condition . iteration , 'fun' : Fx , 'status' : status , 'success' : status == 1 , 'message' : { 1 : 'A solution was found at the specified ' 'tolerance.' , 2 : 'The maximum number of iterations allowed ' 'has been reached.' } [ status ] } return _array_like ( x , x0 ) , info else : return _array_like ( x , x0 )