| 名称 | warp-eval |
| 描述 | > 评估现有热路径是否为可信的 NVIDIA Warp 候选。适用于不规则或空间查询、粒子或几何模拟、分支密集循环、大量小型启动、主机回退或大型中间结果。除非明确禁止 NVIDIA，否则仅 CPU 代码和无 GPU 依赖属于正常。排除必须跨厂商或仅 CPU 部署、供应商底层化的稠密张量或神经网络层、通用 Warp API 问题以及已被选中的 Warp 内核。仅凭贡献策略不构成排除。 |
| 开源协议 | Apache-2.0 metadata: |
| 作者 | NVIDIA Corporation warp-python@nvidia.com tags: [warp, gpu-acceleration, performance, simulation, evaluation] compatibility: > 筛选、静态评估和报告不需要 GPU。测量 Warp 需要 NVIDIA CUDA GPU、目标项目依赖项和代表性工作负载；不具备时，应在性能分析前中止。 |
Warp 评估
目的
收集关于现有代码库中一个狭窄接缝在 NVIDIA Warp 下表现的可复现证据，报告事实，由用户决策。第一行声明 Warp 是受评估选项且不提供采用建议。未经授权不进行实验。测量评估输出 warp-evaluation-report/；绝不修改生产代码。
硬性规则
- 默认目标为延迟、吞吐量及峰值或保留内存；除非用户点名，可维护性等只作为约束或成本。
- 正确性是门槛；现有契约不明时先明确 oracle 或契约，不修复缺陷。
- 不得从源码形态或相似负载预测收益；实际内存以分析器和分配器证据为准。
- “可以用 Warp 编写”只是假设。
- 门限精确触发，不得近似。
- 每条论断标注：观察事实、测量、假设或未知。
- 时间测量覆盖用户可见完整阶段，包含 Warp 冷启动/导入/JIT、传输、启动循环、构建/分配/转换/同步等全部成本。
- 无明确授权不进行 profile、原型、基准或 GPU 使用。
- 授权的测量工作包含 Warp；若无门触发，继续测得项目内最强基线、最小原型和端到端对比。
- 不推断环境意图；只有当用户明确给出约束才中止，否则询问一次并停在 AWAITING INTENT。
- Warp 测量仅限 CUDA 并需同步；丢弃 CPU 解析及派发计时。
- 不推荐或排序任何采用方案；只报告事实与测量。
- 到报告为止，不做生产修改。
要求
静态筛选需要目标仓库及产品约束。测量工作还需要显式授权、NVIDIA CUDA GPU、目标项目依赖和代表性负载。
局限性
- Warp CPU 内核为串行且不在本评估范围。
- 网格/几何查询在内部以 float32/int32 计算，即使公开 API 使用 float64。
- Warp 不遵循 semver，仅最新特性线受维护，弃用周期约四个版本。
- latest 文档对应开发版，应固定到目标项目声明的 Warp 版本。
- 仅内核 builtin 无法从 Python 通过 hasattr 探测；需核对 stub 文件或对应版本文档。
- 无需微分时设置 enable_backward=False 后再测量编译开销。
输出格式
| 状态 | 达到条件 | 报告目录 |
|---|---|---|
| ABORT | 任一门证明 Warp 无法满足范围 | 无（未测量时）；有测量则保留证据 |
| AWAITING INTENT | 环境门取决于用户掌握的只有用户有的信息 | 无——一个问题，两个分支 |
| AWAITING AUTHORIZATION | 候选模式通过阶段 1 | 无——附早期发现和范围/资源预览 |
| INCOMPLETE | 授权后仍缺乏代表性证据 | 是——保留证据，指出缺失工件 |
| 报告交付 | 完成测量或已有报告目录 | 是——事实与缺失证据明确 |
早期退出形如：ABORT — Gate <letter>: <cited fact>; <why scoped warp-eval cannot proceed>。 交付目录遵循模板固定顺序并链接工具与结果。
示例
门退出示例：ABORT — Gate A: deployment.md requires one implementation with AMD, Apple and NVIDIA parity; a Warp-specific path cannot satisfy this scope.
通过候选示例：命名接缝与模式，标注假设，说明无门触发，给出 profile/基线/Warp 原型/基准范围及成本，再问授权问题。
输入
需要：目标仓库，以及存在候选接缝的性能/内存/规模问题。可选：部署约束、日志/profile、代表性数据集、验收标准。Prompt 约束优先。
可用脚本
| 脚本 | 用途 | 参数 |
|---|---|---|
| scripts/driver-template.py | 每瓶颈复制一份并定义负载/变体 | 编辑占位符后运行 |
| scripts/measure.py | 导入后用于同步计时、内存与隔离用例 | Python API，勿直接执行 |
| scripts/validate_report_schema.py | 校验报告与证据链接 | <report-directory> |
故障排查
- 无代表性负载：标为 INCOMPLETE，指出缺失工件，不编数据。
- Warp 解析到 CPU 或无 CUDA：丢弃该运行并停止。
- 报告验证失败：修复报告或工件，不豁免 schema 错误。
指令
除最后阶段外每阶段都可能结束评估；停止后不收集无关证据。
1. 读代码、定契约、查门
按 references/target-patterns.md 识别候选与指标；从仓库推导设备/驻留、dtype/shape、大小、频率、生命周期、梯度与打包，先推断后询问。用一句话陈述契约并要求纠正。频率/硬件/容差等推断不是测量，但可被修正。分析前查 Gates A–E；只有存在现成代表性证据时才查 Gate F。各门定义见 references/rejection-gates.md。
门表：A 生产已声明仅 CPU 或强制非 NVIDIA 移植且无可选 CUDA 路径；B 数据每小/少调用穿越主机/设备边界且无法拓宽；C 稠密张量已映射到调优框架；D 已有成熟 CUDA 实现且无其它非性能目标；E 政策阻止 Warp 依赖/编译/缓存/回退；F 代表性证据显示占比太小。Gates A/E 需要用户陈述；当候选模式存活但 A/E 未定时，询问是否接受可选 NVIDIA 路径。候选存活则结合授权检查点输出预览并停止。
2. 对真实应用做 profile
需授权与意图均已解决。使用项目 profiler，以公开入口和变体命名测量；确认在目标设备执行；时间与峰值内存通过同步端到端获得。若测量 ceiling 低于需求，以 Gate F 中止受影响范围。若无法获得代表性数据/入口，记录缺失工件并标 INCOMPLETE。
3. 形成可证伪假设
记录各候选的来源、瓶颈证据、目标、接缝、Warp 可改机制、最强基线、风险、验收阈值及最廉价证伪实验；再按 references/target-patterns.md 筛选。
4. 先写契约，再写原型
定义值、dtype/shape/设备/错误/顺序/容差/梯度/流/所有权等契约，观察 Warp 输出前固定容差。不能满足契则中止。预注册负载来源、成本状态变量、调优旋钮、基线抖动与 oracle。对抗检查见 references/semantic-contract.md。
5. 先改进基线
算法再后端；先启用项目已依赖的并行后端和编译器；打开项目已有能力；无项目内路由后才收窄到 Warp。对比对象只能是改进后的基线、现有依赖能达到的方案和 Warp。用无调优或劣化基线得不到有效结论。每条未豁免路由需先被测量或被证实缺乏；用户可书面豁免。
6. 最小 Warp 原型
在独立副本中改代码，生产不变。每次原型必须显式选择 CUDA 设备并确认 Warp 实际以 CUDA 运行，不运行 CPU 后端。单元大小按共享数据和生命周期摊销。每个方案以独立补丁保存，补丁要证明可干净应用并复现。先做对抗检查和破坏性测试；失败则 ABORT。
7. 全边界基准测试
从 scripts/driver-template.py 复制驱动，用 scripts/measure.py 的同步计时/内存测量；包含冷/暖启动、传输、JIT、构建、同步及下一步骤开销。用量化结果转写；报告 null_test，一次性成本单列并摊销。GPU 测量用设备锁串行化；低于 1.5× 不算差异；未达到预声明需求则 ABORT。
8. 汇总证据
按接缝/工况报告语义结果、最强基线、负载来源、时长、内存、生命周期、可移植性。状态必须用 pass/fail/not measured/unknown 等客观项。只有包含端到端 Warp 测量才能标记 complete；否则标注 aborted/incomplete。所有≥10% 的阶段加清点行。
9. 交回
按模板固定 schema 生成报告；每瓶颈一个表格比较基线、当前依赖方案与 Warp。运行校验：uv run python scripts/validate_report_schema.py <report-directory>，验证构建与导入后停止。