msgQ: comment out debug if/throw
[charm.git] / doc / fem / parfum.tex
1 \section{ParFUM}
2 \label{sec:ParFUM}
3
4 ParFUM is the name for the latest version of FEM. 
5 ParFUM includes additional features including parallel 
6 mesh modification and adaptivity (geometrical).  ParFUM also contains 
7 functions which generate additional topological adjacency 
8 information.  ParFUM cannot be built separate from \charmpp{} 
9 since it uses various messaging mechanisms that MPI does 
10 not readily support. It is important to note that ParFUM adaptivity
11 at the moment has some limitations. It works only for meshes which 
12 are two-dimensional. The other limitation is that the mesh on which 
13 it works on must have one layer of node-deep ghosts. Most applications 
14 reqire no or one layer ghosts, so it is really not a limitation,
15 but for applications that need multiple layers of ghost information,
16 the adaptivity operations cannot be used.
17
18
19 \subsection{Adaptivity Initialization}
20 If a FEM application wants to use parallel mesh adaptivity,
21 the first task is to call the initialization routine from the 
22 {\it driver} function. This creates the node and element 
23 adjacency information that is essential for the adaptivity 
24 operations. It also initializes all the mesh adaptivity related
25 internal objects in the framework.
26
27 \function{void FEM\_ADAPT\_Init(int meshID)}
28 \index{femAdaptInit}
29 \desc{Initializes the mesh defined by {\it meshID} for the mesh
30 adaptivity operations.}
31
32
33
34
35 \subsection{Preparing the Mesh for Adaptivity}
36 For every element entity in the mesh, there is a desired size entry 
37 for each element. This entry is called meshSizing. This meshSizing entry 
38 contains a metric that decides the element quality. The default metric is
39 the average of the size of the three edges of an element. This section 
40 provides various mechanisms to set this field. Some of the adaptive operations
41 actually use these metrics to maintain quality. Though there is another metric
42 which is computer for each element and maintained on the fly and that 
43 is the ratio of the largest length to the smallest altitude and this value 
44 during mesh adaptivity is not allowed to go beyond a certain limit. Because
45 the larger this value after a cecrtain limit, the worse the element quality.
46
47 \function{void FEM\_ADAPT\_SetElementSizeField(int meshID, int elem, double size);}
48 \index{femAdaptSetElementSizeField1}
49 \desc{For the mesh specified by {\it meshID}, for the element {\it elem},
50 we set the desired size for each element to be {\it size}.}
51
52 \function{void FEM\_ADAPT\_SetElementSizeField(int meshID, double *sizes);}
53 \index{femAdaptSetElementSizeField2}
54 \desc{For the mesh specified by {\it meshID}, for the element {\it elem},
55 we set the desired size for each element from the corresonponding entry in
56 the {\it sizes} array.}
57
58 \function{void FEM\_ADAPT\_SetReferenceMesh(int meshID);}
59 \index{femAdaptSetReferenceMesh}
60 \desc{For each element int this mesh defined by {\it meshID} 
61 set its size to the average edge length of the corresponding element.}
62
63 \function{void FEM\_ADAPT\_GradateMesh(int meshID, double smoothness);}
64 \index{femAdaptGradateMesh}
65 \desc{Resize mesh elements to avoid jumps in element size.
66 i.e. avoid discontinuities in the desired sizes for elements of a mesh
67 by smoothing them out.
68 Algorithm based on h-shock correction, described in
69 Mesh Gradation Control, Borouchaki et al.}
70
71
72
73
74 \subsection{Modifying the Mesh}
75 Once the elements in the mesh has been prepared by specifying there desired
76 sizes, we are ready to use the actual adaptivity operations. Currently we
77 provide delauney flip operations, edge bisect operations and edge-coarsen 
78 operations all of which are implemented in parallel, but the user has 
79 access to these wrapper functions which interlligently decide when 
80 and in which region of the mesh to use the adaptivity operations to 
81 generate a mesh with higher quality elements while achieving the
82 desired size (which is usually average edge length per element), or it
83 could even be the area of each element.
84
85 \function{void FEM\_ADAPT\_Refine(int meshID, int qm, int method, double factor,double *sizes);}
86 \index{femAdaptRefine}
87 \desc{Perform refinements on the mesh specified by {\it meshId}.
88 Tries to maintain/improve element quality by refining the mesh
89 as specified by a quality measure {\it qm}.
90 If {\it method} = 0, refine areas with size larger than {\it factor} down to {\it factor}
91 If {\it method} = 1, refine elements down to sizes specified in the {\it sizes} array.
92 In this array each entry corresponds to the corresponding element.
93 Negative entries in sizes array indicate no refinement. }
94
95 \function{void FEM\_ADAPT\_Coarsen(int meshID, int qm, int method, double factor,double *sizes);}
96 \index{femAdaptCoarsen}
97 \desc{Perform refinements on the mesh specified by {\it meshId}.
98 Tries to maintain/improve element quality by coarsening the mesh
99 as specified by a quality measure {\it qm}.
100 If {\it method} = 0, coarsen areas with size smaller than {\it factor} down to {\it factor}
101 If {\it method} = 1, coarsen elements up to sizes specified in the {\it sizes} array.
102 In this array each entry corresponds to the corresponding element.
103 Negative entries in sizes array indicate no coarsening. }
104
105 \function{void FEM\_ADAPT\_AdaptMesh(int meshID, int qm, int method, double factor,double *sizes);}
106 \index{femAdaptAdaptMesh}
107 \desc{It has the same set of arguments as required by the previous two operations,
108 namely refine and coarsen. This function keeps using the above two functions till
109 we have all elements in the mesh with as close to the desired quality. Apart from
110 using the above two operations, it also performs a mesh repair operation where it
111 gets rid of some bad quality elements by delauney flip or coarsening as the
112 geometry in the area demands.}
113
114 \function{int FEM\_ADAPT\_SimpleRefineMesh(int meshID, double targetA, double xmin, double ymin, double xmax, double ymax);}
115 \index{femAdaptSimpleRefineMesh}
116 \desc{A region is defined by ({\it xmax, xmin, ymax, ymin}) 
117 and the target area to be achieved for all elements in this region
118 in the mesh specified by {\it meshID} is given by {\it targetA}.
119 This function only performs a series of refinements on the elements in this region.
120 If the area is larger, then no coarsening is done.}
121
122 \function{int FEM\_ADAPT\_SimpleCoarsenMesh(int meshID, double targetA, double xmin, double ymin, double xmax, double ymax);}
123 \index{femAdaptSimpleCoarsenMesh}
124 \desc{A region is defined by ({\it xmax, xmin, ymax, ymin}) 
125 and the target area to be achieved for all elements in this region
126 in the mesh specified by {\it meshID} is given by {\it targetA}.
127 This function only performs a series of coarsenings on the elements in this region.
128 If the area is smaller, then no refinement is done.}
129
130
131
132 \subsection{Verifiy correctness of the Mesh}
133 After adaptivity operations are performed and even before adaptivity operations, 
134 it is important to first verify that we are working on a mesh that is consistent
135 geometrically with the types of mesh that the adaptivity algorithms are designed
136 to work on. There is a function that can be used to test various properties of
137 a mesh, like area, quality, geometric consistency, idxl list correctness, etc.
138
139 \function{void FEM\_ADAPT\_TestMesh(int meshID);}
140 \index{femAdaptTestMesh}
141 \desc{This provides a series of tests to determine the consistency of the
142 mesh specified by {\it meshID}.}
143
144
145 These four simple steps define what needs to be used by a program that wishes
146 to use the adaptivity features of ParFUM.
147
148 \subsection{ParFUM developers}
149 This manual is meant for ParFUM users, so developers should look at the source code
150 and the doxygen generated documentaion.
151