<!-- source-page: 201 -->

```txt
C    SVARS(1-6) after the dynamic residual has been
C    calculated.
C    - For half-increment residual calculations: In 7-12,
C    contains the static residual at the beginning
C    of the previous increment. SVARS(1-6) are copied
C    into SVARS(7-12) after the dynamic residual has
C    been calculated.
C
AREA = PROPS(1)
E    = PROPS(2)
ANU    = PROPS(3)
RHO    = PROPS(4)
C
ALEN = ABS(COORDS(1,2)-COORDS(1,1))
AK    = AREA*E/ALEN
AM    = HALF*AREA*RHO*ALEN
C
DO K1 = 1, NDOFEL
    SRESID(K1) = ZERO
    DO KRHS = 1, NRHS
    RHS(K1,KRHS) = ZERO
    END DO
    DO K2 = 1, NDOFEL
    AMATRX(K2,K1) = ZERO
    END DO
    END DO
C
IF (LFLAGS(3).EQ.1) THEN
C    Normal incrementation
    IF (LFLAGS(1).EQ.1 .OR. LFLAGS(1).EQ.2) THEN
C    *STATIC
    AMATRX(1,1) = AK
    AMATRX(4,4) = AK
    AMATRX(1,4) = -AK
    AMATRX(4,1) = -AK
    IF (LFLAGS(4).NE.0) THEN
    FORCE = AK*(U(4)-U(1))
    DFORCE = AK*(DU(4,1)-DU(1,1))
    SRESID(1) = -DFORCE
    SRESID(4) = DFORCE
    RHS(1,1) = RHS(1,1)-SRESID(1)
    RHS(4,1) = RHS(4,1)-SRESID(4) 
```

<!-- source-page: 202 -->

```matlab
ENERGY(2) = HALF*FORCE*(DU(4,1)-DU(1,1))
* + HALF*DFORCE*(U(4)-U(1))
* + HALF*DFORCE*(DU(4,1)-DU(1,1))
ELSE
FORCE = AK*(U(4)-U(1))
SRESID(1) = -FORCE
SRESID(4) = FORCE
RHS(1,1) = RHS(1,1)-SRESID(1)
RHS(4,1) = RHS(4,1)-SRESID(4)
DO KDLOAD = 1, NDLOAD
IF (JDLTYP(KDLOAD,1).EQ.1001) THEN
RHS(4,1) = RHS(4,1)+ADLMAG(KDLOAD,1)
ENERGY(8) = ENERGY(8)+(ADLMAG(KDLOAD,1)
* - HALF*DDLMAG(KDLOAD,1))*DU(4,1)
IF (NRHS.EQ.2) THEN
C
Riks
RHS(4,2) = RHS(4,2)+DDLMAG(KDLOAD,1)
END IF
END IF
END DO
ENERGY(2) = HALF*FORCE*(U(4)-U(1))
END IF
ELSE IF (LFLAGS(1).EQ.11 .OR. LFLAGS(1).EQ.12) THEN
C
*DYNAMIC
ALPHA = PARAMS(1)
BETA = PARAMS(2)
GAMMA = PARAMS(3)
C
DADU = ONE/(BETA*DTIME**2)
DVDU = GAMMA/(BETA*DTIME)
C
DO K1 = 1, NDOFEL
AMATRX(K1,K1) = AM*DADU
RHS(K1,1) = RHS(K1,1)-AM*A(K1)
END DO
AMATRX(1,1) = AMATRX(1,1)+(ONE+ALPHA)*AK
AMATRX(4,4) = AMATRX(4,4)+(ONE+ALPHA)*AK
AMATRX(1,4) = AMATRX(1,4)-(ONE+ALPHA)*AK
AMATRX(4,1) = AMATRX(4,1)-(ONE+ALPHA)*AK
FORCE = AK*(U(4)-U(1))
SRESID(1) = -FORCE
SRESID(4) = FORCE 
```

<!-- source-page: 203 -->

