【合入来源】

任务 https://gitcode.com/Ascend/pytorch/issues/1613
关联issue https://gitcode.com/Ascend/pytorch/issues/2431
请勿携带内部流程信息（需求链接、问题单、内部issue等）

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新

【修改方案】

请描述修改内容的具体实现，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列
如果是需求或者重构类的PR，需要补充详细设计文档（说明上下游组件关系、时序图、类图、DFX能力等内容）

本 PR 属于 Torch-NPU API 一致性对齐任务中的测试用例补齐，目标分支为 v2.10.0，面向 torch.fx.experimental.symbolic_shapes 下 5 个关联 API 完成上游用例核查、Torch-NPU 现有覆盖复查、API 行为验证和 UT 看护补充。

本 PR 仅修改：

test/fx/test_symbolic_shapes_api.py

最终变更为 85 行新增、0 行删除：新增 4 个直接 API 测试及对应英文说明注释，不修改 torch/fx/experimental/symbolic_shapes.py、torch_npu 功能源码、原有测试逻辑或 API 对外语义。

架构上下文说明

DimDynamic 与 DimConstraints 属于 PyTorch FX / Dynamo 编译前端的符号形状基础设施。它们服务于动态图捕获、动态维度约束收集、SymPy 表达式求解、强制特化识别以及约束错误信息生成，不直接执行 Tensor 数值计算。

验证对象包括 sympy.Symbol、FloorDiv、ConstantSource、torch.export.Dim 和 inspect.Signature。测试不创建 NPU Tensor、不调用 NPU 算子，也不做精度对比；重点是确认这些编译前端 API 在 v2.10.0 中可稳定调用并产生符合 PyTorch 语义的约束结果。

上游社区测试情况与用例路线判断

上游源码与测试检索范围

由于开发环境访问 GitHub 不稳定，使用 PyTorch 的 Gitee 镜像进行版本化检索：

https://gitee.com/mirrors/pytorch.git

本 PR 重点检查官方 v2.10.0 tag，并交叉检查 v2.7.1、v2.9.0、v2.11.0、v2.12.0，确认 API 和测试路线在相邻版本中的延续情况。各版本源码 torch/fx/experimental/symbolic_shapes.py 均存在 DimDynamic、DimConstraints.solve、forced_specializations、prettify_results 和 rewrite_with_congruences 定义。

官方测试目录执行的核心检索模式包括：

grep -rn "dim_constraints\.solve()" test --include="*.py"
grep -rn "\.forced_specializations()" test --include="*.py"
grep -rn "\.prettify_results" test --include="*.py"
grep -rn "\.rewrite_with_congruences(" test --include="*.py"
grep -rn "DimDynamic\." test --include="*.py"

检索日志：

/workspace/user_data/task02_logs/official_pytorch_exact_api_search_20260617_223640.log

v2.10.0 上游检索结论

API	PyTorch v2.10.0 upstream 测试情况	本 PR 路线
DimConstraints.forced_specializations	仅命中与 forced specialization 有关的测试名称，未发现对 .forced_specializations() 的直接调用。	上游缺少目标方法直接看护，新增聚焦自写测试。
DimConstraints.prettify_results	未检索到直接调用目标方法的官方测试。	新增自写测试，验证强制特化说明及建议修复。
DimConstraints.rewrite_with_congruences	未检索到直接调用目标方法的官方测试。	新增自写测试，验证表达式改写和 congruence 记录。
DimConstraints.solve	test/test_dynamic_shapes.py:3028 存在 dim_constraints.solve() 直接调用。	官方用例无需 NPU 迁移；补充轻量直接测试，形成 Torch-NPU API 文件内稳定看护。
DimDynamic	v2.10.0 官方测试中检索到 43 处 DimDynamic.* 直接使用。	不重复新增测试，复用 Torch-NPU 已有直接覆盖。

