About User Subroutines and Utilities

Every user subroutine written in Fortran must include one of the following statements as the first statement after the argument list:

• Abaqus/Standard:

include 'aba_param.inc'

• Abaqus/Explicit:

include 'vaba_param.inc'

If variables are exchanged between the main user subroutine and subsequent subroutines, you should specify the above include statement in all the subroutines to preserve precision.

Every C and C++ user subroutine must include the statement

#include <omi_for_c.h>

This file contains macros for the Fortran-to-C interface interoperability.

The files aba_param.inc, vaba_param.inc, and omi_for_c.h are installed on the system by the Abaqus installation procedure and contain important installation parameters. These statements tell the Abaqus execution procedure, which compiles and links the user subroutine with the rest of Abaqus, to include the aba_param.inc or vaba_param.inc file automatically. It is not necessary to find the file and copy it to any particular directory; Abaqus will know where to find it.

If user subroutines call other subroutines or use COMMON blocks to pass information, such subroutines or COMMON blocks should begin with the letter K since this letter is never used to start the name of any subroutine or COMMON block in Abaqus.

User subroutines written in C or C++ will be called from Fortran; therefore, they must conform to the Fortran calling conventions: the name of a C or C++ subroutine must be wrapped in a FOR_NAME macro; for example,

 extern “C“ void   FOR_NAME(film,FILM) (double & arg1, ...) { ˙˙˙ } 

and the arguments must be passed and received by reference.

User subroutines must perform their intended function without overwriting other parts of Abaqus. In particular, you should redefine only those variables identified in this chapter as “variables to be defined.” Redefining “variables passed in for information” will have unpredictable effects.

If problems are encountered during compilation or linking of the subroutine, make sure that the Abaqus environment file (the default location for this file is the site subdirectory of the Abaqus installation) contains the correct compile and link commands as specified in . These commands should have been set up by the Abaqus site manager during installation. The number and type of arguments must correspond to what is specified in the documentation. Mismatches in type or number of arguments might lead to platform-dependent linking or runtime errors.

Your user subroutine will share memory resources with Abaqus. When you need to use large arrays or other large data structures, you should allocate their memory dynamically, so that memory is allocated from the heap and not the stack. Failure to dynamically allocate large arrays might result in stack overflow errors and an exit of your Abaqus analysis. For an example of dynamic allocation using native Fortran allocatable arrays, refer to Creation of a data file to facilitate the postprocessing of elbow element results: FELBOW. Abaqus also provides another, more convenient way for users to allocate their own storage (see Allocatable Arrays).

When developing user subroutines, test them thoroughly on smaller examples in which the user subroutine is the only complicated aspect of the model before attempting to use them in production analysis work.

If needed, debug output can be written to the Abaqus/Standard message (.msg) file using Fortran unit 7 or to the Abaqus/Standard data (.dat) file or the Abaqus/Explicit log (.log) file using Fortran unit 6; these units should not be opened by your routines since they are already opened by Abaqus.

Fortran units 15 through 18 or units greater than 100 can be used to read or write other user-specified information. The use of other Fortran units might interfere with Abaqus file operations; see Fortran Unit Numbers. You must open these Fortran units; and because of the use of scratch directories, the full pathname for the file must be used in the OPEN statement.

Environment variable ABA_PARALLEL_DEBUG can be set to turn on verbosity, to display compilation and linking commands, and to enable debugging of user subroutines.

Utility routine XIT (Abaqus/Standard) or XPLB_EXIT (Abaqus/Explicit) should be used instead of STOP when terminating an analysis from within a user subroutine. This will ensure that all files associated with the analysis are closed properly (Terminating an Analysis).

Although a local coordinate system can be defined for each part instance, all variables (such as current coordinates) are passed to a user subroutine in the global coordinate system, not in a part-local coordinate system. The only exception to this rule is when the user subroutine interface specifically indicates that a variable is in a user-defined local coordinate system (Orientations, or Transformed Coordinate Systems). The local coordinate system originally might have been defined relative to a part coordinate system, but it was transformed according to the positioning data given for the part instance. As a result, a new local coordinate system was created relative to the assembly (global) coordinate system. This new coordinate system definition is the one used for local orientations in user subroutines.

