PhysX error when setting angular damping: PxSceneFlag::eENABLE_DIRECT_GPU_API prevents setGlobalPose / setLinearVelocity

[shy924]

Description

I encounter a PhysX runtime error when trying to apply PhysxRigidBodyAPI and set angular damping for a prim.

The code works for creating the attribute, but during simulation PhysX throws errors related to PxSceneFlag::eENABLE_DIRECT_GPU_API.

Code

prim = stage.GetPrimAtPath(prim_path)

physx_rigid_body = PhysxSchema.PhysxRigidBodyAPI(prim)
if not physx_rigid_body:
    physx_rigid_body = PhysxSchema.PhysxRigidBodyAPI.Apply(prim)

angular_attr = physx_rigid_body.CreateAngularDampingAttr()
angular_attr.Set(angular_damping)

Error Log

[Error] [omni.physx.plugin] PhysX error: PxRigidDynamic::setGlobalPose(): it is illegal to call this method if PxSceneFlag::eENABLE_DIRECT_GPU_API is enabled!, FILE /builds/omniverse/physics/physx/source/physx/src/NpRigidDynamic.cpp, LINE 102 

[Error] [omni.physx.plugin] PhysX error: PxRigidDynamic::setLinearVelocity(): it is illegal to call this method if PxSceneFlag::eENABLE_DIRECT_GPU_API is enabled!, FILE /builds/omniverse/physics/physx/source/physx/src/NpRigidDynamic.cpp, LINE 239 

[Error] [omni.physx.plugin] PhysX error: PxRigidDynamic::setAngularVelocity(): it is illegal to call this method if PxSceneFlag::eENABLE_DIRECT_GPU_API is enabled!, FILE /builds/omniverse/physics/physx/source/physx/src/NpRigidDynamic.cpp, LINE 287

Expected Behavior

Setting the angular damping attribute should not trigger PhysX errors during simulation.

Questions

Is this caused by the PhysX scene running with PxSceneFlag::eENABLE_DIRECT_GPU_API?

Are we not allowed to modify rigid body state (angular damping) when the direct GPU API is enabled?

Is there a recommended way to configure damping parameters for rigid bodies when running GPU PhysX?

Environment

Simulator: Isaac Sim

Framework: Isaac Lab

PhysX backend: GPU PhysX

Python API: `PhysxSchema.PhysxRigidBodyAPI```

[michaellin6]

Hi @shy924 thank you for posting this issue. I'll look into this issue shortly.

[michaellin6]

Hi @shy924, are you calling these API functions after having started simulation?

When eENABLE_DIRECT_GPU_API is set, PhysX restricts calls (setGlobalPose, setLinearVelocity, setAngularVelocity) that modify its internal state.

In Isaac Sim with GPU PhysX, you should set physics properties before simulation starts or during stage setup, not during runtime.

[shy924]

Hi @michaellin6 .Thanks for your response and feedback!

I want to clarify that I am indeed setting the physics properties during the startup phase using the mode="startup". Specifically, I'm using the Isaac Lab Event Manager to randomize and set properties (like angular damping) at the startup, well before the simulation begins.

Here is the detailed flow:

1. Using the Event Manager:
   I have configured the physics properties to be randomized on startup with the EventCfg class. This is done by calling RandomizeRigidBodyProperties with mode="startup". The RandomizeRigidBodyProperties class is responsible for randomizing and setting properties such as angular damping.

2. Code Setup:
   Below is the relevant part of the code in env_cfg.py and event.py, where I define how properties are set:

# env_cfg.py
@configclass
class EventCfg:
    physics_properties_object = EventTerm(
        func=mdp.RandomizeRigidBodyProperties,
        mode="startup",  # Ensuring this runs on startup
        params={
            "asset_cfg": SceneEntityCfg("object", body_names=".*"),
            "angular_damping_range": (0.4, 0.6),
        },
    )


