added more documentation on return_magphase per @sawyerbfuller

murrayrm · murrayrm · commit 135734a9f7c7 · 2022-04-15T13:31:45.000-07:00
diff --git a/control/frdata.py b/control/frdata.py
@@ -151,7 +151,7 @@ def __init__(self, *args, **kwargs):
         FRD object.
 
         To construct frequency response data for an existing LTI
-        object, other than an FRD, call FRD(sys, omega)
+        object, other than an FRD, call FRD(sys, omega).
 
         """
         # TODO: discrete-time FRD systems?
diff --git a/control/lti.py b/control/lti.py
@@ -412,18 +412,21 @@ def frequency_response(sys, omega, squeeze=None):
 
     Returns
     -------
-    mag : ndarray
-        The magnitude (absolute value, not dB or log10) of the system
-        frequency response.  If the system is SISO and squeeze is not True,
-        the array is 1D, indexed by frequency.  If the system is not SISO or
-        squeeze is False, the array is 3D, indexed by the output, input, and
+    response : FrequencyResponseData
+        Frequency response data object representing the frequency response.
+        This object can be assigned to a tuple using
+
+            mag, phase, omega = response
+
+        where ``mag`` is the magnitude (absolute value, not dB or log10) of
+        the system frequency response, ``phase`` is the wrapped phase in
+        radians of the system frequency response, and ``omega`` is the
+        (sorted) frequencies at which the response was evaluated.  If the
+        system is SISO and squeeze is not True, ``magnitude`` and ``phase``
+        are 1D, indexed by frequency.  If the system is not SISO or squeeze
+        is False, the array is 3D, indexed by the output, input, and
         frequency.  If ``squeeze`` is True then single-dimensional axes are
         removed.
-    phase : ndarray
-        The wrapped phase in radians of the system frequency response.
-    omega : ndarray
-        The list of sorted frequencies at which the response was
-        evaluated.
 
     See Also
     --------
diff --git a/control/tests/frd_test.py b/control/tests/frd_test.py
@@ -532,3 +532,34 @@ def test_frequency_response():
     np.testing.assert_equal(resp.magnitude, np.abs(eval))
     np.testing.assert_equal(resp.phase, np.angle(eval))
     np.testing.assert_equal(resp.omega, omega)
+
+    # Make sure that we can change the properties of the response
+    sys = ct.rss(2, 1, 1)
+    resp_default = ct.frequency_response(sys, omega)
+    mag_default, phase_default, omega_default = resp_default
+    assert mag_default.ndim == 1
+    assert phase_default.ndim == 1
+    assert omega_default.ndim == 1
+    assert mag_default.shape[0] == omega_default.shape[0]
+    assert phase_default.shape[0] == omega_default.shape[0]
+
+    resp_nosqueeze = ct.frequency_response(sys, omega, squeeze=False)
+    mag_nosqueeze, phase_nosqueeze, omega_nosqueeze = resp_nosqueeze
+    assert mag_nosqueeze.ndim == 3
+    assert phase_nosqueeze.ndim == 3
+    assert omega_nosqueeze.ndim == 1
+    assert mag_nosqueeze.shape[2] == omega_nosqueeze.shape[0]
+    assert phase_nosqueeze.shape[2] == omega_nosqueeze.shape[0]
+
+    # Try changing the response
+    resp_def_nosq = resp_default(squeeze=False)
+    mag_def_nosq, phase_def_nosq, omega_def_nosq = resp_def_nosq
+    assert mag_def_nosq.shape == mag_nosqueeze.shape
+    assert phase_def_nosq.shape == phase_nosqueeze.shape
+    assert omega_def_nosq.shape == omega_nosqueeze.shape
+
+    resp_nosq_sq = resp_nosqueeze(squeeze=True)
+    mag_nosq_sq, phase_nosq_sq, omega_nosq_sq = resp_nosq_sq
+    assert mag_nosq_sq.shape == mag_default.shape
+    assert phase_nosq_sq.shape == phase_default.shape
+    assert omega_nosq_sq.shape == omega_default.shape
diff --git a/doc/conventions.rst b/doc/conventions.rst
@@ -74,6 +74,28 @@ FRD systems have a somewhat more limited set of functions that are
 available, although all of the standard algebraic manipulations can be
 performed.
 
+The FRD class is also used as the return type for the
+:func:`frequency_response` function (and the equivalent method for the
+:class:`StateSpace` and :class:`TransferFunction` classes).  This
+object can be assigned to a tuple using
+
+    mag, phase, omega = response
+
+where `mag` is the magnitude (absolute value, not dB or log10) of the
+system frequency response, `phase` is the wrapped phase in radians of
+the system frequency response, and `omega` is the (sorted) frequencies
+at which the response was evaluated.  If the system is SISO and the
+`squeeze` argument to :func:`frequency_response` is not True,
+`magnitude` and `phase` are 1D, indexed by frequency.  If the system
+is not SISO or `squeeze` is False, the array is 3D, indexed by the
+output, input, and frequency.  If `squeeze` is True then
+single-dimensional axes are removed.  The processing of the `squeeze`
+keyword can be changed by calling the response function with a new
+argument:
+
+    mag, phase, omega = response(squeeze=False)
+
+
 Discrete time systems
 ---------------------
 A discrete time system is created by specifying a nonzero 'timebase', dt.
