docs: add reference to sync example program
[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 the network protocol CCS (Converse Client/Server).
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 Online}
47
48 Once you have a NetFEM program, you can run it and view 
49 the results online 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 To view the results online, you then start the NetFEM client, 
60 which can be downloaded 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 you might run:
69
70 \begin{verbatim}
71   netfem foo.bar.edu:1234
72 \end{verbatim}
73
74 The NetFEM client will then connect to the program,
75 download the most recent mesh registered with 
76 \kw{NetFEM\_POINTAT}, and display it.
77 At any time, you can press the ``update'' button 
78 to reload the latest mesh.
79
80
81 \section{Running NetFEM Offline}
82
83 Rather than using CCS as above, you can register your meshes
84 using \kw{NetFEM\_WRITE}, which makes the server write out 
85 binary output dump files.  For example, to view timestep 10,
86 which is written to the ``NetFEM/10/`` directory, you'd 
87 run the client program as:
88
89 \begin{verbatim}
90   netfem NetFEM/10
91 \end{verbatim}
92
93 In offline mode, the ``update'' button fetches the next
94 extant timestep directory.
95
96 \section{NetFEM with other Visualization Tools}
97
98 You can use a provided converter program to convert the offline NetFEM files into an XML format compatible with the powerful offline visualization tool ParaView(\url{http://paraview.org}). The converter is located in .../charm/src/libs/ck-libs/netfem/ParaviewConverter/. Build the converter by simply issuing a ``make'' command in that directory(assuming NetFEM already has been built).
99
100
101
102 Run the converter from the parent directory of the "NetFEM" directory to be converted. The converter will generate a directory called ``ParaViewData'', which contains subdirectories for each timestep, along with a ``timestep''directory for index files for each timestep. All files in the ParaViewData directory can be opened by ParaView. To open all chunks for a given timestep, open the desired timestep file in ``ParaViewData/timesteps''. Also, individual partition files can also be opened from ``ParaViewData / $<$timestep$>$ / $<$partition\_num$>$''.
103
104
105
106 \section{Interface Basics}
107
108 You publish your data via NetFEM by making a series of
109 calls to describe the current state of your data.  
110 There are only 6 possible calls you can make.
111
112 \kw{NetFEM\_Begin} is the first routine you call.
113 \kw{NetFEM\_End} is the last routine to call.  These
114 two calls bracket all the other NetFEM calls.
115
116 \kw{NetFEM\_Nodes} describes the properties of the
117 nodes, or vertices of the domain.  \kw{NetFEM\_Elements}
118 describes the properties of your elements (triangles,
119 tetrahedra, etc.).  After making one of these calls,
120 you list the different data arrays associated with your 
121 nodes or elements by making calls to \kw{NetFEM\_Scalar} 
122 or \kw{NetFEM\_Vector}.
123
124 For example, a typical finite element simulation might
125 have a scalar mass and vector position, velocity, and net force
126 associated with each node; and have a scalar stress value
127 associated with each element.  The sequence of NetFEM calls
128 this application would make would be:
129
130 \begin{verbatim}
131   NetFEM_Begin
132     NetFEM_Nodes -- lists position of each node
133       NetFEM_Vector -- lists velocity of each node
134       NetFEM_Vector -- lists net force on each node
135       NetFEM_Scalar -- lists mass of each node
136     
137     NetFEM_Elements -- lists the nodes of each element
138       NetFEM_Scalar -- lists the stress of each element
139   
140   NetFEM_End
141 \end{verbatim}
142
143 \begin{figure}[h]
144 \begin{center}
145 \includegraphics[width=5in]{fig/example}
146 \end{center}
147 \caption{These arrays, typical of a finite element analysis
148 program, might be passed into NetFEM.}
149 \label{fig:example}
150 \end{figure}
151
152
153 \section{Simple Interface}
154 The details of how to make each call are:
155
156 \prototype{NetFEM\_Begin}
157 \function{NetFEM NetFEM\_Begin(int source, int step, int dim, int flavor);}
158 \function{integer function NetFEM\_Begin(source,step,dim,flavor)}
159   \args{integer, intent(in)  :: source,step,dim,flavor}
160
161 Begins describing a single piece of a mesh.  Returns a handle
162 that is used for each subsequent call until \kw{NetFEM\_End}.  
163 This call, like all NetFEM calls, is collective---every processor 
164 should make the same calls in the same order.
165
166 \uw{source} identifies the piece of the mesh---use FEM\_My\_partition
167 or CkMyPe.
168
169 \uw{step} identifies which version of the mesh this is---for example,
170 you might use the timestep number.  This is only used to identify the
171 mesh in the client.
172
173 \uw{dim} is the number of spatial dimensions.  For example, in a 2D
174 computation, you'd pass dim==2; in a 3D computation, dim==3.
175 The client currently only supports 2D or 3D computations.
176
177 \uw{flavor} specifies what to do with the data.  This can
178 take the value \kw{NetFEM\_POINTAT}, which is used in online visualization,
179 and specifies that NetFEM should only keep a pointer to your data 
180 rather than copy it out of your arrays.  Or it can take the value
181 \kw{NetFEM\_WRITE}, which writes out the data to files named
182 ``NetFEM/\uw{step}/\uw{source}.dat'' for offline visualization. 
183
184
185 \prototype{NetFEM\_End}
186 \function{void NetFEM\_End(NetFEM n);}
187 \function{subroutine NetFEM\_End(n)}
188   \args{integer, intent(in)  :: n}
189
190 Finishes describing a single piece of a mesh, which 
191 then makes the mesh available for display.
192
193
194 \prototype{NetFEM\_Nodes}
195 \function{void NetFEM\_Nodes(NetFEM n,int nNodes,const double *loc,const char *name);}
196 \function{subroutine NetFEM\_Nodes(n,nNodes,loc,name)}
197   \args{integer, intent(in)  :: n, nNodes}
198   \args{double precision, intent(in)  :: loc(dim,nNodes) }
199   \args{character*(*), intent(in)  :: name}
200
201 Describes the nodes in this piece of the mesh.
202
203 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
204
205 \uw{nNodes} is the number of nodes listed here.
206
207 \uw{loc} is the location of each node.  This must be double-precision
208 array, laid out with the same number of dimentions as passed to 
209 \kw{NetFEM\_Begin}.  For example, in C the location of a 2D
210 node $n$ is stored in loc[2*n+0] (x coordinate) and loc[2*n+1]
211 (y coordinate).  In Fortran, location of a node $n$ is stored 
212 in loc(:,n).
213
214 \uw{name} is a human-readable name for the node locations
215 to display in the client.  We recommend also including the location
216 units here, for example "Position (m)".
217
218
219 \prototype{NetFEM\_Elements}
220 \function{void NetFEM\_Elements(NetFEM n,int nElements,int nodePerEl,const int *conn,const char *name);}
221 \function{subroutine NetFEM\_Elements(n,nElements,nodePerEl,conn,name)}
222   \args{integer, intent(in)  :: n, nElements, nodePerEl}
223   \args{integer, intent(in)  :: conn(nodePerEl,nElements) }
224   \args{character*(*), intent(in)  :: name}
225
226 Describes the elements in this piece of the mesh.
227 Unlike \kw{NetFEM\_Nodes}, this call can be repeated
228 if there are different types of elements (For example, 
229 some meshes contain a mix of triangles and quadrilaterals).
230
231 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
232
233 \uw{nElements} is the number of elements listed here.
234
235 \uw{nodePerEl} is the number of nodes for each element.
236 For example, a triangle has 3 nodes per element; while 
237 tetrahedra have 4.
238
239 \uw{conn} gives the index of each element's nodes.  Note
240 that when called from C, the first node is listed in 
241 \uw{conn} as 0 (0-based node indexing), and element $e$'s
242 first node is stored in conn[e*nodePerEl+0].
243 When called from Fortran, the first node is listed as 1 
244 (1-based node indexing), and element $e$'s first node is
245 stored in conn(1,e) or conn((e-1)*nodePerEl+1).
246
247 \uw{name} is a human-readable name for the elements
248 to display in the client.  For example, this might be
249 "Linear-Strain Triangles".
250
251
252
253 \prototype{NetFEM\_Vector}
254 \function{void NetFEM\_Vector(NetFEM n,const double *data,const char *name);}
255 \function{subroutine NetFEM\_Vector(n,data,name)}
256   \args{integer, intent(in)  :: n}
257   \args{double precision, intent(in)  :: data(dim,lastEntity) }
258   \args{character*(*), intent(in)  :: name}
259
260 Describes a spatial vector associated with each node or element
261 in the mesh.  Attaches the vector to the most recently listed 
262 node or element.  You can repeat this call several times to 
263 describe different vectors.
264
265 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
266
267 \uw{data} is the double-precision array of vector values.
268 The dimensions of the array have to match up with the node
269 or element the data is associated with--in C, a 2D element $e$'s
270 vector starts at data[2*e]; in Fortran, element $e$'s 
271 vector is data(:,e).
272
273 \uw{name} is a human-readable name for this vector data.
274 For example, this might be "Velocity (m/s)".
275
276
277 \prototype{NetFEM\_Scalar}
278 \function{void NetFEM\_Scalar(NetFEM n,const double *data,int dataPer,const char *name);}
279 \function{subroutine NetFEM\_Scalar(n,data,dataPer,name)}
280   \args{integer, intent(in)  :: n, dataPer}
281   \args{double precision, intent(in)  :: data(dataPer,lastEntity) }
282   \args{character*(*), intent(in)  :: name}
283
284 Describes some scalar data associated with each node or element
285 in the mesh.  Like \kw{NetFEM\_Vector}, this data is attached 
286 to the most recently listed node or element and this call 
287 can be repeated.  For a node or element, you can make the 
288 calls to \kw{NetFEM\_Vector} and \kw{NetFEM\_Scalar} in any order.
289
290 \uw{n} is the NetFEM handle obtained from \kw{NetFEM\_Begin}.
291
292 \uw{data} is the double-precision array of values.
293 In C, an element $e$'s scalar values start at data[dataPer*e];
294 in Fortran, element $e$'s values are in data(:,e).
295
296 \uw{dataPer} is the number of values associated with each 
297 node or element.  For true scalar data, this is 1; but 
298 can be any value.  Even if dataPer happens to equal the number
299 of dimensions, the client knows that this data does not 
300 represent a spatial vector.
301
302 \uw{name} is a human-readable name for this scalar data.
303 For example, this might be "Mass (Kg)" or "Stresses (pure)".
304
305
306
307 \section{Advanced ``Field'' Interface}
308 This more advanced interface can be used if you 
309 store your node or element data in arrays of C structs or 
310 Fortran TYPEs.  To use this interface, you'll have to
311 provide the name of your struct and field.  Each
312 ``field'' routine is just an extended version of 
313 a regular NetFEM call described above, and can be 
314 used in place of the regular NetFEM call.
315 In each case, you pass a description of your field
316 in addition to the usual NetFEM parameters.
317
318 In C, use the macro ``NetFEM\_Field(theStruct,theField)''
319 to describe the FIELD.  For example, to describe
320 the field ``loc'' of your structure named ``node\_t'',
321
322 \begin{verbatim}
323    node\_t *myNodes=...;
324    ..., NetFEM\_Field(node\_t,loc), ...
325 \end{verbatim}
326
327
328 In Fortran, you must pass as FIELD the byte offset from the start 
329 of the structure to the start of the field,
330 then the size of the structure.  The FEM "foffsetof" routine,
331 which returns the number of bytes between its arguments,
332 can be used for this.  For example, to describe the field
333 ``loc'' of your named type ``NODE'',
334
335 \begin{verbatim}
336    TYPE(NODE), ALLOCATABLE :: n(:)
337    ..., foffsetof(n(1),n(1)%loc),foffsetof(n(1),n(2)), ...
338 \end{verbatim}
339
340
341 \prototype{NetFEM\_Nodes\_field}
342 \function{void NetFEM\_Nodes\_field(NetFEM n,int nNodes,FIELD,const void *loc,const char *name);}
343 \function{subroutine NetFEM\_Nodes\_field(n,nNodes,FIELD,loc,name)}
344
345 A FIELD version of \kw{NetFEM\_Nodes}.
346
347 \prototype{NetFEM\_Elements\_field}
348 \function{void NetFEM\_Elements\_field(NetFEM n,int nElements,int nodePerEl,FIELD,int idxBase,const int *conn,const char *name);}
349 \function{subroutine NetFEM\_Elements\_field(n,nElements,nodePerEl,FIELD,idxBase,conn,name)}
350
351 A FIELD version of \kw{NetFEM\_Elements}.
352 This version also allows you to control the starting node
353 index of the connectivity array---in C, this is normally 0;
354 in Fortran, this is normally 1.
355
356 \prototype{NetFEM\_Vector\_field}
357 \function{void NetFEM\_Vector\_field(NetFEM n,const double *data,FIELD,const char *name);}
358 \function{subroutine NetFEM\_Vector\_field(n,data,FIELD,name)}
359
360 A FIELD version of \kw{NetFEM\_Vector}.
361
362
363 \prototype{NetFEM\_Scalar\_field}
364 \function{void NetFEM\_Scalar\_field(NetFEM n,const double *data,int dataPer,FIELD,const char *name);}
365 \function{subroutine NetFEM\_Scalar(n,data,dataPer,FIELD,name)}
366
367 A FIELD version of \kw{NetFEM\_Scalar}.
368
369
370 \end{document}