From 3a79e65d76fe98bddabb4509497a804e67f47119 Mon Sep 17 00:00:00 2001
From: "kodiakhq[bot]" <49736102+kodiakhq[bot]@users.noreply.github.com>
Date: Thu, 14 Dec 2023 17:42:09 +0000
Subject: [PATCH] Remove kinetic energy contribution from virtual sites (#4839)

Fixes #4838

Description of changes:
- fix virtual sites regression introduced in ESPResSo 4.2.0
- update description of `MASS` and `ROTATIONAL_INERTIA` features
---
 doc/sphinx/installation.rst             |  8 ++++----
 src/core/energy_inline.hpp              |  2 +-
 src/core/unit_tests/energy_test.cpp     | 19 ++++++++++++++++++-
 src/python/espressomd/particle_data.pyx |  2 +-
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/doc/sphinx/installation.rst b/doc/sphinx/installation.rst
index 554d48873d1..6be874247c7 100644
--- a/doc/sphinx/installation.rst
+++ b/doc/sphinx/installation.rst
@@ -404,15 +404,15 @@ General features
 -  ``THERMOSTAT_PER_PARTICLE`` Allows setting a per-particle friction
    coefficient for the Langevin and Brownian thermostats.
 
--  ``ROTATIONAL_INERTIA``
+-  ``ROTATIONAL_INERTIA`` Allows particles to have individual rotational inertia matrix eigenvalues.
+   When not built in, all eigenvalues are unity in simulation units.
 
 -  ``EXTERNAL_FORCES`` Allows to define an arbitrary constant force for each particle
    individually. Also allows to fix individual coordinates of particles,
    keep them at a fixed position or within a plane.
 
--  ``MASS`` Allows particles to have individual masses. Note that some analysis
-   procedures have not yet been adapted to take the masses into account
-   correctly.
+-  ``MASS`` Allows particles to have individual masses.
+   When not built in, all masses are unity in simulation units.
 
    .. seealso:: :attr:`espressomd.particle_data.ParticleHandle.mass`
 
diff --git a/src/core/energy_inline.hpp b/src/core/energy_inline.hpp
index 79f94e20dd0..3215ddbc641 100644
--- a/src/core/energy_inline.hpp
+++ b/src/core/energy_inline.hpp
@@ -300,7 +300,7 @@ inline double translational_kinetic_energy(Particle const &p) {
  */
 inline double rotational_kinetic_energy(Particle const &p) {
 #ifdef ROTATION
-  return p.can_rotate()
+  return (p.can_rotate() and not p.is_virtual())
              ? 0.5 * (hadamard_product(p.omega(), p.omega()) * p.rinertia())
              : 0.0;
 #else
diff --git a/src/core/unit_tests/energy_test.cpp b/src/core/unit_tests/energy_test.cpp
index f04aa0ace31..cd9e9dbf455 100644
--- a/src/core/unit_tests/energy_test.cpp
+++ b/src/core/unit_tests/energy_test.cpp
@@ -17,7 +17,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#define BOOST_TEST_MODULE tests
+#define BOOST_TEST_MODULE energy calculation
 #define BOOST_TEST_DYN_LINK
 #include <boost/test/unit_test.hpp>
 
@@ -69,6 +69,23 @@ BOOST_AUTO_TEST_CASE(rotational_kinetic_energy_) {
         0.5 * (hadamard_product(p.omega(), p.omega()) * p.rinertia());
     BOOST_CHECK_EQUAL(rotational_kinetic_energy(p), expected);
   }
+
+  // virtual particle
+  {
+#ifdef VIRTUAL_SITES
+
+    Particle p;
+#ifdef ROTATIONAL_INERTIA
+    p.rinertia() = {1., 2., 3.};
+#endif
+    p.set_virtual(true);
+    p.omega() = {3., 4., 5.};
+    p.set_can_rotate_all_axes();
+
+    auto const expected = 0.;
+    BOOST_CHECK_EQUAL(rotational_kinetic_energy(p), expected);
+#endif
+  }
 #endif
 }
 
diff --git a/src/python/espressomd/particle_data.pyx b/src/python/espressomd/particle_data.pyx
index 862ce23c80f..e4bad81666b 100644
--- a/src/python/espressomd/particle_data.pyx
+++ b/src/python/espressomd/particle_data.pyx
@@ -541,7 +541,7 @@ cdef class ParticleHandle:
 
             rinertia : (3,) array_like of :obj:`float`
 
-            Sets the diagonal elements of this particles rotational inertia
+            Sets the diagonal elements of this particle's rotational inertia
             tensor. These correspond with the inertial moments along the
             coordinate axes in the particle's co-rotating coordinate system.
             When the particle's quaternions are set to ``[1, 0, 0, 0,]``, the