dmp

Dynamic Motion Primitive (DMP) generation and reproduction utilities.

DMPs represent demonstrations as stable dynamical systems with learned Gaussian-basis forcing terms. This module supports standard signals, quaternion orientations, and Cartesian pose trajectories.

DMP parameter dictionaries use the following entries:

DMP parameters

Parameter

Description

N

Number of Gaussian basis functions (default: 25).

a_z

Transformation-system spring gain (default: 48.0).

b_z

Transformation-system damping gain (default: a_z / 4).

a_x

Canonical-system phase decay rate (default: 2.0).

dt

Integration time step; inferred from the demonstration if omitted.

tau

Demonstration duration used for temporal scaling.

c

Centers of the Gaussian basis functions in phase space.

sigma

Variances of the Gaussian basis functions.

w

Learned basis-function weights for each trajectory dimension.

ps

Scaling factor for canonical phase decoding DMP.

y0

Initial signal value or, for a Cartesian DMP, initial pose.

dy0

Initial signal velocity or Cartesian twist.

goal

Goal signal value or, for a Cartesian DMP, goal pose.

q0

Initial quaternion for a quaternion DMP.

o0

Initial scaled angular velocity for a quaternion DMP.

gq

Goal quaternion for a quaternion DMP.

diag

Per-axis forcing-term scale for a quaternion DMP.
robotblockset.dmp.encodeDMP(inputTime: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], inputTrajectory: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], DMP: Mapping[str, Any] | None = None) → Dict[str, Any][source]

Encode sampled signals into a non-recursive locally weighted DMP.

Parameters:

  • inputTime (ArrayLike) – Sample times (n,) or a scalar sample interval.

  • inputTrajectory (ArrayLike) – Input signals with shape (n, m) or (n,).

  • DMP (Mapping[str, Any], optional) – Initial parameters. Supported values include N, a_z, b_z, a_x, ps, and dt. Missing values use DMP defaults.

Returns:

DMP parameters including w, c, sigma, tau, y0, dy0, and goal.

Return type:

DMPType

Raises:

ValueError – If the trajectory or time vector has an invalid shape or duration.

robotblockset.dmp.integrateStepDMP(DMP: Mapping[str, Any], S: MutableMapping[str, Any], phase_scaling: float = 1.0) → MutableMapping[str, Any][source]

Advance a standard DMP state by one Euler step.

S is updated in place and contains at least x, y, and z. The calculated dy, ddy, and normalized basis activation are added to the state.

Parameters:

  • DMP (Mapping[str, Any]) – Standard DMP parameter dictionary.

  • S (DMPState) – Mutable integration state.

  • phase_scaling (float, optional) – Positive canonical-phase time-scaling factor. Values greater than 1 slow phase progression and values below 1 accelerate it. Default is 1.

Returns:

The updated state dictionary.

Return type:

DMPState

Raises:

ValueError – If phase_scaling is not greater than zero.

robotblockset.dmp.decodeDMP(tf: float, DMP: Mapping[str, Any]) → Tuple[ndarray, ndarray, ndarray, ndarray][source]

Generate a trajectory from a standard DMP up to tf.

Parameters:

  • tf (float) – Requested final time in seconds.

  • DMP (Mapping[str, Any]) – Standard DMP parameter dictionary.

Returns:

Position, velocity, acceleration, and canonical phase arrays. The first three have shape (n, m) and phase has shape (n,). The initial state at t = 0 is included, so decoding a demonstration duration of (n - 1) * dt returns n samples.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

robotblockset.dmp.encodeQuaternionDMP(inputTime: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], inputQuaternionTrajectory: ndarray, DMP: Mapping[str, Any] | None = None) → Dict[str, Any][source]

Encode a quaternion trajectory into a quaternion DMP.

Quaternions use the scalar-first convention [w, x, y, z]. Angular velocity and acceleration are represented as three-dimensional vectors.

Parameters:

  • inputTime (ArrayLike) – Sample times (n,) or a scalar sample interval.

  • inputQuaternionTrajectory (QuaternionsType) – Unit quaternion trajectory with shape (n, 4).

  • DMP (Mapping[str, Any], optional) – Initial DMP parameters. Missing values use DMP defaults.

Returns:

Quaternion DMP parameters, including q0, gq, w, c, sigma, tau, and diag.

Return type:

DMPType

Raises:

ValueError – If the quaternion trajectory or time vector is invalid.

robotblockset.dmp.integrateStepQuaternionDMP(DMP: Mapping[str, Any], S: MutableMapping[str, Any], phase_scaling: float = 1.0) → MutableMapping[str, Any][source]

Advance a quaternion DMP state by one Euler step.

The quaternion in S['q'] is integrated on the unit sphere and remains normalized after the update.

Parameters:

  • DMP (Mapping[str, Any]) – Quaternion DMP parameter dictionary.

  • S (DMPState) – Mutable state containing q, o, and x.

  • phase_scaling (float, optional) – Positive canonical-phase time-scaling factor. Values greater than 1 slow phase progression and values below 1 accelerate it. Default is 1.

Returns:

Updated state containing quaternion, angular velocity, and angular acceleration values.

Return type:

DMPState

Raises:

ValueError – If phase_scaling is not greater than zero.

robotblockset.dmp.decodeQuaternionDMP(tf: float, DMP: Mapping[str, Any]) → Tuple[ndarray, ndarray, ndarray, ndarray][source]

Generate a quaternion trajectory from a quaternion DMP.

Parameters:

  • tf (float) – Requested final time in seconds.

  • DMP (Mapping[str, Any]) – Quaternion DMP parameter dictionary.

Returns:

