returnn.tf.util.data
¶
Provides Data
, Dim
, SearchBeam
.
See Tensor and Dim for some higher-level description.
- returnn.tf.util.data.FeatureDim(description, dimension, **kwargs)[source]¶
DEPRECATED. Use
Dim
instead, and setting the kind is not needed anymore.- Parameters:
description (str)
dimension (int|None)
- Return type:
- returnn.tf.util.data.SpatialDim(description, dimension=None, **kwargs)[source]¶
DEPRECATED. Use
Dim
instead, and setting the kind is not needed anymore.- Parameters:
description (str)
dimension (int|None)
- Return type:
- class returnn.tf.util.data.BatchInfo(base, new_dim, new_dim_index=None)[source]¶
A batched tensor is a tensor with batch dimension, i.e. consisting of multiple samples/sequences which are supposed to be totally independent of each other.
The batch dim can consists out of one or more flattened “virtual” dims, which
BatchInfo
keeps track of. This class provides some additional information about the batch dimension. Only one instance per different type of batch-dim is expected (i.e. batch_info1 is batch_info2 <==> same batch info).When we pass data from the dataset to the network (in all cases (training, inference …) via
Runner
in the TF engine), we get a batch dimension due to the minibatch construction. This is a global batch size (usually dynamic, because every minibatch/step can have a different amount of samples, although we can also support static sizes, which is needed e.g. for TPUs) represented byBatchInfo.GlobalBatchDim
.When we do beam search (see
SearchBeam
), we have multiple hypotheses per batch item, and thus a different batch dimension.We can also pack arrays (multiple sequences) (also referred to as “flattened tensors”, “non-padded tensors”, “ragged tensors”). See e.g.
FlattenBatchLayer
orflatten_with_seq_len_mask()
. Also seetf.RaggedTensor
which also represents packed tensors (but only batch-major, although this is just a reinterpretation). We do not directly usetf.RaggedTensor
inData
to have robust and reliable code (which expectstf.Tensor
). However, we maybe can make use of some of the functions intf.ragged
.- Parameters:
base (BatchInfo|None) – If this is extended or based on another batch. Except of the batch dim of the dataset minibatch, we would always have a base.
new_dim (BatchInfo.VirtualDimBase|None)
new_dim_index (int|None)
In most cases, this constructor would probably not be used directly by the user.
- class FixedDim(size: Tensor | int, dim_tag: Dim | None = None)[source]¶
Represents a dim with fixed size.
- Parameters:
size
dim_tag
- class GlobalBatchDim(size: Tensor | int, dim_tag: Dim | None = None)[source]¶
Represents the global batch dim by the network (minibatch construction from the dataset).
- Parameters:
size
dim_tag
- class BeamDim(beam)[source]¶
Represents a search beam.
- Parameters:
beam (SearchBeam)
- class PaddedDim(dim_tag)[source]¶
Represents a dim with variable size, which is flattened with padding (not packed) into the batch.
- Parameters:
dim_tag (Dim)
- class PackedDim(dim_tag, key_axes)[source]¶
Represents a dim with variable sizes, which is packed (un-padded) into the batch. Variable w.r.t. other dims (must be per batch entry).
- Parameters:
dim_tag (Dim)
key_axes (list[BatchInfo.VirtualDimBase]) – most common case would be [GlobalBatchDim(…)], but [GlobalBatchDim(…),BeamDim(…)] is also common.
- classmethod make_global_batch_info(batch_dim)[source]¶
- Parameters:
batch_dim (tf.Tensor|int)
- Returns:
global batch info w.r.t. the network / graph
- Return type:
- classmethod make_global_broadcast_batch_info()[source]¶
- Returns:
BatchInfo with no virtual dims, s.t. the dimension is 1 (== prod([])) (broadcastable)
- Return type:
- property beam[source]¶
- Return type:
SearchBeam|None
- copy_extend_with_beam(beam)[source]¶
- Parameters:
beam (SearchBeam)
- Return type:
- copy_remove_dim(remove_dim)[source]¶
- Parameters:
remove_dim (VirtualDimBase)
- Return type:
- copy_set_beam(beam)[source]¶
- Parameters:
beam (SearchBeam|None)
- Return type:
- class returnn.tf.util.data.SearchBeam(beam_size, dependency=<class 'returnn.util.basic.NotSpecified'>, name=None, _next_frame=None)[source]¶
Represents info about the beam from some beam search (e.g. via
beam_search()
), e.g. such as the beam size, but also the dependencies. This is somewhat parallel toSearchChoices
, but simpler, and independent from the layers/network (returnn.tf.layers.base.LayerBase
).- Parameters:
beam_size (int)
dependency (SearchBeam|NotSpecified|None)
name (str|None)
_next_frame (SearchBeam|None)
- classmethod get_combined_beam(beam1, beam2=None, *beams)[source]¶
Combines beams. This will throw an exception if they cannot be combined. Note that in beam search (see
SearchChoices
), the logic to combine beams from different search choices happens in a generic way for all layers automatically viaTFNetwork._create_layer_layer_desc()
, so normally we already have the same beam. Unless we are at template construction.- Parameters:
beam1 (SearchBeam|None)
beam2 (SearchBeam|None)
beams (SearchBeam|None)
- Return type:
SearchBeam|None