# Copyright 2015 The TensorFlow Authors. All Rights Reserved.

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

# ==============================================================================

"""## Casting

TensorFlow provides several operations that you can use to cast tensor data

types in your graph.

@@string_to_number

@@to_double

@@to_float

@@to_bfloat16

@@to_int32

@@to_int64

@@cast

@@bitcast

@@saturate_cast

## Shapes and Shaping

TensorFlow provides several operations that you can use to determine the shape

of a tensor and change the shape of a tensor.

@@shape

@@shape_n

@@size

@@rank

@@reshape

@@squeeze

@@expand_dims

@@meshgrid

## Slicing and Joining

TensorFlow provides several operations to slice or extract parts of a tensor,

or join multiple tensors together.

@@slice

@@strided_slice

@@split

@@tile

@@pad

@@concat

@@pack

@@unpack

@@reverse_sequence

@@reverse

@@transpose

@@extract_image_patches

@@space_to_batch_nd

@@space_to_batch

@@required_space_to_batch_paddings

@@batch_to_space_nd

@@batch_to_space

@@space_to_depth

@@depth_to_space

@@gather

@@gather_nd

@@unique_with_counts

@@dynamic_partition

@@dynamic_stitch

@@boolean_mask

@@one_hot

@@sequence_mask

"""

from __future__ import absolute_import

from __future__ import division

from __future__ import print_function

import sys

import numpy as np

from tensorflow.python.framework import common_shapes

from tensorflow.python.framework import constant_op

from tensorflow.python.framework import dtypes

from tensorflow.python.framework import ops

from tensorflow.python.framework import tensor_shape

from tensorflow.python.framework import tensor_util

# 'Constant' gets imported in the module 'array_ops'.

from tensorflow.python.framework.constant_op import constant

from tensorflow.python.ops import gen_array_ops

from tensorflow.python.ops import gen_logging_ops

from tensorflow.python.ops import gen_math_ops

# go/tf-wildcard-import

# pylint: disable=wildcard-import

from tensorflow.python.ops.gen_array_ops import *

# pylint: enable=wildcard-import

# Used for slicing to specify a new 1 size dimension

newaxis = None

# We override the 'slice' for the "slice" op, so we keep python's

# existing 'slice' for later use in this module.

_baseslice = slice

# Aliases for some automatically-generated names.

listdiff = gen_array_ops.list_diff

def shape(input, name=None, out_type=dtypes.int32):

# pylint: disable=redefined-builtin

"""Returns the shape of a tensor.

This operation returns a 1-D integer tensor representing the shape of `input`.

For example:

```python

# 't' is [[[1, 1, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]]

shape(t) ==> [2, 2, 3]

```

Args:

input: A `Tensor` or `SparseTensor`.

name: A name for the operation (optional).

out_type: (Optional) The specified output type of the operation

(`int32` or `int64`). Defaults to tf.int32.

Returns:

A `Tensor` of type `out_type`.

"""

return shape_internal(input, name, optimize=True, out_type=out_type)

def shape_internal(input, name=None, optimize=True, out_type=dtypes.int32):

# pylint: disable=redefined-builtin

"""Returns the shape of a tensor.

Args:

input: A `Tensor` or `SparseTensor`.

name: A name for the operation (optional).

optimize: if true, encode the shape as a constant when possible.

out_type: (Optional) The specified output type of the operation

(`int32` or `int64`). Defaults to tf.int32.

Returns:

A `Tensor` of type `out_type`.

"""

with ops.name_scope(name, "Shape", [input]) as name:

if isinstance(input, (ops.SparseTensor, ops.SparseTensorValue)):

return gen_math_ops.cast(input.shape, out_type)

else:

input_tensor = ops.convert_to_tensor(input)

input_shape = input_tensor.get_shape()

if optimize and input_shape.is_fully_defined():

return constant(input_shape.as_list(), out_type, name=name)

return gen_array_ops.shape(input, name=name, out_type=out_type)

def size(input, name=None, out_type=dtypes.int32):

# pylint: disable=redefined-builtin

