NAG FL Interface
c05qsf (sparsys_​func_​easy)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{fcn}$ – Subroutine, supplied by the user. External Procedure

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

The specification of fcn is:

Fortran Interface

Subroutine fcn ( n, lindf, indf, x, fvec, iuser, ruser, iflag) Integer, Intent (In) :: n, lindf, indf(lindf) Integer, Intent (Inout) :: iuser(*), iflag Real (Kind=nag_wp), Intent (In) :: x(n) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Real (Kind=nag_wp), Intent (Out) :: fvec(n)

C Header Interface

void  fcn_ (const Integer *n, const Integer *lindf, const Integer indf[], const double x[], double fvec[], Integer iuser[], double ruser[], Integer *iflag)

C++ Header Interface

#include <nag.h> extern "C" { void  fcn_ (const Integer &n, const Integer &lindf, const Integer indf[], const double x[], double fvec[], Integer iuser[], double ruser[], Integer &iflag) }

1: $\mathbf{n}$ – Integer Input

On entry: $n$, the number of equations.

2: $\mathbf{lindf}$ – Integer Input

On entry: lindf specifies the number of indices $i$ for which values of $f_i\left(x\right)$ must be computed.

3: $\mathbf{indf}\left(\mathbf{lindf}\right)$ – Integer array Input

On entry: 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.

4: $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input

On entry: the components of the point $x$ at which the functions must be evaluated. $\mathbf{x}\left(i\right)$ contains the coordinate $x_i$.

5: $\mathbf{fvec}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: $\mathbf{fvec}\left(i\right)$ must contain the function values $f_i\left(x\right)$, for all indices $i$ in indf.

6: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

7: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

fcn is called with the arguments iuser and ruser as supplied to c05qsf. You should use the arrays iuser and ruser to supply information to fcn.

8: $\mathbf{iflag}$ – Integer Input/Output

On entry: $\mathbf{iflag}>0$.

On exit: in general, iflag should not be reset by fcn. If, however, you wish to terminate execution (perhaps because some illegal point x has been reached), iflag should be set to a negative integer.

fcn must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which c05qsf is called. Arguments denoted as Input must not be changed by this procedure.

Note: fcn should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by c05qsf. If your code inadvertently does return any NaNs or infinities, c05qsf is likely to produce unexpected results.

2: $\mathbf{n}$ – Integer Input

On entry: $n$, the number of equations.

Constraint: $\mathbf{n}>0$.

3: $\mathbf{x}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: an initial guess at the solution vector. $\mathbf{x}\left(i\right)$ must contain the coordinate $x_i$.

On exit: the final estimate of the solution vector.

4: $\mathbf{fvec}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: the function values at the final point returned in x. $\mathbf{fvec}\left(i\right)$ contains the function values $f_i$.

5: $\mathbf{xtol}$ – Real (Kind=nag_wp) Input

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

Suggested value: $\sqrt{\epsilon }$, where $\epsilon$ is the machine precision returned by x02ajf.

Constraint: $\mathbf{xtol}\ge 0.0$.

6: $\mathbf{init}$ – Logical Input

On entry: init must be set to .TRUE. to indicate that this is the first time c05qsf is called for this specific problem. c05qsf then computes the dense Jacobian and detects and stores its sparsity pattern (in rcomm and icomm) before proceeding with the iterations. This is noticeably time consuming when n is large. If not enough storage has been provided for rcomm or icomm, c05qsf will fail. On exit with $\mathbf{ifail}=\mathbf{0}$, $\mathbf{2}$, $\mathbf{3}$ or $\mathbf{4}$, $\mathbf{icomm}\left(1\right)$ contains $\mathit{nnz}$, the number of nonzero entries found in the Jacobian. On subsequent calls, init can be set to .FALSE. if the problem has a Jacobian of the same sparsity pattern. In that case, the computation time required for the detection of the sparsity pattern will be smaller.

7: $\mathbf{rcomm}\left(\mathbf{lrcomm}\right)$ – Real (Kind=nag_wp) array Communication Array

rcomm must not be altered between successive calls to c05qsf.

8: $\mathbf{lrcomm}$ – Integer Input

On entry: the dimension of the array rcomm as declared in the (sub)program from which c05qsf is called.

Constraint: $\mathbf{lrcomm}\ge 12+\mathit{nnz}$ where $\mathit{nnz}$ is the number of nonzero entries in the Jacobian, as computed by c05qsf.

9: $\mathbf{icomm}\left(\mathbf{licomm}\right)$ – Integer array Communication Array

If $\mathbf{ifail}=\mathbf{0}$, $\mathbf{2}$, $\mathbf{3}$ or $\mathbf{4}$ on exit, $\mathbf{icomm}\left(1\right)$ contains $\mathit{nnz}$ where $\mathit{nnz}$ is the number of nonzero entries in the Jacobian.

icomm must not be altered between successive calls to c05qsf.

10: $\mathbf{licomm}$ – Integer Input

On entry: the dimension of the array icomm as declared in the (sub)program from which c05qsf is called.

Constraint: $\mathbf{licomm}\ge 8\times \mathbf{n}+19+\mathit{nnz}$ where $\mathit{nnz}$ is the number of nonzero entries in the Jacobian, as computed by c05qsf.

11: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

12: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

iuser and ruser are not used by c05qsf, but are passed directly to fcn and may be used to pass information to this routine.

13: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=2$

There have been at least $200\times \left(\mathbf{n}+1\right)$ calls to fcn. Consider setting $\mathbf{init}=\mathrm{.FALSE.}$ and restarting the calculation from the point held in x.

$\mathbf{ifail}=3$

No further improvement in the solution is possible. xtol is too small: $\mathbf{xtol}=〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=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 Section 7). Otherwise, rerunning c05qsf from a different starting point may avoid the region of difficulty. The condition number of the Jacobian is $〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=5$

Termination requested in fcn.

$\mathbf{ifail}=6$

On entry, $\mathbf{lrcomm}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lrcomm}\ge 〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=7$

On entry, $\mathbf{licomm}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{licomm}\ge 〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=9$

An internal error has occurred. Code $=〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=11$

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}>0$.

$\mathbf{ifail}=12$

On entry, $\mathbf{xtol}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{xtol}\ge 0.0$.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results