<!-- source-page: 1111 -->

You can read the mass and/or stiffness matrices from a file or define them directly. In either case Abaqus/Standard reads four values per line, using F20 format. This format ensures that the data are read with adequate precision. Data written in E20.14 format can be read under this format.

Start with the first column of the matrix. Start a new line for each column. If you do not specify that the element matrix is unsymmetric, give the matrix entries from the top of each column to the diagonal term only: do not give the terms below the diagonal. If you specify that the element matrix is unsymmetric, give all terms in each column, starting from the top of the column.

Input File Usage: Use the following option to define the element mass matrix:

\*MATRIX, TYPE=MASS

Use the following option to define the element stiffness matrix:

\*MATRIX, TYPE=STIFFNESS

Use the following option to read the element mass or stiffness matrix from a file:

\*MATRIX, TYPE=MASS or STIFFNESS, INPUT=file\_name

For example, if the matrix is symmetric, the following data lines should be used:

$A_{11}$ $A_{12}$ , $A_{22}$ $A_{13}$ , $A_{23}$ , $A_{33}$ $A_{14}$ , $A_{24}$ , $A_{34}$ , $A_{44}$ $A_{15}$ , $A_{25}$ , $A_{35}$ , $A_{45}$ $A_{55}$ $A_{16}$ , $A_{26}$ , $A_{36}$ , $A_{46}$ $A_{56}$ , $A_{66}$

Etc.

If the matrix is unsymmetric, the following data lines should be used:

$A_{11}, A_{21}, A_{31}, A_{41}$ $A_{51}, A_{61}, A_{71}, A_{81}$ ...
..., $A_{m1}$ $A_{12}, A_{22}, A_{32}, A_{42}$

where m is the size of the matrix and $A _ { i j }$ is the entry in the matrix for row i column j.

# Geometrically nonlinear analysis

When a linear user element is used in a geometrically nonlinear analysis, the stiffness matrix provided will not be updated to account for any nonlinear effects such as finite rotations.

<!-- source-page: 1112 -->

# Defining the element properties

You must associate a property definition with every user element, even though no property values (except Rayleigh damping factors) are associated with linear user elements.

Input File Usage: Use the following option to associate a property definition with a user element set:

$$
* \text { UEL   PROPERTY,   ELSET } = \text { name }
$$

Defining Rayleigh damping for direct-integration dynamic analysis

You can define the Rayleigh damping factors for direct-integration dynamic analysis (“Implicit dynamic analysis using direct integration,” Section 6.3.2) for linear user elements. The Rayleigh damping factors are defined as

$$
[ \mathbf {C} ] = \alpha [ \mathbf {M} ] + \beta [ \mathbf {K} ],
$$

where is the damping matrix, is the mass matrix, is the stiffness matrix, and and are the user-specified damping factors. See “Material damping,” Section 26.1.1, for more information on Rayleigh damping.

Input File Usage: \*UEL PROPERTY, ELSET=name, ALPHA= , BETA=

# Defining loads

You can apply point loads, moments, fluxes, etc. to the nodes of linear user-defined elements in the usual way using concentrated loads and concentrated fluxes (“Concentrated loads,” Section 34.4.2, and “Thermal loads,” Section 34.4.4).

Distributed loads and fluxes cannot be defined for linear user-defined elements.

# Defining a general user element

General user elements are defined in user subroutines UEL and UELMAT in Abaqus/Standard and in user subroutine VUEL in Abaqus/Explicit. The implementation of user elements in user subroutines is recommended only for advanced users.

# Defining the number of nodes associated with the element

You must specify the number of nodes associated with a general user element. You can define “internal” nodes that are not connected to other elements.

Input File Usage: \*USER ELEMENT, NODES=n

# Defining whether or not the element matrices are symmetric in Abaqus/Standard

If the contribution of the element to the Jacobian operator matrix of the overall Newton method is not symmetric (i.e., the element matrices are not symmetric), you can request that Abaqus/Standard use its nonsymmetric equation solution capability (see “Defining an analysis,” Section 6.1.2).

Input File Usage: \*USER ELEMENT, NODES=n, UNSYMM

<!-- source-page: 1113 -->

# Defining the maximum number of coordinates needed at any nodal point

