718 lines
28 KiB
Python
718 lines
28 KiB
Python
"""
|
|
Unified interfaces to root finding algorithms.
|
|
|
|
Functions
|
|
---------
|
|
- root : find a root of a vector function.
|
|
"""
|
|
__all__ = ['root']
|
|
|
|
import numpy as np
|
|
|
|
ROOT_METHODS = ['hybr', 'lm', 'broyden1', 'broyden2', 'anderson',
|
|
'linearmixing', 'diagbroyden', 'excitingmixing', 'krylov',
|
|
'df-sane']
|
|
|
|
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
|
|
|
|
|
|
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)
|
|
|
|
# fun also returns the Jacobian
|
|
if not callable(jac) and meth in ('hybr', 'lm'):
|
|
if bool(jac):
|
|
fun = MemoizeJac(fun)
|
|
jac = fun.derivative
|
|
else:
|
|
jac = None
|
|
|
|
# set default tolerances
|
|
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('Method %s does not use the jacobian (jac).' % (method,),
|
|
RuntimeWarning)
|
|
|
|
|
|
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'))
|
|
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:
|
|
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)
|
|
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
|