User-Defined Elements

Assigning an Element Type Key to a User-Defined Element

You must assign an element type key to a user-defined element. The element type key must be of the form Un in Abaqus/Standard and VUn in Abaqus/Explicit, where n is a positive integer that identifies the element type uniquely. For example, you can define element types U1, U2, U3, VU1, VU7, etc. In Abaqus/Standardn must be less than 10000; while in Abaqus/Explicitn must be less than 9000.

The element type key is used to identify the element in the element definition. For general user elements the integer part of the identifier is provided in user subroutines UEL, UELMAT and VUEL so that you can distinguish between different element types.

Input File Usage

USER ELEMENT, TYPE=element_type

Invoking User-Defined Elements

User-defined elements are invoked in the same way as native Abaqus elements: you specify the element type, Un or VUn, and define element numbers and nodes associated with each element (see Abaqus Model Definition). User elements can be assigned to element sets in the usual way, for cross-reference to element property definitions, output requests, distributed load specifications, etc.

Material definitions (Material Data Definition) are relevant only to user-defined elements in Abaqus/Standard. If a material is assigned to a user-defined element (Assigning an Abaqus Material to the User Element), user subroutine UELMAT will be used to define the element response. User subroutine UELMAT allows access to selected Abaqus materials. If no material definition is specified, all material behavior must be defined in user subroutines UEL and VUEL, based on user-defined material constants and on solution-dependent state variables associated with the element and calculated in the same subroutines. For linear user elements all material behavior must be defined through a user-defined stiffness matrix.

Input File Usage

Use the following options to invoke a user-defined element:

USER ELEMENT, TYPE=element_type
ELEMENT, TYPE=element_type

Defining the Active Degrees of Freedom at the Nodes

Any number of user element types can be defined and used in a model. Each user element can have any number of nodes, at each of which a specified set of degrees of freedom is used by the element. The activated degrees of freedom should follow the Abaqus convention (Conventions). In Abaqus/Standard this is important because the convergence criteria are based on the degrees of freedom numbers. In Abaqus/Explicit the activated degrees of freedom must follow the Abaqus convention because these are the only degrees of freedom that can be updated.

Abaqus always works in the global system when passing information to or from a user element. Therefore, the user element's stiffness, mass, etc. should always be defined with respect to global directions at its nodes, even if local transformations (Transformed Coordinate Systems) are applied to some of these nodes.

You define the ordering of the variables on a user element. The standard and recommended ordering is such that the degrees of freedom at the first node appear first, followed by the degrees of freedom at the second node, etc. For example, suppose that the user-defined element type is a planar beam with three nodes. The element uses degrees of freedom 1, 2, and 6 ( $u_{x}$ , $u_{y}$ , and $ϕ_{z}$ ) at its first and last node and degrees of freedom 1 and 2 at its second (middle) node. In this case the ordering of variables on the element is:


Element variable number	Node	Degree of freedom
1	1	1
2	1	2
3	1	6
4	2	1
5	2	2
6	3	1
7	3	2
8	3	6

This ordering will be used in most cases. However, if you define an element matrix that does not have its degrees of freedom ordered in this way, you can change the ordering of the degrees of freedom as outlined below.

You specify the active degrees of freedom at each node of the element. If the degrees of freedom are the same at all of the element's nodes, you specify the list of degrees of freedom only once. Otherwise, you specify a new list of degrees of freedom each time the degrees of freedom at a node are different from those at previous nodes. Thus, different nodes of the element can use different degrees of freedom; this is especially useful when the element is being used in a coupled field problem so that, for example, some of its nodes have displacement degrees of freedom only, while others have displacement and temperature degrees of freedom. This method will produce an ordering of the element variables such that all of the degrees of freedom at the first node appear first, followed by the degrees of freedom at the second node, etc.

In Abaqus/Standard there are two ways to define element variable numbers that order the degrees of freedom on the element differently.

Since the user element can accept repeated node numbers when defining the nodal connectivity for the element, the element can be declared to have one node per degree of freedom on the element. For example, if the element is a planar, 3-node triangle for stress analysis, it has three nodes, each of which has degrees of freedom 1 and 2. If all degrees of freedom 1 are to appear first in the element variables, the element can be defined with six nodes, the first three of which have degree of freedom 1, while nodes 4–6 have degree of freedom 2. The element variables would be ordered as follows:


Element variable number	Node	Degree of freedom
1	1	1
2	2	1
3	3	1
4	4	2
5	5	2
6	6	2

