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 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 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 may 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 may result in
stack overflow errors and an abort 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 may
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 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 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 may 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 may 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 may 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 may
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
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.