naginterfaces.library.roots.sys_​deriv_​easy

naginterfaces.library.roots.sys_deriv_easy(fcnval, fcnjac, x, xtol=1.0536712127723509e-08, data=None, spiked_sorder='C')

sys_deriv_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. You must provide the Jacobian.

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

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/c05/c05rbf.html

Parameters

fcnvalcallable fvec = fcnval(x, data=None)

$fcnval$ 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)$

$fvec$ must contain the function values $f_i\left(x\right)$.

fcnjaccallable fjac = fcnjac(x, data=None)

$fcnjac$ must return the Jacobian at $x$.

Parameters

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

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

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

fjacfloat, array-like, shape $(n,n)$

$fjac[\text{i}-1,\text{j}-1]$ must contain the value of $\frac{\partial f_{\text{i}}}{\partial x_{\text{j}}}$ at the point $x$, for $\text{j}=1,2,\dots ,n$, for $\text{i}=1,2,\dots ,n$.

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.

spiked_sorderstr, optional

If $fjac$ in $fcnjac$ is spiked (i.e., has unit extent in all but one dimension, or has size $1$), $spiked\_sorder$ selects the storage order to associate with it in the NAG Engine:

spiked_sorder = $\text{'C'}$

row-major storage will be used;

spiked_sorder = $\text{'F'}$

column-major storage will be used.

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$.

fjacfloat, ndarray, shape $(n,n)$

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

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 $100\times (n+1)$ calls to $fcnval$ and $fcnjac$ combined. 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_deriv_easy from a different starting point may avoid the region of difficulty.

NagCallbackTerminateWarning

(errno $5$)

Termination requested in $fcnval$ or $fcnjac$.

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_deriv_easy is based on the MINPACK routine HYBRJ1 (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 requested, but it is not asked for 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