Quaternion formalism comments and docs (#3392)

Fixes #2964 Description of changes: - code minor comment - docs minor change - bib ref to both PR Checklist ------------ - [ ] Tests? - [ ] Interface - [ ] Core - [ ] Docs?
espressomd · Jan 3, 2020 · 6e066ea · 6e066ea
2 parents d40b456 + 427a5cd
commit 6e066ea
Show file tree

Hide file tree

Showing 4 changed files with 26 additions and 3 deletions.
diff --git a/doc/doxygen/bibliography.bib b/doc/doxygen/bibliography.bib
@@ -394,6 +394,17 @@ @Article{sonnenschein85a
 doi = {10.1016/0021-9991(85)90151-2},
 }
 
+@book{allen2017,
+  title={Computer simulation of liquids},
+  author={Allen, Michael P and Tildesley, Dominic J},
+  year={2017},
+  publisher={Oxford university press},
+  url={https://global.oup.com/academic/product/computer-simulation-of-liquids-9780198803201},
+  doi={10.1093/oso/9780198803195.001.0001},
+  isbn={9780198803195},
+  edition={2nd},
+}
+
 @Article{swope92a,
 author = {Swope, William C. and Ferguson, David M.},
 title = {{Alternative expressions for energies and forces due to angle bending and torsional energy}},

diff --git a/doc/sphinx/running.rst b/doc/sphinx/running.rst
@@ -184,7 +184,7 @@ Rotational degrees of freedom and particle anisotropy
 When the feature ``ROTATION`` is compiled in, particles not only have a position, but also an orientation that changes with an angular velocity. A torque on a particle leads to a change in angular velocity depending on the particles rotational inertia. The property :attr:`espressomd.particle_data.ParticleHandle.rinertia` has to be specified as the three eigenvalues of the particles rotational inertia tensor.
 
 The rotational degrees of freedom are also integrated using a velocity Verlet scheme.
-The implementation is based on a quaternion representation of the particle orientation and described in :cite:`omelyan98`.
+The implementation is based on a quaternion representation of the particle orientation and described in :cite:`omelyan98` with quaternion components indexing made according to the formalism :math:`q = a + b\mathbf{i} + c\mathbf{j} + d\mathbf{k}` :cite:`allen2017`.
 
 When the Langevin thermostat is enabled, the rotational degrees of freedom are also thermalized.
 

diff --git a/doc/sphinx/zrefs.bib b/doc/sphinx/zrefs.bib
@@ -688,6 +688,17 @@ @article{omelyan98
 URL = {https://aip.scitation.org/doi/abs/10.1063/1.168642}
 }
 
+@book{allen2017,
+  title={Computer simulation of liquids},
+  author={Allen, Michael P and Tildesley, Dominic J},
+  year={2017},
+  publisher={Oxford university press},
+  url={https://global.oup.com/academic/product/computer-simulation-of-liquids-9780198803201},
+  doi={10.1093/oso/9780198803195.001.0001},
+  isbn={9780198803195},
+  edition={2nd},
+}
+
 @ARTICLE{pasichnyk04a,
   author = {Igor Pasichnyk and Burkhard D{\"u}nweg},
   title = {Coulomb interactions via local dynamics: {A} molecular-dynamics algorithm},

diff --git a/src/core/rotation.cpp b/src/core/rotation.cpp
@@ -23,8 +23,9 @@
  *
  *  A velocity Verlet <a
  * HREF="http://ciks.cbt.nist.gov/~garbocz/dpd1/dpd.html">algorithm</a>
- *  using quaternions is implemented to tackle rotational motion. A random
- * torque and a friction
+ *  using quaternions is implemented to tackle rotational motion.
+ *  See @cite allen2017 for the quaternion components indexing used here.
+ *  A random torque and a friction
  *  term are added to provide the constant NVT conditions. Due to this feature
  * all particles are
  *  treated as 3D objects with 3 translational and 3 rotational degrees of