addInterface

Add interface for physical assembly

Since R2026a

Syntax

asys = addInterface(sys,PortName,Hy,Hu)

asys = addInterface(sys,PortName,H)

asys = addInterface(sys,PortName,idx)

Description

Use addInterface to augment the inputs and outputs of a state-space model to include the displacements and efforts associated with a particular physical coupling interface. The function adds a forcing term f = H_uλ to the state equation and a vector z = H_yx to the outputs. This facilitates the assembly of components of a structure using the assemble function.

asys = addInterface(sys,PortName,Hy,Hu) adds a physical port for coupling with matrices Hy and Hu. Typically, Hy and Hu specify the displacements and forces at the interface nodes relative to the current state coordinates and equation sorting. For first-order state-space models, the state equation becomes $E \dot{x} = A x + B u + H_{u} λ$ and adds z = H_yx to the output vector.

For mechss models, the function modifies the second-order state equation to $M \ddot{q} + C \dot{q} + K q = B u + H_{u} λ$ and adds z = H_yq to the output vector. To facilitate assembly with assemble, the function also adds input and output groups with name "SysName_PortName", where sys.Name = "SysName".

example

asys = addInterface(sys,PortName,H) uses H_y = H and H_u = H^T. This corresponds to symmetric formulations where forces and displacements at a particular interface appear in the same position in x and f such that $E \dot{x} = A x + f$ .

asys = addInterface(sys,PortName,idx) uses z = x(idx) and f(idx) = f_i, where f is the forcing term in the state equation.

Examples

collapse all

Create Torsional Coupling Between Two Bodies Using Generalized Coupling of Components

Open Live Script

This example shows how to create a generalized coupling between two parts. For this example, you model a connection between inertia 1 and inertia 2 as a generalized torsional coupling. You can represent the system dynamics as follows.

$J_{1} {θ_{}^{¨}}_{1} = T_{1} - T_{c}$

$J_{2} {θ_{}^{¨}}_{2} = T_{2} + T_{c}$

$J_{c} ({θ_{}^{¨}}_{1} - {θ_{}^{¨}}_{2}) + b_{c} ({θ_{}^{˙}}_{1} - {θ_{}^{˙}}_{2}) + k_{c} (θ_{1} - θ_{2}) = T_{c}$

Here:

$J_{1}$ and $J_{2}$ is the inertia of body 1 and 2, respectively.
$θ_{1}$ and $θ_{2}$ is the angular positions of body 1 and 2, respectively.
$T_{1}$ is the input torque and $T_{2}$ is the load torque.
$T_{c}$ is the coupling torque.
$J_{c}$ is the coupling inertia.
$k_{c}$ is the coupling stiffness.
$b_{c}$ is the coupling damping.

Define the model parameters.

J1 = 2;      % kg*m^2
J2 = 1;      % kg*m^2
Jc = 0.1;    % kg*m^2
bc = 0.1;    % N*m*s/rad
kc = 10;     % N*m/rad

Assembly of Individual Components

addInterface augments the inputs and outputs of the model to include the displacements as extra outputs and forces as extra inputs associated with a particular coupling interface.

$\begin{array}{l} E x_{}^{˙} = A x + B u + H_{u} λ \\ y = C x \\ z = H_{y} x \end{array}$

These coupling dynamics model the action-reaction reaction forces $λ$ between two parts. When you use the assembly interface, the software automatically handles the force balance between the two components. For this example, inertia 1 exerts a torque $T_{c}$ on inertia 2, while inertia 2 exerts a torque $- T_{c}$ on inertia 1. Therefore, you can define the individual dynamics and coupling as follows.

Inertia 1

