interface

(Not recommended) Specify physical connections between components of mechss model

interface is not recommended. Use addInterface and assemble instead. For more information, see Version History.

Syntax

sysCon = interface(sys,C1,IC1,C2,IC2)

sysCon = interface(sys,C,IC)

sysCon = interface(___,KI,CI)

sysCon = interface(___,method)

Description

sysCon = interface(sys,C1,IC1,C2,IC2) specifies physical couplings between components 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.

example

sysCon = interface(sys,C,IC) specifies that component C interfaces with the ground. Connecting the degrees of freedom q of C to the ground amounts to the zero displacement constraint q(IC) = 0.

sysCon = interface(___,KI,CI) further specifies the stiffness KI and damping CI for nonrigid interfaces.

sysCon = interface(___,method) specifies the assembly method. By default, 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

collapse all

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

collapse all

`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

collapse all

`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

collapse all

Rigid Interface

For n substructures in the physical domain, the sparse matrices in block diagonal form are:

$\begin{array}{l} M ≜ d i a g (M_{1}, ..., M_{n}) = [\begin{matrix} M_{1} & 0 & 0 \\ 0 & ⋱ & 0 \\ 0 & 0 & M_{n} \end{matrix}] \\ C ≜ d i a g (C_{1}, ..., C_{n}) \\ K ≜ d i a g (K_{1}, ..., K_{n}) \\ q ≜ [\begin{matrix} q_{1} \\ ⋮ \\ q_{n} \end{matrix}], B ≜ [\begin{matrix} B_{1} \\ ⋮ \\ B_{n} \end{matrix}], F ≜ [\begin{matrix} F_{1} & \dots & F_{n} \end{matrix}], G ≜ [\begin{matrix} G_{1} & \dots & G_{n} \end{matrix}], \end{array}$

Two interfaced components share a set of DOFs in the global finite element mesh q: the subset N₁ 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:

The displacements q at the shared DOFs are the same for both components.

$q (N_{1}) = q (N_{2})$
The forces g one component exerts on the other are opposite (by the action/reaction principle).

$g (N_{1}) + g (N_{2}) = 0$

These relations can be summarized as:

$\begin{array}{l} M \ddot{q} + C \dot{q} + K q = B u + g, H q = 0, g = - H^{T} λ, \\ y = F q + G \dot{q} + D u, \end{array}$

where H is a localisation matrix with entries 0, 1, or –1. The equation Hq = 0 is equivalent to q(N₁) = q(N₂), and the equation g = −H^T λ is equivalent to g(N₁) = −λ and g(N₂) = λ.

Dual-Assembly Model

The equations

$\begin{array}{l} M \ddot{q} + C \dot{q} + K q = B u + g, H q = 0, g = - H^{T} λ, \\ y = F q + G \dot{q} + D u, \end{array}$

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

$\begin{array}{l} [\begin{matrix} M & 0 \\ 0 & 0 \end{matrix}] [\begin{matrix} \ddot{q} \\ \ddot{λ} \end{matrix}] + [\begin{matrix} C & 0 \\ 0 & 0 \end{matrix}] [\begin{matrix} \dot{q} \\ \dot{λ} \end{matrix}] + [\begin{matrix} K & H^{T} \\ H & 0 \end{matrix}] [\begin{matrix} q \\ λ \end{matrix}] = [\begin{matrix} B \\ 0 \end{matrix}] u \\ y = [\begin{matrix} F & 0 \end{matrix}] [\begin{matrix} q \\ λ \end{matrix}] + [\begin{matrix} G & 0 \end{matrix}] [\begin{matrix} \dot{q} \\ \dot{λ} \end{matrix}] + D u . \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 (N_{1}) = q (N_{2})$

If Hq = 0 is the matrix expression of this constraint, this amounts to writing q = Lq_r. Here, q_r is the set of independent (free) DOFs and L spans the null space of H.

$H L = 0$

Using q = Lq_r, the equations

$\begin{array}{l} \begin{matrix} M \ddot{q} + C \dot{q} + K q = B u + g, & g = - H^{T} λ \end{matrix} \\ y = F q + G \dot{q} + D u \end{array}$

become

$\begin{matrix} M L {\ddot{q}}_{r} + C L {\dot{q}}_{r} + K L q_{r} = B u + g, & y = F L q_{r} + G L {\dot{q}}_{r} + D u . \end{matrix}$

