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.

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
• 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.