NAG Library Function Document

nag_zero_nonlin_eqns_deriv_expert (c05rcc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     fcn – function, supplied by the userExternal Function

Depending upon the value of iflag, fcn must either return the values of the functions $f_i$ at a point $x$ or return the Jacobian at $x$.

The specification of fcn is:

void  fcn (Integer n, const double x[], double fvec[], double fjac[], Nag_Comm *comm, Integer *iflag)

1:     n – IntegerInput

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

2:     x[n] – const doubleInput

On entry: the components of the point $x$ at which the functions or the Jacobian must be evaluated.

3:     fvec[n] – doubleInput/Output

On entry: if $\mathbf{iflag}=0$ or $2$, fvec contains the function values $f_i\left(x\right)$ and must not be changed.

On exit: if $\mathbf{iflag}=1$ on entry, fvec must contain the function values $f_i\left(x\right)$ (unless iflag is set to a negative value by fcn).

4:     fjac[$\mathbf{n}\times \mathbf{n}$] – doubleInput/Output

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{fjac}\left[\left(j-1\right)\times \mathbf{n}+i-1\right]$.

On entry: if $\mathbf{iflag}=0$, $\mathbf{fjac}\left[\left(\mathit{j}-1\right)\times \mathbf{n}+\mathit{i}-1\right]$ contains the value of $\frac{\partial f_{\mathit{i}}}{\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$. When $\mathbf{iflag}=0$ or $1$, fjac must not be changed.

On exit: if $\mathbf{iflag}=2$ on entry, $\mathbf{fjac}\left[\left(\mathit{j}-1\right)\times \mathbf{n}+\mathit{i}-1\right]$ must contain the value of $\frac{\partial f_{\mathit{i}}}{\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,n$, (unless iflag is set to a negative value by fcn).

5:     comm – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to fcn.

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_zero_nonlin_eqns_deriv_expert (c05rcc) you may allocate memory and initialize these pointers with various quantities for use by fcn when called from nag_zero_nonlin_eqns_deriv_expert (c05rcc) (see Section 3.2.1.1 in the Essential Introduction).

6:     iflag – Integer *Input/Output

On entry: $\mathbf{iflag}=0$, $1$ or $2$.

$\mathbf{iflag}=0$

x, fvec and fjac are available for printing (see nprint).

$\mathbf{iflag}=1$

fvec is to be updated.

$\mathbf{iflag}=2$

fjac is to be updated.

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), then iflag should be set to a negative integer value.

2:     n – IntegerInput

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

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

3:     x[n] – doubleInput/Output

On entry: an initial guess at the solution vector.

On exit: the final estimate of the solution vector.

4:     fvec[n] – doubleOutput

On exit: the function values at the final point returned in x.

5:     fjac[$\mathbf{n}\times \mathbf{n}$] – doubleOutput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{fjac}\left[\left(j-1\right)\times \mathbf{n}+i-1\right]$.

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

6:     xtol – doubleInput

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

Suggested value: $\sqrt{\epsilon }$, where $\epsilon$ is the machine precision returned by nag_machine_precision (X02AJC).

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

7:     maxfev – IntegerInput

On entry: the maximum number of calls to fcn with $\mathbf{iflag}\ne 0$. nag_zero_nonlin_eqns_deriv_expert (c05rcc) will exit with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_TOO_MANY_FEVALS, if, at the end of an iteration, the number of calls to fcn exceeds maxfev.

Suggested value: $\mathbf{maxfev}=100\times \left(\mathbf{n}+1\right)$.

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

8:     scale_mode – Nag_ScaleTypeInput

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

If $\mathbf{scale\_mode}=\mathrm{Nag\_ScaleProvided}$ the scaling must have been specified in diag.

Otherwise, if $\mathbf{scale\_mode}=\mathrm{Nag\_NoScaleProvided}$, the variables will be scaled internally.

Constraint: $\mathbf{scale\_mode}=\mathrm{Nag\_NoScaleProvided}$ or $\mathrm{Nag\_ScaleProvided}$.

9:     diag[n] – doubleInput/Output

On entry: if $\mathbf{scale\_mode}=\mathrm{Nag\_ScaleProvided}$, diag must contain multiplicative scale factors for the variables.

If $\mathbf{scale\_mode}=\mathrm{Nag\_NoScaleProvided}$, diag need not be set.

Constraint: if $\mathbf{scale\_mode}=\mathrm{Nag\_ScaleProvided}$, $\mathbf{diag}\left[\mathit{i}-1\right]>0.0$, for $\mathit{i}=1,2,\dots ,n$.

On exit: the scale factors actually used (computed internally if $\mathbf{scale\_mode}=\mathrm{Nag\_NoScaleProvided}$).

10:   factor – doubleInput

On 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 $\mathbf{factor}\times {‖\mathbf{diag}\times \mathbf{x}‖}_2$ if this is nonzero; otherwise the bound is factor.)

Suggested value: $\mathbf{factor}=100.0$.

Constraint: $\mathbf{factor}>0.0$.

11:   nprint – IntegerInput

On entry: indicates whether (and how often) special calls to fcn, with iflag set to $0$, are to be made for printing purposes.

$\mathbf{nprint}\le 0$

No calls are made.

$\mathbf{nprint}>0$

fcn is called at the beginning of the first iteration, every nprint iterations thereafter and immediately before the return from nag_zero_nonlin_eqns_deriv_expert (c05rcc).

12:   nfev – Integer *Output

On exit: the number of calls made to fcn to evaluate the functions.

13:   njev – Integer *Output

On exit: the number of calls made to fcn to evaluate the Jacobian.

14:   r[$\mathbf{n}\times \left(\mathbf{n}+1\right)/2$] – doubleOutput

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

15:   qtf[n] – doubleOutput

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

16:   comm – Nag_Comm *Communication Structure

The NAG communication argument (see Section 3.2.1.1 in the Essential Introduction).

17:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_DIAG_ELEMENTS

On entry, $\mathbf{scale\_mode}=\mathrm{Nag\_ScaleProvided}$ and diag contained a non-positive element.

NE_INT

On entry, $\mathbf{maxfev}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{maxfev}>0$.

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

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_NO_IMPROVEMENT

The iteration is not making good progress, as measured by the improvement from the last $⟨\mathit{\text{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 Section 7). Otherwise, rerunning nag_zero_nonlin_eqns_deriv_expert (c05rcc) from a different starting point may avoid the region of difficulty.

The iteration is not making good progress, as measured by the improvement from the last $⟨\mathit{\text{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 Section 7). Otherwise, rerunning nag_zero_nonlin_eqns_deriv_expert (c05rcc) from a different starting point may avoid the region of difficulty.

NE_REAL

On entry, $\mathbf{factor}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{factor}>0.0$.

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

NE_TOO_MANY_FEVALS

There have been at least maxfev calls to fcn: $\mathbf{maxfev}=⟨\mathit{\text{value}}⟩$. Consider restarting the calculation from the final point held in x.

NE_TOO_SMALL

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

NE_USER_STOP

iflag was set negative in fcn. $\mathbf{iflag}=⟨\mathit{\text{value}}⟩$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (c05rcce.c)

10.2  Program Data

10.3  Program Results

Program Results (c05rcce.r)