def function(func=None, input_signature=None, autograph=False, experimental_autograph_options=None): """Defines a function as per the "functions, not sessions" document.""" if input_signature is not None: function_lib.validate_signature(input_signature) def decorated(inner_function): try: name = inner_function.__name__ except AttributeError: name = "function" return tf_decorator.make_decorator( inner_function, PolymorphicFunction( inner_function, name, input_signature=input_signature, autograph=autograph, experimental_autograph_options=experimental_autograph_options)) # This code path is for the `foo = tf.function(foo, ...)` use case if func is not None: return decorated(func) # This code path is for the # # @tf.function(...) # def foo(...): # ... # # use case, which is equivalent to `foo = tf.function(...)(foo)` return decorated
def function(func=None, input_signature=None): """Defines a function as per the "functions, not sessions" document.""" if input_signature is not None: function_lib.validate_signature(input_signature) def decorated(inner_function): try: name = inner_function.__name__ except AttributeError: name = "function" return tf_decorator.make_decorator( inner_function, PolymorphicFunction( inner_function, name, input_signature=input_signature)) # This code path is for the `foo = tf.function(foo, ...)` use case if func is not None: return decorated(func) # This code path is for the # # @tf.function(...) # def foo(...): # ... # # use case, which is equivalent to `foo = tf.function(...)(foo)` return decorated
def function(func=None, input_signature=None, autograph=True, experimental_autograph_options=None): """Creates a callable TensorFlow graph from a Python function. `function` constructs a callable that executes a TensorFlow graph (`tf.Graph`) created by tracing the TensorFlow operations in `func`. This allows the TensorFlow runtime to apply optimizations and exploit parallelism in the computation defined by `func`. _Example Usage_ ```python def f(x, y): return tf.reduce_mean(tf.multiply(x ** 2, 3) + y) g = tf.function(f) x = tf.constant([[2.0, 3.0]]) y = tf.constant([[3.0, -2.0]]) # `f` and `g` will return the same value, but `g` will be executed as a # TensorFlow graph. assert f(x, y).numpy() == g(x, y).numpy() # Tensors and tf.Variables used by the Python function are captured in the # graph. @tf.function def h(): return f(x, y) assert (h().numpy() == f(x, y).numpy()).all() # Data-dependent control flow is also captured in the graph. Supported # control flow statements include `if`, `for`, `while`, `break`, `continue`, # `return`. @tf.function def g(x): if tf.reduce_sum(x) > 0: return x * x else: return -x // 2 # print and TensorFlow side effects are supported, but exercise caution when # using Python side effects like mutating objects, saving to files, etc. l = [] @tf.function def g(x): for i in x: print(i) # Works tf.compat.v1.assign(v, i) # Works tf.compat.v1.py_func(lambda i: l.append(i))(i) # Works l.append(i) # Caution! Doesn't work. ``` Note that unlike other TensorFlow operations, we don't convert python numerical inputs to tensors. Moreover, a new graph is generated for each distinct python numerical value, for example calling `g(2)` and `g(3)` will generate two new graphs (while only one is generated if you call `g(tf.constant(2))` and `g(tf.constant(3))`). Therefore, python numerical inputs should be restricted to arguments that will have few distinct values, such as hyperparameters like the number of layers in a neural network. This allows TensorFlow to optimize each variant of the neural network. _Referencing `tf.Variable`s_ The Python function `func` may reference stateful objects (such as `tf.Variable`). These are captured as implicit inputs to the callable returned by `function`. For example: ```python c = tf.Variable(0) @tf.function def f(x): c.assign_add(1) return x + tf.compat.v1.to_float(c) assert int(c) == 0 assert f(1.0) == 2.0 assert int(c) == 1 assert f(1.0) == 3.0 assert int(c) == 2 ``` `function` can be applied to methods of an object. For example: ```python class Dense(object): def __init__(self): self.W = tf.Variable(tf.compat.v1.glorot_uniform_initializer()((10, 10))) self.b = tf.Variable(tf.zeros(10)) @tf.function def compute(self, x): return tf.matmul(x, self.W) + self.b d1 = Dense() d2 = Dense() x = tf.random.uniform((10, 10)) # d1 and d2 are using distinct variables assert not (d1.compute(x).numpy() == d2.compute(x).numpy()).all() ``` _Usage with `tf.keras`_ The `call` methods of a `tf.keras.Model` subclass can be decorated with `function` in order to apply graph execution optimizations on it. For example: ```python class MyModel(tf.keras.Model): def __init__(self, keep_probability=0.2): super(MyModel, self).__init__() self.dense1 = tf.keras.layers.Dense(4) self.dense2 = tf.keras.layers.Dense(5) self.keep_probability = keep_probability @tf.function def call(self, inputs, training=True): y = self.dense2(self.dense1(inputs)) if training: return tf.nn.dropout(y, self.keep_probability) else: return y model = MyModel() model(x, training=True) # executes a graph, with dropout model(x, training=False) # executes a graph, without dropout ``` _Input Signatures_ `function` instantiates a separate graph for every unique set of input shapes and datatypes. For example, the following code snippet will result in three distinct graphs being traced, as each input has a different shape. ```python @tf.function def f(x): return tf.add(x, 1.) scalar = tf.constant(1.0) vector = tf.constant([1.0, 1.0]) matrix = tf.constant([[3.0]]) f(scalar) f(vector) f(matrix) ``` An "input signature" can be optionally provided to `function` to control the graphs traced. The input signature specifies the shape and type of each `Tensor` argument to the function using a `tf.TensorSpec` object. For example, the following code snippet ensures that a single graph is created where the input `Tensor` is required to be a floating point tensor with no restrictions on shape. ```python @tf.function(input_signature=[tf.TensorSpec(shape=None, dtype=tf.float32)]) def f(x): return tf.add(x, 1.) ``` When an `input_signature` is specified, the callable will convert the inputs to the specified TensorSpecs. _Tracing and staging_ When `autograph` is `True`, all Python control flow that depends on `Tensor` values is staged into a TensorFlow graph. When `autograph` is `False`, the function is traced and control flow is not allowed to depend on data. Note that `function` only stages TensorFlow operations, all Python code that `func` executes and does not depend on data will shape the _construction_ of the graph. For example, consider the following: ```python import numpy as np def add_noise(): return tf.eye(5) + np.random.randn(5, 5) traced = tf.function(add_noise) ``` `add_noise()` will return a different output every time it is invoked. However, `traced()` will return the same value every time it is called, since a particular random value generated by the `np.random.randn` call will be inserted in the traced/staged TensorFlow graph as a constant. In this particular example, replacing `np.random.randn(5, 5)` with `tf.random.normal((5, 5))` will result in the same behavior for `add_noise()` and `traced()`. _Python Side-Effects_ A corollary of the previous discussion on tracing is the following: If a Python function `func` has Python side-effects, then executing `func` multiple times may not be semantically equivalent to executing `F = tf.function(func)` multiple times; this difference is due to the fact that `function` only captures the subgraph of TensorFlow operations that is constructed when `func` is invoked to trace a graph. The same is true if code with Python side effects is used inside control flow, such as a loop. If your code uses side effects that are not intended to control graph construction, wrap them inside `tf.compat.v1.py_func`. _Retracing_ A single tf.function object might need to map to multiple computation graphs under the hood. This should be visible only as performance (tracing graphs has a nonzero computational and memory cost) but should not affect the correctness of the program. A traced function should return the same result as it would when run eagerly, assuming no unintended Python side-effects. Calling a `tf.function` with tensor arguments of different dtypes should lead to at least one computational graph per distinct set of dtypes. Alternatively, always calling a `tf.function` with tensor arguments of the same shapes and dtypes and the same non-tensor arguments should not lead to additional retracings of your function. Other than that, TensorFlow reserves the right to retrace functions as many times as needed, to ensure that traced functions behave as they would when run eagerly and to provide the best end-to-end performance. For example, the behavior of how many traces TensorFlow will do when the function is repeatedly called with different python scalars as arguments is left undefined to allow for future optimizations. To control the tracing behavior, use the following tools: - different `tf.function` objects are guaranteed to not share traces; and - specifying a signature or using concrete function objects returned from get_concrete_function() guarantees that only one function graph will be built. Args: func: function to be compiled. If `func` is None, returns a decorator that can be invoked with a single argument - `func`. The end result is equivalent to providing all the arguments up front. In other words, `tf.function(input_signature=...)(func)` is equivalent to `tf.function(func, input_signature=...)`. The former can be used to decorate Python functions, for example: @tf.function(input_signature=...) def foo(...): ... input_signature: A possibly nested sequence of `tf.TensorSpec` objects specifying the shapes and dtypes of the Tensors that will be supplied to this function. If `None`, a separate function is instantiated for each inferred input signature. If input_signature is specified, every input to `func` must be a `Tensor`, and `func` cannot accept `**kwargs`. autograph: Whether autograph should be applied on `func` before tracing a graph. This allows for dynamic control flow (Python if's, loops etc.) in the traced graph. See https://www.tensorflow.org/guide/autograph for more information. experimental_autograph_options: Experimental knobs (in the form of a tuple of tensorflow.autograph.Feature values) to control behavior when autograph=True. Returns: If `func` is not None, returns a callable that will execute the compiled function (and return zero or more `tf.Tensor` objects). If `func` is None, returns a decorator that, when invoked with a single `func` argument, returns a callable equivalent to the case above. Raises: TypeError: If `input_signature` is neither `None` nor a sequence of `TensorSpec` objects. """ if input_signature is not None: function_lib.validate_signature(input_signature) def decorated(inner_function): try: name = inner_function.__name__ except AttributeError: name = "function" return tf_decorator.make_decorator( inner_function, Function( inner_function, name, input_signature=input_signature, autograph=autograph, experimental_autograph_options=experimental_autograph_options)) # This code path is for the `foo = tf.function(foo, ...)` use case if func is not None: return decorated(func) # This code path is for the # # @tf.function(...) # def foo(...): # ... # # use case, which is equivalent to `foo = tf.function(...)(foo)` return decorated
def function(func=None, input_signature=None, autograph=True, experimental_autograph_options=None): """Creates a callable TensorFlow graph from a Python function. `function` constructs a callable that executes a TensorFlow graph (`tf.Graph`) created by tracing the TensorFlow operations in `func`. This allows the TensorFlow runtime to apply optimizations and exploit parallelism in the computation defined by `func`. _Example Usage_ ```python def f(x, y): return tf.reduce_mean(tf.multiply(x ** 2, 3) + y) g = tf.function(f) x = tf.constant([[2.0, 3.0]]) y = tf.constant([[3.0, -2.0]]) # `f` and `g` will return the same value, but `g` will be executed as a # TensorFlow graph. assert f(x, y).numpy() == g(x, y).numpy() # Tensors and tf.Variables used by the Python function are captured in the # graph. @tf.function def h(): return f(x, y) assert (h().numpy() == f(x, y).numpy()).all() # Data-dependent control flow is also captured in the graph. Supported # control flow statements include `if`, `for`, `break`, `continue`, `return`. @tf.function def g(x): if tf.reduce_sum(x) > 0: return x * x else: return -x // 2 # print and TensorFlow side effects are supported, but exercise caution when # using Python side effects like mutating objects, saving to files, etc. l = [] @tf.function def g(x): for i in x: print(i) # Works tf.assign(v, i) # Works tf.py_func(lambda i: l.append(i))(i) # Works l.append(i) # Caution! Doesn't work. ``` Note that unlike other TensorFlow operations, we don't convert python numerical inputs to tensors. _Referencing `tf.Variable`s_ The Python function `func` may reference stateful objects (such as `tf.Variable`). These are captured as implicit inputs to the callable returned by `function`. For example: ```python c = tf.Variable(0) @tf.function def f(x): c.assign_add(1) return x + tf.to_float(c) assert int(c) == 0 assert f(1.0) == 2.0 assert int(c) == 1 assert f(1.0) == 3.0 assert int(c) == 2 ``` `function` can be applied to methods of an object. For example: ```python class Dense(object): def __init__(self): self.W = tf.Variable(tf.glorot_uniform_initializer()((10, 10))) self.b = tf.Variable(tf.zeros(10)) @tf.function def compute(self, x): return tf.matmul(x, self.W) + self.b d1 = Dense() d2 = Dense() x = tf.random_uniform((10, 10)) # d1 and d2 are using distinct variables assert not (d1.compute(x).numpy() == d2.compute(x).numpy()).all() ``` _Usage with `tf.keras`_ The `call` methods of a `tf.keras.Model` subclass can be decorated with `function` in order to apply graph execution optimizations on it. For example: ```python class MyModel(tf.keras.Model): def __init__(self, keep_probability=0.2): super(MyModel, self).__init__() self.dense1 = tf.keras.layers.Dense(4) self.dense2 = tf.keras.layers.Dense(5) self.keep_probability = keep_probability @tf.function def call(self, inputs, training=True): y = self.dense2(self.dense1(inputs)) if training: return tf.nn.dropout(y, self.keep_probability) else: return y model = MyModel() model(x, training=True) # executes a graph, with dropout model(x, training=False) # executes a graph, without dropout ``` _Input Signatures_ `function` instantiates a separate graph for every unique set of input shapes and datatypes. For example, the following code snippet will result in three distinct graphs being traced, as each input has a different shape. ```python @tf.function def f(x): return tf.add(x, 1.) scalar = tf.constant(1.0) vector = tf.constant([1.0, 1.0]) matrix = tf.constant([[3.0]]) f(scalar) f(vector) f(matrix) ``` An "input signature" can be optionally provided to `function` to control the graphs traced. The input signature specifies the shape and type of each `Tensor` argument to the function using a `tf.TensorSpec` object. For example, the following code snippet ensures that a single graph is created where the input `Tensor` is required to be a floating point tensor with no restrictions on shape. ```python @tf.function(input_signature=[tf.TensorSpec(shape=None, dtype=tf.float32)]) def f(x): return tf.add(x, 1.) ``` When an `input_signature` is specified, the callable will convert the inputs to the specified TensorSpecs. _Tracing and staging_ When `autograph` is `True`, all Python code that depends on `Tensor` values is staged into a TensorFlow graph. When `autograph` is `False`, the function is traced and control flow is not allowed to depend on data. Note that `function` only stages TensorFlow operations, all Python code that `func` executes and does not depend on data will shape the _construction_ of the graph. For example, consider the following: ```python import numpy as np def add_noise(): return tf.eye(5) + np.random.randn(5, 5) traced = tf.function(add_noise) ``` `add_noise()` will return a different output every time it is invoked. However, `traced()` will return the same value every time it is called, since a particular random value generated by the `np.random.randn` call will be inserted in the traced/staged TensorFlow graph as a constant. In this particular example, replacing `np.random.randn(5, 5)` with `tf.random_normal((5, 5))` will result in the same behavior for `add_noise()` and `traced()`. _Python Side-Effects_ A corollary of the previous discussion on tracing is the following: If a Python function `func` has Python side-effects, then executing `func` multiple times may not be semantically equivalent to executing `F = tf.function(func)` multiple times; this difference is due to the fact that `function` only captures the subgraph of TensorFlow operations that is constructed when `func` is invoked to trace a graph. The same is true if code with Python side effects is used inside control flow, such as a loop. If your code uses side effects that are not intended to control graph construction, wrap them inside `tf.py_func`. Args: func: function to be compiled. If `func` is None, returns a decorator that can be invoked with a single argument - `func`. The end result is equivalent to providing all the arguments up front. In other words, `tf.function(input_signature=...)(func)` is equivalent to `tf.function(func, input_signature=...)`. The former can be used to decorate Python functions, for example: @tf.function(input_signature=...) def foo(...): ... input_signature: A possibly nested sequence of `tf.TensorSpec` objects specifying the shapes and dtypes of the Tensors that will be supplied to this function. If `None`, a separate function is instantiated for each inferred input signature. If input_signature is specified, every input to `func` must be a `Tensor`, and `func` cannot accept `**kwargs`. autograph: Whether autograph should be applied on `func` before tracing a graph. This allows for dynamic control flow (Python if's, loops etc.) in the traced graph. See https://www.tensorflow.org/guide/autograph for more information. experimental_autograph_options: Experimental knobs (in the form of a tuple of tensorflow.autograph.Feature values) to control behavior when autograph=True. Returns: If `func` is not None, returns a callable that will execute the compiled function (and return zero or more `tf.Tensor` objects). If `func` is None, returns a decorator that, when invoked with a single `func` argument, returns a callable equivalent to the case above. Raises: TypeError: If `input_signature` is neither `None` nor a sequence of `TensorSpec` objects. """ if input_signature is not None: function_lib.validate_signature(input_signature) def decorated(inner_function): try: name = inner_function.__name__ except AttributeError: name = "function" return tf_decorator.make_decorator( inner_function, Function( inner_function, name, input_signature=input_signature, autograph=autograph, experimental_autograph_options=experimental_autograph_options)) # This code path is for the `foo = tf.function(foo, ...)` use case if func is not None: return decorated(func) # This code path is for the # # @tf.function(...) # def foo(...): # ... # # use case, which is equivalent to `foo = tf.function(...)(foo)` return decorated
def function(func=None, input_signature=None, autograph=True, experimental_implements=None, experimental_autograph_options=None, experimental_relax_shapes=False, experimental_compile=None): """Compiles a function into a callable TensorFlow graph. `tf.function` constructs a callable that executes a TensorFlow graph (`tf.Graph`) created by trace-compiling the TensorFlow operations in `func`, effectively executing `func` as a TensorFlow graph. Example usage: >>> @tf.function ... def f(x, y): ... return x ** 2 + y >>> x = tf.constant([2, 3]) >>> y = tf.constant([3, -2]) >>> f(x, y) <tf.Tensor: ... numpy=array([7, 7], ...)> _Features_ `func` may use data-dependent control flow, including `if`, `for`, `while` `break`, `continue` and `return` statements: >>> @tf.function ... def f(x): ... if tf.reduce_sum(x) > 0: ... return x * x ... else: ... return -x // 2 >>> f(tf.constant(-2)) <tf.Tensor: ... numpy=1> `func`'s closure may include `tf.Tensor` and `tf.Variable` objects: >>> @tf.function ... def f(): ... return x ** 2 + y >>> x = tf.constant([-2, -3]) >>> y = tf.Variable([3, -2]) >>> f() <tf.Tensor: ... numpy=array([7, 7], ...)> `func` may also use ops with side effects, such as `tf.print`, `tf.Variable` and others: >>> v = tf.Variable(1) >>> @tf.function ... def f(x): ... for i in tf.range(x): ... v.assign_add(i) >>> f(3) >>> v <tf.Variable ... numpy=4> Important: Any Python side-effects (appending to a list, printing with `print`, etc) will only happen once, when `func` is traced. To have side-effects executed into your `tf.function` they need to be written as TF ops: >>> l = [] >>> @tf.function ... def f(x): ... for i in x: ... l.append(i + 1) # Caution! Will only happen once when tracing >>> f(tf.constant([1, 2, 3])) >>> l [<tf.Tensor ...>] Instead, use TensorFlow collections like `tf.TensorArray`: >>> @tf.function ... def f(x): ... ta = tf.TensorArray(dtype=tf.int32, size=0, dynamic_size=True) ... for i in range(len(x)): ... ta = ta.write(i, x[i] + 1) ... return ta.stack() >>> f(tf.constant([1, 2, 3])) <tf.Tensor: ..., numpy=array([2, 3, 4], ...)> _`tf.function` is polymorphic_ Internally, `tf.function` can build more than one graph, to support arguments with different data types or shapes, since TensorFlow can build more efficient graphs that are specialized on shapes and dtypes. `tf.function` also treats any pure Python value as opaque objects, and builds a separate graph for each set of Python arguments that it encounters. To obtain an individual graph, use the `get_concrete_function` method of the callable created by `tf.function`. It can be called with the same arguments as `func` and returns a special `tf.Graph` object: >>> @tf.function ... def f(x): ... return x + 1 >>> isinstance(f.get_concrete_function(1).graph, tf.Graph) True Caution: Passing python scalars or lists as arguments to `tf.function` will always build a new graph. To avoid this, pass numeric arguments as Tensors whenever possible: >>> @tf.function ... def f(x): ... return tf.abs(x) >>> f1 = f.get_concrete_function(1) >>> f2 = f.get_concrete_function(2) # Slow - builds new graph >>> f1 is f2 False >>> f1 = f.get_concrete_function(tf.constant(1)) >>> f2 = f.get_concrete_function(tf.constant(2)) # Fast - reuses f1 >>> f1 is f2 True Python numerical arguments should only be used when they take few distinct values, such as hyperparameters like the number of layers in a neural network. _Input signatures_ For Tensor arguments, `tf.function` instantiates a separate graph for every unique set of input shapes and datatypes. The example below creates two separate graphs, each specialized to a different shape: >>> @tf.function ... def f(x): ... return x + 1 >>> vector = tf.constant([1.0, 1.0]) >>> matrix = tf.constant([[3.0]]) >>> f.get_concrete_function(vector) is f.get_concrete_function(matrix) False An "input signature" can be optionally provided to `tf.function` to control the graphs traced. The input signature specifies the shape and type of each Tensor argument to the function using a `tf.TensorSpec` object. More general shapes can be used. This is useful to avoid creating multiple graphs when Tensors have dynamic shapes. It also restricts the dhape and datatype of Tensors that can be used: >>> @tf.function( ... input_signature=[tf.TensorSpec(shape=None, dtype=tf.float32)]) ... def f(x): ... return x + 1 >>> vector = tf.constant([1.0, 1.0]) >>> matrix = tf.constant([[3.0]]) >>> f.get_concrete_function(vector) is f.get_concrete_function(matrix) True _Variables may only be created once_ `tf.function` only allows creating new `tf.Variable` objects when it is called for the first time: >>> class MyModule(tf.Module): ... def __init__(self): ... self.v = None ... ... @tf.function ... def call(self, x): ... if self.v is None: ... self.v = tf.Variable(tf.ones_like(x)) ... return self.v * x In general, it is recommended to create stateful objects like `tf.Variable` outside of `tf.function` and passing them as arguments. Args: func: the function to be compiled. If `func` is None, `tf.function` returns a decorator that can be invoked with a single argument - `func`. In other words, `tf.function(input_signature=...)(func)` is equivalent to `tf.function(func, input_signature=...)`. The former can be used as decorator. input_signature: A possibly nested sequence of `tf.TensorSpec` objects specifying the shapes and dtypes of the Tensors that will be supplied to this function. If `None`, a separate function is instantiated for each inferred input signature. If input_signature is specified, every input to `func` must be a `Tensor`, and `func` cannot accept `**kwargs`. autograph: Whether autograph should be applied on `func` before tracing a graph. Data-dependent control flow requires `autograph=True`. For more information, see the [tf.function and AutoGraph guide]( https://www.tensorflow.org/guide/function). experimental_implements: If provided, contains a name of a "known" function this implements. For example "mycompany.my_recurrent_cell". This is stored as an attribute in inference function, which can then be detected when processing serialized function. See https://github.com/tensorflow/community/blob/master/rfcs/20190610-standardizing-composite_ops.md for details. For an example of utilizing this attribute see: https://github.com/tensorflow/tensorflow/blob/master/tensorflow/compiler/mlir/lite/transforms/prepare_composite_functions_tf.cc The code above automatically detects and substitutes function that implements "embedded_matmul" and allows TFLite to substitute its own implementations. For instance, a tensorflow user can use this attribute to mark that their function also implements `embedded_matmul``` (perhaps more efficiently!) by specifying it using this flag. ```python @tf.function(experimental_implements="embedded_matmul"): def embedding_matmul(a, b): # custom implementation here ``` experimental_autograph_options: Optional tuple of `tf.autograph.experimental.Feature` values. experimental_relax_shapes: When True, `tf.function` may generate fewer, graphs that are less specialized on input shapes. experimental_compile: If True, the function is always compiled by [XLA](https://www.tensorflow.org/xla). XLA may be more efficient in some cases (e.g. TPU, XLA_GPU, dense tensor computations). Returns: If `func` is not None, returns a callable that will execute the compiled function (and return zero or more `tf.Tensor` objects). If `func` is None, returns a decorator that, when invoked with a single `func` argument, returns a callable equivalent to the case above. """ if input_signature is not None: function_lib.validate_signature(input_signature) def decorated(inner_function): try: name = inner_function.__name__ except AttributeError: name = "function" return tf_decorator.make_decorator( inner_function, Function( inner_function, name, input_signature=input_signature, autograph=autograph, experimental_autograph_options=experimental_autograph_options, experimental_relax_shapes=experimental_relax_shapes, experimental_compile=experimental_compile, experimental_implements=experimental_implements)) # This code path is for the `foo = tf.function(foo, ...)` use case if func is not None: return decorated(func) # This code path is for the # # @tf.function(...) # def foo(...): # ... # # use case, which is equivalent to `foo = tf.function(...)(foo)` return decorated
def function(func=None, input_signature=None, autograph=True, experimental_autograph_options=None): """Creates a callable TensorFlow graph from a Python function. `function` constructs a callable that executes a TensorFlow graph (`tf.Graph`) created by tracing the TensorFlow operations in `func`. This allows the TensorFlow runtime to apply optimizations and exploit parallelism in the computation defined by `func`. _Example Usage_ ```python def f(x, y): return tf.reduce_mean(tf.multiply(x ** 2, 3) + y) g = tf.function(f) x = tf.constant([[2.0, 3.0]]) y = tf.constant([[3.0, -2.0]]) # `f` and `g` will return the same value, but `g` will be executed as a # TensorFlow graph. assert f(x, y).numpy() == g(x, y).numpy() # Tensors and tf.Variables used by the Python function are captured in the # traced graph. @tf.function def h(): return f(x, y) assert (h().numpy() == f(x, y).numpy()).all() ``` _Referencing `tf.Variable`s_ The Python function `func` may reference stateful objects (such as `tf.Variable`). These are captured as implicit inputs to the callable returned by `function`. For example: ```python c = tf.Variable(0) @tf.function def f(x): c.assign_add(1) return x + tf.to_float(c) assert int(c) == 0 assert f(1.0) == 2.0 assert int(c) == 1 assert f(1.0) == 3.0 assert int(c) == 2 ``` `function` can be applied to methods of an object. For example: ```python class Dense(object): def __init__(self): self.W = tf.Variable(tf.glorot_uniform_initializer()((10, 10))) self.b = tf.Variable(tf.zeros(10)) @tf.function def compute(self, x): return tf.matmul(x, self.W) + self.b d1 = Dense() d2 = Dense() x = tf.random_uniform((10, 10)) # d1 and d2 are using distinct variables assert not (d1.compute(x).numpy() == d2.compute(x).numpy()).all() ``` _Usage with `tf.keras`_ The `call` methods of a `tf.keras.Model` subclass can be decorated with `function` in order to apply graph execution optimizations on it. For example: ```python class MyModel(tf.keras.Model): def __init__(self, keep_probability=0.2): super(MyModel, self).__init__() self.dense1 = tf.keras.layers.Dense(4) self.dense2 = tf.keras.layers.Dense(5) self.keep_probability = keep_probability @tf.function def call(self, inputs, training=True): y = self.dense2(self.dense1(inputs)) if training: return tf.nn.dropout(y, self.keep_probability) else: return y model = MyModel() model(x, training=True) # executes a graph, with dropout model(x, training=False) # executes a graph, without dropout ``` _Input Signatures_ `function` instantiates a separate graph for every unique set of input shapes and datatypes. For example, the following code snippet will result in three distinct graphs being traced, as each input has a different shape. ```python @tf.function def f(x): return tf.add(x, 1.) scalar = tf.constant(1.0) vector = tf.constant([1.0, 1.0]) matrix = tf.constant([[3.0]]) f(scalar) f(vector) f(matrix) ``` An "input signature" can be optionally provided to `function` to control the graphs traced. The input signature specifies the shape and type of each `Tensor` argument to the function using a `tf.TensorSpec` object. For example, the following code snippet ensures that a single graph is created where the input `Tensor` is required to be a floating point tensor with no restrictions on shape. ```python @tf.function(input_signature=[tf.TensorSpec(shape=None, dtype=tf.float32)]) def f(x): return tf.add(x, 1.) ``` When an `input_signature` is specified, the callable will only accept `Tensor` (or NumPy `ndarray`) objects as arguments. _Tracing_ Note that `function` only traces TensorFlow operations, all the other Python code that `func` executes will shape the _construction_ of the graph. For example, consider the following: ```python import numpy as np def add_noise(): return tf.eye(5) + np.random.randn(5, 5) traced = tf.function(add_noise) ``` `add_noise()` will return a different output every time it is invoked. However, `traced` will return the same value every time it is called, since a particular random value generated by the `np.random.randn` call will be inserted in the traced TensorFlow graph as a constant. In this particular example, replacing `np.random.randn(5, 5)` with `tf.random_normal((5, 5))` will result in the same behavior for `add_noise()` and `traced()`. _Python Side-Effects_ A corollary of the previous discussion on tracing is the following: If a Python function `func` has Python side-effects, then executing `func` multiple times may not be semantically equivalent to executing `F = tf.function(func)` multiple times; this difference is due to the fact that `function` only captures the subgraph of TensorFlow operations that is constructed when `func` is invoked to trace a graph. Args: func: function to be compiled. If `func` is None, returns a decorator that can be invoked with a single argument - `func`. The end result is equivalent to providing all the arguments up front. In other words, `tf.function(input_signature=...)(func)` is equivalent to `tf.function(func, input_signature=...)`. The former can be used to decorate Python functions, for example: @tf.function(input_signature=...) def foo(...): ... input_signature: A possibly nested sequence of `tf.TensorSpec` objects specifying the shapes and dtypes of the Tensors that will be supplied to this function. If `None`, a separate function is instantiated for each inferred input signature. If input_signature is specified, every input to `func` must be a `Tensor`, and `func` cannot accept `**kwargs`. autograph: Whether autograph should be applied on `func` before tracing a graph. This allows for dynamic control flow (Python if's, loops etc.) in the traced graph. See https://www.tensorflow.org/guide/autograph for more information. experimental_autograph_options: Experimental knobs (in the form of a tuple of tensorflow.autograph.Feature values) to control behavior when autograph=True. Returns: If `func` is not None, returns a callable that will execute the compiled function (and return zero or more `tf.Tensor` objects). If `func` is None, returns a decorator that, when invoked with a single `func` argument, returns a callable equivalent to the case above. Raises: TypeError: If `input_signature` is neither `None` nor a sequence of `TensorSpec` objects. """ if input_signature is not None: function_lib.validate_signature(input_signature) def decorated(inner_function): try: name = inner_function.__name__ except AttributeError: name = "function" return tf_decorator.make_decorator( inner_function, PolymorphicFunction( inner_function, name, input_signature=input_signature, autograph=autograph, experimental_autograph_options=experimental_autograph_options)) # This code path is for the `foo = tf.function(foo, ...)` use case if func is not None: return decorated(func) # This code path is for the # # @tf.function(...) # def foo(...): # ... # # use case, which is equivalent to `foo = tf.function(...)(foo)` return decorated