NAG Library Routine Document
d03eaf (dim2_laplace)
1
Purpose
d03eaf solves Laplace's equation in two dimensions for an arbitrary domain bounded internally or externally by one or more closed contours, given the value of either the unknown function or its normal derivative (into the domain) at each point of the boundary.
2
Specification
Fortran Interface
Subroutine d03eaf ( 
stage1, ext, dorm, n, p, q, x, y, n1p1, phi, phid, alpha, c, ldc, np4, icint, np1, ifail) 
Integer, Intent (In)  ::  n, n1p1, ldc, np4, np1  Integer, Intent (Inout)  ::  ifail  Integer, Intent (Out)  ::  icint(np1)  Real (Kind=nag_wp), Intent (In)  ::  p, q, x(n1p1), y(n1p1)  Real (Kind=nag_wp), Intent (Inout)  ::  phi(n), phid(n), alpha, c(ldc,np4)  Logical, Intent (In)  ::  stage1, ext, dorm 

C Header Interface
#include nagmk26.h
void 
d03eaf_ (const logical *stage1, const logical *ext, const logical *dorm, const Integer *n, const double *p, const double *q, const double x[], const double y[], const Integer *n1p1, double phi[], double phid[], double *alpha, double c[], const Integer *ldc, const Integer *np4, Integer icint[], const Integer *np1, Integer *ifail) 

3
Description
d03eaf uses an integral equation method, based upon Green's formula, which yields the solution, $\varphi $, within the domain, given its value or that of its normal derivative at each point of the boundary (except possibly at a finite number of discrete points). The solution is obtained in two stages. The first, which is executed once only, determines the complementary boundary values, i.e., $\varphi $, where its normal derivative is known and vice versa. The second stage is entered once for each point at which the solution is required.
The boundary is divided into a number of intervals in each of which
$\varphi $ and its normal derivative are approximated by constants. Of these half are evaluated by applying the given boundary conditions at one ‘nodal’ point within each interval while the remainder are determined (in stage
$1$) by solving a set of simultaneous linear equations. Here this is achieved by means of auxiliary routine
f08aaf (dgels), which will yield the least squares solution of an overdetermined system of equations as well as the unique solution of a square nonsingular system.
In exterior domains the solution behaves as $c+s\hspace{0.17em}\mathrm{log}\left(r\right)+\mathit{O}\left(1/r\right)$ as $r$ tends to infinity, where $c$ is a constant, $s$ is the total integral of the normal derivative around the boundary and $r$ is the radial distance from the origin of coordinates. For the Neumann problem (when the normal derivative is given along the whole boundary) $s$ is fixed by the boundary conditions whilst $c$ is chosen by you. However, for a Dirichlet problem (when $\varphi $ is given along the whole boundary) or for a mixed problem, stage $1$ produces a value of $c$ for which $s=0$; then as $r$ tends to infinity the solution tends to the constant $c$.
4
References
Symm G T and Pitfield R A (1974) Solution of Laplace's equation in two dimensions NPL Report NAC 44 National Physical Laboratory
5
Arguments
 1: $\mathbf{stage1}$ – LogicalInput

On entry: indicates whether the routine call is for stage
$1$ of the computation as defined in
Section 3.
 ${\mathbf{stage1}}=\mathrm{.TRUE.}$
 The call is for stage $1$.
 ${\mathbf{stage1}}=\mathrm{.FALSE.}$
 The call is for stage $2$.
 2: $\mathbf{ext}$ – LogicalInput

On entry: the form of the domain. If ${\mathbf{ext}}=\mathrm{.TRUE.}$, the domain is unbounded. Otherwise the domain is an interior one.
 3: $\mathbf{dorm}$ – LogicalInput

On entry: the form of the boundary conditions. If ${\mathbf{dorm}}=\mathrm{.TRUE.}$, the problem is a Dirichlet or mixed boundary value problem. Otherwise it is a Neumann problem.
 4: $\mathbf{n}$ – IntegerInput

On entry: the number of intervals into which the boundary is divided (see
Sections 7 and
9).
 5: $\mathbf{p}$ – Real (Kind=nag_wp)Input
 6: $\mathbf{q}$ – Real (Kind=nag_wp)Input