"""Returns the size of a tensor.

This operation returns an integer representing the number of elements in

`input`.

For example:

```python

# 't' is [[[1, 1, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]]]

size(t) ==> 12

```

Args:

input: A `Tensor` or `SparseTensor`.

name: A name for the operation (optional).

out_type: (Optional) The specified output type of the operation

(`int32` or `int64`). Defaults to tf.int32.

Returns:

A `Tensor` of type `out_type`. Defaults to tf.int32.

"""

return size_internal(input, name, optimize=True, out_type=out_type)

def size_internal(input, name=None, optimize=True, out_type=dtypes.int32):

# pylint: disable=redefined-builtin,protected-access

"""Returns the size of a tensor.

Args:

input: A `Tensor` or `SparseTensor`.

name: A name for the operation (optional).

optimize: if true, encode the size as a constant when possible.

out_type: (Optional) The specified output type of the operation

(`int32` or `int64`). Defaults to tf.int32.

Returns:

A `Tensor` of type `out_type`.

"""

with ops.name_scope(name, "Size", [input]) as name:

if isinstance(input, (ops.SparseTensor, ops.SparseTensorValue)):

return gen_math_ops._prod(

gen_math_ops.cast(input.shape, out_type), 0, name=name)

else:

input_tensor = ops.convert_to_tensor(input)

input_shape = input_tensor.get_shape()

if optimize and input_shape.is_fully_defined():

return constant(input_shape.num_elements(), out_type, name=name)

return gen_array_ops.size(input, name=name, out_type=out_type)

def rank(input, name=None):

# pylint: disable=redefined-builtin

"""Returns the rank of a tensor.

This operation returns an integer representing the rank of `input`.

For example:

```python

# 't' is [[[1, 1, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]]

# shape of tensor 't' is [2, 2, 3]

rank(t) ==> 3

```

**Note**: The rank of a tensor is not the same as the rank of a matrix. The

rank of a tensor is the number of indices required to uniquely select each

element of the tensor. Rank is also known as "order", "degree", or "ndims."

Args:

input: A `Tensor` or `SparseTensor`.

name: A name for the operation (optional).

Returns:

A `Tensor` of type `int32`.

"""

return rank_internal(input, name, optimize=True)

def rank_internal(input, name=None, optimize=True):

# pylint: disable=redefined-builtin

"""Returns the rank of a tensor.

Args:

input: A `Tensor` or `SparseTensor`.

name: A name for the operation (optional).

optimize: if true, encode the rank as a constant when possible.

Returns:

A `Tensor` of type `int32`.

"""

with ops.name_scope(name, "Rank", [input]) as name:

if isinstance(input, (ops.SparseTensor, ops.SparseTensorValue)):

return gen_array_ops.size(input.shape, name=name)

else:

input_tensor = ops.convert_to_tensor(input)

input_shape = input_tensor.get_shape()

if optimize and input_shape.ndims is not None:

return constant(input_shape.ndims, dtypes.int32, name=name)

return gen_array_ops.rank(input, name=name)

def _SliceHelper(tensor, slice_spec, var=None):

"""Overload for Tensor.__getitem__.

This operation extracts the specified region from the tensor.

The notation is similar to NumPy with the restriction that

currently only support basic indexing. That means that

using a tensor as input is not currently allowed

Some useful examples:

```

# strip leading and trailing 2 elements

foo = tf.constant([1,2,3,4,5,6])

print(foo[2:-2].eval()) # => [3,4]

# skip every row and reverse every column

foo = tf.constant([[1,2,3], [4,5,6], [7,8,9]])

print(foo[::2,::-1].eval()) # => [[3,2,1], [9,8,7]]

# Insert another dimension

foo = tf.constant([[1,2,3], [4,5,6], [7,8,9]])

print(foo[tf.newaxis, :, :].eval()) # => [[[3,2,1], [9,8,7]]]

print(foo[:, tf.newaxis, :].eval()) # => [[[3,2,1]], [[9,8,7]]]

print(foo[:, :, tf.newaxis].eval()) # => [[[3],[2],[1]], [[9],[8],[7]]]

# Ellipses (3 equivalent operations)

print(foo[tf.newaxis, :, :].eval()) # => [[[3,2,1], [9,8,7]]]

print(foo[tf.newaxis, ...].eval()) # => [[[3,2,1], [9,8,7]]]

print(foo[tf.newaxis].eval()) # => [[[3,2,1], [9,8,7]]]

```

Notes:

- `tf.newaxis` is `None` as in NumPy.

- An implicit ellipsis is placed at the end of the `slice_spec`

- NumPy advanced indexing is currently not supported.

Args:

tensor: An ops.Tensor object.

slice_spec: The arguments to Tensor.__getitem__.

var: In the case of variable slice assignment, the Variable

object to slice (i.e. tensor is the read-only view of this

variable).

Returns:

The appropriate slice of "tensor", based on "slice_spec".

Raises:

ValueError: If a slice range is negative size.

TypeError: If the slice indices aren't int, slice, or Ellipsis.

"""

