Util

Utility Modules

finn.util.basic

class finn.util.basic.CppBuilder

Bases: object

Builds the g++ compiler command to produces the executable of the c++ code in code_gen_dir which is passed to the function build() of this class.

append_includes(library_path)

Adds given library path to include_paths list.

append_sources(cpp_file)

Adds given c++ file to cpp_files list.

build(code_gen_dir)

Builds the g++ compiler command according to entries in include_paths and cpp_files lists. Saves it in bash script in given folder and executes it.

set_executable_path(path)

Sets member variable “executable_path” to given path.

finn.util.basic.calculate_signed_dot_prod_range(dt_a, dt_b, len)

Returns the (min,max) values a dot product between two signed vectors of types dt_a and dt_b of len elements can take.

finn.util.basic.gen_finn_dt_tensor(finn_dt, tensor_shape)

Generates random tensor in given shape and with given FINN DataType.

finn.util.basic.get_by_name(container, name, name_field='name')

Return item from container by .name field if it exists, None otherwise

finn.util.basic.get_finn_root()

Return the root directory that FINN is cloned into.

finn.util.basic.interleave_matrix_outer_dim_from_partitions(matrix, n_partitions)

Interleave the outermost dimension of a matrix from given partitions (n_partitions).

finn.util.basic.make_build_dir(prefix='')

Creates a temporary folder with given prefix to be used as a build dir. Use this function instead of tempfile.mkdtemp to ensure any generated files will survive on the host after the FINN Docker container exits.

finn.util.basic.pad_tensor_to_multiple_of(ndarray, pad_to_dims, val=0, distr_pad=False)

Pad each dimension of given NumPy ndarray using val, so that each dimension is a multiple of the respective value in pad_to_dims. -1 means do not pad that particular dimension. If distr_pad is False, all padding will be inserted after the existing values; otherwise it will be split evenly between before and after the existing values, with one extra value inserted after if the padding amount is not divisible by two.

finn.util.basic.random_string(stringLength=6)

Randomly generate a string of letters and digits.

finn.util.basic.remove_by_name(container, name, name_field='name')

Remove item from container by .name field if it exists.

finn.util.basic.roundup_to_integer_multiple(x, factor)

Round up integer x to the nearest integer multiple of integer factor. Returns x if factor is set to -1. Both x and factor must otherwise be positive.

finn.util.data_packing

finn.util.data_packing.array2hexstring(array, dtype, pad_to_nbits, prefix='0x', reverse=False)

Pack given one-dimensional NumPy array with FINN DataType dtype into a hex string. Any BIPOLAR values will be converted to a single bit with a 0 representing -1. pad_to_nbits is used to prepend leading zeros to ensure packed strings of fixed width. The minimum value for pad_to_nbits is 4, since a single hex digit is four bits. reverse can be used to reverse the array prior to packing.

Examples:

array2hexstring([1, 1, 1, 0], DataType.BINARY, 4) = “0xe”

array2hexstring([1, 1, 1, 0], DataType.BINARY, 8) = “0x0e”

array2hexstring([1, 1, 0, 1], DataType.BINARY, 4, reverse=True) = “0xb”

array2hexstring([1, 1, 1, 0], DataType.BINARY, 8, reverse=True) = “0x07”

finn.util.data_packing.finnpy_to_packed_bytearray(ndarray, dtype, reverse_inner=False)

Given a numpy ndarray with FINN DataType dtype, pack the innermost dimension and return the packed representation as an ndarray of uint8. The packed innermost dimension will be padded to the nearest multiple of 8 bits. The returned ndarray has the same number of dimensions as the input.

finn.util.data_packing.hexstring2npbytearray(hexstring, remove_prefix='0x')

Convert a hex string into a NumPy array of dtype uint8.

Example:

hexstring2npbytearray(“0f01”) = array([15, 1], dtype=uint8)

finn.util.data_packing.npbytearray2hexstring(npbytearray, prefix='0x')

Convert a NumPy array of uint8 dtype into a hex string.

Example:

npbytearray2hexstring(array([15, 1], dtype=uint8)) = “0x0f01”