```vba
RHS(1,1) = RHS(1,1) -
* ((ONE+ALPHA)*SRESID(1)-ALPHA*SVARS(1))
RHS(4,1) = RHS(4,1) -
* ((ONE+ALPHA)*SRESID(4)-ALPHA*SVARS(4))
ENERGY(1) = ZERO
DO K1 = 1, NDOFEL
SVARS(K1+6) = SVARS(k1)
SVARS(K1) = SRESID(K1)
ENERGY(1) = ENERGY(1)+HALF*V(K1)*AM*V(K1)
END DO
ENERGY(2) = HALF*FORCE*(U(4)-U(1))
END IF
ELSE IF (LFLAGS(3).EQ.2) THEN
C Stiffness matrix
AMATRX(1,1) = AK
AMATRX(4,4) = AK
AMATRX(1,4) = -AK
AMATRX(4,1) = -AK
ELSE IF (LFLAGS(3).EQ.4) THEN
C Mass matrix
DO K1 = 1, NDOFEL
AMATRX(K1,K1) = AM
END DO
ELSE IF (LFLAGS(3).EQ.5) THEN
C Half-increment residual calculation
ALPHA = PARAMS(1)
FORCE = AK*(U(4)-U(1))
SRESID(1) = -FORCE
SRESID(4) = FORCE
RHS(1,1) = RHS(1,1)-AM*A(1)-(ONE+ALPHA)*SRESID(1)
* + HALF*ALPHA*(SVARS(1)+SVARS(7))
RHS(4,1) = RHS(4,1)-AM*A(4)-(ONE+ALPHA)*SRESID(4)
* + HALF*ALPHA*(SVARS(4)+SVARS(10))
ELSE IF (LFLAGS(3).EQ.6) THEN
C Initial acceleration calculation
DO K1 = 1, NDOFEL
AMATRX(K1,K1) = AM
END DO
FORCE = AK*(U(4)-U(1))
SRESID(1) = -FORCE
SRESID(4) = FORCE
RHS(1,1) = RHS(1,1)-SRESID(1) 
```

<!-- source-page: 204 -->

```matlab
RHS(4,1) = RHS(4,1) - SRESID(4)
ENERGY(1) = ZERO
DO K1 = 1, NDOFEL
SVARS(K1) = SRESID(K1)
ENERGY(1) = ENERGY(1) + HALF*V(K1) * AM*V(K1)
END DO
ENERGY(2) = HALF*FORCE*(U(4) - U(1))
ELSE IF (LFLAGS(3).EQ.100) THEN
C Output for perturbations
IF (LFLAGS(1).EQ.1 .OR. LFLAGS(1).EQ.2) THEN
C *STATIC
FORCE = AK*(U(4) - U(1))
DFORCE = AK*(DU(4,1) - DU(1,1))
SRESID(1) = -DFORCE
SRESID(4) = DFORCE
RHS(1,1) = RHS(1,1) - SRESID(1)
RHS(4,1) = RHS(4,1) - SRESID(4)
ENERGY(2) = HALF*FORCE*(DU(4,1) - DU(1,1))
* + HALF*DFORCE*(U(4) - U(1))
* + HALF*DFORCE*(DU(4,1) - DU(1,1))
DO KVAR = 1, NSVARS
SVARS(KVAR) = ZERO
END DO
SVARS(1) = RHS(1,1)
SVARS(4) = RHS(4,1)
ELSE IF (LFLAGS(1).EQ.41) THEN
C *FREQUENCY
DO KRHS = 1, NRHS
DFORCE = AK*(DU(4, KRHS) - DU(1, KRHS))
SRESID(1) = -DFORCE
SRESID(4) = DFORCE
RHS(1, KRHS) = RHS(1, KRHS) - SRESID(1)
RHS(4, KRHS) = RHS(4, KRHS) - SRESID(4)
END DO
DO KVAR = 1, NSVARS
SVARS(KVAR) = ZERO
END DO
SVARS(1) = RHS(1,1)
SVARS(4) = RHS(4,1)
END IF
END IF
C 
```

<!-- source-page: 205 -->

RETURN
END

<!-- source-page: 206 -->

<!-- source-page: 207 -->

# 1.1.29 UELMAT: User subroutine to define an element with access to Abaqus materials.

# Product: Abaqus/Standard

WARNING: This feature is intended for advanced users only. Its use in all but the simplest test examples will require considerable coding by the user/developer. “User-defined elements,” Section 32.17.1 of the Abaqus Analysis User’s Guide, should be read before proceeding.

# References

