# 7. Interface and Gap Elements - Inter2D, Inter3D, Gap

Interface and gap elements are designed to model surface interactions between two surfaces termed the master and slave surfaces. In structural analysis these interactions include various types of surface contact in which the relative displacement of the interacting faces remains small and the nodes on opposite faces are closely positioned. In thermal analysis these interactions include thermal contact resistance, surface convection and radiation effects. In thermal analysis the nodes on opposite faces are not restrained to be closely positioned.

When used to model contacting surfaces, the surface interaction can consist of a normal pressure and two tangential tractions which would typically arise from contact and sliding frictional effects. The contact pressures are functions of the relative displacement of the master and slave surfaces. The exact nature of the pressure, relative displacement relationship is determined by the underlying interface material model (usually an InterProp object). The relative displacements, dx, dy, dz along the element local axes are computed given the total displacement of the master surface Dxm,Dym,Dzm and the slave surface Dxs,Dys,Dzs in the element local system.

```dx = Dxm - Dxs - ci
dy = Dym - Dys
dz = Dzm - Dzs
```

where ci is the initial clearance. The initial clearance is the sum of the specified element node clearance and the actual geometric distance between the master and slave surfaces along the master surface normal. The inclusion of the actual geometric distance in the initial clearance calculation is optional.

When used to model thermal interactions, in all cases the geometry of the surface is determined solely from the coordinates and other element node properties associated with the nodes on the master surface. The type of thermal interaction selected determines the expression used to compute the generalized temperature difference, dt, given the temperature Tm of the master surface and the temperature Ts of the slave surface. The flux q across the interface is given by:

```q = -h*dt
```

where h is the film coefficient supplied from the underlying interface material (usually an InterProp object) and as such may be temperature dependent. The type of interface is specified by selecting an exchange law and optional exponent, a. Currently supported thermal interactions are:

• VFE_HEATEXCH_NONE, dt = 0.

• VFE_HEATEXCH_LINEAR, linear law, dt = Ts - Tm

• VFE_HEATEXCH_EXP, exponential law, dt = Ts**a - Tm**a

• VFE_HEATEXCH_POW, power law, dt = (Ts - Tm)**a

## 7.1. 2D Interface Elements - Inter2D

The Inter2D module is used to simulate surface interactions in 2D space. The interface element may be used in structural and thermal analysis.

The methods associated with a Inter2D object are the following.

Instance a Inter2D object using `vfe_Inter2DBegin()`. Once a Inter2D is instanced, set the material function attribute object MatlFun using `vfe_Inter2DSetObject()`. The current topology of the element is specified using `vfe_Inter2DSetTopology()`. Certain geometric details of the interface such as initial gap separation are specified using `vfe_Inter2DSetPropPtr()`. Query the element degree of freedom map using `vfe_Inter2DDofMap()` and `vfe_Inter2DNumDof()`.

If the element is to support a material model, such as a surface friction material model, which requires a material history then the user must manage the material history information using `vfe_Inter2DSetHistPtr()` and `vfe_Inter2DInitHist()`.

## 7.2. Element Geometry

The interface element consists of two matched surfaces termed the master surface and the slave surface. The basic interface element geometry is defined by the node coordinates of the the master surface and possibly the coordinates of the slave surface. The separation of the two surfaces is defined by normals and clearances specified at the nodes of the master surface. These properties are set using `vfe_Inter2DSetPropPtr()`. Other element node properties which may be set are temperature, depth and area factor.

The master and slave surfaces may be either explicitly defined as surfaces in terms of the nodal geometry as shown in Figure 7-1a or implicitly as lines in terms of the nodal geometry and associated nodal area factors as shown in Figure 7-1b. For 2D planar analysis the surface area is multiplied by the element node depth. If the interface element is being used to model surface contact in structural analysis, the separation of the master and slave surfaces is always measured along the normal to the master surface. The master surface normal may be determined from the nodal geometry or specified at the master surface nodes using `vfe_Inter2DSetPropPtr()`. The element local coordinate system is constructed so that the x’ direction is along the specified normal to the master surface. The y’ direction is perpendicular to x’.

In thermal analysis the geometry of the slave surface is ignored and only the temperatures of the slave surface nodes are used. For thermal analysis the element coordinate system is unused and is undefined.

The implicit surface interface element is only available for thermal analysis. In this case, since the master surface is defined as a single node, the element node area factor is interpreted as an effective thickness at the node for the calculation of surface area.

## 7.3. Function Descriptions

vfe_Inter2D *vfe_Inter2DBegin(void)

create an instance of an Inter2D object

Create an instance of a object. Memory is allocated for the object private data and the pointer to the object is returned. Default topology is the 4-node per surface quadrilateral interface

Destroy an instance of a object using

```void vfe_Inter2DEnd (vfe_Inter2D *inter2d)
```

Return the current value of a object error flag using

```Vint vfe_Inter2DError (vfe_Inter2D *inter2d)
```

Returns:

The function returns a pointer to the newly created object. If the object creation fails, NULL is returned.

void vfe_Inter2DEnd(vfe_Inter2D *p)

destroy an instance of an Inter2D object

See `vfe_Inter2DBegin()`

Vint vfe_Inter2DError(vfe_Inter2D *p)

return the current value of an Inter2D object error flag

See `vfe_Inter2DBegin()`

void vfe_Inter2DSetObject(vfe_Inter2D *p, Vint objecttype, Vobject *object)

set attribute object

Set a pointer to an attribute object. Users must supply a object prior to computing any quantity that requires a material model definition. The module provides a suitable material model.

Errors

`SYS_ERROR_OBJECTTYPE` is generated if an improper objecttype is specified.

Parameters:
• p – Pointer to object.

• objecttype – The object type identifier

```x=VFE_MATLFUN            MatlFun object
```

• object – Pointer to the object to be set.

void vfe_Inter2DSetTopology(vfe_Inter2D *p, Vint shape, Vint maxi, Vint maxj)

set element topology

Specify the topology of a 2D interface element. If maxi is set to 3 then a quadratic element form is assumed. The default topology is SYS_SHAPEQUAD with maxi = 0 and maxj = 2.

Errors

• `SYS_ERROR_VALUE` is generated if an improper maxi or maxj is specified.

• `SYS_ERROR_ENUM` is generated if an improper shape is input.

Parameters:
• p – Pointer to object.

• shape – The topological shape for the element

```x=VIS_SHAPEQUAD          Quadrilateral
=VIS_SHAPELINE          Line
```

• maxi – The number of points along the i direction. If maxi = 0 then the linear Serendipity element form of the specified shape is assumed.

• maxj – The number of points along the j direction. For quadrilateral shapes maxj = 2. For line shapes maxj = 0.

void vfe_Inter2DSetParami(vfe_Inter2D *p, Vint type, Vint iparam)

set element formulation parameters

Set element formulation parameters. Set element heat exchange law using `VFE_HEATEXCH`. By default `VFE_HEATEXCH` is set to `VFE_HEATEXCH_LINEAR`.

