>From a079d335c3cb2a15bb05ca36ba5db291cebfb098 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20H=C3=B6fling?=
Date: Thu, 1 Aug 2013 10:38:17 +0200
Subject: [PATCH] box: drop geometry attribute, change "nonperiodic" to "none"
The geometry attribute is not needed since it can be inferred from the
shape of "edges".
Extend the spec for a simple support of cubic boxes with a scalar edge
value.
Shorten the specification of time-dependent vs. -independent and drop
the subsection headlines. The issue has been specified in the general
part already, and the two examples should clarify this again.
http://article.gmane.org/gmane.science.simulation.h5md.user/218
---
draft.rst | 56 +++++++++++++++++++++-----------------------------------
1 file changed, 21 insertions(+), 35 deletions(-)
diff --git a/draft.rst b/draft.rst
index 46a068e..5bb7956 100644
--- a/draft.rst
+++ b/draft.rst
@@ -310,20 +310,23 @@ The specification of the simulation box is stored in the group ``box``, which
must be contained within each of the subgroups of the ``particles`` group.
The group ``box`` must further be stored in (or hard-linked to) the
``observables`` group, if present.
+A specific requirement for ``box`` groups inside ``particles`` is that the
+``step`` and ``time`` datasets exactly match those of the corresponding
+``position`` groups, which may be accomplished by hard-linking the datasets.
+
Storing the box information at several places reflects the fact that all root
groups are optional (except for ``h5md``), and further that different subgroups
may be sampled at different time grids. This way, the box information remains
associated to a group of particles or the collection of observables.
-The spatial dimension, the type of geometry, and the boundary conditions of the
-box are stored as attributes to the ``box`` group, e.g., ::
+The spatial dimension and the boundary conditions of the box are stored as
+attributes to the ``box`` group, e.g., ::
particles
\--
\-- box
+-- dimension
+-- boundary [D]
- +-- geometry
\-- ...
``dimension``
@@ -333,52 +336,36 @@ box are stored as attributes to the ``box`` group, e.g., ::
``boundary``
An attribute that is a string-valued array of size ``D`` that
specifies the boundary condition of the box along each dimension. The
- elements of ``boundary`` are either ``periodic`` or ``nonperiodic``.
+ elements of ``boundary`` are either ``periodic`` or ``none``.
-``geometry``
- An attribute that is string-valued and is either ``cuboid`` or
- ``triclinic``.
-
-For a cuboid box, the following additional data is stored:
+Information on the geometry of the box edges and on the coordinate offset is
+stored as attributes or as H5MD data groups, depending on whether the box is
+fixed in time or not.
``edges``
- A ``D``-dimensional vector specifying the space diagonal of the
- box. The box is not restricted to having the same edge lengths in the
- different dimensions.
+ A scalar, a ``D``-dimensional vector, or a ``D`` Ã ``D`` matrix, depending
+ on the geometry of the box. The box is neither restricted to having the
+ same edge lengths in all directions nor to having orthogonal edges.
-``offset``
- A ``D``-dimensional vector specifying the lower coordinate
- for all directions.
+ If ``edges`` is a scalar, the box is a (hyper-)cube with the given edge
+ length.
-For a triclinic box, the following additional data is stored:
+ If ``edges`` is a vector, it specifies the space diagonal of a
+ cuboid-shaped box.
-``edges``
- A ``D`` Ã ``D`` matrix with the rows specifying the edge vectors
- of the box.
+ If ``edges`` is a matrix, the box is of general triclinic shape with the
+ edge vectors given by the rows of the matrix.
``offset``
A ``D``-dimensional vector specifying the lower coordinate
for all directions.
-Time dependence
-^^^^^^^^^^^^^^^
-
-If the simulation box is fixed in time, ``edges`` and ``offset`` are stored as
-attributes of the ``box`` group for all box kinds. Else, ``edges`` and
-``offset`` are stored as datasets following the ``value``, ``step``, ``time``
-organization.
-
-A specific requirement for ``box`` groups inside ``particles`` is that the
-``step`` and ``time`` datasets exactly match those of the corresponding
-``position`` groups, which may be accomplished by hard-linking the datasets.
-
For instance, a cuboid box that changes in time would appear as::
particles
\--
\-- box
+-- dimension
- +-- geometry
+-- boundary
\-- edges
\-- value [variable][D]
@@ -389,19 +376,18 @@ For instance, a cuboid box that changes in time would appear as::
\-- step [variable]
\-- time [variable]
-where ``dimension`` is equal to ``D`` and ``geometry`` is set to ``cuboid``.
+where ``dimension`` is equal to ``D``.
A fixed-in-time triclinic box would appear as::
particles
\--
\-- box
+-- dimension
- +-- geometry
+-- boundary
+-- edges [D][D]
+-- offset [D]
-where ``dimension`` is equal to ``D`` and ``geometry`` is set to ``triclinic``.
+where ``dimension`` is equal to ``D``.
Observables group
--
1.7.11.4