unisim.backend.genesis.materialization

Cold-path scene materialization for the independent genesis backend.

Genesis 1.3.3 drops three MJCF features UniLab relies on (measured in scripts/tools/genesis_feasibility/REPORT.md #1372 §3): <keyframe>, the global <option> block, and the whole <sensor> block. This module compensates on the cold path exactly as the report prescribes: keyframe and sensor metadata are scanned once with the mujoco package (the isaacgym parent-process metadata-scan pattern) and cached — hot paths never parse XML; global options arrive as explicit owner fields; and gs.init host-side effects (torch default device/dtype and RNG) are contained by preserve_torch_globals() plus the one-session-per-process guard.

Functions

build_genesis_scene(deps, *, sim_dt, ...)

Construct the unbuilt Genesis scene with explicit global options.

destroy_genesis_session(deps)

Tear down the process-wide session; re-initialization stays forbidden.

init_genesis_session(deps, *[, device_id, ...])

Initialize the process-wide Genesis session exactly once.

preserve_torch_globals(torch)

Snapshot torch global defaults and restore them after gs.init.

scan_genesis_model_metadata(mujoco, scene)

Resolve the scene and scan MJCF metadata with the mujoco package.

Classes

GenesisModelMetadata

MJCF metadata scanned once on the cold path (never on hot paths).

GenesisSensorPlan

One MJCF sensor mapped onto a Genesis-readable equivalent.
class unisim.backend.genesis.materialization.GenesisSensorPlan[source]

Bases: object

One MJCF sensor mapped onto a Genesis-readable equivalent.

body_name is the owning link for site sensors and the robot-side geom body for contact sensors. site_pos/site_quat (wxyz) are the local site frame in the body frame; both are None for contact sensors.

Parameters:
name: str
kind: str
dim: int
body_name: str
site_pos: tuple[float, ...] | None
site_quat: tuple[float, ...] | None
__init__(name, kind, dim, body_name, site_pos, site_quat)
Parameters:
class unisim.backend.genesis.materialization.GenesisModelMetadata[source]

Bases: object

MJCF metadata scanned once on the cold path (never on hot paths).

Parameters:
source_model_file: str
cleanup_handle: Any | None
nq: int
nv: int
nbody: int
root_qpos_dim: int
root_qvel_dim: int
joint_names: tuple[str, ...]
joint_qpos_adrs: tuple[int, ...]
joint_dof_adrs: tuple[int, ...]
body_names: tuple[str, ...]
actuator_names: tuple[str, ...]
actuator_joint_names: tuple[str, ...]
actuator_ctrl_range: ndarray
actuator_kp: ndarray
actuator_kv: ndarray
keyframe_qpos: tuple[tuple[str, ndarray], ...]
default_qpos: ndarray
joint_range: ndarray | None
dof_armature: ndarray
gravity: ndarray
body_mass: ndarray
body_ipos: ndarray
sensor_plans: tuple[GenesisSensorPlan, ...]
__init__(source_model_file, cleanup_handle, nq, nv, nbody, root_qpos_dim, root_qvel_dim, joint_names, joint_qpos_adrs, joint_dof_adrs, body_names, actuator_names, actuator_joint_names, actuator_ctrl_range, actuator_kp, actuator_kv, keyframe_qpos, default_qpos, joint_range, dof_armature, gravity, body_mass, body_ipos, sensor_plans)
Parameters:
unisim.backend.genesis.materialization.preserve_torch_globals(torch)[source]

Snapshot torch global defaults and restore them after gs.init.

gs.init mutates the host process: it forces torch.set_default_device("cuda:0") on the GPU lane, and passing seed= would reseed the global RNG (REPORT #1372 §3.5 [10]). The adapter never passes a seed and restores default device/dtype plus the torch RNG state so the training process observes no pollution (REPORT #1372 §5.8).

Parameters:

torch (Any)

Return type:

Iterator[None]

unisim.backend.genesis.materialization.init_genesis_session(deps, *, device_id=None, logging_level='warning')[source]

Initialize the process-wide Genesis session exactly once.

Repeated init -> destroy cycles are functional but leak 200-450 MB of host RSS per cycle (REPORT #1372 §3.5 [9a]), so a long-lived training process gets exactly one session. Multiple GenesisBackend instances share the live session (multi-scene coexistence is measured OK, REPORT [9b]); after destroy_genesis_session() any further construction fails closed with a clear error.

Parameters:
Return type:

None

unisim.backend.genesis.materialization.destroy_genesis_session(deps)[source]

Tear down the process-wide session; re-initialization stays forbidden.

Parameters:

deps (Any)

Return type:

None

unisim.backend.genesis.materialization.build_genesis_scene(deps, *, sim_dt, gravity, integrator, constraint_solver, friction_cone, solver_iterations)[source]

Construct the unbuilt Genesis scene with explicit global options.

Parameters:
Return type:

Any

unisim.backend.genesis.materialization.scan_genesis_model_metadata(mujoco, scene)[source]

Resolve the scene and scan MJCF metadata with the mujoco package.

Parameters:

  • mujoco (Any)

  • scene (SceneCfg)

Return type:

GenesisModelMetadata