Merge branch 'userguide-22Dec2024' into latest

Author: murrayrm

.github/conda-env/doctest-env.yml

@@ -13,3 +13,4 @@ dependencies:
   - nbsphinx
   - docutils
   - numpydoc
+  - sphinx-copybutton

.github/conda-env/test-env.yml

@@ -9,3 +9,4 @@ dependencies:
   - numpy
   - matplotlib
   - scipy
+  - numpydoc

.github/workflows/doctest.yml

@@ -36,6 +36,13 @@ jobs:
         make html
         make doctest
 
+    - name: Run pytest
+      shell: bash -l {0}
+      working-directory: doc
+      run: |
+        make html
+        PYTHONPATH=../ pytest
+
     - name: Archive results
       uses: actions/upload-artifact@v4
       with:

control/__init__.py

@@ -1,50 +1,23 @@
 # __init__.py - initialization for control systems toolbox
 #
 # Author: Richard M. Murray
-# Date: 24 May 09
-#
-# This file contains the initialization information from the control package.
-#
-# Copyright (c) 2009 by California Institute of Technology
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-#
-# 1. Redistributions of source code must retain the above copyright
-#    notice, this list of conditions and the following disclaimer.
-#
-# 2. Redistributions in binary form must reproduce the above copyright
-#    notice, this list of conditions and the following disclaimer in the
-#    documentation and/or other materials provided with the distribution.
-#
-# 3. Neither the name of the California Institute of Technology nor
-#    the names of its contributors may be used to endorse or promote
-#    products derived from this software without specific prior
-#    written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
-# FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CALTECH
-# OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
-# USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
-# OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-# SUCH DAMAGE.
-#
-# $Id$
+# Date: 24 May 2009
 
-"""
-The Python Control Systems Library :mod:`control` provides common functions
+"""The Python Control Systems Library :mod:`control` provides common functions
 for analyzing and designing feedback control systems.
 
+The initial goal for the package is to implement all of the
+functionality required to work through the examples in the textbook
+`Feedback Systems <http://fbsbook.org>`_ by Astrom and Murray.  In
+addition to standard techniques available for linear control systems,
+support for nonlinear systems (including trajectory generation, gain
+scheduling, phase plane diagrams, and describing functions) is also
+included.  A :ref:`matlab-module` is available that provides many of
+the common functions corresponding to commands available in the MATLAB
+Control Systems Toolbox.
+
 Documentation is available in two forms: docstrings provided with the code,
-and the python-control users guide, available from `the python-control
+and the python-control User Guide, available from the `python-control
 homepage <https://www.python-control.org>`_.
 
 The docstring examples assume that the following import commands::

control/bdalg.py

@@ -69,10 +69,10 @@
            'combine_tf', 'split_tf']
 
 
-def series(sys1, *sysn, **kwargs):
-    r"""series(sys1, sys2, [..., sysn])
+def series(*sys, **kwargs):
+    r"""series(sys1, sys2[, ..., sysn])
 
-    Return the series connection (`sysn` \* ...\  \*) `sys2` \* `sys1`.
+    Return series connection (`sysn` \* ...\  \*) `sys2` \* `sys1`.
 
     Parameters
     ----------
@@ -136,15 +136,15 @@ def series(sys1, *sysn, **kwargs):
     (2, 1, 5)
 
     """
-    sys = reduce(lambda x, y: y * x, sysn, sys1)
+    sys = reduce(lambda x, y: y * x, sys[1:], sys[0])
     sys.update_names(**kwargs)
     return sys
 
 
-def parallel(sys1, *sysn, **kwargs):
-    r"""parallel(sys1, sys2, [..., sysn])
+def parallel(*sys, **kwargs):
+    r"""parallel(sys1, sys2[, ..., sysn])
 
-    Return the parallel connection `sys1` + `sys2` (+ ...\  + `sysn`).
+    Return parallel connection `sys1` + `sys2` (+ ...\  + `sysn`).
 
     Parameters
     ----------
@@ -206,7 +206,7 @@ def parallel(sys1, *sysn, **kwargs):
     (3, 4, 7)
 
     """
-    sys = reduce(lambda x, y: x + y, sysn, sys1)
+    sys = reduce(lambda x, y: x + y, sys[1:], sys[0])
     sys.update_names(**kwargs)
     return sys
 
@@ -354,16 +354,16 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
     return sys
 
 def append(*sys, **kwargs):
-    """append(sys1, sys2, [..., sysn])
+    """append(sys1, sys2[, ..., sysn])
 
-    Group LTI state space models by appending their inputs and outputs.
+    Group LTI state space models by appending inputs and outputs.
 
     Forms an augmented system model, and appends the inputs and
     outputs together.
 
     Parameters
     ----------
-    sys1, sys2, ..., sysn: scalar, array, or :class:`StateSpace`
+    sys1, sys2, ..., sysn : scalar, array, or :class:`StateSpace`
         I/O systems to combine.
 
     Other Parameters
