API reference

onnx2akida.convert(model, input_shape=None, input_dtype='uint8', enable_experimental=True, device=None, enable_hwpr=False, sram_size=None, minimal_memory=False, initial_num_nodes=36)[source]

Check ONNX model compatibility with Akida and convert the model into a HybridModel.

Parameters:

model (onnx.ModelProto) – The ONNX model.
input_shape (Iterable, optional) – An iterable specifying the new model input shape excluding batch dimension. Defaults to None.
input_dtype (np.dtype or str, optional) – expected model input format. If given as a string, should follow numpy string type requirements. Defaults to ‘uint8’.
enable_experimental (bool, optional) – Enable or Disable experimental patterns context. Defaults to True.
device (akida.Device, optional) – the Akida device to map the Akida sub models. Defaults to None.
enable_hwpr (bool, optional) – if True, the device is computed assuming partial reconfiguration. Used when device is None. Defaults to False.
sram_size (akida.NP.SramSize, optional) – Size of shared SRAM available inside the mesh. Ignored when minimal_memory is True. Used when device is None. Defaults to None.
minimal_memory (bool, optional) – if True, computes and sets the minimal required inputs and weights memory for the device. Used when device is None. Defaults to False.
initial_num_nodes (int, optional) – The initial number of nodes that will be used to compute the base device. Defaults to 36.

Returns:

converted model and object containing information about model compatibility.

Return type:

HybridModel, ModelCompatibilityInfo

onnx2akida.print_report(compatibility_info, hybrid_model)[source]

Prints a report of the model compatibility with Akida.

Parameters:

compatibility_info (ModelCompatibilityInfo) – The compatibility information.
hybrid_model (HybridModel) – The converted hybrid model.

Compatibility

class onnx2akida.compatibility_info.ModelCompatibilityInfo(model)[source]

Tracks Akida compatibility of an ONNX model.

Parameters:: model (onnx.ModelProto) – The ONNX model to analyze.

Attributes:

`compatibility_percentage`	Returns the model compatibility percentage with the Akida accelerator.
`incompatibilities`	Returns a list of incompatibilities with reasons and other information.
`incompatible_nodes`	Returns a list of all incompatible nodes.
`incompatible_op_types`	Returns a list of unique op types of incompatible nodes.

Methods:

save_tagged_model(save_path)

Saves a model with node op_types tagged as 'AK<>' for compatible nodes and 'CPU<>' for incompatible nodes.

property compatibility_percentage

Returns the model compatibility percentage with the Akida accelerator.

Returns:: percentage of compatible nodes in the model.
Return type:: float

property incompatibilities

Returns a list of incompatibilities with reasons and other information.

Example

[
    {
        "node_sequence": [
            {"name": "cos_node", "op_type": "Cos"},
            ...
        ],
        "stage": "Quantization",
        "faulty_node": "cos_node",
        "reason": "Unsupported op."
    },
    ...
]

Returns:: list of incompatibilities with reasons and other information.
Return type:: list

property incompatible_nodes

Returns a list of all incompatible nodes.

Returns:: list of nodes from all incompatible sequences.
Return type:: list

property incompatible_op_types

Returns a list of unique op types of incompatible nodes.

Returns:: list of unique op types of incompatible nodes.
Return type:: list

save_tagged_model(save_path)[source]

Saves a model with node op_types tagged as ‘AK<>’ for compatible nodes and ‘CPU<>’ for incompatible nodes.

Parameters:: save_path (str) – File path to save the tagged model.

HybridModel

class onnx2akida.hybrid_model.HybridModel(models=None, name='HybridModel')[source]

A container for combining and managing multiple Akida and ONNX models as a single one.

HybridModel allows to sequentially add Akida or ONNX models, connect their inputs and outputs, and manage their relationships. It provides a unified interface to access layers, input/output shapes and to retrieve or connect sub-models by layer name.

The class ensures model integrity by checking for unique layer names and valid inbound connections.

Parameters:

models (list, optional) – list of Akida or ONNX models to initialize the hybrid model with. Defaults to None.
name (str, optional) – name of the hybrid model. Defaults to “HybridModel”.

Attributes:

`akida_models`	Returns a list of Akida models within the hybrid model.
`input_shape`	Returns the hybrid model input shape.
`layers`	Returns the hybrid model layers.
`output_shape`	Returns the hybrid model output shape.

Methods:

`compute_data_movement`()	Computes the data movement between CPU and Akida for models in the HybridModel.
`generate_inference_model`([dirpath])	Generates a unified ONNX inference model from all sub-models in the HybridModel.
`get_layer`(name)	Retrieves a layer from the model by its name.
`map`(device[, mode])	Map (if possible) all akida models to a given device.

property akida_models

Returns a list of Akida models within the hybrid model.

Returns:: the akida models within the hybrid model.
Return type:: list

compute_data_movement()[source]

Computes the data movement between CPU and Akida for models in the HybridModel.