The parameter `VFE_GEOMCLEARANCE` is used to toggle the inclusion of the actual geometric location of the slave nodes in the calculation of the clearance between the master and slave surfaces. If `VFE_GEOMCLEARANCE` is disabled then the geometry of the slave surface is ignored and the initial clearance between the master and slave surfaces is determined by the element node clearances set using `vfe_Inter2DSetPropPtr()`. If `VFE_GEOMCLEARANCE` is enabled then the actual geometric separation of the master and slave surfaces is added to the specified element node clearances. By default `VFE_GEOMCLEARANCE` is set to `SYS_OFF`.

The parameter `VFE_2D` sets the particular 2D approximation for the element. The choices include plane stress, `VFE_PLANESTRESS`, plane strain, `VFE_PLANESTRAIN` and axisymmetric, `VFE_AXISYMMETRIC`. By default `VFE_2D` is set to `VFE_PLANESTRESS`.

Errors

• `SYS_ERROR_ENUM` is generated if an improper type is specified.

• `SYS_ERROR_VALUE` is generated if an improper iparam is specified.

Parameters:
• p – Pointer to object.

• type – Type of formulation parameter to set

```x=VFE_HEATEXCH           Element exchange law
=VFE_GEOMCLEARANCE      Clearance determined by geometry
=VFE_2D                 2D Approximation
```

• iparam – Integer parameter value.

```x=VFE_HEATEXCH_NONE      No exchange
=VFE_HEATEXCH_LINEAR    Linear exchange law
=VFE_HEATEXCH_EXP       Exponential exchange law
=VFE_HEATEXCH_POW       Power exchange law
=VFE_AXISYMMETRIC       2D axisymmetric
=VFE_PLANESTRAIN        2D plane strain
=VFE_PLANESTRESS        2D plane stress
```

void vfe_Inter2DSetParamd(vfe_Inter2D *p, Vint type, Vdouble dparam)

set double formulation parameters

Set double formulation parameters. Set element heat exchange exponent law using `VFE_HEATEXP`. This value is used if `VFE_HEATEXCH` is set to `VFE_HEATEXCH_POW`. Defaults to 1.0.

Set the absolute zero temperature for radiation exchange. Defaults to 0.

Errors

• `SYS_ERROR_ENUM` is generated if an improper type is specified.

• `SYS_ERROR_VALUE` is generated if an improper dparam is specified.

Parameters:
• p – Pointer to object.

• type – Type of formulation parameter to set

```x=VFE_HEATEXP            Heat exchange exponent
=VFE_ABSZEROTEMP        Absolute zero temperature
```

• dparam – Double parameter value.

void vfe_Inter2DStiff(vfe_Inter2D *p, Vdouble x[][3], Vdouble kl[])

linear stiffness matrix

Compute the linear stiffness matrix, kl, given the node coordinates, x. The lower triangle of the stiffness matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• kl[out] Degree of freedom stiffness matrix

void vfe_Inter2DStrsStrn(vfe_Inter2D *p, Vdouble x[][3], Vdouble u[], Vdouble strs[], Vdouble strn[])

stress and strain

Compute nodal stresses and strains, strs and strn, given the node coordinates, x, and the degree of freedom displacement vector, u. The stresses and strains are computed in the interface local system.

The strs is composed of 3 contact pressures and the strn is composed of 3 associated relative displacements in the element local system. The z’ values are returned as 0.

The strs and strn values are ordered first by the 3 vectoral components followed by the the number of element nodes.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• strs[out] Array of nodal stresses

• strn[out] Array of nodal strains

void vfe_Inter2DReact(vfe_Inter2D *p, Vdouble x[][3], Vdouble u[], Vdouble r[])

reaction vector

Compute the reaction vector, r, given the node coordinates, x, and the degree of freedom displacement vector, u.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• r[out] Degree of freedom reaction vector

void vfe_Inter2DReactStiff(vfe_Inter2D *p, Vdouble x[][3], Vdouble u[], Vint kflag, Vdouble r[], Vdouble k[])

reaction vector, stiffness matrix

Compute the reaction vector, r, and optionally the stiffness matrix, k, given the node coordinates, x, and the degree of freedom displacement vector, u. The lower triangle of the stiffness matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• kflag – Flag to compute stiffness matrix, k

```=SYS_OFF      Do not compute stiffness matrix
=SYS_ON       Compute and return stiffness matrix
```

• r[out] Degree of freedom reaction vector

• k[out] Degree of freedom stiffness matrix

void vfe_Inter2DNumDof(vfe_Inter2D *p, Vint analysistype, Vint *nedofs)

query number of element degrees of freedom

Query for number of element degree of freedom nedofs. The number of degrees of freedom will generally be equal to the number of nodal degrees of freedom per node times the number of nodes plus the number of elemental degrees of freedom. Use `vfe_Inter2DDofMap()` to return the location and type of each degree of freedom.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• nedofs[out] Number of element degrees of freedom

void vfe_Inter2DDofMap(vfe_Inter2D *p, Vint analysistype, Vint loc[], Vint tag[])

query element degree of freedom map

Query for element degree of freedom map. The degree of freedom map consists of a location index, loc and type, tag for each degree of freedom used by the element.

The location index is either a positive node index into the element connectivity indicating a nodal freedom or a zero value indicating an elemental degree of freedom. The tag indicates the type of the degree of freedom. Tag values are one of a set of enumerated types which indicate whether the degree of freedom is a translation, temperature, etc.

The length of the loc and tag vectors is equal to the number of element degrees of freedom. Use `vfe_Inter2DNumDof()` to return the number of element degrees of freedom.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• loc[out] Vector of degree of freedom locations

• tag[out] Vector of degree of freedom types

void vfe_Inter2DInitHist(vfe_Inter2D *p)

initialize material history

Initialize the values of the history variables used in the underlying element or primitive material model for the element. This operation should be performed once for each element (at the first load or time step for example) to initialize the old history variables to reflect the initial configuration condition. If the number of history variables is zero, this function need not be called.

Errors

`SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

Parameters:

p – Pointer to object.

void vfe_Inter2DNumIntPnt(vfe_Inter2D *p, Vint analysistype, Vint *nepnts)

query number of element integration points

Query for number of element integration points nepnts.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• nepnts[out] Number of element integration points

void vfe_Inter2DDirCos(vfe_Inter2D *p, Vdouble x[][3], Vdouble tm[][3][3])

compute interface local direction cosines

Compute the direction cosine matrices of the element local coordinate system. For stress and strain computation the local coordinate system at each stress output location is the coordinate system in which the output stresses and strains at the location using `vfe_Inter2DStrsStrn()` are expressed. Given that X’ and Y’ are two orthonormal vectors indicating the direction of the local coordinate axes in the global coordinate system (x,y,z), then the direction cosine matrix, tm for this local coordinate system is defined as:

``` tm[0][0] = X'x  tm[0][1] = X'y  tm[0][2] = 0.
tm[1][0] = Y'x  tm[1][1] = Y'y  tm[1][2] = 0.
tm[2][0] = 0.   tm[2][1] = 0.   tm[2][2] = 1.
```
The local coordinate system is determined by the local system convention and the element node normals which may be optionally set using `vfe_Inter2DSetPropPtr()`.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• tm[out] Array of direction cosine matrices at the element nodes.

void vfe_Inter2DSetPropPtr(vfe_Inter2D *p, Vint type, Vdouble *propptr)

set pointer to element nodal properties

Set a pointer to the start of a specified type of element properties. Note that the properties are not copied by this function, only the pointer itself is copied. If a property pointer is not set the element assumes a default value for the associated property. By default the temperature is 0., the depth is 1., the area factor is 1., the initial clearance is 0. and the normal is assumed to be computed from the master surface geometry.

Errors

`SYS_ERROR_ENUM` is generated if an improper type is specified.

Parameters:
• p – Pointer to object.

• type – Type of element property

```x=VFE_PROP_AREAFACT         Area Factor
=VFE_PROP_DEPTH            Depth
=VFE_PROP_TEMPERATURE      Temperatures
=VFE_PROP_NORMAL           Normals
=VFE_PROP_CLEARANCE        Initial clearance
```

• propptr – Pointer to start of element nodal properties

void vfe_Inter2DSetHistPtr(vfe_Inter2D *p, Vdouble *oldhist, Vdouble *newhist)

set pointers to material history

Set pointers to the start of the material history data at the previous step, oldhist and the current step newhist. This function is required when an underlying material model such as plasticity is used. Note that the material history data is not copied by this function, only the pointers themselves are copied. The number of double precision values required for the material history at a step is the number of history variables at an integration point times the number of element integration points. The number of history variables depends on the underlying material model and may be queried using `vfe_MatlFunNumHist()`. The number of element integration points is returned using `vfe_Inter2DNumIntPnt()`. By default the pointers to the material history are NULL. If the number of history variables is zero, this function need not be called.

Parameters:
• p – Pointer to object.

• oldhist – Pointer to start of material history at previous step

• newhist – Pointer to start of material history at current step

void vfe_Inter2DPowerCond(vfe_Inter2D *p, Vdouble x[][3], Vdouble u[], Vint kflag, Vdouble r[], Vdouble k[])

thermal power, conductance matrix

Compute the power vector, r, and optionally the conductance matrix, k, given the node coordinates, x, and the degree of freedom temperature vector, u. The lower triangle of the conductance matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• kflag – Flag to compute conductance matrix, k

```=SYS_OFF      Do not compute conductance matrix
=SYS_ON       Compute and return conductance matrix
```

• r[out] Degree of freedom power vector

• k[out] Degree of freedom conductance matrix

void vfe_Inter2DPower(vfe_Inter2D *p, Vdouble x[][3], Vdouble u[], Vdouble r[])

thermal power vector

Compute the power vector, r, given the node coordinates, x, and the degree of freedom temperature vector, u.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• r[out] Degree of freedom power vector

void vfe_Inter2DCond(vfe_Inter2D *p, Vdouble x[][3], Vdouble kl[])

thermal conductance matrix

Compute the linear conductance matrix, kl, given the node coordinates, x. The lower triangle of the conductance matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• kl[out] Degree of freedom conductance matrix

void vfe_Inter2DHFlxTGrd(vfe_Inter2D *p, Vdouble x[][3], Vdouble u[], Vdouble hflx[], Vdouble tgrd[])

Heat flux and temperature difference.

Compute nodal heat fluxes and temperature differences, hflx and tgrd, given the node coordinates, x, and the degree of freedom temperature vector, u.

The hflx is a scalar flux and the tgrd is the associated temperature difference across the interface at each element node.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• hflx[out] Array of nodal heat fluxes

• tgrd[out] Array of nodal temperature differences

void vfe_Inter2DDistHeat(vfe_Inter2D *p, Vdouble x[][3], Vint enttype, Vint no, Vdouble q[], Vdouble f[])

Compute the consistent degree of freedom loads given a distributed heat load, q on a 2D interface element edge or node. The vector q contains values for the heat flux for each node in the element. The distributed flux for both edges and nodes are in units of flux per unit area.

Errors

• `SYS_ERROR_ENUM` is generated if an improper enttype is specified.

• `SYS_ERROR_VALUE` is generated if an improper no is specified.

• `SYS_ERROR_COMPUTE` is generated if a zero edge Jacobian is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• enttype – Entity type on which load is applied

```=SYS_NODE     Element node
=SYS_EDGE     Element edge
```

• no – Element node or edge number

• q – Vector of distributed load values

• f[out] Degree of freedom vector of consistent loads.

void vfe_Inter2DDistLoad(vfe_Inter2D *p, Vdouble x[][3], Vint enttype, Vint no, Vint loadtype, Vdouble q[], Vdouble f[])

Compute the consistent degree of freedom loads given a distributed load, q on a 2D interface element face. The vector q contains values for the load type for each node in the element. If the loadtype is `VFE_DISTLOAD_TRAC` then q contains a vector traction at each element node. If the loadtype is `VFE_DISTLOAD_PRES` then q contains a scalar pressure at each element node.

Errors

• `SYS_ERROR_ENUM` is generated if an improper enttype or loadtype is specified.

• `SYS_ERROR_OPERATION` is generated if an invalid combination of enttype and loadtype is specified.

• `SYS_ERROR_VALUE` is generated if an improper no is specified.

• `SYS_ERROR_COMPUTE` is generated if a zero face Jacobian is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• enttype – Entity type on which load is applied

```=SYS_EDGE     Element edge
```

• no – Element edge number

```=1            Master face
=3            Slave face
```

```x=VFE_DISTLOAD_PRES      Pressure normal to face
```

• q – Vector of distributed load values

• f[out] Degree of freedom vector of consistent loads.

## 7.4. 3D Interface Elements - Inter3D

The Inter3D module is used to simulate surface interactions in 3D space. The interface element may be used in structural and thermal analysis.

The methods associated with a Inter3D object are the following.

Instance a Inter3D object using `vfe_Inter3DBegin()`. Once a Inter3D is instanced, set the material function attribute object MatlFun using `vfe_Inter3DSetObject()`. The current topology of the element is specified using `vfe_Inter3DSetTopology()`. Certain geometric details of the interface such as initial gap separation are specified using `vfe_Inter3DSetPropPtr()`. Query the element degree of freedom map using `vfe_Inter3DDofMap()` and `vfe_Inter3DNumDof()`.

If the element is to support a material model, such as a surface friction material model, which requires a material history then the user must manage the material history information using `vfe_Inter3DSetHistPtr()` and `vfe_Inter3DInitHist()`.

## 7.5. Element Geometry

The interface element consists of two matched surfaces termed the master surface and the slave surface. The basic interface element geometry is defined by the node coordinates of the the master surface and possibly the coordinates of the slave surface. The separation of the two surfaces is defined by normals and clearances specified at the nodes of the master surface. These properties are set using `vfe_Inter3DSetPropPtr()`. Other element node properties which may be set are temperature and area factor.

The master and slave surfaces may be either explicitly defined as surfaces in terms of the nodal geometry as shown in Figure 7-2a or implicitly as lines in terms of the nodal geometry and associated nodal area factors as shown in Figure 7-2b. If the interface element is being used to model surface contact in structural analysis, the separation of the master and slave surfaces is always measured along the normal to the master surface. The master surface normal may be determined from the nodal geometry or specified at the master surface nodes using `vfe_Inter3DSetPropPtr()`. The element local coordinate system is constructed so that the x’ direction is along the specified normal to the master surface. The y’ and z’ directions are constructed using the prescription specified using `vfe_Inter3DSetLocalSystem()`. If the normal, x’ direction, is specified using `vfe_Inter3DSetPropPtr()`, the y’ and z’ tangential directions are adjusted to remain orthogonal to x’.

In thermal analysis the geometry of the slave surface is ignored and only the temperatures of the slave surface nodes are used. For thermal analysis the element coordinate system is unused and is undefined.

The implicit surface interface element is only available for thermal analysis. In this case, since the master surface is defined as a line of nodes, the element node area factor is interpreted as an effective thickness at each node for the calculation of surface area.

## 7.6. Function Descriptions

The currently available Inter3D functions are described in detail in this section.

vfe_Inter3D *vfe_Inter3DBegin(void)

create an instance of an Inter3D object

Create an instance of a object. Memory is allocated for the object private data and the pointer to the object is returned. Default topology is the 4-node per surface quadrilateral interface

Destroy an instance of a object using

```void vfe_Inter3DEnd (vfe_Inter3D *inter3d)
```

Return the current value of a object error flag using

```Vint vfe_Inter3DError (vfe_Inter3D *inter3d)
```

Returns:

The function returns a pointer to the newly created object. If the object creation fails, NULL is returned.

void vfe_Inter3DEnd(vfe_Inter3D *p)

destroy an instance of an Inter3D object

See `vfe_Inter3DBegin()`

Vint vfe_Inter3DError(vfe_Inter3D *p)

return the current value of an Inter3D object error flag

See `vfe_Inter3DBegin()`

void vfe_Inter3DSetObject(vfe_Inter3D *p, Vint objecttype, Vobject *object)

set attribute object

Set a pointer to an attribute object. Users must supply a object prior to computing any quantity that requires a material model definition.

Parameters:
• p – Pointer to object.

• objecttype – The object type identifier

```x=VFE_MATLFUN            MatlFun object
```

• object – Pointer to the object to be set.

void vfe_Inter3DSetTopology(vfe_Inter3D *p, Vint shape, Vint maxi, Vint maxj, Vint maxk)

set element topology

Specify the topology of a 3D interface element. If maxi is set to 3 then a quadratic element form is assumed. The default topology is SYS_SHAPEHEX with maxi = maxj = 0 and maxk = 2.

Errors

• `SYS_ERROR_VALUE` is generated if an improper maxi, maxj or maxk is specified.

• `SYS_ERROR_ENUM` is generated if an improper shape is input.

Parameters:
• p – Pointer to object.

• shape – The topological shape for the element

```x=VIS_SHAPEWED           Wedge
=VIS_SHAPEHEX           Hexahedron
```

• maxi – The number of points along the i direction. If maxi = 0 then the linear Serendipity element form of the specified shape is assumed.

• maxj – The number of points along the j direction. If maxj = 0 then a Serendipity finite element is assumed. If 2 <= maxj <= 3 and 2 <= maxi <= 3, then a Lagrange finite element is assumed. If maxi != 0 then maxj = 0 or maxj = maxi. For quadrilateral shapes maxj = 2.

• maxk – The number of points along the k direction. For wedge and hexahedron shapes maxk = 2. For quadrilateral shapes maxk is ignored.

void vfe_Inter3DSetParami(vfe_Inter3D *p, Vint type, Vint iparam)

set element formulation parameters

Set element formulation parameters. Set element heat exchange law using `VFE_HEATEXCH`. By default `VFE_HEATEXCH` is set to `VFE_HEATEXCH_LINEAR`.

The parameter `VFE_GEOMCLEARANCE` is used to toggle the inclusion of the actual geometric location of the slave nodes in the calculation of the clearance between the master and slave surfaces. If `VFE_GEOMCLEARANCE` is disabled then the geometry of the slave surface is ignored and the initial clearance between the master and slave surfaces is determined by the element node clearances set using `vfe_Inter3DSetPropPtr()`. If `VFE_GEOMCLEARANCE` is enabled then the actual geometric separation of the master and slave surfaces is added to the specified element node clearances. By default `VFE_GEOMCLEARANCE` is set to `SYS_OFF`.

Errors

• `SYS_ERROR_ENUM` is generated if an improper type is specified.

• `SYS_ERROR_VALUE` is generated if an improper iparam is specified.

Parameters:
• p – Pointer to object.

• type – Type of formulation parameter to set

```x=VFE_HEATEXCH           Element exchange law
=VFE_GEOMCLEARANCE      Clearance determined by geometry
```

• iparam – Integer parameter value.

```x=VFE_HEATEXCH_NONE      No exchange
=VFE_HEATEXCH_LINEAR    Linear exchange law
=VFE_HEATEXCH_EXP       Exponential exchange law
=VFE_HEATEXCH_POW       Power exchange law
```

void vfe_Inter3DSetParamd(vfe_Inter3D *p, Vint type, Vdouble dparam)

set double formulation parameters

Set double formulation parameters. Set element heat exchange exponent law using `VFE_HEATEXP`. This value is used if `VFE_HEATEXCH` is set to `VFE_HEATEXCH_POW`. Defaults to 1.0.

Set the tolerance for clamping the natural coordinates when performing projections. Defaults to 0.1.

Set the absolute zero temperature for radiation exchange. Defaults to 0.

Errors

• `SYS_ERROR_ENUM` is generated if an improper type is specified.

• `SYS_ERROR_VALUE` is generated if an improper dparam is specified.

Parameters:
• p – Pointer to object.

• type – Type of formulation parameter to set

```x=VFE_HEATEXP       Heat exchange exponent
=VFE_EXTENSION     Tolerance for natural coordinates clamping
=VFE_ABSZEROTEMP   Absolute zero temperature
```

• dparam[in] Double parameter value.

void vfe_Inter3DStiff(vfe_Inter3D *p, Vdouble x[][3], Vdouble kl[])

linear stiffness matrix

Compute the linear stiffness matrix, kl, given the node coordinates, x. The lower triangle of the stiffness matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• kl[out] Degree of freedom stiffness matrix

void vfe_Inter3DStrsStrn(vfe_Inter3D *p, Vdouble x[][3], Vdouble u[], Vdouble strs[], Vdouble strn[])

stress and strain

Compute nodal stresses and strains, strs and strn, given the node coordinates, x, and the degree of freedom displacement vector, u. The stresses and strains are computed in the interface local system. The convention used to generate local coordinate systems is specified using `vfe_Inter3DSetLocalSystem()` with an optional surface normal specified using `vfe_Inter3DSetPropPtr()`.

The strs is composed of 3 contact pressures and the strn is composed of 3 associated relative displacements in the element local system.

The strs and strn values are ordered first by the 3 vectoral components followed by the the number of element nodes.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• strs[out] Array of nodal stresses

• strn[out] Array of nodal strains

void vfe_Inter3DReact(vfe_Inter3D *p, Vdouble x[][3], Vdouble u[], Vdouble r[])

reaction vector

Compute the reaction vector, r, given the node coordinates, x, and the degree of freedom displacement vector, u.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• r[out] Degree of freedom reaction vector

void vfe_Inter3DReactStiff(vfe_Inter3D *p, Vdouble x[][3], Vdouble u[], Vint kflag, Vdouble r[], Vdouble k[])

reaction vector, stiffness matrix

Compute the reaction vector, r, and optionally the stiffness matrix, k, given the node coordinates, x, and the degree of freedom displacement vector, u. The lower triangle of the stiffness matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• kflag – Flag to compute stiffness matrix, k

```=SYS_OFF      Do not compute stiffness matrix
=SYS_ON       Compute and return stiffness matrix
```

• r[out] Degree of freedom reaction vector

• k[out] Degree of freedom stiffness matrix

void vfe_Inter3DNumDof(vfe_Inter3D *p, Vint analysistype, Vint *nedofs)

query number of element degrees of freedom

Query for number of element degree of freedom nedofs. The number of degrees of freedom will generally be equal to the number of nodal degrees of freedom per node times the number of nodes plus the number of elemental degrees of freedom. Use `vfe_Inter3DDofMap()` to return the location and type of each degree of freedom.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• nedofs[out] Number of element degrees of freedom

void vfe_Inter3DDofMap(vfe_Inter3D *p, Vint analysistype, Vint loc[], Vint tag[])

query element degree of freedom map

Query for element degree of freedom map. The degree of freedom map consists of a location index, loc and type, tag for each degree of freedom used by the element.

The location index is either a positive node index into the element connectivity indicating a nodal freedom or a zero value indicating an elemental degree of freedom. The tag indicates the type of the degree of freedom. Tag values are one of a set of enumerated types which indicate whether the degree of freedom is a translation, temperature, etc.

The length of the loc and tag vectors is equal to the number of element degrees of freedom. Use `vfe_Inter3DNumDof()` to return the number of element degrees of freedom.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• loc[out] Vector of degree of freedom locations

• tag[out] Vector of degree of freedom types

void vfe_Inter3DInitHist(vfe_Inter3D *p)

initialize material history

Initialize the values of the history variables used in the underlying element or primitive material model for the element. This operation should be performed once for each element (at the first load or time step for example) to initialize the old history variables to reflect the initial configuration condition. If the number of history variables is zero, this function need not be called.

Errors

`SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

