Python 二次开发 SAP2000 概述

阿阳的 SAP2000 二次开发简明教程，本系列博客仅用于个人学习，除此之外，无其他任何用途。

Blog Links

• Python 二次开发 SAP2000 概述
• Python 二次开发 SAP2000 定义
• Python 二次开发 SAP2000 绘制
• Python 二次开发 SAP2000 指定 (未完待续)
• Python 二次开发 SAP2000 分析 (未完待续)
• Python 二次开发 SAP2000 设计 (未完待续)
• Python 二次开发 SAP2000 实例

因个人能力有限，该系列博客难免有所疏漏/错误，不妥之处还请各位批评指正。

本系列博客暂未全部完结，极其不定期的更新。

转载请注明出处！

一、前沿

  SAP2000 (Structure Analysis Program 2000) 是由美国 Computer and Structure Inc.(CSI) 公司开发研制的通用结构分析与设计软件，在世界范围内应用广泛。

  通过 SAP2000 API (Application Programing Interface/应用软件编程接口)，用户便可编写程序控制 SAP2000，调用 SAP2000 中的各种功能，实现自动建模、自动分析，还可以实现自动调整参数、迭代运行等。

二、pywin32库

  pywin32 是一个 Python 库，为 Python 提供访问 Windows API 的扩展，提供了齐全的 windows 常量、接口、线程以及 COM 机制等，了解更多详见博客：如何利用Python和win32编程避免重复性体力劳动（一） 。

  如已安装 Anaconda，在 Anaconda Prompt 中键入 pip install pywin32 便可自动完成该库的导入；如未安装 Anaconda，也可 pip 手动导入，其在PyPI (Python Package Index) 上的注册地址为： https://pypi.org/project/pywin32 。

  本文通过 pywin32 库调用 SAP2000 程序，本文中的 SAP2000 版本为 v15.2.1，其余版本的调用类似。

三、帮助文档

  SAP2000 二次开发的官方帮助文档为 CSi_OAPI_Documentation ，该文件位于 SAP2000 的安装路径内，只要你的电脑中安装了 SAP2000，它就一定存在。

  按照如下方式操作可快速找到 CSi_OAPI_Documentation 文件：

    1. 安装文件搜索神器 Everything 。

    2. Everything 搜索栏内输入 CSi_OAPI_Documentation.chm 。

  如下图所示，便可看到 CSi_OAPI_Documentation 文件及其所在路径。

  此外，按如上方式还可得到的随软件一同安装到你电脑中的官方参考文档有：

  • SAP2000_cn.chm —— SP2000 Help 中文版

  • SAP2000.chm —— SP2000 Help 英文版

  • SAP2000Sched_cn.chm —— SP2000 Construction Scheduler / 施工进度表 和 非线性静力阶段施工荷载工况 中文版

四、访问SAP2000

#!/usr/bin/env python
# -*- coding: utf-8 -*-

'''
=============================
Author: DalNur 
Email: [email protected]
=============================
'''

import win32com.client

SapObject = win32com.client.Dispatch("Sap2000v15.SapObject")  # create Sap2000 object
SapObject.ApplicationStart()  # start Sap2000 application
SapModel = SapObject.SapModel  # create SapModel object
SapModel.InitializeNewModel(9)  # initialize model

  初始化模型的单位为：N_mm_C 。

Item	eUnits enumeration
kN_m_C	6
N_mm_C	9
N_m_C	10

4.1 ProgID

  上述代码中，“Sap2000v15.SapObject” 为 ProgID，根据 SAP2000 版本的不同，ProgID 可能发生变化，部分版本 SAP2000 的 ProgID 如下：

SAP2000 版本	ProgID
Sap2000v15	Sap2000v15.SapObject
-	-

  其余版本 SAP2000 的 ProgID 在官方二次开发帮助文档中查看，具体查找位置如下图所示。

五、文件

5.1 新建

ret = SapModel.File.NewBlank()  # create new blank model

Remarks ：

  1. 不要使用该函数来加载一个已经存在的模型，该该函数仅用于创建新模型以及呼叫程序启动 / 初始化新模型。

  2. 如果新空白模型成功创建则函数的返回值为 0 ，否则函数返回非 0 数值。

5.2 打开

fileName = "C:\SapAPI\Example 1-019a.sdb"
ret = SapModel.File.OpenFile(fileName)  # open an existing file

5.3 保存

ret=SapModel.File.Save("C:\SapAPI\x.sdb")  # save SDB file

Remarks ：

  1. 如果指定文件名，则它须含拓展名 .sdb；如果不指定文件名，则使用当前名称将其保存。

  2. 如果文件没有当前名称，即文件为新建文件，此前从未保存过，则该函数报错： no file name specified 。

  3. 文件被成功保存，则该函数返回值为 0 ，否则函数返回非 0 数值。

5.4 退出

  当完成模型创建后，需要关闭 SAP2000 应用程序，此时，可采用如下 Python 代码实现：

