NAG Library Function Document

nag_mesh2d_bound (d06bac)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

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\times \mathbf{nlines}$] – const doubleInput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{coorch}\left[\left(j-1\right)\times 2+i-1\right]$.

On entry: $\mathbf{coorch}\left[\left(\mathit{i}-1\right)\times 2\right]$ contains the $x$ coordinate of the $\mathit{i}$th characteristic point, for $\mathit{i}=1,2,\dots ,\mathbf{nlines}$; while $\mathbf{coorch}\left[\left(i-1\right)\times 2+1\right]$ contains the corresponding $y$ coordinate.

3:     lined[$4\times \mathbf{nlines}$] – const IntegerInput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{lined}\left[\left(j-1\right)\times 4+i-1\right]$.

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[\left(i-1\right)\times 4\right]$

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

$\mathbf{lined}\left[\left(i-1\right)\times 4+1\right]$

The first end point of the line. If $\mathbf{lined}\left[\left(i-1\right)\times 4+1\right]=j$, then the coordinates of the first end point are those stored in $\mathbf{coorch}\left[\left(j-1\right)\times 2\right],\mathbf{coorch}\left[\left(j-1\right)\times 2+1\right]$.

$\mathbf{lined}\left[\left(i-1\right)\times 4+2\right]$

The second end point of the line. If $\mathbf{lined}\left[\left(i-1\right)\times 4+2\right]=k$, then the coordinates of the second end point are those stored in $\mathbf{coorch}\left[\left(k-1\right)\times 2\right],\mathbf{coorch}\left[\left(k-1\right)\times 2+1\right]$.

$\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]$

This defines the type of line segment connecting the end points. Additional information is conveyed by the numerical value of $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]$ as follows:

(i)	$\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]>0$, the line is described in fbnd with $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]$ as the index. In this case, the line must be described in the trigonometric (anticlockwise) direction;
(ii)	$\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]=0$, the line is a straight line;
(iii)	if $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]<0$, say (i.e., $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]=-p$ for some index $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[\left(j-1\right)\times 2+z\right],\mathbf{crus}\left[\left(p-1\right)\times 2+z\right],\mathbf{crus}\left[p\times 2+z\right],\dots ,\mathbf{crus}\left[\left(p+r-4\right)\times 2+z\right],\mathbf{coorch}\left[\left(k-1\right)\times 2+z\right]$, where $z\in \left\{0,1\right\}$, $r=\mathbf{lined}\left[\left(i-1\right)\times 4\right]$, $j=\mathbf{lined}\left[\left(i-1\right)\times 4+1\right]$ and $k=\mathbf{lined}\left[\left(i-1\right)\times 4+2\right]$.

Constraints:

• $2\le \mathbf{lined}\left[\left(i-1\right)\times 4\right]$;
• $1\le \mathbf{lined}\left[\left(i-1\right)\times 4+1\right]\le \mathbf{nlines}$;
• $1\le \mathbf{lined}\left[\left(i-1\right)\times 4+2\right]\le \mathbf{nlines}$;
• $\mathbf{lined}\left[\left(\mathit{i}-1\right)\times 4+1\right]\ne \mathbf{lined}\left[\left(\mathit{i}-1\right)\times 4+2\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{nlines}$.

For each line described by fbnd (lines with $\mathbf{lined}\left[\left(\mathit{i}-1\right)\times 4+3\right]>0$, for $\mathit{i}=1,2,\dots ,\mathbf{nlines}$) the two end points ($\mathbf{lined}\left[\left(i-1\right)\times 4+1\right]$ and $\mathbf{lined}\left[\left(i-1\right)\times 4+2\right]$) lie on the curve defined by index $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]$ in fbnd, i.e.,

$\mathbf{fbnd}\left(\mathbf{lined}\left[\left(i-1\right)\times 4+3\right],\mathbf{coorch}\left[\left(\mathbf{lined}\left[\left(i-1\right)\times 4+1\right]-1\right)\times 2\right],\mathbf{coorch}\left[\left(\mathbf{lined}\left[\left(i-1\right)\times 4+1\right]-1\right)\times 2+1\right],\mathbf{comm}\right)=0$;

$\mathbf{fbnd}\left(\mathbf{lined}\left[\left(\mathit{i}-1\right)\times 4+3\right],\mathbf{coorch}\left[\left(\mathbf{lined}\left[\left(\mathit{i}-1\right)\times 4+2\right]-1\right)\times 2\right],\mathbf{coorch}\left[\left(\mathbf{lined}\left[\left(\mathit{i}-1\right)\times 4+2\right]-1\right)\times 2+1\right],\mathbf{comm}\right)=0$, for $\mathit{i}=1,2,\dots ,\mathbf{nlines}$.

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

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

or

$$-\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]+\mathbf{lined}\left[\left(i-1\right)\times 4\right]-2=-\mathbf{lined}\left[\left(j-1\right)\times 4+3\right]\text{,}$$

for a $j$ such that $j=1,2,\dots ,\mathbf{nlines}$, $j\ne i$ and $\mathbf{lined}\left[\left(j-1\right)\times 4+3\right]<0$.

