From c3fab57acc222c881018884b7516aeef88d8d66d Mon Sep 17 00:00:00 2001
From: Alexander Fabisch <alexander.fabisch@dfki.de>
Date: Tue, 28 Nov 2023 14:35:47 +0100
Subject: [PATCH] Introduction to DMPs

---
 doc/source/api.rst                  |  4 ++--
 movement_primitives/dmp/__init__.py | 15 ++++++++++++++-
 movement_primitives/dmp/_base.py    |  7 ++++++-
 3 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/doc/source/api.rst b/doc/source/api.rst
index 93288ca..2bf4443 100644
--- a/doc/source/api.rst
+++ b/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
diff --git a/movement_primitives/dmp/__init__.py b/movement_primitives/dmp/__init__.py
index 6b412fb..12c58bd 100644
--- a/movement_primitives/dmp/__init__.py
+++ b/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
diff --git a/movement_primitives/dmp/_base.py b/movement_primitives/dmp/_base.py
index 668d2f0..da883af 100644
--- a/movement_primitives/dmp/_base.py
+++ b/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.