SapObject.ApplicationExit(False)

  此外，SapModel 和 SapObjectobjects 必须设置为空，Python 代码如下：

SapModel = 0 SapObject = 0

  设置对象为空是非常重要的一步，它将断开用户程序与 SAP2000 间的联系，释放系统资源。如果对象没有设置为空，则 SAP2000 应用程序没有被完全关闭，仍然占用系统内存。此时，你可以在 Windows 任务管理器进程中看到，SAP2000 仍然运行。

  综上，在建模完成后的最后一步，应退出 SAP2000 应用程序，释放其占用的系统内存，完整的 Python 代码如下：

ret = SapObject.ApplicationExit(False)  # close Sap2000
SapModel = 0
SapObject = 0

六、视图

6.1 刷新视图

ret = SapModel.View.RefreshView(Window=0, Zoom=False)  # refresh view, update (initialize) zoom

Parameters	Description
Window	This is 0 meaning all windows or an existing window number. It indicates the window(s) to have its view refreshed.
Zoom	If this item is True, the window zoom is maintained when the view is refreshed. If it is False, the zoom returns to a default zoom.

Remarks ：

  This function refreshes the view for the specified window(s). It returns zero if the window views are successfully refreshed, otherwise it returns a nonzero value.

6.2 刷新窗口

ret = SapModel.View.RefreshWindow(Window=0)  # refresh all windows

七、颜色

  SAP2000 中可以为截面、材料等指定不同的颜色，以便于用户更直观的查看所创建的模型。若用户没有特意指定相应的颜色，则程序自动采用系统默认配色。用户如想自定义颜色，则需要为函数中的变量 color 指定数值，以定义颜色。如指定某框架截面属性的颜色为蓝色：

color = 16711935
ret = SapModel.PropFrame.SetTube(secName, matName, t3, t2, tf, tw, color)

  color 为非负整数，取值范围为 [ 0, 16777215 ]，为十进制下的颜色代号，是由 RGB 颜色值转化而来的，具体换算公式如下：

${color} = R + 256 × G + 256 × 256 × B$

  例如：对于白色（R=255,G=255,B=255），其颜色代号 color 为 255 + 256 × 255 + 256 × 256 × 255 = 16777215。

  常用标准颜色代号如下：

颜色	color	颜色	color
黑色	0	青色	16776960
红色	255	蓝色	16711680
黄色	65535	洋红	16711935
绿色	65280	白色	16777215

  该颜色定义方式与 AutoCAD 二次开发中关于颜色的定义方式相一致，如想了解更多，详见博客 【Python AutoCAD 系统设置 】。

八、示例

import win32com.client  # 库导入
SapObject = win32com.client.Dispatch("Sap2000v15.SapObject")  # 创建Sap2000对象
SapObject.ApplicationStart()  # 启动Sap2000程序
SapModel = SapObject.SapModel  # 创建SapModel对象
SapModel.InitializeNewModel(10)  # 初始化模型，设置单位为N_m_C。

# call Sap2000 API functions here to perform desired tasks
# in this example a new 2D frame is created from template
ret = SapModel.File.New2DFrame(0, 3, 124, 3, 200)

# save model
import os
APIPath = 'C:\API'
if not os.path.exists(APIPath):
 try:
     os.makedirs(APIPath)
 except OSError:
     pass
ret = SapModel.File.Save(APIPath + os.sep + 'API_1-001.sdb')

# close the Sap2000 application, if desired
ret = SapObject.ApplicationExit(False)

# set the objects to Nothing
# at the end of your program ALWAYS terminate the objects in this manner
SapModel = 0
SapObject = 0

# open an existing file
SapObject = win32com.client.Dispatch("Sap2000v15.SapObject")
SapObject.ApplicationStart()
SapModel = SapObject.SapModel
SapModel.InitializeNewModel()
ret = SapModel.File.OpenFile("C:\API\API_1-001.sdb")

#switch to k-in units
kip_in_F = 3;
ret = SapModel.SetPresentUnits(kip_in_F)

# refresh view, update (initialize) zoom
ret = SapModel.View.RefreshView(Window=0, Zoom=False)

九、尾声

  以上，便是关于 Python 语言二次开发 SAP2000 的简单介绍，如有疑问欢迎邮件来询。

  仅以此文为我 Python 调用 SAP2000 的相关工作做一个总结，同时也为有需要的人提供多一点参考。

  胸藏文墨怀若谷，腹有诗书气自华，希望各位都能在知识的 pāo 子里快乐徜徉。

  因个人水平有限，文中难免有所疏漏，还请各位大神不吝批评指正。

  最后，祝各位攻城狮们，珍爱生命，保护发际线！

  欢迎大家点赞、评论及转载，转载请注明出处！

  为我打call，不如为我打款！

---

十、参考文献

[1]. SAP2000中文版使用指南 (第二版). 北京金土木软件技术有限公司 & 中国建筑标准设计研究院 编著.

[2]. SAP2000 Help. Computers and Structures， Inc.