NAG Library Routine Document

D06BAF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     NLINES – INTEGERInput

On entry: $m$, the number of lines that define the boundary of the closed connected subdomain (this equals the number of characteristic points which separate the entire boundary $\partial \Omega$ into lines).

Constraint: $\mathbf{NLINES}\ge 1$.

2:     COORCH($2$,NLINES) – REAL (KIND=nag_wp) arrayInput

On entry: $\mathbf{COORCH}\left(1,\mathit{i}\right)$ contains the $x$ coordinate of the $\mathit{i}$th characteristic point, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$; while $\mathbf{COORCH}\left(2,i\right)$ contains the corresponding $y$ coordinate.

3:     LINED($4$,NLINES) – INTEGER arrayInput

On entry: the description of the lines that define the boundary domain. The line $\mathit{i}$, for $\mathit{i}=1,2,\dots ,m$, is defined as follows:

$\mathbf{LINED}\left(1,i\right)$

The number of points on the line, including two end points.

$\mathbf{LINED}\left(2,i\right)$

The first end point of the line. If $\mathbf{LINED}\left(2,i\right)=j$, then the coordinates of the first end point are those stored in $\mathbf{COORCH}\left(:,j\right)$.

$\mathbf{LINED}\left(3,i\right)$

The second end point of the line. If $\mathbf{LINED}\left(3,i\right)=k$, then the coordinates of the second end point are those stored in $\mathbf{COORCH}\left(:,k\right)$.

$\mathbf{LINED}\left(4,i\right)$

This defines the type of line segment connecting the end points. Additional information is conveyed by the numerical value of $\mathbf{LINED}\left(4,i\right)$ as follows:

(i)	$\mathbf{LINED}\left(4,i\right)>0$, the line is described in FBND with $\mathbf{LINED}\left(4,i\right)$ as the index. In this case, the line must be described in the trigonometric (anticlockwise) direction;
(ii)	$\mathbf{LINED}\left(4,i\right)=0$, the line is a straight line;
(iii)	if $\mathbf{LINED}\left(4,i\right)<0$, say ($-p$), then the line is a polygonal arc joining the end points and interior points specified in CRUS. In this case the line contains the points whose coordinates are stored in $\mathbf{COORCH}\left(:,j\right),\mathbf{CRUS}\left(:,p\right),\mathbf{CRUS}\left(:,p+1\right),\dots ,\mathbf{CRUS}\left(:,p+r-3\right),\mathbf{COORCH}\left(:,k\right)$,where $z\in \left\{1,2\right\}$, $r=\mathbf{LINED}\left(1,i\right)$, $j=\mathbf{LINED}\left(2,i\right)$ and $k=\mathbf{LINED}\left(3,i\right)$.

Constraints:

