Tasks

Base classes

class mink_warp.Task

Bases: ABC

Abstract base class for kinematic tasks.

cost

Weight vector (same dimension as the task error). Units depend on the task (e.g. \([\mathrm{cost}] / [\mathrm{m}]\) for position).

gain

Task gain \(\alpha \in [0, 1]\) for low-pass filtering. Defaults to 1.0 (dead-beat).

lm_damping

Unitless Levenberg–Marquardt scale (active when the error is large). Helps under infeasible targets.

k: int = 0

supports_cuda_graph: bool = True

False when _eval() reads device state on the host (e.g. q.numpy()); such tasks cannot participate in CUDA graph capture.

compute_error(configuration: Configuration) → array

compute_jacobian(configuration: Configuration) → array

error_jacobian_cost(configuration: Configuration) → tuple[array, array, array]

Raw (error, jacobian, cost) after a single _eval.

Used by the optimizer solvers (LM / L-BFGS), which own their damping and therefore need the unweighted, non-negated residual — not the gain/lm_damping-shaped compute_residual().

error_cost(configuration: Configuration) → tuple[array, array]

Raw (error, cost) after a single _eval (trial-cost evaluation).

compute_residual(configuration: Configuration) → tuple[array, array, array]

Weighted residual (W, e, mu) for the IK normal equations.

Tasks are stacked into a least-squares objective equivalent to Mink’s QP cost:

\[\frac{1}{2} \| W J \Delta q + \alpha e \|_2^2 = \frac{1}{2} \Delta q^\top H \Delta q + c^\top \Delta q\]

with \(H = \sum_i W_i^\top W_i + \mu I\) and \(c = \sum_i -W_i^\top (\alpha e_i)\). Here \(W\) is a diagonal weight matrix from cost, \(\alpha\) is gain, and \(\mu\) is the per-task LM term from lm_damping.

First-order task dynamics (per task, before stacking):

\[J(q)\, \Delta q = -\alpha\, e(q)\]

Parameters:

configuration – Batched robot configuration \(q\) with shape (nworld, nq).

Returns:

Weighted Jacobian \(WJ\), weighted error \(-\alpha W e\), and scalar LM damping \(\mu\) per world.

compute_qp_residual(configuration: Configuration) → tuple[array, array, array]

Weighted residual (W, e, mu) for the IK normal equations.

Tasks are stacked into a least-squares objective equivalent to Mink’s QP cost:

\[\frac{1}{2} \| W J \Delta q + \alpha e \|_2^2 = \frac{1}{2} \Delta q^\top H \Delta q + c^\top \Delta q\]

with \(H = \sum_i W_i^\top W_i + \mu I\) and \(c = \sum_i -W_i^\top (\alpha e_i)\). Here \(W\) is a diagonal weight matrix from cost, \(\alpha\) is gain, and \(\mu\) is the per-task LM term from lm_damping.

First-order task dynamics (per task, before stacking):

\[J(q)\, \Delta q = -\alpha\, e(q)\]

Parameters:

configuration – Batched robot configuration \(q\) with shape (nworld, nq).

Returns:

Weighted Jacobian \(WJ\), weighted error \(-\alpha W e\), and scalar LM damping \(\mu\) per world.

class mink_warp.tasks.TargetedTask

Bases: Task

Task with a batched device target buffer.

Targets are wp.array with shape (nworld, target_width) or a single row broadcast to all worlds. Host uploads use to_wp() at boundaries.

target_width: int = 0

Kinematic tasks

class mink_warp.FrameTask

Bases: TargetedTask

Regulate the pose of a body, geom, or site in the world frame.

The error is a body twist \(e(q) \in \mathbb{R}^6\) (linear then angular) expressed in the regulated frame \(b\). With target frame \(t\) and world frame \(0\):

\[e(q) := \log(T_{bt}) = \log(T_{b0}^{-1} T_{t0})\]

The Jacobian (Mink / Pink body-frame convention) is:

\[J(q) = -\mathrm{jlog}_6(T_{tb})\, {}_b J_{0b}(q)\]

Costs homogenize SI units: position_cost is in \([\mathrm{cost}] / [\mathrm{m}]\), orientation_cost in \([\mathrm{cost}] / [\mathrm{rad}]\). A 1 cm position error at unit position cost weighs like a 1 rad error at unit orientation cost only when the costs are chosen accordingly.

See also

RelativeFrameTask when the target is expressed in a mobile root frame rather than the world.

k: int = 6

target_width: int = 7

set_position_cost(position_cost: ArrayLike) → None

set_orientation_cost(orientation_cost: ArrayLike) → None

