Limits

Limits#

Definition#

All kinematic limits derive from the Limit base class.

class mink.limits.limit.Constraint#

Linear inequality constraint of the form \(G(q) \Delta q \leq h(q)\).

Inactive if G and h are None.

G: ndarray | None#

Alias for field number 0

h: ndarray | None#

Alias for field number 1

property inactive: bool#

Returns True if the constraint is inactive.

class mink.limits.limit.Limit#

Abstract base class for kinematic limits.

Subclasses must implement the compute_qp_inequalities() method which takes in the current robot configuration and integration time step and returns an instance of Constraint.

abstract compute_qp_inequalities(configuration: Configuration, dt: float) → Constraint#

Compute limit as linearized QP inequalities of the form:

\[G(q) \Delta q \leq h(q)\]

where \(q \in {\cal C}\) is the robot’s configuration and \(\Delta q \in T_q({\cal C})\) is the displacement in the tangent space at \(q\).

Parameters:

  • configuration (Configuration) – Robot configuration \(q\).

  • dt (float) – Integration time step in [s].

Returns:

Pair \((G, h)\).

Return type:

Constraint

Configuration limits#

Joint position limit.

class mink.limits.configuration_limit.ConfigurationLimit#

Inequality constraint on joint positions in a robot model.

Floating base joints are ignored. Slide and hinge joints are box-constrained to their range. A limited ball joint is constrained on its total rotation angle, bounded by the second element of its range (the first element is ignored, following MuJoCo semantics).

Note

The ball joint constraint is a first-order linearization that only bounds motion along the current rotation axis; motion orthogonal to the axis grows the angle at second order. Pair it with a velocity limit on the ball joint’s degrees of freedom so that large steps cannot overshoot the limit.

compute_qp_inequalities(configuration: Configuration, dt: float) → Constraint#

Compute the configuration-dependent joint position limits.

The limits are defined as:

\[{q \ominus q_{min}} \leq \Delta q \leq {q_{max} \ominus q}\]

where \(q \in {\cal C}\) is the robot’s configuration and \(\Delta q \in T_q({\cal C})\) is the displacement in the tangent space at \(q\). See the Derivations section for more information.

Parameters:

  • configuration (Configuration) – Robot configuration \(q\).

  • dt (float) – Integration timestep in [s].

Returns:

Pair \((G, h)\) representing the inequality constraint as \(G \Delta q \leq h\), or None if there is no limit.

Return type:

Constraint

Velocity limits#

Joint velocity limit.

class mink.limits.velocity_limit.VelocityLimit#

Inequality constraint on joint velocities in a robot model.

Floating base joints are ignored.

indices#

Tangent indices corresponding to velocity-limited joints. Shape (nb,).

Type:

numpy.ndarray

limit#

Maximum allowed velocity magnitude for velocity-limited joints, in [m]/[s] for slide joints and [rad]/[s] for hinge joints. Shape (nb,).

Type:

numpy.ndarray

projection_matrix#

Projection from tangent space to subspace with velocity-limited joints. Shape (nb, nv) where nb is the dimension of the velocity-limited subspace and nv is the dimension of the tangent space.

Type:

numpy.ndarray | None

compute_qp_inequalities(configuration: Configuration, dt: float) → Constraint#

Compute the configuration-dependent joint velocity limits.

The limits are defined as:

\[-v_{\text{max}} \cdot dt \leq \Delta q \leq v_{\text{max}} \cdot dt\]

where \(v_{max} \in {\cal T}\) is the robot’s velocity limit vector and \(\Delta q \in T_q({\cal C})\) is the displacement in the tangent space at \(q\). See the Derivations section for more information.

Parameters:

  • configuration (Configuration) – Robot configuration \(q\).

  • dt (float) – Integration timestep in [s].

Returns:

Pair \((G, h)\) representing the inequality constraint as \(G \Delta q \leq h\), or None if there is no limit. G has shape (2nb, nv) and h has shape (2nb,).

Return type:

