Util

Utility Modules

qonnx.util.basic

qonnx.util.basic.auto_pad_to_explicit_padding(autopad_str, idim_h, idim_w, k_h, k_w, stride_h, stride_w, n_dims)

qonnx.util.basic.calculate_matvec_accumulator_range(matrix: ndarray, vec_dt: DataType)

Calculate the minimum and maximum possible result (accumulator) values for a dot product x * A, given matrix A of dims (MW, MH), and vector (1, MW) with datatype vec_dt. Returns (acc_min, acc_max).

qonnx.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.

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

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

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

Return item from protobuf container by .name field if it exists, None otherwise. Will throw an Exception if multiple items are found, since this violates the ONNX standard.

qonnx.util.basic.get_execution_error_thresh()

Return the max error that is allowed for rounding in QONNX execution.

qonnx.util.basic.get_num_default_workers()

Return the number of workers for parallel transformations. Controllable via the NUM_DEFAULT_WORKERS environment variable. If the env.var. is undefined, the default value of 1 is returned.

qonnx.util.basic.get_preferred_onnx_opset()

Return preferred ONNX opset version for QONNX

qonnx.util.basic.get_sanitize_quant_tensors()

Return whether tensors with quantization annotations should be sanitized. Enabled by default, disabling will yield faster ONNX execution but may give incorrect results. Use with caution.

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

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

qonnx.util.basic.is_finn_op(op_type)

Return whether given op_type string is a QONNX or FINN custom op

qonnx.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.

qonnx.util.basic.qonnx_make_model(graph_proto, **kwargs)

Wrapper around ONNX make_model with preferred qonnx opset version

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

Randomly generate a string of letters and digits.

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

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

qonnx.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.

qonnx.util.basic.sanitize_quant_values(model, node_tensors, execution_context, check_values=False)

Sanitize given list of tensors in execution_context by rounding values that are supposed to be integers (as indicated by their quantization annotation). Will raise an assertion if the amount of rounding is too large. Returns the sanitized execution context.

If check_values is specified, an extra DataType.allowed() check will be performed on any rounded tensors.

Background: QONNX uses floating point tensors as a carrier data type to represent integers. Floating point arithmetic can introduce rounding errors, e.g. (int_num * float_scale) / float_scale is not always equal to int_num. We use this function to ensure that the values that are supposed to be integers are indeed integers.

qonnx.util.cleanup

qonnx.util.cleanup.cleanup(in_file, *, out_file=None, preserve_qnt_ops=True, override_inpsize: str | None = None, extract_conv_bias=False)

Execute a set of graph transformations to clean-up the given ONNX file.

Parameters:

• in_file – Filename for the input ONNX model

• preserve_qnt_ops – Preserve weight quantization operators

• out_file – If set, filename for the output ONNX model. Set to in_file with _clean suffix otherwise.

• override_inpsize – If specified, override the input size (e.g. “(1,3,224,224)” to set all or just 1 to set batchsize to 1) for the ONNX graph

• extract_conv_bias – If specified, separate Conv bias into its own Add node

qonnx.util.cleanup.cleanup_model(model, preserve_qnt_ops=True, override_inpsize=None, extract_conv_bias=False)

Execute the transformations for the cleanup function on a model level. This allows the reuse of the cleanup transformations, without needing to read/write the model from/to disk.

Parameters:

model – A raw QONNX model from as example Brevitas.

Return model_clean:

The cleaned model

qonnx.util.cleanup.main()

qonnx.util.config

qonnx.util.config.extract_model_config_to_json(model, json_filename, attr_names_to_extract)

Create a json file with layer name -> attribute mappings extracted from the model. The created json file can be later applied on a model with qonnx.transform.general.ApplyConfig.

qonnx.util.convert

qonnx.util.convert.convert(input_model_file, *, output_style: functools.partial(<function _use_class at 0x7f7b98c97040>, <class 'clize.parser.use_mixin.<locals>._PosWithMixin'>, <class 'clize.parser.use_mixin.<locals>._VarargsWithMixin'>, <class 'clize.parser.use_mixin.<locals>._NamedWithMixin'>, <function unimplemented_parameter at 0x7f7b98d0bb80>, {'case_sensitive': None, 'list_name': 'list', 'values': [('qcdq', ['qcdq', ]'Convert from Quant to QCDQ'), ('quant', ['quant', ]'Convert from QCDQ to Quant')]}), output_file: str | None = None)

