Matrix_lib

This library contains functionalities to perform triple-assisted convolutions and fully connected layers.

convolution and fully connected layers

convolution

conv3d_sfix2sfix

Performs a convolution of 3d features (rearranged as 2d matrixes). It accepts strides 1 and 2. It accepts any padding. The input features and kernels must be type SFIX. The convolutional triple must be previously declared (please check documentation related to matrix triples).

arguments	description
X_sfix	Input features – 2d matrix with dimension (w $\cdot$ h, s) (type SFIX)
Y_sfix	Kernels – 2d matrix with dimension (kw $\cdot$ kh $\cdot$ s, s_)
(type SFIX)
triple_type	Convolutional triple element type
kh	Kernel height
kw	Kernel width
s	Input channels
s_	Output channels
h	Feature height
w	Feature width
stride	stride (1 or 2)
padding	padding (any value)
mode	Trunc_Mode.ON or Trunc_Mode.OFF

OUTPUT: A matrix Z with dimension (w_out $\cdot$ h_out, s_) where 'w_out' and 'h_out' are width and hight of the output features, which depend on the stride and the padding.

Both w' and h' are internally calculated as:

if padding > 0:  
    h = (h + (2 * padding))  
    w = (w + (2 * padding))  

if stride == 2:  
    w_out = (w - kw + 1)  
    h_out = (h - kh + 1)  
    w_out = (w_out // stride)  
    h_out = (h_out // stride)  

    if (w % stride) > 0:  
        w_out += 1  
    if (h % stride) > 0:  
        h_out += 1

NOTE 1 :This function calls conv3d_sint2sint, after converting the input matrixes into SINT type. Then it performs probabilistic truncation on the output matrix.

NOTE 2: TruncMode is a class defined in this library. It accepts two values, ON or OFF. When ON, the output is appropriately truncated after the convolution, otherwise this must be done later.

NOTE 3: For testing purposes, you can define the triple with offline_triple_lib.NNTripleType(0, w, h, s, kh, kw, s_, stride, padding), but remember to import offline_triple_lib

matrix multiplication

multmat_sfix2sfix

Performs a matrix multiplication using matrix triples. Returns X $\cdot$ Y. The matrixes must be type SFIX. The matrix triple must be previously declared (please check documentation related to matrix triples).

arguments	description
X_sfix	Input features – 2d matrix with dimension (w $\cdot$ h, s) (type SFIX)
Y_sfix	Kernels – 2d matrix with dimension (kw $\cdot$ kh $\cdot$ s, s_) (type SFIX)
triple_type	Matrix triple element type

OUTPUT: Z = X $\cdot$ Y.

NOTE 1: This function calls multmat_sint2sint, after converting the input matrixes into SINT type. Then it performs probabilistic truncation on the output matrix.

NOTE 2: TruncMode is a class defined in this library. It accepts two values, ON or OFF. When ON, the output is appropriately truncated after the convolution, otherwise this must be done later.

NOTE 3: For testing purposes, you can define the triple with offline_triple_lib.TripleType(0, 1, s, s, s_, 1, s_), but remember to import offline_triple_lib

vectorized ReLUs with truncation

truncate_sfix_matrix_plus_ReLU

Performs a ReLU in all elements, and in parallel several truncations. Returns ReLU(Trunc(X)). The matrixes must be type SFIX.

arguments	description
X	Input 2d matrix (type SFIX)
number_of_truncs	number of truncations to perform (default = 1)

NOTE: The number of truncations must correspond with the number of multiplications / convolutions previously executed without truncation.

scaling

scale_matrix

Makes a shift left for as many bits as needed to equal the number of truncations specified. This is needed when a matrix has to be added to another matrix that has been multiplied/convolved without truncation.

arguments	description
X	Input 2d matrix (type SFIX)
number_of_truncs	number of truncations to to scale (default = 1)

NOTE: When two matrix are to be added, and one of them has been multiplied previously without truncation. Then the other matrix should be scaled, and the number of truncations must correspond with the number of multiplications / convolutions previously executed without truncation.

vectorized probabilistic truncation

truncate_sfix_matrix

arguments	description
X	2d matrix (type SFIX)
value	SFIX value with correct fractional part

OUTPUT: X with correct fractional size. Takes a Matrix that has undergone a multiplication / convolution, and truncates the all values. This function is required to correct the offset of the fractional part. Second argument is used as a reference.

NOTE 1: This function equals the functionality of performing truncation individually in each matrix value, but it is more efficient. The process is vectorized, thus it renders less lines of code in the MPC program, and it also ensures that the number of communication rounds is minimized even when the compiler uses the -O1 flag.

NOTE 2: This function is called in conv3d_sfix2sfix and mulmat_sfix2sfix when mode = matrix_lib.TruncMode.ON

data formatting

rearrange_3d_features_into_2d_matrix

arguments	description
X	3d tensor with dimension (s, h, w), (any type)

OUTPUT: Outputs a 2d matrix with dimension (h $\cdot$ w, s)

rearrange_2d_matrix_into_3d_features

arguments	description
X	2d matrix (r, s), (any type)
h	height
w	width

OUTPUT: Outputs a 3d tensor with dimension (s, h, w).

NOTE: h and w must fulfil h$\cdot$w = r

rearrange_4d_kernels_into_2d_matrix

arguments	description
X	4d tensor with dimension (s_, s, kh, kw), (any type)

OUTPUT: Outputs a 2d matrix with dimension (kh $\cdot$ kw, s $\cdot$ s_).

rearrange_2d_matrix_into_4d_kernels

arguments	description
X	2d matrix (r, s), (any type)
l	padding
s	input channels
s_	output channels

OUTPUT: Outputs a 4d tensor with dimension (s_, s, kh, kw); where kh = kw = 2 $\cdot$l + 1

support functions

conv3d_sint2sint

arguments	description
X_sfix	Input features – 2d matrix with dimension (w $\cdot$ h, s) (type SINT)
Y_sfix	Kernels – 2d matrix with dimension (kw $\cdot$ kh $\cdot$ s, s_) (type SINT)
A	Convolutional triple element A
B	Convolutional triple element B
C	Convolutional triple element C
kh	Kernel height
kw	Kernel width
s	Input channels
s_	Output channels
h	Feature height
w	Feature width
stride	stride (1 or 2)
padding	padding (any value)

OUTPUT: Same as conv3d_sfix2sfix but for SINT type. This function is called by conv3d_sfix2sfix.

matrix multiplication

multmat_sint2sint

arguments	description
X_sfix	Input features – 2d matrix with dimension (w $\cdot$ h, s) (type SINT)
Y_sfix	Kernels – 2d matrix with dimension (kw $\cdot$ kh $\cdot$ s, s_) (type SINT)
A	Convolutional triple element A
B	Convolutional triple element B
C	Convolutional triple element C

OUTPUT: Same as multmat_sfix2sfix but for SINT type. This functions is called by multmat_sfix2sfix

multmat_sint2cint

arguments	description
A	2d matrix (type SINT)
B	2d matrix (type CINT)

multmat_cint2sint

arguments	description
A	2d matrix (type CINT)
B	2d matrix (type SINT)

multmat_cint2cint

arguments	description
A	2d matrix (type CINT)
B	2d matrix (type CINT)

OUTPUT: C = A $\cdot$ B

NOTE: Multiplies A and B (with different types when at least one is CINT). These operations do not require communication rounds and triples. This functions are required in: i) conv3d_sint2sint; and ii) multmat_sint2sint.

