file_format.tex 12.3 KB
 Praetorius, Simon committed Aug 15, 2016 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}  SiqiLing committed Aug 18, 2016 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:  Praetorius, Simon committed Aug 15, 2016 132 \begin{enumerate}  SiqiLing committed Aug 18, 2016 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.  Praetorius, Simon committed Aug 15, 2016 137 138 \end{enumerate}  SiqiLing committed Aug 18, 2016 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}  Praetorius, Simon committed Aug 15, 2016 194 \end{document}