You can include one or more user subroutines in a model by specifying the name of a C, C++,
or Fortran source or precompiled object file that contains the subroutines. Details are
provided in Abaqus/Standard and Abaqus/Explicit Execution.
Job module: job editor: General: User subroutine file
Managing External Databases in Abaqus and Exchanging Information with Other Software
In Abaqus it is sometimes desirable to set up the runtime environment and manage interactions with
external data files or parallel processes that are used in conjunction with user
subroutines. For example, there might 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 might 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 in Abaqus/Standard and VEXTERNALDB in Abaqus/Explicit. This user interface can potentially be used to exchange data with another code, allowing
for “stagger” between Abaqus 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. For a detailed discussion
of the individual subroutines, including coding interfaces and requirements, refer to the
Abaqus User Subroutines Guide.
Required INCLUDEs
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.
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.
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,
and the arguments must be passed and received by reference.
Redefining Variables
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.
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 System customization parameters. 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.
Memory Allocation Considerations
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).
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 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.
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).
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 Assembly Definition).
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 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.
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). 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 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.
Allocating Space for Solution-Dependent State 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.
Input File Usage
For most subroutines the number of such variables required at the points or nodes is
entered as the only value on the first 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 most subroutines the number of such variables required at the points or nodes is
entered as part of the material definition for every material in which
solution-dependent state variables are to be considered:
Property module: material editor: GeneralDepvar: Number of solution-dependent state variables
Defining Initial Values
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.
Defining Initial Values Directly
You can define the initial values in a tabular format for elements and/or element sets.
See Initial Conditions for additional
details.
Defining Initial Values in a User Subroutine in Abaqus/Standard
For complicated cases in Abaqus/Standard you can call user subroutine SDVINI so that dependencies on
coordinates, element numbers, etc. can be used in the definition of the variable field.
Element Deletion Controlled by Solution-Dependent State Variables
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.
Element solution-dependent variables are values that can be defined at each applicable
element to evolve with the solution of an Abaqus/Standard analysis. Element solution-dependent variables are different from solution-dependent
state variables, which are defined at each applicable integration point or node.
Defining and Updating
Any number of element solution-dependent variables can be used in the following user
subroutines:
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.
Allocating Space for Element Solution-Dependent Variables
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.
Input File Usage
Use the following options to allocate space for element solution-dependent variables
in shell elements:
Defining element solution-dependent variables is not supported in Abaqus/CAE.
Defining Initial Values
You can define the initial values of element solution-dependent variables in a tabular
format for elements and/or element sets. See Initial Conditions for additional
details.
Defining initial values of element solution-dependent variables is not supported in
Abaqus/CAE.
Element Deletion Controlled by Element Solution-Dependent Variables
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.
Defining element deletion controlled by element solution-dependent variables is not
supported in Abaqus/CAE.
Output
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).
Alphanumeric Data
Alphanumeric data, 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. 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 might have been defined as
mat1 and mat2, respectively.)
Precision in Abaqus/Explicit
Abaqus/Explicit is installed with both single precision and double precision executables. To use the
double precision executable, you must specify double precision when you run the analysis
(see Abaqus/Standard and Abaqus/Explicit Execution). 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 you run. The precision of the executable is
defined in the vaba_param.inc file, 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 routines (VFABRIC and VUMAT) are 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
User subroutines can be used when running jobs in parallel. In thread-parallel mode access
to common blocks, common files, and other shared resources need to be guarded against race
conditions. Special utility routines are provided for that purpose. For details, see Ensuring Thread Safety. An environment
variable ABA_PARALLEL_DEBUG can be set to increase verbosity and help
troubleshoot problems should they arise in parallel runs.
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 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.
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 for all iterations of all increments
whenever the current field variable is needed.
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 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.
Utility Routines
A variety of utility routines are available to assist in the coding of user subroutines.
You include the utility routine inside a user subroutine. When called, the utility routine
will perform a predefined function or action whose output or results can be integrated into
the user subroutine. Some utility routines are only applicable to particular user
subroutines. Each utility routine is discussed in detail in
General Utility Routines. For information
about the utility routines that are available for use with the toolpath-mesh intersection
module, see Toolpath-Mesh Intersection Utility Routines.
Variables Provided for Use in Utility Routines
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
getElMPtVar
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.