Parameters:

p – Pointer to object.

void vfe_Inter3DNumIntPnt(vfe_Inter3D *p, Vint analysistype, Vint *nepnts)

query number of element integration points

Query for number of element integration points nepnts.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• nepnts[out] Number of element integration points

void vfe_Inter3DSetLocalSystem(vfe_Inter3D *p, Vint type, Vdouble vec[], Vdouble angle)

set local coordinate system convention

Specify the convention to be used to construct the orientation of the element local x’,y’,z’ coordinate system with respect to the interface surface.

For stress and strain computation for output using `vfe_Inter3DStrsStrn()`, the local coordinate system is evaluated at each output location and is the coordinate system in which the output stresses and strains at the output location are expressed.

The vec array is only used if the specified type requires position or direction vectors. An additional rotation of the y’,z’ axes about the x’ axis can be specified with angle. By default the local system convention is `SYS_ELEMSYS_STANDARD` with angle set to 0.

For a description of element coordinate systems, type, and associated orientation vector data, please see

Errors

`SYS_ERROR_ENUM` is generated if an improper type is input.

Parameters:
• p – Pointer to object.

• type – Local system convention

• vec – Orientation vector data

• angle – Angle to rotate element y’,z’ axes about the element x’ axis in degrees.

void vfe_Inter3DSetMatlSystem(vfe_Inter3D *p, Vint type, Vdouble vec[], Vdouble angle)

