arh2_file_format.tex

\documentclass[10pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{longtable}
\usepackage{multirow}
\usepackage{bigdelim}
\usepackage{bigstrut}
\usepackage[left=1.5cm,right=2cm,top=2cm,bottom=2cm]{geometry}


\newcommand{\for}{$\triangleright$ \texttt{FOR} }
\newcommand{\first}[1]{\multicolumn{2}{l|}{#1}}
\newcommand{\second}[1]{\multicolumn{3}{l|}{#1}}
\newcommand{\third}[1]{\multicolumn{4}{l|}{#1}}

\author{Simon Praetorius}
\date{2015-03-02}
\title{File format description for ARH Version 3.0}

\begin{document}
\maketitle
\begin{abstract}
This document describes the AMDiS Refinement Hierarchy (ARH) File format, version 3.0. The file format includes a description of the refinement of mesh-elements and value containers for the degrees of freedom (DOFs) for a given Finite Element. The concrete definition of finite elements is thereby described in a separate file format (AMDiS Finite Element Description (AFED) ) given elsewhere.

Historically the ARH format is based on the format from 2010 by Thomas Witkowski and Florian Stenger.

Please send comments on ARH to the AMDiS form:\\ \url{https://fusionforge.zih.tu-dresden.de/forum/?group_id=11}\\or post the comments on the Wiki:\\
\url{https://fusionforge.zih.tu-dresden.de/plugins/mediawiki/wiki/amdis}
\end{abstract}

\section{Version history}
\begin{description}
\item[Version 3.0: March 02, 2015] The file descriptor is now \texttt{sARH} for sequential ARH file format, since a new file format for parallel data (pARH) is added. Definition and description of Finite Elements was restructured and extracted from the ARH file format and put into a new file format.

\item[Version 2.1: May 20, 2014] A zlib compression for the file was added.

\item[Version 2.0: November 29, 2013] First official release of the ARH version 2 file format. The format consists of two parts, the \textit{header} and the \textit{body}. The header contains the general information about the content in this file, the format version number, the header size, dimensions, a macro table, an simplified Finite Element description and a value table. The header is followed by body structure for each macro element, which includes mesh structure code and DOF value vectors. 

\item [Version 1.1, December 2010] Format description, as implemented in AMDiS.

\item[Version 1.0: July 29, 2010] First format description of original ARH file format. Implemented by MeshConv.
\end{description}

\section{The sARH file format}
The sARH file format to describe local macro-element wise mesh structure and data on the macro elements consists of four sections: 
\begin{enumerate}
\item The first section contains a file format descriptor and version informations. This can be used to distinguish between the old ARH format and the ARH2 format and all of its versions, i.e. test whether the reader supports the actual format.

\item The second part contains header information about the data stored in the file. This contains information about the dimension of the mesh and the elements, amount of data stored in the file and some flags concerning the data format and compression of the data.

\item The third part contains information about the macro-elements stored in the file, about the different finite elements spaces of the value vectors stored in the file and a list of the value vectors including addition information used to extract only parts of the data from file.

\item The last block contains for all macro element the structure code (an information how to refine a macro element) and all values stored on this macro element.
\end{enumerate}

The concrete structure is given in the table below:
\newpage
\begin{longtable}{p{.01\linewidth}p{.18\linewidth}|p{.1\linewidth}|p{.09\linewidth}|p{.55\linewidth}}
&\textbf{Field} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline\endfirsthead
&\textbf{Field} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline
\multicolumn{5}{r}{\textit{(Continued from last page)}}\\\endhead
\multicolumn{5}{r}{\textit{(Continued on next page)}}\\\endfoot
\multicolumn{5}{r}{\textit{(End of header)}}\\\endlastfoot

\first{fd} & 4 & string & Format descriptor (lower case) [\texttt{sarh}] \\
\first{maj} & 1 & uchar & major version [3] \\
\first{min} & 1 & uchar & minor version [0] \\\hline
\first{hs} & 4 & uint & header size \\
\first{dow} & 4 & uint & dimension of world \\
\first{dim} & 4 & uint & dimension of the mesh \\
\first{\#fes} & 4 & uint & number of Finite Element spaces \\
\first{\#vec} & 4 & uint & number of value vectors \\
\first{\#el} & 4 & uint & number of macro elements \\
\first{cps} & 4 & int & compression flag: \texttt{0}: no compression, \texttt{1}: ZLib compression\footnote{Details of ZLib Version, Parameters etc.}, \texttt{2}: BZip2 \\\hline

& & & & \\
\first{\for $i=0,\ldots,$\#el-1} & & &\\
\ldelim[{3}{1mm} & macro[i]$\rightarrow$index & 4 & uint & global index of the macro element \\
& macro[i]$\rightarrow$pos & 4 & uint & position of the macro description in this file \\
& macro[i]$\rightarrow$size & 4 & uint & uncompressed size of the data block for the macro element \\

\first{index\_end} & 4 & uint & index to indicate the end of the macro list [-1] \\
\first{pos\_end} & 4 & uint & size of the compressed file \\
\first{size\_end} & 4 & uint & (size of the uncompressed file $|$ 0)\footnote{This value is not needed, thus an arbitrary value could be stored.} \\

& & & & \\
\first{\for $i=0,\ldots,$\#fes-1} & & &\\
\ldelim[{3}{1mm} & fe[i]$\rightarrow$nl & 4 & uint & length of filename w.o. suffix (0: default Lagrange elements) \\
\ldelim[{3}{1mm} & fe[i]$\rightarrow$ID & nl & string & name of file (w.o. suffix) with description of Finite Element in AFED format \\
& fe[i]$\rightarrow$DOFs/pos & 16 & $4\times$uint & number of DOFs per position (vertex, edge, face, center) \\

& & & & \\
\first{\for $i=0,\ldots,$\#vec-1} & & & \\
\ldelim[{4}{1mm} & vec[i]$\rightarrow$nl & 4 & uint & length of name \\
& vec[i]$\rightarrow$name & nl & string & name of the value vector\\
& vec[i]$\rightarrow$fe & 4 & uint & index of the fe it belongs to\\
& vec[i]$\rightarrow$type & 4 & string & value-type descriptor: \texttt{[SU][IF][0-9]+}\footnote{regular expression: \texttt{[SU]} signed/unsigned, \texttt{[IF]} integer/float, \texttt{[0-9]+} number of bits (08/16/32/64)} default: \texttt{SF64}\\

& & & & \\\hline
\end{longtable}

\begin{longtable}{p{.01\linewidth}p{.01\linewidth}p{.01\linewidth}p{.16\linewidth}|p{.1\linewidth}|p{.05\linewidth}|p{.53\linewidth}}
\third{\textbf{Field}} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline\endfirsthead
\third{\textbf{Field}} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline
\multicolumn{7}{r}{\textit{(Continued from last page)}}\\\endhead
\multicolumn{7}{r}{\textit{(Continued on next page)}}\\\endfoot
\multicolumn{7}{r}{\textit{(End of body)}}\\\endlastfoot

& & & & & & \\
\third{\for Macro[i], $i=0,\ldots,$\#el-1} & & &\\
\ldelim[{10}{1mm} & \second{\#codes} & 4 & uint & number of structure codes \\
& \second{\#bits} & 4 & uint & total number of bits for structure codes \\
& \second{code-data} & $8\times$\#codes & uint & all structure codes \\
& & & & & & \\

& \second{\for $j=0,\ldots,$\#fes-1} & & & \\
& \ldelim[{5}{1mm} & \first{\#el\_val} & 4 & uint & number of values per vector in fespace fe[$j$] \\
& & & & & & \\

& & \first{\for $k=0,\ldots,N_j-1$} & & & \\
& & \ldelim[{2}{1mm} & data[$i_k(j)$] & $X\times$\#el\_val & \texttt{T} & sequence of values\footnote{Value vectors are ordered in the same way as in the vec array of the header, when assigned to an fespace. Thus fe[j]$\rightarrow$vectors=\{vec[$i_0(j)$], vec[$i_1(j)$],\ldots\}, with $i_0(j) < i_1(j) < \ldots$ and vec[$i_k(j)$]$\rightarrow$fe == $j$ for $k=0,\ldots,N_j-1$ and $N_j:=$size(fe[j]$\rightarrow$vectors)}, $N_j$: number of value vector belonging to fe[$j$], $X$: size of data-type \texttt{T} $\triangleq$ vec[$i_k(j)$)]$\rightarrow$type.\\

& & & & & & \\\hline
\end{longtable}

\section{The pARH file format}
To describe the distribution of macro elements and the partition of a macro mesh among several processors a container format is defined. This can be used to improve performance of parallel file reading. The file consists of four section:
\begin{enumerate}
\item The first section contains a file descriptor and version information, as in the sARH file.
\item In the second part information about the 
\end{enumerate}

\end{document}