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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3570 - (show annotations)
Thu Sep 1 03:11:26 2011 UTC (8 years, 1 month ago) by jfenwick
File MIME type: application/x-tex
File size: 14248 byte(s)
Fixed some bib entries, changed visit script in guide to use " instead of '.
Reworded a sentence.

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

  ViewVC Help
Powered by ViewVC 1.1.26