5.4. ABAQUS Materials

This chapter describes input for ABAQUS material models, or so-called VUMAT and UMAT materials. The VUMAT specification is for explicit material models/analyses, whereas UMAT materials are typlically used for implicit analyses as they provide a material stiffness.

USER SUBROUTINE FILE = <string>sub_file_name

BEGIN MATERIAL <string>mat_name
  DENSITY = <real>density_value
  BEGIN PARAMETERS FOR MODEL ABAQUS_VUMAT | ABAQUS_UMAT
    #
    # Elastic constants
    #
    YOUNGS MODULUS = <real>
    POISSONS RATIO = <real>
    SHEAR MODULUS  = <real>
    BULK MODULUS   = <real>
    LAMBDA         = <real>
    #
    # Required parameters
    #
    VUMAT SUBROUTINE | UMAT SUBROUTINE = <string>sub_name
    PROPERTIES       = <real list>props
    DEPVAR           = <int>num_state
    #
    # Optional parameters
    #
    COORDINATE SYSTEM = <string>coordinate_system_name
  END
END

The ABAQUS_VUMAT and ABAQUS_UMAT models in Sierra/SM provides an interface for most user-defined material subroutines which conform to the Abaqus VUMAT or UMAT standards. The VUMAT interface currently supports both shell and solid elements, whereas the UMAT interface currently only supports solid elements.

The following commands are available.

Although the material response is defined solely by the user subroutine, at least two elastic constants must still be provided. The elastic constants are used in computation of hourglass stiffness, contact stiffness, solver preconditioners, and other capabilities that require a measure of approximate material stiffness. See Section 5.1.5 for more information on elastic constants input.
The name of the VUMAT/UMAT subroutine is specified by the VUMAT SUBROUTINE and UMAT SUBROUTINE command lines, respectively.

The USER SUBROUTINE FILE should contain the source code for the material subroutine. User subroutines are built into Sierra/SM using the sierra --make option. Consult Section 10 and/or Section 11 for more information on building and running user subroutines.

Warning

The subroutine name sub_name must not be VUMAT or vumat. Simularly, it must not be named UMAT or umat. Instead, choose a unique name.

The user may supply a list of material properties for the ABAQUS_VUMAT model associated with material mat_name using the PROPERTIES command line. The order of the property list will be the same as the order of the PROPS array in the material subroutine.
The DEPVAR command line specifies the number of state variables that should be allocated for the VUMAT/UMAT material.
Users may also specify a material coordinate system for the VUMAT. In order to use a material coordinate system, the user must specify a coordinate system using the COORDINATE SYSTEM command line in the VUMAT command block. Consult Section 5.1.7 for additional guidance on defining coordinate systems.

If a custom coordinate system is specified, STRESSOLD, STRAININC, DEFGRADOLD, and DEFGRADNEW will be rotated into the material frame before entering the VUMAT subroutine. Output stress STRESSNEW should be computed in the material coordinate frame, since it will automatically be rotated into the global Cartesian coordinate frame upon leaving the material subroutine.

In addition to specifying a coordinate system, the user may input up to three ordered rotation axis-Euler angle pairs for additional rotation. Axis-angle pairs may be prescribed on an element-by-element basis using an INITIAL CONDITION command block to set VUMAT state variables ANGLE_1, AXIS_1, ANGLE_2, AXIS_2, and ANGLE_3, AXIS_3. Angles are specified in degrees, while axes are denoted \((1, 2, 3)\), representing \((X, Y, Z)\), respectively. These variables may be, e.g., read from a file or expressed as a user function. Use of INITIAL CONDITION command blocks is described in the chapter on Boundary Conditions and Initial Conditions, see Section 7.3.

Built-in state variables pertaining to material coordinate system rotations are listed in Table Table 5.37.

The VUMAT/UMAT state variables are available for output as ABQ_STATE_ \(j\), where \(j\) is a one-based index \(1 \le j \le\) DEPVAR. Consult Section 9 for additional details on output of variables.

Input and output VUMAT subroutine arguments are listed in Tables Table 5.35 and Table 5.36. Arguments which are not currently fully supported in the VUMAT interface are indicated with an !.

Table 5.35 VUMAT Input Arguments
Argument Name	Description (Value)
`JBLOCK`	Number of elements in workset (always one, since the VUMAT currently processes one element at a time)
`NDIR`	Number of stress components (three for both solids and shells)
`NSHR`	Number of shear components (three for solids or one for shells)
`NSTATEV`	Number of state variables (input `num_state`)
`NFIELD` !	Number of user-defined field variables (zero)
`NPROPS`	Length of property array (length of input `props`)
`LANNEAL` !	Annealing process flag (zero)
`STEPTIME`	Current analysis time
`TOTALTIME`	Current analysis time (identical to `STEPTIME`)
`DT`	Current time step size
`CMNAME` !	Material name (empty string)
`COORDMP` !	Material point coordinates (zero)
`CHARLENGTH`	Element characteristic size (cube root of solid volume or square root of shell area)
`PROPS`	User-defined property array (input `props`)
`DENSITY` !	Current material point density (zero)
`STRAININC`	Strain increment over the current time step
`RELSPININC` !	Incremental relative rotation at each material point (zero)
`TEMPOLD`	Temperature at start of time step
`STRETCHOLD` !	Stretch at start of time step (identity tensor)
`DEFGRADOLD`	Deformation gradient (calculated for solids; unsupported for shells and set to identity tensor)
`FIELDOLD` !	User-defined field variable values at start of time step (zero)
`STRESSOLD`	Material stress at start of time step
`STATEOLD`	Material state variables at start of time step
`ENERINTERNOLD` !	Internal energy per unit mass at start of time step (zero)
`ENERINELASOLD` !	Dissipated inelastic energy per unit mass at start of time step (zero)
`TEMPNEW`	Temperature at end of time step
`STRETCHNEW` !	Stretch tensor at end of time step (identity tensor)
`DEFGRADNEW`	Deformation gradient (calculated for solids; unsupported for shells and set to identity tensor)
`FIELDNEW` !	User-defined field variable values at end of time step (zero)

