Simulation Management

You are able to have fine grained control over PhysX simulations. To do this, you can adjust settings that are located in four key places in the UI:

1. The property window of the prims that are simulation objects, for example rigid bodies. In the property window, you can add and remove simulation components, and fine-tune properties such as mass and collision-shape approximation.

2. The property window of the Physics Scene that holds general simulation properties such as gravity and solver parameters.

3. The Physics Settings window provides per-stage settings saved in USD metadata for portability; for example, settings include a lower bound on the simulation rate and mouse-interaction parameters.

4. The Physics Preferences in Edit > Preferences provides general simulation settings such as the option to enable or disable reset on stop.

5. The layer metadata that USD uses to scale units (for example, distance). The physics extension considers this scaling when parsing simulation parameters, so you must be aware of what scale you are using to author a simulation.

Debug visualization

To help you better analyze and locate potential issues in a simulation, the extension features a number of ways to visualize the physics elements of the scene.

Some of these can be enabled through the Physics section of the Show/Hide (Eye) menu in the viewport:

Here you can toggle the drawing of, for example, collision-shape approximations for physics bodies and the location of joints. You can also enable the Simulation Settings Window and the Simulation Data Visualizer Window from this section.

There are many other visualization and debug options available in the Physics Debug Window (Window > Simulation > Debug) under the Simulation Debug Visualization section.

Note

Debug visualization can be slow for large scenes.

Simulation Settings Window

This window allows you to view and change where simulation data (such as new positions and velocities) is being tracked and stored.

Note

If using Fabric, property windows will not be updated with the current simulation values.

You can also toggle whether the simulation data is reset to the initial values when stopped.

Simulation Data Visualizer Window

Often it is not enough to know the current simulation state to be able to analyze data and identify issues, but you may also need to know how the data is changing over time. The Simulation Data Visualizer window allows you to visualize this by plotting graphs of a physics object’s properties during simulation. To use this, enable the tool and select the Prim you want to monitor.

By default, the window targets the current scene selection. However it is possible to lock the window to a given prim by pressing the lock button:

When the window is locked, it targets the same prim, even as the current selection changes.

You can also create new Simulation Data Visualizer windows by pressing the new button:

Combined with the ability to lock windows, this enables you to monitor several prims at the same time by having multiple Simulation Data Visualizer windows open.

The contents of the individual windows changes based on what prim they are targeting.

Rigid Bodies

If the target is a rigid body, the window show the following information:

In the Velocity section, the ‘M’ field (yellow) shows the magnitude of the velocity vector, that is, the current speed.

Also notice that the window provides some other simulation information that may not be observable through the regular property windows, for example current world pose and accelerations.

Note

Accelerations are derived from comparing the velocity between two discrete data samples, yielding the mean acceleration of the time delta rather than the current. However, given the high sample rate, the difference is usually negligible.

You can also inspect the mass and inertia properties of the rigid body, which is particularly useful if you have not set them explicitly and want to know the generated values (given that these are static throughout the simulation, they are not accompanied by graphs).

Joints

When the window is targeting a joint prim, it provides information about the current offsets, velocities and accelerations in the local frame of the joint, that is, the values of the second attachment relative to the first:

The exact values shown change depending on the type of joint targeted.

Note

For joints, both velocities and accelerations are derived from comparing two discrete data samples, yielding the mean velocity and acceleration of the time delta. See the note above.

Residuals

In addition, the window visualizes solver residuals if the targeted prim has the Residuals API applied:

These values provide an error metric that indicates the solver convergence in the respective part of the simulation (the entire scene, an articulation root, or a single joint). When the values are zero, the solver converged perfectly.

Note

For joints, the RMS and Max values are always identical and do not appear as separate properties and graphs.

Inspecting and Exporting Graph Data

Whenever a type of sampled data contains multiple components (for example, XYZ coordinates), you can toggle each of the subcomponents by left-clicking their label button:

You may also right-click a component, which enables showing that specific component and hides all the others.

After the visualizer has plotted data in a graph, you can inspect the values at a specific data point by pressing down the left mouse button while hovering over it.

If you right click the graph, all the samples for that plot are be copied to the clipboard in comma separated values format (CSV) that allows you to paste it into other database programs.

