GitHub 提交活动 GitHub - CI

NVIDIA Warp

Warp 是一个用于编写高性能模拟和图形代码的 Python 框架。Warp 将普通的 Python 函数进行即时编译，转换为可在 CPU 或 GPU 上运行的高效内核代码。

Warp 专为空间计算而设计，它提供了一套丰富的原语，使得编写物理模拟、感知、机器人和几何处理程序变得简单。此外，Warp 内核是可微分的，可以作为机器学习管道的一部分与 PyTorch 和 JAX 等框架一起使用。

请参阅项目文档以获取 API 和语言参考，以及 CHANGELOG.md 了解发布历史。

<div align="center"> <img src="https://yellow-cdn.veclightyear.com/ab5030c0/9af0e1a1-9156-4955-b43f-f43cd89149e4.jpg"> <p><i>使用 Warp 计算的部分物理模拟示例</i></p> </div>

安装

推荐使用 Python 3.9 或更高版本。Warp 可以在 Windows、Linux 和 macOS 的 x86-64 和 ARMv8 CPU 上运行。GPU 支持需要 CUDA 兼容的 NVIDIA GPU 和驱动程序（最低要求为 GeForce GTX 9xx）。

安装 Warp 最简单的方法是从 PyPI 安装：

pip install warp-lang

您也可以使用 pip install warp-lang[extras] 来安装运行示例和 USD 相关功能所需的额外依赖项。

PyPI 上托管的二进制文件目前是使用 CUDA 12 运行时构建的，因此需要最低版本的 CUDA 驱动程序为 525.60.13（Linux x86-64）或 528.33（Windows x86-64）。

如果您需要在安装了较旧 CUDA 驱动程序的系统上使用 GPU 支持，可以从源代码构建 Warp，或从 GitHub Releases 页面安装使用 CUDA 11.8 运行时构建的 wheel 文件。复制适当的 wheel 文件（warp-lang-{ver}+cu12-py3-none-{platform}.whl）的 URL，并将其传递给 pip install 命令，例如：

平台	安装命令
Linux aarch64	`pip install https://github.com/NVIDIA/warp/releases/download/v1.3.1/warp_lang-1.3.1+cu11-py3-none-manylinux2014_aarch64.whl`
Linux x86-64	`pip install https://github.com/NVIDIA/warp/releases/download/v1.3.1/warp_lang-1.3.1+cu11-py3-none-manylinux2014_x86_64.whl`
Windows x86-64	`pip install https://github.com/NVIDIA/warp/releases/download/v1.3.1/warp_lang-1.3.1+cu11-py3-none-win_amd64.whl`

可能需要使用 --force-reinstall 选项来覆盖之前的安装。

CUDA 要求

使用 CUDA Toolkit 11.x 构建的 Warp 包需要 NVIDIA 驱动程序 470 或更高版本。
使用 CUDA Toolkit 12.x 构建的 Warp 包需要 NVIDIA 驱动程序 525 或更高版本。

这适用于在 PyPI 和 GitHub 上分发的预构建包，以及从源代码构建 Warp 时。

请注意，使用 --quick 标志构建 Warp 会改变驱动程序要求。快速构建会跳过 CUDA 向后兼容性，因此最低要求的驱动程序由 CUDA Toolkit 版本决定。请参考最新的 CUDA Toolkit 发行说明，以找到不同 CUDA Toolkit 版本的最低要求驱动程序（例如，CUDA Toolkit 12.5 的这个表格）。

Warp 在初始化过程中会检查已安装的驱动程序，如果驱动程序不合适，将报告警告，例如：

Warp UserWarning:
   CUDA 驱动程序版本不足。
   最低要求的 CUDA 驱动程序版本是 12.0，但已安装的 CUDA 驱动程序版本是 11.8。
   请访问 https://github.com/NVIDIA/warp/blob/main/README.md#installing 获取指导。

这将导致 CUDA 设备不可用，但仍可以使用 CPU。

要解决这个问题，有以下几个选项：

更新驱动程序。
安装兼容的预构建 Warp 包。
使用与已安装驱动程序兼容的 CUDA Toolkit 从源代码构建 Warp。

入门

下面是一个计算随机 3D 向量长度的示例程序：

import warp as wp
import numpy as np

num_points = 1024

@wp.kernel
def length(points: wp.array(dtype=wp.vec3),
           lengths: wp.array(dtype=float)):

    # 线程索引
    tid = wp.tid()
    
    # 计算每个点到原点的距离
    lengths[tid] = wp.length(points[tid])


# 分配一个 3D 点数组
points = wp.array(np.random.rand(num_points, 3), dtype=wp.vec3)
lengths = wp.zeros(num_points, dtype=float)

# 启动内核
wp.launch(kernel=length,
          dim=len(points),
          inputs=[points, lengths])

print(lengths)

运行示例

