Newton GPU 机器人仿真器入门教程（零）— NVIDIA、DeepMind、Disney 联合推出

Newton 是一个基于英伟达™（NVIDIA®）Warp 的 GPU 加速物理仿真引擎，主要面向机器人专家和仿真研究人员。它扩展和概括了 Warp 现有的 warp.sim 模块，并将 MuJoCo Warp 集成为主要后端。牛顿强调基于 GPU 的计算、可微分性和用户定义的可扩展性，有利于快速迭代和可扩展的机器人仿真。

牛顿由迪斯尼研究院、谷歌 DeepMind 和英伟达公司共同维护。

一、快速入门

1.1 实时渲染

Newton 提供了一个简单的 OpenGL 渲染器，用于可视化模拟。渲染器需要安装 pyglet（版本 >= 2.0）。

renderer = newton.utils.SimRendererOpenGL(model=model, path="Newton Simulator", scaling=2.0)

# at every frame:
renderer.begin_frame(sim_time)
renderer.render(state)
renderer.end_frame()

# pause the simulation (blocks the control flow):
renderer.pause = True

使用 OpenGLRenderer（又名 newton.utils.SimRendererOpenGL）时的键盘快捷键：

键盘快捷键
Key(s)	Description
`W`, `A`, `S`, `D` (or arrow keys) + mouse drag	像在 FPS 游戏中一样移动摄像头
`X`	切换线框渲染
`B`	切换背面剔除
`C`	切换坐标系轴的可见性
`G`	切换地面网格
`D`	切换深度渲染
`I`	切换左上角的信息文本
`SPACE`	暂停/继续模拟
`TAB`	跳过渲染，在后台继续模拟（可在运行渲染器时加快 RL 训练速度）

1.2 USD 渲染

您也可以将模拟渲染为时间采样的美元阶段，以便在 Omniverse 中可视化，而不是实时渲染。

renderer = newton.utils.SimRenderer(model=model, path="simulation.usd", scaling=2.0)

# at every frame:
renderer.begin_frame(sim_time)
renderer.render(state)
renderer.end_frame()

# to save the USD stage:
renderer.save()

1.3 示例：创建一个粒子链

import newton

builder = newton.ModelBuilder()

# anchor point (zero mass)
builder.add_particle((0, 1.0, 0.0), (0.0, 0.0, 0.0), 0.0)

# build chain
for i in range(1, 10):
    builder.add_particle((i, 1.0, 0.0), (0.0, 0.0, 0.0), 1.0)
    builder.add_spring(i - 1, i, 1.0e3, 0.0, 0)

model = builder.finalize("cpu")

print(f"{model.spring_indices.numpy()=}")
print(f"{model.particle_count=}")
print(f"{model.particle_mass.numpy()=}")

model.spring_indices.numpy()=array([0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9], dtype=int32)
model.particle_count=10
model.particle_mass.numpy()=array([0., 1., 1., 1., 1., 1., 1., 1., 1., 1.], dtype=float32)

二、重要概念

三、API 参考

3.1 求解器

3.1.1 XPBD 求解器

class newton.solvers.XPBDSolver(model=None, iterations=2, soft_body_relaxation=0.9, soft_contact_relaxation=0.9, joint_linear_relaxation=0.7, joint_angular_relaxation=0.4, rigid_contact_relaxation=0.8, rigid_contact_con_weighting=True, angular_damping=0.0, enable_restitution=False)

使用基于位置的扩展动力学 (XPBD) 的隐式积分器，用于刚体和软体仿真。

参考文献

Miles Macklin、Matthias Müller 和 Nuttapong Chentanez。2016. XPBD：基于位置的顺应约束动力学仿真。第九届国际游戏运动大会（MIG '16）论文集。美国计算机协会，纽约州纽约市，49-54。https://doi.org/10.1145/2994258.2994272
Matthias Müller, Miles Macklin, Nuttapong Chentanez, Stefan Jeschke, and Tae-Yong Kim. 2020. 基于扩展位置动力学的详细刚体仿真。ACM SIGGRAPH/Eurographics 计算机动画研讨会（SCA '20）论文集》。欧洲图形协会，德国戈斯拉尔，第 10 条，1-12。https://doi.org/10.1111/cgf.14105。

在构建模型、状态和控制（可选）对象后，可使用时间积分器将模拟状态在时间上向前推进。

示例

solver = newton.XPBDSolver(model)

# simulation loop
for i in range(100):
    solver.step(model, state_in, state_out, control, contacts, dt)

3.1.2 VBD 求解器

class newton.solvers.VBDSolver(model, iterations=10, handle_self_contact=False, penetration_free_conservative_bound_relaxation=0.42, friction_epsilon=1e-2, body_particle_contact_buffer_pre_alloc=4, vertex_collision_buffer_pre_alloc=32, edge_collision_buffer_pre_alloc=64, triangle_collision_buffer_pre_alloc=32, edge_edge_parallel_epsilon=1e-5)

