isaaclab_ov.physics

OvPhysX physics manager implementation.

Classes

OvPhysxManager	Manages an ovphysx-backed physics simulation lifecycle.
OvPhysxCfg	Configuration for the ovphysx physics manager.
OvPhysxBackendCfg	Native runtime construction settings, separate from physics scene policy.

Physics Manager

class isaaclab_ov.physics.OvPhysxManager

Bases: PhysicsManager

Manages an ovphysx-backed physics simulation lifecycle.

Unlike PhysxManager, this manager does not depend on a host Kit or Carbonite runtime, or on the Omniverse timeline. It drives the simulation through the OVPhysX Python wheel and its packaged runtime.

Lifecycle: initialize() -> reset() -> step() (repeated) -> close()

Methods:

__init__()
get_dt()	Get the physics timestep.
require_full_stage()	Load every authored environment during the next stage warmup.
fix_articulation_root(articulation_prim[, stage])	Fix and normalize an articulation root for the OVPhysX parser.
setup_deformable_body(prim, deformable_type, ...)	Apply the OmniPhysics deformable anchor APIs, rest state, and bind pose.
register_clone(source, targets[, ...])	Queue clones at the given world positions with identity rotations.
initialize(sim_context)	Initialize the physics manager with simulation context.
reset([soft])	Reset physics simulation.
forward()	Evaluate and publish state changes made without stepping physics.
pre_render()	Finish native kinematics before SDP publishes manually written joint poses.
update_kinematics()	Update dirty articulation kinematics without publishing or rendering.
step()	Step the simulation by one physics timestep.
close()	Release ovphysx resources and clean up.
get_physx_instance()	Return the underlying ovphysx.PhysX instance (or None if not yet created).
get_gravity()	Return the last successfully applied world-frame gravity vector [m/s^2].
set_gravity(gravity)	Set the scene-wide gravity vector through OvStage [m/s^2].
get_scene_data_backend()	Return the SDP backend created during initialization; native bindings are acquired lazily.
after_visualizers_render()	Hook after visualizers have stepped during render().
clear_callbacks()	Remove all registered callbacks.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_device()	Get the physics simulation device.
get_physics_dt()	Get the physics timestep in seconds.
get_physics_sim_view()	Get the physics simulation view.
get_simulation_time()	Get the current simulation time in seconds.
handles_decimation()	True when step() executes the full decimation loop internally.
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
register_callback(callback, event[, order, ...])	Register a callback for a physics event.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
set_decimation(decimation)	Inform the physics backend how many substeps the environment runs per policy step.
stop()	Stop physics simulation.
video_capture_backend()	Return the video capture backend identifier for this physics manager.
wait_for_playing()	Block until the timeline is playing.

Attributes:

backend	Native resource borrowed from the context registry after warmup.
backend_name	Backend implementation key used by asset and sensor factories.
supports_anim_recording	Whether this backend can service --anim_recording_enabled (OVD Recorder).
views	Backend views by prim path expression, shared by the consumers of this manager.

Classes:

clone_context_type

alias of OvPhysxReplicateContext

__init__()

backend: OvPhysxBackend | None

Native resource borrowed from the context registry after warmup.

backend_name: ClassVar[str] = 'ovphysx'

Backend implementation key used by asset and sensor factories.

clone_context_type

alias of OvPhysxReplicateContext

get_dt() → float

Get the physics timestep. Alias for get_physics_dt().

require_full_stage() → None

Load every authored environment during the next stage warmup.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Fix and normalize an articulation root for the OVPhysX parser.

classmethod setup_deformable_body(prim: Any, deformable_type: str, sim_mesh_prim: Any, vis_mesh_prim: Any) → None

Apply the OmniPhysics deformable anchor APIs, rest state, and bind pose.

OVPhysX reads the same OmniPhysics deformable schemas as the Kit PhysX backend, so both backends share one authoring path.

register_clone(source: str, targets: list[str], parent_positions: list[tuple[float, float, float]] | None = None) → None

Queue clones at the given world positions with identity rotations.

Parameters:

• source – Source prim path (env_0 articulation root).

• targets – Target prim paths for env_1..N.

• parent_positions – Final world positions (x, y, z) [m] for whole-environment target roots. Each position uses an identity rotation.

initialize(sim_context: SimulationContext) → None

Initialize the physics manager with simulation context.

This stores the config and device but does not load the USD stage yet – the stage may not be fully populated at this point. The actual load happens lazily in reset().

The simulation registry retains its native resource across reinitialization.

reset(soft: bool = False) → None

Reset physics simulation.