You can define the maximum number of coordinates needed in user subroutines UEL, UELMAT, or VUEL at any node point of the element. Abaqus assigns space to store this many coordinate values at all of the nodes associated with elements of this type. The default maximum number of coordinates at each node is 1.

Abaqus will change the maximum number of coordinates to be the maximum of the user-specified value or the value of the largest active degree of freedom of the user element that is less than or equal to 3. For example, if you specify a maximum number of coordinates of 1 and the active degrees of freedom of the user element are 2, 3, and 6, the maximum number of coordinates will be changed to 3. If you specify a maximum number of coordinates of 2 and the active degrees of freedom of the user element are 11 and 12, the maximum number of coordinates will remain as 2.

Input File Usage: \*USER ELEMENT, COORDINATES=n

# Defining the element properties

You can define the number of properties associated with a particular user element and then specify their numerical values.

# Specifying the number of property values required

Any number of properties can be defined to be used in forming a general user element. You can specify the number of integer property values required, n, and the number of real (floating point) property values required, m; the total number of values required is the sum of these two numbers. The default number of integer property values required is 0 and the default number of real property values required is 0.

Integer property values can be used inside user subroutines UEL, UELMAT, and VUEL as flags, indices, counters, etc. Examples of real (floating point) property values are the cross-sectional area of a beam or rod, thickness of a shell, and material properties to define the material behavior for the element.

Input File Usage: \*USER ELEMENT, I PROPERTIES=n, PROPERTIES=m

# Specifying the numerical values of element properties

You must associate a user element property definition with each user-defined element, even if no property values are required. The property values specified in the property definition are passed into user subroutines UEL, UELMAT, and VUEL each time the subroutine is called for the user elements that are in the specified element set.

Input File Usage: Use the following option to associate a property definition with a user element set:

\*UEL PROPERTY, ELSET=name

To define the property values, enter all floating point values on the data lines first, followed immediately by the integer values. Eight values should be entered on all data lines except the last one, which may have fewer than eight values.

<!-- source-page: 1114 -->

Assigning an Abaqus material to the user element

If the Abaqus material library is accessed from a user element, a material must be defined and assigned to the user element.

Input File Usage:

Use the following option to associate a material with the user element:

\*UEL PROPERTY, MATERIAL=name

If this option is used, user subroutine UELMAT must be used to define the contribution of the element to the model. Otherwise, user subroutine UEL must be used.

Assigning an orientation definition

If the Abaqus material library is accessed from a user element, you can associate a material orientation definition (“Orientations,” Section 2.2.5) with the user element. The orientation definition specifies a local coordinate system for material calculations in the element. The local coordinate system is assumed to be uniform in a given element and is based on the coordinates at the element centroid.

Input File Usage:

Use the following option to associate an orientation definition with a user element:

\*UEL PROPERTY, ORIENTATION=name

Specifying the element type

If the Abaqus material library is accessed from a user element, the element type must be specified.

Input File Usage:

Use the following option to define a three-dimensional element in a stress/ displacement or a heat transfer analysis:

\*USER ELEMENT, TENSOR=THREED

Use the following option to define a two-dimensional element in a heat transfer analysis:

\*USER ELEMENT, TENSOR=TWOD

Use the following option to define a plane strain element in a stress/ displacement analysis:

\*USER ELEMENT, TENSOR=PSTRAIN

Use the following option to define a plane stress element in a stress/ displacement analysis:

\*USER ELEMENT, TENSOR=PSTRESS

Specifying the number of integration points

If the Abaqus material library is accessed from a user element, the number of integration points must be specified.

Input File Usage:

Use the following option to specify the number of integration points:

\*USER ELEMENT, INTEGRATION=n

<!-- source-page: 1115 -->

# Defining the number of solution-dependent variables that must be stored within the element

You can define the number of solution-dependent state variables that must be stored within a general user element. The default number of variables is 1.

Examples of such variables are strains, stresses, section forces, and other state variables (for example, hardening measures in plasticity models) used in the calculations within the element. These variables allow quite general nonlinear kinematic and material behavior to be modeled. These solution-dependent state variables must be calculated and updated in user subroutines UEL, UELMAT, and VUEL.

As an example, suppose the element has four numerical integration points, at each of which you wish to store strain, stress, inelastic strain, and a scalar hardening variable to define the material state. Assume that the element is a three-dimensional solid, so that there are six components of stress and strain at each integration point. Then, the number of solution-dependent variables associated with each such element is $4 \times ( 6 \times 3 + 1 ) = 7 6$ .

