sim2sim

# X1 sim2sim Use this sub-skill to validate an exported X1 DH stand policy against the bundled MuJoCo model, or to prepare the guarded native `sim2sim.py` handoff. The supported task is **`x1_dh_stand`**. Start with [workflows](references/workflows.md), then use [model-and-asset-validation](references/model-and-asset-validation.md) for shape/XML checks and [troubleshooting](references/troubleshooting.md) for fail-closed diagnosis. ## Hard backend and safety boundary The full native script is currently **`BLOCKED_REQUIRED_BACKEND`** until NVIDIA Isaac Gym Preview 4 is installed and verified. Although it uses MuJoCo, it imports `humanoid.envs` before parsing arguments; that import chain requires Isaac Gym. A working modern MuJoCo install alone does not make the native workflow runnable. The native path also requires the repository's documented Python 3.8 / PyTorch 1.13.1 + CUDA 11.7 stack, `mujoco==2.3.6`, `mujoco-python-viewer`, `pygame`, an X1 checkout with its meshes, and a valid exported policy. Until that gate is cleared, perform only isolated XML, URDF, filesystem, JIT container, and metadata checks. Run the bundled `scripts/sim2sim_preflight.py`; it never imports `humanoid` or Isaac Gym, opens a viewer, initializes pygame, loads TorchScript, or steps a simulator. Do not launch a viewer by default and do not treat a preflight pass as a sim2sim behavior result. The helper's `--compile-mujoco` option compiles XML in a child process only; it does not render or step. ## Operating invariants - Native invocation is `python humanoid/scripts/sim2sim.py --task=x1_dh_stand --load_model=<timestamp-directory>`. `--task` is required. In the source, `--load_model` is a child name under `logs/<task>/exported_policies/`, not a free-form absolute model file; if omitted, the source selects the last lexicographically sorted directory. Inside that directory it takes the last `os.listdir` entry, so pin a directory containing exactly one artifact. - The exported artifact is a TorchScript file normally named `policy_dh.jit`, written by the DH exporter under a timestamp directory. It accepts a float32 tensor shaped `[batch, 3102]` and returns `[batch, 12]`. The 3102 values are 66 history frames × 47 features. The export wrapper takes the final 235 values (5 × 47) for the state estimator, reshapes the full input as `[-1, 66, 47]` for the long-history encoder, concatenates estimator and compressed history with the short history, and emits 12 action means. - Each 47-value frame is: 5 command/gait values (`sin phase`, `cos phase`, scaled `vx`, scaled `vy`, scaled `yaw`), 12 DOF-position offsets, 12 DOF velocities, 12 previous actions, 3 body angular-velocity values, and 3 Euler-angle values. The X1 config has `num_actions=12`, `num_single_obs=47`, `frame_stack=66`, `short_frame_stack=5`, and `num_observations=3102`. - The 12 action order is left hip pitch/roll/yaw, left knee pitch, left ankle pitch/roll, then the corresponding six right-leg joints. The MuJoCo actuator and URDF revolute order must agree with that order. Actions are clipped by the configured action limit, scaled by `0.5`, offset by the 12 default joint angles, and passed through position PD; do not pass a runner checkpoint or an ONNX file to sim2sim. - The sim loop uses a MuJoCo timestep of `0.001` seconds and decimation `10`: physics advances at 1 kHz and the policy/observation update occurs every 10 low-level steps (100 Hz). The source sets `model.opt.timestep` from this value, runs for 100 seconds by default, applies PD torques at every physics step, and renders every step. Native rendering is interactive and must be explicitly authorized after all gates pass. ## Controller and native handoff The README documents a Logitech F710 button-4 gate, but the current native thread does not implement that gate. It continuously reads axes every 100 ms: `x_vel_cmd = -axis(1)`, `y_vel_cmd = -axis(0)`, and `yaw_vel_cmd = -axis(3)`. The README's intended semantic mapping is button 4 + stick 1− forward, 1+ backward, 0− left, 0+ right, 3− counterclockwise, and 3+ clockwise. Treat button gating as an operator procedure, not an implemented safety interlock; center the controller and begin with one small command. After a successful training run, hand off checkpoints to [training](../training/SKILL.md) only for provenance or repair. Hand a runner checkpoint to [export](../export/SKILL.md) to produce `policy_dh.jit`; only then return here. Hand a JIT path to this sub-skill, and hand any interactive Isaac Gym checkpoint playback to [playback](../playback/SKILL.md). Do not make this route train, export, or replace a missing backend with a fake simulator. ## Bundled runtime files - [workflows.md](references/workflows.md): guarded execution, artifact selection, timing, and sibling handoffs. - [model-and-asset-validation.md](references/model-and-asset-validation.md): distilled JIT, observation/action, MJCF, mesh, URDF, and timing contracts. - [troubleshooting.md](references/troubleshooting.md): backend, policy, XML, observation, controller, and viewer failure recovery. - [scripts/sim2sim_preflight.py](scripts/sim2sim_preflight.py): safe static preflight and optional no-viewer XML compilation.