摘要：本文简要介绍了SAP2000应用编程接口即CSi OAPI的功能特点及其在结构分析中的应用。我们以空间网格结构建模分析过程为例详细阐述了CSi OAPI在结构参数化建模、分析及后处理中的流程和方法。本文对应用编程接口及Python语言在结构分析方面的使用进行了初步的探索，对同类型的工程项目具有借鉴意义。
关键词：CSi OAPI；Python；参数化建模；结构分析；空间网格结构
引言
SAP2000是美国CSi公司(Computer and Structures Inc.)开发研制的通用结构分析程序，是一款集成化、高效率的通用结构分析设计程序，在世界各国的结构分析项目中得到广泛应用。SAP2000采用基于对象的有限元技术，可以实现方便的建模，并具有稳定的分析内核，可对其他分析程序的结果进行对比和校核。
CSi OAPI (CSi Open Application Programming Interface)，即CSi 开放应用编程接口，原名SAP2000 API，是SAP2000提供的二次开发接口。它包含了SAP2000中大部分功能的函数，通过调用可以实现与SAP2000等效的操作或扩充SAP2000的功能。并且，通过程序操作可以方便地实现批处理、参数化等过程。CSi OAPI目前支持C#、Visual Basic、Fortran、Matlab和Python等常用编程语言和应用程序。
Python是一种面向对象、解释型的计算机程序设计语言。其语法简洁清晰，具有很强的可读性，支持面向对象的程序设计。Python属于脚本语言，具有丰富和强大的函数库，它常被昵称为胶水语言，能够把用其他语言制作的各种模块很轻松地联结在一起。基于这一特性，很多程序将Python作为二次开发的接口语言进行支持，结构分析中常用的Abaqus即支持Python进行二次开发，新版本的CSi OAPI也开始支持Python。本文中涉及的程序即采用Python语言编写。
本文拟通过一个典型的二次开发程序，介绍CSi OAPI应用的一般过程，实现对SAP2000既有功能的扩充，使其能更有效地用于结构分析和设计。
1 CSi OAPI开发要点
在SAP2000 最初是在V11版本中推出了应用编程接口功能模块，原名SAP2000 API，作为开放给用户进行扩充开发的应用程序接口。在SAP2000 V15中，SAP2000不仅完成了诸如界面上的重大改进，也进一步增加完善了API功能，并且API不只适用于SAP2000程序，同样适用于CSIBridge程序中，此次版本的API更名为CSi OAPI[1]。在最新的SAP2000 V20版本中，CSi OAPI的各项功能又进行了升级和强化。
CSi OAPI作为一个通用性强的工具，允许用户通过编程的方式，利用API调用函数，在结构建模、分析和设计过程中进行定制来实现参数化的模型生成、分析和设计，完成自定义的结果输出和数据提取。同界面交互操作的方式相比，这种操作方式将扩展设计人员的分析能力，提高效率。用户还可以应用OAPI实现SAP2000分析程序与第三方软件的连接，实现与其他程序对建筑结构模型信息的共享。并且，通过Python可以方便地进行数据提取与分析，并对分析结果进行可视化，对进一步的优化提供了便利。
在安装了SAP2000(V11版本以上)和相应开发环境的计算机上，都可以利用CSi OAPI进行开发。大多数编程语言都可以与OAPI结合来实现用户程序的定制，如C#，Visual Basic，C++，Fortran，Matlab、Python、VBA等。
不同的编程语言有各自的语法、限制和特点，但程序开发过程都遵循相同的基本原理。
目前应用OAPI二次开发主要有以下两种方式，外部调用和内部调用。外部调用指通过一个调用API的程序，自动启动SAP2000程序，然后执行批处理的操作。内部调用则是在SAP2000程序内，封装集成SAP2000既有的功能。
OAPI中的函数和数据以面向对象的方式组织在一起，在程序初始时定义类对象并初始化。各个函数可作为该对象的方法进行调用。OAPI中的函数组织如图1所示。
OAPI参数分为ByVal和ByRef两种，第一种只是将参数的值传递给函数，第二种将参数的地址传递给函数，通过第二种方法，可得到多个返回值。参数允许使用默认值，默认值在函数定义中存在，在调用函数时可以不重新赋予。若要给后面参数赋值，前面参数可不赋值，但位置要留出。
OAPI函数以一个长整形数作为返回值，如函数执行成功，返回值为0；否则返回非零值。通过函数返回值，可以判定OAPI函数执行情况。
图1 OAPI 函数组织图
以下为利用python语言调用CSi OAPI的部分程序代码：
import os
import win32com.client
import math
zso= win32com.client.Dispatch(("
Sap2000v15.SapObject"))
zso.ApplicationStart()
zsm = zso.SapModel
zsm.InitializeNewModel()
ret = zsm.File.NewBlank()
2 空间网格建模分析要点
空间网格结构包括球面网壳、圆柱面网壳、平板网架、弦支穹顶等多种。球面网壳又可以分为凯威特型、联方型、施威德勒型、肋环型、短程线型等。空间网格结构的组成特点是：以杆件单元为主；节点和杆件的数量大；构成具有较强的规律性，适合利用程序自动生成并参数化施加荷载和约束。
各种球面网壳的建模过程均类似，下面以凯威特型K6球面网壳为例，介绍参数化建模过程。
2.1 几何构成和控制参数
图2所示是一个K6凯威特球面网壳的控制参数示意图。凯威特型单层球面网壳的几何构型可由网壳跨度S，矢高H，扇区数Kn，径向等分数nx几个参数确定。本例中Kn=6，nx=6。网壳节点编号图和杆件编号图分别如图3、图4所示。
图2 凯威特网壳参数示意图
通过控制参数，可在确定的笛卡尔坐标系下计算得到各个节点的空间三维坐标；根据节点坐标和球面网壳的空间几何组成，生成节点和全部杆件[3、4]。
2.2 节点和杆件建立
规定球面网壳球面的球心作为空间三维坐标系的原点，以竖直向上方向作为Z轴，以一水平轴作为X轴，由右手定则确定Y轴方向。则确定了空间坐标系以及网壳在其中的定位。
在CSi OAPI中，分别通过PointObj和FrameObj两个函数建立节点对象和杆件对象，python语法如下：
PointObj.AddSpherical(Radius，alpha，beta，pointname，name)
FrameObj.AddByPoint(pointname1，pointname2，name)
FrameObj.AddByCoord (xi，yi，xj，yj，name)
图5所示为生成后的完整网壳模型。图6、图7为节点和杆件的透视图。
图3 凯威特网壳节点编号图
图4 凯威特网壳杆件编号图
图5 SAP2000中凯威特网壳结构模型
笛卡尔坐标系下节点坐标可按下列公式计算：
计算所得到的节点坐标可记录在一个一维数组中。按照结构杆件的构成规律，可以通过连接对应节点形成所有杆件。
图6 通过程序生成的节点图
图7 通过程序生成的杆件图
2.3 支座约束
一个完整的有限元模型包括节点、单元、支座约束、材性信息、截面信息、方位、支座位移等信息。
通过网壳组成规律，可利用OAPI给底部节点对象设置约束，约束可以是固定、铰接和弹性支座，并可施加支座位移。通过对一个长度为6的布尔数组赋值即可实现。
语法为：PointObj. SetRestraint (pointname, [True, True, True, True, True, True])
本例中，将支座全部设置为固定支座，如图8、图9所示。
图8 网壳支座示意图
图9 网壳节点荷载示意图
2.4 节点荷载的施加
在SAP2000中，可直接对点对象施加节点荷载。
在网壳结构的构造中，屋面荷载直接传到网壳节点上，杆件为轴力杆，不承受横向荷载，所以可将荷载按点荷载的方式施加在结构上。
语法为：PointObj.SetLoadForce(point，loadpattern， [0,0,-force,0,0,0])
2.5 结构分析
参数化模型建立之后，可通过交互方式或命令方式进行结构分析和结果数据的后处理。
在SAP2000环境下，需要先保存模型然后再运行分析，python代码如下。
APIPath = 'C:SAPAPI_xzh' #save model
if not os.path.exists(APIPath):
try:
os.makedirs(APIPath)
except OSError:
pass
ret = zsm.File.Save(APIPath + os.sep + 'SAPAPI.sdb')
#run model
ret = zsm.Analyze.RunAnalysis()
经过分析后，可以得到内力图、位移图等静力计算结果和特征值计算结果，如图10、图11所示。
图10 部分静力计算结果
图11 部分特征值计算结果
3 结论与展望
本文结合空间网格结构的建模特点和SAP2000 API的应用，介绍了在SAP2000平台上利用OAPI进行空间网格结构快速参数化建模的方法和流程，为了说明基本原理，本文通过一个简单的空间网格结构实例来具体介绍程序编制的过程和步骤，但利用API能做的工作远不止这些。API中包含了SAP2000中绝大部分功能的实现函数，并且与通用编程语言结合之后，可以利用python数据分析库来进行结果后处理，大大扩展SAP2000的功能并显著提高效率，并且通过程序控制，用批处理的方式进行多步骤的分析则更能显现API的便捷。后续开发可以在以下几个方面扩展。
3.1 单层球面网壳整体稳定分析
空间网格结构技术规程(JGJ7-2010) 4.3.1条规定：单层网壳以及厚度小于跨度1/50的双层网壳均应进行稳定性计算。稳定性计算可按考虑初始缺陷的几何非线性分析，初始缺陷按第一阶振型，位移最大值取为跨度的1/300[3]。
通过API可以读取特征值分析的一阶振型，按照比例通过改变节点坐标来施加初始缺陷，进而进行几何非线性分析来获取网壳结构的整体稳定系数。这个过程通过界面交互方式建模将耗费大量建模时间甚至难以实现。
3.2 数据共享与模型转换
通过模型信息的建立，可以完成空间网格结构模型建立，包括节点、单元、截面特性、材性、约束、荷载等有限元模型全部要素。通常数据转换的方式是对文本的处理，而通过API可直接访问SAP2000数据库，对数据进行格式化的文本输出。
3.3 节点刚度对网壳稳定性的影响
在钢结构分析中，节点都模型化为完全铰接或完全刚接，但实际的节点构造都是半刚接，在强度分析中，节点刚度会影响内力分布，在稳定分析中，节点刚度则会显著影响极限荷载。
在Ansys中，节点刚度只能通过弹簧单元Combin14或矩阵单元Matrix27进行节点刚度设置，设置时需要在杆件端部插入弹簧单元。而SAP2000中的杆对象中已经包括了节点刚度的考虑，只需在程序中设定刚度系数并赋值即可。
此外，通过API可以实现自定义荷载组合，包络设计，简单的优化，多步分析等。
参考文献
[1]北京金土木软件技术有限公司. SAP2000中文版使用指南[M]. 北京：人民交通出版社, 2012.
[2]陈志华. 空间钢结构APDL参数化计算与分析[M]. 北京：中国水利水电出版社，2009.
[3]中国建筑科学研究院. JGJ7-2010. 空间网格结构技术规程[S]. 北京：中国建筑工业出版社, 2010.
论文作者:李皓
论文发表刊物:《基层建设》2019年第12期
论文发表时间:2019/7/16
标签：节点论文; 结构论文; 参数论文; 荷载论文; 程序论文; 函数论文; 建模论文; 《基层建设》2019年第12期论文;