<!-- source-page: 181 -->

# CELENT

Characteristic element length, which is a typical length of a line across an element for a first-order element; it is half of the same typical length for a second-order element. For beams and trusses it is a characteristic length along the element axis. For membranes and shells it is a characteristic length in the reference surface. For axisymmetric elements it is a characteristic length in the (r, z) plane only. For cohesive elements it is equal to the constitutive thickness.

# DROT(3,3)

Rotation increment matrix. This matrix represents the increment of rigid body rotation of the basis system in which the components of stress (STRESS) and strain (STRAIN) are stored. It is provided so that vector- or tensor-valued state variables can be rotated appropriately in this subroutine: stress and strain components are already rotated by this amount before UDMGINI is called. This matrix is passed in as a unit matrix for small-displacement analysis and for large-displacement analysis if the basis system for the material point rotates with the material (as in a shell element or when a local orientation is used).

# ORI(3,3)

Material orientation with respect to global basis.

# Example: User-defined damage initiation criterion with two different failure mechanisms

As a simple example of the coding of user subroutine UDMGINI, consider a damage initiation criterion based on two different failure mechanisms: the maximum principal stress and the quadratic tractioninteraction.

```csv
SUBROUTINE UDMGINI(FINDEX,NFINDEX,FNORMAL,NDI,NSHR,NTENS,PROPS,
1 NPROPS,STATEV,NSTATEV,STRESS,STRAIN,STRAINEE,LXFEM,TIME,
2 DTIME,TEMP,DTEMP,PREDEF,DPRED,NFIELD,COORDS,NOEL,NPT,
3 KLAYER,KSPT,KSTEP,INC,KDIRCYC,KCYCLELCF,TIMECYC,SSE,SPD,
4 SCD,SVD,SMD,JMAC,JMATYP,MATLAYO,LACCFLA,CELENT,DROT,ORI)
C
INCLUDE 'ABA_PARAM.INC'
CC
DIMENSION FINDEX(NFINDEX),FNORMAL(NDI,NFINDEX),COORDS(*),
1 STRESS(NTENS),STRAIN(NTENS),STRAINEE(NTENS),PROPS(NPROPS),
2 STATEV(NSTATEV),PREDEF(NFIELD),DPRED(NFIELD),TIME(2),
3 JMAC(*),JMATYP(*),DROR(3,3),ORI(3,3)
DIMENSION PS(3), AN(3,3), WT(6)
PS(1)=0.0
PS(2)=0.0
PS(3)=0.0 
```

<!-- source-page: 182 -->

```txt
C
C ROTATE THE STRESS TO GLOBAL SYSTEM IF THERE IS ORIENTATION
C
CALL ROTSIG(STRESS,ORI,WT,1,NDI,NSHR)
C
C MAXIMUM PRINCIPAL STRESS CRITERION
C
CALL SPRIND(WT,PS,AN,1,NDI,NSHR)
SIG1 = PS(1)
KMAX=1
DO K1 = 2, NDI
IF(PS(K1).GT.SIG1) THEN
SIG1 = PS(K1)
KMAX = K1
END IF
END DO
FINDEX(1) = SIG1/PROPS(1)
DO K1=1, NDI
FNORMAL(K1,1) = AN(KMAX,K1)
END DO
C
C QUADRATIC TRACTION-INTERACTION CRITERION
C
FINDEX(2)=(STRESS(1)/PROPS(2))**2.0+(STRESS(NDI+1)/
$ PROPS(3))**2.0+(STRESS(NDI+2)/PROPS(4))**2.0
C
FINDEX(2)=sqrt(FINDEX(2))
C
DO K1=1, NDI
FNORMAL(K1,2)=ORI(K1,1)
END DO
RETURN
END 
```

<!-- source-page: 183 -->

# 1.1.27 UDSECURRENT: User subroutine to define nonuniform surface current density in an eddy current or magnetostatic analysis.

Product: Abaqus/Standard

# References

• “Eddy current analysis,” Section 6.7.5 of the Abaqus Analysis User’s Guide   
• “Magnetostatic analysis,” Section 6.7.6 of the Abaqus Analysis User’s Guide   
• \*DSECURRENT

# Overview

User subroutine UDSECURRENT:

• can be used to define the variation of surface current density vector as a function of position, time, element number, load integration point number, etc. for a transient eddy current or magnetostatic analysis or as a function of position, excitation frequency, phase, element number, load integration point number, etc. for a time-harmonic eddy current analysis;   
• will be called at each surface load integration point for each nonuniform surface current density definition during eddy current and magnetostatic analyses; and   
• ignores any amplitude references that may appear with the associated step definition or nonuniform distributed surface current density definition.

# User subroutine interface

```txt
subroutine udsecurrent (
C Write only -
* surfacecurrent,
C Read only -
* coords, nBlock,
* i_array, niarray,
* r_array, nrarray,
* c_array, narray )
C
include 'aba_param.inc'
C
dimension surfacecurrent(nBlock,*),
* coords(nBlock,*),
* i_array(*),
* r_array(*)
C 
```

<!-- source-page: 184 -->

```lua
character*80 c_array(*)

parameter(i_udsecurr_kstep = 1,
* i_udsecurr_kinc = 2,
* i_udsecurr_noel = 3,
* i_udsecurr_currtyp = 4,
* i_udsecurr_phase = 5,
* i_udsecurr_proc = 6)

parameter(ir_udsecurr_time_1 = 1,
* ir_udsecurr_time_2 = 2,
* ir_udsecurr_time_3 = 3)

parameter(ic_udsecurr_surf = 1)

parameter(i_currtyp_tangential = 1)

parameter(i_proc_lf_th = 1,
* i_proc_lf_td = 2,
* i_proc_ms = 3)

parameter(i_udsecurr_phase_real = 1,
* i_udsecurr_phase_imag = 2)

user coding to define surfacecurrent

return
end 
```

