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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.26