Alternatively, the user element variables can be defined so as to order the degrees of freedom on the element in any arbitrary fashion. You specify a list of degrees of freedom for the first node on the element. All nodes with a nodal connectivity number that is less than the next connectivity number for which a list of degrees of freedom is specified will have the first list of degrees of freedom. The second list of degrees of freedom will be used for all nodes until a new list is defined, etc. If a new list of degrees of freedom is encountered with a nodal connectivity number that is less than or equal to that given with the previous list, the previous list's degrees of freedom will be assigned through the last node of the element. This generation of degrees of freedom can be stopped before the last node on the element by specifying a nodal connectivity number with an empty (blank) list of degrees of freedom.

Example

The above procedure continues using this new list to define additional degrees of freedom according to the new node and degrees of freedom. For example, consider a 3-node beam that has degrees of freedom 1, 2, and 6 at nodes 1 and 3 and degrees of freedom 1 and 2 at node 2 (middle node). To order degrees of freedom 1 first, followed by 2, followed by 6, the following input could be used:

USER ELEMENT
1
1, 2
1, 6
2,
3, 6

In this case the ordering of the variables on the element is:


Element variable number	Node	Degree of freedom
1	1	1
2	2	1
3	3	1
4	1	2
5	2	2
6	3	2
7	1	6
8	3	6

Requirements for Activated Degrees of Freedom in Abaqus/Explicit

There are the following additional requirements with respect to activated degrees of freedom on a user element of type VUn:

Only degrees of freedom 1 through 6, 8, and 11 can be activated because these are the only degrees of freedom numbers that can be updated in Abaqus/Explicit. (In Abaqus/Standard degrees of freedom 1 through 30 can be used.)
If one translational degree of freedom is activated at a node, all translational degrees of freedom up to the specified maximum number of coordinates must be activated at that node; moreover, the translational degrees of freedom at the node must be in consecutive order.
In three-dimensional analyses, if one rotational degree of freedom is activated at a node, all three rotational degrees of freedom must be activated in consecutive order.

For example, if you define a 4-node three-dimensional user element that has translations and rotations active at the first and fourth nodes, temperature only at the second node, and translations and temperature at the third node, the following input could be used:

USER ELEMENT
1,2,3,4,5,6
2,11
3,1,2,3,11
4,1,2,3,4,5,6

Rotation Update in Geometrically Nonlinear Analyses

If all three rotational degrees of freedom (4, 5, and 6) are used at a node in a geometrically nonlinear analysis, Abaqus assumes that these rotations are finite rotations. In this case the incremental values of these degrees of freedom are not simply added to the total values: the quaternion update formulae are used instead. Similarly, the corrections are not simply added to the incremental values. The update procedure is described in Rotation variables and is mentioned in Conventions.

To avoid the rotation update in a geometrically nonlinear analysis in Abaqus/Standard, you may define repeated node numbers in the nodal connectivity of the element such that at least one of the degrees of freedom 4, 5, or 6 is missing from the degree of freedom list at each node.

Visualizing User-Defined Elements in Abaqus/CAE

Plotting of user elements is not supported in Abaqus/CAE. However, if the user elements contain displacement degrees of freedom, they can be overlaid with standard elements; and model plots of these standard elements can be displayed, allowing you to see the shape of the user elements. If deformed mesh plots of the user elements are required, the material properties of the overlaying standard elements must be chosen so that the solution is not changed by including them. If this technique is used, nodes of the user element will be tied to nodes of the standard elements. Therefore, degrees of freedom 1, 2, and 3 in the user element must correspond to the displacement degrees of freedom at the nodes of the standard elements.

Defining a Linear User Element in Abaqus/Standard

Linear user elements can be defined only in Abaqus/Standard. In the simplest case a linear user element can be defined as a stiffness matrix and, if required, a mass matrix, as well as viscous and/or structural damping matrices. Stiffness and mass matrices can be read from a results file or defined directly. When damping is required, the linear user element must be defined directly. The damping matrices cannot be stored on a result file.

Reading the Element Matrices from an Abaqus/Standard Results File

To read the element matrices from an Abaqus/Standard results file, you must have written the stiffness and/or mass matrices in a previous analysis to the results file as element matrix output (Element Matrix Output in Abaqus/Standard) or substructure matrix output (Writing the Recovery Matrix, Reduced Stiffness Matrix, Mass Matrix, Load Case Vectors, and Gravity Vectors to a File). Damping matrices cannot be written to the results file.

You must specify the element number, n, or substructure identifier, Zn, to which the matrices correspond. For models defined in terms of an assembly of part instances (Assembly Definition), the element numbers written to the results file are internal numbers generated by Abaqus/Standard (see About Output). A map between these internal numbers and the original element numbers and part instance names is provided in the data file of the analysis from which the element matrix output was written.

In addition, for element matrix output you must specify the step number and increment number at which the element matrix was written. These items are not required if a substructure whose matrix was output during its generation is used.

Input File Usage

USER ELEMENT, FILE=name, OLD ELEMENT=n or Zn, STEP=n, INCREMENT=n

