Warp 顶层 Python API 全景指南数据模型、内核编程、设备管理与跨框架互操作【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp本指南围绕 docs/api_reference/warp.rst 这份 Warp 顶层 API 参考索引展开系统梳理import warp后暴露的全部公开接口从标量/向量/矩阵等数据模型、array数组体系与空间加速结构到wp.kernel内核编程、wp.launch执行、wp.Tape自动微分再到设备、模块、CUDA 流/事件/内存/图管理以及 NumPy、JAX、PyTorch、Paddle、DLPack 等互操作层。读完本文你将掌握 Warp 公共 API 的完整分类脉络与核心函数签名并能基于源码定位每个 API 的实现位置快速上手 GPU 加速的仿真与机器学习编程。从 warp.rst 说起Warp 顶层 API 的组织方式warp.rst是 Sphinx 自动文档生成的顶层 API 索引页它通过两套机制把 warp/init.py 中暴露的所有公开符号组织成文档automodule:: warp直接引用包模块读取warp/__init__.py顶部 docstring 中的包级描述——该描述明确了 Warp 的定位提供在 CPU 与 CUDA 设备上创建和操作多维数据的数组类型与函数包含用于定义并行代码的内核/函数装饰器kernel、func以及一套完整的内置类型与函数见 内置函数语言参考。各分类小节使用autosummary指令生成指向每个符号独立文档页的链接列表。Warp 的顶层__init__.py本身就是一张公开 API 地图文件按# category:注释把from warp._src.* import ...语句分成与warp.rst完全对应的章节每个公开符号都标注了它在内部_src包中的真实来源。例如kernel、launch、get_device来自warp._src.contextvec3f、array来自warp._src.typesTape来自warp._src.tapeTexture2D来自warp._src.texture。这意味着本文列出的所有 API 都能在源码中一一对位是学习 Warp 内部实现的最佳索引。子模块体系自动可用与显式导入warp.rst将子模块分为两类规则很简单自动可用import warp后即可访问warp.build_experimental—— 外部构建扩展对应 warp_build_experimental APIwarp.config—— 全局编译/运行配置对应 warp.config API配置项详解见 配置指南warp.types—— 类型工具对应 warp.types APIwarp.utils—— 通用工具对应 warp.utils API显式导入需要import warp.autograd等warp.autogradAPI、warp.fem有限元API、warp.geometryAPI、warp.optimAPI、warp.render可视化API、warp.sparse稀疏线性代数API显式导入的子模块并非散落各处而是在warp/__init__.py开头的_register_module_source()调用中统一注册如(warp.fem, warp._src.fem)由内部module_registry保证内核/结构体/函数归属到正确的公开模块名下。类型注解与标量数据类型类型注解warp.rst的 Type Annotations 小节收录了 5 个用于类型标注的符号DeviceLike、Float、Int、Scalar、ref。从源码看DeviceLike来自warp._src.context是设备标识的注解类型允许设备参数同时接受字符串如cpu、cuda:0或Device对象——get_device(ident: DeviceLike None)的签名即为其典型用法。Float、Int、Scalar来自warp._src.types用于在 Python 侧注解泛型化的 Warp 代码。ref表示内核参数按引用传递对应wp.ref引用类型相关行为可参考 warp/tests/test_ref.py。标量类型Data Types Scalars 一节定义了 Warp 内核中可用的全部 13 种标量类型全部在 warp/_src/types.py 中实现类型说明类型说明bool布尔float16半精度浮点int8/uint88 位有/无符号整数float32单精度浮点默认int16/uint1616 位有/无符号整数float64双精度浮点int32/uint3232 位有/无符号整数bfloat16Brain 浮点int64/uint6464 位有/无符号整数handle不透明句柄类型向量、矩阵、四元数与变换向量vec2 / vec3 / vec4 与精度后缀向量类型按维度 元素类型后缀命名__init__.py的导入块完整覆盖了后缀矩阵后缀元素类型示例b/ubint8 / uint8vec3b、vec3ubs/usint16 / uint16vec3s、vec3usi/uiint32 / uint32vec3i、vec3uil/ulint64 / uint64vec3l、vec3ulhfloat16vec3hffloat32vec3f默认别名dfloat64vec3d不带后缀的vec2、vec3、vec4是 float32 的别名。矩阵、四元数与变换矩阵mat22、mat33、mat44及其h/f/d精度变体构造函数matrix_from_cols、matrix_from_rows按列/按行构造矩阵。四元数quat、quath、quatf、quatd以及工具函数quat_between_vectors计算两个向量之间的旋转四元数实现在 warp/_src/utils.py。变换transform系列transformh/f/d表示位置 四元数的刚体变换transform_expand用于展开变换参数。空间向量与矩阵spatial_vector、spatial_matrix系列用于刚体动力学等场景中的 6 维空间向量/矩阵运算。数组体系array、索引数组与 tile数组类型与工厂函数Arrays 小节是 Warp 数据流的核心。类型层面有array、array1d~array4d维度别名与fixedarray固定长度数组工厂函数层面有zeros/ones/full/empty及其*_like变体依据现有数组推断 shape/dtype/deviceclone深拷贝数组、copy拷贝数据到目标数组from_ptr从裸内存指针构造数组。源码warp/_src/types.py明确标注该方法已废弃建议改用array构造器并传入ptruint64 内存地址参数。这些工厂函数实现在 warp/_src/context.py 中与设备上下文强耦合——数组必然归属于某个Device。索引数组与 tileindexedarray/indexedarray1d~indexedarray4d元素本身是数组的数组支持数据相关的间接索引访问。tile与tile_stack面向 GPU 分块tile编程的栈式数据结构是 Warp tile 语言launch_tiled、wp.tile_matmul等的基础相关示例见 asv/benchmarks/tile/ 与 warp/tests/test_array.py。空间加速结构Spatial Acceleration 小节把仿真常用的空间数据结构统一收进顶层命名空间Bvh层次包围盒BvhQuery/BvhQueryTiled查询句柄GPU 构建可走 cuBQL见 warp/native/bvh.cu 与 warp/native/cuBQL/HashGrid均匀哈希网格HashGridQuery实现见 warp/native/hashgrid.cppMesh三角网格MeshQuery及MeshQueryAABB/AABBTiled/Point/Ray等各类查询见 warp/native/mesh.cppVolumeOpenVDB 风格体素场见 warp/native/volume.cpp这些类型既可在 Python 侧构建也能在 kernel 内部被查询配合 warp/tests/test_spatial.py 可以了解典型用法。纹理系统Textures 小节来自 warp/_src/texture.pyTexture、Texture1D、Texture2D、Texture3D一/二/三维纹理对象TextureAddressMode寻址模式、TextureFilterMode过滤模式、TextureResourceFlags资源标志三个枚举GLTextureResource与 OpenGL 纹理资源互操作对应 warp/_src/render/render_opengl.py 的可视化管线运行时初始化与诊断Runtime 小节提供了生命周期与可用性检查函数init()任何其他 API 调用之前必须调用源码 warp/_src/context.py 明确This function must be called before any other API call。launch()等函数内部会自动调用init()兜底若warp.config.track_memory为 Trueinit()还会自动启用全局内存跟踪。is_cpu_available()判断 CPU 执行是否可用等价于 LLVM 后端是否加载runtime.llvm is not None。is_cuda_available()判断是否存在 CUDA 设备get_cuda_device_count() 0。is_cubql_available()判断 cuBQL BVH 构建器是否可用。print_diagnostics()打印 Warp 构建与运行环境的完整快照Python/原生库版本、LLVM/Clang 版本、可选互操作框架版本等返回包含全部信息的 dict便于调试与提交 bug 报告自 1.12.0 引入。clear_kernel_cache()/clear_lto_cache()清空编译缓存实现在 warp/_src/build.py。内核编程wp.kernel 与函数装饰器Kernel Programming 小节是编写 GPU 代码的入口。核心装饰器kernel的完整签名源码 warp/_src/context.pydef kernel( fNone, *, nameNone, # 自定义内核注册名须为合法 C 标识符 enable_backwardNone, # False 时不生成反向传播代码 launch_boundsNone, # CUDA __launch_bounds__int 或 (maxThreadsPerBlock, minBlocksPerMultiprocessor) cuda_max_registersNone, # CUDA __maxnreg__不能与 launch_bounds 同时使用 enable_cuda_smem_spillingNone, # CUDA 13 允许用共享内存承接寄存器溢出 cluster_dimNone, # 线程簇维度 moduleNone, # 归属模块unique 表示创建独占新模块 module_optionsNone, # 模块级编译选项如 {fast_math: True} entry_point_abiNone, # warp 或 external_constant_params grid_strideNone, # 是否生成 grid-stride 循环配合 launch 的 max_blocks )最基本的用法要求函数对所有参数做类型注解、且不返回任何值import warp as wp wp.kernel def add_kernel(a: wp.array[float], b: wp.array[float]): tid wp.tid() b[tid] a[tid] 1.0同组还包括函数装饰器func可被内核调用的 Warp 函数、func_grad自定义梯度、func_native、func_replay、grad在 Python 中调用可微函数并取梯度、overload类型重载、static编译期静态分支、struct自定义结构体类型mapwarp/_src/utils.py 的 Python 侧数组映射、address_of取数组元素地址、constant编译期常量声明源码 warp/_src/types.py 限定只接受内置数学类型代码生成错误类型WarpCodegenError及其子类WarpCodegenAttributeError/IndexError/KeyError/TypeError/ValueError来自 warp/_src/codegen.py用于捕获内核编译阶段的诊断信息内核执行launch、launch_tiled 与同步wp.launch 参数详解launch是 Warp 执行内核的统一入口源码 warp/_src/context.py启动相对于 Python 调用线程是异步的def launch( kernel, # 被 wp.kernel 装饰的内核函数 dim, # 线程数int 或最多 4 维的序列 inputs[], outputs[], # 输入/输出参数 adj_inputs[], adj_outputs[], # 反向传播伴随参数 deviceNone, # 目标设备 streamNone, # 目标流指定后 device 取自 stream.device adjointFalse, # 是否运行反向通道 record_tapeTrue, # 是否记录到全局 Tape record_cmdFalse, # True 时返回 Launch 对象需手动调用 Launch.launch() max_blocks0, # 最大 CUDA 线程块数依赖 grid-stride 循环 block_dim256, # 每块线程数CPU 设备恒为 1 )值得注意的实现细节launch()会自动调用init()若传入 stream 则设备取stream.device。泛型内核generic kernel会在 launch 时根据实参推断具体重载kernel.infer_argument_types。print_launchesTrue时每次 launch 都会打印内核名、维度、参数与设备。跨设备数组访问默认不做检查LaunchArrayAccessMode.RELAXED可设置wp.config.launch_array_access_mode为CHECKED在 launch 前检测已知非法访问或STRICT强制要求所有数组参数都分配在启动设备上。其他执行 APIlaunch_tiled以分块tile方式启动用于 tile 语言内核。synchronize()等待所有设备上的内核执行完毕。get_suggested_block_size/get_cuda_kernel_properties查询建议块大小与 CUDA 内核属性。Kernel、Function、Launch、Module、ModuleBuildOptions执行相关的对象类型其中Module承载编译产物ModuleBuildOptions描述模块级编译选项如fast_math、enable_backward、lineinfo等可结合 配置指南 理解。自动微分wp.TapeAutomatic Differentiation 小节只有一个类Tapewarp/_src/tape.py它是 Warp 反向模式自动微分的核心tape wp.Tape() # 前向传播在 tape 上下文中记录 kernel launch with tape: wp.launch(kernelcompute1, inputs[a, b], devicecuda) wp.launch(kernelcompute2, inputs[c, d], devicecuda) wp.launch(kernelloss, inputs[d, l], devicecuda) # 反向传播以 loss 为损失标量 tape.backward(l) # 梯度通过 tape.gradients 字典访问 print(tape.gradients[a])要点Tape.__enter__会把自身挂到运行时全局同时只允许一个 tape 激活backward()接受单个数组loss或梯度字典grads作为反向通道的入口梯度梯度写入目标数组的.grad缓冲区。注意内核必须开启enable_backward默认 True才能记录反向传播。相关测试见 warp/tests/test_tape.py 与 warp/tests/test_grad.py。设备管理Device Management 小节提供多设备与 CUDA 环境的完整控制面设备对象Device、作用域切换器ScopedDevicewith 语句内临时切换设备查询get_devices()、get_device(ident)、get_preferred_device()、is_device_available(device)、can_access(...)CUDA 专用查询get_cuda_device_count()、get_cuda_devices()、get_cuda_device()、get_cuda_toolkit_version()、get_cuda_driver_version()、get_cuda_supported_archs()切换与同步set_device()、synchronize_device()多进程映射map_cuda_device()/unmap_cuda_device()在子进程中映射 CUDA 设备上下文模块管理Module Management 小节负责内核模块的编译、加载与缓存load_module(module, ...)、force_load(module, ...)延迟/强制加载模块编译为 CPU/CUDA 原生代码。并行加载线程数由warp.config.load_module_max_workers控制默认0表示串行None时由 Warp 决定目前约等于min(os.cpu_count(), 4)。get_module()、set_module_options(options, module)/get_module_options()读写模块级编译选项。compile_aot_module()/load_aot_module()Ahead-of-Time 编译与加载用于离线编译、部署场景示例见 warp/tests/aot/。CUDA 流、事件与内存管理流与事件流Stream、ScopedStream、get_stream()、set_stream()、wait_stream()、synchronize_stream()。配合launch(..., stream...)可实现异步与多流并发。事件Event、record_event()、wait_event()、synchronize_event()、get_event_elapsed_time()用于跨流同步与计时。内存CUDA Memory Management 小节覆盖了分配器与显存池控制分配器Allocator分配器基类、CudaManagedAllocatorCUDA managed memory、MemoryKind、ScopedAllocator全局设置set_cuda_allocator()、设备级set_device_allocator()/get_device_allocator()显存池mempoolScopedMempool、ScopedMempoolAccess以及is_mempool_supported/enabled、set_mempool_enabled、set_mempool_release_threshold、get_mempool_used_mem_current/high等状态 APIwarp.config.enable_mempools_at_init决定 init 时是否自动启用显存池可通过环境变量WARP_ENABLE_MEMPOOLS_AT_INIT0关闭跨设备访问ScopedPeerAccess、is_peer_access_supported/enabled、set_peer_access_enabled以及get_cuda_max_cluster_dim()CUDA 图捕获与进程间通信图管理Graph ManagementGraph 小节支持将一串内核 launch 捕获为 CUDA Graph 以降低启动开销Graph、CaptureMode、ScopedCapturewith 语法捕获底层 APIcapture_begin()/capture_end()/capture_launch()序列化capture_save()/capture_load()控制流capture_if()、capture_while()支持在图中记录条件/循环分支前提是is_conditional_graph_supported()为 True调试capture_debug_dot_print()导出图结构的 DOT 描述注意warp.config.verify_cuda在 CUDA 图捕获期间不可用会在捕获时引发问题而launch_array_access_mode的检查发生在每次 launch 记录之前因此可用于图捕获场景。CUDA IPCfrom_ipc_handle(handle, dtype, shape, ...)从 IPC 句柄创建数组不复制数据跨进程共享显存event_from_ipc_handle()类似地导入跨进程事件。IPC 句柄由 warp/_src/context.py 的原生接口生成。性能剖析与日志计时与内存跟踪ScopedTimer上下文管理器计时、TimingResult、timing_begin()/timing_end()/timing_print()手动区间计时计时开关TIMING_ALL、TIMING_GRAPH、TIMING_KERNEL、TIMING_KERNEL_BUILTIN、TIMING_MEMCPY、TIMING_MEMSET内存ScopedMemoryTracker按需跟踪与print_memory_report(file, sort, max_items)打印分配报告需要warp.config.track_memoryTrue或活跃的 tracker否则抛RuntimeError源码见 warp/_src/context.pyCUDA ProfilerScopedCudaProfiler、cuda_profiler_start()/cuda_profiler_stop()日志Logging 小节提供可插拔日志系统warp/_src/logger.pyLogger日志器基类、set_logger()/get_logger()作用域工具ScopedLogLevel临时调整日志阈值、ScopedLogger级别常量LOG_DEBUG、LOG_INFO、LOG_WARNING、LOG_ERRORwarp.config.log_level默认LOG_INFO20跨框架互操作互操作是 Warp 生态的关键warp.rst用六个小节完整覆盖生态顶层 API说明NumPyfrom_numpy、dtype_from_numpy、dtype_to_numpy与 NumPy 数组/数据类型互转DLPackfrom_dlpack、to_dlpack标准 DLPack 内存句柄互转warp/_src/dlpack.pyJAXfrom_jax、to_jax、dtype_from/to_jax、device_from/to_jax、jax_callable、jax_kernel、JaxCallableGraphMode、JaxModulePreloadMode、clear_jax_callable_graph_cache数据互转 把 Warp 内核包装为 JAX 可调用对象warp/_src/jaxPyTorchfrom_torch、to_torch、dtype_from/to_torch、device_from/to_torch、stream_from/to_torchTensor 零拷贝互转支持流对齐warp/_src/torch.pyOmniverse Fabricfabricarray、indexedfabricarray、fabricarrayarray、indexedfabricarrayarray与 Omniverse Runtime Fabric 共享数组warp/_src/fabric.pyPaddlefrom_paddle、to_paddle、dtype/device/stream_from/to_paddlePaddlePaddle 互转warp/_src/paddle.py这些互操作接口的基准示例见 warp/examples/benchmarks/benchmark_interop_torch.py 与 benchmark_interop_paddle.py以及 PyTorch 互操作指南 与 JAX 互操作指南。常量与配置模式编译期常量与数学常量constant(x)声明内核可访问的编译期常量源码仅接受内置数学类型值。数学常量两个大小写系列来源 warp/_src/constants.py通过import *导出E/e、PI/pi、TAU/tau、HALF_PI/half_pi、PHI/phi、INF/inf、NAN/nan、LN2/ln2、LN10/ln10、LOG2E/log2e、LOG10E/log10e。DeterministicModeConfiguration Modes 小节收录DeterministicMode枚举warp/config.py用于受支持原子操作的确定性执行NOT_GUARANTEED0默认不约束原子执行顺序RUN_TO_RUN1同一 GPU 架构上逐次运行结果比特级一致GPU_TO_GPU2更强的跨 GPU 架构可复现路径通过wp.config.deterministic wp.DeterministicMode.RUN_TO_RUN设置须在模块创建/导入前生效详细模式、性能考量与限制见 确定性执行指南。其他工具MarchingCubes等值面提取器warp/_src/marching_cubes.py用于把标量场转为网格。RegisteredGLBuffer已注册的 OpenGL 缓冲对象服务于 渲染模块。配置模块速览与下一步warp.rst将warp.config列为自动可用的子模块其全部配置项mode、optimization_level、cache_kernels、kernel_cache_dir、cuda_output、ptx_target_arch、verify_fp、verify_cuda、print_launches、max_unroll、fast_math等的完整说明见 warp.config API。几个常用项warp.config.mode debug编译为调试模式包含行号信息性能降低warp.config.cache_kernels跨进程复用编译缓存kernel_cache_dir可由WARP_CACHE_PATH环境变量或系统用户缓存目录解析warp.config.launch_array_access_modelaunch 前数组访问校验级别RELAXED/CHECKED/STRICT想深入某个 API 时推荐以本文列出的源码路径为索引继续阅读类型体系看 warp/_src/types.py运行机制看 warp/_src/context.py配置项看 warp/config.py并配合 内置函数语言参考 与各分类测试如 warp/tests/test_array.py、warp/tests/test_graph.py、warp/tests/test_tape.py验证行为。至此从数据模型到内核执行、从设备管理到跨框架互操作Warp 顶层 API 的完整版图已经清晰可循。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Warp 顶层 Python API 全景指南数据模型、内核编程、设备管理与跨框架互操作【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp本指南围绕 docs/api_reference/warp.rst 这份 Warp 顶层 API 参考索引展开系统梳理import warp后暴露的全部公开接口从标量/向量/矩阵等数据模型、array数组体系与空间加速结构到wp.kernel内核编程、wp.launch执行、wp.Tape自动微分再到设备、模块、CUDA 流/事件/内存/图管理以及 NumPy、JAX、PyTorch、Paddle、DLPack 等互操作层。读完本文你将掌握 Warp 公共 API 的完整分类脉络与核心函数签名并能基于源码定位每个 API 的实现位置快速上手 GPU 加速的仿真与机器学习编程。从 warp.rst 说起Warp 顶层 API 的组织方式warp.rst是 Sphinx 自动文档生成的顶层 API 索引页它通过两套机制把 warp/init.py 中暴露的所有公开符号组织成文档automodule:: warp直接引用包模块读取warp/__init__.py顶部 docstring 中的包级描述——该描述明确了 Warp 的定位提供在 CPU 与 CUDA 设备上创建和操作多维数据的数组类型与函数包含用于定义并行代码的内核/函数装饰器kernel、func以及一套完整的内置类型与函数见 内置函数语言参考。各分类小节使用autosummary指令生成指向每个符号独立文档页的链接列表。Warp 的顶层__init__.py本身就是一张公开 API 地图文件按# category:注释把from warp._src.* import ...语句分成与warp.rst完全对应的章节每个公开符号都标注了它在内部_src包中的真实来源。例如kernel、launch、get_device来自warp._src.contextvec3f、array来自warp._src.typesTape来自warp._src.tapeTexture2D来自warp._src.texture。这意味着本文列出的所有 API 都能在源码中一一对位是学习 Warp 内部实现的最佳索引。子模块体系自动可用与显式导入warp.rst将子模块分为两类规则很简单自动可用import warp后即可访问warp.build_experimental—— 外部构建扩展对应 warp_build_experimental APIwarp.config—— 全局编译/运行配置对应 warp.config API配置项详解见 配置指南warp.types—— 类型工具对应 warp.types APIwarp.utils—— 通用工具对应 warp.utils API显式导入需要import warp.autograd等warp.autogradAPI、warp.fem有限元API、warp.geometryAPI、warp.optimAPI、warp.render可视化API、warp.sparse稀疏线性代数API显式导入的子模块并非散落各处而是在warp/__init__.py开头的_register_module_source()调用中统一注册如(warp.fem, warp._src.fem)由内部module_registry保证内核/结构体/函数归属到正确的公开模块名下。类型注解与标量数据类型类型注解warp.rst的 Type Annotations 小节收录了 5 个用于类型标注的符号DeviceLike、Float、Int、Scalar、ref。从源码看DeviceLike来自warp._src.context是设备标识的注解类型允许设备参数同时接受字符串如cpu、cuda:0或Device对象——get_device(ident: DeviceLike None)的签名即为其典型用法。Float、Int、Scalar来自warp._src.types用于在 Python 侧注解泛型化的 Warp 代码。ref表示内核参数按引用传递对应wp.ref引用类型相关行为可参考 warp/tests/test_ref.py。标量类型Data Types Scalars 一节定义了 Warp 内核中可用的全部 13 种标量类型全部在 warp/_src/types.py 中实现类型说明类型说明bool布尔float16半精度浮点int8/uint88 位有/无符号整数float32单精度浮点默认int16/uint1616 位有/无符号整数float64双精度浮点int32/uint3232 位有/无符号整数bfloat16Brain 浮点int64/uint6464 位有/无符号整数handle不透明句柄类型向量、矩阵、四元数与变换向量vec2 / vec3 / vec4 与精度后缀向量类型按维度 元素类型后缀命名__init__.py的导入块完整覆盖了后缀矩阵后缀元素类型示例b/ubint8 / uint8vec3b、vec3ubs/usint16 / uint16vec3s、vec3usi/uiint32 / uint32vec3i、vec3uil/ulint64 / uint64vec3l、vec3ulhfloat16vec3hffloat32vec3f默认别名dfloat64vec3d不带后缀的vec2、vec3、vec4是 float32 的别名。矩阵、四元数与变换矩阵mat22、mat33、mat44及其h/f/d精度变体构造函数matrix_from_cols、matrix_from_rows按列/按行构造矩阵。四元数quat、quath、quatf、quatd以及工具函数quat_between_vectors计算两个向量之间的旋转四元数实现在 warp/_src/utils.py。变换transform系列transformh/f/d表示位置 四元数的刚体变换transform_expand用于展开变换参数。空间向量与矩阵spatial_vector、spatial_matrix系列用于刚体动力学等场景中的 6 维空间向量/矩阵运算。数组体系array、索引数组与 tile数组类型与工厂函数Arrays 小节是 Warp 数据流的核心。类型层面有array、array1d~array4d维度别名与fixedarray固定长度数组工厂函数层面有zeros/ones/full/empty及其*_like变体依据现有数组推断 shape/dtype/deviceclone深拷贝数组、copy拷贝数据到目标数组from_ptr从裸内存指针构造数组。源码warp/_src/types.py明确标注该方法已废弃建议改用array构造器并传入ptruint64 内存地址参数。这些工厂函数实现在 warp/_src/context.py 中与设备上下文强耦合——数组必然归属于某个Device。索引数组与 tileindexedarray/indexedarray1d~indexedarray4d元素本身是数组的数组支持数据相关的间接索引访问。tile与tile_stack面向 GPU 分块tile编程的栈式数据结构是 Warp tile 语言launch_tiled、wp.tile_matmul等的基础相关示例见 asv/benchmarks/tile/ 与 warp/tests/test_array.py。空间加速结构Spatial Acceleration 小节把仿真常用的空间数据结构统一收进顶层命名空间Bvh层次包围盒BvhQuery/BvhQueryTiled查询句柄GPU 构建可走 cuBQL见 warp/native/bvh.cu 与 warp/native/cuBQL/HashGrid均匀哈希网格HashGridQuery实现见 warp/native/hashgrid.cppMesh三角网格MeshQuery及MeshQueryAABB/AABBTiled/Point/Ray等各类查询见 warp/native/mesh.cppVolumeOpenVDB 风格体素场见 warp/native/volume.cpp这些类型既可在 Python 侧构建也能在 kernel 内部被查询配合 warp/tests/test_spatial.py 可以了解典型用法。纹理系统Textures 小节来自 warp/_src/texture.pyTexture、Texture1D、Texture2D、Texture3D一/二/三维纹理对象TextureAddressMode寻址模式、TextureFilterMode过滤模式、TextureResourceFlags资源标志三个枚举GLTextureResource与 OpenGL 纹理资源互操作对应 warp/_src/render/render_opengl.py 的可视化管线运行时初始化与诊断Runtime 小节提供了生命周期与可用性检查函数init()任何其他 API 调用之前必须调用源码 warp/_src/context.py 明确This function must be called before any other API call。launch()等函数内部会自动调用init()兜底若warp.config.track_memory为 Trueinit()还会自动启用全局内存跟踪。is_cpu_available()判断 CPU 执行是否可用等价于 LLVM 后端是否加载runtime.llvm is not None。is_cuda_available()判断是否存在 CUDA 设备get_cuda_device_count() 0。is_cubql_available()判断 cuBQL BVH 构建器是否可用。print_diagnostics()打印 Warp 构建与运行环境的完整快照Python/原生库版本、LLVM/Clang 版本、可选互操作框架版本等返回包含全部信息的 dict便于调试与提交 bug 报告自 1.12.0 引入。clear_kernel_cache()/clear_lto_cache()清空编译缓存实现在 warp/_src/build.py。内核编程wp.kernel 与函数装饰器Kernel Programming 小节是编写 GPU 代码的入口。核心装饰器kernel的完整签名源码 warp/_src/context.pydef kernel( fNone, *, nameNone, # 自定义内核注册名须为合法 C 标识符 enable_backwardNone, # False 时不生成反向传播代码 launch_boundsNone, # CUDA __launch_bounds__int 或 (maxThreadsPerBlock, minBlocksPerMultiprocessor) cuda_max_registersNone, # CUDA __maxnreg__不能与 launch_bounds 同时使用 enable_cuda_smem_spillingNone, # CUDA 13 允许用共享内存承接寄存器溢出 cluster_dimNone, # 线程簇维度 moduleNone, # 归属模块unique 表示创建独占新模块 module_optionsNone, # 模块级编译选项如 {fast_math: True} entry_point_abiNone, # warp 或 external_constant_params grid_strideNone, # 是否生成 grid-stride 循环配合 launch 的 max_blocks )最基本的用法要求函数对所有参数做类型注解、且不返回任何值import warp as wp wp.kernel def add_kernel(a: wp.array[float], b: wp.array[float]): tid wp.tid() b[tid] a[tid] 1.0同组还包括函数装饰器func可被内核调用的 Warp 函数、func_grad自定义梯度、func_native、func_replay、grad在 Python 中调用可微函数并取梯度、overload类型重载、static编译期静态分支、struct自定义结构体类型mapwarp/_src/utils.py 的 Python 侧数组映射、address_of取数组元素地址、constant编译期常量声明源码 warp/_src/types.py 限定只接受内置数学类型代码生成错误类型WarpCodegenError及其子类WarpCodegenAttributeError/IndexError/KeyError/TypeError/ValueError来自 warp/_src/codegen.py用于捕获内核编译阶段的诊断信息内核执行launch、launch_tiled 与同步wp.launch 参数详解launch是 Warp 执行内核的统一入口源码 warp/_src/context.py启动相对于 Python 调用线程是异步的def launch( kernel, # 被 wp.kernel 装饰的内核函数 dim, # 线程数int 或最多 4 维的序列 inputs[], outputs[], # 输入/输出参数 adj_inputs[], adj_outputs[], # 反向传播伴随参数 deviceNone, # 目标设备 streamNone, # 目标流指定后 device 取自 stream.device adjointFalse, # 是否运行反向通道 record_tapeTrue, # 是否记录到全局 Tape record_cmdFalse, # True 时返回 Launch 对象需手动调用 Launch.launch() max_blocks0, # 最大 CUDA 线程块数依赖 grid-stride 循环 block_dim256, # 每块线程数CPU 设备恒为 1 )值得注意的实现细节launch()会自动调用init()若传入 stream 则设备取stream.device。泛型内核generic kernel会在 launch 时根据实参推断具体重载kernel.infer_argument_types。print_launchesTrue时每次 launch 都会打印内核名、维度、参数与设备。跨设备数组访问默认不做检查LaunchArrayAccessMode.RELAXED可设置wp.config.launch_array_access_mode为CHECKED在 launch 前检测已知非法访问或STRICT强制要求所有数组参数都分配在启动设备上。其他执行 APIlaunch_tiled以分块tile方式启动用于 tile 语言内核。synchronize()等待所有设备上的内核执行完毕。get_suggested_block_size/get_cuda_kernel_properties查询建议块大小与 CUDA 内核属性。Kernel、Function、Launch、Module、ModuleBuildOptions执行相关的对象类型其中Module承载编译产物ModuleBuildOptions描述模块级编译选项如fast_math、enable_backward、lineinfo等可结合 配置指南 理解。自动微分wp.TapeAutomatic Differentiation 小节只有一个类Tapewarp/_src/tape.py它是 Warp 反向模式自动微分的核心tape wp.Tape() # 前向传播在 tape 上下文中记录 kernel launch with tape: wp.launch(kernelcompute1, inputs[a, b], devicecuda) wp.launch(kernelcompute2, inputs[c, d], devicecuda) wp.launch(kernelloss, inputs[d, l], devicecuda) # 反向传播以 loss 为损失标量 tape.backward(l) # 梯度通过 tape.gradients 字典访问 print(tape.gradients[a])要点Tape.__enter__会把自身挂到运行时全局同时只允许一个 tape 激活backward()接受单个数组loss或梯度字典grads作为反向通道的入口梯度梯度写入目标数组的.grad缓冲区。注意内核必须开启enable_backward默认 True才能记录反向传播。相关测试见 warp/tests/test_tape.py 与 warp/tests/test_grad.py。设备管理Device Management 小节提供多设备与 CUDA 环境的完整控制面设备对象Device、作用域切换器ScopedDevicewith 语句内临时切换设备查询get_devices()、get_device(ident)、get_preferred_device()、is_device_available(device)、can_access(...)CUDA 专用查询get_cuda_device_count()、get_cuda_devices()、get_cuda_device()、get_cuda_toolkit_version()、get_cuda_driver_version()、get_cuda_supported_archs()切换与同步set_device()、synchronize_device()多进程映射map_cuda_device()/unmap_cuda_device()在子进程中映射 CUDA 设备上下文模块管理Module Management 小节负责内核模块的编译、加载与缓存load_module(module, ...)、force_load(module, ...)延迟/强制加载模块编译为 CPU/CUDA 原生代码。并行加载线程数由warp.config.load_module_max_workers控制默认0表示串行None时由 Warp 决定目前约等于min(os.cpu_count(), 4)。get_module()、set_module_options(options, module)/get_module_options()读写模块级编译选项。compile_aot_module()/load_aot_module()Ahead-of-Time 编译与加载用于离线编译、部署场景示例见 warp/tests/aot/。CUDA 流、事件与内存管理流与事件流Stream、ScopedStream、get_stream()、set_stream()、wait_stream()、synchronize_stream()。配合launch(..., stream...)可实现异步与多流并发。事件Event、record_event()、wait_event()、synchronize_event()、get_event_elapsed_time()用于跨流同步与计时。内存CUDA Memory Management 小节覆盖了分配器与显存池控制分配器Allocator分配器基类、CudaManagedAllocatorCUDA managed memory、MemoryKind、ScopedAllocator全局设置set_cuda_allocator()、设备级set_device_allocator()/get_device_allocator()显存池mempoolScopedMempool、ScopedMempoolAccess以及is_mempool_supported/enabled、set_mempool_enabled、set_mempool_release_threshold、get_mempool_used_mem_current/high等状态 APIwarp.config.enable_mempools_at_init决定 init 时是否自动启用显存池可通过环境变量WARP_ENABLE_MEMPOOLS_AT_INIT0关闭跨设备访问ScopedPeerAccess、is_peer_access_supported/enabled、set_peer_access_enabled以及get_cuda_max_cluster_dim()CUDA 图捕获与进程间通信图管理Graph ManagementGraph 小节支持将一串内核 launch 捕获为 CUDA Graph 以降低启动开销Graph、CaptureMode、ScopedCapturewith 语法捕获底层 APIcapture_begin()/capture_end()/capture_launch()序列化capture_save()/capture_load()控制流capture_if()、capture_while()支持在图中记录条件/循环分支前提是is_conditional_graph_supported()为 True调试capture_debug_dot_print()导出图结构的 DOT 描述注意warp.config.verify_cuda在 CUDA 图捕获期间不可用会在捕获时引发问题而launch_array_access_mode的检查发生在每次 launch 记录之前因此可用于图捕获场景。CUDA IPCfrom_ipc_handle(handle, dtype, shape, ...)从 IPC 句柄创建数组不复制数据跨进程共享显存event_from_ipc_handle()类似地导入跨进程事件。IPC 句柄由 warp/_src/context.py 的原生接口生成。性能剖析与日志计时与内存跟踪ScopedTimer上下文管理器计时、TimingResult、timing_begin()/timing_end()/timing_print()手动区间计时计时开关TIMING_ALL、TIMING_GRAPH、TIMING_KERNEL、TIMING_KERNEL_BUILTIN、TIMING_MEMCPY、TIMING_MEMSET内存ScopedMemoryTracker按需跟踪与print_memory_report(file, sort, max_items)打印分配报告需要warp.config.track_memoryTrue或活跃的 tracker否则抛RuntimeError源码见 warp/_src/context.pyCUDA ProfilerScopedCudaProfiler、cuda_profiler_start()/cuda_profiler_stop()日志Logging 小节提供可插拔日志系统warp/_src/logger.pyLogger日志器基类、set_logger()/get_logger()作用域工具ScopedLogLevel临时调整日志阈值、ScopedLogger级别常量LOG_DEBUG、LOG_INFO、LOG_WARNING、LOG_ERRORwarp.config.log_level默认LOG_INFO20跨框架互操作互操作是 Warp 生态的关键warp.rst用六个小节完整覆盖生态顶层 API说明NumPyfrom_numpy、dtype_from_numpy、dtype_to_numpy与 NumPy 数组/数据类型互转DLPackfrom_dlpack、to_dlpack标准 DLPack 内存句柄互转warp/_src/dlpack.pyJAXfrom_jax、to_jax、dtype_from/to_jax、device_from/to_jax、jax_callable、jax_kernel、JaxCallableGraphMode、JaxModulePreloadMode、clear_jax_callable_graph_cache数据互转 把 Warp 内核包装为 JAX 可调用对象warp/_src/jaxPyTorchfrom_torch、to_torch、dtype_from/to_torch、device_from/to_torch、stream_from/to_torchTensor 零拷贝互转支持流对齐warp/_src/torch.pyOmniverse Fabricfabricarray、indexedfabricarray、fabricarrayarray、indexedfabricarrayarray与 Omniverse Runtime Fabric 共享数组warp/_src/fabric.pyPaddlefrom_paddle、to_paddle、dtype/device/stream_from/to_paddlePaddlePaddle 互转warp/_src/paddle.py这些互操作接口的基准示例见 warp/examples/benchmarks/benchmark_interop_torch.py 与 benchmark_interop_paddle.py以及 PyTorch 互操作指南 与 JAX 互操作指南。常量与配置模式编译期常量与数学常量constant(x)声明内核可访问的编译期常量源码仅接受内置数学类型值。数学常量两个大小写系列来源 warp/_src/constants.py通过import *导出E/e、PI/pi、TAU/tau、HALF_PI/half_pi、PHI/phi、INF/inf、NAN/nan、LN2/ln2、LN10/ln10、LOG2E/log2e、LOG10E/log10e。DeterministicModeConfiguration Modes 小节收录DeterministicMode枚举warp/config.py用于受支持原子操作的确定性执行NOT_GUARANTEED0默认不约束原子执行顺序RUN_TO_RUN1同一 GPU 架构上逐次运行结果比特级一致GPU_TO_GPU2更强的跨 GPU 架构可复现路径通过wp.config.deterministic wp.DeterministicMode.RUN_TO_RUN设置须在模块创建/导入前生效详细模式、性能考量与限制见 确定性执行指南。其他工具MarchingCubes等值面提取器warp/_src/marching_cubes.py用于把标量场转为网格。RegisteredGLBuffer已注册的 OpenGL 缓冲对象服务于 渲染模块。配置模块速览与下一步warp.rst将warp.config列为自动可用的子模块其全部配置项mode、optimization_level、cache_kernels、kernel_cache_dir、cuda_output、ptx_target_arch、verify_fp、verify_cuda、print_launches、max_unroll、fast_math等的完整说明见 warp.config API。几个常用项warp.config.mode debug编译为调试模式包含行号信息性能降低warp.config.cache_kernels跨进程复用编译缓存kernel_cache_dir可由WARP_CACHE_PATH环境变量或系统用户缓存目录解析warp.config.launch_array_access_modelaunch 前数组访问校验级别RELAXED/CHECKED/STRICT想深入某个 API 时推荐以本文列出的源码路径为索引继续阅读类型体系看 warp/_src/types.py运行机制看 warp/_src/context.py配置项看 warp/config.py并配合 内置函数语言参考 与各分类测试如 warp/tests/test_array.py、warp/tests/test_graph.py、warp/tests/test_tape.py验证行为。至此从数据模型到内核执行、从设备管理到跨框架互操作Warp 顶层 API 的完整版图已经清晰可循。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
