2.1. Creating a New Element

Two tools are available for creating a user-defined element:

Ansys, Inc. recommends the user-defined element API in most cases. The direct-access method is generally for special-purpose use only, or if you are already using preexisting elements created with this method.

This table highlights the differences between the two methods:

Interface User-defined element API Accessing program database and files directly

Description Offers a simpler interface while preserving much of the underlying user-element capability. An understanding of the database subroutines and the file structure is rarely necessary to use the interface. No special interface. With few exceptions, if a capability exists for an element, it will exist here. The logic necessary for using this interface effectively is more complex.

Relative level of difficulty Medium High

Expected compatibility between versions High Medium

Element names USER300 USER100 to USER105

Demonstration logic included on your product distribution media 4-node quad and 20-node brick elements uel100 (a structural mass element) and uel101 (a simple link element)

Typical linear material access subroutine getMatProp propev

New nonlinear material properties Program in UserMatTh. No special programming has been set up.

Existing nonlinear material properties All standard structural materials are accessible via ElemGetMat. Limited capability. Accessible via plastx, creepx, and swellx.

Non-structural material properties No special programming has been implemented. No special programming has been implemented.

Number of different element types allowed Effectively, no limit. Effectively, no limit.

Element characteristic capability Input the basic 10 element characteristics (via the USRELEM and USRDOF commands). All other characteristics default automatically. Input all 140 element characteristics (using uec100). Approximately 30 are normally used, and the rest default unless required for special cases.

Applicable subroutines to be programmed UserElem uec100, uel100, and rarely uex100 and uep100. Subroutines uec101 to uec105 are analogous.

Access to database information Generally through the interface. Through subroutines (such as tmpget, prsget, svgidx, svrget, svpidx, svrput).

Access to file information Through the interface. Through pointers and subroutines (such as eldwrtL, eldwrnL).

Special features

Element convergence criteria

Cutback control via element

None.

Capabilities not included

Control information unavailable for:

Birth and death

Superelement stress pass

Initial stress

Section input

Input of fluences

Swelling

Material TB labels PLASTIC, NLISO, AHYPER, HYPER, PRONY, SHIFT, ELASTIC, ANEL, SDAMP, SMA, CAST, EDP, and GURSON.

2.1.1. Input and Output Abbreviations

The descriptions of the subroutines or functions within this chapter describe both the input arguments and output arguments. Argument information includes the argument's type, size and intent.

Argument type is one of the following:
int - integer
dp - double-precision
log - logical
chr - character
dcp - double-precision complex
Argument size is one of the following:
sc - scalar variable
ar(n) - array variable of length n
func - functional return value
Argument intent is one of the following:
in - input argument
out - output argument
inout - both an input and an output argument

2.1.2. Creating a New Element via the User-Defined Element API

Following is the general process for creating your own element via the user-defined element API.

Steps 2 and 3 specify data for the user-defined element API. All other steps represent standard features.

Step	Description	Comments
1.	Specify the element type.	Issue the ET and TYPE commands. The name of the element must be USER300.
2.	Define your new element according to the specified element type.	Issue the USRELEM command. Specify the element characteristics (such as the number of nodes, number of dimensions, number of real constants etc.).
3.	Specify nodal degrees of freedom.	Issue the USRDOF command. You can specify a maximum of 10 degrees of freedom per USRDOF command; to define additional degrees of freedom, issue the command again. Each node will have the same degrees of freedom. Although you can specify any valid degrees of freedom, the total number of degrees of freedom for your element cannot exceed 480, and the number of degrees of freedom for each node cannot exceed 32.
4.	Define real constants.	If needed.
5.	Create finite element models.	Use either of these methods: Direct generation -- Create elements directly from nodes, using commands such as E, EGEN, EN, ENGEN, or EMORE. (You can also use the CDREAD command if the .cdb file is available.) This method is the only way to create an element with a topology different from that of any standard element. Meshing commands -- This method is available only if your element has the same topology as that of a standard element and you have specified any standard element shape (USRELEM `KeyShape` value) except ANYSHAPE.
6.	Apply boundary conditions and loads.	As needed.
7.	Specify solution options.	If your element has multi-field degrees of freedom (displacements and temperatures).
8.	Perform postprocessing.	Postprocessing occurs normally as with any other element. Only total strain (or equivalent quantities such as thermal gradient) and stress (or equivalent quantities such as thermal flux) are saved as regular result quantities. Other variables are saved as nonsummable miscellaneous variables in the results file.

Recommendations and Restrictions

The following recommendations and restrictions apply to user-defined element USER300:

Verify that your input data for the USRELEM and USRDOF commands are consistent with the values used in the UserElem.F code. For example, if the number of dimensions (NDIM) specified via the USRELEM command is 2, do not change the number of dimensions specified in the UserElem.F subroutine from 2. A runtime error or incorrect results can occur if the values do not match.
The program may activate default solution settings automatically according to the USER300 element's degrees of freedom, but the default solution control settings may not be optimal for your element.
The USER300 element does not support section (SECxxx) commands. For composite beams and layered shells, you must input element data via real constants and code the UserElem.F subroutine accordingly.