Mouse Interaction

It may be helpful for testing or just good practice to interact with objects. You can push or grab objects by shift-clicking them in the viewport when the simulation is running. See the related settings and description in the Mouse Interaction Settings.

Property Window

In the Property Window (Window > Property), you can edit the physics properties of a prim, or you can add or remove simulation components (that is, USD APIs).

You can add physics components with the Add button that shows a list of components that you may add to the selected prim. The list is context-sensitive and only shows physics components that are compatible with the prim and other physics components that the prim already has. Adding a component populates the Property Window with a new rollout that shows the component’s properties (that is, API attributes).

You may remove a component from a prim by clicking the red X that is shown with the component rollout:

A hint for editing numeric values: Ctrl-click or double-click lets you edit the current value. If you want to reset values to their default, you can do so by clicking the blue square next to the value:

Tool Tips

You can hover over the name of a property to reveal a tooltip with further information about a parameter:

Physics Scene

The Physics Scene holds simulation settings such as gravity. To create a scene, select Create > Physics > Physics Scene. Then, you can configure the scene settings in its property window. For details on the parameters, refer to their tool tips.

Note

• The extension creates a temporary default scene if simulation objects are detected but a physics scene is missing. You may disable this behavior in the Physics Preferences.

• Often it makes sense to create physics objects such as a scene in their own USD layer.

Multiple Scenes

Multiple simulation scenes are supported. Each simulation actor, like a rigid body does have a simulationOwner relationship that defines where the actor is simulated. If empty, the first scene found during traversal is used.

Multiple simulationOwners can be set for an actor:

• For dynamic rigid body, the first simulationOwner rel owns that body and is simulated there as a dynamic body. The rest of the simulationOwners get a mirror of that body. That body is moved as a kinematic body.

• For static rigid body all bodies are mirrored into each simulationOwner scene.

Note

• Actors in different scenes do not interact with each other.

Physics Solver

The physics solver iteratively resolves constraints (including joints and contacts ) 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 bodies picking 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” because it allows for slightly improved convergence.

Solver Residual Reporting

The residual values (a measure for the convergence of the physics solver) 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. 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.

Scene Stepping

Physics stepping is determined by several variables. Scene is always stepped with a fixed time step. This is defined on a physics scene primitive - Time Steps Per Second (60 default). However the time provided by the update loop is variable (can be set to fixed in rendering properties). So physics is doing substeps to simulate the given variable delta time.

The number of steps is determined from the given variable delta time, the time steps per second on a physics scene and min frame rate setting defined in Physics settings (Window > Simulation > Settings). The required number of steps is equal to the delta time multiplied by the time steps per seconds. However, if the delta would be large, the number of steps would continue to grow. To prevent this, the min frame rate does limit the maximum number of steps. The maximum number of steps equals the time steps per second divided by the min frame rate. For example, if the time steps per second is 60, the min frame rate is 30, then the maximum number of steps is two and for any delta that is larger then 1/30 only two substeps are done, with a fixed 1/60 step.

Physics Materials

Materials defining properties of physics objects can be created with Create > Physics > Physics Material or added to an already existing Material prim through the Add > Physics menu.

A physics material can be assigned to a physics object in the Physics Materials on Selected Models rollout in the Property window, which binds the material to the prim with the ‘physics’ purpose. Physics materials follow the same resolution logic as render materials because they are both based on the same Material prim type.

You can define render and physics properties on the same Material prim (for example, to combine the visual and physical properties of rubber in a single material prim) and assign it in the “Materials on selected models” rollout.

Another option is to bind a material to the Physics Scene prim in the Physics default material rollout, and this material is used as a default when a physics object does not have a physics material bound to it after USD material resolve. Multiple physics material types (Rigid/Deformable/PBD Particle) can be added to the same material prim, so that the material bound to the Physics Scene can define defaults for all physics object types.

When parsing physics material properties of a prim the priority is as follows:

1. Material binding with a ‘physics’ purpose (physics material).

2. Material binding with no purpose (render material).

3. Material binding with a ‘physics’ purpose on the Physics Scene prim.

4. Default values of material properties.

Physics Settings

Physics Settings are per-stage settings saved in USD metadata. You can view and change them through Window > Simulation > Settings. The Physics Settings window is, by default, docked behind the Stage tab on the upper-right side.

