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, in relation with several optional quaternion aware integrators.
ESPResSo optionally integration quaternion degrees of freedom with the “ROTATION” feature.
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 https://lammps.sandia.gov/doc/read_data.html. 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. 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.