cuPyNumeric 迁移就绪评估

目的

在迁移之前（而非迁移期间）使用本技能。 回答一个核心问题：在用户投入数周的移植工作之前，其现有的 NumPy API 中有哪些能在 cuPyNumeric 上扩展，哪些需要重构？ 为此：阅读源代码，根据在 Legate/NVIDIA GPU 栈上的多 GPU 扩展能力对每个 NumPy 惯用模式进行分类，交叉参考附带的 API 支持清单，并生成结构化结论，包含每个发现的推理和配方指引。

这是一项静态的只读评估。 使用 Read、Grep 和 Glob 工具检查用户的源代码。不要执行用户的代码、修改或写入文件，也不要打印环境变量或密钥。下面展示的 legate 和 cuPyNumeric Doctor 命令是建议由用户运行的，而非本技能执行的操作。

如果之前从未见过本技能，请先前往 references/getting-started.md。

何时使用本技能

当用户即将将 NumPy 代码迁移到 GPU，并询问是否能在 cuPyNumeric/GPU 上扩展、是否应该迁移、哪些部分会受益、移植前需要更改什么、移植是否值得，或提及预移植评估、扩缩容分析、惯用模式分析、GPU 重构规划、识别 NumPy GPU 反模式时使用。

在以下情况拒绝并重定向（请求不是预迁移评估时）：

• 迁移后的性能/性能分析（"已经移植了，为什么慢？"）→ 指向 legate --profile 和上游的性能分析与调试指南。
• 自定义 CUDA / 内核编写（"编写/优化 CUDA 内核"）

用户要求评估的图谱/稀疏/ML/NLP 工作负载仍然在范围内：进行评估并通过关卡 4 返回 NOT RECOMMENDED。这是一种结论，而非拒绝。

指令

按顺序执行以下所有五个步骤。语义性地阅读用户的代码并推理；不要一次性输出散文式结论。

步骤 1 — 收集上下文

在扫描代码之前先收集信息。以下每项都针对典型工作负载提供了默认值——当用户未主动提供细节时使用默认值；不要卡在提问上。

• 源代码位置。 未指定路径时默认使用当前工作目录。
• 运行时的热路径数组大致大小。 默认 3000 万到 5000 万个元素。将用户提供的数字（或此默认值）映射到关卡 2 层级（每 GPU 下限 65K；10M+ 可实现真正单 GPU 加速；100M+ 可实现多 GPU）。
• 目标硬件。 默认 1-4 GPU，单节点。在假设多节点前确认。仅 CPU 运行时，询问每节点 RAM 而非 FBMEM。
• 主要计算模式。 模板计算 / GEMM / 蒙特卡洛 / 归约 / 混合-SciPy。让用户说明；否则在步骤 3 中从代码推断。

在评估报告顶部说明你使用的默认值，以便用户修正。如果某个值无法确定，如实说明并仅进行定性评估——不要编造超出上述默认值的数字。

步骤 2 — 加载 API 支持清单

读取 assets/api-support.md，即上游 NumPy 与 cuPyNumeric 对比表的已提交快照。对于代码中调用的每个 NumPy API，找到其所在行并读取前导符号：

• ✓✓ numpy.X —— 已实现且可在多 GPU 上工作（最佳路径）。
• ✓ numpy.X —— 已实现但仅限单 GPU/CPU（多节点有限制）。
• 🟡 numpy.X — <注释> —— 部分支持；阅读注释。
• ✗ numpy.X —— 未在 cuPyNumeric 分布式路径上实现。调用时的行为因版本而异（部分不支持的 API 会通过主机 NumPy 路由，其他会抛出异常）——无论哪种情况，在热路径上使用都是迁移阻塞项。不要向用户承诺会静默回退到主机 NumPy。

如果 Fetched: 行超过约 90 天，请刷新快照——参见可用脚本部分。

步骤 3 — 语义性读取代码

使用 Read 和 Grep 遍历用户文件，根据 references/idioms-that-scale.md 和 references/idioms-that-block.md（完整的推理和 R-code 见上述文件）对每个数组数学区域进行分类。进行语义性阅读，而非正则表达式匹配：标记前，确认 arr 追踪到 cupynumeric 数组（或别名为它的 np.*），并检查访问是否位于热循环内。应用以下规则：