finn.util.data_packing.npy_to_rtlsim_input(input_file, input_dtype, pad_to_nbits, reverse_inner=True)

Convert the multidimensional NumPy array of integers (stored as floats) from input_file into a flattened sequence of Python arbitrary-precision integers, packing the innermost dimension. See finn.util.basic.pack_innermost_dim_as_hex_string() for more info on how the packing works. If reverse_inner is set, the innermost dimension will be reversed prior to packing.

finn.util.data_packing.numpy_to_hls_code(ndarray, dtype, hls_var_name, pack_innermost_dim=True, no_decl=False)

Return C++ code representation of a numpy ndarray with FINN DataType dtype, using hls_var_name as the resulting C++ variable name. If pack_innermost_dim is specified, the innermost dimension of the ndarray will be packed into a hex string using array2hexstring. If no_decl is set to True, no variable name and type will be generated as part of the emitted string.

finn.util.data_packing.pack_innermost_dim_as_hex_string(ndarray, dtype, pad_to_nbits, reverse_inner=False)

Pack the innermost dimension of the given numpy ndarray into hex strings using array2hexstring.

Examples:

A = [[1, 1, 1, 0], [0, 1, 1, 0]]

eA = [“0e”, “06”]

pack_innermost_dim_as_hex_string(A, DataType.BINARY, 8) == eA

B = [[[3, 3], [3, 3]], [[1, 3], [3, 1]]]

eB = [[ “0f”, “0f”], [“07”, “0d”]]

pack_innermost_dim_as_hex_string(B, DataType.UINT2, 8) == eB

finn.util.data_packing.packed_bytearray_to_finnpy(packed_bytearray, dtype, output_shape=None, reverse_inner=False, reverse_endian=False)

Given a packed numpy uint8 ndarray, unpack it into a FINN array of given DataType.

output_shape can be specified to remove padding from the packed dimension, or set to None to be inferred from the input.

finn.util.data_packing.rtlsim_output_to_npy(output, path, dtype, shape, packedBits, targetBits, reverse_inner=True)

Convert a flattened sequence of Python arbitrary-precision integers output into a NumPy array, saved as npy file at path. Each arbitrary-precision integer is assumed to be a packed array of targetBits-bit elements, which will be unpacked as the innermost dimension of the NumPy array.

finn.util.data_packing.unpack_innermost_dim_from_hex_string(ndarray, dtype, out_shape, packedBits, reverse_inner=False)

Convert a NumPy array of hex strings into a FINN NumPy array by unpacking the hex strings into the specified data type. out_shape can be specified such that any padding in the packing dimension is removed. If reverse_inner is set, the innermost unpacked dimension will be reversed.

finn.util.fpgadataflow

class finn.util.fpgadataflow.IPGenBuilder

Bases: object

Builds the bash script to generate IP blocks using Vivado HLS.

append_tcl(tcl_script)

Sets member variable “tcl_script” to given tcl script.

build(code_gen_dir)

Builds the bash script with given parameters and saves it in given folder. To guarantee the generation in the correct folder the bash script contains a cd command.

set_ipgen_path(path)

Sets member variable ipgen_path to given path.

finn.util.fpgadataflow.pyverilate_get_liveness_threshold_cycles()

Return the number of no-output cycles rtlsim will wait before assuming the simulation is not finishing and throwing an exception.

finn.util.fpgadataflow.pyverilate_stitched_ip(model)

Given a model with stitched IP, return a PyVerilator sim object.

finn.util.onnx

finn.util.onnx.valueinfo_to_tensor(vi)

Creates an all-zeroes numpy tensor from a ValueInfoProto.

finn.util.test

finn.util.test.get_test_model_def_fxn(netname)

Returns the PyTorch model instantation function related to netname.

finn.util.test.get_test_model_trained(netname, wbits, abits)

Returns the pretrained model specified by input arguments loaded with weights and activations from the FINN Brevitas test networks.

finn.util.test.get_test_model_untrained(netname, wbits, abits)

Returns untrained model specified by input arguments.

finn.util.test.get_trained_checkpoint(netname, wbits, abits)

Returns the weights and activations from the FINN Brevitas test networks for given netname and the number of bits for weights and activations