modalsep
Syntax
Description
[
computes the modal decomposition for a linear timeinvariant (LTI) system
H
,H0
] = modalsep(G
)G
and returns the modal components as a statespace array
H
and the static gain H0
.
$$G(s)={H}_{0}+{\displaystyle \sum _{j=1}^{m}{H}_{j}(s)}$$
Each modal component in H_{j}(s) is associated with a single real pole, a pair of complex conjugate poles, or a cluster repeated poles.
[
returns the modal decomposition based on the options specified by one or more namevalue
arguments. Use these options to control the granularity and accuracy of the
decomposition.H
,H0
] = modalsep(G
,Name=Value
)
[
computes the regionbased modal decompositionH
,H0
] = modalsep(G
,N
,regionFcn
)
$$G(s)={H}_{0}+{\displaystyle \sum _{j=1}^{N}{H}_{j}(s)}$$
Here, the modal components
H_{j}(s) have their poles in
disjoint regions R_{j} of the complex plane.
N
specifies the number of regions and
regionFcn
is the name or a handle to the function that specifies
the partition into N
regions.
Examples
Compute Modal Decomposition of LTI Models
This example shows how to obtain a modal decomposition for a linear timeinvariant (LTI) model using modalsep
.
Create a random MIMO statespace model with 20 states.
rng(0) G = rss(20,2,3);
Obtain the modal decomposition of this model.
[H,H0] = modalsep(G);
Examine the size of H
.
size(H)
16x1 array of statespace models. Each model has 2 outputs, 3 inputs, and between 1 and 2 states.
Typically, the modal components are of order 1 or 2, but can have higher orders in case of cluster of repeated poles.
For this model, modalsep
returns the static gain H0
for each I/O pair.
H0
H0 = D = u1 u2 u3 y1 0 1.237 0.3334 y2 0.1554 2.193 0 Static gain.
Additionally, you can obtain the original model back from the modal decomposition using modalsum
.
G2 = modalsum(H,H0);
sigma(G,G2,'r')
RegionBased Modal Decomposition
This example shows how to perform regionbased modal decomposition of a statespace model. In this example, you perform the modal decomposition of a highorder model based on damping ratio of the poles.
Load a model and examine the damping ratio and natural frequency of the poles.
load('highOrderModel.mat','G') [wn,zeta] = damp(G);
Visualize the damping ratios and natural frequencies.
semilogy(zeta,wn,"x"); grid on title("Mode Damping and Natural Frequency") ylabel("Natural frequency") xlabel("Damping")
Based on this, you can define regions function that decomposes the model based on the damping ratio values. For example, this model has damping ratios between 0.023 and 0.05, you can divide three regions as follows:
Region 1: $0.023\le \mathit{z}<0.033$
Region 2: $0.033\le \mathit{z}<0.040$
Region 3: $\mathit{z}\ge 0.040$
The region function to assign region index to these values is defined at the end of this example. See Region Function Definition.
Perform the modal decomposition.
[h,h0,info] = modalsep(G,3,@regionFcn);
Examine the size of each region.
size(h(:,:,1))
Statespace model with 1 outputs, 1 inputs, and 24 states.
size(h(:,:,2))
Statespace model with 1 outputs, 1 inputs, and 12 states.
size(h(:,:,3))
Statespace model with 1 outputs, 1 inputs, and 12 states.
For this decomposition, region 1 has 24 poles in the specified range. Region 2 and 3 have 12 poles each in their specified ranges.
Region Function Definition
function IR = regionFcn(p) [~,z] = damp(p); IR = zeros(size(z)); IR(z<0.033 & z>=0.023) = 1; IR(z<0.04 & z>=0.033) = 2; IR(z>=0.04) = 3; end
Input Arguments
N
— Number of regions
positive scalar
Number of regions, specified as a positive scalar.
Specify this value as the number of partitions performed by the
regionFcn
.
regionFcn
— Region function
function name  function handle
Userdefined function for partitioning the complex plane, specified as a function name (string) or a function handle.
Specify a region function of the form:
IR = regionFcn(p);
The function assigns a region index IR
between
1
and N
to a given pole p
. To
specify additional inputs to the region function, use an anonymous function.
regionFcn = @(p) myFcn(p,param1,...,paramK);
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: [H,H0] = modalsep(G,InputScaling=[1,1e3])
DCFrequency
— Frequency for evaluating DC contribution
0
(default)  nonnegative scalar
Frequency for evaluating and matching DC contributions, specified as a nonnegative scalar.
For models with integrators, you cannot evaluate modal contributions at DC since the DC gain is infinite. To evaluate modal contributions and match gains at a different frequency, set the property to a positive value. The default value of this property corresponds to the true DC value.
InputScaling
— Input scaling
[]
(default)  vector
Input scaling factors, specified as a vector of length Nu,
where Nu is the number of inputs in the original model
sys
.
Use this option to emphasize specific input channels in sys
.
The software evaluates the modal contributions for the scaled system (see the
info
argument).
OutputScaling
— Output scaling
[]
(default)  vector
Output scaling factors, specified as a vector of length Ny,
where Ny is the number of outputs in the original model
sys
.
Use this option to emphasize specific output channels in sys
.
The software evaluates the modal contributions for the scaled system (see the
info
argument).
SepTol
— Relative accuracy of modal decomposition
1e12
(default)  scalar between 0 and 1
Relative accuracy of modal decomposition, specified as a scalar between 0 and 1.
This option limits the condition number of the block diagonalizing transformation
to roughly SepTol
/eps
. Increasing
SepTol
helps yield smaller modal components at the expense of
accuracy.
For regionbased decompositions, the function ignores this option because the block sized are predefined.
Output Arguments
H
— Modal components
model array
Modal components, returned as an array of models of the same type as
G
. For example, if G
is a zpk
model, modalsep
returns the modal components as an array of
zpk
models.
Use H(:,:,j)
to retrieve the submodel
H_{j}(s).
H0
— Static gain
matrix  ss
object
Static gain, returned as a matrix or a static ss
object.
info
— Additional information
structure  []
Additional information about the modal decomposition, returned as structure with these fields.
Field  Description 

Mode  Average mode (pole) value in the modal component H_{j}, returned as a vector of length n_{c}by1, where n_{c} is the number of modal components. 
DCGain  Normalized DC contribution of modal components, returned as a vector of length n_{c}by1, where n_{c} is the number of modal components. 
TL  Leftside matrix of the blockdiagonalizing transformation, returned
as a matrix with dimensions NxbyNx,
where Nx is the number of states in the model
The algorithm transforms the statespace realization (A, B, C, D, E) of a model to block diagonal matrices (A_{m}, B_{m}, C_{m}, D_{m}, E_{m}) given by:

TR  Rightside matrix of the blockdiagonalizing transformation, returned
as a matrix with dimensions NxbyNx,
where Nx is the number of states in the model

For zpk
and tf
models, the function returns an
empty value []
for this argument.
Version History
Introduced in R2023b
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)