regularize dt keyword use and related annotations (see develop.rst)

Author: murrayrm

control/bdalg.py

@@ -58,8 +58,8 @@ def series(*sys, **kwargs):
     Raises
     ------
     ValueError
-        if ``sys2.ninputs`` does not equal ``sys1.noutputs``
-        if ``sys1.dt`` is not compatible with ``sys2.dt``
+        If `sys2.ninputs` does not equal `sys1.noutputs` or if `sys1.dt` is
+        not compatible with `sys2.dt`.
 
     See Also
     --------
@@ -72,8 +72,8 @@ def series(*sys, **kwargs):
     system class.  The output type is the type of `sys1` unless a more
     general type is required based on type type of `sys2`.
 
-    If both systems have a defined timebase (dt = 0 for continuous time,
-    dt > 0 for discrete time), then the timebase for both systems must
+    If both systems have a defined timebase (`dt` = 0 for continuous time,
+    `dt` > 0 for discrete time), then the timebase for both systems must
     match.  If only one of the system has a timebase, the return
     timebase will be set to match it.
 
@@ -143,8 +143,8 @@ def parallel(*sys, **kwargs):
     the type of `sys1`.  If `sys1` is a scalar, then the output type is
     the type of `sys2`.
 
-    If both systems have a defined timebase (dt = 0 for continuous time,
-    dt > 0 for discrete time), then the timebase for both systems must
+    If both systems have a defined timebase (`dt` = 0 for continuous time,
+    `dt` > 0 for discrete time), then the timebase for both systems must
     match.  If only one of the system has a timebase, the return
     timebase will be set to match it.
 

control/canonical.py

@@ -498,7 +498,7 @@ def modal_form(xsys, condmax=None, sort=False):
     Parameters
     ----------
     xsys : StateSpace object
-        System to be transformed, with state ``x``.
+        System to be transformed, with state x.
     condmax : None or float, optional
         An upper bound on individual transformations.  If None, use
         `bdschur` default.
@@ -509,7 +509,7 @@ def modal_form(xsys, condmax=None, sort=False):
     Returns
     -------
     zsys : StateSpace object
-        System in modal canonical form, with state ``z``.
+        System in modal canonical form, with state z.
     T : (M, M) ndarray
         Coordinate transformation: z = T * x.
 

control/ctrlplot.py

@@ -148,7 +148,7 @@ class ControlPlot():
         Figure on which the Axes are drawn.
     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``