Convert an ONNX file from one style of quantization to another, where possible. Please see the documentation on the QuantToQCDQ and QCDQToQuant transformations to learn more about the particular limitations.

Parameters:

• input_model_file – Filename for the input ONNX model.

• output_style – Quantization style for the output.

• output_file – If specified, write the output ONNX model to this filename. Otherwise, will default to the input file with an _output_style suffix.

qonnx.util.convert.main()

qonnx.util.exec_qonnx

qonnx.util.exec_qonnx.exec_qonnx(qonnx_model_file, *in_npy, override_batchsize: int | None = None, override_opset: int | None = None, expose_intermediates: str | None = None, output_prefix: str = 'out_', output_mode: functools.partial(<function _use_class at 0x7f7b98c97040>, <class 'clize.parser.use_mixin.<locals>._PosWithMixin'>, <class 'clize.parser.use_mixin.<locals>._VarargsWithMixin'>, <class 'clize.parser.use_mixin.<locals>._NamedWithMixin'>, <function unimplemented_parameter at 0x7f7b98d0bb80>, {'case_sensitive': None, 'list_name': 'list', 'values': [('tensor_index', ['tensor_index', ]'Output files named by index'), ('tensor_name', ['tensor_name', ]'Output files named by tensor')]}) = 'tensor_name', argmax_verify_npy: str | None = None, save_modified_model: str | None = None, input_pix2float=False, input_zerocenter=False, maxiters: int | None = None, output_nosave=False)

Execute a given QONNX model by initializing its inputs from .npy files, and write outputs as .npy files. The input model have been previously cleaned by the cleanup transformation or commandline tool.

Parameters:

• qonnx_model_file – Filename for the input ONNX model

• in_npy – List of .npy files to supply as inputs. If not specified, inputs will be set to zero.

• override_batchsize – If specified, override the batch size for the ONNX graph

• override_opset – If specified, override the imported ONNX opset to this version.

• expose_intermediates – Comma-separated list of tensor name patterns. Matched patterns will expose intermediate outputs as top-level outputs.

• output_prefix – Prefix for the generated output files.

• output_mode – Naming mode for generated output files.

• argmax_verify_npy – If specified, take argmax of output and compare to this file for top-1 accuracy measurement

• save_modified_model – If specified, save the modified model (after batchsize changes or exposed intermediate tensors) with this filename

• input_pix2float – If specified, do uint8 [0,255] -> fp32 [0,1] mapping for input

• input_zerocenter – If specified together with pix2float, do uint8 [0,255] -> fp32 [-1,+1] mapping for input

• maxiters – If specified, limit maximum number of iterations (batches) to be processed

• output_nosave – If specified, do not save output tensors to files

qonnx.util.exec_qonnx.main()

qonnx.util.inference_cost

qonnx.util.inference_cost.compute_bops_and_macs(inf_cost_dict)

qonnx.util.inference_cost.compute_mem_bits_and_elems(inf_cost_dict, filter_string='mem_w')

qonnx.util.inference_cost.inference_cost(model_filename_or_wrapper, *, output_json=None, output_onnx=None, preprocess=True, discount_sparsity=True)

Return the inference cost estimate metric for given ONNX model. Supports the Quant op for weight/activation quantization.

Parameters:

• model_filename_or_wrapper – Filename or ModelWrapper for ONNX model

• output_json – Optional JSON filename to save the inference cost dict

• output_onnx – Optional ONNX filename to save the final model after any preprocessing

• preprocess – If set, run preprocessing steps such as shape inference, datatype inference and constant folding. Strongly recommended.

• discount_sparsity – If set, will discount op cost of MAC ops with a constant zero weight, and the mem cost of constant zero weights.

qonnx.util.inference_cost.main()

qonnx.util.onnx

qonnx.util.onnx.nchw_to_nhwc(t, model, idx, reverse=False)

Converts between NCHW <-> NHWC layouts for tensor t by inserting a transpose. If reverse=False, t is assumed NCHW and we insert transpose to convert NCHW -> NHWC If reverse=True, t is assumed NHWC and we insert transpose to convert NHWC -> NCHW.

qonnx.util.onnx.valueinfo_to_tensor(vi)

Creates an all-zeroes numpy tensor from a ValueInfoProto.

qonnx.util.prune_channels

qonnx.util.prune_channels.main()

