# interface

Specify physical connections between components of `mechss`

model

## Syntax

## Description

specifies physical couplings between components `sysCon`

= interface(`sys`

,C1,IC1,C2,IC2)`C1`

and
`C2`

in the second-order sparse model `sys`

.
`IC1`

and `IC2`

contain the indices of the coupled
degrees of freedom (DOFs) relative to the DOFs of `C1`

and
`C2`

. The physical interface is assumed rigid and satisfies the standard
consistency and equilibrium conditions. `sysCon`

is the resultant model
with the specified physical connections. Use `showStateInfo`

to get the list of all available components of `sys`

.

specifies the assembly method. By default, `sysCon`

= interface(___,`method`

)`method`

=
`'dual'`

and the function uses the dual-assembly method of physical
coupling. Set `method`

= `'primal'`

to use the
primal-assembly method of physical coupling. For more information, see Algorithms.

## Examples

### Physical Connections Between Components in Sparse Second-Order Model

For this example, consider a structural model that consists of two square plates connected with pillars at each vertex as depicted in the figure below. The lower plate is attached rigidly to the ground while the pillars are attached rigidly to each vertex of the square plate.

Load the finite element model matrices contained in `platePillarModel.mat`

and create the sparse second-order model representing the above system.

load('platePillarModel.mat') model = ... mechss(M1,[],K1,B1,F1,'Name','Plate1') + ... mechss(M2,[],K2,B2,F2,'Name','Plate2') + ... mechss(Mp,[],Kp,Bp,Fp,'Name','Pillar3') + ... mechss(Mp,[],Kp,Bp,Fp,'Name','Pillar4') + ... mechss(Mp,[],Kp,Bp,Fp,'Name','Pillar5') + ... mechss(Mp,[],Kp,Bp,Fp,'Name','Pillar6'); sys = model;

Use `showStateInfo`

to examine the components of the `mechss`

model object.

showStateInfo(sys)

The state groups are: Type Name Size ---------------------------- Component Plate1 2646 Component Plate2 2646 Component Pillar3 132 Component Pillar4 132 Component Pillar5 132 Component Pillar6 132

Now, load the interfaced degree of freedom (DOF) index data from `dofData.mat`

and use `interface`

to create the physical connections between the two plates and the four pillars. `dofs`

is a `6x7`

cell array where the first two rows contain DOF index data for the first and second plates while the remaining four rows contain index data for the four pillars. By default, the function uses dual-assembly method of physical coupling.

load('dofData.mat','dofs') for i=3:6 sys = interface(sys,"Plate1",dofs{1,i},"Pillar"+i,dofs{i,1}); sys = interface(sys,"Plate2",dofs{2,i},"Pillar"+i,dofs{i,2}); end

Specify connection between the bottom plate and the ground.

`sysConDual = interface(sys,"Plate2",dofs{2,7});`

Use `showStateInfo`

to confirm the physical interfaces.

showStateInfo(sysConDual)

The state groups are: Type Name Size ----------------------------------- Component Plate1 2646 Component Plate2 2646 Component Pillar3 132 Component Pillar4 132 Component Pillar5 132 Component Pillar6 132 Interface Plate1-Pillar3 12 Interface Plate2-Pillar3 12 Interface Plate1-Pillar4 12 Interface Plate2-Pillar4 12 Interface Plate1-Pillar5 12 Interface Plate2-Pillar5 12 Interface Plate1-Pillar6 12 Interface Plate2-Pillar6 12 Interface Plate2-Ground 6

You can use `spy`

to visualize the sparse matrices in the final model.

spy(sysConDual)

Now, specify physical connections using the primal-assembly method.

sys = model; for i=3:6 sys = interface(sys,"Plate1",dofs{1,i},"Pillar"+i,dofs{i,1},'primal'); sys = interface(sys,"Plate2",dofs{2,i},"Pillar"+i,dofs{i,2},'primal'); end sysConPrimal = interface(sys,"Plate2",dofs{2,7},'primal');

Use `showStateInfo`

to confirm the physical interfaces.

showStateInfo(sysConPrimal)

The state groups are: Type Name Size ---------------------------- Component Plate1 2646 Component Plate2 2640 Component Pillar3 108 Component Pillar4 108 Component Pillar5 108 Component Pillar6 108

Primal assembly eliminates half of the redundant DOFs associated with the shared set of DOFs in the global finite element mesh.

You can use `spy`

to visualize the sparse matrices in the final model.

spy(sysConPrimal)

The data set for this example was provided by Victor Dolk from ASML.

## Input Arguments

`sys`

— Sparse second-order model

`mechss`

model object

Sparse second-order model, specified as a `mechss`

model object.
For more information, see `mechss`

.

`C`

— Components to connect

string | array of character vectors

Components of `sys`

to connect, specified as a string or an array
of character vectors. Use `showStateInfo`

