docs: Improve chapters on observables and constraints

Make notation more consistent in particle-based observables.
Move observable array shape from the constructor to the calculate()
method (the constructor returns an object). Fix incorrect shape in
the density profile observable. Distinguish vectors from scalars in
the expressions for the single-particle force constraints. Increase
runtime of the tutorial job in CI.

.gitlab-ci.yml

@@ -470,6 +470,7 @@ run_tutorials:
     paths:
     - build/doc/tutorials
     expire_in: 1 week
+  timeout: 2h
   tags:
     - espresso
     - cuda

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}` and :math:`\\vec{r}` are the particle dipole moment and position.
+
     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,20 @@ class LinearElectricPotential(Constraint):
     """
     Electric potential of the form
 
-    :math:`\\phi = -E \\cdot x + \\phi_0`,
+    :math:`\\phi = -\\vec{E} \\cdot \\vec{r} + \\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{r}` are the particle charge and position.
+    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 +473,15 @@ 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{r} + \\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{r}` are the particle charge and position.
     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.
 
     Arguments
     ----------
@@ -482,7 +492,7 @@ class ElectricPlaneWave(Constraint):
     omega : :obj:`float`
         Frequency of the wave
     phi : :obj:`float`, optional
-        Phase shift
+        Phase
 
     """
 
@@ -520,9 +530,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{r}) - \\vec{v} \\right)`
 
-    where :math:`v` is the velocity of the particle.
+    where :math:`\\vec{v}` and :math:`\\vec{r}` are the particle velocity and position,
+    and :math:`\\vec{u}(\\vec{r})` is a 3D flow field on a grid.
 
     Arguments
     ----------
@@ -549,9 +560,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 +592,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.