The node and element numbers passed to a user subroutine are internal numbers generated by Abaqus. These numbers are global in nature; all internal node and element numbers are unique. If the original number and the part instance name are required, call the utility subroutine GETPARTINFO (Abaqus/Standard) or VGETPARTINFO (Abaqus/Explicit) from within your user subroutine (see Obtaining Part Information). The expense of calling these routines is not trivial, so minimal use of them is recommended.

Another utility subroutine, GETINTERNAL (Abaqus/Standard) or VGETINTERNAL (Abaqus/Explicit), can be used to retrieve the internal node or element number corresponding to a given part instance name and local number.

Set and surface names passed to user subroutines are always prefixed by the assembly and part instance names, separated by underscores. For example, a surface named surf1 belonging to part instance Part1-1 in assembly Assembly1 will be passed to a user subroutine as

Assembly1_Part1-1_surf1

Any number of solution-dependent state variables can be used in the following user subroutines:

• CREEP

• FRIC

• FRIC_COEF

• HETVAL

• UANISOHYPER_INV

• UANISOHYPER_STRAIN

• UEL

• UEXPAN

• UGENS

• UHARD

• UHYPER

• UINTER

• UMAT

• UMATHT

• UMULLINS

• USDFLD

• UTRS

• VFABRIC

• VFRIC

• VFRICTION

• VHETVAL

• VUANISOHYPER_INV

• VUANISOHYPER_STRAIN

• VUFLUIDEXCH

• VUHARD

• VUINTER

• VUINTERACTION

• VUMAT

• VUMATHT

• VUMULLINS

• VUSDFLD

• VUTRS

• VUVISCOSITY

• VWAVE

The state variables can be defined as a function of any other variables appearing in these subroutines and can be updated accordingly. Solution-dependent state variables should not be confused with field variables, which might also be needed in the constitutive routines and can vary with time; field variables are discussed in detail in Predefined Fields.

Solution-dependent state variables used in VFRIC, VUINTER, VFRICTION, and VUINTERACTION are defined as state variables at secondary nodes and are updated with other contact variables.

You must allocate space for each of the solution-dependent state variables at every applicable integration point or contact secondary node.

Separate user subroutine groups have been identified that differ in the way the number of solution-dependent state variables is defined. These groups are described below. Solution-dependent state variables can be shared by subroutines within the same group; they cannot be shared between subroutines belonging to different groups.

You can define the initial values of solution-dependent state variable fields directly or in Abaqus/Standard through a user subroutine. The initial values of solution-dependent state variables for contact or for user subroutine VWAVE in Abaqus/Explicit are assigned as zero internally.

If element deletion controlled by state variables is defined in an analysis (see User-Defined Mechanical Material Behavior), the value of the state variable that is controlling the deletion flag can be modified by any of the user subroutines in which state variables are used, provided that the user subroutine is called at a material point.

User-defined, solution-dependent state variables can be written to the data (.dat) file, the output database (.odb) file, and the results (.fil) file; the output identifiers SDV and SDVn are available as element integration variables (see Abaqus/Standard Output Variable Identifiers and Abaqus/Explicit Output Variable Identifiers). Output of these variables is not available for user subroutines VFRIC, VUINTER, VFRICTION, VUINTERACTION, and VWAVE.

Any number of element solution-dependent variables can be used in the following user subroutines:

• UEPACTIVATIONFACET

• UEPACTIVATIONVOL

• UMDFLUX

Element solution-dependent variables can be defined as a function of any other variables appearing in these subroutines and can be updated accordingly. Element solution-dependent variables should not be confused with field variables, which might also be needed in the constitutive routines and can vary with time; field variables are discussed in detail in Predefined Fields.

