file_format.tex 12.3 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
\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}
131
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 sections:
132
\begin{enumerate}
133
134
135
136
\item The first section contains a file descriptor and version information, as in the sARH file. But the format is a little bit different.
\item The second part specifies the information about the sARH files this pARH file includes.
\item The third part is related to the macro file or any other file which contains the information about macro meshes.
\item The Last section contains a partition table for all the macro elements.
137
138
\end{enumerate}

139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
The concrete structure is given in the table below:

\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} & 16 & string & Format descriptor (lower case) [\texttt{parh\_[0-9].[0-9]}] \footnote{First [0-9] is major version, second is minor version. The rest is padding of blanks.} \\\hline
\first{ln\_basedir} & 4 & uint & length of the base directory \\
\first{basedir} & ln\_basedir & string & sARH base directory relative to this pARH file \\
\first{n\_files} & 4 & uint & number of sARH files \\\hline
& & & & \\
\first{ln\_macrofile} & 4 & uint & length of the macro file name \footnote{If len\_macrofile is zero, then no macro mesh information is specified.}\\
\first{macrofile} & ln\_macrofile & uint & macro file name \newline [\texttt{(this|macro\_fn)($\epsilon$|:pos)$(\epsilon\mid$;(this|periodic\_fn)($\epsilon$|:pos)$)$}] \footnote{The first part is the macro file name (does not necessary to be the macro file, it can be any file which contains the macro mesh information). Either we give a explicit file name or we use ``this" which means the current pARH file. An optional argument ``pos" is followed, which means the offset of the location of macro mesh data in the file. It is separated by ``:". The third part is an optional periodic data information, which has the same format as macro file and it is separated by ``;".}\\\hline
& & & & \\
\first{\#macro} & 4 & uint & number of macro elements \\
\first{\for $i=0,\ldots,$\#macro-1} & & &\\
& & & & \\
\ldelim[{1}{1mm} & macro[i]$\rightarrow$rank & 4 & uint & rank of the macro element \\
& & & & \\\hline
\end{longtable}

\section{The tARH file format}
For instationary problems, there is a need to store the animation frames like the ParaView Data File Format (PVD). For ARH file, we designed a similar container format called tARH. The file consists of three sections:
\begin{enumerate}
\item The first section contains a file descriptor and version information, exactly as in the pARH file.
\item The second part specifies the information about the pARH files this tARH file includes.
\item The third part provides a table of timestep values.
\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} & 16 & string & Format descriptor (lower case) [\texttt{tarh\_[0-9].[0-9]}]  \\\hline
\first{ln\_basedir} & 4 & uint & length of the base directory \\
\first{basedir} & ln\_basedir & string & pARH base directory relative to this tARH file \\
\first{length} & 4 & uint & total length of appended time index \\
\first{decimals} & 4 & uint & number of decimals in time index \\
\hline
& & & & \\
\first{\for $i=0,\ldots,EOF$} & & &\\
& & & & \\
\ldelim[{1}{1mm} & timestep[i] & 8 & double & timestep values until the end of file\\
& & & & \\\hline
\end{longtable}

194
\end{document}