NAG Library Function Document

nag_zero_nonlin_eqns_easy (c05qbc)

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

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] – doubleOutput

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

5:     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), 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:     comm – Nag_Comm *Communication Structure

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

7:     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_INT

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. 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_easy (c05qbc) from a different starting point may avoid the region of difficulty.

NE_REAL

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

NE_TOO_MANY_FEVALS

There have been at least $200\times \left(\mathbf{n}+1\right)$ calls to fcn. Consider restarting the calculation from the 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 (c05qbce.c)

10.2  Program Data

10.3  Program Results

Program Results (c05qbce.r)