• $2\le \mathbf{LINED}\left(1,i\right)$;
• $1\le \mathbf{LINED}\left(2,i\right)\le \mathbf{NLINES}$;
• $1\le \mathbf{LINED}\left(3,i\right)\le \mathbf{NLINES}$;
• $\mathbf{LINED}\left(2,\mathit{i}\right)\ne \mathbf{LINED}\left(3,\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$.

For each line described by FBND (lines with $\mathbf{LINED}\left(4,\mathit{i}\right)>0$, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$) the two end points ($\mathbf{LINED}\left(2,i\right)$ and $\mathbf{LINED}\left(3,i\right)$) lie on the curve defined by index $\mathbf{LINED}\left(4,i\right)$ in FBND, i.e.,

$\mathbf{FBND}\left(\mathbf{LINED}\left(4,i\right),\mathbf{COORCH}\left(1,\mathbf{LINED}\left(2,i\right)\right),\mathbf{COORCH}\left(2,\mathbf{LINED}\left(2,i\right)\right),\mathbf{RUSER},\mathbf{IUSER}\right)=0$;

$\mathbf{FBND}\left(\mathbf{LINED}\left(4,\mathit{i}\right),\mathbf{COORCH}\left(1,\mathbf{LINED}\left(3,\mathit{i}\right)\right),\mathbf{COORCH}\left(2,\mathbf{LINED}\left(3,\mathit{i}\right)\right),\mathbf{RUSER},\mathbf{IUSER}\right)=0$, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$.

For all lines described as polygonal arcs (lines with $\mathbf{LINED}\left(4,\mathit{i}\right)<0$, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$) the sets of intermediate points (i.e.,$\left[-\mathbf{LINED}\left(4,i\right):-\mathbf{LINED}\left(4,i\right)+\mathbf{LINED}\left(1,i\right)-3\right]$ for all $i$ such that $\mathbf{LINED}\left(4,i\right)<0$) are not overlapping. This can be expressed as:

$$-\mathbf{LINED}\left(4,i\right)+\mathbf{LINED}\left(1,i\right)-3=\sum _{\left\{i,\mathbf{LINED}\left(4,i\right)<0\right\}}\left\{\mathbf{LINED}\left(1,i\right)-2\right\}$$

or

$$-\mathbf{LINED}\left(4,i\right)+\mathbf{LINED}\left(1,i\right)-2=-\mathbf{LINED}\left(4,j\right)\text{,}$$

for a $j$ such that $j=1,2,\dots ,\mathbf{NLINES}$, $j\ne i$ and $\mathbf{LINED}\left(4,j\right)<0$.

4:     FBND – REAL (KIND=nag_wp) FUNCTION, supplied by the user.External Procedure

FBND must be supplied to calculate the value of the function which describes the curve $\left\{\left(x,y\right)\in {ℝ}^2\text{; such that }f\left(x,y\right)=0\right\}$ on segments of the boundary for which $\mathbf{LINED}\left(4,i\right)>0$. If there are no boundaries for which $\mathbf{LINED}\left(4,i\right)>0$ FBND will never be referenced by D06BAF and FBND may be the dummy function D06BAD. (D06BAD is included in the NAG Library.)

The specification of FBND is:

FUNCTION FBND ( I, X, Y, RUSER, IUSER) REAL (KIND=nag_wp) FBND INTEGER  I, IUSER(*) REAL (KIND=nag_wp)  X, Y, RUSER(*)

1:     I – INTEGERInput

On entry: $\mathbf{LINED}\left(4,i\right)$, the reference index of the line (portion of the contour) $i$ described.

2:     X – REAL (KIND=nag_wp)Input

3:     Y – REAL (KIND=nag_wp)Input

On entry: the values of $x$ and $y$ at which $f\left(x,y\right)$ is to be evaluated.

4:     RUSER($*$) – REAL (KIND=nag_wp) arrayUser Workspace

5:     IUSER($*$) – INTEGER arrayUser Workspace

FBND is called with the parameters RUSER and IUSER as supplied to D06BAF. You are free to use the arrays RUSER and IUSER to supply information to FBND as an alternative to using COMMON global variables.

FBND must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which D06BAF is called. Parameters denoted as Input must not be changed by this procedure.

5:     CRUS($2$,SDCRUS) – REAL (KIND=nag_wp) arrayInput

On entry: the coordinates of the intermediate points for polygonal arc lines. For a line $i$ defined as a polygonal arc (i.e., $\mathbf{LINED}\left(4,i\right)<0$), if $p=-\mathbf{LINED}\left(4,i\right)$, then $\mathbf{CRUS}\left(1,\mathit{k}\right)$, for $\mathit{k}=p,\dots ,p+\mathbf{LINED}\left(1,i\right)-3$, must contain the $x$ coordinate of the consecutive intermediate points for this line. Similarly $\mathbf{CRUS}\left(2,\mathit{k}\right)$, for $\mathit{k}=p,\dots ,p+\mathbf{LINED}\left(1,i\right)-3$, must contain the corresponding $y$ coordinate.

6:     SDCRUS – INTEGERInput

On entry: the second dimension of the array CRUS as declared in the (sub)program from which D06BAF is called.

Constraint: $\mathbf{SDCRUS}\ge {\displaystyle \sum _{\left\{i,\mathbf{LINED}\left(4,i\right)<0\right\}}}\left\{\mathbf{LINED}\left(1,i\right)-2\right\}$.

7:     RATE(NLINES) – REAL (KIND=nag_wp) arrayInput

On entry: $\mathbf{RATE}\left(\mathit{i}\right)$ is the geometric progression ratio between the points to be generated on the line $\mathit{i}$, for $\mathit{i}=1,2,\dots ,m$ and $\mathbf{LINED}\left(4,i\right)\ge 0$.

If $\mathbf{LINED}\left(4,i\right)<0$, $\mathbf{RATE}\left(i\right)$ is not referenced.

Constraint: if $\mathbf{LINED}\left(4,i\right)\ge 0$, $\mathbf{RATE}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$.

8:     NCOMP – INTEGERInput

On entry: $n$, the number of separately connected components of the boundary.

Constraint: $\mathbf{NCOMP}\ge 1$.

9:     NLCOMP(NCOMP) – INTEGER arrayInput

On entry: $\left|\mathbf{NLCOMP}\left(k\right)\right|$ is the number of line segments in component $k$ of the contour. The line $i$ of component $k$ runs in the direction $\mathbf{LINED}\left(2,i\right)$ to $\mathbf{LINED}\left(3,i\right)$ if $\mathbf{NLCOMP}\left(k\right)>0$, and in the opposite direction otherwise; for $k=1,2,\dots ,n$.

Constraints:

• $1\le \left|\mathbf{NLCOMP}\left(\mathit{k}\right)\right|\le \mathbf{NLINES}$, for $\mathit{k}=1,2,\dots ,\mathbf{NCOMP}$;
• ${\displaystyle \sum _{k=1}^n}\left|\mathbf{NLCOMP}\left(k\right)\right|=\mathbf{NLINES}$.

10:   LCOMP(NLINES) – INTEGER arrayInput

On entry: $\mathbf{LCOMP}\left(l1:l2\right)$, where $l2={\displaystyle \sum _{i=1}^k}\left|\mathbf{NLCOMP}\left(i\right)\right|$ and $l1=l2+1-\left|\mathbf{NLCOMP}\left(\mathit{k}\right)\right|$ is the list of line numbers for the $\mathit{k}$th components of the boundary, for $\mathit{k}=1,2,\dots ,\mathbf{NCOMP}$.

Constraint: $\mathbf{LCOMP}$ must hold a valid permutation of the integers $\left[1,\mathbf{NLINES}\right]$.

11:   NVMAX – INTEGERInput

On entry: the maximum number of the boundary mesh vertices to be generated.

Constraint: $\mathbf{NVMAX}\ge \mathbf{NLINES}$.

12:   NEDMX – INTEGERInput

On entry: the maximum number of boundary edges in the boundary mesh to be generated.

Constraint: $\mathbf{NEDMX}\ge 1$.

13:   NVB – INTEGEROutput

On exit: the total number of boundary mesh vertices generated.

14:   COOR($2$,NVMAX) – REAL (KIND=nag_wp) arrayOutput

On exit: $\mathbf{COOR}\left(1,\mathit{i}\right)$ will contain the $x$ coordinate of the $\mathit{i}$th boundary mesh vertex generated, for $\mathit{i}=1,2,\dots ,\mathbf{NVB}$; while $\mathbf{COOR}\left(2,i\right)$ will contain the corresponding $y$ coordinate.

15:   NEDGE – INTEGEROutput

On exit: the total number of boundary edges in the boundary mesh.

16:   EDGE($3$,NEDMX) – INTEGER arrayOutput

On exit: the specification of the boundary edges. $\mathbf{EDGE}\left(1,j\right)$ and $\mathbf{EDGE}\left(2,j\right)$ will contain the vertex numbers of the two end points of the $j$th boundary edge. $\mathbf{EDGE}\left(3,j\right)$ is a reference number for the $j$th boundary edge and

• $\mathbf{EDGE}\left(3,j\right)=\mathbf{LINED}\left(4,i\right)$, where $i$ and $j$ are such that the $j$th edges is part of the $i$th line of the boundary and $\mathbf{LINED}\left(4,i\right)\ge 0$;
• $\mathbf{EDGE}\left(3,j\right)=100+\left|\mathbf{LINED}\left(4,i\right)\right|$, where $i$ and $j$ are such that the $j$th edges is part of the $i$th line of the boundary and $\mathbf{LINED}\left(4,i\right)<0$.

17:   ITRACE – INTEGERInput

On entry: the level of trace information required from D06BAF.

$\mathbf{ITRACE}=0$ or $\mathbf{ITRACE}<-1$

No output is generated.

$\mathbf{ITRACE}=1$

Output from the boundary mesh generator is printed on the current advisory message unit (see X04ABF). This output contains the input information of each line and each connected component of the boundary.

$\mathbf{ITRACE}=-1$

An analysis of the output boundary mesh is printed on the current advisory message unit. This analysis includes the orientation (clockwise or anticlockwise) of each connected component of the boundary. This information could be of interest to you, especially if an interior meshing is carried out using the output of this routine, calling either D06AAF, D06ABF or D06ACF.

$\mathbf{ITRACE}>1$

The output is similar to that produced when $\mathbf{ITRACE}=1$, but the coordinates of the generated vertices on the boundary are also output.

You are advised to set $\mathbf{ITRACE}=0$, unless you are experienced with finite element mesh generation.

18:   RUSER($*$) – REAL (KIND=nag_wp) arrayUser Workspace

19:   IUSER($*$) – INTEGER arrayUser Workspace

RUSER and IUSER are not used by D06BAF, but are passed directly to FBND and may be used to pass information to this routine as an alternative to using COMMON global variables.

20:   RWORK(LRWORK) – REAL (KIND=nag_wp) arrayWorkspace

21:   LRWORK – INTEGERInput

On entry: the dimension of the array RWORK as declared in the (sub)program from which D06BAF is called.

Constraint: $\mathbf{LRWORK}\ge 2\times \left(\mathbf{NLINES}+\mathbf{SDCRUS}\right)+2\times {\max }_{i=1,2,\dots ,m}\left\{\mathbf{LINED}\left(1,i\right)\right\}\times \mathbf{NLINES}$.

22:   IWORK(LIWORK) – INTEGER arrayWorkspace

23:   LIWORK – INTEGERInput

On entry: the dimension of the array IWORK as declared in the (sub)program from which D06BAF is called.

Constraint: $\mathbf{LIWORK}\ge {\displaystyle \sum _{\left\{i,\mathbf{LINED}\left(4,i\right)<0\right\}}}\left\{\mathbf{LINED}\left(1,i\right)-2\right\}+8\times \mathbf{NLINES}+\mathbf{NVMAX}+3\times \mathbf{NEDMX}+2\times \mathbf{SDCRUS}$.

24:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ 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\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 parameter, 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{NLINES}<1$;
or	$\mathbf{NVMAX}<\mathbf{NLINES}$;
or	$\mathbf{NEDMX}<1$;
or	$\mathbf{NCOMP}<1$;
or	$\mathbf{LRWORK}<2\times \left(\mathbf{NLINES}+\mathbf{SDCRUS}\right)+2\times {\max }_{i=1,2,\dots ,m}\left\{\mathbf{LINED}\left(1,i\right)\right\}\times \mathbf{NLINES}$;
or	$\mathbf{LIWORK}<{\displaystyle \sum _{\left\{i,\mathbf{LINED}\left(4,i\right)<0\right\}}}\left\{\mathbf{LINED}\left(1,i\right)-2\right\}+8\times \mathbf{NLINES}+\mathbf{NVMAX}+3\times \mathbf{NEDMX}+2\times \mathbf{SDCRUS}$;
or	$\mathbf{SDCRUS}<{\displaystyle \sum _{\left\{i,\mathbf{LINED}\left(4,i\right)<0\right\}}}\left\{\mathbf{LINED}\left(1,i\right)-2\right\}$;
or	$\mathbf{RATE}\left(i\right)<0.0$ for some $i=1,2,\dots ,\mathbf{NLINES}$ with $\mathbf{LINED}\left(4,i\right)\ge 0$;
or	$\mathbf{LINED}\left(1,i\right)<2$ for some $i=1,2,\dots ,\mathbf{NLINES}$;
or	$\mathbf{LINED}\left(2,i\right)<1$ or $\mathbf{LINED}\left(2,i\right)>\mathbf{NLINES}$ for some $i=1,2,\dots ,\mathbf{NLINES}$;
or	$\mathbf{LINED}\left(3,i\right)<1$ or $\mathbf{LINED}\left(3,i\right)>\mathbf{NLINES}$ for some $i=1,2,\dots ,\mathbf{NLINES}$;
or	$\mathbf{LINED}\left(2,i\right)=\mathbf{LINED}\left(3,i\right)$ for some $i=1,2,\dots ,\mathbf{NLINES}$;
or	$\mathbf{NLCOMP}\left(k\right)=0$, or $\left|\mathbf{NLCOMP}\left(k\right)\right|>\mathbf{NLINES}$ for a $k=1,2,\dots ,\mathbf{NCOMP}$;
or	${\displaystyle \sum _{k=1}^n}\left|\mathbf{NLCOMP}\left(k\right)\right|\ne \mathbf{NLINES}$;
or	LCOMP does not represent a valid permutation of the integers in $\left[1,\mathbf{NLINES}\right]$;
or	one of the end points for a line $\mathit{i}$ described by the user-supplied function (lines with $\mathbf{LINED}\left(4,\mathit{i}\right)>0$, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$) does not belong to the corresponding curve in FBND;
or	the intermediate points for the lines described as polygonal arcs (lines with $\mathbf{LINED}\left(\mathit{i}\right)<0$, for $\mathit{i}=1,2,\dots ,\mathbf{NLINES}$) are overlapping.

$\mathbf{IFAIL}=2$

An error has occurred during the generation of the boundary mesh. It appears that NEDMX is not large enough, so you are advised to increase the value of NEDMX.

$\mathbf{IFAIL}=3$

An error has occurred during the generation of the boundary mesh. It appears that NVMAX is not large enough, so you are advised to increase the value of NVMAX.

$\mathbf{IFAIL}=4$

An error has occurred during the generation of the boundary mesh. Check the definition of each line (the parameter LINED) and each connected component of the boundary (the arguments NLCOMP, and LCOMP, as well as the coordinates of the characteristic points. Setting $\mathbf{ITRACE}>0$ may provide more details.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (d06bafe.f90)

9.2  Program Data

Program Data (d06bafe.d)

9.3  Program Results

Program Results (d06bafe.r)