other operations

sint_to_sfix_matrix

arguments	description
X	2d matrix (type SINT)

OUTPUT: transforms a matrix from SINT to SFIX. This is used to come back to SFIX after operating over mantissas.

traspose

arguments	description
X	2d matrix (any type)

OUTPUT: transpose of a matrix. Any type (SFIX, SINT, CINT).

add_matrices

arguments	description
X	2d matrix (any type)
Y	2d matrix (any type)

OUTPUT: X + Y. Any type (SFIX, SINT, CINT).

flatten_to_array

arguments	description
X	2d matrix (any type)

OUTPUT: X as an Array type. Any type (SFIX, SINT, CINT). Ordered by input rows.

flatten_to_rowmatrix

arguments	description
X	2d matrix (any type)

OUTPUT: A as single row Matrix. Any type (SFIX, SINT, CINT). Ordered by input columns.

sfix_matrix_equals

arguments	description
X	2d matrix (type SFIX)
Y	2d matrix (type SFIX)
tolerance	allowed difference in the mantissa

OUTPUT: 1 if matrixes are equal, 0 otherwise.

NOTE: Tests equality of two matrixes of type SFIX. Each value is compared individually and some difference (‘tolerance’) is allowed in the mantissa. This function is NOT PRIVATE. Used for testing only.

transformations for convolution

The below transformations allow performing a convolution as a matrix multiplication.

transform_input_features

arguments	description
X	2d matrix with dimension (h$\cdot$w,s) (type any)
h	height
w	width
s	channels
kh	kernel height
kw	kernel width
stride	stride (1 or 2)

OUTPUT: Transforms X into another 2d matrix with dimension (w’ $\cdot$ h’ , kh $\cdot$ kw $\cdot$ s). Stride supported 1 and 2. Function used in: conv3d_sint2sint.

transform_kernels

arguments	description
K	2d matrix with dimension (h$\cdot$w,s) (type any)
kh	height
kw	width
s	input channels
s_	output channels

OUTPUT: Transforms the Kernels K from a 2D matrix (kh $\cdot$ kw, s $\cdot$ s_) into another 2d matrix (kh $\cdot$ kw $\cdot$ s, s_). Function used in: conv3d_sint2sint.

prune_matrix_rows_according_to_stride

arguments	description
X	2d matrix with dimension (h$\cdot$w,s) (type any)
h	height
w	width
stride	stride

OUTPUT: Takes a set of 3D features, represented as 2D matrix, and deletes rows according to the stride. This function is used inside conv3d_sfix2sfix->conv3d_sint2sint->transform_input_features.

pad_feature_with_zeros_2d(X, h, w, l)

arguments	description
X	2d matrix with dimension (h$\cdot$w,s) (type any)
h	height
w	width
l	padding

OUTPUT: Takes a set of 3D features, represented as 2D matrix, pads 'l' zeros in the edges. This function is used inside conv3d_sfix2sfix->conv3d_sint2sint.

input / output functions

input_to_matrix

arguments	description
input	List
n	number of rows
m	number of columns

OUTPUT: Converts input list to a matrix (n, m).

input_matrix_triple

arguments	description
rowsA	number of rows of A
colsA	number of columns of A
colsB	number of columns of B
channel	input channel (default=0)

OUTPUT: Inputs a matrix triple A,B,C from channel

output_matrix_triple

arguments	description
triple	Tuple [A,B,C]
channel	output channel (default=0)

OUTPUT: Outputs a matrix triple A,B,C to channel

compare__matrix_from_file

arguments	description
A	matrix (type SFIX)
path	file path
tolerance	allowed difference in the mantissa

OUTPUT: 1 if equal, 0 otherwise. Compares a SFIX matrix with another one stored in a file. It uses a tolerance and calls function sfix_matrix_equals. This function is NOT PRIVATE, used for testing.

faster helper functions

These functions user register memory, and are faster than their counterparts. Only compatible with SINT type.

traspose_sint_reg

arguments	description
A	matrix (type SINT)
h	height (rows)
w	width (columns)

OUTPUT: Outputs transpose of a matrix. Only SINT type. Same functionality as traspose.

flatten_to_array

arguments	description
A	matrix (type SINT)

OUTPUT: Transforms a Matrix type into an Array type. Only SINT type. Same functionality as flatten_to_array.

legacy functions

These functions have not been properly tested. We recommend using conv3d_sfix2sfix*, conv3d_sint2sint, transform_kernels, transform_input_features instead. They operate like the previous functions but are optimized for padding equal to 'l' where the kernels have size ((2l+1) , (2l+1)).

conv3d_sfix2sfix_adjusted_padding

conv3d_sint2sint_adjusted_padding

transform_kernels_adjusted_padding

transform_input_features_adjusted_padding

new byte codes in SCALE compiler

The following bytecodes have been added to the compiler to extend its functionality. These byte codes perform a summation of an array of SINT or CINT values.

Both bytecodes have the following syntax:

sums(output, input_array, size)
sumc(output, input_array, size)

for example:

sint_array1 = sint(size=100) # array of 100 elements  
summation = sint() # a single sint 
sums(summation, aint_array, 100) # the variable 'summation' stores the addition of 100 elements

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

matrix_lib.md

matrix_lib.md

Matrix_lib

convolution and fully connected layers

convolution

matrix multiplication

vectorized ReLUs with truncation

scaling

vectorized probabilistic truncation

data formatting

support functions

matrix multiplication

other operations

transformations for convolution

input / output functions

faster helper functions

legacy functions

new byte codes in SCALE compiler

Files

matrix_lib.md

Latest commit

History

matrix_lib.md

File metadata and controls

Matrix_lib

convolution and fully connected layers

convolution

matrix multiplication

vectorized ReLUs with truncation

scaling

vectorized probabilistic truncation

data formatting

support functions

matrix multiplication

other operations

transformations for convolution

input / output functions

faster helper functions

legacy functions

new byte codes in SCALE compiler