On the first (non-soft) reset the method: - Serializes the current USD stage in memory - Creates the ovphysx.PhysX instance - Populates and attaches an OVStage - Warms up GPU buffers (if on CUDA) - Dispatches PHYSICS_READY

A forced re-warm dispatches STOP before replacing the attached stage so listeners discard stale bindings.

forward() → None

Evaluate and publish state changes made without stepping physics.

pre_render() → None

Finish native kinematics before SDP publishes manually written joint poses.

update_kinematics() → None

Update dirty articulation kinematics without publishing or rendering.

step() → None

Step the simulation by one physics timestep.

close() → None

Release ovphysx resources and clean up.

get_physx_instance() → Any

Return the underlying ovphysx.PhysX instance (or None if not yet created).

get_gravity() → tuple[float, float, float]

Return the last successfully applied world-frame gravity vector [m/s^2].

Mirrors PhysX’s SimulationView.get_gravity() so backend-agnostic sensor code can read gravity from their owning manager. The value tracks set_gravity(), falling back to the simulation cfg until the first live update.

Raises:

RuntimeError – If no simulation is active. Call initialize() first.

set_gravity(gravity: tuple[float, float, float]) → None

Set the scene-wide gravity vector through OvStage [m/s^2].

The OvPhysX runtime accepts live scene changes only as sealed OvStage control updates. This method authors the scene’s gravity direction and magnitude at the next control ordinal, seals it, and applies that single ordinal to the running simulation.

Parameters:

gravity – World-frame gravity vector [m/s^2].

Raises:

• RuntimeError – If the OVPhysX simulation has not been initialized.

• ValueError – If gravity does not contain three finite values.

get_scene_data_backend() → SceneDataBackend

Return the SDP backend created during initialization; native bindings are acquired lazily.

after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

clear_callbacks() → None

Remove all registered callbacks.

IDs remain unique for this manager’s lifetime. Otherwise a retained handle could deregister a new callback after a close and reinitialization of the same manager.

deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

get_device() → str

Get the physics simulation device.

get_physics_dt() → float

Get the physics timestep in seconds.

get_physics_sim_view() → Any

Get the physics simulation view. Override in subclasses.

get_simulation_time() → float

Get the current simulation time in seconds.

handles_decimation() → bool

True when step() executes the full decimation loop internally.

When this returns True the environment should call step() once per policy step instead of looping decimation times.

pause() → None

Pause physics simulation. Default is no-op.

play() → None

Start or resume physics simulation. Default is no-op.

