Merge pull request #371 from pllab/matrix_helper

Move and improve list_to_int helper from test_matrix.py to matrix.py file

Author: mdko

pyrtl/rtllib/matrix.py

@@ -6,6 +6,7 @@
 from ..wire import Const, WireVector
 from ..corecircuits import as_wires, concat, select
 from ..pyrtlexceptions import PyrtlError
+from ..helperfuncs import formatted_str_to_val
 
 
 class Matrix(object):
@@ -1342,3 +1343,58 @@ def matrix_wv_to_list(matrix_wv, rows, columns, bits):
             result[i][j] = int_value
             bit_pointer += bits
     return result
+
+
+def list_to_int(matrix, n_bits):
+    ''' Convert a Python matrix (a list of lists) into an integer.
+
+    :param list[list[int]] matrix: a pure Python list of lists representing a matrix
+    :param int n_bits: number of bits to be used to represent each element; if an
+        element doesn't fit in n_bits, it truncates the most significant bits.
+    :return int: a N*n_bits wide wirevector containing the elements of `matrix`,
+        where N is the number of elements in `matrix`
+
+    Integers that are signed will automatically be converted to their two's complement form.
+
+    This function is helpful for turning a pure Python list of lists
+    into a integer suitable for creating a Constant wirevector that can
+    be passed in to as a Matrix intializer's `value` argument, or for
+    passing into a Simulation's step function for a particular input wire.
+
+    For example, calling Matrix.list_to_int([3, 5], [7, 9], 4) produces 13,689,
+    which in binary looks like this::
+
+        0011 0101 0111 1001
+
+    Note how the elements of the list of lists were added, 4 bits at a time,
+    in row order, such that the element at row 0, column 0 is in the most significant
+    4 bits, and the element at row 1, column 1 is in the least significant 4 bits.
+
+    Here's an example of using it in simulation::
+
+        a_vals = [[0, 1], [2, 3]]
+        b_vals = [[2, 4, 6], [8, 10, 12]]
+
+        a_in = pyrtl.Input(4 * 4, 'a_in')
+        b_in = pyrtl.Input(6 * 4, 'b_in')
+        a = Matrix.Matrix(2, 2, 4, value=a_in)
+        b = Matrix.Matrix(2, 3, 4, value=b_in)
+        ...
+
+        sim = pyrtl.Simulation()
+        sim.step({
+            'a_in': Matrix.list_to_int(a_vals)
+            'b_in': Matrix.list_to_int(b_vals)
+        })
+    '''
+    if n_bits <= 0:
+        raise PyrtlError("Number of bits per element must be positive, instead got %d" % n_bits)
+
+    result = 0
+
+    for i in range(len(matrix)):
+        for j in range(len(matrix[0])):
+            val = formatted_str_to_val(str(matrix[i][j]), 's' + str(n_bits))
+            result = (result << n_bits) | val
+
+    return result

tests/rtllib/test_matrix.py

@@ -159,7 +159,7 @@ def test_init_random_wirevector(self):
         self.init_wirevector(matrix, rows, columns, bits)
 
     def init_wirevector(self, matrix_value, rows, columns, bits):
-        matrix_input = pyrtl.Const(matrix_to_int(matrix_value, bits), rows * columns * bits)
+        matrix_input = pyrtl.Const(Matrix.list_to_int(matrix_value, bits), rows * columns * bits)
         matrix = Matrix.Matrix(rows, columns, bits, value=matrix_input)
 
         self.assertEqual(rows, matrix.rows)
@@ -2445,19 +2445,29 @@ def test_vstack_on_non_matrices_fails(self):
             _v = Matrix.vstack(w, m)
 
 
-'''
-These are helpful functions to use in testing
-'''
+class TestHelpers(unittest.TestCase):
+    def setUp(self):
+        pyrtl.reset_working_block()
 
+    def test_list_to_int(self):
+        self.assertEquals(Matrix.list_to_int([[0]], 1), 0b0)
+        self.assertEquals(Matrix.list_to_int([[1, 2]], 2), 0b0110)
+        self.assertEquals(Matrix.list_to_int([[1, 2, 3]], 2), 0b011011)
+        self.assertEquals(Matrix.list_to_int([[4, 9, 11], [3, 5, 6]], 4),
+                          0b010010011011001101010110)
 
-def matrix_to_int(matrix, n_bits):
-    result = ''
+    def test_list_to_int_truncates(self):
+        self.assertEquals(Matrix.list_to_int([[4, 9, 27]], 3), 0b100001011)
 
-    for i in range(len(matrix)):
-        for j in range(len(matrix[0])):
-            result = result + bin(matrix[i][j])[2:].zfill(n_bits)
+    def test_list_to_int_negative(self):
+        self.assertEquals(Matrix.list_to_int([[-4, -9, 11]], 5), 0b111001011101011)
 
-    return int(result, 2)
+    def test_list_to_int_negative_truncates(self):
+        self.assertEquals(Matrix.list_to_int([[-4, -9, 11]], 3), 0b100111011)
+
+    def test_list_to_int_non_positive_n_bits(self):
+        with self.assertRaises(pyrtl.PyrtlError):
+            Matrix.list_to_int([[3]], 0)
 
 
 if __name__ == '__main__':