diff --git a/control/statefbk.py b/control/statefbk.py index 758f093f9..43cdbdf23 100644 --- 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 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 index 50dacf70c..b1bb6ef46 100644 --- a/control/stochsys.py +++ b/control/stochsys.py @@ -36,24 +36,24 @@ # contributed by Sawyer B. Fuller 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