Using L^TH^T = (HL)^T = 0, the first part of equation can be projected onto the range of L by premultiplying by L^T:

$\begin{matrix} (L^{T} M L) {\ddot{q}}_{r} + (L^{T} C L) {\dot{q}}_{r} + (L^{T} K L) q_{r} = L^{T} B u, & y = F L q_{r} + G L {\dot{q}}_{r} + D u . \end{matrix}$

This is the primal-assembly model of the overall structure. It has 2N₁ 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₁(N₁) and q₂(N₂) are allowed to differ and the internal force is given by:

$λ = K_{i} δ + C_{i} \dot{δ}, δ ≜ H q = q_{1} (N_{1}) - q_{2} (N_{2}) .$

This models spring-damper-like connections between DOFs N₁ in the first component and DOFs N₂ in the second component. Going from rigid to non-rigid connection eliminates the algebraic constraints Hq = 0 and explicates the internal forces. Then, eliminate λ to obtain:

$M \ddot{q} + (C + H^{T} C_{i} H) \dot{q} + (K + H^{T} K_{i} H) q = 0, y = F q + G \dot{q} + D u .$

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:

$[\begin{matrix} M & 0 & 0 \\ 0 & 0 & 0 \\ 0 & 0 & 0 \end{matrix}] [\begin{matrix} \ddot{q} \\ \ddot{δ} \\ \ddot{λ} \end{matrix}] + [\begin{matrix} C & 0 & 0 \\ 0 & C_{i} & 0 \\ 0 & 0 & 0 \end{matrix}] [\begin{matrix} \dot{q} \\ \dot{δ} \\ \dot{λ} \end{matrix}] + [\begin{matrix} K & 0 & H^{T} \\ 0 & K_{i} & - I \\ H & - I & 0 \end{matrix}] [\begin{matrix} q \\ δ \\ λ \end{matrix}] = [\begin{matrix} B \\ 0 \\ 0 \end{matrix}] u .$

Version History

Introduced in R2020b

collapse all

R2026a: `interface` is not recommended

interface is not recommended. Use addInterface and assemble instead.

Starting in R2026a, use addInterface and assemble to perform physical assembly of components. Unlike interface, addInterface and assemble can handle more general situations when working in non-nodal (general) coordinates and allow you to create physical assemblies for ss and sparss models. The notion of coupling for mechss models remains the same as with interface, as you can still define the coupling interface using the index of interface nodes using the addInterface function.

interface

Syntax

Description

Examples

Physical Connections Between Components in Sparse Second-Order Model

Input Arguments

`sys` — Sparse second-order model
`mechss` model object

`C` — Components to connect
string | array of character vectors

`IC` — Index information of components to connect
`Nc`-by-`Ni` cell array

`KI` — Stiffness matrix
`Nq`-by-`Nq` sparse matrix

`CI` — Damping matrix
`Nq`-by-`Nq` sparse matrix

`method` — Assembly method
`'dual'` (default) | `'primal'`

Output Arguments

`sysCon` — Output system with physical interfaces
`mechss` model object

Algorithms

Rigid Interface

Nonrigid Interface

Version History

R2026a: `interface` is not recommended

See Also

Topics

interface

Syntax

Description

Examples

Physical Connections Between Components in Sparse Second-Order Model

Input Arguments

sys — Sparse second-order model mechss model object

C — Components to connect string | array of character vectors

IC — Index information of components to connect Nc-by-Ni cell array

KI — Stiffness matrix Nq-by-Nq sparse matrix

CI — Damping matrix Nq-by-Nq sparse matrix

method — Assembly method 'dual' (default) | 'primal'

Output Arguments

sysCon — Output system with physical interfaces mechss model object

Algorithms

Rigid Interface

Nonrigid Interface

Version History

R2026a: interface is not recommended

See Also

Topics

`sys` — Sparse second-order model
`mechss` model object

`C` — Components to connect
string | array of character vectors

`IC` — Index information of components to connect
`Nc`-by-`Ni` cell array

`KI` — Stiffness matrix
`Nq`-by-`Nq` sparse matrix

`CI` — Damping matrix
`Nq`-by-`Nq` sparse matrix

`method` — Assembly method
`'dual'` (default) | `'primal'`

`sysCon` — Output system with physical interfaces
`mechss` model object

R2026a: `interface` is not recommended