docs more consistent

murrayrm · Jan 8, 2021 · Aug 14, 2020 · Aug 16, 2020 · Aug 16, 2020 · Aug 16, 2020
commit b37c16b6d53e9ec0f7d63b2645cb3ef0a75b8ae7
diff --git a/control/frdata.py b/control/frdata.py
@@ -344,21 +344,27 @@ def __pow__(self, other):
     # update Sawyer B. Fuller 2020.08.14: __call__ added to provide a uniform 
     # interface to systems in general and the lti.frequency_response method
     def eval(self, omega, squeeze=True):
-        """Evaluate a transfer function at a single angular frequency.
-
-        self.evalfr(omega) returns the value of the frequency response
-        at frequency omega.
+        """Evaluate a transfer function at angular frequency omega.
 
         Note that a "normal" FRD only returns values for which there is an
         entry in the omega vector. An interpolating FRD can return
         intermediate values.     
 
         Parameters
         ----------
+        omega: float or array_like
+            Frequencies in radians per second
         squeeze: bool, optional (default=True)
-            If True and sys is single input, single output (SISO), return a 
-            1D array or scalar the same length as omega.
-        """
+            If True and sys is single input single output (SISO), returns a 
+            1D array or scalar depending on the length of omega 
+
+        Returns
+        -------
+        fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
+            The frequency response of the system. Array is len(x) if and only if
+            system is SISO and squeeze=True.
+
+        """     
         omega_array = np.array(omega, ndmin=1) # array-like version of omega 
         if any(omega_array.imag > 0): 
             raise ValueError("FRD.eval can only accept real-valued omega")