Table 5.36 VUMAT Output Arguments
Argument Name	Description
`STRESSNEW`	Updated material stress at end of step
`STATENEW`	Updated material state variables at end of step
`ENERINTERNNEW` !	Updated internal energy per unit mass at start of time step (ignored)
`ENERINELASNEW` !	Updated dissipated inelastic energy per unit mass at end of time step (ignored)

Table 5.37 Built-In State Variables for ABAQUS_VUMAT Model (Section 5.4)
Index	Name	Variable Description
`num_state` + 1	`Q_XX`	X component of the material 11 unit vector
`num_state` + 2	`Q_YY`	Y component of the material 22 unit vector
`num_state` + 3	`Q_ZZ`	Z component of the material 33 unit vector
`num_state` + 4	`Q_XY`	Y component of the material 11 unit vector
`num_state` + 5	`Q_YZ`	Z component of the material 22 unit vector
`num_state` + 6	`Q_ZX`	X component of the material 33 unit vector
`num_state` + 7	`Q_YX`	X component of the material 22 unit vector
`num_state` + 8	`Q_ZY`	Y component of the material 33 unit vector
`num_state` + 9	`Q_XZ`	Z component of the material 11 unit vector
`num_state` + 10	`ANGLE_1`	Rotation angle about axis 1 (degrees)
`num_state` + 11	`ANGLE_2`	Rotation angle about axis 2 (degrees)
`num_state` + 12	`ANGLE_3`	Rotation angle about axis 3 (degrees)
`num_state` + 13	`AXIS_1`	First axis of rotation
`num_state` + 14	`AXIS_2`	Second axis of rotation
`num_state` + 15	`AXIS_3`	Third axis of rotation

Arguments to the UMAT interface are described in Table 5.38. For more details of the expected behavior of the UMAT interface, see the Abaqus User’s Guide.

Warning

The UMAT capability is relatively new in SIERRA/SM. Please report all issues/inconsistencies in using this capability to sierra-help@sandia.gov.

Table 5.38 UMAT Arguments
Argument Name	Description
`STRESS`	(in/out) Material stress at start of step
`STATEV`	(in/out) Material state variables at start of step
`DDSDDE`	(out) Jacobiian of the constitutive model \(\partial\Delta\sigma/ \partial\Delta\epsilon\)
`SSE`	(in/out) specific elastic strain energy
`SPD`	(in/out) specific plastic dissipation
`SCD`	(in/out) specific creep dissipation
`RPL`	unsupported
`DDSDDT`	(len=``NTENS``) unsupported
`DRPLDE`	(len=``NTENS``) unsupported
`DRPLDT`	unsupported
`STRAN`	total mechanical strain at the beginning of the increment (rotated to approximate logarithmic strain)
`DSTRAN`	mechanical strain increments
`TIME`	(len=2) (1) value of step time at beginning of increment, (2) value of tatal time at beginning of increment
`DTIME`	time increment
`TEMP`	temperature at beginning of step
`DTEMP`	increment of temperature
`PREDEF`	Array of interpolated valies of predefined field variables at material point at the start of the increment (unused?)
`DPRED`	Array of increments of `PREDEF`
`CMNAME`	User-defined material name, left-justified (unused)
`NDI`	Number of direct stress components (3)
`NSHR`	Number of enigneering shear stress components (3)
`NTENS`	Size of the stress or strain component array (6)
`NSTATV`	Number of dependant state variables, (`DEPVAR` in input command)
`PROPS`	Array of property values
`NPROPS`	Number of properties, (`PROPERTIES` in input command)
`COORDS`	Current coordinates at material point
`DROT`	Increment of rotation
`PNEWDT`	Suggested time step scale factor, can be used to cut implicit time step
`CELENT`	Characteristic element length
`DFGRD0`	Deformation gradient at the beginning of the increment
`DFGRD1`	Deformation gradient at the end of increment
`NOEL`	Element id
`NPT`	Integration point id
`LAYER`	Layer id for composite/layered materials (unused)
`KSPT`	Section point number within the current layer (unused)
`KSTEP`	Step number
`KINC`	Increment number

5.4.1. Other Guidelines for VUMAT Use

The shell VUMAT is currently only supported for plane stress conditions. The out-of-plane stress, STRESSNEW(i,3), is explicitly set to zero upon return. The VUMAT can alter the plane strain increment STRAININC(i,3) accordingly to satisfy plane stress.

When implementing a VUMAT, it is important to note that all internal variables are initialized to zero, so constitutive routines must be designed accordingly. For example, in the presence of a damage-type variable, it is recommended to adopt the convention that an undamaged state has damage \(d = 0.0\), while a damaged state has damage \(d > 0.0\). Because there is currently no way to detect the beginning of a simulation from within the VUMAT interface, there is no reliable way to use the standard VUMAT initialization.

As noted in Tables Table 5.35 and Table 5.36, internal work and plastic dissipation may not be specified or accessed within the current VUMAT interface. External work and kinetic energy are computed outside of the material subroutine by LAMÉ and can be accessed via a USER OUTPUT block in the Sierra/SM input file (consult Section 9 for details). To store dissipated plastic energy, an additional internal state variable may be defined and updated within the VUMAT.