进一步查看 test/test_dynamic_shapes.py 中 solve() 调用上下文后确认，该官方用例只构造 SymPy 表达式、DimConstraints、TensorPropertySource、LocalSource 等元信息，并断言 _static_results 和 _dynamic_results。用例不包含 torch.randn、torch.tensor、.cuda()、.npu()、.to(device)、NPU 算子或 CPU/NPU 精度比较，所以不需要创建 test_upstream NPU 适配 patch。

后续官方版本的交叉检索结论一致：solve() 和 DimDynamic 有直接覆盖，其余 3 个目标方法缺少直接测试，说明该路线并非 v2.10.0 的单版本偶然结果。

Torch-NPU v2.10.0 已有测试、patch 与资料复查

在 upstream/v2.10.0 的 test、test_upstream、docs/zh/native_apis 中进行了精确计数复查。日志：

/workspace/user_data/task02_logs/ascend_pytorch_count_search_20260617_224903.log

以下 4 个方法的结果均为：

DimConstraints.forced_specializations: test=0, test_upstream=0, docs=0
DimConstraints.prettify_results:       test=0, test_upstream=0, docs=0
DimConstraints.rewrite_with_congruences:test=0, test_upstream=0, docs=0
DimConstraints.solve:                  test=0, test_upstream=0, docs=0

粗检索曾在 test/unsupported_test_cases/.pytorch-disabled-tests*.json 中命中 test_dim_constraints_solve_full，但该条目只是禁用记录，不是测试实现；最终计数已排除 disabled JSON，避免把名称记录误判成已有测试或 patch。

DimDynamic 在 v2.10.0 的 test 中有 20 处命中；当前文件的 stateless/stateful symbolic context 测试已直接使用 DUCK 与 INFER_STRIDE，所以不增加重复枚举测试。

本次覆盖 API 的功能说明、完备性分析与用例开发思路

API	功能说明	上游及当前覆盖	是否需要新开发用例	本 PR 用例思路与完备性
DimConstraints.rewrite_with_congruences	根据已知符号提示值和同余关系，改写包含整除/取模的 SymPy 表达式，并记录推导出的模约束。	v2.10.0 upstream 和 Torch-NPU 均无目标方法直接测试。	需要。	令正整数 s0 的提示值为 5，输入 FloorDiv(s0, 2)；断言输出为 s0 / 2 - 1/2，并检查记录 Mod(s0 + 1, 2)，同时覆盖返回值和 congruence 副作用。
DimConstraints.solve	汇总已添加的等式、不等式和符号关系，执行求解，并把结论分类写入静态结果、动态结果和替换关系。	upstream 有嵌入式直接调用；Torch-NPU v2.10.0 无聚焦测试和 patch。	需要轻量补充。	对 s0 >= 2 求解，断言静态结果为空、动态结果为 2 <= x；后续两个测试还调用 solve() 产生静态特化，交叉覆盖动态和静态路径。
DimConstraints.forced_specializations	从求解结果提取原本标记为动态、但被约束迫使成为具体值的维度，并根据 source/debug name 生成可读映射。	upstream 无目标方法直接调用；Torch-NPU v2.10.0 无测试。	需要。	配置 source x、调试名 dx 和等式 s0 == 4，求解后断言返回 {"dx = x": 4}，覆盖动态标记、来源映射和具体值输出。
DimConstraints.prettify_results	将约束违反和强制特化结果转换成面向用户的说明，并结合 dynamic_shapes 生成建议修复。	upstream 与 Torch-NPU v2.10.0 均无直接测试。	需要。	使用 inspect.signature、Dim("dx") 和强制特化结果调用接口；分别断言特化标题、dx = x 来源关系和 dx = 4 建议值，避免完整文本匹配造成脆弱测试。
DimDynamic	枚举符号维度动态策略，例如 DYNAMIC、DUCK、STATIC、INFER_STRIDE，供符号上下文决定尺寸和步长动态性。	upstream 有 43 处直接使用；Torch-NPU v2.10.0 已有 DUCK、INFER_STRIDE 直接测试。	不需要。	现有 stateless/stateful symbolic context 测试已验证枚举值进入上下文后的保存行为；继续复用现有覆盖，避免重复断言。

