/[escript]/trunk/doc/user/weipa.tex
ViewVC logotype

Contents of /trunk/doc/user/weipa.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3383 - (show annotations)
Thu Nov 25 02:17:51 2010 UTC (9 years, 11 months ago) by caltinay
File MIME type: application/x-tex
File size: 14012 byte(s)
Fixed some typos and added missing symlinks. 

1
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %
4 % Copyright (c) 2003-2010 by University of Queensland
5 % Earth Systems Science Computational Center (ESSCC)
6 % http://www.uq.edu.au/esscc
7 %
8 % Primary Business: Queensland, Australia
9 % Licensed under the Open Software License version 3.0
10 % http://www.opensource.org/licenses/osl-3.0.php
11 %
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14 \chapter{The \weipa Module and Data Visualization}\label{chap:weipa}
15 %\declaremodule{extension}{weipa}
16 %\modulesynopsis{Exporting escript data and domains for post-processing}
17
18 The {\it weipa} C++ library and accompanying \PYTHON module allow exporting
19 \escript \Data objects and their domain in a format suitable for visualization.
20 Besides creating output files, {\it weipa} can also interface with the \VisIt
21 visualization software. This allows accessing the latest simulation data while
22 the simulation is still running without the need to save any files.
23
24 \section{The \class{EscriptDataset} class}
25 \begin{classdesc}{EscriptDataset}{}
26 holds an {\it escript} dataset including a domain and data variables
27 for a single time step and offers methods to export the data in various
28 formats.
29 It is not recommended to create a dataset object directly in \PYTHON using
30 the constructor (it is not actually exposed) but use the
31 \var{createDataset} function from \weipa instead, see \Sec{sec:weipafuncs}.
32 \end{classdesc}
33
34 \noindent The following methods are available:
35 \begin{methoddesc}[EscriptDataset]{setDomain}{domain}
36 sets the \Domain for this dataset. Note that the domain can only be set
37 once and all \Data objects added to this dataset must be defined on the
38 same domain.
39 \end{methoddesc}
40
41 \begin{methoddesc}[EscriptDataset]{addData}{data, name \optional{, units=""}}
42 adds the \Data object \var{data} to this dataset which will be exported by
43 the given \var{name}. Some export formats support data units which can be
44 set through the \var{units} parameter, e.g. \code{"km/h"}.
45 Before calling this method a domain must be set with \member{setDomain}
46 and all \Data objects added must be defined on the same domain.
47 There is no restriction, however, on the \FunctionSpace used.
48 \end{methoddesc}
49
50 \begin{methoddesc}[EscriptDataset]{setCycleAndTime}{cycle, time}
51 sets the cycle and time values for this dataset.
52 The cycle is an integer value which usually corresponds with the loop
53 counter of the simulation script. That is, every time a new data file is
54 created this counter is incremented.
55 The value of \var{time} on the other hand is a floating point number that
56 encodes some form of simulation time.
57 Both, cycle and time may be read by analysis tools and shown alongside
58 other metadata to the user.
59 \end{methoddesc}
60
61 \begin{methoddesc}[EscriptDataset]{setMeshLabels}{x, y \optional{, z=""}}
62 sets the labels of the X, Y, and Z axis. By default, visualization tools
63 display default strings such as "X-Axis" or "X" along the axes. Some export
64 formats allow overriding these with more specific strings such as "Width",
65 "Horizontal Distance", etc.
66 \end{methoddesc}
67
68 \begin{methoddesc}[EscriptDataset]{setMeshUnits}{x, y \optional{, z=""}}
69 sets the units to be displayed along the X, Y, and Z axis in visualization
70 tools (if supported). Not all export formats will use these values.
71 \end{methoddesc}
72
73 \begin{methoddesc}[EscriptDataset]{setMetadataSchemaString}{\optional{schema="" \optional{, metadata=""}}}
74 adds custom metadata and/or XML schema strings to VTK files.
75 The content of \var{schema} is added to the top-level \emph{VTKFile}
76 element so care must be taken to keep the resulting file valid.
77 As an example, \var{schema} may contain the string
78 \code{xmlns:gml="http://www.opengis.net/gml"}. The content of \var{metadata}
79 will be written enclosed in \code{<MetaData>} tags. Thus, a valid example
80 would be \code{<dataSource>something</dataSource>}.
81 Note that these values are ignored by other exporters.
82 \end{methoddesc}
83
84 \begin{methoddesc}[EscriptDataset]{saveSilo}{filename}
85 saves the dataset in the \SILO file format to a file named \var{filename}.
86 The file extension \code{.silo} will be automatically added if not present.
87 \end{methoddesc}
88
89 \begin{methoddesc}[EscriptDataset]{saveVTK}{filename}
90 saves the dataset in the \VTK file format to a file named \var{filename}.
91 The file extension \code{.vtu} will be automatically added if not present.
92 Certain combinations of function spaces cannot be written to a single \VTK
93 file due to format restrictions. In these cases this method will save
94 separate files where each file contains compatible data.
95 The function space name is appended to the filename to distinguish them.
96 \end{methoddesc}
97
98 \section{Functions}\label{sec:weipafuncs}
99 \begin{funcdesc}{createDataset}{domain, **data}
100 creates an \class{EscriptDataset} object, sets its domain, populates it
101 with the given \Data objects and returns it.
102 Note that it is not possible to set units for the data variables added with
103 this function. If this is required, it is recommended to call this function
104 with a domain only and use the \member{addData} method subsequently.
105 \end{funcdesc}
106
107 \begin{funcdesc}{saveVTK}{filename \optional{, domain=None \optional{, metadata="" \optional{, metadata_schema=None}}}, **data}
108 convenience function that creates a dataset with the given domain and \Data
109 objects and saves it to a file in the \VTK file format.
110 If \var{domain} is \code{None} the domain will be determined by the \Data
111 objects.
112 See the \member{setDomain}, \member{addData}, \member{saveVTK}, and
113 \member{setMetadataSchemaString} methods of the \class{EscriptDataset}
114 class for details.
115 Unlike the class method, the \var{metadata_schema} parameter should be a
116 dictionary that maps namespace name to URI, e.g.\\
117 \code{\{"gml":"http://www.opengis.net/gml"\}}.
118 \end{funcdesc}
119
120 \begin{funcdesc}{saveSilo}{filename \optional{, domain=None}, **data}
121 convenience function that creates a dataset with the given domain and \Data
122 objects and saves it to a file in the \SILO file format.
123 If \var{domain} is \code{None} the domain will be determined by the \Data
124 objects.
125 See the \member{setDomain}, \member{addData}, and \member{saveSilo}
126 methods of the \class{EscriptDataset} class for details.
127 \end{funcdesc}
128
129 \begin{funcdesc}{visitInitialize}{simFile \optional{, comment=""}}
130 initializes the \VisIt simulation interface which is responsible for the
131 communication with a \VisIt client.
132 This function will create a file by the name given via \var{simFile}
133 (extension \code{.sim2}) which can be loaded by a compatible \VisIt client
134 in order to connect to the simulation. The optional \var{comment} string
135 is forwarded to the client.
136 Note that this function only succeeds if {\it escript} was compiled with
137 support for \VisIt and the appropriate libraries are found in the runtime
138 environment. Clients wanting to connect can only do so if the version
139 number matches the version number used to compile \weipa.
140 Calling this function does not make any data available yet, see the
141 \var{visitPublishData} function.
142 \end{funcdesc}
143
144 \begin{funcdesc}{visitPublishData}{dataset}
145 publishes an \class{EscriptDataset} object through the \VisIt simulation
146 interface, checks for client requests and handles any outstanding ones.
147 Before publishing any data, the \var{visitInitialize} function must be
148 called to set up the interface.
149 Since this function not only publishes new data but polls for incoming
150 connections and handles requests, it should be called as often as practical
151 (even with the same dataset) to avoid timeout errors from clients.
152 On the other hand it should be noted that the same process(es) deal with
153 visualization requests that run your simulation. So a request for an
154 expensive task by a \VisIt client will pause the simulation code while it
155 is being processed.
156 \end{funcdesc}
157
158 \section{Visualizing {\it escript} Data}
159 This section gives a very brief overview on how data exported through \weipa
160 can be visualized. While there are many visualization packages available that
161 are compatible with \VTK and \SILO files produced by {\it escript}, this
162 discussion will refer to \VisIt~\cite{VisIt}, an actively maintained open
163 source package optimally suited to visualize and analyze large datasets both
164 interactively and through \PYTHON scripts. You can find a number of manuals,
165 a wiki page and links to mailing lists on the \VisIt website.
166 It is assumed that you have a working \VisIt installation that can be started
167 by entering \code{visit} on the command line.
168
169 The examples that follow will use the output produced by the Elastic
170 Deformation example from \Sec{ELASTIC CHAP} (\file{heatedblock.py} in the
171 \ExampleDirectory) which produces the file \file{deform.vtu}.
172 This \VTK file contains a 3D scalar variable called \code{stress} and a vector
173 variable called \code{disp}, among others.
174
175 \subsection{Using the \VisIt GUI}
176 Start the VisIt graphical user interface and open the file \file{deform.vtu}
177 via the 'File' menu. Alternatively, you can directly open the file on startup
178 by issuing
179 \begin{verbatim}
180 visit -o deform.vtu
181 \end{verbatim}
182 You should see the \VisIt GUI on the left hand side and an empty visualization
183 window on the right. Click on 'Add' under Plots in the GUI to bring up a menu
184 of plot types, then click on 'Pseudocolor' and select 'stress'.
185 This will add a plot to the list which maps values of the 'stress' variable to
186 colors. Note, that the plot will not be generated until you click on the 'Draw'
187 button in the GUI. You should now see a coloured box in the visualization
188 window which you can rotate around and inspect from different angles using your
189 mouse. The example uses a coarse mesh of 10 by 10 by 10 elements which are
190 clearly visible in this plot.
191
192 We can improve the visual effect by enabling interpolation between the elements.
193 To do so, bring up the plot attributes by double-clicking the
194 'Pseudocolor - stress' plot entry in the GUI.
195 Next, select 'Nodal' under 'Centering', click on 'Apply' and dismiss the dialog.
196 Notice how the colours now smoothly blend into each other and the element
197 boundaries are no longer visible.
198
199 Now we will add arrows to visualize the displacement vectors. Click on 'Add'
200 and under 'Vector' select 'disp'. Once again click on 'Draw' to execute the
201 new plot. By default only few vectors are shown but since the mesh is very
202 coarse we can tell \VisIt to draw all available vectors.
203 Bring up the Vector plot attributes (double-click on the plot as before) and
204 under 'Vector amount' select 'Stride', leaving the parameter as 1.
205 Click on 'Apply' and dismiss the dialog.
206
207 As a final step we would like to see inside the plot. One possibility to do so
208 is slicing. However, we want to keep all vectors while slicing only the
209 Pseudocolor plot. In \VisIt slicing is one of the Operators that may be added
210 to plots and by default, Operators are added to \emph{all} plots.
211 To change this behaviour, uncheck the 'Apply operators to all plots' box which
212 is located underneath the plot list in the GUI.
213 Then select the Pseudocolor plot, bring up the Operators menu by clicking on
214 'Operators' and select 'ThreeSlice' from the 'Slicing' submenu.
215 Again, click on 'Draw' to update the plots and notice how the box has now been
216 sliced. We can move the slices to more suitable positions by editing the
217 operator attributes. Click on the little triangle to the left of the
218 Pseudocolor plot to reveal the list of elements that have been applied to it.
219 Next, double-click the 'ThreeSlice' element to bring up the attribute window.
220 Change the values to $X=0.3$ and $Y=0.3$, leaving $Z=0$. Apply the changes and
221 dismiss the dialog to see the result.
222
223 You can now create an image of the plots as shown in the window. First, adjust
224 the save options to your needs in the 'Set Save options' dialog which is
225 accessible from the 'File' menu. Then select 'Save Window' and you should find
226 an image file with the name and location as entered in the options dialog.
227
228 \subsection{Using the \VisIt CLI}
229 We will now perform exactly the same steps as in the last section but using the
230 \PYTHON interface of \VisIt instead of the GUI. Start up the CLI by issuing
231 \begin{verbatim}
232 visit -cli
233 \end{verbatim}
234 You should now see an empty visualization window but unlike in the previous
235 section there will be no graphical user interface but a \PYTHON command line
236 instead.
237 Enter the following commands, one by one, noticing the changes in the
238 visualization window after every block of commands:
239 \begin{python}
240 OpenDatabase('deform.vtu')
241 AddPlot('Pseudocolor','stress')
242 DrawPlots()
243
244 p=PseudocolorAttributes()
245 p.centering=p.Nodal
246 SetPlotOptions(p)
247
248 AddOperator('ThreeSlice')
249 DrawPlots()
250
251 t=ThreeSliceAttributes()
252 t.x=0.3
253 t.y=0.3
254 SetOperatorOptions(t)
255
256 AddPlot('Vector', 'disp')
257 DrawPlots()
258
259 v=VectorAttributes()
260 v.useStride=1
261 SetPlotOptions(v)
262
263 s=SaveWindowAttributes()
264 #change settings as required
265 SaveWindow()
266 exit()
267 \end{python}
268 All but the last call to \code{DrawPlots()} is not required and was only put
269 there for demonstrating the effects of the commands.
270 You can save these commands to a file, e.g. \file{deformVis.py} and let \VisIt
271 process them non-interactively like so:
272 \begin{verbatim}
273 visit -cli -nowin -s deformVis.py
274 \end{verbatim}
275 The \code{-nowin} option prevents the visualization window from being shown
276 which is not required since the purpose of the script is to save an image file.
277
278 Obviously, we have barely touched on the powerful features of \VisIt and this
279 section was only meant to give you a minimal introduction. The \VisIt website
280 has a reference manual for the \PYTHON interface that explains how to perform
281 other operations programmatically, such as changing the view.
282

  ViewVC Help
Powered by ViewVC 1.1.26