Update

You can configure what data the simulation writes back to USD (analogous to editing operations).

Update to USD	Enables writing object transforms back to USD. Expert setting best left enabled.
Update velocities to USD.	Enables writing object velocities back to USD. If you do not need velocity information, you can disable the writeback to save some computational overhead.
Output Velocities in Local space.	Display velocities in local coordinate space. The simulation also expects user changes to velocities (like initial velocity of a body) to be in local or global space according to this setting.
Update Particles to USD.	Enables writing particle positions (and velocities, if update velocities is enabled) back to USD. Particle updates are otherwise disabled if particle ISO-surface mesh generation is enabled.

Simulator

Min Simulation Frame Rate

Sets the minimum simulation update rate in Hertz with respect to render-frame updates. In general, the Physics simulation runs in real (wall) time, so if rendering is slow, the simulation may take many steps at Time Steps Per Second to keep the Physics simulation state synchronized with wall time. This parameter limits how many steps the simulation may take to keep up synchronization. For example, if Min Simulation Frame Rate is 30Hz and the PhysicsScene Time Steps Per Second is 60 (Hz), the simulation takes at most two steps between render frame updates, no matter how long a frame render takes. This is a useful parameter when rendering a Physics scene to keep the simulation updates in lockstep with rendering: Just set Min Simulation Frame Rate equal to the Time Steps Per Second value.

Mouse Interaction

Mouse Interaction Enabled	Enables interaction with physics objects through shift-click if the simulation is running. For advanced physics-based authoring, refer to the Zero Gravity extension.
Mouse Grab	Toggles between grabbing behavior (enabled) and applying a push (disabled).
Mouse Grab Ignore Invisible	Toggles whether to affect Prims that are set to be invisible.
Mouse Grab With Force	Toggles between grabbing using a force (enabled) or using a D6 joint (disabled). Both the force and D6 are applied at the click (Raycast) location.
Mouse Grab Force Coefficient	Scales the force used for grabbing. The grabbing force is proportional to the mass of the grabbed object and multiplied with this parameter.
Mouse Push Acceleration	Scales the push-acceleration applied to the object.

Physics Preferences

Besides the physics scene and physics settings, the Physics tab in Edit > Preferences provides global simulation-related settings.

General

Create Temporary Default PhysicsScene When Needed	Controls whether a scene is auto-created when you press Play and simulation objects are present but no PhysicsScene was added to the stage.
Reset simulation on stop	If enabled, the state (that is, transforms, velocities) of the simulation objects is reset to the initial state before Play was pressed.
Use Active CUDA Context	If enabled, the PhysX simulation uses the currently active CUDA context for its GPU computations. If disabled, a new context is created for the simulation.
Reset Physics Preferences	Use this button to reset the values of the Physics preferences here, and the debug-visualization.

Backward Compatibility

Backward Compatibility Check on Scene Open	Configures the behavior of the physics USD backward compatibility module: To open a scene with a deprecated USD schema, the extension can ignore it, print out a warning to console, show a visual prompt to upgrade, or upgrade the scene automatically without prompting.
Run Backwards Compatibility On Current Stage	Manually trigger a backwards compatibility check and update on current stage.
Run Backwards Compatibility On Folder	Manually trigger a backwards compatibility check and update on a folder.

Simulator

Num Simulation Threads	The number of simulation threads controls how many background threads are spawned and reserved for simulation.
Use PhysX CPU Dispatcher	Use the internal PhysX task scheduler instead of the default one. Can be more efficient for some scenes.
Expose PhysX SDK Profiler Data	Adds PhysX SDK profiling zones to the Kit profiler.
Release Physics Cooked Data	Deletes cooked data (for example, pre-optimized simulation data for collision meshes) for all prims on the stage from USD, that is, deletes the corresponding API and attributes holding the data. Forces re-cooking of the data (if the local mesh cache is cleared as well).

Local Mesh Cache

Enable, set the size of, and release the local (disk) mesh cache that stores results from collision mesh approximations and Physics data cooking for reuse with identical geometry.

Units

USD supports scaling of units through layer metadata that you may edit in the layer properties, see below. The default unit scaling for new stages can be set in the Stage tab of the Preferences Window.

