ANSYS Help USER300

备注
文档仅为学习记录，如有错漏之处，烦请指正。
目前文章仅为ANSYS_Help文档翻译版本，尚有翻译不准确的问题出现，后续尽量更新应用实例。

1 概述

用户程序特性(UPFs)
向用户提供丰富的FORTRAN77用户程序开发子程序和函数，用户利用它们从开发程序源代码的级别上扩充ANSYS的功能。使用这些子程序和函数，编写用户功能的源代码程序，在与ANSYS版本要求匹配的FORTRAN或c++编译器上重新编译和连接，生成用户版本的ANSYS程序。另外，还提供了外部命令功能，允许用户创建ANSYS可以利用的共享库。

1.1 单元描述

Mechanical APDL提供了一种方便的方法来创建自定义的单元，命名为USER300，可以创建几乎任何单元类型。
UserElem子程序为Mechanical APDL在单元类型创建上提供了一个接口，可传递用户自定义单元创建时所需的所有数据，然后从自定义单元返回所有数据和结果，以更新数据库和文件。通过接口可以访问数据库和文件信息，所以很少需要了解Mechanical APDL数据库程序和文件结构。该接口还提供了获取Mechanical APDL材料定义程序的途径，允许自定义单元程序调用Mechanical APDL标准材料库中的子程序。

For detailed instructions, see Creating a New Element via the User-Defined Element API in the Guide to User-Programmable Features，详见本文第2节。

1.2 输入数据

使用 USRELEM 和 USRDOF 命令来输入基本的单元属性，所有其他的属性自动默认设置。
特殊功能包括单元收敛准则和通过单元进行二分控制。（Special features include element convergence criteria and cutback control via the element）
单元支持并行处理和分布式ANSYS求解。

---

基本命令 1） USRELEM

USRELEM, NNODES, NDIM, KeyShape, NREAL, NSAVEVARS, NRSLTVAR, KEYANSMAT, NINTPNTS, KESTRESS, KEYSYM

定义自定义单元 USER300的相关属性.
前处理模块 /PREP7 → Elements

标识符	描述	选项设置
NNODES	节点数量
NDIM	节点坐标系的维数	有效值为2或3
KeyShape	单元形状选择	ANYSHAPE– 默认无指定形状；POINT– 点；LINE– 直线；TRIAN– 三角形；QUAD– 四边形，可退化为三角形；TET– 四面体；BRICK– 砖形，可以退化为楔形、棱锥或四面体
NREAL	实常数的数量
NSAVEVARS	保存变量的数量(The number of saved variables)
NRSLTVAR	结果文件中变量保存的数量
KEYANSMAT	单元公式的控制参数	0– 在单元公式中创建自己的材料程序。实常数可用来输入材料属性，也可以通过MP和MPDATA输入线性材料属性；1– 使用ANSYS标准材料程序或者USERMAT子程序创建结构材料数据。ANSYS材料属性必须通过标准方法输入，当形状设置为ANYSHAPE时，这设置无效。
NINTPNTS	积分点(integration points)的最大数量	当 KEYANSMAT= 1 时可用
KESTRESS	单元应力状态的设置，当 KEYANSMAT= 1 时可用	0– 平面应力单元；1– 轴对称单元；2– 平面应变单元；3– 3-D 实体单元；4– 3-D 实体壳单元；5– 广义平面应变单元；6– 梁单元；7– 杆/桁架单元；8– 3-D 壳单元；9– 轴对称壳单元
KEYSYM	定义单元刚度矩阵为对称或者非对称	0– 对称；1– 非对称

备注
USRELEM 命令用于定义自定义单元 USER300 的属性.
可以根据分析需要夹杂其他命令，将USRELEM命令作为以下通用命令普通顺序的一部分使用：
1）为 USER300 单元采用ET命令，接着需采用相关的TYPE命令
2）同时采用USRELEM和USRDOF命令（顺序不限）
3）采用USER300定义用户单元

实常数的数量NREAL可以表征几何量、材料、或者单元公式中的任何参数。

当NSAVEVARS值为正时，ANSYS在 .esav 文件中存储指定的变量。

当KEYANSMAT = 0时，保存材料公式和运动学公式的所有变量。
当KEYANSMAT = 1时，保存运动学公式的所有变量（例如形变梯度张量），这种情况下，材料程序自动保存所有必要的材料数据。

保存在结果文件NRSLTVAR中的单元数据，只能作为不可求和的杂项数据（miscellaneous data）。ANSYS自动在 .rst 文件中存储结构单元的应力和总应变数据（对于热单元，存储例如热梯度和热通量这类等效变量）；NRSLTVAR不需要包含应力和总应变数据。

To learn more about creating user-defined elements, see Creating a New Element in the Programmer’s Reference.

---

基本命令 2） USRDOF

USRDOF, Action, DOF1, DOF2, DOF3, DOF4, DOF5, DOF6, DOF7, DOF8, DOF9, DOF10

定义用户单元 USER300 的自由度
前处理模块 /PREP7 → Elements