warp/examples 目录下包含了多个子目录，其中包含了一些脚本，展示了如何使用 Warp API 实现各种模拟方法。大多数示例会在当前工作目录中生成包含时间采样动画的 USD 文件。在运行示例之前，用户应确保已安装 usd-core、matplotlib 和 pyglet 包，可以使用以下命令安装：

pip install warp-lang[extras]

这些依赖项也可以手动安装：

pip install usd-core matplotlib pyglet

可以通过命令行运行示例，如下所示：

python -m warp.examples.<example_subdir>.<example>

要浏览示例源代码，可以像这样打开文件所在的目录：

python -m warp.examples.browse

大多数示例可以在 CPU 或 CUDA 兼容设备上运行，但有少数示例需要 CUDA 兼容设备。这些示例在脚本顶部有标记。

USD 文件可以在 NVIDIA Omniverse、Pixar 的 UsdView 和 Blender 中查看或渲染。请注意，不建议在 macOS 上使用 Preview，因为它对时间采样动画的支持有限。

可以通过命令行运行内置单元测试，如下所示：

python -m warp.tests

warp/examples/core

<table> <tbody> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_dem.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/d8ee5ba2-0b53-497b-80fa-5dd7d27ba67e.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_fluid.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/bdcead1d-751e-478a-850a-598c0392f91b.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_graph_capture.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/b2050b1a-09c4-4b84-bda6-337f044d4637.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_marching_cubes.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/3b434a02-0119-4e15-a074-bbf4eddc58bc.png"></a></td> </tr> <tr> <td align="center">离散元方法</td> <td align="center">流体</td> <td align="center">图捕获</td> <td align="center">移动立方体</td> </tr> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_mesh.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/bbe3c983-3a33-469f-9a2d-dc4db6243174.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_nvdb.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/3bc8bebc-1ebf-46dc-b8a1-03ba75d85e23.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_raycast.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/12ff45d9-c5c7-4d30-a133-f157b75a0da3.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_raymarch.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/3a8263ed-9a7e-4d58-9a92-74e505b823cc.png"></a></td> </tr> <tr> <td align="center">网格</td> <td align="center">NVDB</td> <td align="center">光线投射</td> <td align="center">光线行进</td> </tr> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_sph.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/4e5374e9-ab4b-449c-84e4-e22cb11eb970.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_torch.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/b04efc27-fb3e-4e8c-a56c-14724cc2170b.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/core/example_wave.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/89863111-4216-4b56-9275-3af008a6227e.png"></a></td> <td></td> </tr> <tr> <td align="center">光滑粒子流体动力学</td> <td align="center">PyTorch</td> <td align="center">波</td> <td align="center"></td> </tr> </tbody> </table>

warp/examples/fem

<table> <tbody> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_diffusion_3d.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/882e0bdd-0d62-4efd-817e-28f596bc9038.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_mixed_elasticity.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/39d238ca-1c9f-4c8e-a280-a714b61bdc4b.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_apic_fluid.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/f3a0d934-b013-442e-b175-361ed6a1665f.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_streamlines.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/711114aa-d7fe-4081-827a-3a544f869bdd.png"></a></td> </tr> <tr> <td align="center">三维扩散</td> <td align="center">混合弹性</td> <td align="center">APIC流体</td> <td align="center">流线</td> </tr> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_convection_diffusion.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/8c906e8b-e76f-4752-a463-12f92e191f1a.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_navier_stokes.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/1fe566ec-3e5f-4ebb-b3c7-e27b09dd9588.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_burgers.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/c84ebb84-1bca-4a3b-bf4d-44e46e73422e.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/fem/example_magnetostatics.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/4458399d-9d82-4bc1-9a05-aabc705b081c.png"></a></td> </tr> <tr> <td align="center">对流扩散</td> <td align="center">纳维-斯托克斯方程</td> <td align="center">伯格斯方程</td> <td align="center">磁静力学</td> </tr> </tbody> </table>

warp/examples/optim

<table> <tbody> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_bounce.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/1a0ed0d3-f99d-4c64-8727-eb3031de5dde.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_cloth_throw.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/58de2ecd-adaf-4ed9-bd93-ca051c92a608.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_diffray.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/da5d7900-91a0-4d42-b9b4-3c0d678aeff4.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_drone.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/32561d3c-f94f-4400-b675-94b2f106c8da.png"></a></td> </tr> <tr> <td align="center">弹跳</td> <td align="center">布料投掷</td> <td align="center">差分光线追踪</td> <td align="center">无人机</td> </tr> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_inverse_kinematics.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/f7bf56e6-555b-4089-872c-52dda8051605.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_spring_cage.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/d20e3404-a2fe-43ff-bd20-214c7a582b8c.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_trajectory.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/4c693de5-7d77-424b-b90c-98c756650a4f.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/optim/example_walker.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/e164dd8a-478a-4ff9-8adb-8e8dc6243ac4.png"></a></td> </tr> <tr> <td align="center">逆向运动学</td> <td align="center">弹簧笼</td> <td align="center">轨迹</td> <td align="center">步行机</td> </tr> </tbody> </table>