2.1.2.1. Subroutine UserElem (Writing Your Own Elements)

The UserElem subroutine provides an interface to program code above the element level. UserElem supports shared memory and distributed parallel processing; however, you are responsible for ensuring that your code can use parallel processing.

The subroutine passes all data needed to create a user-defined element and returns all data and results from the element to update the program database and files. With this API, you can create virtually any element type without having to access program database and files directly. Two examples are included in this subroutine: a 4-node quadrilateral 2D element, and 20-node brick structural element, both for geometric linear analysis. Key options (KEYOPT settings) switch the elements.

The following table shows the input and output arguments, and their definition and usage. Some argument names (such as those pertaining to element matrices and load vectors) are common to structural analyses; however, you can specify argument values appropriate to analyses in other engineering disciplines.

Argument Input (I) or Output (O) Definition Purpose How Defined

elId I Element number Output information At FE model creation

matId

Material number

Output information

Call material subroutines

At FE model creation

keyMtx I Formulation request Specifying which matrices and load vectors to form Program code

lumpm

Mass matrix format:

0 = Consistent mass matrix

1 = Lumped mass matrix

Specifying how to form the mass matrix

LUMPM command

nDim I Number of dimensions Element coding USRELEM command

nNodes I Number of element nodes Element coding USRELEM command

Nodes

Element node list

Connectivity

Output

At FE model creation

nIntPnts I Maximum number of element integration points Element coding USRELEM command

nUsrDof

Number of element degrees of freedom

Element coding -- The degrees of freedom are ordered in the way in which they are listed via the USRDOF command for each node and repeated for all nodes

All element matrices -- DOF values and load vectors must be arranged in the same way

USRELEM and USRDOF commands

kEStress

Element stress state

Element coding

Calling material subroutines if requested

USRELEM command

keyAnsMat

Element formulation key:

0 -- Write your own material formulation

1 -- Use standard material subroutines and call ElemGetMat subroutine

Specifying how to create material data

USRELEM command

keySym

Flag for symmetricity of element matrices

Element coding

Program assembly logic

USRELEM command

nKeyOpt

Maximum number of element key options allowed (up to 2)

Element coding

Program code

KeyOpt

Element key options

KEYOPT(1) = 0~99

Branching the user-element codes to different formulations. (This could be equivalent to 100 x 100 different types of elements.)

ET command

temper I Nodal temperatures at current time Temperature dependence and thermal loads BF and BFE commands (if keyShape is specified in the UserElem subroutine)

temperB I Nodal temperatures at the end of the last substep Temperature dependence and thermal loads Program code

tRef I Reference temperature Temperature dependence and thermal loads TREF command

kTherm

Key indicating whether a thermal load exists:

1 = Calculate the thermal load

0 = No thermal load calculation

Element coding

---

nPress

Number of pressure values

Element coding

The size of the press vector

USRELEM command

At FE model creation

Press

Pressures at nodes of element facets (available only when keyShape is specified via the USRELEM command)

The pressure vector is ordered in the element with the same topology as that in the standard element library. Refer to that element for details.

Pressure load and pressure load stiffness

SF and SFE commands

kPress

Key indicating whether a pressure load exists:

1 = Calculate the pressure load

0 = No pressure load calculation

Element coding

Program code

nReal I Number of real constants Element coding USRELEM command

RealConst

The list of real constants

Element coding

Can pass material properties, section/layer information, element material control, and any element data

R command

nSaveVars

The number of variables saved in the .esav file for the element

Element coding

The size of saveVars

USRELEM command

saveVars

I/O

The data saved in the .esav file

The program saves the data after exiting the UserElem subroutine and retrieves it immediately before entering UserElem again. It should include kinematic related variables only when the material subroutine is called; otherwise, it should include both kinematic and material data. History dependent variables can only be saved/updated when the substep is converged (keyHisUpd = 1).

Element coding

UserElem subroutine

xRef

Initial coordinates of the element nodes

Values in global Cartesian coordinates

Element coding

At FE model creation

xCur

Current (deformed) coordinates of element nodes

Values in global Cartesian coordinate system, equal to xRef when nlgeom = off

Element coding

Program code

TotValDofs

Total values of degrees of freedom (displacements for structural analysis)

Values in global Cartesian coordinate system

Element coding

Program code

IncValDofs

Increment values of degrees of freedom occurring at the current substeps

Values in global Cartesian coordinate system

Element coding

Program code

ItrValDofs

Iteration values of degrees of freedom occurring at the last iteration

Values in global Cartesian coordinate system

Element coding

Program code

VelValDofs I First time derivatives of degrees of freedom Velocities Program code

AccValDofs I Second time derivatives of degrees of freedom Accelerations Program code

kfstps

Key indicating first time entering the element subroutine:

1 = First time

0 = Other than first time

Initializing data

Program code

nlgeom I Flag indicating whether large displacement/deformation is in effect Element coding NLGEOM command

