H5MD - proposal 104: Storage of orientation and quaternions
-----------------------------------------------------------
**status:** draft
### Objective
This proposal aims at defining the storage of the orientation associated with each particle,
either as a real-space vector or as a quaternion.
### Motivations
The motivations below cover the use of quaternions, which requires a non-ambiguous
definition of the orientation.
Quaternions are useful for coarse-grained simulations in which the quaternion represents the
orientation of a particle.
A quaternion encodes the full rotation in 3D for a rigid body, represents a robust
alternative to Euler angles, and is used as the actual simulation variable in several MD
codes.
The interpretation of the value depends however on the situation.
Current simulation software that could benefit directly from quaternions:
- LAMMPS uses quaternions for the ["ellipsoid" atom
style](https://lammps.sandia.gov/doc/atom_style.html), in relation with several optional
[quaternion aware integrators](https://lammps.sandia.gov/doc/Howto_spherical.html).
- ESPResSo optionally integration quaternion degrees of freedom with the ["ROTATION"
feature](http://espressomd.org/html/doc/running.html#rotational-degrees-of-freedom-and-particle-anisotropy).
- RMPCDMD implements a quaternion integrator to model rigid bead assemblies
http://lab.pdebuyl.be/rmpcdmd/algorithms/quaternions.html
### Comparison to other file formats
There is no generic file format such as PDB that encodes quaternions. LAMMPS and HOOMD-blue
can store quaternions in their custom file formats:
#### LAMMPS
LAMMPS: see the command "read_data" for a description of the file format
. Atoms of stype "ellipsoid" store the four
components of the quaternions. The storage order is user-defined by using a "dump custom"
entry in the simulation script.
#### HOOMD-blue
HOOMD-blue uses the custom file format [GSD](https://gsd.readthedocs.io/en/stable/). Every
particle in a GSD file may contain a property "orientation" that is a unit quaternion. The
storage order is scalar first, the vector.
### Data in particles group
`orientation`
: An element that contains the orientation associated to each particle as a vector of
`Float` type. A length-4 vector implies a quaternion storage (see *add
cross-reference*). Else, the vector is the normalized orientation with the same
dimensionality as the position element.
There will be an extra note in the specification for the storage of quaternions:
A quaternion is stored as a vector of length 4. The storage order is "scalar vector": $(s,
x, y, z)$ or $(w, i, j, k)$, depending on the notation. Quaternions are normalized.
A quaternion defines the orientation of a particle as follows: Any point on the body
represented by the particle, and located at $p_0$ at an arbitrary reference in time, is
located at the time corresponding to quaternion $q_1$ at $p_1 = q_1\ p_0\ q_1^\ast$ where
$q_1^\ast$ is the conjugated quaternion to $q_1$ and the multiplications in the formula are
quaternion products. The position of the point so defined is always relative to the position
of the particle.