VUSDFLD

User subroutine to redefine field variables at a material point.

User subroutine VUSDFLD:

allows the redefinition of field variables at a material point as functions of time or of any of the available material point quantities listed in Available Output Variable Keys;
can be used to introduce solution-dependent material properties since such properties can be easily defined as functions of field variables;
is called at all material points of elements for which the material definition includes user-defined field variables;
can call utility routine VGETVRM to access material point data; and
can use and update solution-dependent state variables.

This page discusses:

Explicit Solution Dependence
Defining Field Variables
State Variables
Accessing Material Point Data
Component Ordering in Symmetric Tensors
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 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. However, in most situations this is not a concern for explicit dynamic analysis because the stable time increment is usually sufficiently small to ensure good accuracy.

Defining Field Variables

Before user subroutine VUSDFLD 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 or predefined field variables or the values defined in user subroutine VUFIELD. 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.)

State Variables

Since the redefinition of field variables in VUSDFLD 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 VUSDFLD and then passed into other user subroutines that can be called at this material point, such as those listed above. The number of such state variables can be specified as shown in the example at the end of this section (see Allocating Space for Solution-Dependent State Variables).

Accessing Material Point Data

The values of the material point quantities at the start of the increment can be accessed through the utility routine VGETVRM described in Obtaining Material Point Information in an Abaqus/Explicit Analysis. The values of the material point quantities are obtained by calling VGETVRM with the appropriate output variable keys.

Component Ordering in Symmetric Tensors

For symmetric tensors such as the stress and strain tensors there are ndir+nshr components, and the component order is given as a natural permutation of the indices of the tensor. The direct components are first and then the indirect components, beginning with the 12-component. For example, a stress tensor contains ndir direct stress components and nshr shear stress components, which are returned as:


Component	2D Case	3D Case
1	$σ_{11}$	$σ_{11}$
2	$σ_{22}$	$σ_{22}$
3	$σ_{33}$	$σ_{33}$
4	$σ_{12}$	$σ_{12}$
5		$σ_{23}$
6		$σ_{31}$

The shear strain components in user subroutine VUSDFLD are stored as tensor components and not as engineering components; unlike user subroutine USDFLD in Abaqus/Standard, which uses engineering components.

User Subroutine Interface

      subroutine vusdfld(
c Read only variables -
     1   nblock, nstatev, nfieldv, nprops, ndir, nshr, 
     2   jElem, kIntPt, kLayer, kSecPt, 
     3   stepTime, totalTime, dt, cmname, 
     4   coordMp, direct, T, charLength, props, 
     5   stateOld, 
c Write only variables -
     6   stateNew, field )
c
      include 'vaba_param.inc'
c
      dimension jElem(nblock), coordMp(nblock,*), 
     1          direct(nblock,3,3), T(nblock,3,3), 
     2          charLength(nblock), props(nprops), 
     3          stateOld(nblock,nstatev), 
     4          stateNew(nblock,nstatev),
     5          field(nblock,nfieldv)
      character*80 cmname
c
c     Local arrays from vgetvrm are dimensioned to 
c     maximum block size (maxblk)
c
      parameter( nrData=6 )
      character*3 cData(maxblk*nrData)
      dimension rData(maxblk*nrData), jData(maxblk*nrData)
c
      do 100 k = 1, nblock

         user coding to define field(nblock,nfieldv)
         and, if necessary, stateNew(nblock,nstatev)

  100 continue
c
      return
      end

Variables to Be Defined

field(nblock,nfieldv): An array containing the field variables at the material points. 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 VUFIELD. 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 that are called at the material points.

Variables That Can Be Updated

stateNew(nblock,nstatev): An array containing the solution-dependent state variables at the material points. In all cases stateNew can be updated in this subroutine, and the updated values are passed into other user subroutines that are called at the material points. The number of state variables associated with this material point is defined as described in Allocating Space for Solution-Dependent State Variables.

Variables Passed in for Information

