AbaqusSubroutineDev/docs/AbaqusUserSubroutineManual/AbaqusUserSubroutineManual_062.md

order 11, 22, 33, 12, 13, 23 for symmetric tensors, followed by 21, 31, 32 for unsymmetric tensors (deformation gradient). Thus, the stresses for a plane stress element are returned as ARRAY(1)=S11, ARRAY(2)=S22, ARRAY(3)=0.0, and ARRAY(4)=S12. Three values are always returned for principal value requests, the minimum value first and maximum value third, regardless of the dimensionality of the analysis.

The description of the output variable (see “Abaqus/Standard output variable identifiers,” Section 4.2.1 of the Abaqus Analysis User’s Guide) determines which components are retrieved with GETVRM.

Analysis time for which values are returned

When a material point quantity is requested with utility routine GETVRM, the time in the increment at which the values are returned will depend upon which user subroutine calls it. GETVRM returns values at the end of the current increment to user subroutine UVARM, whereas it returns values at the beginning of the current increment to user subroutine USDFLD.

Equilibrium state for values returned

User subroutine UVARM may call GETVRM multiple times for each increment, as Abaqus/Standard iterates to a converged solution. Values returned from GETVRM calls preceding the final iteration for the increment will not represent the converged solution.

Example

To illustrate the use of GETVRM, if the identifier PEQC is specified for use with a jointed material, ARRAY will be returned with the individual equivalent plastic strain components PEQC1, PEQC2, PEQC3, and PEQC4. Since there are no integer output variables associated with this identifier, JARRAY will be returned with default values of 0. The FLGRAY array will contain either YES or NO flags indicating whether each component is actively yielding. If the identifier PE is specified for a material with plasticity, ARRAY will be returned with plastic strain components PE11, PE22, PE33, PE12, PE13, PE23, the equivalent plastic strain PEEQ, and the plastic strain magnitude PEMAG. Since there are no integer values associated with this request, JARRAY will be 0. The FLGRAY array will have N/A for the first six components, either YES or NO in the seventh component (corresponding to PEEQ) indicating whether the material is currently yielding, and N/A in the eighth component. If the identifier HFL is specified, ARRAY will be returned with the magnitude HFLM and the components HFL1, HFL2, and HFL3 as described in “Abaqus/Standard output variable identifiers,” Section 4.2.1 of the Abaqus Analysis User’s Guide.

Accessing state-dependent variables

If GETVRM is used to access state-dependent variables (output variable key SDV) and more than 15 state-dependent variables have been defined in the analysis, the dimension statement for ARRAY and JARRAY must be changed so that these arrays are dimensioned to the maximum number of state-dependent variables.

Unsupported element types, procedures and output variable keys

Since this capability pertains to material point quantities, it cannot be used for most of the element types that do not require a material definition. The following element types are, therefore, not supported:

• DASHPOTx
• SPRINGx
• CONNxDx
• FRAMExD
• JOINTC
• JOINTxD
• DRAGxD
• PSIxx
• ITSxxx
• MASS
• ROTARYI
• all acoustic elements
• all contact elements
• all hydrostatic fluid elements

If used with user subroutine UVARM, this capability is not available for linear perturbation procedures (“General and linear perturbation procedures,” Section 6.1.3 of the Abaqus Analysis User’s Guide):

• static linear perturbation analysis (“Defining an analysis,” Section 6.1.2 of the Abaqus Analysis User’s Guide),
• “Eigenvalue buckling prediction,” Section 6.2.3 of the Abaqus Analysis User’s Guide,
• “Natural frequency extraction,” Section 6.3.5 of the Abaqus Analysis User’s Guide,
• “Transient modal dynamic analysis,” Section 6.3.7 of the Abaqus Analysis User’s Guide,
• “Mode-based steady-state dynamic analysis,” Section 6.3.8 of the Abaqus Analysis User’s Guide,
• “Direct-solution steady-state dynamic analysis,” Section 6.3.4 of the Abaqus Analysis User’s Guide,
• “Subspace-based steady-state dynamic analysis,” Section 6.3.9 of the Abaqus Analysis User’s Guide,
• “Response spectrum analysis,” Section 6.3.10 of the Abaqus Analysis User’s Guide, and
• “Random response analysis,” Section 6.3.11 of the Abaqus Analysis User’s Guide.

The following output variable keys are not available for use with GETVRM:

• SVOL
• TSHR
• CTSHR
• COORD

2.1.7 OBTAINING MATERIAL POINT INFORMATION IN AN Abaqus/Explicit ANALYSIS

Product: Abaqus/Explicit

References

• “VUSDFLD,” Section 1.2.24
• “Damage and failure of a laminated composite plate,” Section 1.1.14 of the Abaqus Example Problems Guide