$[\begin{array}{cc} 1 & 0 \\ 0 & J_{1} \end{array}] [\begin{array}{c} {θ_{}^{˙}}_{1} \\ {θ_{}^{¨}}_{1} \end{array}] = [\begin{array}{cc} 0 & 1 \\ 0 & 0 \end{array}] [\begin{array}{c} θ_{1} \\ {θ_{}^{˙}}_{1} \end{array}] + [\begin{array}{c} 0 \\ 1 \end{array}] T_{1} - \underset{H_{u 1} λ}{{[\begin{array}{c} 0 \\ 1 \end{array}] T_{c}}_{⏟}^{}}$

Inertia 2

$[\begin{array}{cc} 1 & 0 \\ 0 & J_{2} \end{array}] [\begin{array}{c} {θ_{}^{˙}}_{2} \\ {θ_{}^{¨}}_{2} \end{array}] = [\begin{array}{cc} 0 & 1 \\ 0 & 0 \end{array}] [\begin{array}{c} θ_{2} \\ {θ_{}^{˙}}_{2} \end{array}] + [\begin{array}{c} 0 \\ 1 \end{array}] T_{2} + \underset{H_{u 2} λ}{{[\begin{array}{c} 0 \\ 1 \end{array}] T_{c}}_{⏟}^{}}$

Coupling

$J_{c} ({θ_{}^{¨}}_{1} - {θ_{}^{¨}}_{2}) + b_{c} ({θ_{}^{˙}}_{1} - {θ_{}^{˙}}_{2}) + k_{c} (θ_{1} - θ_{2}) = T_{c}$

$T_{c} (s) = Q (s) (θ_{1} - θ_{2})$

$Q (s) = J_{c} s^{2} + b_{c} s + k_{c}$

When you assemble parts using a generalized coupling, the software models the coupling dynamics as $λ = Q (s) δ$ , where $λ$ is obtained as the output of linear system driven by the gap $δ = z_{1} - z_{2} = θ_{1} - θ_{2}$ .

Create the state-space model and define the interface for inertia 1.

E1 = [1 0; 0 J1];
A1 = [0 1; 0 0];
B1 = [0;1];
C1 = [0 1]; % output angular velocity w1
D1 = 0;
sys1 = dss(A1,B1,C1,D1,E1);
sys1.Name = "inertia1";
sys1.InputName = "Input Torque";
sys1.OutputName = "w1";
Hu1 = [0;1]; 
Hy1 = [1 0]; % z1 = theta1
sys1 = addInterface(sys1,"w1tow2",Hy1,Hu1)

sys1 =
 
  A = 
       x1  x2
   x1   0   1
   x2   0   0
 
  B = 
       Input Torque  inertia1:w1t
   x1             0             0
   x2             1             1
 
  C = 
                 x1  x2
   w1             0   1
   inertia1:w1t   1   0
 
  D = 
                 Input Torque  inertia1:w1t
   w1                       0             0
   inertia1:w1t             0             0
 
  E = 
       x1  x2
   x1   1   0
   x2   0   2
 
Input groups:                
        Name         Channels
   inertia1_w1tow2      2    
Output groups:               
        Name         Channels
   inertia1_w1tow2      2    
Name: inertia1
Continuous-time state-space model.
Model Properties

The addInterface function adds an extra input and output to facilitate the coupling at this interface.

Similarly, define the interface for inertia 2.

E2 = [1 0; 0 J2];
A2 = [0 1; 0 0];
B2 = [0;1];
C2 = [0 1]; % output angular velocity w1
D2 = 0;
sys2 = dss(A2,B2,C2,D2,E2);
sys2.Name = "inertia2";
sys2.InputName = "Load Torque";
sys2.OutputName = "w2";
Hu2 = [0;1];
Hy2 = [1 0]; % z2 = theta2
sys2 = addInterface(sys2,"w2tow1",Hy2,Hu2)

sys2 =
 
  A = 
       x1  x2
   x1   0   1
   x2   0   0
 
  B = 
        Load Torque  inertia2:w2t
   x1             0             0
   x2             1             1
 
  C = 
                 x1  x2
   w2             0   1
   inertia2:w2t   1   0
 
  D = 
                  Load Torque  inertia2:w2t
   w2                       0             0
   inertia2:w2t             0             0
 
  E = 
       x1  x2
   x1   1   0
   x2   0   1
 