set material coordinate system convention

Specify the convention to be used to construct the orientation of the element material x’,y’,z’ coordinate system with respect to the interface surface. This material system is computed at each integration point location on the interface and is assumed to be the coordinate system in which the material properties of the element at the integration point are expressed.

The vec array is only used if the specified type requires position or direction vectors. An additional rotation of the y’,z’ axes about the x’ axis can be specified with angle. By default the local system convention is `SYS_ELEMSYS_STANDARD` with angle set to 0.

For a description of element coordinate systems, type, and associated orientation vector data, please see

Errors

`SYS_ERROR_ENUM` is generated if an improper type is input.

Parameters:
• p – Pointer to object.

• type – Local system convention

• vec – Orientation vector data

• angle – Angle to rotate element y’,z’ axes about the element x’ axis in degrees.

void vfe_Inter3DDirCos(vfe_Inter3D *p, Vdouble x[][3], Vdouble tm[][3][3])

compute interface local direction cosines

Compute the direction cosine matrices of the element local coordinate system. For stress and strain computation the local coordinate system at each stress output location is the coordinate system in which the output stresses and strains at the location using `vfe_Inter3DStrsStrn()` are expressed. Given that X’,Y’ and Z’ are three orthonormal vectors indicating the direction of the local coordinate axes in the global coordinate system (x,y,z), then the direction cosine matrix, tm for this local coordinate system is defined as:

``` tm[0][0] = X'x  tm[0][1] = X'y  tm[0][2] = X'z
tm[1][0] = Y'x  tm[1][1] = Y'y  tm[1][2] = Y'z
tm[2][0] = Z'x  tm[2][1] = Z'y  tm[2][2] = Z'z
```
The local coordinate system is determined by the local system convention set using `vfe_Inter3DSetLocalSystem()` and the element node normals which may be optionally set using `vfe_Inter3DSetPropPtr()`.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• tm[out] Array of direction cosine matrices at the element nodes.

void vfe_Inter3DSetPropPtr(vfe_Inter3D *p, Vint type, Vdouble *propptr)

set pointer to element nodal properties

Set a pointer to the start of a specified type of element properties. Note that the properties are not copied by this function, only the pointer itself is copied. If a property pointer is not set the element assumes a default value for the associated property. By default the temperature is 0., the area factor is 1., the initial clearance is 0. and the normal is assumed to be computed from the master surface geometry.

Errors

`SYS_ERROR_ENUM` is generated if an improper type is specified.

Parameters:
• p – Pointer to object.

