Add metadata and some documentation

docs/user-guide/utilities/fieldconvert.tex

 \chapter{FieldConvert}
 \label{s:utilities:fieldconvert}
-FieldConvert is a utility embedded in \nekpp with the primary aim of
-allowing the user to convert the \nekpp output binary files (.chk and
-.fld) into a format which can be read by two common visualisation
-softwares: Paraview/VisIt (.vtu format) or Tecplot/VisIt (.dat or .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.
+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.
 
 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
@@ -19,6 +19,49 @@ how to implement \nekpp using MPI). \footnote{Modules that do not have parallel
 %
 %
 %
+\section{Basic usage}
+FieldConvert expects at least one input file (such as a session file and its
+corresponding field file) and one output file. These are specified on the
+command line as
+%
+\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}.
+
 \section{Convert .fld / .chk files into Paraview, VisIt or Tecplot format}
 \label{s:utilities:fieldconvert:sub:convert}
 To convert the \nekpp output binary files (.chk and .fld) into a

library/FieldUtils/InputModules/InputSemtex.cpp

@@ -78,9 +78,6 @@ InputSemtex::~InputSemtex()
  * memory and populates the field definitions to match the data format. Semtex
  * is a classic nodal-Lagrangian spectral element code at a single polynomial
  * order, meaning that the field data are set up according to this structure.
- *
- * This module is adapted from the VisIt visualisation software, which supports
- * a number of Semtex inputs.
  */
 void InputSemtex::Process(po::variables_map &vm)
 {
@@ -92,12 +89,12 @@ void InputSemtex::Process(po::variables_map &vm)
         }
     }
 
+    // Variables to be read from session file
     string sessionName, date, fields, endian;
     int nr, ns, nz, nelmt, step;
     NekDouble time, dt, kinvis, beta;
 
-    string fldending = "fldsem";
-    ifstream file(m_f->m_inputfiles[fldending][0].c_str(), ios::binary);
+    ifstream file(m_f->m_inputfiles["fldsem"][0].c_str(), ios::binary);
 
     // -- Read header information.
     char buf[25];
@@ -108,6 +105,7 @@ void InputSemtex::Process(po::variables_map &vm)
     sessionName = string(buf, 25);
     boost::trim(sessionName);
     getline(file, line);
+    m_f->m_fieldMetaDataMap["SessionName0"] = sessionName;
 
     // Date
     file.read(buf, 25);
@@ -126,14 +124,17 @@ void InputSemtex::Process(po::variables_map &vm)
     // Time
     file >> time;
     getline(file, line);
+    m_f->m_fieldMetaDataMap["Time"] = boost::lexical_cast<string>(time);
 
     // Timestep
     file >> dt;
     getline(file, line);
+    m_f->m_fieldMetaDataMap["TimeStep"] = boost::lexical_cast<string>(dt);
 
     // Viscosity
     file >> kinvis;
     getline(file, line);
+    m_f->m_fieldMetaDataMap["Kinvis"] = boost::lexical_cast<string>(kinvis);
 
     // Beta
     file >> beta;
@@ -145,7 +146,7 @@ void InputSemtex::Process(po::variables_map &vm)
     boost::trim(fields);
     getline(file, line);
 
-    // TODO Endian-ness
+    // Endian-ness
     LibUtilities::EndianType systemEndian =  LibUtilities::Endianness();
     std::string endianSearch;
     if (systemEndian == LibUtilities::eEndianBig)