<!-- source-page: 551 -->

# 1.2.23 VUMULLINS: User subroutine to define damage variable for the Mullins effect material model.

Product: Abaqus/Explicit

# References

• “Mullins effect,” Section 22.6.1 of the Abaqus Analysis User’s Guide   
• “Energy dissipation in elastomeric foams,” Section 22.6.2 of the Abaqus Analysis User’s Guide   
• \*MULLINS EFFECT   
• “Mullins effect and permanent set,” Section 2.2.3 of the Abaqus Verification Guide

# Overview

# User subroutine VUMULLINS:

• can be used to define the damage variable for the Mullins effect material model (“Mullins effect,” Section 22.6.1 of the Abaqus Analysis User’s Guide), including the use of the Mullins effect approach to model energy dissipation in elastomeric foams (“Energy dissipation in elastomeric foams,” Section 22.6.2 of the Abaqus Analysis User’s Guide);   
• will be called for blocks of material calculation points for which the material definition contains a user-defined Mullins effect;   
• can be used to define a failure criterion based on the strain energy density of the material;   
• can use and update solution-dependent state variables;   
• can use any field variables that are passed in; and   
• should be used when you do not want to use the Ogden and Roxburgh form of the damage variable, , that is used by Abaqus/Explicit.

# Material point deletion

Material points that satisfy a user-defined failure criterion can be deleted from the model (see “Userdefined mechanical material behavior,” Section 26.7.1 of the Abaqus Analysis User’s Guide). You must specify the state variable number controlling the element deletion flag when you allocate space for the solution-dependent state variables, as explained in “User-defined mechanical material behavior,” Section 26.7.1 of the Abaqus Analysis User’s Guide. The deletion state variable can be set to a value of one or zero inside user subroutine VUMULLINS. A value of one indicates that the material point is active, and a value of zero indicates that Abaqus/Explicit should delete the material point from the model by setting the stresses to zero. The structure of the block of material points passed to user subroutine VUMULLINS remains unchanged during the analysis; deleted material points are not removed from the block. Abaqus/Explicit will “freeze” the values of the strain energy density passed to user subroutine VUMULLINS for all deleted material points; that is, the values remain constant after deletion is triggered. Once a material point has been flagged as deleted, it cannot be reactivated.

<!-- source-page: 552 -->

```fortran
subroutine vumullins (
C Read only (unmodifiable) variables -
    1    nblock,
    2    jElem, kIntPt, kLayer, kSecPt,
    3    cmname,
    4    nstatev, nfieldv, nprops,
    5    props, tempOld, tempNew, fieldOld, fieldNew,
    6    stateOld, enerDamageOld,
    7    uMaxOld, uMaxNew, uDev,
C Write only (modifiable) variables -
    8    eta, detaDuDev,
    9    stateNew, enerDamageNew )
C
    include 'vaba_param.inc'
C
    dimension props(nprops),
    1    tempOld(nblock),
    2    fieldOld(nblock,nfieldv),
    3    stateOld(nblock,nstatev),
    4    tempNew(nblock),
    5    fieldNew(nblock,nfieldv),
    6    enerDamageOld(nblock),
    7    uMaxOld(nblock), uMaxNew(nblock),
    8    uDev(nblock),
    9    eta(nblock), detaDuDev(nblock),
    1    stateNew(nblock,nstatev),
    2    enerDamageNew(nblock)
C
    character*80 cmname
C
    do 100 km = 1,nblock
    user coding
100 continue
    return
    end 
```

<!-- source-page: 553 -->

# Variables to be defined

eta(nblock)

The damage variable, .

detaDuDev(nblock)

The derivative of the damage variable with respect to the deviatoric elastic strain energy density of the undamaged material, $d \eta / d \tilde { U } _ { d e v }$ , when the primary material behavior is hyperelastic. The derivative of the damage variable with respect to the total elastic strain energy density of the undamaged material, $d \eta / d { \tilde { U } }$ , when the primary material behavior is hyperfoam. This quantity is needed for the evaluation of the effective moduli of the material, which enters the stable time increment calculation.

