25.1.1 User subroutines: overview

User subroutines provide an extremely powerful and flexible tool for analysis. This chapter defines the interfaces for the user subroutines that are available in ABAQUS.

Reference

Overview

User subroutines:

  • are provided to increase the functionality of several ABAQUS options for which data line usage alone may be too restrictive;

  • are typically written as FORTRAN code and must be included in a model through an execution command line option, as discussed below;

  • must be included and, if desired, can be revised in a restarted run, since they are not saved to the restart files (see Restarting an analysis, Section 7.1.1);

  • cannot be called one from another; and

  • can in some cases call utility routines that are also available in ABAQUS (see Utility routines: overview, Section 26.1.1).

Including user subroutines in a model

One or more user subroutines can be included in a model by using the user option on the abaqus execution procedure to specify the name of a FORTRAN source or object file that contains the subroutines. Details are provided in Execution procedure for ABAQUS/Standard and ABAQUS/Explicit, Section 3.2.2.

Managing external databases in ABAQUS/Standard and exchanging information with other software

In ABAQUS/Standard it is sometimes desirable to set up the FORTRAN environment and manage interactions with external data files that are used in conjunction with user subroutines. For example, there may be history-dependent quantities to be computed externally, once per increment, for use during the analysis; or output quantities that are accumulated over multiple elements in COMMON block variables within user subroutines may need to be written to external files at the end of a converged increment for postprocessing. Such operations can be performed with user subroutine UEXTERNALDB (UEXTERNALDB, Section 25.2.21). This user interface can potentially be used to exchange data with another code, allowing for “stagger” between ABAQUS/Standard and another code.

Writing a user subroutine

User subroutines should be written with great care. To ensure their successful implementation, the rules and guidelines below should be followed.

Required INCLUDE statement

Every ABAQUS/Standard user subroutine must include the statement

include 'aba_param.inc'
as the first statement after the argument list.

Every ABAQUS/Explicit user subroutine must include the statement

include 'vaba_param.inc'
as the first statement after the argument list.

The files aba_param.inc and vaba_param.inc 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.

Naming convention

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.

Redefining variables

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

Compilation and linking problems

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 the ABAQUS Installation and Licensing Guide. 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 may lead to platform-dependent linking or runtime errors.

Testing and debugging

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 status (.sta) file using FORTRAN unit 6; these units should not be opened by the user's 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 may interfere with ABAQUS file operations; see FORTRAN unit numbers used by ABAQUS, Section 3.7.1. These FORTRAN units must be opened by the user; and because of the use of scratch directories, the full pathname for the file must be used in the OPEN statement.

Terminating an analysis

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, Section 26.2.9).

Models defined in terms of an assembly of part instances

An ABAQUS model can be defined in terms of an assembly of part instances (see Defining an assembly, Section 2.6.1).

Reference coordinate system

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 local coordinate system defined by the *ORIENTATION or *TRANSFORM option. The local coordinate system originally may 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 *ORIENTATION or *TRANSFORM definition was created relative to the assembly (global) coordinate system. This new *ORIENTATION or *TRANSFORM definition is the one used for local orientations in user subroutines.

Node and element numbers

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, Section 26.2.4). 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

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

Solution-dependent state variables

Solution-dependent state variables are values that can be defined to evolve with the solution of an analysis.

Defining and updating

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

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 may also be needed in the constitutive routines and can vary with time; field variables are discussed in detail in Predefined fields, Section 19.6.1.

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

Allocating space

Space must be allocated for each of the solution-dependent state variables at every applicable integration point or contact slave node. For most subroutines the number of such variables required at the points or nodes is entered as the only value on the data line of the *DEPVAR option, which should be included as part of the *MATERIAL definition for every material in which solution-dependent state variables are to be considered. For subroutines that do not use the material behavior defined with the *MATERIAL option, the *DEPVAR option is not used. For subroutines UEL and UGENS the number of variables is defined with the VARIABLES parameter on the *USER ELEMENT and *SHELL GENERAL SECTION options, respectively. For subroutines FRIC or VFRIC and UINTER or VUINTER the number of variables is defined with the DEPVAR parameter on the *FRICTION and the *SURFACE INTERACTION, USER options, respectively.

Usage: For most subroutines:

*DEPVAR

For subroutine UEL:

*USER ELEMENT, VARIABLES=number of variables

For subroutine UGENS:

*SHELL GENERAL SECTION, USER, VARIABLES=number of variables

For subroutines FRIC and VFRIC:

*FRICTION, USER, DEPVAR=number of variables

For subroutines UINTER and VUINTER:

*SURFACE INTERACTION, USER, DEPVAR=number of variables

Defining initial values

The initial values of solution-dependent state variable fields can be defined in a tabular format for elements and/or element sets by including the TYPE=SOLUTION parameter on the *INITIAL CONDITIONS option. See Initial conditions, Section 19.2.1, for additional details.

Usage: *INITIAL CONDITIONS, TYPE=SOLUTION

For complicated cases in ABAQUS/Standard user subroutine SDVINI can be called by adding the USER parameter to the option so that dependencies on coordinates, element numbers, etc. can be used in the definition of the variable field. See SDVINI, Section 25.2.16, for additional details.

Usage: *INITIAL CONDITIONS, TYPE=SOLUTION, USER

The initial values of solution-dependent state variables for contact in ABAQUS/Explicit are assigned as zero internally.

Output

User-defined, solution-dependent state variables can be written to the data file (.dat), the output database file (.odb), and the results file (.fil); the output identifiers SDV and SDVn are available as element integration variables (see ABAQUS/Standard output variable identifiers, Section 4.2.1, and ABAQUS/Explicit output variable identifiers, Section 4.2.2). These variables are not available for user subroutines VFRIC and VUINTER.

Alphanumeric parameters

Alphanumeric parameters, such as labels (names) of surfaces or materials, are always passed into user subroutines in the upper case. As a result, direct comparison of these labels with corresponding lower case characters will fail. Upper case must be used for all such comparisons. An example of such a comparison can be found in UMAT, Section 25.2.30. It illustrates the code setup inside user subroutine UMAT when more than one user-defined material model needs to be defined. The variable CMNAME is compared against MAT1 and MAT2 (even in situations where the material names may have been defined, using *MATERIAL, as mat1 and mat2, respectively.)

Precision in ABAQUS/Explicit

ABAQUS/Explicit is installed on all 32-bit floating point word systems with both single precision and double precision executables and on 64-bit floating point word systems as a single precision executable. By default, ABAQUS/Explicit is run in the native precision of the machine. To use the double precision executable on 32-bit machines, the double option must be specified on the command line (see Execution procedure for ABAQUS/Standard and ABAQUS/Explicit, Section 3.2.2). All variables in the user subroutines that start with the letters a to h and o to z will automatically be defined in the precision of the executable that is run by the user. The precision of the executable is defined in the file vaba_param.inc, and it is not necessary to define the precision of the variables explicitly.

Vectorization in ABAQUS/Explicit

ABAQUS/Explicit user subroutines are written with a vector interface, which means that blocks of data are passed to the user subroutines. For example, the vectorized user material routine (VUMAT) is passed stresses, strains, state variables, etc. for nblock material points. One of the parameters defined by vaba_param.inc is maxblk, the maximum block size. If the user subroutine requires the dimensioning of temporary arrays, they can be dimensioned by maxblk.

Parallelization in ABAQUS/Explicit

User subroutines can be used when running ABAQUS/Explicit in parallel. However, the use of common block statements in the user subroutines or in subroutines called by the user subroutines must be avoided since it will result in unpredictable behavior of the executable.

User subroutine calls

Most of the user subroutines available in ABAQUS are called at least once for each increment during an analysis step. However, as discussed below, many subroutines are called more or less often.

Subroutines that define material, element, or interface behavior

Most user subroutines that are used to define material, element, or interface behavior are called twice per material point, element, or slave 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 slave surface node in each succeeding iteration within the increment.

In transient implicit dynamic analyses (Implicit dynamic analysis using direct integration, Section 6.3.2) for which half-step residual tolerances are being checked (by means of the *DYNAMIC, HAFTOL=haftol option), it is necessary that these user subroutines be called one extra time for each material point, element, or slave surface node at the end of each increment. If the NOHAF parameter appears on the *DYNAMIC option, the half-step residual calculations are not performed and the extra call to the user subroutines will not be made.

User subroutines UHARD and UHYPEL, as well as user subroutine UHYPER when used in plane stress analyses, are called more often.

Subroutines that define initial conditions or orientations

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.

Subroutines that define predefined fields

User subroutines that are used to define predefined fields are called prior to the first iteration of the relevant step's first increment.

Verification of subroutine calls

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 may not be passed into the user subroutine; however, if printed output is sent from the subroutine to the message (.msg) file (Output, Section 4.1.1), 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.