diff --git a/.gitattributes b/.gitattributes index d68fae8..cf6ca26 100644 --- a/.gitattributes +++ b/.gitattributes @@ -28,6 +28,7 @@ doc/H5PartVisIt/cloud_visit_2D.png -text doc/H5PartVisIt/cloud_visit_2D.s.png -text doc/H5PartVisIt/visit_query1.png -text doc/H5PartVisIt/visit_query1.s.png -text +doc/H5X_File_Format.txt -text doc/H5tools/H5tools.html -text doc/H5tools/H5tools_files/snapshot1.jpg -text doc/InternalLayout.html -text diff --git a/doc/H5X_File_Format.txt b/doc/H5X_File_Format.txt new file mode 100644 index 0000000..f42e4f1 --- /dev/null +++ b/doc/H5X_File_Format.txt @@ -0,0 +1,151 @@ +Proposal for a more general file format used by H5Part/H5Block + + Authors: Achim Gsell + Status: Draft + +1. Introduction + +H5X is the file format used by H5Part and H5Block. H5X is designed on +top of HDF5: A H5X file is a very special HDF5 file. + + +--------------------+ + | Application | + +--------------------+ + | H5Part/H5Block API | + +--------------------+ + | H5X API | + +--------------------+ + | HDF5 API | + +--------------------+ + | Filesystem of OS | + +--------------------+ + + +2. H5X file format specification + +2.1 The root group + +2.1.1 File attributes + +Attributes of the HDF5 root group are called "file attributes". There +are no restrictions on file attribute names. Supported values are +scalars and arrays of 64bit integer and 64bit floating point number as +well as string values, but not arrays of strings. + +2.1.1.1 Predefined file attributes + +__stepname__ (optional) + See below. + +__stepnumwidth__ (optional) + See below. + +2.1.2 Members of the root group + +Members of the root group are special formated HDF5 groups called +"step groups". The name of a step group is "#". +Whereby is either defined by the optional file attribute +__stepname__ or set to "Step" by default. is an +unsigned integer less than 2^63. + +/ ++- Step#0 ++- Step#1 +... ++- Step#n ++- StepProperties [NEW] ++- Mesh [NEW] + +The optional file attribute __stepnumwidth__ defines the minimum width +of in the name of the step group. The number is padded with +'0'. The minimum width defaults to zero, so that no paddings occurs. +Example: With __stepnumwidth__ := 5 the name of the step group with +number 42 is "Step#00042", with __stepnumwidth__ := 0 the name is +"Step#42". + +Step groups may be unsorted in the HDF5 file und may not be number +consecutively. + + +2.2 Format of a step group + +2.2.1 Step attributes + +Step attributes are HDF5 attributes asigned to a step group. There +are no restrictions on file attribute names. Supported values are +scalars and arrays of 64bit integer and 64bit floating point number as +well as string values, but not arrays of strings. + +2.2.2 Predefined step attributes + +No predefined step attributes exists. + + +2.2.3 Members of a step group + +Members of a step group are HDF5 datasets and optional one HDF5 group +with the name "Block". HDF5 datasets in a step group are called "step +datasets". The optional block group is called "block data". + +Mesh?! + +2.2.4 Step datasets + +Step datasets are arrays of rank 1. The dataset size must be the same +for all datasets inside a step. The size of the dataset may vary +from step to step. Array values are 64bit integer or 64bit floating +point numbers. No limitations (other than given by HDF5) are given on +step dataset names. + + +2.2.5 Block Data + +The block data group is a container for an arbitrary number of field +data. A field is a data structure to store arrays of rank m with +n-dimensional vector values. Fields are represented within HDF5 +groups. The HDF5 group name is the unique identifier for a field in +the current step. + +2.2.5.1 m-rank fields with n-dimensional-vector values + +Values are stored per dimension in separate datasets. Thus we have n +datasets for a field with n-dimensional vector values. Each dataset +corresponse to one dimension. The datasets are numbered from '0' to +'n-1'. Arrays are stored in column major order (Fortran indexing +scheme). + +/ # HDF5 root group +... ++- Step# # HDF5 group + | + +- Block # HDF5 group + | + +- # HDF5 group + | + +- 0 # HDF5 dataset, first dim of vector + +- 1 # HDF5 dataset, second dim of vector + ... + +- n-1 # HDF5 dataset, last dim of vector +... + +2.2.5.2 m-rank fields with scalar values + +Fields with scalar values are stored as special case of fields with +n-dimensional vector values with n := 1. + +/ # HDF5 root group +... ++- Step# # HDF5 group + | + +- Block # HDF5 group + | + +- # HDF5 group + | + +- 0 # HDF5 dataset, scalar value +... + + +2.3 Step properties [NEW] + + +