Module: tf.nest

Functions that work with structures.

A structure is either:

  • one of the recognized Python collections, holding nested structures;
  • a value of any other type, typically a TensorFlow data type like Tensor, Variable, or of compatible types such as int, float, ndarray, etc. these are commonly referred to as atoms of the structure.

A structure of type T is a structure whose atomic items are of type T. For example, a structure of tf.Tensor only contains tf.Tensor as its atoms.

Historically a nested structure was called a nested sequence in TensorFlow. A nested structure is sometimes called a nest or a tree, but the formal name nested structure is preferred.

Refer to Nesting Data Structures.

The following collection types are recognized by tf.nest as nested structures:

  • collections.abc.Sequence (except string and bytes). This includes list, tuple, and namedtuple.
  • collections.abc.Mapping (with sortable keys). This includes dict and collections.OrderedDict.
  • collections.abc.MappingView (with sortable keys).
  • attr.s classes.
  • Classes (including dataclass) that implement the __tf_flatten__ and __tf_unflatten__ methods. See examples in nest_util.py

Any other values are considered atoms. Not all collection types are considered nested structures. For example, the following types are considered atoms:

  • set; {"a", "b"} is an atom, while ["a", "b"] is a nested structure.
  • dataclass classes that don't implement the custom flattening/unflattening methods mentioned above.
  • tf.Tensor.
  • numpy.array.

tf.nest.is_nested checks whether an object is a nested structure or an atom. For example:

  tf.nest.is_nested("1234")
    False
  tf.nest.is_nested([1, 3, [4, 5]])
    True
  tf.nest.is_nested(((7, 8), (5, 6)))
    True
  tf.nest.is_nested([])
    True
  tf.nest.is_nested({"a": 1, "b": 2})
    True
  tf.nest.is_nested({"a": 1, "b": 2}.keys())
    True
  tf.nest.is_nested({"a": 1, "b": 2}.values())
    True
  tf.nest.is_nested({"a": 1, "b": 2}.items())
    True
  tf.nest.is_nested(set([1, 2]))
    False
  ones = tf.ones([2, 3])
  tf.nest.is_nested(ones)
    False

Functions

assert_same_structure(...): Asserts that two structures are nested in the same way.

flatten(...): Returns a flat list from a given structure.

is_nested(...): Returns true if its input is a nested structure.

map_structure(...): Creates a new structure by applying func to each atom in structure.

pack_sequence_as(...): Returns a given flattened sequence packed into a given structure.