标识符	描述	选项设置
Action	命令选项	DEFINE– 指定自由度（默认）；LIST– 列出所有先前指定的自由度；DELETE– 删除所有先前指定的自由度
DOF1, DOF2, DOF3, . . . , DOF10	自由度序列

备注
USRDOF 命令用于定义自定义单元 USER300的自由度。

可以根据分析需要夹杂其他命令，将USRDOF命令作为以下通用命令普通顺序的一部分使用：
1）为USER300单元采用ET命令，接着需采用相关的TYPE命令
2）同时采用USRELEM和USRDOF命令（顺序不限）
3）采用USER300定义用户单元

每个USRDOF命令自由度序列最多可以定义10个自由度（DOF1至DOF10），可使用任何有效且合适的DOF (例如 UX, UY, UZ, ROTX, ROTY, ROTZ, AX, AY, AZ, VX, VY, VZ, PRES, WARP, TEMP, VOLT, MAG, EMF, 和CURR)，若需定义额外的自由度，需要再次使用USRDOF命令。
自定义单元的最大自由度数量： 节点数量 ╳ 每个节点的自由度数 ≤ 480。

1.3 假设与限制条件

以下功能不适用于自定义单元：

编号	描述
1	Birth and death	单元生死
2	Superelement stress pass	超单元应力传递
3	Initial stress	初始应力
4	Section input	输入单元截面
5	Input of fluences
6	Swelling	膨胀

2 创建新单元

ANSYS Help Viewer-- Programmer’s Reference-- 2.1. Creating a New Element

有两种方式创建自定义单元。
1）自定义单元API(应用程序接口) ← 2.1.2.Creating a New Element via the User-Defined Element API
2）直接访问程序数据库和文件 ← 2.1.3. Creating a New Element by Directly Accessing the Program Database

ANSYS在大多数情况下推荐用户自定义单元API的方式。
直接访问方法通常只用于特殊目的，或者如果您已经使用了用该方法创建了预先存在的单元。

两种新建单元的差异见下表：

接口	User-defined element API	Accessing program database and files directly
描述	提供更简单的界面，同时保留大部分用户单元的底层功能。很少需要了解数据库子例程和文件结构。	没有特殊接口。极少例外，如果一个单元的某功能存在，则单元存在。有效使用此接口所需的逻辑更复杂。
相对难度	中	高
版本间的预期兼容性	高	中
单元名称	USER300	USER100 - USER105
Demonstration logic included on your product distribution media	4节点四边形 和 20节点六面体	uel100(结构质量单元) 和 uel101(简化杆单元)
典型的线性材料访问子程序	getMatProp	propev
新非线性材料属性	UserMatTh.中程序	无已有程序
现有非线性材料特性	所有标准的结构材料都可以通过ElemGetMat访问	能力有限。可通过plasx, creepx和swellx获得
非结构性材料特性	No special programming has been implemented	No special programming has been implemented
允许不同单元类型的数量	无限制	无限制
Element characteristic capability	通过USRELEM和USRDOF输入10个基本单元属性，其他属性自动默认	使用uec100输入全部140个单元属性。通常使用大约30个，除特殊情况，其余均默认
可编程的适用子程序	UserElem	uec100, uel100, 很少 uex100 和uep100。子程序 uec101 到 uec105 是类似的
访问数据库信息	一般通过接口	通过子程序 (例如 tmpget, prsget, svgidx, svrget, svpidx, svrput).
访问文件信息	通过接口	通过指针和子例程(如eldwrtL、eldwrnL)
特点	单元收敛准则；通过单元进行二分控制？（Cutback control via element）	无
不支持的功能	以下功能不适用于自定义单元：1)单元生死；2)超单元应力传递；3)初始应力；4)截面属性输入；5)Input of fluences；6)膨胀	材料 TB 标识 PLASTIC, NLISO, AHYPER, HYPER, PRONY, SHIFT, ELASTIC, ANEL, SDAMP, SMA, CAST, EDP, 和 GURSON.

2.1 输入和输出缩略词

参数类型

标识	描述
int	integer	整数
dp	double-precision	双精度
log	logical
chr	character	字符
dcp	double-precision complex	双精度复数

参数大小

标识	描述
sc	scalar variable	标量
ar(n)	array variable of length n	长度为n的数组变量
func	functional return value	函数返回值

参数目标

标识	描述
in	input argument	输入参数
out	output argument	输出参数
inout	both an input and an output argument	输入参数和输出参数

2.2 通过自定义单元API创建新单元

Creating a New Element via the User-Defined Element API
通过API创建新单元的一般步骤：
Steps 2 和 3为用户自定义的单元API设置数据，所有其他步骤表示标准特性。

