.. _materials-vumat:

*****
VUMAT
*****

.. code-block:: sierrainput

   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 :numref:`materials-elasticConstants` 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 :numref:`subroutines` 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 :numref:`materials-coordSys` 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 :math:`(1, 2, 3)`, representing :math:`(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 :numref:`conditions-variable`.

  Built-in state variables pertaining to material coordinate system rotations are listed in Table :numref:`output-tab-vumat`.

The VUMAT state variables are available for output as ABQ_STATE\_:math:`j`, where :math:`j` is a one-based index :math:`1 \le j \le` ``DEPVAR``. Consule :numref:`output` for additional details on output of variables.

Input and output subroutine arguments are listed in Tables :numref:`tab-vumaterials-input` and :numref:`tab-vumaterials-output`. Arguments which are not currently fully supported in the VUMAT interface are indicated with a **!**.

.. _tab-vumaterials-input:

.. csv-table:: VUMAT Input Arguments
   :align: center
   :delim: &
   :header: Argument Name, Description (Value)
   :widths: auto

   ``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)

.. _tab-vumaterials-output:

.. csv-table:: VUMAT Output Arguments
   :align: center
   :delim: &
   :header: Argument Name, Description
   :widths: auto

   ``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)

.. _output-tab-vumat:

.. csv-table:: Built-In State Variables for ABAQUS_VUMAT Model (:numref:`materials-vumat`)
   :align: center
   :delim: &
   :header: Index, Name, Variable Description
   :widths: auto

   ``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

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 :math:`d = 0.0`, while a damaged state has damage :math:`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 :numref:`tab-vumaterials-input` and :numref:`tab-vumaterials-output`, 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 :numref:`output` for details). To store dissipated plastic energy, an additional internal state variable may be defined and updated within the VUMAT.
