fix up examples and document list vs tuple more carefully

murrayrm · murrayrm · commit ff965643e5d2 · 2023-06-06T21:00:01.000-07:00
diff --git a/control/iosys.py b/control/iosys.py
@@ -2724,12 +2724,13 @@ def interconnect(
       'sysname.signal[i:j]'             range of signal names, i through j-1
       'sysname.signal[:]'               all signals with given prefix
 
-    It is possible to replace lists in most of arguments with tuples
-    instead, but strictly speaking the only use of tuples should be in the
+    While in many Python functions tuples can be used in place of lists,
+    for the interconnect() function the only use of tuples should be in the
     specification of an input- or output-signal via the tuple notation
     `(subsys_i, signal_j, gain)` (where `gain` is optional).  If you get an
-    unexpected error message about a specification being of the wrong type,
-    check your use of tuples.
+    unexpected error message about a specification being of the wrong type
+    or not being found, check to make sure you are not using a tuple where
+    you should be using a list.
 
     In addition to its use for general nonlinear I/O systems, the
     :func:`~control.interconnect` function allows linear systems to be
diff --git a/examples/cruise-control.py b/examples/cruise-control.py
@@ -140,13 +140,13 @@ def motor_torque(omega, params={}):
 # Outputs: v (vehicle velocity)
 cruise_tf = ct.InterconnectedSystem(
     (control_tf, vehicle), name='cruise',
-    connections=(
+    connections=[
         ['control.u', '-vehicle.v'],
-        ['vehicle.u', 'control.y']),
-    inplist=('control.u', 'vehicle.gear', 'vehicle.theta'),
-    inputs=('vref', 'gear', 'theta'),
-    outlist=('vehicle.v', 'vehicle.u'),
-    outputs=('v', 'u'))
+        ['vehicle.u', 'control.y']],
+    inplist=['control.u', 'vehicle.gear', 'vehicle.theta'],
+    inputs=['vref', 'gear', 'theta'],
+    outlist=['vehicle.v', 'vehicle.u'],
+    outputs=['v', 'u'])
 
 # Define the time and input vectors
 T = np.linspace(0, 25, 101)
@@ -280,11 +280,11 @@ def pi_output(t, x, u, params={}):
 # Create the closed loop system
 cruise_pi = ct.InterconnectedSystem(
     (vehicle, control_pi), name='cruise',
-    connections=(
+    connections=[
         ['vehicle.u', 'control.u'],
-        ['control.v', 'vehicle.v']),
-    inplist=('control.vref', 'vehicle.gear', 'vehicle.theta'),
-    outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])
+        ['control.v', 'vehicle.v']],
+    inplist=['control.vref', 'vehicle.gear', 'vehicle.theta'],
+    outlist=['control.u', 'vehicle.v'], outputs=['u', 'v'])
 
 # Figure 4.3b shows the response of the closed loop system.  The figure shows
 # that even if the hill is so steep that the throttle changes from 0.17 to
@@ -409,12 +409,12 @@ def sf_output(t, z, u, params={}):
 # Create the closed loop system for the state space controller
 cruise_sf = ct.InterconnectedSystem(
     (vehicle, control_sf), name='cruise',
-    connections=(
+    connections=[
         ['vehicle.u', 'control.u'],
         ['control.x', 'vehicle.v'],
-        ['control.y', 'vehicle.v']),
-    inplist=('control.r', 'vehicle.gear', 'vehicle.theta'),
-    outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])
+        ['control.y', 'vehicle.v']],
+    inplist=['control.r', 'vehicle.gear', 'vehicle.theta'],
+    outlist=['control.u', 'vehicle.v'], outputs=['u', 'v'])
 
 # Compute the linearization of the dynamics around the equilibrium point
 
diff --git a/examples/cruise.ipynb b/examples/cruise.ipynb
@@ -328,13 +328,13 @@
     "\n",
     "# Create the closed loop system for the state space controller\n",
     "cruise_sf = ct.InterconnectedSystem(\n",
-    "    (vehicle, control_sf), name='cruise',\n",
-    "    connections=(\n",
-    "        ('vehicle.u', 'control.u'),\n",
-    "        ('control.x', 'vehicle.v'),\n",
-    "        ('control.y', 'vehicle.v')),\n",
-    "    inplist=('control.r', 'vehicle.gear', 'vehicle.theta'),\n",
-    "    outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])\n",
+    "    [vehicle, control_sf], name='cruise',\n",
+    "    connections=[\n",
+    "        ['vehicle.u', 'control.u'],\n",
+    "        ['control.x', 'vehicle.v'],\n",
+    "        ['control.y', 'vehicle.v']],\n",
+    "    inplist=['control.r', 'vehicle.gear', 'vehicle.theta'],\n",
+    "    outlist=['control.u', 'vehicle.v'], outputs=['u', 'v'])\n",
     "\n",
     "# Define the time and input vectors\n",
     "T = np.linspace(0, 25, 501)\n",
@@ -460,14 +460,14 @@
     "# Construct the closed loop system and plot the response\n",
     "# Create the closed loop system for the state space controller\n",
     "cruise_pz = ct.InterconnectedSystem(\n",
