documentation updates

Author: murrayrm

control/statefbk.py

@@ -610,7 +610,7 @@ def create_statefbk_iosystem(
 
     where :math:`\mu` represents the scheduling variable.
 
-    Alternatively, a control of the form
+    Alternatively, a controller of the form
 
     .. math:: u = k_f r - K_p x - K_i \int(C x - r)
 
@@ -652,7 +652,8 @@ def create_statefbk_iosystem(
 
     feedfwd_pattern : str, optional
         If set to 'refgain', the reference gain design pattern is used to
-        create the controller instead of the trajectory generation pattern.
+        create the controller instead of the trajectory generation
+        ('trajgen') pattern.
 
     integral_action : ndarray, optional
         If this keyword is specified, the controller can include integral

control/tests/statesp_test.py

@@ -127,7 +127,7 @@ def test_constructor(self, sys322ABCD, dt, argfun):
          ((1, 2), TypeError, "1, 4, or 5 arguments"),
          ((np.ones((3, 2)), np.ones((3, 2)),
            np.ones((2, 2)), np.ones((2, 2))), ValueError,
-          "A is the wrong shape; expected \(3, 3\)"), 
+          "A is the wrong shape; expected \(3, 3\)"),
          ((np.ones((3, 3)), np.ones((2, 2)),
            np.ones((2, 3)), np.ones((2, 2))), ValueError,
           "B is the wrong shape; expected \(3, 2\)"),

doc/iosys.rst

@@ -470,6 +470,30 @@ closed loop systems `clsys`, both as I/O systems.  The input to the
 controller is the vector of desired states :math:`x_\text{d}`, desired
 inputs :math:`u_\text{d}`, and system states :math:`x`.
 
+The above design pattern is referred to as the "trajectory generation"
+('trajgen') pattern, since it assumes that the input to the controller is a
+feasible trajectory :math:`(x_\text{d}, u_\text{d})`.  Alternatively, a
+controller using the "reference gain" pattern can be created, which
+implements a state feedback controller of the form
+
+.. math::
+
+  u = k_\text{f}\, r - K x,
+
+where :math:`r` is the reference input and :math:`k_\text{f}` is the
+feedforward gain (normally chosen so that the steady state output
+:math:`y_\text{ss}` will be equal to :math:`r`.
+
+A reference gain controller can be created with the command::
+
+  ctrl, clsys = ct.create_statefbk_iosystem(
+      sys, K, feedfwd_gain=kf, feedfwd_pattern='refgain')
+
+This reference gain design pattern is described in more detail in Section
+7.2 of FBS2e (Stabilization by State Feedback) and the trajectory
+generation design pattern is described in Section 8.5 (State Space
+Controller Design).
+
 If the full system state is not available, the output of a state
 estimator can be used to construct the controller using the command::
 
@@ -507,10 +531,11 @@ must match the number of additional columns in the `K` matrix.  If an
 estimator is specified, :math:`\hat x` will be used in place of
 :math:`x`.
 
-Finally, gain scheduling on the desired state, desired input, or
-system state can be implemented by setting the gain to a 2-tuple
-consisting of a list of gains and a list of points at which the gains
-were computed, as well as a description of the scheduling variables::
+Finally, for the trajectory generation design pattern, gain scheduling on
+the desired state, desired input, or system state can be implemented by
+setting the gain to a 2-tuple consisting of a list of gains and a list of
+points at which the gains were computed, as well as a description of the
+scheduling variables::
 
   ctrl, clsys = ct.create_statefbk_iosystem(
       sys, ([g1, ..., gN], [p1, ..., pN]), gainsched_indices=[s1, ..., sq])