update class documentation (+ unit tests)

Author: murrayrm

control/bdalg.py

@@ -53,7 +53,7 @@ def series(*sys, **kwargs):
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
-        name <sys[id]> is generated with a unique integer id.
+        name 'sys[id]' is generated with a unique integer id.
 
     Raises
     ------
@@ -124,7 +124,7 @@ def parallel(*sys, **kwargs):
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
-        name <sys[id]> is generated with a unique integer id.
+        name 'sys[id]' is generated with a unique integer id.
 
     Raises
     ------
@@ -139,7 +139,7 @@ def parallel(*sys, **kwargs):
     Notes
     -----
     This function is a wrapper for the __add__ function in the
-    StateSpace and TransferFunction classes.  The output type is usually
+    `StateSpace` and `TransferFunction` classes.  The output type is usually
     the type of `sys1`.  If `sys1` is a scalar, then the output type is
     the type of `sys2`.
 
@@ -168,8 +168,7 @@ def parallel(*sys, **kwargs):
     return sys
 
 def negate(sys, **kwargs):
-    """
-    Return the negative of a system.
+    """Return the negative of a system.
 
     Parameters
     ----------
@@ -193,16 +192,17 @@ def negate(sys, **kwargs):
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
-        name <sys[id]> is generated with a unique integer id.
+        name 'sys[id]' is generated with a unique integer id.
 
     See Also
     --------
     append, feedback, interconnect, parallel, series
 
     Notes
     -----
-    This function is a wrapper for the __neg__ function in the StateSpace and
-    TransferFunction classes.  The output type is the same as the input type.
+    This function is a wrapper for the __neg__ function in the `StateSpace`
+    and `TransferFunction` classes.  The output type is the same as the
+    input type.
 
     Examples
     --------
@@ -248,16 +248,16 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
-        name <sys[id]> is generated with a unique integer id.
+        name 'sys[id]' is generated with a unique integer id.
 
     Raises
     ------
     ValueError
-        if `sys1` does not have as many inputs as `sys2` has outputs, or if
-        `sys2` does not have as many inputs as `sys1` has outputs
+        If `sys1` does not have as many inputs as `sys2` has outputs, or if
+        `sys2` does not have as many inputs as `sys1` has outputs.
     NotImplementedError
-        if an attempt is made to perform a feedback on a MIMO TransferFunction
-        object
+        If an attempt is made to perform a feedback on a MIMO `TransferFunction`
+        object.
 
     See Also
     --------
@@ -334,7 +334,7 @@ def append(*sys, **kwargs):
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
-        name <sys[id]> is generated with a unique integer id.
+        name 'sys[id]' is generated with a unique integer id.
 
     Returns
     -------
@@ -471,16 +471,16 @@ def combine_tf(tf_array, **kwargs):
 
     Parameters
     ----------
-    tf_array : list of list of TransferFunction or array_like
+    tf_array : list of list of `TransferFunction` or array_like
         Transfer matrix represented as a two-dimensional array or
-        list-of-lists containing TransferFunction objects. The
+        list-of-lists containing `TransferFunction` objects. The
         `TransferFunction` objects can have multiple outputs and inputs, as
         long as the dimensions are compatible.
 
     Returns
     -------
-    TransferFunction
-        Transfer matrix represented as a single MIMO TransferFunction object.
+    `TransferFunction`
+        Transfer matrix represented as a single MIMO `TransferFunction` object.
 
     Other Parameters
     ----------------
@@ -490,7 +490,7 @@ def combine_tf(tf_array, **kwargs):
         or 'y'). See `InputOutputSystem` for more information.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
-        name <sys[id]> is generated with a unique integer id.
+        name 'sys[id]' is generated with a unique integer id.
 
     Raises
     ------
@@ -602,7 +602,7 @@ def split_tf(transfer_function):
 
     Parameters
     ----------
-    transfer_function : TransferFunction
+    transfer_function : `TransferFunction`
         MIMO transfer function to split.
 
     Returns
@@ -657,11 +657,11 @@ def split_tf(transfer_function):
     return np.array(tf_split_lst, dtype=object)
 
 def _ensure_tf(arraylike_or_tf, dt=None):
-    """Convert an array-like to a transfer function.
+    """Convert an array_like to a transfer function.
 
     Parameters
     ----------
-    arraylike_or_tf : TransferFunction or array_like
+    arraylike_or_tf : `TransferFunction` or array_like
         Array-like or transfer function.
     dt : None, True or float, optional
         System timebase. 0 (default) indicates continuous
@@ -672,7 +672,7 @@ def _ensure_tf(arraylike_or_tf, dt=None):
 
     Returns
     -------
-    TransferFunction
+    `TransferFunction`
         Transfer function.
 
     Raises
@@ -706,7 +706,7 @@ def _ensure_tf(arraylike_or_tf, dt=None):
         )
     except TypeError:
         raise ValueError(
-            "`arraylike_or_tf` must only contain array-likes or transfer "
+            "`arraylike_or_tf` must only contain array_likes or transfer "
             "functions."
         )
     return tfn

control/canonical.py