4:     fbnd – function, supplied by the userExternal Function

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[\left(i-1\right)\times 4+3\right]>0$. If there are no boundaries for which $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]>0$ fbnd will never be referenced by nag_mesh2d_bound (d06bac), in which case fbnd may be NULLFN.

The specification of fbnd is:

double  fbnd (Integer i, double x, double y, Nag_Comm *comm)

1:     i – IntegerInput

On entry: $\mathbf{lined}\left[3\right]\left[i-1\right]$, the reference index of the line (portion of the contour) $i$ described.

2:     x – doubleInput

3:     y – doubleInput

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

4:     comm – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to fbnd.

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_mesh2d_bound (d06bac) you may allocate memory and initialize these pointers with various quantities for use by fbnd when called from nag_mesh2d_bound (d06bac) (see Section 3.2.1.1 in the Essential Introduction).

5:     crus[$2\times \mathbf{sdcrus}$] – const doubleInput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{crus}\left[\left(j-1\right)\times 2+i-1\right]$.

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[\left(i-1\right)\times 4+3\right]<0$), if $p=-\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]$, then $\mathbf{crus}\left[\left(\mathit{k}-1\right)\times 2\right]$, for $\mathit{k}=p,\dots ,p+\mathbf{lined}\left[\left(i-1\right)\times 4\right]-3$, must contain the $x$ coordinate of the consecutive intermediate points for this line. Similarly $\mathbf{crus}\left[\left(\mathit{k}-1\right)\times 2+1\right]$, for $\mathit{k}=p,\dots ,p+\mathbf{lined}\left[\left(i-1\right)\times 4\right]-3$, must contain the corresponding $y$ coordinate.

6:     sdcrus – IntegerInput

On entry: the half dimension of the array crus as declared in the function from which nag_mesh2d_bound (d06bac) is called.

Constraint: $\mathbf{sdcrus}\ge {\displaystyle \sum _{\left\{i,\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]<0\right\}}}\left\{\mathbf{lined}\left[\left(i-1\right)\times 4\right]-2\right\}$.

7:     rate[nlines] – const doubleInput

On entry: $\mathbf{rate}\left[\mathit{i}-1\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[\left(i-1\right)\times 4+3\right]\ge 0$.

If $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]<0$, $\mathbf{rate}\left[i-1\right]$ is not referenced.

Constraint: if $\mathbf{lined}\left[\left(i-1\right)\times 4+3\right]\ge 0$, $\mathbf{rate}\left[\mathit{i}-1\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] – const IntegerInput

