NAG Library Routine Document

d03faf  (dim3_ellip_helmholtz)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{xs}$ – Real (Kind=nag_wp)Input

On entry: the lower bound of the range of $x$, i.e., $\mathbf{xs}\le x\le \mathbf{xf}$.

Constraint: $\mathbf{xs}<\mathbf{xf}$.

2:     $\mathbf{xf}$ – Real (Kind=nag_wp)Input

On entry: the upper bound of the range of $x$, i.e., $\mathbf{xs}\le x\le \mathbf{xf}$.

Constraint: $\mathbf{xs}<\mathbf{xf}$.

3:     $\mathbf{l}$ – IntegerInput

On entry: the number of panels into which the interval (xs,xf) is subdivided. Hence, there will be $\mathbf{l}+1$ grid points in the $x$-direction given by $x_{\mathit{i}}=\mathbf{xs}+\left(\mathit{i}-1\right)\times \delta x$, for $\mathit{i}=1,2,\dots ,\mathbf{l}+1$, where $\delta x=\left(\mathbf{xf}-\mathbf{xs}\right)/\mathbf{l}$ is the panel width.

Constraint: $\mathbf{l}\ge 5$.

4:     $\mathbf{lbdcnd}$ – IntegerInput

On entry: indicates the type of boundary conditions at $x=\mathbf{xs}$ and $x=\mathbf{xf}$.

$\mathbf{lbdcnd}=0$

If the solution is periodic in $x$, i.e., $u\left(\mathbf{xs},y,z\right)=u\left(\mathbf{xf},y,z\right)$.

$\mathbf{lbdcnd}=1$

If the solution is specified at $x=\mathbf{xs}$ and $x=\mathbf{xf}$.

$\mathbf{lbdcnd}=2$

If the solution is specified at $x=\mathbf{xs}$ and the derivative of the solution with respect to $x$ is specified at $x=\mathbf{xf}$.

$\mathbf{lbdcnd}=3$

If the derivative of the solution with respect to $x$ is specified at $x=\mathbf{xs}$ and $x=\mathbf{xf}$.

$\mathbf{lbdcnd}=4$

If the derivative of the solution with respect to $x$ is specified at $x=\mathbf{xs}$ and the solution is specified at $x=\mathbf{xf}$.

Constraint: $0\le \mathbf{lbdcnd}\le 4$.