to get the list of all available components of
`sys`

.

`IC`

— Index information of components to connect

`Nc`

-by-`Ni`

cell array

Index information of components to connect, specified as an
`Nc`

-by-`Ni`

cell array, where `Nc`

is the number of components and `Ni`

is the number of physical
interfaces.

`KI`

— Stiffness matrix

`Nq`

-by-`Nq`

sparse matrix

Stiffness matrix, specified as an `Nq`

-by-`Nq`

sparse matrix, where `Nq`

is the number of DOFs in
`sys`

.

`CI`

— Damping matrix

`Nq`

-by-`Nq`

sparse matrix

Damping matrix, specified as an `Nq`

-by-`Nq`

sparse matrix, where `Nq`

is the number of DOFs in
`sys`

.

`method`

— Assembly method

`'dual'`

(default) | `'primal'`

Interface assembly method, specified as one of the following:

`'dual'`

— Use the dual-assembly method of physical coupling. This method maintains sparsity at the expense of additional algebraic variables.`'primal'`

— Use the primal-assembly method of physical coupling. This method uses a minimal number of DOFs but the system may suffer from fill-in.

For more information, see Algorithms.

## Output Arguments

`sysCon`

— Output system with physical interfaces

`mechss`

model object

Output system with physical interfaces, returned as a `mechss`

model object. Use `showStateInfo`

to examine the list of physical interfaces in the
system.

## Algorithms

### Dual-Assembly Model

**Rigid interface**

By default, `interface`

uses
the concept of *dual assembly* to physically connect the degrees of
freedom (DOFs) of the model components. For *n* substructures in the
physical domain, the sparse matrices in block diagonal form are:

$$\begin{array}{l}M\text{}\triangleq \text{}diag\left({M}_{1},\mathrm{...},{M}_{n}\right)=\left[\begin{array}{ccc}{M}_{1}& 0& 0\\ 0& \ddots & 0\\ 0& 0& {M}_{n}\end{array}\right]\\ C\text{}\triangleq \text{}diag\left({C}_{1},\mathrm{...},{C}_{n}\right)\\ \\ K\text{}\triangleq \text{}diag\left({K}_{1},\mathrm{...},{K}_{n}\right)\\ q\text{}\triangleq \text{}\left[\begin{array}{c}{q}_{1}\\ \vdots \\ {q}_{n}\end{array}\right],\text{B}\triangleq \text{}\left[\begin{array}{c}{B}_{1}\\ \vdots \\ {B}_{n}\end{array}\right]\text{,F}\triangleq \text{}\left[\begin{array}{ccc}{F}_{1}& \cdots & {F}_{n}\end{array}\right],\text{G}\triangleq \text{}\left[\begin{array}{ccc}{G}_{1}& \cdots & {G}_{n}\end{array}\right],\end{array}$$

where *f* is the force vector dependent on time and
*g* is the vector of internal forces at the interface.

Two interfaced components share a set of DOFs in the global finite element mesh
*q*: the subset *N _{1}* of DOFs from
the first component coincides with the subset

*N*of DOFs from the second component. The coupling between the two components is rigid only if:

_{2}The displacements

*q*at the shared DOFs are the same for both components.$$q\left({N}_{1}\right)=q\left({N}_{2}\right)$$

The forces

*g*one component exerts on the other are opposite (by the action/reaction principle).$$g\left({N}_{1}\right)+g\left({N}_{2}\right)=0$$

This relation can be summarized as:

$$M\text{}\ddot{q}+C\text{}\dot{q}+K\text{}q=B\text{}u+g,\text{}H\text{}q=0,\text{}g=-{H}^{T}\lambda ,$$

where *H* is a localisation matrix with entries 0, 1,
or –1. The equation *Hq* = 0 is equivalent to
*q(N _{1}) = q(N_{2})*, and the
equation

*g = −H*is equivalent to

^{T}λ*g(N*and

_{1}) = −λ*g(N*. These equations can be combined in the differential-algebraic equation (DAE) form:

_{2}) = λ$$\begin{array}{l}\left[\begin{array}{cc}M& 0\\ 0& 0\end{array}\right]\left[\begin{array}{c}\ddot{q}\\ \ddot{\lambda}\end{array}\right]+\left[\begin{array}{cc}C& 0\\ 0& 0\end{array}\right]\left[\begin{array}{c}\dot{q}\\ \dot{\lambda}\end{array}\right]+\left[\begin{array}{cc}K& {H}^{T}\\ H& 0\end{array}\right]\left[\begin{array}{c}q\\ \lambda \end{array}\right]=\left[\begin{array}{c}B\\ 0\end{array}\right]u\\ y=\left[\begin{array}{cc}F& 0\end{array}\right]\left[\begin{array}{c}q\\ \lambda \end{array}\right]+\left[\begin{array}{cc}G& 0\end{array}\right]\left[\begin{array}{c}\dot{q}\\ \dot{\lambda}\end{array}\right]+Du.\end{array}$$

