• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AutoGraph
2
3IMPORTANT: AutoGraph is beta software, and under active development. Expect rough edges and bugs, but if you try it, we appreciate early feedback! We'd also love contributions ([please see our contributing guidelines](CONTRIBUTING.md) and our [style guide](STYLE_GUIDE.md)).
4
5AutoGraph is a Python to TensorFlow compiler.
6
7With AutoGraph, you can write [Eager style](https://www.tensorflow.org/guide/eager) code in a concise manner, and run it as a TensorFlow graph. AutoGraph uses source code transformation and partial evaluation to generate Python code that builds an equivalent TensorFlow subgraph. The result is code that behaves like ops and can be freely combined with other TensorFlow ops.  [Please see this file for which parts of the Python language we currently support](LIMITATIONS.md).
8
9For example, this Python function:
10
11```
12def f(x):
13  if x < 0:
14    x = -x
15  return x
16```
17
18would be converted to this:
19
20```
21def graph_mode_f(x):
22  with tf.name_scope('f'):
23
24    def if_true():
25      with tf.name_scope('if_true'):
26        x_1, = x,
27        x_1 = tf.negative(x_1)
28        return x_1,
29
30    def if_false():
31      with tf.name_scope('if_false'):
32        x_1, = x,
33        return x_1,
34    x = ag__.utils.run_cond(tf.greater(x, 0), if_true, if_false)
35    return x
36```
37
38so you can use it like an op:
39
40```
41with tf.Graph().as_default():
42  x = tf.constant(-1.0)
43
44  converted_f = autograph.to_graph(f)
45  y = converted_f(x)
46
47  with tf.Session() as sess:
48    print(sess.run(y))
49    # Output: 1
50```
51
52# Getting started
53
54Use AutoGraph in one of the following ways, described below:
55
56 1. Annotations (simpler)
57 2. Functional API (more flexible)
58
59To get started, install the latest nightly TensorFlow build:
60
61```shell
62pip install -U tf-nightly
63```
64
65Then import the `autograph` module from `tf.contrib`:
66
67```
68from tensorflow.python import autograph as ag
69```
70
71### Related links
72
73Articles:
74
75 * [TensorFlow blog post](https://medium.com/tensorflow/autograph-converts-python-into-tensorflow-graphs-b2a871f87ec7)
76
77Interactive notebooks:
78
79 * [Quick guide](https://colab.research.google.com/github/tensorflow/models/blob/master/samples/core/guide/autograph.ipynb)
80 * [RNN trained using Keras and Estimators](https://colab.research.google.com/github/tensorflow/tensorflow/blob/master/tensorflow/contrib/autograph/examples/notebooks/rnn_keras_estimator.ipynb)
81 * [Demo from the TF Dev Summit 2018](https://colab.research.google.com/github/tensorflow/tensorflow/blob/master/tensorflow/contrib/autograph/examples/notebooks/dev_summit_2018_demo.ipynb)
82 * [Basic control flow speed test](https://colab.research.google.com/github/tensorflow/tensorflow/blob/master/tensorflow/contrib/autograph/examples/notebooks/ag_vs_eager_collatz_speed_test.ipynb)
83 * [MNIST training speed test](https://colab.research.google.com/github/tensorflow/tensorflow/blob/master/tensorflow/contrib/autograph/examples/notebooks/ag_vs_eager_mnist_speed_test.ipynb)
84 * [Basic algorithm samples](https://colab.research.google.com/github/tensorflow/tensorflow/blob/master/tensorflow/contrib/autograph/examples/notebooks/algorithms.ipynb)
85 * [Introductory workshop support notebook](https://colab.research.google.com/github/tensorflow/tensorflow/blob/master/tensorflow/contrib/autograph/examples/notebooks/workshop.ipynb)
86
87## Using with annotations
88
89Annotating a function or class with `@convert` converts it in place:
90
91```
92@ag.convert()
93def f(x):
94  if x < 0:
95    x = -x
96  return x
97```
98
99... so that it always outputs TensorFlow code:
100
101```
102with tf.Graph().as_default():
103  x = tf.constant(-1)
104
105  y = f(x)
106
107  with tf.Session() as sess:
108    print(sess.run(y))
109    # Output: 1
110```
111
112## Using the functional API
113
114The functional API allows you to convert an existing function, class or object after it was defined:
115
116```
117converted_f = ag.to_graph(f)
118
119print(converted_f(tf.constant(-1)))
120# Output: Tensor
121
122print(f(-1))
123# Output: 1
124```
125
126You can use the functional API to inspect the generated code as well:
127
128```
129print(ag.to_code(f))
130# Output: <Python and TensorFlow code>
131```
132
133## Filing bugs and feature requests
134
135### Reporting a bug
136
137 - If AutoGraph-generated code is compiling and running, but producing an incorrect result, send us a minimal reproduction case that includes the original Eager code, the inputs and if possible, the outputs or the error message.
138 - If AutoGraph-generated code is compiling, but not running, send us a minimal reproduction case that includes the original Eager code, the inputs and if possible, the outputs or the error message.
139 - If AutoGraph-generated code is not compiling, send us two minimal pieces of code. First, the Eager code that you would like to write, and second, the Graph code that you would like AutoGraph to have generated for you.
140
141### Requesting a feature
142
143If you’d like AutoGraph to convert a feature of Python or TF that we currently don’t handle, please let us know by filing a bug. We’ll make it as easy as possible to interact with us through there.
144