naginterfaces.library.roots.sys_deriv_expert¶

naginterfaces.library.roots.sys_deriv_expert(fcnval, fcnjac, fcnmon, x, mode, diag, nprint, xtol=1.0536712127723509e-08, maxfev=None, factor=100.0, data=None, spiked_sorder='C')[source]¶

sys_deriv_expert is a comprehensive 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 c05rc

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

Parameters

fcnvalcallable fvec = fcnval(x, data=None)

$f c n v a l$ must return the values of the functions $f_{i}$ at a point $x$ .

Parameters

xfloat, ndarray, shape $(n)$: 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 $(n)$: $f v e c$ must contain the function values $f_{i} (x)$ .

fcnjaccallable fjac = fcnjac(x, data=None)

$f c n j a c$ must return the Jacobian at $x$ .

Parameters

xfloat, ndarray, shape $(n)$: 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)$: $f j a c [i - 1, j - 1]$ must contain the value of $\frac{\partial f_{i}}{\partial x_{j}}$ at the point $x$ , for $j = 1, 2, \dots, n$ , for $i = 1, 2, \dots, n$ .

fcnmoncallable fcnmon(x, fvec, fjac, data=None)

$f c n m o n$ may be used to monitor the progress of the algorithm.

Parameters

xfloat, ndarray, shape $(n)$: The components of the current evaluation point $x$ .
fvecfloat, ndarray, shape $(n)$: $f v e c$ contains the function values $f_{i} (x)$ .
fjacfloat, ndarray, shape $(n, n)$: $f j a c [i - 1, j - 1]$ contains the value of $\frac{\partial f_{i}}{\partial x_{j}}$ at the point $x$ , for $j = 1, 2, \dots, n$ , for $i = 1, 2, \dots, n$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

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

An initial guess at the solution vector.

modeint

Indicates whether or not you have provided scaling factors in $d i a g$ .

If $m o d e = 2$ , the scaling must have been specified in $d i a g$ .

Otherwise, if $m o d e = 1$ , the variables will be scaled internally.

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

If $m o d e = 2$ , $d i a g$ must contain multiplicative scale factors for the variables.

If $m o d e = 1$ , $d i a g$ need not be set.

nprintint

Indicates whether (and how often) calls to $f c n m o n$ are to be made.

$n p r i n t \leq 0$

No calls are made.

$n p r i n t > 0$

$f c n m o n$ is called at the beginning of the first iteration, every $n p r i n t$ iterations thereafter and immediately before the return from sys_deriv_expert.

xtolfloat, optional

The accuracy in $x$ 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: $100 \times (n + 1)$ .

The maximum number of calls to $f c n v a l$ and $f c n j a c$ combined. sys_deriv_expert will exit with $e r r n o$ = 2, if, at the end of an iteration, the number of calls to $f c n v a l$ and $f c n j a c$ combined exceeds $m a x f e v$ .

factorfloat, optional

A quantity to be used in determining the initial step bound. In most cases, $f a c t o r$ should lie between $0.1$ and $100.0$ . (The step bound is $f a c t o r \times {∥ d i a g \times x ∥}_{2}$ if this is nonzero; otherwise the bound is $f a c t o r$ .)

dataarbitrary, optional

User-communication data for callback functions.

spiked_sorderstr, optional

If $f j a c$ in $f c n j a c$ is spiked (i.e., has unit extent in all but one dimension, or has size $1$ ), $s p i k e d_s o r d e r$ selects the storage order to associate with it in the NAG Engine:

spiked_sorder = $'C'$: row-major storage will be used;
spiked_sorder = $'F'$: column-major storage will be used.

Returns

xfloat, ndarray, shape $(n)$: The final estimate of the solution vector.
fvecfloat, ndarray, shape $(n)$: The function values at the final point returned in $x$ .
fjacfloat, ndarray, shape $(n, n)$: The orthogonal matrix $Q$ produced by the $Q R$ factorization of the final approximate Jacobian.
diagfloat, ndarray, shape $(n)$: The scale factors actually used (computed internally if $m o d e = 1$ ).
nfevint: The number of calls made to $f c n v a l$ and $f c n j a c$ combined to evaluate the functions.
njevint: The number of calls made to $f c n j a c$ .
rfloat, ndarray, shape $(n \times (n + 1) / 2)$: The upper triangular matrix $R$ produced by the $Q R$ factorization of the final approximate Jacobian, stored row-wise.
qtffloat, ndarray, shape $(n)$: The vector $Q^{T} f$ .

Raises

NagValueError

(errno $11$ )

On entry, $n = ⟨ v a l u e ⟩$ .

Constraint: $n > 0$ .

(errno $12$ )

On entry, $x t o l = ⟨ v a l u e ⟩$ .

Constraint: $x t o l \geq 0.0$ .

(errno $13$ )

On entry, $m o d e = ⟨ v a l u e ⟩$ .

Constraint: $m o d e = 1$ or $2$ .

(errno $14$ )

On entry, $f a c t o r = ⟨ v a l u e ⟩$ .

Constraint: $f a c t o r > 0.0$ .

(errno $15$ )

On entry, $m o d e = 2$ and $d i a g$ contained a non-positive element.

(errno $18$ )

On entry, $m a x f e v = ⟨ v a l u e ⟩$ .

Constraint: $m a x f e v > 0$ .

Warns

NagAlgorithmicWarning

(errno $2$ ): There have been at least $m a x f e v$ calls to $f c n v a l$ and $f c n j a c$ combined: $m a x f e v = ⟨ v a l u e ⟩$ . Consider restarting the calculation from the final point held in $x$ .
(errno $3$ ): No further improvement in the solution is possible. $x t o l$ is too small: $x t o l = ⟨ v a l u e ⟩$ .
(errno $4$ ): The iteration is not making good progress, as measured by the improvement from the last $⟨ v a l u e ⟩$ Jacobian evaluations. 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_expert from a different starting point may avoid the region of difficulty.
(errno $5$ ): The iteration is not making good progress, as measured by the improvement from the last $⟨ v a l u e ⟩$ iterations. 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_expert from a different starting point may avoid the region of difficulty.

NagCallbackTerminateWarning

(errno $6$ ): Termination requested in $f c n v a l$ , $f c n j a c$ or $f c n m o n$ .

Notes

The system of equations is defined as:

f_{i} (x_{1}, x_{2}, \dots, x_{n}) = 0, i = 1, 2, \dots, n .

sys_deriv_expert is based on the MINPACK routine HYBRJ (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

NAG and Python

Return to Front

naginterfaces.library.roots.sys_deriv_expert¶

naginterfaces.library.roots.sys_​deriv_​expert¶

naginterfaces.library.roots.sys_deriv_expert¶