nblock: Number of material points to be processed in this call to VUSDFLD.
nstatev: Number of user-defined state variables that are associated with this material type (you define this as described in Allocating Space for Solution-Dependent State Variables).
nfieldv: Number of user-defined external field variables.
nprops: User-specified number of user-defined material properties.
ndir: Number of direct components in a symmetric tensor.
nshr: Number of indirect components in a symmetric tensor.
jElem: Array of element numbers.
kIntPt: Integration point number.
kLayer: Layer number (for composite shells).
kSecPt: Section point number within the current layer.
stepTime: Value of time since the step began.
totalTime: Value of total time. The time at the beginning of the step is given by totalTime-stepTime.
dt: Time increment size.
cmname: User-specified material name, left justified. It is passed in as an uppercase character string. Some internal material models are given names starting with the “ABQ_” character string. To avoid conflict, you should not use “ABQ_” as the leading string for cmname.
coordMp(nblock,*): Material point coordinates. It is the midplane material point for shell elements and the centroid for beam elements.
direct(nblock,3,3): An array containing the direction cosines of the material directions in terms of the global basis directions. For material point k, direct(k,1,1), direct(k,2,1), direct(k,3,1) give the (1, 2, 3) components of the first material direction; direct(k,1,2), direct(k,2,2), direct(k,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(nblock,3,3): An array containing the direction cosines of the material orientation components relative to the element basis directions. For material point k, 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(k,1,1) $ = \cos θ$ , T(k,1,2) $ = - \sin θ$ , T(k,2,1) $ = \sin θ$ , T(k,2,2) $ = \cos θ$ , T(k,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.
charLength(nblock): Characteristic element length, which is either the default value based on the geometric mean or the user-defined characteristic element length defined in user subroutine VUCHARLENGTH. The default value 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 the default value 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. For cohesive elements it is equal to the constitutive thickness.
props(nprops): User-supplied material properties.
stateOld (nblock, nstatev): State variables at each material point at the beginning of the increment.

Example: Damaged Elasticity Model

Included below is an example of user subroutine VUSDFLD. 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).

Input file

HEADING
 Damaged elasticity model with user subroutine vusdfld
ELEMENT, TYPE=T2D2, ELSET=ONE
1, 1, 2
NODE, NSET=NALL
   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
DENSITY
1.0e-6
USER DEFINED FIELD
DEPVAR
1
1,EPSMAX,"Maximum strain value"
BOUNDARY
1, 1, 2
2, 2
AMPLITUDE, NAME=LOAD1
0.0, 0.0, 1.0, 1.0
AMPLITUDE, NAME=LOAD2
0.0, 0.0, 2.0, 1.0
AMPLITUDE, NAME=UNLOAD
0.0, 1.0, 1.0, 0.0
STEP, NLGEOM=NO
DYNAMIC, EXPLICIT
 , 1.0
CLOAD, AMPLITUDE=LOAD1
2, 1, 20.
OUTPUT, FIELD, VARIABLE=PRESELECT
OUTPUT, HISTORY, VARIABLE=PRESELECT
ELEMENT OUTPUT, ELSET=ONE
S, E, SDV
NODE OUTPUT, NSET=NALL
RF, CF, U
END STEP
STEP, NLGEOM=NO
DYNAMIC, EXPLICIT
, 1.0
CLOAD, AMPLITUDE=UNLOAD
2, 1, 20.
END STEP
STEP, NLGEOM=NO
DYNAMIC, EXPLICIT
 , 2.0
CLOAD, AMPLITUDE=LOAD2
2, 1, 40.
END STEP

User subroutine

      subroutine vusdfld(
c Read only -
     *   nblock, nstatev, nfieldv, nprops, ndir, nshr, 
     *   jElem, kIntPt, kLayer, kSecPt, 
     *   stepTime, totalTime, dt, cmname, 
     *   coordMp, direct, T, charLength, props, 
     *   stateOld, 
c Write only -
     *   stateNew, field )
c
      include 'vaba_param.inc'
c
      dimension jElem(nblock), coordMp(nblock,*), 
     *          direct(nblock,3,3), T(nblock,3,3), 
     *          charLength(nblock), props(nprops), 
     *          stateOld(nblock,nstatev), 
     *          stateNew(nblock,nstatev),
     *          field(nblock,nfieldv)
      character*80 cmname
c
c     Local arrays from vgetvrm are dimensioned to 
c     maximum block size (maxblk)
c
      parameter( nrData=6 )
      character*3 cData(maxblk*nrData)
      dimension rData(maxblk*nrData), jData(maxblk*nrData)
c
      jStatus = 1
      call vgetvrm( 'LE', rData, jData, cData, jStatus )
c
      if( jStatus .ne. 0 ) then
         call xplb_abqerr(-2,'Utility routine VGETVRM '//
     *      'failed to get variable.',0,zero,' ')
         call xplb_exit
      end if
c
      call setField( nblock, nstatev, nfieldv, nrData, 
     *   rData, stateOld, stateNew, field)
c
      return
      end
      subroutine setField( nblock, nstatev, nfieldv, nrData, 
     *   strain, stateOld, stateNew, field )
c
      include 'vaba_param.inc'
c
      dimension stateOld(nblock,nstatev), 
     *   stateNew(nblock,nstatev),
     *   field(nblock,nfieldv), strain(nblock,nrData)
c
      do k = 1, nblock
c
c     Absolute value of current strain:
         eps = abs( strain(k,1) )
c
c     Maximum value of strain up to this point in time:
         epsmax = stateOld(k,1)
c
c     Use the maximum strain as a field variable
         field(k,1) = max( eps, epsmax )
c
c     Store the maximum strain as a solution dependent state 
         stateNew(k,1) = field(k,1)
c
      end do
c
      return
     
end