Unit quaternions (n, 4), angular velocities (n, 3), angular accelerations (n, 3), and canonical phase values (n,). The initial state at t = 0 is included.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

robotblockset.dmp.encodeCartesianDMP(inputTime: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], inputTrajectory: ndarray, DMP: Mapping[str, Any] | None = None) → Dict[str, Any][source]

Encode an SE(3) trajectory as a combined Cartesian DMP.

The input pose is [x, y, z, qw, qx, qy, qz]. The returned dictionary combines the three position DMP outputs and the three-dimensional quaternion DMP forcing term, matching the MATLAB Cartesian DMP format.

Parameters:

  • inputTime (ArrayLike) – Sample times (n,) or a scalar sample interval.

  • inputTrajectory (Poses3DType) – Cartesian pose trajectory with shape (n, 7).

  • DMP (Mapping[str, Any], optional) – Initial DMP parameters. Missing values use DMP defaults.

Returns:

Combined Cartesian DMP parameter dictionary.

Return type:

DMPType

Raises:

ValueError – If the input trajectory is not an (n, 7) pose path.

robotblockset.dmp.decodeCartesianDMP(tf: float, DMP: Mapping[str, Any]) → Tuple[ndarray, ndarray, ndarray, ndarray][source]

Generate an SE(3) trajectory from a combined Cartesian DMP.

Parameters:

  • tf (float) – Requested final time in seconds.

  • DMP (Mapping[str, Any]) – Combined Cartesian DMP parameter dictionary.

Returns:

Cartesian poses (n, 7), twists (n, 6), accelerations (n, 6), and canonical phase values (n,). The initial state at t = 0 is included.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

robotblockset.dmp.Path2DMP(p: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], N: int = 25) → Dict[str, Any][source]

Encode a time-parameterized path into a standard DMP.

Parameters:

  • p (ArrayLike) – Path array (n, m + 1). The first column contains time and the remaining columns contain the signals.

  • N (int, optional) – Number of Gaussian basis functions. Default is 25.

Returns:

Encoded DMP parameter dictionary.

Return type:

DMPType

Raises:

ValueError – If the path does not contain a time column and at least one signal.

robotblockset.dmp.DMP2Path(DMP: Mapping[str, Any], x_f: float | None = None) → ndarray[source]

Decode a standard DMP into a time, phase, and state path.

Parameters:

  • DMP (Mapping[str, Any]) – Standard DMP parameter dictionary.

  • x_f (float, optional) – Stopping phase. If omitted, it is selected from tau and dt.

Returns:

Array with columns [time, phase, y, dy, ddy].

Return type:

np.ndarray

robotblockset.dmp.x_encodeDMP(y: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], DMP: Mapping[str, Any]) → Dict[str, Any][source]

Encode uniformly sampled signals using recursive regression.

Parameters:

  • y (ArrayLike) – Uniformly sampled signals with shape (n, m) or (n,).

  • DMP (Mapping[str, Any]) – Initial parameters. It must contain dt; other missing parameters use DMP defaults.

Returns:

DMP parameter dictionary containing recursively fitted weights.

Return type:

DMPType

robotblockset.dmp.x_decodeDMP(DMP: Mapping[str, Any], S: MutableMapping[str, Any]) → MutableMapping[str, Any][source]

Advance a recursive-regression DMP state by one step.

Parameters:

  • DMP (Mapping[str, Any]) – DMP parameter dictionary.

  • S (DMPState) – Mutable state containing phase, position, and scaled velocity.

Returns:

Updated state dictionary.

Return type:

DMPState

robotblockset.dmp.integrateStepCartesianDMP(DMP: Mapping[str, Any], S: MutableMapping[str, Any], phase_scaling: float = 1.0) → MutableMapping[str, Any][source]

Advance a combined Cartesian DMP state by one Euler step.

Parameters:

  • DMP (Mapping[str, Any]) – Combined Cartesian DMP parameter dictionary.

  • S (DMPState) – Mutable state containing a seven-dimensional pose y, six- dimensional scaled velocity z, and phase x.

  • phase_scaling (float, optional) – Positive canonical-phase time-scaling factor. Values greater than 1 slow phase progression and values below 1 accelerate it. Default is 1.

Returns:

Updated Cartesian state with pose, velocity, acceleration, and phase.

Return type:

DMPState

Raises:

ValueError – If phase_scaling is not greater than zero.

Functions

DMP2Path(DMP[, x_f])

Decode a standard DMP into a time, phase, and state path.

Path2DMP(p[, N])

Encode a time-parameterized path into a standard DMP.

decodeCartesianDMP(tf, DMP)

Generate an SE(3) trajectory from a combined Cartesian DMP.

decodeDMP(tf, DMP)

Generate a trajectory from a standard DMP up to tf.

decodeQuaternionDMP(tf, DMP)

Generate a quaternion trajectory from a quaternion DMP.

encodeCartesianDMP(inputTime, inputTrajectory)

Encode an SE(3) trajectory as a combined Cartesian DMP.

encodeDMP(inputTime, inputTrajectory[, DMP])

Encode sampled signals into a non-recursive locally weighted DMP.

encodeQuaternionDMP(inputTime, ...[, DMP])

Encode a quaternion trajectory into a quaternion DMP.

integrateStepCartesianDMP(DMP, S[, ...])

Advance a combined Cartesian DMP state by one Euler step.

integrateStepDMP(DMP, S[, phase_scaling])

Advance a standard DMP state by one Euler step.

integrateStepQuaternionDMP(DMP, S[, ...])

Advance a quaternion DMP state by one Euler step.

x_decodeDMP(DMP, S)

Advance a recursive-regression DMP state by one step.

x_encodeDMP(y, DMP)

Encode uniformly sampled signals using recursive regression.