D03FAF (PDF version)
D03 Chapter Contents
D03 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

D03FAF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

D03FAF solves the Helmholtz equation in Cartesian coordinates in three dimensions using the standard seven-point finite difference approximation. This routine is designed to be particularly efficient on vector processors.

2  Specification

SUBROUTINE D03FAF ( XS, XF, L, LBDCND, BDXS, BDXF, YS, YF, M, MBDCND, BDYS, BDYF, ZS, ZF, N, NBDCND, BDZS, BDZF, LAMBDA, LDF, LDF2, F, PERTRB, W, LWRK, IFAIL)
INTEGER  L, LBDCND, M, MBDCND, N, NBDCND, LDF, LDF2, LWRK, IFAIL
REAL (KIND=nag_wp)  XS, XF, BDXS(LDF2,N+1), BDXF(LDF2,N+1), YS, YF, BDYS(LDF,N+1), BDYF(LDF,N+1), ZS, ZF, BDZS(LDF,M+1), BDZF(LDF,M+1), LAMBDA, F(LDF,LDF2,N+1), PERTRB, W(LWRK)

3  Description

D03FAF solves the three-dimensional Helmholtz equation in Cartesian coordinates:
2u x2 + 2u y2 + 2u z2 +λu=fx,y,z.  
This subroutine forms the system of linear equations resulting from the standard seven-point finite difference equations, and then solves the system using a method based on the fast Fourier transform (FFT) described by Swarztrauber (1984). This subroutine is based on the routine HW3CRT from FISHPACK (see Swarztrauber and Sweet (1979)).
More precisely, the routine replaces all the second derivatives by second-order central difference approximations, resulting in a block tridiagonal system of linear equations. The equations are modified to allow for the prescribed boundary conditions. Either the solution or the derivative of the solution may be specified on any of the boundaries, or the solution may be specified to be periodic in any of the three dimensions. By taking the discrete Fourier transform in the x- and y-directions, the equations are reduced to sets of tridiagonal systems of equations. The Fourier transforms required are computed using the multiple FFT routines found in Chapter C06.

4  References

Swarztrauber P N (1984) Fast Poisson solvers Studies in Numerical Analysis (ed G H Golub) Mathematical Association of America
Swarztrauber P N and Sweet R A (1979) Efficient Fortran subprograms for the solution of separable elliptic partial differential equations ACM Trans. Math. Software 5 352–364

5  Parameters

