Simulation Control#

Overview#

When a simulation is started, Omni PhysX will go through the following sequence of events:

1. The USD stage is parsed and physics objects are created within PhysX.

2. If required, PhysX cooking and convex decomposition is executed depending on mesh approximation USD schema attributes. The results of the cooking are cached in the USD stage file, so if the USD Stage is saved, the cooking doesn’t need to be repeated.

3. In addition, cooked data is also cached in the workstation’s local cache, so recomputation is sometimes also avoided even when the USD stage is not saved.

4. Simulation stepping begins once parsing is complete.

5. Simulation output is written to USD after each step. By default, this includes transformations and velocities (in local space) but it’s possible to change this.

6. Omni PhysX listens to USD changes, and changes are applied to PhysX while the simulation is running.

Simulation Output#

Physics simulation by default outputs transformations and velocities to USD, but on larger or complex scenes this can be very slow. It’s possible to write the output to Fabric using the omni.physx.fabric extension.

Examples of how to retrieve the rigid body position differs based on the simulation output - default USD, Fabric.

Default USD output:

from pxr import Usd, UsdGeom, Gf
import omni.usd

# Get the USD stage
stage = omni.usd.get_context().get_stage()

# Get the USD prim on the rigid body path
rbo_prim = stage.GetPrimAtPath("/World/boxActor")

# Change the type to UsdGeom.Xformable which is a requirement for rigid bodies
xform = UsdGeom.Xformable(rbo_prim)

# Acquire the world transformation, the result is a 4x4 doubles matrix
transform_matrix = xform.ComputeLocalToWorldTransform(Usd.TimeCode.Default())

# Decompose Gf.Transform to read individual components
transform = Gf.Transform(transform_matrix)
pos = transform.GetTranslation()
quat = transform.GetRotation().GetQuat()

Fabric and the USDRT interface may be used as follows:

from usdrt import Usd as UsdRt
import omni.usd

# Get the USDRT stage
usdrt_stage = UsdRt.Stage.Attach(omni.usd.get_context().get_stage_id())

# Get the USDRT prim
usdrt_prim = usdrt_stage.GetPrimAtPath("/World/boxActor")

# If Fabric is used the world transform is computed and stored in custom attributes.
usdrt_world_pos_attr = usdrt_prim.GetAttribute("_worldPosition")
pos = usdrt_world_pos_attr.Get()

usdrt_world_quat_attr = usdrt_prim.GetAttribute("_worldOrientation")
orient = usdrt_world_quat_attr.Get()

Alternatively, a batched approach can be used to access data with Warp arrays:

import warp as wp
from usdrt import Usd as UsdRt
from usdrt import Sdf as SdfRt
import omni.usd

# Get the USDRT stage
usdrt_stage = UsdRt.Stage.Attach(omni.usd.get_context().get_stage_id())

#Create a selection of rigid body positions in the world frame.
# Note that the selection may be created on CPU or GPU as required.
selection = usdrt_stage.SelectPrims(
    require_applied_schemas=["PhysicsRigidBodyAPI"],
    require_attrs=[
  (SdfRt.ValueTypeNames.Double3, "_worldPosition", UsdRt.Access.Read),
    ],
    device="cpu"
)

# Setup a simple Warp kernel to just read the position attribute values
@wp.kernel()
def read_prims(positions: wp.fabricarray(dtype=wp.vec3d)):
    i = wp.tid()
    pos = positions[i]
    print(pos)

# Use Warp on CPU to get the _worldPosition attribute array from the selection
# and process it with the kernel above
with wp.ScopedDevice("cpu"):
    positions = wp.fabricarray(selection, "_worldPosition")
    wp.launch(read_prims, dim=positions.size, inputs=[positions], device="cpu")

Setting up a USD Stage and a Physics Scene#

PhysicsScene prims are created by applying PhysxSchema.PhysxSceneAPI. PhysicsScene prims are responsible for simulating bodies added to their associated stage.

To simulate physics, each stage must have at least one PhysicsScene prim. However, the default behavior is that a single PhysicsScene is automatically created with default settings and that all bodies of the stage are simulated by this PhysicsScene prim. Alternatively, a user-created PhysicsScene with custom setting may take the place of the default PhysicsScene prim.

The following python snippet demonstrates how to create a stage and a single associated PhysicsScene prim:

import omni.usd
from pxr import UsdPhysics

stage = omni.usd.get_context().get_stage()

# Physics scene definition
scene = UsdPhysics.Scene.Define(stage, "/physicsScene")

import omni.usd
from pxr import UsdGeom, UsdPhysics, Gf

stage = omni.usd.get_context().get_stage()

