| """ |
| Unified interfaces to root finding algorithms. |
| |
| Functions |
| --------- |
| - root : find a root of a vector function. |
| """ |
| __all__ = ['root'] |
|
|
| import numpy as np |
|
|
| from warnings import warn |
|
|
| from ._optimize import MemoizeJac, OptimizeResult, _check_unknown_options |
| from ._minpack_py import _root_hybr, leastsq |
| from ._spectral import _root_df_sane |
| from . import _nonlin as nonlin |
|
|
|
|
| ROOT_METHODS = ['hybr', 'lm', 'broyden1', 'broyden2', 'anderson', |
| 'linearmixing', 'diagbroyden', 'excitingmixing', 'krylov', |
| 'df-sane'] |
|
|
|
|
| def root(fun, x0, args=(), method='hybr', jac=None, tol=None, callback=None, |
| options=None): |
| r""" |
| Find a root of a vector function. |
| |
| Parameters |
| ---------- |
| fun : callable |
| A vector function to find a root of. |
| x0 : ndarray |
| Initial guess. |
| args : tuple, optional |
| Extra arguments passed to the objective function and its Jacobian. |
| method : str, optional |
| Type of solver. Should be one of |
| |
| - 'hybr' :ref:`(see here) <optimize.root-hybr>` |
| - 'lm' :ref:`(see here) <optimize.root-lm>` |
| - 'broyden1' :ref:`(see here) <optimize.root-broyden1>` |
| - 'broyden2' :ref:`(see here) <optimize.root-broyden2>` |
| - 'anderson' :ref:`(see here) <optimize.root-anderson>` |
| - 'linearmixing' :ref:`(see here) <optimize.root-linearmixing>` |
| - 'diagbroyden' :ref:`(see here) <optimize.root-diagbroyden>` |
| - 'excitingmixing' :ref:`(see here) <optimize.root-excitingmixing>` |
| - 'krylov' :ref:`(see here) <optimize.root-krylov>` |
| - 'df-sane' :ref:`(see here) <optimize.root-dfsane>` |
| |
| jac : bool or callable, optional |
| If `jac` is a Boolean and is True, `fun` is assumed to return the |
| value of Jacobian along with the objective function. If False, the |
| Jacobian will be estimated numerically. |
| `jac` can also be a callable returning the Jacobian of `fun`. In |
| this case, it must accept the same arguments as `fun`. |
| tol : float, optional |
| Tolerance for termination. For detailed control, use solver-specific |
| options. |
| callback : function, optional |
| Optional callback function. It is called on every iteration as |
| ``callback(x, f)`` where `x` is the current solution and `f` |
| the corresponding residual. For all methods but 'hybr' and 'lm'. |
| options : dict, optional |
| A dictionary of solver options. E.g., `xtol` or `maxiter`, see |
| :obj:`show_options()` for details. |
| |
| Returns |
| ------- |
| sol : OptimizeResult |
| The solution represented as a ``OptimizeResult`` object. |
| Important attributes are: ``x`` the solution array, ``success`` a |
| Boolean flag indicating if the algorithm exited successfully and |
| ``message`` which describes the cause of the termination. See |
| `OptimizeResult` for a description of other attributes. |
| |
| See also |
| -------- |
| show_options : Additional options accepted by the solvers |
| |
| Notes |
| ----- |
| This section describes the available solvers that can be selected by the |
| 'method' parameter. The default method is *hybr*. |
| |
| Method *hybr* uses a modification of the Powell hybrid method as |
| implemented in MINPACK [1]_. |
| |
| Method *lm* solves the system of nonlinear equations in a least squares |
| sense using a modification of the Levenberg-Marquardt algorithm as |
| implemented in MINPACK [1]_. |
| |
| Method *df-sane* is a derivative-free spectral method. [3]_ |
| |
| Methods *broyden1*, *broyden2*, *anderson*, *linearmixing*, |
| *diagbroyden*, *excitingmixing*, *krylov* are inexact Newton methods, |
| with backtracking or full line searches [2]_. Each method corresponds |
| to a particular Jacobian approximations. |
| |
| - Method *broyden1* uses Broyden's first Jacobian approximation, it is |
| known as Broyden's good method. |
| - Method *broyden2* uses Broyden's second Jacobian approximation, it |
| is known as Broyden's bad method. |
| - Method *anderson* uses (extended) Anderson mixing. |
| - Method *Krylov* uses Krylov approximation for inverse Jacobian. It |
| is suitable for large-scale problem. |
| - Method *diagbroyden* uses diagonal Broyden Jacobian approximation. |
| - Method *linearmixing* uses a scalar Jacobian approximation. |
| - Method *excitingmixing* uses a tuned diagonal Jacobian |
| approximation. |
| |
| .. warning:: |
| |
| The algorithms implemented for methods *diagbroyden*, |
| *linearmixing* and *excitingmixing* may be useful for specific |
| problems, but whether they will work may depend strongly on the |
| problem. |
| |
| .. versionadded:: 0.11.0 |
| |
| References |
| ---------- |
| .. [1] More, Jorge J., Burton S. Garbow, and Kenneth E. Hillstrom. |
| 1980. User Guide for MINPACK-1. |
| .. [2] C. T. Kelley. 1995. Iterative Methods for Linear and Nonlinear |
| Equations. Society for Industrial and Applied Mathematics. |
| <https://archive.siam.org/books/kelley/fr16/> |
| .. [3] W. La Cruz, J.M. Martinez, M. Raydan. Math. Comp. 75, 1429 (2006). |
| |
| Examples |
| -------- |
| The following functions define a system of nonlinear equations and its |
| jacobian. |
| |
| >>> import numpy as np |
| >>> def fun(x): |
| ... return [x[0] + 0.5 * (x[0] - x[1])**3 - 1.0, |
| ... 0.5 * (x[1] - x[0])**3 + x[1]] |
| |
| >>> def jac(x): |
| ... return np.array([[1 + 1.5 * (x[0] - x[1])**2, |
| ... -1.5 * (x[0] - x[1])**2], |
| ... [-1.5 * (x[1] - x[0])**2, |
| ... 1 + 1.5 * (x[1] - x[0])**2]]) |
| |
| A solution can be obtained as follows. |
| |
| >>> from scipy import optimize |
| >>> sol = optimize.root(fun, [0, 0], jac=jac, method='hybr') |
| >>> sol.x |
| array([ 0.8411639, 0.1588361]) |
| |
| **Large problem** |
| |
| Suppose that we needed to solve the following integrodifferential |
| equation on the square :math:`[0,1]\times[0,1]`: |
| |
| .. math:: |
| |
| \nabla^2 P = 10 \left(\int_0^1\int_0^1\cosh(P)\,dx\,dy\right)^2 |
| |
| with :math:`P(x,1) = 1` and :math:`P=0` elsewhere on the boundary of |
| the square. |
| |
| The solution can be found using the ``method='krylov'`` solver: |
| |
| >>> from scipy import optimize |
| >>> # parameters |
| >>> nx, ny = 75, 75 |
| >>> hx, hy = 1./(nx-1), 1./(ny-1) |
| |
| >>> P_left, P_right = 0, 0 |
| >>> P_top, P_bottom = 1, 0 |
| |
| >>> def residual(P): |
| ... d2x = np.zeros_like(P) |
| ... d2y = np.zeros_like(P) |
| ... |
| ... d2x[1:-1] = (P[2:] - 2*P[1:-1] + P[:-2]) / hx/hx |
| ... d2x[0] = (P[1] - 2*P[0] + P_left)/hx/hx |
| ... d2x[-1] = (P_right - 2*P[-1] + P[-2])/hx/hx |
| ... |
| ... d2y[:,1:-1] = (P[:,2:] - 2*P[:,1:-1] + P[:,:-2])/hy/hy |
| ... d2y[:,0] = (P[:,1] - 2*P[:,0] + P_bottom)/hy/hy |
| ... d2y[:,-1] = (P_top - 2*P[:,-1] + P[:,-2])/hy/hy |
| ... |
| ... return d2x + d2y - 10*np.cosh(P).mean()**2 |
| |
| >>> guess = np.zeros((nx, ny), float) |
| >>> sol = optimize.root(residual, guess, method='krylov') |
| >>> print('Residual: %g' % abs(residual(sol.x)).max()) |
| Residual: 5.7972e-06 # may vary |
| |
| >>> import matplotlib.pyplot as plt |
| >>> x, y = np.mgrid[0:1:(nx*1j), 0:1:(ny*1j)] |
| >>> plt.pcolormesh(x, y, sol.x, shading='gouraud') |
| >>> plt.colorbar() |
| >>> plt.show() |
| |
| """ |
| if not isinstance(args, tuple): |
| args = (args,) |
|
|
| meth = method.lower() |
| if options is None: |
| options = {} |
|
|
| if callback is not None and meth in ('hybr', 'lm'): |
| warn('Method %s does not accept callback.' % method, |
| RuntimeWarning, stacklevel=2) |
|
|
| |
| if not callable(jac) and meth in ('hybr', 'lm'): |
| if bool(jac): |
| fun = MemoizeJac(fun) |
| jac = fun.derivative |
| else: |
| jac = None |
|
|
| |
| if tol is not None: |
| options = dict(options) |
| if meth in ('hybr', 'lm'): |
| options.setdefault('xtol', tol) |
| elif meth in ('df-sane',): |
| options.setdefault('ftol', tol) |
| elif meth in ('broyden1', 'broyden2', 'anderson', 'linearmixing', |
| 'diagbroyden', 'excitingmixing', 'krylov'): |
| options.setdefault('xtol', tol) |
| options.setdefault('xatol', np.inf) |
| options.setdefault('ftol', np.inf) |
| options.setdefault('fatol', np.inf) |
|
|
| if meth == 'hybr': |
| sol = _root_hybr(fun, x0, args=args, jac=jac, **options) |
| elif meth == 'lm': |
| sol = _root_leastsq(fun, x0, args=args, jac=jac, **options) |
| elif meth == 'df-sane': |
| _warn_jac_unused(jac, method) |
| sol = _root_df_sane(fun, x0, args=args, callback=callback, |
| **options) |
| elif meth in ('broyden1', 'broyden2', 'anderson', 'linearmixing', |
| 'diagbroyden', 'excitingmixing', 'krylov'): |
| _warn_jac_unused(jac, method) |
| sol = _root_nonlin_solve(fun, x0, args=args, jac=jac, |
| _method=meth, _callback=callback, |
| **options) |
| else: |
| raise ValueError('Unknown solver %s' % method) |
|
|
| return sol |
|
|
|
|
| def _warn_jac_unused(jac, method): |
| if jac is not None: |
| warn(f'Method {method} does not use the jacobian (jac).', |
| RuntimeWarning, stacklevel=2) |
|
|
|
|
| def _root_leastsq(fun, x0, args=(), jac=None, |
| col_deriv=0, xtol=1.49012e-08, ftol=1.49012e-08, |
| gtol=0.0, maxiter=0, eps=0.0, factor=100, diag=None, |
| **unknown_options): |
| """ |
| Solve for least squares with Levenberg-Marquardt |
| |
| Options |
| ------- |
| col_deriv : bool |
| non-zero to specify that the Jacobian function computes derivatives |
| down the columns (faster, because there is no transpose operation). |
| ftol : float |
| Relative error desired in the sum of squares. |
| xtol : float |
| Relative error desired in the approximate solution. |
| gtol : float |
| Orthogonality desired between the function vector and the columns |
| of the Jacobian. |
| maxiter : int |
| The maximum number of calls to the function. If zero, then |
| 100*(N+1) is the maximum where N is the number of elements in x0. |
| epsfcn : float |
| A suitable step length for the forward-difference approximation of |
| the Jacobian (for Dfun=None). If epsfcn is less than the machine |
| precision, it is assumed that the relative errors in the functions |
| are of the order of the machine precision. |
| factor : float |
| A parameter determining the initial step bound |
| (``factor * || diag * x||``). Should be in interval ``(0.1, 100)``. |
| diag : sequence |
| N positive entries that serve as a scale factors for the variables. |
| """ |
|
|
| _check_unknown_options(unknown_options) |
| x, cov_x, info, msg, ier = leastsq(fun, x0, args=args, Dfun=jac, |
| full_output=True, |
| col_deriv=col_deriv, xtol=xtol, |
| ftol=ftol, gtol=gtol, |
| maxfev=maxiter, epsfcn=eps, |
| factor=factor, diag=diag) |
| sol = OptimizeResult(x=x, message=msg, status=ier, |
| success=ier in (1, 2, 3, 4), cov_x=cov_x, |
| fun=info.pop('fvec'), method="lm") |
| sol.update(info) |
| return sol |
|
|
|
|
| def _root_nonlin_solve(fun, x0, args=(), jac=None, |
| _callback=None, _method=None, |
| nit=None, disp=False, maxiter=None, |
| ftol=None, fatol=None, xtol=None, xatol=None, |
| tol_norm=None, line_search='armijo', jac_options=None, |
| **unknown_options): |
| _check_unknown_options(unknown_options) |
|
|
| f_tol = fatol |
| f_rtol = ftol |
| x_tol = xatol |
| x_rtol = xtol |
| verbose = disp |
| if jac_options is None: |
| jac_options = dict() |
|
|
| jacobian = {'broyden1': nonlin.BroydenFirst, |
| 'broyden2': nonlin.BroydenSecond, |
| 'anderson': nonlin.Anderson, |
| 'linearmixing': nonlin.LinearMixing, |
| 'diagbroyden': nonlin.DiagBroyden, |
| 'excitingmixing': nonlin.ExcitingMixing, |
| 'krylov': nonlin.KrylovJacobian |
| }[_method] |
|
|
| if args: |
| if jac is True: |
| def f(x): |
| return fun(x, *args)[0] |
| else: |
| def f(x): |
| return fun(x, *args) |
| else: |
| f = fun |
|
|
| x, info = nonlin.nonlin_solve(f, x0, jacobian=jacobian(**jac_options), |
| iter=nit, verbose=verbose, |
| maxiter=maxiter, f_tol=f_tol, |
| f_rtol=f_rtol, x_tol=x_tol, |
| x_rtol=x_rtol, tol_norm=tol_norm, |
| line_search=line_search, |
| callback=_callback, full_output=True, |
| raise_exception=False) |
| sol = OptimizeResult(x=x, method=_method) |
| sol.update(info) |
| return sol |
|
|
| def _root_broyden1_doc(): |
| """ |
| Options |
| ------- |
| nit : int, optional |
| Number of iterations to make. If omitted (default), make as many |
| as required to meet tolerances. |
| disp : bool, optional |
| Print status to stdout on every iteration. |
| maxiter : int, optional |
| Maximum number of iterations to make. If more are needed to |
| meet convergence, `NoConvergence` is raised. |
| ftol : float, optional |
| Relative tolerance for the residual. If omitted, not used. |
| fatol : float, optional |
| Absolute tolerance (in max-norm) for the residual. |
| If omitted, default is 6e-6. |
| xtol : float, optional |
| Relative minimum step size. If omitted, not used. |
| xatol : float, optional |
| Absolute minimum step size, as determined from the Jacobian |
| approximation. If the step size is smaller than this, optimization |
| is terminated as successful. If omitted, not used. |
| tol_norm : function(vector) -> scalar, optional |
| Norm to use in convergence check. Default is the maximum norm. |
| line_search : {None, 'armijo' (default), 'wolfe'}, optional |
| Which type of a line search to use to determine the step size in |
| the direction given by the Jacobian approximation. Defaults to |
| 'armijo'. |
| jac_options : dict, optional |
| Options for the respective Jacobian approximation. |
| alpha : float, optional |
| Initial guess for the Jacobian is (-1/alpha). |
| reduction_method : str or tuple, optional |
| Method used in ensuring that the rank of the Broyden |
| matrix stays low. Can either be a string giving the |
| name of the method, or a tuple of the form ``(method, |
| param1, param2, ...)`` that gives the name of the |
| method and values for additional parameters. |
| |
| Methods available: |
| |
| - ``restart`` |
| Drop all matrix columns. Has no |
| extra parameters. |
| - ``simple`` |
| Drop oldest matrix column. Has no |
| extra parameters. |
| - ``svd`` |
| Keep only the most significant SVD |
| components. |
| |
| Extra parameters: |
| |
| - ``to_retain`` |
| Number of SVD components to |
| retain when rank reduction is done. |
| Default is ``max_rank - 2``. |
| max_rank : int, optional |
| Maximum rank for the Broyden matrix. |
| Default is infinity (i.e., no rank reduction). |
| |
| Examples |
| -------- |
| >>> def func(x): |
| ... return np.cos(x) + x[::-1] - [1, 2, 3, 4] |
| ... |
| >>> from scipy import optimize |
| >>> res = optimize.root(func, [1, 1, 1, 1], method='broyden1', tol=1e-14) |
| >>> x = res.x |
| >>> x |
| array([4.04674914, 3.91158389, 2.71791677, 1.61756251]) |
| >>> np.cos(x) + x[::-1] |
| array([1., 2., 3., 4.]) |
| |
| """ |
| pass |
|
|
| def _root_broyden2_doc(): |
| """ |
| Options |
| ------- |
| nit : int, optional |
| Number of iterations to make. If omitted (default), make as many |
| as required to meet tolerances. |
| disp : bool, optional |
| Print status to stdout on every iteration. |
| maxiter : int, optional |
| Maximum number of iterations to make. If more are needed to |
| meet convergence, `NoConvergence` is raised. |
| ftol : float, optional |
| Relative tolerance for the residual. If omitted, not used. |
| fatol : float, optional |
| Absolute tolerance (in max-norm) for the residual. |
| If omitted, default is 6e-6. |
| xtol : float, optional |
| Relative minimum step size. If omitted, not used. |
| xatol : float, optional |
| Absolute minimum step size, as determined from the Jacobian |
| approximation. If the step size is smaller than this, optimization |
| is terminated as successful. If omitted, not used. |
| tol_norm : function(vector) -> scalar, optional |
| Norm to use in convergence check. Default is the maximum norm. |
| line_search : {None, 'armijo' (default), 'wolfe'}, optional |
| Which type of a line search to use to determine the step size in |
| the direction given by the Jacobian approximation. Defaults to |
| 'armijo'. |
| jac_options : dict, optional |
| Options for the respective Jacobian approximation. |
| |
| alpha : float, optional |
| Initial guess for the Jacobian is (-1/alpha). |
| reduction_method : str or tuple, optional |
| Method used in ensuring that the rank of the Broyden |
| matrix stays low. Can either be a string giving the |
| name of the method, or a tuple of the form ``(method, |
| param1, param2, ...)`` that gives the name of the |
| method and values for additional parameters. |
| |
| Methods available: |
| |
| - ``restart`` |
| Drop all matrix columns. Has no |
| extra parameters. |
| - ``simple`` |
| Drop oldest matrix column. Has no |
| extra parameters. |
| - ``svd`` |
| Keep only the most significant SVD |
| components. |
| |
| Extra parameters: |
| |
| - ``to_retain`` |
| Number of SVD components to |
| retain when rank reduction is done. |
| Default is ``max_rank - 2``. |
| max_rank : int, optional |
| Maximum rank for the Broyden matrix. |
| Default is infinity (i.e., no rank reduction). |
| """ |
| pass |
|
|
| def _root_anderson_doc(): |
| """ |
| Options |
| ------- |
| nit : int, optional |
| Number of iterations to make. If omitted (default), make as many |
| as required to meet tolerances. |
| disp : bool, optional |
| Print status to stdout on every iteration. |
| maxiter : int, optional |
| Maximum number of iterations to make. If more are needed to |
| meet convergence, `NoConvergence` is raised. |
| ftol : float, optional |
| Relative tolerance for the residual. If omitted, not used. |
| fatol : float, optional |
| Absolute tolerance (in max-norm) for the residual. |
| If omitted, default is 6e-6. |
| xtol : float, optional |
| Relative minimum step size. If omitted, not used. |
| xatol : float, optional |
| Absolute minimum step size, as determined from the Jacobian |
| approximation. If the step size is smaller than this, optimization |
| is terminated as successful. If omitted, not used. |
| tol_norm : function(vector) -> scalar, optional |
| Norm to use in convergence check. Default is the maximum norm. |
| line_search : {None, 'armijo' (default), 'wolfe'}, optional |
| Which type of a line search to use to determine the step size in |
| the direction given by the Jacobian approximation. Defaults to |
| 'armijo'. |
| jac_options : dict, optional |
| Options for the respective Jacobian approximation. |
| |
| alpha : float, optional |
| Initial guess for the Jacobian is (-1/alpha). |
| M : float, optional |
| Number of previous vectors to retain. Defaults to 5. |
| w0 : float, optional |
| Regularization parameter for numerical stability. |
| Compared to unity, good values of the order of 0.01. |
| """ |
| pass |
|
|
| def _root_linearmixing_doc(): |
| """ |
| Options |
| ------- |
| nit : int, optional |
| Number of iterations to make. If omitted (default), make as many |
| as required to meet tolerances. |
| disp : bool, optional |
| Print status to stdout on every iteration. |
| maxiter : int, optional |
| Maximum number of iterations to make. If more are needed to |
| meet convergence, ``NoConvergence`` is raised. |
| ftol : float, optional |
| Relative tolerance for the residual. If omitted, not used. |
| fatol : float, optional |
| Absolute tolerance (in max-norm) for the residual. |
| If omitted, default is 6e-6. |
| xtol : float, optional |
| Relative minimum step size. If omitted, not used. |
| xatol : float, optional |
| Absolute minimum step size, as determined from the Jacobian |
| approximation. If the step size is smaller than this, optimization |
| is terminated as successful. If omitted, not used. |
| tol_norm : function(vector) -> scalar, optional |
| Norm to use in convergence check. Default is the maximum norm. |
| line_search : {None, 'armijo' (default), 'wolfe'}, optional |
| Which type of a line search to use to determine the step size in |
| the direction given by the Jacobian approximation. Defaults to |
| 'armijo'. |
| jac_options : dict, optional |
| Options for the respective Jacobian approximation. |
| |
| alpha : float, optional |
| initial guess for the jacobian is (-1/alpha). |
| """ |
| pass |
|
|
| def _root_diagbroyden_doc(): |
| """ |
| Options |
| ------- |
| nit : int, optional |
| Number of iterations to make. If omitted (default), make as many |
| as required to meet tolerances. |
| disp : bool, optional |
| Print status to stdout on every iteration. |
| maxiter : int, optional |
| Maximum number of iterations to make. If more are needed to |
| meet convergence, `NoConvergence` is raised. |
| ftol : float, optional |
| Relative tolerance for the residual. If omitted, not used. |
| fatol : float, optional |
| Absolute tolerance (in max-norm) for the residual. |
| If omitted, default is 6e-6. |
| xtol : float, optional |
| Relative minimum step size. If omitted, not used. |
| xatol : float, optional |
| Absolute minimum step size, as determined from the Jacobian |
| approximation. If the step size is smaller than this, optimization |
| is terminated as successful. If omitted, not used. |
| tol_norm : function(vector) -> scalar, optional |
| Norm to use in convergence check. Default is the maximum norm. |
| line_search : {None, 'armijo' (default), 'wolfe'}, optional |
| Which type of a line search to use to determine the step size in |
| the direction given by the Jacobian approximation. Defaults to |
| 'armijo'. |
| jac_options : dict, optional |
| Options for the respective Jacobian approximation. |
| |
| alpha : float, optional |
| initial guess for the jacobian is (-1/alpha). |
| """ |
| pass |
|
|
| def _root_excitingmixing_doc(): |
| """ |
| Options |
| ------- |
| nit : int, optional |
| Number of iterations to make. If omitted (default), make as many |
| as required to meet tolerances. |
| disp : bool, optional |
| Print status to stdout on every iteration. |
| maxiter : int, optional |
| Maximum number of iterations to make. If more are needed to |
| meet convergence, `NoConvergence` is raised. |
| ftol : float, optional |
| Relative tolerance for the residual. If omitted, not used. |
| fatol : float, optional |
| Absolute tolerance (in max-norm) for the residual. |
| If omitted, default is 6e-6. |
| xtol : float, optional |
| Relative minimum step size. If omitted, not used. |
| xatol : float, optional |
| Absolute minimum step size, as determined from the Jacobian |
| approximation. If the step size is smaller than this, optimization |
| is terminated as successful. If omitted, not used. |
| tol_norm : function(vector) -> scalar, optional |
| Norm to use in convergence check. Default is the maximum norm. |
| line_search : {None, 'armijo' (default), 'wolfe'}, optional |
| Which type of a line search to use to determine the step size in |
| the direction given by the Jacobian approximation. Defaults to |
| 'armijo'. |
| jac_options : dict, optional |
| Options for the respective Jacobian approximation. |
| |
| alpha : float, optional |
| Initial Jacobian approximation is (-1/alpha). |
| alphamax : float, optional |
| The entries of the diagonal Jacobian are kept in the range |
| ``[alpha, alphamax]``. |
| """ |
| pass |
|
|
| def _root_krylov_doc(): |
| """ |
| Options |
| ------- |
| nit : int, optional |
| Number of iterations to make. If omitted (default), make as many |
| as required to meet tolerances. |
| disp : bool, optional |
| Print status to stdout on every iteration. |
| maxiter : int, optional |
| Maximum number of iterations to make. If more are needed to |
| meet convergence, `NoConvergence` is raised. |
| ftol : float, optional |
| Relative tolerance for the residual. If omitted, not used. |
| fatol : float, optional |
| Absolute tolerance (in max-norm) for the residual. |
| If omitted, default is 6e-6. |
| xtol : float, optional |
| Relative minimum step size. If omitted, not used. |
| xatol : float, optional |
| Absolute minimum step size, as determined from the Jacobian |
| approximation. If the step size is smaller than this, optimization |
| is terminated as successful. If omitted, not used. |
| tol_norm : function(vector) -> scalar, optional |
| Norm to use in convergence check. Default is the maximum norm. |
| line_search : {None, 'armijo' (default), 'wolfe'}, optional |
| Which type of a line search to use to determine the step size in |
| the direction given by the Jacobian approximation. Defaults to |
| 'armijo'. |
| jac_options : dict, optional |
| Options for the respective Jacobian approximation. |
| |
| rdiff : float, optional |
| Relative step size to use in numerical differentiation. |
| method : str or callable, optional |
| Krylov method to use to approximate the Jacobian. Can be a string, |
| or a function implementing the same interface as the iterative |
| solvers in `scipy.sparse.linalg`. If a string, needs to be one of: |
| ``'lgmres'``, ``'gmres'``, ``'bicgstab'``, ``'cgs'``, ``'minres'``, |
| ``'tfqmr'``. |
| |
| The default is `scipy.sparse.linalg.lgmres`. |
| inner_M : LinearOperator or InverseJacobian |
| Preconditioner for the inner Krylov iteration. |
| Note that you can use also inverse Jacobians as (adaptive) |
| preconditioners. For example, |
| |
| >>> jac = BroydenFirst() |
| >>> kjac = KrylovJacobian(inner_M=jac.inverse). |
| |
| If the preconditioner has a method named 'update', it will |
| be called as ``update(x, f)`` after each nonlinear step, |
| with ``x`` giving the current point, and ``f`` the current |
| function value. |
| inner_tol, inner_maxiter, ... |
| Parameters to pass on to the "inner" Krylov solver. |
| See `scipy.sparse.linalg.gmres` for details. |
| outer_k : int, optional |
| Size of the subspace kept across LGMRES nonlinear |
| iterations. |
| |
| See `scipy.sparse.linalg.lgmres` for details. |
| """ |
| pass |
|
|
