fieldconvert.tex 49.4 KB
Newer Older
1
\chapter{FieldConvert}
2
\label{s:utilities:fieldconvert}
3 4 5 6 7 8 9 10 11 12 13
FieldConvert is a utility embedded in \nekpp with the primary aim of allowing
the user to convert the \nekpp output binary files (\inltt{.chk} and
\inltt{.fld}) into formats which can be read by common visualisation and
post-processing software, primarily Paraview/VisIt (in unstructured VTK
\inltt{.vtu} format) or Tecplot/VisIt (in ASCII \inltt{.dat} or binary
\inltt{.plt} formats). FieldConvert also allows the user to manipulate the
\nekpp output binary files by using some additional modules which can be called
with the option \inltt{-m} which stands for \inltt{m}odule. Note that another
flag, \inltt{-r} (which stand for \inltt{r}ange) allows the user to specify a
sub-range of the domain on which the conversion or manipulation of the \nekpp
output binary files will be performed.
14

15 16 17 18
Almost all of the FieldConvert functionalities can be run in parallel if \nekpp
is compiled using MPI (see the installation documentation for additional info on
how to implement \nekpp using MPI). \footnote{Modules that do not have parallel
  support will be specified in the appropriate section.}
19 20 21
%
%
%
22
\section{Basic usage}
Dave Moxey's avatar
Dave Moxey committed
23 24 25
FieldConvert expects at least one input specification (such as a session file
and its corresponding field file) and one output specification. These are
specified on the command line as
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
%
\begin{lstlisting}[style=BashInputStyle]
  FieldConvert in1.xml in2.fld out.dat
\end{lstlisting}
%
These can be combined with a processing module by adding the \inltt{-m} command
line option. There can be more than one module specified, and they can appear
anywhere in the command line arguments, although the order of execution is
inferred from their order in the command line. For example, the command
%
\begin{lstlisting}[style=BashInputStyle]
  FieldConvert in1.xml -m module1 in2.fld -m module2 out.dat
\end{lstlisting}
%
causes \inltt{in1.xml} and \inltt{in2.fld} to be read, followed by the
\inltt{module1} processing module, the \inltt{module2} processing module, and
finally output to the \inltt{out.dat} Tecplot file.

\subsection{Input formats}