• type – Type of element property

```x=VFE_PROP_AREAFACT         Area Factor
=VFE_PROP_TEMPERATURE      Temperatures
=VFE_PROP_NORMAL           Normals
=VFE_PROP_CLEARANCE        Initial clearance
```

• propptr – Pointer to start of element nodal properties

void vfe_Inter3DSetHistPtr(vfe_Inter3D *p, Vdouble *oldhist, Vdouble *newhist)

set pointers to material history

Set pointers to the start of the material history data at the previous step, oldhist and the current step newhist. This function is required when an underlying material model such as plasticity is used. Note that the material history data is not copied by this function, only the pointers themselves are copied. The number of double precision values required for the material history at a step is the number of history variables at an integration point times the number of element integration points. The number of history variables depends on the underlying material model and may be queried using `vfe_MatlFunNumHist()`. The number of element integration points is returned using `vfe_Inter3DNumIntPnt()`. By default the pointers to the material history are NULL. If the number of history variables is zero, this function need not be called.

Parameters:
• p – Pointer to object.

• oldhist – Pointer to start of material history at previous step

• newhist – Pointer to start of material history at current step

void vfe_Inter3DPowerCond(vfe_Inter3D *p, Vdouble x[][3], Vdouble u[], Vint kflag, Vdouble r[], Vdouble k[])

thermal power, conductance matrix

Compute the power vector, r, and optionally the conductance matrix, k, given the node coordinates, x, and the degree of freedom temperature vector, u. The lower triangle of the conductance matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• kflag – Flag to compute conductance matrix, k

```=SYS_OFF      Do not compute conductance matrix
=SYS_ON       Compute and return conductance matrix
```

• r[out] Degree of freedom power vector

• k[out] Degree of freedom conductance matrix

void vfe_Inter3DPower(vfe_Inter3D *p, Vdouble x[][3], Vdouble u[], Vdouble r[])

thermal power vector

Compute the power vector, r, given the node coordinates, x, and the degree of freedom temperature vector, u.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• r[out] Degree of freedom power vector

void vfe_Inter3DCond(vfe_Inter3D *p, Vdouble x[][3], Vdouble kl[])

thermal conductance matrix

Compute the linear conductance matrix, kl, given the node coordinates, x. The lower triangle of the conductance matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• kl[out] Degree of freedom conductance matrix

void vfe_Inter3DHFlxTGrd(vfe_Inter3D *p, Vdouble x[][3], Vdouble u[], Vdouble hflx[], Vdouble tgrd[])

Heat flux and temperature difference.

Compute nodal heat fluxes and temperature differences, hflx and tgrd, given the node coordinates, x, and the degree of freedom temperature vector, u.

The hflx is a scalar flux and the tgrd is the associated temperature difference across the interface at each element node.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• hflx[out] Array of nodal heat fluxes

• tgrd[out] Array of nodal temperature differences

void vfe_Inter3DDistLoad(vfe_Inter3D *p, Vdouble x[][3], Vint enttype, Vint no, Vint loadtype, Vdouble q[], Vdouble f[])

Compute the consistent degree of freedom loads given a distributed load, q on a 3D interface element face. The vector q contains values for the load type for each node in the element. If the loadtype is `VFE_DISTLOAD_TRAC` then q contains a vector traction at each element node. If the loadtype is `VFE_DISTLOAD_PRES` then q contains a scalar pressure at each element node.

Errors

• `SYS_ERROR_ENUM` is generated if an improper enttype or loadtype is specified.

• `SYS_ERROR_OPERATION` is generated if an invalid combination of enttype and `loadtype` is specified.

• `SYS_ERROR_VALUE` is generated if an improper no is specified.

• `SYS_ERROR_COMPUTE` is generated if a zero face Jacobian is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• enttype – Entity type on which load is applied

```=SYS_FACE     Element face
```

• no – Element face number

```=1            Master face
```

```x=VFE_DISTLOAD_PRES      Pressure normal to face
```

• q – Vector of distributed load values

• f[out] Degree of freedom vector of consistent loads.

void vfe_Inter3DDistHeat(vfe_Inter3D *p, Vdouble x[][3], Vint enttype, Vint no, Vdouble q[], Vdouble f[])

Compute the consistent degree of freedom loads given a distributed heat load, q on a 3D interface element face or edge. The vector q contains values for the heat flux for each node in the element. The distributed flux for faces and edges are in units of flux per unit area.

Errors

• `SYS_ERROR_ENUM` is generated if an improper enttype is specified.

• `SYS_ERROR_VALUE` is generated if an improper no is specified.

• `SYS_ERROR_COMPUTE` is generated if a zero edge Jacobian is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• enttype – Entity type on which load is applied

```=SYS_EDGE     Element edge
=SYS_FACE     Element face
```

• no – Element edge or face number

```=1            Master edge or face
```

• q – Vector of distributed load values

• f[out] Degree of freedom vector of consistent loads.

## 7.7. Gap Elements - Gap

The Gap module is used to simulate simple surface interactions in 2D or 3D space. The master and slave surfaces are assumed to be infinite, passing through the gap element end points and and perpendicular to the specified normal at the first end point. The gap element may be used in structural and thermal analysis.

The methods associated with a Gap object are the following.

Instance a Gap object using `vfe_GapBegin()`. Once a Gap is instanced, set the material function attribute object MatlFun using `vfe_GapSetObject()`. The function `vfe_GapDef()` is used to defined the gap as either being used in 2D or 3D analysis.

Certain geometric details of the gap such as initial gap separation are specified using `vfe_GapSetPropPtr()`. Query the element degree of freedom map using `vfe_GapDofMap()` and `vfe_GapNumDof()`.

If the element is to support a material model, such as a surface friction material model, which requires a material history then the user must manage the material history information using `vfe_GapSetHistPtr()` and `vfe_GapInitHist()`.

## 7.8. Element Geometry

The gap element consists of two matched surfaces termed the master surface and the slave surface. The basic gap element geometry is defined by the node coordinates of the the first node and possibly the coordinates of the second node. The separation of the two surfaces is defined by normals and clearances specified at the first of the master surface. These properties are set using `vfe_GapSetPropPtr()`. Other element node properties which may be set are temperature and area.

The master surface passes through the first node and is perpendicular to the normal at the first node. The normal may be computed to be along the line connecting the first and second node or may be explicitly specified using `vfe_GapSetPropPtr()`. The slave surface passes through the second node and is parallel to the master surface. Both surfaces are assumed to be of infinite extent for contact purposes. The 3D gap element geometry is shown in Figure 7-3a and the 2D gap geometry is shown in Figure 7-3b.

If the gap element is being used to model surface contact in structural analysis, the separation of the master and slave surfaces is always measured along the normal to the master surface. The element local coordinate system is constructed so that the x’ direction is along the specified normal to the master surface. The y’ and z’ directions are constructed using the prescription specified using `vfe_GapSetLocalSystem()`. If the normal, x’ direction, is specified using `vfe_GapSetPropPtr()`, the y’ and z’ tangential directions are adjusted to remain orthogonal to x’.