+        included, this will be an array with each entry being either None
         (for no legend) or a legend object.
 
     """

control/ctrlutil.py

@@ -24,7 +24,7 @@ def unwrap(angle, period=2*math.pi):
     angle : array_like
         Array of angles to be unwrapped.
     period : float, optional
-        Period (defaults to ``2*pi``).
+        Period (defaults to 2 pi).
 
     Returns
     -------

control/descfcn.py

@@ -626,9 +626,9 @@ class relay_hysteresis_nonlinearity(DescribingFunctionNonlinearity):
 
         F = relay_hysteresis_nonlinearity(b, c)
 
-    The output of this function is ``b`` if ``x > c`` and ``-b`` if ``x <
-    -c``.  For ``-c <= x <= c``, the value depends on the branch of the
-    hysteresis loop (as illustrated in Figure 10.20 of FBS2e).
+    The output of this function is b if x > c and -b if x < -c.  For -c <=
+    x <= c, the value depends on the branch of the hysteresis loop (as
+    illustrated in Figure 10.20 of FBS2e).
 
     Parameters
     ----------
@@ -702,9 +702,9 @@ class friction_backlash_nonlinearity(DescribingFunctionNonlinearity):
         F = friction_backlash_nonlinearity(b)
 
     This function maintains an internal state representing the 'center' of
-    a mechanism with backlash.  If the new input is within ``b/2`` of the
+    a mechanism with backlash.  If the new input is within b/2 of the
     current center, the output is unchanged.  Otherwise, the output is
-    given by the input shifted by ``b/2``.
+    given by the input shifted by b/2.
 
     Parameters
     ----------

control/flatsys/flatsys.py

@@ -184,12 +184,15 @@ def flatsys(*args, updfcn=None, outfcn=None, **kwargs):
     variety of forms:
 
     ``fs.flatsys(forward, reverse)``
+
         Create a flat system with mapings to/from flat flag.
 
     ``fs.flatsys(forward, reverse, updfcn[, outfcn])``
+
         Create a flat system that is also a nonlinear I/O system.
 
     ``fs.flatsys(linsys)``
+
         Create a flat system from a linear (StateSpace) system.
 
     Parameters

control/flatsys/systraj.py

@@ -122,9 +122,9 @@ def response(self, tlist, transpose=False, return_x=False, squeeze=None):
         squeeze : bool, optional
             By default, if a system is single-input, single-output (SISO)
             then the output response is returned as a 1D array (indexed by
-            time).  If ``squeeze=True`, remove single-dimensional entries
+            time).  If `squeeze` = True, remove single-dimensional entries
             from the shape of the output even if the system is not SISO. If
-            ``squeeze=False``, keep the output as a 3D array (indexed by
+            `squeeze` = False, keep the output as a 3D array (indexed by
             the output, input, and time) even if the system is SISO. The
             default value can be set using
             `config.defaults['control.squeeze_time_response']`.

control/frdata.py

@@ -64,9 +64,9 @@ class constructor, using the `frd` factory function, or
         frequency) and if a system is multi-input or multi-output, then the
         outputs are returned as a 2D array (indexed by output and
         frequency) or a 3D array (indexed by output, trace, and frequency).
-        If ``squeeze=True``, access to the output response will remove
+        If `squeeze` = True, access to the output response will remove
         single-dimensional entries from the shape of the inputs and outputs
-        even if the system is not SISO. If ``squeeze=False``, the output is
+        even if the system is not SISO. If `squeeze` = False, the output is
         returned as a 3D array (indexed by the output, input, and
         frequency) even if the system is SISO. The default value can be set
         using `config.defaults['control.squeeze_frequency_response']`.
@@ -106,10 +106,10 @@ class constructor, using the `frd` factory function, or
         If set to False, don't plot the magnitude or phase, respectively.
     return_magphase : bool, optional
         If True, then a frequency response data object will enumerate
-        as a tuple of the form ``(mag, phase, omega)`` where where ``mag``
+        as a tuple of the form ``(mag, phase, omega)`` where 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
+        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.
 
     See Also
@@ -174,9 +174,9 @@ class constructor, using the `frd` factory function, or
     #: frequency) and if a system is multi-input or multi-output, then the
     #: outputs are returned as a 2D array (indexed by output and frequency)
     #: or a 3D array (indexed by output, trace, and frequency).  If
-    #: ``squeeze=True``, access to the output response will remove
+    #: `squeeze` = True, access to the output response will remove
     #: single-dimensional entries from the shape of the inputs and outputs
-    #: even if the system is not SISO. If ``squeeze=False``, the output is
+    #: even if the system is not SISO. If `squeeze` = False, the output is
     #: returned as a 3D array (indexed by the output, input, and frequency)
     #: even if the system is SISO. The default value can be set using
     #: config.defaults['control.squeeze_frequency_response'].
@@ -623,9 +623,9 @@ def eval(self, omega, squeeze=None):
         omega : float or 1D array_like
             Frequencies in radians per second.
         squeeze : bool, optional
-            If ``squeeze=True``, remove single-dimensional entries from
+            If `squeeze` = True, remove single-dimensional entries from
             the shape of the output even if the system is not SISO. If
-            ``squeeze=False``, keep all indices (output, input and, if omega
+            `squeeze` = False, keep all indices (output, input and, if omega
             is array_like, frequency) even if the system is SISO. The
             default value can be set using
             `config.defaults['control.squeeze_frequency_response']`.
@@ -694,19 +694,19 @@ def __call__(self, s=None, squeeze=None, return_magphase=None):
             processing (`squeeze`, `return_magphase`).
 
         squeeze : bool, optional
-            If ``squeeze=True``, remove single-dimensional entries from the
+            If `squeeze` = True, remove single-dimensional entries from the
             shape of the output even if the system is not SISO. If
-            ``squeeze=False``, keep all indices (output, input and, if
+            `squeeze` = False, keep all indices (output, input and, if
             omega is array_like, frequency) even if the system is SISO. The
             default value can be set using
             `config.defaults['control.squeeze_frequency_response']`.
 
         return_magphase : bool, optional
             If True, then a frequency response data object will
             enumerate as a tuple of the form ``(mag, phase, omega)`` where
-            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
+            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.
 
         Returns
@@ -828,9 +828,9 @@ def plot(self, plot_type=None, *args, **kwargs):
         """Plot the frequency response using Bode or singular values plot.
 
         Plot the frequency response using either a standard Bode plot
