doc/parfum/mesh.tex

   1 {\it TERRY}
   2
   3 \subsection{Mesh Entities}
   4 \label{sec:entities}
   5
   6 {\it TERRY}
   7
   8 \subsubsection{Nodes}
   9 \label{sec:nodes}
  10
  11 {\it TERRY}
  12
  13 \subsubsection{Elements}
  14 \label{sec:elements}
  15
  16 {\it TERRY}
  17
  18 \subsubsection{Sparse Elements}
  19 \label{sec:sparse}
  20
  21 {\it TERRY}
  22
  23 \subsubsection{Mesh Entity Operations}
  24
  25 {\it TERRY}
  26
  27 \subsubsection{Mesh Entity Queries}
  28
  29 {\it TERRY}
  30
  31 \subsubsection{Advanced Mesh Entity Operations}
  32
  33 {\it TERRY}
  34
  35 \subsection{Meshes}
  36 \label{sec:meshes}
  37
  38 {\it TERRY}
  39
  40 \subsubsection{Basic Mesh Operations}
  41
  42 {\it TERRY}
  43
  44 \subsubsection{Mesh Utilities}
  45
  46 {\it TERRY}
  47
  48 \subsubsection{Advanced Mesh Operations}
  49
  50 {\it TERRY}
  51
  52 \subsection{Mesh Communication: Ghost Layers}
  53 \label{sec:ghost}
  54
  55 {\it SAYANTAN}
  56
  57 \subsubsection{Ghost Numbering}
  58
  59 {\it SAYANTAN}
  60
  61 \subsubsection{Ghost Layer Creation\label{SectionGhostLayerCreation}}
  62
  63 {\it SAYANTAN}
  64
  65 \subsubsection{Symmetries and Ghosts: Geometric Layer}
  66
  67 {\it SAYANTAN}
  68
  69 \subsubsection{Advanced Symmetries and Ghosts: Lower Layer}
  70
  71 {\it SAYANTAN}
  72
  73 \subsection{Older Mesh Operations}
  74
  75 {\it SAYANTAN}
  76
  77 \subsubsection{Mesh Data Operations}
  78
  79 {\it SAYANTAN}
  80
  81 \subsubsection{Ghost Numbering}
  82
  83 {\it SAYANTAN}
  84
  85 \subsubsection{Backward Compatability}
  86
  87 {\it SAYANTAN}
  88
  89 \subsubsection{Sparse Data}
  90
  91 {\it SAYANTAN}
  92
  93 \subsection{Mesh Modification}
  94
  95 {\it AARON}
  96
  97 \subsection{Topological Mesh Data}
  98
  99 A ParFUM application can request that the ParFUM framework compute topological adjacencies. All ParFUM applications initially specify the mesh as a set of elements, each element defined by a fixed number of nodes. ParFUM can compute and maintain other sets of adjacencies such as which elements are adjacent to a given node, or which nodes are adjacent(they are both associated with a single element), or which elements share an edge/face with another element. Currently only a single element type is supported, and that element must be \texttt{FEM\_ELEM+0}. To generate the structures storing the other types of adjacencies, each process in the ParFUM application should call the following subroutines:
 100
 101 \begin{list}{-}{}
 102 \item \texttt{FEM\_Add\_elem2face\_tuples(int mesh, 0, nodesPerFace, numFacesPerElement, faces);} specifies the topology of an element, specifically the configuration of its faces(if 3D) or edges(if 2D). Two elements are adjacent if they share a common face. The parameter faces is an integer array of length $nodesPerFace \cdot numFacesPerElement$. The description is the same as used for determining ghost layers in section \ref{SectionGhostLayerCreation}.
 103 \item \texttt{FEM\_Mesh\_allocate\_valid\_attr(int mesh, int entity\_type);}
 104 \item \texttt{FEM\_Mesh\_create\_node\_elem\_adjacency(int mesh);}
 105 \item \texttt{FEM\_Mesh\_create\_node\_node\_adjacency(int mesh);}
 106 \item \texttt{FEM\_Mesh\_create\_elem\_elem\_adjacency(int mesh);}
 107 \end{list}
 108
 109 These subroutines can be called in \texttt{init} on a sequential mesh, or after partitioning in \texttt{driver}. The adjacencies will contain references to ghost elements if the subroutines were called in \texttt{driver} when ghosts are used. The indexes to ghosts are negative integers which can easily be converted to positive indices by using the function \texttt{FEM\_To\_ghost\_index(id)}. The C header \texttt{ParFUM\_internals.h} is required to be included by the ParFUM application to access the adjacencies. The functions to access the adjacencies are in sections \ref{adjacencies-e2e},\ref{adjacencies-n2e}, and \ref{adjacencies-n2n}.
 110
 111 The internal data structures representing the adjacencies are maintained correctly when the adaptivity operations described in section \ref{Subsection-Mesh-Adaptivity} are used.
 112
 113 \subsubsection{Accessing Element to Element Adjacencies\label{adjacencies-e2e}}
 114
 115 \begin{list}{-}{}
 116 \item \texttt{void e2e\_getAll(int e, int *neighbors);} places all of element e's adjacent element ids in neighbors; assumes \texttt{neighbors} is already allocated to correct size
 117 \item \texttt{int e2e\_getNbr(int e, short idx);} returns the id of the idx-th adjacent element
 118 \end{list}
 119
 120
 121 \subsubsection{Accessing Node to Element Adjacencies\label{adjacencies-n2e}}
 122
 123 \begin{list}{-}{}
 124 \item \texttt{n2e\_getLength(int n)} returns the number of elements adjacent to the given node \texttt{n}.
 125 \item \texttt{n2e\_getAll(int n, int *\&adjelements, int \&sz)} for node \texttt{n} place all the ids for adjacent elements into \texttt{adjelements}. You can ignore sz if you correctly determine the length beforehand.
 126 \end{list}
 127
 128
 129 \subsubsection{Accessing Node to Node Adjacencies\label{adjacencies-n2n}}
 130
 131 \begin{list}{-}{}
 132 \item \texttt{n2n\_getLength(int n)} returns the number of nodes adjacent to the given node \texttt{n}.
 133 \item \texttt{n2n\_getAll(int n, int *\&adjnodes, int \&sz)} for node \texttt{n} place all the ids for adjacent nodes into \texttt{adjnodes}. You can ignore sz if you correctly determine the length beforehand.
 134 \end{list}
 135
 136
 137
 138
 139 \subsection{Mesh Adaptivity\label{Subsection-Mesh-Adaptivity}}
 140
 141
 142 \subsubsection{Initialization}
 143 If a ParFUM application wants to use parallel mesh adaptivity,
 144 the first task is to call the initialization routine from the
 145 {\it driver} function. This creates the node and element
 146 adjacency information that is essential for the adaptivity
 147 operations. It also initializes all the mesh adaptivity related
 148 internal objects in the framework.
 149
 150 \function{void FEM\_ADAPT\_Init(int meshID)}
 151 \index{femAdaptInit}
 152 \desc{Initializes the mesh defined by {\it meshID} for the mesh
 153 adaptivity operations.}
 154
 155 \subsubsection{Preparing the Mesh}
 156 For every element entity in the mesh, there is a desired size entry
 157 for each element. This entry is called meshSizing. This meshSizing entry
 158 contains a metric that determines element quality. The default metric is
 159 the average of the length of the three edges of an element. ParFUM provides
 160 various mechanisms to set this field. Some of the adaptive operations
 161 use these metrics to maintain quality. In addition, there is another metric
 162 which is computed for each element and maintained during mesh adaptivity. This metric
 163 is the ratio of the longest side to the shortest altitude, and this value
 164 is not allowed to go beyond a certain limit in order to maintain element quality.
 165
 166 \function{void FEM\_ADAPT\_SetElementSizeField(int meshID, int elem, double size);}
 167 \index{femAdaptSetElementSizeField1}
 168 \desc{For the mesh specified by {\it meshID}, for the element {\it elem},
 169 we set the desired size for each element to be {\it size}.}
 170
 171 \function{void FEM\_ADAPT\_SetElementSizeField(int meshID, double *sizes);}
 172 \index{femAdaptSetElementSizeField2}
 173 \desc{For the mesh specified by {\it meshID}, for the element {\it elem},
 174 we set the desired size for each element from the corresonponding entry in
 175 the {\it sizes} array.}
 176
 177 \function{void FEM\_ADAPT\_SetReferenceMesh(int meshID);}
 178 \index{femAdaptSetReferenceMesh}
 179 \desc{For each element int this mesh defined by {\it meshID}
 180 set its size to the average edge length of the corresponding element.}
 181
 182 \function{void FEM\_ADAPT\_GradateMesh(int meshID, double smoothness);}
 183 \index{femAdaptGradateMesh}
 184 \desc{Resize mesh elements to avoid jumps in element size.
 185 That is, avoid discontinuities in the desired sizes for elements of a mesh
 186 by smoothing them out. Algorithm based on h-shock correction, described in
 187 Mesh Gradation Control, Borouchaki et al.}
 188
 189
 190 \subsubsection{Modifying the Mesh}
 191 Once the elements in the mesh have been prepared by specifying their desired
 192 sizes, we are ready to use the actual adaptivity operations. Currently we
 193 provide delaunay flip operations, edge bisect operations and edge coarsen
 194 operations, all of which are implemented in parallel. We provide several higher level
 195 functions which use these basic operations to
 196 generate a mesh with higher quality elements while achieving the
 197 desired sizing.
 198
 199 \function{void FEM\_ADAPT\_Refine(int meshID, int qm, int method, double factor,double *sizes);}
 200 \index{femAdaptRefine}
 201 \desc{Perform refinements on the mesh specified by {\it meshId}.
 202 Tries to maintain/improve element quality by refining the mesh
 203 as specified by a quality measure {\it qm}.
 204 If {\it method} = 0, refine areas with size larger than {\it factor} down to {\it factor}
 205 If {\it method} = 1, refine elements down to sizes specified in the {\it sizes} array.
 206 In this array each entry corresponds to the corresponding element.
 207 Negative entries in sizes array indicate no refinement. }
 208
 209 \function{void FEM\_ADAPT\_Coarsen(int meshID, int qm, int method, double factor,double *sizes);}
 210 \index{femAdaptCoarsen}
 211 \desc{Perform refinements on the mesh specified by {\it meshId}.
 212 Tries to maintain/improve element quality by coarsening the mesh
 213 as specified by a quality measure {\it qm}.
 214 If {\it method} = 0, coarsen areas with size smaller than {\it factor} down to {\it factor}
 215 If {\it method} = 1, coarsen elements up to sizes specified in the {\it sizes} array.
 216 In this array each entry corresponds to the corresponding element.
 217 Negative entries in sizes array indicate no coarsening. }
 218
 219 \function{void FEM\_ADAPT\_AdaptMesh(int meshID, int qm, int method, double factor,double *sizes);}
 220 \index{femAdaptAdaptMesh}
 221 \desc{This function has the same set of arguments as required by the previous two operations,
 222 namely refine and coarsen. This function keeps using the above two functions until
 223 we have all elements in the mesh with as close to the desired quality. Apart from
 224 using the above two operations, it also performs a mesh repair operation which
 225 gets rid of some bad quality elements by delaunay flip or coarsening as the
 226 geometry in the area demands.}
 227
 228 \function{int FEM\_ADAPT\_SimpleRefineMesh(int meshID, double targetA, double xmin, double ymin, double xmax, double ymax);}
 229 \index{femAdaptSimpleRefineMesh}
 230 \desc{A region is defined by ({\it xmax, xmin, ymax, ymin})
 231 and the target area to be achieved for all elements in this region
 232 in the mesh specified by {\it meshID} is given by {\it targetA}.
 233 This function only performs a series of refinements on the elements in this region.
 234 If the area is larger, then no coarsening is done.}
 235
 236 \function{int FEM\_ADAPT\_SimpleCoarsenMesh(int meshID, double targetA, double xmin, double ymin, double xmax, double ymax);}
 237 \index{femAdaptSimpleCoarsenMesh}
 238 \desc{A region is defined by ({\it xmax, xmin, ymax, ymin})
 239 and the target area to be achieved for all elements in this region
 240 in the mesh specified by {\it meshID} is given by {\it targetA}.
 241 This function only performs a series of coarsenings on the elements in this region.
 242 If the area is smaller, then no refinement is done.}
 243
 244
 245 \subsection{Verifying correctness}
 246 We provide a checking function that can be used for debugging purposes to identify corrupted meshes or low quality elements.
 247
 248 \function{void FEM\_ADAPT\_TestMesh(int meshID);}
 249 \index{femAdaptTestMesh}
 250 \desc{This provides a series of tests to determine the consistency of the
 251 mesh specified by {\it meshID}.}