Skip to content

Commit 6c8988a

Browse files
committed
update matrix documentation
1 parent 5740c31 commit 6c8988a

File tree

1 file changed

+59
-59
lines changed

1 file changed

+59
-59
lines changed

pyrtl/rtllib/matrix.py

Lines changed: 59 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111

1212
class Matrix(object):
13-
'''Class for making a Matrix using PyRTL.
13+
''' Class for making a Matrix using PyRTL.
1414
1515
Provides the ability to perform different matrix operations.
1616
'''
@@ -21,18 +21,18 @@ class Matrix(object):
2121
def __init__(self, rows, columns, bits, signed=False, value=None, max_bits=64):
2222
''' Constructs a Matrix object.
2323
24-
:param int rows: the number of rows in the matrix. Must be greater than 0.
25-
:param int columns: the number of columns in the matrix. Must be greater than 0.
26-
:param int bits: The amount of bits per wirevector. Must be greater than 0.
24+
:param int rows: the number of rows in the matrix. Must be greater than 0
25+
:param int columns: the number of columns in the matrix. Must be greater than 0
26+
:param int bits: The amount of bits per wirevector. Must be greater than 0
2727
:param bool signed: Currently not supported (will be added in the future)
2828
:param (WireVector/list) value: The value you want to initialize the Matrix with.
2929
If a WireVector, must be of size `rows * columns * bits`. If a list, must have
3030
`rows` rows and `columns` columns, and every element must fit in `bits` size.
31-
If not given, the matrix initializes to 0.
31+
If not given, the matrix initializes to 0
3232
:param int max_bits: The maximum number of bits each wirevector can have, even
3333
after operations like adding two matrices together results in larger
34-
resulting wirevectors.
35-
:return: a constructed Matrix object.
34+
resulting wirevectors
35+
:return: a constructed Matrix object
3636
'''
3737
if not isinstance(rows, int):
3838
raise PyrtlError('Rows must be of type int, instead "%s" '
@@ -107,15 +107,15 @@ def __init__(self, rows, columns, bits, signed=False, value=None, max_bits=64):
107107
def bits(self):
108108
''' Gets the number of bits each value is allowed to hold.
109109
110-
:return: an integer representing the number of bits.
110+
:return: an integer representing the number of bits
111111
'''
112112
return self._bits
113113

114114
@bits.setter
115115
def bits(self, bits):
116116
''' Sets the number of bits.
117117
118-
:param int bits: The number of bits. Must be greater than 0.
118+
:param int bits: The number of bits. Must be greater than 0
119119
120120
Called automatically when bits is changed.
121121
NOTE: This function will truncate the most significant bits.
@@ -139,17 +139,17 @@ def __len__(self):
139139
140140
:return: an integer representing the output WireVector bitwidth
141141
142-
Used with default len() function
142+
Used with default `len()` function
143143
'''
144144
return self.bits * self.rows * self.columns
145145

146146
def to_wirevector(self):
147147
''' Outputs the PyRTL Matrix as a singular concatenated Wirevector.
148148
149-
:return: a Wirevector representing the whole PyRTL matrix.
149+
:return: a Wirevector representing the whole PyRTL matrix
150150
151-
For instance, if we had a 2 x 1 matrix [[wire_a, wire_b]] it would
152-
return the concatenated wire: wire = wire_a.wire_b
151+
For instance, if we had a 2 x 1 matrix `[[wire_a, wire_b]]` it would
152+
return the concatenated wire: `wire = wire_a.wire_b`
153153
'''
154154
result = []
155155

@@ -162,7 +162,7 @@ def to_wirevector(self):
162162
def transpose(self):
163163
''' Constructs the transpose of the matrix
164164
165-
:return: a Matrix object representing the transpose.
165+
:return: a Matrix object representing the transpose
166166
'''
167167
result = Matrix(self.columns, self.rows, self.bits, max_bits=self.max_bits)
168168
for i in range(result.rows):
@@ -173,7 +173,7 @@ def transpose(self):
173173
def __reversed__(self):
174174
''' Constructs the reverse of matrix
175175
176-
:return: a Matrix object representing the reverse.
176+
:return: a Matrix object representing the reverse
177177
178178
Used with the reversed() method
179179
'''
@@ -315,8 +315,7 @@ def __setitem__(self, key, value):
315315
:param (slice/int rows, slice/int columns) key: The key value to set
316316
:param Wirevector/int/Matrix value: The value in which to set the key
317317
318-
Called when setting a value using square brackets.
319-
(e.g. matrix[a, b] = value)
318+
Called when setting a value using square brackets (e.g. `matrix[a, b] = value`).
320319
321320
The value given will be truncated to match the bitwidth of all the elements
322321
in the matrix.
@@ -434,9 +433,9 @@ def copy(self):
434433
def __iadd__(self, other):
435434
''' Perform the in-place addition operation.
436435
437-
:return: a Matrix object with the element wise addition being preformed.
436+
:return: a Matrix object with the elementwise addition being preformed
438437
439-
Is used with a += b. Performs an elementwise addition.
438+
Is used with `a += b`. Performs an elementwise addition.
440439
'''
441440
new_value = (self + other)
442441
self._matrix = new_value._matrix
@@ -446,9 +445,9 @@ def __iadd__(self, other):
446445
def __add__(self, other):
447446
''' Perform the addition operation.
448447
449-
:return: a Matrix object with the element wise addition being performed.
448+
:return: a Matrix object with the element wise addition being performed
450449
451-
Is used with a + b. Performs an elementwise addition.
450+
Is used with `a + b`. Performs an elementwise addition.
452451
'''
453452
if not isinstance(other, Matrix):
454453
raise PyrtlError('error: expecting a Matrix, '
@@ -478,9 +477,9 @@ def __isub__(self, other):
478477
''' Perform the inplace subtraction opperation.
479478
480479
:Matrix other: the PyRTL Matrix to subtract
481-
:return: a Matrix object with the element wise subtraction being performed.
480+
:return: a Matrix object with the element wise subtraction being performed
482481
483-
Is used with a -= b. Performs an elementwise subtraction.
482+
Is used with `a -= b`. Performs an elementwise subtraction.
484483
'''
485484
new_value = self - other
486485
self._matrix = new_value._matrix
@@ -491,11 +490,11 @@ def __sub__(self, other):
491490
''' Perform the subtraction operation.
492491
493492
:Matrix other: the PyRTL Matrix to subtract
494-
:return: a Matrix object with the elementwise subtraction being performed.
493+
:return: a Matrix object with the elementwise subtraction being performed
495494
496-
Is used with a - b. Performs an elementwise subtraction.
495+
Is used with `a - b`. Performs an elementwise subtraction.
497496
498-
Note: If using unsigned numbers, the result will be floored at 0
497+
Note: If using unsigned numbers, the result will be floored at 0.
499498
'''
500499
if not isinstance(other, Matrix):
501500
raise PyrtlError('error: expecting a Matrix, '
@@ -531,10 +530,10 @@ def __sub__(self, other):
531530
def __imul__(self, other):
532531
''' Perform the in-place multiplication operation.
533532
534-
:Matrix/Wirevector other: the Matrix or scalar to multiply
535-
:return: a Matrix object with the resulting multiplication operation being preformed.
533+
:param Matrix/Wirevector other: the Matrix or scalar to multiply
534+
:return: a Matrix object with the resulting multiplication operation being preformed
536535
537-
Is used with a *= b. Performs an elementwise or scalar multiplication.
536+
Is used with `a *= b`. Performs an elementwise or scalar multiplication.
538537
'''
539538
new_value = self * other
540539
self._matrix = new_value._matrix
@@ -544,10 +543,10 @@ def __imul__(self, other):
544543
def __mul__(self, other):
545544
''' Perform the elementwise or scalar multiplication operation.
546545
547-
:Matrix/Wirevector other: the Matrix to multiply
548-
:return: a Matrix object with the resulting multiplication operation being performed.
546+
:param Matrix/Wirevector other: the Matrix to multiply
547+
:return: a Matrix object with the resulting multiplication operation being performed
549548
550-
Is used with a * b.
549+
Is used with `a * b`.
551550
'''
552551

553552
if isinstance(other, Matrix):
@@ -583,7 +582,7 @@ def __imatmul__(self, other):
583582
:param Matrix other: the second matrix.
584583
:return: a PyRTL Matrix that contains the matrix multiplication product of this and other
585584
586-
Is used with a @= b
585+
Is used with `a @= b`.
587586
588587
Note: The matmul symbol (@) only works in python 3.5+. Otherwise you must
589588
call `__imatmul__(other)`.
@@ -601,7 +600,7 @@ def __matmul__(self, other):
601600
:param Matrix other: the second matrix.
602601
:return: a PyRTL Matrix that contains the matrix multiplication product of this and other
603602
604-
Is used with a @ b
603+
Is used with `a @ b`.
605604
606605
Note: The matmul symbol (@) only works in python 3.5+. Otherwise you must
607606
call `__matmul__(other)`.
@@ -633,7 +632,7 @@ def __ipow__(self, power):
633632
:param int power: the power to perform the matrix on
634633
:return: a PyRTL Matrix that contains the matrix power product
635634
636-
Is used with a **= b
635+
Is used with `a **= b`.
637636
'''
638637
new_value = self ** power
639638
self._matrix = new_value._matrix
@@ -646,7 +645,7 @@ def __pow__(self, power):
646645
:param int power: the power to perform the matrix on
647646
:return: a PyRTL Matrix that contains the matrix power product
648647
649-
Is used with a ** b
648+
Is used with `a ** b`.
650649
'''
651650
if not isinstance(power, int):
652651
raise PyrtlError('Unexpected power given. Type int expected, '
@@ -754,6 +753,7 @@ def reshape(self, *newshape, order='C'):
754753
and the number of elements in the matrix.
755754
756755
Examples::
756+
757757
int_matrix = [[0, 1, 2, 3], [4, 5, 6, 7]]
758758
matrix = Matrix.Matrix(2, 4, 4, value=int_matrix)
759759
@@ -835,7 +835,7 @@ def flatten(self, order='C'):
835835
''' Flatten the matrix into a single row.
836836
837837
:param str order: 'C' means row-major order (C-style), and
838-
'F' means column-major order (Fortran-style).
838+
'F' means column-major order (Fortran-style)
839839
:return: A copy of the matrix flattened in to a row vector matrix
840840
'''
841841
return self.reshape(self.rows * self.columns, order=order)
@@ -844,9 +844,9 @@ def flatten(self, order='C'):
844844
def multiply(first, second):
845845
''' Perform the elementwise or scalar multiplication operation.
846846
847-
:param Matrix first: first matrix.
848-
:param Matrix/Wirevector second: second matrix.
849-
:return: a Matrix object with the element wise or scaler multiplication being performed.
847+
:param Matrix first: first matrix
848+
:param Matrix/Wirevector second: second matrix
849+
:return: a Matrix object with the element wise or scaler multiplication being performed
850850
'''
851851
if not isinstance(first, Matrix):
852852
raise PyrtlError('error: expecting a Matrix, '
@@ -858,9 +858,9 @@ def sum(matrix, axis=None, bits=None):
858858
''' Returns the sum of all the values in a matrix
859859
860860
:param Matrix/Wirevector matrix: the matrix to perform sum operation on.
861-
If it is a WireVector, it will return itself.
862-
:param None/int axis: The axis to perform the operation on.
863-
None refers to sum of all item. 0 is sum of column. 1 is sum of rows. Defaults to None.
861+
If it is a WireVector, it will return itself
862+
:param None/int axis: The axis to perform the operation on
863+
None refers to sum of all item. 0 is sum of column. 1 is sum of rows. Defaults to None
864864
:param int bits: The bits per value of the sum. Defaults to bits of old matrix
865865
:return: A wirevector or Matrix representing sum
866866
'''
@@ -922,9 +922,9 @@ def min(matrix, axis=None, bits=None):
922922
''' Returns the minimum value in a matrix.
923923
924924
:param Matrix/Wirevector matrix: the matrix to perform min operation on.
925-
If it is a WireVector, it will return itself.
926-
:param None/int axis: The axis to perform the operation on.
927-
None refers to min of all item. 0 is min of column. 1 is min of rows. Defaults to None.
925+
If it is a WireVector, it will return itself
926+
:param None/int axis: The axis to perform the operation on
927+
None refers to min of all item. 0 is min of column. 1 is min of rows. Defaults to None
928928
:param int bits: The bits per value of the min. Defaults to bits of old matrix
929929
:return: A WireVector or Matrix representing the min value
930930
'''
@@ -986,10 +986,10 @@ def max(matrix, axis=None, bits=None):
986986
''' Returns the max value in a matrix.
987987
988988
:param Matrix/Wirevector matrix: the matrix to perform max operation on.
989-
If it is a wirevector, it will return itself.
990-
:param None/int axis: The axis to perform the operation on.
989+
If it is a wirevector, it will return itself
990+
:param None/int axis: The axis to perform the operation on
991991
None refers to max of all items. 0 is max of the columns. 1 is max of rows.
992-
Defaults to None.
992+
Defaults to None
993993
:param int bits: The bits per value of the max. Defaults to bits of old matrix
994994
:return: A WireVector or Matrix representing the max value
995995
'''
@@ -1053,10 +1053,10 @@ def argmax(matrix, axis=None, bits=None):
10531053
''' Returns the index of the max value of the matrix.
10541054
10551055
:param Matrix/Wirevector matrix: the matrix to perform argmax operation on.
1056-
If it is a WireVector, it will return itself.
1056+
If it is a WireVector, it will return itself
10571057
:param None/int axis: The axis to perform the operation on.
10581058
None refers to argmax of all items. 0 is argmax of the columns. 1 is argmax of rows.
1059-
Defaults to None.
1059+
Defaults to None
10601060
:param int bits: The bits per value of the argmax. Defaults to bits of old matrix
10611061
:return: A WireVector or Matrix representing the argmax value
10621062
@@ -1126,9 +1126,9 @@ def argmax(matrix, axis=None, bits=None):
11261126
def dot(first, second):
11271127
''' Performs the dot product on two matrices.
11281128
1129-
:param Matrix first: the first matrix.
1130-
:param Matrix second: the second matrix.
1131-
:return: a PyRTL Matrix that contains the dot product of the two PyRTL Matrices.
1129+
:param Matrix first: the first matrix
1130+
:param Matrix second: the second matrix
1131+
:return: a PyRTL Matrix that contains the dot product of the two PyRTL Matrices
11321132
11331133
Specifically, the dot product on two matrices is
11341134
* If either first or second are WireVectors/have both rows and columns
@@ -1182,15 +1182,15 @@ def hstack(*matrices):
11821182
11831183
All the matrices must have the same number of rows and same 'signed' value.
11841184
1185-
For example:
1185+
For example::
11861186
11871187
m1 = Matrix(2, 3, bits=5, value=[[1,2,3],
11881188
[4,5,6]])
11891189
m2 = Matrix(2, 1, bits=10, value=[[17],
11901190
[23]]])
11911191
m3 = hstack(m1, m2)
11921192
1193-
m3 looks like:
1193+
m3 looks like::
11941194
11951195
[[1,2,3,17],
11961196
[4,5,6,23]]
@@ -1236,14 +1236,14 @@ def vstack(*matrices):
12361236
12371237
All the matrices must have the same number of columns and same 'signed' value.
12381238
1239-
For example:
1239+
For example::
12401240
12411241
m1 = Matrix(2, 3, bits=5, value=[[1,2,3],
12421242
[4,5,6]])
12431243
m2 = Matrix(1, 3, bits=10, value=[[7,8,9]])
12441244
m3 = vstack(m1, m2)
12451245
1246-
m3 looks like:
1246+
m3 looks like::
12471247
12481248
[[1,2,3],
12491249
[4,5,6],
@@ -1350,7 +1350,7 @@ def list_to_int(matrix, n_bits):
13501350
13511351
:param list[list[int]] matrix: a pure Python list of lists representing a matrix
13521352
:param int n_bits: number of bits to be used to represent each element; if an
1353-
element doesn't fit in n_bits, it truncates the most significant bits.
1353+
element doesn't fit in n_bits, it truncates the most significant bits
13541354
:return int: a N*n_bits wide wirevector containing the elements of `matrix`,
13551355
where N is the number of elements in `matrix`
13561356

0 commit comments

Comments
 (0)