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.