reverted mistaken margin argument rearrangement and clarified definitions in docstring of margin

sawyerbfuller · sawyerbfuller · commit bc5079bfa940 · 2021-11-05T14:17:11.000-07:00
diff --git a/control/margins.py b/control/margins.py
@@ -522,10 +522,12 @@ def margin(*args):
         Gain margin
     pm : float
         Phase margin (in degrees)
-    wgc : float or array_like
-        Gain crossover frequency (where gain crosses 1)
-    wpc : float or array_like
-        Phase crossover frequency (where phase crosses -180 degrees)
+    wcg : float or array_like
+        Crossover frequency associated with gain margin (phase crossover
+        frequency), where phase crosses below -180 degrees.
+    wcp : float or array_like
+        Crossover frequency associated with phase margin (gain crossover
+        frequency), where gain crosses below 1.
 
     Margins are calculated for a SISO open-loop system.
 
@@ -536,7 +538,7 @@ def margin(*args):
     Examples
     --------
     >>> sys = tf(1, [1, 2, 1, 0])
-    >>> gm, pm, wg, wp = margin(sys)
+    >>> gm, pm, wcg, wcp = margin(sys)
 
     """
     if len(args) == 1:
@@ -548,4 +550,4 @@ def margin(*args):
         raise ValueError("Margin needs 1 or 3 arguments; received %i."
                          % len(args))
 
-    return margin[0], margin[1], margin[4], margin[3]
+    return margin[0], margin[1], margin[3], margin[4]
diff --git a/control/tests/margin_test.py b/control/tests/margin_test.py
@@ -102,15 +102,15 @@ def test_margin_sys(tsys):
     sys, refout, refoutall = tsys
     """Test margin() function with system input"""
     out = margin(sys)
-    assert_allclose(out, np.array(refout)[[0, 1, 4, 3]], atol=1.5e-3)
+    assert_allclose(out, np.array(refout)[[0, 1, 3, 4]], atol=1.5e-3)
 
 def test_margin_3input(tsys):
     sys, refout, refoutall = tsys
     """Test margin() function with mag, phase, omega input"""
     omega = np.logspace(-2, 2, 2000)
     mag, phase, omega_ = sys.frequency_response(omega)
     out = margin((mag, phase*180/np.pi, omega_))
-    assert_allclose(out, np.array(refout)[[0, 1, 4, 3]], atol=1.5e-3)
+    assert_allclose(out, np.array(refout)[[0, 1, 3, 4]], atol=1.5e-3)
 
 
 @pytest.mark.parametrize(
@@ -276,23 +276,23 @@ def tsys_zmore(request, tsys_zmoresystems):
 @pytest.mark.parametrize(
     'tsys_zmore',
     [dict(sysname='typem1', K=2.0, atol=1.5e-3,
-          result=(float('Inf'), -120.0007,  0.5774, float('NaN'))),
+          result=(float('Inf'), -120.0007, float('NaN'), 0.5774)),
      dict(sysname='type0', K=0.8, atol=1.5e-3,
-          result=(10.0014, float('inf'), float('nan'), 1.7322)),
+          result=(10.0014, float('inf'), 1.7322, float('nan'))),
      dict(sysname='type0', K=2.0, atol=1e-2,
-          result=(4.000, 67.6058, 0.7663, 1.7322)),
+          result=(4.000, 67.6058, 1.7322, 0.7663)),
      dict(sysname='type1', K=1.0, atol=1e-4,
-          result=(float('Inf'), 144.9032, 0.3162, float('NaN'))),
+          result=(float('Inf'), 144.9032, float('NaN'), 0.3162)),
      dict(sysname='type2', K=1.0, atol=1e-4,
-          result=(float('Inf'), 44.4594, 0.7907, float('NaN'))),
+          result=(float('Inf'), 44.4594, float('NaN'), 0.7907)),
      dict(sysname='type3', K=1.0, atol=1.5e-3,
-          result=(0.0626, 37.1748, 0.7951, 0.1119)),
+          result=(0.0626, 37.1748, 0.1119, 0.7951)),
      dict(sysname='example21', K=1.0, atol=1e-2,
           result=(0.0100, -14.5640, 0, 0.0022)),
      dict(sysname='example21', K=1000.0, atol=1e-2,
-          result=(0.1793, 22.5215, 0.0630, 0.0243)),
+          result=(0.1793, 22.5215, 0.0243, 0.0630)),
      dict(sysname='example21', K=5000.0, atol=1.5e-3,
-          result=(4.5596, 21.2101, 0.1868, 0.4385)),
+          result=(4.5596, 21.2101, 0.4385, 0.1868)),
      ],
     indirect=True)
 def test_zmore_margin(tsys_zmore):
diff --git a/control/tests/matlab_test.py b/control/tests/matlab_test.py
@@ -355,13 +355,13 @@ def testLsim_mimo(self, mimo):
     def testMargin(self, siso):
         """Test margin()"""
         #! TODO: check results to make sure they are OK
-        gm, pm, wg, wp = margin(siso.tf1)
-        gm, pm, wg, wp = margin(siso.tf2)
-        gm, pm, wg, wp = margin(siso.ss1)
-        gm, pm, wg, wp = margin(siso.ss2)
-        gm, pm, wg, wp = margin(siso.ss2 * siso.ss2 * 2)
+        gm, pm, wcg, wcp = margin(siso.tf1)
+        gm, pm, wcg, wcp = margin(siso.tf2)
+        gm, pm, wcg, wcp = margin(siso.ss1)
+        gm, pm, wcg, wcp = margin(siso.ss2)
+        gm, pm, wcg, wcp = margin(siso.ss2 * siso.ss2 * 2)
         np.testing.assert_array_almost_equal(
-            [gm, pm, wg, wp], [1.5451, 75.9933, 0.6559, 1.2720], decimal=3)
+            [gm, pm, wcg, wcp], [1.5451, 75.9933, 1.2720, 0.6559], decimal=3)
 
     def testDcgain(self, siso):
         """Test dcgain() for SISO system"""
@@ -781,12 +781,12 @@ def testCombi01(self):
         # total open loop
         Hol = Hc*Hno*Hp
 
-        gm, pm, wg, wp = margin(Hol)
-        # print("%f %f %f %f" % (gm, pm, wg, wp))
+        gm, pm, wcg, wcp = margin(Hol)
+        # print("%f %f %f %f" % (gm, pm, wcg, wcp))
         np.testing.assert_allclose(gm, 3.32065569155)
         np.testing.assert_allclose(pm, 46.9740430224)
-        np.testing.assert_allclose(wg, 0.0616288455466)
-        np.testing.assert_allclose(wp, 0.176469728448)
+        np.testing.assert_allclose(wcg, 0.176469728448)
+        np.testing.assert_allclose(wcp, 0.0616288455466)
 
     def test_tf_string_args(self):
         """Make sure s and z are defined properly"""
