<!-- source-page: 521 -->

```julia
5 jSlvUid, jMstUid, jConMstid, timStep, timGlb,
6 dTimCur, surfInt, surfSlv, surfMst,
7 rdisp, drdisp, drot, stiffDflt, condDflt,
8 shape, coordSlv, coordMst, alocaldir, props,
9 areaSlv, tempSlv, dtempSlv, preDefSlv, dpreDefSlv,
1 tempMst, dtempMst, preDefMst, dpreDefMst)
C
    include `vaba_param.inc'
C
    character*80 surfInt, surfSlv, surfMst
C
    dimension props(nProps), statev(nStateVar,nSlvNod),
    1 drot(2,2,nSlvNod), sed(nSlvNod), sfd(nSlvNod),
    2 scd(nSlvNod), spd(nSlvNod), svd(nSlvNod),
    3 rdisp(nDir,nSlvNod), drdisp(nDir,nSlvNod),
    4 stress(nDir,nSlvNod), fluxSlv(nSlvNod),
    5 fluxMst(nSlvNod), areaSlv(nSlvNod),
    6 stiffDflt(nSlvNod), condDflt(nSlvNod),
    7 alocaldir(nDir,nDir,nSlvNod), shape(nFacNod,nSlvNod),
    8 coordSlv(nDir,nSlvNod), coordMst(nDir,nMstNod),
    9 jSlvUid(nSlvNod), jMstUid(nMstNod),
    1 jConMstid(nFacNod,nSlvNod), tempSlv(nSlvNod),
    2 dtempSlv(nSlvNod), preDefSlv(nPred,nSlvNod),
    3 dpreDefSlv(nPred,nSlvNod), tempMst(numDefTfv),
    4 dtempMst(numDefTfv), preDefMst(nPred,numDefTfv),
    5 dpreDefMst(nPred,numDefTfv)

    user coding to define stress,
    and, optionally, fluxSlv, fluxMst, statev, sed, sfd, scd, spd,
    and svd

    return
    end 
