Python 2 SAM API：已验证接口与失败清单 / Verified Python 2 SAM APIs and Known Failures

📅 创建时间：2026-07-23
🏷️ 标签：#SAM #Python2 #API #Section #网格编辑
📚 前置知识：00-overview-and-evidence
📖 系列导航：总目录 · 上一篇：02-pyd-registration-and-fragments · 下一篇：04-cpp-sdk-mesh-api

第4部分：已验证的 Python 2 SAM API

4.1 推荐脚本骨架

python

# -*- coding: utf-8 -*-
from __future__ import print_function

from sam import *
from samConstants import *
from caeModules import *

SAM 控制台运行：

python

import utils
utils.execfile('D:/path/to/script.py')

不要在控制台执行脚本中依赖 Python 3 语法，包括：

text

f-string
pathlib
函数类型注解
dataclass
Python 3 专用 subprocess 参数

4.2 数据库生命周期：A级验证

以下调用已经用于成功生成 1338_repaired_v01.sam：

python

Mdb()
openMdb(pathName=SOURCE_PATH)

model = mdb.models['Model-1']
part = model.parts['Part-5000t']

mdb.saveAs(pathName=OUTPUT_PATH)

推荐原则：

python

if os.path.exists(OUTPUT_PATH):
    raise RuntimeError('Output already exists: ' + OUTPUT_PATH)

永远不默认覆盖源模型。

4.3 节点、单元与仓库读取：A级验证

python

for node in part.nodes:
    label = int(node.label)
    xyz = tuple(float(v) for v in node.coordinates)

for element in part.elements:
    label = int(element.label)
    kind = str(element.type)
    indices = tuple(int(i) for i in element.connectivity)

注意：element.connectivity 在当前模型中用于索引 part.nodes：

python

nodes = [part.nodes[int(i)] for i in element.connectivity]

按标签选择单元：

python

elements = part.elements.sequenceFromLabels(
    labels=tuple(element_labels))

位置式兼容分支也实际使用过：

python

try:
    elements = part.elements.sequenceFromLabels(labels=labels)
except Exception:
    elements = part.elements.sequenceFromLabels(labels)

不要把录制脚本中的 getSequenceFromMask() 当成稳定业务标识。Mask 会随网格编号和选择状态变化，正式工具应保存标签。

4.4 Set：A级验证

python

region = part.Set(
    elements=elements,
    name='SET_REPAIR_TARGET')

已确认的重要兼容问题：

纯 Python 2 str 名称成功；
从 JSON 读出的 unicode 名称曾触发 TypeError: expected 1, got 0；
进入 SAM API 前应把名称转成普通字节字符串。

python

def plain(value):
    if isinstance(value, unicode):
        return value.encode('ascii', 'replace')
    return str(value)

SetFromElementLabels 的探针虽然接受调用，但创建后的仓库键名行为不稳定，因此当前推荐 sequenceFromLabels + part.Set。

4.5 壳 Section：A级验证

以下流程成功为 49,398 个未分配 S3/S4R 单元分配 12 mm 壳截面：

python

model.HomogeneousShellSection(
    name='SECTION_SHELL_T12',
    material='Beam-L',
    thickness=12.0)

region = part.Set(
    elements=elements,
    name='SET_UNASSIGNED_SHELL_T12')

part.SectionAssignment(
    region=region,
    sectionName='SECTION_SHELL_T12')

验证结果：

text

SHELL_ASSIGNED=49398
Post-check missing shell assignments=0

4.6 普通 B31 Section：A级验证

python

model.RectangularProfile(
    name='PROFILE_GENERIC_SQUARE_10X10',
    a=10.0,
    b=10.0)

model.BeamSection(
    name='SECTION_GENERIC_BEAM_10X10',
    profile='PROFILE_GENERIC_SQUARE_10X10',
    integration=DURING_ANALYSIS,
    material='Beam-L')

part.SectionAssignment(
    region=region,
    sectionName='SECTION_GENERIC_BEAM_10X10',
    n1type=UNIFORM,
    n1=(0.0, 1.0, 0.0),
    n1field='',
    offset1Type=UNIFORM,
    offset1Vector=(0.0, 0.0, 0.0),
    offset1Field='')

成功结果：

text

B31_ASSIGNED=484
OTHER_UNASSIGNED_LEFT=0
Post-check missing B31 assignments=0

n1 不能与梁轴平行。当前成功实现会从全局 X/Y/Z 中选择与梁轴最不平行的方向。

4.7 有效 Section 判断：A级验证

不能只相信 Set_unassign。真实判断必须组合：

text

Set 的单元成员
        +
SectionAssignment.region 指向的 Set
        +
SectionAssignment.sectionName

python

for assignment in part.sectionAssignments:
    set_name = assignment.region[0]
    section_name = assignment.sectionName

这套方法已用于保护已有 Section，只补真正未分配单元。

4.8 网格编辑：A级验证

在 1338_repaired_v01.sam 的成功修复中验证了：

python

part.deleteElement(elements=elements)

part.createNode(x=x, y=y, z=z)

part.Element(
    nodes=(node1, node2, node3, node4),
    elemShape=QUAD,
    intersectNodes=True)

part.mirrorElement(
    elements=elements,
    isCoordinatePlane=True,
    principalPlane=XZPLANE,
    offset=0.0,
    copyProperties=True)

part.mergeNodes(
    state=0,
    tolerance=0.005,
    keepHighLabel=False)

all_labels = tuple(element.label for element in part.elements)
all_elements = part.elements.sequenceFromLabels(labels=all_labels)
part.deleteDuplicateElement(elements=all_elements)
part.clearFreeNodes()