Overview

Utility routine VGETVRM can be called from VUSDFLD to access selected output variables at the material points for the current block of elements being processed by VUSDFLD.

Interface

include 'vaba_param.inc'
parameter( nrData=6 )
character*3 cData(maxblk*nrData)
dimension rData(maxblk*nrData), jData(maxblk*nrData)
...
call vgetvrm('VAR', rData, jData, cData, jStatus ) 

Variable to be provided to the utility routine

VAR

Output variable key. The available material point variables are given in “Available output variable keys,” below.

Variables returned from the utility routine

rData

Real array containing individual components of the output variable.

jData

Integer array containing individual components of the output variable.

cData

Character array containing flags corresponding to the individual components. Flags will either be YES, NO, or N/A (not applicable).

jStatus

Return code (0: output request successful; 1: output request not available).

Available output variable keys

The following output variable keys are currently supported:

• S: All stress components.
• LE: All logarithmic strain components.
• THE: All thermal strain components.
• PE: All plastic strain components.
• PEEQ: Equivalent plastic strain.
• PEEQT: Equivalent plastic strain in uniaxial tension, defined as \int \dot { \bar { \varepsilon } } _ { t } ^ { p l } d t
• PEQC: All equivalent plastic strains for models that have more than one yield/failure surface.
• ALPHA: All total kinematic hardening shift tensor components.
• TEMP: Temperature.
• EVF: Volume fraction (Eulerian elements only).

A requested output variable must be valid for the material model for the request to be successful.

The returned arrays rData, jData, and cData correspond to the real-valued variable, integervalued variable, and string variable, respectively, that can be associated with the request output variable key VAR. If any output variable component is not applicable for a given request, its value will be returned as the initialized value: 0.0 in rData, 0 in jData, and N/A in cData. Currently the association of the integer-valued variable and the string variable with the request output variable is not supported. The error flag jStatus is returned with a value of 1 if a request key is not recognized, not valid, or not supported; otherwise, jStatus is returned with a value of 0.

Component ordering in symmetric tensors

For symmetric tensors such as the stress and strain tensors, there are ndir+nshr components, where ndir and nshr are the number of direct and shear components, respectively, that are passed into user subroutine VUSDFLD. 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	$\sigma_{11}$	$\sigma_{11}$
2	$\sigma_{22}$	$\sigma_{22}$
3	$\sigma_{33}$	$\sigma_{33}$
4	$\sigma_{12}$	$\sigma_{12}$

Component	2D Case	3D Case
5		$\sigma_{23}$
6		$\sigma_{31}$

The shear strain components returned from utility subroutine VGETVRM are tensor components and not engineering components.

Analysis time for which values are returned

Utility subroutine VGETVRM returns values of the requested variable that correspond to the beginning of the current increment.

Example

To illustrate the use of VGETVRM, if the identifier PE is specified for a material with plasticity, rData will be returned with plastic strain components PE11, PE22, PE33, PE12, PE23, and PE13. jData will be 0 and cData array will have N/A for all components.

Unsupported element types, procedures, and output variable keys

Since this capability pertains to material point quantities, it cannot be used for most of the element types that do not require a material definition. The following element types are, therefore, not supported:

• DASHPOTx
• SPRINGx
• CONNxDx
• MASS
• ROTARYI
• all acoustic elements

2.1.8 OBTAINING MATERIAL POINT INFORMATION AVERAGED AT A NODE

Product: Abaqus/Standard

References

• “UMESHMOTION,” Section 1.1.46
• “Erosion of material (sand production) in an oil wellbore,” Section 1.1.22 of the Abaqus Example Problems Guide

Overview

Utility routine GETVRMAVGATNODE can be called from user subroutine UMESHMOTION to access material integration point information averaged at a node.

The results variables available from GETVRMAVGATNODE are nearly the same as those available from GETVRM; the exceptions follow from the restriction that, since it will average results, GETVRMAVGATNODE will operate only on real-valued results. Results values represented as integers or as flags are not available.

Interface

DIMENSION ARRAY(15), JELEMLIST(NELEMS)
...
CALL GETVRMAVGATNODE(NODE, JTYP, 'VAR', ARRAY, JRCD, JELEMLIST, NELEMS, JMATYP, JGVBLOCK) 

Variables to be provided to the utility routine

NODE

Node number.

JTYP

An integer flag indicating how the material point information is averaged. Set JTYP=0 to extrapolate results, using element shape functions, and to average results at the node. Set JTYP=1 to perform a volume-weighted average of results.

VAR

Output variable key from the table in “Abaqus/Standard output variable identifiers,” Section 4.2.1 of the Abaqus Analysis User’s Guide. The applicable keys are listed in the output table as being available for results file output at the element integration points; e.g., S for stress. One exception is the integration point coordinates variable COORD, which cannot be passed into the utility routine; you should use utility routine GETVRN instead to obtain nodal coordinates.