qonnx.util.prune_channels.prune_channels(input_filename, prunespec_filename, *, lossy=True, output_filename='')

Prune channels from specified tensors and their dependencies from a model. The model must have already been cleaned up by qonnx-cleanup, including the –extract-conv-bias=True –preserve-qnt-ops=False options.

Parameters:

• input_filename – Filename for the input ONNX model

• prunespec_filename – Filename for the pruning specification, formatted as a Python dict formatted as {tensor_name : {axis : {channels}}}. See test_pruning.py for examples.

• lossy – Whether to perform lossy pruning, see the PruneChannels transformation for description.

• output_filename – If specified, write the resulting pruned model to this filename. Otherwise, the input_filename will be used with a _pruned suffix.

qonnx.util.random_reseed

qonnx.util.random_reseed.reseed(newseed)

qonnx.util.range_analysis

qonnx.util.range_analysis.calc_conv_range(node, model, range_dict)

qonnx.util.range_analysis.calc_convtranspose_range(node, model, range_dict)

qonnx.util.range_analysis.calc_gemm_range(node, model, range_dict)

qonnx.util.range_analysis.calc_matmul_range(node, model, range_dict)

qonnx.util.range_analysis.calc_monotonic_range(node, model, range_dict, i_channel_axis=1)

qonnx.util.range_analysis.calc_range_outdtype(node, model, range_dict)

qonnx.util.range_analysis.calculate_matvec_accumulator_extremum(matrix: ndarray, vec_min, vec_max)

Calculate the minimum and maximum possible result (accumulator) values for a dot product A*x, given matrix A of dims (MH, MW), and vector (MW) with range (vec_min, vec_max). vec_min and vec_max are either scalars, or 1D arrays of length MW. Returns (acc_min, acc_max) where acc_min and acc_max are 1D arrays of length MH.

qonnx.util.range_analysis.get_minmax_prototype_tensors(irange, ishp, inp_vi, i_channel_axis=1)

qonnx.util.range_analysis.is_dyn_input(x, model)

qonnx.util.range_analysis.main()

qonnx.util.range_analysis.range_analysis(model_filename_or_wrapper, *, irange='', key_filter: str = '', report_mode: functools.partial(<function _use_class at 0x7f7b98c97040>, <class 'clize.parser.use_mixin.<locals>._PosWithMixin'>, <class 'clize.parser.use_mixin.<locals>._VarargsWithMixin'>, <class 'clize.parser.use_mixin.<locals>._NamedWithMixin'>, <function unimplemented_parameter at 0x7f7b98d0bb80>, {'case_sensitive': None, 'list_name': 'list', 'values': [('range', ['range', ]'Report ranges'), ('stuck_channel', ['stuck_channel', ]'Report stuck channels'), ('zerostuck_channel', ['zerostuck_channel', ]'Report 0-stuck channels')]}) = 'stuck_channel', prettyprint=False, do_cleanup=False)

qonnx.util.range_analysis.simplify_range(range)

Where possible, simplify a range that is expressed as channelwise ranges back to a scalar range if all channels’ ranges were equal.

qonnx.util.test

qonnx.util.test.download_model(test_model: functools.partial(<function _use_class at 0x7f7b98c97040>, <class 'clize.parser.use_mixin.<locals>._PosWithMixin'>, <class 'clize.parser.use_mixin.<locals>._VarargsWithMixin'>, <class 'clize.parser.use_mixin.<locals>._NamedWithMixin'>, <function unimplemented_parameter at 0x7f7b98d0bb80>, {'case_sensitive': None, 'list_name': 'list', 'values': [('FINN-CNV_W2A2', ['FINN-CNV_W2A2', ]'2-bit VGG-10-like CNN on CIFAR-10'), ('FINN-CNV_W1A2', ['FINN-CNV_W1A2', ]'1/2-bit VGG-10-like CNN on CIFAR-10'), ('FINN-CNV_W1A1', ['FINN-CNV_W1A1', ]'1-bit VGG-10-like CNN on CIFAR-10'), ('FINN-TFC_W1A1', ['FINN-TFC_W1A1', ]'1-bit tiny MLP on MNIST'), ('FINN-TFC_W1A2', ['FINN-TFC_W1A2', ]'1/2-bit tiny MLP on MNIST'), ('FINN-TFC_W2A2', ['FINN-TFC_W2A2', ]'2-bit tiny MLP on MNIST'), ('RadioML_VGG10', ['RadioML_VGG10', ]'8-bit VGG-10-like CNN on RadioML 2018'), ('Conv_bias_example', ['Conv_bias_example', ]''), ('MobileNetv1-w4a4', ['MobileNetv1-w4a4', ]'4-bit MobileNet-v1 on ImageNet')]}), *, dl_dir='/tmp', do_cleanup=False, return_modelwrapper=False)

qonnx.util.test.get_golden_in_and_output(test_model)

qonnx.util.test.qonnx_download_model()

qonnx.util.to_channels_last

qonnx.util.to_channels_last.main()

qonnx.util.to_channels_last.to_channels_last(in_file, *, make_input_channels_last=False, out_file=None)

Execute a set of graph transformations to convert an ONNX file to the channels last data format. The input file have been previously cleaned by the cleanup transformation or commandline tool.

Parameters:

• in_file – Filename for the input ONNX model

• make_input_channels_last – Sets if the input of the model should also be converted to the channels last data layout (True) or if a transpose node should be left at the beginning of the graph (False). Defaults to False.

• out_file – If set, filename for the output ONNX model. Set to in_file with _chan_last suffix otherwise.

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.get_finn_root()

Return the root directory that FINN is cloned into.

finn.util.basic.get_memutil_alternatives(req_mem_spec, mem_primitives={'BRAM18_18x1024': (18, 1024), 'BRAM18_36x512': (36, 512), 'BRAM18_9x2048': (9, 2048), 'LUTRAM': (1, 64), 'URAM_18x16384': (18, 16384), 'URAM_36x8192': (36, 8192), 'URAM_72x4096': (72, 4096), 'URAM_9x32768': (9, 32768)}, sort_min_waste=True)

Computes how many instances of a memory primitive are necessary to implement a desired memory size, where req_mem_spec is the desired size and the primitive_spec is the primitve size. The sizes are expressed as tuples of (mem_width, mem_depth). Returns a list of tuples of the form (primitive_name, (primitive_count, efficiency, waste)) where efficiency in range [0,1] indicates how much of the total capacity is utilized, and waste indicates how many bits of storage are wasted. If sort_min_waste is True, the list is sorted by increasing waste.

finn.util.basic.get_remote_vivado()

Return the address of the remote Vivado synthesis server as set by the, REMOTE_VIVADO environment variable, otherwise return None

finn.util.basic.get_rtlsim_trace_depth()

Return the trace depth for rtlsim via PyVerilator. Controllable via the RTLSIM_TRACE_DEPTH environment variable. If the env.var. is undefined, the default value of 1 is returned. A trace depth of 1 will only show top-level signals and yield smaller .vcd files.

The following depth values are of interest for whole-network stitched IP rtlsim: - level 1 shows top-level input/output streams - level 2 shows per-layer input/output streams - level 3 shows per full-layer I/O including FIFO count signals

finn.util.basic.launch_process_helper(args, proc_env=None, cwd=None)

Helper function to launch a process in a way that facilitates logging stdout/stderr with Python loggers. Returns (cmd_out, cmd_err).

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

Creates a 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.memutil(req_mem_spec, primitive_spec)

Computes how many instances of a memory primitive are necessary to implemented a desired memory size, where req_mem_spec is the desired size and the primitive_spec is the primitve size. The sizes are expressed as tuples of (mem_width, mem_depth). Returns (primitive_count, efficiency, waste) where efficiency in range [0,1] indicates how much of the total capacity is utilized, and waste indicates how many bits of storage are wasted.

finn.util.basic.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.basic.which(program)

Python equivalent of the shell cmd ‘which’.

finn.util.create

finn.util.create.hls_mlp_maker(layer_spec)

Create an MLP of given specification using HLSCustomOp instances.

finn.util.create.hls_random_mlp_maker(layer_spec)

Create an MLP of given specification using HLSCustomOp instances. Generate random weights/thresholds of appropriate size.

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, reverse_endian=False, fast_mode=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.

If fast_mode is enabled, will attempt to use shortcuts to save on runtime for certain cases: * 8-bit ndarray -> 8-bit * ndarray -> 1-bit and total bits % 8 == 0 This mode is currently not well-tested, use at your own risk!

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, prefix='0x')

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, fast_mode=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.

If fast_mode is enabled, will attempt to use shortcuts (casting) to save on runtime for certain cases. This mode is currently not well-tested, use at your own risk.

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. If path is not None it will also be saved as a npy file.

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

