warp-eval

Warp 评估

目的

收集可复现的证据，了解现有代码库中的狭窄衔接点在 NVIDIA Warp 中会如何表现。报告事实；由用户作出决定。

第一行须将 Warp 列为评估选项，说明不会给出采纳建议，也不得将触发性能请求视为进行实验的授权。

测量评估会生成 warp-evaluation-report/：报告、每个解决方案各一份可独立应用的差异文件、驱动程序和原始结果。绝不修改生产代码。在测量工作开始前退出时，不创建目录。

硬性规则

这些规则优先于任何本地判断。

1. 默认目标是延迟、吞吐量以及峰值或保留内存。 只有用户明确提出可维护性、易用性、打包、可扩展性、自动微分或新功能时，才将其计入目标；否则应将其报告为约束或成本，而非收益。
2. 正确性是门槛。 如果现有实现有缺陷或其契约不明确，在独立预言机或明确契约确立之前，中止该比较。报告缺陷，但不规定应如何应对。
3. 绝不根据源码结构或其他工作负载预测节省。 物化内存须有分析器或分配器证据，不能依据编译器可能融合的源码推断。
4. “可以用 Warp 编写”是假设，绝非已证实的机会。
5. 门槛必须严格匹配，不得用相邻或类似条件替代。 只有在定义中的所有条件均已确认时，才触发门槛。门槛 D 要求已确认某个受维护实现能够在 NVIDIA GPU 上使用 CUDA 执行；快速的原生 CPU 库只是基线，不属于门槛 D。
6. 每项主张都须标注为观察到的事实、测量结果、假设或未知。
7. 测量用户可见的阶段，而非内核。 在实际进程模式中纳入 Warp 的冷启动导入／初始化／JIT，以及传输、启动、Python 启动循环、结构构建／重构、分配、转换、验证、压缩和同步。分别报告每项成本及端到端差异。
8. 未经明确授权，不得进行测量工作。 阶段 1 完成后，先停止并征求授权，再进行分析、环境变更、原型开发、基准测试或 GPU 使用。
9. 获准的测量工作包含 Warp。 如果分析未发现任何门槛，仍须继续评估项目内最强基线、最小 Warp 原型和端到端比较。如果 Warp 不在范围内，则在分析前停止。
10. 绝不推断环境意图。 是否部署到 NVIDIA 以及是否承担可选编译依赖的维护责任，都是产品决策。只有明确提出约束时才中止；否则询问一次后停止（AWAITING INTENT）。
11. Warp 测量仅限 CUDA，且须同步。 明确指定 NVIDIA CUDA 设备；丢弃解析到 CPU 的结果和仅测派发的计时。
12. 绝不建议或排序采纳选项。 按衔接点和运行模式报告事实、测量结果、假设及未知事项。
13. 报告完成即停止。 不进行推广部署或生产代码修改。

要求

静态筛查需要目标代码库及其已声明的产品约束。测量工作还需要明确授权、NVIDIA CUDA GPU、目标项目依赖项和代表性工作负载。

限制

• Warp CPU 内核是串行的，不在此技能的评估范围内。 “改用 CPU 运行”并非性能回退方案。
• 网格和几何查询使用 float32/int32 计算，即使公开 API 使用 float64 也是如此。绝对误差会随坐标大小增加。
• **Warp 不遵循语义化版本控制。**功能版本可能会破坏 API；只有最新的功能版本线会得到维护；弃用周期约为每四个月发布四个版本。
• **latest 文档对应开发中的版本，而非已发布版本。**请固定到目标项目自身使用的 Warp 版本；若项目未指定版本，则使用当前稳定版，并说明所用版本。
• 仅内核可用的内置函数无法从 Python 解析——即使某个版本包含 mesh_query_point，hasattr(wp, "mesh_query_point") 仍可能返回 False。在断定某个内置函数不存在之前，请检查存根文件或该版本的文档。
• enable_backward=False（内核、模块或全局设置）会移除伴随代码生成。如果没有任何内容需要通过该衔接点求导，请在测量编译成本前设置此项。

输出格式

