Skip to content

Commit decab2e

Browse files
justinchubyjustinchuby
authored
Improvement to IR docs 2/n (#2229)
Major improvement in documenting all submodules in onnxscript.ir. Also added documentation for the rewriter, optimizer and version converter. ![image](https://github.com/user-attachments/assets/cdb66f93-0f93-4112-b20f-055f275b2cca) ![image](https://github.com/user-attachments/assets/2610c439-4ecf-4e96-9c9b-ff98b5d6dc23)
1 parent a028d2b commit decab2e

28 files changed

+367
-40
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ dmypy.json
100100
*.onnxlib
101101
**/onnx_backend_test_code/**
102102
docs/auto_examples/*
103-
docs/intermediate_representation/generated/*
103+
docs/**/generated/*
104104
tests/export/*
105105
tests/models/testoutputs/*
106106
tests/mylib.onnxlib

‎docs/_templates/classtemplate.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77

88
.. autoclass:: {{ name }}
99
:members:
10-
10+
:undoc-members:
11+
:member-order: bysource
1112

1213
..
1314
autogenerated from docs/_templates/classtemplate.rst
14-
note it does not have :inherited-members:

‎docs/_templates/classtemplate_inherited.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. role:: hidden
2+
:class: hidden-section
3+
.. currentmodule:: {{ module }}
4+
5+
6+
{{ name | underline}}
7+
8+
.. autoclass:: {{ name }}
9+
:members:
10+
:undoc-members:
11+
:inherited-members:
12+
:member-order: bysource
13+
14+
15+
..
16+
autogenerated from docs/_templates/classtemplate.rst

‎docs/_templates/functiontemplate.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. role:: hidden
2+
:class: hidden-section
3+
.. currentmodule:: {{ module }}
4+
5+
6+
{{ name | underline}}
7+
8+
.. autofunction:: {{ name }}
9+
10+
11+
..
12+
autogenerated from docs/_templates/functiontemplate.rst

‎docs/api/index.md

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,29 @@
33
## Author Models
44

55
```{toctree}
6+
:maxdepth: 1
7+
68
decorator
79
opsets
810
converter
911
values
1012
```
1113

12-
## Tests and Tools
14+
## Model transformation
1315

1416
```{toctree}
17+
:maxdepth: 1
18+
19+
optimizer
20+
rewriter
21+
rewriter_pattern
22+
version_converter
23+
```
24+
25+
## Testing
26+
27+
```{toctree}
28+
:maxdepth: 1
29+
1530
testing
16-
tools
1731
```

‎docs/api/optimizer.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# onnxscript.optimizer
2+
3+
```{eval-rst}
4+
.. automodule::onnxscript.optimizer
5+
.. currentmodule:: onnxscript
6+
```
7+
8+
```{eval-rst}
9+
.. autosummary::
10+
:toctree: generated
11+
:template: functiontemplate.rst
12+
:nosignatures:
13+
14+
optimizer.optimize
15+
optimizer.inline
16+
optimizer.basic_constant_propagation
17+
optimizer.fold_constants
18+
optimizer.remove_unused_nodes
19+
```

‎docs/api/rewriter.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# onnxscript.rewriter
2+
3+
```{eval-rst}
4+
.. automodule::onnxscript.rewriter
5+
.. currentmodule:: onnxscript
6+
```
7+
8+
```{eval-rst}
9+
.. autosummary::
10+
:toctree: generated
11+
:template: functiontemplate.rst
12+
:nosignatures:
13+
14+
rewriter.rewrite
15+
```
16+
17+
## IR passes
18+
19+
```{eval-rst}
20+
.. autosummary::
21+
:toctree: generated
22+
:template: classtemplate.rst
23+
:nosignatures:
24+
25+
rewriter.RewritePass
26+
```

‎docs/api/rewriter_pattern.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# onnxscript.rewriter.pattern
2+
3+
```{eval-rst}
4+
.. automodule::onnxscript.rewriter.pattern
5+
.. currentmodule:: onnxscript
6+
```
7+
8+
```{eval-rst}
9+
.. autosummary::
10+
:toctree: generated
11+
:template: classtemplate.rst
12+
:nosignatures:
13+
14+
rewriter.pattern.Pattern
15+
rewriter.pattern.StringPattern
16+
rewriter.pattern.StringConstantPattern
17+
rewriter.pattern.PrefixPattern
18+
rewriter.pattern.AttrPattern
19+
rewriter.pattern.AttrConstantPattern
20+
rewriter.pattern.OpsetPatternBuilder
21+
rewriter.pattern.OpPatternBuilder
22+
rewriter.pattern.MatchResult
23+
rewriter.pattern.ValuePattern
24+
rewriter.pattern.NodePattern
25+
rewriter.pattern.NodeOutputPattern
26+
rewriter.pattern.AnyValue
27+
rewriter.pattern.Constant
28+
rewriter.pattern.GraphPattern
29+
rewriter.pattern.ReplacementSubgraph
30+
rewriter.pattern.ReplacementPatternFunction
31+
rewriter.pattern.PatternMatcher
32+
rewriter.pattern.SimplePatternMatcher
33+
rewriter.pattern.RewriteRule
34+
rewriter.pattern.RewriteRuleAsClass
35+
rewriter.pattern.RewriteRuleSet
36+
rewriter.pattern.MatchStatus
37+
rewriter.pattern.MatchInfo
38+
rewriter.pattern.MatchingTracer
39+
```

‎docs/api/tools.md

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎docs/api/version_converter.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# onnxscript.version_converter
2+
3+
```{eval-rst}
4+
.. automodule::onnxscript.version_converter
5+
.. currentmodule:: onnxscript
6+
```
7+
8+
## Functions
9+
10+
```{eval-rst}
11+
.. autosummary::
12+
:toctree: generated
13+
:template: functiontemplate.rst
14+
:nosignatures:
15+
16+
version_converter.convert_version
17+
```
18+
19+
## IR passes
20+
21+
```{eval-rst}
22+
.. autosummary::
23+
:toctree: generated
24+
:template: classtemplate.rst
25+
:nosignatures:
26+
27+
version_converter.ConvertVersionPass
28+
```

‎docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ result = MatmulAdd(x, wt, bias)
103103
Overview <self>
104104
tutorial/index
105105
api/index
106-
intermediate_representation/index
106+
ir/index
107107
auto_examples/index
108108
articles/index
109109
```

‎docs/intermediate_representation/getting_started.ipynb renamed to ‎docs/ir/getting_started.ipynb

File renamed without changes.

‎docs/intermediate_representation/index.md renamed to ‎docs/ir/index.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,5 @@ An in-memory IR that supports the full ONNX spec, designed for graph constructio
1919
2020
getting_started
2121
tensors
22-
ir_api
23-
generated
22+
ir_api/index
2423
```

‎docs/intermediate_representation/ir_api.md renamed to ‎docs/ir/ir_api/core.md

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,40 @@
22

33
```{eval-rst}
44
.. automodule::onnxscript.ir
5+
.. currentmodule:: onnxscript
56
```
67

7-
## IR objects
8+
## Functions and constructors
89

910
```{eval-rst}
10-
.. currentmodule:: onnxscript
1111
.. autosummary::
1212
:toctree: generated
13+
:template: functiontemplate.rst
1314
:nosignatures:
14-
:template: classtemplate.rst
1515
16-
ir.Model
16+
ir.load
17+
ir.save
18+
ir.from_proto
19+
ir.to_proto
20+
ir.tensor
21+
ir.node
22+
```
23+
24+
## Classes
25+
26+
```{eval-rst}
27+
.. autosummary::
28+
:toctree: generated
29+
:template: classtemplate_inherited.rst
30+
:nosignatures:
31+
32+
ir.TensorProtocol
33+
ir.Value
34+
ir.Node
1735
ir.Graph
36+
ir.Model
1837
ir.GraphView
1938
ir.Function
20-
ir.Node
21-
ir.Value
2239
ir.Attr
2340
ir.RefAttr
2441
ir.Shape
@@ -38,8 +55,8 @@
3855
```{eval-rst}
3956
.. autosummary::
4057
:toctree: generated
41-
:nosignatures:
4258
:template: classtemplate.rst
59+
:nosignatures:
4360
4461
ir.DataType
4562
ir.AttributeType

‎docs/ir/ir_api/index.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# IR APIs
2+
3+
```{toctree}
4+
:maxdepth: 1
5+
6+
core
7+
ir_convenience
8+
ir_external_data
9+
ir_passes
10+
ir_passes_common
11+
ir_traversal
12+
ir_tape
13+
```

‎docs/ir/ir_api/ir_convenience.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# ir.convenience
2+
3+
```{eval-rst}
4+
.. automodule::onnxscript.ir.convenience
5+
.. currentmodule:: onnxscript.ir.convenience
6+
```
7+
8+
9+
```{eval-rst}
10+
.. autofunction:: convert_attribute
11+
.. autofunction:: convert_attributes
12+
.. autofunction:: replace_all_uses_with
13+
.. autofunction:: replace_nodes_and_values
14+
.. autofunction:: create_value_mapping
15+
```

‎docs/ir/ir_api/ir_external_data.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# ir.external_data
2+
3+
```{eval-rst}
4+
.. automodule::onnxscript.ir.external_data
5+
.. currentmodule:: onnxscript.ir.external_data
6+
```
7+
8+
The `ir.external_data` module provides utilities for handling external data in ONNX models. It enables the conversion of tensors to and from external data files, allowing for efficient storage and manipulation of large tensor data. This is particularly useful for models with large initializers that exceed memory constraints.
9+
10+
## Functions
11+
12+
```{eval-rst}
13+
.. autofunction:: load_to_model
14+
.. autofunction:: unload_from_model
15+
.. autofunction:: convert_tensors_to_external
16+
.. autofunction:: convert_tensors_from_external
17+
.. autofunction:: set_base_dir
18+
```
19+
20+
<!-- TODO: Create examples -->

‎docs/ir/ir_api/ir_passes.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# ir.passes
2+
3+
```{eval-rst}
4+
.. automodule::onnxscript.ir.passes
5+
.. currentmodule:: onnxscript
6+
```
7+
8+
## Use built-in passes
9+
10+
Common, reusable passes are implemented in `ir.passes.common`. You can use {py:class}`ir.passes.Sequential <onnxscript.ir.passes.Sequential>` to chain passes or use {py:class}`ir.passes.PassManager <onnxscript.ir.passes.PassManager>` which supports early stopping if no changes are made.
11+
12+
## Pass infrastructure
13+
14+
Inherent {py:class}`ir.passes.InPlacePass <onnxscript.ir.passes.InPlacePass>` or {py:class}`ir.passes.FunctionalPass <onnxscript.ir.passes.FunctionalPass>` to define a pass. You will need to implement the `call` method which returns a {py:class}`ir.passes.PassResult <onnxscript.ir.passes.PassResult>`.
15+
16+
Alternatively, inherent the base class `ir.passes.PassBase <onnxscript.ir.passes.PassBase>` and override the two properties `changes_input` and `in_place` to set properties of the pass.
17+
18+
```{eval-rst}
19+
.. autosummary::
20+
:toctree: generated
21+
:template: classtemplate.rst
22+
:nosignatures:
23+
24+
ir.passes.PassBase
25+
ir.passes.InPlacePass
26+
ir.passes.FunctionalPass
27+
ir.passes.Sequential
28+
ir.passes.PassResult
29+
ir.passes.PassManager
30+
```
31+
32+
## Errors
33+
34+
```{eval-rst}
35+
.. autoexception:: onnxscript.ir.passes.InvariantError
36+
.. autoexception:: onnxscript.ir.passes.PreconditionError
37+
.. autoexception:: onnxscript.ir.passes.PostconditionError
38+
.. autoexception:: onnxscript.ir.passes.PassError
39+
```

0 commit comments

Comments
 (0)