if not isinstance(slice_spec, (list, tuple)):

slice_spec = [slice_spec]

begin, end, strides = [], [], []

index = 0

new_axis_mask, shrink_axis_mask = 0, 0

begin_mask, end_mask = 0, 0

ellipsis_mask = 0

for s in slice_spec:

if isinstance(s, _baseslice):

strides.append(s.step if s.step is not None else 1)

# python doesn't always use None when constructing ranges

# for example a[:] gives slice(None,sys.maxsize,None)

# whereas a[::1] gives slice(None,None,None)

if s.start is not None and s.start is not sys.maxsize:

begin.append(s.start)

else:

begin.append(0)

begin_mask |= (1 << index)

if s.stop is not None and s.stop != sys.maxsize:

end.append(s.stop)

else:

end.append(0)

end_mask |= (1 << index)

elif s is Ellipsis:

begin.append(0)

end.append(0)

strides.append(1)

ellipsis_mask |= (1 << index)

elif s is newaxis:

begin.append(0)

end.append(0)

strides.append(1)

new_axis_mask |= (1 << index)

else:

begin.append(s)

end.append(s + 1)

strides.append(1)

shrink_axis_mask |= (1 << index)

index += 1

# pack possibly involves often involves no tensors, so we must use op_scope

# correct graph

with ops.name_scope(None, "strided_slice",

[tensor] + begin + end + strides) as name:

if begin:

packed_begin, packed_end, packed_strides = pack(begin), pack(end), pack(

strides)

else:

empty = constant([], dtype=dtypes.int32)

packed_begin = packed_end = packed_strides = empty

return strided_slice(

tensor,

packed_begin,

packed_end,

packed_strides,

begin_mask=begin_mask,

end_mask=end_mask,

shrink_axis_mask=shrink_axis_mask,

new_axis_mask=new_axis_mask,

ellipsis_mask=ellipsis_mask,

var=var,

name=name)

# pylint: disable=undefined-variable,protected-access

def slice(input_, begin, size, name=None):

# pylint: disable=redefined-builtin

"""Extracts a slice from a tensor.

This operation extracts a slice of size `size` from a tensor `input` starting

at the location specified by `begin`. The slice `size` is represented as a

tensor shape, where `size[i]` is the number of elements of the 'i'th dimension

of `input` that you want to slice. The starting location (`begin`) for the

slice is represented as an offset in each dimension of `input`. In other

words, `begin[i]` is the offset into the 'i'th dimension of `input` that you

want to slice from.

`begin` is zero-based; `size` is one-based. If `size[i]` is -1,

all remaining elements in dimension i are included in the

slice. In other words, this is equivalent to setting:

`size[i] = input.dim_size(i) - begin[i]`

This operation requires that:

`0 <= begin[i] <= begin[i] + size[i] <= Di for i in [0, n]`

For example:

```

# 'input' is [[[1, 1, 1], [2, 2, 2]],

# [[3, 3, 3], [4, 4, 4]],

# [[5, 5, 5], [6, 6, 6]]]

tf.slice(input, [1, 0, 0], [1, 1, 3]) ==> [[[3, 3, 3]]]

tf.slice(input, [1, 0, 0], [1, 2, 3]) ==> [[[3, 3, 3],

[4, 4, 4]]]

tf.slice(input, [1, 0, 0], [2, 1, 3]) ==> [[[3, 3, 3]],

[[5, 5, 5]]]

```

Args:

input_: A `Tensor`.

begin: An `int32` or `int64` `Tensor`.

size: An `int32` or `int64` `Tensor`.

name: A name for the operation (optional).

Returns:

A `Tensor` the same type as `input`.

"""