register_callback(callback: Callable[[Any], None], event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback for a physics event.

Parameters:

• callback – The callback function. Receives event payload as argument.

• event – The event to listen for.

• order – Priority order (lower = earlier). Default 0.

• name – Optional name for debugging.

• wrap_weak_ref – If True, wrap bound methods with weak references to prevent preventing garbage collection. Default True.

Returns:

CallbackHandle that can be used to deregister the callback.

Example

>>> def on_physics_ready(payload):
...     print("Physics is ready!")
>>> handle = sim.backend_manager.register_callback(on_physics_ready, PhysicsEvent.PHYSICS_READY)
>>> # Later, to remove:
>>> handle.deregister()

static safe_callback_invoke(fn: Callable, *args, backend_manager: PhysicsManager | None = None, physics_manager: PhysicsManager | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to backend_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Parameters:

• fn – Callback to invoke.

• *args – Positional arguments for fn.

• backend_manager – Manager that stores swallowed exceptions, if any.

• physics_manager – Deprecated alias of backend_manager.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

set_decimation(decimation: int) → None

Inform the physics backend how many substeps the environment runs per policy step.

Backends that can fold the full decimation loop into a single step() call (e.g. Newton with all-graphable actuators) use this to size their internal loop / CUDA graph. The default implementation is a no-op.

Parameters:

decimation – Number of physics steps per environment step.

stop() → None

Stop physics simulation. Default is no-op.

supports_anim_recording: ClassVar[bool] = False

Whether this backend can service --anim_recording_enabled (OVD Recorder).

Overridden by backends that implement the recorder (currently PhysX-only).

video_capture_backend() → str | None

Return the video capture backend identifier for this physics manager.

Used by VideoRecorder to select how perspective video frames are captured when no visualizer is active.

Returns:

"kit" for backends that use Kit/Replicator (e.g. PhysxManager), "newton_gl" for backends that use a headless Newton GL viewer (e.g. NewtonManager), or None if the backend does not support perspective video capture.

wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

views: dict[str, Any]

Backend views by prim path expression, shared by the consumers of this manager.

Physics Configuration

class isaaclab_ov.physics.OvPhysxCfg

Bases: PhysicsCfg

Configuration for the ovphysx physics manager.

PhysX scene-level parameters (solver iterations, GPU buffer sizes, etc.) are read from the USD PhysicsScene prim. Only ovphysx-specific settings that are not captured in USD live here.

Attributes:

class_type	The physics manager class to use.
legacy_joint_friction_replacements	Explicit OVPhysX 0.7 migration values for legacy USD joint friction.
cooked_collider_cache_dir	Directory for the OVPhysX cooked-collider cache, defaulting to a per-user directory under the system temporary directory.
enable_enhanced_determinism	Enable/disable improved determinism at the expense of performance.
deterministic	Whether to request reproducible physics from the backend.
enable_external_forces_every_iteration	Enable/disable external forces every position iteration in the TGS solver.
gpu_max_rigid_contact_count	Size of the GPU rigid-body contact buffer.
gpu_max_rigid_patch_count	Size of the GPU rigid-body patch buffer.
gpu_found_lost_pairs_capacity	Capacity for GPU found/lost broadphase pairs.
gpu_found_lost_aggregate_pairs_capacity	Capacity for GPU found/lost aggregate broadphase pairs.
gpu_total_aggregate_pairs_capacity	Capacity for total GPU aggregate broadphase pairs.
gpu_collision_stack_size	GPU collision stack size in bytes.

class_type: type[PhysicsManager] | Any

The physics manager class to use. Must be set by subclasses.

legacy_joint_friction_replacements: dict[str, tuple[float, float, float]]

Explicit OVPhysX 0.7 migration values for legacy USD joint friction.

Keys are regular expressions matched against the complete joint name. Values are (static effort, dynamic effort, viscous coefficient) in SI units: N or N*m, and N*s/m or N*m*s/rad. These are calibrated replacement efforts, not converted legacy coefficients. Static effort must be at least dynamic effort.

Only the private OVPhysX 0.7 export is changed. Older runtimes ignore this mapping. Authored modern friction takes precedence. Unmatched nonzero legacy friction still raises an error; this mapping does not provide a global fallback for unknown assets.

cooked_collider_cache_dir: str | None

Directory for the OVPhysX cooked-collider cache, defaulting to a per-user directory under the system temporary directory. Set to None to use the runtime default.

The datastore is created once per process, so the first OVPhysX construction fixes the location and a later config does not relocate it. The runtime garbage collects the cache against a disk budget; deleting the directory reclaims the space immediately, and a system temporary directory may also be purged between boots.

enable_enhanced_determinism: bool

Enable/disable improved determinism at the expense of performance. Defaults to False.

For more information on PhysX determinism, please check here.

deterministic: bool

Whether to request reproducible physics from the backend. Defaults to False.

This is the backend-agnostic form of the request, set by the --deterministic command-line flag. Each physics manager translates it into its own settings when the simulation starts, and raises when its configuration cannot provide the guarantee. A backend-specific determinism attribute set explicitly, such as deterministic_mode, is the more specific instruction and takes precedence.

Deterministic execution can increase memory use and reduce simulation performance.

enable_external_forces_every_iteration: bool

Enable/disable external forces every position iteration in the TGS solver. Default is True.

This matches the PhysX backend default and can improve the accuracy of velocity updates. Set to False explicitly to preserve the previous OvPhysX default behavior. Changing this setting can affect simulated velocities and contact forces.

gpu_max_rigid_contact_count: int

Size of the GPU rigid-body contact buffer.

gpu_max_rigid_patch_count: int

Size of the GPU rigid-body patch buffer.

gpu_found_lost_pairs_capacity: int

Capacity for GPU found/lost broadphase pairs.

gpu_found_lost_aggregate_pairs_capacity: int

Capacity for GPU found/lost aggregate broadphase pairs.

gpu_total_aggregate_pairs_capacity: int

Capacity for total GPU aggregate broadphase pairs.

gpu_collision_stack_size: int

GPU collision stack size in bytes.

class isaaclab_ov.physics.OvPhysxBackendCfg

Bases: BackendCfg

Native runtime construction settings, separate from physics scene policy.

Attributes:

class_type	Constructor called through instantiate(cfg); the returned resource must implement close().
device	cpu or cuda:<index>.
cooked_collider_cache_dir	Cooked-collider cache location, fixed by the first runtime created in the process.

class_type: type[OvPhysxBackend] | str

Constructor called through instantiate(cfg); the returned resource must implement close().

device: str

cpu or cuda:<index>.

Type:

Normalized device

cooked_collider_cache_dir: str | None

Cooked-collider cache location, fixed by the first runtime created in the process.