1:     XS – REAL (KIND=nag_wp)Input
On entry: the lower bound of the range of x, i.e., XSxXF.
Constraint: XS<XF.
2:     XF – REAL (KIND=nag_wp)Input
On entry: the upper bound of the range of x, i.e., XSxXF.
Constraint: XS<XF.
3:     L – INTEGERInput
On entry: the number of panels into which the interval (XS,XF) is subdivided. Hence, there will be L+1 grid points in the x-direction given by xi=XS+i-1×δx, for i=1,2,,L+1, where δx=XF-XS/L is the panel width.
Constraint: L5.
4:     LBDCND – INTEGERInput
On entry: indicates the type of boundary conditions at x=XS and x=XF.
LBDCND=0
If the solution is periodic in x, i.e., uXS,y,z=uXF,y,z.
LBDCND=1
If the solution is specified at x=XS and x=XF.
LBDCND=2
If the solution is specified at x=XS and the derivative of the solution with respect to x is specified at x=XF.
LBDCND=3
If the derivative of the solution with respect to x is specified at x=XS and x=XF.
LBDCND=4
If the derivative of the solution with respect to x is specified at x=XS and the solution is specified at x=XF.
Constraint: 0LBDCND4.
5:     BDXSLDF2N+1 – REAL (KIND=nag_wp) arrayInput
On entry: the values of the derivative of the solution with respect to x at x=XS. When LBDCND=3 or 4, BDXSjk=uxXS,yj,zk, for j=1,2,,M+1 and k=1,2,,N+1.
When LBDCND has any other value, BDXS is not referenced.
6:     BDXFLDF2N+1 – REAL (KIND=nag_wp) arrayInput
On entry: the values of the derivative of the solution with respect to x at x=XF. When LBDCND=2 or 3, BDXFjk=uxXF,yj,zk, for j=1,2,,M+1 and k=1,2,,N+1.
When LBDCND has any other value, BDXF is not referenced.
7:     YS – REAL (KIND=nag_wp)Input
On entry: the lower bound of the range of y, i.e., YSyYF.
Constraint: YS<YF.
8:     YF – REAL (KIND=nag_wp)Input
On entry: the upper bound of the range of y, i.e., YSyYF.
Constraint: YS<YF.
9:     M – INTEGERInput
On entry: the number of panels into which the interval (YS,YF) is subdivided. Hence, there will be M+1 grid points in the y-direction given by yj=YS+j-1×δy, for j=1,2,,M+1, where δy=YF-YS/M is the panel width.
Constraint: M5.
10:   MBDCND – INTEGERInput
On entry: indicates the type of boundary conditions at y=YS and y=YF.
MBDCND=0
If the solution is periodic in y, i.e., ux,YF,z=ux,YS,z.
MBDCND=1
If the solution is specified at y=YS and y=YF.
MBDCND=2
If the solution is specified at y=YS and the derivative of the solution with respect to y is specified at y=YF.
MBDCND=3
If the derivative of the solution with respect to y is specified at y=YS and y=YF.
MBDCND=4
If the derivative of the solution with respect to y is specified at y=YS and the solution is specified at y=YF.
Constraint: 0MBDCND4.
11:   BDYSLDFN+1 – REAL (KIND=nag_wp) arrayInput
On entry: the values of the derivative of the solution with respect to y at y=YS. When MBDCND=3 or 4, BDYSik=uyxi,YS,zk, for i=1,2,,L+1 and k=1,2,,N+1.
When MBDCND has any other value, BDYS is not referenced.
12:   BDYFLDFN+1 – REAL (KIND=nag_wp) arrayInput
On entry: the values of the derivative of the solution with respect to y at y=YF. When MBDCND=2 or 3, BDYFik=uyxi,YF,zk, for i=1,2,,L+1 and k=1,2,,N+1.
When MBDCND has any other value, BDYF is not referenced.
13:   ZS – REAL (KIND=nag_wp)Input
On entry: the lower bound of the range of z, i.e., ZSzZF.
Constraint: ZS<ZF.
14:   ZF – REAL (KIND=nag_wp)Input
On entry: the upper bound of the range of z, i.e., ZSzZF.
Constraint: ZS<ZF.
15:   N – INTEGERInput
On entry: the number of panels into which the interval (ZS,ZF) is subdivided. Hence, there will be N+1 grid points in the z-direction given by zk=ZS+k-1×δz, for k=1,2,,N+1, where δz=ZF-ZS/N is the panel width.
Constraint: N5.
16:   NBDCND – INTEGERInput
On entry: specifies the type of boundary conditions at z=ZS and z=ZF.
NBDCND=0
if the solution is periodic in z, i.e., ux,y,ZF=ux,y,ZS.
NBDCND=1
if the solution is specified at z=ZS and z=ZF.
NBDCND=2
if the solution is specified at z=ZS and the derivative of the solution with respect to z is specified at z=ZF.
NBDCND=3
if the derivative of the solution with respect to z is specified at z=ZS and z=ZF.
NBDCND=4
if the derivative of the solution with respect to z is specified at z=ZS and the solution is specified at z=ZF.
Constraint: 0NBDCND4.
17:   BDZSLDFM+1 – REAL (KIND=nag_wp) arrayInput
On entry: the values of the derivative of the solution with respect to z at z=ZS. When NBDCND=3 or 4, BDZSij=uzxi,yj,ZS, for i=1,2,,L+1 and j=1,2,,M+1.
When NBDCND has any other value, BDZS is not referenced.
18:   BDZFLDFM+1 – REAL (KIND=nag_wp) arrayInput
On entry: the values of the derivative of the solution with respect to z at z=ZF. When NBDCND=2 or 3, BDZFij=uzxi,yj,ZF, for i=1,2,,L+1 and j=1,2,,M+1.
When NBDCND has any other value, BDZF is not referenced.
19:   LAMBDA – REAL (KIND=nag_wp)Input
On entry: the constant λ in the Helmholtz equation. For certain positive values of λ 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 λ>0, then D03FAF will set IFAIL=3, but will still attempt to find a solution. However, since in general the values of λ for which no solution exists cannot be predicted a priori, you are advised to treat any results computed with λ>0 with great caution.
20:   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: LDFL+1.
21:   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: LDF2M+1.
22:   FLDFLDF2N+1 – REAL (KIND=nag_wp) arrayInput/Output
On entry: the values of the right-side of the Helmholtz equation and boundary values (if any).
Fijk = fxi,yj,zki=2,3,,L, j=2,3,,M ​ and ​ k=2,3,,N.  
On the boundaries F is defined by
LBDCND F1jk FL+1jk
0 fXS,yj,zk fXS,yj,zk  
1 uXS,yj,zk uXF,yj,zk
2 uXS,yj,zk fXF,yj,zk j=1,2,,M+1
3 fXS,yj,zk fXF,yj,zk k=1,2,,N+1
4 fXS,yj,zk uXF,yj,zk
       