return gen_array_ops._slice(input_, begin, size, name=name)

# pylint: disable=invalid-name

def strided_slice(input_,

begin,

end,

strides,

begin_mask=0,

end_mask=0,

ellipsis_mask=0,

new_axis_mask=0,

shrink_axis_mask=0,

var=None,

name=None):

"""Extracts a strided slice from a tensor.

To a first order, this operation extracts a slice of size `end - begin`

from a tensor `input`

starting at the location specified by `begin`. The slice continues by adding

`stride` to the `begin` index until all dimensions are not less than `end`.

Note that components of stride can be negative, which causes a reverse

slice.

This operation can be thought of an encoding of a numpy style sliced

range. Given a python slice input[<spec0>, <spec1>, ..., <specn>]

this function will be called as follows.

`begin`, `end`, and `strides` will be all length n. n is in general

not the same dimensionality as `input`.

For the ith spec,

`begin_mask`, `end_mask`, `ellipsis_mask`, `new_axis_mask`,

and `shrink_axis_mask` will have the ith bit corresponding to

the ith spec.

If the ith bit of `begin_mask` is non-zero, `begin[i]` is ignored and

the fullest possible range in that dimension is used instead.

`end_mask` works analogously, except with the end range.

`foo[5:,:,:3]` on a 7x8x9 tensor is equivalent to `foo[5:7,0:8,0:3]`.

`foo[::-1]` reverses a tensor with shape 8.

If the ith bit of `ellipsis_mask`, as many unspecified dimensions

as needed will be inserted between other dimensions. Only one

non-zero bit is allowed in `ellipsis_mask`.

For example `foo[3:5,...,4:5]` on a shape 10x3x3x10 tensor is

equivalent to `foo[3:5,:,:,4:5]` and

`foo[3:5,...]` is equivalent to `foo[3:5,:,:,:]`.

If the ith bit of `new_axis_mask` is one, then a `begin`,

`end`, and `stride` are ignored and a new length 1 dimension is

added at this point in the output tensor.

For example `foo[3:5,4]` on a 10x8 tensor produces a shape 2 tensor

whereas `foo[3:5,4:5]` produces a shape 2x1 tensor with shrink_mask

being 1<<1 == 2.

If the ith bit of `shrink_axis_mask` is one, then `begin`,

`end[i]`, and `stride[i]` are used to do a slice in the appropriate

dimension, but the output tensor will be reduced in dimensionality

by one. This is only valid if the ith entry of slice[i]==1.

NOTE: `begin` and `end` are zero-indexed`.

`strides` entries must be non-zero.

```

# 'input' is [[[1, 1, 1], [2, 2, 2]],

# [[3, 3, 3], [4, 4, 4]],

# [[5, 5, 5], [6, 6, 6]]]

tf.slice(input, [1, 0, 0], [2, 1, 3], [1, 1, 1]) ==> [[[3, 3, 3]]]

tf.slice(input, [1, 0, 0], [2, 2, 3], [1, 1, 1]) ==> [[[3, 3, 3],

[4, 4, 4]]]

tf.slice(input, [1, 1, 0], [2, -1, 3], [1, -1, 1]) ==>[[[4, 4, 4],

[3, 3, 3]]]

```

Args:

input_: A `Tensor`.

begin: An `int32` or `int64` `Tensor`.

end: An `int32` or `int64` `Tensor`.

strides: An `int32` or `int64` `Tensor`.

begin_mask: An `int32` mask.

end_mask: An `int32` mask.

ellipsis_mask: An `int32` mask.

new_axis_mask: An `int32` mask.

shrink_axis_mask: An `int32` mask.

var: The variable coresponding to `input_` or None

name: A name for the operation (optional).

Returns:

A `Tensor` the same type as `input`.

"""

