- doc/H5X_File_Format.txt

* added

.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

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 "<name>#<number>". 
+Whereby <name> is either defined by the optional file attribute
+__stepname__ or set to "Step" by default. <number> 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 <number> 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#<i>			# HDF5 group
+   |
+   +- Block			# HDF5 group
+      |
+      +- <field name>		# 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#<i>			# HDF5 group
+   |
+   +- Block			# HDF5 group
+      |
+      +- <field name>		# HDF5 group
+         |
+         +- 0			# HDF5 dataset, scalar value
+...
+
+
+2.3    Step properties [NEW]
+
+
+