nrkey

Newton-Raphson algorithm key:

1 -- Any nonlinear analysis

0 -- Pure linear analysis

Output

Element coding

---

outkey

Key indicating output result type:

1 -- This is an output call, the substep is converged, and you can print/save element results

0 -- All other cases

Element coding

Program code

elPrint

Key indicating whether any element output should appear in the print file:

0 = No

1 = Yes

Element coding

Program code

OUTPR command

iott I Output file number The FORTRAN output file number. All information written in the specified file appears in the output file. Program code

keyHisUpd

Key to update history-dependent variables:

1 = The substep converged; ready to update history-dependent variables (such as equivalent plastic strain)

0 = Solution not yet converged; cannot update history-dependent variables

Element coding

Program code

The following variables are for debug, timing, and convergence-control purposes only. You can usually ignore them.

ldstep

Current load step number

Output

Debug

Program code

isubst I Current substep number Output Program code

ieqitr I Current iteration number Output Program code

timval I Current time Output Program code

keyEleErr

I/O

Formulation error key:

0 = No error (preset value)

1 = Error occurred in element formulation, possibly due to excessive deformation. (The program lessens deformation if possible by cutback.)

Element coding

Program code

keyEleCnv

I/O

Element convergence key:

1 = Converged (preset value before calling)

0 = Not converged

Provides manual control of convergence when you introduce any constraint at the element level (such as volumetric constraint for mixed u-P)

Program code

End of special-purpose variable group

eStiff

Small-deformation stiffness matrix

In global Cartesian coordinate system

Solution

Requested when keyMtx(1) = 1

eMass

Mass matrix

In global Cartesian coordinate system

Solution

Requested when keyMtx(2) = 1

eDamp

Damping matrix

In global Cartesian coordinate system

Solution

Requested when keyMtx(3) = 1

eSStiff

Stress stiffness matrix

In global Cartesian coordinate system

Solution

Requested when keyMtx(4) = 1

fExt

External load vector

In global Cartesian coordinate system

Solution

Requested when keyMtx(5) = 1

fInt

Internal nodal force vector

In global Cartesian coordinate system

Solution

Requested when keyMtx(6) = 1

elVol O Element volume Output UserElem subroutine

elMass O Element mass Output UserElem subroutine

elCG

Element centroid coordinates

In global Cartesian coordinate system

Postprocessing

UserElem subroutine

nRsltBsc I Number of basic result data saved in result file Specifying the size of RsltBsc Program code

RsltBsc

Basic result data saved in results file

These variables are accessible via the PRESOL and PRNSOL commands in the standard way and can also be plotted if you specify a KeyShape value via the USRELEM command.

Postprocessing

UserElem subroutine

nRsltVar I The number of result data to be saved in the result file as non-summable miscellaneous variables Specifying the size of RsltVar USRELEM command

RsltVar

The result data saved in the result file as non-summable miscellaneous variables

The data is accessible via element solution-related commands (such as PLESOL, ESOL, and PRESOL), but only one value for an element each time.

Postprocessing

UserElem subroutine

nElEng

Number of energies

Fixed at 3

Solution

UserElem subroutine

elEnergy

Element energy vector:

elEnergy(1) -- Strain energy

elEnergy(2) -- Plastic energy

elEnergy(3) -- Creep energy

Output

UserElem subroutine