op = gen_array_ops.strided_slice(

input=input_,

begin=begin,

end=end,

strides=strides,

name=name,

begin_mask=begin_mask,

end_mask=end_mask,

ellipsis_mask=ellipsis_mask,

new_axis_mask=new_axis_mask,

shrink_axis_mask=shrink_axis_mask)

def assign(val):

"""Closure that holds all the arguments to create an assignment."""

if var is None:

raise ValueError("Sliced assignment is only supported for variables")

return gen_array_ops.strided_slice_assign(

ref=var,

begin=begin,

end=end,

strides=strides,

value=val,

name=name + "_assign",

begin_mask=begin_mask,

end_mask=end_mask,

ellipsis_mask=ellipsis_mask,

new_axis_mask=new_axis_mask,

shrink_axis_mask=shrink_axis_mask)

op.assign = assign

return op

def _SliceHelperVar(var, slice_spec):

"""Creates a slice helper object given a variable.

This allows creating a sub-tensor from part of the current contents

of a variable.

See

[`Tensor.__getitem__`](../../api_docs/python/framework.md#Tensor.__getitem__)

for detailed examples of slicing.

This function in addition also allows assignment to a sliced range.

This is similar to `__setitem__` functionality in Python. However,

the syntax is different so that the user can capture the assignment

operation for grouping or passing to `sess.run()`.

For example,

```prettyprint

import tensorflow as tf

A = tf.Variable([[1,2,3], [4,5,6], [7,8,9]], dtype=tf.float32)

with tf.Session() as sess:

sess.run(tf.initialize_all_variables())

print sess.run(A[:2, :2]) # => [[1,2], [4,5]]

op = A[:2,:2].assign(22. * tf.ones((2, 2)))

print sess.run(op) # => [[22, 22, 3], [22, 22, 6], [7,8,9]]

```

Note that assignments currently do not support NumPy broadcasting

semantics.

Args:

var: An `ops.Variable` object.

slice_spec: The arguments to `Tensor.__getitem__`.

Returns:

The appropriate slice of "tensor", based on "slice_spec".

As an operator. The operator also has a `assign()` method

that can be used to generate an assignment operator.

Raises:

ValueError: If a slice range is negative size.

TypeError: If the slice indices aren't int, slice, or Ellipsis.

"""

return _SliceHelper(var._AsTensor(), slice_spec, var)

ops.Tensor._override_operator("__getitem__", _SliceHelper)

def pack(values, axis=0, name="pack"):

"""Packs a list of rank-`R` tensors into one rank-`(R+1)` tensor.

Packs the list of tensors in `values` into a tensor with rank one higher than

each tensor in `values`, by packing them along the `axis` dimension.

Given a list of length `N` of tensors of shape `(A, B, C)`;

if `axis == 0` then the `output` tensor will have the shape `(N, A, B, C)`.

if `axis == 1` then the `output` tensor will have the shape `(A, N, B, C)`.

Etc.

For example:

```prettyprint

# 'x' is [1, 4]

# 'y' is [2, 5]

# 'z' is [3, 6]

pack([x, y, z]) => [[1, 4], [2, 5], [3, 6]] # Pack along first dim.

pack([x, y, z], axis=1) => [[1, 2, 3], [4, 5, 6]]

```

This is the opposite of unpack. The numpy equivalent is

tf.pack([x, y, z]) = np.asarray([x, y, z])

Args:

values: A list of `Tensor` objects with the same shape and type.

axis: An `int`. The axis to pack along. Defaults to the first dimension.

Supports negative indexes.

name: A name for this operation (optional).

Returns:

output: A packed `Tensor` with the same type as `values`.

Raises:

ValueError: If `axis` is out of the range [-(R+1), R+1).

"""

if axis == 0:

try:

# If the input is a constant list, it can be converted to a constant op

return ops.convert_to_tensor(values, name=name)

except (TypeError, ValueError):

