# PyTorch ONNX Exporter (POE) Rules are based on sarif ReportingDescriptor format.

## Rules for PyTorch (TorchScript based) ONNX Exporter (POE)

- id: POE0001
  name: node-missing-onnx-shape-inference
  short_description:
    text: Node is missing ONNX shape inference.
  full_description:
    text: "Node is missing ONNX shape inference.
      This usually happens when the node is not valid under standard ONNX operator spec."
    markdown: |
      Node is missing ONNX shape inference.
      This usually happens when the node is not valid under standard ONNX operator spec.
  message_strings:
    default:
      text: "The shape inference of {op_name} type is missing, so it may result in wrong shape inference for the exported graph.
      Please consider adding it in symbolic function."
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: POE0002
  name: missing-custom-symbolic-function
  short_description:
    text: Missing symbolic function for custom PyTorch operator, cannot translate node to ONNX.
  full_description:
    text: Missing symbolic function for custom PyTorch operator, cannot translate node to ONNX.
    markdown: |
      Missing symbolic function for custom PyTorch operator, cannot translate node to ONNX.
  message_strings:
    default:
      text: "ONNX export failed on an operator with unrecognized namespace {op_name}.
      If you are trying to export a custom operator, make sure you registered
      it with the right domain and version."
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: POE0003
  name: missing-standard-symbolic-function
  short_description:
    text: Missing symbolic function for standard PyTorch operator, cannot translate node to ONNX.
  full_description:
    text: Missing symbolic function for standard PyTorch operator, cannot translate node to ONNX.
    markdown: |
      Missing symbolic function for standard PyTorch operator, cannot translate node to ONNX.
  message_strings:
    default:
      text: "Exporting the operator '{op_name}' to ONNX opset version {opset_version} is not supported.
      Please feel free to request support or submit a pull request on PyTorch GitHub: {issue_url}."
  help_uri:
  properties:
    deprecated: false
    tags: []


- id: POE0004
  name: operator-supported-in-newer-opset-version
  short_description:
    text: Operator is supported in newer opset version.
  full_description:
    text: Operator is supported in newer opset version.
    markdown: |
      Operator is supported in newer opset version.

      Example:
      ```python
      torch.onnx.export(model, args, ..., opset_version=9)
      ```
  message_strings:
    default:
      text: "Exporting the operator '{op_name}' to ONNX opset version {opset_version} is not supported.
      Support for this operator was added in version {supported_opset_version}, try exporting with this version."
  help_uri:
  properties:
    deprecated: false
    tags: []

## Rules for PyTorch (dynamo fx based) ONNX Exporter (FXE)