finn.util.fpgadataflow.is_fpgadataflow_node(node)

Returns True if given node is fpgadataflow node. Otherwise False.

finn.util.fpgadataflow.is_hls_node(node)

Returns True if given node is hls node. Otherwise False.

finn.util.fpgadataflow.is_rtl_node(node)

Returns True if given node is rtl node. Otherwise False.

finn.util.fpgadataflow.is_versal(fpgapart)

Returns whether board is part of the Versal family

finn.util.hls

class finn.util.hls.CallHLS

Bases: object

Call vitis_hls to run HLS build tcl scripts.

append_tcl(tcl_script)

Sets the tcl script to be executed.

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.imagenet

finn.util.imagenet.get_val_images(n_images=100, interleave_classes=False)

Returns generator over (path_to_jpeg, imagenet_class_id) for the first n_images in the ILSVRC2012 validation dataset. The IMAGENET_VAL_PATH environment variable must point to the validation dataset folder, containing 1000 folders (one for each ImageNet-1K class), in turn each containing 50 test images.

interleave_classes controls the ordering of the picked images. If False (default), consecutive images will have the same class until that class has no more images. Otherwise, consecutive images will be from classes 0, 1, 2… and back to class 0 after the first 1000 images.

For more information on how to prepare the ILSVRC2012 validation dataset, please see: https://github.com/Xilinx/brevitas/blob/dev/brevitas_examples/imagenet_classification/README.md

finn.util.imagenet.load_resize_crop(img_path, layout=['N', 'C', 'H', 'W'], dtype=<class 'numpy.float32'>)

Load, resize and center crop given image for standard ImageNet preprocessing, return a numpy array.

finn.util.imagenet.measure_topk(n_images, fxn_pre, fxn_exec, fxn_post, verbose=True, k=5)

Do top-k accuracy measurement on ILSVRC2012 with given functions.

finn.util.platforms

