Skip to content

T
tic
Unverified Commit d2ae8c95 by Tianqi Chen Committed by GitHub
Options

[DOCS] Update API docs to reflect the status after the refactor. (#4907)

parent 41835d17
Showing with 122 additions and 333 deletions
docs/_static/css/tvm_theme.css
......@@ -38,3 +38,6 @@ nav .hidden-section {
color: #404040 !important;
}
.wy-nav-content {
max-width: 950px !important;
}
docs/api/python/dev.rst deleted 100644 → 0
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
.. http://www.apache.org/licenses/LICENSE-2.0
.. Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
Developer API
-------------
This page contains modules that are used by developers of TVM.
Many of these APIs are PackedFunc registered in C++ backend.
tvm.expr
~~~~~~~~
.. automodule:: tvm.expr
:members:
:undoc-members:
tvm.codegen
~~~~~~~~~~~
.. automodule:: tvm.codegen
:members:
:undoc-members:
tvm.stmt
~~~~~~~~
.. automodule:: tvm.stmt
:members:
:undoc-members:
tvm.ir_pass
~~~~~~~~~~~
.. autosummary::
tvm.ir_pass.Inline
tvm.ir_pass.Simplify
tvm.ir_pass.ConvertSSA
tvm.ir_pass.VerifySSA
tvm.ir_pass.CanonicalSimplify
tvm.ir_pass.StorageFlatten
tvm.ir_pass.VectorizeLoop
tvm.ir_pass.SkipVectorize
tvm.ir_pass.UnrollLoop
tvm.ir_pass.ThreadSync
tvm.ir_pass.StorageRewrite
tvm.ir_pass.MakeAPI
tvm.ir_pass.SplitHostDevice
tvm.ir_pass.InjectVirtualThread
tvm.ir_pass.LoopPartition
tvm.ir_pass.RemoveNoOp
tvm.ir_pass.SplitPipeline
tvm.ir_pass.LowerThreadAllreduce
tvm.ir_pass.LowerIntrin
tvm.ir_pass.LowerTVMBuiltin
tvm.ir_pass.NarrowChannelAccess
.. automodule:: tvm.ir_pass
:members:
tvm.ir_builder
~~~~~~~~~~~~~~
.. automodule:: tvm.ir_builder
:members:
tvm.make
~~~~~~~~
.. automodule:: tvm.make
:members:
docs/api/python/build.rst → docs/api/python/driver.rst
......@@ -15,10 +15,10 @@
specific language governing permissions and limitations
under the License.
tvm.build
---------
tvm.driver
----------
.. automodule:: tvm.driver
.. autofunction:: tvm.lower
.. autofunction:: tvm.build
.. autofunction:: tvm.build_config
docs/api/python/error.rst
......@@ -20,3 +20,4 @@ tvm.error
.. automodule:: tvm.error
:members:
:imported-members:
:autosummary:
docs/api/python/hybrid.rst
......@@ -18,11 +18,6 @@
tvm.hybrid
----------
.. automodule:: tvm.hybrid
.. autosummary::
tvm.hybrid.parse
tvm.hybrid.script
.. autofunction:: tvm.hybrid.parse
.. autofunction:: tvm.hybrid.script
:members:
:imported-members:
:autosummary:
docs/api/python/index.rst
......@@ -21,23 +21,19 @@ Python API
.. toctree::
:maxdepth: 2
tvm
runtime
ndarray
error
ir
target
intrin
tensor
schedule
build
function
tir
te
driver
autotvm
rpc
contrib
graph_runtime
dev
topi
vta/index
hybrid
relay/index
vta/index
topi
docs/api/python/intrin.rst deleted 100644 → 0
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
.. http://www.apache.org/licenses/LICENSE-2.0
.. Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
tvm.intrin
----------
.. automodule:: tvm.intrin
.. autosummary::
tvm.call_packed
tvm.call_pure_intrin
tvm.call_intrin
tvm.call_pure_extern
tvm.call_extern
tvm.call_llvm_intrin
tvm.register_intrin_rule
tvm.if_then_else
tvm.exp
tvm.log
tvm.floor
tvm.ceil
tvm.trunc
tvm.round
tvm.nearbyint
tvm.abs
tvm.isnan
.. autofunction:: tvm.call_packed
.. autofunction:: tvm.call_pure_intrin
.. autofunction:: tvm.call_intrin
.. autofunction:: tvm.call_pure_extern
.. autofunction:: tvm.call_extern
.. autofunction:: tvm.call_llvm_intrin
.. autofunction:: tvm.register_intrin_rule
.. autofunction:: tvm.if_then_else
.. autofunction:: tvm.exp
.. autofunction:: tvm.log
.. autofunction:: tvm.floor
.. autofunction:: tvm.ceil
.. autofunction:: tvm.trunc
.. autofunction:: tvm.round
.. autofunction:: tvm.nearbyint
.. autofunction:: tvm.abs
.. autofunction:: tvm.isnan
docs/api/python/ir.rst
......@@ -20,3 +20,4 @@ tvm.ir
.. automodule:: tvm.ir
:members:
:imported-members:
:autosummary:
docs/api/python/ndarray.rst
......@@ -23,14 +23,5 @@ tvm.runtime.ndarray
:members:
:inherited-members:
.. autoclass:: tvm.runtime.TVMContext
:members:
.. autofunction:: tvm.context
.. autofunction:: tvm.cpu
.. autofunction:: tvm.gpu
.. autofunction:: tvm.opencl
.. autofunction:: tvm.metal
.. autofunction:: tvm.nd.array
.. autofunction:: tvm.nd.empty
docs/api/python/relay/index.rst
......@@ -15,7 +15,7 @@
specific language governing permissions and limitations
under the License.
Relay API
tvm.relay
=========
This document contains the Python API for the Relay frontend, optimizer, and
......@@ -35,9 +35,7 @@ compiler stack.
image
analysis
transform
module
nn
op
scope_builder
ty
vision
docs/api/python/relay/ty.rst deleted 100644 → 0
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
.. http://www.apache.org/licenses/LICENSE-2.0
.. Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
tvm.relay.ty
------------
.. automodule:: tvm.relay.ty
:members:
.. autoclass:: tvm.relay.ty.Type
:members:
.. autoclass:: tvm.relay.ty.TensorType
:members:
.. autoclass:: tvm.relay.ty.Kind
:members:
.. autoclass:: tvm.relay.ty.TypeVar
:members:
.. autoclass:: tvm.relay.ty.TypeConstraint
:members:
.. autoclass:: tvm.relay.ty.TupleType
:members:
.. autoclass:: tvm.relay.ty.FuncType
:members:
.. autoclass:: tvm.relay.ty.IncompleteType
:members:
.. autoclass:: tvm.relay.ty.TypeRelation
:members:
docs/api/python/rpc.rst
......@@ -18,22 +18,6 @@
tvm.rpc
-------
.. automodule:: tvm.rpc
.. autofunction:: tvm.rpc.connect
.. autofunction:: tvm.rpc.connect_tracker
.. autoclass:: tvm.rpc.TrackerSession
:members:
:inherited-members:
.. autoclass:: tvm.rpc.RPCSession
:members:
:inherited-members:
.. autoclass:: tvm.rpc.LocalSession
:members:
:inherited-members:
.. autoclass:: tvm.rpc.Server
:members:
:inherited-members:
:members:
:imported-members:
:autosummary:
docs/api/python/runtime.rst
......@@ -19,6 +19,11 @@ tvm.runtime
-----------
.. automodule:: tvm.runtime
:members:
:imported-members:
:exclude-members: NDArray
:autosummary:
.. autoclass:: tvm.runtime.PackedFunc
:members:
......
docs/api/python/target.rst
......@@ -20,3 +20,4 @@ tvm.target
.. automodule:: tvm.target
:members:
:imported-members:
:autosummary:
docs/api/python/schedule.rst → docs/api/python/te.rst
......@@ -15,22 +15,16 @@
specific language governing permissions and limitations
under the License.
tvm.schedule
------------
.. automodule:: tvm.schedule
.. autoclass:: tvm.schedule.IterVar
:members:
.. autoclass:: tvm.schedule.Buffer
:members:
.. autofunction:: tvm.create_schedule
.. autoclass:: tvm.schedule.Schedule
:members:
:inherited-members:
.. autoclass:: tvm.schedule.Stage
:members:
:inherited-members:
tvm.te
------
.. Exclude the ops imported from tir.
.. automodule:: tvm.te
:members:
:imported-members:
:exclude-members:
exp, erf, tanh, sigmoid, log, cos, sin, atan, sqrt, rsqrt, floor, ceil,
trunc, abs, round, nearbyint, isnan, power, popcount, fmod, if_then_else,
div, indexdiv, indexmod, truncdiv, truncmod, floordiv, floormod,
comm_reducer, min, max, sum
:autosummary:
docs/api/python/relay/module.rst → docs/api/python/tir.rst
......@@ -15,10 +15,10 @@
specific language governing permissions and limitations
under the License.
tvm.relay.module
----------------
.. automodule:: tvm.relay.module
.. autoclass:: tvm.relay.module.Module
:members:
tvm.tir
-------
.. automodule:: tvm.tir
:members:
:imported-members:
:exclude-members: PrimExpr
:autosummary:
docs/api/python/topi.rst
......@@ -15,7 +15,7 @@
specific language governing permissions and limitations
under the License.
TOPI
topi
----
.. automodule:: topi
......
docs/api/python/vta/index.rst
......@@ -15,8 +15,8 @@
specific language governing permissions and limitations
under the License.
VTA API
=======
vta
===
This document contains the python API to VTA compiler toolchain.
......
docs/conf.py
......@@ -49,9 +49,9 @@ sys.path.insert(0, os.path.join(curr_path, '../vta/python'))
# General information about the project.
project = u'tvm'
author = u'%s developers' % project
copyright = u'2018, %s' % author
github_doc_root = 'https://github.com/tqchen/tvm/tree/master/docs/'
author = u'Apache Software Foundation'
copyright = u'2019, %s' % author
github_doc_root = 'https://github.com/apache/incubator-tvm/tree/master/docs/'
# add markdown parser
CommonMarkParser.github_doc_root = github_doc_root
......@@ -73,6 +73,7 @@ extensions = [
'sphinx.ext.napoleon',
'sphinx.ext.mathjax',
'sphinx_gallery.gen_gallery',
'autodocsumm'
]
breathe_projects = {'tvm' : 'doxygen/xml/'}
......@@ -139,9 +140,6 @@ pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# sort autodoc order by the source file.
autodoc_member_order = 'bysource'
# -- Options for HTML output ----------------------------------------------
# The theme is set by the make target
......@@ -199,9 +197,9 @@ def run_doxygen(folder):
intersphinx_mapping = {
'python': ('https://docs.python.org/{.major}'.format(sys.version_info), None),
'numpy': ('http://docs.scipy.org/doc/numpy/', None),
'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
'matplotlib': ('http://matplotlib.org/', None),
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
'matplotlib': ('https://matplotlib.org/', None),
}
from sphinx_gallery.sorting import ExplicitOrder
......@@ -242,8 +240,8 @@ sphinx_gallery_conf = {
'doc_module': ('tvm', 'numpy'),
'reference_url': {
'tvm': None,
'matplotlib': 'http://matplotlib.org',
'numpy': 'http://docs.scipy.org/doc/numpy-1.9.1'},
'matplotlib': 'https://matplotlib.org/',
'numpy': 'https://docs.scipy.org/doc/numpy/'},
'examples_dirs': examples_dirs,
'gallery_dirs': gallery_dirs,
'subsection_order': subsection_order,
......@@ -251,3 +249,7 @@ sphinx_gallery_conf = {
'find_mayavi_figures': False,
'expected_failing_examples': []
}
autodoc_default_options = {
'member-order': 'bysource',
}
docs/contribute/committer_guide.rst
......@@ -59,7 +59,7 @@ Here are some example applications of this principle:
Shepherd a Pull Request
----------------------
-----------------------
Here are some tips to shepherd a pull request.
You can also take a look at the :ref:`code_review_guide`.
......
docs/contribute/error_handling.rst
......@@ -15,25 +15,27 @@
specific language governing permissions and limitations
under the License.
.. _error_guide:
.. _error-handling-guide:
Error Handling Guide
====================
TVM contains structured error classes to indicate specific types of error.
Please raise a specific error type when possible, so that users can
write code to handle a specific error category if necessary.
All the error types are defined in :any:`tvm.error` namespace.
You can directly raise the specific error object in python.
In other languages like c++, you simply add ``<ErrorType>:`` prefix to
the error message(see below).
.. note::
Please refer to :py:mod:`tvm.error` for the list of errors.
Raise a Specific Error in C++
-----------------------------
You can add ``<ErrorType>:`` prefix to your error message to
raise an error of the corresponding type.
Note that you do not have to add a new type
:any:`tvm.error.TVMError` will be raised by default when
:py:class:`tvm.error.TVMError` will be raised by default when
there is no error type prefix in the message.
This mechanism works for both ``LOG(FATAL)`` and ``CHECK`` macros.
The following code gives an example on how to do so.
......@@ -55,7 +57,7 @@ Here is what will happen if we call the registered function:
.. code::
>>> import tvm
>>> tvm._api_internal._ErrorTest(0, 1)
>>> tvm.testing.ErrorTest(0, 1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/path/to/tvm/python/tvm/_ffi/_ctypes/function.py", line 190, in __call__
......@@ -68,7 +70,7 @@ Here is what will happen if we call the registered function:
File "/path/to/tvm/src/api/api_test.cc", line 80
ValueError: Check failed: x == y (0 vs. 1) : expect x and y to be equal.
>>>
>>> tvm._api_internal._ErrorTest(1, 1)
>>> tvm.testing.ErrorTest(1, 1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/path/to/tvm/python/tvm/_ffi/_ctypes/function.py", line 190, in __call__
......@@ -95,7 +97,7 @@ We try to keep a reasonable amount of error types.
If you feel there is a need to add a new error type, do the following steps:
- Send a RFC proposal with a description and usage examples in the current codebase.
- Add the new error type to :any:`tvm.error` with clear documents.
- Add the new error type to :py:mod:`tvm.error` with clear documents.
- Update the list in this file to include the new error type.
- Change the code to use the new error type.
......@@ -118,22 +120,3 @@ error messages when necessary.
If we need to introduce a wrapper function that constructs multi-line error messages,
please put wrapper in the same file so other developers can look up the implementation easily.
System-wide Errors
------------------
.. autoclass:: tvm.error.TVMError
.. autoclass:: tvm.error.InternalError
Frontend Errors
---------------
.. autoclass:: tvm.error.OpNotImplemented
.. autoclass:: tvm.error.OpAttributeInvalid
.. autoclass:: tvm.error.OpAttributeRequired
.. autoclass:: tvm.error.OpAttributeNotImplemented
docs/dev/runtime.rst
......@@ -183,7 +183,7 @@ RPC server on iPhone/android/raspberry pi or even the browser. The cross compila
This instant feedback gives us a lot of advantages. For example, to test the correctness of generated code on iPhone, we no longer have to write test-cases in swift/objective-c from scratch -- We can use RPC to execute on iPhone, copy the result back and do verification on the host via numpy. We can also do the profiling using the same script.
TVM Object and Compiler Stack
---------------------------
-----------------------------
As we mentioned earlier, we build compiler stack API on top of the PackedFunc runtime system.
We faced a constant changing of the compiler API for the need of research. We need a new language object or IR node whenever we want to test out new primitives.
......
python/tvm/autotvm/tuner/xgboost_tuner.py
......@@ -37,28 +37,32 @@ class XGBTuner(ModelBasedTuner):
Note on choosing feature type:
For single task tuning, 'itervar' and 'knob' are good.
'itervar' is more accurate but 'knob' is much faster.
There are some constraints on 'itervar', if you meet
problems with feature extraction when using 'itervar',
you can switch to 'knob'.
'itervar' is more accurate but 'knob' is much faster.
There are some constraints on 'itervar', if you meet
problems with feature extraction when using 'itervar',
you can switch to 'knob'.
For cross-shape tuning (e.g. many convolutions with different shapes),
'itervar' and 'curve' has better transferability,
'knob' is faster.
'itervar' and 'curve' has better transferability,
'knob' is faster.
For cross-device or cross-operator tuning, you can use 'curve' only.
loss_type: str
If is 'reg', use regression loss to train cost model.
The cost model predicts the normalized flops.
The cost model predicts the normalized flops.
If is 'rank', use pairwise rank loss to train cost model.
The cost model predicts relative rank score.
The cost model predicts relative rank score.
num_threads: int, optional
The number of threads. optimizer: str or ModelOptimizer, optional
If is 'sa', use a default simulated annealing optimizer.
Otherwise it should be a ModelOptimizer object.
diversity_filter_ratio: int or float, optional
If is not None, the tuner will first select
top-(plan_size * diversity_filter_ratio) candidates according to the cost model
and then pick batch_size of them according to the diversity metric.
log_interval: int, optional
The verbose level.
If is 0, output nothing.
......
python/tvm/contrib/graph_runtime.py
......@@ -25,19 +25,23 @@ from ..rpc import base as rpc_base
def create(graph_json_str, libmod, ctx):
"""Create a runtime executor module given a graph and module.
Parameters
----------
graph_json_str : str or graph class
The graph to be deployed in json format output by json graph.
The graph can only contain one operator(tvm_op) that
points to the name of PackedFunc in the libmod.
libmod : tvm.Module
libmod : tvm.runtime.Module
The module of the corresponding function
ctx : TVMContext or list of TVMContext
The context to deploy the module. It can be local or remote when there
is only one TVMContext. Otherwise, the first context in the list will
be used as this purpose. All context should be given for heterogeneous
execution.
Returns
-------
graph_module : GraphModule
......@@ -61,11 +65,14 @@ def create(graph_json_str, libmod, ctx):
def get_device_ctx(libmod, ctx):
"""Parse and validate all the device context(s).
Parameters
----------
libmod : tvm.Module
libmod : tvm.runtime.Module
The module of the corresponding function
ctx : TVMContext or list of TVMContext
Returns
-------
ctx : list of TVMContext
......@@ -113,12 +120,12 @@ class GraphModule(object):
Parameters
----------
module : Module
module : tvm.runtime.Module
The internal tvm module that holds the actual graph functions.
Attributes
----------
module : Module
module : tvm.runtime.Module
The internal tvm module that holds the actual graph functions.
"""
......
python/tvm/error.py
......@@ -20,6 +20,10 @@ Each error class takes an error message as its input.
See the example sections for for suggested message conventions.
To make the code more readable, we recommended developers to
copy the examples and raise errors with the same message convention.
.. note::
Please also refer to :ref:`error-handling-guide`.
"""
from tvm._ffi.base import register_error, TVMError
......
python/tvm/relay/op/nn/nn.py
......@@ -1424,10 +1424,12 @@ def batch_norm(data,
Besides the inputs and the outputs, this operator accepts two auxiliary
states, ``moving_mean`` and ``moving_var``, which are *k*-length
vectors. They are global statistics for the whole dataset, which are updated by::
vectors. They are global statistics for the whole dataset, which are updated by
moving_mean = moving_mean * momentum + data_mean * (1 - momentum)
moving_var = moving_var * momentum + data_var * (1 - momentum)
.. code:: python
moving_mean = moving_mean * momentum + data_mean * (1 - momentum)
moving_var = moving_var * momentum + data_var * (1 - momentum)
The parameter ``axis`` specifies which axis of the input shape denotes
the 'channel' (separately normalized groups). The default is 1.
......
python/tvm/relay/op/tensor.py
......@@ -847,6 +847,7 @@ def clip(a, a_min, a_max):
Examples
--------
.. code:: python
x = relay.Constant(tvm.nd.array([0, 1, 5, 3, 4, 2]))
relay.clip(x, 1., 4.)
# [1, 1, 4, 3, 4, 2]
......
python/tvm/target/__init__.py
......@@ -51,7 +51,7 @@ The list of options include:
It is useful in environments where dynamic loading api like dlopen is banned.
The system lib will be available as long as the result code is linked by the program.
We can use :py:func:`~tvm.target.create` to create a tvm.target.Target from the target string.
We can use :py:func:`tvm.target.create` to create a tvm.target.Target from the target string.
We can also use other specific function in this module to create specific targets.
"""
from .target import Target, create
......
python/tvm/target/target.py
......@@ -30,12 +30,12 @@ class Target(Object):
----
Do not use class constructor, you can create target using the following functions
- :py:func:`~tvm.target.create` create target from string
- :py:func:`~tvm.target.arm_cpu` create arm_cpu target
- :py:func:`~tvm.target.cuda` create CUDA target
- :py:func:`~tvm.target.rocm` create ROCM target
- :py:func:`~tvm.target.mali` create Mali target
- :py:func:`~tvm.target.intel_graphics` create Intel Graphics target
- :py:func:`tvm.target.create` create target from string
- :py:func:`tvm.target.arm_cpu` create arm_cpu target
- :py:func:`tvm.target.cuda` create CUDA target
- :py:func:`tvm.target.rocm` create ROCM target
- :py:func:`tvm.target.mali` create Mali target
- :py:func:`tvm.target.intel_graphics` create Intel Graphics target
"""
def __new__(cls):
# Always override new to enable class
......@@ -262,7 +262,7 @@ def create(target_str):
Note
----
See the note on :py:mod:`~tvm.target` on target string format.
See the note on :py:mod:`tvm.target` on target string format.
"""
if isinstance(target_str, Target):
return target_str
......
python/tvm/te/__init__.py
......@@ -15,12 +15,16 @@
# specific language governing permissions and limitations
# under the License.
# pylint: disable=unused-import, redefined-builtin, wildcard-import
"""Namespace for Tensor-level IR"""
"""Namespace for Tensor Expression Language
"""
# expose all operators in tvm tir.op
from tvm.tir.op import *
from tvm.tir import exp, erf, tanh, sigmoid, log, cos, sin, atan, sqrt, rsqrt, floor, ceil
from tvm.tir import trunc, abs, round, nearbyint, isnan, power, popcount, fmod, if_then_else
from tvm.tir import div, indexdiv, indexmod, truncdiv, truncmod, floordiv, floormod
from tvm.tir import comm_reducer, min, max, sum
from .schedule import Schedule, create_schedule
from .tensor import TensorSlice, Tensor
from .tensor import Tensor
from .tensor_intrin import decl_tensor_intrin
from .tag import tag_scope
from .operation import placeholder, compute, scan, extern, var, size_var
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment