\section{Geometry}
This section defines the mesh. It specifies a list of vertices, edges (in two or
three dimensions) and faces (in three dimensions) and how they connect to create
the elemental decomposition of the domain. It also defines a list of composites
which are used in the Expansions and Conditions sections of the file to describe
the polynomial expansions and impose boundary conditions.

The GEOMETRY section is structured as
\begin{lstlisting}[style=XMLStyle]
<GEOMETRY DIM="2" SPACE="2">
  <VERTEX> ... </VERTEX>
  <EDGE> ... </EDGE>
  <FACE> ... </FACE>
  <ELEMENT> ... </ELEMENT>
  <CURVED> ... </CURVED>
  <COMPOSITE> ... </COMPOSITE>
  <DOMAIN> ... </DOMAIN>
</GEOMETRY>
\end{lstlisting}
It has two (required) attributes:
\begin{itemize}
    \item \inltt{DIM} specifies the dimension of the expansion elements.
    \item \inltt{SPACE} specifies the dimension of the space in which the
    elements exist.
\end{itemize}
These attributes allow, for example, a two-dimensional surface to be embedded in
a three-dimensional space.

\begin{notebox}
The attribute \inltt{PARTITION} may also appear in a partitioned mesh.
However, this attribute should not be explicitly specified by the user.
\end{notebox}

The contents of each of the \inltt{VERTEX}, \inltt{EDGE}, \inltt{FACE}, \inltt{ELEMENT}
and \inltt{CURVED} sections may optionally be compressed and stored in
base64-encoded gzipped binary form, using either little-endian or big-endian
ordering, as specified by the \inltt{COMPRESSED} attribute to these sections.
Currently supported values are:
\begin{itemize}
    \item \inltt{B64Z-LittleEndian}: Base64 Gzip compressed using little-endian
        ordering.
    \item \inltt{B64Z-BigEndian}: Base64 Gzip compressed using big-endian
        ordering.
\end{itemize}
When generating mesh input files for \nekpp using \inltt{NekMesh}, the binary compressed form will be used by default. To convert a compressed XML file into
human-readable ASCII format use, for example:
\begin{lstlisting}[style=BashInputStyle]
NekMesh file.msh newfile.xml:xml:uncompress
\end{lstlisting}

\begin{notebox}
The description in the remainder of this section explains how the \inltt{GEOMETRY} section is laid out in uncompressed ASCII format.
\end{notebox}


\subsection{Vertices}

Vertices have three coordinates. Each has a unique vertex ID. In
uncompressed form, they are defined within \inltt{VERTEX} subsection as follows:
\begin{lstlisting}[style=XMLStyle] <VERTEX>
<V ID="0"> 0.0  0.0  0.0 </V> ...
\end{lstlisting}
The \inltt{VERTEX} subsection has optional attributes which can be used to
apply a transformation to the mesh:\\
\inltt{XSCALE}, \inltt{YSCALE}, \inltt{ZSCALE},
\inltt{XMOVE}, \inltt{YMOVE}, \inltt{ZMOVE}, \inltt{ZROT}

They specify scaling factors (centred at the origin), translations to
the vertex coordinates as well as a rotational factor about the
z-axis. For example, the following snippet
\begin{lstlisting}[style=XMLStyle]
<VERTEX XSCALE="5">
  <V ID="0"> 0.0  0.0  0.0 </V>
  <V ID="1"> 1.0  2.0  0.0 </V>
</VERTEX>
\end{lstlisting}
defines two vertices with coordinates $(0.0,0.0,0.0), (1.0,2.0,0.0)$.

All of these attributes can be arbitrary analytic expressions depending on pre-
defined constants and parameters defined in the XML file and
mathematical operations/functions of the latter. If omitted, default scaling
factors 1.0, and translations of 0.0, and zero rotation,  are assumed.