*deck,UserElem                      USERDISTRIB
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  (int,sc,in)        kEStress 
c                                       (defined on USRELEM command as KESTRESS)
c     keyAnsMat (int,sc,in)        key to indicate if ANSYS material
c                                     routine is going to be called
c                                     (defined on USRELEM command as KEYANSMAT)
c                                     = 0, No
c                                     = 1, Yes
c                                     = 3, define NL COMBIN characteristics
c     keySym    (int,sc,in)        key to indicate if element matrices
c                                     is symmetric
c                                       (defined on USRELEM command as KEYSYM)
c                                     = 0, symmetric
c                                     = 1, unsymmetric
c     nKeyOpt   (int,sc,in)        number of element key options able to be
c                                     used in this routine
c     KeyOpt    (int,ar(nKeyOpt),in) values of element key option defined
c                                     by et or keyopt command for the
c                                     user elements, only the first
c                                     nKeyOpt values are passed in and can
c                                     be used to branch the routine for
c                                     different formulations
c     temper    (dp,ar(nNodes),in) nodal temperatures at current time
c     temperB   (dp,ar(nNodes),in) nodal temperatures at the beginning of this
c                                     incremental step (substep)
c     tRef      (dp,sc,in)         reference temperature
c     kTherm    (int,sc,inout)     input:  flag for thermal loading 
c                                      = 1, Temperatures at nodes are different 
c                                      from the reference temperature, 
c                                      thermal loading might be needed.
c                                      = 0, Temperatures at nodes are the same
c                                      as the reference temperature, 
c                                      thermal loading is not needed.
c                                  output:  flag for thermal strains
c     nPress    (int,sc,in)        number of pressure values for this element
c     Press     (dp,ar(nPress),in) applied elemental face load (pressure)
c     kPress    (int,sc,in)        flag for pressure loading 
c                                      = 1, pressure load is applied and 
c                                      equivalent nodal forces should be 
c                                      calculated
c                                      = 0, no pressure loading
c     nReal     (int,sc,in)        number of real constants
c                                       (defined on USRELEM command as NREAL)
c     RealConst (dp,ar(nReal),in)  user defined real constants 
c     nSaveVars (int,sc,in)        number of saved variables
c                                      (defined on USRELEM command as NSAVEVARS)
c     saveVars  (dp,ar(nSaveVars),inout) user saved variables
c     xRef      (dp,ar(nDim,nNodes),in)
c                                  nodal coordinates in initial configuration
c     xCur      (dp,ar(nDim,nNodes),in)
c                                  nodal coordinates in current configuration
c     TotValDofs (dp,ar(nUsrDof),in) total values of DOFs (displacements) 
c                                     from time = 0
c     IncValDofs (dp,ar(nUsrDof),in) incremental values of DOFs (displacements) 
c                                     for the current step
c     ItrValDofs (dp,ar(nUsrDof),in) iterative values of DOFs (displacements)
c                                     for the current iteration
c                                     (normally needed for debug only)
c     VelValDofs (dp,ar(nUsrDof),in) first time derivatives of DOFs 
c                                             (velocities) (normally not needed)
c     AccValDofs (dp,ar(nUsrDof),in) second time derivatives of DOFs 
c                                          (accelerations) (normally not needed)
c     kfstps    (int,sc,in)        key for the first iteration of first 
c                                     substep of the first load step
c                                     = 1 yes
c                                     = 0 no
c     nlgeom    (int,sc,in)        large deformation key [from nlgeom command]
c                                     = 0 NLGEOM,OFF
c                                     = 1 NLGEOM, ON
c     nrkey     (int,sc,in)        key to indicate a newton-raphson
c                                     (incremental) procedure
c                                     = 0 No
c                                     = 1 Yes
c     outkey    (int,sc,in)        key to indicate if any element output is
c                                     to be placed on the print file or the 
c                                     result file
c                                     = 0 No
c                                     = 1 Yes
c     elPrint   (int,sc,in)        key to indicate if any element output is 
c                                     to be placed on the print file
c                                     = 0 No
c                                     = 1 Yes
c     iott      (int,sc,in)        print output file unit number
c     keyHisUpd (int,sc,in)        key to indicate if history-dependent
c                                    variables need to be updated, like
c                                    equivalent plastic strain, back stress
c                                    etc. since the iteration is already
c                                    converged
c                                     = 0 not converged, don't need to update
c                                         history dependent variables
c                                     = 1 yes, converged, need to update
c                                         history dependent variables
c
c     --- The following 7 variable group can usually be ignored.
c     --- The variables are used for debug, timing, and convergence control.
c     ldstep    (int,sc,in)        current load step number
c     isubst    (int,sc,in)        current substep number
c     ieqitr    (int,sc,in)        current equilibium iteration  number
c     timval    (int,sc,in)        current time value
c     keyEleErr (int,sc,inout)     key to indicate if there is any element 
c                                     formulation error, like negative Jacobian.
c                                     The error could be caused by too
c                                     large incremental step, illegal model.
c                                     = 0 no error (preset value before calling)
c                                     = 1 some error happens. ANSYS will
c                                     decide to stop the analysis or cutback
c                                     the substep (bi-section) based on other
c                                     user input and information at higher
c                                     level.
c     keyEleCnv (int,sc,inout)     key to flag if this element satisfies
c                                     the user defined element convergence
c                                     criterion. 
c                                     = 1, yes, the criterion is satisfied
c                                       or don't have any criterion at all
c                                       it is preset value before calling
c                                     = 0, no, the element doesn't satisfy
c                                       element convergence criterion. If
c                                       this is the case, the iteration will
c                                       not converge even when both force
c                                       and displacement converge 
c       ---- end of 7 variable group -----
c
c                                                                  requested if
c     eStiff(dp,ar(nUsrDof,nUsrDof),inout) stiffness matrix         keyMtx(1)=1
c     eMass (dp,ar(nUsrDof,nUsrDof),inout) mass matrix              keyMtx(2)=1
c     eDamp (dp,ar(nUsrDof,nUsrDof),inout) damping matrix           keyMtx(3)=1
c     eSStiff(dp,ar(nUsrDof,nUsrDof),inout)stress stiffness matrix  keyMtx(4)=1
c     fExt      (dp,ar(nUsrDof),out)       applied f vector         keyMtx(5)=1
c     fInt      (dp,ar(nUsrDof),out)       internal force vector    keyMtx(6)=1