本 PR 新增 4 个直接测试；其中 solve 被 3 个测试调用，forced_specializations 被 2 个测试调用，并通过后续流程形成交叉验证。现有断言已覆盖关键输出和副作用，无需为数量增加重复测试或锁定更多私有细节。

开发前行为探测与断言稳定性

编写测试前检查了实际 API 签名：

DimDynamic => (*values)
DimConstraints => (symbol_to_source, var_to_val, marked_dynamic, source_name_to_debug_name)
rewrite_with_congruences => (self, s, expr)
solve => (self)
forced_specializations => (self)
prettify_results => (self, original_signature, dynamic_shapes,
                      constraint_violation_error, forced_specializations)

行为探测日志：

/workspace/user_data/task02_logs/task02_api_probe3_final_20260617_231527.log
/workspace/user_data/task02_logs/task02_prettify_probe_20260618_000308.log

探测确认：提示值为 5 时 FloorDiv(s0, 2) 可稳定改写为 s0/2 - 1/2 并记录 Mod(s0 + 1, 2)；下界约束可产生 2 <= x；等式特化可返回 {"dx = x": 4}；格式化结果稳定包含特化标题、来源关系和 dx = 4 建议。

断言只锁定稳定语义：prettify_results 检查三个关键子串，congruence 使用字符串集合比较，动态结果和强制特化字典采用精确断言，从而兼顾回归检测与跨版本维护性。

v2.10.0 用例充分性与分支适用性判断

上游 solve() 调用位于较大的 dynamic-shapes 流程中，主要验证整体约束生成结果；本 PR 的测试则直接构造最小 DimConstraints 对象，明确检查 _static_results 为空且 _dynamic_results 为 {"2 <= x"}。二者关注层级不同：前者提供流程级回归，后者提供 API 级故障定位，因此不是简单重复。

forced_specializations、prettify_results、rewrite_with_congruences 在 v2.10.0 upstream 中没有直接调用，若只依赖间接流程，一旦返回映射、同余记录或提示文本发生回归，很难快速定位到具体接口。新增测试分别覆盖“求解后提取特化”“生成可读修复建议”“改写表达式并记录模关系”三类独立职责，已经覆盖各方法最核心的可观察行为。

DimDynamic 的情况相反：官方有 43 处直接使用，Torch-NPU v2.10.0 也已有 20 处相关命中，当前文件还直接验证 DUCK 和 INFER_STRIDE。继续新增只枚举成员或重复字段保存的测试不会增加有效行为覆盖，因此采用已有用例看护。该取舍以缺口和行为分支为依据，而不是要求每个任务 API 都机械增加一个新函数。

上述新增断言不依赖设备张量、随机数或硬件执行结果，输入完全确定；同时避免比较 prettify_results 的完整长文本。因而用例能够在 v2.10.0 分支稳定运行，也便于后续版本沿用。

具体修改内容

本 PR 新增以下测试方法：

test_dim_constraints_rewrite_with_congruences_records_mod_guard
test_dim_constraints_solve_records_dynamic_results
test_dim_constraints_forced_specializations_reports_marked_dynamic_equalities
test_dim_constraints_prettify_results_reports_forced_specialization

具体实现：

1. 构造带正整数假设和具体 hint 的 SymPy 符号，验证 floor division 的同余改写结果及 _congruences 记录；
2. 通过 ConstantSource("x") 建立符号到来源的映射，验证范围约束求解后进入 _dynamic_results；
3. 使用 source_name_to_debug_name={"x": "dx"} 验证强制特化输出同时保留调试名、source 和具体值；
4. 使用 inspect.signature 与 torch.export.Dim 构造动态形状输入，验证说明文本包含原因和可执行修复建议；
5. 为每个新增测试补充两行英文注释，说明测试目标和关键断言；
6. 所有改动均位于现有 UT 文件，不改变原有测试和产品代码。

