Language

SuperDex 后端¶

SuperDex 已作为 packed CPU HOST_BRIDGE 后端加入 tensor-only Manager runtime。Go2 owner 仍是 Configured 研究配置，不构成完整训练或跨平台生产支持声明。

SuperDex 是由 unisim.backend.superdex 拥有的可选 CPU 物理后端。当前签入的 owner 为 go2_joystick_flat/superdex。当前支持等级为 Configured；短 rollout 或少量训练迭代不能证明完整训练效果、性能或跨平台支持。

安装¶

SuperDex Physics/Robotics 1.0.0 已发布 Python wheel，是 UniLab 的 optional extra，不再需要源码编译 native extension。wheel 携带 native batch executor，仅支持 CPython 3.12/3.13 的 Linux x86_64；其他平台上该 extra 为空，CLI 会给出针对性的运行时诊断。CPU 物理不需要 CUDA。

# 源码 checkout（默认 Python 3.13；wheel 支持 CPython 3.12/3.13）：
uv sync --extra superdex

# 从 PyPI 安装：
pip install "unilab[superdex]"

该 extra 通过 unisim-core[superdex] 委托 UniSim 钉定版本；UniSim 的 superdex extra 已包含普通 mujoco 包（MJCF 转换与离线回放渲染使用），不需要 mjbatch（仅 MuJoCo 物理后端需要）。当前 wheel 为临时 unilabsim 构建（superdex-physics-uni/superdex-robotics-uni）；上游 project_superdex 发布正式 superdex-physics/superdex-robotics wheel 后， UniSim 会切换包名，UniLab 侧无需改动。

若要审计本地 project_superdex checkout，可设置 SUPERDEX_ASSETS_PATH=/absolute/path/to/project_superdex/assets；单次运行也可通过 env.superdex_assets_root=/absolute/path/to/project_superdex/assets 覆盖。显式 root 优先于 Hugging Face 下载，且不会触发下载。

只有修改 SuperDex 引擎源码本身时才需要本地源码构建： bash scripts/tools/setup_superdex_env.sh 会 clone integration branch、编译 native extension 并以 editable 方式链接本地 UniSim/UniLab；常规使用不需要它。

运行 Go2 任务¶

go2_joystick_flat/superdex owner 在 SuperDex 上训练和评估 Go2 四足机器人。它继承 MuJoCo owner 的 policy I/O（49 维 actor 观测、52 维 critic 观测、 12 维位置目标动作）与控制时序，声明自己的 command 范围和 reward 权重，并显式接受接触近似；contract 细节见下文”验证与归属”。

直接在 SuperDex 上训练（CPU 物理，自动 native worker）：

uv run train --algo ppo --task go2_joystick_flat --sim superdex

owner 默认 1024 个环境、400 轮迭代。日志和 checkpoint 写入 logs/rsl_rl_ppo/Go2JoystickFlat/<timestamp>_superdex/。

用 --load-run 评估已训练的 run。默认 record 回放：跨 16 个环境推进 200 帧，通过离线 MuJoCo renderer 把 play_video.mp4 写入 run 目录，物理仍由 SuperDex 执行：

uv run eval --algo ppo --task go2_joystick_flat --sim superdex \
  --load-run 2026-09-10_10-50-00_superdex

如需 native SuperDex（Polyscope）viewer 而不是视频，加 --render-mode interactive；CLI 会强制 training.play_env_num=1，owner 层同时把该次运行的 env 切到 serial executor。

在 MuJoCo 上训练的 checkpoint 可以直接在 SuperDex 上评估（sim2sim）：把它的 run 目录传给 --load-run。play 入口会在构造环境前按 sim2sim contract 验证来源 run_config.json，并拒绝不兼容的 policy I/O。

默认 CPU 环境并行¶

backend 使用 SuperDex wheel 携带的 SceneBatchExecutor。它是跨独立 scene 的常驻 C++ 线程池：每个子步批量写入广义力、推进 scene，并回写 articulation/link state、 contact sensor 和 solver status，不再逐环境跨越 Python binding。资产物化、reset 和 cache frame 转换仍由 UniSim adapter 负责。这是 CPU 线程并行，不是 GPU physics；它不改变 PPO/APPO collector、learner 或 policy contract。决策见 ADR-0009 SuperDex Native C++ Scene Batch Executor 和 unisim#41。

两个 task owner 默认选择自动 worker：

Owner 选项	含义
`env.superdex_num_workers=0`	自动：`min(affinity 内可用物理核心数, num_envs)`
`env.superdex_num_workers=1`	一个 native C++ scene worker
`env.superdex_num_workers=K`	显式 C++ worker 数，最多为 `num_envs`