• “User-defined elements,” Section 32.17.1 of the Abaqus Analysis User’s Guide   
• \*UEL PROPERTY  
• \*USER ELEMENT   
• “Accessing Abaqus materials,” Section 2.1.17   
• “Accessing Abaqus thermal materials,” Section 2.1.18

# Overview

# User subroutine UELMAT:

• will be called for each element that is of a general user-defined element type (i.e., not defined by a linear stiffness or mass matrix read either directly or from results file data) each time element calculations are required;   
• (or subroutines called by user subroutine UELMAT) must perform all of the calculations for the element, appropriate to the current activity in the analysis;   
• can access some of the Abaqus materials through utility routines MATERIAL\_LIB\_MECH and MATERIAL\_LIB\_HT;   
• is available for a subset of the procedures supported for user subroutine UEL (see “User-defined elements,” Section 32.17.1 of the Abaqus Analysis User’s Guide); and   
• is available for plane stress and three-dimensional element types in a stress/displacement analysis and for two-dimensional and three-dimensional element types in a heat transfer analysis (see “Userdefined elements,” Section 32.17.1 of the Abaqus Analysis User’s Guide).

# User subroutine interface

SUBROUTINE UELMAT(RHS,AMATRX,SVARS,ENERGY,NDOFEL,NRHS,NSVARS,  
1 PROPS,NPROPS,COORDS,MCRD,NNODE,U,DU,V,A,JTYPE,TIME,DTIME,   
2 KSTEP,KINC,JELEM,PARAMS,NDLOAD,JDLTYP,ADLMAG,PREDEF,NPREDF,  
3 LFLAGS,MLVARX,DDLMAG,MDLOAD,PNEWDT,JPROPS,NJPROP,PERIOD,   
4 MATERIALLIB)

<!-- source-page: 208 -->

C

INCLUDE 'ABA\_PARAM.INC'

C

DIMENSION RHS(MLVARX,\*),AMATRX(NDOFEL,NDOFEL),PROPS(\*),

1 SVARS(\*),ENERGY(8),COORDS(MCRD,NNODE),U(NDOFEL),

2 DU(MLVARX,\*),V(NDOFEL),A(NDOFEL),TIME(2),PARAMS(\*),

3 JDLTYP(MDLOAD,\*),ADLMAG(MDLOAD,\*),DDLMAG(MDLOAD,\*),

4 PREDEF(2,NPREDF,NNODE),LFLAGS(\*),JPROPS(\*)

user coding to define RHS, AMATRX, SVARS, ENERGY, and PNEWDT

RETURN

END

# Variables to be defined

These arrays depend on the value of the LFLAGS array.

# RHS

An array containing the contributions of this element to the right-hand-side vectors of the overall system of equations. For most nonlinear analysis procedures, NRHS=1 and RHS should contain the residual vector. The exception is the modified Riks static procedure (“Static stress analysis,” Section 6.2.2 of the Abaqus Analysis User’s Guide), for which NRHS=2 and the first column in RHS should contain the residual vector and the second column should contain the increments of external load on the element. RHS(K1,K2) is the entry for the K1th degree of freedom of the element in the K2th right-hand-side vector.

# AMATRX

An array containing the contribution of this element to the Jacobian (stiffness) or other matrix of the overall system of equations. The particular matrix required at any time depends on the entries in the LFLAGS array (see below).

All nonzero entries in AMATRX should be defined, even if the matrix is symmetric. If you do not specify that the matrix is unsymmetric when you define the user element, Abaqus/Standard will use the symmetric matrix defined by ${ \mathsf { \Omega } } _ { 2 } ^ { 1 } ( [ A ] + [ A ] ^ { T } )$ , where is the matrix defined as AMATRX in this subroutine. If you specify that the matrix is unsymmetric when you define the user element, Abaqus/Standard will use AMATRX directly.

# SVARS

An array containing the values of the solution-dependent state variables associated with this element. The number of such variables is NSVARS (see below). You define the meaning of these variables.

For general nonlinear steps this array is passed into UELMAT containing the values of these variables at the start of the current increment. They should be updated to be the values at the end

<!-- source-page: 209 -->

of the increment, unless the procedure during which UELMAT is being called does not require such an update; this requirement depends on the entries in the LFLAGS array (see below). For linear perturbation steps this array is passed into UELMAT containing the values of these variables in the base state. They should be returned containing perturbation values if you wish to output such quantities.

