# tensorplay.nested API

Source: https://www.tensorplay.cn/docs/api/tensorplay.nested.html

## Functions 4

[#](#api-tensorplay.nested.as_nested_tensor)

### as_nested_tensor

function[Full reference ↗](/docs/generated/tensorplay.nested.as_nested_tensor.html)

```python
tensorplay.nested.as_nested_tensor(ts, dtype=None, device=None, layout=None)
```

Constructs a nested tensor preserving autograd history from a tensor
or a list / tuple of tensors.

If a nested tensor is passed, it is returned directly unless the device
/ dtype differ.  A dense tensor of rank two or more is treated as a batch
of constituents of consistent size; its storage is shared when no device
/ dtype conversion is requested.  Constituents given as a list / tuple
are always copied into one packed buffer.

Parameters:

ts ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor) or List[[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)] or Tuple[[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)]) – a tensor to treat as a
nested tensor or a list / tuple of tensors with the same rank.

Keyword Arguments:

- dtype ([tensorplay.dtype](/docs/generated/tensorplay.DType.html#tensorplay.DType), optional) – desired dtype of the result. Default: the dtype of the first input.

- device ([tensorplay.device](/docs/generated/tensorplay.Device.html#tensorplay.Device), optional) – desired device of the result. Default: the device of the first input.

- layout – only the strided layout (None or 0) is supported.

Returns:

the nested tensor.

Return type:

[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)

[#](#api-tensorplay.nested.nested_tensor)

### nested_tensor

function[Full reference ↗](/docs/generated/tensorplay.nested.nested_tensor.html)

```python
tensorplay.nested.nested_tensor(ts, *, dtype=None, device=None, requires_grad=False, layout=None, pin_memory=False)
```

Constructs a nested tensor from a list / tuple of tensors.

Constituents must share the same rank; they are always copied into one
packed buffer sized to the total element count.

Parameters:

ts (List[[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)] or Tuple[[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)]) – tensors of the same rank.

Keyword Arguments:

- dtype ([tensorplay.dtype](/docs/generated/tensorplay.DType.html#tensorplay.DType), optional) – desired dtype of the result.

- device ([tensorplay.device](/docs/generated/tensorplay.Device.html#tensorplay.Device), optional) – desired device of the result.

- requires_grad ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – whether the result tracks gradients.

- layout – only the strided layout (None or 0) is supported.

- pin_memory ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – whether the packed buffer is pinned.

Returns:

the nested tensor.

Return type:

[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)

[#](#api-tensorplay.nested.nested_to_padded_tensor)

### nested_to_padded_tensor

function[Full reference ↗](/docs/generated/tensorplay.nested.nested_to_padded_tensor.html)

```python
tensorplay.nested.nested_to_padded_tensor()
```

nested_to_padded_tensor(Tensor self, float padding, int[]? output_size=None) -> Tensor

[#](#api-tensorplay.nested.to_padded_tensor)

### to_padded_tensor

function[Full reference ↗](/docs/generated/tensorplay.nested.to_padded_tensor.html)

```python
tensorplay.nested.to_padded_tensor(input, padding, output_size=None)
```

Pads a nested tensor into a regular dense tensor and returns it.

The leading entries of each output slice carry the nested data while the
trailing entries are filled with padding.  Padding always copies the
underlying data, since the nested and dense representations differ in
memory layout.

Parameters:

- input ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the nested tensor.

- padding ([float](https://docs.python.org/3/builtins/functions.html#float)) – the fill value for the trailing entries.

Keyword Arguments:

output_size (Tuple[[int](https://docs.python.org/3/builtins/functions.html#int)], optional) – the size of the output.  If
given, it must be large enough to contain all nested data;
otherwise the maximum extent of the constituents along each
dimension is inferred.

Returns:

the dense padded tensor.

Return type:

[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)