Document transformation systems.

movement_primitives/dmp/_cartesian_dmp.py

@@ -151,7 +151,7 @@ def dmp_step_quaternion_python(
 
 
 class CartesianDMP(DMPBase):
-    """Cartesian dynamical movement primitive.
+    r"""Cartesian dynamical movement primitive.
 
     The Cartesian DMP handles orientation and position separately. The
     orientation is represented by a quaternion. The quaternion DMP is
@@ -175,6 +175,27 @@ class CartesianDMP(DMPBase):
     While the dimension of the state space is 7, the dimension of the
     velocity, acceleration, and forcing term is 6.
 
+    Equation of transformation system for the orientation
+    (Ude et al. 2014, Eq. 16):
+
+    .. math::
+
+        \ddot{y} = (\alpha_y (\beta_y (g - y) - \tau \dot{y}) + f(z) + C_t) / \tau^2
+
+    Note that in this case :math:`y` is a quaternion in this case,
+    :math:`g - y` the quaternion difference (expressed as rotation vector),
+    :math:`\dot{y}` is the angular velocity, and :math:`\ddot{y}` the
+    angular acceleration.
+
+    With smooth scaling:
+
+    .. math::
+
+        \ddot{y} = (\alpha_y (\beta_y (g - y) - \tau \dot{y} - \beta_y (g - y_0) z) + f(z) + C_t) / \tau^2
+
+    The position is handled in the same way, just like in the original
+    :class:`DMP`.
+
     Parameters
     ----------
     execution_time : float, optional (default: 1)

movement_primitives/dmp/_dmp.py

@@ -340,7 +340,7 @@ def dmp_step_euler(
 
 
 class DMP(WeightParametersMixin, DMPBase):
-    """Dynamical movement primitive (DMP).
+    r"""Dynamical movement primitive (DMP).
 
     Implementation according to
 
@@ -358,6 +358,18 @@ class DMP(WeightParametersMixin, DMPBase):
     Kobe, Japan, 2009, pp. 763-768, doi: 10.1109/ROBOT.2009.5152385,
     https://h2t.iar.kit.edu/pdf/Pastor2009.pdf
 
+    Equation of transformation system (Ijspeert et al. 2013, Eq. 2.1):
+
+    .. math::
+
+        \ddot{y} = (\alpha_y (\beta_y (g - y) - \tau \dot{y}) + f(z) + C_t) / \tau^2
+
+    With smooth scaling:
+
+    .. math::
+
+        \ddot{y} = (\alpha_y (\beta_y (g - y) - \tau \dot{y} - \beta_y (g - y_0) z) + f(z) + C_t) / \tau^2
+
     Parameters
     ----------
     n_dims : int

movement_primitives/dmp/_dmp_with_final_velocity.py

@@ -6,7 +6,7 @@
 
 
 class DMPWithFinalVelocity(WeightParametersMixin, DMPBase):
-    """Dynamical movement primitive (DMP) with final velocity.
+    r"""Dynamical movement primitive (DMP) with final velocity.
 
     Implementation according to
 
@@ -15,6 +15,12 @@ class DMPWithFinalVelocity(WeightParametersMixin, DMPBase):
     (2013), International Journal of Robotics Research 32(3), pp. 263-279,
     https://www.ias.informatik.tu-darmstadt.de/uploads/Publications/Muelling_IJRR_2013.pdf
 
+    Equation of transformation system (Muelling et al. 2013, Eq. 6):
+
+    .. math::
+
+        \ddot{y} = (\alpha_y (\beta_y (g - y) + \tau\dot{g} - \tau \dot{y}) + f(z))/\tau^2
+
     Parameters
     ----------
     n_dims : int

movement_primitives/dmp/_dual_cartesian_dmp.py

@@ -194,6 +194,9 @@ class DualCartesianDMP(WeightParametersMixin, DMPBase):
     While the dimension of the state space is 14, the dimension of the
     velocity, acceleration, and forcing term is 12.
 
+    See :class:`CartesianDMP` for details about the equation of the
+    transformation system.
+
     Parameters
     ----------
     execution_time : float, optional (default: 1)