c     elVol     (dp,sc,out)        element volume
c     elMass    (dp,sc,out)        element mass
c     elCG      (dp,ar(3),out)     element centroid coordinates in current
c                                     configuration
c     nRsltBsc  (dp,sc,in)         number of basic elemental results saved in
c                                   result files 
c     RsltBsc   (dp,ar(nRsltBsc),out) basic elemental results 
c                                       (see EXPLANATION below)
c     nRsltVar  (int,sc,in)        number of elemental results saved in 
c                                     result file as non-summable miscellaneous
c                                     variables 
c                                       (defined on USRELEM command as NRSLTVAR)
c     RsltVar   (dp,ar(nRsltVar),out) variables to saved in result files as
c                                      non-summable miscellaneous variables 
c                                      requested when outkey = 1
c
c     nElEng    (int,sc,in)        number of energies (fixed at 3)
c
c     elEnergy  (dp,ar(nElEng),out) elemental energy
c                                     elEnergy(1), element strain energy
c                                     elEnergy(2), element plastic strain energy
c                                     elEnergy(3), element creep strain energy
c
c     EXPLANATION OF RsltBsc
c     
c       Basic element results are saved and total number of result 
c     quantities is nRsltBsc, where:
c            nRsltBsc = (7+7)* number of corner nodes at one element.
c       To process the quantites by post processing properly, the results 
c     must be in the following order:
c       1.) Stresses: Sx Sy Sz Sxy Syz Sxz Seqv at all corner points,
c     followed by:
c       2.) Strains : Ex Ey Ez Exy Eyz Exz Eeqv at all corner points
c     where Seqv and Eeqv = equivalent stress and strain respectively
c
c
************************************************************************
c

2.1.2.2. Subroutine ElemGetMat (Calling the Standard Structural Material Library)

The ElemGetMat subroutine is the API to the standard materials. When you issue the USRELEM command after setting the command's KEYANSMAT argument, the subroutine accesses the standard structural material library. It allows you to focus on the kinematic portion of element formulation while the program handles the material part of the formulation.

When calling the subroutine, input the associated material data via the standard method. There is no need to access this subroutine, only to call it.

The following table shows the input and output arguments, and their definition and usage.

Argument Input (I) or Output (O) Definition Purpose How Defined

elId I Element number Output At FE model creation

matId

Material number

Output information

Getting material data

At FE model creation

nDim

Number of dimensions of element geometry

2 = 2D element geometry

3 = 3D element geometry

Specifying the size of the nodal coordinates

Material calculation

At FE model creation

nTens

Number of stress/strain tensor components:

4 = 2D and ordered as x, y, z, xy

6 = 3D and ordered as x, y, z, xy, yz, xz

Specifying the data size

UserElem subroutine

nDirect

Number of direct component of stress/strain tensors

nDirect< or = nTens

Specifying the data size

UserElem subroutine

intPnt

Current integration point number

Output

Data handling

UserElem subroutine

xCurIP

Coordinates of current integration point

Values in global Cartesian coordinate system

Material calculation

UserElem subroutine

TemperIP I Integration point temperatures at the current time Evaluating temperature-dependent material data UserElem subroutine

TemperIPB I Integration point temperatures at the end of the last incremental step Evaluating temperature-dependent material data UserElem subroutine

IncStrain

Strain components [1]

Incremental strain of the current substep when nlgeom = on

Total strain when nlgeom = off

Material calculation

UserElem subroutine

defG0

Deformation gradient tensor at the end of previous substep [1]

Material updating

UserElem subroutine

defG I/O Total deformation gradient tensor at the current time [1] The component in thickness direction is updated by material subroutines for plane stress and shell elements UserElem subroutine

kTherm

I/O

Thermal loading key:

0 = No thermal loading

1 = Has thermal loading

Thermal load calculation

UserElem subroutine

cMat O Material Jacobian [1] Forming stiffness Material subroutine

MatProp

Material data for element formulation

Forming mass matrix

Handling transverse shear

Output

Material subroutine

Stress

Cauchy stress [1]

Forming geometric stiffness

Calculating internal forces

Material subroutine

Strain O Total strain components [1] Output Material subroutine

StressTh

Total thermal stress components [1]

Output

Calculating thermal loading

Material subroutine

StrainTh O Total thermal strain components [1] Output Material subroutine

StrainPl O Total plastic strain components [1] Output ---

StrainCr O Total creep strain components [1] Output ---

StressBk O Backstress components [1] Output ---

StrainSw O Swelling strain Not yet supported ---

EnergyD

Energy density:

1 = Elastic energy density

2 = Plastic energy density

3 = Creep energy density

---

MatRotGlb

Rotation matrix

Rotation matrix from global Cartesian to rotated element coordinate system

Used only for solid elements when nlgeom = on

All tensor component values in the subroutine are in the global Cartesian coordinate system for solid elements, and in the co-rotated element Cartesian coordinate system for link, beam and shell elements.

*deck,ElemGetMat

      subroutine ElemGetMat (elId, matId,  nDim, nTens, nDirect,
     &                           intPnt, xCurIP, TemperIP,
     &                           TemperIPB, kTherm, IncStrain,
     &                           defG0, defG, CMat, MatProp,
     &                           Stress, Strain, StressTh, StrainTh,
     &                           StrainPl, StrainCr, StressBk, StrainSw,
     &                           EnergyD, MatRotGlb)

