| Add ShapeEnv symbolic shapes API tests
Co-authored-by: nannan-2026<1794949109@qq.com>
# message auto-generated for no-merge-commit merge:
!36575 merge test-shape-env-symbolic-shapes-master into master
Add ShapeEnv symbolic shapes API tests
Created-by: nannan-2026
Commit-by: nannan-2026
Merged-by: ascend-robot
Description: # 【合入来源】
> <font color="red">**如有社区issue，请关联issue链接**</font>\
> <font color="red">**请勿携带内部流程信息（需求链接、问题单、内部issue等）**</font>
- [ ] 需求
- [ ] 问题单
- [x] issue/工单
- [ ] 重构优化
- [ ] 资料更新
关联 issue：https://gitcode.com/Ascend/pytorch/issues/1622
# 【修改方案】
> 请描述修改内容的具体实现，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列\
> 如果是需求或者重构类的PR，需要补充详细设计文档（说明上下游组件关系、时序图、类图、DFX能力等内容）
本 PR 针对 torch.fx.experimental.symbolic_shapes.ShapeEnv 相关 PyTorch 原生 API 在 master 分支补充 Torch-NPU 侧本地专项测试用例，覆盖如下 API：
- torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symboolnode
- torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symfloatnode
本 PR 仅涉及测试用例补齐，不修改 torch_npu/ 功能代码，不新增 NPU 算子实现，不改变现有 API 行为。
说明：
- master 分支不提交 test_upstream patch；
- 对于已有 PyTorch 上游社区用例的 API，相关 test_upstream patch 已在 release 分支提交；
- 本 PR 仅针对 PyTorch 上游社区缺少充分、直接专项验证的 API 新增本地测试文件。
## 一、API 功能说明
1. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symboolnode
该 API 用于根据 symbolic boolean expression 创建 torch.SymBool，用于表达符号化布尔条件。
2. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symfloatnode
该 API 用于根据 symbolic float expression 创建 torch.SymFloat，用于表达符号化浮点值。
## 二、上游社区用例分析与用例补齐说明
经检索 PyTorch 上游社区测试用例，本次 issue 中部分 API 已存在上游测试覆盖，部分 API 缺少充分、直接的专项验证。
1. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symbolic_sizes_strides_storage_offset
PyTorch 上游社区已有相关测试，位于 test/dynamo/test_misc.py。该 API 的上游用例 NPU 适配已通过 release 分支的 test_upstream patch 提交。根据要求，master 分支不提交 test_upstream patch。
2. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_unbacked_symbool
PyTorch 上游社区已有相关测试，位于 test/dynamo/test_misc.py。该 API 的上游用例 NPU 适配已通过 release 分支的 test_upstream patch 提交。根据要求，master 分支不提交 test_upstream patch。
3. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symintnode
PyTorch 上游社区已有相关测试，位于 test/test_python_dispatch.py。该 API 的上游用例 NPU 适配已通过 release 分支的 test_upstream patch 提交。根据要求，master 分支不提交 test_upstream patch。
4. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symboolnode
经检索，PyTorch 上游社区中未发现该 API 充分、直接的专项验证用例。
5. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symfloatnode
经检索，PyTorch 上游社区中未发现该 API 充分、直接的专项验证用例。
因此，本 PR 在 master 分支新增本地专项测试文件：
- test/fx/experimental/test_symbolic_shapes.py
用于集中验证 torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symboolnode 和 torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symfloatnode 的基础行为和 NPU 侧兼容性。
## 三、test_upstream patch 说明
本 PR 为 master 分支测试 PR，不涉及 test_upstream patch。
原因如下：
1. master 分支根据任务要求不提交 test_upstream patch；
2. 对于已有 PyTorch 上游社区测试覆盖的 API，test_upstream patch 已分别提交到 release 分支；
3. 本 PR 仅新增本地测试文件，验证上游社区缺少充分直接测试的 ShapeEnv.create_symboolnode 和 ShapeEnv.create_symfloatnode。
因此，本 PR 不包含以下文件：
- test_upstream/test/dynamo/test_misc.py.patch
- test_upstream/test/test_python_dispatch.py.patch
## 四、新增测试文件说明
本 PR 新增测试文件：
- test/fx/experimental/test_symbolic_shapes.py
该文件用于集中验证 torch.fx.experimental.symbolic_shapes.ShapeEnv 相关 API 的基础兼容性。文件开头已补充英文说明，说明该文件用于补充 ShapeEnv symbolic shape API 的 NPU 侧验证用例，并可继续扩展同类 API 测试。
文件开头说明如下：
"""
Add validation cases for torch.fx.experimental.symbolic_shapes.ShapeEnv APIs on NPU:
1. PyTorch community lacks sufficient and direct API validations for these APIs, so this file is added.
2. This file validates ShapeEnv.create_symboolnode and ShapeEnv.create_symfloatnode.
3. This file is extendable for other torch.fx.experimental.symbolic_shapes.ShapeEnv APIs.
"""
新增测试覆盖以下场景：
1. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symboolnode 基础行为验证
通过 NPU Tensor 的 shape metadata 构造 symbolic expression，调用 ShapeEnv.create_symboolnode 创建 torch.SymBool，并验证返回类型和布尔结果。
2. torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symfloatnode 基础行为验证
通过 NPU Tensor 的 shape metadata 构造 symbolic expression，调用 ShapeEnv.create_symfloatnode 创建 torch.SymFloat，并验证返回类型和具体数值结果。
## 五、NPU 适配说明
本次涉及的 API 均属于 torch.fx.experimental.symbolic_shapes.ShapeEnv Python 层 symbolic shape 相关接口，不涉及新增 NPU 算子实现，也不涉及 C++、Kernel 或底层算子逻辑修改。
但测试用例中涉及 Tensor，因此需要确保测试 Tensor 运行在 NPU / 当前 accelerator 侧。
新增本地测试文件中使用如下方式获取当前 accelerator：
device_type = acc.type if (acc := torch.accelerator.current_accelerator()) else "cpu"
并通过如下方式将测试 Tensor 迁移到当前设备：
tensor = torch.ones(2, 3).to(device_type)
在 Torch-NPU 测试环境中，当前 accelerator 为 NPU，因此测试 Tensor 会通过 .to(device_type) 迁移到 NPU 侧运行，满足新增用例涉及 Tensor 必须运行在 NPU 侧的要求。
## 六、涉及版本说明
本次用例补齐分别提交到以下目标分支：
- v2.7.1
- v2.9.0
- v2.10.0
- v2.11.0
- v2.12.0
- master
各版本均单独提交 PR，目标分支与源码分支一一对应。
本 PR 为 master 分支对应的测试 PR。
说明：
1. release 分支提交 test_upstream patch 和本地测试；
2. master 分支不提交 test_upstream patch，仅提交本地测试；
3. 文档资料补齐通过单独文档 PR 提交到 v2.7.1 分支；
4. 本次根据当前任务要求提交上述分支，不涉及 v2.8.0 分支。
# 【资料变更】
> 请确认是否涉及资料变更。如涉及，需要在PR中体现，并简要说明修改内容。如不涉及，需填写“不涉及”
不涉及。
本 PR 仅补齐 master 分支本地测试用例，不直接修改 docs/zh/native_apis 资料文档。
资料支持情况已同步检查：
1. 本次涉及的 API 均属于 torch.fx.experimental.symbolic_shapes.ShapeEnv 下的 Python 层 symbolic shape 相关接口；
2. 经检查，相关 API 在 docs/zh/native_apis 中需要补充支持状态记录；
3. 本测试 PR 仅负责补齐 test/fx/experimental/test_symbolic_shapes.py 测试用例，不直接修改资料文档；
4. 相关 API 的 docs/zh/native_apis 支持状态通过单独资料 PR 补充；
5. 文档 PR 仅提交到 v2.7.1 分支，并刷新 docs/zh/native_apis 下要求版本的 API 支持状态。
配套文档 PR：
- 待补充：Add ShapeEnv symbolic shapes API documentation
# 【接口变更】
> 请确认是否涉及跨代码仓或者客户面可见的接口变更。如涉及，需要详细说明接口以及对应的变更内容，同时需要在资料中体现。如不涉及，需填写“不涉及”
不涉及。
本 PR 不修改客户可见接口，不修改 API 行为，仅新增测试用例验证现有 API 兼容性。
# 【功能验证】
> 说明测试场景，测试方法。如果本次测试方式与常规单元测试不同，请详细说明您的测试步骤\
> 新增/变更内容是否已新增/适配UT测试用例看护，并补充测试自验证截图
新增测试内容：
- test/fx/experimental/test_symbolic_shapes.py
测试场景：
1. 验证 torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symboolnode 可基于 NPU Tensor shape metadata 创建 torch.SymBool；
2. 验证 torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symfloatnode 可基于 NPU Tensor shape metadata 创建 torch.SymFloat；
3. 验证新增测试中涉及的 Tensor 已通过 .to(device_type) 迁移到当前 accelerator / NPU 侧运行；
4. 验证该组 Python 层 symbolic shape API 不需要新增 NPU kernel 实现即可在 Torch-NPU 环境中完成基础行为验证。
本地验证命令：
cd /tmp
python /root/torch_npu_api_task/pytorch-master/test/fx/experimental/test_symbolic_shapes.py
本地验证结果：
..
----------------------------------------------------------------------
Ran 2 tests in 1.251s
OK
说明：
该组 API 为 torch.fx.experimental.symbolic_shapes.ShapeEnv Python 层 symbolic shape 相关接口，不涉及 NPU 算子计算。本次测试主要验证 API 功能行为与 PyTorch 原生保持一致，同时确保测试中涉及的 Tensor 运行在当前 accelerator / NPU 侧。
# 【CheckList】
> PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x]
- [x] 代码注释完备，正确记录错误日志
- [x] 代码实现进行了返回值、空指针等校验
- [x] PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等
- [ ] PR持续集成流水线（CI）执行通过，代码检查无异常
See merge request: Ascend/pytorch!36575 | 5 天前 |
