naginterfaces.library.roots.sys_​func_​rcomm

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

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

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/c05/c05qdf.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=1$, $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$.

mlint

On initial entry: the number of subdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set $ml=n-1$.)

muint

On initial entry: the number of superdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set $mu=n-1$.)

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 entry: if $mode=2$, $diag$ must contain multiplicative scale factors for the variables.

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

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

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

On initial entry: need not be set.

On intermediate exit: must not be changed.

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

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.

epsfcnfloat, optional

On initial entry: the order 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 $epsfcn$ 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

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_func_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_func_rcomm, $fvec$ must contain the function values $f_i\left(x\right)$.

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

Raises

NagValueError

(errno $2$)

On entry, $irevcm=⟨value⟩$.

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

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

(errno $16$)

On entry, $ml=⟨value⟩$.

Constraint: $ml\ge 0$.

(errno $17$)

On entry, $mu=⟨value⟩$.

Constraint: $mu\ge 0$.

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.

(errno $5$)

The iteration is not making good progress, as measured by the improvement from the last $⟨value⟩$ iterations.

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

See also

naginterfaces.library.examples.roots.sys_func_rcomm_ex.main()