@@ -25,7 +25,7 @@ def canonical_form(xsys, form='reachable'):
 
     Parameters
     ----------
-    xsys : StateSpace object
+    xsys : `StateSpace` object
         System to be transformed, with state 'x'.
     form : str
         Canonical form for transformation.  Chosen from:
@@ -35,7 +35,7 @@ def canonical_form(xsys, form='reachable'):
 
     Returns
     -------
-    zsys : StateSpace object
+    zsys : `StateSpace` object
         System in desired canonical form, with state 'z'.
     T : (M, M) real ndarray
         Coordinate transformation matrix, z = T * x.
@@ -77,12 +77,12 @@ def reachable_form(xsys):
 
     Parameters
     ----------
-    xsys : StateSpace object
+    xsys : `StateSpace` object
         System to be transformed, with state `x`.
 
     Returns
     -------
-    zsys : StateSpace object
+    zsys : `StateSpace` object
         System in reachable canonical form, with state `z`.
     T : (M, M) real ndarray
         Coordinate transformation: z = T * x.
@@ -142,12 +142,12 @@ def observable_form(xsys):
 
     Parameters
     ----------
-    xsys : StateSpace object
+    xsys : `StateSpace` object
         System to be transformed, with state `x`.
 
     Returns
     -------
-    zsys : StateSpace object
+    zsys : `StateSpace` object
         System in observable canonical form, with state `z`.
     T : (M, M) real ndarray
         Coordinate transformation: z = T * x.
@@ -203,7 +203,7 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
 
     Parameters
     ----------
-    xsys : StateSpace object
+    xsys : `StateSpace` object
         System to transform.
     T : (M, M) array_like
         The matrix `T` defines the new set of coordinates z = T x.
@@ -215,7 +215,7 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
 
     Returns
     -------
-    zsys : StateSpace object
+    zsys : `StateSpace` object
         System in transformed coordinates, with state 'z'.
 
     See Also
@@ -497,7 +497,7 @@ def modal_form(xsys, condmax=None, sort=False):
 
     Parameters
     ----------
-    xsys : StateSpace object
+    xsys : `StateSpace` object
         System to be transformed, with state x.
     condmax : None or float, optional
         An upper bound on individual transformations.  If None, use
@@ -508,9 +508,9 @@ def modal_form(xsys, condmax=None, sort=False):
 
     Returns
     -------
-    zsys : StateSpace object
+    zsys : `StateSpace` object
         System in modal canonical form, with state z.
-    T : (M, M) ndarray
+    T : (M, M) array
         Coordinate transformation: z = T * x.
 
     Examples

control/config.py

@@ -29,7 +29,7 @@
 
 
 class DefaultDict(collections.UserDict):
-    """Map names for settings from older version to their renamed ones.
+    """Default parameters dictionary, with legacy warnings.
 
     If a user wants to write to an old setting, issue a warning and write to
     the renamed setting instead. Accessing the old setting returns the value

control/ctrlplot.py

@@ -122,7 +122,7 @@
 #
 
 class ControlPlot():
-    """A class for representing control figures.
+    """Return class for control platting functions.
 
     This class is used as the return type for control plotting functions.
     It contains the information required to access portions of the plot
@@ -136,17 +136,17 @@ class ControlPlot():
 
     Parameters
     ----------
-    lines : array of list of `matplotlib:Line2D`
+    lines : array of list of `matplotlib.lines.Line2D`
         Array of Line2D objects for each line in the plot.  Generally, the
         shape of the array matches the subplots shape and the value of the
         array is a list of Line2D objects in that subplot.  Some plotting
         functions will return variants of this structure, as described in
         the individual documentation for the functions.
-    axes : 2D array of `matplotlib:Axes`
+    axes : 2D array of `matplotlib.axes.Axes`
         Array of Axes objects for each subplot in the plot.
-    figure : `matplotlib:Figure`
+    figure : `matplotlib.figure.Figure`
         Figure on which the Axes are drawn.
-    legend : `matplotlib:.legend.Legend` (instance or ndarray)
+    legend : `matplotlib.legend.Legend` (instance or ndarray)
         Legend object(s) for the plot.  If more than one legend is
         included, this will be an array with each entry being either None
         (for no legend) or a legend object.
@@ -176,6 +176,7 @@ def __setitem__(self, item, val):
         self.lines[item] = val
     shape = property(lambda self: self.lines.shape, None)
     def reshape(self, *args):
+        """Reshape lines array (legacy)."""
         return self.lines.reshape(*args)
 
     def set_plot_title(self, title, frame='axes'):
@@ -310,11 +311,11 @@ def pole_zero_subplots(
                 case 'empty', _:        # empty grid
                     ax_array[row, col] = fig.add_subplot(nrows, ncols, index+1)
 
-                case True, True:        # continuous time grid
+                case True, True:        # continuous-time grid
                     ax_array[row, col], _ = sgrid(
                         (nrows, ncols, index+1), scaling=scaling)
 
-                case True, False:       # discrete time grid
+                case True, False:       # discrete-time grid
                     ax_array[row, col] = fig.add_subplot(nrows, ncols, index+1)
                     zgrid(ax=ax_array[row, col], scaling=scaling)