Input groups:                
        Name         Channels
   inertia2_w2tow1      2    
Output groups:               
        Name         Channels
   inertia2_w2tow1      2    
Name: inertia2
Continuous-time state-space model.
Model Properties

Define the coupling and assemble the model components.

Q = tf([Jc bc kc],1);
asys = assemble(sys1,sys2,"inertia1:w1tow2","inertia2:w2tow1",Q,Method="primal");

Compare with Full Dynamics Model

You can represent the model that accounts for generalized torsional dynamics in the following state-space form.

$\begin{array}{l} [\begin{array}{cccc} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & J_{1} + J_{c} & - J_{c} \\ 0 & 0 & - J_{c} & J_{2} + J_{c} \end{array}] [\begin{array}{c} {θ_{}^{˙}}_{1} \\ {θ_{}^{˙}}_{2} \\ {θ_{}^{¨}}_{1} \\ {θ_{}^{¨}}_{2} \end{array}] = [\begin{array}{cccc} 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \\ - k_{c} & k_{c} & - b_{c} & b_{c} \\ k_{c} & - k_{c} & b_{c} & - b_{c} \end{array}] [\begin{array}{c} θ_{1} \\ θ_{2} \\ {θ_{}^{˙}}_{1} \\ {θ_{}^{˙}}_{2} \end{array}] + [\begin{array}{cc} 0 & 0 \\ 0 & 0 \\ 1 & 0 \\ 0 & 1 \end{array}] [\begin{array}{c} T_{1} \\ T_{2} \end{array}] \\ y = [\begin{array}{cccc} 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{array}] [\begin{array}{c} θ_{1} \\ θ_{2} \\ {θ_{}^{˙}}_{1} \\ {θ_{}^{˙}}_{2} \end{array}] \end{array}$

Define the state-space matrices and create the model.

Ec = [ 1  0   0    0;
      0  1    0    0;
      0  0  J1+Jc  -Jc;
      0  0   -Jc   J2+Jc ];

Ac = [ 0  0   1    0;
      0  0   0    1;
    -kc kc -bc  bc;
     kc -kc  bc -bc ];

Bc = [ 0  0;
      0  0;
      1  0;
      0  1 ];
Cc = [0 0 1 0;
    0 0 0 1];
Dc = 0;
sysc = dss(Ac, Bc, Cc, Dc,Ec);

Comparing the Bode response of both models, you can see they are equivalent.

opt = bodeoptions;
opt.PhaseWrapping = "on";
bodeplot(asys,sysc,"r--",opt)

MATLAB figure

Simulate both models to a sinusoidal torque $T_{1}$ applied to inertia 1 and zero load torque $T_{2}$ .