On entry: $\left|\mathbf{nlcomp}\left[k-1\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[\left(i-1\right)\times 4+1\right]$ to $\mathbf{lined}\left[\left(i-1\right)\times 4+2\right]$ if $\mathbf{nlcomp}\left[k-1\right]>0$, and in the opposite direction otherwise; for $k=1,2,\dots ,n$.

Constraints:

• $1\le \left|\mathbf{nlcomp}\left[\mathit{k}-1\right]\right|\le \mathbf{nlines}$, for $\mathit{k}=1,2,\dots ,\mathbf{ncomp}$;
• ${\displaystyle \sum _{k=1}^n}\left|\mathbf{nlcomp}\left[k-1\right]\right|=\mathbf{nlines}$.

10:   lcomp[nlines] – const IntegerInput

On entry: lcomp must contain the list of line numbers for the each component of the boundary. Specifically, the line numbers for the $\mathit{k}$th component of the boundary, for $\mathit{k}=1,2,\dots ,\mathbf{ncomp}$, must be in elements $l1-1$ to $l2-1$ of lcomp, where $l2={\displaystyle \sum _{i=1}^k}\left|\mathbf{nlcomp}\left[i-1\right]\right|$ and $l1=l2+1-\left|\mathbf{nlcomp}\left[\mathit{k}-1\right]\right|$.

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 – Integer *Output

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

14:   coor[$2\times \mathbf{nvmax}$] – doubleOutput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{coor}\left[\left(j-1\right)\times 2+i-1\right]$.

On exit: $\mathbf{coor}\left[\left(\mathit{i}-1\right)\times 2\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[\left(i-1\right)\times 2+1\right]$ will contain the corresponding $y$ coordinate.

15:   nedge – Integer *Output

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

16:   edge[$3\times \mathbf{nedmx}$] – IntegerOutput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{edge}\left[\left(j-1\right)\times 3+i-1\right]$.

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

• $\mathbf{edge}\left[\left(j-1\right)\times 3+2\right]=\mathbf{lined}\left[\left(i-1\right)\times 4+3\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[\left(i-1\right)\times 4+3\right]\ge 0$;
• $\mathbf{edge}\left[\left(j-1\right)\times 3+2\right]=100+\left|\mathbf{lined}\left[\left(i-1\right)\times 4+3\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[\left(i-1\right)\times 4+3\right]<0$.

Note that the edge vertices are numbered from $1$ to nvb.

17:   itrace – IntegerInput

On entry: the level of trace information required from nag_mesh2d_bound (d06bac).

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

No output is generated.

$\mathbf{itrace}=1$

Output from the boundary mesh generator is printed. 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 function, calling either nag_mesh2d_inc (d06aac), nag_mesh2d_delaunay (d06abc) or nag_mesh2d_front (d06acc).

$\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:   outfile – const char *Input

On entry: the name of a file to which diagnostic output will be directed. If outfile is NULL the diagnostic output will be directed to standard output.

19:   comm – Nag_Comm *Communication Structure

The NAG communication argument (see Section 3.2.1.1 in the Essential Introduction).

20:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_INT

On entry, ncomp the number of connected components of the boundary is less than $1$: $\mathbf{ncomp}=⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{nedmx}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nedmx}\ge 1$.

On entry, nedmx the maximum number of boundary edge lines is less than $1$: $\mathbf{nedmx}=⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nlines}\ge 1$.

On entry, nlines the number of lines is less than $1$: $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.

NE_INT_2

On entry, $\mathbf{nvmax}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nvmax}\ge \mathbf{nlines}$.

On entry, nvmax the maximum number of boundary vertices is less than nlines: $\mathbf{nvmax}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{sdcrus}=⟨\mathit{\text{value}}⟩$ and $\mathit{nusmin}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{sdcrus}\ge \mathit{nusmin}$.

On entry, the line list for the separate connected component of the boundary is badly set: $\mathbf{lcomp}\left[l-1\right]=⟨\mathit{\text{value}}⟩$ and $l=⟨\mathit{\text{value}}⟩$. It should be less than or equal to nlines and greater than or equal to $1$.

On entry, the number of points on line $⟨\mathit{\text{value}}⟩$ is $⟨\mathit{\text{value}}⟩$. It should be greater than or equal to $2$.

On entry, there is a correlation problem between the user-supplied coordinates and the specification of the polygonal arc representing line $\mathit{I}=⟨\mathit{\text{value}}⟩$ with the index in $\mathbf{crus}=⟨\mathit{\text{value}}⟩$.

On entry, the sum of absolute values of all numbers of line segments is different from nlines. The sum of all the elements of $\mathbf{nlcomp}=⟨\mathit{\text{value}}⟩$. $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.

NE_INT_3

On entry, the absolute number of line segments in the $k$th component of the contour should be less than or equal to nlines and greater than $0$. $k=⟨\mathit{\text{value}}⟩$, $\mathbf{nlcomp}\left[k-1\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.

On entry, the index of the first end point of line $⟨\mathit{\text{value}}⟩$ is $⟨\mathit{\text{value}}⟩$. It should be greater than or equal to $1$ and less than or equal to $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.

On entry, the index of the second end point of line $⟨\mathit{\text{value}}⟩$ is $⟨\mathit{\text{value}}⟩$. It should be greater than or equal to $1$ and less than or equal to $\mathbf{nlines}=⟨\mathit{\text{value}}⟩$.

On entry, the indices of the extremities of line $⟨\mathit{\text{value}}⟩$ are both equal to $⟨\mathit{\text{value}}⟩$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_MESH_ERROR

An error has occurred during the generation of the boundary mesh. It appears that nedmx is not large enough: $\mathbf{nedmx}=⟨\mathit{\text{value}}⟩$.

An error has occurred during the generation of the boundary mesh. It appears that nvmax is not large enough: $\mathbf{nvmax}=⟨\mathit{\text{value}}⟩$.

On entry, end point $1$, with index $\mathit{K}$, does not lie on the curve representing line $\mathit{I}$ with index $\mathit{J}$: $\mathit{K}=⟨\mathit{\text{value}}⟩$, $\mathit{I}=⟨\mathit{\text{value}}⟩$, $\mathit{J}=⟨\mathit{\text{value}}⟩$, $f\left(x,y\right)=⟨\mathit{\text{value}}⟩$.

On entry, end point $2$, with index $\mathit{K}$, does not lie on the curve representing line $\mathit{I}$ with index $\mathit{J}$: $\mathit{K}=⟨\mathit{\text{value}}⟩$, $\mathit{I}=⟨\mathit{\text{value}}⟩$, $\mathit{J}=⟨\mathit{\text{value}}⟩$, $f\left(x,y\right)=⟨\mathit{\text{value}}⟩$.

On entry, the geometric progression ratio between the points to be generated on line $⟨\mathit{\text{value}}⟩$ is $⟨\mathit{\text{value}}⟩$. It should be greater than $0$ unless the line segment is defined by user-supplied points.

On entry, there is a problem with either the coordinates of characteristic points, or with the definition of the mesh lines.

NE_NOT_CLOSE_FILE

Cannot close file $⟨\mathit{\text{value}}⟩$.

NE_NOT_WRITE_FILE

Cannot open file $⟨\mathit{\text{value}}⟩$ for writing.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (d06bace.c)

10.2  Program Data

Program Data (d06bace.d)

10.3  Program Results

Program Results (d06bace.r)