This DAE model is called the *dual assembly* model of
the overall structure. While the principle was explained for two components, this model can
accommodate multiple interfaces, including interfaces involving more than two
components.

**Nonrigid Interface**

In non-rigid interfaces, the displacements
*q _{1}(N_{1})* and

*q*are allowed to differ and the internal force is given by:

_{2}(N_{2})$$\lambda \text{}=\text{}{K}_{i}\delta +{C}_{i}\dot{\delta},\delta \triangleq Hq={q}_{1}\left({N}_{1}\right)-{q}_{2}\left({N}_{2}\right).$$

This models spring-damper-like connections between DOFs
*N _{1}* in the first component and DOFs

*N*in the second component. Going from rigid to non-rigid connection eliminates the algebraic constraints

_{2}*Hq = 0*and explicates the internal forces. Then, eliminate

*λ*to obtain:

$$M\text{}\ddot{q}+\left(C+{H}^{T}{C}_{i}H\right)\dot{q}+\left(K+{H}^{T}{K}_{i}H\right)q=0,\text{}y=Fq+G\dot{q}+Du.$$

This is the set of the *primal-assembly* equations for non-rigid
coupling form that remains symmetric when the uncoupled model is symmetric. A drawback of
this form is that the coupling terms $${H}^{T}{C}_{i}H$$ and $${H}^{T}{K}_{i}H$$ may cause fill-in. To avoid this, `interface`

instead
constructs the dual-assembly form:

$$\left[\begin{array}{ccc}M& 0& 0\\ 0& 0& 0\\ 0& 0& 0\end{array}\right]\left[\begin{array}{c}\ddot{q}\\ \ddot{\delta}\\ \ddot{\lambda}\end{array}\right]+\left[\begin{array}{ccc}C& 0& 0\\ 0& {C}_{i}& 0\\ 0& 0& 0\end{array}\right]\left[\begin{array}{c}\dot{q}\\ \dot{\delta}\\ \dot{\lambda}\end{array}\right]+\left[\begin{array}{ccc}K& 0& {H}^{T}\\ 0& {K}_{i}& -I\\ H& -I& 0\end{array}\right]\left[\begin{array}{c}q\\ \delta \\ \lambda \end{array}\right]=\left[\begin{array}{c}B\\ 0\\ 0\end{array}\right]u.$$

### Primal-Assembly Model

For rigid interfaces, *primal assembly* consists of eliminating half
of the redundant DOFs associated with the following constraint.

$$q\left({N}_{1}\right)=q\left({N}_{2}\right)$$

If *Hq* = 0 is the matrix expression of this constraint, this amounts
to writing *q = Lq _{r}*. Here,

*q*is the set of independent (free) DOFs and

_{r}*L*spans the null space of

*H*.

$$HL=0$$

Since the nonzero part of *H* is of the form *(I –I)*,
*L* can be constructed by starting from the identity matrix of size
*q*, moving the block
*(N _{2},N_{2})* to the position

*(N*, and deleting the zero columns with index

_{2},N_{1})*N*. Using

_{2}*q = Lq*, the equations

_{r}$$\begin{array}{l}\begin{array}{cc}M\ddot{q}+C\dot{q}+Kq=Bu+g,& g=-{H}^{T}\lambda \end{array}\\ y=Fq+G\dot{q}+Du\end{array}$$

become

$$\begin{array}{cc}ML{\ddot{q}}_{r}+CL{\dot{q}}_{r}+KL{q}_{r}=Bu+g,& y=FL{q}_{r}+GL{\dot{q}}_{r}+Du.\end{array}$$

Using *L ^{T}H^{T} =
(HL)^{T}* = 0, the first part of equation can be
projected onto the range of

*L*by premultiplying by

*L*:

^{T}$$\begin{array}{cc}({L}^{T}ML){\ddot{q}}_{r}+({L}^{T}CL){\dot{q}}_{r}+({L}^{T}KL){q}_{r}={L}^{T}Bu,& y=FL{q}_{r}+GL{\dot{q}}_{r}+Du.\end{array}$$

This is the *primal-assembly* model of the
`interface`

. It has 2*N _{1}* fewer
algebraic variables than its dual-assembly counterpart, at the expense of potential fill-in
in the reduced

*M*,

*C*, and

*K*.

For the non-rigid interfaces, use the explicit expression for *λ* and
*g* to obtain the primal assembly equations:

$$M\text{}\ddot{q}+\left(C+{H}^{T}{C}_{i}H\right)\dot{q}+\left(K+{H}^{T}{K}_{i}H\right)q=0,\text{}y=Fq+G\dot{q}+Du.$$

Here the interface damping and stiffness modify *C* and
*K*, and the number of DOFs remains unchanged.

## Version History

**Introduced in R2020b**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)