使用顶点块下降 (VBD) 的隐式积分器，用于布料模拟。

参考文献

Anka He Chen, Ziheng Liu, Yin Yang, and Cem Yuksel. 2024. 顶点块下降。ACM Trans. Graph. 43, 4, Article 116 (July 2024), 16 pages. https://doi.org/10.1145/3658179

请注意，VBDSolver 的构造函数需要一个 Model 对象作为输入，以便进行一些预计算和预分配空间。构建完成后，您必须提供与构建过程中使用的相同的模型对象。目前，您必须手动提供粒子着色并将其分配给 model.particle_color_groups，才能使 VBD 正常工作。

VBDSolver.simulate 接受三个参数：class:Model（类）、State（状态）和 Control（控制）（可选）对象。

示例

model.particle_color_groups = # load or generate particle coloring
solver = newton.VBDSolver(model)

# simulation loop
for i in range(100):
    solver.step(model, state_in, state_out, control, contacts, dt)

3.1.3 MuJoCo 求解器

class newton.solvers.MuJoCoSolver(model, *, mjw_model=None, mjw_data=None, separate_envs_to_worlds=None, nefc_per_env=100, ncon_per_env=None, iterations=20, ls_iterations=10, solver='cg', integrator='euler', use_mujoco=False, disable_contacts=False, register_collision_groups=True, joint_damping=0.05, default_actuator_gear=None, actuator_gears=None, update_data_every=1, save_to_mjcf=None)

该求解器提供了一个使用 MuJoCo 物理引擎模拟物理的接口，并通过 mujoco_warp 优化了 GPU 加速。它同时支持 MuJoCo 和 mujoco_warp 后端，可高效模拟带有接触和约束的铰接系统。

注意事项

该求解器需要安装 mujoco_warp 及其依赖项。
有关安装说明，请参阅 mujoco_warp 软件源。

示例

solver = newton.MuJoCoSolver(model)

# simulation loop
for i in range(100):
    solver.step(model, state_in, state_out, control, contacts, dt)

3.2 关节控制模式

关节模式控制关节控制输入 Control.joint_act 如何影响施加在给定关节轴上的扭矩。默认情况下，它通过 JOINT_MODE_FORCE 直接施加力。其他模式可用于实现关节位置或速度驱动：

joint_mode_force

这是默认的控制模式，控制输入是施加在关节轴上的扭矩 $\tau$ 。

joint_mode_target_position （目标位置模式

控制输入是目标位置 $\mathbf{q}_{\mathrm{target}}$ ，通过对扭矩 $\tau$ 的 PD 控制来实现，其中比例和导数增益由 Model.joint_target_ke 和 Model.joint_target_kd 设置：

$\tau=k_e(\mathbf{q}_{\mathrm{target}}-\mathbf{q})-k_d\mathbf{\dot{q}}$

JOINT_MODE_TARGET_VELOCITY

控制输入是目标速度 $\dot{\mathbf{q}}_{\mathrm{target}}$ ，通过比例增益 Model.joint_target_ke 实现扭矩 $\tau$ 控制，使关节轴上的速度达到目标速度：

$\tau=k_e(\mathbf{\dot{q}_{target}}-\mathbf{\dot{q}})$

四、Newton 集成

4.1 Isaac Lab

4.2 MuJoCo

五、warp.sim 迁移指南

本指南旨在帮助用户将其应用程序从 warp.sim 迁移到 Newton。

5.1 求解器

warp.sim	Newton
warp.sim.FeatherstoneIntegrator	`newton.solvers.FeatherstoneSolver`
warp.sim.SemiImplicitIntegrator	`newton.solvers.SemiImplicitSolver`
warp.sim.VBDIntegrator	newton.solvers.VBDSolver
warp.sim.XPBDIntegrator	newton.solvers.XPBDSolver
`integrator.simulate(self.model, self.state0, self.state1, self.dt, None)`	`solver.step(self.model, self.state0, self.state1, self.control, None, self.dt)`

5.2 导入器

warp.sim	Newton
warp.sim.parse_urdf()	newton.utils.parse_urdf()
warp.sim.parse_mjcf()	newton.utils.parse_mjcf()
warp.sim.parse_usd()	newton.utils.parse_usd()
warp.sim.resolve_usd_from_url()	newton.utils.import_usd.resolve_usd_from_url()

5.2.1 模型

ModelShapeGeometry.is_solid 现在的 dtype 是 bool，而不是 wp.uint8。

5.2.2 模型构建器

warp.sim	Newton
`ModelBuilder.add_body(origin=..., m=...)`	`ModelBuilder.add_body(xform=..., mass=...)`
`ModelBuilder._add_shape()`	`ModelBuilder.add_shape()`
`ModelBuilder.add_shape_*(pos=..., rot=...)`	`ModelBuilder.add_shape_*(xform=...)`

