11/15/2017 1.1.

49 USDFLD

1.1.49 USDFLD
User subroutine to redefine field variables at a material point.

Product: Abaqus/Standard

References

Obtaining material point information in an Abaqus/Standard analysis, Section 2.1.6

Material data definition, Section 21.1.2 of the Abaqus Analysis User's Manual

*USER DEFINED FIELD

Damage and failure of a laminated composite plate, Section 1.1.14 of the Abaqus Example Problems
Manual

USDFLD, Section 4.1.24 of the Abaqus Verification Manual

User subroutine USDFLD:

allows you to define field variables at a material point as functions of time or of any of the available
material point quantities listed in the Output Variable Identifiers table (Abaqus/Standard output variable
identifiers, Section 4.2.1 of the Abaqus Analysis User's Manual) except the user-defined output variables
UVARM and UVARMn;

can be used to introduce solution-dependent material properties since such properties can easily be defined
as functions of field variables;

will be called at all material points of elements for which the material definition includes user-defined field
variables;

must call utility routine GETVRM to access material point data;

can use and update state variables; and

can be used in conjunction with user subroutine UFIELD to prescribe predefined field variables.

Explicit solution dependence

Since this routine provides access to material point quantities only at the start of the increment, the solution
dependence introduced in this way is explicit: the material properties for a given increment are not influenced by
the results obtained during the increment. Hence, the accuracy of the results depends on the size of the time
increment. Therefore, you can control the time increment in this routine by means of the variable PNEWDT.

Defining field variables

Before user subroutine USDFLD is called, the values of the field variables at the material point are calculated by
interpolation from the values defined at the nodes. Any changes to the field variables in the user subroutine are
local to the material point: the nodal field variables retain the values defined as initial conditions, predefined field
variables, or in user subroutine UFIELD. The values of the field variables defined in this routine are used to
calculate values of material properties that are defined to depend on field variables and are passed into other user
subroutines that are called at the material point, such as the following:

CREEP
http://abaqus.software.polimi.it/v6.12/books/sub/default.htm 1/7
11/15/2017 1.1.49 USDFLD

HETVAL

UEXPAN

UHARD

UHYPEL

UMAT

UMATHT

UTRS

Output of the user-defined field variables at the material points can be obtained with the element integration point
output variable FV (see Abaqus/Standard output variable identifiers, Section 4.2.1 of the Abaqus Analysis
User's Manual).

Accessing material point data

You are provided with access to the values of the material point quantities at the start of the increment (or in the
base state in a linear perturbation step) through the utility routine GETVRM described in Obtaining material point
information in an Abaqus/Standard analysis, Section 2.1.6. The values of the material point quantities are
obtained by calling GETVRM with the appropriate output variable keys. The values of the material point data are
recovered in the arrays ARRAY, JARRAY, and FLGRAY for floating point, integer, and character data, respectively.
You may not get values of some material point quantities that have not been defined at the start of the increment;
e.g., ER.

State variables

Since the redefinition of field variables in USDFLD is local to the current increment (field variables are restored to
the values interpolated from the nodal values at the start of each increment), any history dependence required to
update material properties by using this subroutine must be introduced with user-defined state variables.

The state variables can be updated in USDFLD and then passed into other user subroutines that can be called at this
material point, such as those listed above. You specify the number of such state variables, as shown in the example
at the end of this section (see also Allocating space in User subroutines: overview, Section 18.1.1 of the
Abaqus Analysis User's Manual).
User subroutine interface

SUBROUTINE USDFLD(FIELD,STATEV,PNEWDT,DIRECT,T,CELENT,
1 TIME,DTIME,CMNAME,ORNAME,NFIELD,NSTATV,NOEL,NPT,LAYER,
2 KSPT,KSTEP,KINC,NDI,NSHR,COORD,JMAC,JMATYP,MATLAYO,LACCFLA)
C
INCLUDE 'ABA_PARAM.INC'
C
CHARACTER*80 CMNAME,ORNAME
CHARACTER*3 FLGRAY(15)
DIMENSION FIELD(NFIELD),STATEV(NSTATV),DIRECT(3,3),
1 T(3,3),TIME(2)
DIMENSION ARRAY(15),JARRAY(15),JMAC(*),JMATYP(*),COORD(*)

http://abaqus.software.polimi.it/v6.12/books/sub/default.htm 2/7
11/15/2017 1.1.49 USDFLD

user coding to define FIELD and, if necessary, STATEV and PNEWDT

RETURN
END
Variable to be defined

FIELD(NFIELD)

An array containing the field variables at the current material point. These are passed in with the values
interpolated from the nodes at the end of the current increment, as specified with initial condition definitions,
predefined field variable definitions, or user subroutine UFIELD. The interpolation is performed using the
same scheme used to interpolate temperatures: an average value is used for linear elements; an approximate
linear variation is used for quadratic elements (also see Solid (continuum) elements, Section 28.1.1 of the
Abaqus Analysis User's Manual). The updated values are used to calculate the values of material properties
that are defined to depend on field variables and are passed into other user subroutines (CREEP, HETVAL,
UEXPAN, UHARD, UHYPEL, UMAT, UMATHT, and UTRS) that are called at this material point.
Variables that can be updated

STATEV(NSTATV)

An array containing the solution-dependent state variables. These are passed in as the values at the beginning
of the increment. In all cases STATEV can be updated in this subroutine, and the updated values are passed
into other user subroutines (CREEP, HETVAL, UEXPAN, UMAT, UMATHT, and UTRS) that are called at this
material point. The number of state variables associated with this material point is defined as described in
Allocating space in User subroutines: overview, Section 18.1.1 of the Abaqus Analysis User's Manual.

PNEWDT

Ratio of suggested new time increment to the time increment 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).

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

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.

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

DIRECT(3,3)

http://abaqus.software.polimi.it/v6.12/books/sub/default.htm 3/7
11/15/2017 1.1.49 USDFLD

An array containing the direction cosines of the material directions in terms of the global basis directions.
DIRECT(1,1), DIRECT(2,1), DIRECT(3,1) give the (1, 2, 3) components of the first material direction;
DIRECT(1,2), DIRECT(2,2), DIRECT(3,2) give the second material direction, etc. For shell and
membrane elements, the first two directions are in the plane of the element and the third direction is the
normal. This information is not available for beam elements.

T(3,3)

An array containing the direction cosines of the material orientation components relative to the element basis
directions. This is the orientation that defines the material directions (DIRECT) in terms of the element basis
directions. For continuum elements T and DIRECT are identical. For shell and membrane elements T(1,1)
, T(1,2) , T(2,1) , T(2,2) , T(3,3) , and all other components
are zero, where is the counterclockwise rotation around the normal vector that defines the orientation. If no
orientation is used, T is an identity matrix. Orientation is not available for beam elements.

CELENT

Characteristic element length. This 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 plane only.

TIME(1)

Value of step time at the beginning of the current increment.

TIME(2)

Value of total time at the beginning of the current increment.

DTIME

Time increment.

CMNAME

User-specified material name, left justified.

ORNAME

User-specified local orientation name, left justified.

NFIELD

Number of field variables defined at this material point.

NSTATV

User-defined number of solution-dependent state variables (see Allocating space in User subroutines:
overview, Section 18.1.1 of the Abaqus Analysis User's Manual).

NOEL

Element number.

http://abaqus.software.polimi.it/v6.12/books/sub/default.htm 4/7
11/15/2017 1.1.49 USDFLD

NPT

Integration point number.

LAYER

Layer number (for composite shells and layered solids).

KSPT

Section point number within the current layer.

KSTEP

Step number.

KINC

Increment number.

NDI

Number of direct stress components at this point.

NSHR

Number of shear stress components at this point.

COORD

Coordinates at this material point.

JMAC

Variable that must be passed into the GETVRM utility routine to access an output variable.

JMATYP

Variable that must be passed into the GETVRM utility routine to access an output variable.

MATLAYO

Variable that must be passed into the GETVRM utility routine to access an output variable.

LACCFLA

Variable that must be passed into the GETVRM utility routine to access an output variable.

Example: Damaged elasticity model

Included below is an example of user subroutine USDFLD. In this example a truss element is loaded in tension. A
damaged elasticity model is introduced: the modulus decreases as a function of the maximum tensile strain that
occurred during the loading history. The maximum tensile strain is stored as a solution-dependent state variable
see Defining solution-dependent field variables in Predefined fields, Section 33.6.1 of the Abaqus Analysis
User's Manual.

http://abaqus.software.polimi.it/v6.12/books/sub/default.htm 5/7
11/15/2017 1.1.49 USDFLD

Input file

*HEADING
DAMAGED ELASTICITY MODEL WITH USER SUBROUTINE USDFLD
*ELEMENT, TYPE=T2D2, ELSET=ONE
1, 1, 2
*NODE
1, 0., 0.
2, 10., 0.
*SOLID SECTION, ELSET=ONE, MATERIAL=ELASTIC
1.
*MATERIAL, NAME=ELASTIC
*ELASTIC, DEPENDENCIES=1
** Table of modulus values decreasing as a function
** of field variable 1.
2000., 0.3, 0., 0.00
1500., 0.3, 0., 0.01
1200., 0.3, 0., 0.02
1000., 0.3, 0., 0.04
*USER DEFINED FIELD
*DEPVAR
1
*BOUNDARY
1, 1, 2
2, 2
*STEP
*STATIC
0.1, 1.0, 0.0, 0.1
*CLOAD
2, 1, 20.
*END STEP
*STEP
*STATIC
0.1, 1.0, 0.0, 0.1
*CLOAD
2, 1, 0.
*END STEP
*STEP, INC=20
*STATIC
0.1, 2.0, 0.0, 0.1
*CLOAD
2, 1, 40.
*END STEP

User subroutine

SUBROUTINE USDFLD(FIELD,STATEV,PNEWDT,DIRECT,T,CELENT,
1 TIME,DTIME,CMNAME,ORNAME,NFIELD,NSTATV,NOEL,NPT,LAYER,
2 KSPT,KSTEP,KINC,NDI,NSHR,COORD,JMAC,JMATYP,MATLAYO,
3 LACCFLA)
C
INCLUDE 'ABA_PARAM.INC'
http://abaqus.software.polimi.it/v6.12/books/sub/default.htm 6/7
11/15/2017 1.1.49 USDFLD

C
CHARACTER*80 CMNAME,ORNAME
CHARACTER*3 FLGRAY(15)
DIMENSION FIELD(NFIELD),STATEV(NSTATV),DIRECT(3,3),
1 T(3,3),TIME(2)
DIMENSION ARRAY(15),JARRAY(15),JMAC(*),JMATYP(*),
1 COORD(*)
C
C Absolute value of current strain:
CALL GETVRM('E',ARRAY,JARRAY,FLGRAY,JRCD,JMAC,JMATYP,
MATLAYO,LACCFLA)
EPS = ABS( ARRAY(1) )
C Maximum value of strain up to this point in time:
CALL GETVRM('SDV',ARRAY,JARRAY,FLGRAY,JRCD,JMAC,JMATYP,
MATLAYO,LACCFLA)
EPSMAX = ARRAY(1)
C Use the maximum strain as a field variable
FIELD(1) = MAX( EPS , EPSMAX )
C Store the maximum strain as a solution dependent state
C variable
STATEV(1) = FIELD(1)
C If error, write comment to .DAT file:
IF(JRCD.NE.0)THEN
WRITE(6,*) 'REQUEST ERROR IN USDFLD FOR ELEMENT NUMBER ',
1 NOEL,'INTEGRATION POINT NUMBER ',NPT
ENDIF
C
RETURN
END

http://abaqus.software.polimi.it/v6.12/books/sub/default.htm 7/7