# Set the stage up axis to Z
UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.z)

# Set units to 1.0
UsdGeom.SetStageMetersPerUnit(stage, 1.0)
UsdPhysics.SetStageKilogramsPerUnit(stage, 1.0)

# Physics scene definition
scene = UsdPhysics.Scene.Define(stage, "/physicsScene")

# Setup gravity to correspond to our stage up axis and unit scale.
# Note: By default, these values are derived from the USD stage settings as set above.
#       They are set here for the purpose of example but can usually be omitted.
scene.CreateGravityDirectionAttr().Set(Gf.Vec3f(0.0, 0.0, -1.0))
scene.CreateGravityMagnitudeAttr().Set(9.81)

Multiple Physics Scenes#

Simulation may proceed with multiple PhysicsScene prims. It is possible to specify the physics scene that will be used to simulate individual bodies and colliders: UsdPhysics.RigidBodyAPI and UsdPhysics.CollisionAPI have a simulationOwner relationship that defines the physics scene owner. If simulationOwner is not set, the first PhysicsScene found during traversal will be used. Note that objects in separate physics scenes do not collide with each other.

Using multiple scenes you can also distribute simulation across multiple GPUs.

from pxr import Usd, UsdGeom, UsdPhysics, UsdShade, Sdf, Gf, Tf

stage = omni.usd.get_context().get_stage()

# Physics scene definitions
scene0 = UsdPhysics.Scene.Define(stage, "/physicsScene0")
scene1 = UsdPhysics.Scene.Define(stage, "/physicsScene1")

# Create two rigid bodies
cube0 = UsdGeom.Cube.Define(stage, "/cube0")
rbo0 = UsdPhysics.RigidBodyAPI.Apply(cube0.GetPrim())

cube1 = UsdGeom.Cube.Define(stage, "/cube1")
rbo1 = UsdPhysics.RigidBodyAPI.Apply(cube1.GetPrim())

# Assign each to a different scene
rbo0.GetSimulationOwnerRel().AddTarget("/physicsScene0")
rbo1.GetSimulationOwnerRel().AddTarget("/physicsScene1")

Physics Solver#

The physics solver iteratively resolves constraints (joints, contacts, etc.) to achieve a physically accurate solution without object overlaps or disconnected joints. The solver can be configured using the scene API. Two different solver strategies are available: PGS (Projected Gauss-Seidel) and TGS (Temporal Gauss-Seidel). PGS converges more slowly but is less prone to overshooting compared to TGS. Overshooting occurs when objects gain excessive velocity in complex collision scenarios, even when they should not.

There are various solver settings. The iteration count defines how many iterations the solver can do to obtain the physics state after a time step. More iterations lead to more accurate results but take longer to compute. Position iterations ensure that bodies don’t overlap while velocity iterations avoid that bodies pick up velocity artificially when they interact. For TGS, only very few (around 1) velocity iterations are recommended but the TGS solver benefits from the option “Enable External Forces Every Iteration” since it allows for slightly improved convergence.

from pxr import Usd, UsdGeom, UsdPhysics, UsdShade, Sdf, Gf, Tf, PhysxSchema

stage = omni.usd.get_context().get_stage()

# Physics scene definition
scene = UsdPhysics.Scene.Define(stage, "/physicsScene")

# Set desired solver, thats PhysX SDK parameter, PhysxSchema has to be applied in order to add PhysX features
physxSceneAPI = PhysxSchema.PhysxSceneAPI.Apply(scene.GetPrim())
physxSceneAPI.CreateSolverTypeAttr().Set("TGS")

PhysX SDK GPU Memory Buffers#

PhysX SDK internal GPU buffers needs to be setup during initialization, if the buffer gets overflown error is reported and its required to increase the buffer size.

from pxr import Usd, UsdGeom, UsdPhysics, UsdShade, Sdf, Gf, Tf, PhysxSchema

stage = omni.usd.get_context().get_stage()

# Physics scene definition
scene = UsdPhysics.Scene.Define(stage, "/physicsScene")

# Change the initial GPU buffer size, thats PhysX SDK parameter, PhysxSchema has to be applied in order to add PhysX features
physxSceneAPI = PhysxSchema.PhysxSceneAPI.Apply(scene.GetPrim())
physxSceneAPI.CreateGpuFoundLostPairsCapacityAttr().Set(10 * 1024)

Solver Residual Reporting#

The residual values (a measure of physics solver convergence) can be obtained by using the residual reporting API. This API can be applied to non-articulation joints, articulation roots, and the physics scene. It reports aggregated residual values for the object to which it is added. These aggregated residuals include the root mean squared (RMS) and the maximum value from all residual sources. Therefore, the scene’s statistics encompass all residual sources within the scene, while an articulation only reports residual values originating from the articulation solve step. Note that the articulation only provides residual information on the articulation root and not on individual joints. The residuals are computed during the final position and velocity iterations.