c*************************************************************************
c
c *** Primary function: call ANSYS material routines to obtain material
c                        data for USER300 elements

c *** Notice - This file contains ANSYS Confidential information ***
c
c     input arguments
c     ===============
c     elId        (int,sc)           element number
c     matId       (int,sc)           material number of this element
c     nDim        (int,sc)           number of dimensions of the problem
c                                    = 2 2D
c                                    = 3 3D
c     nTens       (int,sc)           number of stress/strain components
c     nDirect     (int,sc)           number of stress/strain direct 
c                                      components
c     intPnt      (int,sc)           current integration point number
c     xCurIP      (dp,ar(3))         coordinates of integration point
c     TemperIP    (dp,sc)            integration point  temperatures at 
c                                      current time
c     TemperIPB   (dp,sc)            integration point  temperatures at 
c                                      the end of last incremetal step
c     IncStrain   (dp,ar(nTens))     strain for the current substep step when
c                                       nlgeom = on
c                                    total strain when nlgeom = off
c     defG0       (dp,ar(3x3))       deformation gradient tensor at the end
c                                       of last incremental step 
c
c     input output arguments         input desc     / output desc
c     ======================         ==========       ===========
c     defG        (dp, ar(3x3))      deformation gradient tensor at current
c                                      time, updated for thichness change in
c                                      plane stress when nlgeom=on
c     kTherm      (int,sc)           flag for thermal loading 
c                                      input as:
c                                      = 0 if temp = tref
c                                      = 1 if temp .ne. tref
c                                      gets reset to 0
c                                                   if ALPX, ALPY, and ALPZ = 0
c                                     
c     output arguments
c     ================
c     cMat        (nTens*nTens)      material Jacobian matrix
c     MatProp     (dp,ar(5))         commonly used materail properties
c                                    MatProp(1),Gxz: shear modulus
c                                    MatProp(2),Gyz: shear modulus
c                                    MatProp(3),Gxy: shear modulus
c                                    MatProp(4), density
c                                    MatProp(5), nuxy
c     Stress      (dp,ar(nTens))     total stress
c     Strain      (dp,ar(nTens))     total strain
c     StressTh    (dp,ar(nTens))     thermal stress
c     StrainTh    (dp,ar(nTens))     thermal strain
c     StrainPl    (dp,ar(nTens))     plastic strain
c     StrainCr    (dp,ar(nTens))     creep strain
c     StressBk    (dp,ar(nTens))     back stress for kinematic hardening
c     StrainSw    (dp,sc)            isotropic swelling strain 
c                                        (swelling capability not available yet)
c     EnergyD      (dp,ar(3))        energy density 
c                                    EnergyD(1) elastic energy density
c                                    EnergyD(2) plastic energy density  
c                                    EnergyD(3) creep energy density
c     MatRotGlb   (dp,ar(3,3))       The rotation matrix from global 
c                                     to  material coordinate system
************************************************************************
c

2.1.3. Creating a New Element by Directly Accessing the Program Database

The next few pages describe the user subroutines and supporting subroutines you use to create new elements. Using these subroutines, you can create new element types, add them to the element library, and use them as "regular" elements. You can create up to six independent element types (names USER100 - USER105). For demonstration purposes, the subroutines uel100 (for a structural mass element) and uel101 (for a simple link element) are included on the product distribution media.

2.1.3.1. User Subroutines

Subroutines uec100 through uec105 describe the element characteristics. Subroutine elccmt (on the distribution medium) describes the input for these subroutines in detail. You can use subroutines uex100 through uex105 to override default logic. Subroutines uec100 through uec105 define parameters such as:

2D or 3D geometry
Degree of freedom set
Symmetric or unsymmetric matrix
Number of nodes
Number of body loads (for example, temperatures)
Number of surface loads (for example, pressures)
Number of real constants
Number of variables to be saved
Number of rows in element matrices
Linear or nonlinear element.

Subroutines uel100 through uel105 calculate the element matrices (stiffness, specific heat, and so on), the element load vector (force, heat flow, and so on), and any element output quantities. The element printout also is generated, and the variables to be saved are calculated and stored in the results file.

Other user subroutines available for manipulating element information include the following:

Subroutines uep100 through uep105 provide printed output of line elements. The general postprocessor, POST1, calls the subroutines, or you can call them using uel100 through uel105.
Subroutine usertr allows access to the nodal transformations.
Subroutine userac describes some of the data handling.

2.1.3.2. Subroutine uec100 (Defining Characteristics of the usr100 Subroutine)

*deck,uec100                      USERDISTRIB
      subroutine uec100 (elcdn,ielc,kerr)
