Core

Modules

qonnx.core.data_layout

qonnx.core.data_layout.get_channels_first_layout_for_ndims(ndims)

qonnx.core.data_layout.get_channels_last_layout_for_ndims(ndims)

qonnx.core.data_layout.is_channels_last(layout)

qonnx.core.datatype

class qonnx.core.datatype.ArbPrecFloatType(exponent_bits: int, mantissa_bits: int, exponent_bias: int | float | None = None)

Bases: BaseDataType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

bitwidth() → int

Returns the number of bits required for this DataType.

exponent_bias() → int | float

exponent_bits() → int

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

get_num_possible_values() → int

Returns the number of possible values this DataType can take. Only implemented for integer types for now.

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

mantissa_bits() → int

max() → float

Returns the largest possible value allowed by this DataType.

min() → float

Returns the smallest possible value allowed by this DataType.

signed() → bool

Returns whether this DataType can represent negative numbers.

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.BaseDataType

Bases: ABC

Base class for QONNX data types.

abstract allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

abstract bitwidth() → int

Returns the number of bits required for this DataType.

abstract get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

abstract get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

abstract get_num_possible_values() → int

Returns the number of possible values this DataType can take. Only implemented for integer types for now.

abstract is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

abstract is_integer() → bool

Returns whether this DataType represents integer values only.

abstract max() → int | float

Returns the largest possible value allowed by this DataType.

abstract min() → int | float

Returns the smallest possible value allowed by this DataType.

property name: str

signed() → bool

Returns whether this DataType can represent negative numbers.

abstract to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.BipolarType

Bases: BaseDataType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

bitwidth() → int

Returns the number of bits required for this DataType.

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

get_num_possible_values() → int

Returns the number of possible values this DataType can take. Only implemented for integer types for now.

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

max() → int

Returns the largest possible value allowed by this DataType.

min() → int

Returns the smallest possible value allowed by this DataType.

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.DataType(value)

Bases: Enum

Enum class that contains QONNX data types to set the quantization annotation. ONNX does not support data types smaller than 8-bit integers, whereas in QONNX we are interested in smaller integers down to ternary and bipolar.

static get_accumulator_dt_cands() → list[str]

static get_smallest_possible(value: int | float) → BaseDataType

Returns smallest (fewest bits) possible DataType that can represent value. Prefers unsigned integers where possible.

class qonnx.core.datatype.DataTypeMeta(cls, bases, classdict, **kwds)

Bases: EnumMeta

class qonnx.core.datatype.FixedPointType(bitwidth: int, intwidth: int)

Bases: IntType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

frac_bits() → int

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

int_bits() → int

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

max() → float

Returns the largest possible value allowed by this DataType.

min() → float

Returns the smallest possible value allowed by this DataType.

scale_factor() → float

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.Float16Type

Bases: BaseDataType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

bitwidth() → int

Returns the number of bits required for this DataType.

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

get_num_possible_values() → int

Returns the number of possible values this DataType can take. Only implemented for integer types for now.

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

max() → float

Returns the largest possible value allowed by this DataType.

min() → float

Returns the smallest possible value allowed by this DataType.

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.FloatType

Bases: BaseDataType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

bitwidth() → int

Returns the number of bits required for this DataType.

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

get_num_possible_values() → int

Returns the number of possible values this DataType can take. Only implemented for integer types for now.

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

max() → float

Returns the largest possible value allowed by this DataType.

min() → float

Returns the smallest possible value allowed by this DataType.

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.IntType(bitwidth: int, signed: bool)

Bases: BaseDataType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

bitwidth() → int

Returns the number of bits required for this DataType.

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

get_num_possible_values() → int

Returns the number of possible values this DataType can take. Only implemented for integer types for now.

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

max() → int | float

Returns the largest possible value allowed by this DataType.

min() → int | float

Returns the smallest possible value allowed by this DataType.

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.ScaledIntType(bitwidth: int)

Bases: IntType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

max() → int

Returns the largest possible value allowed by this DataType.

min() → int

Returns the smallest possible value allowed by this DataType.

signed() → bool

Returns whether this DataType can represent negative numbers.

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

class qonnx.core.datatype.TernaryType

Bases: BaseDataType

allowed(value: int | float | ndarray) → bool | ndarray

Check whether given value is allowed for this DataType.

• value (float32): value to be checked

• returns: bool if input is scalar, ndarray of bools if input is ndarray

bitwidth() → int

Returns the number of bits required for this DataType.

get_canonical_name() → str

Return a canonical string representation of this QONNX DataType.

get_hls_datatype_str() → str

Returns the corresponding Vivado HLS datatype name.

get_num_possible_values() → int

Returns the number of possible values this DataType can take. Only implemented for integer types for now.

is_fixed_point() → bool

Returns whether this DataType represent fixed-point values only.

is_integer() → bool

Returns whether this DataType represents integer values only.

max() → int

Returns the largest possible value allowed by this DataType.

min() → int

Returns the smallest possible value allowed by this DataType.

