docstring fixes: standardize description for lyap and care to be consistent with other functions, fix formatting in a few other functions. add references to NonlinearIOSystem and __call__ and remove evalfr

sawyerbfuller · sawyerbfuller · commit 3a554b507066 · 2022-11-30T12:09:42.000-08:00
diff --git a/control/dtime.py b/control/dtime.py
@@ -84,14 +84,6 @@ def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None,
     copy_names : bool, Optional
         If True, copy the names of the input signals, output
         signals, and states to the sampled system.
-
-    Returns
-    -------
-    sysd : linsys
-        Discrete time system, with sampling rate Ts
-
-    Additional Parameters
-    ---------------------
     inputs : int, list of str or None, optional
         Description of the system inputs.  If not specified, the origional
         system inputs are used.  See :class:`NamedIOSystem` for more
@@ -102,6 +94,11 @@ def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None,
         Description of the system states.  Same format as `inputs`. Only
         available if the system is :class:`StateSpace`.
 
+    Returns
+    -------
+    sysd : linsys
+        Discrete time system, with sampling rate Ts
+
     Notes
     -----
     See :meth:`StateSpace.sample` or :meth:`TransferFunction.sample` for
diff --git a/control/iosys.py b/control/iosys.py
@@ -2203,15 +2203,6 @@ def linearize(sys, xeq, ueq=None, t=0, params=None, **kw):
     copy_names : bool, Optional
         If True, Copy the names of the input signals, output signals, and
         states to the linearized system.
