Rigit solver batch_dofs_info needs explanation.

[stergiosba]

Bug Description

Hi team, this is not a bug but in my opinion some parameters/options need better documentation. Best example of this is the batch_dofs_info option. I had to look into the solver's code to see what this is doing and how its converting the shapes. The parameter is missing from RigidOptions docs in general.

For someone who is like me and doesn't "just get it", if you don't know about this parameter all the getter and setters for a RigidEntity will have wrong shape and from this someone can infer that the feature has not been implemented yet or get errors that scream about the shape (in setter functions).

Parameters of RigidEntity objects in the scene such as:

• get_dofs_act_gain
• get_dofs_bias
• get_dofs_force_range
  ....
  All are affected and have shape (n_dofs) instead of the expected (n_envs, n_dofs).

Note: I understand why this parameter is set to false by default for performance reasons.

KinematicOptions on the other hand are defined as:

genesis-world/genesis/options/solvers.py

Lines 352 to 373 in 4cfb9f0

	class KinematicOptions(Options):
	"""
	Options configuring the KinematicSolver (visualization-only solver).
	KinematicSolver is a lightweight solver for ghost/reference entities that only computes
	forward kinematics for visualization. No collision, physics integration, or constraint
	solving is performed.
	Parameters
	----------
	dt : float, optional
	Time duration for each simulation step in seconds. If none, it will inherit from `SimOptions`. Defaults to None.
	batch_links_info : bool, optional
	Whether to batch link info. Automatically enabled for heterogeneous simulation. Defaults to False.
	batch_dofs_info : bool, optional
	Whether to batch DOF info. Defaults to False.
	"""
	dt: PositiveFloat | None = None
	batch_links_info: StrictBool = False
	batch_joints_info: StrictBool = False
	batch_dofs_info: StrictBool = False

Here we can immediately see what this is.

Steps to Reproduce

This is just the simple franka example demo +dofs getters and setters.

import torch

import genesis as gs

########################## init ##########################
gs.init(backend=gs.gpu)

########################## create a scene ##########################
scene = gs.Scene(
    show_viewer=False,
    viewer_options=gs.options.ViewerOptions(
        camera_pos=(3.5, -1.0, 2.5),
        camera_lookat=(0.0, 0.0, 0.5),
        camera_fov=40,
    ),
    rigid_options=gs.options.RigidOptions(
        dt=0.01,
    ),
)

########################## entities ##########################
plane = scene.add_entity(
    gs.morphs.Plane(),
)

franka = scene.add_entity(
    gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"),
)

########################## build ##########################

# create 20 parallel environments
B = 20
scene.build(n_envs=B, env_spacing=(1.0, 1.0))

# control all the robots
franka.control_dofs_position(
    torch.tile(torch.tensor([0, 0, 0, -1.0, 0, 1.0, 0, 0.02, 0.02], device=gs.device), (B, 1)),
)

print(franka.get_dofs_act_gain().shape) # Prints Torch.size([9]) when it should be Torch.size([20, 9])
franka.set_dofs_stiffness(torch.ones([9]), envs_idx=(5,))
print(franka.get_dofs_stiffness()) # This prints tensor of 9 ones.
for i in range(1000):
    scene.step()

Expected Behavior

If we set:

scene = gs.Scene(
    show_viewer=False,
    viewer_options=gs.options.ViewerOptions(
        camera_pos=(3.5, -1.0, 2.5),
        camera_lookat=(0.0, 0.0, 0.5),
        camera_fov=40,
    ),
    rigid_options=gs.options.RigidOptions(
        dt=0.01,
        batch_dofs_info=True
    ),
)

This makes everything work as intended but it was not clear.

Screenshots/Videos

No response

Relevant log output

Environment

Not relevant.

Release version or Commit ID

Latest but also not relevant.

Additional Context

No response

[duburcqa]

The thing is, for now it is not clear if exposing this option to the user by documenting it is a good idea in the first place. It impedes performance while being useless if not confusing for most users.

I would like to know more about your use-case to determine if it is niche for something really standard. If it is standard, then we will document it properly.

[stergiosba]

Thanks for the reply. II try to give as much context as possible here, sorry if its to much. If I have misunderstood how this is to be used please tell me.

What I am trying to do: Domain randomization over different dof attributes.
Main need: Different values of dof attributes per environment.

My setup is the classic Gym style RL Environment class with reset() and step() functionality.
The Environment class has a self.scene defined as:

self.enable_batch_dofs_info = True <- Here I specify that dofs have shape: (n_envs, n_dofs)
self.scene = gs.Scene(
    sim_options=...
    vis_options=...
    viewer_options=...
    profiling_options=...
    rigid_options=gs.options.RigidOptions(
        dt=self.dt,
        constraint_solver=gs.constraint_solver.Newton,
        enable_collision=True,
        enable_joint_limit=True,
        batch_dofs_info=self.enable_batch_dofs_info,
    ),
    show_viewer=False,
)

After building the scene I do the following:

self.dof_random_dofs_attr = [
    "dofs_damping",
    "dofs_frictionloss",
    "dofs_armature",
    "dofs_stiffness",
]
for dofs_attr in self.dof_random_dofs_attr:
    getter = getattr(self.robot, f"get_{dofs_attr}")
    setattr(
        self, f"base_{dofs_attr}", getter(dofs_idx_local=self.motors_dof_idx)[0]
    ) if self.enable_batch_dofs_info else setattr(
        self, f"base_{dofs_attr}", getter(dofs_idx_local=self.motors_dof_idx)
    )

Then inside the reset function I do:

N = len(envs_idx)
for dofs_attr in self.dof_random_dofs_attr:
    dofs_attr_base_val = getattr(self, f"base_{dofs_attr}")
    dofs_attr_rnd_val = perturb_vector(
        dofs_attr_base_val, getattr(self.cfg.env.dofs_random, dofs_attr, 0.0), distribution="half-normal"
    )
    attr_dofs_setter = getattr(self.robot, f"set_{dofs_attr}")
    attr_dofs_setter(dofs_attr_rnd_val, self.motors_dof_idx, envs_idx=envs_idx)

Note: I use the above mentioned setup cause I compare some randomization strategies so I want to change things fast with the setters and getters.
perturb_vector samples a random vector from a selected torch.distributions.Distribution here a torch.distributions.half_normal.HalfNormal with the appropriate size. You can ignore it.

The last code block is the same as:

self.robot.set_dofs_damping(base_damping+random_damping)
self.robot.set_dofs_stiffness(base_stiffness+random_stiffness)
self.robot.set_dofs_armature(base_armature+random_armature)
self.robot.set_dofs_frictionloss(base_frictionloss+random_frictionloss)

This sets the dofs parameters as random for each environment. I hope this was clear.

Interesting note: I don't know why but when a lot of resets are happening (mostly at beginning of training where the majority of episodes end early) the set_dofs_armature is making things sluggish, all others do not. This has nothing to do with the random function because even by setting the armature to the base armature like self.robot.set_dofs_armature(base_armature) is very slow, when the 3 other properties are not. I am not sure how to benchmark this to communicate it better.