USDFLD

User subroutine to redefine field variables at a material point.

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 (Using Abaqus/Standard Output Variable Identifiers) 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.

This page discusses:

Explicit Solution Dependence
Defining Field Variables
Accessing Material Point Data
State Variables
User Subroutine Interface
Variables to Be Defined
Variables That Can Be Updated
Variables Passed in for Information
Example: Damaged Elasticity Model

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:

Output of the user-defined field variables at the material points can be obtained with the element integration point output variable FV (see Element Integration Point Variables).

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. 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 for Solution-Dependent State Variables).

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(*)


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


      RETURN
      END

Variables 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). 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 for Solution-Dependent State Variables.

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): 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) $ = \cos θ$ , T(1,2) $ = - \sin θ$ , T(2,1) $ = \sin θ$ , T(2,2) $ = \cos θ$ , T(3,3) $ = 1.0$ , 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 $(r, z)$ 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 for Solution-Dependent State Variables).
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.
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.

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