Input File Usage: \*USER ELEMENT, VARIABLES=n

# Defining the contribution of the element to the model in user subroutine UEL

For a general user element in Abaqus/Standard, user subroutine UEL may be coded to define the contribution of the element to the model. Abaqus/Standard calls this routine each time any information about a user-defined element is needed. At each such call Abaqus/Standard provides the values of the nodal coordinates and of all solution-dependent nodal variables (displacements, incremental displacements, velocities, accelerations, etc.) at all degrees of freedom associated with the element, as well as values, at the beginning of the current increment, of the solution-dependent state variables associated with the element. Abaqus/Standard also provides the values of all user-defined properties associated with this element and a control flag array indicating what functions the user subroutine must perform. Depending on this set of control flags, the subroutine must define the contribution of the element to the residual vector, define the contribution of the element to the Jacobian (stiffness) matrix, update the solution-dependent state variables associated with the element, form the mass matrix, and so on. Often, several of these functions must be performed in a single call to the routine.

# Formulation of an element with user subroutine UEL

The element’s principal contribution to the model during general analysis steps is that it provides nodal forces $F ^ { N }$ that depend on the values of the nodal variables $u ^ { M }$ and on the solution-dependent state variables $H ^ { \alpha }$ within the element:

$$
F ^ {N} = F ^ {N} (u ^ {M}, H ^ {\alpha}, \text { geometry,   attributes,   predefined   field   variables,   distributed   loads }).
$$

Here we use the term “force” to mean that quantity in the variational statement that is conjugate to the basic nodal variable: physical force when the associated degree of freedom is physical displacement, moment when the associated degree of freedom is a rotation, heat flux when it is a temperature value, and so on. The signs of the forces in $F ^ { N }$ are such that external forces provide positive nodal force values and “internal” forces caused by stresses, internal heat fluxes, etc. in the element provide negative nodal

<!-- source-page: 1116 -->

force values. For example, in the case of mechanical equilibrium of a finite element subject to surface tractions and body forces with stress , and with interpolation $\delta { \bf u } = { \bf N } ^ { N } \delta u ^ { N } , \delta \varepsilon = \bar { \beta } ^ { N } \delta u ^ { N }$

$$
F ^ {N} = \int_ {S} \mathbf {N} ^ {N} \cdot \mathbf {t} d S + \int_ {V} \mathbf {N} ^ {N} \cdot \mathbf {f} d V - \int_ {V} \boldsymbol {\beta} ^ {N}: \boldsymbol {\sigma} d V.
$$

In general procedures Abaqus/Standard solves the overall system of equations by Newton’s method:

$$
S o l v e \qquad \tilde {K} ^ {N M} c ^ {M} = R ^ {M},
$$

$$
S e t \quad u ^ {N} = u ^ {N} + c ^ {N},
$$

Iterate

where $R ^ { N }$ is the residual at degree of freedom N and

$$
\tilde {K} ^ {N M} = - \frac {d R ^ {N}}{d u ^ {M}}
$$

is the Jacobian matrix.

During such iterations you must define $F ^ { N }$ , which is the element’s contribution to the residual, $R ^ { N }$ , and

$$
- \frac {d F ^ {N}}{d u ^ {M}},
$$

which is the element’s contribution to the Jacobian $\tilde { K } ^ { N M }$ . By writing the total derivative $- d F ^ { N } / d u ^ { M }$ , we imply that the element’s contribution to $\tilde { K } ^ { N M }$ should include all direct and indirect dependencies of the $\mathbf { \bar { \rho } } _ { F } \mathbf { \bar { { N } } }$ on the $u ^ { M }$ . For example, the $H ^ { \alpha }$ will generally depend on $u ^ { M }$ ; therefore, $- d F ^ { N } / d u ^ { M }$ will include terms such as

$$
- \frac {\partial F ^ {N}}{\partial H ^ {\alpha}} \frac {\partial H ^ {\alpha}}{\partial u ^ {M}}.
$$

Use in transient analysis procedures

