%% How Disk-Based Margins Are Computed
% The diskmarginplot function plots the uncertainty disk F for a given range of relative gain variations DGM = [gmin,gmax]. For example, if the gain can increase or decrease by a factor 2, the uncertain factor F takes values in the following disk.

diskmarginplot([0.5 2],'disk')

% This disk models both gain and phase variations. Here, as the plot shows, the phase can change by 37 degrees for the nominal gain (|F| = 1).
%
%% Eccentricity of Uncertainty Model
% As noted previously, The disk of F values is given by
% F=\frac{1+\alpha \left\lbrack \left(1-e\right)/2\right\rbrack \delta }{1-\alpha \left\lbrack \left(1+e\right)/2\right\rbrack \delta },\;\left|\delta \right|<1,
% where δ is a normalized dynamic uncertainty. The parameter ɑ adjusts the level of uncertainty. The parameter e, called the eccentricity, is a bias toward gain increase or gain decrease. The default e = 0 corresponds to the balanced case, where the gain can increase or decrease by the same factor. Nonzero eccentriciy models gain variations such that  \not= \;1. For a given [gmin,gmax], the gm2dm commmand computes the corresponding values of ɑ and e. The diskmarginplot command shows you the corresponding uncertainty disks.

GainRange1 = [0.2 1.3];
GainRange2 = [0.5 2];
GainRange3 = [0.8 3];
[alpha1,E1] = gm2dm(GainRange1); % E1 = eccentricity for GainRange1
[alpha2,E2] = gm2dm(GainRange2);
[alpha3,E3] = gm2dm(GainRange3);
diskmarginplot([GainRange1;GainRange2;GainRange3],'disk')
legend("E=" + [E1 E2 E3])

% Note that e < 0 when gain uncertainty is skewed toward gain decrease (gmin*gmax < 1) and e > 0 when gain uncertainty is skewed toward gain increase (gmin*gmax > 1). This relationship is even clearer when plotting the corresponding ranges of simultaneous gain and phase variations. In the following plot, the x and y axes represent the relative amount of gain variation and absolute amount of phase variation.

diskmarginplot([GainRange1;GainRange2;GainRange3])
legend("e =" + [E1 E2 E3])

% Thus, for instance, when you use umargin to model a particular gain and phase variation in a feedback loop, umargin selects an uncertainty model F by choosing values for e and ɑ that correspond to the range of variation you specify.
%
%% Disk Margins and Eccentricity
% For an open-loop transfer function L and a given e, the command diskmargin(L,e) computes the largest disk size ɑ for which the feedback loop remain stable. This largest disk is characterized by its intersection DGM = [GMIN,GMAX] with the real axis, also called the disk-based gain margin. Different E values yield different DGM ranges. For example, using E>0 may reveal that the feedback loop is very robust to gain increase, because positive E models more gain increase than decrease. However this may also say little about robustness to gain decrease. The next example illustrates the effect of computing disk-based margins with different eccentricity.

L = tf(25,[1 10 10 10]);
DM1 = diskmargin(L,-2);  % E<0
DM2 = diskmargin(L);     % E=0
DM3 = diskmargin(L,2);   % E>0
DM1.GainMargin
DM2.GainMargin
DM3.GainMargin

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

diskmarginplot([DM1.GainMargin;DM2.GainMargin;DM3.GainMargin])
legend('E=-2','E=0','E=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, it is more sensitive to gain increase. Note that it would be misleading to just take the largest reported phase margin (nearly 30 degrees for E=-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 eccentricity E 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 E. Instead use the default E=0 to get unbiased estimates of gain and phase margins. When using nonzero values of E, use both positive and negative values to compare relative sensitivity to gain increase vs. gain decrease.
%
%% Nyquist Plot Interpretation
% The requirement of robust stablity 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 margin for each value of e defines an exclusion region that the Nyquist curve does not enter if closed-loop stability is preserved. All of these disks –1/F contain the critical point (–1,0) and are tangent to the Nyquist curve. The eccentricity adjusts the size and position of the tangent disks, as illustrated in the following plot. As e increases, each disk provides lower estimates of the classical gain and phase margins.

nyquist(L), hold on
diskmarginplot([DM1.GainMargin;DM2.GainMargin;DM3.GainMargin],'nyquist')
p = findobj(gca,'type','patch');
legend(p,'E=-2','E=0','E=2')
hold off

%
%
%
% Copyright 2019 The MathWorks, Inc.