# Module: tf.compat.v1.nest

<br />

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`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/Tensor) only contains [`tf.Tensor`](https://www.tensorflow.org/versions/r2.13/api_docs/python/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](https://en.wikipedia.org/wiki/Nesting_(computing)#Data_structures).

The following collection types are recognized by [`tf.nest`](https://www.tensorflow.org/versions/r2.13/api_docs/python/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](https://www.attrs.org/).

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](https://docs.python.org/library/dataclasses.html)
- [`tf.Tensor`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/Tensor)
- `numpy.array`

[`tf.nest.is_nested`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/nest/is_nested) checks whether an object is a nested structure or an atom.
For example:

<br />

      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
        
      
<br />

> [!NOTE]
> **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(...)`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/nest/assert_same_structure): Asserts that two structures are nested in the same way.

[`flatten(...)`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/nest/flatten): Returns a flat list from a given structure.

[`is_nested(...)`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/nest/is_nested): Returns true if its input is a nested structure.

[`map_structure(...)`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/nest/map_structure): Creates a new structure by applying `func` to each atom in `structure`.

[`pack_sequence_as(...)`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/nest/pack_sequence_as): Returns a given flattened sequence packed into a given structure.