In procedures such as transient heat transfer and dynamic analysis, the problem also involves time integration of rates of change of the nodal degrees of freedom. The time integration schemes used by Abaqus/Standard for the various procedures are described in more detail in the Abaqus Theory Guide. For example, in transient heat transfer analysis, the backward difference method is used:

$$
\dot {u} _ {t + \Delta t} = \frac {1}{\Delta t} \left(u _ {t + \Delta t} - u _ {t}\right).
$$

Therefore, if $F ^ { N }$ depends on $u ^ { M }$ and $\dot { u } ^ { M }$ (as would be the case if the user element includes thermal energy storage), the Jacobian contribution should include the term

<!-- source-page: 1117 -->

$$
- \frac {\partial F ^ {N}}{\partial \dot {u} ^ {M}} \left(\frac {d \dot {u}}{d u}\right) _ {t + \Delta t},
$$

where $( d \dot { u } / d u ) _ { t + \Delta t }$ is defined from the time integration procedure as $1 / \Delta t .$ .

In all cases where Abaqus/Standard integrates first-order problems in time, the $\dot { u } ^ { M }$ are never stored because they are readily available as $\Delta u ^ { M } / \Delta t ,$ , where $\Delta u ^ { \hat { M } } = u _ { t + \Delta t } ^ { M } - u _ { t } ^ { \hat { M } }$ . However, for direct, implicit integration of dynamic systems (see “Implicit dynamic analysis,” Section 2.4.1 of the Abaqus Theory Guide) Abaqus/Standard requires storage of $\dot { u } ^ { M }$ and $\ddot { u } ^ { M }$ . These values are, therefore, passed into subroutine UEL. If the user element contains effects that depend on these time derivatives (damping and inertial effects), its Jacobian contribution will include

$$
- \frac {\partial F ^ {N}}{\partial u ^ {M}} - \frac {\partial F ^ {N}}{\partial \dot {u} ^ {M}} \left(\frac {d \dot {u}}{d u}\right) _ {t + \Delta t} - \frac {\partial F ^ {N}}{\partial \ddot {u} ^ {M}} \left(\frac {d \ddot {u}}{d u}\right) _ {t + \Delta t}.
$$

For the Hilber-Hughes-Taylor scheme

$$
\left(\frac {d \dot {u}}{d u}\right) _ {t + \Delta t} = \frac {\gamma}{\beta \Delta t},
$$

$$
\left(\frac {d \ddot {u}}{d u}\right) _ {t + \Delta t} = \frac {1}{\beta \Delta t ^ {2}},
$$

where $\beta$ and $\gamma$ are the (Newmark) parameters of the integration scheme. For backwark Euler time integration, the same expressions apply with $\beta$ and $\gamma$ equal to unity. The term $- \partial F ^ { N } / \partial \dot { u } ^ { M }$ is the element’s damping matrix, and $- \partial F ^ { N } / \partial \ddot { u } ^ { M }$ is its mass matrix.

The Hilber-Hughes-Taylor scheme writes the overall dynamic equilibrium equations as

$$
- M ^ {N M} \ddot {u} _ {t + \Delta t} + (1 + \alpha) G _ {t + \Delta t} ^ {N} - \alpha G _ {t} ^ {N} = 0,
$$

where $G ^ { N }$ is the total force at degree of freedom N, excluding d’Alembert (inertia) forces. $G ^ { N }$ is often referred to as the “static residual.” Therefore, if a user element is to be used with Hilber-Hughes-Taylor time integration, the element’s contribution $F ^ { N }$ to the overall residual must be formulated in the same way. Since Abaqus/Standard provides information only at the time point at which UEL is called, this implies that each time UEL is called the $H _ { \alpha }$ array must be used to recover $G _ { t } ^ { N }$ (and $G _ { t ^ { - } } ^ { N }$ if half-increment residual calculations are required, where indicates $G ^ { N }$ from the beginning of the previous increment) and used to store $G _ { t + \Delta t }$ (and $G _ { t } ^ { N }$ if half-increment residual calculations are required) for use in the next increment. This complication can be avoided if the numerical damping control parameter, $\alpha ,$ for the dynamic step is set to zero; i.e., if the trapezoidal rule is used for integration of the dynamic equations (see “Implicit dynamic analysis using direct integration,” Section 6.3.2, for details). This complication is also avoided with the backward Euler time integration operator because dynamic equilibrium is enforced at the end of the step.

