\section{Field Convert}
\label{s:utilities:fieldconvert}

In this section, the capabilities of the field convert utility are explained. This utility allows the user to convert and add extra output data to the already existing output data (.fld or .chk file) given by running a solver in \nekpp. The new output data is converted into a format that is compatible with the available external visualizers like Tecplot or Paraview. For now, this utility has the following functionality:
\begin{itemize}
\item Convert a .fld file to a .vtu or .dat file
\item Calculate vorticity
\item Extract a boundary region
\item Specify a sub-range of the domain
\end{itemize}
Converting an output file that has been obtained using \nekpp into a .dat file goes then as follows:
\begin{lstlisting}[style=BashInputStyle]
FieldConvert test.xml test.fld test.dat
\end{lstlisting}
%---------------------------------------------------------------
\subsection{Calculating vorticity}
To perform the vorticity calculation and obtain an output data containing the vorticity solution, the executable FieldConvert has to be run. This executable can be found in:\\
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m vorticity test.xml test.fld test-vort.fld
\end{lstlisting}
where the file test-vort.fld can be processed in a similar way as described above to visualise the solution.
%---------------------------------------------------------------
\subsection{Sub-range of the domain}
One can also select a region in the computational domain and process only the data for that part of the domain. For example for processing the data of a 2D plane defined by $-2\leq x \leq 3$, $-1\leq y \leq 2$, the following command can be run:\\
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -r -2,3,-1,2  test.xml test.fld test.dat
\end{lstlisting}
where -r defines the range option of the field convert utility, the two first numbers define the range in $x$ direction and the the third and forth number specify the $y$ range. The a 3D part of the domain, a third set of numbers has to be provided to define the $z$ range. For calculating the vorticity in a specified part of the computational domain, the following command line can be run:\\
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -r -2,3,-1,2 -m vorticity test.xml test.fld test-vort.fld
\end{lstlisting}
%---------------------------------------------------------------
\subsection{Extracting a boundary region}
The boundary region of a domain be extracted from the output data using the following command line
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m extract:bnd=2:fldtoboundary=1 test.xml test.fld \
        test-boundary.fld
\end{lstlisting}
The option \inltt{bnd} specifies which boundary region to extract. Note this is different to MeshConvert where the parameter \inltt{surf} is specified and corresponds to composites rather boundaries. If bnd is to provided all boundaries are extracted to different field. The fldtoboundary is an optional command argument which copies the expansion of test.fld into the boundary region before outputting the .fld file. This option is on by default. If it turned off using \inltt{fldtoboundary=0} the extraction will only evaluate the boundary condition from the xml file. 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 outputted. To process this file you will need an xml file of the same region. This can be generated using the command:
\begin{lstlisting}[style=BashInputStyle]
MeshConvert -m extract:surf=5  test.xml test-b0.xml
\end{lstlisting}
The surface to be extracted in this command is the composite number and so needs to correspond to the boundary region of interest. Finally to process the surface file one can use
\begin{lstlisting}[style=BashInputStyle]
MeshConvert -m extract:surf=5  test.xml test-b0.xml
\end{lstlisting}
This will obviously generate a tecplot output using a .dat file is specified in the last argument. A .vtu extension will produce a vtk output.

To run the utility, if you have compiled \nekpp with MPI support, you may run in
parallel
\begin{lstlisting}[style=BashInputStyle] mpirun -np <nprocs>
FieldConvert test.xml test.fld test.dat
\end{lstlisting}
replacing <nprocs> with the number of processors. This will produce multiple
.dat files of the form test-P0.dat, test-P1.dat, test-P2.dat etc. Similarly the
VTK files can be processed in this manner as can the vorticity option. In the
case of the vorticity option a directory called test-vort.fld (or the specified
output name) will be produced with the standard parallel field files placed
within the directory.
%---------------------------------------------------------------
\subsection{Interpolating one filed to another}
You can interpolate one field to another using the following command:
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m interpfield:fromxml=file1.xml:fromfld=file1.fld \
        file2.xml file2.fld
\end{lstlisting}

This command will interpolate the field defined by \inlsh{file1.xml} and
\inlsh{file1.fld} to the new mesh defined in \inlsh{file2.xml} and output it to
\inlsh{file2.fld}.
The \inlsh{fromxml} and \inlsh{fromfld} must be specified in this module. In
addition there are two optional arguments \inltt{clamptolowervalue} and
\inltt{clamptouppervalue} which clamp the interpolation between these two
values. Their default values are -10,000,000 and 10,000,000.