pass # Input list contains non-constant tensors

value_shape = ops.convert_to_tensor(values[0], name=name).get_shape()

if value_shape.ndims is not None:

expanded_num_dims = value_shape.ndims + 1

if axis < -expanded_num_dims or axis >= expanded_num_dims:

raise ValueError("axis = %d not in [%d, %d)" %

(axis, -expanded_num_dims, expanded_num_dims))

return gen_array_ops._pack(values, axis=axis, name=name)

# pylint: disable=invalid-name

def _autopacking_helper(list_or_tuple, dtype, name):

"""Converts the given list or tuple to a tensor by packing.

Args:

list_or_tuple: A (possibly nested) list or tuple containing a tensor.

dtype: The element type of the returned tensor.

name: A name for the returned tensor.

Returns:

A `tf.Tensor` with value equivalent to `list_or_tuple`.

"""

must_pack = False

converted_elems = []

with ops.name_scope(name) as scope:

for i, elem in enumerate(list_or_tuple):

if ops.is_dense_tensor_like(elem):

if dtype is not None and elem.dtype.base_dtype != dtype:

raise TypeError(

"Cannot convert a list containing a tensor of dtype "

"%s to %s (Tensor is: %r)" % (elem.dtype, dtype, elem))

converted_elems.append(elem)

must_pack = True

elif isinstance(elem, (list, tuple)):

converted_elem = _autopacking_helper(elem, dtype, str(i))

if ops.is_dense_tensor_like(converted_elem):

must_pack = True

converted_elems.append(converted_elem)

else:

converted_elems.append(elem)

if must_pack:

elems_as_tensors = []

for i, elem in enumerate(converted_elems):

if ops.is_dense_tensor_like(elem):

elems_as_tensors.append(elem)

else:

# NOTE(mrry): This is inefficient, but it enables us to

# handle the case where the list arguments are other

# convertible-to-tensor types, such as numpy arrays.

elems_as_tensors.append(

constant_op.constant(elem, dtype=dtype, name=str(i)))

return gen_array_ops._pack(elems_as_tensors, name=scope)

else:

return converted_elems

def _get_dtype_from_nested_lists(list_or_tuple):

"""Returns the dtype of any tensor-like object in `list_or_tuple`, if found.

Args:

list_or_tuple: A list or tuple representing an object that can be

converted to a `tf.Tensor`.

Returns:

The dtype of any tensor-like object in `list_or_tuple`, or `None` if no

such object exists.

"""

for elem in list_or_tuple:

if ops.is_dense_tensor_like(elem):

return elem.dtype.base_dtype

elif isinstance(elem, (list, tuple)):

maybe_dtype = _get_dtype_from_nested_lists(elem)

if maybe_dtype is not None:

return maybe_dtype

return None

def _autopacking_conversion_function(v, dtype=None, name=None, as_ref=False):

"""Tensor conversion function that automatically packs arguments."""

if as_ref:

return NotImplemented

inferred_dtype = _get_dtype_from_nested_lists(v)

if inferred_dtype is None:

# We did not find any tensor-like objects in the nested lists, so defer to

# other conversion functions.

return NotImplemented

if dtype is not None and dtype != inferred_dtype:

return NotImplemented

return _autopacking_helper(v, inferred_dtype, name or "packed")

# pylint: enable=invalid-name

# NOTE: Register this conversion function to run *before* one that

# assumes every element is a value.

ops.register_tensor_conversion_function(

(list, tuple), _autopacking_conversion_function, 99)

def unpack(value, num=None, axis=0, name="unpack"):

"""Unpacks the given dimension of a rank-`R` tensor into rank-`(R-1)` tensors.

Unpacks `num` tensors from `value` by chipping it along the `axis` dimension.

If `num` is not specified (the default), it is inferred from `value`'s shape.

If `value.shape[axis]` is not known, `ValueError` is raised.

For example, given a tensor of shape `(A, B, C, D)`;

If `axis == 0` then the i'th tensor in `output` is the slice

`value[i, :, :, :]` and each tensor in `output` will have shape `(B, C, D)`.

(Note that the dimension unpacked along is gone, unlike `split`).

If `axis == 1` then the i'th tensor in `output` is the slice

`value[:, i, :, :]` and each tensor in `output` will have shape `(A, C, D)`.

Etc.

This is the opposite of pack. The numpy equivalent is

tf.unpack(x, n) = list(x)

Args:

value: A rank `R > 0` `Tensor` to be unpacked.

num: An `int`. The length of the dimension `axis`. Automatically inferred

if `None` (the default).

axis: An `int`. The axis to unpack along. Defaults to the first

dimension. Supports negative indexes.

name: A name for the operation (optional).

Returns:

The list of `Tensor` objects unpacked from `value`.

Raises:

ValueError: If `num` is unspecified and cannot be inferred.

ValueError: If `axis` is out of the range [-R, R).

"""

if num is None:

value = ops.convert_to_tensor(value)

value_shape = value.get_shape()

if value_shape.ndims is not None:

if axis < -value_shape.ndims or axis >= value_shape.ndims:

raise ValueError("axis = %d not in [%d, %d)" %

(axis, -value_shape.ndims, value_shape.ndims))

num = value_shape[axis].value

if num is None:

raise ValueError("Cannot infer num from shape %s" % value_shape)

return gen_array_ops._unpack(value, num=num, axis=axis, name=name)

def concat(concat_dim, values, name="concat"):

"""Concatenates tensors along one dimension.

Concatenates the list of tensors `values` along dimension `concat_dim`. If

`values[i].shape = [D0, D1, ... Dconcat_dim(i), ...Dn]`, the concatenated

result has shape

[D0, D1, ... Rconcat_dim, ...Dn]

where

Rconcat_dim = sum(Dconcat_dim(i))

That is, the data from the input tensors is joined along the `concat_dim`

dimension.

The number of dimensions of the input tensors must match, and all dimensions

except `concat_dim` must be equal.

For example:

```python

t1 = [[1, 2, 3], [4, 5, 6]]

t2 = [[7, 8, 9], [10, 11, 12]]

tf.concat(0, [t1, t2]) ==> [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]]

tf.concat(1, [t1, t2]) ==> [[1, 2, 3, 7, 8, 9], [4, 5, 6, 10, 11, 12]]

# tensor t3 with shape [2, 3]

# tensor t4 with shape [2, 3]

tf.shape(tf.concat(0, [t3, t4])) ==> [4, 3]

tf.shape(tf.concat(1, [t3, t4])) ==> [2, 6]

```

Note: If you are concatenating along a new axis consider using pack.

E.g.

```python

tf.concat(axis, [tf.expand_dims(t, axis) for t in tensors])

```

can be rewritten as

```python

tf.pack(tensors, axis=axis)

```

Args:

concat_dim: 0-D `int32` `Tensor`. Dimension along which to concatenate.

values: A list of `Tensor` objects or a single `Tensor`.

name: A name for the operation (optional).

Returns:

A `Tensor` resulting from concatenation of the input tensors.

"""

if not isinstance(values, (list, tuple)):

values = [values]

# TODO(mrry): Change to return values?

if len(values) == 1: # Degenerate case of one tensor.

# Make a throwaway call to convert_to_tensor to make sure

# that concat_dim is of the correct type, and make sure that

# the returned tensor is a scalar.

# TODO(keveman): Implement a standalone type and shape checker.

with ops.name_scope(name) as scope:

ops.convert_to_tensor(concat_dim,

name="concat_dim",

dtype=dtypes.int32).get_shape(

).assert_is_compatible_with(tensor_shape.scalar())

return identity(values[0], name=scope)

return gen_array_ops._concat(concat_dim=concat_dim,

values=values,

name=name)

ops.RegisterShape("Pack")(common_shapes.call_cpp_shape_fn)

ops.RegisterShape("Unpack")(common_shapes.call_cpp_shape_fn)

@ops.RegisterShape("Concat")

def _ConcatShape(op):

return common_shapes.call_cpp_shape_fn(op, input_tensors_needed=[0])

ops.RegisterShape("ConcatOffset")(common_shapes.call_cpp_shape_fn)