t = 0:0.01:15;
u = [sin(t); zeros(size(t))];
ya = lsim(asys,u',t);
yc = lsim(sysc,u',t);
tiledlayout(2,1)
nexttile
plot(t,ya(:,1),t,yc(:,1),'r--');
title("\omega_1")
nexttile
plot(t,ya(:,2),t,yc(:,2),'r--');
title("\omega_2")
legend("Assembled model","Complete model")

Figure contains 2 axes objects. Axes object 1 with title omega indexOf 1 baseline contains 2 objects of type line. Axes object 2 with title omega indexOf 2 baseline contains 2 objects of type line. These objects represent Assembled model, Complete model.

You can see that both approaches result in an equivalent model. Assembly of individual components is helpful when you want to couple several parts with some coupling dynamics.

Create Mass-Spring-Damper Model Using Compliant Coupling

Open Live Script

This example shows how to create a mass-spring-damper model using compliant coupling between a mass and a wall.

You can model this equation by:

$m x_{}^{¨} = F - F_{c}$

$x_{}^{¨} = \frac{1}{m} F + \frac{1}{m} (- F_{c})$

In this coupling, the mass exerts a force $F_{c}$ on the wall, while the wall exerts a force $- F_{c}$ on the mass. Modeling the mass and coupling dynamics separately, you get:

$\begin{array}{l} x_{}^{¨} = \frac{1}{m} F + \underset{H_{u} λ}{{\frac{1}{m} (- F_{c})}_{⏟}^{}} \\ y = x \\ z_{1} = x \end{array}$

$λ = (k (z_{1} - z_{2}) - b ({z_{1}}_{}^{˙} - {z_{}^{˙}}_{2}))$

Since the mass is connected to a wall (ground), $z_{2} = 0$ .

Define the model parameters.

m = 3;
c = 1;
k = 2;

Create the state-space model and define the coupling interface.

A = [0 1; 0 0];
B = [0; 1/m];
C = [1 0];
D = 0;
Hy = [1 0];
Hu = [0; 1/m];
sys = ss(A,B,C,D);
sys.Name = "mass";
sys.InputName = "force";
sys.OutputName = "displacement";
isys = addInterface(sys,"masstowall",Hy,Hu);

Since the mass is connected to a wall, connect the coupling interface port to the ground to create the assembled model.

asys = assemble(isys,"mass:masstowall","Ground",k,c);

Compare with Complete Model

The equation of motion that accounts for full dynamics is given by:

$m x_{}^{¨} = F - k x - c x_{}^{˙}$

Create the state-space model.

Ac = [0 1; -k/m -c/m];
Bc = [0;1/m];
Cc = [1 0];
Dc = 0;
sysc = ss(Ac,Bc,Cc,Dc);

Simulating the impulse response of both models, you can see they are equivalent.

impulseplot(asys,sysc,"r--")
legend("Assembled components","Complete system")

MATLAB figure

Create Motor-Load-Shaft System with Gear Ratio and Compliant Coupling

Open Live Script

This example shows how to couple a motor and a load using compliant coupling. The and motor and load are connected by a gearbox, with coupling stiffness $k_{c}$ and gear ratio $N$ .

You can define the equations for this system as follows:

$J_{m} {θ_{m}}_{}^{¨} = T_{in} - T_{c}$

$J_{l} {θ_{l}}_{}^{¨} = \frac{1}{N} T_{c} - T_{l o a d}$

$T_{c} = k_{c} (θ_{m} - N θ_{l})$

Here:

$J_{m}$ is the motor inertia
$J_{l}$ is the load inertia
$T_{c}$ is the coupling torque
$k_{c}$ is the coupling stiffness
$N$ is the gear ratio, where motor rotates $N$ times faster than the load side
$θ_{m}$ is the motor shaft angle
$θ_{l}$ is the load shaft angle

Define the model parameters

Jm = 0.01;      % kg*m^2
Jl = 0.05;      % kg*m^2
kc = 10;        % N*m/rad
N  = 2;         % Gear ratio

Assembly of Individual Components

When you model this as an internal coupling, you can define the equations as follows.

${θ_{}^{¨}}_{m} = \frac{1}{J_{m}} T_{i n} - \underset{H_{u 1} λ}{{\frac{1}{J_{m}} (T_{c})}_{⏟}^{}}$

${θ_{}^{¨}}_{l} = \underset{H_{u 2} λ}{{\frac{1}{J_{l} N} (T_{c})}_{⏟}^{}} - \frac{1}{J_{l}} T_{l o a d}$

Here, $T_{c} = λ = k_{c} δ$ and the collocation gap $δ = z_{1} - z_{2}$ is defined relative to the state values, with $z_{1} = θ_{m}$ and $z_{2} = N θ_{l}$ .

Create the state-space model and define the coupling interface on the motor side.

Am = [0 1; 0 0];
Bm = [0; 1/Jm];
Cm = [1 0];
Dm = 0;
Hu1 = [0;1/Jm];
Hy1 = [1 0];   % z1 = theta_m
sysm = ss(Am,Bm,Cm,Dm);
sysm.Name = "motor";
sysm.InputName = "Input Torque";
sysm.OutputName = "Motor speed";
sysma = addInterface(sysm,"motortoload",Hy1,Hu1);

Similarly, define the coupling interface on the load side.

Al = [0 1; 0 0];
Bl = [0; -1/Jl];
Cl = [1 0];
Dl = 0;
Hu2 = [0;1/(Jl*N)];
Hy2 = [N 0];    % z2 = N*theta_l
sysl = ss(Al,Bl,Cl,Dl);
sysl.Name = "load";
sysl.InputName = "Load Torque";
sysl.OutputName = "Load speed";
sysla = addInterface(sysl,"loadtomotor",Hy2,Hu2);

Create the model assembly with compliant coupling with stiffness K = $k_{c}$ . When you do not specify a value for damping C, the software uses C = 0.

asys = assemble(sysma,sysla,"motor:motortoload","load:loadtomotor",kc);

Complete Model with Full Dynamics

You can define the model that accounts for full coupling dynamics in the state-space form as follows.

$\begin{array}{l} x_{}^{˙} = [\begin{array}{cccc} 0 & 1 & 0 & 0 \\ - \frac{k_{c}}{J_{m}} & 0 & \frac{k_{c} N}{J_{m}} & 0 \\ 0 & 0 & 0 & 1 \\ \frac{k_{c}}{J_{l} N} & 0 & - \frac{k_{c}}{J_{l}} & 0 \end{array}] [\begin{array}{c} θ_{m} \\ {θ_{}^{˙}}_{m} \\ θ_{l} \\ {θ_{}^{˙}}_{l} \end{array}] + [\begin{array}{cc} 0 & 0 \\ \frac{1}{J_{m}} & 0 \\ 0 & 0 \\ 0 & - \frac{1}{J_{l}} \end{array}] \\ y = [\begin{array}{cccc} 1 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 \end{array}] [\begin{array}{c} θ_{m} \\ {θ_{}^{˙}}_{m} \\ θ_{l} \\ {θ_{}^{˙}}_{l} \end{array}] \end{array}$

Create the state-space model.

Ac = [ 0,      1,      0,       0;
     -kc/Jm,   0,  (kc*N)/Jm,   0;
      0,       0,      0,       1;
   kc/(N*Jl),  0,   -kc/Jl,     0 ];

Bc = [ 0,      0;
      1/Jm,    0;
      0,       0;
      0,     -1/Jl ];

Cc = [1 0 0 0;
      0 0 1 0];
Dc = 0;
sysc = ss(Ac, Bc, Cc, Dc);

Compare Models

Simulate both models to a sinusoidal input torque and zero load torque.

t = 0:0.001:15;
u = [sin(t); zeros(size(t))];
yc = lsim(sysc,u',t);
ya = lsim(asys,u',t);

Compute the torsional deflection $θ_{d} = θ_{m} - N θ_{l}$ and plot the results.

ya_def = ya(:,1)-N.*ya(:,2);
yc_def = yc(:,1)-N.*yc(:,2);
plot(t,ya_def,t,yc_def,'r--');
title("Torsional Deflection")

Figure contains an axes object. The axes object with title Torsional Deflection contains 2 objects of type line.

As you can see, both approaches result in an equivalent model. Notice the sustained oscillations in the torsional deflection. This the because there is no damping in the system.

Physical Connections Between Components in Sparse Second-Order Model

Open Live Script

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

Define interfaces.

Plate1 = mechss(M1,[],K1,B1,F1,'Name','Plate1');
Plate2 = mechss(M2,[],K2,B2,F2,'Name','Plate2');

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 ct=1:4
    % Plates to pillars
    Plate1 = addInterface(Plate1,"Pillar"+ct,dofs{1,2+ct});
    Plate2 = addInterface(Plate2,"Pillar"+ct,dofs{2,2+ct});
end

P = cell(4,1);
for ct=1:4
    % Pillars to plates
    P{ct} = mechss(Mp,[],Kp,Bp,Fp,'Name',"Pillar"+ct);
    P{ct} = addInterface(P{ct},"TopMount",dofs{2+ct,1});
    P{ct} = addInterface(P{ct},"BottomMount",dofs{2+ct,2});
end
% Plate 2 to ground

Specify connection between the bottom plate and the ground.

Plate2 = addInterface(Plate2,"Ground",dofs{2,7});

% Assemble
model = append(Plate1,Plate2,P{:});

Use showStateInfo to confirm the physical interfaces.

showStateInfo(model)

The state groups are:

    Type        Name      Size
  ----------------------------
  Component    Plate1     2646
  Component    Plate2     2646
  Component    Pillar1     132
  Component    Pillar2     132
  Component    Pillar3     132
  Component    Pillar4     132

sysConDual = model;
for ct=1:4
    sysConDual = assemble(sysConDual,"Plate1:Pillar"+ct,"Pillar"+ct+":TopMount"');
    sysConDual = assemble(sysConDual,"Plate2:Pillar"+ct,"Pillar"+ct+":BottomMount");
end
sysConDual = assemble(sysConDual,"Plate2:Ground","Ground");

Use showStateInfo to confirm the physical interfaces.

showStateInfo(sysConDual)

The state groups are:

    Type                      Name                   Size
  -------------------------------------------------------
  Component                  Plate1                  2646
  Component                  Plate2                  2646
  Component                 Pillar1                   132
  Component                 Pillar2                   132
  Component                 Pillar3                   132
  Component                 Pillar4                   132
  Interface     Plate1:Pillar1-Pillar1:TopMount        12
  Interface    Plate2:Pillar1-Pillar1:BottomMount      12
  Interface     Plate1:Pillar2-Pillar2:TopMount        12
  Interface    Plate2:Pillar2-Pillar2:BottomMount      12
  Interface     Plate1:Pillar3-Pillar3:TopMount        12
  Interface    Plate2:Pillar3-Pillar3:BottomMount      12
  Interface     Plate1:Pillar4-Pillar4:TopMount        12
  Interface    Plate2:Pillar4-Pillar4:BottomMount      12
  Interface           Plate2:Ground-Ground              6

You can use spy to visualize the sparse matrices in the final model.

spy(sysConDual)

Figure contains an axes object. The axes object with title nnz: M=95256, K=249052, B=1, F=1., xlabel Right-click to select matrices contains 37 objects of type line. One or more of the lines displays its values using only markers These objects represent K, B, F, D.

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

sysConPrimal = model;
for ct=1:4
    sysConPrimal = assemble(sysConPrimal,"Plate1:Pillar"+ct,"Pillar"+ct+":TopMount"',Method="primal");
    sysConPrimal = assemble(sysConPrimal,"Plate2:Pillar"+ct,"Pillar"+ct+":BottomMount",Method="primal");
end
sysConPrimal = assemble(sysConPrimal,"Plate2:Ground","Ground",Method="primal");

Use showStateInfo to confirm the physical interfaces.

showStateInfo(sysConPrimal)

The state groups are:

    Type       Name    Size
  -------------------------
  Component            5718

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)

Figure contains an axes object. The axes object with title nnz: M=94666, K=247126, B=1, F=1., xlabel Right-click to select matrices contains 9 objects of type line. One or more of the lines displays its values using only markers These objects represent K, B, F, D.

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

Input Arguments

collapse all

`sys` — State-space model
`ss` model object | `sparss` model object | `mechss` model object

State-space model for which you want to define a physical port or an interface for assembly with other parts, specified as an ss, sparss, or mechss model object. You must provide a named model. To specify a model name, use sys.Name = "modelName".

`PortName` — Name of physical coupling port
string

Name of the physical coupling port, specified as a string. The string PortName labels the physical coupling port for assembly using the assemble function and adds the input and output groups with name modelName_PortName, where modelName is the name of model sys defined using the sys.Name property. You must specify a unique PortName that is not already defined in sys.

`Hy` — Displacements at physical coupling interface
matrix

Displacements at physical coupling interface, specified as a matrix of size n_x-by-n_y, where n_x is the number of states (x) or degrees of freedom (q) and n_y is the number of displacements at the physical coupling interface.

The function adds the displacements z = H_yx as extra outputs to sys, where H_y defines the displacements at the interface location relative to the current state coordinates.

`Hu` — Forces at physical coupling interface
matrix

Forces at physical coupling interface, specified as a matrix of size n_i-by-n_x, where n_x is the number of states (x) or degrees of freedom (q) and n_i is the number of internal forces for physical coupling.

The function adds the forces f = H_uλ as extra inputs to sys, where H_u defines the forces at the interface location relative to the current state coordinates.

`H` — Symmetric forces and displacements
matrix

Symmetric forces and displacements, specified as a matrix with H_y = H and H_u = H^T. This corresponds to symmetric formulations where forces and displacements at a particular interface appear in the same position in x and f such that $E \dot{x} = A x + f$ .

`idx` — State or node index
vector of integers

Index information of components to connect, specified as a vector of integers. To define the physical coupling, the function uses z = x(idx) and f(idx) = f_i, where f is the forcing term in the state equation.

Output Arguments

collapse all

`asys` — Augmented system with interfaces
`ss` model object | `sparss` model object | `mechss` model object

Augmented system with interfaces, returned as a model of the same type as sys. The augmented model contains:

Extra inputs for the forcing term f = H_uλ
Extra outputs for the displacements z = H_yx.
Input and output groups with name modelName_PortName to facilitate assembly with assemble.

Version History

Introduced in R2026a

addInterface

Syntax

Description

Examples

Create Torsional Coupling Between Two Bodies Using Generalized Coupling of Components

Create Mass-Spring-Damper Model Using Compliant Coupling

Create Motor-Load-Shaft System with Gear Ratio and Compliant Coupling

Physical Connections Between Components in Sparse Second-Order Model

Input Arguments

`sys` — State-space model
`ss` model object | `sparss` model object | `mechss` model object

`PortName` — Name of physical coupling port
string

`Hy` — Displacements at physical coupling interface
matrix

`Hu` — Forces at physical coupling interface
matrix

`H` — Symmetric forces and displacements
matrix

`idx` — State or node index
vector of integers

Output Arguments

`asys` — Augmented system with interfaces
`ss` model object | `sparss` model object | `mechss` model object

Version History

See Also

Topics

addInterface

Syntax

Description

Examples

Create Torsional Coupling Between Two Bodies Using Generalized Coupling of Components

Create Mass-Spring-Damper Model Using Compliant Coupling

Create Motor-Load-Shaft System with Gear Ratio and Compliant Coupling

Physical Connections Between Components in Sparse Second-Order Model

Input Arguments

sys — State-space model ss model object | sparss model object | mechss model object

PortName — Name of physical coupling port string

Hy — Displacements at physical coupling interface matrix

Hu — Forces at physical coupling interface matrix

H — Symmetric forces and displacements matrix

idx — State or node index vector of integers

Output Arguments

asys — Augmented system with interfaces ss model object | sparss model object | mechss model object

Version History

See Also

Topics

`sys` — State-space model
`ss` model object | `sparss` model object | `mechss` model object

`PortName` — Name of physical coupling port
string

`Hy` — Displacements at physical coupling interface
matrix

`Hu` — Forces at physical coupling interface
matrix

`H` — Symmetric forces and displacements
matrix

`idx` — State or node index
vector of integers

`asys` — Augmented system with interfaces
`ss` model object | `sparss` model object | `mechss` model object