set_target(transform_target_to_world: array | SE3 | TypeAliasForwardRef('ArrayLike'), *, configuration: Configuration | None = None) → None

set_target_from_configuration(configuration: Configuration) → None

class mink_warp.RelativeFrameTask

Bases: TargetedTask

Regulate a frame pose relative to a root frame.

The target is a rigid transform \(T_{tr}\) (frame \(t\) expressed in root \(r\)). With current relative pose \(T_{br}\):

\[e(q) = \log(T_{bt}) \quad \text{with} \quad T_{bt} = T_{br}\, T_{tr}^{-1}\]

The Jacobian accounts for both the regulated frame and the root frame (chain rule on \(SE(3)\)), matching Mink’s RelativeFrameTask.

Costs use the same units as FrameTask: \([\mathrm{cost}] / [\mathrm{m}]\) and \([\mathrm{cost}] / [\mathrm{rad}]\).

k: int = 6

target_width: int = 7

set_position_cost(position_cost: ArrayLike) → None

set_orientation_cost(orientation_cost: ArrayLike) → None

set_target(transform_target_to_root: array | SE3 | TypeAliasForwardRef('ArrayLike'), *, configuration: Configuration | None = None) → None

set_target_from_configuration(configuration: Configuration) → None

class mink_warp.PostureTask

Bases: TargetedTask

Regulate joint coordinates toward a nominal posture.

\[e(q) = \mathrm{diff}(q, q^\star), \qquad J(q) = I_{n_v}\]

where \(\mathrm{diff}\) is MuJoCo’s mj_differentiatePos (handles hinge, slide, ball, and free joints). Free-joint rows are zeroed in the residual (Mink behaviour). Cost units: \([\mathrm{cost}] / [\mathrm{rad}]\) for revolute joints, \([\mathrm{cost}] / [\mathrm{m}]\) for prismatic joints.

set_cost(cost: ArrayLike) → None

set_target(target_q: array | TypeAliasForwardRef('ArrayLike'), *, configuration: Configuration | None = None) → None

set_target_from_configuration(configuration: Configuration) → None

class mink_warp.EqualityConstraintTask

Bases: Task

Regulate MuJoCo equality constraints (connect, weld, joint equality, …).

\[e(q) = \mathrm{efc\_pos}(q), \qquad J(q) = \mathrm{efc\_J}(q)\]

Rows are read from host mj_forward per world (MuJoCo Warp does not yet expose batched equality data). Suitable for closed chains at moderate nworld.

supports_cuda_graph: bool = False

False when _eval() reads device state on the host (e.g. q.numpy()); such tasks cannot participate in CUDA graph capture.

set_cost(cost: ArrayLike) → None

class mink_warp.ComTask

Bases: TargetedTask

Regulate the center of mass of subtree body 1 (whole robot).

\[e(q) = c(q) - c^\star, \qquad J(q) = \frac{\partial c}{\partial q}\]

where \(c(q) \in \mathbb{R}^3\) is the mass-weighted subtree CoM. Cost units: \([\mathrm{cost}] / [\mathrm{m}]\) per axis.

k: int = 3

target_width: int = 3

set_cost(cost: ArrayLike) → None

set_target(target_com: array | TypeAliasForwardRef('ArrayLike'), *, configuration: Configuration | None = None) → None

set_target_from_configuration(configuration: Configuration) → None

Regularization

class mink_warp.DampingTask

Bases: PostureTask

L2 regularization on joint velocities.

Sets \(e(q) = 0\) and \(J = I_{n_v}\) with gain=0, so the task contributes only through the weighted Jacobian term in \(H = J^\top W^2 J\), penalizing large \(\Delta q\) (velocity when divided by \(\mathrm{d}t\)). Cost units match PostureTask.

set_target(target_q=None, *, configuration=None) → None

set_target_from_configuration(configuration: Configuration) → None

Soft limits

class mink_warp.JointLimitTask

Bases: Task

Soft hinge/slide joint limits as a least-squares penalty.

When \(q_i\) violates bounds \([q_i^{\min}, q_i^{\max}]\):

\[\begin{split}e_i = \begin{cases} q_i - q_i^{\max} & q_i > q_i^{\max} \\ q_i - q_i^{\min} & q_i < q_i^{\min} \\ 0 & \text{otherwise} \end{cases}\end{split}\]

with \(J_{ii} = 1\) on limited dofs. Free and ball joints are ignored. For hard limits use ConfigurationLimit.

set_cost(cost: ArrayLike) → None

mink_warp.ConfigurationLimitTask

alias of JointLimitTask