# interface

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

### Rigid Interface

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}$$

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

These relations can be summarized as:

$$\begin{array}{l}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 ,\\ y=Fq+G\dot{q}+Du,\end{array}$$

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*.

_{2}) = λ**Dual-Assembly Model**

The equations

$$\begin{array}{l}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 ,\\ y=Fq+G\dot{q}+Du,\end{array}$$

can be combined in the differential-algebraic equation (DAE) form:

$$\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.

**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$$

Using *q = Lq _{r}*, the equations

$$\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 overall structure. 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*.

### 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, you can use the equivalent 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.$$

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