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