class finn.util.platforms.Alveo_NxU200_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.Alveo_NxU250_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.Alveo_NxU280_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.Alveo_NxU50_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.Alveo_NxU55C_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.Platform(nslr=1, ndevices=1, sll_count=[], hbm_slr=-1, ddr_slr=[0], eth_slr=0, eth_gbps=0, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: object

property compute_connection_cost

property compute_connection_resource

abstract property compute_resources

property guide_resources

map_device_to_slr(idx)

Given a global SLR index, return device id and local slr index

property resource_count_dict

class finn.util.platforms.ZU28DR_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.ZU3EG_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.ZU7EV_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.ZU9EG_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

class finn.util.platforms.Zynq7020_Platform(ndevices=1, limits=array([0.7, 0.5, 0.8, 0.8, 0.8]), avg_constraints=[((2, 3, 4), 0.7)])

Bases: Platform

property compute_resources

finn.util.pytorch

class finn.util.pytorch.Normalize(mean, std, channels)

Bases: Module

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool

class finn.util.pytorch.NormalizePreProc(mean, std, channels)

Bases: Module

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool

class finn.util.pytorch.ToTensor

Bases: Module

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool

finn.util.pyverilator

finn.util.pyverilator.make_single_source_file(filtered_verilog_files, target_file)

Dump all Verilog code used by stitched IP into a single file. This is because large models with many files require a verilator command line too long for bash on most systems

finn.util.pyverilator.prepare_stitched_ip_for_verilator(model)

Prepare sources from given stitched IP for verilator simulation, including generating a single source file and replacing certain Vivado infrastructure headers with Verilator-compatible ones

finn.util.pyverilator.pyverilate_stitched_ip(model, read_internal_signals=True, disable_common_warnings=True, extra_verilator_args=[])

Given a model with stitched IP, return a PyVerilator sim object. Trace depth is also controllable, see get_rtlsim_trace_depth()

:param read_internal_signals If set, it will be possible to examine the

internal (not only port) signals of the Verilog module, but this may slow down compilation and emulation.

:param disable_common_warnings If set, disable the set of warnings that

Vivado-HLS-generated Verilog typically triggers in Verilator (which can be very verbose otherwise)

finn.util.pyverilator.verilator_fifosim(model, n_inputs, max_iters=100000000)

Create a Verilator model of stitched IP and use a simple C++ driver to drive the input stream. Useful for FIFO sizing, latency and throughput measurement.

finn.util.test

finn.util.test.crop_center(size, img)

Crop central size*size window out of a PIL image.

finn.util.test.execute_parent(parent_path, child_path, input_tensor_npy, return_full_ctx=False)

Execute parent model containing a single StreamingDataflowPartition by replacing it with the model at child_path and return result.

finn.util.test.get_build_env(board, target_clk_ns)

Get board-related build environment for testing. - board = any from pynq_part_map or alveo_part_map

finn.util.test.get_example_input(topology)

Get example numpy input tensor for given topology.

finn.util.test.get_test_model(netname, wbits, abits, pretrained)

Returns the model specified by input arguments from the Brevitas BNN-PYNQ test networks. Pretrained weights loaded if pretrained is True.

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

get_test_model with pretrained=True

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

get_test_model with pretrained=False

finn.util.test.get_topk(vec, k)

Return indices of the top-k values in given array vec (treated as 1D).

finn.util.test.get_trained_network_and_ishape(topology, wbits, abits)

Return (trained_model, shape) for given BNN-PYNQ test config.

finn.util.test.load_test_checkpoint_or_skip(filename)

Try to load given .onnx and return ModelWrapper, else skip current test.

finn.util.test.resize_smaller_side(target_pixels, img)

Resizes smallest side of image to target pixels and resizes larger side with same ratio. Expects a PIL image.

finn.util.test.soft_verify_topk(invec, idxvec, k)

Check that the topK indices provided actually point to the topK largest values in the input vector

finn.util.vcd

finn.util.vcd.get_all_fifo_count_max(vcd_file, fifo_count_signals=None)

Return a list of max FIFO counts. If fifo_count_signals is None, all FIFO count signals will be returned, otherwise treated as a list of signal names to return the stats for.

finn.util.vcd.get_all_stream_if_stats(vcd_file, stream_ifs=None, sort_by="{'V': 1, 'R': 0}", num_workers=None)

Return a list of streaming interface stats, sorted by the percentage for the given sort_by key. If stream_ifs is None, all streaming interface stats will be returned, otherwise treated as a list of interface names to return the stats for. By default the number of parallel workers from the environment variable NUM_DEFAULT_WORKERS will be used. This behavior can be changed on a per call basis by supplying the optional parameter: num_workers

finn.util.vcd.get_fifo_count_max(vcd_file, fifo_count_signal)

Return the maximum value of the given FIFO count signal in vcd trace.

finn.util.vcd.get_stream_if_stats(vcd_file, if_base_name)

Return statistics for given streaming interface in vcd trace in the following dict format:

<stream_state>: (<num_samples>, <fraction_of_time>),

where <stream_state> is the combination of (V)alid/(R)eady values, <num_samples> is the approximate number of rising clock edges spent in <state>, and <fraction_of_time> is the fraction of <num_samples> to total amount of time recorded by the trace.

Example: { “{‘V’: 0, ‘R’: 0}”: (5, 0.0006060606060606061), “{‘V’: 1, ‘R’: 0}”: (0, 0.0), “{‘V’: 0, ‘R’: 1}”: (7605, 0.9218181818181819), “{‘V’: 1, ‘R’: 1}”: (640, 0.07757575757575758) } Here we can see the stream was transmitting values 7.7% of the time, and 9.2% of the time there was no incoming data (valid 0, ready 1)

finn.util.vcd.list_fifo_count_signals(vcd_file)

Return a list of FIFO count signal names from given vcd trace.

finn.util.vcd.list_stream_if(vcd_file)

Return a list of stream interface names from given vcd trace.

finn.util.visualization

finn.util.visualization.showInNetron(model_filename: str, localhost_url: str | None = None, port: int | None = None)

Shows a ONNX model file in the Jupyter Notebook using Netron.

Parameters:

• model_filename (str) – The path to the ONNX model file.

• localhost_url (str, optional) – The IP address used by the Jupyter IFrame to show the model. Defaults to localhost.

• port (int, optional) – The port number used by Netron and the Jupyter IFrame to show the ONNX model. Defaults to 8081.

Returns:

The IFrame displaying the ONNX model.

Return type:

IPython.lib.display.IFrame

finn.util.visualization.showSrc(what)

finn.util.vivado

finn.util.vivado.out_of_context_synth(verilog_dir, top_name, fpga_part='xczu3eg-sbva484-1-e', clk_name='ap_clk_0', clk_period_ns=5.0)

Run out-of-context Vivado synthesis, return resources and slack.