MBDCND Fi1k FiM+1k
0 fxi,YS,zk fxi,YS,zk
1 uYS,xi,zk uYF,xi,zk
2 uxi,YS,zk fxi,YF,zk i=1,2,,L+1
3 fxi,YS,zk fxi,YF,zk k=1,2,,N+1
4 fxi,YS,zk uxi,YF,zk
       
NBDCND Fij1 FijN+1
0 fxi,yj,ZS fxi,yj,ZS
1 uxi,yj,ZS uxi,yj,ZF
2 uxi,yj,ZS fxi,yj,ZF i=1,2,,L+1
3 fxi,yj,ZS fxi,yj,ZF j=1,2,,M+1
4 fxi,yj,ZS uxi,yj,ZF
Note: if the table calls for both the solution u and the right-hand side f on a boundary, then the solution must be specified.
On exit: contains the solution ui,j,k of the finite difference approximation for the grid point xi,yj,zk, for i=1,2,,L+1, j=1,2,,M+1 and k=1,2,,N+1.
23:   PERTRB – REAL (KIND=nag_wp)Output
On exit: PERTRB=0, unless a solution to Poisson's equation λ=0 is required with a combination of periodic or derivative boundary conditions (LBDCND, MBDCND and 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:   WLWRK – REAL (KIND=nag_wp) arrayWorkspace
25:   LWRK – INTEGERInput
On entry: the dimension of the array W as declared in the (sub)program from which D03FAF is called. 2×N+1×maxL,M+3×L+3×M+4×N+6 is an upper bound on the required size of W. If LWRK is too small, the routine exits with IFAIL=2, and if on entry IFAIL=0 or -1, a message is output giving the exact value of LWRK required to solve the current problem.
26:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ 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 parameter, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry,XSXF,
orL<5,
orLBDCND<0,
orLBDCND>4,
orYSYF,
orM<5,
orMBDCND<0,
orMBDCND>4,
orZSZF,
orN<5,
orNBDCND<0,
orNBDCND>4,
orLDF<L+1,
orLDF2<M+1.
IFAIL=2
On entry,LWRK is too small.
IFAIL=3
On entry,λ>0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.8 in the Essential Introduction for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.7 in the Essential Introduction for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

Not applicable.

8  Parallelism and Performance

D03FAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
D03FAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9  Further Comments

The execution time is roughly proportional to L×M×N× log2L + log2M +5 , but also depends on input parameters LBDCND and MBDCND.

10  Example

This example solves the Helmholz equation
2u x2 + 2u y2 + 2u z2 +λ u=fx,y,z  
for x,y,z0,1×0,2π×0,π2, where λ=-2, and fx,y,z is derived from the exact solution
ux,y,z=x4sinycosz.  
The equation is subject to the following boundary conditions, again derived from the exact solution given above.

10.1  Program Text

Program Text (d03fafe.f90)

10.2  Program Data

Program Data (d03fafe.d)

10.3  Program Results

Program Results (d03fafe.r)


D03FAF (PDF version)
D03 Chapter Contents
D03 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2015