4
\section{Capabilities}\label{sec:caps}
5
The capabilities of \textsc{pamgen} are best understood by studying Section ~\ref{sec:specifying_a_mesh}, which documents in detail the instructions available for specifying a mesh. This section provides a brief overview of the library's capabilities. \textsc{pamgen} will be distributed as part of the \textsc{Trilinos} package of matrix and finite element tools.
7
\subsection{Dimensions}
8
\textsc{pamgen} can create both two and three dimensional meshes. It creates quadrilateral finite element meshes if two dimensions are specified, and it creates hexahedral finite element meshes if three dimensions are specified. For two dimensional quadrilateral meshes the Z component of nodal coordinates is not supplied.
10
\subsection{Mesh Geometries}
12
The \textsc{pamgen} library handles the mesh geometries shown below:
13
\begin{itemize}\addtolength{\itemsep}{-0.5\baselineskip}
15
\item Partial hollow cylinders
16
\item Complete hollow cylinders
17
\item Partial solid cylinders
18
\item Complete solid cylinders
24
\includegraphics[width=1.0in]{brick}
25
\includegraphics[width=1.0in]{cubit_radial1}
26
\includegraphics[width=1.0in]{cubit_radial2}
27
\includegraphics[width=1.0in]{cubit_radial_trisection}
28
\includegraphics[width=1.0in]{cubit_radial_trisection2}
29
\caption{The mesh geometry zoo in 3D.}
33
\subsection{Boundary Conditions}
34
Boundary conditions application regions in the form of node sets and side sets can be applied to the face, edge, or corner of any element block in the finite element mesh. They may also be applied to any face, edge, or corner of the entire mesh.
35
\subsection{Decomposition}
36
There are several mesh decomposition strategies available in \textsc{pamgen}:
37
\begin{itemize}\addtolength{\itemsep}{-0.5\baselineskip}
38
\item A default decomposition based on a constrained optimized solution that slices through the entire mesh in its three (or two in 2D) topological dimensions.
39
\item A user defined slicing strategy that specifies the number of slices through the mesh in each topological direction.
40
\item A sequential strategy that distributes elements beetween processors based on their element ids with the first n elements going to processor 0 ...
41
\item A random strategy that assigns element to processors randomly.
44
\subsection {Geometry Transformation}
45
Any mesh can be modified by re-evaluating the nodal coordinate values using a user-supplied function. This function has the original nodal coordinates as input values. Its output values define the new nodal coordinates.
51
\includegraphics[width=1.0in]{3d_warped_geometry_white_bg}
52
\includegraphics[width=1.0in]{mesh_warp_2d_white_bg}
53
\caption{Examples of geometry transformation.}
58
\subsection{Element Density}
59
Several of the geometry types allow specification of first and last element sizes within a block in a particular cartesian direction. In addition the user may control node distribution over any geometry by providing a user defined distribution function. This function is evaluated so that nodes are shifted towards areas where the function has its highest values.
62
\section{Approach}\label{sec:challenge}
63
\textsc{pamgen} operates on the premise that mesh generation is deterministic. This means that every execution of code compiled with compiler A and run on processor B under operating system C reading mesh instructions file D will produce an identical mesh. The mesh will have the same topology and the nodes will have the same coordinate locations. On a multi-processor machine of identical nodes an arbitrary number of processors executing identical instructions produce an identical mesh. Use of \textsc{pamgen} on heterogeneous machines may produce unexpected results.
65
With one significant exception, \textsc{pamgen} operates in the same way as these identical processors producing identical mesh. The exception is that each processor only allocates for a subset of the nodes and elements, and each processor performs topology and geometry calculations only for the entities and dependencies present on that processor. \textsc{pamgen} exploits the fact that each processor is capable of producing the entire mesh in order to allow each processor to produce its own mesh. The deterministic nature of the meshing process is essential to allow correspondence in topologies and geometries produced on adjacent processors.
67
The implementation of the mesh generation in \textsc{pamgen} is as much as possible implicit. Quantities are not allocated until they are ready for output, and they are not calculated until they can be stored, or until they are required by a dependent calculation. This approach can result in duplication of intermediate calculations, but it avoids the severe limitations on total problem size that occur if attempts are made to allocate any quantity with a size related to the total mesh size.
70
\section{Usage}\label{sec:usage}
71
For the few simple geometries and element types it supports, the \textsc{pamgen} library is a substitute for pre-processed finite element mesh files. Successful usage of the library requires some modification of the analysis code.
73
The \textsc{pamgen} library must be linked into the analysis executable to allow access to the mesh creation, query and deletion functions.
75
The modules in the analysis code that read finite element mesh data from a file must be adapted to:
76
\begin{itemize}\addtolength{\itemsep}{-0.5\baselineskip}
77
\item Read in a ``C''-progamming language string that specifices the geometry, topology, and boundary conditions of a mesh.
78
\item Pass that string to the \textsc{pamgen} Create\_Pamgen\_Mesh(...) function along with the rank of the mesh requested and the total number of processors across which the mesh is spread.
79
\item Handle message and possibly error strings available after calling Create\_Pamgen\_Mesh(...).
80
\item Call the \textsc{pamgen} query functions to populate the analysis code's mesh and communication data structures.
81
\item Call the \textsc{pamgen} Delete\_Pamgen\_Mesh() function release memory allocated within the library.
84
The source code for a stand-alone executable called ``pamgen\_lt\_c'' is distributed with the \textsc{pamgen} library. This example code is an excellent starting point for adapting an analysis code to use the \textsc{pamgen} library.
88
\section{Specifying a Mesh}\label{sec:specifying_a_mesh}
90
The ``C''-programming language string passed to \textsc{pamgen} is the complete definition of the mesh's geometry, topology, node sets, side sets, and parallel decomposition. It must begin with a \texttt{MESH} keyword, and it must end with an \texttt{END} keyword. The \texttt{MESH -- END} keyword pair must surround a \texttt{RECTILINEAR --
91
END}, \texttt{SPHERICAL -- END}, \texttt{BRICK -- END}, \texttt{RADIAL -- END}, \texttt{RADIAL TRISECTION -- END}, or \texttt{CYLINDRICAL -- END}
92
keyword pair and may have additional \texttt{SET ASSIGN -- END}, \texttt{DECOMPOSITION STRATEGY -- END},
93
\texttt{USER DEFINED ELEMENT DENSITY -- END}, or \texttt{USER DEFINED GEOMETRY TRANSFORMATION -- END} keyword pairs.
95
{\ttfamily \begin{verbatim}
97
{RECTILINEAR | SPHERICAL | BRICK | RADIAL | RADIAL TRISECTION | CYLINDRICAL}
102
[DECOMPOSITION STRATEGY]
104
[USER DEFINED GEOMETRY TRANSFORMATION]
106
[USER DEFINED ELEMENT DENSITY]
112
\subsection{Dimensionality}
113
\label{sec:dimensionality}
114
\index{Dimensionality}
115
The dimensionality of the mesh is not specified in the ``C'' programming language string. It is passed to the \textsc{pamgen} library at execution time through the \textsc{pamgen} API. In general a 2D mesh can be specified by removing 3D specific keywords and values (those referencing a third coordinate [for example Z or k]) from a 3D mesh description.
117
\subsection{Block IDs}
120
The finite elements created using \textsc{pamgen} are grouped into blocks. Each block has a positive non-zero id. These ids are automatically assigned by \textsc{pamgen} and are not under the control of the user. If there is a single block then its id is 1. When there are more than one block, the ids are assigned beginning with the block in the lowest topological position in i, j, k space. Subsequent blocks are incrementally numbered first in the i topological direction, next in the j topological direction, and finally in the k topological direction. In the case of \texttt{BRICK} and \texttt{RECTILINEAR} meshes i, j, and k correspond to the coordinate directions x, y, and z. In the case of \texttt{CYLINDRICAL}, \texttt{RADIAL}, and \texttt{RADIAL TRISECTION} meshes i, j, and k correspond to r, $\theta$, and z.
124
\subsection{Geometry and Topology}
125
\label{sec:inline-mesh}
126
\index{Geometry and Topology}
128
\subsubsection {Rectilinear}
130
{\ttfamily \begin{verbatim}
137
The \texttt{RECTILINEAR -- END} block pair surrounds the description
138
of the geometry of a rectilinear mesh. The extent
139
of the domain is given by a pair of vectors (gmin and gmax). The
140
number of blocks in each coordinate direction and the number of
141
elements in each block are given by additional keywords. The total
142
number of elements specified in this type of mesh is the
143
product of the total number of blocks \texttt{BX} $\times$ \texttt{BY}
144
$\times$ \texttt{BZ} and the total number of elements per block
145
\texttt{NX} $\times$ \texttt{NY} $\times$ \texttt{NZ}. For a 2D mesh
146
\texttt{NZ} and \texttt{BZ} must be omitted. The keywords associated
147
with the \texttt{RECTILINEAR} keyword are given in
148
Table~\ref{tab:inlinemesh-rectilinear}.
151
Keywords for \texttt{RECTILINEAR -- END}.
152
\label{tab:inlinemesh-rectilinear}
155
Sub-Keyword & Input & Description \\
158
\texttt{NX} & \texttt{int} &
159
Number of cells in x-direction. \\ \hline
160
\texttt{NY} & \texttt{int} &
161
Number of cells in y-direction. \\ \hline
162
\texttt{NZ} & \texttt{int} &
163
Number of cells in z-direction. \\ \hline
164
\texttt{BX} & \texttt{int} &
165
Number of blocks in the x-direction. \\ \hline
166
\texttt{BY} & \texttt{int} &
167
Number of blocks in the y-direction. \\ \hline
168
\texttt{BZ} & \texttt{int} &
169
Number of blocks in the z-direction. \\ \hline
170
\texttt{GMIN} & \texttt{vector} &
171
Minimum domain coordinates (x,y,z). \\ \hline
172
\texttt{GMAX} & \texttt{vector} &
173
Maximum domain coordinates (x,y,z). \\ \hline
176
An example of a mesh specification with the
177
\texttt{RECTILINEAR} option is illustrated in Figure~\ref{fig:rect_inline}.
183
\begin{minipage}[c]{0.5\linewidth}
185
{\ttfamily \begin{verbatim}
206
\begin{minipage}[c]{0.5\linewidth}
208
\includegraphics[width=3.25in]{rect_inline}
210
\caption{Definition of a three-dimensional \texttt{RECTILINEAR} mesh.}
211
\label{fig:rect_inline}
215
\subsubsection{Spherical}
217
{\ttfamily \begin{verbatim}
224
The \texttt{SPHERICAL -- END} block pair allows the description of a
225
curvilinear spherical mesh centered at the origin and described by an
226
inner and outer radius, and the extent of revolution in $\theta$ and $\phi$
227
directions. Angle $\theta$ is measured counter-clockwise about the z-axis from
228
the x-axis, and angle $\phi$ is measured counter-clockwise from the y-axis
229
about the x-axis. The number of elements and blocks in each
230
curvilinear coordinate direction are specified by the keywords in
231
Table~\ref{tab:inlinemesh-radial}. The parameters \texttt{PHI, NPHI,
232
and BPHI} are only appropriate for 3D problems. When used in 2D
233
simulations, \texttt{CYLINDRICAL} and \texttt{SPHERICAL} keywords
234
produce identical meshes.
237
Keywords for \texttt{SPHERICAL -- END}.
238
\label{tab:inlinemesh-radial}
241
Sub-Keyword & Input & Description \\
244
\texttt{NR} & \texttt{int} &
245
Number of cells in r-direction. \\ \hline
246
\texttt{NTHETA} & \texttt{int} &
247
Number of cells in $\theta$-direction. \\ \hline
248
\texttt{NPHI} & \texttt{int} &
249
Number of cells in $\phi$-direction. \\ \hline
250
\texttt{BR} & \texttt{int} &
251
Number of blocks in the r-direction. \\ \hline
252
\texttt{BTHETA} & \texttt{int} &
253
Number of blocks in $\theta$-direction. \\ \hline
254
\texttt{BPHI} & \texttt{int} &
255
Number of blocks in $\phi$-direction. \\ \hline
256
\texttt{RI} & \texttt{real} &
257
Inner radius \\ \hline
258
\texttt{RO} & \texttt{real} &
259
Outer radius \\ \hline
260
\texttt{THETA} & \texttt{real} &
261
Angular extent in $\theta$ (degrees,0.-180. in 3D, 0.-360. in 2D) \\ \hline
262
\texttt{PHI} & \texttt{real} &
263
Angular extent in $\phi$ (0.-360) \\ \hline
268
An example of a mesh definition syntax with the
269
\texttt{SPHERICAL} option is illustrated in
270
Figure~\ref{fig:test_radial} for a 2D simulation. An example of 3D
271
spherical mesh generation follows in
272
Figure~\ref{fig:str_inline_sphere}.
276
\begin{minipage}[c]{0.4\linewidth}
278
{\ttfamily \begin{verbatim}
293
\begin{minipage}[c]{0.6\linewidth}
295
\includegraphics[width=2.75in]{test_radial}
297
\caption{Definition of a two-dimensional spherical mesh.}
298
\label{fig:test_radial}
305
\begin{minipage}[c]{0.4\linewidth}
307
{\ttfamily \begin{verbatim}
325
\begin{minipage}[c]{0.6\linewidth}
327
\includegraphics[width=2.75in]{str_inline_sphere}
329
\caption{Definition of a three-dimensional spherical mesh.}
330
\label{fig:str_inline_sphere}
334
\subsubsection{Cylindrical}
336
{\ttfamily \begin{verbatim}
343
The \texttt{CYLINDRICAL -- END} block pair allows the description of a
344
curvilinear cylindrical mesh centered at the origin in x and y, and
345
aligned along the z-axis. It is described by an inner and outer
346
radius, the extent of revolution in angle $\theta$ about the z-axis,
347
and its start and end in the z-direction. Angle $\theta$ is measured
348
counter-clockwise about the z-axis from the x-axis. The number of
349
elements and blocks in each indicial direction are specified by the
350
keywords in Table~\ref{tab:inlinemesh-cylinder}. The parameters
351
\texttt{ZMIN, ZMAX, NZ, and BZ} are only appropriate for 3D
352
problems. When used in 2D solutions, \texttt{CYLINDRICAL} and
353
\texttt{SPHERICAL} produce identical meshes.
356
Keywords for \texttt{CYLINDRICAL -- END}.
357
\label{tab:inlinemesh-cylinder}
360
Sub-Keyword & Input & Description \\
363
\texttt{NR} & \texttt{int} &
364
Number of cells in r-direction. \\ \hline
365
\texttt{NTHETA} & \texttt{int} &
366
Number of cells in $\theta$-direction. \\ \hline
367
\texttt{NZ} & \texttt{int} &
368
Number of cells in z-direction. \\ \hline
369
\texttt{BR} & \texttt{int} &
370
Number of blocks in the r-direction. \\ \hline
371
\texttt{BTHETA} & \texttt{int} &
372
Number of blocks in $\theta$-direction. \\ \hline
373
\texttt{BZ} & \texttt{int} &
374
Number of blocks in z-direction. \\ \hline
375
\texttt{RI} & \texttt{real} &
376
Inner radius \\ \hline
377
\texttt{RO} & \texttt{real} &
378
Outer radius \\ \hline
379
\texttt{THETA} & \texttt{real} &
380
Angular extent in $\theta$ degrees, 0.-360. \\ \hline
381
\texttt{ZMIN} & \texttt{real} &
382
Start of mesh in z-direction \\ \hline
383
\texttt{ZMAX} & \texttt{real} &
384
End of mesh in z-direction \\ \hline
387
An example of a \textsc{pamgen} mesh definition with the
388
\texttt{CYLINDRICAL} option is illustrated in
389
Figure~\ref{fig:rect_cylinder}.
393
\begin{minipage}[c]{0.4\linewidth}
395
{\ttfamily \begin{verbatim}
413
\begin{minipage}[c]{0.6\linewidth}
415
\includegraphics[width=3.5in]{cylinder}
417
\caption{Three dimensional \texttt{CYLINDRICAL} mesh.}
418
\label{fig:rect_cylinder}
422
\subsubsection {Radial and Radial Trisection}
424
\index{Radial Trisection}
426
{\ttfamily \begin{verbatim}
427
{RADIAL | RADIAL TRISECTION }
428
[ENFORCE PERIODICITY]
429
[TRISECTION BLOCKS, int]
430
[TRANSITION RADIUS, int]
433
ZBLOCK int real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
434
{NUMR | NUMX} int INITIAL RADIUS real
435
RBLOCK int real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
437
ABLOCK int real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
442
The \texttt{RADIAL} and \texttt{RADIAL TRISECTION} block pairs allow the description of
444
curvilinear cylindrical mesh centered at the origin in x and y, and
445
aligned along the z-axis. The \texttt{RADIAL TRISECTION -- END}
446
block pair fills in the center of the cylindrical mesh with transition
447
elements. These options are similar to the \texttt{CYLINDRICAL}
448
but they have a different set of controls on element distribution. The
449
successful creation of these meshes requires sequential
450
specification of the information for the number of elements blocks and
451
their sizes in each coordinate direction.
453
The \texttt{ENFORCE PERIODICITY} keyword applies only to \texttt{RADIAL} and \texttt{RADIAL TRISECTION} mesh descriptions that meet certain requirements:
455
\item The meshes must have azimuthal angles of 90, 180, or 360 degrees.
456
\item The meshes must have a single block of elements in the azimuthal direction.
457
\item The meshes must have an even number of elements in each 90 degree segment of the mesh.
458
\item For \texttt{RADIAL TRISECTION} meshes, one transition zone is required for each 90 degrees of azimuth.
461
This keyword causes the mesh generation to perform all node coordinate calculations in the first 45 degrees of the azimuthal domain. Coordinate locations of nodes ouside of 45 degrees are formed by permuting the sign and oder of the components of periodically corresponding nodes' locations. This guarantees that there will be no differences between the absolute floating point values of periodically corresponding nodes' coordinates.
463
The \texttt{NUMZ | NUMR | NUMA} keywords are followed by an integer
464
specifying the number
465
of element blocks in that coordinate direction. The
466
\texttt{NUMR} line includes an additional real parameter that
467
specifies the inner radius of the cylindrical mesh. Specification of
468
an inner radius of 0.0 will result in degenerate elements with
469
co-located nodes along the \texttt{Z} axis. The innner radius
470
specification is ignored for \texttt{RADIAL TRISECTION} meshes.
472
Immediately following
473
the \texttt{NUMZ int | NUMR int INITIAL RADIUS real | NUMA int} lines, there must be a \texttt{ZBLOCK |
474
RBLOCK | ABLOCK} line for each of the blocks in that direction.
475
These lines specify the spatial extent of the particular block and the
476
distribution of elements in the block in that direction. The \texttt{INTERVAL int} keyword
477
specifies a fixed number of elements in the
478
block. A \texttt{FIRST SIZE real LAST SIZE real} pair specifies the absolute
479
size of the first and last elements in the block. When the \texttt{FIRST SIZE real LAST SIZE real} specification is
480
used, the element sizing will be linear between the first and last
481
elements. The sizes of the first and last elements may be
482
adjusted slightly to provide linear sizing. The approximate number of elements that will be generated using \texttt{FIRST SIZE} and \texttt{LAST SIZE} sizing controls is given by truncating to an integer, the length of the mesh segment divided by the average of the \texttt{FIRST SIZE} and \texttt {LAST SIZE} values. There is a slight chance that this calculation will result in a different number of elements on different computer platforms. Omission of the
483
\texttt{LAST real} keyword is equivalent to setting the element size
484
to that given by the \texttt{FIRST SIZE real} keyword.
486
The \texttt{RADIAL TRISECTION -- END} block pair requires the
487
additional input of \texttt{TRISECTION BLOCKS, int} and it accepts the
488
optional \texttt{TRANSITION RADIUS, real} keyword value pair. The
489
\texttt{TRISECTION BLOCKS} keyword specifies the number of transition
490
zones that will be used in the central region of the mesh. This
491
number must be supplied. One transition zone is recommended for each
492
90 degrees of azimuth. The \texttt{TRANSITION RADIUS} is the distance
493
from the origin to the corners of the transition zones of
494
mesh. Without this parameter the transition radius is chosen to be one
495
half of the radial thickness of the first block. When \texttt{RADIAL TRISECTION} is selected, any \texttt{INITIAL RADIUS} supplied is
498
The \texttt{ZMIN real} keyword value pair is available to specify an offset for the
499
entire mesh in the \texttt{Z} direction.
501
If the cumulative values of the sizes of the azimuthal blocks, given
502
by the second argument of \texttt{ABLOCK int real} is equal to 360.0 degrees, then the mesh
503
will form an single closed ring of elements.
506
An example of \textsc{pamgen} mesh definition with the
507
\texttt{RADIAL} option is illustrated in
508
Figure~\ref{fig:rect_cubit_radial}.
510
\begin{figure}[!thbp]
513
\begin{minipage}[c]{1.0\linewidth}
515
\includegraphics[width=3.0in]{cubit_radial1}
516
{\ttfamily \begin{verbatim}
520
zblock 1 10.0 first size 1 last size 2
521
zblock 2 10.0 first size 2 last size 1
522
numr 2 initial radius 1.
523
rblock 1 10. first size 1. last size 2.
524
rblock 2 10. first size 2. last size 1.
526
ablock 1 120. interval 10
531
\caption{Three dimensional \texttt{RADIAL} mesh.}
532
\label{fig:rect_cubit_radial}
537
A second example of \textsc{pamgen} mesh definition with the
538
\texttt{RADIAL} option is illustrated in
539
Figure~\ref{fig:rect_cubit_radial2}. In this case the sum of the
540
azimuthal blocks is 360.0 and the mesh is a
545
\begin{minipage}[c]{0.4\linewidth}
547
{\ttfamily \begin{verbatim}
551
zblock 1 10.0 interval 6
553
rblock 1 2. interval 12
554
rblock 2 5. interval 6
555
rblock 3 5. interval 12
557
ablock 1 360. interval 36
563
\begin{minipage}[c]{0.6\linewidth}
565
\includegraphics[width=3.0in]{cubit_radial2}
567
\caption [A 360 degree \texttt{RADIAL} mesh.]{Three dimensional \texttt{RADIAL} mesh with azimuthal
568
angle of 360 degrees.}
569
\label{fig:rect_cubit_radial2}
572
An example of a \textsc{pamgen} mesh definition with the
573
\texttt{RADIAL TRISECTION} option is illustrated in
574
Figure~\ref{fig:cubit_radial_trisect3}. This figure is annotated to
575
show the correspondence between input parameters and the
576
resulting mesh. This mesh uses a \texttt{TRISECTION BLOCKS} setting of 3. In this case the azimuthal
577
angle is 90. degrees and the \texttt{FIRST SIZE}, \texttt{LAST SIZE},
578
and \texttt{TRANSITION RADIUS} directives are used.
580
\begin{figure}[!thbp]
583
\begin{minipage}[c]{1.0\linewidth}
585
\includegraphics[width=5.5in,height=4.5in]{cubit_tris_rad_grad_trans}
586
{\ttfamily \begin{verbatim}
590
transition radius, 6.5
592
zblock 1 1. interval 1
594
rblock 1 8.0 interval 4
595
rblock 2 3.0 first size 0.05 last size 0.5
596
rblock 3 4.0 first size 0.5 last size 0.05
598
ablock 1 90. interval 12
603
\caption [A \texttt{RADIAL TRISECTION} mesh with three trisection blocks.]{A \texttt{RADIAL TRISECTION} mesh with azimuthal
604
angle of 90 degrees and three trisection blocks. \texttt{FIRST
605
SIZE} and \texttt{LAST SIZE} commands are used to specify
607
\label{fig:cubit_radial_trisect3}
610
An second example of a \textsc{pamgen} mesh definition with the
611
\texttt{RADIAL TRISECTION} option is illustrated in
612
Figure~\ref{fig:cubit_radial_trisect1}.
616
\begin{minipage}[c]{0.4\linewidth}
618
{\ttfamily \begin{verbatim}
624
zblock 1 1. interval 4
626
rblock 1 2.0 interval 4
627
rblock 2 3.0 interval 4
628
rblock 3 4.0 interval 4
630
ablock 1 90. interval 12
636
\begin{minipage}[c]{0.6\linewidth}
638
\includegraphics[width=3.0in]{cubit_radial_trisection}
640
\caption [A \texttt{RADIAL TRISECTION} mesh with three trisection blocks.] {Three dimensional \texttt{RADIAL TRISECTION} mesh with azimuthal
641
angle of 90 degrees and two trisection blocks.}
642
\label{fig:cubit_radial_trisect1}
646
A third example of a \textsc{pamgen} mesh definition with the
647
\texttt{RADIAL TRISECTION} option is illustrated in
648
Figure~\ref{fig:cubit_radial_trisect2}. In this case the azimuthal
649
angle is 360. degrees and the mesh is a complete circular disk.
653
\begin{minipage}[c]{0.4\linewidth}
655
{\ttfamily \begin{verbatim}
661
zblock 1 4. interval 4
663
rblock 1 2.0 interval 4
664
rblock 2 3.0 interval 4
665
rblock 3 5.0 interval 4
667
ablock 1 360. interval 32
673
\begin{minipage}[c]{0.6\linewidth}
675
\includegraphics[width=3.0in]{cubit_radial_trisection2}
677
\caption [A 360 degree \texttt{RADIAL TRISECTION} mesh.] {Three dimensional \texttt{RADIAL TRISECTION} mesh with azimuthal
678
angle of 360 degrees and four trisection blocks.}
679
\label{fig:cubit_radial_trisect2}
684
\subsubsection {Brick}
687
{\ttfamily \begin{verbatim}
690
ZBLOCK 1 real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
691
ZBLOCK 2 real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
694
ZBLOCK l real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
696
XBLOCK 1 real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
697
XBLOCK 2 real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
700
XBLOCK m real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
702
YBLOCK 1 real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
703
YBLOCK 2 real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
706
YBLOCK n real {INTERVAL int | FIRST SIZE real [LAST SIZE real]}
711
The \texttt{BRICK} mesh topology type is a more flexible version of the \texttt{RECTILINEAR} type in that it allows different numbers of elements in each element block in each coordinate direction. The creation of a
712
\texttt{BRICK} mesh is analogous to the \texttt{RADIAL} mesh option
714
successful creation of these meshes requires sequential
715
specification of the information for the number of elements blocks and
716
their sizes in each coordinate direction.
718
The \texttt{NUMX | NUMY | NUMZ} keywords are followed by an integer
719
specifying the number
720
of element blocks in that coordinate direction. The
722
Immediately following
723
the \texttt{NUMX int | NUMY int | NUMZ int} lines, there must be a \texttt{XBLOCK |
724
YBLOCK | ZBLOCK} line for each of the blocks in that direction. The first integer on this line corresponds to the ordinal (beginning with 1) of the line.
725
These lines specify the spatial extent of the particular block and the
726
distribution of elements in the block in that direction. The \texttt{INTERVAL int} keyword
727
specifies a fixed number of elements in the
728
block. A \texttt{FIRST SIZE real LAST SIZE real} pair specifies the absolute
729
size of the first and last elements in the block. When the \texttt{FIRST SIZE real LAST SIZE real} specification is
730
used, the element sizing will be linear between the first and last
731
elements. The sizes of the first and last elements may be
732
adjusted slightly to provide linear sizing. Omission of the
733
\texttt{LAST real} keyword is equivalent to setting the element size
734
to that given by the \texttt{FIRST SIZE real} keyword.
737
An example of a \textsc{pamgen} mesh definition with the
738
\texttt{BRICK} option is illustrated in
739
Figure~\ref{fig:brick1}.
743
\begin{minipage}[c]{0.4\linewidth}
745
{\ttfamily \begin{verbatim}
759
zblock 1 2. interval 5
760
zblock 2 8. interval 4
762
xblock 1 5.0 interval 5
763
xblock 2 5.0 interval 5
765
yblock 1 10. first size 1. last size .1
766
yblock 2 10. first size .1 last size 1.
772
\begin{minipage}[c]{0.6\linewidth}
774
\includegraphics[width=3.0in]{brick}
776
\caption{Three dimensional \texttt{BRICK} mesh.}
782
\subsection{Boundary Conditions (Nodesets and Sidesets)}
783
\label{sec:nodesets-sidests}
784
\index{Boundary Conditions}
789
{\ttfamily \small \begin{verbatim}
791
[{NODESET | SIDESET},{IHI | JHI | ... | V00 | V01 | ... | E00 |
792
E01 | ALL| ... }, int]
793
[{BLOCK SIDESET | BLOCK NODESET},{IHI | JHI | ... | V00 | V01 |
794
... | E00 | E01 | ... }, int, int]
800
The \texttt{SET ASSIGN -- END} keyword pair allows the specification
801
of nodesets and sidesets on the exterior of meshes. These
802
nodesets and sidesets can be used for specifying boundary conditions
803
on the domain. The nodeset or sideset is applied to the topological
804
face, edge, or vertex associated with the prescribed topological
805
direction. The mesh domain topology and associated labels are
806
shown in Figure~\ref{fig:set_assign_topology}.This specification
807
applies to the entire domain and cannot be used to
808
specifiy individual blocks.
810
The most commonly used sub-domains are the exterior faces of the
811
domain. They can be prescribed using \textsc {IHI, JHI, KHI, ILO,
812
JLO,} or \textsc {KLO}. For RECTILINEAR meshes \textsc {I,J,} and
813
\textsc {K} correspond to the coordinate directions x, y, and z. For
814
SPHERICAL meshes \textsc {I,J,} and \textsc {K} correspond to the
815
coordinate directions r, $\theta$, and $\phi$. For CYLINDRICAL meshes \textsc
816
{I,J,} and \textsc {K} correspond to the coordinate directions r,
817
$\theta$, and z. The \textsc {KHI, KLO} options do not exist in two
818
dimension simulations.
820
The \textsc{ALL} option for nodesets places all the nodes of the mesh in a
821
nodeset with the requested id. The \textsc{ALL} option is not available for
824
Specifying a nodeset on the \textsc{ILO} face of a \texttt{RADIAL TRISECTION} mesh
825
refers to the edge aligned with the Z axis (see Figure~\ref{fig:block_ss}).
826
Sidesets may not be specified on the \textsc{ILO} face of
827
\texttt{RADIAL TRISECTION} meshes.
830
{\ttfamily \small \begin{verbatim}
831
Side: 0-4-7-3 - ILO k 7---------6 Edge: 0-1 - E00
832
Side: 1-2-6-5 - IHI | /| j /| Edge: 1-2 - E01
833
Side: 0-1-5-4 - JLO |/ | / / | Edge: 3-2 - E02
834
Side: 3-7-6-2 - JHI 4---------5 | Edge: 0-3 - E03
835
Side: 0-3-2-1 - KLO | 3------|--2 Edge: 0-4 - E04
836
Side: 4-5-6-7 - KHI | / | / Edge: 1-5 - E05
837
|/ |/ Edge: 2-6 - E06
838
Vertex: 0 - V00 0---------1 --i Edge: 3-7 - E07
839
Vertex: 1 - V01 Edge: 4-5 - E08
840
Vertex: 2 - V02 Edge: 5-6 - E09
841
Vertex: 3 - V03 Edge: 7-6 - E10
842
Vertex: 4 - V04 Edge: 4-7 - E11
848
\caption{Block topology and labels.}
849
\label{fig:set_assign_topology}
852
\emph{BLOCK NODESETS and BLOCK SIDESETS are only available to the BRICK,
853
RADIAL, and RADIAL TRISECTION geometry mesh types.}
855
The \texttt{ [{BLOCK SIDESET | BLOCK NODESET},{ IHI | JHI | KHI | ILO | JLO |
856
KLO }, int, int]} command allows specification of nodesets and
857
sidesets on the topological faces of blocks that may be within the
858
finite element mesh. The first integer specifies the id that the
859
sideset or nodeset will have, the second integer specifies the block
860
on which the sideset or nodeset is applied.
862
An example of \texttt{BLOCK SIDESET} applied to a mesh definition with the
863
\texttt{RADIAL TRISECTION} option is illustrated in
864
Figure~\ref{fig:block_ss}. In this example a sidet is applied to the
865
\texttt{IHI} face of block 2. The sideset applied to block 2 will
866
have sideset id 45. The faces called out in these sidesets will have
867
outward normals facing in the \texttt{IHI} direction.
871
\begin{minipage}[c]{0.4\linewidth}
873
{\ttfamily \begin{verbatim}
879
zblock 1 1. interval 4
881
rblock 1 2.0 interval 4
882
rblock 2 3.0 interval 4
883
rblock 3 4.0 interval 4
885
ablock 1 90. interval 12
889
block sideset, ihi, 45, 2
895
\begin{minipage}[c]{0.6\linewidth}
897
\includegraphics[width=3.0in]{block_ss}
899
\caption [A \texttt{RADIAL TRISECTION} mesh with sidesets.] {Three dimensional \texttt{RADIAL TRISECTION} mesh with azimuthal
900
angle of 90 degrees and two trisection blocks having sidesets
901
specified on the radially outward directed faces of blocks 1 and 2. A nodeset is specified on the \textsc{ILO} face of this mesh and marks the edge corresponding to the z axis (blue circles).}
906
\subsection{User Defined Geometry Transformation}
907
\label{sec:inline-geometry-transform}
908
\index{User Defined Geometry Transformation}
911
{\ttfamily \small \begin{verbatim}
912
USER DEFINED GEOMETRY TRANSFORMATION
914
user supplied `C' language instructions;
920
The \texttt{USER DEFINED GEOMETRY TRANSFORMATION -- END} keyword pair provides
921
a powerful way to modify the coordinats of any node of a mesh. The keyword-end
922
pair must surround a double quote surrounded block of `C' code. This code will be called with coordinates of every node in the mesh. It may modify the the coordinats by setting the output variables \texttt{outxcoord}, \texttt{outycoord}, and \texttt{outzcoord}. The unmodified values of the node's coordinates are available in the input variables \texttt{inxcoord}, \texttt{inycoord}, and \texttt{inzcoord}. The coordinates will remain unchanged if the output variables are not modified. A presentation of the capabilities and
923
limitations of runtime compiled 'C' functions is included in
924
Appendix~\ref{sec:runtime-compiler-functionality}.
926
Examples of meshes produced using this capability feature of \textsc{pamgen} are shown below in Figure~\ref{fig:3d_transform_example} and Figure~\ref{fig:2d_transform_example}. In the first example the nodes with positive Z coordinate values are rotated about the Z axis an angle propportional to their distance from the Z=0 plane. In the second example nodes a distance of 0.5 from the origin are rotated about the origin in proportion to their distance from the origin.
930
\begin{minipage}{0.3\linewidth}
931
{\ttfamily \begin{verbatim}
946
gmin = -1.0 -1.0 -1.0
949
user defined geometry transformation
951
double r = sqrt(inxcoord*inxcoord+inycoord*inycoord);
952
double theta = atan2(inycoord,inxcoord);
955
theta = theta + (3.14159 / 4.0)*(inzcoord/1.0);
956
r = r*(1.0-inzcoord/1.1);
957
outxcoord = r*cos(theta);
958
outycoord = r*sin(theta);
966
\begin{minipage}[t]{0.65\linewidth}
968
\includegraphics[width=4.8in]{3d_warped_geometry_white_bg}
970
\caption [3D Geometry Transformation Example]{3D mesh illustrating the ability to modify nodal coordinates using \texttt{USER
971
DEFINED GEOMETRY TRANSFORMATION}.}
972
\label{fig:3d_transform_example}
978
\begin{minipage}{0.3\linewidth}
979
{\ttfamily \begin{verbatim}
999
user defined geometry transformation
1001
double r = sqrt(inxcoord*inxcoord+inycoord*inycoord);
1002
double theta = atan2(inycoord,inxcoord);
1005
theta = theta + (3.14159 / 4.0)*((r-0.5)/0.5);
1006
outxcoord = r*cos(theta);
1007
outycoord = r*sin(theta);
1015
\begin{minipage}[t]{0.65\linewidth}
1017
\includegraphics[width=3.8in]{mesh_warp_2d_white_bg}
1019
\caption [2D Geometry Transformation Example]{2D mesh illustrating the ability to modify nodal coordinates using \texttt{USER
1020
DEFINED GEOMETRY TRANSFORMATION}.}
1021
\label{fig:2d_transform_example}
1026
\subsection{User Defined Element Density}
1027
\label{sec:inline-element-density}
1028
\index{User Defined Element Density}
1031
{\ttfamily \small \begin{verbatim}
1032
USER DEFINED ELEMENT DENSITY, {I|J|K}
1034
user supplied `C' language instructions;
1040
The \texttt{USER DEFINED ELEMENT DENSITY -- END} keyword pair provides
1041
a flexible way to bias \texttt{RECTILINEAR},
1042
\texttt{SPHERICAL}, and \texttt{CYLINDRICAL} meshes. The keyword-end
1043
pair must surround a double quote surrounded block of `C' code that
1044
evaluates on the input variable \texttt{coord} and sets the return
1045
value \texttt{field}. The return value \texttt{field} must be set to a
1046
positive value across the range of the mesh in the selected
1047
topological direction. A presentation of the capabilities and
1048
limitations of runtime compiled 'C' functions is included in
1049
Appendix~\ref{sec:runtime-compiler-functionality}.
1051
The mesh biasing adjusts the nodal coordinates such that the density
1052
of the elements in a region of the mesh in the selected coordinate
1053
direction is proportional to the value of \texttt{field} relative to
1054
the integral of \texttt{field} across the mesh domain. This is
1055
implemented by numerically solving the equation given below. In this
1056
equation \begin {math} x _ i \end {math} is the coordinate of node
1057
\begin {math} i \end {math}, \begin {math} n \end {math} is the total
1058
number of nodes in the coordinate direction, and \begin {math} f(u)
1059
\end {math} is the user supplied function.
1062
\frac {\int _ {0} ^ {x _ i} f(u)du } {\int _ {0} ^ {x _ n} f(u)du }
1066
When these functions are applied to a two dimensional
1067
\texttt{RECTILINEAR} mesh spanning from $(0.0, 0.0)$ to $(1.0, 1.0)$ and
1068
having two blocks and 10 elements in both the 'I', and 'J' directions,
1069
the resulting mesh is graded as shown in
1070
Figure~\ref{fig:bias_example}. The grading is a continuous
1071
exponential function in the 'I' direction and is a discontinuous
1072
function in the 'J' direction. In the 'J' direction the domain
1073
stretching from 0.0 to 0.5 has twice the element density as the range
1077
Diagnostic information for the user provided functions is included in
1078
the \texttt{runid.out} file. This information includes the total
1079
integrated value of the function, the minimum and maximum value of the
1080
function, and a plot of the function's values across the range of
1083
\begin{figure}[htbp]
1085
\begin{minipage}{0.5\linewidth}
1086
{\ttfamily \begin{verbatim}
1087
user defined element density, i
1089
field = 1.*exp(-5.*(coord));
1092
user defined element density, j
1095
if(coord < 0.5) { field = 2;}
1096
if(coord >= 0.5) { field = 1;}
1102
\begin{minipage}{0.45\linewidth}
1104
\includegraphics[width=2.8in]{bias_example}
1106
\caption{2D mesh created with a \texttt{USER
1107
DEFINED ELEMENT DENSITY}.}
1108
\label{fig:bias_example}
1111
\renewcommand{\textfraction}{0.2}
1112
\renewcommand{\topfraction}{0.7}
1113
\renewcommand{\bottomfraction}{0.3}
1114
\renewcommand{\floatpagefraction}{0.5}
1117
\subsection{Decomposition Strategy}
1118
\label{sec:inline-decomposition-strategy}
1119
\index{Decomposition Strategy}
1121
{\ttfamily \begin{verbatim}
1122
DECOMPOSITION STRATEGY
1125
{NUMPROCS, I, int (1)}
1126
{NUMPROCS, J, int (1)}
1127
{NUMPROCS, K, int (1)}
1135
An optional \texttt{DECOMPOSITION STRATEGY -- END} block pair surrounds the description
1136
of the decomposition method used for parallel simulations. The default strategy is \texttt{BISECTION}. The keywords associated
1137
with the \texttt{DECOMPOSITION STRATEGY} keyword are given in
1138
Table~\ref{tab:inlinemesh-decomp_strat}.
1141
Keywords for \texttt{DECOMPOSITION STRATEGY -- END}.
1142
\label{tab:inlinemesh-decomp_strat}
1145
Sub-Keyword & Input & Description \\
1148
\smallskip \texttt{BISECTION} & &
1149
Recursively bisect domain making slices calculated to assign nearly equal numbers of elements to each processor. This option is the default. \\ \hline \smallskip
1150
\begin{minipage} [c]{1.0\linewidth} \setlength{\parindent}{0.1in} \noindent \texttt{PROCESSOR LAYOUT} \\ \indent \texttt{NUMPROCS \{I|J|K\}}, int (1) \\ \texttt{END} \end{minipage} & \texttt{int} (1)&
1151
Invokes a decomposition strategy that slices up the mesh in accordance with the request of the user. The integer value value is number of segments into which the mesh should be divided in
1152
the given direction. The product of the number of segments requested in each direction must equal the number of processors. \\ \hline
1153
\smallskip \texttt{SEQUENTIAL} & &
1154
Invokes a decomposition strategy that distributes the elements between processors in sequential order. If there are k elements and n processors an average of k/n elements will go to each processor. \emph{This decomposition strategy is not for large simulations and is intended mainly for testing and verification purposes.} \\ \hline
1155
\smallskip \texttt{RANDOM} & &
1156
Invokes a decomposition strategy that randomly distributes the elements between processors. It results in tremendous communications overhead. \emph{This decomposition strategy is not for production simulations and is intended mainly for testing and verification purposes.}\\ \hline
1159
The \texttt{BISECTION} decomposition strategy is the default for parallel calculations. This is
1160
because it is robust in providing decompositions and the resulting
1161
regions have satisfactory surface area to volume ratios. This strategy
1162
attempts to automatically determine the number of slices to make through
1163
the entire mesh domain to provide an equal number of elements to each processor. This strategy will be most successful when the number of processors, and the number of elements in each direction are a power of 2 or a product of several prime numbers.
1165
The \texttt{PROCESSOR LAYOUT} decomposition strategy offers the user
1166
improved control of the distribution of elements to each
1167
processor in a parallel simulation. The strategy divides the mesh into the number of segments specified by the keyword-value pair for each coordinate direction. The number of
1168
processors must equal the product of the values given for each of the
1169
\texttt{NUMPROCS} directions. The default value for a coordinate direction is one.
1171
When using a \texttt{RADIAL TRISECTION} mesh the number of processors in the \texttt{I} (radial) direction is fixed at 1, and the total number of processors must be equal to the
1172
product of the values given for the \texttt{J} and \texttt{K}
1173
\texttt{NUMPROCS} directions. For this mesh type the decomposition
1174
assigns elements from the inner transition blocks to the processor
1175
that owns the adjacent elements in the outer cylinderical blocks.
1176
An example of the \texttt{PROCESSOR LAYOUT} decomposition option
1177
applied to a \texttt{RADIAL TRISECTION} mesh is shown in Figure \ref{fig:tri_dec}.
1179
Examples of \texttt{BISECTION} and
1180
\texttt{PROCESSOR LAYOUT} decomposition options applied to a mesh definition with the
1181
\texttt{RADIAL} option are shown below in
1182
Figures~\ref{fig:dec_bis} and
1183
\ref{fig:dec_pl}. The total
1184
number of elements in this problem was 204, 17 in the radial or
1185
\texttt{I} direction and 12 in the azimuthal or \texttt{J} direction.
1187
For the \texttt{BISECTION} decomposition the recursive cuts made on
1188
the 17x12x1 array of elements results in three processors with 3x12x1 elements,
1189
four processors with 2x12x1
1190
elements and a single processor 6x8x1 elements.
1192
For the \texttt{PROCESSOR LAYOUT} decomposition the
1193
17 elements in the \texttt{I} or radial direction are divided by 4 to
1194
set the size of segments produced in that direction at 4. The first segment's size is increased by one to handle the remainder of dividing 14 by 4. This decomposition would equally
1195
distribute elements to each processor if the \texttt{I} direction had a number of
1196
elements evenly divisible by 4.
1198
\begin{figure}[htbp]
1200
\begin{minipage}[c]{0.4\linewidth}
1202
{\ttfamily \begin{verbatim}
1206
zblock 1 10.0 interval 1
1207
numr 4 initial radius 1.
1208
rblock 1 2. interval 3
1209
rblock 2 4. interval 3
1210
rblock 3 6. interval 5
1211
rblock 4 8. interval 6
1213
ablock 1 60. interval 12
1215
decomposition strategy
1222
\begin{minipage}[c]{0.6\linewidth}
1224
\includegraphics[width=2.0in]{bisect_7_white}
1226
\caption [\texttt{BISECTION} decomposition run on 7 processors.] {Three dimensional \texttt{RADIAL} mesh with azimuthal
1227
angle of 60 degrees run on 7 processors using \texttt{BISECTION} decomposition.}
1232
\begin{figure}[htbp]
1234
\begin{minipage}[c]{0.4\linewidth}
1236
{\ttfamily \begin{verbatim}
1240
zblock 1 10.0 interval 1
1241
numr 4 initial radius 1.
1242
rblock 1 2. interval 3
1243
rblock 2 4. interval 3
1244
rblock 3 6. interval 5
1245
rblock 4 8. interval 6
1247
ablock 1 60. interval 12
1249
decomposition strategy
1257
\begin{minipage}[c]{0.6\linewidth}
1259
\includegraphics[width=2.0in]{numprocs_8}
1261
\caption [\texttt{PROCESSOR LAYOUT} decomposition run on 8 processors.] {Three dimensional \texttt{RADIAL} mesh with azimuthal
1262
angle of 60 degrees run on 8 processors using \texttt{PROCESSOR LAYOUT} decomposition.}
1265
\begin{figure}[htbp]
1267
\begin{minipage}[c]{0.4\linewidth}
1269
{\ttfamily \begin{verbatim}
1272
trisection blocks, 4
1274
zblock 1 4.0 interval 1
1276
rblock 1 2. interval 4
1277
rblock 2 3. interval 4
1278
rblock 3 5. interval 4
1280
ablock 1 360. interval 32
1282
decomposition strategy
1289
\begin{minipage}[c]{0.6\linewidth}
1291
\includegraphics[width=2.0in]{trisection_decomp}
1293
\caption [\texttt{PROCESSOR LAYOUT} decomposition on 8 processors.] {Three dimensional \texttt{RADIAL TRISECTION} mesh run on 8 processors using \texttt{PROCESSOR LAYOUT} decomposition.}
1299
\section{Library Interface}\label{sec:execution_steps}
1300
\subsection{Creating a Mesh}
1301
Mesh creation proceeds through a single function call. Additional functions are available to access messages generated during the mesh creation.
1302
\subsubsection{Create\_Pamgen\_Mesh}
1303
{\ttfamily \begin{verbatim}
1304
int Create_Pamgen_Mesh( char * file_char_array,
1309
This function creates a representation of the mesh for the processor of the specified rank out of the total num\_procs. It returns an enumerated value. A return value of \textbf{ERROR\_FREE\_CREATION
1310
} signifies success. A return value of \textbf{ERROR\_CREATING\_IMD} significes an error in the specification of the mesh geometry, topology, or boundary conditions. A return value of \textbf{ERROR\_CREATING\_MS} significes an error in allocating and populating the arrays that store the mesh geometry and topology. A return value of \textbf{ERROR\_PARSING\_DEFINITION} significes an error occurred while parsing the string passed in file\_char\_array. The details of the syntax error are recoverable by subsequent calls.
1314
\setlength{\parindent}{0pt}
1316
\textbf{char *file\_char\_array}
1317
This input variable points to a null terminated string that holds a terse description of the desired mesh. This form of this description is given in a later section.
1319
\textbf{int dimension}
1320
This input variable indicates the dimension of the desired mesh. Acceptable values are 2 (quadrilaterals created in x,y plane) and 3 (hexahedral elements created in 3 space).
1323
This input variable may range from 0 to one less than num\_procs. It specifies for which processor the mesh is being generated.
1325
\textbf{int num\_procs}
1326
This input variable must be greater than 0. It specifes the total number of processors across which the mesh is decomposed.
1329
\subsubsection{getPamgenEchoStreamSize}
1330
{\ttfamily \begin{verbatim}
1331
int getPamgenEchoStreamSize(void);
1334
This function returns the size of the string (not counting termination character) that contains an echo of the \textbf{char * file\_char\_array} string previously passed to Create\_Pamgen\_Mesh. If a parsing error occurred, this string will be annotated with a summary of the error. Use of this function and subsequent access and display of this string is highly recommended if the value pointed to by \textbf{int * parse\_error\_count} is non-zero on return.
1336
\subsubsection{getPamgenEchoStream}
1337
{\ttfamily \begin{verbatim}
1338
char * getPamgenEchoStream(char * echo_stream_pointer);
1340
This function takes a character pointer and returns that same pointer after it has been filled.
1342
{\setlength{\parindent}{0pt}
1343
\textbf{char *echo\_stream\_pointer} This input variable must point to allocated memory big enough to hold the the results of ``getEchoStreamSize(void)'' plus a termination character.
1346
\subsubsection{getPamgenErrorStreamSize}
1347
{\ttfamily \begin{verbatim}
1348
int getPamgenErrorStreamSize(void);
1350
This function returns the size of an error string associated with a return value of \textbf{ERROR\_CREATING\_MS} from Create\_Pamgen\_Mesh.
1353
\subsubsection{getPamgenErrorStream}
1354
{\ttfamily \begin{verbatim}
1355
char * getPamgenErrorStream(char * error_stream_pointer);
1357
This function takes a character pointer and returns that same pointer after it has been filled.
1359
{\setlength{\parindent}{0pt}
1360
\textbf{char *error\_stream\_pointer} This input variable must point to allocated memory big enough to hold the the results of getErrorStreamSize plus a termination character.
1364
\subsubsection{getPamgenWarningStreamSize}
1365
{\ttfamily \begin{verbatim}
1366
int getPamgenWarningStreamSize(void);
1368
This function returns the size of a string containing warnings generated within the Create\_Pamgen\_Mesh function.
1370
\subsubsection{getPamgenWarningStream}
1371
{\ttfamily \begin{verbatim}
1372
char * getPamgenWarningStream(char * warning_stream_pointer);
1374
This function takes a character pointer and returns that same pointer after it has been filled.
1376
{\setlength{\parindent}{0pt}
1377
\textbf{char *warning\_stream\_pointer} This input variable must point to allocated memory big enough to hold the the results of getWarningStreamSize plus a termination character.
1380
\subsubsection{getPamgenInfoStreamSize}
1381
{\ttfamily \begin{verbatim}
1382
int getPamgenInfoStreamSize(void);
1384
This function returns the size of a string containing information messages generated within the Create\_Pamgen\_Mesh function. These messages include information such as the total number of elements in the mesh, the total number of nodes in the mesh, and the mesh distribution based on decomposition.
1386
\subsubsection{getPamgenInfoStream}
1387
{\ttfamily \begin{verbatim}
1388
char * getPamgenInfoStream(char * info_stream_pointer);
1390
This function takes a character pointer and returns that same pointer after it has been filled.
1392
{\setlength{\parindent}{0pt}
1393
\textbf{char *info\_stream\_pointer} This input variable must point to allocated memory big enough to hold the the results of getInfoStreamSize plus a termination character.
1396
\subsection{Querying a Mesh}
1397
All of the mesh query and access functions are based on the \texttt{EXODUS II} ~\cite{Schoof-Yarberry:1995} and \texttt{NEMESIS} ~\cite{Hennigan-StJohn-Shadid:1998} APIs. These APIs were written to standardize a platform independent interface for writing and reading binary mesh specification files. \texttt{NEMESIS} is a parallel extension of the serial \texttt{EXODUS II} API. The \textsc{pamgen} function names are formed by prefixing the \texttt{EXODUS II} or \texttt{NEMESIS} function name with \textbf{im\_}. The remainder of the function signature and functionality remains unchanged. It may help to note that the original \texttt{EXODUS II} functions begin with \textbf{ex\_}, and the original \texttt{NEMESIS} functions begin with \textbf{ne\_}.
1399
Querying a mesh database to build up a complete representation in accessible memory is a straightforward process. Typically a query function is used to ascertain the number of items in an array, then memory is allocated and passed in through an access function which fills the memory with the requested information. The query and access functions will be presented in the same order they appear in the example function ``read\_mesh\_to\_memory()'' shown in Appendix~\ref{sec:read-mesh-to-memory}.
1402
\subsubsection{im\_ex\_get\_init}
1403
{\ttfamily \begin{verbatim}
1404
int im_ex_get_init( int exoid,
1411
int *num_side_sets);
1413
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. The number of nodes, elements, element blocks is limited to those entities local to the rank processor for which the mesh was created. It returns a non-zero value if an error occurs.
1415
{\setlength{\parindent}{0pt}
1416
\textbf{int exoid} An unused input variable.\par
1417
\textbf{char *title} A title string containing ``PAMGEN Inline Mesh''.\par
1418
\textbf{char *num\_dim} On return points to the number of coordinates per node (2 or 3).\par
1419
\textbf{char *num\_nodes} On return points to the number of nodes.\par
1420
\textbf{char *num\_elem} On return points to the number of elements.\par
1421
\textbf{char *num\_elem\_blk} On return points to the number of element blocks.\par
1422
\textbf{char *num\_node\_sets} On return points to the number of node sets.\par
1423
\textbf{char *num\_side\_sets} On return points to the number of side sets.\par
1426
\subsubsection{im\_ex\_inquire}
1427
{\ttfamily \begin{verbatim}
1428
int im_ex_inquire( int exoid,
1432
char * char_array_value);
1434
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. This is a general purpose query function that takes an enumerated query value and changes the value pointed to by int\_value, float\_value, or char\_array\_value depending on the data requested by the query\_value. It returns a non-zero value in case of error. Im\_ex\_inquire supports the following query values:
1435
\begin{itemize}\addtolength{\itemsep}{-0.5\baselineskip}\renewcommand{\labelitemi}{}
1436
\item \textbf{IM\_EX\_INQ\_NS\_NODE\_LEN} The length of the concatenated nodeset list is returned in int\_value.
1437
\item \textbf{IM\_EX\_INQ\_NS\_DF\_LEN} The length of the concatenated nodeset distribution list is returned in int\_value.
1438
\item \textbf{IM\_EX\_INQ\_SS\_ELEM\_LEN} The length of the concatenated sidesets element list is returned in int\_value.
1439
\item \textbf{IM\_EX\_INQ\_SS\_NODE\_LEN} The aggregate length of the sideset nodes is returned in int\_value.
1440
\item \textbf{IM\_EX\_INQ\_SS\_DF\_LEN } The length of the concatenated side sets distribution factor is returned in int\_alue.
1441
\item \textbf{IM\_EX\_INQ\_API\_VERS} The API version is returned in float\_value.
1442
\item \textbf{IM\_EX\_INQ\_EB\_PROP} The number of element block properties is returned in int\_value.
1443
\item \textbf{IM\_EX\_INQ\_NS\_PROP} The number of node sets properties is returned in int\_value.
1444
\item \textbf{IM\_EX\_INQ\_SS\_PROP} The number of side set properties is returned in int\_value.
1445
\item \textbf{IM\_EX\_INQ\_QA} The number of QA records is returned in int\_value.
1446
\item \textbf{IM\_EX\_INQ\_INFO} The number of INFO records is returned in int\_value.
1450
\subsubsection{im\_ex\_get\_coord}
1451
{\ttfamily \begin{verbatim}
1452
int im_ex_get_coord( int exoid,
1457
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. This function takes pointers to memory allocated to a length equal to the number of nodes local to the processor and fills in the nodal coordinate values. A non-zero return value indicates an error.
1459
{\setlength{\parindent}{0pt}
1460
\textbf{int exoid} Unused input variable.}
1462
{\setlength{\parindent}{0pt}
1463
\textbf{double * x\_coors} Returned X coordinates of the nodes.}
1465
{\setlength{\parindent}{0pt}
1466
\textbf{double * y\_coors} Returned Y coordinates of the nodes.}
1468
{\setlength{\parindent}{0pt}
1469
\textbf{double * z\_coors} Returned Z coordinates of the nodes (if num\_dim = 3).}
1472
\subsubsection{im\_ex\_get\_coord\_names}
1473
{\ttfamily \begin{verbatim}
1474
int im_ex_get_coord_names( int exoid,
1475
char ** coord_names);
1477
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It returns the names of the coordinates. A non-zero return indicates an error.
1479
{\setlength{\parindent}{0pt}
1480
\textbf{int exoid} Unused input variable.}
1482
{\setlength{\parindent}{0pt}
1483
\textbf{char ** coord\_names} Returned vector pointing to num\_dim coord names. \textbf{coord\_names} can be declared and allocated as shown below.}
1484
{\ttfamily \begin{verbatim}
1485
char* coord_names[3];
1486
for(int i = 0; i < num_dim; i++)
1487
coord_names[i] = (char*)calloc((MAX_STR_LENGTH+1),sizeof(char));
1490
\subsubsection{im\_ex\_get\_map}
1491
{\ttfamily \begin{verbatim}
1492
int im_ex_get_map( int exoid,
1495
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It loads the global element numbers into the provided storage. A non-zero return value indicates an error.
1497
{\setlength{\parindent}{0pt}
1498
\textbf{int exoid} Unused input variable.}
1500
{\setlength{\parindent}{0pt}
1501
\textbf{int * element\_map} On return this array holds the global element ids of the elements local to this processor. For a serial problem this runs sequentially from 1 to num\_elem. Memory sized to num\_elem must be allocated prior to making this call.}
1503
\subsubsection{im\_ex\_get\_elem\_num\_map}
1504
{\ttfamily \begin{verbatim}
1505
int im_ex_get_elem_num_map( int exoid,
1506
int * element_num_map);
1508
For \textsc{pamgen} this function is identical to ``im\_ex\_get\_map''.
1510
{\setlength{\parindent}{0pt}
1511
\textbf{int exoid} Unused input variable.}
1513
{\setlength{\parindent}{0pt}
1514
\textbf{int * element\_num\_map} On return this array holds the global element ids of the elements local to this processor. For a serial problem these values run sequentially from 1 to num\_elem. Memory sized to num\_elem must be allocated prior to making this call.}
1516
\subsubsection{im\_ex\_get\_node\_num\_map}
1517
{\ttfamily \begin{verbatim}
1518
int im_ex_get_node_num_map( int exoid,
1519
int * node_num_map);
1521
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It loads the global node numbers into the provided storage. A non-zero return indicates an error.
1523
{\setlength{\parindent}{0pt}
1524
\textbf{int exoid} Unused input variable.}
1526
{\setlength{\parindent}{0pt}
1527
\textbf{int * node\_num\_map} On return this array holds the global node ids of the nodes local to this processor. For a serial problem this runs from 1 to num\_nodes. Memory sized to num\_nodes must be allocated prior to making this call.}
1529
\subsubsection{im\_ex\_get\_elem\_blk\_ids}
1530
{\ttfamily \begin{verbatim}
1531
int im_ex_get_elem_blk_ids( int exoid,
1532
int * elem_blk_ids);
1534
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It loads the element block ids into the provided storage. A non-zero return value indicates an error.
1536
{\setlength{\parindent}{0pt}
1537
\textbf{int exoid} Unused input variable.}
1539
{\setlength{\parindent}{0pt}
1540
\textbf{int * elem\_blk\_ids} On return this array holds the ids of the element blocks on this processor. For \textsc{pamgen} meshes the element block ids across the entire problem will run sequentially from 1 to num\_elem\_blk. On any particular processor of a parallel mesh any set of the global element blocks may be present. Storage sized to num\_elem\_blk must be allocated prior to making this call.}
1542
\subsubsection{im\_ex\_get\_elem\_block}
1543
{\ttfamily \begin{verbatim}
1544
int im_ex_get_elem_block( int exoid,
1547
int * num_elem_this_blk,
1548
int * num_nodes_per_elem,
1551
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It provides information about the requested element block. Review of the conventions documented in the \texttt{EXODUS II} manual is the most effective way to understand the mesh storage and retrieval. Under the \texttt{EXODUS II} convention, a finite element mesh is composed of one or more blocks of elements. Each block contains elements of the same type. Within a block, all elements have the same number of nodes and the same connectivity convention. The number of nodes is stored explicitly, and the connectivity convention is called out by a string. This string corresponds to a table of conventional element connectivities in the \texttt{EXODUS II} manual. A non-zero return value indicates an error.
1553
{\setlength{\parindent}{0pt}
1554
\textbf{int exoid} Unused input variable.}
1556
{\setlength{\parindent}{0pt}
1557
\textbf{int elem\_blk\_id} Input variable specifying the id of the block for which information is requested. This id must be one of the values in the elem\_blk\_ids array.}
1559
{\setlength{\parindent}{0pt}
1560
\textbf{char * elem\_type} On return this variable holds one of the standard \texttt{EXODUS II} element types as a string. The element\_type pointer must be allocated as length MAX\_STR\_LENGTH+1. For \textsc{pamgen} the stored value will be QUAD in 2D or HEX in 3D.}
1562
{\setlength{\parindent}{0pt}
1563
\textbf{int * num\_elem\_this\_blk} On return this variable holds the number of elements in this block. }
1565
{\setlength{\parindent}{0pt}
1566
\textbf{int * num\_nodes\_per\_elem} On return this variable holds the number of nodes per element for the elements in this block. }
1568
{\setlength{\parindent}{0pt}
1569
\textbf{int * num\_attr} On return this variable holds the number of attributes for this block for \textsc{pamgen} this is always 0. }
1571
\subsubsection{im\_ex\_get\_elem\_conn}
1572
{\ttfamily \begin{verbatim}
1573
int im_ex_get_elem_conn( int exoid,
1577
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It fills the storage pointed to by connect with the connectivity of the elements in the block referred to by elem\_blk\_id. A non-zero return value indicates an error.
1579
{\setlength{\parindent}{0pt}
1580
\textbf{int exoid} Unused input variable.}
1582
{\setlength{\parindent}{0pt}
1583
\textbf{int elem\_blk\_id} Input variable specifying the id of the block for which information is requested. This id must be one of the values in the elem\_blk\_ids array.}
1585
{\setlength{\parindent}{0pt}
1586
\textbf{int * connect} On return the storage pointed to by \textbf{connect} holds the connectivity for the requested block. \textbf{Connect} must point to storage sized to num\_elem\_this\_block*num\_nodes\_per\_elem. \textbf{Connect} holds (in the order specified by the \texttt{EXODUS II} convention) the nodes of each element in the specified block. The first element's connectivity begins at an offset of 0 and the nth element's connectivity begins at an offset of n*num\_nodes\_per\_element. The \texttt{EXODUS II} standard specifies that the indices of the connectivity are numbered from 1 so that in order to retrieve the coordinates of an element's nodes the indices given in \textbf{connect} must be decrimented by 1.}
1588
\subsubsection{im\_ex\_get\_node\_set\_ids}
1589
{\ttfamily \begin{verbatim}
1590
int im_ex_get_node_set_ids( int exoid,
1591
int * node_set_ids);
1593
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It loads the node set ids into the provided storage. Node set ids are specified in the string passed to the Create\_Pamgen\_Mesh function. By convention they must be non-zero and positive. A non-zero return value indicates an error.
1595
{\setlength{\parindent}{0pt}
1596
\textbf{int exoid} Unused input variable.}
1598
{\setlength{\parindent}{0pt}
1599
\textbf{int * node\_set\_ids} On return this array holds the ids of the node sets on this processor. Storage sized to num\_node\_sets must be allocated prior to making this call.}
1602
\subsubsection{im\_ex\_get\_node\_set\_param}
1603
{\ttfamily \begin{verbatim}
1604
int im_ex_get_node_set_param( int exoid,
1606
int * num_nodes_in_node_set,
1607
int * num_df_in_node_set);
1609
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It function provides sizing information for node set data. A non-zero return value indicates an error.
1611
{\setlength{\parindent}{0pt}
1612
\textbf{int exoid} Unused input variable.}
1614
{\setlength{\parindent}{0pt}
1615
\textbf{int node\_set\_id} Input variable specifying the id of the node set for which information is requested. This id must be one of the values in the node\_set\_ids array.}
1617
{\setlength{\parindent}{0pt}
1618
\textbf{int * num\_nodes\_in\_node\_set} On return this variable is set to the number of nodes in the specified node set.}
1620
{\setlength{\parindent}{0pt}
1621
\textbf{int * num\_df\_in\_node\_set} On return this variable is set to the number of df in the specified node set. Distribution factors are scalar values linked to the members of node sets or side sets. \textsc{pamgen} does not produce any distribution factors on node sets or side sets. For \textsc{pamgen} this will be 0.}
1624
\subsubsection{im\_ex\_get\_node\_set}
1625
{\ttfamily \begin{verbatim}
1626
int im_ex_get_node_set( int exoid,
1628
int * node_set_node_list);
1630
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. On return the provided storage is populated with the local nodes of the node set.
1632
{\setlength{\parindent}{0pt}
1633
\textbf{int exoid} Unused input variable.}
1635
{\setlength{\parindent}{0pt}
1636
\textbf{int node\_set\_id} Input variable specifying the id of the node set for which information is requested. This id must be one of the values in the node\_set\_ids array.}
1638
{\setlength{\parindent}{0pt}
1639
\textbf{int * node\_set\_node\_list} On return this array holds the local ids of the nodes in the node set. The ids are numbered from 1. Storage must be sized for num\_nodes\_in\_nodeset.}
1642
\subsubsection{im\_ex\_get\_side\_set\_ids}
1643
{\ttfamily \begin{verbatim}
1644
int im_ex_get_side_set_ids( int exoid,
1645
int * side_set_ids);
1647
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It loads the side set ids into the provided storage. Side set ids are specified in the string passed to the Create\_Pamgen\_Mesh function. By convention they must be non-zero and positive. A non-zero return value indicates an error.
1649
{\setlength{\parindent}{0pt}
1650
\textbf{int exoid} Unused input variable.}
1652
{\setlength{\parindent}{0pt}
1653
\textbf{int * side\_set\_ids} On return this array holds the ids of the side sets on this processor. Storage sized to num\_side\_sets must be allocated prior to making this call.}
1656
\subsubsection{im\_ex\_get\_side\_set\_param}
1657
{\ttfamily \begin{verbatim}
1658
int im_ex_get_side_set_param( int exoid,
1660
int * num_sides_in_side_set,
1661
int * num_df_in_side_set);
1663
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It provides sizing information for side set data. A non-zero return value indicates an error.
1665
{\setlength{\parindent}{0pt}
1666
\textbf{int exoid} Unused input variable.}
1668
{\setlength{\parindent}{0pt}
1669
\textbf{int side\_set\_id} Input variable specifying the id of the side set for which information is requested. This id must be one of the values in the side\_set\_ids array.}
1671
{\setlength{\parindent}{0pt}
1672
\textbf{int * num\_sides\_in\_side\_set} On return this variable is set to the number of sides in the specified side set.}
1674
{\setlength{\parindent}{0pt}
1675
\textbf{int * num\_df\_in\_side\_set} On return this variable is set to the number of df in the specified side set. Distribution factors are scalar values linked to the members of node sets or side sets. \textsc{pamgen} does not produce any distribution factors on node sets or side sets. For \textsc{pamgen} this will be 0.}
1680
\subsubsection{im\_ex\_get\_side\_set}
1681
{\ttfamily \begin{verbatim}
1682
int im_ex_get_side_set( int exoid,
1684
int * side_set_element_list,
1685
int * side_set_side_list);
1687
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It populates storage that specifies the sides of elements that are in a particular side set. The \texttt{EXODUS II} convention specifies a side by listing an element id and the side of that element that is in the sideset. This information is provided in two corresponding arrays of equal length. The sides specify a set of nodes on the element by reference to element topology tables in the \texttt{EXODUS II} manual. A non-zero return value indicates an error.
1689
{\setlength{\parindent}{0pt}
1690
\textbf{int exoid} Unused input variable.}
1692
{\setlength{\parindent}{0pt}
1693
\textbf{int side\_set\_id} Input variable specifying the id of the side set for which information is requested. This id must be one of the values in the side\_set\_ids array.}
1695
{\setlength{\parindent}{0pt}
1696
\textbf{int * side\_set\_element\_list} On return this array holds the local ids of the elements having sides in the side set. Storage must be sized for num\_sides\_in\_sideset.}
1698
{\setlength{\parindent}{0pt}
1699
\textbf{int * side\_set\_side\_list} On return this array holds the sides that are in the side set. Storage must be sized for num\_sides\_in\_sideset.}
1702
\subsubsection{im\_ex\_get\_qa}
1703
{\ttfamily \begin{verbatim}
1704
int im_ex_get_qa( int exoid,
1705
char * qa_record[][4]);
1707
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It populates previously allocated qa\_record storage with Quality Assurance (QA) information. By convention the four components of each record are:
1709
\begin{enumerate}\addtolength{\itemsep}{-0.5\baselineskip}
1710
\item The analysis code name\par
1711
\item The analysis code QA descriptor\par
1712
\item The analysis time
1713
\item The analysis date
1715
\textsc{pamgen} will return ``PAMGEN'', ``Parallel Mesh Generator'' and then two copies of the date and time. A non-zero return value indicates an error.
1717
{\setlength{\parindent}{0pt}
1718
\textbf{int exoid} Unused input variable.}
1720
{\setlength{\parindent}{0pt}
1721
\textbf{char * qa\_record[][4]} Previously allocated storage that is filled with QA records. The memory may be allocated as shown below.}
1722
{\ttfamily \begin{verbatim}
1723
char * qa_record[10][4];
1724
for(int i = 0; i < 10; i++)
1725
for(int j=0; j<4; j++) qa_record[i][j] = (char*)malloc(MAX_STR_LENGTH+1);
1728
\subsubsection{im\_ex\_get\_info}
1729
{\ttfamily \begin{verbatim}
1730
int im_ex_get_info( int exoid,
1731
char ** info_record);
1733
This function is based on the \texttt{EXODUS II} API and is concerned only with serial information. It populates previously allocated info\_record storage. A non-zero return value indicates an error.
1735
{\setlength{\parindent}{0pt}
1736
\textbf{int exoid} Unused input variable.}
1738
{\setlength{\parindent}{0pt}
1739
\textbf{char ** info\_record} Previously allocated storage into which info records are copied. At present for \textsc{pamgen} num\_info\_records is zero. Memory should would be allocated as shown below.}
1740
{\ttfamily \begin{verbatim}
1741
char ** info_record;
1742
info_record = (char**)malloc(num_info_records*sizeof(char*));
1743
for(int i = 0; i < num_info_records; i++)
1744
info_record[i] = (char*)malloc(MAX_STR_LENGTH+1);
1747
\subsubsection{im\_ne\_get\_init\_global}
1748
This function is adapted from the \texttt{NEMESIS} API. It is typically the first function called when gathering information about the parallel nature of the mesh. It retrieves the mesh sizing information for the complete mesh. A non-zero return value indicates an error.
1749
{\ttfamily \begin{verbatim}
1750
int im_ne_get_init_global( int neid,
1751
int *num_nodes_global,
1752
int *num_elems_global,
1753
int *num_elem_blks_global,
1754
int *num_node_sets_global,
1755
int *num_side_sets_global );
1758
{\setlength{\parindent}{0pt}
1759
\textbf{int neid} Unused input variable.}
1761
{\setlength{\parindent}{0pt}
1762
\textbf{int * num\_nodes\_global} On return this variable is set to the total number of nodes in the mesh.}
1764
{\setlength{\parindent}{0pt}
1765
\textbf{int * num\_elems\_global} On return this variable is set to the total number of elements in the mesh.}
1767
{\setlength{\parindent}{0pt}
1768
\textbf{int * num\_elem\_blks\_global} On return this variable is set to the total number of element blocks in the mesh.}
1770
{\setlength{\parindent}{0pt}
1771
\textbf{int * num\_node\_sets\_global} On return this variable is set to the total number of node sets in the mesh.}
1773
{\setlength{\parindent}{0pt}
1774
\textbf{int * num\_side\_sets\_global} On return this variable is set to the total number of side sets in the mesh.}
1777
\subsubsection{im\_ne\_get\_init\_info}
1778
This function is adapted from the \texttt{NEMESIS} API. It retrieves information about the decomposition of the mesh. A non-zero return value indicates an error.
1779
{\ttfamily \begin{verbatim}
1780
int im_ne_get_init_info( int neid,
1782
int *num_proc_in_file,
1786
{\setlength{\parindent}{0pt}
1787
\textbf{int neid} Unused input variable.}
1789
{\setlength{\parindent}{0pt}
1790
\textbf{int *num\_proc} On return this variable is filled with the total number of processors over which the mesh is spread.}
1792
{\setlength{\parindent}{0pt}
1793
\textbf{int *num\_proc\_in\_file} On return this variable is filled with the number of processors for which mesh is available via query. This value will always be 1 when using \textsc{pamgen}.}
1795
{\setlength{\parindent}{0pt}
1796
\textbf{char *file\_type} Unused variable should be sized as shown below.}
1798
\begin{verbatim}char file_type [2];\end{verbatim}}
1800
\subsubsection{im\_ne\_get\_eb\_info\_global}
1801
{\ttfamily \begin{verbatim}
1802
int im_ne_get_eb_info_global( int neid,
1803
int *el_blk_ids_global,
1804
int *el_blk_cnts_global);
1806
This function is adapted from the \texttt{NEMESIS} API. It retrieves the element block ids from the entire mesh as well as the sizes of each of these element blocks. A non-zero return value indicates an error.
1808
{\setlength{\parindent}{0pt}
1809
\textbf{int neid} Unused input variable.}
1811
{\setlength{\parindent}{0pt}
1812
\textbf{int *el\_blk\_ids\_global} On return this array holds the element block ids for the entire mesh. It must be sized to hold num\_elem\_blks\_global integers.}
1814
{\setlength{\parindent}{0pt}
1815
\textbf{int *el\_blk\_cnts\_global} On return this array holds the number of elements in each element block of the entire mesh. It must be sized to hold num\_elem\_blks\_global integers.}
1819
\subsubsection{im\_ne\_get\_ns\_param\_global}
1820
{\ttfamily \begin{verbatim}
1821
int im_ne_get_ns_param_global(int neid,
1823
int *ns_n_cnt_global,
1824
int *ns_df_cnt_global);
1826
This function is adapted from the \texttt{NEMESIS} API. It retrieves node set information for the entire mesh. A non-zero return value indicates an error.
1828
{\setlength{\parindent}{0pt}
1829
\textbf{int neid} Unused input variable.}
1831
{\setlength{\parindent}{0pt}
1832
\textbf{int *ns\_ids\_global} On return this array holds the node set ids for the entire mesh. It must be sized to hold num\_node\_sets\_global integers.}
1834
{\setlength{\parindent}{0pt}
1835
\textbf{int *ns\_n\_cnt\_global} On return this array holds the number of nodes in each node set for the entire mesh. It must be sized to hold num\_node\_sets\_global integers.}
1837
{\setlength{\parindent}{0pt}
1838
\textbf{int *ns\_df\_cnt\_global} On return this array holds the number of node set distribution factors for the entire mesh. It must be sized to hold num\_node\_sets\_global integers. For \textsc{pamgen} the number of distribution factors for each node set will be 0.}
1842
\subsubsection{im\_ne\_get\_ss\_param\_global}
1843
{\ttfamily \begin{verbatim}
1844
int im_ne_get_ss_param_global(int neid,
1846
int *ss_s_cnt_global,
1847
int *ss_df_cnt_global);
1849
This function is adapted from the \texttt{NEMESIS} API. It retrieves side set information for the entire mesh. A non-zero return value indicates an error.
1851
{\setlength{\parindent}{0pt}
1852
\textbf{int neid} Unused input variable.}
1854
{\setlength{\parindent}{0pt}
1855
\textbf{int *ss\_ids\_global} On return this array holds the side set ids for the entire mesh. It must be sized to hold num\_side\_sets\_global integers.}
1857
{\setlength{\parindent}{0pt}
1858
\textbf{int *ss\_s\_cnt\_global} On return this array holds the number of sides in each side set for the entire mesh. It must be sized to hold num\_side\_sets\_global integers.}
1860
{\setlength{\parindent}{0pt}
1861
\textbf{int *ss\_df\_cnt\_global} On return this array holds the number of side set distribution factors for the entire mesh. It must be sized to hold num\_side\_sets\_global integers. For \textsc{pamgen} the number of distribution factors for each side set will be 0.}
1863
\subsubsection{im\_ne\_get\_loadbal\_param}
1864
{\ttfamily \begin{verbatim}
1865
int im_ne_get_loadbal_param( int neid,
1866
int *num_internal_nodes,
1867
int num_border_nodes,
1868
int *num_external_nodes,
1869
int *num_internal_elems,
1870
int *num_border_elems,
1871
int *num_node_cmaps,
1872
int *num_elem_cmaps,
1875
This function is adapted from the \texttt{NEMESIS} API. On return its arguments are filled with sizing information for processor communication data. This information is the first step in gathering all the information required to construct communication protocols between adjacent regions of decomposed mesh. A non-zero return value indicates an error.
1877
{\setlength{\parindent}{0pt}
1878
\textbf{int neid} Unused input variable.}
1880
{\setlength{\parindent}{0pt}
1881
\textbf{int * num\_internal\_nodes} On return this variable is filled with the number of nodes that are local to the mesh on this processor.}
1883
{\setlength{\parindent}{0pt}
1884
\textbf{int * num\_border\_nodes} On return this variable is filled with the number of nodes that are common to the mesh on this processor and to adjacent processors.}
1886
{\setlength{\parindent}{0pt}
1887
\textbf{int * num\_external\_nodes} On return this variable is filled with the number of nodes that are not local to this processor but are common to elements that share nodes with this processor.}
1889
{\setlength{\parindent}{0pt}
1890
\textbf{int * num\_internal\_elems} On return this variable is filled with the number of elements that are local to this processor.}
1892
{\setlength{\parindent}{0pt}
1893
\textbf{int * num\_border\_elems} On return this variable is filled with the number of elements that are not local to this processor but do share nodes with elements local to this processor.}
1895
{\setlength{\parindent}{0pt}
1896
\textbf{int * num\_node\_cmaps} On return this variable is filled with the number of node communication maps.}
1898
{\setlength{\parindent}{0pt}
1899
\textbf{int * num\_elem\_cmaps} On return this variable is filled with the number of element communication maps.}
1901
{\setlength{\parindent}{0pt}
1902
\textbf{int proc} Unused input variable.}
1905
\subsubsection{im\_ne\_get\_elem\_map}
1906
{\ttfamily \begin{verbatim}
1907
int im_ne_get_elem_map( int neid,
1913
This function is adapted from the \texttt{NEMESIS} API. On return the the arguments of this function are populated with the internal and boundary element maps.
1915
{\setlength{\parindent}{0pt}
1916
\textbf{int neid} Unused input variable.}
1918
{\setlength{\parindent}{0pt}
1919
\textbf{int * elem\_mapi} On return this variable is filled with the internal element ids. Storage sized to num\_internal\_elems must be supplied.}
1921
{\setlength{\parindent}{0pt}
1922
\textbf{int * elem\_mapb} On return this variable is filled with the border element ids. Storage sized to num\_border\_elems must be supplied. }
1924
{\setlength{\parindent}{0pt}
1925
\textbf{int proc} Unused input variable.}
1928
\subsubsection{im\_ne\_get\_node\_map}
1929
{\ttfamily \begin{verbatim}
1930
int im_ne_get_node_map( int neid,
1937
This function is adapted from the \texttt{NEMESIS} API. On return the the arguments of this function are populated with the internal and boundary node maps.
1939
{\setlength{\parindent}{0pt}
1940
\textbf{int neid} Unused input variable.}
1942
{\setlength{\parindent}{0pt}
1943
\textbf{int * node\_mapi} On return this variable is filled with the internal node ids. Storage sized to num\_internal\_nodes must be supplied.}
1945
{\setlength{\parindent}{0pt}
1946
\textbf{int * node\_mapb} On return this variable is filled with the border node ids. Storage sized to num\_border\_nodes must be supplied. }
1948
{\setlength{\parindent}{0pt}
1949
\textbf{int * node\_mape} On return this variable is filled with the external node ids. Storage sized to num\_external\_nodes must be supplied. }
1952
{\setlength{\parindent}{0pt}
1953
\textbf{int proc} Unused input variable.}
1956
\subsubsection{im\_ne\_get\_cmap\_params}
1957
{\ttfamily \begin{verbatim}
1958
int im_ne_get_cmap_params( int neid,
1960
int *node_cmap_node_cnts,
1962
int *elem_cmap_elem_cnts,
1965
This function is adapted from the \texttt{NEMESIS} API. On return the storage passed in its arguments is filled with the communication map ids and counts. A non-zero return value indicates an error.
1967
{\setlength{\parindent}{0pt}
1968
\textbf{int neid} Unused input variable.}
1970
{\setlength{\parindent}{0pt}
1971
\textbf{int * node\_cmap\_ids} On return this storage is filled with the ids for each node communication map. Storage sized to num\_node\_cmap must be provided.For \textsc{pamgen} these values will run from 0 to num\_node\_cmaps-1.}
1973
{\setlength{\parindent}{0pt}
1974
\textbf{int * node\_cmap\_cnts} On return this storage is filled with the number of nodes in each node communication map. Storage sized to num\_node\_cmap must be provided.}
1976
{\setlength{\parindent}{0pt}
1977
\textbf{int * elem\_cmap\_ids} On return this storage is filled with the ids for each element communication map. Storage sized to num\_elem\_cmap must be provided. For \textsc{pamgen} these values will run from 0 to num\_elem\_cmaps-1.}
1979
{\setlength{\parindent}{0pt}
1980
\textbf{int * elem\_cmap\_elem\_cnts} On return this storage is filled with the number of elements in each element communication map. Storage sized to num\_elem\_cmap must be provided. }
1982
{\setlength{\parindent}{0pt}
1983
\textbf{int proc} Unused input variable.}
1985
\subsubsection{im\_ne\_get\_node\_cmap}
1986
{\ttfamily \begin{verbatim}
1987
int im_ne_get_node_cmap( int neid,
1993
This function is adapted from the \texttt{NEMESIS} API. On return the storage passed in its arguments is filled with the node communication maps. A non-zero return value indicates an error.
1995
{\setlength{\parindent}{0pt}
1996
\textbf{int neid} Unused input variable.}
1998
{\setlength{\parindent}{0pt}
1999
\textbf{int map\_ids} The id of the node communication map that is being queried. This must be one of the entries in node\_cmap\_ids.}
2001
{\setlength{\parindent}{0pt}
2002
\textbf{int * node\_ids} On return this storage is filled with the ids of nodes in the map. Storage must be sized to node\_cmap\_cnts[map\_id]. }
2004
{\setlength{\parindent}{0pt}
2005
\textbf{int * proc\_ids} The processor id onto which the associated node in node\_ids maps. Storage must be sized to node\_cmap\_cnts[map\_id].}
2007
{\setlength{\parindent}{0pt}
2008
\textbf{int proc} Unused input variable.}
2010
\subsubsection{im\_ne\_get\_elem\_cmap}
2011
{\ttfamily \begin{verbatim}
2012
int im_ne_get_elem_cmap( int neid,
2019
This function is adapted from the \texttt{NEMESIS} API. On return the storage passed in its arguments is filled with the element communication maps. A non-zero return value indicates an error.
2021
{\setlength{\parindent}{0pt}
2022
\textbf{int neid} Unused input variable.}
2024
{\setlength{\parindent}{0pt}
2025
\textbf{int map\_ids} The id of the element communication map that is being queried.This must be one of the entries in elem\_cmap\_ids.}
2027
{\setlength{\parindent}{0pt}
2028
\textbf{int * elem\_ids} On return this storage is filled with the ids of elements in the map. Storage must be sized to elem\_cmap\_cnts[map\_id]. }
2030
{\setlength{\parindent}{0pt}
2031
\textbf{int * side\_ids} On return this storage is filled with the ids sides of elements in the map. Storage must be sized to elem\_cmap\_cnts[map\_id]. }
2033
{\setlength{\parindent}{0pt}
2034
\textbf{int * proc\_ids} The processor id onto which the associated element in elem\_ids maps. Storage must be sized to elem\_cmap\_cnts[map\_id].}
2036
{\setlength{\parindent}{0pt}
2037
\textbf{int proc} Unused input variable.}
2040
\subsection{Deleting a Mesh}
2042
\subsubsection{Delete\_Pamgen\_Mesh}
2043
{\ttfamily \begin{verbatim}
2044
int Delete_Pamgen_Mesh(void);
2046
This function clears and deletes the memory used to store mesh data created with the ``Create\_Pamgen\_Mesh(...)'' function. After this function is called ``Create\_Pamgen\_Mesh(...)'' may be called again to create a different mesh.
added
removed
packages/pamgen/doc/sand_report/pamgen_mesh.tex