FieldConvert supports XML and FLD-format files as produced by \nekpp. It also
supports the reading of data files from two external spectral element codes:
\emph{Semtex}\footnote{http://users.monash.edu.au/~bburn/semtex.html} and
\emph{Nek5000}\footnote{https://nek5000.mcs.anl.gov}. These files can be
directly converted to \nekpp format files by using the command
%
\begin{lstlisting}[style=BashInputStyle]
  FieldConvert input.fld output.fld
\end{lstlisting}
%
Note that even though the \inltt{.fld} extension is typically associated with
\nekpp files, FieldConvert can automatically identify \emph{Semtex} and
\emph{Nek5000} input field files.

To use these files in a simulation, or to post-process the results of a
simulation, an appropriate mesh must also be defined in the \nekpp XML format.
\nm can be used to convert these input files to XML, as outlined in
section~\ref{s:utilities:nekmesh}.

65
\section{Convert .fld / .chk files into Paraview, VisIt or Tecplot format}
66
\label{s:utilities:fieldconvert:sub:convert}
67 68
To convert the \nekpp output binary files (.chk and .fld) into a
format which can be read by two common visualisation softwares:
69
Paraview (.vtu format), VisIt (.vtu format) or Tecplot (.dat or .plt format)
70
the user can run the following commands:
71
%
72
\begin{itemize}
73
\item Paraview or VisIt (.vtu format)
74 75 76 77 78 79 80
%
\begin{lstlisting}[style=BashInputStyle]
FieldConvert test.xml test.fld test.vtu
\end{lstlisting}
%
\item Tecplot (.dat format)
%
81 82 83
\begin{lstlisting}[style=BashInputStyle]
FieldConvert test.xml test.fld test.dat
\end{lstlisting}
84
%
85 86 87 88 89
\item Tecplot or VisIt(.plt format)
%
\begin{lstlisting}[style=BashInputStyle]
FieldConvert test.xml test.fld test.plt
\end{lstlisting}
90 91
\end{itemize}
%
Michael Turner's avatar
Michael Turner committed
92
where \inltt{FieldConvert} is the executable associated to the utility
93 94 95
FieldConvert, \inltt{test.xml} is the session file and
\inltt{test.vtu}, \inltt{test.dat},  \inltt{test.plt} are the desired
format outputs, either Paraview, VisIt or Tecplot formats.
96 97
%
\begin{tipbox}
Michael Turner's avatar
Michael Turner committed
98
Note that the session file is also supported
99 100 101 102 103
in its compressed format \inltt{test.xml.gz}.
\end{tipbox}
%
%
%
104 105 106 107 108 109 110 111 112 113 114
\section{Convert field files between XML and HDF5 format}
%
When \nekpp is compiled with HDF5 support, solvers can select the format used
for output of \inltt{.fld} files. FieldConvert can be used to convert between
these formats using an option on the \inltt{.fld} output module. For example, if
\inltt{in.fld} is stored in the default XML format, it can be converted to HDF5
format by issuing the command
%
\begin{lstlisting}[style=BashInputStyle]
FieldConvert in.fld out.fld:fld:format=Hdf5
\end{lstlisting}
Michael Turner's avatar
Michael Turner committed
115
%
116
\section{Range option \textit{-r}}
Michael Turner's avatar
Michael Turner committed
117 118 119 120 121 122 123
The Fieldconvert range option \inltt{-r} allows the user to specify
a sub-range of the mesh (computational domain) by using an
additional flag, \inltt{-r} (which stands for \inltt{r}ange and either
convert or manipulate the \nekpp output binary files.
Taking as an example the conversion of the \nekpp binary files
(.chk or .fld) shown before and wanting to convert just the 2D
sub-range defined by $-2\leq x \leq 3$, $-1\leq y \leq 2$ the
124 125 126
additional flag \inltt{-r} can be used as follows:
%
\begin{itemize}
127
\item Paraview or VisIt (.vtu format)
128
%
129
\begin{lstlisting}[style=BashInputStyle]
130 131 132 133 134 135 136
FieldConvert -r -2,3,-1,2 test.xml test.fld test.vtu
\end{lstlisting}
%
\item Tecplot (.dat format)
%
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -r 2,3,-1,2 test.xml test.fld test.dat
137
\end{lstlisting}
138 139
%
\end{itemize}
Dave Moxey's avatar
Dave Moxey committed
140
where \inltt{-r} defines the range option of the FieldConvert
Michael Turner's avatar
Michael Turner committed
141
utility, the two first numbers define the range in $x$ direction
142
and the the third and fourth number specify the $y$ range.
Michael Turner's avatar
Michael Turner committed
143 144
A sub-range of a 3D domain can also be specified.
For doing so, a third set of numbers has to be provided
145 146 147 148
to define the $z$ range.
%
%
%
149
\section{FieldConvert modules \textit{-m}}
Michael Turner's avatar
Michael Turner committed
150 151
FieldConvert allows the user to manipulate the \nekpp output
binary files (.chk and .fld) by using the flag \inltt{-m} (which
Douglas Serson's avatar
Douglas Serson committed
152
stands for \inltt{m}odule).
153 154 155 156 157
Specifically, FieldConvert has these additional functionalities
%
\begin{enumerate}
\item \inltt{C0Projection}: Computes the C0 projection of a given output file;
\item \inltt{QCriterion}: Computes the Q-Criterion for a given output file;
Dave Moxey's avatar
Dave Moxey committed
158
\item \inltt{addcompositeid}: Adds the composite ID of an element as an additional field;
159
\item \inltt{addFld}: Sum two .fld files;
Douglas Serson's avatar
Douglas Serson committed
160 161
\item \inltt{combineAvg}: Combine two \nekpp binary output (.chk or .fld) field file containing averages of fields (and
possibly also Reynolds stresses) into single file;
Douglas Serson's avatar
Douglas Serson committed
162
\item \inltt{concatenate}: Concatenate a \nekpp binary output (.chk or .fld) field file into single file (deprecated);
163
\item \inltt{equispacedoutput}: Write data as equi-spaced output using simplices to represent the data for connecting points;
164
\item \inltt{extract}: Extract a boundary field;
165
\item \inltt{gradient}: Computes gradient of fields;
166
\item \inltt{homplane}: Extract a plane from 3DH1D expansions;
167
\item \inltt{homstretch}: Stretch a 3DH1D expansion by an integer factor;
Michael Turner's avatar
Michael Turner committed
168
\item \inltt{innerproduct}: take the inner product between one or a series of fields with another field (or series of fields).
169 170
\item \inltt{interpfield}: Interpolates one field to another, requires fromxml, fromfld to be defined;
\item \inltt{interppointdatatofld}: Interpolates given discrete data using a finite difference approximation to a fld file given an xml file;
171 172
\item \inltt{interppoints}: Interpolates a field to a set of points. Requires fromfld, fromxml to be defined, and a topts, line, plane or box of target points;
\item \inltt{interpptstopts}: Interpolates a set of points to another. Requires a topts, line, plane or box of target points;
Julian Marcon's avatar
Typo  
Julian Marcon committed
173
\item \inltt{isocontour}: Extract an isocontour of ``fieldid'' variable and at value ``fieldvalue''. Optionally ``fieldstr'' can be specified for a string definition or ``smooth'' for smoothing;
174
\item \inltt{jacobianenergy}: Shows high frequency energy of Jacobian;
175
\item \inltt{qualitymetric}: Evaluate a quality metric of the underlying mesh to show mesh quality;
176
\item \inltt{meanmode}: Extract mean mode (plane zero) of 3DH1D expansions;
177
\item \inltt{pointdatatofld}: Given discrete data at quadrature points
Michael Turner's avatar
Michael Turner committed
178
  project them onto an expansion basis and output fld file;
179 180 181 182
\item \inltt{printfldnorms}: Print L2 and LInf norms to stdout;
\item \inltt{scalargrad}: Computes scalar gradient field;
\item \inltt{scaleinputfld}: Rescale input field by a constant factor;
\item \inltt{shear}: Computes time-averaged shear stress metrics: TAWSS, OSI, transWSS, TAAFI, TACFI, WSSG;
Douglas Serson's avatar
Douglas Serson committed
183
\item \inltt{streamfunction}: Calculates stream function of a 2D incompressible flow.
Dave Moxey's avatar
Dave Moxey committed
184
\item \inltt{surfdistance}: Computes height of a prismatic boundary layer mesh and projects onto the surface (for e.g. $y^+$ calculation).
185
\item \inltt{vorticity}: Computes the vorticity field.
186
\item \inltt{wss}: Computes wall shear stress field.
187 188 189
\end{enumerate}
The module list above can be seen by running the command
%
190
\begin{lstlisting}[style=BashInputStyle]
Michael Turner's avatar
Michael Turner committed
191
FieldConvert -l
192
\end{lstlisting}
193 194 195 196 197
%
In the following we will detail the usage of each module.
%
%
%
198

199
\subsection{Smooth the data: \textit{C0Projection} module}
Michael Turner's avatar
Michael Turner committed
200
To smooth the data of a given .fld file one can
201 202
use the \inltt{C0Projection} module of FieldConvert
%
203
\begin{lstlisting}[style=BashInputStyle]
204
FieldConvert -m C0Projection test.xml test.fld test-C0Proj.fld
205
\end{lstlisting}
206
%
Michael Turner's avatar
Michael Turner committed
207
where the file \inltt{test-C0Proj.fld} can be processed in a similar
208
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
209
to visualise the result either in Tecplot, Paraview or VisIt.
210

211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
The option \inltt{localtoglobalmap} will do a global gather of the
coefficients and then scatter them back to the local elements. This
will replace the coefficients shared between two elements with the
coefficients of one of the elements (most likely the one with the
highest id). Although not a formal projection it does not require any
matrix inverse and so is very cheap to perform.

The option \inltt{usexmlbcs} will enforce the boundary conditions
specified in the input xml file.

The option \inltt{helmsmoothing=$L$} will perform a Helmholtz
smoothing projection of the form
\[
\left (\nabla^2 + \left (\frac{2 \pi}{L}\right )^2 \right ) \hat{u}^{new} =
\left (\frac{2 \pi}{L}\right )^2 \hat{u}^{orig}
\]
which can be interpreted in a Fourier sense as smoothing the original
coefficients using a low pass filter of the form
\[
\hat{u}_k^{new} = \frac{1}{(1 + k^2/K_0^2)} \hat{u}_k^{orig} \mbox{\,  where  \,}
K_0 = \frac{2 \pi}{L}
\]
and so $L$ is the length scale below which the coefficients values are
halved or more. Since this form of the Helmholtz operator is not
possitive definite, currently a direct solver is necessary and so this
smoother is mainly of use in two-dimensions.

238
\subsection{Calculate Q-Criterion: \textit{QCriterion} module}
Michael Turner's avatar
Michael Turner committed
239
To perform the Q-criterion calculation and obtain an output
240 241
data containing the Q-criterion solution, the user can run
%
242
\begin{lstlisting}[style=BashInputStyle]
243
FieldConvert -m QCriterion test.xml test.fld test-QCrit.fld
244
\end{lstlisting}
245
%
Michael Turner's avatar
Michael Turner committed
246
where the file \inltt{test-QCrit.fld} can be processed in a similar
247
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
248
to visualise the result either in Tecplot, Paraview or VisIt.
249 250 251
%
%
%
252

Dave Moxey's avatar
Dave Moxey committed
253 254
\subsection{Add composite ID: \textit{addcompositeid} module}
When dealing with a geometry that has many surfaces, we need to identify the
Dave Moxey's avatar
Dave Moxey committed
255
composites to assign boundary conditions. To assist in this, FieldConvert has a
Dave Moxey's avatar
Dave Moxey committed
256 257 258 259 260 261 262 263 264 265
\inltt{addcompositeid} module, which adds the composite ID of every element as a
new field. To use this we simply run
%
\begin{lstlisting}[style=BashInputStyle]
  FieldConvert -m addcompositeid mesh.xml out.dat
\end{lstlisting}
%
In this case, we have produced a Tecplot file which contains the mesh and a
variable that contains the composite ID. To assist in boundary identification,
the input file \inlsh{mesh.xml} should be a surface XML file that can be
Michael Turner's avatar
Michael Turner committed
266
obtained through the \nm \inltt{extract} module (see section
Dave Moxey's avatar
Dave Moxey committed
267 268
\ref{s:utilities:nekmesh:extract}).

269
\subsection{Sum two .fld files: \textit{addFld} module}
270 271 272
To sum two .fld files one can use the \inltt{addFld} module of FieldConvert
%
\begin{lstlisting}[style=BashInputStyle]
273 274
  FieldConvert -m addfld:fromfld=file1.fld:scale=-1 file1.xml file2.fld \
  file3.fld
275 276
\end{lstlisting}
%
Michael Turner's avatar
Michael Turner committed
277 278 279 280 281
In this case we use it in conjunction with the command \inltt{scale}
which multiply the values of a given .fld file by a constant \inltt{value}.
\inltt{file1.fld} is the file multiplied by \inltt{value}, \inltt{file1.xml}
is the associated session file, \inltt{file2.fld} is the .fld file which
is summed to \inltt{file1.fld} and finally \inltt{file3.fld} is the output
282
which contain the sum of the two .fld files.
Michael Turner's avatar
Michael Turner committed
283 284
\inltt{file3.fld} can be processed in a similar way as described
in section \ref{s:utilities:fieldconvert:sub:convert} to visualise
285
the result either in Tecplot, Paraview or VisIt.
286 287 288
%
%
%
Douglas Serson's avatar
Douglas Serson committed
289 290 291 292 293 294 295 296 297
\subsection{Combine two .fld files containing time averages: \textit{combineAvg} module}
To combine two .fld files obtained through the AverageFields or ReynoldsStresses filters,
use the \inltt{combineAvg} module of FieldConvert
%
\begin{lstlisting}[style=BashInputStyle]
  FieldConvert -m combineAvg:fromfld=file1.fld file1.xml file2.fld \
  file3.fld
\end{lstlisting}
%
Michael Turner's avatar
Michael Turner committed
298 299
\inltt{file3.fld} can be processed in a similar way as described
in section \ref{s:utilities:fieldconvert:sub:convert} to visualise
Douglas Serson's avatar
Douglas Serson committed
300 301 302 303
the result either in Tecplot, Paraview or VisIt.
%
%
%
304
\subsection{Concatenate two files: \textit{concatenate} module}
305 306 307
To concatenate \inltt{file1.fld} and \inltt{file2.fld} into \inltt{file-conc.fld}
one can run the following command
%
308
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
309
FieldConvert file.xml  file1.fld  file2.fld  file-conc.fld
310
\end{lstlisting}
311
%
Michael Turner's avatar
Michael Turner committed
312
where the file \inltt{file-conc.fld} can be processed in a similar
313
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
Douglas Serson's avatar
Douglas Serson committed
314 315 316
to visualise the result either in Tecplot, Paraview or VisIt. The
\inltt{concatenate} module previously used for this purpose is not
required anymore, and will be removed in a future release.
317 318 319
%
%
%
320
\subsection{Equi-spaced output of data: \textit{equispacedoutput} module}
Douglas Serson's avatar
Douglas Serson committed
321
This module interpolates the output data to a truly equispaced set of
322 323 324 325 326 327
points (not equispaced along the collapsed coordinate
system). Therefore a tetrahedron is represented by a tetrahedral
number of poinst. This produces much smaller output files. The points
are then connected together by simplices (triangles and tetrahedrons).

\begin{lstlisting}[style=BashInputStyle]
Spencer Sherwin's avatar
Spencer Sherwin committed
328
FieldConvert -m equispacedoutput test.xml test.fld test.dat
329 330 331 332 333
\end{lstlisting}

or

\begin{lstlisting}[style=BashInputStyle]
Spencer Sherwin's avatar
Spencer Sherwin committed
334
FieldConvert -m equispacedouttput test.xml test.fld test.vtu
335 336 337
\end{lstlisting}


Michael Turner's avatar
Michael Turner committed
338
\begin{notebox}
339
Currently this option is only set up for triangles, quadrilaterals,
340
tetrahedrons and prisms.
341 342
\end{notebox}

343
\subsection{Extract a boundary region: \textit{extract} module}
Michael Turner's avatar
Michael Turner committed
344
The boundary region of a domain can be extracted from the output
345 346 347
data using the following command line
%
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
348
FieldConvert -m extract:bnd=2 test.xml \
349 350 351
	test.fld test-boundary.fld
\end{lstlisting}
%
Michael Turner's avatar
Michael Turner committed
352 353 354
The option \inltt{bnd} specifies which boundary region to extract.
Note this is different to NekMesh where the parameter \inltt{surf}
is specified and corresponds to composites rather boundaries. If \inltt{bnd}
Douglas Serson's avatar
Douglas Serson committed
355 356 357
is not provided, all boundaries are extracted to different fields.
The output will be placed in test-boundary\_b2.fld.
If more than one boundary region is specified the extension \_b0.fld, \_b1.fld etc will be
Michael Turner's avatar
Michael Turner committed
358
outputted. To process this file you will need an xml file of the same region.
359 360
This can be generated using the command:
%
361
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
362
NekMesh -m extract:surf=5  test.xml test\_b0.xml
363
\end{lstlisting}
364
%
Michael Turner's avatar
Michael Turner committed
365 366
The surface to be extracted in this command is the composite
number and so needs to correspond to the boundary region
367 368 369
of interest. Finally to process the surface file one can use
%
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
370
FieldConvert  test\_b0.xml test\_b0.fld test\_b0.dat
371
\end{lstlisting}
372
%
Michael Turner's avatar
Michael Turner committed
373 374
This will obviously generate a Tecplot output if a .dat file
is specified as last argument. A .vtu extension will produce
375
a Paraview or VisIt output.
376 377 378
%
%
%
379
\subsection{Compute the gradient of a field: \textit{gradient} module}
380 381 382 383 384 385
To compute the spatial gradients of all fields one can run the following command
%
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m gradient test.xml  test.fld  test-grad.fld
\end{lstlisting}
%
Michael Turner's avatar
Michael Turner committed
386
where the file \inltt{file-grad.fld} can be processed in a similar
387
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
388
to visualise the result either in Tecplot, Paraview or VisIt.
389 390
%
%
391 392 393 394 395

\subsection{Extract a plane from 3DH1D expansion: \textit{homplane} module}

To obtain a 2D expansion containing one of the planes of a
3DH1D field file, use the command:
Michael Turner's avatar
Michael Turner committed
396
\begin{lstlisting}[style=BashInputStyle]
397 398 399 400 401
FieldConvert -m homplane:planeid=value file.xml file.fld file-plane.fld
\end{lstlisting}

If the option \inltt{wavespace} is used, the Fourier coefficients
corresponding to \inltt{planeid} are obtained. The command in this case is:
Michael Turner's avatar
Michael Turner committed
402
\begin{lstlisting}[style=BashInputStyle]
403 404 405 406
FieldConvert -m homplane:wavespace:planeid=value file.xml \
    file.fld file-plane.fld
\end{lstlisting}

Michael Turner's avatar
Michael Turner committed
407
The output file \inltt{file-plane.fld} can be processed in a similar
408 409 410
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
to visualise it either in Tecplot or in Paraview.

411 412 413
\subsection{Stretch a 3DH1D expansion: \textit{homstretch} module}

To stretch a 3DH1D expansion in the z-direction, use the command:
Michael Turner's avatar
Michael Turner committed
414
\begin{lstlisting}[style=BashInputStyle]
415 416 417
FieldConvert -m homstretch:factor=value file.xml file.fld file-stretch.fld
\end{lstlisting}
The number of modes in the resulting field can be chosen using the command-line
Douglas Serson's avatar
Douglas Serson committed
418
parameter \inltt{output-points-hom-z}.
419

Michael Turner's avatar
Michael Turner committed
420
The output file \inltt{file-stretch.fld} can be processed in a similar
421 422 423
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
to visualise it either in Tecplot or in Paraview.

424

425 426 427 428 429 430 431 432
\subsection{Inner Product of a single or series of fields with respect to a single or series of fields: \textit{innerproduct} module}
You can take the inner product of one field with another field using
the following command:
\begin{lstlisting}[style=BashInputStyle]
  FieldConvert -m innerproduct:fromfld=file1.fld  file2.xml file2.fld \
  out.stdout
\end{lstlisting}
This command will load the \inltt{file1.fld} and \inltt{file2.fld}
433
assuming they both are spatially defined by \inltt{files.xml} and
434 435 436 437
determine the inner product of these fields. The input option
\inltt{fromfld} must therefore be specified in this module.

Optional arguments for this module are \inltt{fields} which allow you to specify
Michael Turner's avatar
Michael Turner committed
438
the fields that you wish to use for the inner product, i.e.
439
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
440
  FieldConvert -m innerproduct:fromfld=file1.fld:fields="0,1,2" file2.xml \
441 442 443 444 445 446 447 448 449 450
  file2.fld out.stdout
\end{lstlisting}
will only take the inner product between the variables 0,1 and 2 in
the two fields files. The default is to take the inner product between
all fields provided.

Additional options include \inltt{multifldids} and \inltt{allfromflds}
which allow for a series of fields to be evaluated in the following
manner:
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
451
  FieldConvert -m innerproduct:fromfld=file1.fld:multifldids="0-3"\
452 453 454 455 456 457
  file2.xml  file2.fld out.stdout
\end{lstlisting}
will take the inner product between a file names
field1\_0.fld, field1\_1.fld, field1\_2.fld and field1\_3.fld with
respect to field2.fld.

Michael Turner's avatar
Michael Turner committed
458
Analogously including the options \inltt{allfromflds}, i.e.
459
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
460
  FieldConvert -m innerproduct:fromfld=file1.fld:multifldids="0-3":\
461 462 463 464 465 466 467 468 469
  allfromflds  file2.xml file2.fld out.stdout
\end{lstlisting}
Will take the inner product of all the from fields,
i.e. field1\_0.fld,field1\_1.fld,field1\_2.fld and field1\_3.fld with
respect to each other. This option essentially ignores file2.fld. Only
the unique inner products are evaluated so if four from fields are
given only the related trianuglar number $4\times5/2=10$ of inner
products are evaluated.

Michael Turner's avatar
Michael Turner committed
470
This option can be run in parallel.
471 472

%
473 474
%
%
475

476
\subsection{Interpolate one field to another: \textit{interpfield} module}
477 478
To interpolate one field to another, one can use the following command:
%
479
\begin{lstlisting}[style=BashInputStyle]
Michael Turner's avatar
Michael Turner committed
480
FieldConvert -m interpfield:fromxml=file1.xml:fromfld=file1.fld \
481
	file2.xml file2.fld
482
\end{lstlisting}
483
%
Michael Turner's avatar
Michael Turner committed
484 485
This command will interpolate the field defined by \inltt{file1.xml}
and \inltt{file1.fld} to the new mesh defined in \inltt{file2.xml} and
486
output it to \inltt{file2.fld}.
Michael Turner's avatar
Michael Turner committed
487 488 489
The \inltt{fromxml} and \inltt{fromfld} must be specified in this module.
In addition there are two optional arguments \inltt{clamptolowervalue}
and \inltt{clamptouppervalue} which clamp the interpolation between
490 491
these two values. Their default values are -10,000,000 and 10,000,000.
%
492 493
\begin{tipbox}
This module can run in parallel where the speed is increased not
Michael Turner's avatar
Michael Turner committed
494 495
only due to using more cores but also, since the mesh is split into
smaller sub-domains, the search method currently adopted performs
496
faster.
497
\end{tipbox}
498 499 500
%
%
%
501
\subsection{Interpolate scattered point data to a field: \textit{interppointdatatofld} module}
502
\label{s:utilities:fieldconvert:sub:interppointdatatofld}
503
To interpolate discrete point data to a field, use the interppointdatatofld module:
504
%
505
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
506
FieldConvert -m interppointdatatofld:frompts=file1.pts file1.xml file1.fld
507
\end{lstlisting}
508 509
or alternatively for csv data:
 \begin{lstlisting}[style=BashInputStyle]
Kilian Lackhove's avatar
Kilian Lackhove committed
510
FieldConvert -m interppointdatatofld:frompts=file1.csv file1.xml file1.fld
511
\end{lstlisting}
512
%
513
This command will interpolate the data from \inltt{file1.pts} (\inltt{file1.csv}) to the mesh
514
and expansions defined in \inltt{file1.xml} and output the field to \inltt{file1.fld}.
515
The file \inltt{file.pts} must be of the form:
516 517 518 519 520 521 522 523 524 525 526 527
%
\begin{lstlisting}[style=XMLStyle]
<?xml version="1.0" encoding="utf-8" ?>
<NEKTAR>
  <POINTS DIM="1" FIELDS="a,b,c">
    1.0000 -1.0000 1.0000 -0.7778
    2.0000 -0.9798 0.9798 -0.7980
    3.0000 -0.9596 0.9596 -0.8182
    4.0000 -0.9394 0.9394 -0.8384
  </POINTS>
</NEKTAR>
\end{lstlisting}
528
%
529 530 531 532 533 534
where \inltt{DIM="1" FIELDS="a,b,c} specifies that the field is one-dimensional
and contains three variables, $a$, $b$, and $c$.
Each line defines a point, while the  first column contains its $x$-coordinate,
the second one contains the $a$-values, the third the $b$-values and so on.
In case of $n$-dimensional data, the $n$ coordinates are specified in the first $n$
columns accordingly.
535
%
Julian Marcon's avatar
Typo  
Julian Marcon committed
536
An equivalent csv file is:
Kilian Lackhove's avatar
Kilian Lackhove committed
537
\begin{lstlisting}[style=BashInputStyle]
538 539 540 541 542 543 544
# x, a, b, c
1.0000,-1.0000,1.0000,-0.7778
2.0000,-0.9798,0.9798,-0.7980
3.0000,-0.9596,0.9596,-0.8182
4.0000,-0.9394,0.9394,-0.8384
\end{lstlisting}
%
545 546 547 548
In order to interpolate 1D data to a $n$D field, specify the matching coordinate in
the output field using the \inltt{interpcoord} argument:
%
\begin{lstlisting}[style=BashInputStyle]
549
FieldConvert -m interppointdatatofld:frompts=1D-file1.pts:interpcoord=1 \
Douglas Serson's avatar
Douglas Serson committed
550
        3D-file1.xml 3D-file1.fld
551 552 553 554 555
\end{lstlisting}
%
This will interpolate the 1D scattered point data from \inltt{1D-file1.pts} to the
$y$-coordinate of the 3D mesh defined in \inltt{3D-file1.xml}. The resulting field
will have constant values along the $x$ and $z$ coordinates.
Michael Turner's avatar
Michael Turner committed
556 557
For 1D Interpolation, the module implements a quadratic scheme and automatically
falls back to a linear method if only two data points are given.
558
A modified inverse distance method is used for 2D and 3D interpolation.
Michael Turner's avatar
Michael Turner committed
559 560
Linear and quadratic interpolation require the data points in the \inlsh{.pts}-file to be
sorted by their location in ascending order.
561
The Inverse Distance implementation has no such requirement.
562 563 564
%
%
%
565
\subsection{Interpolate a field to a series of points: \textit{interppoints} module}
566
You can interpolate one field to a series of given points using the following command:
567
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
568 569
FieldConvert -m interppoints:fromxml=file1.xml:fromfld=\
        file1.fld:topts=file2.pts file2.dat
570
\end{lstlisting}
571
This command will interpolate the field defined by \inltt{file1.xml} and
Mike's avatar
Mike committed
572
\inltt{file1.fld} to the points defined in \inltt{file2.pts} and output it to
573
\inltt{file2.dat}.
574 575 576 577
The \inltt{fromxml} and \inltt{fromfld} must be specified in this module.
The format of the file \inltt{file2.pts} is of the same form as for the
\textit{interppointdatatofld} module:
\begin{lstlisting}[style=XMLStyle]
578 579
<?xml version="1.0" encoding="utf-8" ?>
<NEKTAR>
580
  <POINTS DIM="2" FIELDS="">
581 582 583
    0.0 0.0
    0.5 0.0
    1.0 0.0
584
  </POINTS>
585 586
</NEKTAR>
\end{lstlisting}
587 588
Similar to the \textit{interppointdatatofld} module, the \inltt{.pts} file can
be interchanged with a \inltt{.csv} file:
Kilian Lackhove's avatar
Kilian Lackhove committed
589
\begin{lstlisting}[style=BashInputStyle]
590 591 592 593 594 595
# x, y
0.0,0.0
0.5,0.0
1.0,0.0
\end{lstlisting}

596 597
There are three optional arguments \inltt{clamptolowervalue},
\inltt{clamptouppervalue} and \inltt{defaultvalue} the first two clamp the
Michael Turner's avatar
Michael Turner committed
598 599
interpolation between these two values and the third defines the default
value to be used if the point is outside the domain. Their default values
600
are -10,000,000, 10,000,000 and 0.
601

602
In addition, instead of specifying the file \inltt{file2.pts}, a module list of the form
Michael Turner's avatar
Michael Turner committed
603 604
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m interppoints:fromxml=file1.xml:fromfld= \
605 606
	file1.fld:line=npts,x0,y0,x1,y1
\end{lstlisting}
607 608 609
can be specified where \inltt{npts} is the number of equispaced points between
$(x0,y0)$ to $(x1,y1)$ which can also be used in 3D by specifying $(x0,y0,z0)$
to $(x1,y1,z1)$.
610

611
An extraction of a plane of points can also be specified by
Michael Turner's avatar
Michael Turner committed
612
\begin{lstlisting}[style=BashInputStyle]
613 614
  FieldConvert -m interppoints:fromxml=file1.xml:fromfld=file1.fld:\
        plane=npts1,npts2,x0,y0,z0,x1,y1,z1,x2,y2,z2,x3,y3,z3
615
\end{lstlisting}
Michael Turner's avatar
Michael Turner committed
616 617
where \inltt{npts1,npts2} is the number of equispaced points in each
direction and $(x0,y0,z0)$, $(x1,y1,z1)$, $(x2,y2,z2)$ and $(x3,y3,z3)$
618
define the plane of points specified in a clockwise or anticlockwise direction.
619 620

In addition an extraction of a box of points can also be specified by
Michael Turner's avatar
Michael Turner committed
621
\begin{lstlisting}[style=BashInputStyle]
622 623 624
  FieldConvert -m interppoints:fromxml=file1.xml:fromfld=file1.fld:\
       box=npts1,npts2,npts3,xmin,xmax,ymin,ymax,zmin,zmax
\end{lstlisting}
Michael Turner's avatar
Michael Turner committed
625 626 627
where \inltt{npts1,npts2,npts3} is the number of equispaced points in each
direction and $(xmin,ymin,zmin)$ and $(xmax,ymax,zmax3)$
define the limits of the box of points.
628

Douglas Serson's avatar
Douglas Serson committed
629 630 631 632
There is also an additional optional argument \inltt{cp=p0,q} which adds to the
interpolated fields the value of $c_p=(p-p0)/q$ and $c_{p0}=(p-p0+0.5 u^2)/q$
where $p0$ is a reference pressure and $q$ is the free stream dynamics pressure.
If the input does not contain a field ``p'' or a velocity field ``u,v,w'' then $cp$
633
and $cp0$ are not evaluated accordingly
634
%
Michael Turner's avatar
Michael Turner committed
635
\begin{notebox}
Douglas Serson's avatar
Douglas Serson committed
636
This module  runs in parallel for the line, plane and box extraction of points.
637
\end{notebox}
638 639 640
%
%
%
641 642 643
\subsection{Interpolate a set of points to another: \textit{interpptstopts} module}
You can interpolate one set of points to another using the following command:
\begin{lstlisting}[style=BashInputStyle]
644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671
FieldConvert file1.pts -m interpptstopts:topts=file2.pts file2.dat
\end{lstlisting}
This command will interpolate the data in  \inltt{file1.pts} to a new set
of points defined in \inltt{file2.pts} and output it to
\inltt{file2.dat}.

Similarly to the \textit{interppoints} module, the target point distribution
can also be specified using the \inltt{line}, \inltt{plane} or \inltt{box}
options. The optional arguments \inltt{clamptolowervalue},
\inltt{clamptouppervalue}, \inltt{defaultvalue} and \inltt{cp} are also
supported with the same meaning as in \textit{interppoints}.

One useful application for this module is with 3DH1D expansions, for which
currently the \textit{interppoints} module does not work. In this case, we can
use for example
\begin{lstlisting}[style=BashInputStyle]
FieldConvert file1.xml file1.fld -m interpptstopts:\
    plane=npts1,npts2,x0,y0,z0,x1,y1,z1,x2,y2,z2,x3,y3,z3 \
    file2.dat
\end{lstlisting}
With this usage, the \textit{equispacedoutput} module will be automatically
called to interpolate the field to a set of equispaced points in each element.
The result is then interpolated to a plane by the \textit{interpptstopts} module.

\begin{notebox}
	This module  does not work in parallel.
\end{notebox}

672 673 674
%
%
%
675
\subsection{Isocontour extraction: \textit{iscontour} module}
676 677 678 679 680 681 682

Extract an isocontour from a field file. This option automatically
take the field to an equispaced distribution of points connected by
linear simplicies of triangles or tetrahedrons. The linear simplices
are then inspected to extract the isocontour of interest. To specify
the field \inltt{fieldid} can be provided giving the id of the field
of interest and \inltt{fieldvalue} provides the value of the
Michael Turner's avatar
Michael Turner committed
683
isocontour to be extracted.
684 685 686 687 688 689

\begin{lstlisting}[style=BashInputStyle]
  FieldConvert -m isocontour:fieldid=2:fieldvalue=0.5 test.xml test.fld \
          test-isocontour.dat
\end{lstlisting}

Douglas Serson's avatar
Douglas Serson committed
690 691 692
Alternatively \inltt{fieldstr="u+v"} can be specified to calculate
the field $u+v$ and extract its isocontour. You can also specify
\inltt{fieldname="UplusV"} to define the name of the isocontour in
693 694 695 696 697 698 699 700 701
the .dat file, i.e.
\begin{lstlisting}[style=BashInputStyle]
  FieldConvert -m isocontour:fieldstr="u+v":fieldvalue=0.5:\
    fieldname="UplusV" test.xml  test.fld test-isocontour.dat
\end{lstlisting}

Optionally \inltt{smooth} can be specified to smooth the isocontour
with default values \inltt{smoothnegdiffusion}=0.495,
\inltt{smoothnegdiffusion}=0.5 and \inltt{smoothiter}=100. This option
702 703 704 705 706 707 708
typically should be used wiht the \inltt{globalcondense} option which
removes multiply defined verties from the simplex definition which
arise as isocontour are generated element by element. The
\inltt{smooth} option preivously automatically called the
\inltt{globalcondense} option but this has been depracated since it is
now possible to read isocontour files directly and so it is useful to
have these as separate options.
709

710 711
In addition to the \inltt{smooth} or \inltt{globalcondense} options
you can specify \inltt{removesmallcontour}=100 which will remove
Michael Turner's avatar
Michael Turner committed
712
separate isocontours of less than 100 triangles.
713

714 715
\begin{notebox}
Currently this option is only set up for triangles, quadrilaterals,
Michael Turner's avatar
Michael Turner committed
716
 tetrahedrons and prisms.
717
\end{notebox}
718 719 720 721
%
%
%
%
722

723
\subsection{Show high frequency energy of the Jacobian: \textit{jacobianenergy} module}
724

Michael Turner's avatar
Michael Turner committed
725
\begin{lstlisting}[style=BashInputStyle]
726
FieldConvert -m jacobianenergy file.xml file.fld jacenergy.fld
727 728
\end{lstlisting}

729 730 731
The option \inltt{topmodes} can be used to specify the number of top modes to
keep.

Michael Turner's avatar
Michael Turner committed
732
The output file \inltt{jacenergy.fld} can be processed in a similar
733
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
Michael Turner's avatar
Michael Turner committed
734
to visualise the result either in Tecplot, Paraview or VisIt.
735

736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767
\subsection{Calculate mesh quality: \textit{qualitymetric} module}

The \inltt{qualitymetric} module assesses the quality of the mesh by calculating
a per-element quality metric and adding an additional field to any resulting
output. This does not require any field input, therefore an example usage looks
like

\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m qualitymetric mesh.xml mesh-with-quality.dat
\end{lstlisting}

Two quality metrics are implemented that produce scalar fields $Q$:

\begin{itemize}
  \item By default a metric outlined in~\cite{GaRoPeSa15} is produced, where all
  straight sided elements have quality $Q = 1$ and $Q < 1$ shows the deformation
  between the curved element and the straight-sided element. If $Q = 0$ then the
  element is invalid. Note that $Q$ varies over the volume of the element but is
  not guaranteed to be continuous between elements.
  \item Alternatively, if the \inlsh{scaled} option is passed through to the
  module, then the scaled Jacobian
  \[
    J_s =
    \frac{\min_{\xi\in\Omega_{\text{st}}}J(\xi)}{\max_{\xi\in\Omega_{\text{st}}}J(\xi)}
  \]
  (i.e. the ratio of the minimum to maximum Jacobian of each element) is
  calculated. Again $Q = 1$ denotes an ideal element, but now invalid elements
  are shown by $Q < 0$. Any elements with $Q$ near zero are determined to be low
  quality.
\end{itemize}


768 769 770 771
%
%
%

772
\subsection{Extract mean mode of 3DH1D expansion: \textit{meanmode} module}
773 774 775

To obtain a 2D expansion containing the mean mode (plane zero in Fourier space) of a
3DH1D field file, use the command:
Michael Turner's avatar
Michael Turner committed
776
\begin{lstlisting}[style=BashInputStyle]
777 778 779
FieldConvert -m meanmode file.xml file.fld file-mean.fld
\end{lstlisting}

Michael Turner's avatar
Michael Turner committed
780
The output file \inltt{file-mean.fld} can be processed in a similar
781
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
782
to visualise the result either in Tecplot or in Paraview or VisIt.
783 784 785 786 787 788 789 790 791
%
%
%

\subsection{ Project point data to a field: \textit{pointdatatofld} module}
\label{s:utilities:fieldconvert:sub:pointdatatofld}
To project a series of points given at the same quadrature distribution as the .xml file and write out a .fld file use the pointdatatofld module:
%
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
792
FieldConvert -m pointdatatofld:frompts=file.pts file.xml file.fld
793 794 795 796 797
\end{lstlisting}
%
This command will read in the points provided in the \inltt{file.pts}
and assume these are given at the same quadrature distribution as the
mesh and expansions defined in \inltt{file.xml} and output the field
Michael Turner's avatar
Michael Turner committed
798
to \inltt{file.fld}. If the points do not match an error will be dumped.
799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820


The file \inltt{file.pts} which is assumed to be given by an interpolation from another source is of the form:
%
\begin{lstlisting}[style=XMLStyle]
<?xml version="1.0" encoding="utf-8" ?>
<NEKTAR>
  <POINTS DIM="3" FIELDS="p">
  1.70415 -0.4       -0.0182028      -0.106893
  1.70415 -0.395683  -0.0182028      -0.106794
  1.70415 -0.3875    -0.0182028      -0.106698
  1.70415 -0.379317  -0.0182028      -0.103815
  </POINTS>
</NEKTAR>
\end{lstlisting}
%
where \inltt{DIM="3" FIELDS="p} specifies that the field is
three-dimensional and contains one variable, $p$. Each line defines a
point, the first, second, and third columns contains the
$x,y,z$-coordinate and subsequent columns contain the field values, in
this case the $p$-value So in the general case of $n$-dimensional
data, the $n$ coordinates are specified in the first $n$ columns
821 822
accordingly followed by the field data. Alternatively, the \inltt{file.pts}
can be interchanged with a csv file.
823

Douglas Serson's avatar
Douglas Serson committed
824
The default argument is to use the equispaced (but potentially
825 826 827 828 829 830
collapsed) coordinates which can  be obtained from the command.

\begin{lstlisting}[style=BashInputStyle]
FieldConvert file.xml file.dat
\end{lstlisting}

Douglas Serson's avatar
Douglas Serson committed
831
In this case the pointdatatofld module should be used without the
832 833 834 835
\inltt{--noequispaced} option. However this can lead to problems when
peforming an elemental forward projection/transform since the mass
matrix in a deformed element can be singular as the equispaced points
do not have a sufficiently accurate quadrature rule that spans the
Douglas Serson's avatar
Douglas Serson committed
836
polynomial space. Therefore it is advisable to use the set of points
837 838 839 840 841 842 843
given by

\begin{lstlisting}[style=BashInputStyle]
FieldConvert --noequispaced file.xml file.dat
\end{lstlisting}

which produces a set of points at the gaussian collapsed
Douglas Serson's avatar
Douglas Serson committed
844
coordinates.
845 846 847 848 849

Finally the option \inltt{setnantovalue=0} can also be used which sets
any nan values in the interpolation to zero or any specified value in
this option.

850 851 852 853
%
%
%

854
\subsection{Print L2 and LInf norms: \textit{printfldnorms} module}
855

Michael Turner's avatar
Michael Turner committed
856
\begin{lstlisting}[style=BashInputStyle]
857
FieldConvert -m printfldnorms test.xml test.fld out.stdout
858
\end{lstlisting}
Gianmarco Mengaldo's avatar
Gianmarco Mengaldo committed
859

860
This module does not create an output file which is reinforced by the
861
out.stdout option. The L2 and LInf norms for each field variable are
862
then printed to the stdout.
863 864 865 866
%
%
%

867
\subsection{Computes the scalar gradient: \textit{scalargrad} module}
868
The scalar gradient of a field is computed by running:
Michael Turner's avatar
Michael Turner committed
869
\begin{lstlisting}[style=BashInputStyle]
870 871
FieldConvert -m scalargrad:bnd=0 test.xml test.fld test-scalgrad.fld
\end{lstlisting}
Michael Turner's avatar
Michael Turner committed
872
The option \inltt{bnd} specifies which boundary region to extract. Note this is different to NekMesh where the parameter \inltt{surf} is specified and corresponds to composites rather boundaries. If \inltt{bnd} is not provided, all boundaries are extracted to different fields. To process this file you will need an xml file of the same region.
873 874 875 876 877

%
%
%

878
\subsection{Scale a given .fld: \textit{scaleinputfld} module}
879
To scale a .fld file by a given scalar quantity, the user can run:
Michael Turner's avatar
Michael Turner committed
880
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
881
FieldConvert -m scaleinputfld:scale=value test.fld test-scal.fld
Gianmarco Mengaldo's avatar
Gianmarco Mengaldo committed
882
\end{lstlisting}
Michael Turner's avatar
Michael Turner committed
883
The argument \inltt{scale=value} rescales of a factor \inltt{value}
Gianmarco Mengaldo's avatar
Gianmarco Mengaldo committed
884
\inltt{test.fld} by the factor value.
Douglas Serson's avatar
Douglas Serson committed
885
The output file \inltt{file-scal.fld} can be processed in a similar
Gianmarco Mengaldo's avatar
Gianmarco Mengaldo committed
886
way as described in section \ref{s:utilities:fieldconvert:sub:convert}
887
to visualise the result  either in Tecplot, Paraview or VisIt.
Gianmarco Mengaldo's avatar
Gianmarco Mengaldo committed
888

889 890 891
%
%
%
892
\subsection{Time-averaged shear stress metrics: \textit{shear} module}
893 894 895 896 897 898 899 900 901 902
Time-dependent wall shear stress derived metrics relevant to cardiovascular fluid dynamics research can be computed using this module. They are

\begin{itemize}
\item TAWSS: time-averaged wall shear stress;
\item OSI: oscillatory shear index;
\item transWSS: transverse wall shear stress;
\item TACFI: time-averaged cross-flow index;
\item TAAFI: time-averaged aneurysm formation index;
\item |WSSG|: wall shear stress gradient.
\end{itemize}
903

904
To compute these, the user can run:
Michael Turner's avatar
Michael Turner committed
905
\begin{lstlisting}[style=BashInputStyle]
Douglas Serson's avatar
Douglas Serson committed
906 907
FieldConvert -m shear:N=value:fromfld=test_id_b0.fld \
    test.xml test-multishear.fld
908
\end{lstlisting}
Michael Turner's avatar
Michael Turner committed
909
The argument \inltt{N} and \inltt{fromfld} are compulsory arguments that respectively define the number of \inltt{fld} files corresponding to the number of discrete equispaced time-steps, and the first \inltt{fld} file which should have the form of \inltt{test\_id\_b0.fld} where the first underscore in the name marks the starting time-step file ID.
Yumnah Mohamied's avatar
Yumnah Mohamied committed
910

Michael Turner's avatar
Michael Turner committed
911
The input \inltt{.fld} files are the outputs of the \textit{wss} module. If they do not contain the surface normals (an optional output of the \textit{wss} modle), then the \textit{shear} module will not compute the last metric, |WSSG|.
912

Douglas Serson's avatar
Douglas Serson committed
913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932
%
%
%
\subsection{Stream function of a 2D incompressible flow: \textit{streamfunction} module}

The streamfunction module calculates the stream function of a 2D incompressible flow, by
solving the Poisson equation
\[
\nabla^2 \psi = -\omega
\]
where $\omega$ is the vorticity. Note that this module applies the same boundary conditions
specified for the y-direction velocity component \inltt{v} to the stream function,
what may not be the most appropriate choice.

To use this module, the user can run
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m streamfunction test.xml test.fld test-streamfunc.fld
\end{lstlisting}
where the file \inltt{test-streamfunc.fld} can be processed in a similar
way as described in section \ref{s:utilities:fieldconvert:sub:convert}.
Dave Moxey's avatar
Dave Moxey committed
933 934 935 936 937 938

%
%
%
\subsection{Boundary layer height calculation: \textit{surfdistance} module}

Douglas Serson's avatar
Douglas Serson committed
939 940
The surface distance module computes the height of a boundary layer formed by
quadrilaterals (in 2D) or prisms and hexahedrons (in 3D)
Dave Moxey's avatar
Dave Moxey committed
941 942
and projects this value onto the surface of the boundary, in a similar fashion
to the \inltt{extract} module. In conjunction with a mesh of the surface, which
Michael Turner's avatar
Michael Turner committed
943
can be obtained with \inltt{NekMesh}, and a value of the average wall shear
Dave Moxey's avatar
Dave Moxey committed
944 945 946 947 948 949 950 951 952 953 954
stress, one potential application of this module is to determine the
distribution of $y^+$ grid spacings for turbulence calculations.

To compute the height of the prismatic layer connected to boundary region 3, the
user can issue the command:
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m surfdistance:bnd=3 input.xml output.fld
\end{lstlisting}
Note that no \inltt{.fld} file is required, since the mesh is the only input
required in order to calculate the element height. This produces a file
\inltt{output\_b3.fld}, which can be visualised with the appropriate surface
Michael Turner's avatar
Michael Turner committed
955
mesh from \inltt{NekMesh}.
Dave Moxey's avatar
Dave Moxey committed
956

957 958 959
%
%
%
960
\subsection{Calculate vorticity: \textit{vorticity} module}
Michael Turner's avatar
Michael Turner committed
961
To perform the vorticity calculation and obtain an output
962 963 964 965
data containing the vorticity solution, the user can run
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m vorticity test.xml test.fld test-vort.fld
\end{lstlisting}
Michael Turner's avatar
Michael Turner committed
966
where the file \inltt{test-vort.fld} can be processed in a similar
967 968 969 970
way as described in section \ref{s:utilities:fieldconvert:sub:convert}.
%
%
%
971

972
\subsection{Computing the wall shear stress: \textit{wss} module}
973
To obtain the wall shear stres vector and magnitude, the user can run:
Michael Turner's avatar
Michael Turner committed
974
\begin{lstlisting}[style=BashInputStyle]
975 976
FieldConvert -m wss:bnd=0:addnormals=1 test.xml test.fld test-wss.fld
\end{lstlisting}
Douglas Serson's avatar
Douglas Serson committed