to_numpy_dt() → dtype

Return an appropriate numpy datatype that can represent this QONNX DataType.

qonnx.core.datatype.resolve_datatype(name: str) → BaseDataType

qonnx.core.execute_custom_node

qonnx.core.execute_custom_node.execute_custom_node(node, context, graph, onnx_opset_version)

Call custom implementation to execute a single custom node. Input/output provided via context.

qonnx.core.modelwrapper

class qonnx.core.modelwrapper.ModelWrapper(onnx_model_proto: str | bytes | ModelProto, make_deepcopy: bool = False, fix_float64: bool = False, fix_missing_initializer_valueinfo: bool = True)

Bases: object

A wrapper around ONNX ModelProto that exposes some useful utility functions for graph manipulation and exploration.

T = ~T

analysis(analysis_fxn: Callable[['ModelWrapper', bool], T] | Callable[['ModelWrapper'], T], apply_to_subgraphs: bool = False) → T

Runs given anaylsis_fxn on this model and return resulting dict.

check_all_tensor_shapes_specified(fix_missing_init_shape: bool = False) → bool

Checks whether all tensors have a specified shape (ValueInfo). The ONNX standard allows for intermediate activations to have no associated ValueInfo, but QONNX expects this. If fix_missing_init_shape is specified, it will add a ValueInfoProto for initializers that are missing theirs.

cleanup() → ModelWrapper

Run cleanup transformations on the model.

del_initializer(initializer_name: str) → None

Deletes an initializer from the model.

find_consumer(tensor_name: str) → NodeProto | None

Finds and returns the node that consumes the tensor with given name. If there are multiple consumers, only the first one is returned. If there are no consumers, returns None.

find_consumers(tensor_name: str) → list[NodeProto]

Finds and returns a list of the nodes that consume tensor with given name.

find_direct_predecessors(node: NodeProto) → list[NodeProto] | None

Finds and returns a list of the nodes that are predecessors of given node.

find_direct_successors(node: NodeProto) → list[NodeProto] | None

Finds and returns a list of the nodes that are successors of given node.

find_producer(tensor_name: str) → NodeProto | None

Finds and returns the node that produces the tensor with given name.

find_upstream(tensor_name: str, finder_fxn: Callable[[NodeProto], bool], keep_if_not_found: bool = False) → list[NodeProto] | None

Follow the producer chain upstream, calling finder_fxn on each upstream node until it returns True or there are no nodes left. Returns the list of nodes visited, or None if finder_fxn did not return True. If keep_if_not_found is specified, returns the list of nodes visited, even if finder_fxn never returned True, i.e., if the search terminated at an input or initializer.

get_all_tensor_names() → list[str]

Returns a list of all (input, output and value_info) tensor names in the graph.

get_customop_wrapper(node, fallback_customop_version=1)

Return CustomOp instance for given node, respecting the imported opset version in the model protobuf. If the node’s domain is not found in the model’s opset imports, fallback_customop_version will be used.

get_finn_nodes() → list[NodeProto]

Returns a list of nodes where domain == ‘qonnx.*’.

get_first_global_in() → str

Return the name of the first global input tensor.

get_first_global_out() → str

Return the name of the first global output tensor.

get_initializer(tensor_name: str, return_dtype: bool = False) → ndarray | tuple[ndarray, int] | tuple[None, None] | None

Gets the initializer value for tensor with given name, if any. ret_dtype can be set to True to retrieve the TensorProto.DataType of the initializer by returning it as a second element of a tuple.

get_metadata_prop(key: str) → str | None

Returns the value associated with metadata_prop with given key, or None otherwise.

get_node_from_name(node_name: str) → NodeProto | None

Returns the node with the specified name, or None if not found.

get_node_index(node: NodeProto) → int | None

Returns current index of given node, or None if not found.

get_nodes_by_op_type(op_type: str) → list[NodeProto]

Returns a list of nodes with specified op_type.

get_non_finn_nodes() → list[NodeProto]

Returns a list of nodes where domain != ‘qonnx.*’.

get_opset_imports()

Returns a list of imported opsets as a {domain, version} dictionary.

get_tensor_datatype(tensor_name: str) → BaseDataType

Returns the QONNX DataType of tensor with given name.

get_tensor_fanout(tensor_name: str) → int

Returns the number of nodes for which the tensor with given name is as input.

get_tensor_layout(tensor_name: str) → list[str] | None

Returns the data layout annotation of tensor with given name. The data layout is expressed as a list of strings with as many elements as the number of dimensions in the tensor shape. Each string annotates what is contained in that dimension. If there is no data layout annotation, None will be returned. Examples of data layout annotations: [“N”, “C”] is tensor[batch][channel] [“N”, “C”, “H”, “W”] is tensor[batch][channel][height][width] [“N”, “H”, “W”, “C”] is tensor[batch][height][width][channel]

get_tensor_shape(tensor_name: str, fix_missing_init_shape: bool = False) → list[int] | None