其中 part.Element 的第三个参数 intersectNodes=True 是 SAM 当前绑定所要求的。只传 nodes 与 elemShape 已明确失败：

text

TypeError: expected 3, got 2

4.9 视口刷新：A级验证

python

viewport = session.viewports['Viewport: 1']
viewport.setValues(displayedObject=part)

viewport.partDisplay.setValues(
    sectionAssignments=ON,
    engineeringFeatures=ON,
    mesh=OFF)

viewport.partDisplay.setValues(renderBeamProfiles=ON)
viewport.view.fitView()

4.10 Moment：B级验证，不等于总纵求解已通过

以下调用能够创建、保存并重新打开：

python

model.Moment(
    name='Moment-TotalLongitudinal-L',
    createStepName='Step-TotalLongitudinal',
    region=assembly.sets['SET-L1'],
    cm1=0.0,
    cm2=100000.0,
    cm3=0.0)

SAM V2026 拒绝曾经猜测的 Abaqus 风格 field= 参数，因此当前只使用上述六个已接受参数。

但是总纵 INP 最终出现：

text

***ERROR: badsubscript
File: ReadInp.readCloadData

原因是 SET-L1/SET-R1 没有作为有效装配级参考节点集合写入 INP。因此 Moment 只能标记为“对象持久化成功”，不能标记为“总纵载荷链端到端成功”。

第5部分：已经明确失败或需要谨慎的 Python API

5.1 禁止冒用的 ReferencePoint Set 写法

以下写法全部在 SAM V2026 中失败：

python

assembly.Set(referencePoints=(stored,), name='SET-RP')
assembly.Set(referencePoint=stored, name='SET-RP')
assembly.Set(features=(stored,), name='SET-RP')
assembly.Set(nodes=(stored,), name='SET-RP')

错误包括：

text

TypeError: keyword error on referencePoints
TypeError: keyword error on referencePoint
TypeError: keyword error on features
SAMException: object type mismatch

因此不能从 Abaqus 文档复制 assembly.Set(referencePoints=...)。

5.2 Assembly.Node 路线仍需完成运行验证

运行时 dir() 已确认 Assembly 存在：

text

Node
SetFromNodeLabels
nodes

待验证的正确候选是：

python

node = assembly.Node(coordinates=(0.0, 0.0, 3950.0))
selected = assembly.nodes.sequenceFromLabels(labels=(node.label,))
assembly.Set(nodes=selected, name='SET-L1')

在出现实际 SET_PASS、导出有效 *Node/*Nset 并完成求解前，本文不把它列为正式可用接口。

5.3 不存在的 `mergeElements`

python

part.mergeElements(elements=elements)

已明确返回：

text

AttributeError: 'Part' object has no attribute 'mergeElements'

5.4 `meshRebuild` 可调用，但不是万能修复

对胶囊孔附近单元调用 meshRebuild 后：

text

free_edges: 11042 -> 11282
closed_capsule_loops: 6 -> 2

程序已撤销修改。这说明：

API 名称存在且能够执行；
它不适合无差别修复自由边；
工具验收标准必须比较拓扑，而不是只判断调用是否成功。

5.5 `fillet`、`cornerBracket`、`openingMesh`

这些方法在运行时对象中存在，但当前项目中的尝试没有形成可靠的端到端成功案例：

fillet：所选区域返回 Failed to Create Fillet
cornerBracket：基于手工点坐标的调用失败
openingMesh：可以产生网格变化，但孔形、位置和参数未达到图纸要求

所以它们只能进入“待建最小模型验证”清单，不能在 Agent 中作为默认自动工具。

Python 2 SAM API：已验证接口与失败清单 / Verified Python 2 SAM APIs and Known Failures ​

第4部分：已验证的 Python 2 SAM API ​

4.1 推荐脚本骨架 ​

4.2 数据库生命周期：A级验证 ​

4.3 节点、单元与仓库读取：A级验证 ​

4.4 Set：A级验证 ​

4.5 壳 Section：A级验证 ​

4.6 普通 B31 Section：A级验证 ​

4.7 有效 Section 判断：A级验证 ​

4.8 网格编辑：A级验证 ​

4.9 视口刷新：A级验证 ​

4.10 Moment：B级验证，不等于总纵求解已通过 ​

第5部分：已经明确失败或需要谨慎的 Python API ​

5.1 禁止冒用的 ReferencePoint Set 写法 ​

5.2 Assembly.Node 路线仍需完成运行验证 ​

5.3 不存在的 mergeElements ​

5.4 meshRebuild 可调用，但不是万能修复 ​

5.5 fillet、cornerBracket、openingMesh ​

Python 2 SAM API：已验证接口与失败清单 / Verified Python 2 SAM APIs and Known Failures

第4部分：已验证的 Python 2 SAM API

4.1 推荐脚本骨架

4.2 数据库生命周期：A级验证

4.3 节点、单元与仓库读取：A级验证

4.4 Set：A级验证

4.5 壳 Section：A级验证

4.6 普通 B31 Section：A级验证

4.7 有效 Section 判断：A级验证

4.8 网格编辑：A级验证

4.9 视口刷新：A级验证

4.10 Moment：B级验证，不等于总纵求解已通过

第5部分：已经明确失败或需要谨慎的 Python API

5.1 禁止冒用的 ReferencePoint Set 写法

5.2 Assembly.Node 路线仍需完成运行验证

5.3 不存在的 `mergeElements`

5.4 `meshRebuild` 可调用，但不是万能修复

5.5 `fillet`、`cornerBracket`、`openingMesh`