```

# Variable to be defined

stress(nDir, nSlvNod)

On entry this array contains the stress at the interface during the previous time increment. It must be updated to the stress at the interface in the current time increment.

<!-- source-page: 522 -->

# fluxSlv(nSlvNod)

On entry this array contains the flux entering the slave surface during the previous time increment. It must be updated to the flux entering the slave surface during the current increment.

# fluxMst(nSlvNod)

On entry this array contains the flux entering the master surface during the previous time increment. It must be updated to the flux entering the master surface during the current time increment.

# sfd(nSlvNod)

This array can be updated to contain the increment in frictional dissipation at each node (units of energy per unit area). These values contribute to the output variables SFDR and ALLFD and have no effect on other solution variables.

# scd(nSlvNod)

This array can be updated to contain the increment in creep dissipation at each node (units of energy per unit area). These values contribute to the output variables SFDR and ALLCD and have no effect on other solution variables.

# spd(nSlvNod)

This array can be updated to contain the increment in plastic dissipation at each node (units of energy per unit area). These values contribute to the output variables SFDR and ALLPD and have no effect on other solution variables.

# svd(nSlvNod)

This array can be updated to contain the increment in viscous dissipation at each node (units of energy per unit area). These values contribute to the output variables SFDR and ALLVD and have no effect on other solution variables.

# sed(nSlvNod)

On entry this array contains the elastic energy density at the slave nodes at the beginning of the increment. It can be updated to contain the elastic energy density at the end of the current time increment. These values contribute to the output variable ALLSE and have no effect on other solution variables.

# statev(nstateVar, nSlvNod)

This array contains the user-defined solution-dependent state variables for all the nodes on the slave surface. You define the size of this array (see “User-defined interfacial constitutive behavior,” Section 37.1.6 of the Abaqus Analysis User’s Guide, for more information). This array will be passed in containing the values of these variables prior to the call to user subroutine VUINTER. If any of the solution-dependent state variables is being used in conjunction with the surface interaction, it must be updated in this subroutine.

<!-- source-page: 523 -->

kStep

Step number.

kInc

Increment number.

nFacNod

Number of nodes on each master surface facet. nFacNod is 2 for two-dimensional surfaces, and nFacNod is 4 for three-dimensional surfaces (the first and last nodes are the same for triangular facets). If the master surface is an analytical rigid surface, this variable is passed in as 0.

nSlvNod

Number of slave nodes.

nMstNod

Number of master surface nodes, if the master surface is made up of facets. If the master surface is an analytical rigid surface, this variable is passed in as 0.

nSurfDir

Number of tangent directions at the contact points (nSurfDir = nDir - 1).

nDir

Number of coordinate directions at the contact points. (In a three-dimensional model nDir will be 2 if the surfaces in the contact pair are two-dimensional analytical rigid surfaces or are formed by two-dimensional elements.)

nStateVar

Number of user-defined state variables.

nProps

User-specified number of property values associated with this surface interaction model.

nTemp

1 if the temperature is defined and 0 if the temperature is not defined.

nPred

Number of predefined field variables.

numDefTfv

Equal to nSlvNod if the master surface is made up of facets. If the master surface is an analytical rigid surface, this variable is passed in as 1.

<!-- source-page: 524 -->

jSlvUid(nSlvNod)

This array lists the user-defined global node numbers (or internal node numbers for models defined in terms of an assembly of part instances) of the nodes on the slave surface.

jMstUid(nMstNod)

This array lists the user-defined global node numbers (or internal node numbers for models defined in terms of an assembly of part instances) of the nodes on the master surface. If the master surface is an analytical rigid surface, this array is passed in as a dummy array.

jConMstid(nFacNod, nSlvNod)

This array lists the surface node numbers of the master surface nodes that make up the facet onto which each slave node projects. If the master surface is an analytical rigid surface, this array is passed in as a dummy array.

timStep

Value of step time.

timGlb

Value of total time.

dtimCur

Current increment in time from $t = t _ { c u r r } - \Delta t { \mathrm { t } } 0 t = t _ { c u r r } .$

surfInt

User-specified surface interaction name, left justified.

surfSlv

Slave surface name.

surfMst

Master surface name.

rdisp(nDir, nSlvNod)

An array containing the relative positions between the two surfaces. The first component is the relative position of the slave node, with respect to the master surface, in the normal direction (a positive value indicates a penetration, and a negative value indicates a gap). The second and third components, if applicable, are the accumulated incremental relative tangential displacements of the slave node, measured from the beginning of the step in which the contact pair is defined. The local directions in which the relative displacements are defined are stored in alocaldir. If the master surface is an analytical surface, the elements in rdisp are set to r\_MaxVal for the slave nodes that are far from the master surface.

<!-- source-page: 525 -->

drdisp(nDir, nSlvNod)

An array containing the increments in relative positions between the two surfaces during the current time increment. If the master surface is an analytical surface, the elements in drdisp are set to r\_MaxVal for the slave nodes that are far from the master surface.

drot(2, 2, nSlvNod)

Rotation increment matrix. This matrix represents the incremental rotation of the local surface tangent directions for a three-dimensional surface. This rotation matrix for each slave node is defined as a unit matrix for two-dimensional surfaces. If the master surface is an analytical surface, the elements in drot are set to r\_MaxVal for the slave nodes that are far from the master surface.

stiffDflt(nSlvNod)

Values of the default penalty stiffnesses for each slave node (units of FL ).

condDflt(nSlvNod)

Values of the default penalty conductances for each slave node (units of $J \theta ^ { - 1 } \mathrm { T } ^ { - 1 } )$ .

shape(nFacNod, nSlvNod)

For each contact point this array contains the shape functions of the nodes of its master surface facet, evaluated at the location of the contact point. If the master surface is an analytical rigid surface, this array is passed in as a dummy array.

coordSlv(nDir, nSlvNod)

Array containing the nDir components of the current coordinates of the slave nodes.

coordMst(nDir, nMstNod)

Array containing the nDir components of the current coordinates of the master nodes. If the master surface is an analytical rigid surface, this array is passed in as the coordinates of the contact points on the master surface.

alocaldir(nDir, nDir, nSlvNod)

Direction cosines of the local surface coordinate system. The first array index corresponds to the components of the local directions, and the second array index corresponds to the local direction number. The first direction (alocaldir(1..nDir,1,...)) is the normal to the surface. The second direction (alocaldir(1..nDir,2,...)) is the first surface tangent. For a three-dimensional surface, the third direction (alocaldir(1..3,3,...)) is the second surface tangent. If the master surface is an analytical rigid surface, the numbers in alocaldir are valid only if the corresponding parts in rdisp are valid (i.e., not equal to r\_MaxVal).

props(nProps)

User-specified vector of property values to define the behavior between the contacting surfaces.

areaSlv(nSlvNod)

Area associated with the slave nodes (equal to 1 for node-based surface nodes).

<!-- source-page: 526 -->

tempSlv(nSlvNod)

Current temperature at the slave nodes.

dtempSlv(nSlvNod)

Increment in temperature during the previous time increment at the slave nodes.

preDefSlv(nPred, nSlvNod)

Current user-specified predefined field variables at the slave nodes (initial values at the beginning of the analysis and current values during the analysis).

dpreDefSlv(nPred, nSlvNod)

Increment in the predefined field variables at the slave nodes during the previous time increment.

tempMst(numDefTfv)

Current temperature at the nearest points on the master surface.

dtempMst(numDefTfv)

Increment in temperature during the previous time increment at the nearest points on the master surface.

preDefMst(nPred, numDefTfv)

Current user-specified predefined field variables at the nearest points on the master surface (initial values at the beginning of the analysis and current values during the analysis).

dpreDefMst(nPred, numDefTfv)

Increment in the predefined field variables during the previous time increment at the nearest points on the master surface.

<!-- source-page: 527 -->

# 1.2.21 VUINTERACTION: User subroutine to define the contact interaction between surfaces with the general contact algorithm.

Product: Abaqus/Explicit

# References

• “User-defined interfacial constitutive behavior,” Section 37.1.6 of the Abaqus Analysis User’s Guide   
• \*SURFACE INTERACTION   
• “VUINTERACTION,” Section 4.1.37 of the Abaqus Verification Guide

# Overview

User subroutine VUINTERACTION:

• can be used to define the mechanical and thermal interaction between contact surfaces;   
• must provide the entire definition of the interaction between the contact surfaces;   
• can utilize a user-specified tracking thickness to determine potential points of interaction on a surface (and thus which nodes should be passed into the subroutine);   
• can use and update solution-dependent state variables for node-to-face contact and node-toanalytical rigid surface contact; and   
• must be used with the general contact algorithm.

# Terminology

The use of user subroutine VUINTERACTION requires familiarity with the following terminology.

# Tracking thickness

For efficiency, user subroutine VUINTERACTION considers only regions of two surfaces that are likely to be in contact or come into contact in a given increment. This likelihood is defined by a tracking thickness: only portions of surfaces separated by less than the tracking thickness in a given increment are passed into the subroutine; portions of the surfaces with a separation larger than the tracking thickness are ignored for the current increment. Surface thicknesses are accounted for in the separation calculations.

Abaqus/Explicit provides an internal default value for the tracking thickness, but a nondefault value can be specified; see “Tracking thickness when VUINTER or VUINTERACTION is used” in “Userdefined interfacial constitutive behavior,” Section 37.1.6 of the Abaqus Analysis User’s Guide. The tracking thickness is passed into VUINTERACTION using the variable rData(4).

# Proximity points

A proximity point is a potential point of interaction for you to consider in user subroutine VUINTERACTION. Each proximity point is primarily associated with a slave node or a point along

<!-- source-page: 528 -->

a slave edge; the proximity point also references a corresponding, locally nearest point on the master surface within the tracking thickness. A proximity point exists for each pairing of slave node and proximal master surface point. Therefore, more than one proximity point may reference the same node on the slave surface but different points on the master surface if multiple local minimum distances to the slave node exist on the master surface; this phenomenon commonly occurs near the corners of a master surface. No proximity points exist for a slave node that is separated from the master surface by more than the tracking thickness. A two-dimensional representation for contact between portions of shell surfaces is shown in Figure 1.2.21–1.

![](images/page-528_d67aa33ffe88f079716c883afaefbecc9ec3b146925363501935690a1e52fef4.jpg)

<details>
<summary>text_image</summary>

Gap is greater than
tracking thickness
(no proximity point)
4 proximity points for these local
minima (within tracking thickness)
Slave surface
Master surface
</details>

Figure 1.2.21–1 Four proximity points are associated with three slave nodes in this surface pairing.

The number of proximity points currently being passed into user subroutine VUINTERACTION is nBlock. The array jSlvUid(nNodSlv,nBlock) gives the slave surface node numbers associated with the proximity points. The variable nNodSlv indicates whether a single slave node (for node-to-face contact) or two slave nodes of an edge (for edge-to-edge contact) are associated with each proximity point. Similarly, the array jMstUid(nNodMst,nBlockAnal) gives the master surface node numbers associated with the proximity points; the nodes can belong to a facet, an edge, or an analytical surface. The variable nNodMst indicates the number of master nodes associated with each proximity point.

An Abaqus/Explicit model can be defined in terms of an assembly of part instances (see “Defining an assembly,” Section 2.10.1 of the Abaqus Analysis User’s Guide). In such models a node number is an internally generated node number. If the original node number and part instance name are required, call the utility routine VGETPARTINFO (see “Obtaining part information,” Section 2.1.5).

# Local coordinate system

The array dircos defines the direction cosines of a local coordinate system for each proximity point. The first local direction corresponds to the contact normal direction from the perspective of the slave node. The second and third local directions correspond to two orthogonal tangent directions $\mathbf { t } _ { 1 }$ and $\mathbf { t } _ { 2 }$ , which are set as follows:

<!-- source-page: 529 -->

• If the master surface is a cylindrical analytical surface, the second local direction corresponds to the generator direction (see “Analytical rigid surface definition,” Section 2.3.4 of the Abaqus Analysis User’s Guide), and the third local direction is the cross product of the first and second local directions.   
• If the master surface is an analytical surface of revolution, the third local direction corresponds to the hoop direction, and the second local direction is the cross product of the third and first local directions.   
• If the master surface is element-based, the tangential directions are based on the slave normal and the line connecting the first and third nodes on the master facet.

For the two cases listed above involving analytical surfaces, the local tangential directions will reflect a rotation of the master surface. For the last case (element-based master surface) the tangential directions follow the rotation of the master surface only approximately. The second tangential direction is constructed such that it is perpendicular to the slave normal and the line going from the first to the third node on the master facet. The slave normal, the first tangent, and the second tangent form a right-handed system.

# Conventions for stress and heat flux

A positive normal stress denotes a pressure directed into the surface (opposite the local normal direction). Positive shear stresses denote shear tractions in the direction of the local surface tangents.

A positive flux indicates heat flowing into a surface, and a negative flux denotes heat leaving the surface. Flux must be specified for both surfaces, and they need not be equal and opposite so that effects such as frictional dissipation and differential surface heating can be modeled.

# User subroutine interface

```csv
subroutine vinteraction (
C Read/Write -
* stress, fluxSlv, fluxMst,
* state, sed,
C Write only -
* sfd, scd, spd, svd,
C Read only -
* nBlock, nBlockAnal, nBlockEdge,
* nNodState, nNodSlv, nNodMst, nDir,
* nStates, nProps, nTemp, nFields,
* jFlags, rData,
* surfInt, surfSlv, surfMst,
* jSlvUid, jMstUid, props,
* penetration, drDisp, dRot, dircos, stiffDef, conductDef,
* coordSlv, coordMst, areaProx, shapeSlv, shapeMst, 
```

<!-- source-page: 530 -->

```txt
* tempSlv, tempMst, dTempSlv, dTempMst,
* fieldSlv, fieldMst, dFieldSlv, dFieldMst)
C
    include `vaba_param.inc'
C
    dimension stress(nDir, nBlock),
    *    fluxSlv(nBlock),
    *    fluxMst(nBlock),
    *    state(nStates, nNodState, nBlock),
    *    sed(nBlock),
    *    sfd(nBlock),
    *    scd(nBlock),
    *    spd(nBlock),
    *    svd(nBlock),
    *    jSlvUid(nNodSlv, nBlock),
    *    jMstUid(nNodMst, nBlockAnal),
    *    props(nProps),
    *    penetration(nBlock),
    *    drDisp(nDir, nBlock),
    *    dRot(2, 2, nBlock),
    *    stiffDef(nBlock),
    *    conductDef(nBlock),
    *    dircos(nDir, nDir, nBlock),
    *    coordSlv(nDir, nNodSlv, nBlock),
    *    coordMst(nDir, nNodMst, nBlockAnal),
    *    areaProx(nBlock),
    *    shapeSlv(nNodSlv, nBlockEdge),
    *    shapeMst(nNodMst, nBlockAnal),
    *    tempSlv(nBlock),
    *    tempMst(nBlockAnal),
    *    dTempSlv(nBlock),
    *    dTempMst(nBlockAnal),
    *    fieldSlv(nFields, nBlock),
    *    fieldMst(nFields, nBlockAnal)
    *    dFieldSlv(nFields, nBlock),
    *    dFieldMst(nFields, nBlockAnal)
C
    parameter( iKStep    = 1,
    *    iKInc    = 2,
    *    iLConType    = 3,
    *    nFlags    = 3 )
C 
```
