diff --git a/tensorflow/python/autograph/g3doc/reference/index.md b/tensorflow/python/autograph/g3doc/reference/index.md new file mode 100644 index 00000000000..41d02f5d6f1 --- /dev/null +++ b/tensorflow/python/autograph/g3doc/reference/index.md @@ -0,0 +1,10 @@ +# AutoGraph reference + +This reference document describes the semantics of AutoGraph transformations. + +* [Introduction](intro.md) +* Control Flow (coming soon) +* Collections (coming soon) +* Exceptions (coming soon) +* Builtin Functions (coming soon) +* Datasets (coming soon) diff --git a/tensorflow/python/autograph/g3doc/reference/intro.md b/tensorflow/python/autograph/g3doc/reference/intro.md new file mode 100644 index 00000000000..0b15b94e3be --- /dev/null +++ b/tensorflow/python/autograph/g3doc/reference/intro.md @@ -0,0 +1,161 @@ +# AutoGraph reference + +[Index](index.md) + +## Introduction + +This document describes the semantics of AutoGraph's code transformations. + +For more information on AutoGraph, see the following articles: + +* [AutoGraph tutorial](https://www.tensorflow.org/alpha/guide/autograph) +* [Eager tutorial](https://www.tensorflow.org/alpha/guide/eager) +* [TensorFlow 2.0 Alpha](https://www.tensorflow.org/alpha) +* [AutoGraph blog post](https://medium.com/tensorflow/autograph-converts-python-into-tensorflow-graphs-b2a871f87ec7) + +### Terminology + +Typically, AutoGraph operates by converting a function into a new function with +new semantics. + +``` +def f(...): + ... + +converted_f = tf.autograph.to_graph(f) +``` + +In TensorFlow 2, AutoGraph is used to convert functions before they are being +traced, when using the `tf.function` API. For example, the following code: + +``` +def f(...): + ... + +graph_f = tf.function(f) +``` + +is roughly equivalent to: + +``` +converted_f = tf.autograph.to_graph(f) +graph_f = tf.function(autograph=False)(converted_f) +``` + +For the remainder of this document: + + * **converted functions** are functions converted by AutoGraph + * **graph functions** are functions compiled with `tf.function` + +Graph functions are usually also converted, unless specified otherwise. + +### Python semantics + +In general, AutoGraph does not change the semantics of error-free Python. +In special circumstances, AutoGraph may also preserve the semantics of code that +raises error as well. Semantics are preserved in the sense of the +[as-if rule](https://en.wikipedia.org/wiki/As-if_rule). + +More specifically, code that would not be legal TensorFlow Graph code may become +legal when converted. + +For example, consider the following function and the corresponding converted +function: + +``` +def f(x): + if x > 0: + return x + return -x + +converted_f = tf.autograph.to_graph(f) +``` + +If `f` executes without error, then the `converted_f` has identical results: + +``` +>>> f(3) # Runs without error +3 +>>> converted_f(3) # Identical result +3 +``` + +### TensorFlow Eager semantics + +If a function is called with `Tensor` arguments in Eager execution mode, it has +certain semantics that are different the Graph execution semantics. + +For example, the function below produces different results when executed in +Eager and Graph modes: + +``` +def f(x): + if x > 0: + return x + return -x + +# Use tf.function to run code as a TensorFlow Graph. +unconverted_graph_f = tf.function(f, autograph=False) +graph_f = tf.function(f, autograph=True) +``` + +``` +>>> f(tf.constant(3)) # Valid in Eager + + +>>> unconverted_graph_f(tf.constant(3)) # Error - not legal Graph code +TypeError: Using a `tf.Tensor` ... +``` + +AutoGraph transfers the Eager semantics to the graph function: + +``` +>>> graph_f(tf.constant(3)) # Valid in AutoGraph + +``` + +### Subset of Eager + +AutoGraph currently supports only a subset of Eager. For example, list operation +semantics are not supported: + +``` +def f(n): + l = [] + for i in tf.range(n): + l.append(i) + return l + +converted_f = tf.autograph.to_graph(f) +``` + +``` +>>> f(3) # Valid in Eager +[1, 2, 3] +>>> converted_f(3) # Not valid in AutoGraph (by default) +<> +``` + +### Experimental features + +AutoGraph supports additional semantics which are not yet stable. This includes +for example support for list semantics applied to `TensorArray`: + +``` +def f(n): + l = tf.TensorArray(...) + for i in tf.range(n): + l.append(i) + return l + +converted_f = tf.autograph.to_graph(f) +experimental_converted_f = tf.autograph.to_graph( + f, experimental_autograph_options=tf.autograph.experimental.Feature.LISTS) +``` + +``` +>>> converted_f(3) # Not valid in AutoGraph (by default) +<> +>>> experimental_converted_f(3) # Valid +<> +```