Improve user guide chapters on observables and constraints (espressom…

…d#4898)

Fixes espressomd#4897

Description of changes:
- fix issues in the description of observable return values and array shapes
- fix vector notation in the expressions of single-particle force constraints
- make notation more consistent across particle-based observables

src/python/espressomd/constraints.py

@@ -183,8 +183,19 @@ def total_normal_force(self):
 
 @script_interface_register
 class HomogeneousMagneticField(Constraint):
-
     """
+    Homogeneous magnetic field :math:`\\vec{H}`.
+    The resulting force :math:`\\vec{F}`, torque :math:`\\vec{\\tau}`
+    and energy `U` on the particles are then
+
+    :math:`\\vec{F} = \\vec{0}`
+
+    :math:`\\vec{\\tau} = \\vec{\\mu} \\times \\vec{H}`
+
+    :math:`U = -\\vec{\\mu} \\cdot \\vec{H}`
+
+    where :math:`\\vec{\\mu}` is the particle dipole moment.
+
     Attributes
     ----------
     H : (3,) array_like of :obj:`float`
@@ -393,12 +404,12 @@ class Gravity(Constraint):
     """
     Gravity force
 
-    :math:`F = m \\cdot g`
+    :math:`\\vec{F} = m \\cdot \\vec{g}`
 
     Arguments
     ----------
     g : (3,) array_like of :obj:`float`
-        The gravitational acceleration.
+        The gravitational constant.
 
     """
 
@@ -420,21 +431,21 @@ class LinearElectricPotential(Constraint):
     """
     Electric potential of the form
 
-    :math:`\\phi = -E \\cdot x + \\phi_0`,
+    :math:`\\phi = -\\vec{E} \\cdot \\vec{x} + \\phi_0`,
 
-    resulting in the electric field E
-    everywhere. (E.g. in a plate capacitor).
+    resulting in the electric field :math:`\\vec{E}` everywhere.
     The resulting force on the particles are then
 
-    :math:`F = q \\cdot E`
+    :math:`\\vec{F} = q \\cdot \\vec{E}`
 
-    where :math:`q` is the charge of the particle.
+    where :math:`q` and :math:`\\vec{x}` are the particle charge and position
+    in folded coordinates.
+    This can be used to model a plate capacitor.
 
     Arguments
     ----------
     E : array_like of :obj:`float`
         The electric field.
-
     phi0 : :obj:`float`
         The potential at the origin
 
@@ -463,15 +474,18 @@ class ElectricPlaneWave(Constraint):
     """
     Electric field of the form
 
-    :math:`E = E0 \\cdot \\sin(k \\cdot x + \\omega \\cdot t + \\phi)`
+    :math:`\\vec{E} = \\vec{E_0} \\cdot \\sin(\\vec{k} \\cdot \\vec{x} + \\omega \\cdot t + \\phi)`
 
     The resulting force on the particles are then
 
-    :math:`F = q \\cdot E`
+    :math:`\\vec{F} = q \\cdot \\vec{E}`
 
-    where :math:`q` is the charge of the particle.
+    where :math:`q` and :math:`\\vec{x}` are the particle charge and position
+    in folded coordinates.
     This can be used to generate a homogeneous AC
-    field by setting k to zero.
+    field by setting :math:`\\vec{k}` to the null vector.
+    For periodic systems, :math:`\\vec{k}` must be an integer multiple
+    of :math:`2\\pi \\vec{L}^{-1}` with :math:`\\vec{L}` the box length.
 
     Arguments
     ----------
@@ -482,7 +496,7 @@ class ElectricPlaneWave(Constraint):
     omega : :obj:`float`
         Frequency of the wave
     phi : :obj:`float`, optional
-        Phase shift
+        Phase
 
     """
 
@@ -520,9 +534,10 @@ class FlowField(_Interpolated):
     Viscous coupling to a flow field that is
     interpolated from tabulated data like
 
-    :math:`F = -\\gamma \\cdot \\left( u(r) - v \\right)`
+    :math:`\\vec{F} = -\\gamma \\cdot \\left( \\vec{u}(\\vec{x}) - \\vec{v} \\right)`
 
-    where :math:`v` is the velocity of the particle.
+    where :math:`\\vec{v}` and :math:`\\vec{x}` are the particle velocity and position
+    in folded coordinates, and :math:`\\vec{u}(\\vec{x})` is a 3D flow field on a grid.
 
     Arguments
     ----------
@@ -549,9 +564,10 @@ class HomogeneousFlowField(Constraint):
     Viscous coupling to a flow field that is
     constant in space with the force
 
-    :math:`F = -\\gamma \\cdot (u - v)`
+    :math:`\\vec{F} = -\\gamma \\cdot (\\vec{u} - \\vec{v})`
 
-    where :math:`v` is the velocity of the particle.
+    where :math:`\\vec{v}` is the velocity of the particle
+    and :math:`\\vec{u}` is the constant flow field.
 
     Attributes
     ----------
@@ -580,11 +596,11 @@ class ElectricPotential(_Interpolated):
 
     """
     Electric potential interpolated from
-    provided data. The electric field E is
+    provided data. The electric field :math:`\\vec{E}` is
     calculated numerically from the potential,
     and the resulting force on the particles are
 
-    :math:`F = q \\cdot E`
+    :math:`\\vec{F} = q \\cdot \\vec{E}`
 
     where :math:`q` is the charge of the particle.