If solution-dependent state variables $( H ^ { \alpha } )$ are used in the element, a suitable time integration method must be coded into subroutine UEL for these variables. Any of the $u ^ { N }$ associated with the element that are not shared with standard Abaqus/Standard elements may be integrated in time by any

<!-- source-page: 1118 -->

suitable technique. If, in such cases, it is necessary to store values of $u ^ { N } , \dot { u } ^ { N }$ , etc. at particular points in time, the solution-dependent state variable array, $H _ { \alpha }$ , can be used for this purpose. Abaqus/Standard will still compute and store values of $\dot { u } ^ { N }$ and $\ddot { u } ^ { \bar { N } }$ using the formulae associated with whatever time integrator it is using, but these values need not be used. To ensure accurate, stable time integration, you can control the size of the time increment used by Abaqus/Standard.

# Constraints defined with Lagrange multipliers

Introduction of constraints with Lagrange multipliers should be avoided since Abaqus/Standard cannot detect such variables and avoid eigensolver problems by proper ordering of the equations.

# Defining the contribution of the element to the model in user subroutine UELMAT

Alternatively, for a general user element in Abaqus/Standard, user subroutine UELMAT may be coded to define the contribution of the element to the model. User subroutine UELMAT is an enhanced version of user subroutine UEL; consequently, all the information provided for user subroutine UEL is also valid for user subroutine UELMAT. The enhancement allows you to access some of the material models from the Abaqus material library from UELMAT. UELMAT works only with a subset of procedures for which UEL is available:

• static;   
• direct-integration dynamic;   
• frequency extraction;   
• steady-state uncouple heat transfer; and   
• transient uncouple heat transfer.

User subroutine UELMAT will be called if an Abaqus material model is assigned to a user element (see “Assigning an Abaqus material to the user element,” above); otherwise, user subroutine UEL will be called.

# Accessing Abaqus materials from user subroutine UELMAT

Abaqus allows you to access some of the material models from the Abaqus material library from user subroutine UELMAT. The material models are accessed through the utility routines MATERIAL\_LIB\_MECH and MATERIAL\_LIB\_HT (“Accessing Abaqus thermal materials,” Section 2.1.18 of the Abaqus User Subroutines Reference Guide, and “Accessing Abaqus materials,” Section 2.1.17 of the Abaqus User Subroutines Reference Guide). Each time user subroutine UELMAT is called with the flags set to values that require computation of the right-hand-side vector and the element Jacobian, the material library must be called for each integration point, where the number of integration points is specified in the element definition (“Specifying the number of integration points” in “User-defined elements,” Section 32.17.1). The material models that are accessible from user subroutine UELMAT are:

• linear elastic model;   
• hyperelastic model;   
• Ramberg-Osgood model;

<!-- source-page: 1119 -->

• classical metal plasticity models (Mises and Hill);   
• extended Drucker-Prager model;   
• modified Drucker-Prager/Cap plasticity model;   
• porous metal plasticity model;   
• elastomeric foam material model; and   
• crushable foam plasticity model.

# Defining the contribution of the element to the model in user subroutine VUEL

For a general user element in Abaqus/Explicit, user subroutine VUEL must be coded to define the contribution of the element to the model. Abaqus/Explicit calls this routine each time any information about a user-defined element is needed. At each such call Abaqus/Explicit provides the values of the nodal coordinates and of all solution-dependent nodal variables (displacements, velocities, accelerations, etc.) at all degrees of freedom associated with the element, as well as values of the solution-dependent state variables associated with the element at the beginning of the current increment. The incremental displacements are those obtained in a previous increment. Abaqus/Explicit also provides the values of all user-defined properties associated with this element and a control flag array indicating what functions the user subroutine must perform. Depending on this set of control flags, the subroutine must define the contribution of the element to the internal or external force/flux vector, form the mass/capacity matrix, update the solution-dependent state variables associated with the element, and so on.

The element’s principal contribution to the model is that it provides nodal forces $F ^ { J }$ that depend on the values of the nodal variables $u ^ { M }$ , the rate of nodal variables $\dot { u } ^ { M }$ , and on the solution-dependent state variables $H ^ { \alpha }$ within the element:

$$
F ^ {J} = F ^ {J} (u ^ {M}, \dot {u} ^ {M}, H ^ {\alpha}, \text {geometry, attributes, predefined field variables, distributed loads}).
$$