状态	达成条件	报告目录
ABORT	任一关卡确认所评估的衔接点无法满足既定范围	如果尚未进行测量，则不提供；否则保留已收集的证据
AWAITING INTENT	环境关卡揭示了只有用户才掌握的事实	不提供——提出一个问题，并具体说明两个分支
AWAITING AUTHORIZATION	候选模式通过阶段 1	不提供——提供早期发现以及范围/资源预览
INCOMPLETE	已获授权的工作无法获取范围评估所需的代表性证据	是——保留已收集的证据，并指出唯一缺失的材料
已交付报告	已获授权的工作产生了测量结果，或在报告目录创建后停止	是——按衔接点和运行条件列出事实，并明确说明缺失的证据

早期退出时请使用以下精确格式： ABORT — Gate <letter>: <cited fact>; <why the scoped Warp evaluation cannot proceed>. 不要指出首选替代方案。 报告规则： references/evidence-and-reporting.md。 已交付的目录必须遵循模板规定的顺序：架构与来源、授权与评估状态、阶段普查、每个衔接点/运行条件各一个 B<n> 证据章节、注意事项，然后是环境/复现信息。solutions/、benchmarks/ 和 results/ 包含所有已链接的材料。

示例

关卡退出： ABORT — Gate A: deployment.md requires one implementation with AMD, Apple and NVIDIA parity; a Warp-specific path cannot satisfy this scope.

**候选方案通过：**指出衔接点和模式，将推断事实标为假设，说明没有触发任何关卡，预览性能分析/基线/Warp 原型/基准测试的范围及成本，然后分别提出 references/authorization-checkpoint.md 中的意图确认和授权问题。

输入

**必需：**目标代码仓库，以及存在候选衔接点的性能、内存或规模问题。**可选：**明确的部署/打包约束、现有性能分析结果或日志、有代表性的数据集和验收标准。提示词中的约束优先于代码仓库策略/配置，其次是现有日志。用户更正优先于推断。绝不要用假设替代明确陈述的事实或测量结果。

可用脚本

脚本	用途	参数
scripts/driver-template.py	为每个瓶颈复制一份；定义工作负载和变体	编辑占位符，然后运行复制出的驱动程序
scripts/measure.py	从驱动程序导入，用于同步计时、内存测量和隔离用例	Python API；不要直接执行
scripts/validate_report_schema.py	验证已交付报告及证据链接	<report-directory>

在支持时，请使用 run_script("scripts/validate_report_schema.py", args=["warp-evaluation-report"])；否则，请使用 Python 和报告目录调用该脚本。

故障排查

• 没有代表性工作负载：将范围标记为 INCOMPLETE，并指出缺失的 工件；不要编造数据，也不要触发 Gate F。
• Warp 解析到 CPU，或没有 CUDA 设备：丢弃此次运行，并停止，不得声称 正确性或性能数据。
• 报告验证失败：修正报告或其引用的工件；绝不豁免架构错误。

说明

除最后一个阶段外，每个阶段都可能结束评估。一旦触发某个关卡就立即停 止；不要收集无法改变已界定事实的证据。

1. 阅读代码，推导契约，检查关卡

• 使用 references/target-patterns.md 确定候选对象及其指标。
• 根据代码仓库推导设备/驻留位置、数据类型/形状、大小、频率、进程生命 周期、梯度和打包方式。先推断，再询问。
• 用一行陈述推断出的契约，并邀请对方纠正。未知的硬件、数量、大小和容 差都只是假设，不是测量结果。所有推断都仍可纠正，且不能满足要求明示 事实或测量结果的关卡。
• 在分析性能之前检查 Gate A–E。仅当已有代表性证据时，才立即检查 Gate F；否则将其留到阶段 2。每个关卡都只能使用 references/rejection-gates.md 中明确规定的边界。

关卡	触发条件
A	已明确说明生产环境仅使用 CPU，或需要支持非 NVIDIA 平台，且没有可接受的可选 CUDA 路径
B	每次小型或低频调用都必须跨越主机/设备边界，且无法扩大边界范围
C	该区域是密集张量代数，且已由经过调优的框架或厂商库实现
D	已有成熟的 CUDA 实现满足契约，且未提出非性能目标
E	已说明的策略禁止 Warp 的依赖、编译、缓存或回退要求
F	代表性证据证明，该区域在所请求指标中占比过小，以至于任何后端都无法改善指标