Returns the shape of tensor with given name, if it has ValueInfoProto. If fix_missing_init_shape is specified, it will add a ValueInfoProto for initializers that are missing theirs.

get_tensor_sparsity(tensor_name: str) → dict[str, Any] | None

Returns the sparsity of a given tensor as dictionary.

get_tensor_valueinfo(tensor_name: str) → ValueInfoProto | None

Returns ValueInfoProto of tensor with given name, if it has one.

property graph: GraphProto

Returns the graph of the model.

is_fork_node(node: NodeProto) → bool

Checks if the given node is a fork, that is, the node has multiple direct successors

is_join_node(node: NodeProto) → bool

Checks if the given node is a join, that is, the node has multiple direct predecessors

make_empty_exec_context() → dict[str, ndarray | None]

Creates an empty execution context for this model.

The execution context is a dictionary of all tensors used for the inference computation. Any initializer values will be taken into account, all other tensors will be zero.

make_new_valueinfo_name() → str

Returns a name that can be used for a new value_info.

make_subgraph_modelwrapper(subgraph: GraphProto) → ModelWrapper

property model: ModelProto

Returns the model.

rename_tensor(old_name: str, new_name: str) → None

Renames a tensor from old_name to new_name.

save(filename: str | Path) → None

Saves the wrapper ONNX ModelProto into a file with given name.

set_initializer(tensor_name: str, tensor_value: ndarray) → None

Sets the initializer value for tensor with given name.

set_metadata_prop(key: str, value: str) → None

Sets metadata property with given key to the given value.

set_opset_import(domain, version)

Sets the opset version for a given domain in the model’s opset imports. If the domain already exists, its version will be updated. If not, a new opset import will be added.

Args:

domain (str): The domain name (e.g. “qonnx.custom_op.general”) version (int): The opset version number

set_tensor_datatype(tensor_name: str, datatype: BaseDataType | None) → None

Sets the QONNX DataType of tensor with given name.

set_tensor_layout(tensor_name: str, data_layout: list[str]) → None

Sets the data layout annotation of tensor with given name. See get_tensor_layout for examples.

set_tensor_shape(tensor_name: str, tensor_shape: Sequence[int], dtype: int | None = None) → None

Assigns shape in ValueInfoProto for tensor with given name. If override_dtype is None, it will try to preserve the existing datatype, otherwise defaults to single-precision float.

set_tensor_sparsity(tensor_name: str, sparsity_dict: dict[str, Any]) → None

Sets the sparsity annotation of a tensor with given name.

temporary_fix_oldstyle_domain() → None

transform(transformation: Transformation, make_deepcopy: bool = True, cleanup: bool = True, apply_to_subgraphs: bool = False, use_preorder_traversal: bool = True) → ModelWrapper

Applies given Transformation repeatedly until no more changes can be made and returns a transformed ModelWrapper instance.

• make_deepcopy : operates on a new (deep)copy of model.

• cleanup : execute cleanup transformations before returning

• apply_to_subgraphs : if True, transformation is applied to all subgraphs of the model

transform_subgraphs(transformation: Transformation, make_deepcopy: bool = True, cleanup: bool = True, apply_to_subgraphs: bool = False, use_preorder_traversal: bool = True) → None

Applies given Transformation to all subgraphs of this ModelWrapper instance.

• make_deepcopy : operates on a new (deep)copy of model.

• cleanup : execute cleanup transformations before returning

• apply_to_subgraphs : if True, transformation is applied to all subgraphs of the model

• use_preorder_traversal : if True, uses preorder traversal for subgraph transformation, otherwise postorder traversal is used.

qonnx.core.onnx_exec

qonnx.core.onnx_exec.compare_execution(model_a, model_b, input_dict, compare_fxn=<function <lambda>>)

Executes two ONNX models and compare their outputs using given function.

compare_fxn should take in two tensors and return a Boolean

qonnx.core.onnx_exec.execute_node(node, context, graph, opset_version, return_full_exec_context=False)

Executes a single node by using onnxruntime or with a custom function.

Input/output provided via context.

qonnx.core.onnx_exec.execute_onnx(model, input_dict, return_full_exec_context=False, start_node=None, end_node=None)

Executes given ONNX ModelWrapper with given named inputs.

If return_full_exec_context is False, a dict of named outputs is returned as indicated by the model.graph.output.

If return return_full_exec_context is True, the full set of tensors used by the execution (including inputs, weights, activations and final outputs) will be returned as a dict.

When start_node and end_node are set to None, the whole graph is executed. If they are set to particular ONNX nodes, only the subgraph between (and including) those nodes is executed.

qonnx.core.onnx_exec.execute_onnx_and_make_model(model, input_dict)

Executes given ONNX ModelWrapper with given named inputs and return a new ModelWrapper where an initializer is provided for each tensor as taken from the execution. This new model is useful for debugging, since it contains all the intermediate activation values.

finn.core.onnx_exec

finn.core.rtlsim_exec

finn.core.throughput_test