-        (``plot_type='bode'``, default) or a singular values plot
-        (``plot_type='svplot'``).  See `bode_plot` and
-        `singular_values_plot` for more detailed descriptions.
+        (plot_type='bode', default) or a singular values plot
+        (plot_type='svplot').  See `bode_plot` and `singular_values_plot`
+        for more detailed descriptions.
 
         """
         from .freqplot import bode_plot, singular_values_plot
@@ -961,10 +961,12 @@ def frd(*args, **kwargs):
     of a system.  This factory function can be called in different ways:
 
     ``frd(response, omega)``
+
         Create an frd model with the given response data, in the form of
         complex response vector, at matching frequencies `omega` [in rad/s].
 
     ``frd(sys, omega)``
+
         Convert an LTI system into an frd model with data at frequencies
         `omega`.
 

control/freqplot.py

@@ -244,15 +244,15 @@ def bode_plot(
     Starting with python-control version 0.10, `bode_plot` returns a
     `ControlPlot` object instead of magnitude, phase, and
     frequency. To recover the old behavior, call `bode_plot` with
-    ``plot=True``, which will force the legacy values (mag, phase, omega) to
+    `plot` = True, which will force the legacy values (mag, phase, omega) to
     be returned (with a warning).  To obtain just the frequency response of
     a system (or list of systems) without plotting, use the
     `frequency_response` command.
 
     If a discrete time model is given, the frequency response is plotted
     along the upper branch of the unit circle, using the mapping ``z =
-    exp(1j * omega * dt)`` where `omega` ranges from 0 to ``pi/dt`` and `dt`
-    is the discrete timebase.  If timebase not specified (``dt=True``),
+    exp(1j * omega * dt)`` where `omega` ranges from 0 to pi/`dt` and `dt`
+    is the discrete timebase.  If timebase not specified (`dt` = True),
     `dt` is set to 1.
 
     The default values for Bode plot configuration parameters can be reset
@@ -1254,9 +1254,9 @@ def nyquist_response(
     -----
     If a discrete time model is given, the frequency response is computed
     along the upper branch of the unit circle, using the mapping ``z =
-    exp(1j * omega * dt)`` where `omega` ranges from 0 to ``pi/dt`` and
+    exp(1j * omega * dt)`` where `omega` ranges from 0 to pi/`dt` and
     `dt` is the discrete timebase.  If timebase not specified
-    (``dt=True``), `dt` is set to 1.
+    (`dt` = True), `dt` is set to 1.
 
     If a continuous-time system contains poles on or near the imaginary
     axis, a small indentation will be used to avoid the pole.  The radius
@@ -1707,9 +1707,9 @@ def nyquist_plot(
     -----
     If a discrete time model is given, the frequency response is computed
     along the upper branch of the unit circle, using the mapping ``z =
-    exp(1j * omega * dt)`` where `omega` ranges from 0 to ``pi/dt`` and
+    exp(1j * omega * dt)`` where `omega` ranges from 0 to pi/`dt` and
     `dt` is the discrete timebase.  If timebase not specified
-    (``dt=True``), `dt` is set to 1.
+    (`dt` = True), `dt` is set to 1.
 
     If a continuous-time system contains poles on or near the imaginary
     axis, a small indentation will be used to avoid the pole.  The radius
@@ -2441,12 +2441,12 @@ def singular_values_plot(
 
     Notes
     -----
-    If ``plot=False``, the following legacy values are returned:
-       * mag : ndarray (or list of ndarray if len(data) > 1))
+    If `plot` = `False`, the following legacy values are returned:
+       * `mag` : ndarray (or list of ndarray if len(data) > 1))
            Magnitude of the response (deprecated).
-       * phase : ndarray (or list of ndarray if len(data) > 1))
+       * `phase` : ndarray (or list of ndarray if len(data) > 1))
            Phase in radians of the response (deprecated).
-       * omega : ndarray (or list of ndarray if len(data) > 1))
+       * `omega` : ndarray (or list of ndarray if len(data) > 1))
            Frequency in rad/sec (deprecated).
 
     """

control/iosys.py

@@ -116,10 +116,10 @@ class InputOutputSystem():
     is operating in continuous or discrete time. It can have the following
     values:
 
-      * ``dt = None``   No timebase specified
-      * ``dt = 0``      Continuous time system
-      * ``dt > 0``      Discrete time system with sampling time dt
-      * ``dt = True``   Discrete time system with unspecified sampling time
+      * `dt` = None: No timebase specified
+      * `dt` = 0: Continuous time system
+      * `dt` > 0: Discrete time system with sampling time dt
+      * `dt` = True: Discrete time system with unspecified sampling time
 
     Parameters
     ----------
@@ -673,15 +673,15 @@ def timebase(sys, strict=True):
     dt = timebase(sys)
 
     returns the timebase for a system 'sys'.  If the strict option is
-    set to True, ``dt = True`` will be returned as 1.
+    set to True, `dt` = True will be returned as 1.
 
     Parameters
     ----------
     sys : InputOutputSystem or float
         System whose timebase is to be determined.
     strict : bool, optional
         Whether to implement strict checking.  If set to True (default),
-        a float will always be returned (``dt = True`` will be returned as 1).
+        a float will always be returned (`dt` = True will be returned as 1).
 
     Returns
     -------