In thermal analysis the geometry of the slave surface is ignored and only the temperature of the slave surface node is used. The element node area is used at the master node for the calculation of surface area. For thermal analysis the element coordinate system is unused and is undefined.

In 2D, the gap element may be used for either 2D axisymmetric or 2D planar analysis.

## 7.9. Function Descriptions

The currently available Gap functions are described in detail in this section.

vfe_Gap *vfe_GapBegin(void)

create an instance of a Gap object

Create an instance of a object. Memory is allocated for the object private data and the pointer to the object is returned.

Destroy an instance of a object using

```void vfe_GapEnd (vfe_Gap *gap)
```

Return the current value of a object error flag using

```Vint vfe_GapError (vfe_Gap *gap)
```

Returns:

The function returns a pointer to the newly created object. If the object creation fails, NULL is returned.

void vfe_GapEnd(vfe_Gap *p)

destroy an instance of a Gap object

See `vfe_GapBegin()`

Vint vfe_GapError(vfe_Gap *p)

return the current value of a Gap object error flag

See `vfe_GapBegin()`

void vfe_GapSetObject(vfe_Gap *p, Vint objecttype, Vobject *object)

set attribute object

Set a pointer to an attribute object. Users must supply a object prior to computing any quantity that requires a material model definition. The module provides a suitable material model.

Errors

`SYS_ERROR_OBJECTTYPE` is generated if an improper objecttype is specified.

Parameters:
• p – Pointer to object.

• objecttype – The object type identifier

```x=VFE_MATLFUN            MatlFun object
```

• object[out] Pointer to the object to be set.

void vfe_GapDef(vfe_Gap *p, Vint dimension)

define gap dimensionality

Define the dimension of the gap element.

Errors

`SYS_ERROR_ENUM` is generated if an improper dime is specified.

Parameters:
• p – Pointer to object.

• dimension – Gap dimension

```=VFE_2D       2D analysis
=VFE_3D       3D analysis
```

void vfe_GapSetParami(vfe_Gap *p, Vint type, Vint iparam)

set element formulation parameters

Set element formulation parameters. Set element heat exchange law using `VFE_HEATEXCH`. By default `VFE_HEATEXCH` is set to `VFE_HEATEXCH_LINEAR`.

The parameter `VFE_GEOMCLEARANCE` is used to toggle the inclusion of the actual geometric location of the slave nodes in the calculation of the clearance between the master and slave surfaces. If `VFE_GEOMCLEARANCE` is disabled then the geometry of the slave surface is ignored and the initial clearance between the master and slave surfaces is determined by the element node clearances set using `vfe_GapSetPropPtr()`. If `VFE_GEOMCLEARANCE` is enabled then the actual geometric separation of the master and slave surfaces is added to the specified element node clearances. By default `VFE_GEOMCLEARANCE` is set to `SYS_OFF`.

Errors

• `SYS_ERROR_ENUM` is generated if an improper type is specified.

• `SYS_ERROR_VALUE` is generated if an improper iparam is specified.

Parameters:
• p – Pointer to object.

• type – Type of formulation parameter to set

```x=VFE_HEATEXCH           Element exchange law
=VFE_GEOMCLEARANCE      Clearance determined by geometry
```

• iparam – Integer parameter value.

```x=VFE_HEATEXCH_NONE      No exchange
=VFE_HEATEXCH_LINEAR    Linear exchange law
=VFE_HEATEXCH_EXP       Exponential exchange law
=VFE_HEATEXCH_POW       Power exchange law
```

void vfe_GapSetParamd(vfe_Gap *p, Vint type, Vdouble dparam)

set double formulation parameters

Set element heat exchange exponent law using `VFE_HEATEXP`. This value is used if `VFE_HEATEXCH` is set to `VFE_HEATEXCH_POW`. Defaults to 1.0.

Errors

• `SYS_ERROR_ENUM` is generated if an improper type is specified.

• `SYS_ERROR_VALUE` is generated if an improper dparam is specified.

Parameters:
• p – Pointer to object.

• type – Type of formulation parameter to set

```x=VFE_HEATEXP            Heat exchange exponent
```

• dparam[out] Double parameter value.

void vfe_GapStiff(vfe_Gap *p, Vdouble x[][3], Vdouble kl[])

linear stiffness matrix

Compute the linear stiffness matrix, kl, given the node coordinates, x. The lower triangle of the stiffness matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• kl[out] Degree of freedom stiffness matrix

void vfe_GapStrsStrn(vfe_Gap *p, Vdouble x[][3], Vdouble u[], Vdouble strs[], Vdouble strn[])

stress and strain

Compute nodal stresses and strains, strs and strn, given the node coordinates, x, and the degree of freedom displacement vector, u. The stresses and strains are computed in the gap local system. The convention used to generate local coordinate systems is specified using `vfe_GapSetLocalSystem()` with an optional surface normal specified using `vfe_GapSetPropPtr()`.

The strs is composed of 3 contact pressures and the strn is composed of 3 associated relative displacements in the element local system.

The strs and strn values are ordered first by the 3 vectoral components followed by the the number of element nodes.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• strs[out] Array of nodal stresses

• strn[out] Array of nodal strains

void vfe_GapReact(vfe_Gap *p, Vdouble x[][3], Vdouble u[], Vdouble r[])

reaction vector

Compute the reaction vector, r, given the node coordinates, x, and the degree of freedom displacement vector, u.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• r[out] Degree of freedom reaction vector

void vfe_GapReactStiff(vfe_Gap *p, Vdouble x[][3], Vdouble u[], Vint kflag, Vdouble r[], Vdouble k[])

reaction vector, stiffness matrix

Compute the reaction vector, r, and optionally the stiffness matrix, k, given the node coordinates, x, and the degree of freedom displacement vector, u. The lower triangle of the stiffness matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of displacements

• kflag – Flag to compute stiffness matrix, k

```=SYS_OFF      Do not compute stiffness matrix
=SYS_ON       Compute and return stiffness matrix
```

• r[out] Degree of freedom reaction vector

• k[out] Degree of freedom stiffness matrix

void vfe_GapNumDof(vfe_Gap *p, Vint analysistype, Vint *nedofs)

query number of element degrees of freedom

Query for number of element degree of freedom nedofs. The number of degrees of freedom will generally be equal to the number of nodal degrees of freedom per node times the number of nodes plus the number of elemental degrees of freedom. Use `vfe_GapDofMap()` to return the location and type of each degree of freedom.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• nedofs[out] Number of element degrees of freedom

void vfe_GapDofMap(vfe_Gap *p, Vint analysistype, Vint loc[], Vint tag[])

query element degree of freedom map

Query for element degree of freedom map. The degree of freedom map consists of a location index, loc and type, tag for each degree of freedom used by the element.

