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

Revision 3383 - (show annotations)
Thu Nov 25 02:17:51 2010 UTC (10 years, 6 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 7 % 8 % Primary Business: Queensland, Australia 9 % Licensed under the Open Software License version 3.0 10 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{} tags. Thus, a valid example 80 would be \code{something}. 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