# Variables that can be updated

stateNew(nblock,nstatev)

State variables at each material point at the end of the increment. You define the size of this array by allocating space for it (see “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User’s Guide, for more information).

enerDamageNew(nblock)

The energy dissipation density at the end of the increment. This quantity can be defined either in total form or in an incremental manner using the old value of the damage dissipation enerDamageOld and the increment in damage dissipation. This quantity is used for output purposes only.

# Variables passed in for information

nblock

Number of material points to be processed in this call to VUMULLINS.

jElem(nblock)

Array of element numbers.

kIntPt

Integration point number.

kLayer

Layer number (for composite shells).

kSecPt

Section point number within the current layer.

cmname

User-specified material name, left justified. It is passed in as an uppercase character string. Some internal material models are given names starting with the “ABQ\_” character string. To avoid conflict, you should not use “ABQ\_” as the leading string for cmname.

<!-- source-page: 554 -->

# nstatev

Number of user-defined state variables that are associated with this material type (you define the number as described in “Allocating space” in “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User’s Guide).

# nfieldv

Number of user-defined external field variables.

# nprops

User-specified number of user-defined material properties.

# props(nprops)

User-supplied material properties.

# tempOld(nblock)

Temperatures at each material point at the beginning of the increment.

# tempNew(nblock)

Temperatures at each material point at the end of the increment.

# fieldOld(nblock,nfieldv)

Values of the user-defined field variables at each material point at the beginning of the increment.

# fieldNew(nblock,nfieldv)

Values of the user-defined field variables at each material point at the end of the increment.

# stateOld(nblock,nstatev)

State variables at each material point at the beginning of the increment.

# enerDamageOld(nblock)

The value of energy dissipated at the beginning of the increment.

# uMaxOld(nblock)

The value, at the beginning of the increment, of the maximum primary strain energy density over its entire deformation history.

# uMaxNew(nblock)

The value, at the end of the increment, of the maximum primary strain energy density over its entire deformation history.

# uDev(nblock)

The value, at the end of the increment, of the deviatoric primary strain energy density, $\tilde { U } _ { d e v }$ , when the primary material behavior is hyperelastic. The value, at the end of the increment, of the total primary strain energy density, $\tilde { U }$ , when the primary material behavior is hyperfoam.

<!-- source-page: 555 -->

As a simple example of the coding of user subroutine VUMULLINS, consider the following damage model based on the softening hyperelasticity approach proposed by Volokh (2007). The damage variable is assumed to vary with the deformation according to

$$
\eta = \exp \left(\frac {- U _ {d e v} ^ {m}}{U _ {0}}\right),
$$

where $U _ { d e v } ^ { m }$ is the maximum value of $\tilde { U } _ { d e v }$ at a material point during its deformation history, $\tilde { U } _ { d e v }$ is the deviatoric part of the strain energy density of the undamaged hyperelastic behavior, and $U _ { 0 }$ is a material parameter with units of strain energy density. The energy dissipation function for this model takes the form

$$
\phi (\eta) = U _ {0} (1 - \eta + \eta \ln (\eta)).
$$

It can be shown that the functions and satisfy the following condition:

$$
\left(\tilde {U} _ {d e v} + \phi^ {\prime} (\eta)\right) \dot {\eta} = 0.
$$

The code in user subroutine VUMULLINS must return the damage variable, ; the derivative of the damage variable with respect to the elastic strain energy density of the undamaged material, $d \eta / d \tilde { U } _ { d e v }$ ; and the energy dissipation . The user subroutine would be coded as follows:
```fortran
subroutine vumullins (
C Read only (unmodifiable) variables -
    1    nblock,
    2    jElem, kIntPt, kLayer, kSecPt,
    3    cmname,
    4    nstatev, nfieldv, nprops,
    5    props, tempOld, tempNew, fieldOld, fieldNew,
    6    stateOld, enerDamageOld,
    7    uMaxOld, uMaxNew, uDev,
C Write only (modifiable) variables -
    8    eta, detaDuDev,
    9    stateNew, enerDamageNew )
C
    include 'vaba_param.inc'
C
    dimension props(nprops),
    1    tempOld(nblock),
    2    fieldOld(nblock, nfieldv),
    3    stateOld(nblock, nstatev), 
```

