Rigid-body constraints#

A constraint ties two rigid links together so the solver keeps a geometric relationship between them: coincident points, a fixed relative pose, or coupled joint values. A model file declares most constraints once, and they hold for the whole simulation. One kind, the weld constraint, can be added and removed while the simulation runs, so a suction gripper can pick an object up and release it.

The complete runnable example is examples/rigid/suction_cup.py: a Franka arm reaches a cube, welds it to the hand, lifts and moves it, then releases.

Weld constraints at runtime#

A weld constraint pins two links so their relative pose is frozen at the values they have the instant you add it: all six degrees of freedom, translation and rotation. It is the constraint you toggle to model suction or a magnetic gripper: engage it when the end-effector reaches the object, delete it to let go.

The API lives on the rigid solver, not on an entity, because a weld couples links that belong to two different entities. Go through scene.sim.rigid_solver after the scene is built:

rigid = scene.sim.rigid_solver
link_cube = cube.get_link("box_baselink").idx
link_franka = franka.get_link("hand").idx
rigid.add_weld_constraint(link_cube, link_franka)

The arguments are global link indices (integers), not link or entity handles. Get an index from a link with entity.get_link(name).idx. The order of the two links does not matter.

Deleting the constraint releases the object:

rigid.delete_weld_constraint(link_cube, link_franka)

Pass the same two link indices you welded. Once released, the object responds to contact and gravity again, so it falls unless something supports it.

Note

A weld does not snap the links together, so move the end-effector into contact with the object before welding, or the object hangs in the air at whatever offset it had when the constraint engaged.

Applying to a subset of environments#

In a parallel simulation, both calls take an envs_idx argument to select which environments the weld applies to. Omit it to apply to all environments:

scene.build(n_envs=4)

rigid.add_weld_constraint(link_cube, link_franka, envs_idx=(0, 1, 2))
rigid.delete_weld_constraint(link_cube, link_franka, envs_idx=(0, 1))

The two link indices are the same across environments; only the environment selection differs.

Budgeting for dynamic constraints#

Runtime welds draw from a fixed pool sized before the scene is built. The pool holds max_dynamic_constraints welds (default 8), set on gs.options.RigidOptions:

scene = gs.Scene(
    rigid_options=gs.options.RigidOptions(max_dynamic_constraints=16),
)

Warning

Adding a weld once the pool is full has no effect: the solver logs a warning and ignores the request rather than raising. If a gripper silently fails to hold its object, check that you have released stale welds and that max_dynamic_constraints is large enough for the number held at once.

Querying active welds#

get_weld_constraints returns the welds currently active, as a dictionary of tensors keyed by field. link_a and link_b hold the welded link indices; force holds the constraint force. Each is batched over environments, with shape (n_envs, n_welds_max, ...):

welds = rigid.get_weld_constraints()  # dict with keys "link_a", "link_b", "force"

Pass to_torch=False for NumPy arrays, or as_tensor=False to get a per-environment tuple instead of a padded batch.

Constraint types#

Genesis World supports four equality-constraint types. Weld and screw are the ones you add at runtime, and connect and joint come from a model’s <equality> block when Genesis World loads an MJCF or URDF.

Type

Constrains

Declared in

Runtime API

Connect

A point on each link to coincide (3 dofs), a ball joint.

MJCF

—

Weld

Relative pose fully fixed (6 dofs).

MJCF, or add_weld_constraint

add_weld_constraint / delete_weld_constraint

Screw

Relative motion restricted to a helix about an axis of the first link (5 dofs), with optional travel limits and dry friction.

add_screw_constraint

add_screw_constraint / delete_screw_constraint

Joint

One joint’s value tied to another’s by a polynomial, or held at a constant offset when the model names a single joint.

MJCF, URDF

—

add_screw_constraint takes the axis in the frame of the first link and the travel per full turn as pitch, in meters. A pitch of zero gives a revolute motion and an infinite one a prismatic motion. The two links stop colliding with each other while the constraint holds, and it is not supported yet when requires_grad=True:

rigid.add_screw_constraint(link_bolt, link_nut, axis=(0.0, 0.0, 1.0), pitch=0.003, limit=(-0.02, 0.0))

A connect or joint constraint enters the simulation with its host model. There is no runtime API to add or remove it; edit the model file’s equality section instead.

See also#