NAG C Library Function Document

nag_inteq_volterra2 (d05bac)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{ck}$ – function, supplied by the userExternal Function

ck must evaluate the kernel $k\left(t\right)$ of the integral equation (1).

The specification of ck is:

double  ck (double t, Nag_Comm *comm)

1:    $\mathbf{t}$ – doubleInput

On entry: $t$, the value of the independent variable.

2:    $\mathbf{comm}$ – Nag_Comm *

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

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_inteq_volterra2 (d05bac) you may allocate memory and initialize these pointers with various quantities for use by ck when called from nag_inteq_volterra2 (d05bac) (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).

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

2:    $\mathbf{cg}$ – function, supplied by the userExternal Function

cg must evaluate the function $g\left(s,y\left(s\right)\right)$ in (1).

The specification of cg is:

double  cg (double s, double y, Nag_Comm *comm)

1:    $\mathbf{s}$ – doubleInput

On entry: $s$, the value of the independent variable.

2:    $\mathbf{y}$ – doubleInput

On entry: the value of the solution $y$ at the point s.

3:    $\mathbf{comm}$ – Nag_Comm *

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

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_inteq_volterra2 (d05bac) you may allocate memory and initialize these pointers with various quantities for use by cg when called from nag_inteq_volterra2 (d05bac) (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).

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

3:    $\mathbf{cf}$ – function, supplied by the userExternal Function

cf must evaluate the function $f\left(t\right)$ in (1).

The specification of cf is:

double  cf (double t, Nag_Comm *comm)

1:    $\mathbf{t}$ – doubleInput

On entry: $t$, the value of the independent variable.

2:    $\mathbf{comm}$ – Nag_Comm *

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

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_inteq_volterra2 (d05bac) you may allocate memory and initialize these pointers with various quantities for use by cf when called from nag_inteq_volterra2 (d05bac) (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).

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

4:    $\mathbf{method}$ – Nag_ODEMethodInput

On entry: the type of method which you wish to employ.

$\mathbf{method}=\mathrm{Nag\_Adams}$

For Adams' type formulae.

$\mathbf{method}=\mathrm{Nag\_BDF}$

For backward differentiation formulae.

Constraint: $\mathbf{method}=\mathrm{Nag\_Adams}$ or $\mathrm{Nag\_BDF}$.

5:    $\mathbf{iorder}$ – IntegerInput

On entry: the order of the method to be used.

Constraints:

• if $\mathbf{method}=\mathrm{Nag\_Adams}$, $3\le \mathbf{iorder}\le 6$;
• if $\mathbf{method}=\mathrm{Nag\_BDF}$, $2\le \mathbf{iorder}\le 5$.

6:    $\mathbf{alim}$ – doubleInput

On entry: $a$, the lower limit of the integration interval.

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

7:    $\mathbf{tlim}$ – doubleInput

On entry: the final point of the integration interval, $T$.

Constraint: $\mathbf{tlim}>\mathbf{alim}$.

8:    $\mathbf{tol}$ – doubleInput

On entry: the relative accuracy required in the computed values of the solution.

Constraint: $\sqrt{\epsilon }\le \mathbf{tol}\le 1.0$, where $\epsilon$ is the machine precision.

9:    $\mathbf{nmesh}$ – IntegerInput

On entry: the number of equidistant points at which the solution is sought.

Constraints:

• if $\mathbf{method}=\mathrm{Nag\_Adams}$, $\mathbf{nmesh}\ge \mathbf{iorder}-1$;
• if $\mathbf{method}=\mathrm{Nag\_BDF}$, $\mathbf{nmesh}\ge \mathbf{iorder}$.

10:  $\mathbf{thresh}$ – doubleInput

On entry: the threshold value for use in the evaluation of the estimated relative errors. For two successive meshes the following condition must hold at each point of the coarser mesh

$$\frac{\left|Y_1-Y_2\right|}{\max \left(\left|Y_1\right|,\left|Y_2\right|,\left|\mathbf{thresh}\right|\right)}\le \mathbf{tol}\text{,}$$

where $Y_1$ is the computed solution on the coarser mesh and $Y_2$ is the computed solution at the corresponding point in the finer mesh. If this condition is not satisfied then the step size is halved and the solution is recomputed.

Note: thresh can be used to effect a relative, absolute or mixed error test. If $\mathbf{thresh}=0.0$ then pure relative error is measured and, if the computed solution is small and $\mathbf{thresh}=1.0$, absolute error is measured.

