reformat numbered notes sections

Author: murrayrm

control/flatsys/flatsys.py

@@ -57,15 +57,17 @@ class FlatSystem(NonlinearIOSystem):
     -----
     The class must implement two functions:
 
-    zflag = flatsys.foward(x, u, params)
+    ``zflag = flatsys.foward(x, u, params)``
+
         This function computes the flag (derivatives) of the flat output.
         The inputs to this function are the state 'x' and inputs 'u' (both
         1D arrays).  The output should be a 2D array with the first
         dimension equal to the number of system inputs and the second
         dimension of the length required to represent the full system
         dynamics (typically the number of states)
 
-    x, u = flatsys.reverse(zflag, params)
+    ``x, u = flatsys.reverse(zflag, params)``
+
         This function system state and inputs give the the flag (derivatives)
         of the flat output.  The input to this function is an 2D array whose
         first dimension is equal to the number of system inputs and whose
@@ -737,19 +739,20 @@ def solve_flat_ocp(
 
     Notes
     -----
-    1. Additional keyword parameters can be used to fine tune the behavior
-       of the underlying optimization function.  See `minimize_*` keywords
-       in `optimal.OptimalControlProblem` for more information.
-
-    2. The return data structure includes the following additional attributes:
-           * success : bool indicating whether the optimization succeeded
-           * cost : computed cost of the returned trajectory
-           * message : message returned by optimization if success if False
-
-    3. A common failure in solving optimal control problem is that the
-       default initial guess violates the constraints and the optimizer
-       can't find a feasible solution.  Using the `initial_guess` parameter
-       can often be used to overcome these errors.
+    Additional keyword parameters can be used to fine tune the behavior of
+    the underlying optimization function.  See `minimize_*` keywords in
+    `optimal.OptimalControlProblem` for more information.
+
+    The return data structure includes the following additional attributes:
+
+        * success : bool indicating whether the optimization succeeded
+        * cost : computed cost of the returned trajectory
+        * message : message returned by optimization if success if False
+
+    A common failure in solving optimal control problem is that the default
+    initial guess violates the constraints and the optimizer can't find a
+    feasible solution.  Using the `initial_guess` parameter can often be
+    used to overcome these errors.
 
     """
     #

control/lti.py

@@ -318,19 +318,20 @@ def damp(sys, doprint=True):
 
     Notes
     -----
-    If the system is continuous,
-        wn = abs(poles)
-        zeta  = -real(poles)/poles
+    If the system is continuous
+
+        | ``wn = abs(poles)``
+        | ``zeta  = -real(poles)/poles``
 
     If the system is discrete, the discrete poles are mapped to their
     equivalent location in the s-plane via
 
-        s = log(poles)/dt
+        | ``s = log(poles)/dt``
 
     and
 
-        wn = abs(s)
-        zeta = -real(s)/wn.
+        | ``wn = abs(s)``
+        | ``zeta = -real(s)/wn``
 
     Examples
     --------
@@ -479,20 +480,19 @@ def frequency_response(
 
     Notes
     -----
-    1. This function is a wrapper for `StateSpace.frequency_response`
-       and `TransferFunction.frequency_response`.
-
-    2. You can also use the lower-level methods ``sys(s)`` or ``sys(z)`` to
-       generate the frequency response for a single system.
-
-    3. All frequency data should be given in rad/sec.  If frequency limits
-       are computed automatically, the `Hz` keyword can be used to ensure
-       that limits are in factors of decades in Hz, so that Bode plots with
-       ``Hz=True`` look better.
-
-    4. The frequency response data can be plotted by calling the
-       `bode_plot` function or using the `plot` method of
-       the `FrequencyResponseData` class.
+    This function is a wrapper for `StateSpace.frequency_response` and
+    `TransferFunction.frequency_response`.  You can also use the
+    lower-level methods ``sys(s)`` or ``sys(z)`` to generate the frequency
+    response for a single system.
+
+    All frequency data should be given in rad/sec.  If frequency limits are
+    computed automatically, the `Hz` keyword can be used to ensure that
+    limits are in factors of decades in Hz, so that Bode plots with
+    ``Hz=True`` look better.
+
+    The frequency response data can be plotted by calling the `bode_plot`
+    function or using the `plot` method of the `FrequencyResponseData`
+    class.
 
     Examples
     --------

control/nlsys.py

@@ -1538,22 +1538,22 @@ def input_output_response(
 
     Notes
     -----
-    1. If a smaller number of initial conditions are given than the number of
-       states in the system, the initial conditions will be padded with
-       zeros.  This is often useful for interconnected control systems where
-       the process dynamics are the first system and all other components
-       start with zero initial condition since this can be specified as
-       [xsys_0, 0].  A warning is issued if the initial conditions are padded
-       and and the final listed initial state is not zero.
-
-    2. If discontinuous inputs are given, the underlying SciPy numerical
-       integration algorithms can sometimes produce erroneous results due
-       to the default tolerances that are used.  The `ivp_method` and
-       `ivp_keywords` parameters can be used to tune the ODE solver and
-       produce better results.  In particular, using 'LSODA' as the
-       `ivp_method` or setting the `rtol` parameter to a smaller value
-       (e.g. using ``ivp_kwargs={'rtol': 1e-4}``) can provide more accurate
-       results.
+    If a smaller number of initial conditions are given than the number of
+    states in the system, the initial conditions will be padded with zeros.
+    This is often useful for interconnected control systems where the
+    process dynamics are the first system and all other components start
+    with zero initial condition since this can be specified as [xsys_0, 0].
+    A warning is issued if the initial conditions are padded and and the
+    final listed initial state is not zero.
+
+    If discontinuous inputs are given, the underlying SciPy numerical
+    integration algorithms can sometimes produce erroneous results due to
+    the default tolerances that are used.  The `ivp_method` and
+    `ivp_keywords` parameters can be used to tune the ODE solver and
+    produce better results.  In particular, using 'LSODA' as the
+    `ivp_method` or setting the `rtol` parameter to a smaller value
+    (e.g. using ``ivp_kwargs={'rtol': 1e-4}``) can provide more accurate
+    results.
 
     """
     #

control/optimal.py

@@ -1111,19 +1111,19 @@ def solve_ocp(
 
     Notes
     -----
-    1. For discrete time systems, the final value of the timepts vector
-       specifies the final time t_N, and the trajectory cost is computed
-       from time t_0 to t_{N-1}.  Note that the input u_N does not affect
-       the state x_N and so it should always be returned as 0.  Further, if
-       neither a terminal cost nor a terminal constraint is given, then the
-       input at time point t_{N-1} does not affect the cost function and
-       hence u_{N-1} will also be returned as zero.  If you want the
-       trajectory cost to include state costs at time t_{N}, then you can
-       set `terminal_cost` to be the same function as `cost`.
-
-    2. Additional keyword parameters can be used to fine-tune the behavior
-       of the underlying optimization and integration functions.  See
-       `OptimalControlProblem` for more information.
+    For discrete time systems, the final value of the timepts vector
+    specifies the final time t_N, and the trajectory cost is computed from
+    time t_0 to t_{N-1}.  Note that the input u_N does not affect the state
+    x_N and so it should always be returned as 0.  Further, if neither a
+    terminal cost nor a terminal constraint is given, then the input at
+    time point t_{N-1} does not affect the cost function and hence u_{N-1}
+    will also be returned as zero.  If you want the trajectory cost to
+    include state costs at time t_{N}, then you can set `terminal_cost` to
+    be the same function as `cost`.
+
+    Additional keyword parameters can be used to fine-tune the behavior of
+    the underlying optimization and integration functions.  See
+    `OptimalControlProblem` for more information.
 
     """
     # Process keyword arguments

control/statefbk.py

@@ -66,15 +66,13 @@ def place(A, B, p):
 
     Notes
     -----
-    Algorithm
-        This is a wrapper function for `scipy.signal.place_poles`, which
-        implements the Tits and Yang algorithm [1]_. It will handle SISO,
-        MISO, and MIMO systems. If you want more control over the algorithm,
-        use `scipy.signal.place_poles` directly.
-
-    Limitations
-        The algorithm will not place poles at the same location more
-        than rank(B) times.
+    This is a wrapper function for `scipy.signal.place_poles`, which
+    implements the Tits and Yang algorithm [1]_. It will handle SISO, MISO,
+    and MIMO systems. If you want more control over the algorithm, use
+    `scipy.signal.place_poles` directly.
+
+    Limitations: The algorithm will not place poles at the same location
+    more than rank(B) times.
 
     References
     ----------

control/statesp.py

@@ -1272,7 +1272,7 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
 
         Notes
         -----
-        Uses `scipy.signal.cont2discrete`
+        Uses `scipy.signal.cont2discrete`.
 
         Examples
         --------

control/timeplot.py

@@ -160,22 +160,21 @@ def time_response_plot(
 
     Notes
     -----
-    1. A new figure will be generated if there is no current figure or
-       the current figure has an incompatible number of axes.  To
-       force the creation of a new figures, use `plt.figure`.  To reuse
-       a portion of an existing figure, use the ``ax`` keyword.
-
-    2. The line properties (color, linestyle, etc) can be set for the
-       entire plot using the `fmt` and/or `kwargs` parameter, which
-       are passed on to `matplotlib`.  When combining signals or
-       traces, the `input_props`, `output_props`, and `trace_props`
-       parameters can be used to pass a list of dictionaries
-       containing the line properties to use.  These input/output
-       properties are combined with the trace properties and finally
-       the kwarg properties to determine the final line properties.
-
-    3. The default plot properties, such as font sizes, can be set using
-       `config.defaults[''timeplot.rcParams']`.
+    A new figure will be generated if there is no current figure or the
+    current figure has an incompatible number of axes.  To force the
+    creation of a new figures, use `plt.figure`.  To reuse a portion of an
+    existing figure, use the ``ax`` keyword.
+
+    The line properties (color, linestyle, etc) can be set for the entire
+    plot using the `fmt` and/or `kwargs` parameter, which are passed on to
+    `matplotlib`.  When combining signals or traces, the `input_props`,
+    `output_props`, and `trace_props` parameters can be used to pass a list
+    of dictionaries containing the line properties to use.  These
+    input/output properties are combined with the trace properties and
+    finally the kwarg properties to determine the final line properties.
+
+    The default plot properties, such as font sizes, can be set using
+    `config.defaults[''timeplot.rcParams']`.
 
     """
     from .ctrlplot import _process_ax_keyword, _process_line_labels

control/timeresp.py

@@ -997,22 +997,22 @@ def forced_response(sysdata, T=None, U=0., X0=0., transpose=False, params=None,
 
     Notes
     -----
-    1. For discrete time systems, the input/output response is computed
-       using the `scipy.signal.dlsim` function.
-
-    2. For continuous time systems, the output is computed using the matrix
-       exponential ``exp(A t)`` and assuming linear interpolation of the
-       inputs between time points.
-
-    3. If a nonlinear I/O system is passed to `forced_response`, the
-       `input_output_response` function is called instead.  The main
-       difference between `input_output_response` and `forced_response` is
-       that `forced_response` is specialized (and optimized) for linear
-       systems.
-
-    4. (legacy) The return value of the system can also be accessed by
-        assigning the function to a tuple of length 2 (time, output) or of
-        length 3 (time, output, state) if `return_x` is True.
+    For discrete time systems, the input/output response is computed
+    using the `scipy.signal.dlsim` function.
+
+    For continuous time systems, the output is computed using the
+    matrix exponential ``exp(A t)`` and assuming linear interpolation
+    of the inputs between time points.
+
+    If a nonlinear I/O system is passed to `forced_response`, the
+    `input_output_response` function is called instead.  The main
+    difference between `input_output_response` and `forced_response`
+    is that `forced_response` is specialized (and optimized) for
+    linear systems.
+
+    (legacy) The return value of the system can also be accessed by
+    assigning the function to a tuple of length 2 (time, output) or of
+    length 3 (time, output, state) if `return_x` is True.
 
     Examples
     --------

control/xferfcn.py

@@ -1168,9 +1168,7 @@ def sample(self, Ts, method='zoh', alpha=None, prewarp_frequency=None,
 
         Notes
         -----
-        1. Available only for SISO systems
-
-        2. Uses `scipy.signal.cont2discrete`
+        Available only for SISO systems.  Uses `scipy.signal.cont2discrete`.
 
         Examples
         --------