[quant] Add IR related recommendations for Quantizer tutorial

Summary:
att

Test Plan:
CI

Reviewers:

Subscribers:

Tasks:

Tags:

Author: jerryzh168

prototype_source/pt2e_quantizer.rst

@@ -302,6 +302,106 @@ functions that are used in the example:
    `get_bias_qspec <https://github.com/pytorch/pytorch/blob/47cfcf566ab76573452787335f10c9ca185752dc/torch/ao/quantization/_pt2e/quantizer/utils.py#L53>`__
    can be used to get the ``QuantizationSpec`` from ``QuantizationConfig`` for a specific pattern.
 
+A Note on IR for PT2E Quantization Flow
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+IR means the intermediate representation of the model, for example, ``torch`` IR (``torch.nn`` modules, ``torch.nn.functional`` ops) or ``aten`` IR (``torch.ops.aten.linear``, ...). PT2E Quantization Flow is using pre autograd aten IR (the output of `torch.export` API) so that we support training. As is shown before, we need to match the operator or operator patterns before we can do annotations on them, So the question is how do we match the pattern?
+
+1. Matching ``aten`` IR directly
+------------------------------------
+
+The most straightforward way might be matching ``aten`` IR directly.
+
+Example::
+
+  for n in gm.graph.nodes:
+        if n.op != "call_function" or n.target not in [
+            torch.ops.aten.relu.default,
+            torch.ops.aten.relu_.default,
+        ]:
+            continue
+        relu_node = n
+        maybe_conv_node = n.args[0]
+        if (
+            not isinstance(maybe_conv_node, Node)
+            or maybe_conv_node.op != "call_function"
+            or maybe_conv_node.target
+            not in [
+                torch.ops.aten.conv1d.default,
+                torch.ops.aten.conv2d.default,
+            ]
+        ):
+            continue
+
+        # annotate conv and relu nodes
+        ...
+
+However one problem for using this IR is that the representation might change if the PyTorch implementation for modules or functional ops changed. But this could be unexpected since modeling users typically assume that when the eager mode model code doesn't change, they should get the same model representation after program capture as well. One concrete effect for this problem is that if a ``Quantizer`` do annotations based on recognizing ``aten`` IR patterns, then it may fail to recognzing the pattern after PyTorch version update, and the same eager mode floating point may be left unquantized.
+
+2. Using ``SubgraphMatcher``
+--------------------------------
+Because of this, we recommend people to recognize the pattern through ``SubgraphMatcher``, through capturing a ``torch`` IR pattern (with the same program capture used for capturing the floating point model), instead of using the ``aten`` IR pattern directly.
+
+Example::
+
+  def conv_relu_pattern(x, weight, bias):
+      conv = torch.nn.functional.conv2d(x, weight, bias)
+      relu = torch.nn.functional.relu(conv)
+      return relu
+
+  matcher = SubgraphMatcher(conv_relu_pattern)
+  matches = matcher.match(model)
+  for match in matches:
+      # find input and output of the pattern
+      # annotate the nodes
+      inputs, output = _find_input_and_output(match)
+      inputs[0].users[0].meta["quantization_annotation"] = ...
+      inputs[1].users[0].meta["quantization_annotation"] = ...
+      output.meta["quantization_annotation"] = ...
+
+With this, the ``Quantizer`` will still be valid even when the implementation for nn modules and functionals changes, the ``aten`` IR for floating point model will change, but since we capture the pattern again instead of hardcoding the ``aten`` IR for the pattern, we'll get the updated ``aten`` IR as well and will still be able to match the pattern.
+
+One caveat is that if inputs of the pattern has multiple users, we don't have a good way to identify which user node we want to annotate except for checking the aten op target.
+
+Another caveat is that we need to make sure we have an exhaustive list of examples (e.g. 2D, 3D, 4D inputs, real v.s. symbolic inputs, training=True v.s. training=False etc.) for the pattern to make sure cover different possible ``aten`` IR outcomes captured from the ``torch`` IR pattern.
+      
+3. Using ``SubgraphMatcherWithNameNodeMap``
+----------------------------------------------
+We also introduced a different SubgraphMatcher util called ``SubgraphMatcherWithNameNodeMap`` to make it easier to query the nodes that people want to annotate.
+
+Example::
+  
+  def conv_relu_pattern(x, weight, bias):
+      conv = torch.nn.functional.conv2d(x, weight, bias)
+      relu = torch.nn.functional.relu(conv)
+      # returns an additional dict that includes a map from name to node that we want to annotate
+      return relu, {"conv": conv, "relu": relu, "x": x, "weight": weight, "bias": bias}
+
+  matcher = SubgraphMatcherWithNameNodeMap(conv_relu_pattern)
+  matches = matcher.match(model)
+  for match in matches:
+      # find input and output of the pattern
+      # annotate the nodes
+      name_node_map = match.name_node_map
+      name_node_map["conv"].meta["quantization_annotation"] = ...
+      name_node_map["relu"].meta["quantization_annotation"] = ...
+
+This should be easier to use than the original ``SubgraphMatcher``, however, it may not work if some of the operators are captured as multiple ops, e.g. if ``torch.nn.functional.conv2d`` is captured as multiple ops, then the inputs ``x``, ``weight``, ``bias`` may not be the direct inputs to the final operator marked by ``conv``, in this case we'll need to revert to the same way of access mentioned in the previous example.
+
+Example::
+
+  for match in matches:
+      # find input and output of the pattern
+      # annotate the nodes
+      name_node_map = match.name_node_map
+      input_x = name_node_map["x"]
+      # since input_x may not be the input of name_node_map["conv"]
+      # we'll get the user nodes of this op and annotate that instead
+      input_x.users[0].meta["quantization_annotation"] = ...
+      ...
+
+
+Similar to ``SubgraphMatcher``, we also need to make sure to capture the PyTorch pattern with different example inputs to cover all possible ``aten`` IR variants.      
+
 Conclusion
 ^^^^^^^^^^^^^^^^^^^