%% Disk Margins for SISO Loops
% For a loop transfer L and a given skew σ, the diskmargin command finds the largest disk size α at which the closed-loop system feedback(L*F,1) is stable for all values of F. This value of α is called the disk margin. The disk-based gain margin DGM and disk-based phase margin DPM are the range of gain and phase variations represented by the corresponding disk.
% For instance, compute the disk margin and associated disk-based gain and phase margins for a SISO transfer function, using the default σ = 0.

sigma = 0;
L = tf(25,[1 10 10 10]);
DM = diskmargin(L,sigma);  
alpha = DM.DiskMargin
DGM = DM.GainMargin
DPM = DM.PhaseMargin

%
% For this system, the balanced (σ = 0) disk margin α is about 0.46. The corresponding disk-based gain margin DGM shows that the system remains stable for relative variations in gain between about 0.63 and 1.6, or for phase variations of about ±26 degrees. This result establishes stability for all values of F of in the disk:

diskmarginplot(DGM,'disk')

% The gain margins are the intersection of the disk with the real axis. The phase margin is the largest angle between the real axis and a line through the origin tangent to the disk.
%
%% Combined Gain and Phase Variations
% The gain margins DGM you obtain from diskmargin assume no phase variation, and the phase margins DPM assume no gain variation. In practice, your system can experience simultaneous gain and phase variations. diskmarginplot lets you visualize the ranges of simultaneous gain and phase variations that the system can tolerate.

diskmarginplot(DGM)

% The shaded region shows the stable range of combined gain and phase variations. Thus, for instance, with no phase variation, the system can tolerate the full range DGM of gain variation, about  –4 dB to 4 dB. If the phase is allowed to vary by ±17 degrees or so, the allowable gain variation drops to a range of about –3 dB to 3 dB.
%
%% Disk Margins and Skew
% The ranges shown above, computed for σ = 0, represent a balanced gain variation, where gmin = 1/gmax. Varying the skew can reveal whether the loop is more sensitive to gain increase or decrease. For example, using σ > 0 may reveal that the feedback loop is very robust to gain increase, because positive σ models more gain increase than decrease. This result, however, says little about robustness to gain decrease. Try computing the disk-based gain and phase margins for L, biasing the margins toward gain increase or gain decrease.

DMdec = diskmargin(L,-2);
DMinc = diskmargin(L,2); 
DGMdec = DMdec.GainMargin
DGMinc = DMinc.GainMargin

%
% Put together, these results show that in the absence of phase variation, stability is maintained for relative gain variations between 0.4 and 1.72. To see how the phase margin depends on these gain variations, plot the stable ranges of gain and phase variations for each diskmargin result.

diskmarginplot([DGMdec;DGM;DGMinc])
legend('\sigma = -2','\sigma = 0','\sigma = 2')
title('Stable range of gain and phase variations')

% This plot shows that the feedback loop can tolerate larger phase variations when the gain decreases. In other words, the loop stability is more sensitive to gain increase. Note that it would be misleading to just take the largest reported phase margin (nearly 30 degrees for σ = –2). Indeed, this large value is predicated on a small gain increase of less than 3 dB. Since both gain and phase are subject to uncertainty in general, it is important to pay attention to combined variations. For example, the plot shows that when the gain increases by 4 dB, the phase margin drops to less than 15 degrees. By contrast, it remains greater than 30 degrees when the gain decreases by 4 dB.
% In conclusion, varying the skew σ can give a fuller picture of sensitivity to gain and phase uncertainty. Unless you are mostly concerned with gain variations in one direction (increase or decrease), it is not recommended to draw conclusions from a single nonzero value of σ. Instead use the default σ = 0 to get unbiased estimates of gain and phase margins. When using nonzero values of σ, use both positive and negative values to compare relative sensitivity to gain increase vs. gain decrease.
%
%% Uncertainty Disk in the Nyquist Plane
% The requirement of robust stability for the closed-loop system feedback(L*F,1) is equivalent to a requirement that 1 + L*F  ≠ 0. In the Nyquist plane, this requirement becomes L(jω) ≠ –1/F. Thus the disk F for each value of σ defines an exclusion region that the Nyquist curve does not enter if closed-loop stability is preserved. All such disks –1/F contain the critical point (–1,0) and are tangent to the Nyquist curve. The skew adjusts the size and position of the tangent disks, as illustrated in the following plot, which shows the exclusion regions for the three disk margins of L computed above. As σ increases, each disk provides lower estimates of the classical gain and phase margins.

nyquist(L)
hold on
diskmarginplot([DGMdec;DGM;DGMinc],'nyquist')
p = findobj(gca,'type','patch');
legend(p,'\sigma = -2','\sigma = 0','\sigma = 2')
hold off

% For more details about the Nyquist interpretation of the uncertainty disk, see Disk Margin and Smallest Destabilizing Perturbation.
%
% Copyright 2019 The MathWorks, Inc.