Introduction to DMPs

doc/source/api.rst

@@ -21,12 +21,12 @@ You can also search for specific modules, classes, or functions in the
    :toctree: _apidoc/
    :template: class.rst
 
-   ~movement_primitives.dmp.DMPBase
-   ~movement_primitives.dmp.WeightParametersMixin
    ~movement_primitives.dmp.DMP
    ~movement_primitives.dmp.DMPWithFinalVelocity
    ~movement_primitives.dmp.CartesianDMP
    ~movement_primitives.dmp.DualCartesianDMP
+   ~movement_primitives.dmp.DMPBase
+   ~movement_primitives.dmp.WeightParametersMixin
    ~movement_primitives.dmp.CouplingTermPos1DToPos1D
    ~movement_primitives.dmp.CouplingTermObstacleAvoidance2D
    ~movement_primitives.dmp.CouplingTermObstacleAvoidance3D

movement_primitives/dmp/__init__.py

@@ -1,10 +1,23 @@
-"""Dynamical Movement Primitive (DMP)
+r"""Dynamical Movement Primitive (DMP)
 ==================================
 
 This module provides implementations of various DMP types. DMPs consist of
 a goal-directed movement generated by the transformation system and a forcing
 term that defines the shape of the trajectory. They are time-dependent and
 usually converge to the goal after a constant execution time.
+
+Every implementation is slightly different, but we use a similar notation for
+all of them:
+
+* :math:`y,\dot{y},\ddot{y}` - position, velocity, and acceleration; these
+  might be translation components only, orientation, or both
+* :math:`y_0` - start position
+* :math:`g` - goal of the movement (attractor of the DMP)
+* :math:`\tau` - execution time
+* :math:`z` - phase variable, starts at 1 and converges to 0
+* :math:`f(z)` - forcing term, learned component that defines the shape of the
+  movement
+* :math:`C_t` - coupling term that is added to the acceleration of the DMP
 """
 from ._base import DMPBase, WeightParametersMixin
 from ._dmp import DMP, dmp_transformation_system

movement_primitives/dmp/_base.py

@@ -27,7 +27,12 @@ def reset(self):
 
 
 class WeightParametersMixin:
-    """Mixin class providing common access methods to forcing term weights."""
+    """Mixin class providing common access methods to forcing term weights.
+
+    This can be used, for instance, for black-box optimization of the weights
+    with respect to some cost / objective function in a reinforcement learning
+    setting.
+    """
     def get_weights(self):
         """Get weight vector of DMP.