def boolean_mask(tensor, mask, name="boolean_mask"):

"""Apply boolean mask to tensor. Numpy equivalent is `tensor[mask]`.

```python

# 1-D example

tensor = [0, 1, 2, 3]

mask = [True, False, True, False]

boolean_mask(tensor, mask) ==> [0, 2]

```

In general, `0 < dim(mask) = K <= dim(tensor)`, and `mask`'s shape must match

the first K dimensions of `tensor`'s shape. We then have:

`boolean_mask(tensor, mask)[i, j1,...,jd] = tensor[i1,...,iK,j1,...,jd]`

where `(i1,...,iK)` is the ith `True` entry of `mask` (row-major order).

Args:

tensor: N-D tensor.

mask: K-D boolean tensor, K <= N and K must be known statically.

name: A name for this operation (optional).

Returns:

Tensor populated by entries in `tensor` corresponding to `True` values in

`mask`.

Raises:

ValueError: If shapes do not conform.

Examples:

```python

# 2-D example

tensor = [[1, 2], [3, 4], [5, 6]]

mask = [True, False, True]

boolean_mask(tensor, mask) ==> [[1, 2], [5, 6]]

```

"""

def _apply_mask_1d(reshaped_tensor, mask):

"""Mask tensor along dimension 0 with a 1-D mask."""

indices = squeeze(where(mask), squeeze_dims=[1])

return gather(reshaped_tensor, indices)

with ops.name_scope(name, values=[tensor, mask]):

tensor = ops.convert_to_tensor(tensor, name="tensor")

mask = ops.convert_to_tensor(mask, name="mask")

shape_mask = mask.get_shape()

ndims_mask = shape_mask.ndims

shape_tensor = tensor.get_shape()

if ndims_mask == 0:

raise ValueError("mask cannot be scalar.")

if ndims_mask is None:

raise ValueError(

"mask dimensions must be specified, even if some dimensions are None"

". E.g. shape=[None] is ok, but shape=None is not.")

shape_tensor[:ndims_mask].assert_is_compatible_with(shape_mask)

tensor = reshape(tensor, concat(0, [[-1], shape(tensor)[ndims_mask:]]))

first_dim = shape_tensor[:ndims_mask].num_elements()

tensor.set_shape(

tensor_shape.as_shape([first_dim])

.concatenate(shape_tensor[ndims_mask:]))

mask = reshape(mask, [-1])

return _apply_mask_1d(tensor, mask)

def sparse_mask(a, mask_indices, name=None):

"""Masks elements of `IndexedSlices`.

Given an `IndexedSlices` instance `a`, returns another `IndexedSlices` that

contains a subset of the slices of `a`. Only the slices at indices not

specified in `mask_indices` are returned.

This is useful when you need to extract a subset of slices in an

`IndexedSlices` object.

For example:

```python

# `a` contains slices at indices [12, 26, 37, 45] from a large tensor

# with shape [1000, 10]

a.indices => [12, 26, 37, 45]

tf.shape(a.values) => [4, 10]

# `b` will be the subset of `a` slices at its second and third indices, so

# we want to mask its first and last indices (which are at absolute

# indices 12, 45)

b = tf.sparse_mask(a, [12, 45])

b.indices => [26, 37]

tf.shape(b.values) => [2, 10]

```

Args:

* `a`: An `IndexedSlices` instance.

* `mask_indices`: Indices of elements to mask.

* `name`: A name for the operation (optional).

Returns:

The masked `IndexedSlices` instance.

"""

with ops.name_scope(name, "sparse_mask", [a, mask_indices]) as name:

indices = a.indices

out_indices, to_gather = listdiff(indices, mask_indices)

out_values = gather(a.values, to_gather, name=name)

return ops.IndexedSlices(out_values, out_indices, a.dense_shape)

def split(split_dim, num_split, value, name="split"):

"""Splits a tensor into `num_split` tensors along one dimension.

Splits `value` along dimension `split_dim` into `num_split` smaller tensors.

Requires that `num_split` evenly divide `value.shape[split_dim]`.