标识	描述	解释
1	设置单元类型	采用 ET 和TYPE命令，单元名称必须为 USER300
2	根据指定的单元类型定义新单元	采用USRELEM，指定单元特征(如节点数量、维度数量、实常数数量等)
3	定义节点自由度数量	采用USRDOF，每个USRDOF可定义10个自由度，若定义额外的自由度，再次使用此命令。每个节点的自由度须一致，每个节点的自由度数量 ≤ 32，每个单元的自由度数量 ≤ 480
4	定义实常数	如果需要
5	创建有限元模型	采用下列方法的任一种：1）直接生成-- 由节点直接创建单元，采用如 E, EGEN, EN, ENGEN, 或 EMORE.(也可尝试使用CDREAD读取 .cdb文件) ，若创建单元不同于任一标准单元的拓扑，此方法为唯一方法 。2）网格命令-- 若单元与任一标准单元具有相同的拓扑，并且已经为标准单元设置了非ANYSHAPE的形状(USRELEM→KeyShape 设置) ，此方法有效
6	施加边界条件和载荷	依据需求
7	求解设置	若单元具有多个物理场的自由度（位移和温度）
8	后处理	后处理与任一单元相同。只有总应变(或热梯度等效量 or equivalent quantities such as thermal gradient)和应力(或热通量等效量 or equivalent quantities such as thermal flux)被保存为常规结果量。在结果文件中，其他变量被保存为不可求和的杂项变量

2.2.1 建议和限制

1）确认 USRELEM 和 USRDOF的输入参数与 UserElem.F 程序中的数值一致。例如，通过USRELEM定义的节点维数 (NDIM) 为2，则不要更改UserElem.F子程序中定义的维数。若数值不匹配，则会产生运行错误或者不正确的结果。
2）运行程序基于USER300单元的自由度，自动激活默认的求解设置，但是默认的求解设置对于自定义单元来说可能不是最优的。
3）USER300单元不支持截面(SECxxx)命令。对于复合梁和铺层壳，需通过实常数和相应的UserElem.F子程序输入数据。

2.2.2 子程序 UserElem

UserElem子程序为单元创建提供了编程代码的接口。UserElem支持共享内存和分布式并行处理；但需用户确保代码可以使用并行处理。

子程序传递创建自定义单元所需的所有数据，并返回单元的所有数据和结果，以更新程序数据库和文件。基于API，几乎可以创建任何单元类型，而不必直接访问程序数据库和文件。子程序中包含两个例子：一个4节点四边形二维单元，和20节点砖结构六面体单元，都是几何线性分析。关键选项(KEYOPT设置)更改单元相关设置。

下表展示了输入和输出参数及其定义和用法。一些参数名称(如与单元矩阵和载荷向量有关的名称)与结构分析共用；也可以指定适合于其他工程学科分析的参数值。

Argument	Input (I) or Output (O)	Definition	Purpose	How Defined
elid	i	Element number	Output	At FE model creation

内容过多，详见help文件。

子程序 UserElem.F位于安装文件夹：Program Files\ANSYS Inc\v172\ansys\customize\user

*deck,UserElem                      USERSDISTRIB
c Copyright ANSYS.  All Rights Reserved.
      subroutine UserElem (elId, matId, keyMtx, lumpm, nDim, nNodes,
     &                     Nodes, nIntPnts, nUsrDof, kEStress, 
     &                     keyAnsMat, keySym, nKeyOpt, KeyOpt,
     &                     temper, temperB, tRef, kTherm, 
     &                     nPress, Press, kPress, nReal, RealConst, 
     &                     nSaveVars, saveVars, xRef, xCur, 
     &                     TotValDofs, IncValDofs, ItrValDofs,
     &                     VelValDofs, AccValDofs,
     &                     kfstps, nlgeom, nrkey, outkey, elPrint, iott,
     &                     keyHisUpd, ldstep, isubst, ieqitr, timval, 
     &                     keyEleErr, keyEleCnv,
     &                     eStiff, eMass, eDamp, eSStiff,
     &                     fExt, fInt, elVol, elMass, elCG, 
     &                     nRsltBsc, RsltBsc, nRsltVar, RsltVar, 
     &                     nElEng, elEnergy) 
     &                     
c*************************************************************************
c
c *** Primary function: General User Element Subroutine
c *** Note:
c       This routine is completed with an example, see more details later.
c
c
c     PROGRAMMER SHOULD NOT CHANGE ANY PURE INPUT ARGUMENTS (marked by ....,in)!
c
c     elId      (int,sc,in)        element number
c     matId     (int,sc,in)        material number of this element
c     keyMtx    (int,ar(10),in)    matrix and load vector form requests
c                                     0 = not requested, 1 = requested
c                                     see below for more details
c     lumpm     (int,sc,in)        mass matrix format
c                                    = 0 no lumped mass matrix
c                                    = 1 lumped mass matrix
c     nDim      (int,sc,in)        number of dimensions of the problem
c                                       (defined on USRELEM command as NDIM)
c                                    = 2 2D
c                                    = 3 3D
c     nNodes    (int,sc,in)        number of nodes of the element
c                                       (defined on USRELEM command as NNODES)
c     Nodes     (int,ar(nNodes),in)node list of this element 
c     nIntPnts  (int,sc,in)        maximum number of integration points
c                                       (defined on USRELEM command as NINTPNTS)
c     nUsrDof   (int,sc,in)        number of DOFs of this element (matrix and 
c                                     load vector size)
c     kEStress