naginterfaces.library.pde.dim3_​ellip_​helmholtz

naginterfaces.library.pde.dim3_ellip_helmholtz(xs, xf, l, lbdcnd, bdxs, bdxf, ys, yf, mbdcnd, bdys, bdyf, zs, zf, nbdcnd, bdzs, bdzf, lamda, f)

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

For full information please refer to the NAG Library document for d03fa

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/d03/d03faf.html

Parameters

xsfloat

The lower bound of the range of $x$, i.e., $xs\le x\le xf$.

xffloat

The upper bound of the range of $x$, i.e., $xs\le x\le xf$.

lint

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 $x_{\text{i}}=xs+(\text{i}-1)\times \delta x$, for $\text{i}=1,2,\dots ,l+1$, where $\delta x=(xf-xs)/l$ is the panel width.

lbdcndint

Indicates the type of boundary conditions at $x=xs$ and $x=xf$.

$lbdcnd=0$

If the solution is periodic in $x$, i.e., $u(xs,y,z)=u(xf,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$.

bdxsfloat, array-like, shape $(m+1,n+1)$

The values of the derivative of the solution with respect to $x$ at $x=xs$. When $lbdcnd=3$ or $4$, $bdxs[\text{j}-1,\text{k}-1]=u_x(xs,y_j,z_k)$, for $\text{k}=1,2,\dots ,n+1$, for $\text{j}=1,2,\dots ,m+1$.

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

bdxffloat, array-like, shape $(m+1,n+1)$

The values of the derivative of the solution with respect to $x$ at $x=xf$. When $lbdcnd=2$ or $3$, $bdxf[\text{j}-1,\text{k}-1]=u_x(xf,y_{\text{j}},z_{\text{k}})$, for $\text{k}=1,2,\dots ,n+1$, for $\text{j}=1,2,\dots ,m+1$.

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

ysfloat

The lower bound of the range of $y$, i.e., $ys\le y\le yf$.

yffloat

The upper bound of the range of $y$, i.e., $ys\le y\le yf$.

mbdcndint

Indicates the type of boundary conditions at $y=ys$ and $y=yf$.

$mbdcnd=0$

If the solution is periodic in $y$, i.e., $u(x,yf,z)=u(x,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$.

bdysfloat, array-like, shape $(l+1,n+1)$

The values of the derivative of the solution with respect to $y$ at $y=ys$. When $mbdcnd=3$ or $4$, $bdys[\text{i}-1,\text{k}-1]=u_y(x_{\text{i}},ys,z_{\text{k}})$, for $\text{k}=1,2,\dots ,n+1$, for $\text{i}=1,2,\dots ,l+1$.

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

bdyffloat, array-like, shape $(l+1,n+1)$

The values of the derivative of the solution with respect to $y$ at $y=yf$. When $mbdcnd=2$ or $3$, $bdyf[\text{i}-1,\text{k}-1]=u_y(x_{\text{i}},yf,z_{\text{k}})$, for $\text{k}=1,2,\dots ,n+1$, for $\text{i}=1,2,\dots ,l+1$.

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

zsfloat

The lower bound of the range of $z$, i.e., $zs\le z\le zf$.

zffloat

The upper bound of the range of $z$, i.e., $zs\le z\le zf$.

nbdcndint

Specifies the type of boundary conditions at $z=zs$ and $z=zf$.

$nbdcnd=0$

if the solution is periodic in $z$, i.e., $u(x,y,zf)=u(x,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$.

bdzsfloat, array-like, shape $(l+1,m+1)$

The values of the derivative of the solution with respect to $z$ at $z=zs$. When $nbdcnd=3$ or $4$, $bdzs[\text{i}-1,\text{j}-1]=u_z(x_i,y_j,zs)$, for $\text{j}=1,2,\dots ,m+1$, for $\text{i}=1,2,\dots ,l+1$.

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

bdzffloat, array-like, shape $(l+1,m+1)$

The values of the derivative of the solution with respect to $z$ at $z=zf$. When $nbdcnd=2$ or $3$, $bdzf[\text{i}-1,\text{j}-1]=u_z(x_i,y_j,zf)$, for $\text{j}=1,2,\dots ,m+1$, for $\text{i}=1,2,\dots ,l+1$.

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

lamdafloat

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$, dim3_ellip_helmholtz will set $errno$ = 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.

ffloat, array-like, shape $(l+1,m+1,n+1)$

The values of the right-side of the Helmholtz equation and boundary values (if any).

$$f[i-1,j-1,k-1]=f(x_i,y_j,z_k)i=2,3,\dots ,l,j=2,3,\dots ,m\text{and}k=2,3,\dots ,n\text{.}$$

On the boundaries $f$ is defined by

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

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

Returns

ffloat, ndarray, shape $(l+1,m+1,n+1)$

Contains the solution $u(\text{i},\text{j},\text{k})$ of the finite difference approximation for the grid point $(x_{\text{i}},y_{\text{j}},z_{\text{k}})$, for $\text{k}=1,2,\dots ,n+1$, for $\text{j}=1,2,\dots ,m+1$, for $\text{i}=1,2,\dots ,l+1$.

pertrbfloat

$pertrb=0$, unless a solution to Poisson’s equation $(\lambda =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. dim3_ellip_helmholtz 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.

Raises

NagValueError

(errno $1$)

On entry, $nbdcnd=⟨value⟩$.

Constraint: $nbdcnd\ge 0$ and $nbdcnd\le 4$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 5$.

(errno $1$)

On entry, $zs=⟨value⟩$ and $zf=⟨value⟩$.

Constraint: $zs<zf$.

(errno $1$)

On entry, $mbdcnd=⟨value⟩$.

Constraint: $mbdcnd\ge 0$ and $mbdcnd\le 4$.

(errno $1$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 5$.

(errno $1$)

On entry, $ys=⟨value⟩$ and $yf=⟨value⟩$.

Constraint: $ys<yf$

(errno $1$)

On entry, $lbdcnd=⟨value⟩$.

Constraint: $lbdcnd\ge 0$ and $lbdcnd\le 4$.

(errno $1$)

On entry, $l=⟨value⟩$.

Constraint: $l\ge 5$.

(errno $1$)

On entry, $xs=⟨value⟩$ and $xf=⟨value⟩$.

Constraint: $xs<xf$.

Warns

NagAlgorithmicWarning

(errno $3$)

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

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

dim3_ellip_helmholtz solves the three-dimensional Helmholtz equation in Cartesian coordinates:

$$\frac{{\partial }^{2}u}{\partial x^2}+\frac{{\partial }^{2}u}{\partial y^2}+\frac{{\partial }^{2}u}{\partial z^2}+\lambda u=f(x,y,z)\text{.}$$

This function 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 function is based on the function HW3CRT from FISHPACK (see Swarztrauber and Sweet (1979)).

More precisely, the function 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 functions found in submodule sum.

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