【合入来源】

任务：【开源实习】Torch-NPU API一致性对齐：补齐测试用例、API功能对齐、补齐文档（15）#1621
关联issue：API一致性说明：torch.fx.experimental.symbolic_shapes.ShapeEnv 系列方法在 NPU 环境无需适配

请勿携带内部流程信息（需求链接、问题单、内部issue等）

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

本次提交对应 Torch-NPU API 补齐任务，涉及以下 5 个 API：

• torch.fx.experimental.symbolic_shapes.ShapeEnv.create_symbol
• torch.fx.experimental.symbolic_shapes.ShapeEnv.bound_sympy
• torch.fx.experimental.symbolic_shapes.ShapeEnv.check_equal
• torch.fx.experimental.symbolic_shapes.ShapeEnv.cleanup
• torch.fx.experimental.symbolic_shapes.ShapeEnv.bind_symbols

【API 功能介绍】

• create_symbol：在ShapeEnv中创建一个带初始值的符号变量，返回sympy.Symbol对象。属于符号形状管理基础操作。
• bound_sympy：计算符号表达式的上下界，返回包含lower和upper属性的边界对象。属于符号表达式分析操作。
• check_equal：校验两个ShapeEnv实例的符号状态是否完全一致。属于符号环境对比操作。
• cleanup：清理ShapeEnv中未使用的符号变量，释放内存。属于符号环境管理操作。
• bind_symbols：将符号变量与具体值绑定，返回绑定后的映射字典。属于符号变量绑定操作。

【社区用例分析】

所有5个API均属于1.3类API（上游无专门测试用例，需自行编写并提交PR到test目录）：

1. 上游PyTorch仓库中，test/fx/目录下无任何针对ShapeEnv核心方法的独立测试文件
2. 虽然在test/dynamo/、test/export/等目录中有间接使用ShapeEnv的代码，但都是作为其他功能的依赖组件调用
3. 没有针对上述5个API的参数合法性、返回值正确性、异常处理等核心行为进行独立验证
4. 因此需要新增专门的测试文件，覆盖所有API的基础功能场景

【修改方案】

1. 新增测试文件test/fx/test_shape_env_methods.py，为每个API编写独立的测试用例
2. 测试用例严格遵循PyTorch单元测试规范，使用torch.testing._internal.common_utils.TestCase基类
3. 每个测试用例聚焦核心功能，无冗余逻辑：
   • test_create_symbol：验证符号变量的类型和命名规则
   • test_bound_sympy：验证简单符号表达式的边界计算正确性
   • test_check_equal：验证空ShapeEnv实例的相等性校验
   • test_cleanup：验证环境清理后可以正常创建新的符号变量
   • test_bind_symbols：验证空符号列表的绑定行为
4. 测试用例无硬件强相关代码，同时兼容昇腾NPU环境与CPU环境

【资料变更】

不涉及。本PR仅补充测试用例，不包含文档修改。

【接口变更】

不涉及。未修改任何跨仓接口，也未改变用户可见的API行为。

【功能验证】

测试环境

• 硬件：昇腾910B NPU
• 软件：CANN 8.5.0 + torch 2.9.0 + torch-npu 2.9.0
• 测试平台：HiDevLab在线开发环境

测试场景1：新增测试用例验证

执行命令：

python -m pytest test/fx/experimental/test_symbolic_shapes.py::TestShapeEnvCoreMethods -v

测试日志：

=========================================================================== test session starts ===========================================================================
platform linux -- Python 3.11.13, pytest-9.0.2, pluggy-1.6.0 -- /usr/local/bin/python
cachedir: .pytest_cache
rootdir: /workspace/pytorch_2373
configfile: pyproject.toml
collected 5 items                                                                                                                                                         

test/fx/experimental/test_symbolic_shapes.py::TestShapeEnvCoreMethods::test_bind_symbols PASSED                                                                     [ 20%]
test/fx/experimental/test_symbolic_shapes.py::TestShapeEnvCoreMethods::test_bound_sympy PASSED                                                                      [ 40%]
test/fx/experimental/test_symbolic_shapes.py::TestShapeEnvCoreMethods::test_check_equal PASSED                                                                      [ 60%]
test/fx/experimental/test_symbolic_shapes.py::TestShapeEnvCoreMethods::test_cleanup PASSED                                                                          [ 80%]
test/fx/experimental/test_symbolic_shapes.py::TestShapeEnvCoreMethods::test_create_symbol PASSED                                                                    [100%]

============================================================================ 5 passed in 4.11s ============================================================================

【CheckList】

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