Product: ABAQUS/Standard
User-defined elements:
can be finite elements in the usual sense of representing a geometric part of the model;
can be feedback links, supplying forces at some points as functions of values of displacement, velocity, etc. at other points in the model;
can be used to solve equations in terms of nonstandard degrees of freedom; and
can be linear or nonlinear.
You must assign an element type key to a user-defined element. The element type key must be of the form Un, where n is a positive integer that identifies the element type uniquely. n must be less than 10000. For example, you can define element types U1, U2, U3, … .
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 UEL so that you can distinguish between different element types.
| Input File Usage: | *USER ELEMENT, TYPE=Un |
User-defined elements are invoked in the same way as native ABAQUS elements: you specify the element type, Un, and define element numbers and nodes associated with each element (see “Defining a model in ABAQUS,” Section 1.3.1). 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,” Section 9.1.2) are not relevant to user-defined element types. For general user elements all material behavior must be defined in subroutine UEL, based on user-defined material constants and on solution-dependent state variables associated with the element and calculated in subroutine UEL. 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=Un *ELEMENT, TYPE=Un |
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,” Section 1.2.2) because the convergence criteria are based on the degrees of freedom numbers.
ABAQUS/Standard always works in the global system when passing information to or from a user element. Therefore, the user element's stiffness, etc. should always be defined with respect to global directions at its nodes, even if local transformations (“Transformed coordinate systems,” Section 2.1.5) 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 (
, 
, and 
) 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:
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.
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:
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.
The above procedure continues using this new list to define additional degrees of freedom in accordance with 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, 6In this case the ordering of the variables on the element is:
If all three rotational degrees of freedom (4, 5, and 6) are used at a node in a geometrically nonlinear analysis, ABAQUS/Standard 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,” Section 1.3.1 of the ABAQUS Theory Manual, and is mentioned in “Conventions,” Section 1.2.2.
To avoid the rotation update in a geometrically nonlinear analysis, 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.
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.
In the simplest case a linear user element can be defined as a stiffness matrix and, if required, a mass matrix. These matrices can be read from an ABAQUS/Standard results file or defined directly.
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” in “Output,” Section 4.1.1) or substructure matrix output (“Writing the recovery matrix, reduced stiffness matrix, mass matrix, load case vectors, and gravity vectors to a file” in “Defining substructures,” Section 7.2.2).
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 (“Defining an assembly,” Section 2.9.1), the element numbers written to the results file are internal numbers generated by ABAQUS/Standard (see “Output,” Section 4.1.1). 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 |
If you define the stiffness and/or mass matrix directly, you must specify the number of nodes associated with the element.
| Input File Usage: | *USER ELEMENT, LINEAR, NODES=n |
If the element matrices are not symmetric, you can request that ABAQUS/Standard use its nonsymmetric equation solution capability (see “Procedures: overview,” Section 6.1.1).
| Input File Usage: | *USER ELEMENT, LINEAR, NODES=n, UNSYMM |
You define the element mass matrix and the element stiffness matrix separately. 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 either one matrix for the element (mass or stiffness) or both types of matrices.
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:
If the matrix is unsymmetric, the following data lines should be used:
where |
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: |
*UEL PROPERTY, ELSET=name |
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
is the damping matrix, 
is the mass matrix, 
is the stiffness matrix, and 
and 
are the user-specified damping factors. See “Material damping,” Section 12.1.1, for more information on Rayleigh damping.| Input File Usage: | *UEL PROPERTY, ELSET=name, ALPHA= |
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 19.4.2, and “Thermal loads,” Section 19.4.4).
Distributed loads and fluxes cannot be defined for linear user-defined elements.
General user elements are defined in user subroutine UEL. The implementation of user elements in user subroutine UEL is recommended only for advanced users.
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 |
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 “Procedures: overview,” Section 6.1.1).
| Input File Usage: | *USER ELEMENT, NODES=n, UNSYMM |
You can define the maximum number of coordinates needed in user subroutine UEL at any node point of the element. ABAQUS/Standard 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/Standard 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 |
You can define the number of properties associated with a particular user element and then specify their numerical values.
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 subroutine UEL 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 |
You must associate a user element property definition with each user-defined element, even if no property values are required. The property values specifed in the property definition are passed into user subroutine UEL 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. |
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 subroutine UEL.
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 |
For a general user element, user subroutine UEL must 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 freedoms 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.
The element's principal contribution to the model during general analysis steps is that it provides nodal forces 
that depend on the values of the nodal variables 
and on the solution-dependent state variables 
within the element:
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 
and body forces 
with stress 
, and with interpolation 
, 
In general procedures ABAQUS/Standard solves the overall system of equations by Newton's method:
where
is the residual at degree of freedom 
and 
During such iterations you must define , which is the element's contribution to the residual, , and
. By writing the total derivative 
, we imply that the element's contribution to should include all direct and indirect dependencies of the on the . For example, the will generally depend on ; therefore, will include terms such as 
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 Theory Manual. For example, in transient heat transfer analysis, the backward difference method is used:
depends on and 
(as would be the case if the user element includes thermal energy storage), the Jacobian contribution should include the term 
is defined from the time integration procedure as 
.In all cases where ABAQUS/Standard integrates first-order problems in time, the are never stored because they are readily available as 
, where 
. However, for direct, implicit integration of dynamic systems ABAQUS/Standard uses the Hilber-Hughes-Taylor scheme (see “Implicit dynamic analysis,” Section 2.4.1 of the ABAQUS Theory Manual), which requires storage of and 
. 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
and 
are the (Newmark) parameters of the integration scheme. The term 
is the element's damping matrix, and 
is its mass matrix.The Hilber-Hughes-Taylor scheme writes the overall dynamic equilibrium equations as
is the total force at degree of freedom , excluding d'Alembert (inertia) forces. is often referred to as the “static residual.” Therefore, if a user element is to be used with the implicit dynamic procedure, the element's contribution 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 
array must be used to recover 
(and 
if half-step residual calculations are required, where 
indicates from the beginning of the previous increment) and used to store 
(and if half-step 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,” Section 6.3.2, for details).If solution-dependent state variables (
) are used in the element, a suitable time integration method must be coded into subroutine UEL for these variables. Any of the 
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 , 
, etc. at particular points in time, the solution-dependent state variable array, , can be used for this purpose. ABAQUS/Standard will still compute and store values of and 
using the Hilber-Hughes-Taylor formulae, 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.
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,” Section 19.4.2, and “Thermal loads,” Section 19.4.4).
You can also define distributed loads and fluxes for general user-defined elements (“Distributed loads,” Section 19.4.3, and “Thermal loads,” Section 19.4.4). These loads require a load type key. For user-defined elements, you can define load type keys of the forms Un and 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.
If the load key is of the form UnNU, all of the load definition will be accomplished inside subroutine UEL. Each time ABAQUS/Standard calls subroutine UEL, it tells the subroutine how many distributed loads/fluxes are currently active and for each active load or flux of type Un ABAQUS/Standard gives the current magnitude and current increment in magnitude of the load. The coding in subroutine UEL must distribute the loads into consistent equivalent nodal forces and, if necessary, provide their contribution to the Jacobian matrix—the “load stiffness matrix.”
All quantities to be output must be saved as solution-dependent state variables. The solution-dependent state variables can be printed or written to the results file using output variable identifier SDV (“ABAQUS/Standard output variable identifiers,” Section 4.2.1).
The components of solution-dependent state variables that belong to a user element are not available in ABAQUS/CAE.
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,” Section 6.10.1). This utility is discussed in “Obtaining wave kinematic data in an ABAQUS/Aqua analysis,” Section 26.2.10, where the arguments to GETWAVE and the syntax for its use are defined.
Only node-based surfaces (“Defining node-based surfaces,” Section 2.3.3) can be created on user-defined elements. Hence, these elements can be used to define only slave surfaces in a contact analysis.
Etc.
…
…, 
Etc.
is the size of the matrix and 
is the entry in the matrix for row i column j.
,
,