Wrote the NetFEM manual.
[charm.git] / doc / netfem / manual.tex
1 \documentclass[10pt]{article}
2 \usepackage{../pplmanual}
3 \input{../pplmanual}
4
5 \makeindex
6
7 \title{\charmpp\\ NetFEM\\ Manual}
8 \version{1.0}
9 \credits{
10 The initial version of \charmpp{} NetFEM Framework was developed
11 by Orion Lawlor in 2001.
12 }
13
14 \begin{document}
15
16 \maketitle
17
18 \section{Introduction}
19
20 NetFEM was built to provide an easy way to visualize
21 the current state of a finite-element simulation, or any 
22 parallel program that computes on an unstructured mesh.
23 NetFEM is designed to require very little effort to add
24 to a program, and connects to the running program over
25 the network via CCS.
26
27
28 \section{Compiling and Installing}
29
30 NetFEM is part of \charmpp{}, so it can be downloaded
31 as part of charm.  To build NetFEM, just build FEM normally,
32 or else do a make in charm/net-linux/tmp/libs/ck-libs/netfem/.
33
34 To link with NetFEM, add \kw{-module netfem} to your
35 program's link line.  Note that you do {\em not} need to use
36 the FEM framework to use NetFEM.
37
38 The netfem header file for C is called ``netfem.h'',
39 the header for fortran is called `netfemf.h'.
40 A simple example NetFEM program is in 
41   charm/pgms/charm++/fem/simple2D/.
42 A more complicated example is in
43   charm/pgms/charm++/fem/crack2D/.
44
45
46 \section{Running NetFEM}
47
48 Once you have a NetFEM program, you run it and view 
49 the results by starting the program with CCS enabled:
50
51 \begin{verbatim}
52    foo.bar.edu>  ./charmrun ./myprogram +p2 ++server ++server-port 1234
53 \end{verbatim}
54
55 ``++server-port'' controls the TCP port number to use for CCS---here,
56 we use 1234.  Currently, NetFEM only works with one chunk per
57 processor---that is, the -vp option cannot be used.
58
59 You then start the NetFEM client, which can be downloaded
60 for Linux or Windows from 
61
62 \begin{verbatim}
63 http://charm.cs.uiuc.edu/research/fem/netfem/
64 \end{verbatim}
65
66 Enter the name of the machine running charmrun and
67 the TCP port number into the NetFEM client---for example, 
68 ``foo.bar.edu:1234''.
69
70 The NetFEM client will then connect to the program,
71 download the most recent mesh, and display it.
72
73
74
75 \section{Interface Basics}
76
77 You publish your data via NetFEM by making a series of
78 calls to describe the current state of your data.  
79 There are only 6 possible calls you can make.
80
81 \kw{NetFEM\_Begin} is the first routine you call.
82 \kw{NetFEM\_End} is the last routine to call.  These
83 two calls bracket all the other NetFEM calls.
84
85 \kw{NetFEM\_Nodes} describes the properties of the
86 nodes, or vertices of the domain.  \kw{NetFEM\_Elements}
87 describes the properties of your elements (triangles,
88 tetrahedra, etc.).  After making one of these calls,
89 you list the different data arrays associated with your 
90 nodes or elements by making calls to \kw{NetFEM\_Scalar} 
91 or \kw{NetFEM\_Vector}.
92
93 For example, a typical finite element simulation might
94 have a scalar mass and vector position, velocity, and net force
95 associated with each node; and have a scalar stress value
96 associated with each element.  The sequence of NetFEM calls
97 this application would make would be:
98
99 \begin{verbatim}
100   NetFEM_Begin
101     NetFEM_Nodes -- lists position of each node
102       NetFEM_Vector -- lists velocity of each node
103       NetFEM_Vector -- lists net force on each node
104       NetFEM_Scalar -- lists mass of each node
105     
106     NetFEM_Elements -- lists the nodes of each element
107       NetFEM_Scalar -- lists the stress of each element
108   
109   NetFEM_End
110 \end{verbatim}
111
112 \begin{figure}[h]
113 \begin{center}
114 \includegraphics[width=5in]{fig/example}
115 \end{center}
116 \caption{These arrays, typical of a finite element analysis
117 program, might be passed into NetFEM.}
118 \label{fig:example}
119 \end{figure}
120
121
122 \section{Simple Interface}
123 The details of how to make each call are:
124
125 \prototype{NetFEM\_Begin}
126 \function{NetFEM NetFEM\_Begin(int source, int step, int dim, int flavor);}
127 \function{integer function NetFEM\_Begin(source,step,dim,flavor)}
128   \args{integer, intent(in)  :: source,step,dim,flavor}
129
130 Begins describing a single piece of a mesh.  Returns a handle
131 that is used for each subsequent call until \kw{NetFEM\_End}.  
132 This call, like all NetFEM calls, is collective---every processor 
133 should make the same calls in the same order.
134
135 \uw{source} identifies the piece of the mesh---use FEM\_My\_partition
136 or CkMyPe.
137
138 \uw{step} identifies which version of the mesh this is---for example,
139 you might use the timestep number.  This is only used to identify the
140 mesh in the client.
141
142 \uw{dim} is the number of spatial dimensions.  For example, in a 2D
143 computation, you'd pass dim==2; in a 3D computation, dim==3.
144 The client currently only supports 2D or 3D computations.
145
146 \uw{flavor} specifies what to do with the data.  Currently, this
147 must be \kw{NetFEM\_POINTAT}, which specifies that NetFEM should 
148 only keep a pointer to the data rather than copy it out of your
149 arrays.
150
151
152 \prototype{NetFEM\_End}
153 \function{void NetFEM\_End(NetFEM n);}
154 \function{subroutine NetFEM\_End(n)}
155   \args{integer, intent(in)  :: n}
156
157 Finishes describing a single piece of a mesh, which 
158 then makes the mesh available for display.
159
160
161 \prototype{NetFEM\_Nodes}
162 \function{void NetFEM\_Nodes(NetFEM n,int nNodes,const double *loc,const char *name);}
163 \function{subroutine NetFEM\_Nodes(n,nNodes,loc,name)}
164   \args{integer, intent(in)  :: n, nNodes}
165   \args{double precision, intent(in)  :: loc(dim,nNodes) }
166   \args{character*(*), intent(in)  :: name}
167
168 Describes the nodes in this piece of the mesh.
169
170 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
171
172 \uw{nNodes} is the number of nodes listed here.
173
174 \uw{loc} is the location of each node.  This must be double-precision
175 array, laid out with the same number of dimentions as passed to 
176 \kw{NetFEM\_Begin}.  For example, in C the location of a 2D
177 node $n$ is stored in loc[2*n+0] (x coordinate) and loc[2*n+1]
178 (y coordinate).  In Fortran, location of a node $n$ is stored 
179 in loc(:,n).
180
181 \uw{name} is a human-readable name for the node locations
182 to display in the client.  We recommend also including the location
183 units here, for example "Position (m)".
184
185
186 \prototype{NetFEM\_Elements}
187 \function{void NetFEM\_Elements(NetFEM n,int nElements,int nodePerEl,const int *conn,const char *name);}
188 \function{subroutine NetFEM\_Elements(n,nElements,nodePerEl,conn,name)}
189   \args{integer, intent(in)  :: n, nElements, nodePerEl}
190   \args{integer, intent(in)  :: conn(nodePerEl,nElements) }
191   \args{character*(*), intent(in)  :: name}
192
193 Describes the elements in this piece of the mesh.
194 Unlike \kw{NetFEM\_Nodes}, this call can be repeated
195 if there are different types of elements (For example, 
196 some meshes contain a mix of triangles and quadrilaterals).
197
198 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
199
200 \uw{nElements} is the number of elements listed here.
201
202 \uw{nodePerEl} is the number of nodes for each element.
203 For example, a triangle has 3 nodes per element; while 
204 tetrahedra have 4.
205
206 \uw{conn} gives the index of each element's nodes.  Note
207 that when called from C, the first node is listed in 
208 \uw{conn} as 0 (0-based node indexing), and element $e$'s
209 first node is stored in conn[e*nodePerEl+0].
210 When called from Fortran, the first node is listed as 1 
211 (1-based node indexing), and element $e$'s first node is
212 stored in conn(1,e) or conn((e-1)*nodePerEl+1).
213
214 \uw{name} is a human-readable name for the elements
215 to display in the client.  For example, this might be
216 "Linear-Strain Triangles".
217
218
219
220 \prototype{NetFEM\_Vector}
221 \function{void NetFEM\_Vector(NetFEM n,const double *data,const char *name);}
222 \function{subroutine NetFEM\_Vector(n,data,name)}
223   \args{integer, intent(in)  :: n}
224   \args{double precision, intent(in)  :: data(dim,lastEntity) }
225   \args{character*(*), intent(in)  :: name}
226
227 Describes a spatial vector associated with each node or element
228 in the mesh.  Attaches the vector to the most recently listed 
229 node or element.  You can repeat this call several times to 
230 describe different vectors.
231
232 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
233
234 \uw{data} is the double-precision array of vector values.
235 The dimensions of the array have to match up with the node
236 or element the data is associated with--in C, a 2D element $e$'s
237 vector starts at data[2*e]; in Fortran, element $e$'s 
238 vector is data(:,e).
239
240 \uw{name} is a human-readable name for this vector data.
241 For example, this might be "Velocity (m/s)".
242
243
244 \prototype{NetFEM\_Scalar}
245 \function{void NetFEM\_Scalar(NetFEM n,const double *data,int dataPer,const char *name);}
246 \function{subroutine NetFEM\_Scalar(n,data,dataPer,name)}
247   \args{integer, intent(in)  :: n, dataPer}
248   \args{double precision, intent(in)  :: data(dataPer,lastEntity) }
249   \args{character*(*), intent(in)  :: name}
250
251 Describes some scalar data associated with each node or element
252 in the mesh.  Like \kw{NetFEM\_Vector}, this data is attached 
253 to the most recently listed node or element and this call 
254 can be repeated.  For a node or element, you can make the 
255 calls to \kw{NetFEM\_Vector} and \kw{NetFEM\_Scalar} in any order.
256
257 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
258
259 \uw{data} is the double-precision array of values.
260 In C, an element $e$'s scalar values start at data[dataPer*e];
261 in Fortran, element $e$'s values are in data(:,e).
262
263 \uw{dataPer} is the number of values associated with each 
264 node or element.  For true scalar data, this is 1; but 
265 can be any value.  Even if dataPer happens to equal the number
266 of dimensions, the client knows that this data does not 
267 represent a spatial vector.
268
269 \uw{name} is a human-readable name for this scalar data.
270 For example, this might be "Mass (Kg)" or "Stresses (pure)".
271
272
273
274 \section{Advanced ``Field'' Interface}
275 This more advanced interface can be used if you 
276 store your node or element data in arrays of C structs or 
277 Fortran TYPEs.  To use this interface, you'll have to
278 provide the name of your struct and field.  Each
279 ``field'' routine is just an extended version of 
280 a regular NetFEM call described above, and can be 
281 used in place of the regular NetFEM call.
282 In each case, you pass a description of your field
283 in addition to the usual NetFEM parameters.
284
285 In C, use the macro ``NetFEM\_Field(theStruct,theField)''
286 to describe the FIELD.  For example, to describe
287 the field ``loc'' of your structure named ``node\_t'',
288
289 \begin{verbatim}
290    node\_t *myNodes=...;
291    ..., NetFEM\_Field(node\_t,loc), ...
292 \end{verbatim}
293
294
295 In Fortran, you must pass as FIELD the byte offset from the start 
296 of the structure to the start of the field,
297 then the size of the structure.  The FEM "foffsetof" routine,
298 which returns the number of bytes between its arguments,
299 can be used for this.  For example, to describe the field
300 ``loc'' of your named type ``NODE'',
301
302 \begin{verbatim}
303    TYPE(NODE), ALLOCATABLE :: n(:)
304    ..., foffsetof(n(1),n(1)%loc),foffsetof(n(1),n(2)), ...
305 \end{verbatim}
306
307
308 \prototype{NetFEM\_Nodes\_field}
309 \function{void NetFEM\_Nodes\_field(NetFEM n,int nNodes,FIELD,const void *loc,const char *name);}
310 \function{subroutine NetFEM\_Nodes\_field(n,nNodes,FIELD,loc,name)}
311
312 A FIELD version of \kw{NetFEM\_Nodes}.
313
314 \prototype{NetFEM\_Elements\_field}
315 \function{void NetFEM\_Elements\_field(NetFEM n,int nElements,int nodePerEl,FIELD,int idxBase,const int *conn,const char *name);}
316 \function{subroutine NetFEM\_Elements\_field(n,nElements,nodePerEl,FIELD,idxBase,conn,name)}
317
318 A FIELD version of \kw{NetFEM\_Elements}.
319 This version also allows you to control the starting node
320 index of the connectivity array---in C, this is normally 0;
321 in Fortran, this is normally 1.
322
323 \prototype{NetFEM\_Vector\_field}
324 \function{void NetFEM\_Vector\_field(NetFEM n,const double *data,FIELD,const char *name);}
325 \function{subroutine NetFEM\_Vector\_field(n,data,FIELD,name)}
326
327 A FIELD version of \kw{NetFEM\_Vector}.
328
329
330 \prototype{NetFEM\_Scalar\_field}
331 \function{void NetFEM\_Scalar\_field(NetFEM n,const double *data,int dataPer,FIELD,const char *name);}
332 \function{subroutine NetFEM\_Scalar(n,data,dataPer,FIELD,name)}
333
334 A FIELD version of \kw{NetFEM\_Scalar}.
335
336
337 \end{document}