Product: Abaqus/Explicit
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” in “Obtaining material point information in an Abaqus/Explicit analysis,” Section 2.1.7;
can be used to introduce solution-dependent material properties since such properties can be easily 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;
can call utility routine VGETVRM to access material point data; and
can use and update solution-dependent state variables.
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.
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 “Abaqus/Explicit output variable identifiers,” Section 4.2.2 of the Abaqus Analysis User's Guide).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” in “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User's Guide).
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,” Section 2.1.7. The values of the material point quantities are obtained by calling VGETVRM with the appropriate output variable keys.
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:
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.
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
endfield(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.
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” in “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User's Guide.
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” in “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User's Guide).
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) 
, T(k,1,2) 
, T(k,2,1) 
, T(k,2,2) 
, T(k,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.
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.
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” in “Predefined fields,” Section 34.6.1 of the Abaqus Analysis User's Guide).
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