<!-- source-page: 556 -->

```txt
4 tempNew(nblock),
5 fieldNew(nblock,nfieldv),
6 enerDamageOld(nblock),
7 uMaxOld(nblock), uMaxNew(nblock),
8 uDev(nblock),
9 eta(nblock), detaDuDev(nblock),
1 stateNew(nblock,nstatev),
2 enerDamageNew(nblock)

C
    character*80 cmname

C
    parameter ( zero = 0.d0, one = 1.d0 )

C
    u0 = props(1)
    u0Inv = zero
    if ( u0 .gt. zero ) u0Inv = one / u0

C
    do k=1, nblock
    eta(k) = exp(-uMaxNew(k) * u0Inv)
    detaDUdev(k) = zero
    if ( uMaxNew(k) .gt. uMaxOld(k) )

1    detaDUdev(k) = -u0Inv * eta(k)
    enerDamageNew(k) = u0*(one-eta(k)+eta(k)*log(eta(k)))
    end do

C
    return
    end 
```

# Additional reference

• Volokh, K. Y., “Hyperelasticity with Softening for Modeling Materials Failure,” Journal of the Mechanics and Physics of Solids, vol. 55, pp. 2237–2264, 2007.

<!-- source-page: 557 -->

# 1.2.24 VUSDFLD: User subroutine to redefine field variables at a material point.

# Product: Abaqus/Explicit

# References

• “Obtaining material point information in an Abaqus/Standard analysis,” Section 2.1.6   
• “Material data definition,” Section 21.1.2 of the Abaqus Analysis User’s Guide   
• \*USER DEFINED FIELD   
• “Damage and failure of a laminated composite plate,” Section 1.1.14 of the Abaqus Example Problems Guide   
• “VUSDFLD,” Section 4.1.39 of the Abaqus Verification Guide

# Overview

User subroutine VUSDFLD:

• allows the redefinition of field variables at a material point as functions of time or of any of the available material point quantities listed in “Available output variable keys” in “Obtaining material point information in an Abaqus/Explicit analysis,” Section 2.1.7;   
• can be used to introduce solution-dependent material properties since such properties can be easily defined as functions of field variables;   
• will be called at all material points of elements for which the material definition includes userdefined field variables;   
• can call utility routine VGETVRM to access material point data; and   
• can use and update solution-dependent state variables.

# Explicit solution dependence

Since this routine provides access to material point quantities only at the start of the increment, the material properties for a given increment are not influenced by the results obtained during the increment. Hence, the accuracy of the results depends on the size of the time increment. However, in most situations this is not a concern for explicit dynamic analysis because the stable time increment is usually sufficiently small to ensure good accuracy.

# Defining field variables

Before user subroutine VUSDFLD is called, the values of the field variables at the material point are calculated by interpolation from the values defined at the nodes. Any changes to the field variables in the user subroutine are local to the material point: the nodal field variables retain the values defined as initial conditions or predefined field variables or the values defined in user subroutine VUFIELD. The values of the field variables defined in this routine are used to calculate values of material properties that

<!-- source-page: 558 -->

are defined to depend on field variables and are passed into other user subroutines that are called at the material point, such as the following:

• VUANISOHYPER\_INV   
• VUANISOHYPER\_STRAIN   
• VUHARD   
• VUMAT   
• VUTRS   
• VUVISCOSITY

Output of the user-defined field variables at the material points can be obtained with the element integration point output variable FV (see “Abaqus/Explicit output variable identifiers,” Section 4.2.2 of the Abaqus Analysis User’s Guide).

# State variables

Since the redefinition of field variables in VUSDFLD is local to the current increment (field variables are restored to the values interpolated from the nodal values at the start of each increment), any history dependence required to update material properties by using this subroutine must be introduced with userdefined state variables.

