5.4. VUMAT

USER SUBROUTINE FILE = <string>sub_file_name

BEGIN MATERIAL <string>mat_name
  DENSITY = <real>density_value
  BEGIN PARAMETERS FOR MODEL ABAQUS_VUMAT
    #
    # Elastic constants
    #
    YOUNGS MODULUS = <real>
    POISSONS RATIO = <real>
    SHEAR MODULUS  = <real>
    BULK MODULUS   = <real>
    LAMBDA         = <real>
    #
    # Required parameters
    #
    VUMAT 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 model in Sierra/SM provides an interface for mos user-defined material subroutines which conform to the Abaqus VUMAT standard The VUMAT interface currently supports both shell and 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 subroutine is specified by the VUMAT SUBROUTINE command line. 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 for more information on building and running user subroutines.

Warning

The subroutine name sub_name must not be VUMAT or vumat. 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 which should be allocated for the VUMAT 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 state variables are available for output as ABQ_STATE_:math:j, where \(j\) is a one-based index \(1 \le j \le\) DEPVAR. Consule Section 9 for additional details on output of variables.

Input and output 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 a !.

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

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.