In addition, the element mass matrix $M ^ { N J }$ can be defined. Optionally, you can also define the external load contribution from the element due to specified distributed loading. In each increment Abaqus/Explicit solves for the accelerations at the end of the increment using

$$
\ddot {u} _ {(i)} ^ {N} = (M ^ {N J}) ^ {- 1} (P _ {(i)} ^ {J} - F _ {(i)} ^ {J}),
$$

where $P ^ { J }$ is the applied load vector. The solution (velocity, displacement) is then integrated in time using the central difference method

$$
\dot {u} _ {(i + \frac {1}{2})} ^ {N} = \dot {u} _ {(i - \frac {1}{2})} ^ {N} + \frac {\Delta t _ {(i + 1)} + \Delta t _ {(i)}}{2} \ddot {u} _ {(i)} ^ {N},
$$

$$
u _ {(i + 1)} ^ {N} = u _ {(i)} ^ {N} + \Delta t _ {(i + 1)} \dot {u} _ {(i + \frac {1}{2})} ^ {N}.
$$

For coupled temperature/displacement elements the temperatures are computed at the beginning of the increment using

<!-- source-page: 1120 -->

$$
\dot {\theta} _ {(i)} ^ {N} = (C ^ {N J}) ^ {- 1} (\mathbf {P} _ {(i)} ^ {J} - F _ {(i)} ^ {J}),
$$

where $C ^ { N J }$ is the lumped capcitance matrix, $P ^ { J }$ is the applied nodal source, and $F ^ { J }$ is the internal flux vector. The temperature is integrated in time using the explicit forward-difference integration rule,

$$
\theta_ {(i + 1)} ^ {N} = \theta_ {(i)} ^ {N} + \Delta t _ {(i + 1)} \cdot \dot {\theta} _ {(i)} ^ {N}.
$$

More details can be found in “Explicit dynamic analysis,” Section 6.3.3 and “Fully coupled thermalstress analysis,” Section 6.5.3. The signs of the forces defined in $F ^ { J }$ are such that external forces provide positive nodal force values and “internal” forces caused by stresses, damping effects, internal heat fluxes, etc. in the element provide negative nodal force values. Internal forces due to bulk viscosity are dependent on the scaled mass of the element. The necessary information (bulk viscosity constants and mass scaling factors) is passed into the user subroutine for this purpose.

# Requirements for defining the mass matrix

As explained in “Explicit dynamic analysis,” Section 6.3.3, what makes the explicit time integration method efficient is that the mass inversion process is extremely effective. This is due to the fact that most of the nonzero entries in the mass matrix are located on the diagonal positions. The only exception is for rotational degrees of freedom in three-dimensional analyses in which case at each node an anisotropic rotary inertia (symmetric 3 × 3 tensor) can be defined. In these cases some of the nonzero entries in the mass matrix may be off-diagonal; but the inversion process is local and, hence, very effective. The mass matrix defined in user subroutine VUEL must adhere to these requirements as illustrated in detail in “VUEL,” Section 1.2.14 of the Abaqus User Subroutines Reference Guide. If you specify a zero mass matrix or skip the definition of the mass matrix altogether, Abaqus/Explicit issues an error message.

The definition of a realistic mass matrix is not mandatory, but it is strongly recommended. If you choose to not define a realistic mass matrix using the user subroutine, you must provide realistic mass, rotary inertia, heat capacity, etc. at all nodes and at all degrees of freedom associated with the user element. This can be accomplished by various means, such as by defining mass and rotary inertia elements at the nodes or by connecting the user element to other elements for which density, heat capacity, etc. was specified.

Mass is computed only once at the beginning of the analysis. Consequently, the mass of the user element cannot be changed arbitrarily during the analysis. If necessary, mass scaling is applied accordingly to ensure the requested time incrementation.

# Definition of the stable time increment

Since the central difference operator is conditionally stable, the time increments in Abaqus/Explicit must be somewhat smaller than the stable time increment. You must provide an accurate estimate for the stable time increment associated with the user element. This scalar value is highly dependent on the element formulation, and sophisticated coding may be required inside the user subroutine to obtain a reliable estimate. A conservative estimate will reduce the time increment size for the entire analysis and, hence, lead to longer analysis times.