The state variables can be updated in VUSDFLD and then passed into other user subroutines that can be called at this material point, such as those listed above. The number of such state variables can be specified as shown in the example at the end of this section (see “Allocating space” in “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User’s Guide).

# Accessing material point data

The values of the material point quantities at the start of the increment can be accessed through the utility routine VGETVRM described in “Obtaining material point information in an Abaqus/Explicit analysis,” Section 2.1.7. The values of the material point quantities are obtained by calling VGETVRM with the appropriate output variable keys.

# Component ordering in symmetric tensors

For symmetric tensors such as the stress and strain tensors there are ndir+nshr components, and 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:

<table><tr><td>Component</td><td>2D Case</td><td>3D Case</td></tr><tr><td>1</td><td> $\sigma_{11}$ </td><td> $\sigma_{11}$ </td></tr><tr><td>2</td><td> $\sigma_{22}$ </td><td> $\sigma_{22}$ </td></tr><tr><td>3</td><td> $\sigma_{33}$ </td><td> $\sigma_{33}$ </td></tr></table>

<!-- source-page: 559 -->

<table><tr><td>Component</td><td>2D Case</td><td>3D Case</td></tr><tr><td>4</td><td> $\sigma_{12}$ </td><td> $\sigma_{12}$ </td></tr><tr><td>5</td><td></td><td> $\sigma_{23}$ </td></tr><tr><td>6</td><td></td><td> $\sigma_{31}$ </td></tr></table>

The shear strain components in user subroutine VUSDFLD are stored as tensor components and not as engineering components; unlike user subroutine USDFLD in Abaqus/Standard, which uses engineering components.

User subroutine interface   
```fortran
subroutine vusdfld(
c Read only variables -
    1 nblock, nstatev, nfieldv, nprops, ndir, nshr,
    2 jElem, kIntPt, kLayer, kSecPt,
    3 stepTime, totalTime, dt, cmname,
    4 coordMp, direct, T, charLength, props,
    5 stateOld,
c Write only variables -
    6 stateNew, field )
c
    include 'vaba_param.inc'
c
    dimension jElem(nblock), coordMp(nblock,*),
    1 direct(nblock,3,3), T(nblock,3,3),
    2 charLength(nblock), props(nprops),
    3 stateOld(nblock,nstatev),
    4 stateNew(nblock,nstatev),
    5 field(nblock,nfieldv)
    character*80 cmname
c
c Local arrays from vgetvm are dimensioned to
c maximum block size (maxblk)
c
    parameter( nrData=6 )
    character*3 cData(maxblk*nrData)
    dimension rData(maxblk*nrData), jData(maxblk*nrData)
c
    do 100 k = 1, nblock
    user coding to define field(nblock,nfieldv)
    and, if necessary, stateNew(nblock,nstatev) 
```

<!-- source-page: 560 -->

```lua
100 continue
c
return
end 
```

# Variable to be defined

# field(nblock,nfieldv)

An array containing the field variables at the material points. These are passed in with the values interpolated from the nodes at the end of the current increment, as specified with initial condition definitions, predefined field variable definitions, or user subroutine VUFIELD. The updated values are used to calculate the values of material properties that are defined to depend on field variables and are passed into other user subroutines that are called at the material points.

# Variable that can be updated

# stateNew(nblock,nstatev)

An array containing the solution-dependent state variables at the material points. In all cases stateNew can be updated in this subroutine, and the updated values are passed into other user subroutines that are called at the material points. The number of state variables associated with this material point is defined as described in “Allocating space” in “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User’s Guide.

# Variables passed in for information

# nblock

Number of material points to be processed in this call to VUSDFLD.

# nstatev

Number of user-defined state variables that are associated with this material type (you define this as described in “Allocating space” in “User subroutines: overview,” Section 18.1.1 of the Abaqus Analysis User’s Guide).

# nfieldv

Number of user-defined external field variables.

# nprops

User-specified number of user-defined material properties.

# ndir

Number of direct components in a symmetric tensor.

# nshr

Number of indirect components in a symmetric tensor.
