address first round of TODO items + add stochastic system examples

Author: murrayrm

control/lti.py

@@ -558,19 +558,12 @@ def frequency_response(
     >>> G = ct.ss([[-1, -2], [3, -4]], [[5], [7]], [[6, 8]], [[9]])
     >>> mag, phase, omega = ct.frequency_response(G, [0.1, 1., 10.])
 
-    .. todo::
-        Add example with MIMO system
-
-        #>>> sys = rss(3, 2, 2)
-        #>>> mag, phase, omega = freqresp(sys, [0.1, 1., 10.])
-        #>>> mag[0, 1, :]
-        #array([ 55.43747231,  42.47766549,   1.97225895])
-        #>>> phase[1, 0, :]
-        #array([-0.12611087, -1.14294316,  2.5764547 ])
-        #>>> # This is the magnitude of the frequency response from the 2nd
-        #>>> # input to the 1st output, and the phase (in radians) of the
-        #>>> # frequency response from the 1st input to the 2nd output, for
-        #>>> # s = 0.1i, i, 10i.
+    >>> sys = ct.rss(3, 2, 2)
+    >>> mag, phase, omega = ct.frequency_response(sys, [0.1, 1., 10.])
+    >>> mag[0, 1, :]    # Magnitude of second input to first output
+    array([..., ..., ...])
+    >>> phase[1, 0, :]  # Phase of first input to second output
+    array([..., ..., ...])
 
     """
     from .frdata import FrequencyResponseData

control/matlab/wrappers.py

@@ -54,16 +54,6 @@ def bode(*args, **kwargs):
 
     >>> sys = ss([[1, -2], [3, -4]], [[5], [7]], [[6, 8]], 9)
     >>> mag, phase, omega = bode(sys)
-
-    .. todo::
-
-        Document these use cases
-
-        * >>> bode(sys, w)                                      # doctest: +SKIP
-        * >>> bode(sys1, sys2, ..., sysN)                       # doctest: +SKIP
-        * >>> bode(sys1, sys2, ..., sysN, w)                    # doctest: +SKIP
-        * >>> bode(sys1, 'plotstyle1', ..., sysN, 'plotstyleN') # doctest: +SKIP
-
     >>> bode(sys, w)                  # one system, freq vector # doctest: +SKIP
     >>> bode(sys1, sys2, ..., sysN)   # several systems         # doctest: +SKIP
     >>> bode(sys1, sys2, ..., sysN, w)                          # doctest: +SKIP

doc/examples.rst

@@ -56,8 +56,6 @@ online sources.
    examples/cruise
    examples/describing_functions
    examples/interconnect_tutorial
-   examples/kincar-fusion
-   examples/mhe-pvtol
    examples/mpc_aircraft
    examples/pvtol-lqr-nested
    examples/pvtol-outputfbk

doc/examples/kalman-pvtol.ipynb

@@ -0,0 +1 @@
+../../examples/cds112-L7_kalman-pvtol.ipynb

doc/stochastic.rst

@@ -187,33 +187,49 @@ time optimal controller.  For the second two forms, the :func:`dlqr`
 function can be used.  Additional arguments and details are given on
 the :func:`lqr` and :func:`dlqr` documentation pages.
 
-.. todo::
-   Convert the following code to testcode
+.. testsetup:: kalman
+
+   sys = ct.rss(2, 2, 2)
+   Qu = np.eye(2)
+   Qv = np.eye(2)
+   Qw = np.eye(2)
+   Qx = np.eye(2)
+
+   timepts = np.linspace(0, 10)
+   U = ct.white_noise(timepts, Qv)
+   Y = ct.white_noise(timepts, Qw)
+
+   X0 = np.zeros(2)
+   P0 = np.eye(2)
 
 The :func:`create_estimator_iosystem` function can be used to create
 an I/O system implementing a Kalman filter, including integration of
 the Riccati ODE.  The command has the form
 
-.. code::
+.. testcode:: kalman
 
   estim = ct.create_estimator_iosystem(sys, Qv, Qw)
 
 The input to the estimator is the measured outputs `Y` and the system
 input `U`.  To run the estimator on a noisy signal, use the command
 
-.. code::
+.. testcode:: kalman
 
-  resp = ct.input_output_response(est, timepts, [Y, U], [X0, P0])
+  resp = ct.input_output_response(estim, timepts, [Y, U], [X0, P0])
 
 If desired, the :func:`correct` parameter can be set to False
-to allow prediction with no additional sensor information::
+to allow prediction with no additional sensor information:
+
+.. testcode:: kalman
 
   resp = ct.input_output_response(
-      estim, timepts, 0, [X0, P0], param={'correct': False})
+      estim, timepts, 0, [X0, P0], params={'correct': False})
 
 The :func:`create_estimator_iosystem` and
 :func:`create_statefbk_iosystem` functions can be used to combine an
-estimator with a state feedback controller::
+estimator with a state feedback controller:
+
+.. testcode:: kalman
 
   K, _, _ = ct.lqr(sys, Qx, Qu)
   estim = ct.create_estimator_iosystem(sys, Qv, Qw, P0)
@@ -229,13 +245,19 @@ estimated state :math:`\hat x` (output of `estim`):
 
 The closed loop controller `clsys` includes both the state
 feedback and the estimator dynamics and takes as its input the desired
-state :math:`x_\text{d}` and input :math:`u_\text{d}`::
+state :math:`x_\text{d}` and input :math:`u_\text{d}`:
+
+.. testcode:: kalman
+   :hide:
+
+   Xd = np.zeros((2, timepts.size))
+   Ud = np.zeros((2, timepts.size))
+
+.. testcode:: kalman
 
   resp = ct.input_output_response(
       clsys, timepts, [Xd, Ud], [X0, np.zeros_like(X0), P0])
 
-.. todo::
-   Add example (with plots?)
 
 
 Maximum Likelihood Estimation
@@ -374,5 +396,17 @@ problems:
    optimal.gaussian_likelihood_cost
    optimal.disturbance_range_constraint
 
-.. todo::
-   Add example: LQE vs MHE (from CDS 112)
+Examples
+========
+
+The following examples illustrate the use of tools from the stochastic
+systems module.  Background information for these examples can be
+found in the FBS2e supplement on `Optimization-Based Control
+<https://fbswiki.org/wiki/index.php/OBC>`_).
+
+.. toctree::
+   :maxdepth: 1
+
+   Kalman filter (kinematic car) <examples/kincar-fusion>
+   (Extended) Kalman filtering (PVTOL) <examples/kalman-pvtol>
+   Moving horizon estimation (PVTOL) <examples/mhe-pvtol>

examples/cds110-L4b_lqr-tracking.ipynb

@@ -907,8 +907,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.1"
   }
  },
  "nbformat": 4,

examples/cds112-L7_kalman-pvtol.ipynb

@@ -416,8 +416,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.1"
   }
  },
  "nbformat": 4,

examples/cds112-L9_mhe-pvtol.ipynb

@@ -28,17 +28,6 @@
     "import control.flatsys as fs"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "1a4e4084",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Import the new MHE routines (to be moved to python-control)\n",
-    "# import ctrlutil as opt_"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "d72a155b",
@@ -749,8 +738,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.1"
   }
  },
  "nbformat": 4,

examples/stochresp.ipynb

@@ -284,7 +284,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.1"
+   "version": "3.13.1"
   }
  },
  "nbformat": 4,