适配方案说明

API 适配方案

5 个目标 API 在源码和验证环境中均可正常导入、构造和调用，未发现缺失实现、签名不一致、返回语义异常或 NPU 设备相关错误。因此本 PR 不修改 API 实现、枚举成员和求解逻辑，只增加测试看护。

用例适配方案

对无上游直接用例的 3 个方法采用自写轻量测试；对已有 upstream 调用但无需设备迁移的 solve，不创建无实际内容的 test_upstream patch，而是在现有 API 测试文件中增加聚焦断言；对 upstream 与 Torch-NPU 都已有直接覆盖的 DimDynamic 不重复开发。

用例统一放在 test/fx/test_symbolic_shapes_api.py。该文件已集中看护 DimConstraints、SymbolicContext 和 ShapeEnv，可复用现有构造与断言模式。

【资料变更】

请确认是否涉及资料变更。如涉及，需要在PR中体现，并简要说明修改内容。如不涉及，需填写“不涉及”

不涉及。

本 PR 只补充 test/fx/test_symbolic_shapes_api.py 的 UT，不修改 docs/zh/native_apis。测试补齐不改变接口支持状态、签名、调用方式或用户可见行为；资料支持度更新应按任务要求由独立资料变更处理，不与本测试 PR 混合。

【接口变更】

请确认是否涉及跨代码仓或者客户面可见的接口变更。如涉及，需要详细说明接口以及对应的变更内容，同时需要在资料中体现。如不涉及，需填写“不涉及”

不涉及。

本 PR 未修改函数、类、枚举、参数列表、返回值或跨仓调用关系，仅新增测试断言和说明注释，不产生客户面可见接口变化。

【功能验证】

说明测试场景，测试方法。如果本次测试方式与常规单元测试不同，请详细说明您的测试步骤
新增/变更内容是否已新增/适配UT测试用例看护，并补充测试自验证截图

验证环境

SoC: Ascend910_9382
Python: 3.12.13
本地验证运行时: torch 2.10.0+cpu / torch_npu 2.10.0
目标代码分支: upstream/v2.10.0
venv: /workspace/user_data/venvs/torch-npu-py312

完整 UT 验证

为避免从源码目录误导入未编译的 torch_npu，从 /tmp 执行完整测试文件：

cd /tmp
/workspace/user_data/venvs/torch-npu-py312/bin/python \
  /workspace/user_data/pytorch/test/fx/test_symbolic_shapes_api.py

最终结果：

....................
----------------------------------------------------------------------
Ran 20 tests in 1.123s

OK

结果说明：完整测试文件中的 20 个测试全部通过，其中包括本 PR 新增的 4 个 DimConstraints 直接测试以及文件中原有的 SymbolicContext、ShapeEnv 等回归用例。本地安装运行时与目标分支均为 torch 2.10.0，完整测试文件未出现版本兼容失败；平台 CI 也在匹配 v2.10.0 的分支构建环境中完成验证。

测试日志：

/workspace/user_data/task02_logs/v2100_add_comments_20260618_134708.log

差异与平台检查

本地执行：

cd /workspace/user_data/pytorch
git diff --check

结果：

git diff --check: OK

同一日志同时确认注释变更为 8 行新增、0 行删除，测试文件不存在空白符错误。提交与推送后，本地 commit 与个人 fork 远端 commit 一致。

v2.10.0 最新提交：

04bcbae7b27eeaa7dbac73c48960fae8454050a6

平台验证结果：PR #38825 的 compile、UT/测试和代码规范检查均已通过。该结果确认新增测试能够在真实 v2.10.0 分支构建环境中运行，并且本 PR 未引入代码格式、依赖或编译回归。

【CheckList】

PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x]

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等
• PR持续集成流水线（CI）执行通过，代码检查无异常