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 |
|
Screw |
Relative motion restricted to a helix about an axis of the first link (5 dofs), with optional travel limits and dry friction. |
|
|
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#
Control your robot: joint-level position, velocity, and force control.
Inverse kinematics and motion planning: the IK solving and path planning the suction example uses to reach the object.