Documentation of Arh2 file format ver. 3.0 added

doc/arh2_file_format.tex

@@ -7,28 +7,30 @@
 \usepackage{hyperref}
 \usepackage{longtable}
 
+\newcommand{\for}{$\triangleright$ \texttt{FOR} }
+
 \author{Simon Praetorius}
 \date{2015-03-02}
-\title{File format description for ARH2 Version 3.0}
+\title{File format description for ARH Version 3.0}
 
 \begin{document}
 \maketitle
 \begin{abstract}
-This document describes the AMDiS Refinement Hierarchy 2 (ARH2) 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.
+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 ARH2 format is based on the ARH format from 2010 (* placeholder for the actual date).
+Historically the ARH format is based on the format from 2010 by Thomas Witkowski and Florian Stenger.
 
-Please send comments on ARH2 to the AMDiS form:\\ \url{https://fusionforge.zih.tu-dresden.de/forum/?group_id=11}\\or post the comments on the Wiki:\\
+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] Definition and description of Finite Elements was restructured and extracted from the ARH2 file format and put into a new file format. A new container format for parallel files (pARH) was added.
+\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 ARH2 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 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.
 
@@ -49,20 +51,57 @@ The ARH2 file format consists of three sections:
 
 The concrete structure is given in the table below:
 \begin{longtable}{p{.2\textwidth}|p{.12\textwidth}|p{.1\textwidth}|p{.58\textwidth}}
-\textbf{Field} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline\endhead
-\hline\multicolumn{4}{r}{\textit{Continued on next page}}\\\hline\endfoot
-\endlastfoot
+\textbf{Field} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline\endfirsthead
+\textbf{Field} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline
+\multicolumn{4}{r}{\textit{(Continued from last page)}}\\\endhead
+\multicolumn{4}{r}{\textit{(Continued on next page)}}\\\endfoot
+\multicolumn{4}{r}{\textit{(End of header)}}\\\endlastfoot
 fd & 4 & string & Format descriptor (lower case) [\texttt{sarh}] \\
 maj & 1 & uchar & major version [3] \\
 min & 1 & uchar & minor version [0] \\\hline
-hs & 4 & uint & header size (until = line) \\
+hs & 4 & uint & header size \\
 dow & 4 & uint & dimension of world \\
 dim & 4 & uint & dimension of the mesh \\
-num\_fes & 4 & uint & number of Finite Element spaces \\
-num\_vec & 4 & uint & number of value vectors \\
-num\_el & 4 & uint & number of macro elements \\
-cps & 4 & int & compression flag: 0... no compression, 1... ZLib compression\footnote{Details of ZLib Version, Parameters etc.} \\\hline\hline
+\#fes & 4 & uint & number of Finite Element spaces \\
+\#vec & 4 & uint & number of value vectors \\
+\#el & 4 & uint & number of macro elements \\
+cps & 4 & int & compression flag: \texttt{0}: no compression, \texttt{1}: ZLib compression\footnote{Details of ZLib Version, Parameters etc.} \\
+\multicolumn{4}{l}{~}\\
+\multicolumn{4}{l}{\for $i=0,\ldots,$\#el-1} \\\hline
+\multicolumn{1}{|l|}{macro[i]$\rightarrow$index} & 4 & uint & global index of the macro element \\
+\multicolumn{1}{|l|}{macro[i]$\rightarrow$pos} & 4 & uint & position of the macro description in this file \\
+\multicolumn{1}{|l|}{macro[i]$\rightarrow$size} & 4 & uint & uncompressed size of the data block for the macro element \\\hline
+index\_end & 4 & uint & index to indicate the end of the macro list [-1] \\
+pos\_end & 4 & uint & size of the compressed file \\
+size\_end & 4 & uint & (size of the uncompressed file $|$ 0)\footnote{This value is not needed, thus an arbitrary value could be stored.} \\\newpage
+\multicolumn{4}{l}{\for $i=0,\ldots,$\#fes-1} \\\hline
+\multicolumn{1}{|l|}{fe[i]$\rightarrow$ID} & 16 & string & ``\texttt{costum}'', or name of file with description of Finite Element in AFED format \\
+\multicolumn{1}{|l|}{fe[i]$\rightarrow$DOFs/pos} & 16 & $4\times$uint & number of DOFs per position (vertex, edge, face, center) \\\hline
+\multicolumn{4}{l}{~}\\
+\multicolumn{4}{l}{\for $i=0,\ldots,$\#vec-1} \\\hline
+\multicolumn{1}{|l|}{vec[i]$\rightarrow$nl} & 4 & uint & length of name \\
+\multicolumn{1}{|l|}{vec[i]$\rightarrow$name} & nl & string & name of the value vector\\
+\multicolumn{1}{|l|}{vec[i]$\rightarrow$fe} & 4 & uint & index of the fe it belongs to\\
+\multicolumn{1}{|l|}{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{.2\textwidth}|p{.12\textwidth}|p{.1\textwidth}|p{.58\textwidth}}
+\textbf{Field} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline\endfirsthead
+\textbf{Field} & \textbf{Size (B)} & \textbf{Type} & \textbf{Description} \\\hline\hline
+\multicolumn{4}{r}{\textit{(Continued from last page)}}\\\endhead
+\multicolumn{4}{r}{\textit{(Continued on next page)}}\\\endfoot
+\multicolumn{4}{r}{\textit{(End of body)}}\\\endlastfoot
+\multicolumn{4}{l}{~}\\
+\multicolumn{4}{l}{\for Macro[i], $i=0,\ldots,$\#el-1} \\\hline
+\multicolumn{1}{|l|}{\#codes} & 4 & uint & number of structure codes \\
+\multicolumn{1}{|l|}{\#bits} & 4 & uint & total number of bits for structure codes \\
+\multicolumn{1}{|l|}{code-data} & $8\times$\#codes & uint & all structure codes \\
+\multicolumn{4}{|l}{~}\\
+\multicolumn{4}{|l}{\for $j=0,\ldots,$\#fes-1} \\\hline
+\multicolumn{1}{||l|}{fe[j]: \#el\_val} & 4 &  & number of values per vector in fespace \\
+\multicolumn{4}{||l}{~}\\
+\multicolumn{4}{||l}{\for $k=0,\ldots,$n-1} \\\hline
+\multicolumn{1}{|||l|}{fe[j]$\rightarrow$data[k]} & $X\times$\#el\_val  & & sequence of values, X: size of data-type (vec[*]$\rightarrow$type), n: number of value vector belonging to fe[j].  \\\hline
 \end{longtable}
 
 \end{document}
\ No newline at end of file