c     ***** this subroutine defines the characteristics of user100.
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c *** Notice - This file contains ANSYS Confidential information ***
c
c     typ=int,dp,log,chr   siz=sc,ar(n)   intent=in,out,inout
c
c  input arguments:
c     variable (typ,siz,intent)     description
c     ielc (int,ar(IELCSZ),inout) - element characteristics
c                                        see include deck elccmt for details
c     kerr   (int,sc,inout)       - error flag up to this point.
c                                    (do not initialize to zero)
c
c  output arguments:
c     variable (typ,siz,intent)     description
c     elcdn   (chr,sc,out)        - name of element
c     ielc (int,ar(IELCSZ),inout) - element characteristics
c                                          see include deck elccmt for details
c     kerr   (int,sc,inout)       - error flag (set to 1 if error)
c       note to programmers:  the validity of keyopt values may be checked here
c

2.1.3.2.1. Subroutines uec101 through uec105

The input and output arguments for subroutines uec101, uec102, uec103, uec104, and uec105 is identical to the uec100 subroutine listed above.

2.1.3.3. Subroutine uex100 (Overriding Element Characteristic Defaults)

*deck,uex100                      USERDISTRIB
      subroutine uex100 (ielc,kerr)
c     *** subroutine to override element characteristic defaults ***
c     *** hence, this routine is needed only in rare cases.
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c *** Notice - This file contains ANSYS Confidential information ***
c
c     *** input and output are the same as for uec100, except that this
c     *** logic is called after the defaulting logic is finished.
c     *** this defaulting is done in ansys subroutine echdft(not a upf).
c     *** as indicated above, this routine is rarely needed, but if it is
c     *** desired to see the effect of echdft, you may print out the ielc array
c     *** leaving uec100 and print it out again entering this routine.
c
c     typ=int,dp,log,chr   siz=sc,ar(n)   intent=in,out,inout
c
c  input arguments:
c     variable (typ,siz,intent)     description
c     ielc (int,ar(IELCSZ),inout) - element characteristics
c                                        see include deck elccmt for details
c     kerr   (int,sc,inout)       - error flag up to this point.
c                                  (do not initialize to zero)
c
c  output arguments:
c     variable (typ,siz,intent)     description
c     ielc (int,ar(IELCSZ),inout) - element characteristics
c                                         see include deck elccmt for details
c     kerr   (int,sc,inout)       - error flag (set to 1 if error)
c

2.1.3.3.1. Subroutines uex101 through uex105

The source code for subroutines uex101, uex102, uex103, uex104, and uex105 is identical to the code for subroutine uex100 listed above.

2.1.3.4. Subroutine uel100 (Calculating Element Matrices, Load Vectors, and Results)

*deck,uel100                      USERDISTRIB
      subroutine uel100 (elem,ielc,elmdat,eomaskL,nodes,locsvrL,kelreq,
     x kelfil,nr,xyz,u,elord,kelout,zs,zass,damp,gstif,zsc,zscnr,elvol,
     x elmass,center,elener,edindxL,lcerstL)
c --- general lumped mass is demonstrated --------------------------------
c *** primary function:
c        1. compute element matrices, load vectors, and results
c *** secondary functions:
c        2. maintain element solution data

c *** user programmable functions may not be used in parallel processing ***

c *** Notice - This file contains ANSYS Confidential information ***

c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.

c  input arguments:
c       elem   (int,sc,in)         - element label (number)
c       ielc   (int,ar(IELCSZ),in) - array of element type characteristics
c                                     (IELCSZ = array size, defined in echprm)
c       elmdat (int,ar(EL_DIM),in) - array of element data
c       eomaskL(LONG,sc,in)        - bit pattern for element output
c                                    (see outpcm)
c       nodes  (int,ar(nnod),in)   - array of element node numbers
c                                   (nnod = number of nodes; 1 in this case)
c       locsvrL(LONG,sc,in)        - location of the saved variables
c                                              on file .esav for this element
c       kelreq (int,ar(10),in)     - matrix and load vector form requests
c                                  (indices for kelreq are given with output
c                                                            arguments below)
c       kelfil (int,ar(10),in)     - keys indicating incoming matrices and
c                                    load vectors (indices for kelfil are the
c                                    same as given for kelreq with output
c                                    arguments below)
c       nr     (int,sc,in)         - matrix and load vector size
c       xyz    (dp,ar(6,nnod),in)  - nodal coordinates (orig) and rotation angle
c       u      (dp,ar(nr,5),in)    - element nodal solution values
c       elord  (int,sc,in)         - internal element number

c  output arguments:
c       kelout (int,ar(10),out)    - keys indicating created matrices and
c                                         load vectors (indices for kelout
c                                            are the same as for kelreq below,
c                                            as well as kelin and kelout later)
c       zs     (dp,ar(nr,nr),inout)- stiffness/conductivity matrix (kelreq(1))
c       zass   (dp,ar(nr,nr),inout)- mass matrix                   (kelreq(2))
c       damp   (dp,ar(nr,nr),inout)- damping/specific heat matrix  (kelreq(3))
c       gstif  (dp,ar(nr,nr),inout)- stress stiffness matrix       (kelreq(4))
c       zsc    (dp,ar(nr),out)     - applied f vector              (kelreq(5))
c       zscnr  (dp,ar(nr),out)     - n-r restoring f vector        (kelreq(6))
c                                    or imaginary f vector         (kelreq(7))
c       elvol  (dp,sc,out)         - element volume
c       elmass (dp,sc,out)         - element mass
c       center (dp,ar(3),out)      - centroid location
c       elener (dp,ar(5),out)      - element energies
c       edindxL(LONG,ar(*),out)   - element result data file indexes
c       lcerstL(LONG,sc,inout)     - position on result file