The location index is either a positive node index into the element connectivity indicating a nodal freedom or a zero value indicating an elemental degree of freedom. The tag indicates the type of the degree of freedom. Tag values are one of a set of enumerated types which indicate whether the degree of freedom is a translation, temperature, etc.

The length of the loc and tag vectors is equal to the number of element degrees of freedom. Use `vfe_GapNumDof()` to return the number of element degrees of freedom.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• loc[out] Vector of degree of freedom locations

• tag[out] Vector of degree of freedom types

void vfe_GapInitHist(vfe_Gap *p)

initialize material history

Initialize the values of the history variables used in the underlying element or primitive material model for the element. This operation should be performed once for each element (at the first load or time step for example) to initialize the old history variables to reflect the initial configuration condition. If the number of history variables is zero, this function need not be called.

Errors

`SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

Parameters:

p – Pointer to object.

void vfe_GapNumIntPnt(vfe_Gap *p, Vint analysistype, Vint *nepnts)

query number of element integration points

Query for number of element integration points nepnts.

Errors

`SYS_ERROR_ENUM` is generated if an improper analysistype is specified.

Parameters:
• p – Pointer to object.

• analysistype – The type of analysis

```x=VFE_ANALYSIS_STRUCTURAL Structural analysis
=VFE_ANALYSIS_THERMAL    Thermal analysis
```

• nepnts[out] Number of element integration points

void vfe_GapDirCos(vfe_Gap *p, Vdouble x[][3], Vdouble tm[][3][3])

compute gap local direction cosines

Compute the direction cosine matrices of the element local coordinate system. For stress and strain computation the local coordinate system at each stress output location is the coordinate system in which the output stresses and strains at the location using `vfe_GapStrsStrn()` are expressed. Given that X’,Y’ and Z’ are three orthonormal vectors indicating the direction of the local coordinate axes in the global coordinate system (x,y,z), then the direction cosine matrix,tm for this local coordinate system is defined as:

``` tm[0][0] = X'x  tm[0][1] = X'y  tm[0][2] = X'z
tm[1][0] = Y'x  tm[1][1] = Y'y  tm[1][2] = Y'z
tm[2][0] = Z'x  tm[2][1] = Z'y  tm[2][2] = Z'z
```
The local coordinate system is determined by the local system convention set using `vfe_GapSetLocalSystem()` and the element node normals which may be optionally set using `vfe_GapSetPropPtr()`.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• tm[out] Array of direction cosine matrices at the element nodes.

void vfe_GapSetPropPtr(vfe_Gap *p, Vint type, Vdouble *propptr)

set pointer to element nodal properties

Set a pointer to the start of a specified type of element properties. Note that the properties are not copied by this function, only the pointer itself is copied. If a property pointer is not set the element assumes a default value. By default the temperature is 0., the area is 1., the initial clearance is 0. and the normal is assumed to be computed from the gap endpoint locations.

Errors

`SYS_ERROR_ENUM` is generated if an improper type is specified.

Parameters:
• p – Pointer to object.

• type – Type of element property

```x=VFE_PROP_AREA             Area
=VFE_PROP_TEMPERATURE      Temperatures
=VFE_PROP_NORMAL           Normals
=VFE_PROP_CLEARANCE        Initial clearance
```

• propptr – Pointer to start of element nodal properties

void vfe_GapSetHistPtr(vfe_Gap *p, Vdouble *oldhist, Vdouble *newhist)

set pointers to material history

Set pointers to the start of the material history data at the previous step, oldhist and the current step newhist. This function is required when an underlying material model such as plasticity is used. Note that the material history data is not copied by this function, only the pointers themselves are copied. The number of double precision values required for the material history at a step is the number of history variables at an integration point times the number of element integration points. The number of history variables depends on the underlying material model and may be queried using `vfe_MatlFunNumHist()`. The number of element integration points is returned using `vfe_GapNumIntPnt()`. By default the pointers to the material history are NULL. If the number of history variables is zero, this function need not be called.

Parameters:
• p – Pointer to object.

• oldhist – Pointer to start of material history at previous step

• newhist – Pointer to start of material history at current step

void vfe_GapPowerCond(vfe_Gap *p, Vdouble x[][3], Vdouble u[], Vint kflag, Vdouble r[], Vdouble k[])

thermal power, conductance matrix

Compute the power vector, r, and optionally the conductance matrix, k, given the node coordinates, x, and the degree of freedom temperature vector, u. The lower triangle of the conductance matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• kflag – Flag to compute conductance matrix, k

```=SYS_OFF      Do not compute conductance matrix
=SYS_ON       Compute and return conductance matrix
```

• r[out] Degree of freedom power vector

• k[out] Degree of freedom conductance matrix

void vfe_GapPower(vfe_Gap *p, Vdouble x[][3], Vdouble u[], Vdouble r[])

thermal power vector

Compute the power vector, r, given the node coordinates, x, and the degree of freedom temperature vector, u.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• r[out] Degree of freedom power vector

void vfe_GapCond(vfe_Gap *p, Vdouble x[][3], Vdouble kl[])

thermal conductance matrix

Compute the linear conductance matrix, kl, given the node coordinates, x. The lower triangle of the conductance matrix is returned.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• kl[out] Degree of freedom conductance matrix

void vfe_GapHFlxTGrd(vfe_Gap *p, Vdouble x[][3], Vdouble u[], Vdouble hflx[], Vdouble tgrd[])

Heat flux and temperature difference.

Compute nodal heat fluxes and temperature differences, hflx and tgrd, given the node coordinates, x, and the degree of freedom temperature vector, u.

The hflx is a scalar flux and the tgrd is the associated temperature difference across the gap at each element node.

Errors

• `SYS_ERROR_NULLOBJECT` is generated if a attribute object has not been set.

• `SYS_ERROR_COMPUTE` is generated if a negative Jacobian transformation is computed.

Parameters:
• p – Pointer to object.

• x – Array of node locations.

• u – Degree of freedom vector of temperatures

• hflx[out] Array of nodal heat fluxes

• tgrd[out] Array of nodal temperature difference

void vfe_GapSetLocalSystem(vfe_Gap *p, Vint type, Vdouble vec[], Vdouble angle)

set local coordinate system convention

Specify the convention to be used to construct the orientation of the element local x’,y’,z’ coordinate system.

For stress and strain computation for output using `vfe_GapStrsStrn()`, the local coordinate system is evaluated at each output location and is the coordinate system in which the output stresses and strains at the output location are expressed.

The vec array is only used if the specified type requires position or direction vectors. An additional rotation of the y’,z’ axes about the x’ axis can be specified with angle. By default the local system convention is `SYS_ELEMSYS_STANDARD` with angle set to 0.

For a description of element coordinate systems, type, and associated orientation vector data, please see

Errors

`SYS_ERROR_ENUM` is generated if an improper type is input.

Parameters:
• p – Pointer to object.

• type – Local system convention

• vec – Orientation vector data

• angle – Angle to rotate element y’,z’ axes about the element x’ axis in degrees.