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://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/c05/c05qcf.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)$ .

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

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 $m l = n - 1$ .)

muint

The number of superdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set $m u = n - 1$ .)

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

$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)$ .
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

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: $200 \times (n + 1)$ .

The maximum number of calls to $f c n v a l$ . sys_func_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$ exceeds $m a x f e v$ .

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 $e p s f c n$ is less than machine precision (returned by machine.precision) then machine precision is used. Consequently a value of $0.0$ will often be suitable.

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.

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$ .
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$ .
fjacfloat, ndarray, shape $(n, n)$: The orthogonal matrix $Q$ produced by the $Q R$ factorization of the final approximate Jacobian.
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 $16$ )

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

Constraint: $m l \geq 0$ .

(errno $17$ )

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

Constraint: $m u \geq 0$ .

(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$ : $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.
(errno $5$ ): The iteration is not making good progress, as measured by the improvement from the last $⟨ v a l u e ⟩$ iterations.

NagCallbackTerminateWarning

(errno $6$ ): Termination requested in $f c n v a l$ 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_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

NAG and Python

Return to Front

naginterfaces.library.roots.sys_func_expert¶

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

naginterfaces.library.roots.sys_func_expert¶