update iosys.rst and associated doc files and docstrings

murrayrm · murrayrm · commit eb70e962eaa3 · 2025-02-02T20:39:22.000-08:00
diff --git a/control/lti.py b/control/lti.py
@@ -61,6 +61,11 @@ def damp(self):
         zeta = -real(splane_poles)/wn
         return wn, zeta, poles
 
+    def feedback(self, other=1, sign=-1):
+        """Feedback interconnection between two LTI objects."""
+        # Implemented in subclasses, but documented here
+        return NotImplemented
+
     def frequency_response(self, omega=None, squeeze=None):
         """Evaluate LTI system response at an array of frequencies.
 
diff --git a/doc/figures/bdalg-feedback.png b/doc/figures/bdalg-feedback.png
diff --git a/doc/functions.rst b/doc/functions.rst
@@ -10,6 +10,7 @@ Function reference
    :no-inherited-members:
    :no-special-members:
 
+
 System creation
 ===============
 
@@ -243,6 +244,7 @@ Utility functions
     db2mag
     isctime
     isdtime
+    iosys_repr
     issiso
     mag2db
     reset_defaults
diff --git a/doc/index.rst b/doc/index.rst
@@ -94,4 +94,3 @@ Your contributions are welcome!  Simply fork the `GitHub repository <https://git
 Please see the `Developer's Wiki`_ for detailed instructions.
 
 .. _Developer's Wiki: https://github.com/python-control/python-control/wiki
-
diff --git a/doc/iosys.rst b/doc/iosys.rst
@@ -1,42 +1,139 @@
 .. _iosys-module:
 
+.. currentmodule:: control
+
 **************************
 Interconnected I/O Systems
 **************************
 
+Input/output systems can be interconnected in a variety of ways,
+including operator overloading, block diagram algebra functions, and
+using the :func:`interconnect` function to build a hiearchical system
+description.  This chapter provides more detailed information on
+operator overloading and block diagram algebra, as well as a
+description of the :class:`InterconnectedSystem` class, which can be
+created using the :func:`interconnect` function.
+
 Operator overloading
 ====================
 
+The following operators are defined to operate between I/O systems:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Operation
+     - Desription
+     - Equivalent command
+   * - `sys1 + sys2`
+     - Add the outputs of two systems receiving the same input
+     - `parallel(sys1, sys2)`
+   * - `sys1 * sys2`
+     - Connect output(s) of sys2 to input(s) of sys1
+     - `series(sys2, sys1)`
+   * - `-sys`
+     - Multiply the output(s) of the system by -1
+     - `negate(sys)`
+   * - `tf1 / tf2`
+     - Divide one SISO transfer function by another
+     - N/A
+   * - `tf**n`
+     - Multiply a transfer function by itself `n` times
+     - N/A
+
+If either of the systems is a number or an array of appropriate
+dimension, then the appropriate scalar or matrix operation is
+performed.
+
+Systems of different types can be combined using these operations,
+with the following rules:
+
+* If the two systems can be converted into the type of the other, the
+  leftmost system determines the type of the output.
+
+* If one system can be converted into the other, then the more general
+  system determines the type of the output.  In particular:
+
+    - State space and transfer function systems can be converted to
+      nonlinear systems.
+
+    - Linear systems can be converted to frequency response data (FRD)
+      systems, using the frequencies of the FRD system.
+
+    - FRD systems can only be combined with FRD systems, constants,
+      and arrays.
+
 
 Block diagram algebra
 =====================
 
+Block diagram algebra is implemented using the following functions:
+
+.. autosummary::
+
+   series
+   parallel
+   feedback
+   negate
+   append
+
+The :func:`feedback` function implements a standard feedback
+interconnection between two systems, as illustrated in the following
+diagram:
+
+.. image:: figures/bdalg-feedback.png
+   :width: 240
+
+By default a gain of -1 is applied at the output of the second system,
+so the dynamics illustrate above can be created using the command
+
+.. code::
+
+   Gyu = ct.feedback(G1, G2)
+
+An optional `gain` parameter can be used to change the sign of the gain.
+
+For LTI systems, the :func:`feedback` operation is also implemented
+via the :func:`LTI.feedback` method, so if `G1` is an LTI system then
+the following command will also work::
+
+  Gyu = G1.feedback(G2)
+
+All block diagram algebra functions allow the names of the system and
+signals to be specified using the usual `name`, `inputs`, and
+`outputs` keywords, as described in the :class:`InputOutputSystem`
+class.  For state space systems, the names of the states can also be
+given, but caution should be used since the order of states in the
+combined system is not gauranteed.
+
 
 Signal-based interconnection
 ============================
 
 More complex input/output systems can be constructed by using the
-:func:`~control.interconnect` function, which allows a collection of
+:func:`interconnect` function, which allows a collection of
 input/output subsystems to be combined with internal connections
 between the subsystems and a set of overall system inputs and outputs
-that link to the subsystems::
+that link to the subsystems.  For example, the closed loop dynamics of
+a feedback control system using the standard names and labels for
+inputs and outputs could be constructed using the command
+
+.. code::
 
-    steering = ct.interconnect(
+    clsys = ct.interconnect(
         [plant, controller], name='system',
         connections=[['controller.e', '-plant.y']],
         inplist=['controller.e'], inputs='r',
         outlist=['plant.y'], outputs='y')
 
-Interconnected systems can also be created using block diagram manipulations
-such as the :func:`~control.series`, :func:`~control.parallel`, and
-:func:`~control.feedback` functions.  The :class:`~control.InputOutputSystem`
-class also supports various algebraic operations such as `*` (series
-interconnection) and `+` (parallel interconnection).
+The remainder of this section provides a detailed description of the
+operation of the :func:`interconnect` function.
 
-Example
-=======
 
-To illustrate the use of the input/output systems module, we create a
+Illustrative example
+--------------------
+
+To illustrate the use of the :func:`interconnect` function, we create a
 model for a predator/prey system, following the notation and parameter
 values in `Feedback Systems <http://fbsbook.org>`_.
 
@@ -123,7 +220,7 @@ lynxes as the desired output (following `Feedback Systems
 To construct the control law, we build a simple input/output system that
 applies a corrective input based on deviations from the equilibrium point.
 This system has no dynamics, since it is a static (affine) map, and can
-constructed using :func:`~control.nlsys` with no update function:
+constructed using :func:`nlsys` with no update function:
 
 .. code-block:: python
 
@@ -169,21 +266,21 @@ Finally, we simulate the closed loop system:
   plt.legend(['input'])
   plt.show(block=False)
 
-Additional features
-===================
+This example shows the standard operations that would be used to build
+up an interconnected nonlinear system.  The I/O systems module has a
+number of other features that can be used to simplify the creation and
+use of interconnected input/output systems.
 
-The I/O systems module has a number of other features that can be used to
-simplify the creation and use of interconnected input/output systems.
 
-Vector elements processing
+Vector element processing
 --------------------------
 
 Several I/O system commands perform processing of vector elements
 (such as initial states or input vectors) and broadcast these to the
 proper shape.
 
 For static elements, such as the initial state in a simulation or the
-nominal state and input for a linearization), the following processing
+nominal state and input for a linearization, the following processing
 is done:
 
 * Scalars are automatically converted to a vector of the appropriate
@@ -254,6 +351,7 @@ use the list processing feature combined with time series broadcasting::
 In this command, the second and third arguments will be broadcast to match
 the number of time points.
 
+
 Summing junction
 ----------------
 
@@ -290,6 +388,7 @@ the command
 will produce an input/output block that implements `e[0] = r[0] - y[0]` and
 `e[1] = r[1] - y[1]`.
 
+
 Automatic connections using signal names
 ----------------------------------------
 
@@ -317,6 +416,7 @@ of the interconnected system) is not found, but inputs and outputs of
 individual systems that are not connected to other systems are left
 unconnected (so be careful!).
 
+
 Advanced specification of signal names
 --------------------------------------
 
@@ -430,6 +530,7 @@ complicated to debug error message when things go wrong.  Setting
 information about how the arguments are processed that may be helpful
 in understanding what is going wrong.
 
+
 Automated creation of state feedback systems
 --------------------------------------------
 

Original file line number	Diff line number	Diff line change
@@ -94,4 +94,3 @@ Your contributions are welcome! Simply fork the `GitHub repository <https://git
`94`	`94`	Please see the `Developer's Wiki`_ for detailed instructions.
`95`	`95`
`96`	`96`	`.. _Developer's Wiki: https://github.com/python-control/python-control/wiki`
`97`		`-`