>From 5a0c644daf29f9ee7a17fd6b83ab97b001169242 Mon Sep 17 00:00:00 2001
From: Peter Colberg <address@hidden>
Date: Thu, 1 Aug 2013 22:06:12 -0400
Subject: [PATCH] Add H5MD metadata group for physical quantities and their
 units.

The example illustrates the definition of SI units for LAMMPS.

http://lammps.sandia.gov/doc/units.html
---
 draft.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 68 insertions(+), 9 deletions(-)

diff --git a/draft.rst b/draft.rst
index a988de9..2a8700f 100644
--- a/draft.rst
+++ b/draft.rst
@@ -43,17 +43,20 @@ of the file and of each of its objects.
 Notation
 --------
 
-HDF5 files are organized into groups and datasets, which form a tree structure.
-Attributes can be attached to each group or dataset. The following notation is
-used to depict the tree or its subtrees:
+HDF5 files are organized into groups, datasets and data types, which form a
+tree structure. Attributes can be attached to each group, dataset or data type.
+The following notation is used to depict the tree or its subtrees:
 
 ``\-- item``
-    An element of a group, that is either a dataset or a group. If it is a
-    group itself, the elements within the group are indented by five spaces
-    with respect to the group name.
+    An element of a group, that is either a group, a dataset or a data type.
+    If it is a group itself, the elements within the group are indented by five
+    spaces with respect to the group name.
 
 ``+-- attribute``
-    An attribute, that relates either to a group or a dataset.
+    An attribute, that relates either to a group, a dataset or a data type.
+
+``+-- attribute = value``
+    An attribute that contains the string ``value``.
 
 ``\-- data [dim1][dim2]``
     A dataset with array dimensions ``dim1`` by ``dim2``.
@@ -196,8 +199,9 @@ attributes. The contents of the group is::
      |    +-- name
      |    +-- (email)
      \-- creator
-          +-- name
-          +-- version
+     |    +-- name
+     |    +-- version
+     \-- (quantities)
 
 ``version``
     An attribute that states the version of the H5MD specification that
@@ -227,6 +231,61 @@ attributes. The contents of the group is::
         An attribute that yields the version of the program, as a string
         containing a proper identification for the given program.
 
+``quantities``
+    An optional group that contains metadata on the physical quantities used
+    in the file.
+
+Physical quantities and units
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Information on physical quantities used in the file, e.g., their unit, is
+stored within the optional ``quantities`` group that is contained in the
+``h5md`` group.  The metadata of a physical quantity is stored as a committed
+(or named) data type in the ``quantities`` group, or in a subgroup of the
+``quantities`` group, etc.  Data stored in the file as a dataset or attribute
+may refer to such metadata by using the respective committed data type upon
+creation of the dataset or attribute. A data type may hold an optional
+attribute ``unit`` that describes the physical unit of the respective quantity
+as a string.
+
+An example for the contents of the ``quantities`` group is the following::
+
+    h5md
+     \-- quantities
+          \-- <charge>
+          |    +-- unit = coulomb
+          \-- <density>
+          |    +-- unit = kilogram per cubic metre
+          \-- <dipole>
+          |    +-- unit = coulomb metre
+          \-- <distance>
+          |    +-- unit = metre
+          \-- <dynamic_viscosity>
+          |    +-- unit = pascal second
+          \-- <electric_field>
+          |    +-- unit = volt per metre
+          \-- <energy>
+          |    +-- unit = joule
+          \-- <force>
+          |    +-- unit = newton
+          \-- <mass>
+          |    +-- unit = kilogram
+          \-- <pressure>
+          |    +-- unit = pascal
+          \-- <temperature>
+          |    +-- unit = kelvin
+          \-- <time>
+          |    +-- unit = second
+          \-- <torque>
+          |    +-- unit = newton metre
+          \-- <velocity>
+               +-- unit = metre per second
+
+where the elements of the ``quantities`` group are real-valued data types
+that each hold an attribute ``unit`` containing a unit conforming to the
+`International System of Units`_.
+
+.. _International System of Units: http://www.bipm.org/en/si/si_brochure/
 
 Particles group
 ---------------
-- 
1.8.4.rc0