NAG Library Function Document

nag_zero_nonlin_eqns_expert (c05qcc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     fcn – function, supplied by the userExternal Function

fcn must return the values of the functions $f_i$ at a point $x$, unless $\mathbf{iflag}=0$ on entry to nag_zero_nonlin_eqns_expert (c05qcc).

The specification of fcn is:

void  fcn (Integer n, const double x[], double fvec[], 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 must be evaluated.

3:     fvec[n] – doubleInput/Output

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

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

4:     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_expert (c05qcc) you may allocate memory and initialize these pointers with various quantities for use by fcn when called from nag_zero_nonlin_eqns_expert (c05qcc) (see Section 3.2.1.1 in the Essential Introduction).

5:     iflag – Integer *Input/Output

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

$\mathbf{iflag}=0$

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

$\mathbf{iflag}>0$

fvec must 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.

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:     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$.

6:     maxfev – IntegerInput

On entry: the maximum number of calls to fcn with $\mathbf{iflag}\ne 0$. nag_zero_nonlin_eqns_expert (c05qcc) 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}=200\times \left(\mathbf{n}+1\right)$.

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

7:     ml – IntegerInput

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

Constraint: $\mathbf{ml}\ge 0$.

8:     mu – IntegerInput

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

Constraint: $\mathbf{mu}\ge 0$.

9:     epsfcn – doubleInput

On entry: a rough estimate 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 nag_machine_precision (X02AJC)) then machine precision is used. Consequently a value of $0.0$ will often be suitable.

Suggested value: $\mathbf{epsfcn}=0.0$.

10:   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}$.

11:   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}$).

12:   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$.

13:   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_expert (c05qcc).

14:   nfev – Integer *Output

On exit: the number of calls made to fcn with $\mathbf{iflag}>0$.

15:   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$ factorisation of the final approximate Jacobian.

16:   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.

17:   qtf[n] – doubleOutput

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

18:   comm – Nag_Comm *Communication Structure

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

19:   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{ml}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ml}\ge 0$.

On entry, $\mathbf{mu}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{mu}\ge 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.

The iteration is not making good progress, as measured by the improvement from the last $⟨\mathit{\text{value}}⟩$ Jacobian evaluations.

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 (c05qcce.c)

10.2  Program Data

10.3  Program Results

Program Results (c05qcce.r)