Updates to the rewriter tutorial

[gramalingam]

Updates to the rewriter tutorial

[Copilot]

Pull Request Overview

This PR updates the rewriter tutorial documentation by improving explanations and demonstrating an alternative class-based approach to defining rewrite rules.

• Introduces a class-based rewrite rule example in the tutorial.
• Enhances documentation on conditional rewrite rules and commutativity handling.
• Updates the index order and adjusts descriptive text in several markdown files.

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/tutorial/rewriter/simple_example.md	Refactored the tutorial to demonstrate an alternative class-based definition for rewrite rules.
docs/tutorial/rewriter/rewrite_patterns.md	Updated text to indicate that rewrite rules are conditional.
docs/tutorial/rewriter/examples/erfgelu.py	Added a new class-based rewrite rule implementation example.
docs/tutorial/rewriter/conditional_rewrite.md	Revised explanation for condition checking with additional IR details.
docs/tutorial/rewriter/commute.md	Expanded discussion on commutativity handling and introduced a warning regarding rule explosion.
docs/tutorial/index.md	Adjusted the ordering for the toctree entries.

Comments suppressed due to low confidence (1)

docs/tutorial/rewriter/simple_example.md:65

• Consider revising the sentence to include a verb, for example: 'This parameter is either a Sequence[PatternRewriteRule] or a RewriteRuleSet.'

2. `pattern_rewrite_rules` : This parameter either a `Sequence[PatternRewriteRule]` or a `RewriteRuleSet`.

[codecov]

❌ 26 Tests Failed:

Tests completed	Failed	Passed	Skipped
16280	26	16254	2528

View the top 3 failed test(s) by shortest run time

onnxscript.backend.onnx_export_test.TestOnnxBackEnd::test_export2python_produces_correct_onnx_script_model_0000_test_abs

Stack Traces | 0.003s run time