5.3 渲染器

warp.sim	Newton
`warp.sim.render.SimRenderer`	`newton.utils.SimRenderer`
warp.sim.render.SimRendererUsd	newton.utils.SimRendererUsd
warp.sim.render.SimRendererOpenGL	newton.utils.SimRendererOpenGL

六、扩展 Newton

本节介绍如何使用新的求解器和碰撞检测算法扩展 Newton。

七、开发指南

本文档是为希望为项目做出贡献的开发人员提供的指南。

7.1 环境设置

克隆版本库

git clone git@github.com:newton-physics/newton.git
cd newton

7.1.1 使用 uv

uv 是一个 Python 软件包和项目管理器。

安装 uv：

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

运行基本示例：

# An example with basic dependencies
uv run newton/examples/example_quadruped.py

# An example that requires extras
uv run --all-extras newton/examples/example_humanoid.py

更新项目锁文件中的所有依赖项，运行后记得提交 uv.lock：

uv lock -U

7.1.2 使用 venv

本说明适用于希望使用 venv 或 Conda（如 Miniforge）建立开发环境的用户。

python -m venv .venv

On macOS and Linux.
source .venv/bin/activate

On Windows (console).
.venv\Scripts\activate.bat

On Windows (PowerShell).
.venv\Scripts\Activate.ps1

安装依赖项，包括可选项：

python -m pip install mujoco --pre -f https://py.mujoco.org/
python -m pip install warp-lang --pre -U -f https://pypi.nvidia.com/warp-lang/
python -m pip install git+https://github.com/google-deepmind/mujoco_warp.git@main
python -m pip install -e .[dev]

运行基本示例：

# An example with basic dependencies
python newton/examples/example_quadruped.py

# An example that requires extras
python newton/examples/example_humanoid.py

7.2 运行测试

Newton 测试套件可通过 uv run -m newton.tests 或 python -m newton.tests 运行。默认情况下，测试套件将在最多八个进程上并行执行。通过 --help 标志可查看测试运行器的可用选项。

某些测试使用可选依赖项（如 usd-core），如果未安装，则会跳过。

使用 uv 时，可以通过运行以下命令，在安装了所有附加组件的情况下运行测试套件：

uv run --all-extras -m newton.tests

使用 venv 时，可从版本库的根目录运行 python -m pip install -e .[dev] 来安装测试套件的附加组件。

代码覆盖率报告需要安装 coverage[toml]，可以通过在测试命令中附加 --coverage --coverage-html 标记来生成，例如

uv run --all-extras -m newton.tests --coverage --coverage-html htmlcov

可使用网络浏览器打开文件 htmlcov/index.html，查看覆盖率报告。

7.3 代码格式化和内核

预提交（pre-commit）可用于确保本地代码符合 Newton 的检查。从版本库顶部运行

# With uv installed
uvx pre-commit run -a

# With venv
python -m pip install pre-commit
pre-commit run -a

自动运行 git commit 的预提交钩子：

# With uv installed
uvx pre-commit install

# With venv
pre-commit install

可通过预提交卸载卸载钩子。

7.4 构建文档

以下是构建文档的几种方法。

7.4.1 使用 uv

rm -rf docs/_build
uv run --extra docs sphinx-build -W -b html docs docs/_build/html

Alternatively using the Makefile
uv sync --extra docs
source .venv/bin/activate
cd docs
make clean
make html

7.4.2 使用 venv

python -m pip install -e .[docs]
python -m sphinx -W -b html docs docs/_build/html

# Alternatively using the Makefile
cd docs
make clean
make html

7.5 测试文档代码片段

doctest Sphinx 生成器用于确保文档中的代码片段保持最新。

可以通过以下方式运行 doctests

# With uv installed
uv run --extra docs sphinx-build -W -b doctest docs docs/_build/doctest

# With venv
python -m sphinx -W -b doctest docs docs/_build/doctest

更多信息，请参阅 sphinx.ext.doctest 文档。

7.6 打包

要生成 .whl 文件（例如，测试分发包的创建），请运行

uv build --wheel

输出结果将放在 dist/ 子目录下。

八、贡献指南

为开发 Newton 做出贡献的方式包括

在 GitHub 上报告错误和申请新功能。
在 GitHub 上提问、分享您的工作或参与讨论主题。
向 Newton 代码库添加新示例。
改进文档。
贡献错误修复或新功能。

8.1 代码贡献

欢迎社区贡献代码。我们不需要正式的《贡献者许可协议》（CLA），而是使用《开发者原产地证书》（Developer Certificate of Origin）来确保贡献者有权向本项目提交贡献。请确保所有提交都添加了签名，签名的电子邮件地址必须与提交作者的电子邮件地址一致，以同意 DCO 条款对每项特定贡献的规定。

DCO 全文如下：

Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or

(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or

(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.

(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.