Constraint

Free-joint velocity limits#

Free-joint (floating base) velocity limit.

class mink.limits.free_joint_velocity_limit.FreeJointVelocityLimit#

Velocity limit on a free joint (floating base).

VelocityLimit skips free joints; this bounds their six velocity DOFs as a linear and an angular part, both expressed in the base body frame.

MuJoCo stores the free-joint linear velocity in the world frame and the angular velocity in the body frame. The angular bound is thus applied directly, while the linear bound is rotated into the body frame by the base orientation \(R\), giving \(|R^\top v| \leq v_{\max}\).

linear_max#

Linear velocity bound in [m]/[s], or None. Shape (3,).

Type:

numpy.ndarray | None

angular_max#

Angular velocity bound in [rad]/[s], or None. Shape (3,).

Type:

numpy.ndarray | None

compute_qp_inequalities(configuration: Configuration, dt: float) → Constraint#

Compute the free-joint velocity limit as \(G \Delta q \leq h\).

Parameters:
Return type:

Constraint

Collision avoidance limits#

Collision avoidance limit.

mink.limits.collision_avoidance_limit.compute_contact_normal_jacobian(model: MjModel, data: MjData, geom1_id: int, geom2_id: int, fromto: ndarray, normal: ndarray, jac1: ndarray, jac2: ndarray) → ndarray#

Compute the contact normal Jacobian between two geoms.

Parameters:

  • model (MjModel)

  • data (MjData)

  • geom1_id (int)

  • geom2_id (int)

  • fromto (ndarray)

  • normal (ndarray)

  • jac1 (ndarray)

  • jac2 (ndarray)

Return type:

ndarray

class mink.limits.collision_avoidance_limit.CollisionAvoidanceLimit#

Normal distance limit between geom pairs.

model#

MuJoCo model.

geom_pairs#

Set of collision pairs in which to perform active collision avoidance. A collision pair is defined as a pair of geom groups. A geom group is a set of geom names. For each geom pair, the solver will attempt to compute joint velocities that avoid collisions between every geom in the first geom group with every geom in the second geom group. Self collision is achieved by adding a collision pair with the same geom group in both pair fields.

gain#

Fraction in (0, 1] of the gap above the minimum distance that the geoms may close in a single step. Smaller values are safer but slow the approach.

minimum_distance_from_collisions#

The minimum distance to leave between any two geoms. A negative distance allows the geoms to penetrate by the specified amount.

collision_detection_distance#

The distance between two geoms below which the limit is active. Must exceed the minimum distance, and the margin between them must exceed the largest distance the geoms can close in a single step (roughly the maximum approach speed times dt); otherwise pairs can pass through the band undetected. Larger values are safer but cost more distance queries.

bound_relaxation#

An offset on the upper bound of each collision avoidance constraint.

broadphase#

If True, skip geom pairs that are provably out of collision detection range before the expensive narrow-phase distance query. The assembled constraint is identical to the unfiltered computation.

compute_qp_inequalities(configuration: Configuration, dt: float) → Constraint#

Compute the configuration-dependent collision avoidance limits.

For each geom pair within the detection distance, the limit is defined as:

\[\begin{split}-\Delta d \leq \begin{cases} \xi (d - d_{min}) + \epsilon & d > d_{min} \\ \epsilon & \text{otherwise} \end{cases}\end{split}\]

where \(d\) is the signed distance between the geoms, \(\Delta d = n^T J \Delta q\) is its first-order change along the contact normal \(n\), \(\xi\) is the gain, \(d_{min}\) is the minimum distance, and \(\epsilon\) is the bound relaxation. The limit is a displacement bound and does not depend on \(dt\).

Parameters:

  • configuration (Configuration) – Robot configuration \(q\).

  • dt (float) – Integration timestep in [s].

Returns:

Pair \((G, h)\) representing the inequality constraint as \(G \Delta q \leq h\). Rows of inactive pairs have \(h = \infty\).

Return type:

Constraint