warp/examples/sim

<table> <tbody> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_cartpole.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/381a2a79-26e9-435a-80a2-4be1c27614f4.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_cloth.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/8a0721b4-dc1f-45b1-8d5a-f03a00591fd5.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_granular.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/b19c6a33-d804-4a66-aa0e-82bb1b20385b.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_granular_collision_sdf.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/626844c4-6920-47eb-aa66-4ae391db553a.png"></a></td> </tr> <tr> <td align="center">倒立摆</td> <td align="center">布料</td> <td align="center">颗粒</td> <td align="center">颗粒碰撞SDF</td> </tr> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_jacobian_ik.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/60979b71-0553-4ac1-adc1-d363c51ce550.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_quadruped.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/ac363370-e96f-4675-9491-de91a7d8eb8a.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_rigid_chain.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/d134583e-e6b7-4eb3-bb89-08ba8ffc0bd3.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_rigid_contact.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/4ca2c9aa-f6b3-4080-8c1b-03a55baaf70c.png"></a></td> </tr> <tr> <td align="center">雅可比逆向运动学</td> <td align="center">四足机器人</td> <td align="center">刚体链</td> <td align="center">刚体接触</td> </tr> <tr> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_rigid_force.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/193394f0-237b-42d0-8be5-b845093cbe56.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_rigid_gyroscopic.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/acd580cd-dc58-4f2d-9446-a0b0a74c266c.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_rigid_soft_contact.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/16bc122a-91cb-4c3d-9e9d-77494400bca6.png"></a></td> <td><a href="https://github.com/NVIDIA/warp/tree/main/warp/examples/sim/example_soft_body.py"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/58893351-0108-4726-be36-0f73fd88e793.png"></a></td> </tr> <tr> <td align="center">刚体力</td> <td align="center">刚体陀螺效应</td> <td align="center">刚体软体接触</td> <td align="center">软体</td> </tr> </tbody> </table>

构建

对于想要自行构建库的开发者，需要以下工具：

Microsoft Visual Studio 2019或更高版本（Windows）
GCC 9.4或更高版本（Linux）
CUDA Toolkit 11.5或更高版本
安装Git LFS

克隆仓库后，用户应运行：

python build_lib.py

成功后，脚本将在warp/bin/目录下输出特定平台的二进制文件。构建脚本将在默认安装路径中查找CUDA Toolkit。可以通过设置CUDA_PATH环境变量来覆盖此路径。或者，可以通过--cuda_path="..."将CUDA Toolkit的路径传递给构建命令。构建完成后，应使用以下命令安装Warp包：

pip install -e .

这确保了对库的后续修改将反映在Python包中。

了解更多

请参阅以下资源以获取有关Warp的更多背景信息：

Warp中的底层技术已在NVIDIA的多个研究项目中使用，包括以下出版物：

基于并行可微分仿真的加速策略学习 - Xu, J., Makoviychuk, V., Narang, Y., Ramos, F., Matusik, W., Garg, A., & Macklin, M. (2022)
DiSECt：用于机器人切割的可微分仿真器 - Heiden, E., Macklin, M., Narang, Y., Fox, D., Garg, A., & Ramos, F (2021)
gradSim：用于系统识别和视觉运动控制的可微分仿真 - Murthy, J. Krishna, Miles Macklin, Florian Golemo, Vikram Voleti, Linda Petrini, Martin Weiss, Breandan Considine 等 (2021)

常见问题

请参阅Warp文档中的常见问题。

支持

问题、疑问和功能请求可以在GitHub Issues上提出。

Warp团队也会关注公共Omniverse Discord服务器上的**#warp**频道，欢迎与我们交流！

版本控制

版本格式为X.Y.Z，类似于Python本身：

X的增加保留用于项目的重大改造，可能导致不兼容性（或达到1.0里程碑）。
Y的增加用于具有新功能集的常规发布。
Z的增加用于错误修复。原则上不会有新功能。如果为0或不相关，可以省略。

这类似于语义化版本控制，但对向后兼容性的要求不那么严格。与Python一样，如果有充分的文档说明并逐步引入，次要版本之间可能存在一些破坏性变更。

请注意，在0.11.0版本之前，并未严格遵守此模式。

许可证

Warp根据NVIDIA软件许可证提供，请参阅LICENSE.md获取完整的许可证文本。

贡献

欢迎社区成员提供贡献和拉取请求，这些贡献和请求将根据LICENSE.md中反馈部分描述的条款接受。 CONTRIBUTING.md提供了有关如何为Warp开启拉取请求的其他信息。

引用

如果您在研究中使用Warp，请使用以下引用：

@misc{warp2022,
title= {Warp: 用于GPU仿真和图形的高性能Python框架},
author = {Miles Macklin},
month = {3月},
year = {2022},
note= {NVIDIA GPU技术大会（GTC）},
howpublished = {\url{https://github.com/nvidia/warp}}
}