[DOC][Relay]: Add API docs for Relay. #1750

jroesch · 2018-09-21T06:42:44Z

This PR comprises the work I did on docs for Relay in the initial PR #1672.

This adds a first pass at the language reference as well as extended documentation for the Python API docs, and some tutorials.

@slyubomirsky will follow up with the language reference pieces of the documentation, this will just contain the API docs.

tqchen

Some stylish issues on restructured text that we might need to fix

tqchen · 2018-09-21T06:44:58Z

docs/api/python/relay/op.rst

@@ -0,0 +1,3 @@
+tvm.relay.op
+-----------


rst requires the underline to havethe same length as the title

tqchen · 2018-09-21T06:46:01Z

docs/langref/relay/expressions.rst

@@ -0,0 +1,161 @@
+==================
+Expressions
+==================


underline need to have the same length of the title.

First Level ======= second level -------------- third level ~~~~~~~ ```

MarisaKirisame · 2018-09-21T06:47:39Z

docs/langref/relay/expressions.rst

+
+.. code-block:: python
+    if (sum(equal(t, u))) {
+        jreturn x:


jreturn -> return

jroesch · 2018-09-21T06:50:09Z

@joshpoll @weberlo @MarisaKirisame @slyubomirsky could you guys take passes over the content. I am going to fix/clean up things which changed between last week and the final PR.

tqchen · 2018-09-21T06:50:21Z

@junrushao1994 @zhiics @yzhliu @ZihengJiang please review

docs/langref/relay/expressions.rst

MarisaKirisame · 2018-09-21T07:02:41Z

docs/langref/relay/intro.rst

+Relay is differentiable programming language with support for
+closures, control-flow, and recursion. It has an advanced
+static type system specifically designed for programs written
+by machine  learning practioniers and researchers.


extra whitespace

MarisaKirisame · 2018-09-21T07:04:40Z

docs/langref/relay/type_system.rst

+
+The shape may be any valid Relay shape as described in the below
+section on shapes.
+


MarisaKirisame · 2018-09-21T07:05:04Z

docs/langref/relay/type_system.rst

+
+See :py:class:`~tvm.relay.type.IncompleteType` for its definition and documentation.
+
+


MarisaKirisame · 2018-09-21T07:06:05Z

tutorials/relay/implement_fma_transform.py

+np.testing.assert_allclose(norm_out, xform_out)
+
+# Use the TVM runtime.
+


zhiics · 2018-09-21T16:22:00Z

docs/langref/relay/intro.rst

+a directed acyclic graph of primitive functions.
+
+This may be a useful way to describe early ML models, but is
+limited onceyou want to generalize to dynamic models.


s/onceyou/once you

zhiics · 2018-09-21T16:23:30Z

docs/langref/relay/intro.rst

+for compiler optimizations is essential to the future of an
+end-to-end deep learning compiler stack.
+
+Relay's design was influenced by the authors previous experince


s/authors/authors' ?

zhiics · 2018-09-21T16:24:35Z

docs/langref/relay/intro.rst

+building advanced optimizing compilers for high level languages,
+as well as experinces with the current TVM stack, and NNVM.
+
+Concretely NNVM has played the role of this high level IR.


Concretely? or Currently?

zhiics · 2018-09-21T16:26:48Z

docs/langref/relay/intro.rst

+
+Concretely NNVM has played the role of this high level IR.
+
+for NNVM which address design flaws of the computation graph IRs


zhiics · 2018-09-21T17:00:13Z

docs/langref/relay/intro.rst

+
+*Note: this is not yet implemented.*
+
+Finally we allo a definition be prefixed by metadata, which adds


allo? You meant allow?

zhiics · 2018-09-21T17:55:21Z

docs/langref/relay/type_system.rst

+parametrized by a data type, and shape. The data type must be a base
+type as enforced by the kind checking rules described in TODO.
+
+This restriction importantly means


Incomplete sentence?

zhiics · 2018-09-21T18:01:00Z

docs/langref/relay/type_system.rst

+Type Call
+~~~~~~~~~
+
+Apply a type relation to a set of input arguments, at the present momen the type


zhiics · 2018-09-21T18:03:57Z

tutorials/relay/implement_fma_transform.py

+    def __init__(self):
+        self.expr_map = {}
+
+    def expr_at(self,id: ir.LocalId) -> ir.Expr:


Add space after self,

masahi · 2018-09-23T00:20:37Z

docs/langref/relay/intro.rst

+Relay which makes the important properties of computations involving tensors
+explicit.
+
+The result is a high-level IR for differentiable comptuation that can


computation

masahi · 2018-09-23T00:22:10Z

docs/langref/relay/expressions.rst

+We support a sequence of bindings followed by a body which
+is the continutation after executing the sequence of bindings.
+
+I believe this representation will be easier to manipulate then


We believe
then - > than

masahi · 2018-09-23T01:01:03Z

docs/langref/relay/expressions.rst

+is the continutation after executing the sequence of bindings.
+
+I believe this representation will be easier to manipulate then
+the mixed dataflow/control flow comptuation graphs.


computation

masahi · 2018-09-23T01:42:17Z

docs/langref/relay/type_system.rst

+
+See :py:class:`~tvm.relay.type.TypeParam` for its definition and documentation.
+
+Type Constriant


masahi · 2018-09-23T04:39:42Z

tutorials/relay/implement_fma_transform.py

+from relay.operators.register import func_ty_to_placeholders, register_op
+from relay.eval import defn_to_pyfunc
+from relay.tyck import check_expr
+


I don't see relay.frontend, eval, tyck etc in the current repo. Are they going to be upstreamed soon?

This code still needs to be updated from the old branch, but hope is to upstream these pieces in the next few days.

We have a few parallel efforts going on, some changes to the type checker for supporting VTA, the runtime compiler and evaluator, AD, debugging support, and work towards automatic quantization/8bit support. We will hopefully be releasing most of this in the next couple weeks.

3 of our team members have been away for the summer so parallelization should pick up soon.

ZihengJiang · 2018-09-26T09:23:43Z

docs/langref/relay/type_system.rst

+Kind
+~~~~
+The kind of a type parameter, represents a variable shape,
+base type, type, or dimension.


what's the difference between base type and type? Actually, a little confused about this part. Can I understand Kind as type's type?

Kind is basically a type's type.
base type is type that has a simple data layout, and thus can act as element of tensor efficiently.

ZihengJiang · 2018-09-26T09:33:01Z

docs/langref/relay/expressions.rst

+
+We support tuple constructors; the tuple node builds a finite (i.e statically known size) sequence of
+heterogenous data.  These tuples match closely to Python's and enable efficient projection of their m
+embers due to their fixed length.


m embers -> members

ZihengJiang · 2018-09-26T09:33:12Z

docs/langref/relay/expressions.rst

+Function
+~~~~~~~~
+
+A function node represents a function, it contains a seqeuence of


ZihengJiang · 2018-09-26T09:33:54Z

docs/langref/relay/expressions.rst

+which may reference the bound identifier.
+
+We will first introduce a single binding with no type
+anntoations:


annotations

slyubomirsky · 2018-09-27T01:25:12Z

docs/api/python/relay/index.rst

+This document contains the Python API to the Relay frontend, optimizer, and
+compiler toolchain.
+
+Relay is the second generation high level intermediate representation for the TVM 


I think there should be hyphens here (compound adjectives):
"Relay is the second-generation high-level intermediate representation for the TVM compiler stack."

there should also be a comma:

"Relay is the second-generation, high-level intermediate representation for the TVM compiler stack."

"intermediate representation (IR)"

slyubomirsky · 2018-09-27T01:28:22Z

docs/langref/relay/expressions.rst

+Expressions
+===========
+
+The Relay IR is a pure, expression oriented language, with a dataflow fragment


"Expression-oriented" should be hyphenated (compound adjective)

Additionally, I think in the next line it should say "Although Relay's representation is an abstract syntax tree" to clarify what exactly we mean by tree (i.e., not a tree in the sense of an acyclic graph)

No comma after language.

slyubomirsky · 2018-09-27T01:30:59Z

docs/langref/relay/intro.rst

+Introduction
+==================
+
+Relay is differentiable programming language with support for


Missing article ("Relay is a differentiable programming language...")

slyubomirsky · 2018-09-27T01:31:16Z

docs/langref/relay/intro.rst

+used to execute it uncessarily hampers many of the goals
+of a framework.
+
+We believe having a high level, an expressive language designed


"a high-level, expressive language..."

slyubomirsky · 2018-09-27T01:32:26Z

docs/langref/relay/intro.rst

+This may be a useful way to describe early ML models, but is
+limited onceyou want to generalize to dynamic models.
+
+At the same time computation graphs have been over loaded


"At the same time, computation graphs have an overloaded purpose as both..."

slyubomirsky · 2018-09-27T01:34:39Z

docs/langref/relay/intro.rst

+The conflation of the description of a computation, the
+representation used for optimizing it, and the data structure
+used to execute it uncessarily hampers many of the goals
+of a framework.


This sentence is phrased rather confusingly. Perhaps the following might be clearer?

"Unnecessarily conflating the description, representation, and execution environment of a computation hampers many of the goals of a framework." (Also appears that this may need to be explained in greater detail.)

slyubomirsky · 2018-09-27T01:37:59Z

docs/langref/relay/intro.rst

+class functions and closures, enabling the design of differentiable
+arbitrary control flow constructs. Second we contribute a type system for
+Relay which makes the important properties of computations involving tensors
+explicit.


Miscellaneous small changes:

"first-class" in this case should be hyphenated (compound adjective)

There should be a comma in "the design of differentiable, arbitrary control flow constructs"

There should be commas after "First" and "Second"

It might be clearer in the last sentence if "makes the important properties of computations involving tensors
explicit" were "makes explicit the important properties of computations involving tensors"

slyubomirsky · 2018-09-27T01:39:17Z

docs/langref/relay/intro.rst

+
+We believe Relay will enable researchers and industry to design a
+new class of DL framework frontends, differentiable programming languages,
+deep probablistic programming languages, thus accelerating the pace of


Should have "and" before "deep probabilistic programming languages"

slyubomirsky · 2018-09-27T01:41:59Z

docs/langref/relay/intro.rst

+no sigil like LLVM's intrinsics. The distinction between global and local identifiers
+makes certain kinds of transformation easier. For example inlining a global definition
+requires no analysis, you can write a pass that just directly inlines the defintions.
+It also ensures there are no spooky action at a distance, introducing a new identifier


Tense does not match: should be "ensures there are no spooky actions at a distance" or "ensures there is no spooky action at a distance." Additionally, the comma should be a semicolon.

slyubomirsky · 2018-09-27T01:43:25Z

docs/langref/relay/intro.rst

+return type is omitted we will infer the return type based on the text of the
+program.
+
+Finally we can directly construct type polymorphic definitions by writing down


should be a hyphen in "type-polymorphic"

slyubomirsky · 2018-09-27T01:44:07Z

docs/langref/relay/intro.rst

+to parameters in the machine learning.
+
+When the type information is omitted we will attempt to infer a most general type
+for the users. This property is known as generalization, for a definition without


I think it would be clearer if the comma after "generalization" were a colon (can misinterpret the "for" in the current phrasing)

slyubomirsky · 2018-09-27T01:46:04Z

docs/langref/relay/type_system.rst

+
+Static types are useful when performing compiler optimization because they
+communicate properties about the data we manipulate, such as runtime shape,
+data layout, storage without needing to run the program.


Missing conjunction before "storage"

slyubomirsky · 2018-09-27T01:46:15Z

docs/langref/relay/type_system.rst

+community, and can be viewed as a method for generalizing shape inference to
+run over arbitrary user programs containing control flow and recursion.
+
+Static types are useful when performing compiler optimization because they


"compiler optimizations" should be plural

slyubomirsky · 2018-09-27T01:47:21Z

docs/langref/relay/type_system.rst

+===========
+
+We have briefly introduced types while detailing the the expression language
+of Relay, but have fully laid out the type system.


Sounds like it should say "but have not yet fully laid out the type system"

jroesch · 2018-12-01T08:13:52Z

Hey everyone @tqchen @zhiics @slyubomirsky @junrushao1994 @zhiics @yzhliu @ZihengJiang sorry this took so long to update, things got busy working on the code. Split out just the API pieces and updated the pull request, if people could just give a quick review it would be great to merge soon. My final todo is fixing up cross-references to work more effectively.

zhiics · 2018-12-01T21:30:08Z

@jroesch LGTM.

junrushao

LGTM

jroesch changed the title ~~[DOC][Relay]: Add initial language reference and API docs for Relay.~~ [DOC][WIP][Relay]: Add initial language reference and API docs for Relay. Sep 21, 2018

tqchen requested changes Sep 21, 2018

View reviewed changes

MarisaKirisame reviewed Sep 21, 2018

View reviewed changes

docs/langref/relay/expressions.rst Outdated

.. code-block:: python

if (sum(equal(t, u))) {

jreturn x:

Copy link

Contributor

MarisaKirisame Sep 21, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

jreturn -> return

jroesch force-pushed the relay-docs branch from eca6cc9 to 6060e91 Compare September 21, 2018 07:00

MarisaKirisame reviewed Sep 21, 2018

View reviewed changes

zhiics reviewed Sep 21, 2018

View reviewed changes

masahi reviewed Sep 23, 2018

View reviewed changes

ZihengJiang reviewed Sep 26, 2018

View reviewed changes

ZihengJiang added the status: WIP label Sep 26, 2018

slyubomirsky reviewed Sep 27, 2018

View reviewed changes

slyubomirsky added 5 commits November 30, 2018 22:42

Grammatical edits to expressions.rst

75629af

Grammatical tweaks to index.rst

cfb92ad

Stylistic and grammar edits to intro.rst

c3f7656

Smaller tweaks to intro.rst

1e5a9a5

Grammar and style changes in type_system.rst

49d453a

jroesch force-pushed the relay-docs branch from d196f22 to 49d453a Compare December 1, 2018 06:43

jroesch added 6 commits November 30, 2018 22:52

Remove language reference

402750f

Fix base

a35f797

Add files for all the Relay models

9569d31

Expose operators and fix some cross-refs

fbd8a47

Add backend and frontend docs

9622dc9

Ensure headings are right length

a0ce6ae

jroesch changed the title ~~[DOC][WIP][Relay]: Add initial language reference and API docs for Relay.~~ [DOC][Relay]: Add initial language reference and API docs for Relay. Dec 1, 2018

jroesch changed the title ~~[DOC][Relay]: Add initial language reference and API docs for Relay.~~ [DOC][Relay]: Add API docs for Relay. Dec 1, 2018

jroesch added 3 commits December 1, 2018 00:16

Export everything op.rst aswell

f1c896c

Tweak backend docs

45825f9

Clean up whitespace

cebbaa7

zhiics approved these changes Dec 1, 2018

View reviewed changes

junrushao approved these changes Dec 2, 2018

View reviewed changes

tqchen approved these changes Dec 2, 2018

View reviewed changes

tqchen merged commit 20afa0a into apache:master Dec 2, 2018

tqchen added status: accepted and removed status: WIP status: need update need update based on feedbacks labels Dec 2, 2018

FrozenGene pushed a commit to FrozenGene/tvm that referenced this pull request Dec 27, 2018

[DOC][Relay]: Add API docs for Relay. (apache#1750)

8f89bbe

wweic pushed a commit to neo-ai/tvm that referenced this pull request Feb 20, 2019

[DOC][Relay]: Add API docs for Relay. (apache#1750)

bf04010

wweic pushed a commit to neo-ai/tvm that referenced this pull request Feb 20, 2019

[DOC][Relay]: Add API docs for Relay. (apache#1750)

c0c2921

jroesch deleted the relay-docs branch February 4, 2021 04:36


		The shape may be any valid Relay shape as described in the below
		section on shapes.


		See :py:class:`~tvm.relay.type.IncompleteType` for its definition and documentation.

		np.testing.assert_allclose(norm_out, xform_out)

		# Use the TVM runtime.


		Concretely NNVM has played the role of this high level IR.

		for NNVM which address design flaws of the computation graph IRs


		Note: this is not yet implemented.

		Finally we allo a definition be prefixed by metadata, which adds


		See :py:class:`~tvm.relay.type.TypeParam` for its definition and documentation.

		Type Constriant

		@@ -0,0 +1,3 @@
		tvm.relay.op
		-----------

[DOC][Relay]: Add API docs for Relay. #1750

[DOC][Relay]: Add API docs for Relay. #1750

Uh oh!

Conversation

jroesch commented Sep 21, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tqchen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jroesch commented Sep 21, 2018

Uh oh!

tqchen commented Sep 21, 2018

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

masahi Sep 23, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

masahi Sep 23, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

jroesch commented Sep 21, 2018 •

edited

Loading

masahi Sep 23, 2018 •

edited

Loading

masahi Sep 23, 2018 •

edited

Loading

slyubomirsky Sep 27, 2018 •

edited

Loading