11:  $\mathbf{work}\left[\mathbf{lwk}\right]$ – doubleOutput

12:  $\mathbf{lwk}$ – IntegerInput

On entry: the dimension of the array work.

Constraint: $\mathbf{lwk}\ge 10\times \mathbf{nmesh}+6$.

Note: the above value of lwk is sufficient for nag_inteq_volterra2 (d05bac) to perform only one extrapolation on the initial mesh as defined by nmesh. In general much more workspace is required and in the case when a large step size is supplied (i.e., nmesh is small), you must provide a considerably larger workspace.

On exit: if $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NW_OUT_OF_WORKSPACE, $\mathbf{work}\left[0\right]$ contains the size of lwk required for the algorithm to proceed further.

13:  $\mathbf{yn}\left[\mathbf{nmesh}\right]$ – doubleOutput

On exit: $\mathbf{yn}\left[\mathit{i}-1\right]$ contains the most recent approximation of the true solution $y\left(t\right)$ at the specified point $t=\mathbf{alim}+\mathit{i}\times H$, for $\mathit{i}=1,2,\dots ,\mathbf{nmesh}$, where $H=\left(\mathbf{tlim}-\mathbf{alim}\right)/\mathbf{nmesh}$.

14:  $\mathbf{errest}\left[\mathbf{nmesh}\right]$ – doubleOutput

On exit: $\mathbf{errest}\left[\mathit{i}-1\right]$ contains the most recent approximation of the relative error in the computed solution at the point $t=\mathbf{alim}+\mathit{i}\times H$, for $\mathit{i}=1,2,\dots ,\mathbf{nmesh}$, where $H=\left(\mathbf{tlim}-\mathbf{alim}\right)/\mathbf{nmesh}$.

15:  $\mathbf{comm}$ – Nag_Comm *

The NAG communication argument (see Section 3.3.1.1 in How to Use the NAG Library and its Documentation).

16:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_CONVERGENCE

The solution is not converging. See Section 9.

NE_ENUM_INT

On entry, $\mathbf{method}=\mathrm{Nag\_Adams}$ and $\mathbf{iorder}=2$.
Constraint: if $\mathbf{method}=\mathrm{Nag\_Adams}$, $3\le \mathbf{iorder}\le 6$.

On entry, $\mathbf{method}=\mathrm{Nag\_BDF}$ and $\mathbf{iorder}=6$.
Constraint: if $\mathbf{method}=\mathrm{Nag\_BDF}$, $2\le \mathbf{iorder}\le 5$.

NE_ENUM_INT_2

On entry, $\mathbf{method}=\mathrm{Nag\_Adams}$, $\mathbf{iorder}=〈\mathit{\text{value}}〉$ and $\mathbf{nmesh}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{method}=\mathrm{Nag\_Adams}$, $\mathbf{nmesh}\ge \mathbf{iorder}-1$.

On entry, $\mathbf{method}=\mathrm{Nag\_BDF}$, $\mathbf{iorder}=〈\mathit{\text{value}}〉$ and $\mathbf{nmesh}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{method}=\mathrm{Nag\_BDF}$, $\mathbf{nmesh}\ge \mathbf{iorder}$.

NE_INT

On entry, $\mathbf{iorder}=〈\mathit{\text{value}}〉$.
Constraint: $2\le \mathbf{iorder}\le 6$.

On entry, $\mathbf{lwk}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lwk}\ge 10\times \mathbf{nmesh}+6$; that is, $〈\mathit{\text{value}}〉$.

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.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

NE_REAL

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

On entry, $\mathbf{tol}=〈\mathit{\text{value}}〉$.
Constraint: $\sqrt{\mathit{machine precision}}\le \mathbf{tol}\le 1.0$.

NE_REAL_2

On entry, $\mathbf{alim}=〈\mathit{\text{value}}〉$ and $\mathbf{tlim}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{tlim}>\mathbf{alim}$.

NW_OUT_OF_WORKSPACE

The workspace which has been supplied is too small for the required accuracy. The number of extrapolations, so far, is $〈\mathit{\text{value}}〉$. If you require one more extrapolation extend the size of workspace to: $\mathbf{lwk}=〈\mathit{\text{value}}〉$.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (d05bace.c)

10.2

Program Data

10.3

Program Results

Program Results (d05bace.r)