onnxscript\backend\onnx_export_test.py:137: in extract_functions
    mod = importlib.import_module(import_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
C:\hostedtoolcache\windows\Python\3.12.10\x64\Lib\importlib\__init__.py:90: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
E   ModuleNotFoundError: No module named 'tests.onnx_backend_test_code.test_abs'

The above exception was the direct cause of the following exception:
.nox\test\Lib\site-packages\parameterized\parameterized.py:620: in standalone_func
    return func(*(a + p.args), **p.kwargs, **kw)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
onnxscript\backend\onnx_export_test.py:271: in test_export2python_produces_correct_onnx_script_model
    functions = extract_functions(backend_test.name, code, self.test_folder)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
onnxscript\backend\onnx_export_test.py:139: in extract_functions
    raise AssertionError(
E   AssertionError: Unable to import 'tests.onnx_backend_test_code.test_abs' (e=No module named 'tests.onnx_backend_test_code.test_abs') (file: 'C:\\a\\onnxscript\\onnxscript\\tests\\onnx_backend_test_code\\test_abs.py', absolute path: 'C:\\a\\onnxscript\\onnxscript\\tests\\onnx_backend_test_code\\test_abs.py', current folder: C:\a\onnxscript\onnxscript
E   ---- CONTENT --
E   import numpy
E   from onnx import TensorProto
E   from onnx.helper import make_tensor
E   from onnxscript import script, external_tensor
E   from onnxscript.values import Opset
E   from onnxscript.onnx_types import FLOAT
E   from onnxscript.onnx_opset import opset13
E   
E   @script()
E   def bck_test_abs(x: FLOAT[3,4,5]) -> (FLOAT[3,4,5]):
E       y = opset13.Abs(x)
E       return y

onnxscript.backend.onnx_export_test.TestOnnxBackEnd::test_export2python_produces_correct_onnx_script_model_0114_test_bitshift_right_uint32

Stack Traces | 0.004s run time

onnxscript\backend\onnx_export_test.py:137: in extract_functions
    mod = importlib.import_module(import_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
C:\hostedtoolcache\windows\Python\3.11.9\x64\Lib\importlib\__init__.py:126: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
E   ModuleNotFoundError: No module named 'tests.onnx_backend_test_code.test_bitshift_right_uint32'

The above exception was the direct cause of the following exception:
.nox\test_ort_nightly\Lib\site-packages\parameterized\parameterized.py:620: in standalone_func
    return func(*(a + p.args), **p.kwargs, **kw)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
onnxscript\backend\onnx_export_test.py:271: in test_export2python_produces_correct_onnx_script_model
    functions = extract_functions(backend_test.name, code, self.test_folder)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
onnxscript\backend\onnx_export_test.py:139: in extract_functions
    raise AssertionError(
E   AssertionError: Unable to import 'tests.onnx_backend_test_code.test_bitshift_right_uint32' (e=No module named 'tests.onnx_backend_test_code.test_bitshift_right_uint32') (file: 'C:\\a\\onnxscript\\onnxscript\\tests\\onnx_backend_test_code\\test_bitshift_right_uint32.py', absolute path: 'C:\\a\\onnxscript\\onnxscript\\tests\\onnx_backend_test_code\\test_bitshift_right_uint32.py', current folder: C:\a\onnxscript\onnxscript
E   ---- CONTENT --
E   import numpy
E   from onnx import TensorProto
E   from onnx.helper import make_tensor
E   from onnxscript import script, external_tensor
E   from onnxscript.values import Opset
E   from onnxscript.onnx_types import UINT32
E   from onnxscript.onnx_opset import opset11
E   
E   @script()
E   def bck_test_bitshift_right_uint32(x: UINT32[3], y: UINT32[3]) -> (UINT32[3]):
E       z = opset11.BitShift(x, y, direction='RIGHT')
E       return z

onnxscript.backend.onnx_export_test.TestOnnxBackEnd::test_export2python_produces_correct_onnx_script_model_1262_test_triu_square_neg

Stack Traces | 0.004s run time

onnxscript\backend\onnx_export_test.py:137: in extract_functions
    mod = importlib.import_module(import_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
C:\hostedtoolcache\windows\Python\3.12.10\x64\Lib\importlib\__init__.py:90: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
E   ModuleNotFoundError: No module named 'tests.onnx_backend_test_code.test_triu_square_neg'

The above exception was the direct cause of the following exception:
.nox\test\Lib\site-packages\parameterized\parameterized.py:620: in standalone_func
    return func(*(a + p.args), **p.kwargs, **kw)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
onnxscript\backend\onnx_export_test.py:271: in test_export2python_produces_correct_onnx_script_model
    functions = extract_functions(backend_test.name, code, self.test_folder)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
onnxscript\backend\onnx_export_test.py:139: in extract_functions
    raise AssertionError(
E   AssertionError: Unable to import 'tests.onnx_backend_test_code.test_triu_square_neg' (e=No module named 'tests.onnx_backend_test_code.test_triu_square_neg') (file: 'C:\\a\\onnxscript\\onnxscript\\tests\\onnx_backend_test_code\\test_triu_square_neg.py', absolute path: 'C:\\a\\onnxscript\\onnxscript\\tests\\onnx_backend_test_code\\test_triu_square_neg.py', current folder: C:\a\onnxscript\onnxscript
E   ---- CONTENT --
E   import numpy
E   from onnx import TensorProto
E   from onnx.helper import make_tensor
E   from onnxscript import script, external_tensor
E   from onnxscript.values import Opset
E   from onnxscript.onnx_types import INT64
E   from onnxscript.onnx_opset import opset14
E   
E   @script()
E   def bck_test_triu_square_neg(x: INT64[2,3,3], k: INT64) -> (INT64[2,3,3]):
E       y = opset14.Trilu(x, k)
E       return y

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[justinchuby]

Looks like there's lint errors

[justinchuby]

Maybe we can disable the # pylint: disable=arguments-differ rule universally in

onnxscript/pyproject_pylint.toml

Line 4 in f62f3bc

disable = [

[gramalingam]

Maybe we can disable the # pylint: disable=arguments-differ rule universally in

onnxscript/pyproject_pylint.toml

Line 4 in f62f3bc

disable = [

I think that would be good. It shows up as a "warning", so it wasn't clear to me if it had to be fixed. Anyway: there is no good fix, since the alternatives are to drop the method from the abstract class completely or add an override everywhere. So, this must be a new pylint requirement?

[justinchuby]

Maybe we can disable the # pylint: disable=arguments-differ rule universally in

onnxscript/pyproject_pylint.toml

Line 4 in f62f3bc

disable = [

I think that would be good. It shows up as a "warning", so it wasn't clear to me if it had to be fixed. Anyway: there is no good fix, since the alternatives are to drop the method from the abstract class completely or add an override everywhere. So, this must be a new pylint requirement?

I think we disabled some pylint rules in the rewriter folder but not in the examples folder. That's why it's showing up. Anyways any lintrunner issue (no matter level) will need to be fixed or silenced.