Aidge ONNX API
==============

Import
------

Method related to the import of an ONNX graph into Aidge.

.. autofunction:: aidge_onnx.load_onnx

Register import functions
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: aidge_onnx.node_import.register_import

.. autofunction:: aidge_onnx.node_import.supported_operators

.. autofunction:: aidge_onnx.node_import.auto_register_import

.. because defaultdict.__doc__ is readonly, Sphinx cannot use the docstring set in the code.
.. data:: aidge_onnx.node_import.ONNX_NODE_CONVERTER_

    This ``defaultdict`` maps the ONNX type to a function which can convert an ONNX Node into an Aidge Node.
    This means that if a key is missing from :py:data:`aidge_onnx.node_import.ONNX_NODE_CONVERTER_`, it will return the function :py:func:`aidge_onnx.node_import.generic.import_generic` which import the ONNX node as an Aidge generic operator.
    It is possible to add keys to this dictionnary at runtime using :py:func:`aidge_onnx.node_import.register_converter` or :py:func:`aidge_onnx.node_import.auto_register`


Converters ONNX to Aidge
~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: aidge_onnx.node_import.generic.import_generic

Check ONNX import with Aidge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to verify the layerwise output consistency between Aidge and ONNX Runtime for your ONNX file, you can use the command-line tool:

.. program-output:: aidge_onnx_checker --help

This tool compares the output tensors produced by Aidge and ONNX Runtime for each layer of your model and summarizes the results.

The typical output looks like this:

.. image:: /source/_static/onnx_checker.png

Each edge of the graphs is listed following the model's topological order. If a layer exists in one framework but not the other, the corresponding column will display a cross (✗) for the missing framework and a check mark (✓) for the available one.
This does not necessarily indicate an error in the model loading, it simply means there is no direct equivalent layer between the two frameworks.

The average error shown in the report corresponds to the mean difference between tensor values for all compared layers.

Optionally, the tool can log per-layer error data to a specified folder, making it easier to identify where discrepancies occur within the model.

Clean ONNX file
~~~~~~~~~~~~~~~

When exporting a model to ONNX, the exported graph may be messy.

We defined a CLI tool that use Aidge in order to clean the ONNX.

This tool curate multiple functions (recipes) that are applied to the graph using Aidge graph matching and replacement algorithms. These functions are applied depending on the opset targeted and optimizations level desired by the user.

Optimization level are as follow:

* ``O0``: Training safe, with these optimizations the graph is still learnable.
* ``O1``: Accuracy safe, with these optimizations the graph will be optimized for inference performances, potentially breaking learnability.
* ``O2``: Approximation, with these optimizations the inference result may diverge from the original one in order to optimize inference speed.

CLI
^^^

The CLI helper is:

.. program-output:: onnx_cleaner --help


List of recipes supported

.. program-output:: onnx_cleaner --show_recipes

Python API
^^^^^^^^^^

One can directly use the Python API to simplify an ONNX graph using :py:func:`aidge_onnx.onnx_cleaner.clean_onnx` or a Aidge :py:class:`aidge_core.GraphView` using :py:func:`aidge_onnx.onnx_cleaner.simplify_graph`.

.. autofunction:: aidge_onnx.onnx_cleaner.clean_onnx

.. autofunction:: aidge_onnx.onnx_cleaner.simplify_graph

Export
------

Method related to the export of an Aidge :py:class:`aidge_core.GraphView` to an ONNX file.

.. autofunction:: aidge_onnx.export_onnx

Register export functions
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: aidge_onnx.node_export.register_export

.. autofunction:: aidge_onnx.node_export.supported_operators

.. autofunction:: aidge_onnx.node_export.auto_register_export

Converters Aidge to ONNX
~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: aidge_onnx.node_export.generic_export.generic_export