margin() docstring updates

murrayrm · murrayrm · commit e42c3609168b · 2021-02-20T13:53:22.000-08:00
diff --git a/control/margins.py b/control/margins.py
@@ -211,36 +211,41 @@ def fun(wdt):
 # Sawyer B. Fuller <minster@uw.edu>, removed a lot of the innards
 # and replaced with analytical polynomial functions for LTI systems.
 #
-# idea for the frequency data solution copied/adapted from
+# The idea for the frequency data solution copied/adapted from
 # https://github.com/alchemyst/Skogestad-Python/blob/master/BODE.py
 # Rene van Paassen <rene.vanpaassen@gmail.com>
 #
 # RvP, July 8, 2014, corrected to exclude phase=0 crossing for the gain
 #                    margin polynomial
+#
 # RvP, July 8, 2015, augmented to calculate all phase/gain crossings with
 #                    frd data. Correct to return smallest phase
 #                    margin, smallest gain margin and their frequencies
+#
 # RvP, Jun 10, 2017, modified the inclusion of roots found for phase
-#                    crossing to include all >= 0, made subsequent calc
-#                    insensitive to div by 0
-#                    also changed the selection of which crossings to
-#                    return on basis of "A note on the Gain and Phase
-#                    Margin Concepts" Journal of Control and Systems
-#                    Engineering, Yazdan Bavafi-Toosi, Dec 2015, vol 3
-#                    issue 1, pp 51-59, closer to Matlab behavior, but
-#                    not completely identical in edge cases, which don't
-#                    cross but touch gain=1
+#                    crossing to include all >= 0, made subsequent
+#                    calc insensitive to div by 0.  Also changed the
+#                    selection of which crossings to return on basis
+#                    of "A note on the Gain and Phase Margin Concepts"
+#                    Journal of Control and Systems Engineering,
+#                    Yazdan Bavafi-Toosi, Dec 2015, vol 3 issue 1, pp
+#                    51-59, closer to Matlab behavior, but not
+#                    completely identical in edge cases, which don't
+#                    cross but touch gain=1.
+#
 # BG, Nov 9, 2020,   removed duplicate implementations of the same code
 #                    for crossover frequencies and enhanced to handle discrete
 #                    systems
+
+>>>>>>> Stashed changes
 def stability_margins(sysdata, returnall=False, epsw=0.0):
     """Calculate stability margins and associated crossover frequencies.
 
     Parameters
     ----------
     sysdata: LTI system or (mag, phase, omega) sequence
         sys : LTI system
-            Linear SISO system
+            Linear SISO system representing the loop transfer function
         mag, phase, omega : sequence of array_like
             Arrays of magnitudes (absolute values, not dB), phases (degrees),
             and corresponding frequencies. Crossover frequencies returned are
@@ -261,12 +266,19 @@ def stability_margins(sysdata, returnall=False, epsw=0.0):
         Phase margin
     sm: float or array_like
         Stability margin, the minimum distance from the Nyquist plot to -1
-    wg: float or array_like
-        Frequency for gain margin (at phase crossover, phase = -180 degrees)
-    wp: float or array_like
-        Frequency for phase margin (at gain crossover, gain = 1)
-    ws: float or array_like
-        Frequency for stability margin (complex gain closest to -1)
+    wpc: float or array_like
+        Phase crossover frequency (where phase crosses -180 degrees)
+    wgc: float or array_like
+        Gain crossover frequency (where gain crosses 1)
+    wms: float or array_like
+        Stability margin frequency (where Nyquist plot is closest to -1)
+
+    Note that the gain margin is determined by the gain of the loop
+    transfer function at the phase crossover frequency(s), the phase
+    margin is determined by the phase of the loop transfer function at
+    the gain crossover frequency(s), and the stability margin is
+    determined by the frequency of maximum sensitivity (given by the
+    magnitude of 1/(1+L)).
     """
     try:
         if isinstance(sysdata, frdata.FRD):
@@ -456,7 +468,7 @@ def margin(*args):
     ----------
     sysdata : LTI system or (mag, phase, omega) sequence
         sys : StateSpace or TransferFunction
-            Linear SISO system
+            Linear SISO system representing the loop transfer function
         mag, phase, omega : sequence of array_like
             Input magnitude, phase (in deg.), and frequencies (rad/sec) from
             bode frequency response data