# Variable to be defined

surfacecurrent(nBlock,\*)

Components of the surface current density vector at a block of surface integration points. The units are $\mathrm { C L ^ { - 1 } T ^ { - 1 } }$ . surfacecurrent will be passed into the routine as the vector specified as part of the surface-based distributed surface current density definition. If the vector is not defined, surfacecurrent will be passed in as zero.

# Variables passed in for information

coords(nBlock,\*)

An array containing the coordinates of a block of surface load integration points.

<!-- source-page: 185 -->

nBlock

Number of surface integration points in this block. Currently equal to 1.

i\_array(i\_udsecurr\_kstep)

Step number.

i\_array(i\_udsecurr\_kinc)

Increment number.

i\_array(i\_udsecurr\_noel)

Element number.

i\_array(i\_udsecurr\_currtyp)

Currently equal to 1.

i\_array(i\_udsecurr\_phase)

This value is relevant only for a time-harmonic eddy current analysis and is either 1 (i\_udsecurr\_phase\_real) or 2 (i\_udsecurr\_phase\_imag), depending on whether the current call to the user subroutine defines the real (in-phase) or the imaginary (out-of-phase) part of the surface current density vector.

i\_array(i\_udsecurr\_proc)

Equal to 1 for a time-harmonic eddy current procedure, 2 for a transient eddy current procedure, and 3 for a magnetostatic procedure.

niarray

Size of array i\_array. Currently equal to 6.

r\_array(ir\_udsecurr\_time\_1)

Excitation frequency in cycles/time for a time-harmonic eddy current analysis; alternatively, the value of step time at the beginning of the current increment for a transient eddy current or magnetostatic analysis.

r\_array(ir\_udsecurr\_time\_2)

Excitation frequency in radians/time for a time-harmonic eddy current analysis; alternatively, the value of total time at the beginning of the current increment for a transient eddy current or magnetostatic analysis.

r\_array(ir\_udsecurr\_time\_3)

Time increment for a transient eddy current or magnetostatic analysis.

nrarray

Size of array r\_array. Currently equal to 3.

c\_array(ic\_udsecurr\_surf)

Surface name.

<!-- source-page: 186 -->

# ncarray

Size of array c\_array. Currently equal to 1.

<!-- source-page: 187 -->

# 1.1.28 UEL: User subroutine to define an element.

# Product: Abaqus/Standard

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

# References

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

# Overview

User subroutine UEL:

• will be called for each element that is of a general user-defined element type (i.e., not defined by a linear stiffness or mass matrix read either directly or from results file data) each time element calculations are required; and   
• (or subroutines called by user subroutine UEL) must perform all of the calculations for the element, appropriate to the current activity in the analysis.

# Wave kinematic data

For Abaqus/Aqua applications four utility routines—GETWAVE, GETWAVEVEL, GETWINDVEL, and GETCURRVEL—are provided to access the fluid kinematic data. These routines are used from within user subroutine UEL and are discussed in detail in “Obtaining wave kinematic data in an Abaqus/Aqua analysis,” Section 2.1.13.

# User subroutine interface

```txt
SUBROUTINE UEL (RHS, AMATRX, SVARS, ENERGY, NDOFEL, NRHS, NSVARS,
1 PROPS, NPROPS, COORDS, MCRD, NNODE, U, DU, V, A, JTYPE, TIME, DTIME,
2 KSTEP, KINC, JELEM, PARAMS, NDLOAD, JDLTYP, ADLMAG, PREDEF, NPREF,
3 LFLAGS, MLVARX, DDLMAG, MDLOAD, PNEWDT, JPROPS, NJPROP, PERIOD)
C
INCLUDE 'ABA_PARAM.INC'
C
DIMENSION RHS (MLVARX, *), AMATRX (NDOFEL, NDOFEL), PROPS (*),
1 SVARS (*), ENERGY (8), COORDS (MCRD, NNODE), U (NDOFEL), 
```

<!-- source-page: 188 -->

2 DU(MLVARX,\*),V(NDOFEL),A(NDOFEL),TIME(2),PARAMS(\*),   
3 JDLTYP(MDLOAD,\*),ADLMAG(MDLOAD,\*),DDLMAG(MDLOAD,\*),   
4 PREDEF(2,NPREDF,NNODE),LFLAGS(\*),JPROPS(\*)

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

RETURN END

# Variables to be defined

These arrays depend on the value of the LFLAGS array.

# RHS

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

# AMATRX

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

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

# SVARS

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

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

<!-- source-page: 189 -->

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

# ENERGY

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

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

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

# Variable that can be updated

# PNEWDT

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

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

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

<!-- source-page: 190 -->

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

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

# Variables passed in for information

# Arrays:

# PROPS

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

# JPROPS

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

# COORDS

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

# U, DU, V, A

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

<table><tr><td>U (K1)</td><td>Total values of the variables. If this is a linear perturbation step, it is the value in the base state.</td></tr><tr><td>DU (K1, KRHS)</td><td>Incremental values of the variables for the current increment for right-hand-side KRHS. If this is an eigenvalue extraction step, this is the eigenvector magnitude for eigenvector KRHS. For steady-state dynamics, KRHS = 1 denotes real components of perturbation displacement and KRHS = 2 denotes imaginary components of perturbation displacement.</td></tr><tr><td>V (K1)</td><td>Time rate of change of the variables (velocities, rates of rotation). Defined for implicit dynamics only (LFLAGS (1) = 11 or 12).</td></tr><tr><td>A (K1)</td><td>Accelerations of the variables. Defined for implicit dynamics only (LFLAGS (1) = 11 or 12).</td></tr></table>