# events.py
def set_rigid_body_properties(
    stage: Usd.Stage,
    prim_path: str,
    kinematic_enabled: Optional[bool] = None,
    linear_damping: Optional[float] = None,
    angular_damping: Optional[float] = None,
    max_linear_velocity: Optional[float] = None,
    max_angular_velocity: Optional[float] = None,
) -> bool:
    """Set rigid body properties on a prim."""
    try:
        prim = stage.GetPrimAtPath(prim_path)
        if not prim:
            logger.warning(f"Prim not found at {prim_path}")
            return False

        rigid_body_api = UsdPhysics.RigidBodyAPI(prim)
        if not rigid_body_api:
            rigid_body_api = UsdPhysics.RigidBodyAPI.Apply(prim)

        if kinematic_enabled is not None:
            kinematic_attr = rigid_body_api.CreateKinematicEnabledAttr()
            kinematic_attr.Set(kinematic_enabled)

        physx_rigid_body = PhysxSchema.PhysxRigidBodyAPI(prim)
        if not physx_rigid_body:
            physx_rigid_body = PhysxSchema.PhysxRigidBodyAPI.Apply(prim)

        if linear_damping is not None:
            linear_attr = physx_rigid_body.CreateLinearDampingAttr()
            linear_attr.Set(linear_damping)

        if angular_damping is not None:
            angular_attr = physx_rigid_body.CreateAngularDampingAttr()
            angular_attr.Set(angular_damping)

        if max_linear_velocity is not None:
            max_linear_attr = physx_rigid_body.CreateMaxLinearVelocityAttr()
            max_linear_attr.Set(max_linear_velocity)

        if max_angular_velocity is not None:
            max_angular_attr = physx_rigid_body.CreateMaxAngularVelocityAttr()
            max_angular_attr.Set(max_angular_velocity)

        return True

    except Exception as e:
        raise RuntimeError(f"Error setting rigid body properties for {prim_path}: {e}")


class RandomizeRigidBodyProperties(ManagerTermBase):
    """Randomize rigid body properties on all geometries of the asset."""

    def __init__(self, cfg: EventTermCfg, env: ManagerBasedEnv):
        super().__init__(cfg, env)

        self.asset_cfg: SceneEntityCfg = cfg.params["asset_cfg"]
        self.asset: RigidObject | Articulation = env.scene[self.asset_cfg.name]

        if not isinstance(self.asset, (RigidObject, Articulation)):
            raise ValueError(
                f"Randomization term 'RandomizeRigidBodyProperties' not supported for asset: '{self.asset_cfg.name}'"
                f" with type: '{type(self.asset)}'."
            )

    def __call__(
        self,
        env: ManagerBasedEnv,
        env_ids: torch.Tensor | None,
        asset_cfg: SceneEntityCfg,
        kinematic_enabled: Optional[bool] = None,
        linear_damping_range: Optional[tuple[float, float]] = None,
        angular_damping_range: Optional[tuple[float, float]] = None,
        max_linear_velocity_range: Optional[tuple[float, float]] = None,
        max_angular_velocity_range: Optional[tuple[float, float]] = None,
    ):
        linear_damping = None
        angular_damping = None
        max_linear_velocity = None
        max_angular_velocity = None

        if linear_damping_range is not None:
            linear_damping = float(torch.empty(1).uniform_(linear_damping_range[0], linear_damping_range[1]).item())

        if angular_damping_range is not None:
            angular_damping = float(torch.empty(1).uniform_(angular_damping_range[0], angular_damping_range[1]).item())

        if max_linear_velocity_range is not None:
            max_linear_velocity = float(torch.empty(1).uniform_(max_linear_velocity_range[0], max_linear_velocity_range[1]).item())

        if max_angular_velocity_range is not None:
            max_angular_velocity = float(torch.empty(1).uniform_(max_angular_velocity_range[0], max_angular_velocity_range[1]).item())

        stage = omni.usd.get_context().get_stage()
        if not stage:
            logger.warning("Could not get USD stage for setting rigid body properties")
            return

        target_prim_paths = []
        if isinstance(self.asset, RigidObject):
            if hasattr(sim_utils, "find_matching_prim_paths"):
                target_prim_paths = sim_utils.find_matching_prim_paths(self.asset.cfg.prim_path)
            else:
                template_prim = sim_utils.find_first_matching_prim(self.asset.cfg.prim_path)
                if template_prim:
                    target_prim_paths = [str(template_prim.GetPath())]

        elif isinstance(self.asset, Articulation):
            if hasattr(self.asset.root_physx_view, "link_paths"):
                for env_links in self.asset.root_physx_view.link_paths:
                    for link_path in env_links:
                        target_prim_paths.append(link_path)

        for prim_path in target_prim_paths:
            set_rigid_body_properties(
                stage=stage,
                prim_path=prim_path,
                kinematic_enabled=kinematic_enabled,
                linear_damping=linear_damping,
                angular_damping=angular_damping,
                max_linear_velocity=max_linear_velocity,
                max_angular_velocity=max_angular_velocity,
            )

The Issue:

Upon testing, I found that the PhysX error only occurs when I modify angular damping. Specifically, the error does not occur when I comment out the part of the code where I set angular_damping:

# Commenting out this section prevents the PhysX error
if angular_damping is not None:
    angular_attr = physx_rigid_body.CreateAngularDampingAttr()
    angular_attr.Set(angular_damping)
    

Possible Cause:

It seems like PhysX is rejecting the modification of angular_damping.
I’m calling set_rigid_body_properties within the RandomizeRigidBodyProperties function that is configured to run on startup, but it seems like there might be a case where this randomization is happening after the simulation has started, thus causing the error.

[michaellin6]

Hi @shy924, thanks for the additional context.
The issue is that mode="startup" event terms in Isaac Lab fire after sim.reset(), which means the PhysX GPU pipeline is already active at that point. Modifying USD attributes (like angular_damping via PhysxSchema) after the GPU scene is created triggers the eENABLE_DIRECT_GPU_API errors as a side effect.

Fix: Change your event mode from "startup" to "prestartup":

  @configclass                                                                                                                                                                                                                                                                                                                                                                                         
  class EventCfg:                                                                                                                                                                                                                                                                                                                                                                                      
      physics_properties_object = EventTerm(                                                                                                                                                                                                                                                                                                                                                           
          func=mdp.RandomizeRigidBodyPrope rties,                                                                                                                                                                                                                                                                                                                                                      
          mode="prestartup",  # <-- runs before physics scene creation                                                                                                                                                                                                                                                                                                                                 
          params={                                                                                                                                                                                                                                                                                                                                                                                     
              "asset_cfg": SceneEntityCfg("object", body_names=".*"),                                                                                                                                                                                                                                                                                                                                  
              "angular_damping_range": (0.4, 0.6),                                                                                                                                                                                                                                                                                                                                                     
          },                                                                                                                                                                                                                                                                                                                                                                                           
      )                                                                                                                                                                                                                                                                                                                                                                                                

"prestartup" fires before the simulation is initialized, so the USD attribute changes get picked up when PhysX creates the scene. By the time the GPU Direct API is active, the damping values are already baked in.

Angular damping is a property that PhysX reads at scene creation time — it's not exposed through the GPU tensor API (RigidBodyView has no set_angular_dampings), so it must be set before the physics scene is built.

If you are looking for randomizing angular damping during training, one way you can achieve that is to apply the damping forces manually. Something like this:

  class ApplyAngularDamping(ManagerTermBa se):                                                                                                                                                                                                                                                                                                                                                          
      """Apply angular damping as an external torque each step (GPU-compatible)."""              
                                                                                                 
      def __init__(self, cfg, env):                                                              
          super().__init__(cfg, env)                                                                                                                                                               
          self.asset = env.scene[cfg.params["asset_cfg" ].name]                                                                                                                                                                                                                                                                                                                                        
          # Random damping coefficient per env, re-sampled on reset                              
          self.damping_coeffs = torch.zeros(env.num_envs, 1, device=env.device)                  
                                                                                                                                                                                                   
      def __call__(self, env, env_ids, asset_cfg, damping_range=(0.4, 0.6)):                                                                                                                                                                                                                                                                                                                           
          if env_ids is not None:                                                                
              # Re-randomize damping for reset envs                                                                                                                                                
              self.damping_coeffs[env_ids] = torch.empty(                                        
                  len(env_ids), 1, device=env.device                                                                                                                                                                                                                                                                                                                                                   
              ).uniform_(*damping_range)                                                                                                                                                                                                                                                                                                                                                               
                                                                                                                                                                                                                                                                                                                                                                                                       
  # In your step loop, apply the damping torque:                                                 
  ang_vel = asset.data.root_ang_vel_w  # (num_envs, 3)                                                                                                                                                                                                                                                                                                                                                 
  damping_torque = -damping_coeffs * ang_vel                                                     
  asset.set_external_torque(dampin g_torque)                                                     

[shy924]

Thanks a lot for your detailed explanation — this is really helpful and clarifies the root cause very well.

I did try switching the event mode to "prestartup" as you suggested. However, in my case this runs into another issue because I have scene replication enabled. Isaac Lab raises the following error:

if term_cfg.mode == "prestartup" and self._env.scene.cfg.replicate_physics:
    raise RuntimeError(
        "Scene replication is enabled, which may affect USD-level randomization."
        " When assets are replicated, their properties are shared across instances,"
        " potentially leading to unintended behavior."
        " For stable USD-level randomization, please disable scene replication"
        " by setting 'replicate_physics' to False in 'InteractiveSceneCfg'."
    )

Since I rely on replicate_physics=True for performance, disabling it is not ideal for my setup.

At the moment, I’m still using the "startup" mode. Interestingly, the angular damping does appear to be correctly applied — I can verify this in the Isaac Lab visualization. The only issue is that during program startup, the PhysX GPU pipeline throws those eENABLE_DIRECT_GPU_API warnings/errors, which are quite noisy.

So functionally things seem to work, but the initialization errors are a bit annoying.

Thanks again for pointing me in the right direction — your explanation about when PhysX reads these properties was especially useful.