Newton 项目 Kamino 求解器单元测试完全指南CLI 与 VS Code 运行配置详解【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton导读本文围绕 Newton 开源物理仿真引擎中 Kamino 求解器SolverKamino的单元测试体系系统讲解如何在命令行与 VS Code / Cursor 集成开发环境中发现、运行和调试 Kamino 测试。Kamino 是 Newton 内部用于仿真具有运动学闭环、欠驱动/过驱动特性的任意机械装配体的物理求解器其测试代码同时分布在内部辅助模块与公共集成测试两个位置。阅读本文后你将掌握python -m unittest discover的完整用法、VS Code 测试资源管理器Test Explorer的配置方法以及测试基础设施全局TestContext、setup_tests、统一测试入口__main__.py背后的实现原理能够在自己机器上复现并扩展 Kamino 的测试流程。一、Kamino 测试体系概览Kamino 求解器位于 newton/_src/solvers/kamino其单元测试并不只有一处。从 测试入口__main__.py的源码注释可以明确看到Kamino tests live in two locations: internal (private helpers) and undernewton/tests/kamino(public-facing / integration).也就是说测试被刻意拆分为两个目录测试位置内容定位相对路径内部单元测试测试 Kamino 私有辅助模块线性代数工具、控制工具、日志、随机数、Simulator 工具类等newton/_src/solvers/kamino/tests公共集成测试测试 Kamino 对外暴露的模型、几何、运动学、动力学、求解器行为newton/tests/kamino内部测试目录当前包含 9 个测试模块test_*.py覆盖范围从 线性代数矩阵/随机工具 到 高层 Simulator 工具类 不等。公共测试目录则覆盖了关节、材质、形状、Delassus 动力学、几何接触、运动学雅可比、关节限位、线性代数 LLT 分解、DVI/PADMM 求解器、前向运动学、传感器 IMU 等 40 余个测试模块例如 test_kamino_solver_padmm.py 与 test_kamino_solver_kamino.py。Kamio 模块的 README 也说明这些测试最终会逐步迁移并入newton/tests主测试集合。二、命令行CLI运行方式2.1 激活 Python 环境首先需要启用 Kamino 开发所需的 Python 环境conda、virtualenv、uv均可。以pyenvvirtualenv为例pyenv activate newton-dev2.2 切换到测试目录cd path-to-parent-dir/newton/newton/_src/solvers/kamino/tests2.3 运行 unittest 测试发现python -m unittest discover -s . -p test_*.py这条命令的参数含义如下-m unittest以模块方式调用 Python 标准库的unittest测试框架无需额外安装第三方测试工具discover启用测试自动发现机制递归扫描指定目录-s .--start-directory指定起始扫描目录为当前目录即kamino/tests-p test_*.py--pattern只匹配以test_开头、.py结尾的文件从而过滤掉__init__.py、__main__.py等非测试文件。需要特别说明这条命令只会发现并运行内部测试目录下的用例。若希望同时运行位于 newton/tests/kamino 的公共集成测试推荐直接使用仓库自带的统一测试入口见下文「统一测试入口」一节。三、VS Code及 Cursor集成运行方式如果希望在 IDE 内利用内置的单元测试发现系统参考 VS Code 官方 Python Testing 文档可按以下步骤配置。3.0 以可编辑模式安装 Newton如已安装可跳过cd path-to-parent-dir/newton pip install -e .[dev,data,docs]可编辑安装-e确保对源码的修改即时生效是 Kamino 这类持续演进求解器的推荐安装方式dev、data、docs三个 extra 分别提供开发工具、数据资产与文档构建依赖。3.1 在 VS Code / Cursor 中打开 Kamino 目录cd path-to-parent-dir/newton/newton/_src/solvers/kamino code .在 Kamino 目录下打开 IDE是为了让 VS Code 的 Python 扩展以该目录为工作区根从而正确解析测试文件夹的相对位置。3.2 创建.vscode/settings.json在newton/newton/_src/solvers/kamino下创建.vscode/settings.json内容如下{ python.testing.unittestArgs: [ -v, -s, ./tests, -p, test_*.py ], python.testing.pytestEnabled: false, python.testing.unittestEnabled: true }各配置项说明python.testing.unittestArgs传递给unittest发现机制的参数。-v开启详细输出-s ./tests指定从 Kamino 目录下的tests子目录开始扫描-p test_*.py限定匹配模式与 CLI 方式的发现规则保持一致python.testing.pytestEnabled: false显式禁用 pytest 发现避免两套框架产生冲突python.testing.unittestEnabled: true启用内置的 unittest 发现与运行。3.3 触发测试发现通过ctrl/cmd shift P打开命令面板输入并执行Testing: Focus on Test Explorer View3.4 运行测试测试发现完成后测试层级右侧会显示绿色播放按钮点击即可自动启动对应的测试集可按模块、类或单个用例粒度运行。同时 VS Code 也支持断点调试在测试函数内打断点后选择 Debug Test 即可进入调试会话这对排查 Kamino 求解器数值问题非常有用。注意VS Code 的测试发现默认同样只覆盖 Kamino 内部tests/目录。若需在 IDE 中运行公共集成测试可将-s指向仓库级测试目录或在 VS Code 中直接打开仓库根目录。四、测试基础设施源码解析4.1 全局测试上下文TestContextnewton/_src/solvers/kamino/tests/init.py 定义了一个模块级共享的TestContextdataclass用于在所有测试模块间传递全局状态setup_done全局测试初始化是否已执行避免重复初始化verbose全局默认详细输出开关device全局默认计算设备wp.DeviceLike默认取自 Warp 的设备output_path测试可选输出如perfprof.csv的缓存目录指向tests/output并会在setup_tests中自动创建。测试用例中常见的if not test_context.setup_done: setup_tests(clear_cacheFalse)模式正是依赖该上下文保证 Warp 与 NumPy 只被初始化一次。4.2 全局初始化setup_testssetup_tests(verbose, device, clear_cache)承担测试前的全局环境配置调整 NumPy 打印选项linewidth、edgeitems、threshold、precision10、suppressTrue抑制科学计数法便于比对数值输出配置 Warpwp.init()、wp.config.mode release、enable_backward False、verify_fp False、verify_cuda False即关闭反向传播与逐运算校验以追求测试运行性能当clear_cacheTrue时调用wp.clear_kernel_cache()与wp.clear_lto_cache()强制重编内核在内核代码变更后非常有用通过wp.get_device(device)解析目标设备并写入test_context.device。4.3 统一测试入口__main__.py除逐模块运行外Kamino 还提供了覆盖全部测试的统一入口 tests/main.py可直接以如下方式运行cd path-to-parent-dir/newton/newton/_src/solvers/kamino/tests python -m unittest或将tests目录加入PYTHONPATH后执行python -m tests。该入口支持三个命令行参数参数默认值说明--devicecuda指定计算设备例如--device cpu或--device cuda:0--clear-cache/--no-clear-cacheFalse是否在运行前清空 Warp 内核/LTO 缓存--verbose/--no-verboseFalse是否打印详细测试输出其执行逻辑为先分别调用内部测试与公共测试的setup_testsnewton.tests.kamino下也有同名函数再以仓库根目录为top_level_dir同时从tests内部与newton/tests/kamino公共两个目录执行unittest.TestLoader().discover最后用自定义的ModuleHeaderTestRunner统一运行。该 Runner 重写了TextTestResult.startTest每当切换到新的测试模块时会打印类似 Running tests in: newton/_src/solvers/kamino/_src/utils/... 的分隔头方便在海量输出中定位失败用例所属模块。这也从实现层面印证了「测试位于两处、需合并运行」的设计。五、测试用例组织与数值验证示例Kamino 测试普遍遵循「构建模型 → 逐步仿真 → 数值断言」的模式。以 test_utils_sim_simulator.py 为例在setUp中调用setup_tests(clear_cacheFalse)并按verbose开关设置日志级别msg.set_log_level(msg.LogLevel.DEBUG)其余用例通过test_context.verbose共享该设置test_01_step_multiple_cartpoles_all_from_initial_state先构建单个 cartpole 模型并仿真 1000 步再把同一个 builder 用builder_multi.add_world(builder_single)复制 42 份构建多实例模型最后用np.testing.assert_allclose断言多实例仿真结果与单实例结果逐位一致test_02_step_multiple_cartpoles_reset_all_from_sampled_states则演示了「采样状态 → 通过state_0.assign(...)/multi_sim.data.state_n.copy_from(state_0)注入 → 单步推进 → 断言结果一致」的确定性重放验证流程其中还覆盖了lambda_kin_j、lambda_dyn_j、lambda_f_j、lambda_tau_j等约束乘子状态的采样与恢复。这些用例一方面验证了 KaminoSimulator在多实例multi-world场景下与单实例逐位等价bit-exact equivalence另一方面也为「如何为求解器编写确定性测试」提供了可直接套用的范本。此外测试还大量使用 Warp 内核做自定义控制注入例如_test_control_callback通过wp.launch按wp.tid()获取世界索引、按时间窗给关节施加外部力矩再经sim.set_control_callback(...)挂载到仿真循环中——这是 Kamino 面向 RL/控制应用的重要测试模式。六、运行前置条件与注意事项6.1 安装要求Newton 需以可编辑模式从源码安装pip install -e .[dev,data,docs]见上文 3.0 节Kamino 依赖 Warp 的最新特性建议使用 Warp nightly 构建pip install warp-lang --pre -U -f https://pypi.nvidia.com/warp-lang/或从源码安装main分支Kamino 求解器的默认目标设备为 CUDA__main__.py中--device默认cuda无 GPU 环境时可显式传--device cpu运行但部分大规模用例的耗时与行为可能不同Linux 平台还需安装 X11 与 Mesa 基础库libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl1-mesa-dev具体可见 Kamino README 的 Development 章节。6.2 内核缓存Warp 采用 JIT 编译首次运行会编译大量 CUDA 内核耗时较长属正常现象若修改了 Warp 内核或底层依赖版本建议在运行测试时启用--clear-cache以清除过期缓存避免使用陈旧编译产物导致结果异常。6.3 关于 Kamino 的稳定性状态需要提醒的是Kamino 目前处于BETA 1阶段其 README 明确建议普通用户暂勿依赖它社区贡献也暂不接收更稳定的BETA 2计划于 2026 年夏季发布。因此运行其测试时应以「理解算法与验证行为」为目的并将其视为 Newton 主求解器之外的可选实验性组件。七、总结快速上手CLI激活虚拟环境 → 进入newton/_src/solvers/kamino/tests→python -m unittest discover -s . -p test_*.py覆盖全部测试内部 公共集成使用 tests/main.py 统一入口并可通过--device、--clear-cache、--verbose控制运行行为IDE 集成VS Code / Cursor在 Kamino 目录创建.vscode/settings.json启用 unittest 发现再通过 Test Explorer 视图的播放按钮按需运行理解测试基础设施全局TestContext与setup_testsNumPy/Warp 配置、缓存清理、设备解析保证了测试的一致性而多实例逐位等价断言与采样重放是 Kamino 测试的核心验证手段。掌握这套流程后无论是快速回归验证、在内核改动后强制重编缓存还是利用 VS Code 断点调试定位数值问题都能在 Kamino 求解器上顺畅开展。【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
