updated docstrings and docs, trim slow unit tests

murrayrm · murrayrm · commit df4508c39021 · 2023-03-18T10:36:19.000-07:00
diff --git a/control/optimal.py b/control/optimal.py
@@ -1038,7 +1038,7 @@ def solve_ocp(
 
     Notes
     -----
-    Additional keyword parameters can be used to fine tune the behavior of
+    Additional keyword parameters can be used to fine-tune the behavior of
     the underlying optimization and integration functions.  See
     :func:`OptimalControlProblem` for more information.
 
@@ -1138,7 +1138,7 @@ def create_mpc_iosystem(
 
     Notes
     -----
-    Additional keyword parameters can be used to fine tune the behavior of
+    Additional keyword parameters can be used to fine-tune the behavior of
     the underlying optimization and integrations functions.  See
     :func:`OptimalControlProblem` for more information.
 
@@ -1189,15 +1189,15 @@ class OptimalEstimationProblem():
     control_indices : int, slice, or list of int or string, optional
         Specify the indices in the system input vector that correspond to
         the control inputs.  These inputs will be used as known control
-        inputs for the estimate.  If value is an integer `m`, the first `m`
-        system inputs are used.  Otherwise, the value should be a slice or
-        a list of indices.  The list of indices can be specified as either
-        integer offsets or as system input signal names.  If not specified,
-        defaults to the complement of the disturbance indices (see also
-        notes below).
+        inputs for the estimator.  If value is an integer `m`, the first
+        `m` system inputs are used.  Otherwise, the value should be a slice
+        or a list of indices.  The list of indices can be specified as
+        either integer offsets or as system input signal names.  If not
+        specified, defaults to the complement of the disturbance indices
+        (see also notes below).
     disturbance_indices : int, list of int, or slice, optional
         Specify the indices in the system input vector that correspond to
-        the input disturbances.  If value is an integer `m`, the last `m`
+        the process disturbances.  If value is an integer `m`, the last `m`
         system inputs are used.  Otherwise, the value should be a slice or
         a list of indices, as describedf for `control_indices`.  If not
         specified, defaults to the complement of the control indicies (see
@@ -1227,14 +1227,13 @@ class OptimalEstimationProblem():
 
     Notes
     -----
-    To describe an optimal estimation problem we need an input/output
-    system, a set of time points, measured inputs and outputs, a cost
-    function, and (optionally) a set of constraints on the state
-    and/or inputs along the trajectory (and at the terminal time).
-    This class sets up an optimization over the state and disturbances
-    at each point in time, using the integral and terminal costs as
-    well as the trajectory constraints.  The
-    :func:`~control.optimal.OptimalEstimationProblem.compute_estimate`
+    To describe an optimal estimation problem we need an input/output system,
+    a set of time points, applied inputs and measured outputs, a cost
+    function, and (optionally) a set of constraints on the state and/or inputs
+    along the trajectory (and at the terminal time).  This class sets up an
+    optimization over the state and disturbances at each point in time, using
+    the integral and terminal costs as well as the trajectory constraints.
+    The :func:`~control.optimal.OptimalEstimationProblem.compute_estimate`
     method solves the underling optimization problem using
     :func:`scipy.optimize.minimize`.
 
@@ -1245,12 +1244,11 @@ class OptimalEstimationProblem():
     the same as the control inputs.
 
     The "cost" (e.g. negative of the log likelihood) of the estimated
-    trajectory generated by the estimated state, the disturbances and
-    noise, and the measured output.  It does this by calling a user-defined
-    function for the integral_cost given the current estimated states,
-    inputs, and measured outputs at each point along the trajectory and
-    then adding the value of a user-defined terminal cost at the initial
-    point in the trajectory.
+    trajectory is computed using the estimated state, the disturbances and
+    noise, and the measured output.  This is done by calling a user-defined
+    function for the integral_cost along the trajectory and then adding the
+    value of a user-defined terminal cost at the initial point in the
+    trajectory.
 
     The constraint functions are evaluated at each point on the trajectory
     generated by the proposed estimate and disturbances.  As in the case of
@@ -1261,8 +1259,8 @@ class OptimalEstimationProblem():
     so that it only needs to be computed once.
 
     The default values for ``minimize_method``, ``minimize_options``,
-    ``minimize_kwargs``, ``solve_ivp_method``, and ``solve_ivp_options`` can
-    be set using config.defaults['optimal.<keyword>'].
+    ``minimize_kwargs``, ``solve_ivp_method``, and ``solve_ivp_options``
+    can be set using config.defaults['optimal.<keyword>'].
 
     """
     def __init__(
@@ -1628,7 +1626,7 @@ def compute_estimate(
         -------
         res : OptimalEstimationResult
             Bundle object with the results of the optimal estimation problem.
-        res.success: bool
+        res.success : bool
             Boolean flag indicating whether the optimization was successful.
         res.time : array
             Time values of the input (same as self.timepts).
@@ -1929,27 +1927,26 @@ def solve_oep(
     -------
     res : TimeResponseData
         Bundle object with the estimated state and noise values.
-
-        res.success : bool
-            Boolean flag indicating whether the optimization was successful.
-        res.time : array
-            Time values of the input.
-        res.inputs : array
-            Disturbance values corresponding to the estimated state.  If
-            the system is SISO and squeeze is not True, the array is 1D
-            (indexed by time).  If the system is not SISO or squeeze is
-            False, the array is 2D (indexed by the output number and time).
-        res.states : array
-            Estimated state vector over the given time points.
-        res.outputs : array
-            Noise values corresponding to the estimated state.  If the
-            system is SISO and squeeze is not True, the array is 1D
-            (indexed by time).  If the system is not SISO or squeeze is
-            False, the array is 2D (indexed by the output number and time).
+    res.success : bool
+        Boolean flag indicating whether the optimization was successful.
+    res.time : array
+        Time values of the input.
+    res.inputs : array
+        Disturbance values corresponding to the estimated state.  If the
+        system is SISO and squeeze is not True, the array is 1D (indexed by
+        time).  If the system is not SISO or squeeze is False, the array is
+        2D (indexed by the output number and time).
+    res.states : array
+        Estimated state vector over the given time points.
+    res.outputs : array
+        Noise values corresponding to the estimated state.  If the system
+        is SISO and squeeze is not True, the array is 1D (indexed by time).
+        If the system is not SISO or squeeze is False, the array is 2D
+        (indexed by the output number and time).
 
     Notes
     -----
-    Additional keyword parameters can be used to fine tune the behavior of
+    Additional keyword parameters can be used to fine-tune the behavior of
     the underlying optimization and integration functions.  See
     :func:`~control.optimal.OptimalControlProblem` for more information.
 
diff --git a/control/statefbk.py b/control/statefbk.py
@@ -341,11 +341,11 @@ def lqr(*args, **kwargs):
     integral_action : ndarray, optional
         If this keyword is specified, the controller includes integral
         action in addition to state feedback.  The value of the
-        `integral_action`` keyword should be an ndarray that will be
+        `integral_action` keyword should be an ndarray that will be
         multiplied by the current state to generate the error for the
         internal integrator states of the control law.  The number of
         outputs that are to be integrated must match the number of
-        additional rows and columns in the ``Q`` matrix.
+        additional rows and columns in the `Q` matrix.
     method : str, optional
         Set the method used for computing the result.  Current methods are
         'slycot' and 'scipy'.  If set to None (default), try 'slycot' first
@@ -491,11 +491,11 @@ def dlqr(*args, **kwargs):
     integral_action : ndarray, optional
         If this keyword is specified, the controller includes integral
         action in addition to state feedback.  The value of the
-        `integral_action`` keyword should be an ndarray that will be
+        `integral_action` keyword should be an ndarray that will be
         multiplied by the current state to generate the error for the
         internal integrator states of the control law.  The number of
         outputs that are to be integrated must match the number of
-        additional rows and columns in the ``Q`` matrix.
+        additional rows and columns in the `Q` matrix.
     method : str, optional
         Set the method used for computing the result.  Current methods are
         'slycot' and 'scipy'.  If set to None (default), try 'slycot' first
@@ -617,9 +617,9 @@ def create_statefbk_iosystem(
 
         ctrl, clsys = ct.create_statefbk_iosystem(sys, K)
 
-    where ``sys`` is the process dynamics and ``K`` is the state (+ integral)
+    where `sys` is the process dynamics and `K` is the state (+ integral)
     feedback gain (eg, from LQR).  The function returns the controller
-    ``ctrl`` and the closed loop systems ``clsys``, both as I/O systems.
+    `ctrl` and the closed loop systems `clsys`, both as I/O systems.
 
     A gain scheduled controller can also be created, by passing a list of
     gains and a corresponding list of values of a set of scheduling
@@ -636,32 +636,32 @@ def create_statefbk_iosystem(
         is given, the output of this system should represent the full state.
 
     gain : ndarray or tuple
-        If a array is give, it represents the state feedback gain (K).
+        If an array is given, it represents the state feedback gain (K).
         This matrix defines the gains to be applied to the system.  If
-        ``integral_action`` is None, then the dimensions of this array
+        `integral_action` is None, then the dimensions of this array
         should be (sys.ninputs, sys.nstates).  If `integral action` is
         set to a matrix or a function, then additional columns
         represent the gains of the integral states of the controller.
 
         If a tuple is given, then it specifies a gain schedule.  The tuple
-        should be of the form ``(gains, points)`` where gains is a list of
+        should be of the form `(gains, points)` where gains is a list of
         gains :math:`K_j` and points is a list of values :math:`\\mu_j` at
         which the gains are computed.  The `gainsched_indices` parameter
         should be used to specify the scheduling variables.
 
     xd_labels, ud_labels : str or list of str, optional
-        Set the name of the signals to use for the desired state and inputs.
-        If a single string is specified, it should be a format string using
-        the variable ``i`` as an index.  Otherwise, a list of strings
-        matching the size of xd and ud, respectively, should be used.
-        Default is ``'xd[{i}]'`` for xd_labels and ``'ud[{i}]'`` for
-        ud_labels.  These settings can also be overriden using the `inputs`
-        keyword.
+        Set the name of the signals to use for the desired state and
+        inputs.  If a single string is specified, it should be a
+        format string using the variable `i` as an index.  Otherwise,
+        a list of strings matching the size of xd and ud,
+        respectively, should be used.  Default is "xd[{i}]" for
+        xd_labels and "ud[{i}]" for ud_labels.  These settings can
+        also be overriden using the `inputs` keyword.
 
     integral_action : ndarray, optional
         If this keyword is specified, the controller can include integral
         action in addition to state feedback.  The value of the
-        `integral_action`` keyword should be an ndarray that will be
+        `integral_action` keyword should be an ndarray that will be
         multiplied by the current and desired state to generate the error
         for the internal integrator states of the control law.
 
@@ -678,7 +678,7 @@ def create_statefbk_iosystem(
         [xd, ud, x] vector are used.  Otherwise, the value should be a
         slice or a list of indices.  The list of indices can be specified
         as either integer offsets or as signal names.  The default is to
-        use the desire state xd.
+        use the desired state xd.
 
     gainsched_method : str, optional
         The method to use for gain scheduling.  Possible values are 'linear'
@@ -691,28 +691,29 @@ def create_statefbk_iosystem(
         Set the type of controller to create. The default for a linear gain
         is a linear controller implementing the LQR regulator. If the type
         is 'nonlinear', a :class:NonlinearIOSystem is created instead, with
-        the gain ``K`` as a parameter (allowing modifications of the gain at
+        the gain `K` as a parameter (allowing modifications of the gain at
         runtime). If the gain parameter is a tuple, then a nonlinear,
         gain-scheduled controller is created.
 
     Returns
     -------
     ctrl : InputOutputSystem
-        Input/output system representing the controller.  This system takes
-        as inputs the desired state ``xd``, the desired input ``ud``, and
-        either the system state ``x`` or the estimated state ``xhat``.  It
-        outputs the controller action u according to the formula :math:`u =
-        u_d - K(x - x_d)`.  If the keyword ``integral_action`` is specified,
-        then an additional set of integrators is included in the control
-        system (with the gain matrix ``K`` having the integral gains
-        appended after the state gains).  If a gain scheduled controller is
-        specified, the gain (proportional and integral) are evaluated using
-        the scheduling variables specified by ``gainsched_indices``.
+        Input/output system representing the controller.  This system
+        takes as inputs the desired state `xd`, the desired input
+        `ud`, and either the system state `x` or the estimated state
+        `xhat`.  It outputs the controller action `u` according to the
+        formula :math:`u = u_d - K(x - x_d)`.  If the keyword
+        `integral_action` is specified, then an additional set of
+        integrators is included in the control system (with the gain
+        matrix `K` having the integral gains appended after the state
+        gains).  If a gain scheduled controller is specified, the gain
+        (proportional and integral) are evaluated using the scheduling
+        variables specified by `gainsched_indices`.
 
     clsys : InputOutputSystem
         Input/output system representing the closed loop system.  This
-        systems takes as inputs the desired trajectory ``(xd, ud)`` and
-        outputs the system state ``x`` and the applied input ``u``
+        systems takes as inputs the desired trajectory `(xd, ud)` and
+        outputs the system state `x` and the applied input `u`
         (vertically stacked).
 
     Other Parameters
diff --git a/control/stochsys.py b/control/stochsys.py
@@ -312,7 +312,6 @@ def dlqe(*args, **kwargs):
 # Function to create an estimator
 #
 # TODO: create predictor/corrector, UKF, and other variants (?)
-# TODO: change *_labels to *_fmtstr and use signal keywords instead
 #
 def create_estimator_iosystem(
         sys, QN, RN, P0=None, G=None, C=None,
@@ -344,19 +343,17 @@ def create_estimator_iosystem(
         estim = ct.create_estimator_iosystem(sys, QN, RN)
 
     where `sys` is the process dynamics and `QN` and `RN` are the covariance
-    of the disturbance noise and sensor noise.  The function returns the
-    estimator `estim` as I/O system with a parameter `correct` that can
+    of the disturbance noise and measurement noise.  The function returns
+    the estimator `estim` as I/O system with a parameter `correct` that can
     be used to turn off the correction term in the estimation (for forward
     predictions).
 
     Parameters
     ----------
     sys : LinearIOSystem
-        The linear I/O system that represents the process dynamics.  If no
-        estimator is given, the output of this system should represent the
-        full state.
+        The linear I/O system that represents the process dynamics.
     QN, RN : ndarray
-        Process and sensor noise covariance matrices.
+        Disturbance and measurement noise covariance matrices.
     P0 : ndarray, optional
         Initial covariance matrix.  If not specified, defaults to the steady
         state covariance.
@@ -409,13 +406,13 @@ def create_estimator_iosystem(
         Set the name of the measurement and control signal names (estimator
         inputs).  If a single string is specified, it should be a format
         string using the variable ``i`` as an index.  Otherwise, a list of
-        strings matching the size of the system inputs and outputs should
-        be used.  Default is the signal names for the system outputs and
-        control inputs. These settings can also be overriden using the
+        strings matching the size of the system inputs and outputs should be
+        used.  Default is the signal names for the system measurements and
+        known control inputs. These settings can also be overriden using the
         `inputs` keyword.
     inputs, outputs, states : int or list of str, optional
         Set the names of the inputs, outputs, and states, as described in
-        :func:`~control.InputOutputSystem`.
+        :func:`~control.InputOutputSystem`.  Overrides signal labels.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
         name <sys[id]> is generated with a unique integer id.
@@ -434,7 +431,7 @@ def create_estimator_iosystem(
         resp = ct.input_output_response(est, T, [Y, U], [X0, P0])
 
     If desired, the ``correct`` parameter can be set to ``False`` to allow
-    prediction with no additional sensor information::
+    prediction with no additional measurement information::
 
         resp = ct.input_output_response(
            est, T, 0, [X0, P0], param={'correct': False)
@@ -458,7 +455,8 @@ def create_estimator_iosystem(
                 kwargs, 'state_labels', estimate_labels)
         else:
             warnings.warn(
-                "deprecated 'state_labels' ignored; use 'state' instead")
+                "deprecated 'state_labels' ignored; use 'states' instead")
+            kwargs.pop('state_labels')
 
     # Set the state matrix for later use
     A = sys.A
@@ -482,7 +480,7 @@ def create_estimator_iosystem(
         if C.shape[0] != RN.shape[0]:
             raise ValueError("System output is the wrong size for C")
     else:
-        # Use the system outputs as the sensor outputs
+        # Use the system outputs as the measurements
         C = sys.C
 
     # Generate the disturbance matrix (G)
diff --git a/control/tests/optimal_test.py b/control/tests/optimal_test.py
@@ -551,6 +551,7 @@ def test_ocp_argument_errors():
             sys, time, x0, cost, solve_ivp_kwargs={'eps': 0.1})
 
 
+@pytest.mark.slow
 @pytest.mark.parametrize("basis", [
     flat.PolyFamily(4), flat.PolyFamily(6),
     flat.BezierFamily(4), flat.BSplineFamily([0, 4, 8], 6)
diff --git a/control/tests/stochsys_test.py b/control/tests/stochsys_test.py
diff --git a/doc/optimal.rst b/doc/optimal.rst
