naginterfaces.library.roots.sys_​func_​expert

naginterfaces.library.roots.sys_func_expert(fcnval, x, ml, mu, mode, diag, nprint, fcnmon=None, xtol=1.0536712127723509e-08, maxfev=None, epsfcn=0.0, factor=100.0, data=None)[source]

sys_func_expert is a comprehensive function that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.

For full information please refer to the NAG Library document for c05qc

https://www.nag.com/numeric/nl/nagdoc_28.7/flhtml/c05/c05qcf.html

Parameters
fcnvalcallable fvec = fcnval(x, data=None)

must return the values of the functions at a point .

Parameters
xfloat, ndarray, shape

The components of the point at which the functions must be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
fvecfloat, array-like, shape

must contain the function values .

xfloat, array-like, shape

An initial guess at the solution vector.

mlint

The number of subdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set .)

muint

The number of superdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set .)

modeint

Indicates whether or not you have provided scaling factors in .

If , the scaling must have been specified in .

Otherwise, if , the variables will be scaled internally.

diagfloat, array-like, shape

If , must contain multiplicative scale factors for the variables.

If , need not be set.

nprintint

Indicates whether (and how often) calls to are to be made.

No calls are made.

is called at the beginning of the first iteration, every iterations thereafter and immediately before the return from sys_func_expert.

fcnmonNone or callable fcnmon(x, fvec, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

may be used to monitor the progress of the algorithm.

Parameters
xfloat, ndarray, shape

The components of the current evaluation point .

fvecfloat, ndarray, shape

contains the function values .

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

xtolfloat, optional

The accuracy in to which the solution is required.

maxfevNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: .

The maximum number of calls to . sys_func_expert will exit with = 2, if, at the end of an iteration, the number of calls to exceeds .

epsfcnfloat, optional

A rough estimate of the largest relative error in the functions. It is used in determining a suitable step for a forward difference approximation to the Jacobian. If is less than machine precision (returned by machine.precision) then machine precision is used. Consequently a value of will often be suitable.

factorfloat, optional

A quantity to be used in determining the initial step bound. In most cases, should lie between and . (The step bound is if this is nonzero; otherwise the bound is .)

dataarbitrary, optional

User-communication data for callback functions.

Returns
xfloat, ndarray, shape

The final estimate of the solution vector.

fvecfloat, ndarray, shape

The function values at the final point returned in .

diagfloat, ndarray, shape

The scale factors actually used (computed internally if ).

nfevint

The number of calls made to .

fjacfloat, ndarray, shape

The orthogonal matrix produced by the factorization of the final approximate Jacobian.

rfloat, ndarray, shape

The upper triangular matrix produced by the factorization of the final approximate Jacobian, stored row-wise.

qtffloat, ndarray, shape

The vector .

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: .

(errno )

On entry, and contained a non-positive element.

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

Warns
NagAlgorithmicWarning
(errno )

There have been at least calls to : . Consider restarting the calculation from the final point held in .

(errno )

No further improvement in the solution is possible. is too small: .

(errno )

The iteration is not making good progress, as measured by the improvement from the last Jacobian evaluations.

(errno )

The iteration is not making good progress, as measured by the improvement from the last iterations.

NagCallbackTerminateWarning
(errno )

Termination requested in or .

Notes

The system of equations is defined as:

sys_func_expert is based on the MINPACK routine HYBRD (see Moré et al. (1980)). It chooses the correction at each step as a convex combination of the Newton and scaled gradient directions. The Jacobian is updated by the rank-1 method of Broyden. At the starting point, the Jacobian is approximated by forward differences, but these are not used again until the rank-1 method fails to produce satisfactory progress. For more details see Powell (1970).

References

Moré, J J, Garbow, B S and Hillstrom, K E, 1980, User guide for MINPACK-1, Technical Report ANL-80-74, Argonne National Laboratory

Powell, M J D, 1970, A hybrid method for nonlinear algebraic equations, Numerical Methods for Nonlinear Algebraic Equations, (ed P Rabinowitz), Gordon and Breach