@@ -382,7 +382,7 @@ def append(*sys, **kwargs):
 
     Returns
     -------
-    out: :class:`StateSpace`
+    out : :class:`StateSpace`
         Combined system, with input/output vectors consisting of all
         input/output vectors appended.
 
@@ -439,9 +439,9 @@ def connect(sys, Q, inputv, outputv):
         values mean the feedback is negative. A zero value is ignored. Inputs
         and outputs are indexed starting at 1 to communicate sign information.
     inputv : 1D array
-        list of final external inputs, indexed starting at 1
+        List of final external inputs, indexed starting at 1.
     outputv : 1D array
-        list of final external outputs, indexed starting at 1
+        List of final external outputs, indexed starting at 1.
 
     Returns
     -------
@@ -512,7 +512,7 @@ def connect(sys, Q, inputv, outputv):
     return Ytrim * sys * Utrim
 
 def combine_tf(tf_array):
-    """Combine array-like of transfer functions into MIMO transfer function.
+    """Combine array of transfer functions into MIMO transfer function.
 
     Parameters
     ----------
@@ -541,26 +541,20 @@ def combine_tf(tf_array):
     --------
     Combine two transfer functions
 
-    >>> s = control.TransferFunction.s
-    >>> control.combine_tf([
+    >>> s = ct.tf('s')
+    >>> ct.combine_tf([
     ...     [1 / (s + 1)],
     ...     [s / (s + 2)],
     ... ])
-    TransferFunction([[array([1])], [array([1, 0])]],
-                     [[array([1, 1])], [array([1, 2])]])
+    TransferFunction([[array([1])], [array([1, 0])]], [[array([1, 1])], [array([1, 2])]])
 
     Combine NumPy arrays with transfer functions
 
-    >>> control.combine_tf([
+    >>> ct.combine_tf([
     ...     [np.eye(2), np.zeros((2, 1))],
-    ...     [np.zeros((1, 2)), control.TransferFunction([1], [1, 0])],
+    ...     [np.zeros((1, 2)), ct.tf([1], [1, 0])],
     ... ])
-    TransferFunction([[array([1.]), array([0.]), array([0.])],
-                      [array([0.]), array([1.]), array([0.])],
-                      [array([0.]), array([0.]), array([1])]],
-                     [[array([1.]), array([1.]), array([1.])],
-                      [array([1.]), array([1.]), array([1.])],
-                      [array([1.]), array([1.]), array([1, 0])]])
+    TransferFunction([[array([1.]), array([0.]), array([0.])], [array([0.]), array([1.]), array([0.])], [array([0.]), array([0.]), array([1])]], [[array([1.]), array([1.]), array([1.])], [array([1.]), array([1.]), array([1.])], [array([1.]), array([1.]), array([1, 0])]])
     """
     # Find common timebase or raise error
     dt_list = []
@@ -600,8 +594,8 @@ def combine_tf(tf_array):
                         f"row {row_index}."
                     )
                 for j_in in range(col.ninputs):
-                    num_row.append(col.num[j_out][j_in])
-                    den_row.append(col.den[j_out][j_in])
+                    num_row.append(col.num_array[j_out, j_in])
+                    den_row.append(col.den_array[j_out, j_in])
             num.append(num_row)
             den.append(den_row)
     for row_index, row in enumerate(num):
@@ -619,7 +613,7 @@ def combine_tf(tf_array):
     return tf.TransferFunction(num, den, dt=dt)
 
 def split_tf(transfer_function):
-    """Split MIMO transfer function into NumPy array of SISO tranfer functions.
+    """Split MIMO transfer function into SISO transfer functions.
 
     Parameters
     ----------
@@ -635,7 +629,7 @@ def split_tf(transfer_function):
     --------
     Split a MIMO transfer function
 
-    >>> G = control.TransferFunction(
+    >>> G = ct.tf(
     ...     [
     ...         [[87.8], [-86.4]],
     ...         [[108.2], [-109.6]],
@@ -645,7 +639,7 @@ def split_tf(transfer_function):
     ...         [[1, 1], [1, 1]],
     ...     ],
     ... )
-    >>> control.split_tf(G)
+    >>> ct.split_tf(G)
     array([[TransferFunction(array([87.8]), array([1, 1])),
             TransferFunction(array([-86.4]), array([1, 1]))],
            [TransferFunction(array([108.2]), array([1, 1])),
@@ -657,8 +651,8 @@ def split_tf(transfer_function):
         for i_in in range(transfer_function.ninputs):
             row.append(
                 tf.TransferFunction(
-                    transfer_function.num[i_out][i_in],
-                    transfer_function.den[i_out][i_in],
+                    transfer_function.num_array[i_out, i_in],
+                    transfer_function.den_array[i_out, i_in],
                     dt=transfer_function.dt,
                 )
             )