• 阶段 1 只有在已有代表性证据时才能触发 Gate F，例如提供的性能分析、 结构性上限，或基于用户提供数据的计算。如果没有此类证据，Gate F 将 保持未决，直到阶段 2 的性能分析；推断值绝不能触发该关卡。
• Gate A 和 Gate E 需要有明确说明的约束。存在 CPU 实现、其他加速器、 不依赖 Warp，或依赖项列表较短，都不能证明任何问题。
• 如果 Gate A/E 尚未解决，且某个模式仍符合条件，询问对方是否接受可选 的 NVIDIA 路径：命名的额外依赖、软导入、现有回退机制，以及保持默认 安装不变。每个肯定答复都必须明确说明将对 Warp 进行原型开发和基准测 试；这些条件只限制 Warp 的范围。答复否定或尚未决定时，结果为 ABORT。
• 如果其他关卡已触发、代码仓库已有答案，或没有匹配的模式，则不要询问。 没有匹配模式就不进行性能分析。
• 如果某个候选对象通过筛选，将意向问题与 authorization-checkpoint （早期发现、确切范围、阶段、资源成本）一并确认，然后停止。阶段 2 必须同时满足意向已确定和明确授权。

2. 为真实应用进行性能分析

需要明确授权，并且意图问题已确定。

• 使用项目自身的性能分析器和有代表性的入口点进行分析。
• 在选择后端之前，测量同步的端到端阶段耗时和峰值内存。报告分析了哪些入口点，以及哪些入口点经过了门控筛查。
• 根据观察到的开销安排后续测量的优先级，而非根据源码表象。
• 每项测量都以实际调用的公开方法和变体命名。回退是该公开接口的一种执行模式，而非不同的操作；较低开销的同类方法不能筛掉指定方法。
• 确认计时分支在预期设备上运行。主机输入与设备输入的开销不变，且设备内存分配量接近于零，表明发生了主机回退。
• 通过公开边界测量阶段空载上限和桩实现下限。不要扣除各操作的计时。
• 如果测得的上限证明候选方案无法改变其自身指标，则依据 Gate F 对受影响范围执行 ABORT，保留已收集的证据，并停止。现有授权已涵盖此重要性检查；不要再次请求授权。
• 如果无法获得有代表性的覆盖——没有有代表性的数据集、可运行的入口点或生产分布——则记录唯一缺失的材料，将受影响范围标记为 INCOMPLETE，并停止。这是证据缺失，不属于 Gate F，也不属于 ABORT。虚构的工作负载无法证明重要性。

流程：references/benchmark-protocol.md。

3. 提出可证伪的假设

针对每个候选方案记录：来源、瓶颈证据、目标、狭窄接口、Warp 可以改变的机制、最强的现有方案、风险、验收阈值，以及成本最低的证伪实验。根据 references/target-patterns.md 进行筛查；如果没有候选方案通过筛查，则撰写报告并停止。

4. 在原型开发前编写契约

定义值、数据类型、形状、设备、错误、修改行为、顺序、并列情况、容量／溢出、拓扑结构／退化情况、容差、所需梯度、流、所有权、别名、失效、并发、捕获、拆卸和回退。

• 在查看 Warp 输出之前确定容差。出现不匹配后，绝不放宽契约。
• 如果拟议接口无法满足必需契约，则在开发原型前执行 ABORT。
• 在计时前预先登记：工作负载来源、决定开销的状态变量及其生产范围、调优参数、现有方案的运行间差异，以及应用于每种实现的判定准则。

风险与对抗性检查： references/semantic-contract.md。

5. 先改进基线

算法优先于后端：（1）更好的算法或输出敏感算法； （2）分块、平铺、稀疏输出、布局、重计算；（3）现有框架的编译器和原生基本操作；（4）项目已有依赖——项目自身的加速器后端、已提供但未启用的并行惯用模式，或现有依赖已暴露但无人接入的能力；（5）最后才考虑范围有限的 Warp。

• 只比较范围内的选项：改进后的现有方案、通过当前依赖可用的能力，以及 Warp。不要加入无关库。
• 在认定某条路径不存在之前，先搜索已声明的依赖，查找未启用的后端、标志和绑定。
• 将改进后的现有方案保留为判定基准。针对未经调优、有错误或渐近复杂度更差的基线得出的结果，不能证明后端对比成立。

在对 Warp 进行原型设计之前，先穷尽项目内的所有路径：

状态	声明该状态所需的依据
已测量	通过与基线相同的边界进行计时
不存在	有引用的声明、符号表或缺失标志证明该能力不可用
已豁免	你已询问用户，且用户选择跳过；记录用户原话

能力虽已存在但尚未绑定，仍属于可用路径，而非不存在。如果暴露该能力的成本不高于计划中的 Warp 接入点，应先进行测量。路径分级详情： references/baselines.md。 已豁免的路径不会阻止进入第 6 阶段；Warp 原型开始之前，每条未明确豁免的路径都必须完成测量，或有证据证明其不存在。

6. 对最小单元进行原型设计

• 在单独的副本中工作，保持生产环境不变，并默认关闭集成接入点。原型只需足以验证假设。
• 对每个 Warp 原型明确指定 CUDA 设备，并在正确性或性能测试前验证 Warp 将其识别为 CUDA。绝不要运行或报告 Warp 的 CPU 后端。
• 根据共享数据和结构的生命周期确定单元大小，而非根据函数边界：如果构建、重拟合和查询的成本能够共同摊销，它们就属于同一个单元。
• 计时前为各个变体命名。将每种方案保留为针对固定基线的独立补丁，并证明补丁能够干净应用且可重现已测量的结果。
• 计时前明确呈现不受支持的情况和溢出问题。
• 运行对抗性契约检查，在生产规模下审查正确性，并故意破坏一个分支以证明测试会失败。任何必需检查失败，都应对受影响范围返回 ABORT。
• 在将令人失望的计算受限或高复用结果视为代表性结果之前，先考虑 references/target-patterns.md 中更强的实现形式。单个朴素内核不足以界定 Warp 的潜力。

7. 对整个边界进行基准测试

• 每个瓶颈复制一次 scripts/driver-template.py，并通过 scripts/measure.py 进行测量。不要自行编写计时或内存测量代码。
• Warp 启动是异步的。测量辅助工具必须在开始计时之前，以及每个计时区间的任务入队之后、停止墙钟计时器之前，立即同步所选设备。
• 纳入第 7 条要求的全部成本、公共调用、紧接其后的下游阶段、实际规模，以及冷启动和热启动进程状态。
• 从输出的 JSON 中逐格转录所有报告数据；缺失的记录填写 not measured。
• 报告 null_test，并分别报告一次性成本及其摊销后成本。GPU 测量必须在独占设备锁下串行执行。低于 1.5× 不算测得差异。
• 如果某个接入点和运行状态未满足预先声明的端到端性能或内存要求，则返回 ABORT，但须保留测量结果。

完整协议： references/benchmark-protocol.md。

8. 总结证据

• 按每个接缝和执行模式，报告语义结果、最强基线的测量数据、工作负载来源、时间、内存、生命周期、可移植性和所有权事实。
• 仅当明确的标准使状态具有客观依据时，才使用 pass、fail、not measured、not available、no representative data、unknown 或 n/a。缺失的证据仍然是缺失的。
• 只有每个已评估的接缝和执行模式都包含端到端 Warp 测量时，才将报告标记为 complete。若触发了关卡，使用 aborted — <gate and scope>；若无法获得有代表性的证据，使用 incomplete — <missing evidence and scope>。保留所有已收集的内容。绝不可将仅含现有方案数据的报告作为已完成的 warp-eval 交付。
• 对每个占测量总量 ≥10 % 的阶段，都提供一行普查记录，注明状态和一行理由，包括筛除的阶段。
• 根据候选方案的模式所耗尽的指标检查每个关卡，而非研究的主要目标。

9. 交付

• 使用 assets/warp-evaluation-report-template.md ，并保持其架构不变。记录授权和范围。
• 每个瓶颈使用一张表：基线、当前依赖项的解决方案，然后是 Warp；记录绝对时间和峰值内存、比率、契约状态及证据缺口。
• 仅在说明测量结果或其界限时加入正文。 工作产物应放在 results/ 中。

uv run python scripts/validate_report_schema.py <report-directory>

• 首次测量建立普查表/数据表后运行一次验证器，交付前再运行一次。修复所有错误。
• 根据产物验证构建和导入，而非依据退出状态。交付实际运行的驱动程序。然后停止。