tf.Graph

TensorFlow 2 version View source on GitHub

Class Graph

A TensorFlow computation, represented as a dataflow graph.

Aliases:

A Graph contains a set of tf.Operation objects, which represent units of computation; and tf.Tensor objects, which represent the units of data that flow between operations.

A default Graph is always registered, and accessible by calling tf.compat.v1.get_default_graph. To add an operation to the default graph, simply call one of the functions that defines a new Operation:

c = tf.constant(4.0)
assert c.graph is tf.compat.v1.get_default_graph()

Another typical usage involves the tf.Graph.as_default context manager, which overrides the current default graph for the lifetime of the context:

g = tf.Graph()
with g.as_default():
  # Define operations and tensors in `g`.
  c = tf.constant(30.0)
  assert c.graph is g

Important note: This class is not thread-safe for graph construction. All operations should be created from a single thread, or external synchronization must be provided. Unless otherwise specified, all methods are not thread-safe.

A Graph instance supports an arbitrary number of "collections" that are identified by name. For convenience when building a large graph, collections can store groups of related objects: for example, the tf.Variable uses a collection (named tf.GraphKeys.GLOBAL_VARIABLES) for all variables that are created during the construction of a graph. The caller may define additional collections by specifying a new name.

__init__

View source

__init__()

Creates a new, empty Graph.

Properties

building_function

Returns True iff this graph represents a function.

collections

Returns the names of the collections known to this graph.

finalized

True if this graph has been finalized.

graph_def_versions

The GraphDef version information of this graph.

For details on the meaning of each version, see GraphDef.

Returns:

A VersionDef.

seed

The graph-level random seed of this graph.

version

Returns a version number that increases as ops are added to the graph.

Note that this is unrelated to the tf.Graph.graph_def_versions.

Returns:

An integer version that increases as ops are added to the graph.

Methods

add_to_collection

View source

add_to_collection(
    name,
    value
)

Stores value in the collection with the given name.

Note that collections are not sets, so it is possible to add a value to a collection several times.

Args:

  • name: The key for the collection. The GraphKeys class contains many standard names for collections.
  • value: The value to add to the collection.

add_to_collections

View source

add_to_collections(
    names,
    value
)

Stores value in the collections given by names.

Note that collections are not sets, so it is possible to add a value to a collection several times. This function makes sure that duplicates in names are ignored, but it will not check for pre-existing membership of value in any of the collections in names.

names can be any iterable, but if names is a string, it is treated as a single collection name.

Args:

  • names: The keys for the collections to add to. The GraphKeys class contains many standard names for collections.
  • value: The value to add to the collections.

as_default

View source

as_default()

Returns a context manager that makes this Graph the default graph.

This method should be used if you want to create multiple graphs in the same process. For convenience, a global default graph is provided, and all ops will be added to this graph if you do not create a new graph explicitly.

Use this method with the with keyword to specify that ops created within the scope of a block should be added to this graph. In this case, once the scope of the with is exited, the previous default graph is set again as default. There is a stack, so it's ok to have multiple nested levels of as_default calls.

The default graph is a property of the current thread. If you create a new thread, and wish to use the default graph in that thread, you must explicitly add a with g.as_default(): in that thread's function.

The following code examples are equivalent:

# 1. Using Graph.as_default():
g = tf.Graph()
with g.as_default():
  c = tf.constant(5.0)
  assert c.graph is g

# 2. Constructing and making default:
with tf.Graph().as_default() as g:
  c = tf.constant(5.0)
  assert c.graph is g

If eager execution is enabled ops created under this context manager will be added to the graph instead of executed eagerly.

Returns:

A context manager for using this graph as the default graph.

as_graph_def

View source

as_graph_def(
    from_version=None,
    add_shapes=False
)

Returns a serialized GraphDef representation of this graph.

The serialized GraphDef can be imported into another Graph (using tf.import_graph_def) or used with the C++ Session API.

This method is thread-safe.

Args:

  • from_version: Optional. If this is set, returns a GraphDef containing only the nodes that were added to this graph since its version property had the given value.
  • add_shapes: If true, adds an "_output_shapes" list attr to each node with the inferred shapes of each of its outputs.

Returns:

A GraphDef protocol buffer.

Raises:

  • ValueError: If the graph_def would be too large.

as_graph_element

View source

as_graph_element(
    obj,
    allow_tensor=True,
    allow_operation=True
)

Returns the object referred to by obj, as an Operation or Tensor.

This function validates that obj represents an element of this graph, and gives an informative error message if it is not.