For each Akida model sequence, this method calculates: - The amount of data transferred from CPU to Akida. - The amount of data transferred from Akida to CPU.

The size is computed as the product of the input or output dimensions.

Returns:

a list of dictionaries, each containing :

”layer”: the Akida layer involved in the data transfer.
”type”: a string indicating the direction (“CPU to Akida” or “Akida to CPU”).
”size”: The size in bytes of the data movement.

Return type:

list of dict

generate_inference_model(dirpath='.')[source]

Generates a unified ONNX inference model from all sub-models in the HybridModel.

This method combines all Akida and ONNX sub-models added to the HybridModel into a single ONNX model suitable for inference. It handles the conversion of Akida models to ONNX and connects sub-models according to their inbounds.

The resulting model can be used for inferences based on AkidaExecutionProvider:

>>> inference_model = model.generate_inference_model()
>>> sess = onnxruntime.InferenceSession(inference_model.SerializeToString(),
...                                     providers=["AkidaExecutionProvider"])
>>> outputs = sess.run(None, feeds)

Parameters:: dirpath (str, optional) – directory path where Akida programs will be saved. Defaults to the current directory.
Returns:: the combined ONNX model ready for inference.
Return type:: onnx.ModelProto

get_layer(name)[source]

Retrieves a layer from the model by its name.

Parameters:: name (str) – the name of the layer to retrieve.
Returns:: the layer.
Return type:: Layer

property input_shape

Returns the hybrid model input shape.

Returns:: the model input shape.
Return type:: list

property layers

Returns the hybrid model layers.

Returns:: the model layers.
Return type:: list

map(device, mode=MapMode.AllNps)[source]

Map (if possible) all akida models to a given device.

Parameters:

device (akida.Device) – An Akida device.
mode (akida.MapMode, optional) – The mapping mode. Defaults to AllNps.

property output_shape

Returns the hybrid model output shape.

Returns:: the model output shape.
Return type:: list

Pipeline

onnx2akida.pipeline.quantize(model, input_dtype='uint8', input_shape=None)[source]

Quantizes an ONNX model, handling partial quantization and quantization errors as needed.

This function attempts to quantize the entire model in one pass. If quantization fails due to unsupported or unquantizable nodes, it analyzes the error, splits the model at the problematic nodes, and recursively quantizes each sub-model. The quantized sub-models are then merged back into the original model graph. This approach ensures that all quantizable parts of the model are quantized, while gracefully handling sections that cannot be quantized.

Parameters:

model (Any) – the ONNX model to quantize.
input_dtype (np.dtype or str, optional) – expected model input format. If given as a string, should follow numpy string type requirements. Defaults to ‘uint8’.
input_shape (Iterable, optional) – an iterable specifying the new model input shape. If not specified, keeps the shape. Defaults to None.

Returns:

the quantized model and the incompatibilites (optional).

Return type:

Any, ModelCompatibilityInfo

onnx2akida.pipeline.convert_to_hybrid(qmodel, device=None, *, enable_hwpr=False, sram_size=None, minimal_memory=False, initial_num_nodes=36)[source]

Converts a quantized ONNX model into a HybridModel containing Akida and ONNX sub-models.

This function splits the input quantized model into convertible sequences, attempts to convert and map each fully quantized sequence to an Akida model and adds it to the HybridModel. Sequences that cannot be converted and mapped to Akida are added on ONNX domain. The function also manages inbound connections between sub-models to preserve the original model’s topology.

When device is not provided, a mimimal device is computed independently for each akida compatible model, then a common device is computed and used to map the HybridModel.

Parameters:

qmodel (Any) – the quantized ONNX model to convert.
device (akida.Device, optional) – the Akida device to map the Akida sub models. Defaults to None.
enable_hwpr (bool, optional) – if True, the device is computed assuming partial reconfiguration. Used when device is None. Defaults to False.
sram_size (akida.NP.SramSize, optional) – Size of shared SRAM available inside the mesh. Ignored when minimal_memory is True. Used when device is None. Defaults to None.
minimal_memory (bool, optional) – if True, computes and sets the minimal required inputs and weights memory for the device. Used when device is None. Defaults to False.
initial_num_nodes (int, optional) – the initial number of nodes with which to compute the base device. Used when device is None. Defaults to 36.

Returns:

a hybrid model containing Akida and ONNX sub-models.

Return type:

HybridModel

Inference

class onnx2akida.inference.AkidaInferenceSession(path_or_bytes, sess_options=None, providers=None, provider_options=None, **kwargs)[source]

A wrapper around onnxruntime.InferenceSession that ensures the Akida custom ops library is registered.

Parameters:

path_or_bytes (str or bytes) – path to the ONNX model file or the model in bytes.
sess_options (ort.SessionOptions, optional) – session options for the inference session. Defaults to None.
providers (list, optional) – list of execution providers. Defaults to None.
provider_options (list, optional) – list of provider options. Defaults to None.
**kwargs – additional keyword arguments for the InferenceSession.