• 标记元素循环（for i in range(n): arr[i] = ...）为阻塞项；将 epoch/step/file 循环（循环体已向量化）视为正常——区分二者。
• 标记标量同步——在热循环内（每次迭代的主机同步）对 cuPyNumeric 数组调用 .item() / float() / int() / bool() / complex()；在边界处允许。
• 标记归约条件——在数组归约上的 if/while（while np.max(err) > tol:）每次迭代都会同步。
• 标记循环中的可提权分配作为可修复的低效项。
• 标记运行时代码中的 mpi4py（与 cupynumeric 配合进行数组分区/通信的代码）（R108）——但首先确认其在热路径上发出了 MPI 调用；忽略 README、构建脚本或备用启动器中的 grep 匹配。
• 在 reshape / asarray / flatten 上标记 order= 为 R109——始终标记，无论版本是警告还是静默无操作。
• 始终在多 GPU 下为 np.random.* 引用 [R304](references/idioms-that-scale.md#r304] 作为 INFO：跨 GPU 的按位一致可重现性默认不可能实现（--gpus N / LEGATE_GPUS 是 Legate 启动器参数）。
• 标记数组上的 Python 内置函数（sum/max/min/any/iter(arr)）——主机迭代回退（R110；上游最佳实践）。允许 len(arr)（形状查找；优先使用 arr.shape[0] / arr.size 以确保零维安全）。
• 标记在热循环中混合使用 cupy 和 cupynumeric（R111）；运行时不共享 GPU 内存，因此每次跳转都经过主机 NumPy。
• 在 assets/api-support.md 中查找代码调用的每个 NumPy API（符号图例见步骤 2）。

关于深层原理，阅读 references/gpu-stack.md（内存、SM、通信、调度）和 references/execution-model.md（惰性执行、同步点、映射器）。

步骤 4 — 生成结构化评估报告

按以下顺序交付报告。每个发现都引用 file:line，方便用户导航。

1. 结论——一句话概括——见下方的"结论框架"。
2. 可扩展部分（SCALES 发现）——引用具有代表性的代码行，让用户看到导入替换后哪些会加速。
3. 阻塞项（BLOCKS 发现）——每个都与 idioms-that-block.md 及 refactor-recipes.md 中的配方关联。
4. 可修复项（REFACTOR 发现）——按配方分组；一个配方通常可修复多处。
5. 兼容性/成本说明（INFO 发现）——SciPy 边界、仅单 GPU 的线性代数/FFT、RNG 布局与 --gpus N。
6. API 支持缺口——代码调用的、清单中未实现或仅单 GPU 的 API。
7. 决策框架摘要——来自 references/decision-framework.md 的关卡 1-6，标记为通过/未通过/不确定。
8. 推荐后续步骤——优先应用哪些配方、是否先移植一个模块、何时引入 cuPyNumeric Doctor。

所有 8 个部分都必须出现，即使结论是 READY 或 NOT RECOMMENDED。在空部分下写 "None for this code" 或 "n/a — see verdict" 一行即可——不要省略标题；标题是评估报告评分的结构契约。参见 assets/sample_report.md 了解实际报告示例。

步骤 5 — 转交至 cuPyNumeric Doctor 进行运行时验证

引导用户在应用配方且代码可运行后，运行 cuPyNumeric Doctor：

CUPYNUMERIC_DOCTOR=1 CUPYNUMERIC_DOCTOR_FORMAT=json CUPYNUMERIC_DOCTOR_FILENAME=doctor-report.json legate --gpus 1 main.py

cuPyNumeric Doctor 能在运行时捕获源代码审查可能遗漏的问题（标量元素访问、ndarray 迭代、高级索引、nonzero 误用、mpi4py 导入、视图的原地操作）。评估的结束语为："现在启用 cuPyNumeric Doctor 运行；以下是你需要在其输出中关注的内容。"

结论框架

定性分配结论，基于发现的类型而非分数：

按顺序应用，第一个匹配即获胜：

1. 关卡 4 失败（稀疏/图谱/ML/顺序/字符串）→ NOT RECOMMENDED。
2. 关卡 2 失败（热路径数组 < 65,536 元素/GPU，无可行的批处理路径）→ NOT RECOMMENDED。
3. 任何 R108（mpi4py） → SIGNIFICANT REFACTOR（并行层重写的成本是代价，而非不推荐的原因）。
4. 热路径中存在多个 BLOCKS（R101–R111）→ SIGNIFICANT REFACTOR（计数不会超过这个级别——每个 BLOCKS 都有记录的配方）。
5. 一两个配方可修复的 BLOCKS（例如 R101–R104 元素循环/同步）→ LIGHT REFACTOR。
6. 仅有 REFACTOR 模式（R201–R206）→ LIGHT REFACTOR；配方是机械性的。
7. 无 BLOCKS，无 REFACTOR → READY。
8. 热路径上清单中缺失的 API → 降级一级（SIGNIFICANT 保持 SIGNIFICANT，从不降为 NOT RECOMMENDED）。仅单 GPU 的 API 仅对多节点有意义。

权衡发现的类型，而非数量。 热循环中的一个 R101 比十个 R001 更重要——它破坏了 R001 本该提供的扩展能力。反之，大量 BLOCKS + R108 仍然是 SIGNIFICANT，而非 NOT RECOMMENDED——层级衡量的是工程成本，而非绝望程度。NOT RECOMMENDED 需要规模或计算模式的失败。完整框架：references/decision-framework.md。

可扩展与阻塞项一览

• SCALES（保持原样）——向量化逐元素操作、归约、matmul/einsum、np.where、每 GPU 大型模板切片 arr[1:-1, 1:-1]、out=、布尔掩码索引。
• BLOCKS（迁移前移除）——元素循环、np.vectorize、for row in arr、热循环中的 .item()/.tolist()/bool(arr)、循环中的归约式 if/while、arr[::2]、dtype=object、mpi4py、order=、min/max/sum(arr)。
• REFACTOR（应用配方）——循环中的分配、循环中的 x = x + y 重新绑定、循环中的 vstack/hstack/concatenate、np.nonzero() + 索引、视图突变 diag/flip/flatten、热循环中的 reshape。
• INFO（成本说明，非阻塞）——SciPy 导入、单设备 linalg.qr/svd、单变换 fft.*、有大小阈值的 linalg.solve/cholesky。

完整分类见 idioms-that-scale.md 和 idioms-that-block.md。清单中未列出的 API 静默忽略（超出上游表格范围——标记会造成噪音）。

阅读顺序

规范化的按序阅读指南位于 references/getting-started.md 中——阅读一次以了解方向。

对于非平凡的评估，必须阅读的是 idioms-that-block.md、refactor-recipes.md 和 decision-framework.md；其余内容（idioms-that-scale.md、gpu-stack.md、execution-model.md、partitioning-and-balance.md、case-studies.md）按需阅读。

限制

• 不运行 cuPyNumeric。 不需要运行时；这是移植前的检查。实际的加速测量发生在迁移之后。
• 不自动生成重构后的代码。 它识别需要更改的内容并指向配方；由用户（或后续代理）应用。
• 不对工作负载进行性能分析。 运行时测量请使用 legate.timing.time() 和上游的性能分析与调试指南。
• 不能替代判断。 模式匹配会遗漏日志记录中的隐式同步、隐藏 .tolist() 的装饰器、运行时数据相关的分区不匹配。需要（尤其是在边界情况下）同时阅读源代码。

示例

附带 assets/examples/ 夹具的工作评估（示例，非模板）：

结论：LIGHT REFACTOR。 scales_well.py 可以顺利翻译；needs_refactor.py 需要提权一次分配；blocks_scaling.py 通过 .item() 每次迭代同步。

可扩展部分： scales_well.py:23-31（模板计算 R005）、:40-44（归约 R002）、:18-22（逐元素 R001）。 阻塞项： blocks_scaling.py:51-58（R104 —— 热循环中的 .item()）→ RR-sync。 可修复项： needs_refactor.py:21-28（R201 —— 循环中的分配）→ RR-alloc。 下一步： 应用配方；重新评估至 READY；首次实际运行时启用 CUPYNUMERIC_DOCTOR=1。

完整的工作报告见 assets/sample_report.md。

权威上游参考资料

• 对比表（assets/api-support.md 的来源）：https://nv-legate.github.io/cupynumeric/api/comparison.html（镜像，最新）/ .../latest/api/comparison.html on docs.nvidia.com（官方）
• 最佳实践、Doctor、性能分析、与 NumPy 的差异、Legate 启动器——位于 https://docs.nvidia.com/cupynumeric/latest/（`user/practices.html`、`user/doctor.html`、`user/profiling_debugging.html`、`user/differences.html`）和 https://docs.nvidia.com/legate/latest/manual/usage/running.html
• 源代码：https://github.com/nv-legate/cupynumeric

可用脚本

用户运行此命令以刷新清单（python scripts/fetch_api_support.py --default-path）。

附带的参考文件和资源

references/ 中的文件已在必需阅读顺序上方列出（R-code 范围：idioms-that-scale.md = R001–R007 / R301–R305；idioms-that-block.md = R101–R111 / R201–R206）。资源：assets/api-support.md（已提交的 API 快照，步骤 2 中加载）、assets/sample_report.md 和 assets/examples/*.py（工作报告和夹具）。

故障排除