Newton 后端

Newton（PyPI 分发名 newton， 仓库钉在 1.5.1）是基于 Warp 的 GPU 物理仿真器，UniLab 以进程内方式 使用它：unisim.backend.newton.NewtonBackend 在其上提供标准的 SimBackend NumPy contract，物理与 learner 同进程运行——没有 worker 子进程，也没有 IPC。

当前状态：Newton 已在 owner/config 边界完成接线（UniLab PR #1511，适配器由 unisim 仓库的 unisim.backend.newton 提供）。g1_walk_flat 提供 PPO 与 SAC owner 配置（src/unilab/conf/{ppo,sac}/task/g1_walk_flat/newton.yaml， registry 注册 G1WalkFlat 的 newton 后端），跨后端契约审计 （scripts/audit_sim2sim_contracts.py）在两棵 algo 树上覆盖 mujoco↔newton（结论 TRANSFERABLE）。支持等级：SAC 为 Tested—— 2026-09-06 在 RTX 4090 / torch 2.8.0+cu128 / newton 1.5.1 / mujoco-warp 3.11 上完成完整 5000-iteration 训练（reward/mean 6.68 → 242.3， episode length → 983，约 43k steps/s，wall 4m25s），并对 model_5000.pt 完成回放验证：原生 ViewerGL 离屏 record（800 帧 1280x720 mp4）与交互式 ViewerGL 窗口冒烟（真实 X display）；PPO 保持 Configured（现有 证据限于 owner 配置、compose/contract 检查和 fail-closed 的 runtime/import 边界，尚无训练或回放验证结论）。

多 GPU 数据并行（issue #1512）：2026-09-06 在 2× NVIDIA RTX 6000D（Blackwell）/ torch 2.8.0+cu128 / newton 1.5.1 / mujoco-warp 3.11 上完成实测——PPO torchrun DP=2 与 SAC DpRankSupervisor DP=2（training.devices=[0,1]）训练冒烟均正常完成， nvidia-smi 采样确认每个 rank 的 learner 与 collector sim 进程物理落位 在各自 GPU、无对端泄漏；单卡 PPO/SAC 回归同步通过。Newton/Warp 遵循标准 CUDA 设备语义，无需 Genesis 那样的 CUDA_VISIBLE_DEVICES 钉卡；rank 本地设备通过 env override 以 newton_device="cuda:N" 传入 spawn collector（uni_rl 1.0.0 的 collector 进程绑定门只覆盖 mjwarp），SAC owner 将 collector tick-0 超时提升到 180 s 以覆盖 Warp 内核编译的冷 路径。

安装

Newton 运行时是 optional extra，钉定 Newton 1.5.1 与 MuJoCo-Warp 3.11 / Warp 1.16 系列：

# 源码 checkout：
uv sync --extra newton

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

该 extra 精确钉定 newton==1.5.1、mujoco-warp==3.11.0、 mujoco==3.11.0、warp-lang==1.16.0，并包含原生 ViewerGL 依赖 （pyglet>=2.1.6,<3、imgui-bundle>=1.92.0）。它与 mujoco extra （mujoco~=3.11.0）和 mjwarp extra（mujoco-warp~=3.11.0、 warp-lang==1.16.0）共享同一条 MuJoCo 3.11 / MuJoCo-Warp 3.11 / Warp 1.16 版本线，三个 extra 可以组合进同一个环境：

uv sync --extra mujoco --extra mjwarp --extra newton

前置条件：

  • Linux，装有 NVIDIA GPU 与 CUDA 驱动。适配器的进程设备绑定 （unisim.backend.newton.runtime.bind_newton_process_device）要求解析 到可用的 CUDA Warp 设备，否则 fail-closed 报错；CPU 设备不是已验证的 支持通道。

  • Python >=3.10（仓库支持范围为 3.10–3.13）。

安装后可运行 unisim 仓库的 scripts/check_newton_runtime.py 做 metadata 级探针（加 --import 显式导入原生运行时）。在 UniLab 侧，缺少 Newton 运行时不是静默失败：顶层 CLI 在训练前检查 newton / mujoco_warp / mujoco / warp 模块，缺失时 fail-closed 并给出安装 提示（src/unilab/cli.py 的 _check_runtime_requirements）。

训练与评估

训练通过标准 CLI 选择 newton owner：

# PPO
uv run train --algo ppo --task g1_walk_flat --sim newton

# SAC
uv run train --algo sac --task g1_walk_flat --sim newton

Newton/MuJoCo-Warp 3.11 要求显式的设备与存储容量，对应 owner YAML 中的 env.* 字段：

  • newton_device：owner 默认 null 是有意设计——进程设备绑定器 （src/unilab/base/process_device.py）在 materialization 前注入 rank 本地的 CUDA 设备。显式设置时必须是非空 CUDA 设备字符串。

  • newton_nconmax / newton_njmax：显式容量上界（g1 owner 为 320 / 512）。适配器在冷路径标定 solver 计数，容量不足时抛出明确的 capacity 错误，绝不静默截断约束。

  • newton_capacity_check_steps：容量检查步数（默认 1）。

Playback 与渲染

Newton 后端通过上游 newton.viewer.ViewerGL 提供原生渲染（依赖已包含 在 newton extra：pyglet>=2.1.6,<3 + imgui-bundle>=1.92.0）。 owner 继承 base 配置的 training.play_render_mode: auto：有显示时 auto 解析为 interactive（ViewerGL 交互窗口），无显示时解析为 record（ViewerGL(headless=True) 离屏渲染写 mp4）。若安装不完整， record 才会回退到 MuJoCo 离线快照渲染，interactive 会 fail-closed； 正常安装 newton 时始终选择原生渲染。headless 离屏渲染仍需 OpenGL context： 无显示服务器的 Linux 主机设 PYOPENGL_PLATFORM=egl，Wayland 设 PYOPENGL_PLATFORM=glx。

uv run eval --algo ppo --task g1_walk_flat --sim newton \
    --load-run <run_dir_name> --render-mode record

uv run eval --algo sac --task g1_walk_flat --sim newton \
    --load-run <run_dir_name> --render-mode record

未支持边界

以下能力 fail-closed（显式报错或拒绝配置），而不是静默降级：

  • PD gain 运行时随机化：Newton 当前拒绝该能力，owner 显式设置 events.pd_gains: null 保持 fail-closed，直到适配器补齐。

  • 原生渲染路径的相机参数：native ViewerGL 路径忽略 camera_kwargs（MuJoCo 快照路径仍生效）。

跨后端迁移（sim2sim）

newton owner 与 mujoco owner 在契约守卫 （src/unilab/utils/sim2sim.py）审计下保持 DENYLIST 一致（结论 TRANSFERABLE），同一 task 的 checkpoint 可跨后端使用。