Merge pull request #923 from KybernetikJo/doc-fix-create_statefbk_iosystem

murrayrm · web-flow · commit 0a6146bb1e71 · 2023-09-16T09:48:01.000-07:00
diff --git a/control/statefbk.py b/control/statefbk.py
@@ -296,14 +296,14 @@ def acker(A, B, poles):
 
 
 def lqr(*args, **kwargs):
-    """lqr(A, B, Q, R[, N])
+    r"""lqr(A, B, Q, R[, N])
 
     Linear quadratic regulator design.
 
     The lqr() function computes the optimal state feedback controller
     u = -K x that minimizes the quadratic cost
 
-    .. math:: J = \\int_0^\\infty (x' Q x + u' R u + 2 x' N u) dt
+    .. math:: J = \int_0^\infty (x' Q x + u' R u + 2 x' N u) dt
 
     The function can be called with either 3, 4, or 5 arguments:
 
@@ -442,14 +442,14 @@ def lqr(*args, **kwargs):
 
 
 def dlqr(*args, **kwargs):
-    """dlqr(A, B, Q, R[, N])
+    r"""dlqr(A, B, Q, R[, N])
 
     Discrete-time linear quadratic regulator design.
 
     The dlqr() function computes the optimal state feedback controller
     u[n] = - K x[n] that minimizes the quadratic cost
 
-    .. math:: J = \\sum_0^\\infty (x[n]' Q x[n] + u[n]' R u[n] + 2 x[n]' N u[n])
+    .. math:: J = \sum_0^\infty (x[n]' Q x[n] + u[n]' R u[n] + 2 x[n]' N u[n])
 
     The function can be called with either 3, 4, or 5 arguments:
 
@@ -584,14 +584,14 @@ def create_statefbk_iosystem(
         xd_labels=None, ud_labels=None, gainsched_indices=None,
         gainsched_method='linear', control_indices=None, state_indices=None,
         name=None, inputs=None, outputs=None, states=None, **kwargs):
-    """Create an I/O system using a (full) state feedback controller.
+    r"""Create an I/O system using a (full) state feedback controller.
 
     This function creates an input/output system that implements a
     state feedback controller of the form
 
-        u = ud - K_p (x - xd) - K_i integral(C x - C x_d)
+    .. math:: u = u_d - K_p (x - x_d) - K_i \int(C x - C x_d)
 
-    It can be called in the form
+    It can be called in the form::
 
         ctrl, clsys = ct.create_statefbk_iosystem(sys, K)
 
@@ -603,9 +603,9 @@ def create_statefbk_iosystem(
     gains and a corresponding list of values of a set of scheduling
     variables.  In this case, the controller has the form
 
-        u = ud - K_p(mu) (x - xd) - K_i(mu) integral(C x - C x_d)
+    .. math:: u = u_d - K_p(\mu) (x - x_d) - K_i(\mu) \int(C x - C x_d)
 
-    where mu represents the scheduling variable.
+    where :math:`\mu` represents the scheduling variable.
 
     Parameters
     ----------
@@ -614,7 +614,7 @@ def create_statefbk_iosystem(
         is given, the output of this system should represent the full state.
 
     gain : ndarray or tuple
-        If an array is given, 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
         should be (sys.ninputs, sys.nstates).  If `integral action` is
@@ -623,18 +623,18 @@ def create_statefbk_iosystem(
 
         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
-        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.
+        gains `K_j` and points is a list of values `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.
+        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 `x_d` and `u_d`, respectively, should
+        be used.  Default is "xd[{i}]" for xd_labels and "ud[{i}]" for
+        ud_labels.  These settings can also be overridden using the
+        `inputs` keyword.
 
     integral_action : ndarray, optional
         If this keyword is specified, the controller can include integral
@@ -650,13 +650,13 @@ def create_statefbk_iosystem(
     gainsched_indices : int, slice, or list of int or str, optional
         If a gain scheduled controller is specified, specify the indices of
         the controller input to use for scheduling the gain. The input to
-        the controller is the desired state xd, the desired input ud, and
-        the system state x (or state estimate xhat, if an estimator is
-        given). If value is an integer `q`, the first `q` values of the
-        [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 desired state xd.
+        the controller is the desired state `x_d`, the desired input `u_d`,
+        and the system state `x` (or state estimate `xhat`, if an
+        estimator is given). If value is an integer `q`, the first `q`
+        values of the `[x_d, u_d, 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 desired state `x_d`.
 
     gainsched_method : str, optional
         The method to use for gain scheduling.  Possible values are 'linear'
@@ -677,10 +677,10 @@ def create_statefbk_iosystem(
     -------
     ctrl : NonlinearIOSystem
         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
+        takes as inputs the desired state `x_d`, the desired input
+        `u_d`, 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
+        formula `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
@@ -690,7 +690,7 @@ def create_statefbk_iosystem(
 
     clsys : NonlinearIOSystem
         Input/output system representing the closed loop system.  This
-        systems takes as inputs the desired trajectory `(xd, ud)` and
+        system takes as inputs the desired trajectory `(x_d, u_d)` and
         outputs the system state `x` and the applied input `u`
         (vertically stacked).
 
@@ -721,6 +721,23 @@ def create_statefbk_iosystem(
         System name. If unspecified, a generic name <sys[id]> is generated
         with a unique integer id.
 
+    Examples
+    --------
+    >>> import control as ct
+    >>> import numpy as np
+    >>>
+    >>> A = [[0, 1], [-0.5, -0.1]]
+    >>> B = [[0], [1]]
+    >>> C = np.eye(2)
+    >>> D = np.zeros((2, 1))
+    >>> sys = ct.ss(A, B, C, D)
+    >>>
+    >>> Q = np.eye(2)
+    >>> R = np.eye(1)
+    >>>
+    >>> K, _, _ = ct.lqr(sys,Q,R)
+    >>> ctrl, clsys = ct.create_statefbk_iosystem(sys, K)
+
     """
     # Make sure that we were passed an I/O system as an input
     if not isinstance(sys, NonlinearIOSystem):
diff --git a/control/stochsys.py b/control/stochsys.py
@@ -36,24 +36,24 @@
 
 # contributed by Sawyer B. Fuller <minster@uw.edu>
 def lqe(*args, **kwargs):
-    """lqe(A, G, C, QN, RN, [, NN])
+    r"""lqe(A, G, C, QN, RN, [, NN])
 
     Linear quadratic estimator design (Kalman filter) for continuous-time
     systems. Given the system
 
     .. math::
 
-        x &= Ax + Bu + Gw \\\\
+        dx/dt &= Ax + Bu + Gw \\
         y &= Cx + Du + v
 
     with unbiased process noise w and measurement noise v with covariances
 
-    .. math::       E{ww'} = QN,    E{vv'} = RN,    E{wv'} = NN
+    .. math::  E\{w w^T\} = QN,  E\{v v^T\} = RN,  E\{w v^T\} = NN
 
     The lqe() function computes the observer gain matrix L such that the
     stationary (non-time-varying) Kalman filter
 
-    .. math:: x_e = A x_e + B u + L(y - C x_e - D u)
+    .. math:: dx_e/dt = A x_e + B u + L(y - C x_e - D u)
 
     produces a state estimate x_e that minimizes the expected squared error
     using the sensor measurements y. The noise cross-correlation `NN` is
@@ -195,7 +195,7 @@ def dlqe(*args, **kwargs):
 
     with unbiased process noise w and measurement noise v with covariances
 
-    .. math::       E{ww'} = QN,    E{vv'} = RN,    E{wv'} = NN
+    .. math::  E\{w w^T\} = QN,  E\{v v^T\} = RN,  E\{w v^T\} = NN
 
     The dlqe() function computes the observer gain matrix L such that the
     stationary (non-time-varying) Kalman filter
