Module: tf.compat.v1.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
    
  

Note: A proper structure shall form a tree. The user shall ensure there is no cyclic references within the items in the structure, i.e., no references in the structure of the input of these functions should be recursive. The behavior is undefined if there is a cycle.

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.