Defining the Linear User Element by Specifying the Matrices Directly

If you define the stiffness, mass, or damping matrices directly, you must specify the number of nodes associated with the element.

Input File Usage

USER ELEMENT, LINEAR, NODES=n

Defining Whether or Not the Element Matrices Are Symmetric

If the element matrices are not symmetric, you can request that Abaqus/Standard use its nonsymmetric equation solution capability (see Defining an Analysis).

Input File Usage

USER ELEMENT, LINEAR, NODES=n, UNSYMM

Defining the Mass, Stiffness, or Damping Matrix

You define the element mass matrix, the element stiffness matrix, and the element viscous or structural damping matrix as needed. If the element is a heat transfer element, the “stiffness matrix” is the conductivity matrix and the “mass matrix” is the specific heat matrix.

You can define any applicable types of matrices simultanously.

You can read the mass and/or stiffness matrices from a file or define them directly. When damping matrices are needed, all of the matrices must be defined 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 define the element viscous damping matrix:

MATRIX, TYPE=VISCOUS DAMPING

Use the following option to define the element structural damping matrix:

MATRIX, TYPE=STRUCTURAL DAMPING

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_{m 1}$   
 $A_{12},$   $A_{22},$   $A_{32},$   $A_{42}$   
Etc.

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.

Defining the Element Properties

You must associate a property definition with every user element, even though no property values (except Rayleigh and/or structural 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:

UEL PROPERTY, ELSET=name

Defining Damping for Dynamic Analyses

You can define the Rayleigh damping factors for dynamic analyses (Implicit Dynamic Analysis Using Direct Integration) only for linear user elements. These damping factors can be defined for mode-based transient analysis, mode-based steady-state analysis, and direct steady-state analysis for both the linear and nonlinear formulations. The Rayleigh damping factors are defined as

[C] = α [M] + β [K],

where $[C]$ is the damping matrix, $[M]$ is the mass matrix, $[K]$ is the stiffness matrix, and $α$ and $β$ are the user-specified damping factors. See Material Damping for more information on Rayleigh damping.

You can define the structural damping factor (s) for direct and mode-based steady-state analyses. The damping matrix resulting from this factor is proportional to the user element stiffness matrix and is defined as

[S] = s [K] .

Input File Usage

Use the following option to specify the Rayleigh damping factors:

UEL PROPERTY, ELSET=name, ALPHA= $α$ , BETA= $β$

Use the following option to specify the structural damping factor:

UEL PROPERTY, ELSET=name, STRUCTURAL= $s$

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 and Thermal Loads).

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).

Input File Usage

USER ELEMENT, NODES=n, UNSYMM

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.

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) 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

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 × (6 × 3 + 1) = 76.

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 and damping matrix, and so on. Often, several of these functions must be performed in a single call to the routine. In mode-based analyses the user element is formulated only once and projected onto the eigensystem.

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^{α}$ within the element:

F^{N} = F^{N} (u^{M}, H^{α}, 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 force values. For example, in the case of mechanical equilibrium of a finite element subject to surface tractions $t$ and body forces $f$ with stress $σ$ , and with interpolation $δ u = N^{N} δ u^{N}$ , $δ ε = β^{N} δ u^{N},$

F^{N} = \int_{S} N^{N} \cdot t d S + \int_{V} N^{N} \cdot f d V - \int_{V} β^{N} : σ d V .

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


Solve	${\tilde{K}}^{N M} c^{M} = R^{M}$ ,
Set	$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 $F^{N}$ on the $u^{M}$ . For example, the $H^{α}$ will generally depend on $u^{M}$ ; therefore, $- d F^{N} / d u^{M}$ will include terms such as

- \frac{\partial F^{N}}{\partial H^{α}} \frac{\partial H^{α}}{\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 Introduction: general. For example, in transient heat transfer analysis, the backward difference method is used:

{\dot{u}}_{t + Δ t} = \frac{1}{Δ t} (u_{t + Δ t} - u_{t}) .

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

- \frac{\partial F^{N}}{\partial {\dot{u}}^{M}} {(\frac{d \dot{u}}{d u})}_{t + Δ t},

where ${(d \dot{u} / d u)}_{t + Δ t}$ is defined from the time integration procedure as $1 / Δ 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 $Δ u^{M} / Δ t$ , where $Δ u^{M} = u_{t + Δ t}^{M} - u_{t}^{M}$ . However, for direct, implicit integration of dynamic systems (see Implicit dynamic analysis) 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}} {(\frac{d \dot{u}}{d u})}_{t + Δ t} - \frac{\partial F^{N}}{\partial {\ddot{u}}^{M}} {(\frac{d \ddot{u}}{d u})}_{t + Δ t} .

For the Hilber-Hughes-Taylor scheme