- id: FXE0007
  name: fx-graph-to-onnx
  short_description:
    text: Transforms graph from FX IR to ONNX IR.
  full_description:
    text: "Transforms graph from FX IR to ONNX IR."
    markdown: |
      This diagnostic tracks the transformation process from an FX Graph (in FX IR) to an ONNX Graph (in ONNX IR).

      ## Key Representations:

      - **FX Graph**: The graph in FX IR produced by dynamo or symbolic tracing.
      - **ONNX Graph**: The graph in ONNX IR and [operators](https://onnx.ai/onnx/operators/).

      ## Additional Notes:

      - Prior to this transformation step, the FX graph undergoes preprocessing through multiple FX passes.
        To gain insight into these transformations, refer to diagnostic `FXE0010`.
      - To enable a detailed view of the graph transformation in progress within this diagnostic, switch to the DEBUG mode.

        - Set DiagnosticOptions.verbosity_level to logging.DEBUG.
        - Activate the environment variable TORCH_LOGS='onnx_diagnostics'.

      - For specific information related to node-level FX to ONNX transformations, explore the diagnostic `FXE0008`.
  message_strings:
    default:
      text: "Transforming FX graph {graph_name} to ONNX graph."
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0008
  name: fx-node-to-onnx
  short_description:
    text: Transforms an FX node to an ONNX node.
  full_description:
    text: "Transforms an FX node to an ONNX node."
    markdown: |
      This diagnostic tracks the transformation process from an FX Node to ONNX [Operators](https://onnx.ai/onnx/operators/).

      The process of converting FX Node to ONNX Node involves dealing with six distinct node types:
        1. `placeholder`: Represents a module input, maps to an ONNX graph input.
        2. `call_module`: Symbolizes a call to a submodule, maps to an ONNX
        3. `call_method`: Symbolizes a method call. Not yet implemented.
        4. `call_function`: Symbolizes a function call. [Core ATen](https://pytorch.org/docs/stable/ir.html#core-aten-ir) is expected
          as the function call target. The mapping from ATen to ONNX is implemented by [ONNXScript torchlib](https://github.com/microsoft/onnxscript/tree/main/onnxscript/function_libs/torch_lib/ops).
          This [guide](https://pytorch.org/docs/stable/onnx.html#onnx-script-functions) shows how to write and register a custom symbolic function for call_function FX node.
        5. `get_attr`: Indicates an attribute access within the current module. Maps to an ONNX graph initializer.
        6. `output`: Represents the module's output. Maps to an ONNX graph output.

      For a granular understanding of how each node type is transformed, refer to the implementation details in `FxOnnxInterpreter`.
  message_strings:
    default:
      text: "Transforming FX node {node_repr} to ONNX node."
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0010
  name: fx-pass
  short_description:
    text: FX graph transformation during ONNX export before converting from FX IR to ONNX IR.
  full_description:
    text: "FX graph transformation during ONNX export before converting from FX IR to ONNX IR."
    markdown: |
      This diagnostic tracks the FX passes executed during the ONNX export process prior
      to converting from FX IR (Intermediate Representation) to ONNX IR.

      Under the scope of ONNX export, an FX pass refers to a specific transformation applied to the FX GraphModule.
      The primary aim of these passes is to streamline the graph into a format that aligns more with the ONNX IR.
      Moreover, these passes work to substitute unsupported FX IR features with those recognized and endorsed by
      ONNX IR. Common transformations include, but aren't limited to, decomposition, functionalization and
      type promotion.

      For those who are interested in a comprehensive log detailing the modifications made during these passes,
      there are a couple of options:

      - Set DiagnosticOptions.verbosity_level to logging.DEBUG.
      - Activate the environment variable TORCH_LOGS='onnx_diagnostics'.

      However, it's noteworthy that by default, such detailed logging is turned off. The primary reason being
      its considerable impact on performance.

      For an in-depth understanding of each specific pass, please refer to the directory: torch/onnx/_internal/fx/passes.

  message_strings:
    default:
      text: "Running {pass_name} pass."
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0011
  name: no-symbolic-function-for-call-function
  short_description:
    text: Cannot find symbolic function to convert the "call_function" FX node to ONNX.
  full_description:
    text: "Cannot find symbolic function to convert the \"call_function\" FX node to ONNX.
      "
    markdown: |
      This error occurs when the ONNX converter is unable to find a corresponding symbolic function
      to convert a "call_function" node in the input graph to its equivalence in ONNX. The "call_function"
      node represents a normalized function call in PyTorch, such as "torch.aten.ops.add".

      To resolve this error, you can try one of the following:

      - If exists, apply the auto-fix suggested by the diagnostic. TODO: this part is not available yet.
      - Rewrite the model using only supported PyTorch operators or functions.
      - Follow this [guide](https://pytorch.org/tutorials/beginner/onnx/onnx_registry_tutorial.html#overview) to write and
        register a custom symbolic function for the unsupported call_function FX node.

  message_strings:
    default:
      text: "No symbolic function to convert the \"call_function\" node {target} to ONNX. "
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0012
  name: unsupported-fx-node-analysis
  short_description:
    text: Result from FX graph analysis to reveal unsupported FX nodes.
  full_description:
    text: "Result from FX graph analysis to reveal unsupported FX nodes."
    markdown: |
      This error indicates that an FX graph contains one or more unsupported nodes. The error message
      is typically accompanied by a list of the unsupported nodes found during analysis.

      To resolve this error, you can try resolving each individual unsupported node error by following
      the suggestions by its diagnostic. Typically, options include:

      - If exists, apply the auto-fix suggested by the diagnostic. TODO: this part is not available yet.
      - Rewrite the model using only supported PyTorch operators or functions.
      - Follow this [guide](https://pytorch.org/docs/stable/onnx.html#onnx-script-functions) to write and
        register a custom symbolic function for the unsupported call_function FX node.
  message_strings:
    default:
      text: "Unsupported FX nodes: {node_op_to_target_mapping}. "
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0013
  name: op-level-debugging
  short_description:
    text: Report any op level validation failure in warnings.
  full_description:
    text: "Report any op level validation failure in warnings."
    markdown: |
      This warning message indicates that during op level debugging, certain symbolic functions
      have failed to match the results of torch ops when using real tensors generated from fake
      tensors. It is important to note that the symbolic functions may not necessarily be
      incorrect, as the validation process is non-deterministic and should only be used as a
      reference.

      There are two categories of warnings that can be triggered:

      1. Non-validated operators:
        If the warnings are caused by the following errors, they can be disregarded by users,
        as these errors occur due to the non-deterministic nature of the validation. However,
        it is important to be aware that the operators have not been validated.

        - IndexError: Unsupported input arguments of randomized dimensions/indices(INT64).
        - RuntimeError: Unsupported input arguments for torch ops are generated.
        - ValueError: Arguments/keyword arguments do not match the signature of the symbolic function.

      2. Potentially wrong torchlib operators:
        If the warnings are triggered by the following error, users should be aware that the symbolic functions
        may be incorrect in dispatching or implementation. In such cases, it is recommended to report
        the issue to the PyTorch-ONNX team, or create/register a custom symbolic function to replace the default one.

        - AssertionError: The symbolic function is potentially wrong as the results do not match the results of torch ops.
        - TypeError: The symbolic function is potentially wrong as the opschema doesn't match inputs.

  message_strings:
    default:
      text: "FX node: {node} and its onnx function: {symbolic_fn} fails on op level validation."
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0014
  name: find-opschema-matched-symbolic-function
  short_description:
    text: Find the OnnxFunction that matches the input/attribute dtypes by comparing them with their opschemas.
  full_description:
    text: "Find the OnnxFunction that matches the input dtypes by comparing them with their opschemas.
      A warning will be issued if the matched OnnxFunction is not an exact match."
    markdown: |
      When an ATen/Custom operator is registered and needs to be dispatched to an OnnxFunction, the input/attribute
      dtypes of the ATen/Custom operator are compared with the input/attribute dtypes of the OnnxFunction opschemas
      to find a match. However, if a perfect/exact match is not found, the dispatcher will attempt to find
      the nearest match with the highest number of input/attribute dtypes matching the OnnxFunction opschemas, while
      issuing a warning.

      There are two types of level that can be triggered in this rule:

      1. NOTE: A perfect match is found, and no warning is issued.
      2. WARNING: The matched OnnxFunction is not a perfect/exact match.

      Here are some suggestions based on the WARNING situation:

      1. If there are NO errors or mismatches in the results, it is safe to disregard this warning,
        as the definition of OnnxFunction schema is usually more stringent.
      2. If there are errors or mismatches in the results, it is recommended to:
        (a) Enable op_level_debugging to determine if the OnnxFunction might be incorrect.
        (b) Report the issue to the PyTorch-ONNX team.
        (c) Create/register a custom symbolic function to replace the default one.

  message_strings:
    default:
      text: "The OnnxFunction: {symbolic_fn} is the nearest match of the node {node}."
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0015
  name: fx-node-insert-type-promotion
  short_description:
    text: Determine if type promotion is required for the FX node. Insert cast nodes if needed.
  full_description:
    text: "Determine if type promotion is required for the FX node. Insert cast nodes if needed."
    markdown: |
      This diagnostic monitors the node-level type promotion insertion process. In PyTorch, there is an automatic process called implicit type promotion,
      where the input types of an operator are promoted to a common type. The determination of the common type is based on the type promotion rule specific to each operator.
      To learn more about PyTorch's type promotion rules, refer to the [elementwise_dtypes doc](https://github.com/pytorch/pytorch/blob/f044613f78df713fb57f70c608483c9f10ad332e/torch/_prims_common/__init__.py#L1252-L1335)
      and [torch._refs ops](https://github.com/pytorch/pytorch/blob/a475ea4542dfe961c9d097e33ab5041f61c8c17f/torch/_refs/__init__.py#L484).

      However, implicit type promotion is not supported in ONNX. Therefore, to replicate the PyTorch behavior, we need to explicitly insert cast nodes.
      This diagnostic tracks the process of node-level type promotion insertion.

      The type promotion rules used by this process can be found in `torch/onnx/_internal/fx/passes/type_promotion.py.`
      To update or add new type promotion rules, please refer to the [Note: Update type promotion rule] section.
  message_strings:
    default:
      text: "Performing explicit type promotion for node {target}. "
  help_uri:
  properties:
    deprecated: false
    tags: []

- id: FXE0016
  name: find-operator-overloads-in-onnx-registry
  short_description:
    text: Find the list of OnnxFunction of the PyTorch operator in onnx registry.
  full_description:
    text: "This rule involves finding the list of OnnxFunction for the PyTorch operator overload in the ONNX registry.
      If the operator overload is not supported but its default overload is, a warning will be issued.
      If both the operator overload and its default overload are not supported, an error will be issued."
    markdown: |
      The operator overload name serves the purpose of verifying whether a PyTorch operator is registered in the ONNX registry.
      If it's not found, the dispatcher takes a fallback approach and tries to locate the default overload of the PyTorch
      operator in the registry. If even the default overload is absent, it signifies that the operator is officially unsupported.

      There are three types of level that can be triggered in this rule:

      1. NOTE: The op overload is supported.
      2. WARNING: The op overload is not supported, but it's default overload is supported.
      3. ERROR: The op overload is not supported, and it's default overload is also not supported.

      Here are some suggestions based on the WARNING situation:

      1. If there are NO errors or mismatches in the results, it is safe to disregard this warning.
      2. If there are errors or mismatches in the results, it is recommended to:
        (a) Enable op_level_debugging to determine if the OnnxFunction might be incorrect.
        (b) Report the unsupported overload to the PyTorch-ONNX team.
        (c) Create/register a custom symbolic function to replace the default one.

      Here are some suggestions based on the ERROR situation:

      1. Report the unsupported operator to the PyTorch-ONNX team.
      2. Create/register a custom symbolic function to replace the default one.

  message_strings:
    default:
      text: "Checking if the FX node: {node} is supported in onnx registry."
  help_uri:
  properties:
    deprecated: false
    tags: []