native scene 的 DebugDraw 状态有线程亲和性，因此 batch 模式与已连接的 native SuperDex debugger 不兼容：adapter 在检测到 debugger 客户端连接时会直接报错并给出可操作提示。需要使用 native debugger 调试时，以 env.superdex_execution_mode=serial 运行——该模式在环境线程上逐步推进每个 scene，完全不创建 native worker pool （unisim#55）。serial 是调试配置，不是性能配置。

eval --sim superdex --render-mode interactive 走 native SuperDex（Polyscope） viewer 渲染，而不是 MuJoCo viewer 路径。owner 层会自动把 env 切到 superdex_execution_mode=serial，CLI 同时强制 training.play_env_num=1（viewer 只绘制一个 scene）；显式传入的 training.play_env_num=... 会被保留。

1024 个环境、16 核 32 线程主机上，自动解析为 16 workers。多 rank 并发 collector 按完整物理核心分配，并将同一核心的 logical sibling 放在同一 rank，避免拆分 SMT 核心。也可以通过 training.dp_collector_cpu_ids 为每个 rank 显式提供 CPU id 列表；该分片在 SuperDex 创建 native worker pool 前应用。

每个物理子步由 host 执行 pre-step control callback，随后进入 native batch barrier，完成后发布新 batch state，再执行下一 callback。局部 reset 保留请求行顺序，不影响未选择环境。native worker 错误会关闭 executor 并报告失败，不静默返回旧状态或回退串行。env.close 会在销毁 scene 前 join C++ worker。

worker 数不能代替加速证据。吞吐对照应匹配模型、控制序列、batch 和子步，记录完整 backend/env 时间、startup、RSS、CPU 使用和实际 worker 数。吞吐按 env 控制步统计，不能把 physics 子步重复计入样本。已有接触近似的物理边界保持不变。

固定根具有名称和可读的 body state，但 reset 只写 joint state，不要求 free-root layout。该任务不需要接触 sensor、相机、site Jacobian 或材料 DR。SuperDex 没有 native renderer；默认 record 回放使用离线 MuJoCo renderer，物理仍由 SuperDex 执行。 .superdex_bot 场景需要提供 visual_model_file。play_render_mode=none 会完全跳过回放，不能作为 checkpoint rollout 已执行的证据。

superdex_allow_contact_approximation 默认 false，只供经过审核的 MJCF 转换配置显式启用。启用后会警告 contact/material 近似，包括 torsional/rolling friction 不等价；这不代表任意 MJCF 任务已兼容。接触查询返回最近一次完成求解的结果。reset 清除该结果，需要一次正时间步才会产生新接触，不能把 reset 后的 contact 当成即时几何重叠测试。运动学 body/joint getter 则在 reset 后立即刷新。

验证与归属¶

go2_joystick_flat/superdex PPO owner 是研究性质的 sim2sim 配置。它继承 MuJoCo owner，保留 49 维 actor 观测、52 维 critic 观测、12 维位置目标动作、归一化、网络维度和控制时序；关闭 runtime PD gain DR，并显式接受接触近似。adapter 的冷路径 MJCF 转换有明确限制，该 owner 不代表任意场景或行走效果等价。

先用 MuJoCo owner 创建一个小型来源 checkpoint，再把路径传给可选 checkpoint 测试：

uv run --no-sync train --algo ppo --task go2_joystick_flat --sim mujoco \
  algo.num_envs=2 algo.max_iterations=2 algo.num_steps_per_env=16 \
  algo.algorithm.num_mini_batches=1 algo.algorithm.num_learning_epochs=1 \
  training.device=cpu training.no_play=true
export UNILAB_SUPERDEX_GO2_CHECKPOINT=/absolute/path/to/source/run/model_1.pt
uv run --no-sync pytest tests/envs/test_go2_superdex.py -q

测试在构造 env 前验证来源 run_config.json，检查修改动作语义时确实拒绝，随后通过 production playback session 加载真实策略，无渲染执行 64 个 SuperDex 控制步。它验证有限数值和接口兼容性；只训练两轮的 checkpoint 不以可靠行走为验收标准。

引擎转换与物理由 UniSim 拥有；资产注册、Hydra 与任务 term 由 UniLab 拥有。相关约束见 ADR-0007 UniSim Extraction Boundary、 ADR-0006 Community Manager API On NumPy Runtime 和 ADR-0002 Backend Capability Boundary For Play And Snapshot。