Product: ABAQUS/Standard
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) 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.
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.
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:
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,” Section 26.2.5. 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.
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 25.1.1).
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(*)
user coding to define FIELD and, if necessary, STATEV and PNEWDT
RETURN
ENDFIELD(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 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, UHYPEL, UMAT, UMATHT, and UTRS) that are called at this material point.
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 25.1.1.
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.
DIRECT(3,3)
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.
NOEL
Element number.
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 using the utility routine.
JMATYP
Variable that must be passed into the GETVRM utility routine to access an output variable using the utility routine.
MATLAYO
Variable that must be passed into the GETVRM utility routine to access an output variable using the utility routine.
LACCFLA
Variable that must be passed into the GETVRM utility routine to access an output variable using the utility routine.
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 19.6.1.
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'
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