[Bug Report] The torque calculation formula in the documentation is inconsistent with the actual code implementation

[Limorettle]

Describe the bug

"The torque calculation formula in the documentation is inconsistent with the actual code implementation, which may cause confusion or errors."

Error details

In the documentation, the formula for calculating torque is:

$$\tau_{j, computed} = k_p * (q - q_{des}) + k_d * (\dot{q} - \dot{q}_{des}) + \tau_{ff}$$

Whereas in the code implementation:

def compute(
        self, control_action: ArticulationActions, joint_pos: torch.Tensor, joint_vel: torch.Tensor
    ) -> ArticulationActions:
        # compute errors
        error_pos = control_action.joint_positions - joint_pos
        error_vel = control_action.joint_velocities - joint_vel
        # calculate the desired joint torques
        self.computed_effort = self.stiffness * error_pos + self.damping * error_vel + control_action.joint_efforts

There are the following inconsistencies between the formula and the code:

The directions of the position error and velocity error are opposite.
In the documentation:
$(q - q_{des}),(\dot{q} - \dot{q}_{des})$

In the code:

$(q_{des} - q),(\dot{q}_{des} - \dot{q})$

This inconsistency may lead to misunderstandings or incorrect controller behavior. I would like to clarify the following points:

Is there a unified definition of the error direction in both the formula and the code?
If the code implementation is correct, should the formula in the documentation be revised to $(q_{des} - q)$ and $(\dot{q}_{des} - \dot{q})$?
If the formula in the documentation is correct, should the code be modified to match the formula?
Looking forward to your response. Thank you!

System Info

Describe the characteristic of your environment:

• Commit: [8f3b9ca]
• Isaac Sim Version: [4.2.0]
• OS: [Ubuntu 20.04]
• GPU: [RTX 4070 Ti Super]
• CUDA: [12.2]
• GPU Driver: [535.171.04]

[RandomOakForest]

Thanks for posting this. If you could share the link to the doc you are referring to would be appreciated. Thanks.

[Limorettle]

Thanks for posting this. If you could share the link to the doc you are referring to would be appreciated. Thanks.

In this class omni.isaac.lab.actuators.IdealPDActuator. The compute torque formula in the doc is inconsistent with the actual code implementation.

In the doc:

$$ \tau_{j, computed} = k_p * (q - q_{des}) + k_d * (\dot{q} - \dot{q}{des}) + \tau{ff} $$

In the code:

def compute(
        self, control_action: ArticulationActions, joint_pos: torch.Tensor, joint_vel: torch.Tensor
    ) -> ArticulationActions:
        # compute errors
        error_pos = control_action.joint_positions - joint_pos
        error_vel = control_action.joint_velocities - joint_vel
        # calculate the desired joint torques
        self.computed_effort = self.stiffness * error_pos + self.damping * error_vel + control_action.joint_efforts
        # clip the torques based on the motor limits
        self.applied_effort = self._clip_effort(self.computed_effort)
        # set the computed actions back into the control action
        control_action.joint_efforts = self.applied_effort
        control_action.joint_positions = None
        control_action.joint_velocities = None
        return control_action

Parameters:

    control_action – The joint action instance comprising of the desired joint positions, joint velocities and (feed-forward) joint efforts.

    joint_pos – The current joint positions of the joints in the group. Shape is (num_envs, num_joints).

    joint_vel – The current joint velocities of the joints in the group. Shape is (num_envs, num_joints).

[kellyguo11]

Thanks for spotting this. The code implementation should be correct, we'll update the docs.