naginterfaces.library.roots.sys_​deriv_​rcomm

naginterfaces.library.roots.sys_deriv_rcomm(irevcm, x, fvec, fjac, mode, diag, r, qtf, comm, xtol=1.0536712127723509e-08, factor=100.0)

sys_deriv_rcomm is a comprehensive reverse communication 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 c05rd

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

Parameters

irevcmint

On initial entry: must have the value $0$.

xfloat, ndarray, shape $\left(n\right)$, modified in place

On initial entry: an initial guess at the solution vector.

On intermediate exit: contains the current point.

On final exit: the final estimate of the solution vector.

fvecfloat, ndarray, shape $\left(n\right)$, modified in place

On initial entry: need not be set.

On intermediate entry: if $irevcm\ne 2$, $fvec$ must not be changed.

If $irevcm=2$, $fvec$ must be set to the values of the functions computed at the current point $x$.

On final exit: the function values at the final point, $x$.

fjacfloat, ndarray, shape $(n,n)$, modified in place

On initial entry: need not be set.

On intermediate entry: if $irevcm\ne 3$, $fjac$ must not be changed.

If $irevcm=3$, $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$.

On final exit: the orthogonal matrix $Q$ produced by the $QR$ factorization of the final approximate Jacobian.

modeint

On initial entry: indicates whether or not you have provided scaling factors in $diag$.

If $mode=2$, the scaling must have been supplied in $diag$.

Otherwise, if $mode=1$, the variables will be scaled internally.

diagfloat, ndarray, shape $\left(n\right)$, modified in place

On initial entry: if $mode=2$, $diag$ must contain multiplicative scale factors for the variables.

If $mode=1$, $diag$ need not be set.

On intermediate exit: $diag$ must not be changed.

On final exit: the scale factors actually used (computed internally if $mode=1$).

rfloat, ndarray, shape $(n\times (n+1)/2)$, modified in place

On initial entry: need not be set.

On intermediate exit: must not be changed.

On final exit: the upper triangular matrix $R$ produced by the $QR$ factorization of the final approximate Jacobian, stored row-wise.

qtffloat, ndarray, shape $\left(n\right)$, modified in place

On initial entry: need not be set.

On intermediate exit: must not be changed.

On final exit: the vector $Q^{T}f$.

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

xtolfloat, optional

On initial entry: the accuracy in $x$ to which the solution is required.

factorfloat, optional

On initial entry: a quantity to be used in determining the initial step bound. In most cases, $factor$ should lie between $0.1$ and $100.0$. (The step bound is $factor\times {\parallel diag\times x\parallel }_2$ if this is nonzero; otherwise the bound is $factor$.)

Returns

irevcmint

On intermediate exit: specifies what action you must take before re-entering sys_deriv_rcomm with $irevcm$ set to this value. The value of $irevcm$ should be interpreted as follows:

$irevcm=1$

Indicates the start of a new iteration. No action is required by you, but $x$ and $fvec$ are available for printing.

$irevcm=2$

Indicates that before re-entry to sys_deriv_rcomm, $fvec$ must contain the function values $f_i\left(x\right)$.

$irevcm=3$

Indicates that before re-entry to sys_deriv_rcomm, $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$.

On final exit: $irevcm=0$ and the algorithm has terminated.

Raises

NagValueError

(errno $2$)

On entry, $irevcm=⟨value⟩$.

Constraint: $irevcm=0$, $1$, $2$ or $3$.

(errno $11$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $12$)

On entry, $xtol=⟨value⟩$.

Constraint: $xtol\ge 0.0$.

(errno $13$)

On entry, $mode=⟨value⟩$.

Constraint: $mode=1$ or $2$.

(errno $14$)

On entry, $factor=⟨value⟩$.

Constraint: $factor>0.0$.

(errno $15$)

On entry, $mode=2$ and $diag$ contained a non-positive element.

Warns

NagAlgorithmicWarning

(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, as measured by the improvement from the last $⟨value⟩$ 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_rcomm 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 $⟨value⟩$ 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_rcomm from a different starting point may avoid the region of difficulty.

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