-
-    Returns
-    -------
-    ss_sys : LinearIOSystem
-        The linearization of the system, as a :class:`~control.LinearIOSystem`
-        object (which is also a :class:`~control.StateSpace` object.
-
-    Additional Parameters
-    ---------------------
     inputs : int, list of str or None, optional
         Description of the system inputs.  If not specified, the origional
         system inputs are used.  See :class:`NamedIOSystem` for more
@@ -2221,6 +2212,12 @@ def linearize(sys, xeq, ueq=None, t=0, params=None, **kw):
     states : int, list of str, or None, optional
         Description of the system states.  Same format as `inputs`.
 
+    Returns
+    -------
+    ss_sys : LinearIOSystem
+        The linearization of the system, as a :class:`~control.LinearIOSystem`
+        object (which is also a :class:`~control.StateSpace` object.
+
     """
     if not isinstance(sys, InputOutputSystem):
         raise TypeError("Can only linearize InputOutputSystem types")
@@ -2716,8 +2713,8 @@ def interconnect(syslist, connections=None, inplist=None, outlist=None,
     :func:`~control.summing_block` function and the ability to automatically
     interconnect signals with the same names:
 
-    >>> P = control.tf2io(control.tf(1, [1, 0]), inputs='u', outputs='y')
-    >>> C = control.tf2io(control.tf(10, [1, 1]), inputs='e', outputs='u')
+    >>> P = control.tf(1, [1, 0], inputs='u', outputs='y')
+    >>> C = control.tf(10, [1, 1], inputs='e', outputs='u')
     >>> sumblk = control.summing_junction(inputs=['r', '-y'], output='e')
     >>> T = control.interconnect([P, C, sumblk], inputs='r', outputs='y')
 
diff --git a/control/mateqn.py b/control/mateqn.py
@@ -88,7 +88,9 @@ def sb03md(n, C, A, U, dico, job='X', fact='N', trana='N', ldwork=None):
 
 
 def lyap(A, Q, C=None, E=None, method=None):
-    """X = lyap(A, Q) solves the continuous-time Lyapunov equation
+    """Solves the continuous-time Lyapunov equation
+
+    X = lyap(A, Q) solves
 
         :math:`A X + X A^T + Q = 0`
 
@@ -217,7 +219,9 @@ def lyap(A, Q, C=None, E=None, method=None):
 
 
 def dlyap(A, Q, C=None, E=None, method=None):
-    """dlyap(A, Q) solves the discrete-time Lyapunov equation
+    """Solves the discrete-time Lyapunov equation
+
+    X = dlyap(A, Q) solves
 
         :math:`A X A^T - X + Q = 0`
 
@@ -348,8 +352,9 @@ def dlyap(A, Q, C=None, E=None, method=None):
 
 def care(A, B, Q, R=None, S=None, E=None, stabilizing=True, method=None,
          A_s="A", B_s="B", Q_s="Q", R_s="R", S_s="S", E_s="E"):
-    """X, L, G = care(A, B, Q, R=None) solves the continuous-time
-    algebraic Riccati equation
+    """Solves the continuous-time algebraic Riccati equation
+
+    X, L, G = care(A, B, Q, R=None) solves
 
         :math:`A^T X + X A - X B R^{-1} B^T X + Q = 0`
 
@@ -505,9 +510,11 @@ def care(A, B, Q, R=None, S=None, E=None, stabilizing=True, method=None,
 
 def dare(A, B, Q, R, S=None, E=None, stabilizing=True, method=None,
          A_s="A", B_s="B", Q_s="Q", R_s="R", S_s="S", E_s="E"):
-    """X, L, G = dare(A, B, Q, R) solves the discrete-time algebraic Riccati
+    """Solves the discrete-time algebraic Riccati
     equation
 
+    X, L, G = dare(A, B, Q, R) solves
+
         :math:`A^T X A - X - A^T X B (B^T X B + R)^{-1} B^T X A + Q = 0`
 
     where A and Q are square matrices of the same dimension. Further, Q
diff --git a/control/sisotool.py b/control/sisotool.py
@@ -209,10 +209,6 @@ def rootlocus_pid_designer(plant, gain='P', sign=+1, input_signal='r',
 
     C_f = Kp + Ki/s + Kd*s/(tau*s + 1).
 
-    If `plant` is a discrete-time system, then the proportional, integral, and
-    derivative terms are given instead by Kp, Ki*dt/2*(z+1)/(z-1), and
-    Kd/dt*(z-1)/z, respectively.
-
     ::
 
           ------> C_ff ------    d
@@ -224,6 +220,10 @@ def rootlocus_pid_designer(plant, gain='P', sign=+1, input_signal='r',
               |             ----- C_b <-------|
               ---------------------------------
 
+    If `plant` is a discrete-time system, then the proportional, integral, and
+    derivative terms are given instead by Kp, Ki*dt/2*(z+1)/(z-1), and
+    Kd/dt*(z-1)/z, respectively.
+
     It is also possible to move the derivative term into the feedback path
     `C_b` using `derivative_in_feedback_path=True`. This may be desired to
     avoid that the plant is subject to an impulse function when the reference
diff --git a/control/statesp.py b/control/statesp.py
@@ -807,7 +807,7 @@ def __rdiv__(self, other):
             "StateSpace.__rdiv__ is not implemented yet.")
 
     def __call__(self, x, squeeze=None, warn_infinite=True):
-        """Evaluate system's transfer function at complex frequency.
+        """Evaluate system's frequency response at complex frequencies.
 
         Returns the complex frequency response `sys(x)` where `x` is `s` for
         continuous-time systems and `z` for discrete-time systems.
diff --git a/doc/control.rst b/doc/control.rst
@@ -20,6 +20,8 @@ System creation
     frd
     rss
     drss
+    NonlinearIOSystem
+
 
 System interconnections
 =======================
@@ -32,9 +34,8 @@ System interconnections
     negate
     parallel
     series
+    interconnect
 
-See also the :ref:`iosys-module` module, which can be used to create and
-interconnect nonlinear input/output systems.
 
 Frequency domain plotting
 =========================
@@ -78,8 +79,9 @@ Control system analysis
 
     dcgain
     describing_function
-    evalfr
-    freqresp
+    frequency_response
+    TransferFunction.__call__
+    StateSpace.__call__
     get_input_ff_index
     get_output_fb_index
     ispassive
@@ -141,7 +143,6 @@ Nonlinear system support
 
     describing_function
     find_eqpt
-    interconnect
     linearize
     input_output_response
     ss2io