You must allocate space for element solution-dependent variables at every applicable element. In each allocation you specify the number of element solution-dependent variables required at each element. You can optionally specify user-defined output keys and descriptions for some or all variables. The allocation should be used in conjunction with an element section definition, which defines section properties for elements in which element solution-dependent variables are to be considered.

You can define the initial values of element solution-dependent variables in a tabular format for elements and/or element sets. See for additional details.

Element deletion in a mesh can be controlled during a stress/displacement analysis by element solution-dependent variables in Abaqus/Standard. Deleted elements have no ability to carry stresses and, therefore, have no contribution to the stiffness of the model. You specify the element solution-dependent variable number controlling the element deletion flag. The deletion variable can be set to a value of one or zero. A value of one indicates that the element is active, while a value of zero indicates that Abaqus should delete the element from the model by setting the stresses to zero. The deletion variable is initialized as a value of one at the beginning of the analysis. This initial value can be overwritten by user-specified initial condition values. Once an element is flagged as deleted, it cannot be reactivated. The status of an element can be determined by requesting output of the variable STATUS. This variable is equal to one if the element is active and is equal to zero if the element is deleted.

Element solution-dependent variables can be written to the output database (.odb) file; the output identifiers ESDV and ESDVn are available as whole element variables (see Abaqus/Standard Output Variable Identifiers).

Most user subroutines that are used to define material, element, or interface behavior are called twice per material point, element, or secondary surface node in the first iteration of every increment such that the model's initial stiffness matrix can be formulated appropriately for the step procedure chosen. The subroutines are called only once per material point, element, or secondary surface node in each succeeding iteration within the increment.

By default, in transient implicit dynamic analyses (Implicit Dynamic Analysis Using Direct Integration) Abaqus/Standard calculates accelerations at the beginning of each dynamic step. Abaqus/Standard must call user subroutines that are used to define material, element, or interface behavior two extra times for each material point, element, or secondary surface node prior to the zero increment. The extra calls to the user subroutines are not made if the initial acceleration calculations are suppressed. If the half-increment residual tolerances are being checked in a transient implicit dynamic step, Abaqus/Standard must call these user subroutines (except UVARM) one extra time for each material point, element, or secondary surface node at the end of each increment. If the calculation of the half-increment residual is suppressed, the extra call to the user subroutines is not made.

User subroutines UHARD, UHYPEL, UHYPER, and UMULLINS, when used in plane stress analyses, are called more often.

User subroutines that are used to define initial conditions or orientations are called before the first iteration of the first step's initial increment within an analysis.

User subroutines that are used to define predefined fields are called prior to the first iteration of the relevant step's first increment for all iterations of all increments whenever the current field variable is needed.

If there is any doubt as to how often a user subroutine is called, this information can be obtained upon testing the subroutine on a small example, as suggested earlier. The current step and increment numbers are commonly passed into these subroutines, and they can be printed out as debug output (also discussed earlier). The iteration number for which the subroutine is called might not be passed into the user subroutine; however, if printed output is sent from the subroutine to the message (.msg) file (About Output), the location of the output within this file will give the iteration number, provided that the output to the message file is written at every increment.

The following utility routines require the use of Abaqus-provided variables passed into the user subroutines from which they are called:

• GETNODETOELEMCONN

• GETVRM

• GETVRMAVGATNODE

• GETVRN

• IGETSENSORID

• IVGETSENSORID

• MATERIAL_LIB_MECH

• MATERIAL_LIB_HT

These variables will be defined properly when passed into your user subroutine; you cannot modify the variables or create alternative variables for use in the utility routines.

For example, the GETVRM utility routine requires the variable JMAC, which is passed from Abaqus/Standard into user subroutine UVARM and other user subroutines for which GETVRM is a supported utility. The variable JMAC represents an Abaqus data structure that requires no further manipulation on your part. If you use the GETVRM utility routine from within user subroutine UVARM, you will pass the JMAC variable from UVARM into GETVRM.