Obtaining material point information in an Abaqus/Standard analysis

Utility routine GETVRM can be called from either user subroutine UVARM, UDMGINI, or USDFLD to access material integration point information.

The following topics are discussed:

Utility routine interface
Variables to be provided to the utility routine
Variables returned from the utility routine
Available output variable keys
Ordering of returned components
Analysis time for which values are returned
Equilibrium state for values returned
Example
Accessing state-dependent variables
Unsupported element types, procedures and output variable keys

Utility routine interface

DIMENSION ARRAY(15), JARRAY(15)
CHARACTER*3 FLGRAY(15)
...
CALL GETVRM('VAR',ARRAY,JARRAY,FLGRAY,JRCD,JMAC,JMATYP,MATLAYO,
LACCFLA)

Variables to be provided to the utility routine

VAR: Output variable key from the table in Element integration point variables. 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.
JMAC: Variable that must be passed into the GETVRM utility routine. The calling user subroutine provides this variable.
JMATYP: Variable that must be passed into the GETVRM utility routine. The calling user subroutine provides this variable.
MATLAYO: Variable that must be passed into the GETVRM utility routine. The calling user subroutine provides this variable.
LACCFLA: Variable that must be passed into the GETVRM utility routine. The calling user subroutine provides this variable.

Variables returned from the utility routine

ARRAY: Real array containing individual components of the output variable.
JARRAY: Integer array containing individual components of the output variable.
FLGRAY: Character array containing flags corresponding to the individual components. Flags will contain either YES, NO, or N/A (not applicable).
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 GETVRM. In general, if a key corresponds to a collective output variable, rather than an individual component, it can be used with GETVRM. 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 the word "yes" after the category .fil in the tables in Abaqus/Standard output variable identifiers. Output variable keys that cannot be used with GETVRM are listed later in this section.

You will be returned ARRAY, JARRAY, and FLGRAY, which correspond to the real-valued components, integer-valued components, and the flags associated with the request VAR, respectively. If any array component is not applicable for a given request, its value will be returned as the initialized value: 0.0 in ARRAY, 0 in JARRAY, and N/A in FLGRAY. The error flag JRCD=1 is returned from GETVRM any time a request key is not recognized, the request is not valid (such as requesting transverse shear stress for a shell element that uses thin shell theory), 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 maximum value third, regardless of the dimensionality of the analysis.

The description of the output variable (see Abaqus/Standard output variable identifiers) 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.

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 perturbation procedures):

static linear perturbation analysis (Defining an analysis),
Eigenvalue buckling prediction,
Natural frequency extraction,
Transient modal dynamic analysis,
Mode-based steady-state dynamic analysis,
Direct-solution steady-state dynamic analysis,
Subspace-based steady-state dynamic analysis,
Response spectrum analysis, and
Random response analysis.

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

SVOL
TSHR
CTSHR
COORD