\begin{matrix} {(\frac{d \dot{u}}{d u})}_{t + Δ t} & = \frac{γ}{β Δ t}, \\ {(\frac{d \ddot{u}}{d u})}_{t + Δ t} & = \frac{1}{β Δ t^{2}}, \end{matrix}

where $β$ and $γ$ are the (Newmark) parameters of the integration scheme. For backwark Euler time integration, the same expressions apply with $β$ and $γ$ 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 + Δ t} + (1 + α) G_{t + Δ t}^{N} - α 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_{α}$ array must be used to recover $G_{t}^{N}$ (and $G_{t^{-}}^{N}$ if half-increment residual calculations are required, where $t^{-}$ indicates $G^{N}$ from the beginning of the previous increment) and used to store $G_{t + Δ 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, $α$ , 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 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^{α}$ ) 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 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_{α}$ , can be used for this purpose. Abaqus/Standard will still compute and store values of ${\dot{u}}^{N}$ and ${\ddot{u}}^{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 and Accessing Abaqus Materials). 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). The material models that are accessible from user subroutine UELMAT are:

linear elastic model;
hyperelastic model;
Ramberg-Osgood model;
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^{α}$ within the element:

F^{J} = F^{J} (u^{M}, {\dot{u}}^{M}, H^{α}, 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{Δ t_{(i + 1)} + Δ t_{(i)}}{2} {\ddot{u}}_{(i)}^{N},

u_{(i + 1)}^{N} = u_{(i)}^{N} + Δ 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

{\dot{θ}}_{(i)}^{N} = {(C^{N J})}^{- 1} (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,

θ^{N}_{(i + 1)} = θ_{(i)}^{N} + Δ t_{(i + 1)} \cdot {\dot{θ}}_{(i)}^{N} .

More details can be found in Explicit Dynamic Analysis and Fully Coupled Thermal-Stress Analysis. 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, 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. 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.

Defining Loads

You can apply point loads, moments, fluxes, etc. to the nodes of general user-defined elements in the usual way, using concentrated loads and concentrated fluxes (Concentrated Loads and Thermal Loads).

You can also define distributed loads and fluxes for general user-defined elements (Distributed Loads and Thermal Loads). These loads require a load type key. For user-defined elements, you can define load type keys of the forms Un and, in Abaqus/Standard, UnNU, where n is any positive integer.

If the load type key is of the form Un, the load magnitude is defined directly and follows the standard Abaqus conventions with respect to its amplitude variation as a function of time. In Abaqus/Standard, if the load key is of the form UnNU, all of the load definition will be accomplished inside subroutine UEL and UELMAT. Each time Abaqus/Standard calls subroutine UEL or UELMAT, it tells the subroutine how many distributed loads/fluxes are currently active. For each active load or flux of type UnAbaqus/Standard gives the current magnitude and current increment in magnitude of the load. The coding in subroutine UEL or UELMAT must distribute the loads into consistent equivalent nodal forces and, if necessary, provide their contribution to the Jacobian matrix—the “load stiffness matrix.”

In Abaqus/Explicit only load keys of the form Un can be used, and they can be used only for distributed loads (however, thermal fluxes can be defined in the coding in subroutine VUEL). Each time Abaqus/Explicit calls subroutine VUEL, it tells the subroutine which load number is currently active and the current magnitude of the load. The coding in subroutine VUEL must distribute the loads into consistent equivalent nodal forces.

Defining Output

All quantities to be output must be saved as solution-dependent state variables. In Abaqus/Standard the solution-dependent state variables can be printed or written to the results file using output variable identifier SDV (Abaqus/Standard Output Variable Identifiers).

The components of solution-dependent state variables that belong to a user element are not available in Abaqus/CAE. You can write output to separate files in a table format that can be accessed in Abaqus/CAE to produce history output.

Currently element output to the output database is not supported for user-defined elements.

Defining Wave Kinematic Data

A utility routine GETWAVE is provided in user subroutine UEL to access the wave kinematic data defined for an Abaqus/Aqua analysis (Abaqus/Aqua Analysis). This utility is discussed in Obtaining Wave Kinematic Data in an Abaqus/Aqua Analysis, where the arguments to GETWAVE and the syntax for its use are defined.

Use in Contact

Only node-based surfaces (Node-Based Surface Definition) can be created on user-defined elements. Hence, these elements can be used to define only secondary surfaces in a contact analysis. In Abaqus/Explicit the user elements will not be included in the general contact algorithm automatically. Node-based surfaces can be defined using these nodes and then included in the general contact definition.

Import of User Elements

User elements cannot be imported from an Abaqus/Standard analysis into an Abaqus/Explicit analysis or vice versa. Equivalent user elements can be defined in both products to overcome this limitation. However, the state variables associated with these elements will not be communicated.