@@ -389,16 +395,15 @@ def eval(self, omega, squeeze=True):
     def __call__(self, s, squeeze=True):
         """Evaluate system's transfer function at complex frequencies.
 
-        Returns the complex frequency response `sys(x)` where `x` is `s` for 
-        continuous-time systems and `x` is `z` for discrete-time systems. 
+        Returns the complex frequency response `sys(s)`.
 
         To evaluate at a frequency omega in radians per second, enter 
-        x = omega*j.
-        
+        x = omega*1j or use FRD.eval(omega)
+
         Parameters
         ----------
-        x: complex scalar or array_like 
-            Complex frequency(s) 
+        s: complex scalar or array_like 
+            Complex frequencies 
         squeeze: bool, optional (default=True)
             If True and sys is single input single output (SISO), returns a 
             1D array or scalar depending on the length of x. 

diff --git a/control/lti.py b/control/lti.py
@@ -134,10 +134,10 @@ def frequency_response(self, omega, squeeze=True):
 
         Returns
         -------
-        mag : (self.outputs, self.inputs, len(omega)) ndarray
+        mag : (self.outputs, self.inputs, len(omega)) or len(omega) ndarray
             The magnitude (absolute value, not dB or log10) of the system
             frequency response.
-        phase : (self.outputs, self.inputs, len(omega)) ndarray
+        phase : (self.outputs, self.inputs, len(omega)) or len(omega) ndarray
             The wrapped phase in radians of the system frequency response.
         omega : ndarray
             The (sorted) frequencies at which the response was evaluated.
@@ -430,10 +430,10 @@ def evalfr(sys, x, squeeze=True):
     Evaluate the transfer function of an LTI system for complex frequency x.
 
     Returns the complex frequency response `sys(x)` where `x` is `s` for 
-    continuous-time systems and `x` is `z` for discrete-time systems. 
+    continuous-time systems and `z` for discrete-time systems. 
 
-    To evaluate at a frequency omega in radians per second, enter x = omega*j, 
-    for continuous-time systems, or x = exp(j*omega*dt) for discrete-time 
+    To evaluate at a frequency omega in radians per second, enter x = omega*1j, 
+    for continuous-time systems, or x = exp(1j*omega*dt) for discrete-time 
     systems. 
 
     Parameters
@@ -448,9 +448,9 @@ def evalfr(sys, x, squeeze=True):
 
     Returns
     -------
-    fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray 
-        The frequency response of the system. If system is SISO and squeezeThe size of the array depends on 
-        whether system is SISO and squeeze keyword.
+    fresp : (sys.outputs, sys.inputs, len(x)) or len(x) complex ndarray 
+        The frequency response of the system. Array is len(x) if and only if
+        system is SISO and squeeze=True.
 
     See Also
     --------
@@ -481,22 +481,22 @@ def freqresp(sys, omega, squeeze=True):
     ----------
     sys: StateSpace or TransferFunction
         Linear system
-    omega: array_like
+    omega: float or array_like
         A list of frequencies in radians/sec at which the system should be
         evaluated. The list can be either a python list or a numpy array
         and will be sorted before evaluation.
     squeeze: bool, optional (default=True)
-        If True and sys is single input, single output (SISO), return a 
+        If True and sys is single input, single output (SISO), returns  
         1D array or scalar depending on omega's length.
 
     Returns
     -------
-    mag : (self.outputs, self.inputs, len(omega)) ndarray
+    mag : (sys.outputs, sys.inputs, len(omega)) or len(omega) ndarray 
         The magnitude (absolute value, not dB or log10) of the system
         frequency response.
-    phase : (self.outputs, self.inputs, len(omega)) ndarray
+    phase : (sys.outputs, sys.inputs, len(omega)) or len(omega) ndarray
         The wrapped phase in radians of the system frequency response.
-    omega : ndarray or list or tuple
+    omega : ndarray
         The list of sorted frequencies at which the response was
         evaluated.
 

diff --git a/control/statesp.py b/control/statesp.py
@@ -438,26 +438,26 @@ def __rdiv__(self, other):
         raise NotImplementedError("StateSpace.__rdiv__ is not implemented yet.")
 
     def __call__(self, x, squeeze=True):
-        """Evaluate system's transfer function at complex frequencies.
+        """Evaluate system's transfer function at complex frequency.
 
         Returns the complex frequency response `sys(x)` where `x` is `s` for 
-        continuous-time systems and `x` is `z` for discrete-time systems. 
+        continuous-time systems and `z` for discrete-time systems. 
 
         To evaluate at a frequency omega in radians per second, enter 
-        x = omega*j, for continuous-time systems, or x = exp(j*omega*dt) for 
+        x = omega*1j, for continuous-time systems, or x = exp(1j*omega*dt) for 
         discrete-time systems. 
 
         Parameters
         ----------
-        x: complex scalar or array_like 
-            Complex frequency(s) 
+        x: complex or complex array_like 
+            Complex frequencies
         squeeze: bool, optional (default=True)
             If True and sys is single input single output (SISO), returns a 
             1D array or scalar depending on the length of x. 
 
         Returns
         -------
-        fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
+        fresp : (self.outputs, self.inputs, len(x)) or len(x) complex ndarray
             The frequency response of the system. Array is len(x) if and only if
             system is SISO and squeeze=True.
 
@@ -472,36 +472,34 @@ def __call__(self, x, squeeze=True):
         else:
             return out
 
-    def slycot_laub(self, s):
-        """Evaluate system's transfer function at complex frequencies s 
+    def slycot_laub(self, x):
+        """Evaluate system's transfer function at complex frequency
         using Laub's method from Slycot.
 
         Expects inputs and outputs to be formatted correctly. Use __call__
         for a more user-friendly interface. 
 
         Parameters
         ----------
-        s : array_like
+        x : complex array_like or complex
             Complex frequency
 
         Returns
         -------
-        output : (outputs, inputs, len(s)) complex ndarray
+        output : (number_outputs, number_inputs, len(x)) complex ndarray
             Frequency response
         """
         from slycot import tb05ad
 
         # preallocate
-        s_arr = np.array(s, ndmin=1) # array-like version of s
-        out = np.empty((self.outputs, self.inputs, len(s_arr)), 
-                        dtype=complex)
+        x_arr = np.array(x, ndmin=1) # array-like version of s
         n = self.states
         m = self.inputs
         p = self.outputs
+        out = np.empty((p, m, len(x_arr)), dtype=complex)
         # The first call both evaluates C(sI-A)^-1 B and also returns
         # Hessenberg transformed matrices at, bt, ct.
-        result = tb05ad(n, m, p, s_arr[0], self.A,
-                        self.B, self.C, job='NG')
+        result = tb05ad(n, m, p, x_arr[0], self.A, self.B, self.C, job='NG')
         # When job='NG', result = (at, bt, ct, g_i, hinvb, info)
         at = result[0]
         bt = result[1]
@@ -514,8 +512,8 @@ def slycot_laub(self, s):
         # transformed state matrices, at, bt, ct.
 
         # Start at the second frequency, already have the first.
-        for kk, s_kk in enumerate(s_arr[1:len(s_arr)]):
-            result = tb05ad(n, m, p, s_kk, at, bt, ct, job='NH')
+        for kk, x_kk in enumerate(x_arr[1:len(x_arr)]):
+            result = tb05ad(n, m, p, x_kk, at, bt, ct, job='NH')
             # When job='NH', result = (g_i, hinvb, info)
 
             # kk+1 because enumerate starts at kk = 0.
@@ -524,23 +522,23 @@ def slycot_laub(self, s):
         return out
 
     def horner(self, x):
-        """Evaluate system's transfer function at complex frequencies x
+        """Evaluate system's transfer function at complex frequency
         using Laub's or Horner's method. 
 
-        Evaluates sys(x) where `x` is `s` for continuous-time systems and `z` 
+        Evaluates `sys(x)` where `x` is `s` for continuous-time systems and `z` 
         for discrete-time systems. 
 
         Expects inputs and outputs to be formatted correctly. Use __call__
         for a more user-friendly interface. 
 
         Parameters
         ----------
-        x : array_like
+        x : complex array_like or complex
             Complex frequencies
 
         Returns
         -------
-        output : (outputs, inputs, len(s)) complex ndarray
+        output : (number_outputs, number_inputs, len(x)) complex ndarray
             Frequency response
 
         Notes

diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -208,23 +208,23 @@ def __call__(self, x, squeeze=True):
         """Evaluate system's transfer function at complex frequencies.
 
         Returns the complex frequency response `sys(x)` where `x` is `s` for 
-        continuous-time systems and `x` is `z` for discrete-time systems. 
+        continuous-time systems and `z` for discrete-time systems. 
 
         To evaluate at a frequency omega in radians per second, enter 
-        x = omega*j, for continuous-time systems, or x = exp(j*omega*dt) for 
+        x = omega*1j, for continuous-time systems, or x = exp(1j*omega*dt) for 
         discrete-time systems. 
 
         Parameters
         ----------
-        x: complex scalar or array_like 
-            Complex frequency(s) 
+        x: complex array_like or complex
+            Complex frequencies
         squeeze: bool, optional (default=True)
             If True and sys is single input single output (SISO), returns a 
             1D array or scalar depending on the length of x. 
 
         Returns
         -------
-        fresp : (num_outputs, num_inputs, len(x)) or len(x) complex ndarray
+        fresp : (self.outputs, self.inputs, len(x)) or len(x) complex ndarray
             The frequency response of the system. Array is len(x) if and only if
             system is SISO and squeeze=True.
 
@@ -239,22 +239,26 @@ def __call__(self, x, squeeze=True):
         else:
             return out
 
-    def horner(self, s):
-        """Evaluates system's transfer function at complex frequencies s 
-        using Horner's method.
+    def horner(self, x):
+        """Evaluate system's transfer function at complex frequency
+        using Horner's method. 
 
+        Evaluates `sys(x)` where `x` is `s` for continuous-time systems and `z`
+        for discrete-time systems. 
+
         Expects inputs and outputs to be formatted correctly. Use __call__
         for a more user-friendly interface. 
 
         Parameters
         ----------
-        s : array_like or scalar
+        x : complex array_like or complex
             Complex frequencies
 
         Returns
         -------
-        output : (outputs, inputs, len(s)) complex ndarray
+        output : (self.outputs, self.inputs, len(x)) complex ndarray
             Frequency response
+
         """
         s_arr = np.array(s, ndmin=1) # force to be an array
         out = empty((self.outputs, self.inputs, len(s_arr)), dtype=complex)