The Physics extension scales default or auto-computed values by this metadata. For example, if Meters Per Unit is 0.01 (i.e. 1cm per unit), as you would set for assets that were authored at a centimeter-scale, the Physics extension sets the gravity magnitude of a newly created scene to 981.0 cm / s². Any property value that you edit is assumed to be in the scale of the layer that it is authored in (see limitations in the note).

Note

• Time is never scaled and is always in seconds (Time Codes Per Second is not considered for physics simulation).

• Automatic reconciliation of unit-scales between different layers is currently not supported, so you must ensure that all layers are authored at the same scale.

• To run simulations in engineering SI units (except angles), set all scaling to 1.0. Related, you may change the stage up-axis in the layer metadata from graphics-default Y-up to Z-up, that is more common in engineering.

• Angles are represented in degrees and cannot be set to radians. All physics parameters that refer to rotation are in degrees as well. For example an angular drive of a revolute joint has its stiffness defined in units of torque/degrees.

Physics Debug Window

The Window > Simulation > Debug window is the first place to look when physics simulation is generating unexpected results.

Simulation Control

In addition to running and stopping, you can Step the simulation one time step at a time, so you can inspect problems that happen very quickly.

Simulation Overrides

You can manually perform updates from USD or release simulation objects, and override the CPU/GPU and solver settings of the PhysicsScene.

Simulation Debug Visualization

You can enable and configure a low-level visualizer that renders directly based on the PhysX engine’s state, which is useful if for some reason the simulation is not in sync with USD. When you check the Enabled box, the different elements to visualize are presented. Data is only visualized when the simulation is running. The Scale field can be used to adjust the length of some lines and arrows.

Some data, like contact points, is generated at the start of an update and bodies are moved at the end of the update. Shapes are also drawn using their state at the start of an update so that they line up with contact points. For this reason, the visualization display may appear to lag one frame behind the graphics rendering.

Deformable Debug Visualization

Configure the options for deformable bodies.

Collision Mesh Debug Visualization

In addition to the wireframe debug visualization available in the viewport show/hide menu, you can visualize the collision-mesh approximations using solid render meshes. You may also inspect a convex decomposition using the explode-view distance.

PVD

Enable and configure PVD data logging by the PhysX PVD logger, which can be helpful when inspecting the PhysX simulation objects created from USD data.

Sleeping

Sleeping is a mechanism in PhysX to save on computational resources when dynamic physics objects (for example, rigid or deformable 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 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

• 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, for example, 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.

Note

There is a subtle connection between sleeping and effective solver iterations (for example, position and velocity iteration settings). In a GPU simulation, it is computationally efficient to apply the same number of iterations to all objects in the scene. This number is equal to the maximal iteration setting over all physics objects in the scene that are not asleep. This is especially the case for deformable bodies whose dynamics can be affected when the effective iteration count changes. For example, if you have two deformable bodies with 20 and 40 iterations each in a scene and both are awake, the solver applies 40 iterations to both. However, if the body with 40 iterations goes to sleep, the other body will only have 20 iterations applied to it, which may change its behavior.

PhysX Flatcache (also known as Fabric)

The Flatcache feature enables bypassing USD to communicate PhysX simulation data to the rendering engine, which is more efficient and results in higher combined simulation and rendering performance.

The feature only supports rigid bodies (excluding point instancer rigid bodies). You can enable and test the Flatcache feature as follows:

1. Enable the extension omni.physx.flatcache.

2. Enable FPS display in the viewport show/hide menu (eye) HUD Stats.

3. Compare FPS in a scene with many rigid bodies (forexample, ~1k) with and without Flatcache enabled.

Note

• When the extension is enabled, a small window is displayed showing what the output of a simulation is (USD/Fabric).

• Using Fabric means that the data are not available in USD. This causes USD based functionality to not work. For example, debug visualization of physics colliders won’t work anymore, because the transformations are not synchronized.

• Using a Python script to update and get the USD state, won’t work because USD does not have current transformation information.

• If scene graph instancing is used together with Fabric, support for that in OmniHydra has to be enabled. Enable omni.hydra.ui and enable the scene graph instancing using omni.hydra. Reload your stage.