unisim.backend.genesis.materialization

Cold-path scene materialization for the independent genesis backend.

Genesis 1.3.3 drops three MJCF features UniLab relies on, as measured in the Genesis 1.3.3 feasibility audit (#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_scene(deps, *, sim_dt, gravity, ...)

Construct the unbuilt Genesis scene with explicit global options.

destroy_genesis_session(deps)

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

genesis_balanced_variant_mapping(...)

Return Genesis 1.3.3's documented heterogeneous env/variant mapping.

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

Initialize the process-wide Genesis session exactly once.

prepare_genesis_portable_sources(mujoco, ...)

Normalize common portable sources into independent Genesis MJCF files.

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.

scan_genesis_portable_composed_metadata(...)

Scan composed sensors and freeze their complete identity across variants.

validate_genesis_portable_sensor_plans(...)

Bind the bounded portable source and fragment sensor subsets.

validate_genesis_variant_assignment(...)

Require the exact mapping Genesis will materialize natively.

Classes

GenesisModelMetadata

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

GenesisPortableEntitySource

Independent normalized MJCF sources for one public entity.

GenesisPortableSources

Cold-path Genesis inputs derived from the common portable compiler.

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 and portable body frame fragment sensors. Contact sensors additionally retain both final geom names and whether the common fragment form is exact pair netforce, so portable validation can bind them without source-model array indices.

Parameters:
name: str
kind: str
dim: int
body_name: str
object_name: str
reference_type: int
reference_id: int
site_pos: tuple[float, ...] | None
site_quat: tuple[float, ...] | None
contact_geom1_name: str | None = None
contact_geom2_name: str | None = None
contact_netforce: bool = False
object_kind: str = 'site'
__init__(name, kind, dim, body_name, object_name, reference_type, reference_id, site_pos, site_quat, contact_geom1_name=None, contact_geom2_name=None, contact_netforce=False, object_kind='site')
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, ...]
geom_names: tuple[str, ...]
geom_body_names: tuple[str, ...]
geom_types: tuple[int, ...]
geom_sizes: ndarray
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
default_qvel: ndarray
default_ctrl: ndarray
joint_range: ndarray | None
dof_armature: ndarray
gravity: ndarray
body_mass: ndarray
body_ipos: ndarray
body_inertia: ndarray
body_iquat: ndarray
body_pos: ndarray
body_quat: 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, geom_names, geom_body_names, geom_types, geom_sizes, actuator_names, actuator_joint_names, actuator_ctrl_range, actuator_kp, actuator_kv, keyframe_qpos, default_qpos, default_qvel, default_ctrl, joint_range, dof_armature, gravity, body_mass, body_ipos, body_inertia, body_iquat, body_pos, body_quat, sensor_plans)
Parameters:
class unisim.backend.genesis.materialization.GenesisPortableEntitySource[source]

Bases: object

Independent normalized MJCF sources for one public entity.

Parameters:
name: str
model_files: tuple[str, ...]
metadata: tuple[GenesisModelMetadata, ...]
__init__(name, model_files, metadata)
Parameters:
class unisim.backend.genesis.materialization.GenesisPortableSources[source]

Bases: object

Cold-path Genesis inputs derived from the common portable compiler.

Parameters:
entities: tuple[GenesisPortableEntitySource, ...]
cleanup_handle: Any
__init__(entities, cleanup_handle)
Parameters:
unisim.backend.genesis.materialization.genesis_balanced_variant_mapping(num_variants, num_envs)[source]

Return Genesis 1.3.3’s documented heterogeneous env/variant mapping.

Genesis dispatches variants in contiguous balanced blocks (the first remainder-sized block gets one extra environment). This local owner-side implementation deliberately does not call Genesis’ private solver helper; construction accepts an assignment only when it is exactly this mapping.

Parameters:

  • num_variants (int)

  • num_envs (int)

Return type:

ndarray

unisim.backend.genesis.materialization.validate_genesis_variant_assignment(assignment, num_variants)[source]

Require the exact mapping Genesis will materialize natively.

Parameters:
Return type:

ndarray

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

Normalize common portable sources into independent Genesis MJCF files.

The common compiler remains the sole layout, identity, and source relationship authority. This owner adapter only serializes each already normalized MjSpec and scans the resulting source for native binding.

Parameters:

  • mujoco (Any)

  • scene (SceneCfg)

  • layout (Any)

Return type:

GenesisPortableSources

unisim.backend.genesis.materialization.validate_genesis_portable_sensor_plans(mujoco, sources, layout, composed_plans)[source]

Bind the bounded portable source and fragment sensor subsets.

Genesis does not import MJCF sensors. Portable support is deliberately limited to entity-owned site FramePos, FrameQuat, Gyro, Velocimeter and identity-orientation Accelerometer declarations whose complete semantic identity is identical in every source variant. The returned plans use qualified public sensor/body names; the backend computes pose/motion values from audited native link state and accelerometer values from a clean public native IMU.

Scene-level fragments are limited further to world-referenced qualified-site and qualified-body FramePos/FrameQuat declarations, world-referenced qualified-site/body FrameLinVel/FrameAngVel declarations, and exact cross-entity geom-pair found/netforce contact declarations. The common compiler appends them after all entity-owned source sensors, so the composed prefix must match the independently audited source plans exactly.

Parameters:
Return type:

tuple[GenesisSensorPlan, ...]

unisim.backend.genesis.materialization.scan_genesis_portable_composed_metadata(mujoco, composed)[source]

Scan composed sensors and freeze their complete identity across variants.

Parameters:
Return type:

GenesisModelMetadata

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_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, *, allow_cross_entity_contacts=False)[source]

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

Parameters:

  • mujoco (Any)

  • scene (SceneCfg)

  • allow_cross_entity_contacts (bool)

Return type:

GenesisModelMetadata