When KINC is equal to zero, the call to UELMAT is made for zero increment output (see “Output,” Section 4.1.1 of the Abaqus Analysis User’s Guide). In this case the values returned will be used only for output purposes and are not updated permanently.

# ENERGY

For general nonlinear steps array ENERGY contains the values of the energy quantities associated with the element. The values in this array when UELMAT is called are the element energy quantities at the start of the current increment. They should be updated to the values at the end of the current increment. For linear perturbation steps the array is passed into UELMAT containing the energy in the base state. They should be returned containing perturbation values if you wish to output such quantities. The entries in the array are as follows:

<table><tr><td>ENERGY (1)</td><td>Kinetic energy.</td></tr><tr><td>ENERGY (2)</td><td>Elastic strain energy.</td></tr><tr><td>ENERGY (3)</td><td>Creep dissipation.</td></tr><tr><td>ENERGY (4)</td><td>Plastic dissipation.</td></tr><tr><td>ENERGY (5)</td><td>Viscous dissipation.</td></tr><tr><td>ENERGY (6)</td><td>“Artificial strain energy” associated with such effects as artificial stiffness introduced to control hourglassing or other singular modes in the element.</td></tr><tr><td>ENERGY (7)</td><td>Electrostatic energy.</td></tr><tr><td>ENERGY (8)</td><td>Incremental work done by loads applied within the user element.</td></tr></table>

When KINC is equal to zero, the call to UELMAT is made for zero increment output (see “Output,” Section 4.1.1 of the Abaqus Analysis User’s Guide). In this case the energy values returned will be used only for output purposes and are not updated permanently.

# Variable that can be updated

# PNEWDT

Ratio of suggested new time increment to the time increment currently being used (DTIME, see below). This variable allows you to provide input to the automatic time incrementation algorithms in Abaqus/Standard (if automatic time incrementation is chosen). It is useful only during equilibrium iterations with the normal time incrementation, as indicated by LFLAGS(3)=1. During a severe discontinuity iteration (such as contact changes), PNEWDT is ignored unless CONVERT SDI=YES is specified for this step. The usage of PNEWDT is discussed below.

PNEWDT is set to a large value before each call to UELMAT.

<!-- source-page: 210 -->

If PNEWDT is redefined to be less than 1.0, Abaqus/Standard must abandon the time increment and attempt it again with a smaller time increment. The suggested new time increment provided to the automatic time integration algorithms is PNEWDT × DTIME, where the PNEWDT used is the minimum value for all calls to user subroutines that allow redefinition of PNEWDT for this iteration.

If PNEWDT is given a value that is greater than 1.0 for all calls to user subroutines for this iteration and the increment converges in this iteration, Abaqus/Standard may increase the time increment. The suggested new time increment provided to the automatic time integration algorithms is PNEWDT × DTIME, where the PNEWDT used is the minimum value for all calls to user subroutines for this iteration.

If automatic time incrementation is not selected in the analysis procedure, values of PNEWDT that are greater than 1.0 will be ignored and values of PNEWDT that are less than 1.0 will cause the job to terminate.

# Variables passed in for information

# Arrays:

# PROPS

A floating point array containing the NPROPS real property values defined for use with this element. NPROPS is the user-specified number of real property values. See “Defining the element properties” in “User-defined elements,” Section 32.17.1 of the Abaqus Analysis User’s Guide.

# JPROPS

An integer array containing the NJPROP integer property values defined for use with this element. NJPROP is the user-specified number of integer property values. See “Defining the element properties” in “User-defined elements,” Section 32.17.1 of the Abaqus Analysis User’s Guide.

# COORDS

An array containing the original coordinates of the nodes of the element. COORDS(K1,K2) is the K1th coordinate of the K2th node of the element.

# U, DU, V, A

Arrays containing the current estimates of the basic solution variables (displacements, rotations, temperatures, depending on the degree of freedom) at the nodes of the element at the end of the current increment. Values are provided as follows:

U(K1)

Total values of the variables. If this is a linear perturbation step, it is the value in the base state.

DU(K1,KRHS)

Incremental values of the variables for the current increment for right-hand-side KRHS. If this is an eigenvalue extraction step, this is the eigenvector magnitude for eigenvector KRHS. For steady-state dynamics KRHS denotes real components of perturbation displacement and KRHS denotes imaginary components of perturbation displacement.