\begin{tipbox}
This module can run in parallel where the speed is increased not
only due to using more cores but also, since the mesh is split into smaller
sub-domains, the search method currently adopted performs faster.
\end{tipbox}

% ---------------------------------------------------------------
\subsection{Interpolating a field to a series of points}
You can interpolate one field to a series of point given in using the following
command:
\begin{lstlisting}[style=BashInputStyle]
FieldConvert -m interppoints:fromxml=from.xml:file1.xml=file1.fld \
        file2.pts file2.dat
\end{lstlisting}
This command will interpolate the field defined by \inlsh{file1.xml} and
\inlsh{file1.fld} to the points defined in \inlsh{file2.xml} and output it to
\inlsh{file2.dat}.
The \inlsh{fromxml} and \inlsh{fromfld} must be specified in this module. The
format of the file \inlsh{file2.pts} is of the form
\begin{lstlisting}[style=XMLStyle] 
<?xml version="1.0" encoding="utf-8" ?>
<NEKTAR>
  <POINTS DIM="2">
    0.0 0.0 0.5 0.0 1.0 0.0
  </POINTS>
</NEKTAR>
\end{lstlisting}
There are three optional arguments \inltt{clamptolowervalue},
\inltt{clamptouppervalue} and \inltt{defaultvalue} the first two clamp the
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 are
-10,000,000, 10,000,000 and 0.

In addition instead of specifying the file \inlsh{file2.pts} a module list of
the form \\
\inlsh{-m interppoints:fromxml=file1.xml:fromfld=file1.fld:line=npts,x0,y0,x1,y1}
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)$.

There is also an extraction of a plane of point which is specified by \\
\inltt{-m interppoints:fromxml=file1.xml:fromfld=file1.fld:plane=npt1, \\
npts2,x0,y0,z0,x1,y1,z1,x2,y2,z2,x3,y3,z3} 
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)$ define the plane
of points specified in a clockwise or anticlockwise direction.

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


\subsection{Running in parallel}
To run the utility, if you have compiled Nektar++ with MPI support, you may run
in parallel. For example,
\begin{lstlisting}[style=BashInputStyle]
mpirun -np <nprocs> FieldConvert test.xml test.fld test.dat
\end{lstlisting}
replacing \inltt{<nprocs>} with the number of processors. This will produce 
multiple \inltt{.dat} files of the form \inltt{test\_P0.dat}, 
\inltt{test\_P1.dat}, \inltt{test\_P2.dat}. Similarly the VTK files can be
processed in this manner as can the vorticity option. In the case of the 
vorticity option a directory called \inltt{test\_vort.fld} (or the specified 
output name) will be produced with the standard parallel field files placed 
within the directory


\subsection{Processing large files}
When processing large files it is not always convenient to run in parallel but 
process each parallel partition in serial, for example when interpolating one 
field to another. To do this we can use the \inltt{--nprocs} and 
\inltt{--procid} options. For example the following option will interpolate 
partition 2 of a decomposition into 10 partitions of \inltt{fiile2.xml} from 
\inltt{file1.fld}
\begin{lstlisting}[style=BashInputStyle] 
FieldConvert --nprocs 10 --procid 2 \
        -m interpfield:fromxml=file1.xml:fromfld=file1.fld \
        file2.xml file2.fld
\end{lstlisting}
This call will only provide part of the overall partition and so to create the 
full interpolated field you need to call a loop of such commands. For example in 
a bash shell you can run
\begin{lstlisting}[style=BashInputStyle] 
for n in `seq 0 1 9`
do 
    FieldConvert --nprocs 10 --procid $n \ 
            -m interpfield:fromxml=file1.xml:fromfld=file1.fld \
            file2.xml file2.fld
done
\end{lstlisting}

This will create a directory called \inltt{file2.fld} and put the different 
parallel partitions into files with names 
\inltt{P0000000.fld, P0000001.fld, ?., P0000009.fld}. This is nearly a complete
parallel field file but the Info.xml file which contains the information about 
which elements are in each partitioned file \inltt{P000000X.fld}. So to generate
this Info.xml file you need to call
\begin{lstlisting}[style=BashInputStyle] 
FieldConvert --nprocs 10 file2.xml file2.fld/Info.xml:info
\end{lstlisting}
Note the final \inltt{:info} extension on the last argument is necessary to tell
FieldConvert that you wish to generate an info file but the extension to this
file is .xml. This syntax allows the routine not to get confused with the
input/output xml files.