-    "    (vehicle, control_pz), name='cruise_pz',\n",
-    "    connections = (\n",
-    "        ('control.u', '-vehicle.v'),\n",
-    "        ('vehicle.u', 'control.y')),\n",
-    "    inplist = ('control.u', 'vehicle.gear', 'vehicle.theta'),\n",
-    "    inputs = ('vref', 'gear', 'theta'),\n",
-    "    outlist = ('vehicle.v', 'vehicle.u'),\n",
-    "    outputs = ('v', 'u'))\n",
+    "    [vehicle, control_pz], name='cruise_pz',\n",
+    "    connections = [\n",
+    "        ['control.u', '-vehicle.v'],\n",
+    "        ['vehicle.u', 'control.y']],\n",
+    "    inplist = ['control.u', 'vehicle.gear', 'vehicle.theta'],\n",
+    "    inputs = ['vref', 'gear', 'theta'],\n",
+    "    outlist = ['vehicle.v', 'vehicle.u'],\n",
+    "    outputs = ['v', 'u'])\n",
     "\n",
     "# Find the equilibrium point\n",
     "X0, U0 = ct.find_eqpt(\n",
@@ -546,11 +546,11 @@
     "    \n",
     "    # Construct the closed loop system by interconnecting process and controller\n",
     "    cruise_tf = ct.InterconnectedSystem(\n",
-    "    (vehicle, control_tf), name='cruise',\n",
-    "    connections = [('control.u', '-vehicle.v'), ('vehicle.u', 'control.y')],\n",
-    "    inplist = ('control.u', 'vehicle.gear', 'vehicle.theta'), \n",
-    "        inputs = ('vref', 'gear', 'theta'),\n",
-    "    outlist = ('vehicle.v', 'vehicle.u'), outputs = ('v', 'u'))\n",
+    "    [vehicle, control_tf], name='cruise',\n",
+    "    connections = [['control.u', '-vehicle.v'], ['vehicle.u', 'control.y']],\n",
+    "    inplist = ['control.u', 'vehicle.gear', 'vehicle.theta'], \n",
+    "        inputs = ['vref', 'gear', 'theta'],\n",
+    "    outlist = ['vehicle.v', 'vehicle.u'], outputs = ['v', 'u'])\n",
     "\n",
     "    # Plot the velocity response\n",
     "    X0, U0 = ct.find_eqpt(\n",
@@ -593,11 +593,11 @@
     "    \n",
     "    # Construct the closed loop system by interconnecting process and controller\n",
     "    cruise_tf = ct.InterconnectedSystem(\n",
-    "    (vehicle, control_tf), name='cruise',\n",
-    "    connections = [('control.u', '-vehicle.v'), ('vehicle.u', 'control.y')],\n",
-    "    inplist = ('control.u', 'vehicle.gear', 'vehicle.theta'), \n",
-    "        inputs = ('vref', 'gear', 'theta'),\n",
-    "    outlist = ('vehicle.v', 'vehicle.u'), outputs = ('v', 'u'))\n",
+    "    [vehicle, control_tf], name='cruise',\n",
+    "    connections = [['control.u', '-vehicle.v'], ['vehicle.u', 'control.y']],\n",
+    "    inplist = ['control.u', 'vehicle.gear', 'vehicle.theta'], \n",
+    "        inputs = ['vref', 'gear', 'theta'],\n",
+    "    outlist = ['vehicle.v', 'vehicle.u'], outputs = ['v', 'u'])\n",
     "\n",
     "    # Plot the velocity response\n",
     "    X0, U0 = ct.find_eqpt(\n",
@@ -630,10 +630,10 @@
     "    name='control', inputs='u', outputs='y')\n",
     "\n",
     "cruise_tf = ct.InterconnectedSystem(\n",
-    "    (vehicle, control_tf), name='cruise',\n",
-    "    connections = [('control.u', '-vehicle.v'), ('vehicle.u', 'control.y')],\n",
-    "    inplist = ('control.u', 'vehicle.gear', 'vehicle.theta'), inputs = ('vref', 'gear', 'theta'),\n",
-    "    outlist = ('vehicle.v', 'vehicle.u'), outputs = ('v', 'u'))"
+    "    [vehicle, control_tf], name='cruise',\n",
+    "    connections = [['control.u', '-vehicle.v'], ['vehicle.u', 'control.y']],\n",
+    "    inplist = ['control.u', 'vehicle.gear', 'vehicle.theta'], inputs = ['vref', 'gear', 'theta'],\n",
+    "    outlist = ['vehicle.v', 'vehicle.u'], outputs = ['v', 'u'])"
    ]
   },
   {
@@ -750,12 +750,12 @@
     "\n",
     "# Create the closed loop system\n",
     "cruise_pi = ct.InterconnectedSystem(\n",
-    "    (vehicle, control_pi), name='cruise',\n",
-    "    connections=(\n",
-    "        ('vehicle.u', 'control.u'),\n",
-    "        ('control.v', 'vehicle.v')),\n",
-    "    inplist=('control.vref', 'vehicle.gear', 'vehicle.theta'),\n",
-    "    outlist=('control.u', 'vehicle.v'), outputs=['u', 'v'])"
+    "    [vehicle, control_pi], name='cruise',\n",
+    "    connections=[\n",
+    "        ['vehicle.u', 'control.u'],\n",
+    "        ['control.v', 'vehicle.v']],\n",
+    "    inplist=['control.vref', 'vehicle.gear', 'vehicle.theta'],\n",
+    "    outlist=['control.u', 'vehicle.v'], outputs=['u', 'v'])"
    ]
   },
   {
