unisim.backend.isaacgym.backend¶
IsaacGym specialization of the shared MJCF subprocess host adapter.
IsaacGym Preview 4 runs in an external Python 3.8 process. The shared owner layer supplies pipe/shm lifecycle, MJCF metadata, selected reset, NumPy state views, and native-render command plumbing; this module only selects the IsaacGym runtime and worker entrypoint.
Classes
NumPy-facing |
|
Opaque metadata returned by the IsaacGym worker handshake. |
Exceptions
Raised when the external IsaacGym worker fails. |
- class unisim.backend.isaacgym.backend.IsaacGymBackend[source]¶
Bases:
MjcfSubprocessBackendNumPy-facing
SimBackendclient for the IsaacGym worker.- get_dr_capabilities()[source]¶
Advertise mapped-scene reset DR and interval wrenches.
The model-file raw-MJCF path declares only the selected-reset PD-gain bridge; mapped entity scenes declare the reset terms the worker writes and reads back natively. Per-env
gravity/dof_dampinghave no PhysX channel (sim-wide parameter, drive-only joint damping) and the multi-root scene has no singlebasetarget, so those terms stay unsupported. The host-plane sets covertorch.cpupayloads; the device plane (torch.cuda) carries the CUDA IPC PD-gain lane only.- Return type:
DomainRandomizationCapabilities
- get_reset_term_default(term)[source]¶
Return per-environment variant-assigned mapped reset defaults.
- apply_interval_randomization(plan)[source]¶
Apply a scheduled interval randomization plan.
Generic dispatch: each op yielded by
plan.iter_ops()is validated against the builtin term specs (custom terms pass through) and routed to the backend-owned handler table returned by_interval_term_handlers(). Op payloads are torch-first: Torch tensors orTensorIntervalPayloadvalues produced by the caller; host adapters convert tensors at their private boundary throughunisim.dr._host, and a missing producer-sampled payload fails closed. A term without a handler fails closed withNotImplementedErrornaming the backend class and the term. Backends that need per-plan prologue/epilogue semantics (for example clearing staged external forces before the ops accumulate) keep a thin override that calls this base implementation.- Parameters:
plan (
IntervalRandomizationPlan)- Return type:
- apply_body_force(body_ids, force, torque=None)[source]¶
Stage a world-frame wrench for the next mapped-scene step.
The force acts at each target body’s center of mass and the optional torque is about that center. Repeated submissions accumulate until the next successful step consumes them.
- get_playback_model(env_index=None)[source]¶
Return the playback model source used by detached MuJoCo replay.
Whole-MJCF (raw) scenes replay through their construction source and mapped entity scenes through the composed MJCF; fixed-variant scenes follow the Drake contract — an explicit
env_indexis required and the row’s assigned variant source is returned.
- get_play_capabilities()[source]¶
Return backend-native play/render capabilities.
- Return type:
PlayCapabilities
- get_physics_state_layout()[source]¶
Return the snapshot layout; unsupported scene shapes fail closed.
- Return type:
PhysicsStateLayout
- get_physics_state()[source]¶
Assemble contract
[time, qpos, qvel, (mocap)?]rows in MuJoCo layout.The worker owns the physics state; one
GET_PHYSICS_STATErequest returns the canonical[qpos, qvel, (mocap_pos, mocap_quat)?]block for every environment in a single reply frame (no out-of-band channel and no per-env round trips). The leading time column is the host-side per-env accumulator because the worker protocol carries no simulation clock.- Return type:
- get_playback_mocap_state(env_index=0)[source]¶
Return copied
(mocap_pos, mocap_quat)rows for detached playback.
- reset_entities(request)[source]¶
Validate the complete selected-entity request, then commit it once.
Validation failure leaves all state unchanged. A native partial commit failure must fault the backend unless the adapter can actually roll back. Unselected entities/environments and fixed identity remain unchanged.
- Parameters:
request (
SceneResetRequest)- Return type:
- get_tensor_execution()[source]¶
Declare the optional tensor lifecycle without discovering SDKs.
- Return type:
TensorExecution
- get_tensor_capabilities()[source]¶
Return fail-closed tensor methods and negotiable state fields.
- Return type:
TensorLifecycleCapabilities
- get_state_views(fields=None, device=None)[source]¶
Return backend-owned state through the declared tensor lifecycle.
Tensor views are Torch tensors. Returned values are logically read-only and mutation is undefined.
DEVICE_RESIDENTadapters return stable live views on the backend’s exact accelerator device;device=Noneselects that device and any other device is rejected.HOST_BRIDGEadapters return explicit copies from authoritative host state;device=Noneselects host CPU and callers pass an explicit accelerator device for H2D copies. Unlike the removed 1.x NumPy snapshot API, successful tensor adapters do not return NumPy arrays. Consume the declared tensor execution mode rather than probing the array implementation.
- get_public_state_widths()[source]¶
Return the synthetic raw-MJCF public tensor state widths.
- Return type:
PublicStateWidths
- get_sensor_view(name, device=None)[source]¶
Return one named sensor view on the declared tensor lifecycle.
- step_tensor(ctrl, nsteps=1)[source]¶
Advance physics from a backend-declared accelerator control tensor.
ctrlis a contiguous float32 Torch tensor with shape(num_envs, num_actuators), lives on the adapter-required device, and must be finite. The method consumes it before synchronizing and returning.
- set_state_tensor(env_indices, qpos, qvel, randomization=None)[source]¶
Set selected state through the adapter-declared tensor lifecycle.
env_indicesis a contiguous one-dimensional int64 Torch tensor with unique values in[0, num_envs);qposandqvelare contiguous float32 tensors with shapes(len(env_indices), nq)and(len(env_indices), nv). All three share one adapter-accepted device and must be finite. Adapters may use a bounded synchronization for fail-closed row validation.DEVICE_RESIDENTadapters otherwise avoid a host detour;HOST_BRIDGEadapters make their explicit accelerator-to-host boundary measurable before CPU state is updated. Inputs are consumed before return.randomizationis the unified torch-firstTensorResetRandomizationPayload: every populated field is a dense selected-row Torch tensor table. Tensors ontorch.cpuform the host plane, checked againstDomainRandomizationCapabilities.supported_reset_terms; tensors on any other device form the device plane, checked againstsupported_device_reset_terms(empty by default, so undeclared device support fails closed naming the term). Non-delta terms hold final absolute values applied as selected-row in-place scatters;base_mass_deltaandbase_com_offsethold deltas merged with the adapter baseline. Host adapters convert tensors at their private NumPy boundary throughunisim.dr._host.
- set_state_tensor_mask(reset_mask, qpos, qvel, randomization=None, *, full_refresh=False)[source]¶
Commit full-width state through a backend-owned mask projection.