bdalg.connect: added and fixed index checks to fix #421; docstring updated to indicate that Q matrix can be >2 columns

sawyerbfuller · sawyerbfuller · commit 85cc6ca9a7c1 · 2020-12-18T20:24:51.000-08:00
diff --git a/control/bdalg.py b/control/bdalg.py
@@ -302,14 +302,16 @@ def connect(sys, Q, inputv, outputv):
     sys : StateSpace Transferfunction
         System to be connected
     Q : 2D array
-        Interconnection matrix. First column gives the input to be connected
-        second column gives the output to be fed into this input.  Negative
-        values for the second column mean the feedback is negative, 0 means
-        no connection is made.  Inputs and outputs are indexed starting at 1.
+        Interconnection matrix. First column gives the input to be connected.
+        The second column gives the index of an output that is to be fed into 
+        that input. Each additional column gives the index of an additional 
+        input that may be optionally added to that input. Negative
+        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
+        list of final external inputs, indexed starting at 1
     outputv : 1D array
-        list of final external outputs
+        list of final external outputs, indexed starting at 1
 
     Returns
     -------
@@ -325,15 +327,34 @@ def connect(sys, Q, inputv, outputv):
     >>> sysc = connect(sys, Q, [2], [1, 2])
 
     """
+    inputv, outputv, Q = np.asarray(inputv), np.asarray(outputv), np.asarray(Q)
+    # check indices
+    index_errors = (inputv - 1 > sys.inputs) | (inputv < 1)
+    if np.any(index_errors):  
+        raise IndexError( 
+            "inputv index %s out of bounds"%inputv[np.where(index_errors)])
+    index_errors = (outputv - 1 > sys.outputs) | (outputv < 1)
+    if np.any(index_errors):  
+        raise IndexError( 
+            "outputv index %s out of bounds"%outputv[np.where(index_errors)])
+    index_errors = (Q[:,0:1] - 1 > sys.inputs) | (Q[:,0:1] < 1)
+    if np.any(index_errors):  
+        raise IndexError( 
+            "Q input index %s out of bounds"%Q[np.where(index_errors)])
+    index_errors = (np.abs(Q[:,1:]) - 1 > sys.outputs)
+    if np.any(index_errors):  
+        raise IndexError( 
+            "Q output index %s out of bounds"%Q[np.where(index_errors)])
+                
     # first connect
     K = np.zeros((sys.inputs, sys.outputs))
     for r in np.array(Q).astype(int):
         inp = r[0]-1
         for outp in r[1:]:
-            if outp > 0 and outp <= sys.outputs:
-                K[inp,outp-1] = 1.
-            elif outp < 0 and -outp >= -sys.outputs:
+            if outp < 0:
                 K[inp,-outp-1] = -1.
+            elif outp > 0:
+                K[inp,outp-1] = 1.
     sys = sys.feedback(np.array(K), sign=1)
 
     # now trim
diff --git a/control/tests/bdalg_test.py b/control/tests/bdalg_test.py
@@ -275,10 +275,43 @@ def test_feedback_args(self):
     def testConnect(self):
         sys = append(self.sys2, self.sys3) # two siso systems
         
-        # feedback interconnection -3 is out of bounds
-        Q1 = [[1, 2], [2, -3]] 
-        self.assertRaises(IndexError, connect(sys, Q1, [2], [1, 2]))
-
+        # feedback interconnection out of bounds: input too high
+        Q = [[1, 3], [2, -2]] 
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [2], [1, 2])
+        # feedback interconnection out of bounds: input too low
+        Q = [[0, 2], [2, -2]] 
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [2], [1, 2])
+
+        # feedback interconnection out of bounds: output too high
+        Q = [[1, 2], [2, -3]] 
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [2], [1, 2])
+        Q = [[1, 2], [2, 4]] 
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [2], [1, 2])
+        
+        # input/output index testing
+        Q = [[1, 2], [2, -2]] # OK interconnection
+        
+        # input index is out of bounds: too high
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [3], [1, 2])
+        # input index is out of bounds: too low
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [0], [1, 2])
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [-2], [1, 2])
+        # output index is out of bounds: too high
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [2], [1, 3])
+        # output index is out of bounds: too low
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [2], [1, 0])
+        with self.assertRaises(IndexError) as context:
+            connect(sys, Q, [2], [1, -1])
+        
 
 if __name__ == "__main__":
     unittest.main()
