Newton 物理引擎开发指南:从源码安装到测试、文档与基准测试的完整开发者工作流
Newton 物理引擎开发指南:从源码安装到测试、文档与基准测试的完整开发者工作流
本篇指南面向希望为 Newton 贡献代码、或想深入理解其内部运作机制的开发者,系统讲解基于 NVIDIA Warp 构建的 GPU 物理仿真引擎 Newton 的开发环境搭建、测试运行、代码规范、文档构建与版本化、示例编写、资产版本固定、基准测试等完整工作流。阅读后你将掌握 uv/venv 两套源码安装方法、并行测试与覆盖率报告、Ruff + pre-commit 代码检查、typos 拼写检查与误报处理、SPDX 许可证头规范、Sphinx 文档构建与 GitHub Pages 版本化发布、__all__ 驱动的 API 文档生成、Towncrier changelog 片段规范、示例的 Example 接口与测试钩子,以及 airspeed velocity 基准测试框架的实战用法。
开发文档定位与相关规范
development.rst 是 Newton 官方文档中面向"开发者与贡献者"的入口文档,与面向普通用户的 installation.rst 互为补充。它覆盖以下主题,也是本文展开的骨架:
- 从源码安装(
uv与venv+ pip 两种方式); - 依赖锁定(
uv.lock)与更新策略; - 并行测试运行、覆盖率、失败排查;
- Ruff 格式化/lint 与 pre-commit 钩子;
- typos 拼写检查与误报配置;
- SPDX 许可证头规范与 CI 检查;
- 本地 Warp 替换、文档构建/预览/版本化;
- API 文档生成、实验性功能标注、doctest;
- changelog 片段、示例编写、资产版本固定、asv 基准测试与发布流程。
贡献与 PR 流程的细节遵循 CONTRIBUTING.md(仓库根目录),治理与法律层面的要求可参考上游 governance 仓库的贡献指南。任何代码或公开 API 变更都必须遵循 source_code_guidelines.rst,评审者可以参考 review_guidelines.rst。
开发环境搭建:从源码安装 Newton
常规最终用户安装请参见 installation.rst;要参与开发或贡献,需要先克隆仓库并安装开发依赖。项目根目录同时维护着 pyproject.toml(构建与依赖元数据)与 uv.lock(锁定文件)。
Method 1:使用 uv(推荐)
uv 是项目首选的 Python 环境与依赖管理工具。先安装 uv:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
然后克隆仓库并创建带 dev 依赖 extras 的本地项目环境:
git clone https://gitcode.com/GitHub_Trending/newton9/newton.git
cd newton
uv sync --extra dev
同步完成后,dev extras 会自动对所有 uv run 命令生效,无需每次重复传 --extra dev。例如列出所有可用示例:
uv run -m newton.examples --list
dev extras 的内容在 pyproject.toml 的 [project.optional-dependencies] 中定义,它递归包含 examples(进而包含 sim、importers、onnx),并额外加入 coverage[toml]>=7.8.0 用于覆盖率测试。所有 extras 的用途说明见 installation.rst 的 "Extra Dependencies" 一节。
Method 2:使用 pip 与虚拟环境
手动管理虚拟环境时,先创建并激活:
# macOS / Linux
python -m venv .venv
source .venv/bin/activate
# Windows (console)
python -m venv .venv
.venv\Scripts\activate.bat
# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1
然后以可编辑(editable)模式安装 Newton 及其开发依赖:
pip install -e ".[dev]" --extra-index-url https://pypi.nvidia.com/
--extra-index-url 将 pip 指向 NVIDIA 包索引——这是找到比 PyPI 上更新版本的 warp-lang 所必需的。这一点在 pyproject.toml 中也有印证:[[tool.uv.index]] name = "nvidia" 定义了独立的 NVIDIA 索引,且 [tool.uv.sources] 中 warp-lang = { index = "nvidia" } 指定 warp-lang 一律从该索引解析。
Python 依赖管理:uv lockfile 的维护
当使用 uv 时,仓库根目录的 uv.lock 会将所有直接与传递依赖解析为精确版本,保证不同机器间构建可复现。需要升级某个依赖时,用 uv lock -P <package-name>:
uv lock -P warp-lang --prerelease allow
uv lock -P mujoco-warp
--prerelease allow 是给使用预发布版本的依赖(如 warp-lang)准备的标志。若想一次性更新 lockfile 中全部依赖:
uv lock -U
任何更新过 lockfile 的命令执行后,记得提交 uv.lock。从依赖声明看,Newton 的唯一强制运行时依赖是 warp-lang>=1.17.0,其余功能均通过 extras 可选安装。
运行测试套件
Newton 的测试套件同时支持 uv 与标准 venv 工作流,默认最多在 8 个并行进程中运行。入口是 python -m newton.tests,其实现位于 newton/tests/main.py,它委托给仓库内置的 unittest-parallel 派生实现 newton/tests/thirdparty/unittest_parallel.py。
# uv:安装开发 extras 并运行测试
uv run --extra dev -m newton.tests
# venv:先安装 dev extras(含测试与覆盖率依赖)
python -m pip install -e ".[dev]"
python -m newton.tests
两种运行方式都可通过 --help 查看全部可用参数。从 unittest_parallel.py 的 argparse 定义可以看到一组值得了解的测试运行器选项:
| 参数 | 默认值 | 说明 |
|---|---|---|
-j, --jobs |
0(全部核心) |
测试进程数;最终取 min(进程数, --maxjobs) |
-m, --maxjobs |
8 |
并行进程数上限 |
--serial-fallback |
关闭 | 单进程模式,不启动 multiprocessing / concurrent.futures |
-k |
— | 只运行匹配指定子串的测试(可重复) |
--coverage / --coverage-html DIR |
— | 覆盖率测量与 HTML 报告输出 |
--junit-report-xml FILE |
— | 生成 JUnit XML 格式报告 |
--parallel-timeout |
3600 |
并行收集结果的超时秒数 |
--no-shared-cache / --no-cache-clear |
— | Warp 内核缓存控制 |
--warp-config KEY=VALUE |
— | 向示例子进程转发 warp.config 覆盖项 |
处理 BrokenProcessPool 与内存压力
如果测试运行以 concurrent.futures.process.BrokenProcessPool 中止,说明某个 worker 进程崩溃了(OOM、段错误等)。运行器默认并行度是 min(cpu_count, 8),在内存受限的机器上可能撑爆内存并杀死 worker。此时应减少 worker 数,或退化为单进程:
python -m newton.tests --jobs 4
--serial-fallback 则是完全单进程运行。此外,测试运行前运行器会执行 wp.clear_lto_cache() 与 wp.clear_kernel_cache() 清理 Warp 内核缓存(见 unittest_parallel.py),多工作区并行开发时可借助 WARP_CACHE_ROOT 环境变量隔离各自缓存。
单独测试某个示例
-k 参数可以只测试某个特定示例,例如 basic_shapes:
# uv
uv run --extra dev -m newton.tests.test_examples -k test_basic.example_basic_shapes
# venv
python -m newton.tests.test_examples -k test_basic.example_basic_shapes
生成覆盖率报告
# uv
uv run --extra dev -m newton.tests --coverage --coverage-html htmlcov
# venv(需已安装 coverage[toml],它随 [dev] 一起安装)
python -m newton.tests --coverage --coverage-html htmlcov
用浏览器打开 htmlcov/index.html 即可查看覆盖率报告。覆盖率配置在 pyproject.toml 的 [tool.coverage.run] 与 [tool.coverage.report] 中:source = ["newton"],并默认忽略 newton/examples/*、newton/tests/* 等目录,@wp/@warp 装饰的 kernel 与 if __name__ == "__main__" 代码不计入覆盖。
代码格式化与静态检查:Ruff + pre-commit
Newton 使用 Ruff 进行 Python 的 lint 与格式化,用 pre-commit 保证本地代码符合项目检查。在仓库根目录运行:
# uv
uvx pre-commit run -a
# venv
python -m pip install pre-commit
pre-commit run -a
要让钩子在每次 git commit 时自动执行:
# uv
uvx pre-commit install
# venv
pre-commit install
卸载钩子用 pre-commit uninstall。Ruff 的规则集配置在 pyproject.toml 的 [tool.ruff.lint] 中,select 覆盖了 pycodestyle(E/W)、isort(I)、pyflakes(F)、flake8-bugbear(B)、flake8-comprehensions(C4)、NumPy 专用规则(NPY)、pylint 部分规则(PLC/PLE/PLW)、pyupgrade(UP)、ruff 专用规则(RUF)与 TID253(禁止模块级导入特定重型依赖)。其中 TID253 通过 banned-module-level-imports 禁止在 newton/_src 与 newton/tests 的模块顶层导入 mujoco、torch、trimesh、pyglet、viser 等重型库,这是 Newton 保持惰性导入(lazy import)策略的工程化保障。格式化方面,[tool.ruff.format] 指定双引号、空格缩进,并开启 docstring 内代码格式化。
拼写检查:typos 与误报处理
Newton 使用 typos 主动捕获拼写错误。typos 会扫描源码中的常见拼写错误,并已集成进 pre-commit 钩子,因此运行或安装 pre-commit 时,代码与文档中的拼写错误都会被标记;也可以手动运行 typos。
typos 偶尔会把项目专有术语、领域词汇或变量名误报为拼写错误。Newton 在仓库根目录 pyproject.toml 的 [tool.typos] 段中配置了三种处理方式:
- 文件排除:
files.extend-exclude忽略匹配的文件与目录,例如examples/assets以及*.urdf、*.usd、*.usda、*.mjcf、*.js等模型/资产文件类型; - 单词白名单:会被误报的单词或缩写列入
[tool.typos.default.extend-words](例如arange、precess、ba、HAA,以及 MuJoCo Menagerie 的品牌/产品名Pincher、Robotis、Iit等); - 标识符白名单:具体的变量或常量名可声明在
[tool.typos.default.extend-identifiers](例如PNGs、Haa、Wonik Allegro 手部关节名tha0~tha3等)。
当 typos 报告了一个在 Newton 代码库中合法的词,就把它加到 pyproject.toml 的对应段中以抑制后续警告;修改后重跑 typos(或 pre-commit)确认该词已被忽略。这样既保持代码库整洁,又为项目专属词汇保留了必要的灵活性。
许可证头规范
仓库中每个源文件都必须携带 2 行 SPDX 许可证头。项目采用 Apache-2.0 许可,许可证正文在仓库根目录 LICENSE.md,附加与第三方许可证文本放在 newton/licenses 目录,因此单个文件不再需要更多样板文本。头根据文件类型而不同:
# Python 文件(.py)—— Apache-2.0
# SPDX-FileCopyrightText: Copyright (c) <year> The Newton Developers
# SPDX-License-Identifier: Apache-2.0
.. 文档文件(.rst)—— CC-BY-4.0
.. SPDX-FileCopyrightText: Copyright (c) <year> The Newton Developers
.. SPDX-License-Identifier: CC-BY-4.0
# Jupyter notebooks(.ipynb)—— CC-BY-4.0,首格纯文本,无注释前缀
SPDX-FileCopyrightText: Copyright (c) <year> The Newton Developers
SPDX-License-Identifier: CC-BY-4.0
年份使用文件首次创建的年份:修改既有文件时不更新年份,也不使用年份区间——git 历史才是变更时间的权威记录。CI 工作流(pr_license_check.yml)通过 Apache SkyWalking Eyes 在每次 PR 上强制检查头。推送前也可以在本地用 Docker 运行许可证检查:
# 检查 Python 源码头(Apache-2.0)
docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header check
# 检查文档头(CC-BY-4.0)
docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes -c .licenserc-docs.yaml header check
从 pyproject.toml 可以看到,license-files = ["LICENSE.md", "newton/licenses/**/*.txt"] 会把许可证文件一并打包进发行物。
使用本地 Warp 安装
开发 Newton 时经常需要搭配本地构建的 Warp(例如调试 Warp 本身)。步骤如下:
uv venv
source .venv/bin/activate
uv sync --extra dev
uv pip install -e "warp-lang @ ../warp"
随后运行 python -m newton.examples basic_pendulum 时,Warp 的初始化消息会正确反映本地 Warp 安装,而非 lockfile 锁定的版本。
构建与本地预览文档
构建文档
先确保已安装文档依赖,再执行 Sphinx 构建:
# uv
rm -rf docs/_build
uv run --extra docs --extra sim sphinx-build -j auto -W -b html docs docs/_build/html
# venv
python -m pip install -e ".[docs]"
cd path/to/newton/docs && make html
构建产物位于 docs/_build/html。-W 将警告视为错误,-j auto 自动并行。注意:文档构建需要 pandoc 来转换 Jupyter notebooks。[docs] 依赖中包含 pypandoc_binary(见 pyproject.toml 的 docs extras),且 docs/conf.py 会在可用时自动使用其捆绑的 pandoc 可执行文件;若环境仍找不到 pandoc,需单独安装(Ubuntu/Debian:sudo apt-get install pandoc;macOS:brew install pandoc;Windows:可从 pandoc 官网下载或 choco install pandoc)。
本地服务文档
构建完成后,可用 docs/serve.py 脚本本地提供服务。这对于测试交互式特性尤其重要——教程 notebook 中的 Viser 3D 可视化需要正确的 WebAssembly 与 JavaScript 模块 MIME 类型。该脚本在 serve.py 中显式注册了 application/wasm、application/javascript 等 MIME 类型,并为响应添加 CORS 头。
# uv
uv run docs/serve.py
# venv
python docs/serve.py
然后在浏览器打开 http://localhost:8000。可以用 --port 指定自定义端口:
# uv
uv run docs/serve.py --port 8080
# venv
python docs/serve.py --port 8080
注意:直接用 Python 内置的 http.server 或直接双击打开 HTML 文件,都无法正确渲染交互式 Viser 可视化,因为它们缺少 serve.py 提供的 CORS 头与 MIME 类型。
文档版本化与部署
Newton 的文档按版本管理并托管在 GitHub Pages 上,多版本可同时访问,导航栏带版本切换下拉框。
工作原理
gh-pages 分支以子目录方式存放各版本文档:
/
├── index.html # 重定向到 /stable/
├── switcher.json # 下拉框的版本清单
├── stable/ # 最新发布版的副本
├── latest/ # main 分支的开发版文档
├── 1.1.0/ # 发布版本
└── 1.0.0/
两个 GitHub Actions 工作流负责部署:
docs-dev.yml:每次推送main分支时部署到/latest/;docs-release.yml:打版本标签时部署到/X.Y.Z/并更新/stable/。
部署文档
开发版文档在 main 分支有推送时自动部署。发布版文档在推送版本标签时部署:
git tag v1.0.0
git push origin v1.0.0
只有严格 semver 标签(vX.Y.Z)会触发发布部署;v1.0.0-rc.1 这类预发布标签会被忽略。
手动运维
移除某个版本(少见):检出 gh-pages 分支 → 删除对应版本目录 → 编辑 switcher.json 移除该条目 → 提交并推送。
重建全部文档(灾难恢复):逐个检出各版本标签,用 Sphinx 构建其文档,部署到 gh-pages 的对应目录;每完成一个版本后,用 scripts/ci/update_docs_switcher.py 更新 switcher.json。
API 文档的生成机制
source_code_guidelines.rst 定义了 canonical export 与 __all__ 的要求,API 参考文档正是由 Newton 公共模块的 __all__ 列表自动生成的。脚本 docs/generate_api.py 会生成 docs/api 下的 reStructuredText 文件,Sphinx 再通过 autosummary 为每个公开符号生成独立页面。
每当你增删或重命名某个公共模块(newton、newton.geometry、newton.solvers、newton.sensors 等)中的公共符号,都需要重新生成 API 页面:
# uv
uv run python docs/generate_api.py
# venv
python docs/generate_api.py
运行后按上文"构建文档"一节重新构建,验证结果。
重要约束:只有出现在 Newton 公共模块 __all__ 中的符号才算是受支持的公开 API。从 generate_api.py 的 public_symbols() 可以看出,docs/generate_api.py 会拒绝那些未将 __all__ 定义为 list 或 tuple 的模块,从而防止未声明的属性被意外发布为文档 API。因此,要把 newton/_src/ 下的用户可见符号作为公开 API 暴露,必须先通过其 canonical 公共模块导出,再生成 API 页面。
实验性功能标注
source_code_guidelines.rst 定义了实验性公共 API 的契约,要求在公开 docstring 或概念页中使用 .. experimental:: 指令。无正文时,该指令渲染 Newton 的标准提示:
.. experimental::
当整个模块、类、方法或函数都是实验性时使用此形式。对于稳定 API 中夹带的实验性行为,可加自定义内容指明确切范围:
Args:
contact_matching: Frame-to-frame contact matching mode.
.. experimental::
The ``"sticky"`` mode may change without prior notice.
记录实验性公共 API 时,状态表与摘要应保持简洁,直接用 experimental 之类的纯文本,而不要把每个状态标签都链接到标记;公共 API 符号变更后运行 uv run python docs/generate_api.py 重新生成。
测试文档中的代码片段:doctest
Sphinx 的 doctest builder 用于确保文档中的代码片段与时代同步。运行 doctest:
# uv
uv run --extra docs --extra sim sphinx-build -j auto -W -b doctest docs docs/_build/doctest
# venv
python -m sphinx -j auto -W -b doctest docs docs/_build/doctest
更多用法参见 sphinx.ext.doctest 的官方文档。
Changelog 片段规范
带用户可见变更的 PR 在 changelog 目录下添加片段文件,而不是直接编辑 CHANGELOG.md。有 issue 时用 GitHub issue 号作为标识符;没有 issue 时用以 + 开头的可读标识符加短随机后缀:
3607.added.md
3607.fixed.md
+camera-rays-a1b2c3d4.added.md
受支持的类别(渲染顺序)为:
- Added — 新特性;
- Changed — 既有功能的变更(需包含迁移指引);
- Deprecated — 将要移除的功能(需包含迁移指引,例如 "Deprecate
Model.geo_meshesin favor ofModel.shapes"); - Removed — 已移除的功能(需包含迁移指引);
- Fixed — 缺陷修复。
每个文件包含一条不带前导圆点的条目。使用祈使句现在时("Add X" 而非 "Added X"),以句号结尾,保持简洁。可选的单行 .skip 片段记录某项工作为何没有用户可见影响。多行条目、多类别、同类别计数器、创建命令以及 Towncrier 非变更的 --draft 预览等,详见 changelog/README.md。这些配置与 pyproject.toml 中 [tool.towncrier] 及五个 [[tool.towncrier.type]] 段落一一对应(directory = "changelog"、filename = "CHANGELOG.md"、ignore = ["*.skip"])。
编写示例
示例统一存放在 newton/examples/<category>/example_<category>_<name>.py(例如 example_basic_pendulum.py)。每个文件定义一个 Example 类,接口如下:
class Example:
def __init__(self, viewer, args):
"""Build the model, create solver/state/control, and set up the viewer."""
...
def step(self):
"""Advance the simulation by one frame (typically with substeps)."""
...
def render(self):
"""Update the viewer with the current state."""
...
def test_final(self):
"""Optionally validate the simulation state after the example completes."""
...
def test_post_step(self):
"""Optional per-step validation, called after every step() in test mode."""
...
每个示例必须实现 test_final() 或 test_post_step()(也可两者都实现)。测试模式下,test_post_step() 在每次仿真步进后运行,test_final() 在示例完成后运行。两个都未实现的示例会在 CI 中抛出 NotImplementedError——这一强制逻辑可在 newton/examples/init.py 的 run() 中看到:测试模式结束且既无 test_final 也无 test_post_step 时直接 raise NotImplementedError(...)。测试模式还会对 state_0/state_1/model/control/contacts 做 NaN 成员通用检查(find_nan_members),任何一个含 NaN 都会使测试失败。
发现与注册
示例是自动发现的:任何匹配 newton/examples/<category>/example_*.py 的文件都会被 newton/examples/init.py 的 get_examples() 拾取。命令行使用的短名是去掉 example_ 前缀与 .py 扩展名后的文件名(例如 basic_pendulum)。同时,新示例必须在示例 README 中注册:附上 python -m newton.examples <example_name> 命令和一张 320x320 的 jpg 截图。
运行与测试示例
# uv
uv run -m newton.examples --list # 列出所有可用示例
uv run -m newton.examples basic_pendulum # 按短名运行示例
uv run -m newton.examples basic_pendulum --viewer null --test # 无头测试模式(CI 使用)
# venv
python -m newton.examples --list
python -m newton.examples basic_pendulum
python -m newton.examples basic_pendulum --viewer null --test
示例运行器在 newton/examples/init.py 的 create_parser() 中提供了统一命令行参数,包括 --device、--viewer(gl/usd/rtx/rerun/null/viser)、--num-frames、--render-fps、--headless、--test、--benchmark、--warp-config KEY=VALUE 等;--warp-config 会校验 key 是否为 warp.config 的合法属性,并用 ast.literal_eval 解析值。
资产版本固定
多个 Newton 测试与示例依赖托管在独立 Git 仓库中的外部资产。为保证任何给定的 Newton 提交总是下载到相同版本的资产,每个仓库都被固定到具体的 commit SHA,固定版本以常量定义在 newton/_src/utils/download_assets.py:
NEWTON_ASSETS_REF——newton-assets仓库的固定 SHA;MENAGERIE_REF——mujoco_menagerie仓库的固定 SHA。
更新固定版本
当上游资产变更且需要采用新版本时:
- 从资产仓库查得新的 commit SHA;
- 更新
download_assets.py中对应的*_REF常量; - 运行完整测试套件,确认新资产不会破坏任何测试;
- 将 SHA 更新与测试调整一起提交。
覆盖固定版本
download_asset() 函数接受 ref 参数,可覆盖默认的固定 SHA。底层实现 download_git_folder()(同文件 download_assets.py)使用内容寻址目录缓存:每个缓存版本目录名包含 Git commit SHA 前缀,上游更新时 SHA 变化即生成新目录,无需原地驱逐;并带有 TTL(3600 秒)、父目录缓存优化、对临时性 Git 错误的指数退避重试(最多 3 次),以及通过 NEWTON_CACHE_PATH 环境变量或系统用户缓存目录决定缓存位置的能力。
Roadmap 与未来工作
官方文档中该小节目前是占位符(Placeholder),列出的方向包括:高级求解器耦合(Advanced solver coupling)、更全面的传感器模型(More comprehensive sensor models)、更丰富的机器人示例(Expanded robotics examples)。功能规划可关注上游 GitHub Discussions 与 Roadmap 看板。
基准测试:airspeed velocity(asv)
Newton 仓库内置一套基于 airspeed velocity 框架的基准测试套件,完整基准集预期在带 CUDA 能力 GPU 的机器上运行。基准配置见 asv.conf.json,基准定义位于 asv/benchmarks 目录(按 compilation / setup / simulation 组织,例如 bench_mujoco.py、bench_kamino.py)。
快速上手
先从 PyPI 安装 airspeed velocity:
python -m pip install asv
使用 uv 时可以避免把 asv 装进项目环境,直接:
uvx --with virtualenv asv run --launch-method spawn ...
如果本机尚未运行过 asv,需要先初始化:
asv machine --yes
在仓库根目录运行基准测试:
# Unix
asv run --launch-method spawn main^!
# Windows
asv run --launch-method spawn main^^!
注意:Windows CMD 中 ^ 是转义字符,必须写成 ^^ 才能按字面解释。该命令用 main 分支的代码状态运行 asv/benchmarks 目录下的基准定义;注意基准定义本身不会从不同分支检出,只有被基准化的代码会。
仿真基准指标
夜间机器人/策略仿真基准会从一次缓存的基准运行发布若干指标,覆盖 batched MuJoCo 与 Kamino KPI 负载、非策略 DR Legs 负载、预训练 Anymal 负载与 XPBD 四足负载。配套的 FastMetrics* 类复用既有聚合基准的工厂、场景、求解器与帧数。渲染、IK、逆动力学、CPU 后端回归、材质/接触微基准与启动基准不属于经验采集负载,不在该指标集内。
设 F 为所有样本中测量的帧数,S 为每帧物理子步数,W 为世界数,dt 为物理时间步(秒),T 为同步的完整步进墙钟时间(秒),T_physics 为负载同步的内部物理时间(秒)。报告的指标为:
- 平均 world-step 时间:带内部计时器的负载为
1000 * T_physics / (F * S * W)(单位ms/world-step),否则为1000 * T / (F * S * W); - 仿真吞吐量:
F * S * W / T(单位world-steps/s); - 实时因子:
F * S * W * dt / T; - p95 步进时间:同步完整步进时间的第 95 百分位(
ms/frame); - 稳态 GPU 内存(MiB);
- MuJoCo 求解器迭代次数:每个测量样本最后一帧、跨世界的均值与最大值。
既有 KPI 平均 world-step 序列保留 track_simulate 名称与定义,既有 time_simulate 聚合序列不变;world_count 仍是适用的 ASV 参数,sim_dt 与 sim_substeps 也作为 tracked 值记录,使仪表盘结果保留解读吞吐量与实时因子所需的配置。吞吐量、实时因子与 p95 指标对完整的 step() 操作计时并同步,包括其包含的策略或控制工作。
GPU 内存定义为:第一个 finalize 的负载创建前的基线 Device.free_memory,与初始化、CUDA graph 捕获及第一个完整测量样本完成之后(该样本负载仍存活时)的差值。这个设备级增量包含 Warp、PyTorch、求解器支撑与 CUDA graphs 的分配。由于是设备级测量,测量期间运行器必须独占 GPU;其余样本不影响该测量。如果最终仿真状态无效、物体旋转未归一化或超出负载的速度界限,基准会失败而非发布指标。
跨提交比较
基准还可以针对一段提交范围运行,用于比较多次近期变更间的性能:
# Unix / Windows
asv run --launch-method spawn HEAD~4..HEAD
注意较旧的提交必须放在前面。也可以用提交哈希代替相对引用:
asv run --launch-method spawn abc1234..def5678
独立运行基准文件
基准文件也可以不经过 asv harness 直接作为 Python 脚本运行——这便于开发期快速迭代,因为跳过了 asv 的环境搭建。每个 asv/benchmarks 下的基准文件都支持 --bench 标志选择特定基准类:
# uv
uv run python asv/benchmarks/simulation/bench_mujoco.py --bench FastAllegro
# venv
python asv/benchmarks/simulation/bench_mujoco.py --bench FastAllegro
省略 --bench 时运行文件中全部基准;--bench 可重复以选择多个:
uv run python asv/benchmarks/simulation/bench_mujoco.py --bench FastAllegro --bench FastG1
编写基准的提示
开发中的基准建议用 --bench BENCH, -b BENCH 过滤到只运行目标基准:
# Unix
asv run --launch-method spawn main^! --bench FastG1
# Windows
asv run --launch-method spawn main^^! --bench FastG1
最耗时的基准是那些测量"从空内核缓存开始加载并运行示例一帧"耗时的基准,其名字以 time_load 结尾。有时需要把它们排除掉:
# Unix
asv run --launch-method spawn main^! -b '^(?!.*time_load$).*'
# Windows
asv run --launch-method spawn main^^! -b "^^(?!.*time_load$).*"
虽然 asv 内置了自动确定收集方式的机制,但手动指定 repeat 与 number 属性来控制基准运行次数往往很有用:
class PretrainedSimulate:
repeat = 3
number = 1
按 asv 关于 benchmark attributes 的文档,setup 与 teardown 方法不会在构成一个 sample 的 number 次迭代之间运行。这些属性应调优到:基准在合理时间内跑完,同时运行足够次数以得到有统计意义的结果。--durations all 标志可传给 asv run 显示所有基准的耗时,便于发现某个基准耗时异常偏长。
发布流程
完整的发布工作流——包括分支策略、测试标准与发布步骤——见 release.rst。简单来说,发布版文档通过推送 vX.Y.Z 严格 semver 标签触发部署(见上文"文档版本化"一节),changelog 片段由 Towncrier 在发布分支上合并进 CHANGELOG.md。
总结
Newton 的开发者工作流是一套围绕 NVIDIA Warp 构建的完整工程体系:uv 提供可复现的依赖锁定,内置的并行测试运行器支撑数百个测试文件的快速回归,Ruff/typos/pre-commit 保障代码与文档质量,SPDX 头与 SkyWalking Eyes 守护许可证合规,Sphinx + GitHub Pages 支撑版本化文档发布,__all__ 驱动 API 文档自动生成,Towncrier 管理 changelog,示例的 Example 接口统一了仿真与 CI 验证,资产 SHA 固定保证可复现性,而 asv 基准套件则对 GPU 上的多求解器性能提供量化度量。掌握这套流程,即可顺畅地参与 Newton 的开发与贡献。