from pxr import Usd, UsdGeom, UsdPhysics, UsdShade, Sdf, Gf, Tf, PhysxSchema

stage = omni.usd.get_context().get_stage()

# Physics scene definition
scene = UsdPhysics.Scene.Define(stage, "/physicsScene")

# Enable the residual reporting
physxSceneAPI = PhysxSchema.PhysxResidualReportingAPI.Apply(scene.GetPrim())

Simulation Stepping#

It is possible to step physics individually if required. In order to step physics a stage has to be attached, while the stage gets attached parsing happens and objects are created inside PhysX SDK. Detaching a stage will release all objects from PhysX SDK.

This example shows how to create completely independent stage that can be stepped individually.

from pxr import Usd, UsdGeom, UsdPhysics, UsdShade, Sdf, Gf, Tf, UsdUtils
from omni.physx import get_physx_simulation_interface

# Create new stage
stage = Usd.Stage.CreateInMemory()

# Add stage to the cache, this is required in order to get stage Id
cache = UsdUtils.StageCache.Get()
cache.Insert(stage)

stage_id = cache.GetId(stage).ToLongInt()

# Physics scene definitions
scene = UsdPhysics.Scene.Define(stage, "/physicsScene")

# Create a rigid bodies
cube = UsdGeom.Cube.Define(stage, "/cube")
UsdPhysics.RigidBodyAPI.Apply(cube.GetPrim())
UsdPhysics.CollisionAPI.Apply(cube.GetPrim())

# Attach the stage to omni.physx this will parse the stage and create objects inside PhysX SDK
get_physx_simulation_interface().attach_stage(stage_id)

# Step simulation few times
for i in range(0, 40):
    # Simulate, by provided delta and current time, the current time is used to update for example kinematic bodies with time sampled data
    # The provided delta time is passed directly to PhysX SDK no substepping happens
    # Note that this is not a blocking call, separate thread will get executed
    get_physx_simulation_interface().simulate(1/60.0, 40 * 1/60 + i * 1/60)

    # Fetch results will wait for simulation to finish and push simulation results to the output
    get_physx_simulation_interface().fetch_results()

# Detach stage, this will release all from PhysX SDK
get_physx_simulation_interface().detach_stage()

# Remove the stage from the cache
cache = UsdUtils.StageCache.Get()
cache.Erase(stage)

Simulation on multiple GPUs#

If your machine has multiple GPUs you can distribute simulation and rendering over those GPUs for potential performance gain.

• Set /renderer/multiGpu/enabled = true and /renderer/multiGpu/activeGpus to a comma separated list of GPU ordinals the renderer should use (e.g. “0, 1” would render using first and second GPU).

• Set /physics/cudaDevice to a GPU ordinal simulation should use OR split your stage into multiple PhysicsScenes and use /physics/sceneMultiGPUMode. You can also use Physics Preferences to switch the latter setting.

Note that the default value of /physics/cudaDevice is -1. This will use the GPU set through the NVIDIA Control Panel in the “Configure Surround, PhysX” section.

Setting /physics/sceneMultiGPUMode to 1 will simulate all available PhysicsScenes by assigning them to available GPUs in a round-robin fashion e.g. with 5 scenes and 2 GPUs the assignment is visualized in the following table:

Setting /physics/sceneMultiGPUMode to 2 will not assign any PhysicsScene to a GPU with device ordinal 0, hence for the example above no scenes would be assigned to GPU 0 and thus all scenes will be simulated only on GPU 1. This mode is intended to improve perfomance in cases where GPU 0 is set to be used for rendering.

There is currently no way how to explicitly assign specific PhysicsScenes to specific GPUs and the PhysicsScenes are assigned in the order they are traversed in USD. Turn on the MultiGPU logging channel to log the scene to GPU assignment.

The following example from a .kit file’s settings section would render on the first GPU and simulate on the second one:

[settings]
renderer.multiGpu.enabled = true
renderer.multiGpu.activeGpus = "0"
physics.cudaDevice = 1

Fabric#

Fabric is a data representation suited for runtime environments.

By default the simulation output is USD, however this does have significant performance overhead, especially if the scene contains many simulation objects. The USD output is considered to be the source of truth and all features are compatible with USD output.

To bypass the USD overhead, it is possible to configure Omni PhysX to output to Fabric.

Fabric only supports rigid bodies, articulations and deformables (excluding point instancer rigid bodies - Point Instancing).

To enable and test the Fabric feature:

1. Open the Extension Manager window.

2. Enable the extension omni.physx.fabric. or Enable the extension in Python code:

   manager = omni.kit.app.get_app().get_extension_manager()
   manager.set_extension_enabled_immediate("omni.physx.fabric", True)
   
   # If scene graph instancing is enabled additionally set this option to true, stage has to be reloaded or setting set before stage is opened
   carb.settings.get_settings().set("/persistent/omnihydra/useSceneGraphInstancing", True)
   

from pxr import Usd, UsdGeom, UsdPhysics, UsdShade, Sdf, Gf, Tf, UsdUtils
from omni.physx import get_physx_simulation_interface
from omni.physxfabric import get_physx_fabric_interface
from omni.physx.bindings._physx import SETTING_UPDATE_TO_USD


manager = omni.kit.app.get_app().get_extension_manager()
manager.set_extension_enabled_immediate("omni.physx.fabric", True)

# Setup physics to not output to USD
settings = carb.settings.get_settings()
settings.set(SETTING_UPDATE_TO_USD, False)

# Create new stage
stage = Usd.Stage.CreateInMemory()

# Add stage to the cache, this is required in order to get stage Id
cache = UsdUtils.StageCache.Get()
cache.Insert(stage)

stage_id = cache.GetId(stage).ToLongInt()

# Physics scene definitions
scene = UsdPhysics.Scene.Define(stage, "/physicsScene")

# Create a rigid bodies
cube = UsdGeom.Cube.Define(stage, "/cube")
UsdPhysics.RigidBodyAPI.Apply(cube.GetPrim())
UsdPhysics.CollisionAPI.Apply(cube.GetPrim())

# Attach the stage to omni.physx and omni.physx.fabric
get_physx_simulation_interface().attach_stage(stage_id)
get_physx_fabric_interface().attach_stage(stage_id)

# Step simulation few times
for i in range(0, 40):
    # Simulate, by provided delta and current time, the current time is used to update for example kinematic bodies with time sampled data
    # The provided delta time is passed directly to PhysX SDK no substepping happens
    # Note that this is not a blocking call, separate thread will get executed
    get_physx_simulation_interface().simulate(1/60.0, 40 * 1/60 + i * 1/60)

    # Fetch results will wait for simulation to finish
    get_physx_simulation_interface().fetch_results()
    # Update the omni.physx.fabric extension and update Fabric output
    get_physx_fabric_interface().update(1/60.0, 40 * 1/60 + i * 1/60)

# Detach stage from omni.physx and omni.physx.fabric
get_physx_fabric_interface().detach_stage()
get_physx_simulation_interface().detach_stage()

# Remove the stage from the cache
cache = UsdUtils.StageCache.Get()
cache.Erase(stage)

settings.set(SETTING_UPDATE_TO_USD, True)

Sleeping#

Sleeping is a mechanism in PhysX to save on computational resources when dynamic physics objects (e.g. bodies) are not in motion and do not require simulation updates. If an object is not moving for a short time duration, it may go to sleep until it is woken up either by:

• the user when they set a property that causes the object to move again, for example applying a force on a rigid body or changing the target position of an articulation joint drive;

• or the simulation when another object collides or interacts with the sleeping object, such that the sleeping object may move again.

For the different dynamic object types, e.g. rigid bodies, articulations or deformable bodies, you will find sleep-related properties such as a flag to have the rigid body start a simulation asleep, or the thresholds that PhysX uses to determine if an object is not moving and may be put to sleep. If you set those thresholds to zero, you can disable sleeping altogether on the object.

Be aware that sleep only occurs when the physics object is completely still. Once a physics object has been set in motion, it will often take long before velocities reach absolute zero, preventing objects from entering the sleep state. To mitigate this and more quickly free up computational resources, consider using the stabilization feature described below.

Stabilization#

The stabilization feature can be enabled to improve the settling behavior of rigid bodies in large-pile or high-interaction scenes by applying additional damping to slow-moving objects.

When a rigid body’s mass-normalized kinetic energy falls below a specified stabilization threshold, additional damping is applied to reduce jitter and instability, allowing objects to settle more efficiently.

However, stabilization reduces momentum, which may lead to unphysical effects. It is not recommended for robotics, industrial applications, or simulations requiring precise physics interactions.

physxSceneAPI = PhysxSchema.PhysxSceneAPI.Apply(physicsScenePrim)
physxSceneAPI.CreateEnableStabilizationAttr().Set(True)

physxRbAPI = PhysxSchema.PhysxRigidBodyAPI.Apply(rigidActorPrim)
physxRbAPI.CreateStabilizationThresholdAttr().Set(0.0001)