5:     $\mathbf{bdxs}\left(\mathbf{ldf2},\mathbf{n}+1\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the values of the derivative of the solution with respect to $x$ at $x=\mathbf{xs}$. When $\mathbf{lbdcnd}=3$ or $4$, $\mathbf{bdxs}\left(\mathit{j},\mathit{k}\right)=u_x\left(\mathbf{xs},y_j,z_k\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{m}+1$ and $\mathit{k}=1,2,\dots ,\mathbf{n}+1$.

When lbdcnd has any other value, bdxs is not referenced.

6:     $\mathbf{bdxf}\left(\mathbf{ldf2},\mathbf{n}+1\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the values of the derivative of the solution with respect to $x$ at $x=\mathbf{xf}$. When $\mathbf{lbdcnd}=2$ or $3$, $\mathbf{bdxf}\left(\mathit{j},\mathit{k}\right)=u_x\left(\mathbf{xf},y_{\mathit{j}},z_{\mathit{k}}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{m}+1$ and $\mathit{k}=1,2,\dots ,\mathbf{n}+1$.

When lbdcnd has any other value, bdxf is not referenced.

7:     $\mathbf{ys}$ – Real (Kind=nag_wp)Input

On entry: the lower bound of the range of $y$, i.e., $\mathbf{ys}\le y\le \mathbf{yf}$.

Constraint: $\mathbf{ys}<\mathbf{yf}$.

8:     $\mathbf{yf}$ – Real (Kind=nag_wp)Input

On entry: the upper bound of the range of $y$, i.e., $\mathbf{ys}\le y\le \mathbf{yf}$.

Constraint: $\mathbf{ys}<\mathbf{yf}$.

9:     $\mathbf{m}$ – IntegerInput

On entry: the number of panels into which the interval (ys,yf) is subdivided. Hence, there will be $\mathbf{m}+1$ grid points in the $y$-direction given by $y_{\mathit{j}}=\mathbf{ys}+\left(\mathit{j}-1\right)\times \delta y$, for $\mathit{j}=1,2,\dots ,\mathbf{m}+1$, where $\delta y=\left(\mathbf{yf}-\mathbf{ys}\right)/\mathbf{m}$ is the panel width.

Constraint: $\mathbf{m}\ge 5$.

10:   $\mathbf{mbdcnd}$ – IntegerInput

On entry: indicates the type of boundary conditions at $y=\mathbf{ys}$ and $y=\mathbf{yf}$.

$\mathbf{mbdcnd}=0$

If the solution is periodic in $y$, i.e., $u\left(x,\mathbf{yf},z\right)=u\left(x,\mathbf{ys},z\right)$.

$\mathbf{mbdcnd}=1$

If the solution is specified at $y=\mathbf{ys}$ and $y=\mathbf{yf}$.

$\mathbf{mbdcnd}=2$

If the solution is specified at $y=\mathbf{ys}$ and the derivative of the solution with respect to $y$ is specified at $y=\mathbf{yf}$.

$\mathbf{mbdcnd}=3$

If the derivative of the solution with respect to $y$ is specified at $y=\mathbf{ys}$ and $y=\mathbf{yf}$.

$\mathbf{mbdcnd}=4$

If the derivative of the solution with respect to $y$ is specified at $y=\mathbf{ys}$ and the solution is specified at $y=\mathbf{yf}$.

Constraint: $0\le \mathbf{mbdcnd}\le 4$.

11:   $\mathbf{bdys}\left(\mathbf{ldf},\mathbf{n}+1\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the values of the derivative of the solution with respect to $y$ at $y=\mathbf{ys}$. When $\mathbf{mbdcnd}=3$ or $4$, $\mathbf{bdys}\left(\mathit{i},\mathit{k}\right)=u_y\left(x_{\mathit{i}},\mathbf{ys},z_{\mathit{k}}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{l}+1$ and $\mathit{k}=1,2,\dots ,\mathbf{n}+1$.

When mbdcnd has any other value, bdys is not referenced.

12:   $\mathbf{bdyf}\left(\mathbf{ldf},\mathbf{n}+1\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the values of the derivative of the solution with respect to $y$ at $y=\mathbf{yf}$. When $\mathbf{mbdcnd}=2$ or $3$, $\mathbf{bdyf}\left(\mathit{i},\mathit{k}\right)=u_y\left(x_{\mathit{i}},\mathbf{yf},z_{\mathit{k}}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{l}+1$ and $\mathit{k}=1,2,\dots ,\mathbf{n}+1$.

When mbdcnd has any other value, bdyf is not referenced.

13:   $\mathbf{zs}$ – Real (Kind=nag_wp)Input

On entry: the lower bound of the range of $z$, i.e., $\mathbf{zs}\le z\le \mathbf{zf}$.

Constraint: $\mathbf{zs}<\mathbf{zf}$.

14:   $\mathbf{zf}$ – Real (Kind=nag_wp)Input

On entry: the upper bound of the range of $z$, i.e., $\mathbf{zs}\le z\le \mathbf{zf}$.

Constraint: $\mathbf{zs}<\mathbf{zf}$.

15:   $\mathbf{n}$ – IntegerInput

On entry: the number of panels into which the interval (zs,zf) is subdivided. Hence, there will be $\mathbf{n}+1$ grid points in the $z$-direction given by $z_{\mathit{k}}=\mathbf{zs}+\left(\mathit{k}-1\right)\times \delta z$, for $\mathit{k}=1,2,\dots ,\mathbf{n}+1$, where $\delta z=\left(\mathbf{zf}-\mathbf{zs}\right)/\mathbf{n}$ is the panel width.

Constraint: $\mathbf{n}\ge 5$.

16:   $\mathbf{nbdcnd}$ – IntegerInput

On entry: specifies the type of boundary conditions at $z=\mathbf{zs}$ and $z=\mathbf{zf}$.

$\mathbf{nbdcnd}=0$

if the solution is periodic in $z$, i.e., $u\left(x,y,\mathbf{zf}\right)=u\left(x,y,\mathbf{zs}\right)$.

$\mathbf{nbdcnd}=1$

if the solution is specified at $z=\mathbf{zs}$ and $z=\mathbf{zf}$.

$\mathbf{nbdcnd}=2$

if the solution is specified at $z=\mathbf{zs}$ and the derivative of the solution with respect to $z$ is specified at $z=\mathbf{zf}$.

$\mathbf{nbdcnd}=3$

if the derivative of the solution with respect to $z$ is specified at $z=\mathbf{zs}$ and $z=\mathbf{zf}$.

$\mathbf{nbdcnd}=4$

if the derivative of the solution with respect to $z$ is specified at $z=\mathbf{zs}$ and the solution is specified at $z=\mathbf{zf}$.

Constraint: $0\le \mathbf{nbdcnd}\le 4$.

17:   $\mathbf{bdzs}\left(\mathbf{ldf},\mathbf{m}+1\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the values of the derivative of the solution with respect to $z$ at $z=\mathbf{zs}$. When $\mathbf{nbdcnd}=3$ or $4$, $\mathbf{bdzs}\left(\mathit{i},\mathit{j}\right)=u_z\left(x_i,y_j,\mathbf{zs}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{l}+1$ and $\mathit{j}=1,2,\dots ,\mathbf{m}+1$.

When nbdcnd has any other value, bdzs is not referenced.

18:   $\mathbf{bdzf}\left(\mathbf{ldf},\mathbf{m}+1\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the values of the derivative of the solution with respect to $z$ at $z=\mathbf{zf}$. When $\mathbf{nbdcnd}=2$ or $3$, $\mathbf{bdzf}\left(\mathit{i},\mathit{j}\right)=u_z\left(x_i,y_j,\mathbf{zf}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{l}+1$ and $\mathit{j}=1,2,\dots ,\mathbf{m}+1$.

When nbdcnd has any other value, bdzf is not referenced.

19:   $\mathbf{lambda}$ – Real (Kind=nag_wp)Input

On entry: the constant $\lambda$ in the Helmholtz equation. For certain positive values of $\lambda$ a solution to the differential equation may not exist, and close to these values the solution of the discretized problem will be extremely ill-conditioned. If $\lambda >0$, d03faf will set $\mathbf{ifail}=\mathbf{3}$, but will still attempt to find a solution. However, since in general the values of $\lambda$ for which no solution exists cannot be predicted a priori, you are advised to treat any results computed with $\lambda >0$ with great caution.

20:   $\mathbf{ldf}$ – IntegerInput

On entry: the first dimension of the arrays f, bdys, bdyf, bdzs and bdzf as declared in the (sub)program from which d03faf is called.

Constraint: $\mathbf{ldf}\ge \mathbf{l}+1$.

21:   $\mathbf{ldf2}$ – IntegerInput

On entry: the second dimension of the array f and the first dimension of the arrays bdxs and bdxf as declared in the (sub)program from which d03faf is called.

Constraint: $\mathbf{ldf2}\ge \mathbf{m}+1$.

22:   $\mathbf{f}\left(\mathbf{ldf},\mathbf{ldf2},\mathbf{n}+1\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: the values of the right-side of the Helmholtz equation and boundary values (if any).

$$\mathbf{f}\left(i,j,k\right)=f\left(x_i,y_j,z_k\right)i=2,3,\dots ,\mathbf{l},j=2,3,\dots ,\mathbf{m}\text{ and }k=2,3,\dots ,\mathbf{n}\text{.}$$

On the boundaries f is defined by

lbdcnd	$\mathbf{f}\left(1,j,k\right)$	$\mathbf{f}\left(\mathbf{l}+1,j,k\right)$
0	$f\left(\mathbf{xs},y_j,z_k\right)$	$f\left(\mathbf{xs},y_j,z_k\right)$
1	$u\left(\mathbf{xs},y_j,z_k\right)$	$u\left(\mathbf{xf},y_j,z_k\right)$
2	$u\left(\mathbf{xs},y_j,z_k\right)$	$f\left(\mathbf{xf},y_j,z_k\right)$	$j=1,2,\dots ,\mathbf{m}+1$
3	$f\left(\mathbf{xs},y_j,z_k\right)$	$f\left(\mathbf{xf},y_j,z_k\right)$	$k=1,2,\dots ,\mathbf{n}+1$
4	$f\left(\mathbf{xs},y_j,z_k\right)$	$u\left(\mathbf{xf},y_j,z_k\right)$
mbdcnd	$\mathbf{f}\left(i,1,k\right)$	$\mathbf{f}\left(i,\mathbf{m}+1,k\right)$
0	$f\left(x_i,\mathbf{ys},z_k\right)$	$f\left(x_i,\mathbf{ys},z_k\right)$
1	$u\left(x_i,\mathbf{ys},z_k\right)$	$u\left(x_i,\mathbf{yf},z_k\right)$
2	$u\left(x_i,\mathbf{ys},z_k\right)$	$f\left(x_i,\mathbf{yf},z_k\right)$	$i=1,2,\dots ,\mathbf{l}+1$
3	$f\left(x_i,\mathbf{ys},z_k\right)$	$f\left(x_i,\mathbf{yf},z_k\right)$	$k=1,2,\dots ,\mathbf{n}+1$
4	$f\left(x_i,\mathbf{ys},z_k\right)$	$u\left(x_i,\mathbf{yf},z_k\right)$
nbdcnd	$\mathbf{f}\left(i,j,1\right)$	$\mathbf{f}\left(i,j,\mathbf{n}+1\right)$
0	$f\left(x_i,y_j,\mathbf{zs}\right)$	$f\left(x_i,y_j,\mathbf{zs}\right)$
1	$u\left(x_i,y_j,\mathbf{zs}\right)$	$u\left(x_i,y_j,\mathbf{zf}\right)$
2	$u\left(x_i,y_j,\mathbf{zs}\right)$	$f\left(x_i,y_j,\mathbf{zf}\right)$	$i=1,2,\dots ,\mathbf{l}+1$
3	$f\left(x_i,y_j,\mathbf{zs}\right)$	$f\left(x_i,y_j,\mathbf{zf}\right)$	$j=1,2,\dots ,\mathbf{m}+1$
4	$f\left(x_i,y_j,\mathbf{zs}\right)$	$u\left(x_i,y_j,\mathbf{zf}\right)$

Note: if the table calls for both the solution $u$ and the right-hand side $f$ on a boundary, the solution must be specified.

On exit: contains the solution $u\left(\mathit{i},\mathit{j},\mathit{k}\right)$ of the finite difference approximation for the grid point $\left(x_{\mathit{i}},y_{\mathit{j}},z_{\mathit{k}}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{l}+1$, $\mathit{j}=1,2,\dots ,\mathbf{m}+1$ and $\mathit{k}=1,2,\dots ,\mathbf{n}+1$.

23:   $\mathbf{pertrb}$ – Real (Kind=nag_wp)Output

On exit: $\mathbf{pertrb}=0$, unless a solution to Poisson's equation $\left(\lambda =0\right)$ is required with a combination of periodic or derivative boundary conditions (lbdcnd, mbdcnd and $\mathbf{nbdcnd}=0$ or $3$). In this case a solution may not exist. pertrb is a constant, calculated and subtracted from the array f, which ensures that a solution exists. d03faf then computes this solution, which is a least squares solution to the original approximation. This solution is not unique and is unnormalized. The value of pertrb should be small compared to the right-hand side f, otherwise a solution has been obtained to an essentially different problem. This comparison should always be made to ensure that a meaningful solution has been obtained.

24:   $\mathbf{w}\left(\mathbf{lwrk}\right)$ – Real (Kind=nag_wp) arrayWorkspace

25:   $\mathbf{lwrk}$ – IntegerInput

On entry: the dimension of the array w as declared in the (sub)program from which d03faf is called. w is no longer used as workspace, lwrk can therefore be safely set to zero.

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

26:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ 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}=1$

On entry,	$\mathbf{xs}\ge \mathbf{xf}$,
or	$\mathbf{l}<5$,
or	$\mathbf{lbdcnd}<0$,
or	$\mathbf{lbdcnd}>4$,
or	$\mathbf{ys}\ge \mathbf{yf}$,
or	$\mathbf{m}<5$,
or	$\mathbf{mbdcnd}<0$,
or	$\mathbf{mbdcnd}>4$,
or	$\mathbf{zs}\ge \mathbf{zf}$,
or	$\mathbf{n}<5$,
or	$\mathbf{nbdcnd}<0$,
or	$\mathbf{nbdcnd}>4$,
or	$\mathbf{ldf}<\mathbf{l}+1$,
or	$\mathbf{ldf2}<\mathbf{m}+1$.

$\mathbf{ifail}=2$

On entry,

$\mathbf{lwrk}<0$.

$\mathbf{ifail}=3$

On entry,

$\lambda >0$.

$\mathbf{ifail}=-99$

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

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

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

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (d03fafe.f90)

10.2

Program Data

Program Data (d03fafe.d)

10.3

Program Results

Program Results (d03fafe.r)