This function is the canonical way to get/validate an object of one of the allowed types from an external argument reference in the Session API.

This method may be called concurrently from multiple threads.

Args:

  • obj: A Tensor, an Operation, or the name of a tensor or operation. Can also be any object with an _as_graph_element() method that returns a value of one of these types. Note: _as_graph_element will be called inside the graph's lock and so may not modify the graph.
  • allow_tensor: If true, obj may refer to a Tensor.
  • allow_operation: If true, obj may refer to an Operation.

Returns:

The Tensor or Operation in the Graph corresponding to obj.

Raises:

  • TypeError: If obj is not a type we support attempting to convert to types.
  • ValueError: If obj is of an appropriate type but invalid. For example, an invalid string.
  • KeyError: If obj is not an object in the graph.

clear_collection

View source

clear_collection(name)

Clears all values in a collection.

Args:

  • name: The key for the collection. The GraphKeys class contains many standard names for collections.

colocate_with

View source

colocate_with(
    op,
    ignore_existing=False
)

Returns a context manager that specifies an op to colocate with.

For example:

a = tf.Variable([1.0])
with g.colocate_with(a):
  b = tf.constant(1.0)
  c = tf.add(a, b)

b and c will always be colocated with a, no matter where a is eventually placed.

NOTE Using a colocation scope resets any existing device constraints.

If op is None then ignore_existing must be True and the new scope resets all colocation and device constraints.

Args:

  • op: The op to colocate all created ops with, or None.
  • ignore_existing: If true, only applies colocation of this op within the context, rather than applying all colocation properties on the stack. If op is None, this value must be True.

Raises:

  • ValueError: if op is None but ignore_existing is False.

Yields:

A context manager that specifies the op with which to colocate newly created ops.

container

View source

container(container_name)

Returns a context manager that specifies the resource container to use.

Stateful operations, such as variables and queues, can maintain their states on devices so that they can be shared by multiple processes. A resource container is a string name under which these stateful operations are tracked. These resources can be released or cleared with tf.Session.reset().

For example:

with g.container('experiment0'):
  # All stateful Operations constructed in this context will be placed
  # in resource container "experiment0".
  v1 = tf.Variable([1.0])
  v2 = tf.Variable([2.0])
  with g.container("experiment1"):
    # All stateful Operations constructed in this context will be
    # placed in resource container "experiment1".
    v3 = tf.Variable([3.0])
    q1 = tf.queue.FIFOQueue(10, tf.float32)
  # All stateful Operations constructed in this context will be
  # be created in the "experiment0".
  v4 = tf.Variable([4.0])
  q1 = tf.queue.FIFOQueue(20, tf.float32)
  with g.container(""):
    # All stateful Operations constructed in this context will be
    # be placed in the default resource container.
    v5 = tf.Variable([5.0])
    q3 = tf.queue.FIFOQueue(30, tf.float32)

# Resets container "experiment0", after which the state of v1, v2, v4, q1
# will become undefined (such as uninitialized).
tf.Session.reset(target, ["experiment0"])

Args:

  • container_name: container name string.

Returns:

A context manager for defining resource containers for stateful ops, yields the container name.

control_dependencies

View source

control_dependencies(control_inputs)

Returns a context manager that specifies control dependencies.

Use with the with keyword to specify that all operations constructed within the context should have control dependencies on control_inputs. For example:

with g.control_dependencies([a, b, c]):
  # `d` and `e` will only run after `a`, `b`, and `c` have executed.
  d = ...
  e = ...

Multiple calls to control_dependencies() can be nested, and in that case a new Operation will have control dependencies on the union of control_inputs from all active contexts.

with g.control_dependencies([a, b]):
  # Ops constructed here run after `a` and `b`.
  with g.control_dependencies([c, d]):
    # Ops constructed here run after `a`, `b`, `c`, and `d`.

You can pass None to clear the control dependencies:

with g.control_dependencies([a, b]):
  # Ops constructed here run after `a` and `b`.
  with g.control_dependencies(None):
    # Ops constructed here run normally, not waiting for either `a` or `b`.
    with g.control_dependencies([c, d]):
      # Ops constructed here run after `c` and `d`, also not waiting
      # for either `a` or `b`.

N.B. The control dependencies context applies only to ops that are constructed within the context. Merely using an op or tensor in the context does not add a control dependency. The following example illustrates this point:

# WRONG
def my_func(pred, tensor):
  t = tf.matmul(tensor, tensor)
  with tf.control_dependencies([pred]):
    # The matmul op is created outside the context, so no control
    # dependency will be added.
    return t

# RIGHT
def my_func(pred, tensor):
  with tf.control_dependencies([pred]):
    # The matmul op is created in the context, so a control dependency
    # will be added.
    return tf.matmul(tensor, tensor)

Also note that though execution of ops created under this scope will trigger execution of the dependencies, the ops created under this scope might still be pruned from a normal tensorflow graph. For example, in the following snippet of code the dependencies are never executed:

  loss = model.loss()
  with tf.control_dependencies(dependencies):
    loss = loss + tf.constant(1)  # note: dependencies ignored in the
                                  # backward pass
  return tf.gradients(loss, model.variables)

This is because evaluating the gradient graph does not require evaluating the constant(1) op created in the forward pass.

Args:

  • control_inputs: A list of Operation or Tensor objects which must be executed or computed before running the operations defined in the context. Can also be None to clear the control dependencies.

Returns:

A context manager that specifies control dependencies for all operations constructed within the context.

Raises:

  • TypeError: If control_inputs is not a list of Operation or Tensor objects.

create_op

View source

create_op(
    op_type,
    inputs,
    dtypes=None,
    input_types=None,
    name=None,
    attrs=None,
    op_def=None,
    compute_shapes=True,
    compute_device=True
)

Creates an Operation in this graph. (deprecated arguments)

This is a low-level interface for creating an Operation. Most programs will not call this method directly, and instead use the Python op constructors, such as tf.constant(), which add ops to the default graph.

Args:

  • op_type: The Operation type to create. This corresponds to the OpDef.name field for the proto that defines the operation.
  • inputs: A list of Tensor objects that will be inputs to the Operation.
  • dtypes: (Optional) A list of DType objects that will be the types of the tensors that the operation produces.
  • input_types: (Optional.) A list of DTypes that will be the types of the tensors that the operation consumes. By default, uses the base DType of each input in inputs. Operations that expect reference-typed inputs must specify input_types explicitly.
  • name: (Optional.) A string name for the operation. If not specified, a name is generated based on op_type.
  • attrs: (Optional.) A dictionary where the key is the attribute name (a string) and the value is the respective attr attribute of the NodeDef proto that will represent the operation (an AttrValue proto).
  • op_def: (Optional.) The OpDef proto that describes the op_type that the operation will have.
  • compute_shapes: (Optional.) Deprecated. Has no effect (shapes are always computed).
  • compute_device: (Optional.) If True, device functions will be executed to compute the device property of the Operation.

Raises:

  • TypeError: if any of the inputs is not a Tensor.
  • ValueError: if colocation conflicts with existing device assignment.

Returns:

An Operation object.

device

View source

device(device_name_or_function)

Returns a context manager that specifies the default device to use.

The device_name_or_function argument may either be a device name string, a device function, or None:

  • If it is a device name string, all operations constructed in this context will be assigned to the device with that name, unless overridden by a nested device() context.
  • If it is a function, it will be treated as a function from Operation objects to device name strings, and invoked each time a new Operation is created. The Operation will be assigned to the device with the returned name.
  • If it is None, all device() invocations from the enclosing context will be ignored.

For information about the valid syntax of device name strings, see the documentation in DeviceNameUtils.

For example:

with g.device('/device:GPU:0'):
  # All operations constructed in this context will be placed
  # on GPU 0.
  with g.device(None):
    # All operations constructed in this context will have no
    # assigned device.

# Defines a function from `Operation` to device string.
def matmul_on_gpu(n):
  if n.type == "MatMul":
    return "/device:GPU:0"
  else:
    return "/cpu:0"

with g.device(matmul_on_gpu):
  # All operations of type "MatMul" constructed in this context
  # will be placed on GPU 0; all other operations will be placed
  # on CPU 0.

N.B. The device scope may be overridden by op wrappers or other library code. For example, a variable assignment op v.assign() must be colocated with the tf.Variable v, and incompatible device scopes will be ignored.

Args:

  • device_name_or_function: The device name or function to use in the context.

Yields:

A context manager that specifies the default device to use for newly created ops.

Raises:

  • RuntimeError: If device scopes are not properly nested.

finalize

View source

finalize()

Finalizes this graph, making it read-only.

After calling g.finalize(), no new operations can be added to g. This method is used to ensure that no operations are added to a graph when it is shared between multiple threads, for example when using a tf.compat.v1.train.QueueRunner.

get_all_collection_keys