naginterfaces.library.roots.sys_​func_​easy

naginterfaces.library.roots.sys_func_easy(fcn, x, xtol=1.0536712127723509e-08, data=None)

sys_func_easy is an easy-to-use 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 c05qb

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/c05/c05qbf.html

Parameters

fcncallable fvec = fcn(x, data=None)

$fcn$ must return the values of the functions $f_i$ at a point $x$.

Parameters

xfloat, ndarray, shape $\left(n\right)$

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

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

fvecfloat, array-like, shape $\left(n\right)$

The function values $f_i\left(x\right)$.

xfloat, array-like, shape $\left(n\right)$

An initial guess at the solution vector.

xtolfloat, optional

The accuracy in $x$ to which the solution is required.

dataarbitrary, optional

User-communication data for callback functions.

Returns

xfloat, ndarray, shape $\left(n\right)$

The final estimate of the solution vector.

fvecfloat, ndarray, shape $\left(n\right)$

The function values at the final point returned in $x$.

Raises

NagValueError

(errno $11$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $12$)

On entry, $xtol=⟨value⟩$.

Constraint: $xtol\ge 0.0$.

Warns

NagAlgorithmicWarning

(errno $2$)

There have been at least $200\times (n+1)$ calls to $fcn$. Consider restarting the calculation from the point held in $x$.

(errno $3$)

No further improvement in the solution is possible. $xtol$ is too small: $xtol=⟨value⟩$.

(errno $4$)

The iteration is not making good progress. This failure exit may indicate that the system does not have a zero, or that the solution is very close to the origin (see Accuracy). Otherwise, rerunning sys_func_easy from a different starting point may avoid the region of difficulty.

NagCallbackTerminateWarning

(errno $5$)

Termination requested in $fcn$.

Notes

The system of equations is defined as:

$$f_i(x_1,x_2,\dots ,x_n)=0\text{,}i=1,2,\dots ,n\text{.}$$

sys_func_easy is based on the MINPACK routine HYBRD1 (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