\subsection{Edges}
\begin{tipbox}
    The \inltt{EDGES} section is only necessary when \inltt{DIM=2} or
    \inltt{DIM=3} in the parent \inltt{GEOMETRY} element and may be omitted for
    one-dimensional meshes.
\end{tipbox}

Edges are defined by two vertices. Each edge has a unique edge ID. In
uncompressed form, they are defined in the file with a line of the form
\begin{lstlisting}[style=XMLStyle]
<E ID="0"> 0 1 </E>
\end{lstlisting}


\subsection{Faces}
\begin{tipbox}
    The \inltt{FACES} section is only necessary when \inltt{DIM=3} in the
    parent \inltt{GEOMETRY} element and may otherwise be omitted.
\end{tipbox}

Faces are defined by three or more edges. Each face has a unique face ID. They
are defined in the file with a line of the form
\begin{lstlisting}[style=XMLStyle]
<T ID="0"> 0 1 2 </T>
<Q ID="1"> 3 4 5 6 </Q>
\end{lstlisting}
The choice of tag specified (T or Q), and thus the number of edges specified depends on the geometry of the face (triangle or quadrilateral).


\subsection{Element}
Elements define the top-level geometric entities in the mesh. Their definition depends upon the dimension of the expansion. For two-dimensional expansions, an element is defined by a sequence of three or four edges. For three-dimensional expansions, the element is defined by a list of faces. Elements are defined in the file with a line of the form
\begin{lstlisting}[style=XMLStyle]
<T ID="0"> 0 1 2 </T>
<H ID="1"> 3 4 5 6 7 8 </H>
\end{lstlisting}
Again, the choice of tag specified depends upon the geometry of the element. The element tags are:

\begin{itemize}
    \item \inltt{S} Segment
    \item \inltt{T} Triangle
    \item \inltt{Q} Quadrilateral
    \item \inltt{A} Tetrahedron
    \item \inltt{P} Pyramid
    \item \inltt{R} Prism
    \item \inltt{H} Hexahedron
\end{itemize}


\subsection{Curved Edges and Faces}
\begin{tipbox}
    The \inltt{CURVED} section is only necessary if curved edges or faces are
    present in the mesh and may otherwise be omitted.
\end{tipbox}

For mesh elements with curved edges and/or curved faces, a separate entry is used to describe the control points for the curve. Each curve has a unique curve ID and is associated with a predefined edge or face. The total number of points in the curve (including end points) and their distribution is also included as attributes. The control points are listed in order, each specified by three coordinates. Curved edges are defined in the file with a line of the form
\begin{lstlisting}[style=XMLStyle]
<E ID="3" EDGEID="7" TYPE="PolyEvenlySpaced" NUMPOINTS="3">
    0.0  0.0  0.0    0.5  0.5  0.0    1.0  0.0  0.0
</E>
\end{lstlisting}

\begin{notebox}
    In the compressed form, this section contains different sub-elements to
    efficiently encode the high-order curvature data. This is not described
    further in this document.
\end{notebox}

\subsection{Composites}
Composites define collections of elements, faces or edges. Each has a unique composite ID associated with it. All components of a composite entry must be of the same type. The syntax allows components to be listed individually, using ranges, or a mixture of the two. Examples include
\begin{lstlisting}[style=XMLStyle]
<C ID="0"> T[0-862] </C>
<C ID="1"> E[61-67,69,70,72-74] </C>
\end{lstlisting}

The composites can also optionally contain a name which is then used in the
multi-block VTK output to label the block descriptively rather than by ID, for
example
\begin{lstlisting}[style=XMLStyle]
<C NAME="Main domain" ID="0"> T[0-862] </C>
<C NAME="Walls" ID="1"> E[61-67,69,70,72-74] </C>
\end{lstlisting}

\subsection{Domain}
This tag specifies composites which describe the entire problem domain. It has the form of
\begin{lstlisting}[style=XMLStyle]
<DOMAIN> C[0] </DOMAIN>
\end{lstlisting}