JELEMLIST

Array of element numbers for elements connected to NODE for which you want material point quantities considered in the average result. Results from each element in the list that contain the node will be extrapolated to that node and averaged. JELEMLIST can be obtained from utility routine GETNODETOELEMCONN.

NELEMS

Length of JELEMLIST.

JGVBLOCK

Variable that must be passed into the GETVRMAVGATNODE utility routine. This variable is available in user subroutine UMESHMOTION for this purpose.

JMATYP

Variable that must be passed into the GETVRMAVGATNODE utility routine. This variable is available in user subroutine UMESHMOTION for this purpose.

Variables returned from the utility routine

ARRAY

Real array containing individual components of the output variable.

JRCD

Return code (0 – no error, 1 – output request error or all components of output request are zero).

Available output variable keys

Only output variable keys that are valid for results file output are available for use with GETVRMAVGATNODE. In general, if a key corresponds to a collective output variable, rather than an individual component, it can be used with GETVRMAVGATNODE. For example, S for the stress tensor can be used, whereas any individual component of stress, say S11, cannot be used. The collective output variable keys are distinguished from their individual components by the fact that they have a bullet ( ) in the .fil column in the tables in “Abaqus/Standard output variable identifiers,” Section 4.2.1 of the Abaqus Analysis User’s Guide. Output variable keys that cannot be used with GETVRMAVGATNODE are listed later in this section.

You will be returned ARRAY with components associated with the request VAR. If any array component is not applicable for a given request, its value will be returned as the initialized value: 0.0 in ARRAY. The error flag JRCD=1 is returned from GETVRMAVGATNODE any time a request key is not recognized, the request is not valid, or all of the output components requested are zero; otherwise, JRCD=0.

Ordering of returned components

The components for a request are written as follows. Single index components (and requests without components) are returned in positions 1, 2, 3, etc. Double index components are returned in the order 11, 22, 33, 12, 13, 23 for symmetric tensors, followed by 21, 31, 32 for unsymmetric tensors (deformation gradient). Thus, the stresses for a plane stress element are returned as ARRAY(1)=S11, ARRAY(2)=S22, ARRAY(3)=0.0, and ARRAY(4)=S12. Three values are always returned for principal value requests, the minimum value first and the maximum value third, regardless of the dimensionality of the analysis.

The description of the output variable (see “Abaqus/Standard output variable identifiers,” Section 4.2.1 of the Abaqus Analysis User’s Guide) determines which components are retrieved with GETVRMAVGATNODE.

Analysis time for which values are returned

GETVRMAVGATNODE returns values at the end of the current increment to user subroutine UMESHMOTION.

Accessing state-dependent variables

If GETVRMAVGATNODE is used to access solution-dependent state variables (output variable key SDV) and more than 15 solution-dependent state variables have been defined in the analysis, the dimension statement for ARRAY must be changed so that these arrays are dimensioned to the maximum number of solution-dependent state variables.

Unsupported element types and output variable keys

Since this capability pertains to material point quantities, it cannot be used for most of the element types that do not require a material definition. The following element types are, therefore, not supported:

• DASHPOTx
• SPRINGx
• CONNxDx
• FRAMExD
• JOINTC
• JOINTxD
• DRAGxD
• PSIxx
• ITSxxx
• MASS
• ROTARYI

• all acoustic elements
• all hydrostatic fluid elements

The following output variable keys are not available for use with GETVRMAVGATNODE:

• SVOL
• TSHR
• CTSHR

Example: Obtaining plastic strain results

To illustrate the use of GETVRMAVGATNODE, consider a case where the identifier PE is specified and JELEMLIST lists four three-dimensional elements, two of which have plastic yield behavior defined and two of which do not. ARRAY will be returned with the individual plastic strain components PE11, PE22, PE33, PE12, PE13, and PE23; the equivalent plastic strain PEEQ; and the plastic strain magnitude PEMAG. The result returned in ARRAY will be an average reflecting extrapolations of plastic strain results to NODE from only the two elements that have plastic yield behavior defined.

Example: Obtaining contact results

A second illustration is relevant to the modeling of wear with UMESHMOTION. Consider a case where JELEMLIST is obtained from GETNODETOELEMCONN and where the identifier CSTRESS is specified. If NODE is associated with a contact pair slave surface, JELEMLIST will contain the internal element identifier for the contact element associated with the slave node pairing. ARRAY will be returned with the individual contact stress components CPRESS, CSHEAR1, and CSHEAR2. Similarly, if CDISP is specified, ARRAY will be returned with the individual contact stress components CDISP, CSLIP1, and CSLIP2.