2.1.3.4.1. Subroutines uel101 through uel105

The input and output arguments for subroutines uel101, uel102, uel103, uel104, and uel105are identical to subroutine uel100 listed above.

2.1.3.5. Subroutine uep100 (Printing Output for User Elements in POST1 via PRESOL,ELEM)

*deck,uep100                      USERDISTRIB
      subroutine uep100 (iott,elem,nodes,mat, kept,tem,
     x  kemn,fluen, kems,force, kens,sig, keel,epel,
     x  keth,eptho,epswel,epino, kenl,sigepl,sigrat,hpres,epeq,
     x  kepl,eppl, kecr,epcrp)
c
c *** primary function:    produce printed output for user100
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c *** Notice - This file contains ANSYS Confidential information ***
c
c  **********  this subroutine is provided for user information  *********
c *** user programmable features may not be used in parallel processing ***
c
c  input arguments:
c     iott     (int,sc,in)         - output unit number
c     elem     (int,sc,in)         - element number
c     nodes    (int,ar(2),in)      - node numbers
c     mat      (int,sc,in)         - material number
c     kept     (int,sc,in)         - key to print temperatures
c     tem      (dp,ar(2),in)       - nodal temperatures
c     kemn     (inr,sc,in)         - key to print fluences
c     fluen    (dp,ar(2),in)       - neutron fluences
c     kems     (int,sc,in)         - key to print moment forces
c     force    (int,sc,in)         - member force fx
c     kens     (int,sc,in)         - key to print strains
c     sig      (dp,sc,in)          - axial stress
c     keel     (int,sc,in)         - key to print elastic strain
c     epel     (dp,sc,in)          - axial elastic strain
c     keth     (int,sc,in)         - key to print thermal,initial,swelling strai
c     eptho    (dp,sc,in)          - axial thermal strain
c     epswel   (dp,sc,in)          - swelling strain
c     epino    (dp,sc,in)          - initial axial strain
c     kenl     (int,sc,in)         - key set if any nonlinear materials present
c     sigepl   (dp,sc,in)          - stress in stress-strain curve
c     sigrat   (dp,sc,in)          - stress ratio
c     hpres    (dp,sc,in)          - hydrostatic pressure
c     epeq     (dp,sc,in)          - plastic equivalent strain
c     kepl     (int,sc,in)         - key to print plastic strain
c     eppl     (dp,sc,in)          - plastic strain
c     kecr     (int,sc,in)         - key to print creep strain
c     epcrp    (dp,sc,in)          - creep strain
c
c  output arguments:     none
c

2.1.3.5.1. Subroutines uep101 through uep105

The source code for subroutines uep101, uep102, uep103, uep104, and uep105 is identical to subroutine uep100 listed above.

2.1.3.6. Subroutine usertr (Adjusting the Nodal Orientation Matrix)

*deck,usertr                      USERDISTRIB
      subroutine usertr (node,tr)
c *** primary function:  adjust nodal orientation matrix
c     secondary function: study nodal orientation matrix
c       accessed with ielc(notran) = -100
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c     typ=int,dp,log,chr,dcp   siz=sc,ar(n)   intent=in,out,inout
c
c  input arguments:
c     variable (typ,siz,intent)    description
c     node     (int,sc,in)       - node number being acted upon
c     tr       (dp,ar(32,32),inout) - nodal to global orientation matrix
c
c  output arguments:
c     variable (typ,siz,intent)    description
c     tr       (dp,ar(32,32),inout) - nodal to global orientation matrix
c
c          tr is a matrix that is already defined based on the degrees
c          of freedom selected.
c          it does not normally need to be changed.
c          it may be printed out here to study.  its functional size is
c          nr by nr, where nr is the number of degrees of freedom in the
c          element
c

2.1.3.7. Subroutine userac (Accessing Element Information)

This subroutine is provided for demonstration purposes.

*deck,userac                      USERDISTRIB
      subroutine userac (elem)
c *** primary function:  To demonstrate user access of element information.
c --- Given the element number, all information about the element is avaiable.
c --- Starting with elmdat, one can get the element type, real constant number,
c --- the material number, the element coordinate system number, as well as
c --- the node numbers.  Then, one can get more information about any or all
c --- of these things.  The below demonstrates getting the element type and
c --- real constants.
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c *** Notice - This file contains ANSYS Confidential information ***
c
c  input arguments:
c     variable (typ,siz,intent)    description
c     elem     (int,sc,in)       - element number
c
c  output arguments:
c     none
c