naginterfaces.library.roots.sparsys_​func_​easy

naginterfaces.library.roots.sparsys_func_easy(fcn, x, xtol=1.0536712127723509e-08, nnz=None, comm=None, data=None)

sparsys_func_easy is an easy-to-use function that finds a solution of a sparse system of nonlinear equations by a modification of the Powell hybrid method.

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

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

Parameters

fcncallable fcn(indf, x, fvec, data=None)

$fcn$ must return the values of the functions $f_i$ at a point $x$.

Parameters

indfint, ndarray, shape $\left(\text{lindf}\right)$

Note: this argument represents array indices; the values supplied will be base-1.

$indf$ specifies the indices $i$ for which values of $f_i\left(x\right)$ must be computed. The indices are specified in strictly ascending order.

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

The components of the point $x$ at which the functions must be evaluated. $x[i-1]$ contains the coordinate $x_i$.

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

On exit: $fvec[i-1]$ must contain the function values $f_i\left(x\right)$, for all indices $i$ in $indf$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

xfloat, array-like, shape $\left(n\right)$

An initial guess at the solution vector. $x[i-1]$ must contain the coordinate $x_i$.

xtolfloat, optional

The accuracy in $x$ to which the solution is required.

nnzNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: $n\times n$.

If supplied $nnz$ should be an upper estimate of the number of nonzero entries found in the Jacobian.

The size of the data that is self communicated to this routine via $comm$ is a function of $nnz$.

A suitable overestimate for $nnz$ is $n^2$, but this may be suboptimal when $\text{n}$ is large.

If an existing sparsity pattern for the problem is communicated via $comm$, $nnz$ will be ignored.

The value that was supplied in the call to sparsys_func_easy which computed that sparsity pattern will be extracted from $comm$ and used instead.

commNone or dict, communication object, optional, modified in place

Optionally, on entry: an existing sparsity pattern for the Jacobian, computed by a subsequent call. Otherwise, supplying an uninitialized object indicates it is the first time sparsys_func_easy is called for this specific problem.

On exit, if not None on entry: will be populated with the sparsity pattern of the Jacobian. On subsequent calls, the same communication object can be passed in again if the problem has a Jacobian of the same sparsity pattern.

dataarbitrary, optional

User-communication data for callback functions.

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$. $fvec[i-1]$ contains the function values $f_i$.

actual_nnzint

The number of nonzero entries found in the Jacobian.

Raises

NagValueError

(errno $6$)

On entry, the supplied $nnz=⟨value⟩$ was too small for this problem.

(errno $7$)

On entry, the supplied $nnz=⟨value⟩$ was too small for this problem.

(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 $200\times (n+1)$ calls to $fcn$. Consider restarting the calculation from the point held in $x$ and supplying the populated sparsity pattern from $comm$.

(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 sparsys_func_easy from a different starting point may avoid the region of difficulty. The condition number of the Jacobian is $⟨value⟩$.

NagCallbackTerminateWarning

(errno $5$)

Termination requested in $fcn$.

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

sparsys_func_easy is based on the MINPACK routine HYBRD1 (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 sparse rank-1 method of Schubert (see Schubert (1970)). At the starting point, the sparsity pattern is determined and the Jacobian is approximated by forward differences, but these are not used again until the rank-1 method fails to produce satisfactory progress. Then, the sparsity structure is used to recompute an approximation to the Jacobian by forward differences with the least number of function evaluations. The function you supply must be able to compute only the requested subset of the function values. The sparse Jacobian linear system is solved at each iteration with sparse.direct_real_gen_lu computing the Newton step. For more details see Powell (1970) and Broyden (1965).

References

Broyden, C G, 1965, A class of methods for solving nonlinear simultaneous equations, Mathematics of Computation (19(92)), 577–593

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

Schubert, L K, 1970, Modification of a quasi-Newton method for nonlinear equations with a sparse Jacobian, Mathematics of Computation (24(109)), 27–30