diff --git a/.gitignore b/.gitignore index cd616c1321..23ce89a464 100644 --- a/.gitignore +++ b/.gitignore @@ -100,7 +100,7 @@ dmypy.json *.onnxlib **/onnx_backend_test_code/** docs/auto_examples/* -docs/intermediate_representation/generated/* +docs/**/generated/* tests/export/* tests/models/testoutputs/* tests/mylib.onnxlib diff --git a/docs/_templates/classtemplate.rst b/docs/_templates/classtemplate.rst index cd1a21dede..24a5ac1803 100644 --- a/docs/_templates/classtemplate.rst +++ b/docs/_templates/classtemplate.rst @@ -7,8 +7,8 @@ .. autoclass:: {{ name }} :members: - + :undoc-members: + :member-order: bysource .. autogenerated from docs/_templates/classtemplate.rst - note it does not have :inherited-members: diff --git a/docs/_templates/classtemplate_inherited.rst b/docs/_templates/classtemplate_inherited.rst new file mode 100644 index 0000000000..07c84a9068 --- /dev/null +++ b/docs/_templates/classtemplate_inherited.rst @@ -0,0 +1,16 @@ +.. role:: hidden + :class: hidden-section +.. currentmodule:: {{ module }} + + +{{ name | underline}} + +.. autoclass:: {{ name }} + :members: + :undoc-members: + :inherited-members: + :member-order: bysource + + +.. + autogenerated from docs/_templates/classtemplate.rst diff --git a/docs/_templates/functiontemplate.rst b/docs/_templates/functiontemplate.rst new file mode 100644 index 0000000000..f41fb0d764 --- /dev/null +++ b/docs/_templates/functiontemplate.rst @@ -0,0 +1,12 @@ +.. role:: hidden + :class: hidden-section +.. currentmodule:: {{ module }} + + +{{ name | underline}} + +.. autofunction:: {{ name }} + + +.. + autogenerated from docs/_templates/functiontemplate.rst diff --git a/docs/api/index.md b/docs/api/index.md index 9ae7651003..a6dd4bd59b 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -3,15 +3,29 @@ ## Author Models ```{toctree} +:maxdepth: 1 + decorator opsets converter values ``` -## Tests and Tools +## Model transformation ```{toctree} +:maxdepth: 1 + +optimizer +rewriter +rewriter_pattern +version_converter +``` + +## Testing + +```{toctree} +:maxdepth: 1 + testing -tools ``` diff --git a/docs/api/optimizer.md b/docs/api/optimizer.md new file mode 100644 index 0000000000..90de403099 --- /dev/null +++ b/docs/api/optimizer.md @@ -0,0 +1,19 @@ +# onnxscript.optimizer + +```{eval-rst} +.. automodule::onnxscript.optimizer +.. currentmodule:: onnxscript +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: functiontemplate.rst + :nosignatures: + + optimizer.optimize + optimizer.inline + optimizer.basic_constant_propagation + optimizer.fold_constants + optimizer.remove_unused_nodes +``` diff --git a/docs/api/rewriter.md b/docs/api/rewriter.md new file mode 100644 index 0000000000..8ff015844b --- /dev/null +++ b/docs/api/rewriter.md @@ -0,0 +1,26 @@ +# onnxscript.rewriter + +```{eval-rst} +.. automodule::onnxscript.rewriter +.. currentmodule:: onnxscript +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: functiontemplate.rst + :nosignatures: + + rewriter.rewrite +``` + +## IR passes + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: classtemplate.rst + :nosignatures: + + rewriter.RewritePass +``` diff --git a/docs/api/rewriter_pattern.md b/docs/api/rewriter_pattern.md new file mode 100644 index 0000000000..a3f1dcbe4b --- /dev/null +++ b/docs/api/rewriter_pattern.md @@ -0,0 +1,39 @@ +# onnxscript.rewriter.pattern + +```{eval-rst} +.. automodule::onnxscript.rewriter.pattern +.. currentmodule:: onnxscript +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: classtemplate.rst + :nosignatures: + + rewriter.pattern.Pattern + rewriter.pattern.StringPattern + rewriter.pattern.StringConstantPattern + rewriter.pattern.PrefixPattern + rewriter.pattern.AttrPattern + rewriter.pattern.AttrConstantPattern + rewriter.pattern.OpsetPatternBuilder + rewriter.pattern.OpPatternBuilder + rewriter.pattern.MatchResult + rewriter.pattern.ValuePattern + rewriter.pattern.NodePattern + rewriter.pattern.NodeOutputPattern + rewriter.pattern.AnyValue + rewriter.pattern.Constant + rewriter.pattern.GraphPattern + rewriter.pattern.ReplacementSubgraph + rewriter.pattern.ReplacementPatternFunction + rewriter.pattern.PatternMatcher + rewriter.pattern.SimplePatternMatcher + rewriter.pattern.RewriteRule + rewriter.pattern.RewriteRuleAsClass + rewriter.pattern.RewriteRuleSet + rewriter.pattern.MatchStatus + rewriter.pattern.MatchInfo + rewriter.pattern.MatchingTracer +``` diff --git a/docs/api/tools.md b/docs/api/tools.md deleted file mode 100644 index 9f565d613c..0000000000 --- a/docs/api/tools.md +++ /dev/null @@ -1,19 +0,0 @@ -# Tools - -## Transformers Models - -```{eval-rst} -.. autofunction:: onnxscript.tools.transformers_models.get_model_and_inputs -``` - -```{eval-rst} -.. autofunction:: onnxscript.tools.transformers_models.phi.get_phi_model_from_config -``` - -```{eval-rst} -.. autofunction:: onnxscript.tools.transformers_models.phi3.get_phi3_model_from_config -``` - -```{eval-rst} -.. autofunction:: onnxscript.tools.transformers_models.llama.get_llama_model_from_config -``` diff --git a/docs/api/version_converter.md b/docs/api/version_converter.md new file mode 100644 index 0000000000..0478efbf5a --- /dev/null +++ b/docs/api/version_converter.md @@ -0,0 +1,28 @@ +# onnxscript.version_converter + +```{eval-rst} +.. automodule::onnxscript.version_converter +.. currentmodule:: onnxscript +``` + +## Functions + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: functiontemplate.rst + :nosignatures: + + version_converter.convert_version +``` + +## IR passes + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: classtemplate.rst + :nosignatures: + + version_converter.ConvertVersionPass +``` diff --git a/docs/index.md b/docs/index.md index 3cd5e3db30..4dd0472706 100644 --- a/docs/index.md +++ b/docs/index.md @@ -103,7 +103,7 @@ result = MatmulAdd(x, wt, bias) Overview tutorial/index api/index -intermediate_representation/index +ir/index auto_examples/index articles/index ``` diff --git a/docs/intermediate_representation/getting_started.ipynb b/docs/ir/getting_started.ipynb similarity index 100% rename from docs/intermediate_representation/getting_started.ipynb rename to docs/ir/getting_started.ipynb diff --git a/docs/intermediate_representation/index.md b/docs/ir/index.md similarity index 98% rename from docs/intermediate_representation/index.md rename to docs/ir/index.md index 0088d5ebeb..807dbddb51 100644 --- a/docs/intermediate_representation/index.md +++ b/docs/ir/index.md @@ -19,6 +19,5 @@ An in-memory IR that supports the full ONNX spec, designed for graph constructio getting_started tensors -ir_api -generated +ir_api/index ``` diff --git a/docs/intermediate_representation/ir_api.md b/docs/ir/ir_api/core.md similarity index 67% rename from docs/intermediate_representation/ir_api.md rename to docs/ir/ir_api/core.md index 0ae18f7453..c612bb13c9 100644 --- a/docs/intermediate_representation/ir_api.md +++ b/docs/ir/ir_api/core.md @@ -2,23 +2,40 @@ ```{eval-rst} .. automodule::onnxscript.ir +.. currentmodule:: onnxscript ``` -## IR objects +## Functions and constructors ```{eval-rst} -.. currentmodule:: onnxscript .. autosummary:: :toctree: generated + :template: functiontemplate.rst :nosignatures: - :template: classtemplate.rst - ir.Model + ir.load + ir.save + ir.from_proto + ir.to_proto + ir.tensor + ir.node +``` + +## Classes + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: classtemplate_inherited.rst + :nosignatures: + + ir.TensorProtocol + ir.Value + ir.Node ir.Graph + ir.Model ir.GraphView ir.Function - ir.Node - ir.Value ir.Attr ir.RefAttr ir.Shape @@ -38,8 +55,8 @@ ```{eval-rst} .. autosummary:: :toctree: generated - :nosignatures: :template: classtemplate.rst + :nosignatures: ir.DataType ir.AttributeType diff --git a/docs/ir/ir_api/index.md b/docs/ir/ir_api/index.md new file mode 100644 index 0000000000..c8ed762621 --- /dev/null +++ b/docs/ir/ir_api/index.md @@ -0,0 +1,13 @@ +# IR APIs + +```{toctree} +:maxdepth: 1 + +core +ir_convenience +ir_external_data +ir_passes +ir_passes_common +ir_traversal +ir_tape +``` diff --git a/docs/ir/ir_api/ir_convenience.md b/docs/ir/ir_api/ir_convenience.md new file mode 100644 index 0000000000..77f09bfe81 --- /dev/null +++ b/docs/ir/ir_api/ir_convenience.md @@ -0,0 +1,15 @@ +# ir.convenience + +```{eval-rst} +.. automodule::onnxscript.ir.convenience +.. currentmodule:: onnxscript.ir.convenience +``` + + +```{eval-rst} +.. autofunction:: convert_attribute +.. autofunction:: convert_attributes +.. autofunction:: replace_all_uses_with +.. autofunction:: replace_nodes_and_values +.. autofunction:: create_value_mapping +``` diff --git a/docs/ir/ir_api/ir_external_data.md b/docs/ir/ir_api/ir_external_data.md new file mode 100644 index 0000000000..faf34514f1 --- /dev/null +++ b/docs/ir/ir_api/ir_external_data.md @@ -0,0 +1,20 @@ +# ir.external_data + +```{eval-rst} +.. automodule::onnxscript.ir.external_data +.. currentmodule:: onnxscript.ir.external_data +``` + +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. + +## Functions + +```{eval-rst} +.. autofunction:: load_to_model +.. autofunction:: unload_from_model +.. autofunction:: convert_tensors_to_external +.. autofunction:: convert_tensors_from_external +.. autofunction:: set_base_dir +``` + + diff --git a/docs/ir/ir_api/ir_passes.md b/docs/ir/ir_api/ir_passes.md new file mode 100644 index 0000000000..ba759a0aee --- /dev/null +++ b/docs/ir/ir_api/ir_passes.md @@ -0,0 +1,39 @@ +# ir.passes + +```{eval-rst} +.. automodule::onnxscript.ir.passes +.. currentmodule:: onnxscript +``` + +## Use built-in passes + +Common, reusable passes are implemented in `ir.passes.common`. You can use {py:class}`ir.passes.Sequential ` to chain passes or use {py:class}`ir.passes.PassManager ` which supports early stopping if no changes are made. + +## Pass infrastructure + +Inherent {py:class}`ir.passes.InPlacePass ` or {py:class}`ir.passes.FunctionalPass ` to define a pass. You will need to implement the `call` method which returns a {py:class}`ir.passes.PassResult `. + +Alternatively, inherent the base class `ir.passes.PassBase ` and override the two properties `changes_input` and `in_place` to set properties of the pass. + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: classtemplate.rst + :nosignatures: + + ir.passes.PassBase + ir.passes.InPlacePass + ir.passes.FunctionalPass + ir.passes.Sequential + ir.passes.PassResult + ir.passes.PassManager +``` + +## Errors + +```{eval-rst} +.. autoexception:: onnxscript.ir.passes.InvariantError +.. autoexception:: onnxscript.ir.passes.PreconditionError +.. autoexception:: onnxscript.ir.passes.PostconditionError +.. autoexception:: onnxscript.ir.passes.PassError +``` diff --git a/docs/ir/ir_api/ir_passes_common.md b/docs/ir/ir_api/ir_passes_common.md new file mode 100644 index 0000000000..695dc21950 --- /dev/null +++ b/docs/ir/ir_api/ir_passes_common.md @@ -0,0 +1,25 @@ +# ir.passes.common + +```{eval-rst} +.. currentmodule:: onnxscript +``` + +## Built-in passes + + +```{eval-rst} +.. autosummary:: + :toctree: generated + :template: classtemplate.rst + :nosignatures: + + ir.passes.common.unused_removal.RemoveUnusedNodesPass + ir.passes.common.unused_removal.RemoveUnusedFunctionsPass + ir.passes.common.unused_removal.RemoveUnusedOpsetsPass + ir.passes.common.inliner.InlinePass + ir.passes.common.topological_sort.TopologicalSortPass + ir.passes.common.constant_manipulation.LiftConstantsToInitializersPass + ir.passes.common.shape_inference.ShapeInferencePass + ir.passes.common.onnx_checker.CheckerPass + ir.passes.common.clear_metadata_and_docstring.ClearMetadataAndDocStringPass +``` diff --git a/docs/ir/ir_api/ir_tape.md b/docs/ir/ir_api/ir_tape.md new file mode 100644 index 0000000000..bdfa83d673 --- /dev/null +++ b/docs/ir/ir_api/ir_tape.md @@ -0,0 +1,18 @@ +# ir.tape + +```{eval-rst} +.. automodule:: onnxscript.ir.tape +.. currentmodule:: onnxscript.ir.tape +``` + +The `ir.tape` module provides utilities for recording nodes and initializers to construct computational graphs or functions. + +## The `Tape` class + +The `Tape` class is a recorder that collects nodes and initializers created during the construction of a graph or function. It supports creating nodes with single or multiple outputs and registering initializers. + +```{eval-rst} +.. autoclass:: Tape + :members: + :undoc-members: +``` diff --git a/docs/ir/ir_api/ir_traversal.md b/docs/ir/ir_api/ir_traversal.md new file mode 100644 index 0000000000..fcb1b6aac7 --- /dev/null +++ b/docs/ir/ir_api/ir_traversal.md @@ -0,0 +1,13 @@ +# ir.traversal + +```{eval-rst} +.. automodule:: onnxscript.ir.traversal +.. currentmodule:: onnxscript.ir.traversal +``` + +```{eval-rst} +.. autoclass:: RecursiveGraphIterator + :members: + :undoc-members: + :special-members: +``` diff --git a/docs/intermediate_representation/tensors.md b/docs/ir/tensors.md similarity index 100% rename from docs/intermediate_representation/tensors.md rename to docs/ir/tensors.md diff --git a/onnxscript/ir/_convenience/__init__.py b/onnxscript/ir/_convenience/__init__.py index 8da5c5b8d2..0addc9da2f 100644 --- a/onnxscript/ir/_convenience/__init__.py +++ b/onnxscript/ir/_convenience/__init__.py @@ -107,7 +107,7 @@ def convert_attribute( A ``Attr`` object. Raises: - ValueError: If :param:`attr` is ``None`` and :param:`attr_type` is not provided. + ValueError: If ``attr`` is ``None`` and ``attr_type`` is not provided. TypeError: If the type of the attribute is not supported. """ if attr is None: diff --git a/onnxscript/ir/_core.py b/onnxscript/ir/_core.py index aa10098cbd..58dad2e6bb 100644 --- a/onnxscript/ir/_core.py +++ b/onnxscript/ir/_core.py @@ -333,7 +333,7 @@ def __init__( value: The backing data of the tensor. It can be a numpy array compatible object or a DLPack compatible object. When the dtype is not one of the numpy native dtypes, the value needs to be ``uint8`` for 4-bit and 8-bit data types, and ``uint16`` for bfloat16 - when the value is a numpy array; :param:`dtype` must be specified in this case. + when the value is a numpy array; ``dtype`` must be specified in this case. dtype: The data type of the tensor. It can be None only when value is a numpy array. Users are responsible for making sure the dtype matches the value when value is not a numpy array. shape: The shape of the tensor. If None, the shape is obtained from the value. diff --git a/onnxscript/ir/_io.py b/onnxscript/ir/_io.py index 0d07992901..a83cfdbd9d 100644 --- a/onnxscript/ir/_io.py +++ b/onnxscript/ir/_io.py @@ -47,7 +47,7 @@ def save( """Save an ONNX model to a file. The model remains unchanged after the call. If any existing external tensor - references the provided :param:`external_data` path, it will be invalidated + references the provided ``external_data`` path, it will be invalidated after the external data is overwritten. To obtain a valid model, use :func:`load` to load the newly saved model, or provide a different external data path that is not currently referenced by any tensors in the model. @@ -64,7 +64,7 @@ def save( with the same external information; if the tensor is not external, it will be serialized in the ONNX Proto message. size_threshold_bytes: Save to external data if the tensor size in bytes is larger than this threshold. - Effective only when :param:`external_data` is set. + Effective only when ``external_data`` is set. Raises: ValueError: If the external data path is an absolute path. diff --git a/onnxscript/ir/_tape.py b/onnxscript/ir/_tape.py index 0a63118d4f..340142df3d 100644 --- a/onnxscript/ir/_tape.py +++ b/onnxscript/ir/_tape.py @@ -26,6 +26,7 @@ class Tape: that they can be used for creating a graph. Example:: + from onnxscript import ir tape = ir.tape.Tape() diff --git a/onnxscript/ir/external_data.py b/onnxscript/ir/external_data.py index 87524899fd..4ca9ca5036 100644 --- a/onnxscript/ir/external_data.py +++ b/onnxscript/ir/external_data.py @@ -341,7 +341,7 @@ def unload_from_model( and not make any other modifications to the model. If any existing external tensor - references the provided :param:`external_data` path, it will be invalidated + references the provided ``external_data`` path, it will be invalidated after the external data is overwritten. To obtain a valid model, use :func:`load` to load the newly saved model, or provide a different external data path that is not currently referenced by any tensors in the model. @@ -354,7 +354,7 @@ def unload_from_model( size_threshold_bytes: Save to external data if the tensor size in bytes is larger than this threshold. Returns: - An ir.Model with all initializer data equal or above :param:`size_threshold_bytes` + An ir.Model with all initializer data equal or above ``size_threshold_bytes`` converted to external tensors. """ # In-memory or external tensors, if equal to or above the threshold, should be converted to or re-saved as external tensors diff --git a/onnxscript/ir/passes/common/__init__.py b/onnxscript/ir/passes/common/__init__.py new file mode 100644 index 0000000000..c211572fd4 --- /dev/null +++ b/onnxscript/ir/passes/common/__init__.py @@ -0,0 +1,32 @@ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. + +__all__ = [ + "clear_metadata_and_docstring", + "constant_manipulation", + "inliner", + "onnx_checker", + "shape_inference", + "topological_sort", + "unused_removal", +] + +from onnxscript.ir.passes.common import ( + clear_metadata_and_docstring, + constant_manipulation, + inliner, + onnx_checker, + shape_inference, + topological_sort, + unused_removal, +) + + +def __set_module() -> None: + """Set the module of all functions in this module to this public module.""" + global_dict = globals() + for name in __all__: + global_dict[name].__module__ = __name__ + + +__set_module()