On entry: to stage
$2$,
p and
q must specify the
$x$ and
$y$ coordinates respectively of a point at which the solution is required.
When
stage1 is .TRUE.,
p and
q are ignored.
 7: $\mathbf{x}\left({\mathbf{n1p1}}\right)$ – Real (Kind=nag_wp) arrayInput
 8: $\mathbf{y}\left({\mathbf{n1p1}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the
$x$ and
$y$ coordinates respectively of points on the one or more closed contours which define the domain of the problem.
Note: each contour is described in such a manner that the subscripts of the coordinates increase when the domain is kept on the left. The final point on each contour coincides with the first and, if a further contour is to be described, the coordinates of this point are repeated in the arrays. In this way each interval is defined by three points, the second of which (the nodal point) always has an even subscript. In the case of the interior Neumann problem, the outermost boundary contour must be given first, if there is more than one.
 9: $\mathbf{n1p1}$ – IntegerInput

On entry: the value $2\left({\mathbf{n}}+M\right)1$, where $M$ denotes the number of closed contours which make up the boundary.
 10: $\mathbf{phi}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: for stage
$1$,
phi must contain the nodal values of
$\varphi $ or its normal derivative (into the domain) as prescribed in each interval. For stage
$2$ it must retain its output values from stage
$1$.
On exit: from stage $1$, it contains the constants which approximate $\varphi $ in each interval. It remains unchanged on exit from stage $2$.
 11: $\mathbf{phid}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: for stage $1$, ${\mathbf{phid}}\left(\mathit{i}\right)$ must hold the value $0.0$ or $1.0$ accordingly as ${\mathbf{phi}}\left(\mathit{i}\right)$ contains a value of $\varphi $ or its normal derivative, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$. For stage $2$ it must retain its output values from stage $1$.
On exit: from stage
$1$,
phid contains the constants which approximate the normal derivative of
$\varphi $ in each interval. It remains unchanged on exit from stage
$2$.
 12: $\mathbf{alpha}$ – Real (Kind=nag_wp)Input/Output

On entry: for stage
$1$, the use of
alpha depends on the nature of the problem:
 if ${\mathbf{dorm}}=\mathrm{.TRUE.}$, alpha need not be set;
 if ${\mathbf{dorm}}=\mathrm{.FALSE.}$ and ${\mathbf{ext}}=\mathrm{.TRUE.}$, alpha must contain the prescribed constant $c$ (see Section 3);
 if ${\mathbf{dorm}}=\mathrm{.FALSE.}$ and ${\mathbf{ext}}=\mathrm{.FALSE.}$, alpha must contain an appropriate value (often zero) for the integral of $\varphi $ around the outermost boundary.
For stage
$2$, on every call
alpha must contain the value returned at stage
$1$.
On exit: from stage
$1$:
 if ${\mathbf{ext}}=\mathrm{.FALSE.}$, alpha contains $0.0$;
 if ${\mathbf{ext}}=\mathrm{.TRUE.}$ and ${\mathbf{dorm}}=\mathrm{.FALSE.}$ alpha is unchanged;
 if ${\mathbf{ext}}=\mathrm{.TRUE.}$ and ${\mathbf{dorm}}=\mathrm{.TRUE.}$ alpha contains a computed estimate for $c$.
From stage
$2$:
 alpha contains the computed value of $\varphi $ at the point (p,q).
 13: $\mathbf{c}\left({\mathbf{ldc}},{\mathbf{np4}}\right)$ – Real (Kind=nag_wp) arrayWorkspace
 14: $\mathbf{ldc}$ – IntegerInput

On entry: the first dimension of the array
c as declared in the (sub)program from which
d03eaf is called.
Constraint:
${\mathbf{ldc}}\ge {\mathbf{n}}+1$.
 15: $\mathbf{np4}$ – IntegerInput

On entry: the value ${\mathbf{n}}+4$.
 16: $\mathbf{icint}\left({\mathbf{np1}}\right)$ – Integer arrayWorkspace
 17: $\mathbf{np1}$ – IntegerInput

On entry: the value ${\mathbf{n}}+1$.
 18: $\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
If on entry
${\mathbf{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:
 ${\mathbf{ifail}}=1$

Invalid tolerance used in an internal call to an auxiliary routine:
 ${\mathbf{icint}}\left(1\right)=0$
 Indicates too large a tolerance.
 ${\mathbf{icint}}\left(1\right)>0$
 Indicates too small a tolerance.
Note: this error is only possible in stage 1, and the circumstances under which it may occur cannot be foreseen. In the event of a failure, it is suggested that you change the scale of the domain of the problem and apply the routine again.
 ${\mathbf{ifail}}=2$

Incorrect rank obtained by an auxiliary routine; ${\mathbf{icint}}\left(1\right)$ contains the computed rank.
 ${\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
The accuracy of the computed solution depends upon how closely $\varphi $ and its normal derivative may be approximated by constants in each interval of the boundary and upon how well the boundary contours are represented by polygons with vertices at the selected points
$\left({\mathbf{x}}\left(\mathit{i}\right),{\mathbf{y}}\left(\mathit{i}\right)\right)$, for $\mathit{i}=1,2,\dots ,2\left({\mathbf{n}}+\mathrm{M}\right)1$ .
Consequently, in general, the accuracy increases as the boundary is subdivided into smaller and smaller intervals and by comparing solutions for successive subdivisions one may obtain an indication of the error in these solutions.
Alternatively, since the point of maximum error always lies on the boundary of the domain, an estimate of the error may be obtained by computing $\varphi $ at a sufficient number of points on the boundary where the true solution is known. The latter method (not applicable to the Neumann problem) is most useful in the case where $\varphi $ alone is prescribed on the boundary (the Dirichlet problem).
8
Parallelism and Performance
d03eaf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
d03eaf 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 implementationspecific information.
The time taken for stage 1, which is executed once only, is roughly proportional to
${{\mathbf{n}}}^{2}$, being dominated by the time taken to compute the coefficients. The time for each stage
$2$ application is proportional to
n.
The intervals into which the boundary is divided need not be of equal lengths.
For many practical problems useful results may be obtained with $20$ to $40$ intervals per boundary contour.
10
Example
An interior Neumann problem to solve Laplace's equation in the domain bounded externally by the triangle with vertices
$\left(3,0\right)$,
$\left(3,0\right)$ and
$\left(0,4\right)$, and internally by the triangle with vertices
$\left(2,1\right)$, (
$2,1$) and
$\left(0,3\right)$, given that the normal derivative of the solution
$\varphi $ is zero on each side of each triangle and, for uniqueness that the total integral of
$\varphi $ around the outer triangle is
$16$ (the length of the contour).
Figure 1
This trivial example has the obvious solution $\varphi =1$ throughout the domain. However it provides a useful illustration of data input for a doublyconnected domain. The solution is computed at one corner of each triangle and at one point inside the domain.
The program is written to handle any of the different types of problem that the routine can solve. The array dimensions must be increased for larger problems.
10.1
Program Text
Program Text (d03eafe.f90)
10.2
Program Data
Program Data (d03eafe.d)
10.3
Program Results
Program Results (d03eafe.r)