NAG FL Interface
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}$ – Integer Input

On entry: the number of panels into which the interval $\left(\mathbf{xs},\mathbf{xf}\right)$ 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}$ – Integer Input

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) array Input

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) array Input

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}$ – Integer Input

On entry: the number of panels into which the interval $\left(\mathbf{ys},\mathbf{yf}\right)$ 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}$ – Integer Input

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) array Input

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) array Input

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}$ – Integer Input

On entry: the number of panels into which the interval $\left(\mathbf{zs},\mathbf{zf}\right)$ 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}$ – Integer Input

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) array Input

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) array Input

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}$ – Integer Input

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}$ – Integer Input

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) array Input/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) array Output

25: $\mathbf{lwrk}$ – Integer Input

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.

26: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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{l}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{l}\ge 5$.

On entry, $\mathbf{lbdcnd}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lbdcnd}\ge 0$ and $\mathbf{lbdcnd}\le 4$.

On entry, $\mathbf{ldf2}=〈\mathit{\text{value}}〉$ and $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldf2}\ge \mathbf{m}+1$.

On entry, $\mathbf{ldf}=〈\mathit{\text{value}}〉$ and $\mathbf{l}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldf}\ge \mathbf{l}+1$.

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

On entry, $\mathbf{mbdcnd}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{mbdcnd}\ge 0$ and $\mathbf{mbdcnd}\le 4$.

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

On entry, $\mathbf{nbdcnd}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nbdcnd}\ge 0$ and $\mathbf{nbdcnd}\le 4$.

On entry, $\mathbf{xs}=〈\mathit{\text{value}}〉$ and $\mathbf{xf}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{xs}<\mathbf{xf}$.

On entry, $\mathbf{ys}=〈\mathit{\text{value}}〉$ and $\mathbf{yf}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ys}<\mathbf{yf}$

On entry, $\mathbf{zs}=〈\mathit{\text{value}}〉$ and $\mathbf{zf}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{zs}<\mathbf{zf}$.

$\mathbf{ifail}=3$

$\lambda >0.0$ in Helmholtz's equation – a solution may not exist.

$\mathbf{ifail}=-99$

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

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

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

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results