diff options
Diffstat (limited to 'tensorflow/g3doc/api_docs/python')
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/array_ops.md | 1025 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/client.md | 638 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/constant_op.md | 565 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/control_flow_ops.md | 590 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/framework.md | 2079 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/image.md | 857 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/index.md | 352 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/io_ops.md | 1956 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/math_ops.md | 1883 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/nn.md | 1306 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/ops.md | 10 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/python_io.md | 104 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/sparse_ops.md | 502 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/state_ops.md | 1383 | ||||
| -rw-r--r-- | tensorflow/g3doc/api_docs/python/train.md | 1825 |
15 files changed, 15075 insertions, 0 deletions
diff --git a/tensorflow/g3doc/api_docs/python/array_ops.md b/tensorflow/g3doc/api_docs/python/array_ops.md new file mode 100644 index 0000000000..eecb442f1c --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/array_ops.md @@ -0,0 +1,1025 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Tensor Transformations +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Casting](#AUTOGENERATED-casting) + * [tf.string_to_number(string_tensor, out_type=None, name=None)](#string_to_number) + * [tf.to_double(x, name='ToDouble')](#to_double) + * [tf.to_float(x, name='ToFloat')](#to_float) + * [tf.to_bfloat16(x, name='ToBFloat16')](#to_bfloat16) + * [tf.to_int32(x, name='ToInt32')](#to_int32) + * [tf.to_int64(x, name='ToInt64')](#to_int64) + * [tf.cast(x, dtype, name=None)](#cast) +* [Shapes and Shaping](#AUTOGENERATED-shapes-and-shaping) + * [tf.shape(input, name=None)](#shape) + * [tf.size(input, name=None)](#size) + * [tf.rank(input, name=None)](#rank) + * [tf.reshape(tensor, shape, name=None)](#reshape) + * [tf.squeeze(input, squeeze_dims=None, name=None)](#squeeze) + * [tf.expand_dims(input, dim, name=None)](#expand_dims) +* [Slicing and Joining](#AUTOGENERATED-slicing-and-joining) + * [tf.slice(input_, begin, size, name=None)](#slice) + * [tf.split(split_dim, num_split, value, name='split')](#split) + * [tf.tile(input, multiples, name=None)](#tile) + * [tf.pad(input, paddings, name=None)](#pad) + * [tf.concat(concat_dim, values, name='concat')](#concat) + * [tf.pack(values, name='pack')](#pack) + * [tf.unpack(value, num=None, name='unpack')](#unpack) + * [tf.reverse_sequence(input, seq_lengths, seq_dim, name=None)](#reverse_sequence) + * [tf.reverse(tensor, dims, name=None)](#reverse) + * [tf.transpose(a, perm=None, name='transpose')](#transpose) + * [tf.gather(params, indices, name=None)](#gather) + * [tf.dynamic_partition(data, partitions, num_partitions, name=None)](#dynamic_partition) + * [tf.dynamic_stitch(indices, data, name=None)](#dynamic_stitch) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Casting <div class="md-anchor" id="AUTOGENERATED-casting">{#AUTOGENERATED-casting}</div> + +TensorFlow provides several operations that you can use to cast tensor data +types in your graph. + +- - - + +### tf.string_to_number(string_tensor, out_type=None, name=None) <div class="md-anchor" id="string_to_number">{#string_to_number}</div> + +Converts each string in the input Tensor to the specified numeric type. + +(Note that int32 overflow results in an error while float overflow +results in a rounded value.) + +##### Args: + + +* <b>string_tensor</b>: A `Tensor` of type `string`. +* <b>out_type</b>: An optional `tf.DType` from: `tf.float32, tf.int32`. Defaults to `tf.float32`. + The numeric type to interpret each string in string_tensor as. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `out_type`. + A Tensor of the same shape as the input string_tensor. + + +- - - + +### tf.to_double(x, name='ToDouble') <div class="md-anchor" id="to_double">{#to_double}</div> + +Casts a tensor to type `float64`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `float64`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `float64`. + + +- - - + +### tf.to_float(x, name='ToFloat') <div class="md-anchor" id="to_float">{#to_float}</div> + +Casts a tensor to type `float32`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `float32`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `float32`. + + +- - - + +### tf.to_bfloat16(x, name='ToBFloat16') <div class="md-anchor" id="to_bfloat16">{#to_bfloat16}</div> + +Casts a tensor to type `bfloat16`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `bfloat16`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `bfloat16`. + + +- - - + +### tf.to_int32(x, name='ToInt32') <div class="md-anchor" id="to_int32">{#to_int32}</div> + +Casts a tensor to type `int32`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `int32`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `int32`. + + +- - - + +### tf.to_int64(x, name='ToInt64') <div class="md-anchor" id="to_int64">{#to_int64}</div> + +Casts a tensor to type `int64`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `int64`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `int64`. + + +- - - + +### tf.cast(x, dtype, name=None) <div class="md-anchor" id="cast">{#cast}</div> + +Casts a tensor to a new type. + +The operation casts `x` (in case of `Tensor`) or `x.values` +(in case of `SparseTensor`) to `dtype`. + +For example: + +```python +# tensor `a` is [1.8, 2.2], dtype=tf.float +tf.cast(a, tf.int32) ==> [1, 2] # dtype=tf.int32 +``` + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>dtype</b>: The destination type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `dtype`. + + + +## Shapes and Shaping <div class="md-anchor" id="AUTOGENERATED-shapes-and-shaping">{#AUTOGENERATED-shapes-and-shaping}</div> + +TensorFlow provides several operations that you can use to determine the shape +of a tensor and change the shape of a tensor. + +- - - + +### tf.shape(input, name=None) <div class="md-anchor" id="shape">{#shape}</div> + +Returns the shape of a tensor. + +This operation returns a 1-D integer tensor representing the shape of `input`. + +For example: + +```prettyprint +# 't' is [[[1, 1, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]] +shape(t) ==> [2, 2, 3] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. + + +- - - + +### tf.size(input, name=None) <div class="md-anchor" id="size">{#size}</div> + +Returns the size of a tensor. + +This operation returns an integer representing the number of elements in +`input`. + +For example: + +```prettyprint +# 't' is [[[1, 1,, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]]] +size(t) ==> 12 +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. + + +- - - + +### tf.rank(input, name=None) <div class="md-anchor" id="rank">{#rank}</div> + +Returns the rank of a tensor. + +This operation returns an integer representing the rank of `input`. + +For example: + +```prettyprint +# '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: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. + + +- - - + +### tf.reshape(tensor, shape, name=None) <div class="md-anchor" id="reshape">{#reshape}</div> + +Reshapes a tensor. + +Given `tensor`, this operation returns a tensor that has the same values +as `tensor` with shape `shape`. + +If `shape` is the special value `[-1]`, then `tensor` is flattened and the +operation outputs a 1-D tensor with all elements of `tensor`. + +If `shape` is 1-D or higher, then the operation returns a tensor with shape +`shape` filled with the values of `tensor`. In this case, the number of elements +implied by `shape` must be the same as the number of elements in `tensor`. + +For example: + +```prettyprint +# tensor 't' is [1, 2, 3, 4, 5, 6, 7, 8, 9] +# tensor 't' has shape [9] +reshape(t, [3, 3]) ==> [[1, 2, 3] + [4, 5, 6] + [7, 8, 9]] + +# tensor 't' is [[[1, 1], [2, 2]] +# [[3, 3], [4, 4]]] +# tensor 't' has shape [2, 2] +reshape(t, [2, 4]) ==> [[1, 1, 2, 2] + [3, 3, 4, 4]] + +# tensor 't' is [[[1, 1, 1], +# [2, 2, 2]], +# [[3, 3, 3], +# [4, 4, 4]], +# [[5, 5, 5], +# [6, 6, 6]]] +# tensor 't' has shape [3, 2, 3] +# pass '[-1]' to flatten 't' +reshape(t, [-1]) ==> [1, 1, 1, 2, 2, 2, 3, 3, 3, 4, 4, 4, 5, 5, 5, 6, 6, 6] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. +* <b>shape</b>: A `Tensor` of type `int32`. Defines the shape of the output tensor. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `tensor`. + + +- - - + +### tf.squeeze(input, squeeze_dims=None, name=None) <div class="md-anchor" id="squeeze">{#squeeze}</div> + +Removes dimensions of size 1 from the shape of a tensor. + +Given a tensor `input`, this operation returns a tensor of the same type with +all dimensions of size 1 removed. If you don't want to remove all size 1 +dimensions, you can remove specific size 1 dimensions by specifying +`squeeze_dims`. + +For example: + +```prettyprint +# 't' is a tensor of shape [1, 2, 1, 3, 1, 1] +shape(squeeze(t)) ==> [2, 3] +``` + +Or, to remove specific size 1 dimensions: + +```prettyprint +# 't' is a tensor of shape [1, 2, 1, 3, 1, 1] +shape(squeeze(t, [2, 4])) ==> [1, 2, 3, 1] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. The `input` to squeeze. +* <b>squeeze_dims</b>: An optional list of `ints`. Defaults to `[]`. + If specified, only squeezes the dimensions listed. The dimension + index starts at 0. It is an error to squeeze a dimension that is not 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + Contains the same data as `input`, but has one or more dimensions of + size 1 removed. + + +- - - + +### tf.expand_dims(input, dim, name=None) <div class="md-anchor" id="expand_dims">{#expand_dims}</div> + +Inserts a dimension of 1 into a tensor's shape. + +Given a tensor `input`, this operation inserts a dimension of 1 at the +dimension index `dim` of `input`'s shape. The dimension index `dim` starts at +zero; if you specify a negative number for `dim` it is counted backward from +the end. + +This operation is useful if you want to add a batch dimension to a single +element. For example, if you have a single image of shape `[height, width, +channels]`, you can make it a batch of 1 image with `expand_dims(image, 0)`, +which will make the shape `[1, height, width, channels]`. + +Other examples: + +```prettyprint +# 't' is a tensor of shape [2] +shape(expand_dims(t, 0)) ==> [1, 2] +shape(expand_dims(t, 1)) ==> [2, 1] +shape(expand_dims(t, -1)) ==> [2, 1] + +# 't2' is a tensor of shape [2, 3, 5] +shape(expand_dims(t2, 0)) ==> [1, 2, 3, 5] +shape(expand_dims(t2, 2)) ==> [2, 3, 1, 5] +shape(expand_dims(t2, 3)) ==> [2, 3, 5, 1] +``` + +This operation requires that: + +`-1-input.dims() <= dim <= input.dims()` + +This operation is related to `squeeze()`, which removes dimensions of +size 1. + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>dim</b>: A `Tensor` of type `int32`. + 0-D (scalar). Specifies the dimension index at which to + expand the shape of `input`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + Contains the same data as `input`, but its shape has an additional + dimension of size 1 added. + + + +## Slicing and Joining <div class="md-anchor" id="AUTOGENERATED-slicing-and-joining">{#AUTOGENERATED-slicing-and-joining}</div> + +TensorFlow provides several operations to slice or extract parts of a tensor, +or join multiple tensors together. + +- - - + +### tf.slice(input_, begin, size, name=None) <div class="md-anchor" id="slice">{#slice}</div> + +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: + + +* <b>input_</b>: A `Tensor`. +* <b>begin</b>: An `int32` or `int64` `Tensor`. +* <b>size</b>: An `int32` or `int64` `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` the same type as `input`. + + +- - - + +### tf.split(split_dim, num_split, value, name='split') <div class="md-anchor" id="split">{#split}</div> + +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]`. + +For example: + +```python +# 'value' is a tensor with shape [5, 30] +# Split 'value' into 3 tensors along dimension 1 +split0, split1, split2 = tf.split(1, 3, value) +tf.shape(split0) ==> [5, 10] +``` + +##### Args: + + +* <b>split_dim</b>: A 0-D `int32` `Tensor`. The dimension along which to split. + Must be in the range `[0, rank(value))`. +* <b>num_split</b>: A 0-D `int32` `Tensor`. The number of ways to split. +* <b>value</b>: The `Tensor` to split. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + `num_split` `Tensor` objects resulting from splitting `value`. + + +- - - + +### tf.tile(input, multiples, name=None) <div class="md-anchor" id="tile">{#tile}</div> + +Constructs a tensor by tiling a given tensor. + +This operation creates a new tensor by replicating `input` `multiples` times. +The output tensor's i'th dimension has `input.dims(i) * multiples[i]` elements, +and the values of `input` are replicated `multiples[i]` times along the 'i'th +dimension. For example, tiling `[a b c d]` by `[2]` produces +`[a b c d a b c d]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. 1-D or higher. +* <b>multiples</b>: A `Tensor` of type `int32`. + 1-D. Length must be the same as the number of dimensions in `input` +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.pad(input, paddings, name=None) <div class="md-anchor" id="pad">{#pad}</div> + +Pads a tensor with zeros. + +This operation pads a `input` with zeros according to the `paddings` you +specify. `paddings` is an integer tensor with shape `[Dn, 2]`, where n is the +rank of `input`. For each dimension D of `input`, `paddings[D, 0]` indicates +how many zeros to add before the contents of `input` in that dimension, and +`paddings[D, 1]` indicates how many zeros to add after the contents of `input` +in that dimension. + +The padded size of each dimension D of the output is: + +`paddings(D, 0) + input.dim_size(D) + paddings(D, 1)` + +For example: + +```prettyprint +# 't' is [[1, 1], [2, 2]] +# 'paddings' is [[1, 1]], [2, 2]] +# rank of 't' is 2 +pad(t, paddings) ==> [[0, 0, 0, 0, 0] + [0, 0, 0, 0, 0] + [0, 1, 1, 0, 0] + [[0, 2, 2, 0, 0] + [0, 0, 0, 0, 0]] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>paddings</b>: A `Tensor` of type `int32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.concat(concat_dim, values, name='concat') <div class="md-anchor" id="concat">{#concat}</div> + +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] +``` + +##### Args: + + +* <b>concat_dim</b>: 0-D `int32` `Tensor`. Dimension along which to concatenate. +* <b>values</b>: A list of `Tensor` objects or a single `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` resulting from concatenation of the input tensors. + + +- - - + +### tf.pack(values, name='pack') <div class="md-anchor" id="pack">{#pack}</div> + +Packs a list of rank-`R` tensors into one rank-`(R+1)` tensor. + +Packs tensors in `values` into a tensor with rank one higher than each tensor +in `values` and shape `[len(values)] + values[0].shape`. The output satisfies +`output[i, ...] = values[i][...]`. + +This is the opposite of unpack. The numpy equivalent is + + tf.pack([x, y, z]) = np.asarray([x, y, z]) + +##### Args: + + +* <b>values</b>: A list of `Tensor` objects with the same shape and type. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + +* <b>output</b>: A packed `Tensor` with the same type as `values`. + + +- - - + +### tf.unpack(value, num=None, name='unpack') <div class="md-anchor" id="unpack">{#unpack}</div> + +Unpacks the outer dimension of a rank-`R` tensor into rank-`(R-1)` tensors. + +Unpacks `num` tensors from `value` along the first dimension. +If `num` is not specified (the default), it is inferred from `value`'s shape. +If `value.shape[0]` is not known, `ValueError` is raised. + +The ith tensor in `output` is the slice `value[i, ...]`. Each tensor in +`output` has shape `value.shape[1:]`. + +This is the opposite of pack. The numpy equivalent is + + tf.unpack(x, n) = list(x) + +##### Args: + + +* <b>value</b>: A rank `R > 0` `Tensor` to be unpacked. +* <b>num</b>: An `int`. The first dimension of value. Automatically inferred if + `None` (the default). +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The list of `Tensor` objects unpacked from `value`. + +##### Raises: + + +* <b>ValueError</b>: If `num` is unspecified and cannot be inferred. + + +- - - + +### tf.reverse_sequence(input, seq_lengths, seq_dim, name=None) <div class="md-anchor" id="reverse_sequence">{#reverse_sequence}</div> + +Reverses variable length slices in dimension `seq_dim`. + +This op first slices `input` along the first dimension, and for each slice `i`, +reverses the first `seq_lengths[i]` elements along the dimension `seq_dim`. + +The elements of `seq_lengths` must obey `seq_lengths[i] < input.dims[seq_dim]`, +and `seq_lengths` must be a vector of length `input.dims(0)`. + +The output slice `i` along dimension 0 is then given by input slice `i`, with +the first `seq_lengths[i]` slices along dimension `seq_dim` reversed. + +For example: + +```prettyprint +# Given this: +seq_dim = 1 +input.dims = (4, ...) +seq_lengths = [7, 2, 3, 5] + +# then slices of input are reversed on seq_dim, but only up to seq_lengths: +output[0, 0:7, :, ...] = input[0, 7:0:-1, :, ...] +output[1, 0:2, :, ...] = input[1, 2:0:-1, :, ...] +output[2, 0:3, :, ...] = input[2, 3:0:-1, :, ...] +output[3, 0:5, :, ...] = input[3, 5:0:-1, :, ...] + +# while entries past seq_lens are copied through: +output[0, 7:, :, ...] = input[0, 7:, :, ...] +output[1, 2:, :, ...] = input[1, 2:, :, ...] +output[2, 3:, :, ...] = input[2, 3:, :, ...] +output[3, 2:, :, ...] = input[3, 2:, :, ...] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. The input to reverse. +* <b>seq_lengths</b>: A `Tensor` of type `int64`. + 1-D with length `input.dims(0)` and + `max(seq_lengths) < input.dims(seq_dim)` +* <b>seq_dim</b>: An `int`. The dimension which is partially reversed. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + The partially reversed input. It has the same shape as `input`. + + +- - - + +### tf.reverse(tensor, dims, name=None) <div class="md-anchor" id="reverse">{#reverse}</div> + +Reverses specific dimensions of a tensor. + +Given a `tensor`, and a `bool` tensor `dims` representing the dimensions +of `tensor`, this operation reverses each dimension i of `tensor` where +`dims[i]` is `True`. + +`tensor` can have up to 8 dimensions. The number of dimensions +of `tensor` must equal the number of elements in `dims`. In other words: + +`rank(tensor) = size(dims)` + +For example: + +```prettyprint +# tensor 't' is [[[[ 0, 1, 2, 3], +# [ 4, 5, 6, 7], +# [ 8, 9, 10, 11]], +# [[12, 13, 14, 15], +# [16, 17, 18, 19], +# [20, 21, 22, 23]]]] +# tensor 't' shape is [1, 2, 3, 4] + +# 'dims' is [False, False, False, True] +reverse(t, dims) ==> [[[[ 3, 2, 1, 0], + [ 7, 6, 5, 4], + [ 11, 10, 9, 8]], + [[15, 14, 13, 12], + [19, 18, 17, 16], + [23, 22, 21, 20]]]] + +# 'dims' is [False, True, False, False] +reverse(t, dims) ==> [[[[12, 13, 14, 15], + [16, 17, 18, 19], + [20, 21, 22, 23] + [[ 0, 1, 2, 3], + [ 4, 5, 6, 7], + [ 8, 9, 10, 11]]]] + +# 'dims' is [False, False, True, False] +reverse(t, dims) ==> [[[[8, 9, 10, 11], + [4, 5, 6, 7], + [0, 1, 2, 3]] + [[20, 21, 22, 23], + [16, 17, 18, 19], + [12, 13, 14, 15]]]] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `bool`, `float32`, `float64`. + Up to 8-D. +* <b>dims</b>: A `Tensor` of type `bool`. 1-D. The dimensions to reverse. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `tensor`. The same shape as `tensor`. + + +- - - + +### tf.transpose(a, perm=None, name='transpose') <div class="md-anchor" id="transpose">{#transpose}</div> + +Transposes `a`. Permutes the dimensions according to `perm`. + +The returned tensor's dimension i will correspond to the input dimension +`perm[i]`. If `perm` is not given, it is set to (n-1...0), where n is +the rank of the input tensor. Hence by default, this operation performs a +regular matrix transpose on 2-D input Tensors. + +For example: + +```python +# 'x' is [[1 2 3] +# [4 5 6]] +tf.transpose(x) ==> [[1 4] + [2 5] + [3 6]] + +# Equivalently +tf.transpose(x perm=[0, 1]) ==> [[1 4] + [2 5] + [3 6]] + +# 'perm' is more useful for n-dimensional tensors, for n > 2 +# 'x' is [[[1 2 3] +# [4 5 6]] +# [[7 8 9] +# [10 11 12]]] +# Take the transpose of the matrices in dimension-0 +tf.transpose(b, perm=[0, 2, 1]) ==> [[[1 4] + [2 5] + [3 6]] + + [[7 10] + [8 11] + [9 12]]] +``` + +##### Args: + + +* <b>a</b>: A `Tensor`. +* <b>perm</b>: A permutation of the dimensions of `a`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A transposed `Tensor`. + + +- - - + +### tf.gather(params, indices, name=None) <div class="md-anchor" id="gather">{#gather}</div> + +Gather slices from `params` according to `indices`. + +`indices` must be an integer tensor of any dimension (usually 0-D or 1-D). +Produces an output tensor with shape `indices.shape + params.shape[1:]` where: + + # Scalar indices + output[:, ..., :] = params[indices, :, ... :] + + # Vector indices + output[i, :, ..., :] = params[indices[i], :, ... :] + + # Higher rank indices + output[i, ..., j, :, ... :] = params[indices[i, ..., j], :, ..., :] + +If `indices` is a permutation and `len(indices) == params.shape[0]` then +this operation will permute `params` accordingly. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/Gather.png" alt> +</div> + +##### Args: + + +* <b>params</b>: A `Tensor`. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `params`. + + +- - - + +### tf.dynamic_partition(data, partitions, num_partitions, name=None) <div class="md-anchor" id="dynamic_partition">{#dynamic_partition}</div> + +Partitions `data` into `num_partitions` tensors using indices from `partitions`. + +For each index tuple `js` of size `partitions.ndim`, the slice `data[js, ...]` +becomes part of `outputs[partitions[js]]`. The slices with `partitions[js] = i` +are placed in `outputs[i]` in lexicographic order of `js`, and the first +dimension of `outputs[i]` is the number of entries in `partitions` equal to `i`. +In detail, + + outputs[i].shape = [sum(partitions == i)] + data.shape[partitions.ndim:] + + outputs[i] = pack([data[js, ...] for js if partitions[js] == i]) + +`data.shape` must start with `partitions.shape`. + +For example: + + # Scalar partitions + partitions = 1 + num_partitions = 2 + data = [10, 20] + outputs[0] = [] # Empty with shape [0, 2] + outputs[1] = [[10, 20]] + + # Vector partitions + partitions = [0, 0, 1, 1, 0] + num_partitions = 2 + data = [10, 20, 30, 40, 50] + outputs[0] = [10, 20, 50] + outputs[1] = [30, 40] + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/DynamicPartition.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. +* <b>partitions</b>: A `Tensor` of type `int32`. + Any shape. Indices in the range `[0, num_partitions)`. +* <b>num_partitions</b>: An `int` that is `>= 1`. + The number of partitions to output. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A list of `num_partitions` `Tensor` objects of the same type as data. + + +- - - + +### tf.dynamic_stitch(indices, data, name=None) <div class="md-anchor" id="dynamic_stitch">{#dynamic_stitch}</div> + +Interleave the values from the `data` tensors into a single tensor. + +Builds a merged tensor such that + + merged[indices[m][i, ..., j], ...] = data[m][i, ..., j, ...] + +For example, if each `indices[m]` is scalar or vector, we have + + # Scalar indices + merged[indices[m], ...] = data[m][...] + + # Vector indices + merged[indices[m][i], ...] = data[m][i, ...] + +Each `data[i].shape` must start with the corresponding `indices[i].shape`, +and the rest of `data[i].shape` must be constant w.r.t. `i`. That is, we +must have `data[i].shape = indices[i].shape + constant`. In terms of this +`constant`, the output shape is + + merged.shape = [max(indices)] + constant + +Values are merged in order, so if an index appears in both `indices[m][i]` and +`indices[n][j]` for `(m,i) < (n,j)` the slice `data[n][j]` will appear in the +merged result. + +For example: + + indices[0] = 6 + indices[1] = [4, 1] + indices[2] = [[5, 2], [0, 3]] + data[0] = [61, 62] + data[1] = [[41, 42], [11, 12]] + data[2] = [[[51, 52], [21, 22]], [[1, 2], [31, 32]]] + merged = [[1, 2], [11, 12], [21, 22], [31, 32], [41, 42], + [51, 52], [61, 62]] + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/DynamicStitch.png" alt> +</div> + +##### Args: + + +* <b>indices</b>: A list of at least 2 `Tensor` objects of type `int32`. +* <b>data</b>: A list with the same number of `Tensor` objects as `indices` of `Tensor` objects of the same type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + + diff --git a/tensorflow/g3doc/api_docs/python/client.md b/tensorflow/g3doc/api_docs/python/client.md new file mode 100644 index 0000000000..b37057e4b5 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/client.md @@ -0,0 +1,638 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Running Graphs +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Session management](#AUTOGENERATED-session-management) + * [class tf.Session](#Session) + * [tf.get_default_session()](#get_default_session) +* [Error classes](#AUTOGENERATED-error-classes) + * [class tf.OpError](#OpError) + * [class tf.errors.CancelledError](#CancelledError) + * [class tf.errors.UnknownError](#UnknownError) + * [class tf.errors.InvalidArgumentError](#InvalidArgumentError) + * [class tf.errors.DeadlineExceededError](#DeadlineExceededError) + * [class tf.errors.NotFoundError](#NotFoundError) + * [class tf.errors.AlreadyExistsError](#AlreadyExistsError) + * [class tf.errors.PermissionDeniedError](#PermissionDeniedError) + * [class tf.errors.UnauthenticatedError](#UnauthenticatedError) + * [class tf.errors.ResourceExhaustedError](#ResourceExhaustedError) + * [class tf.errors.FailedPreconditionError](#FailedPreconditionError) + * [class tf.errors.AbortedError](#AbortedError) + * [class tf.errors.OutOfRangeError](#OutOfRangeError) + * [class tf.errors.UnimplementedError](#UnimplementedError) + * [class tf.errors.InternalError](#InternalError) + * [class tf.errors.UnavailableError](#UnavailableError) + * [class tf.errors.DataLossError](#DataLossError) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +This library contains classes for launching graphs and executing operations. + +The [basic usage](../../get_started/index.md#basic-usage) guide has +examples of how a graph is launched in a [`tf.Session`](#Session). + +## Session management <div class="md-anchor" id="AUTOGENERATED-session-management">{#AUTOGENERATED-session-management}</div> + +- - - + +### class tf.Session <div class="md-anchor" id="Session">{#Session}</div> + +A class for running TensorFlow operations. + +A `Session` object encapsulates the environment in which `Operation` +objects are executed, and `Tensor` objects are evaluated. For +example: + +```python +# Build a graph. +a = tf.constant(5.0) +b = tf.constant(6.0) +c = a * b + +# Launch the graph in a session. +sess = tf.Session() + +# Evaluate the tensor `c`. +print sess.run(c) +``` + +A session may own resources, such as +[variables](state_ops.md#Variable), [queues](io_ops.md#QueueBase), +and [readers](io_ops.md#ReaderBase). It is important to release +these resources when they are no longer required. To do this, either +invoke the [`close()`](#Session.close) method on the session, or use +the session as a context manager. The following two examples are +equivalent: + +```python +# Using the `close()` method. +sess = tf.Session() +sess.run(...) +sess.close() + +# Using the context manager. +with tf.Session() as sess: + sess.run(...) +``` + +The [`ConfigProto`] +(https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/config.proto) +protocol buffer exposes various configuration options for a +session. For example, to create a session that uses soft constraints +for device placement, and log the resulting placement decisions, +create a session as follows: + +```python +# Launch the graph in a session that allows soft device placement and +# logs the placement decisions. +sess = tf.Session(config=tf.ConfigProto(allow_soft_placement=True, + log_device_placement=True)) +``` + +- - - + +#### tf.Session.__init__(target='', graph=None, config=None) {#Session.__init__} + +Creates a new TensorFlow session. + +If no `graph` argument is specified when constructing the session, +the default graph will be launched in the session. If you are +using more than one graph (created with `tf.Graph()` in the same +process, you will have to use different sessions for each graph, +but each graph can be used in multiple sessions. In this case, it +is often clearer to pass the graph to be launched explicitly to +the session constructor. + +##### Args: + + +* <b>target</b>: (Optional.) The execution engine to connect to. + Defaults to using an in-process engine. At present, no value + other than the empty string is supported. +* <b>graph</b>: (Optional.) The `Graph` to be launched (described above). +* <b>config</b>: (Optional.) A [`ConfigProto`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/config.proto) + protocol buffer with configuration options for the session. + + +- - - + +#### tf.Session.run(fetches, feed_dict=None) {#Session.run} + +Runs the operations and evaluates the tensors in `fetches`. + +This method runs one "step" of TensorFlow computation, by +running the necessary graph fragment to execute every `Operation` +and evaluate every `Tensor` in `fetches`, substituting the values in +`feed_dict` for the corresponding input values. + +The `fetches` argument may be a list of graph elements or a single +graph element, and these determine the return value of this +method. A graph element can be one of the following types: + +* If the *i*th element of `fetches` is an + [`Operation`](framework.md#Operation), the *i*th return value + will be `None`. +* If the *i*th element of `fetches` is a + [`Tensor`](framework.md#Tensor), the *i*th return value will + be a numpy ndarray containing the value of that tensor. +* If the *i*th element of `fetches` is a + [`SparseTensor`](sparse_ops.md#SparseTensor), the *i*th + return value will be a + [`SparseTensorValue`](sparse_ops.md#SparseTensorValue) + containing the value of that sparse tensor. + +The optional `feed_dict` argument allows the caller to override +the value of tensors in the graph. Each key in `feed_dict` can be +one of the following types: + +* If the key is a [`Tensor`](framework.md#Tensor), the + value may be a Python scalar, string, list, or numpy ndarray + that can be converted to the same `dtype` as that + tensor. Additionally, if the key is a + [placeholder](io_ops.md#placeholder), the shape of the value + will be checked for compatibility with the placeholder. +* If the key is a [`SparseTensor`](sparse_ops.md#SparseTensor), + the value should be a + [`SparseTensorValue`](sparse_ops.md#SparseTensorValue). + +##### Args: + + +* <b>fetches</b>: A single graph element, or a list of graph elements + (described above). +* <b>feed_dict</b>: A dictionary that maps graph elements to values + (described above). + +##### Returns: + + Either a single value if `fetches` is a single graph element, or + a list of values if `fetches` is a list (described above). + +##### Raises: + + +* <b>RuntimeError</b>: If this `Session` is in an invalid state (e.g. has been + closed). +* <b>TypeError</b>: If `fetches` or `feed_dict` keys are of an inappropriate type. +* <b>ValueError</b>: If `fetches` or `feed_dict` keys are invalid or refer to a + `Tensor` that doesn't exist. + + +- - - + +#### tf.Session.close() {#Session.close} + +Closes this session. + +Calling this method frees all resources associated with the session. + +##### Raises: + + +* <b>RuntimeError</b>: If an error occurs while closing the session. + + + +- - - + +#### tf.Session.graph {#Session.graph} + +The graph that was launched in this session. + + +- - - + +#### tf.Session.as_default() {#Session.as_default} + +Returns a context manager that makes this object the default session. + +Use with the `with` keyword to specify that calls to +[`Operation.run()`](framework.md#Operation.run) or +[`Tensor.run()`](framework.md#Tensor.run) should be executed in +this session. + +```python +c = tf.constant(..) +sess = tf.Session() + +with sess.as_default(): + assert tf.get_default_session() is sess + print c.eval() +``` + +To get the current default session, use +[`tf.get_default_session()`](#get_default_session). + + +*N.B.* The `as_default` context manager *does not* close the +session when you exit the context, and you must close the session +explicitly. + +```python +c = tf.constant(...) +sess = tf.Session() +with sess.as_default(): + print c.eval() +# ... +with sess.as_default(): + print c.eval() + +sess.close() +``` + +Alternatively, you can use `with tf.Session():` to create a +session that is automatically closed on exiting the context, +including when an uncaught exception is raised. + +*N.B.* The default graph is a property of the current thread. If you +create a new thread, and wish to use the default session in that +thread, you must explicitly add a `with sess.as_default():` in that +thread's function. + +##### Returns: + + A context manager using this session as the default session. + + + + +- - - + +### tf.get_default_session() <div class="md-anchor" id="get_default_session">{#get_default_session}</div> + +Returns the default session for the current thread. + +The returned `Session` will be the innermost session on which a +`Session` or `Session.as_default()` context has been entered. + +*N.B.* The default session is a property of the current thread. If you +create a new thread, and wish to use the default session in that +thread, you must explicitly add a `with sess.as_default():` in that +thread's function. + +##### Returns: + + The default `Session` being used in the current thread. + + + +## Error classes <div class="md-anchor" id="AUTOGENERATED-error-classes">{#AUTOGENERATED-error-classes}</div> + +- - - + +### class tf.OpError <div class="md-anchor" id="OpError">{#OpError}</div> + +A generic error that is raised when TensorFlow execution fails. + +Whenever possible, the session will raise a more specific subclass +of `OpError` from the `tf.errors` module. + +- - - + +#### tf.OpError.op {#OpError.op} + +The operation that failed, if known. + +*N.B.* If the failed op was synthesized at runtime, e.g. a `Send` +or `Recv` op, there will be no corresponding +[`Operation`](framework.md#Operation) object. In that case, this +will return `None`, and you should instead use the +[`node_def`](OpError.node_def) to discover information about the op. + +##### Returns: + + The `Operation` that failed, or None. + +- - - + +#### tf.OpError.node_def {#OpError.node_def} + +The `NodeDef` proto representing the op that failed. + + +#### Other Methods +- - - + +#### tf.OpError.__init__(node_def, op, message, error_code) {#OpError.__init__} + +Creates a new OpError indicating that a particular op failed. + +##### Args: + + +* <b>node_def</b>: The graph_pb2.NodeDef proto representing the op that failed. +* <b>op</b>: The ops.Operation that failed, if known; otherwise None. +* <b>message</b>: The message string describing the failure. +* <b>error_code</b>: The error_codes_pb2.Code describing the error. + + +- - - + +#### tf.OpError.error_code {#OpError.error_code} + +The integer error code that describes the error. + +- - - + +#### tf.OpError.message {#OpError.message} + +The error message that describes the error. + + +- - - + +### class tf.errors.CancelledError <div class="md-anchor" id="CancelledError">{#CancelledError}</div> + +Raised when an operation or step is cancelled. + +For example, a long-running operation (e.g. +[`queue.enqueue()`](io_ops.md#QueueBase.enqueue) may be cancelled by +running another operation (e.g. +[`queue.close(cancel_pending_enqueues=True)`](io_ops.md#QueueBase.close), +or by [closing the session](client.md#Session.close). A step that is +running such a long-running operation will fail by raising `CancelledError`. + +- - - + +#### tf.errors.CancelledError.__init__(node_def, op, message) {#CancelledError.__init__} + +Creates a `CancelledError`. + + + +- - - + +### class tf.errors.UnknownError <div class="md-anchor" id="UnknownError">{#UnknownError}</div> + +Unknown error. + +An example of where this error may be returned is if a Status value +received from another address space belongs to an error-space that +is not known to this address space. Also errors raised by APIs that +do not return enough error information may be converted to this +error. + +- - - + +#### tf.errors.UnknownError.__init__(node_def, op, message, error_code=2) {#UnknownError.__init__} + +Creates an `UnknownError`. + + + +- - - + +### class tf.errors.InvalidArgumentError <div class="md-anchor" id="InvalidArgumentError">{#InvalidArgumentError}</div> + +Raised when an operation receives an invalid argument. + +This may occur, for example, if an operation is receives an input +tensor that has an invalid value or shape. For example, the +[`tf.matmul()`](math_ops.md#matmul) op will raise this error if it +receives an input that is not a matrix, and the +[`tf.reshape()`](array_ops.md#reshape) op will raise this error if +the new shape does not match the number of elements in the input +tensor. + +- - - + +#### tf.errors.InvalidArgumentError.__init__(node_def, op, message) {#InvalidArgumentError.__init__} + +Creates an `InvalidArgumentError`. + + + +- - - + +### class tf.errors.DeadlineExceededError <div class="md-anchor" id="DeadlineExceededError">{#DeadlineExceededError}</div> + +Raised when a deadline expires before an operation could complete. + +This exception is not currently used. + +- - - + +#### tf.errors.DeadlineExceededError.__init__(node_def, op, message) {#DeadlineExceededError.__init__} + +Creates a `DeadlineExceededError`. + + + +- - - + +### class tf.errors.NotFoundError <div class="md-anchor" id="NotFoundError">{#NotFoundError}</div> + +Raised when a requested entity (e.g., a file or directory) was not found. + +For example, running the +[`tf.WholeFileReader.read()`](io_ops.md#WholeFileReader) operation +could raise `NotFoundError` if it receives the name of a file that +does not exist. + +- - - + +#### tf.errors.NotFoundError.__init__(node_def, op, message) {#NotFoundError.__init__} + +Creates a `NotFoundError`. + + + +- - - + +### class tf.errors.AlreadyExistsError <div class="md-anchor" id="AlreadyExistsError">{#AlreadyExistsError}</div> + +Raised when an entity that we attempted to create already exists. + +For example, running an operation that saves a file +(e.g. [`tf.train.Saver.save()`](train.md#Saver.save)) could +potentially raise this exception if an explicit filename for an +existing file was passed. + +- - - + +#### tf.errors.AlreadyExistsError.__init__(node_def, op, message) {#AlreadyExistsError.__init__} + +Creates an `AlreadyExistsError`. + + + +- - - + +### class tf.errors.PermissionDeniedError <div class="md-anchor" id="PermissionDeniedError">{#PermissionDeniedError}</div> + +Raised when the caller does not have permission to run an operation. + +For example, running the +[`tf.WholeFileReader.read()`](io_ops.md#WholeFileReader) operation +could raise `PermissionDeniedError` if it receives the name of a +file for which the user does not have the read file permission. + +- - - + +#### tf.errors.PermissionDeniedError.__init__(node_def, op, message) {#PermissionDeniedError.__init__} + +Creates a `PermissionDeniedError`. + + + +- - - + +### class tf.errors.UnauthenticatedError <div class="md-anchor" id="UnauthenticatedError">{#UnauthenticatedError}</div> + +The request does not have valid authentication credentials. + +This exception is not currently used. + +- - - + +#### tf.errors.UnauthenticatedError.__init__(node_def, op, message) {#UnauthenticatedError.__init__} + +Creates an `UnauthenticatedError`. + + + +- - - + +### class tf.errors.ResourceExhaustedError <div class="md-anchor" id="ResourceExhaustedError">{#ResourceExhaustedError}</div> + +Some resource has been exhausted. + +For example, this error might be raised if a per-user quota is +exhausted, or perhaps the entire file system is out of space. + +- - - + +#### tf.errors.ResourceExhaustedError.__init__(node_def, op, message) {#ResourceExhaustedError.__init__} + +Creates a `ResourceExhaustedError`. + + + +- - - + +### class tf.errors.FailedPreconditionError <div class="md-anchor" id="FailedPreconditionError">{#FailedPreconditionError}</div> + +Operation was rejected because the system is not in a state to execute it. + +This exception is most commonly raised when running an operation +that reads a [`tf.Variable`](state_ops.md#Variable) before it has +been initialized. + +- - - + +#### tf.errors.FailedPreconditionError.__init__(node_def, op, message) {#FailedPreconditionError.__init__} + +Creates a `FailedPreconditionError`. + + + +- - - + +### class tf.errors.AbortedError <div class="md-anchor" id="AbortedError">{#AbortedError}</div> + +The operation was aborted, typically due to a concurrent action. + +For example, running a [`queue.enqueue()`](io_ops.md#QueueBase.enqueue) +operation may raise `AbortedError` if a +[`queue.close()`](io_ops.md@QueueBase.close) operation previously ran. + +- - - + +#### tf.errors.AbortedError.__init__(node_def, op, message) {#AbortedError.__init__} + +Creates an `AbortedError`. + + + +- - - + +### class tf.errors.OutOfRangeError <div class="md-anchor" id="OutOfRangeError">{#OutOfRangeError}</div> + +Raised when an operation executed past the valid range. + +This exception is raised in "end-of-file" conditions, such as when a +[`queue.dequeue()`](io_ops.md#QueueBase.dequeue) operation is +blocked on an empty queue, and a +[`queue.close()`](io_ops.md#QueueBase.close) operation executes. + +- - - + +#### tf.errors.OutOfRangeError.__init__(node_def, op, message) {#OutOfRangeError.__init__} + +Creates an `OutOfRangeError`. + + + +- - - + +### class tf.errors.UnimplementedError <div class="md-anchor" id="UnimplementedError">{#UnimplementedError}</div> + +Raised when an operation has not been implemented. + +Some operations may raise this error when passed otherwise-valid +arguments that it does not currently support. For example, running +the [`tf.nn.max_pool()`](nn.md#max_pool) operation would raise this +error if pooling was requested on the batch dimension, because this +is not yet supported. + +- - - + +#### tf.errors.UnimplementedError.__init__(node_def, op, message) {#UnimplementedError.__init__} + +Creates an `UnimplementedError`. + + + +- - - + +### class tf.errors.InternalError <div class="md-anchor" id="InternalError">{#InternalError}</div> + +Raised when the system experiences an internal error. + +This exception is raised when some invariant expected by the runtime +has been broken. Catching this exception is not recommended. + +- - - + +#### tf.errors.InternalError.__init__(node_def, op, message) {#InternalError.__init__} + +Creates an `InternalError`. + + + +- - - + +### class tf.errors.UnavailableError <div class="md-anchor" id="UnavailableError">{#UnavailableError}</div> + +Raised when the runtime is currently unavailable. + +This exception is not currently used. + +- - - + +#### tf.errors.UnavailableError.__init__(node_def, op, message) {#UnavailableError.__init__} + +Creates an `UnavailableError`. + + + +- - - + +### class tf.errors.DataLossError <div class="md-anchor" id="DataLossError">{#DataLossError}</div> + +Raised when unrecoverable data loss or corruption is encountered. + +For example, this may be raised by running a +[`tf.WholeFileReader.read()`](io_ops.md#WholeFileReader) operation, +if the file is truncated while it is being read. + +- - - + +#### tf.errors.DataLossError.__init__(node_def, op, message) {#DataLossError.__init__} + +Creates a `DataLossError`. + + + diff --git a/tensorflow/g3doc/api_docs/python/constant_op.md b/tensorflow/g3doc/api_docs/python/constant_op.md new file mode 100644 index 0000000000..34d2b511ab --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/constant_op.md @@ -0,0 +1,565 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Constants, Sequences, and Random Values +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Constant Value Tensors](#AUTOGENERATED-constant-value-tensors) + * [tf.zeros(shape, dtype=tf.float32, name=None)](#zeros) + * [tf.zeros_like(tensor, dtype=None, name=None)](#zeros_like) + * [tf.ones(shape, dtype=tf.float32, name=None)](#ones) + * [tf.ones_like(tensor, dtype=None, name=None)](#ones_like) + * [tf.fill(dims, value, name=None)](#fill) + * [tf.constant(value, dtype=None, shape=None, name='Const')](#constant) +* [Sequences](#AUTOGENERATED-sequences) + * [tf.linspace(start, stop, num, name=None)](#linspace) + * [tf.range(start, limit, delta=1, name='range')](#range) +* [Random Tensors](#AUTOGENERATED-random-tensors) + * [Examples:](#AUTOGENERATED-examples-) + * [tf.random_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None)](#random_normal) + * [tf.truncated_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None)](#truncated_normal) + * [tf.random_uniform(shape, minval=0.0, maxval=1.0, dtype=tf.float32, seed=None, name=None)](#random_uniform) + * [tf.random_shuffle(value, seed=None, name=None)](#random_shuffle) + * [tf.set_random_seed(seed)](#set_random_seed) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Constant Value Tensors <div class="md-anchor" id="AUTOGENERATED-constant-value-tensors">{#AUTOGENERATED-constant-value-tensors}</div> + +TensorFlow provides several operations that you can use to generate constants. + +- - - + +### tf.zeros(shape, dtype=tf.float32, name=None) <div class="md-anchor" id="zeros">{#zeros}</div> + +Creates a tensor with all elements set to zero. + +This operation returns a tensor of type `dtype` with shape `shape` and +all elements set to zero. + +For example: + +```python +tf.zeros([3, 4], int32) ==> [[0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]] +``` + +##### Args: + + +* <b>shape</b>: Either a list of integers, or a 1-D `Tensor` of type `int32`. +* <b>dtype</b>: The type of an element in the resulting `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to zero. + + +- - - + +### tf.zeros_like(tensor, dtype=None, name=None) <div class="md-anchor" id="zeros_like">{#zeros_like}</div> + +Creates a tensor with all elements set to zero. + +Given a single tensor (`tensor`), this operation returns a tensor of the +same type and shape as `tensor` with all elements set to zero. Optionally, +you can use `dtype` to specify a new type for the returned tensor. + +For example: + +```python +# 'tensor' is [[1, 2, 3], [4, 5, 6]] +tf.zeros_like(tensor) ==> [[0, 0, 0], [0, 0, 0]] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. +* <b>dtype</b>: A type for the returned `Tensor`. Must be `float32`, `float64`, + `int8`, `int16`, `int32`, `int64`, `uint8`, or `complex64`. + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to zero. + + + +- - - + +### tf.ones(shape, dtype=tf.float32, name=None) <div class="md-anchor" id="ones">{#ones}</div> + +Creates a tensor with all elements set to 1. + +This operation returns a tensor of type `dtype` with shape `shape` and all +elements set to 1. + +For example: + +```python +tf.ones([2, 3], int32) ==> [[1, 1, 1], [1, 1, 1]] +``` + +##### Args: + + +* <b>shape</b>: Either a list of integers, or a 1-D `Tensor` of type `int32`. +* <b>dtype</b>: The type of an element in the resulting `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to 1. + + +- - - + +### tf.ones_like(tensor, dtype=None, name=None) <div class="md-anchor" id="ones_like">{#ones_like}</div> + +Creates a tensor with all elements set to 1. + +Given a single tensor (`tensor`), this operation returns a tensor of the same +type and shape as `tensor` with all elements set to 1. Optionally, you can +specify a new type (`dtype`) for the returned tensor. + +For example: + +```python +# 'tensor' is [[1, 2, 3], [4, 5, 6]] +tf.ones_like(tensor) ==> [[1, 1, 1], [1, 1, 1]] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. +* <b>dtype</b>: A type for the returned `Tensor`. Must be `float32`, `float64`, + `int8`, `int16`, `int32`, `int64`, `uint8`, or `complex64`. + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to 1. + + + +- - - + +### tf.fill(dims, value, name=None) <div class="md-anchor" id="fill">{#fill}</div> + +Creates a tensor filled with a scalar value. + +This operation creates a tensor of shape `dims` and fills it with `value`. + +For example: + +```prettyprint +# output tensor shape needs to be [2, 3] +# so 'dims' is [2, 3] +fill(dims, 9) ==> [[9, 9, 9] + [9, 9, 9]] +``` + +##### Args: + + +* <b>dims</b>: A `Tensor` of type `int32`. + 1-D. Represents the shape of the output tensor. +* <b>value</b>: A `Tensor`. 0-D (scalar). Value to fill the returned tensor. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `value`. + + + +- - - + +### tf.constant(value, dtype=None, shape=None, name='Const') <div class="md-anchor" id="constant">{#constant}</div> + +Creates a constant tensor. + + The resulting tensor is populated with values of type `dtype`, as + specified by arguments `value` and (optionally) `shape` (see examples + below). + + The argument `value` can be a constant value, or a list of values of type + `dtype`. If `value` is a list, then the length of the list must be less + than or equal to the number of elements implied by the `shape` argument (if + specified). In the case where the list length is less than the number of + elements specified by `shape`, the last element in the list will be used + to fill the remaining entries. + + The argument `shape` is optional. If present, it specifies the dimensions + of the resulting tensor. If not present, then the tensor is a scalar (0-D) + if `value` is a scalar, or 1-D otherwise. + + If the argument `dtype` is not specified, then the type is inferred from + the type of `value`. + + For example: + + ```python + # Constant 1-D Tensor populated with value list. + tensor = tf.constant([1, 2, 3, 4, 5, 6, 7]) => [1 2 3 4 5 6 7] + + # Constant 2-D tensor populated with scalar value -1. + tensor = tf.constant(-1.0, shape=[2, 3]) => [[-1. -1. -1.] + [-1. -1. -1.]] + ``` + +##### Args: + + +* <b>value</b>: A constant value (or list) of output type `dtype`. + + +* <b>dtype</b>: The type of the elements of the resulting tensor. + + +* <b>shape</b>: Optional dimensions of resulting tensor. + + +* <b>name</b>: Optional name for the tensor. + +##### Returns: + + A Constant Tensor. + + + +## Sequences <div class="md-anchor" id="AUTOGENERATED-sequences">{#AUTOGENERATED-sequences}</div> + +- - - + +### tf.linspace(start, stop, num, name=None) <div class="md-anchor" id="linspace">{#linspace}</div> + +Generates values in an interval. + +A sequence of `num` evenly-spaced values are generated beginning at `start`. +If `num > 1`, the values in the sequence increase by `stop - start / num - 1`, +so that the last one is exactly `stop`. + +For example: + +``` +tf.linspace(10.0, 12.0, 3, name="linspace") => [ 10.0 11.0 12.0] +``` + +##### Args: + + +* <b>start</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + First entry in the range. +* <b>stop</b>: A `Tensor`. Must have the same type as `start`. + Last entry in the range. +* <b>num</b>: A `Tensor` of type `int32`. Number of values to generate. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `start`. 1-D. The generated values. + + + +- - - + +### tf.range(start, limit, delta=1, name='range') <div class="md-anchor" id="range">{#range}</div> + +Creates a sequence of integers. + +This operation creates a sequence of integers that begins at `start` and +extends by increments of `delta` up to but not including `limit`. + +For example: + +``` +# 'start' is 3 +# 'limit' is 18 +# 'delta' is 3 +tf.range(start, limit, delta) ==> [3, 6, 9, 12, 15] +``` + +##### Args: + + +* <b>start</b>: A 0-D (scalar) of type `int32`. First entry in sequence. +* <b>limit</b>: A 0-D (scalar) of type `int32`. Upper limit of sequence, + exclusive. +* <b>delta</b>: A 0-D `Tensor` (scalar) of type `int32`. Optional. Default is 1. + Number that increments `start`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An 1-D `int32` `Tensor`. + + + +## Random Tensors <div class="md-anchor" id="AUTOGENERATED-random-tensors">{#AUTOGENERATED-random-tensors}</div> + +TensorFlow has several ops that create random tensors with different +distributions. The random ops are stateful, and create new random values each +time they are evaluated. + +The `seed` keyword argument in these functions acts in conjunction with +the graph-level random seed. Changing either the graph-level seed using +[`set_random_seed`](constant_op.md#set_random_seed) or the op-level seed +will change the underlying seed of these operations. Setting neither graph-level +nor op-level seed, results in a random seed for all operations. +See [`set_random_seed`](constant_op.md#set_random_seed) for details on the +interaction between operation-level and graph-level random seeds. + +### Examples: <div class="md-anchor" id="AUTOGENERATED-examples-">{#AUTOGENERATED-examples-}</div> + +```python +# Create a tensor of shape [2, 3] consisting of random normal values, with mean +# -1 and standard deviation 4. +norm = tf.random_normal([2, 3], mean=-1, stddev=4) + +# Shuffle the first dimension of a tensor +c = tf.constant([[1, 2], [3, 4], [5, 6]]) +shuff = tf.random_shuffle(c) + +# Each time we run these ops, different results are generated +sess = tf.Session() +print sess.run(norm) +print sess.run(norm) + +# Set an op-level seed to generate repeatable sequences across sessions. +c = tf.constant([[1, 2], [3, 4], [5, 6]]) +sess = tf.Session() +norm = tf.random_normal(c, seed=1234) +print sess.run(norm) +print sess.run(norm) +``` + +Another common use of random values is the intialization of variables. Also see +the [Variables How To](../../how_tos/variables/index.md). + +```python +# Use random uniform values in [0, 1) as the initializer for a variable of shape +# [2, 3]. The default type is float32. +var = tf.Variable(tf.random_uniform([2, 3]), name="var") +init = tf.initialize_all_variables() + +sess = tf.Session() +sess.run(init) +print sess.run(var) +``` + +- - - + +### tf.random_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None) <div class="md-anchor" id="random_normal">{#random_normal}</div> + +Outputs random values from a normal distribution. + +##### Args: + + +* <b>shape</b>: A 1-D integer Tensor or Python array. The shape of the output tensor. +* <b>mean</b>: A 0-D Tensor or Python value of type `dtype`. The mean of the normal + distribution. +* <b>stddev</b>: A 0-D Tensor or Python value of type `dtype`. The standard deviation + of the normal distribution. +* <b>dtype</b>: The type of the output. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of the specified shape filled with random normal values. + + +- - - + +### tf.truncated_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None) <div class="md-anchor" id="truncated_normal">{#truncated_normal}</div> + +Outputs random values from a truncated normal distribution. + +The generated values follow a normal distribution with specified mean and +standard deviation, except that values whose magnitude is more than 2 standard +deviations from the mean are dropped and re-picked. + +##### Args: + + +* <b>shape</b>: A 1-D integer Tensor or Python array. The shape of the output tensor. +* <b>mean</b>: A 0-D Tensor or Python value of type `dtype`. The mean of the + truncated normal distribution. +* <b>stddev</b>: A 0-D Tensor or Python value of type `dtype`. The standard deviation + of the truncated normal distribution. +* <b>dtype</b>: The type of the output. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of the specified shape filled with random truncated normal values. + + +- - - + +### tf.random_uniform(shape, minval=0.0, maxval=1.0, dtype=tf.float32, seed=None, name=None) <div class="md-anchor" id="random_uniform">{#random_uniform}</div> + +Outputs random values from a uniform distribution. + +The generated values follow a uniform distribution in the range +`[minval, maxval)`. The lower bound `minval` is included in the range, while +the upper bound `maxval` is excluded. + +##### Args: + + +* <b>shape</b>: A 1-D integer Tensor or Python array. The shape of the output tensor. +* <b>minval</b>: A 0-D Tensor or Python value of type `dtype`. The lower bound on the + range of random values to generate. +* <b>maxval</b>: A 0-D Tensor or Python value of type `dtype`. The upper bound on + the range of random values to generate. +* <b>dtype</b>: The type of the output. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of the specified shape filled with random uniform values. + + +- - - + +### tf.random_shuffle(value, seed=None, name=None) <div class="md-anchor" id="random_shuffle">{#random_shuffle}</div> + +Randomly shuffles a tensor along its first dimension. + +The tensor is shuffled along dimension 0, such that each `value[j]` is mapped +to one and only one `output[i]`. For example, a mapping that might occur for a +3x2 tensor is: + +```python +[[1, 2], [[5, 6], + [3, 4], ==> [1, 2], + [5, 6]] [3, 4]] +``` + +##### Args: + + +* <b>value</b>: A Tensor to be shuffled. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of same shape and type as `value`, shuffled along its first + dimension. + + +- - - + +### tf.set_random_seed(seed) <div class="md-anchor" id="set_random_seed">{#set_random_seed}</div> + +Sets the graph-level random seed. + +Operations that rely on a random seed actually derive it from two seeds: +the graph-level and operation-level seeds. This sets the graph-level seed. + +Its interactions with operation-level seeds is as follows: + + 1. If neither the graph-level nor the operation seed is set: + A random seed is used for this op. + 2. If the graph-level seed is set, but the operation seed is not: + The system deterministically picks an operation seed in conjunction + with the graph-level seed so that it gets a unique random sequence. + 3. If the graph-level seed is not set, but the operation seed is set: + A default graph-level seed and the specified operation seed are used to + determine the random sequence. + 4. If both the graph-level and the operation seed are set: + Both seeds are used in conjunction to determine the random sequence. + +To illustrate the user-visible effects, consider these examples: + +To generate different sequences across sessions, set neither +graph-level nor op-level seeds: + +```python +a = tf.random_uniform([1]) +b = tf.random_normal([1]) + +print "Session 1" +with tf.Session() as sess1: + print sess1.run(a) # generates 'A1' + print sess1.run(a) # generates 'A2' + print sess1.run(b) # generates 'B1' + print sess1.run(b) # generates 'B2' + +print "Session 2" +with tf.Session() as sess2: + print sess2.run(a) # generates 'A3' + print sess2.run(a) # generates 'A4' + print sess2.run(b) # generates 'B3' + print sess2.run(b) # generates 'B4' +``` + +To generate the same repeatable sequence for an op across sessions, set the +seed for the op: + +```python +a = tf.random_uniform([1], seed=1) +b = tf.random_normal([1]) + +# Repeatedly running this block with the same graph will generate the same +# sequence of values for 'a', but different sequences of values for 'b'. +print "Session 1" +with tf.Session() as sess1: + print sess1.run(a) # generates 'A1' + print sess1.run(a) # generates 'A2' + print sess1.run(b) # generates 'B1' + print sess1.run(b) # generates 'B2' + +print "Session 2" +with tf.Session() as sess2: + print sess2.run(a) # generates 'A1' + print sess2.run(a) # generates 'A2' + print sess2.run(b) # generates 'B3' + print sess2.run(b) # generates 'B4' +``` + +To make the random sequences generated by all ops be repeatable across +sessions, set a graph-level seed: + +```python +tf.set_random_seed(1234) +a = tf.random_uniform([1]) +b = tf.random_normal([1]) + +# Repeatedly running this block with the same graph will generate different +# sequences of 'a' and 'b'. +print "Session 1" +with tf.Session() as sess1: + print sess1.run(a) # generates 'A1' + print sess1.run(a) # generates 'A2' + print sess1.run(b) # generates 'B1' + print sess1.run(b) # generates 'B2' + +print "Session 2" +with tf.Session() as sess2: + print sess2.run(a) # generates 'A1' + print sess2.run(a) # generates 'A2' + print sess2.run(b) # generates 'B1' + print sess2.run(b) # generates 'B2' +``` + +##### Args: + + +* <b>seed</b>: integer. + + diff --git a/tensorflow/g3doc/api_docs/python/control_flow_ops.md b/tensorflow/g3doc/api_docs/python/control_flow_ops.md new file mode 100644 index 0000000000..ad4321f01b --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/control_flow_ops.md @@ -0,0 +1,590 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Control Flow +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Control Flow Operations](#AUTOGENERATED-control-flow-operations) + * [tf.identity(input, name=None)](#identity) + * [tf.tuple(tensors, name=None, control_inputs=None)](#tuple) + * [tf.group(*inputs, **kwargs)](#group) + * [tf.no_op(name=None)](#no_op) + * [tf.count_up_to(ref, limit, name=None)](#count_up_to) +* [Logical Operators](#AUTOGENERATED-logical-operators) + * [tf.logical_and(x, y, name=None)](#logical_and) + * [tf.logical_not(x, name=None)](#logical_not) + * [tf.logical_or(x, y, name=None)](#logical_or) + * [tf.logical_xor(x, y, name='LogicalXor')](#logical_xor) +* [Comparison Operators](#AUTOGENERATED-comparison-operators) + * [tf.equal(x, y, name=None)](#equal) + * [tf.not_equal(x, y, name=None)](#not_equal) + * [tf.less(x, y, name=None)](#less) + * [tf.less_equal(x, y, name=None)](#less_equal) + * [tf.greater(x, y, name=None)](#greater) + * [tf.greater_equal(x, y, name=None)](#greater_equal) + * [tf.select(condition, t, e, name=None)](#select) + * [tf.where(input, name=None)](#where) +* [Debugging Operations](#AUTOGENERATED-debugging-operations) + * [tf.is_finite(x, name=None)](#is_finite) + * [tf.is_inf(x, name=None)](#is_inf) + * [tf.is_nan(x, name=None)](#is_nan) + * [tf.verify_tensor_all_finite(t, msg, name=None)](#verify_tensor_all_finite) + * [tf.check_numerics(tensor, message, name=None)](#check_numerics) + * [tf.add_check_numerics_ops()](#add_check_numerics_ops) + * [tf.Assert(condition, data, summarize=None, name=None)](#Assert) + * [tf.Print(input_, data, message=None, first_n=None, summarize=None, name=None)](#Print) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Control Flow Operations <div class="md-anchor" id="AUTOGENERATED-control-flow-operations">{#AUTOGENERATED-control-flow-operations}</div> + +TensorFlow provides several operations and classes that you can use to control +the execution of operations and add conditional dependencies to your graph. + +- - - + +### tf.identity(input, name=None) <div class="md-anchor" id="identity">{#identity}</div> + +Return a tensor with the same shape and contents as the input tensor or value. + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.tuple(tensors, name=None, control_inputs=None) <div class="md-anchor" id="tuple">{#tuple}</div> + +Group tensors together. + +This creates a tuple of tensors with the same values as the `tensors` +argument, except that the value of each tensor is only returned after the +values of all tensors have been computed. + +`control_inputs` contains additional ops that have to finish before this op +finishes, but whose outputs are not returned. + +This can be used as a "join" mechanism for parallel computations: all the +argument tensors can be computed in parallel, but the values of any tensor +returned by `tuple` are only available after all the parallel computations +are done. + +See also `group` and `with_dependencies`. + +##### Args: + + +* <b>tensors</b>: A list of `Tensor`s or `IndexedSlices`, some entries can be `None`. +* <b>name</b>: (optional) A name to use as a `name_scope` for the operation. +* <b>control_inputs</b>: List of additional ops to finish before returning. + +##### Returns: + + Same as `tensors`. + +##### Raises: + + +* <b>ValueError</b>: If `tensors` does not contain any `Tensor` or `IndexedSlices`. + + +- - - + +### tf.group(*inputs, **kwargs) <div class="md-anchor" id="group">{#group}</div> + +Create an op that groups multiple operations. + +When this op finishes, all ops in `input` have finished. This op has no +output. + +See also `tuple` and `with_dependencies`. + +##### Args: + + +* <b>*inputs</b>: One or more tensors to group. +* <b>**kwargs</b>: Optional parameters to pass when constructing the NodeDef. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + An Operation that executes all its inputs. + +##### Raises: + + +* <b>ValueError</b>: If an unknown keyword argument is provided, or if there are + no inputs. + + +- - - + +### tf.no_op(name=None) <div class="md-anchor" id="no_op">{#no_op}</div> + +Does nothing. Only useful as a placeholder for control edges. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +### tf.count_up_to(ref, limit, name=None) <div class="md-anchor" id="count_up_to">{#count_up_to}</div> + +Increments 'ref' until it reaches 'limit'. + +This operation outputs "ref" after the update is done. This makes it +easier to chain operations that need to use the updated value. + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Must be one of the following types: `int32`, `int64`. + Should be from a scalar `Variable` node. +* <b>limit</b>: An `int`. + If incrementing ref would bring it above limit, instead generates an + 'OutOfRange' error. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `ref`. + A copy of the input before increment. If nothing else modifies the + input, the values produced will all be distinct. + + + +## Logical Operators <div class="md-anchor" id="AUTOGENERATED-logical-operators">{#AUTOGENERATED-logical-operators}</div> + +TensorFlow provides several operations that you can use to add logical operators +to your graph. + +- - - + +### tf.logical_and(x, y, name=None) <div class="md-anchor" id="logical_and">{#logical_and}</div> + +Returns the truth value of x AND y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `bool`. +* <b>y</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.logical_not(x, name=None) <div class="md-anchor" id="logical_not">{#logical_not}</div> + +Returns the truth value of NOT x element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.logical_or(x, y, name=None) <div class="md-anchor" id="logical_or">{#logical_or}</div> + +Returns the truth value of x OR y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `bool`. +* <b>y</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.logical_xor(x, y, name='LogicalXor') <div class="md-anchor" id="logical_xor">{#logical_xor}</div> + +x ^ y = (x | y) & ~(x & y). + + + +## Comparison Operators <div class="md-anchor" id="AUTOGENERATED-comparison-operators">{#AUTOGENERATED-comparison-operators}</div> + +TensorFlow provides several operations that you can use to add comparison +operators to your graph. + +- - - + +### tf.equal(x, y, name=None) <div class="md-anchor" id="equal">{#equal}</div> + +Returns the truth value of (x == y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `complex64`, `quint8`, `qint8`, `qint32`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.not_equal(x, y, name=None) <div class="md-anchor" id="not_equal">{#not_equal}</div> + +Returns the truth value of (x != y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `complex64`, `quint8`, `qint8`, `qint32`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.less(x, y, name=None) <div class="md-anchor" id="less">{#less}</div> + +Returns the truth value of (x < y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.less_equal(x, y, name=None) <div class="md-anchor" id="less_equal">{#less_equal}</div> + +Returns the truth value of (x <= y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.greater(x, y, name=None) <div class="md-anchor" id="greater">{#greater}</div> + +Returns the truth value of (x > y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.greater_equal(x, y, name=None) <div class="md-anchor" id="greater_equal">{#greater_equal}</div> + +Returns the truth value of (x >= y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.select(condition, t, e, name=None) <div class="md-anchor" id="select">{#select}</div> + +Selects elements from `t` or `e`, depending on `condition`. + +The `condition`, `t`, and `e` tensors must all have the same shape, +and the output will also have that shape. The `condition` tensor acts +as an element-wise mask that chooses, based on the value at each +element, whether the corresponding element in the output should be +taken from `t` (if true) or `e` (if false). For example: + +For example: + +```prettyprint +# 'condition' tensor is [[True, False] +# [True, False]] +# 't' is [[1, 1], +# [1, 1]] +# 'e' is [[2, 2], +# [2, 2]] +select(condition, t, e) ==> [[1, 2], + [1, 2]] +``` + +##### Args: + + +* <b>condition</b>: A `Tensor` of type `bool`. +* <b>t</b>: A `Tensor` with the same shape as `condition`. +* <b>e</b>: A `Tensor` with the same type and shape as `t`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with the same type and shape as `t` and `e`. + + +- - - + +### tf.where(input, name=None) <div class="md-anchor" id="where">{#where}</div> + +Returns locations of true values in a boolean tensor. + +This operation returns the coordinates of true elements in `input`. The +coordinates are returned in a 2-D tensor where the first dimension (rows) +represents the number of true elements, and the second dimension (columns) +represents the coordinates of the true elements. Keep in mind, the shape of +the output tensor can vary depending on how many true values there are in +`input`. Indices are output in row-major order. + +For example: + +```prettyprint +# 'input' tensor is [[True, False] +# [True, False]] +# 'input' has two true values, so output has two coordinates. +# 'input' has rank of 2, so coordinates have two indices. +where(input) ==> [[0, 0], + [1, 0]] + +# `input` tensor is [[[True, False] +# [True, False]] +# [[False, True] +# [False, True]] +# [[False, False] +# [False, True]]] +# 'input' has 5 true values, so output has 5 coordinates. +# 'input' has rank of 3, so coordinates have three indices. +where(input) ==> [[0, 0, 0], + [0, 1, 0], + [1, 0, 1], + [1, 1, 1], + [2, 1, 1]] +``` + +##### Args: + + +* <b>input</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + + +## Debugging Operations <div class="md-anchor" id="AUTOGENERATED-debugging-operations">{#AUTOGENERATED-debugging-operations}</div> + +TensorFlow provides several operations that you can use to validate values and +debug your graph. + +- - - + +### tf.is_finite(x, name=None) <div class="md-anchor" id="is_finite">{#is_finite}</div> + +Returns which elements of x are finite. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.is_inf(x, name=None) <div class="md-anchor" id="is_inf">{#is_inf}</div> + +Returns which elements of x are Inf. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.is_nan(x, name=None) <div class="md-anchor" id="is_nan">{#is_nan}</div> + +Returns which elements of x are NaN. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.verify_tensor_all_finite(t, msg, name=None) <div class="md-anchor" id="verify_tensor_all_finite">{#verify_tensor_all_finite}</div> + +Assert that the tensor does not contain any NaN's or Inf's. + +##### Args: + + +* <b>t</b>: Tensor to check. +* <b>msg</b>: Message to log on failure. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + Same tensor as `t`. + + +- - - + +### tf.check_numerics(tensor, message, name=None) <div class="md-anchor" id="check_numerics">{#check_numerics}</div> + +Checks a tensor for NaN and Inf values. + +When run, reports an `InvalidArgument` error if `tensor` has any values +that are not a number (NaN) or infinity (Inf). Otherwise, passes `tensor` as-is. + +##### Args: + + +* <b>tensor</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>message</b>: A `string`. Prefix of the error message. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `tensor`. + + +- - - + +### tf.add_check_numerics_ops() <div class="md-anchor" id="add_check_numerics_ops">{#add_check_numerics_ops}</div> + +Connect a check_numerics to every floating point tensor. + +`check_numerics` operations themselves are added for each `float` or `double` +tensor in the graph. For all ops in the graph, the `check_numerics` op for +all of its (`float` or `double`) inputs is guaranteed to run before the +`check_numerics` op on any of its outputs. + +##### Returns: + + A `group` op depending on all `check_numerics` ops added. + + +- - - + +### tf.Assert(condition, data, summarize=None, name=None) <div class="md-anchor" id="Assert">{#Assert}</div> + +Asserts that the given condition is true. + +If `condition` evaluates to false, print the list of tensors in `data`. +`summarize` determines how many entries of the tensors to print. + +##### Args: + + +* <b>condition</b>: The condition to evaluate. +* <b>data</b>: The tensors to print out when condition is false. +* <b>summarize</b>: Print this many entries of each tensor. +* <b>name</b>: A name for this operation (optional). + + +- - - + +### tf.Print(input_, data, message=None, first_n=None, summarize=None, name=None) <div class="md-anchor" id="Print">{#Print}</div> + +Prints a list of tensors. + +This is an identity op with the side effect of printing `data` when +evaluating. + +##### Args: + + +* <b>input_</b>: A tensor passed through this op. +* <b>data</b>: A list of tensors to print out when op is evaluated. +* <b>message</b>: A string, prefix of the error message. +* <b>first_n</b>: Only log `first_n` number of times. Negative numbers log always; + this is the default. +* <b>summarize</b>: Only print this many entries of each tensor. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same tensor as `input_`. + + diff --git a/tensorflow/g3doc/api_docs/python/framework.md b/tensorflow/g3doc/api_docs/python/framework.md new file mode 100644 index 0000000000..e28daaa77a --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/framework.md @@ -0,0 +1,2079 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Building Graphs +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Core graph data structures](#AUTOGENERATED-core-graph-data-structures) + * [class tf.Graph](#Graph) + * [class tf.Operation](#Operation) + * [class tf.Tensor](#Tensor) +* [Tensor types](#AUTOGENERATED-tensor-types) + * [class tf.DType](#DType) + * [tf.as_dtype(type_value)](#as_dtype) +* [Utility functions](#AUTOGENERATED-utility-functions) + * [tf.device(dev)](#device) + * [tf.name_scope(name)](#name_scope) + * [tf.control_dependencies(control_inputs)](#control_dependencies) + * [tf.convert_to_tensor(value, dtype=None, name=None)](#convert_to_tensor) + * [tf.get_default_graph()](#get_default_graph) + * [tf.import_graph_def(graph_def, input_map=None, return_elements=None, name=None, op_dict=None)](#import_graph_def) +* [Graph collections](#AUTOGENERATED-graph-collections) + * [tf.add_to_collection(name, value)](#add_to_collection) + * [tf.get_collection(key, scope=None)](#get_collection) + * [class tf.GraphKeys](#GraphKeys) +* [Defining new operations](#AUTOGENERATED-defining-new-operations) + * [class tf.RegisterGradient](#RegisterGradient) + * [tf.NoGradient(op_type)](#NoGradient) + * [class tf.RegisterShape](#RegisterShape) + * [class tf.TensorShape](#TensorShape) + * [class tf.Dimension](#Dimension) + * [tf.op_scope(*args, **kwds)](#op_scope) + * [tf.get_seed(op_seed)](#get_seed) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +Import names from the framework library. + +## Core graph data structures <div class="md-anchor" id="AUTOGENERATED-core-graph-data-structures">{#AUTOGENERATED-core-graph-data-structures}</div> + +- - - + +### class tf.Graph <div class="md-anchor" id="Graph">{#Graph}</div> + +A TensorFlow computation, represented as a dataflow graph. + +A `Graph` contains a set of [`Operation`](framework.md#Operation) objects, +which represent units of computation; and [`Tensor`](framework.md#Tensor) +objects, which represent the units of data that flow between operations. + +A default `Graph` is always registered, and accessible by calling +[`tf.get_default_graph()`](framework.md#get_default_graph). To add an +operation to the default graph, simply call one of the functions that defines +a new `Operation`: + +``` +c = tf.constant(4.0) +assert c.graph is tf.get_default_graph() +``` + +Another typical usage involves the +[`Graph.as_default()`](framework.md#Graph.as_default) +context manager, which overrides the current default graph for the +lifetime of the context: + +```python +g = tf.Graph() +with g.as_default(): + # Define operations and tensors in `g`. + c = tf.constant(30.0) + assert c.graph is g +``` + +Important note: This class *is not* thread-safe for graph construction. All +operations should be created from a single thread, or external +synchronization must be provided. Unless otherwise specified, all methods +are not thread-safe. + +- - - + +#### tf.Graph.__init__() {#Graph.__init__} + +Creates a new, empty Graph. + + +- - - + +#### tf.Graph.as_default() {#Graph.as_default} + +Returns a context manager that makes this `Graph` the default graph. + +This method should be used if you want to create multiple graphs +in the same process. For convenience, a global default graph is +provided, and all ops will be added to this graph if you do not +create a new graph explicitly. Use this method the `with` keyword +to specify that ops created within the scope of a block should be +added to this graph. + +The default graph is a property of the current thread. If you +create a new thread, and wish to use the default graph in that +thread, you must explicitly add a `with g.as_default():` in that +thread's function. + +The following code examples are equivalent: + +```python +# 1. Using Graph.as_default(): +g = tf.Graph() +with g.as_default(): + c = tf.constant(5.0) + assert c.graph is g + +# 2. Constructing and making default: +with tf.Graph().as_default() as g: + c = tf.constant(5.0) + assert c.graph is g +``` + +##### Returns: + + A context manager for using this graph as the default graph. + + +- - - + +#### tf.Graph.as_graph_def(from_version=None) {#Graph.as_graph_def} + +Returns a serialized `GraphDef` representation of this graph. + +This method is thread-safe. + +##### Args: + + +* <b>from_version</b>: Optional. If this is set, returns a `GraphDef` + containing only the nodes that were added to this graph since + its `version` property had the given value. + +##### Returns: + + A + [`GraphDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/graph.proto) + protocol buffer. + + +- - - + +#### tf.Graph.finalize() {#Graph.finalize} + +Finalizes this graph, making it read-only. + +After calling `g.finalize()`, no new operations can be added to +`g`. This method is used to ensure that no operations are added +to a graph when it is shared between multiple threads, for example +when using a [`QueueRunner`](train.md#QueueRunner). + + +- - - + +#### tf.Graph.finalized {#Graph.finalized} + +True if this graph has been finalized. + + +- - - + +#### tf.Graph.control_dependencies(control_inputs) {#Graph.control_dependencies} + +Returns a context manager that specifies control dependencies. + +Use with the `with` keyword to specify that all operations constructed +within the context should have control dependencies on +`control_inputs`. For example: + +```python +with g.control_dependencies([a, b, c]): + # `d` and `e` will only run after `a`, `b`, and `c` have executed. + d = ... + e = ... +``` + +Multiple calls to `control_dependencies()` can be nested, and in +that case a new `Operation` will have control dependencies on the union +of `control_inputs` from all active contexts. + +```python +with g.control_dependencies([a, b]): + # Ops declared here run after `a` and `b`. + with g.control_dependencies([c, d]): + # Ops declared here run after `a`, `b`, `c`, and `d`. +``` + +*N.B.* The control dependencies context applies *only* to ops that +are constructed within the context. Merely using an op or tensor +in the context does not add a control dependency. The following +example illustrates this point: + +```python +# WRONG +def my_func(pred, tensor): + t = tf.matmul(tensor, tensor) + with tf.control_dependencies([pred]): + # The matmul op is created outside the context, so no control + # dependency will be added. + return t + +# RIGHT +def my_func(pred, tensor): + with tf.control_dependencies([pred]): + # The matmul op is created in the context, so a control dependency + # will be added. + return tf.matmul(tensor, tensor) +``` + +##### Args: + + +* <b>control_inputs</b>: A list of `Operation` or `Tensor` objects, which + must be executed or computed before running the operations + defined in the context. + +##### Returns: + + A context manager that specifies control dependencies for all + operations constructed within the context. + +##### Raises: + + +* <b>TypeError</b>: If `control_inputs` is not a list of `Operation` or + `Tensor` objects. + + +- - - + +#### tf.Graph.device(*args, **kwds) {#Graph.device} + +Returns a context manager that specifies the default device to use. + +The `device_name_or_function` argument may either be a device name +string, a device function, or None: + +* If it is a device name string, all operations constructed in + this context will be assigned to the device with that name. +* If it is a function, it will be treated as function from + Operation objects to device name strings, and invoked each time + a new Operation is created. The Operation will be assigned to + the device with the returned name. +* If it is None, the default device will be cleared. + +For example: + +```python +with g.device('/gpu:0'): + # All operations constructed in this context will be placed + # on GPU 0. + with g.device(None): + # All operations constructed in this context will have no + # assigned device. + +# Defines a function from `Operation` to device string. +def matmul_on_gpu(n): + if n.type == "MatMul": + return "/gpu:0" + else: + return "/cpu:0" + +with g.device(matmul_on_gpu): + # All operations of type "MatMul" constructed in this context + # will be placed on GPU 0; all other operations will be placed + # on CPU 0. +``` + +##### Args: + + +* <b>device_name_or_function</b>: The device name or function to use in + the context. + +##### Returns: + + A context manager that specifies the default device to use for newly + created ops. + + +- - - + +#### tf.Graph.name_scope(*args, **kwds) {#Graph.name_scope} + +Returns a context manager that creates hierarchical names for operations. + +A graph maintains a stack of name scopes. A `with name_scope(...):` +statement pushes a new name onto the stack for the lifetime of the context. + +The `name` argument will be interpreted as follows: + +* A string (not ending with '/') will create a new name scope, in which + `name` is appended to the prefix of all operations created in the + context. If `name` has been used before, it will be made unique by + calling `self.unique_name(name)`. +* A scope previously captured from a `with g.name_scope(...) as + scope:` statement will be treated as an "absolute" name scope, which + makes it possible to re-enter existing scopes. +* A value of `None` or the empty string will reset the current name scope + to the top-level (empty) name scope. + +For example: + +```python +with tf.Graph().as_default() as g: + c = tf.constant(5.0, name="c") + assert c_1.name == "c" + c_1 = tf.constant(6.0, name="c") + assert c_1.name == "c_1" + + # Creates a scope called "nested" + with g.name_scope("nested") as scope: + nested_c = tf.constant(10.0, name="c") + assert nested_c.name == "nested/c" + + # Creates a nested scope called "inner". + with g.name_scope("inner"): + nested_inner_c = tf.constant(20.0, name="c") + assert nested_inner_c.name == "nested/inner/c" + + # Create a nested scope called "inner_1". + with g.name_scope("inner"): + nested_inner_1_c = tf.constant(30.0, name="c") + assert nested_inner_1_c.name == "nested/inner_1/c" + + # Treats `scope` as an absolute name scope, and + # switches to the "nested/" scope. + with g.name_scope(scope): + nested_d = tf.constant(40.0, name="d") + assert nested_d.name == "nested/d" + + with g.name_scope(""): + e = tf.constant(50.0, name="e") + assert e.name == "e" +``` + +The name of the scope itself can be captured by `with +g.name_scope(...) as scope:`, which stores the name of the scope +in the variable `scope`. This value can be used to name an +operation that represents the overall result of executing the ops +in a scope. For example: + +```python +inputs = tf.constant(...) +with g.name_scope('my_layer') as scope: + weights = tf.Variable(..., name="weights") + biases = tf.Variable(..., name="biases") + affine = tf.matmul(inputs, weights) + biases + output = tf.nn.relu(affine, name=scope) +``` + + +##### Args: + + +* <b>name</b>: A name for the scope. + +##### Returns: + + A context manager that installs `name` as a new name scope. + + + +A `Graph` instance supports an arbitrary number of "collections" +that are identified by name. For convenience when building a large +graph, collections can store groups of related objects: for +example, the `tf.Variable` uses a collection (named +[`tf.GraphKeys.VARIABLES`](framework.md#GraphKeys)) for all variables that are +created during the construction of a graph. The caller may define +additional collections by specifying a new name. + +- - - + +#### tf.Graph.add_to_collection(name, value) {#Graph.add_to_collection} + +Stores `value` in the collection with the given `name`. + +##### Args: + + +* <b>name</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>value</b>: The value to add to the collection. + + +- - - + +#### tf.Graph.get_collection(name, scope=None) {#Graph.get_collection} + +Returns a list of values in the collection with the given `name`. + +##### Args: + + +* <b>key</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>scope</b>: (Optional.) If supplied, the resulting list is filtered to include + only items whose name begins with this string. + +##### Returns: + + The list of values in the collection with the given `name`, or + an empty list if no value has been added to that collection. The + list contains the values in the order under which they were + collected. + + + +- - - + +#### tf.Graph.as_graph_element(obj, allow_tensor=True, allow_operation=True) {#Graph.as_graph_element} + +Returns the object referred to by `obj`, as an `Operation` or `Tensor`. + +This function validates that `obj` represents an element of this +graph, and gives an informative error message if it is not. + +This function is the canonical way to get/validate an object of +one of the allowed types from an external argument reference in the +Session API. + +This method may be called concurrently from multiple threads. + +##### Args: + + +* <b>obj</b>: A `Tensor`, an `Operation`, or the name of a tensor or operation. + Can also be any object with an `_as_graph_element()` method that returns + a value of one of these types. +* <b>allow_tensor</b>: If true, `obj` may refer to a `Tensor`. +* <b>allow_operation</b>: If true, `obj` may refer to an `Operation`. + +##### Returns: + + The `Tensor` or `Operation` in the Graph corresponding to `obj`. + +##### Raises: + + +* <b>TypeError</b>: If `obj` is not a type we support attempting to convert + to types. +* <b>ValueError</b>: If `obj` is of an appropriate type but invalid. For + example, an invalid string. +* <b>KeyError</b>: If `obj` is not an object in the graph. + + +- - - + +#### tf.Graph.get_operation_by_name(name) {#Graph.get_operation_by_name} + +Returns the `Operation` with the given `name`. + +This method may be called concurrently from multiple threads. + +##### Args: + + +* <b>name</b>: The name of the `Operation` to return. + +##### Returns: + + The `Operation` with the given `name`. + +##### Raises: + + +* <b>TypeError</b>: If `name` is not a string. +* <b>KeyError</b>: If `name` does not correspond to an operation in this graph. + + +- - - + +#### tf.Graph.get_tensor_by_name(name) {#Graph.get_tensor_by_name} + +Returns the `Tensor` with the given `name`. + +This method may be called concurrently from multiple threads. + +##### Args: + + +* <b>name</b>: The name of the `Tensor` to return. + +##### Returns: + + The `Tensor` with the given `name`. + +##### Raises: + + +* <b>TypeError</b>: If `name` is not a string. +* <b>KeyError</b>: If `name` does not correspond to a tensor in this graph. + + +- - - + +#### tf.Graph.get_operations() {#Graph.get_operations} + +Return the list of operations in the graph. + +You can modify the operations in place, but modifications +to the list such as inserts/delete have no effect on the +list of operations known to the graph. + +This method may be called concurrently from multiple threads. + +##### Returns: + + A list of Operations. + + + +- - - + +#### tf.Graph.get_default_device() {#Graph.get_default_device} + +Returns the default device. + +##### Returns: + + A string. + + +- - - + +#### tf.Graph.seed {#Graph.seed} + + + +- - - + +#### tf.Graph.unique_name(name) {#Graph.unique_name} + +Return a unique Operation name for "name". + +Note: You rarely need to call unique_name() directly. Most of the time you +just need to create "with g.name_scope()" blocks to generate structured +names. + +`unique_name` is used to generate structured names, separated by "/", +to help identify Operations when debugging a Graph. Operation names +are displayed in error messages reported by the TensorFlow runtime, +and in various visualization tools such as TensorBoard. + +##### Args: + + +* <b>name</b>: The name for an `Operation`. + +##### Returns: + + A string to be passed to `create_op()` that will be used + to name the operation being created. + + +- - - + +#### tf.Graph.version {#Graph.version} + +Returns a version number that increases as ops are added to the graph. + + +- - - + +#### tf.Graph.create_op(op_type, inputs, dtypes, input_types=None, name=None, attrs=None, op_def=None, compute_shapes=True) {#Graph.create_op} + +Creates an `Operation` in this graph. + +This is a low-level interface for creating an `Operation`. Most +programs will not call this method directly, and instead use the +Python op constructors, such as `tf.constant()`, which add ops to +the default graph. + +##### Args: + + +* <b>op_type</b>: The `Operation` type to create. This corresponds to the + `OpDef.name` field for the proto that defines the operation. +* <b>inputs</b>: A list of `Tensor` objects that will be inputs to the `Operation`. +* <b>dtypes</b>: A list of `DType` objects that will be the types of the tensors + that the operation produces. +* <b>input_types</b>: (Optional.) A list of `DType`s that will be the types of + the tensors that the operation consumes. By default, uses the base + `DType` of each input in `inputs`. Operations that expect + reference-typed inputs must specify `input_types` explicitly. +* <b>name</b>: (Optional.) A string name for the operation. If not specified, a + name is generated based on `op_type`. +* <b>attrs</b>: (Optional.) A list of `AttrValue` protos for the `attr` field of + the `NodeDef` proto that will represent the operation. +* <b>op_def</b>: (Optional.) The `OpDef` proto that describes the `op_type` that + the operation will have. +* <b>compute_shapes</b>: (Optional.) If True, shape inference will be performed + to compute the shapes of the outputs. + +##### Raises: + + +* <b>TypeError</b>: if any of the inputs is not a `Tensor`. + +##### Returns: + + An `Operation` object. + + +- - - + +#### tf.Graph.gradient_override_map(*args, **kwds) {#Graph.gradient_override_map} + +EXPERIMENTAL: A context manager for overriding gradient functions. + +This context manager can be used to override the gradient function +that will be used for ops within the scope of the context. + +For example: + +```python +@tf.RegisterGradient("CustomSquare") +def _custom_square_grad(op, inputs): + # ... + +with tf.Graph().as_default() as g: + c = tf.constant(5.0) + s_1 = tf.square(c) # Uses the default gradient for tf.square. + with g.gradient_override_map({"Square": "CustomSquare"}): + s_2 = tf.square(s_2) # Uses _custom_square_grad to compute the + # gradient of s_2. +``` + +##### Args: + + +* <b>op_type_map</b>: A dictionary mapping op type strings to alternative op + type strings. + +##### Returns: + + A context manager that sets the alternative op type to be used for one + or more ops created in that context. + +##### Raises: + + +* <b>TypeError</b>: If `op_type_map` is not a dictionary mapping strings to + strings. + + + +- - - + +### class tf.Operation <div class="md-anchor" id="Operation">{#Operation}</div> + +Represents a graph node that performs computation on tensors. + +An `Operation` is a node in a TensorFlow `Graph` that takes zero or +more `Tensor` objects as input, and produces zero or more `Tensor` +objects as output. Objects of type `Operation` are created by +calling a Python op constructor (such as [`tf.matmul()`](math_ops.md#matmul)) +or [`Graph.create_op()`](framework.md#Graph.create_op). + +For example `c = tf.matmul(a, b)` creates an `Operation` of type +"MatMul" that takes tensors `a` and `b` as input, and produces `c` +as output. + +After the graph has been launched in a session, an `Operation` can +be executed by passing it to [`Session.run()`](client.md#Session.run). +`op.run()` is a shortcut for calling `tf.get_default_session().run(op)`. + +- - - + +#### tf.Operation.name {#Operation.name} + +The full name of this operation. + +- - - + +#### tf.Operation.type {#Operation.type} + +The type of the op (e.g. `"MatMul"`). + +- - - + +#### tf.Operation.inputs {#Operation.inputs} + +The list of `Tensor` objects representing the data inputs of this op. + +- - - + +#### tf.Operation.control_inputs {#Operation.control_inputs} + +The `Operation` objects on which this op has a control dependency. + +Before this op is executed, TensorFlow will ensure that the +operations in `self.control_inputs` have finished executing. This +mechanism can be used to run ops sequentially for performance +reasons, or to ensure that the side effects of an op are observed +in the correct order. + +##### Returns: + + A list of `Operation` objects. + +- - - + +#### tf.Operation.outputs {#Operation.outputs} + +The list of `Tensor` objects representing the outputs of this op. + +- - - + +#### tf.Operation.device {#Operation.device} + +The name of the device to which this op has been assigned, if any. + +##### Returns: + + The string name of the device to which this op has been + assigned, or None if it has not been assigned to a device. + +- - - + +#### tf.Operation.graph {#Operation.graph} + +The `Graph` that contains this operation. + + +- - - + +#### tf.Operation.run(feed_dict=None, session=None) {#Operation.run} + +Runs this operation in a `Session`. + +Calling this method will execute all preceding operations that +produce the inputs needed for this operation. + +*N.B.* Before invoking `Operation.run()`, its graph must have been +launched in a session, and either a default session must be +available, or `session` must be specified explicitly. + +##### Args: + + +* <b>feed_dict</b>: A dictionary that maps `Tensor` objects to feed values. + See [`Session.run()`](client.md#Session.run) for a description of the + valid feed values. +* <b>session</b>: (Optional.) The `Session` to be used to run to this operation. If + none, the default session will be used. + + + +- - - + +#### tf.Operation.get_attr(name) {#Operation.get_attr} + +Returns the value of the attr of this op with the given `name`. + +##### Args: + + +* <b>name</b>: The name of the attr to fetch. + +##### Returns: + + The value of the attr, as a Python object. + +##### Raises: + + +* <b>ValueError</b>: If this op does not have an attr with the given `name`. + + +- - - + +#### tf.Operation.traceback {#Operation.traceback} + +Returns the call stack from when this operation was constructed. + + +#### Other Methods +- - - + +#### tf.Operation.__init__(node_def, g, inputs=None, output_types=None, control_inputs=None, input_types=None, original_op=None, op_def=None) {#Operation.__init__} + +Creates an `Operation`. + +NOTE: This constructor validates the name of the Operation (passed +as "node_def.name"). Valid Operation names match the following +regular expression: + + [A-Za-z0-9.][A-Za-z0-9_.\-/]* + +##### Args: + + +* <b>node_def</b>: graph_pb2.NodeDef. NodeDef for the Operation. + Used for attributes of graph_pb2.NodeDef, typically "name", + "op", and "device". The "input" attribute is irrelevant here + as it will be computed when generating the model. +* <b>g</b>: Graph. The parent graph. +* <b>inputs</b>: list of Tensor objects. The inputs to this Operation. +* <b>output_types</b>: list of types_pb2.DataType. List of the types of the + Tensors computed by this operation. The length of this list indicates + the number of output endpoints of the Operation. +* <b>control_inputs</b>: list of operations or tensors from which to have a + control dependency. +* <b>input_types</b>: List of types_pb2.DataType representing the + types of the Tensors accepted by the Operation. By default + uses [x.dtype.base_dtype for x in inputs]. Operations that expect + reference-typed inputs must specify these explicitly. +* <b>original_op</b>: Optional. Used to associate the new Operation with an + existing Operation (for example, a replica with the op that was + replicated). +* <b>op_def</b>: Optional. The op_def_pb2.OpDef proto that describes the + op type that this Operation represents. + +##### Raises: + + +* <b>TypeError</b>: if control inputs are not Operations or Tensors, + or if node_def is not a NodeDef, + or if g is not a Graph, + or if inputs are not Tensors, + or if inputs and input_types are incompatible. +* <b>ValueError</b>: if the node_def name is not valid. + + +- - - + +#### tf.Operation.node_def {#Operation.node_def} + +Returns a serialized `NodeDef` representation of this operation. + +##### Returns: + + A + [`NodeDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/graph.proto) + protocol buffer. + +- - - + +#### tf.Operation.op_def {#Operation.op_def} + +Returns the `OpDef` proto that represents the type of this op. + +##### Returns: + + An + [`OpDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/op_def.proto) + protocol buffer. + +- - - + +#### tf.Operation.values() {#Operation.values} + +DEPRECATED: Use outputs. + + + +- - - + +### class tf.Tensor <div class="md-anchor" id="Tensor">{#Tensor}</div> + +Represents a value produced by an `Operation`. + +A `Tensor` is a symbolic handle to one of the outputs of an +`Operation`. It does not hold the values of that operation's output, +but instead provides a means of computing those values in a +TensorFlow [`Session`](client.md#Session). + +This class has two primary purposes: + +1. A `Tensor` can be passed as an input to another `Operation`. + This builds a dataflow connection between operations, which + enables TensorFlow to execute an entire `Graph` that represents a + large, multi-step computation. + +2. After the graph has been launched in a session, the value of the + `Tensor` can be computed by passing it to + [`Session.run()`](client.md#Session.run). + `t.eval()` is a shortcut for calling + `tf.get_default_session().run(t)`. + +In the following example, `c`, `d`, and `e` are symbolic `Tensor` +objects, whereas `result` is a numpy array that stores a concrete +value: + +```python +# Build a dataflow graph. +c = tf.constant([[1.0, 2.0], [3.0, 4.0]]) +d = tf.constant([[1.0, 1.0], [0.0, 1.0]]) +e = tf.matmul(c, d) + +# Construct a `Session` to execut the graph. +sess = tf.Session() + +# Execute the graph and store the value that `e` represents in `result`. +result = sess.run(e) +``` + +- - - + +#### tf.Tensor.dtype {#Tensor.dtype} + +The `DType` of elements in this tensor. + +- - - + +#### tf.Tensor.name {#Tensor.name} + +The string name of this tensor. + +- - - + +#### tf.Tensor.value_index {#Tensor.value_index} + +The index of this tensor in the outputs of its `Operation`. + +- - - + +#### tf.Tensor.graph {#Tensor.graph} + +The `Graph` that contains this tensor. + +- - - + +#### tf.Tensor.op {#Tensor.op} + +The `Operation` that produces this tensor as an output. + +- - - + +#### tf.Tensor.consumers() {#Tensor.consumers} + +Returns a list of `Operation`s that consume this tensor. + +##### Returns: + + A list of `Operation`s. + + + +- - - + +#### tf.Tensor.eval(feed_dict=None, session=None) {#Tensor.eval} + +Evaluates this tensor in a `Session`. + +Calling this method will execute all preceding operations that +produce the inputs needed for the operation that produces this +tensor. + +*N.B.* Before invoking `Tensor.eval()`, its graph must have been +launched in a session, and either a default session must be +available, or `session` must be specified explicitly. + +##### Args: + + +* <b>feed_dict</b>: A dictionary that maps `Tensor` objects to feed values. + See [`Session.run()`](client.md#Session.run) for a description of + the valid feed values. +* <b>session</b>: (Optional.) The `Session` to be used to evaluate this tensor. If + none, the default session will be used. + +##### Returns: + + A numpy array corresponding to the value of this tensor. + + + +- - - + +#### tf.Tensor.get_shape() {#Tensor.get_shape} + +Returns the `TensorShape` that represents the shape of this tensor. + +The shape is computed using shape inference functions that are +registered for each `Operation` type using `tf.RegisterShape`. +See [`TensorShape`](framework.md#TensorShape) for more details of what a shape +represents. + +The inferred shape of a tensor is used to provide shape +information without having to launch the graph in a session. This +can be used for debugging, and providing early error messages. For +example: + +```python +c = tf.constant([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]) + +print c.get_shape() +==> TensorShape([Dimension(2), Dimension(3)]) + +d = tf.constant([[1.0, 0.0], [0.0, 1.0], [1.0, 0.0], [0.0, 1.0]]) + +print d.get_shape() +==> TensorShape([Dimension(4), Dimension(2)]) + +# Raises a ValueError, because `c` and `d` do not have compatible +# inner dimensions. +e = tf.matmul(c, d) + +f = tf.matmul(c, d, transpose_a=True, transpose_b=True) + +print f.get_shape() +==> TensorShape([Dimension(3), Dimension(4)]) +``` + +In some cases, the inferred shape may have unknown dimensions. If +the caller has additional information about the values of these +dimensions, `Tensor.set_shape()` can be used to augment the +inferred shape. + +##### Returns: + + A `TensorShape` representing the shape of this tensor. + + +- - - + +#### tf.Tensor.set_shape(shape) {#Tensor.set_shape} + +Updates the shape of this tensor. + +This method can be called multiple times, and will merge the given +`shape` with the current shape of this tensor. It can be used to +provide additional information about the shape of this tensor that +cannot be inferred from the graph alone. For example, this can be used +to provide additional information about the shapes of images: + +```python +_, image_data = tf.TFRecordReader(...).read(...) +image = tf.image.decode_png(image_data, channels=3) + +# The height and width dimensions of `image` are data dependent, and +# cannot be computed without executing the op. +print image.get_shape() +==> TensorShape([Dimension(None), Dimension(None), Dimension(3)]) + +# We know that each image in this dataset is 28 x 28 pixels. +image.set_shape([28, 28, 3]) +print image.get_shape() +==> TensorShape([Dimension(28), Dimension(28), Dimension(3)]) +``` + +##### Args: + + +* <b>shape</b>: A `TensorShape` representing the shape of this tensor. + +##### Raises: + + +* <b>ValueError</b>: If `shape` is not compatible with the current shape of + this tensor. + + + +#### Other Methods +- - - + +#### tf.Tensor.__init__(op, value_index, dtype) {#Tensor.__init__} + +Creates a new `Tensor`. + +##### Args: + + +* <b>op</b>: An `Operation`. `Operation` that computes this tensor. +* <b>value_index</b>: An `int`. Index of the operation's endpoint that produces + this tensor. +* <b>dtype</b>: A `types.DType`. Type of data stored in this tensor. + +##### Raises: + + +* <b>TypeError</b>: If the op is not an `Operation`. + + +- - - + +#### tf.Tensor.device {#Tensor.device} + +The name of the device on which this tensor will be produced, or None. + + + +## Tensor types <div class="md-anchor" id="AUTOGENERATED-tensor-types">{#AUTOGENERATED-tensor-types}</div> + +- - - + +### class tf.DType <div class="md-anchor" id="DType">{#DType}</div> + +Represents the type of the elements in a `Tensor`. + +The following `DType` objects are defined: + +* `tf.float32`: 32-bit single-precision floating-point. +* `tf.float64`: 64-bit double-precision floating-point. +* `tf.bfloat16`: 16-bit truncated floating-point. +* `tf.complex64`: 64-bit single-precision complex. + +* `tf.int8`: 8-bit signed integer. +* `tf.uint8`: 8-bit unsigned integer. +* `tf.int32`: 32-bit signed integer. +* `tf.int64`: 64-bit signed integer. + +* `tf.bool`: Boolean. + +* `tf.string`: String. + +* `tf.qint8`: Quantized 8-bit signed integer. +* `tf.quint8`: Quantized 8-bit unsigned integer. +* `tf.qint32`: Quantized 32-bit signed integer. + +In addition, variants of these types with the `_ref` suffix are +defined for reference-typed tensors. + +The `tf.as_dtype()` function converts numpy types and string type +names to a `DType` object. + +- - - + +#### tf.DType.is_compatible_with(other) {#DType.is_compatible_with} + +Returns True if the `other` DType will be converted to this DType. + +The conversion rules are as follows: + +``` +DType(T) .is_compatible_with(DType(T)) == True +DType(T) .is_compatible_with(DType(T).as_ref) == True +DType(T).as_ref.is_compatible_with(DType(T)) == False +DType(T).as_ref.is_compatible_with(DType(T).as_ref) == True +``` + +##### Args: + + +* <b>other</b>: A `DType` (or object that may be converted to a `DType`). + +##### Returns: + + True if a Tensor of the `other` `DType` will be implicitly converted to + this `DType`. + + +- - - + +#### tf.DType.name {#DType.name} + +Returns the string name for this `DType`. + +- - - + +#### tf.DType.base_dtype {#DType.base_dtype} + +Returns a non-reference `DType` based on this `DType`. + +- - - + +#### tf.DType.is_ref_dtype {#DType.is_ref_dtype} + +Returns `True` if this `DType` represents a reference type. + +- - - + +#### tf.DType.as_ref {#DType.as_ref} + +Returns a reference `DType` based on this `DType`. + +- - - + +#### tf.DType.is_integer {#DType.is_integer} + +Returns whether this is a (non-quantized) integer type. + +- - - + +#### tf.DType.is_quantized {#DType.is_quantized} + +Returns whether this is a quantized data type. + + +- - - + +#### tf.DType.as_numpy_dtype {#DType.as_numpy_dtype} + +Returns a `numpy.dtype` based on this `DType`. + +- - - + +#### tf.DType.as_datatype_enum {#DType.as_datatype_enum} + +Returns a `types_pb2.DataType` enum value based on this `DType`. + + +#### Other Methods +- - - + +#### tf.DType.__init__(type_enum) {#DType.__init__} + +Creates a new `DataType`. + +NOTE(mrry): In normal circumstances, you should not need to +construct a DataType object directly. Instead, use the +types.as_dtype() function. + +##### Args: + + +* <b>type_enum</b>: A `types_pb2.DataType` enum value. + +##### Raises: + + +* <b>TypeError</b>: If `type_enum` is not a value `types_pb2.DataType`. + + +- - - + +#### tf.DType.max {#DType.max} + +Returns the maximum representable value in this data type. + +##### Raises: + + +* <b>TypeError</b>: if this is a non-numeric, unordered, or quantized type. + +- - - + +#### tf.DType.min {#DType.min} + +Returns the minimum representable value in this data type. + +##### Raises: + + +* <b>TypeError</b>: if this is a non-numeric, unordered, or quantized type. + + +- - - + +### tf.as_dtype(type_value) <div class="md-anchor" id="as_dtype">{#as_dtype}</div> + +Converts the given `type_value` to a `DType`. + +##### Args: + + +* <b>type_value</b>: A value that can be converted to a `tf.DType` + object. This may currently be a `tf.DType` object, a + [`DataType` enum](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/types.proto), + a string type name, or a `numpy.dtype`. + +##### Returns: + + A `DType` corresponding to `type_value`. + +##### Raises: + + +* <b>TypeError</b>: If `type_value` cannot be converted to a `DType`. + + + +## Utility functions <div class="md-anchor" id="AUTOGENERATED-utility-functions">{#AUTOGENERATED-utility-functions}</div> + +- - - + +### tf.device(dev) <div class="md-anchor" id="device">{#device}</div> + +Wrapper for `Graph.device()` using the default graph. + +See [`Graph.name_scope()`](framework.md#Graph.name_scope) for more details. + +##### Args: + + +* <b>device_name_or_function</b>: The device name or function to use in + the context. + +##### Returns: + + A context manager that specifies the default device to use for newly + created ops. + + +- - - + +### tf.name_scope(name) <div class="md-anchor" id="name_scope">{#name_scope}</div> + +Wrapper for `Graph.name_scope()` using the default graph. + +See [`Graph.name_scope()`](framework.md#Graph.name_scope) for more details. + +##### Args: + + +* <b>name</b>: A name for the scope. + +##### Returns: + + A context manager that installs `name` as a new name scope in the + default graph. + + +- - - + +### tf.control_dependencies(control_inputs) <div class="md-anchor" id="control_dependencies">{#control_dependencies}</div> + +Wrapper for `Graph.control_dependencies()` using the default graph. + +See [`Graph.control_dependencies()`](framework.md#Graph.control_dependencies) +for more details. + +##### Args: + + +* <b>control_inputs</b>: A list of `Operation` or `Tensor` objects, which + must be executed or computed before running the operations + defined in the context. + +##### Returns: + + A context manager that specifies control dependencies for all + operations constructed within the context. + + +- - - + +### tf.convert_to_tensor(value, dtype=None, name=None) <div class="md-anchor" id="convert_to_tensor">{#convert_to_tensor}</div> + +Converts the given `value` to a `Tensor`. + +This function converts Python objects of various types to `Tensor` +objects. It accepts `Tensor` objects, numpy arrays, Python lists, +and Python scalars. For example: + +```python +import numpy as np +array = np.random.rand((32, 100, 100)) + +def my_func(arg): + arg = tf.convert_to_tensor(arg, dtype=tf.float32) + return tf.matmul(arg, arg) + arg + +# The following calls are equivalent. +value_1 = my_func(tf.constant([[1.0, 2.0], [3.0, 4.0])) +value_2 = my_func([[1.0, 2.0], [3.0, 4.0]]) +value_3 = my_func(numpy.array([[1.0, 2.0], [3.0, 4.0]], dtype=numpy.float32)) +``` + +This function can be useful when composing a new operation in Python +(such as `my_func` in the example above). All standard Python op +constructors apply this function to each of their Tensor-valued +inputs, which allows those ops to accept numpy arrays, Python lists, +and scalars in addition to `Tensor` objects. + +##### Args: + + +* <b>value</b>: An object whose type has a registered `Tensor` conversion function. +* <b>dtype</b>: Optional element type for the returned tensor. If missing, the + type is inferred from the type of `value`. +* <b>name</b>: Optional name to use if a new `Tensor` is created. + +##### Returns: + + A `Tensor` based on `value`. + +##### Raises: + + +* <b>TypeError</b>: If no conversion function is registered for `value`. +* <b>RuntimeError</b>: If a registered conversion function returns an invalid value. + + +- - - + +### tf.get_default_graph() <div class="md-anchor" id="get_default_graph">{#get_default_graph}</div> + +Returns the default graph for the current thread. + +The returned graph will be the innermost graph on which a +`Graph.as_default()` context has been entered, or a global default +graph if none has been explicitly created. + +*N.B.* The default graph is a property of the current thread. If you +create a new thread, and wish to use the default graph in that +thread, you must explicitly add a `with g.as_default():` in that +thread's function. + +##### Returns: + + The default `Graph` being used in the current thread. + + +- - - + +### tf.import_graph_def(graph_def, input_map=None, return_elements=None, name=None, op_dict=None) <div class="md-anchor" id="import_graph_def">{#import_graph_def}</div> + +Imports the TensorFlow graph in `graph_def` into the Python `Graph`. + +This function provides a way to import a serialized TensorFlow +[`GraphDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/graph.proto) +protocol buffer, and extract individual objects in the `GraphDef` as +[`Tensor`](#Tensor) and [`Operation`](#Operation) objects. See +[`Graph.as_graph_def()`](#Graph.as_graph_def) for a way to create a +`GraphDef` proto. + +##### Args: + + +* <b>graph_def</b>: A `GraphDef` proto containing operations to be imported into + the default graph. +* <b>input_map</b>: A dictionary mapping input names (as strings) in `graph_def` + to `Tensor` objects. The values of the named input tensors in the + imported graph will be re-mapped to the respective `Tensor` values. +* <b>return_elements</b>: A list of strings containing operation names in + `graph_def` that will be returned as `Operation` objects; and/or + tensor names in `graph_def` that will be returned as `Tensor` objects. +* <b>name</b>: (Optional.) A prefix that will be prepended to the names in + `graph_def`. Defaults to `"import"`. +* <b>op_dict</b>: (Optional.) A dictionary mapping op type names to `OpDef` protos. + Must contain an `OpDef` proto for each op type named in `graph_def`. + If omitted, uses the `OpDef` protos registered in the global registry. + +##### Returns: + + A list of `Operation` and/or `Tensor` objects from the imported graph, + corresponding to the names in `return_elements'. + +##### Raises: + + +* <b>TypeError</b>: If `graph_def` is not a `GraphDef` proto, + `input_map' is not a dictionary mapping strings to `Tensor` objects, + or `return_elements` is not a list of strings. +* <b>ValueError</b>: If `input_map`, or `return_elements` contains names that + do not appear in `graph_def`, or `graph_def` is not well-formed (e.g. + it refers to an unknown tensor). + + + +## Graph collections <div class="md-anchor" id="AUTOGENERATED-graph-collections">{#AUTOGENERATED-graph-collections}</div> + +- - - + +### tf.add_to_collection(name, value) <div class="md-anchor" id="add_to_collection">{#add_to_collection}</div> + +Wrapper for `Graph.add_to_collection()` using the default graph. + +See [`Graph.add_to_collection()`](framework.md#Graph.add_to_collection) +for more details. + +##### Args: + + +* <b>name</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>value</b>: The value to add to the collection. + + +- - - + +### tf.get_collection(key, scope=None) <div class="md-anchor" id="get_collection">{#get_collection}</div> + +Wrapper for `Graph.get_collection()` using the default graph. + +See [`Graph.get_collection()`](framework.md#Graph.get_collection) +for more details. + +##### Args: + + +* <b>key</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>scope</b>: (Optional.) If supplied, the resulting list is filtered to include + only items whose name begins with this string. + +##### Returns: + + The list of values in the collection with the given `name`, or + an empty list if no value has been added to that collection. The + list contains the values in the order under which they were + collected. + + +- - - + +### class tf.GraphKeys <div class="md-anchor" id="GraphKeys">{#GraphKeys}</div> + +Standard names to use for graph collections. + +The standard library uses various well-known names to collect and +retrieve values associated with a graph. For example, the +`tf.Optimizer` subclasses default to optimizing the variables +collected under `tf.GraphKeys.TRAINABLE_VARIABLES` if none is +specified, but it is also possible to pass an explicit list of +variables. + +The following standard keys are defined: + +* `VARIABLES`: the `Variable` objects that comprise a model, and + must be saved and restored together. See + [`tf.all_variables()`](state_ops.md#all_variables) for more details. +* `TRAINABLE_VARIABLES`: the subset of `Variable` objects that will + be trained by an optimizer. See + [`tf.trainable_variables()`](state_ops.md#trainable_variables) + for more details. +* `SUMMARIES`: the summary `Tensor` objects that have been created + in the graph. See [`tf.merge_all_summaries()`](train.md#merge_all_summaries) + for more details. +* `QUEUE_RUNNERS`: the `QueueRunner` objects that are used to + produce input for a computation. See + [`tf.start_queue_runners()`](train.md#start_queue_runners) for more details. + + +## Defining new operations <div class="md-anchor" id="AUTOGENERATED-defining-new-operations">{#AUTOGENERATED-defining-new-operations}</div> + +- - - + +### class tf.RegisterGradient <div class="md-anchor" id="RegisterGradient">{#RegisterGradient}</div> + +A decorator for registering the gradient function for an op type. + +This decorator is only used when defining a new op type. For an op +with `m` inputs and `n` inputs, the gradient function is a function +that takes the original `Operation` and `n` `Tensor` objects +(representing the gradients with respect to each output of the op), +and returns `m` `Tensor` objects (representing the partial gradients +with respect to each input of the op). + +For example, assuming that operations of type `"Sub"` take two +inputs `x` and `y`, and return a single output `x - y`, the +following gradient function would be registered: + +```python +@tf.RegisterGradient("Sub") +def _sub_grad(unused_op, grad): + return grad, tf.Neg(grad) +``` + +The decorator argument `op_type` is the string type of an +operation. This corresponds to the `OpDef.name` field for the proto +that defines the operation. + +- - - + +#### tf.RegisterGradient.__init__(op_type) {#RegisterGradient.__init__} + +Creates a new decorator with `op_type` as the Operation type. + +##### Args: + + +* <b>op_type</b>: The string type of an operation. This corresponds to the + `OpDef.name` field for the proto that defines the operation. + + + +- - - + +### tf.NoGradient(op_type) <div class="md-anchor" id="NoGradient">{#NoGradient}</div> + +Specifies that ops of type `op_type` do not have a defined gradient. + +This function is only used when defining a new op type. It may be +used for ops such as `tf.size()` that are not differentiable. For +example: + +```python +tf.NoGradient("Size") +``` + +##### Args: + + +* <b>op_type</b>: The string type of an operation. This corresponds to the + `OpDef.name` field for the proto that defines the operation. + +##### Raises: + + +* <b>TypeError</b>: If `op_type` is not a string. + + +- - - + +### class tf.RegisterShape <div class="md-anchor" id="RegisterShape">{#RegisterShape}</div> + +A decorator for registering the shape function for an op type. + +This decorator is only used when defining a new op type. A shape +function is a function from an `Operation` object to a list of +`TensorShape` objects, with one `TensorShape` for each output of the +operation. + +For example, assuming that operations of type `"Sub"` take two +inputs `x` and `y`, and return a single output `x - y`, all with the +same shape, the following shape function would be registered: + +```python +@tf.RegisterShape("Sub") +def _sub_shape(op): + return [op.inputs[0].get_shape().merge_with(op.inputs[1].get_shape())] +``` + +The decorator argument `op_type` is the string type of an +operation. This corresponds to the `OpDef.name` field for the proto +that defines the operation. +- - - + +#### tf.RegisterShape.__init__(op_type) {#RegisterShape.__init__} + +Saves the "op_type" as the Operation type. + + + +- - - + +### class tf.TensorShape <div class="md-anchor" id="TensorShape">{#TensorShape}</div> + +Represents the shape of a `Tensor`. + +A `TensorShape` represents a possibly-partial shape specification for a +`Tensor`. It may be one of the following: + +* *Fully-known shape:* has a known number of dimensions and a known size + for each dimension. +* *Partially-known shape:* has a known number of dimensions, and an unknown + size for one or more dimension. +* *Unknown shape:* has an unknown number of dimensions, and an unknown + size in all dimensions. + +If a tensor is produced by an operation of type `"Foo"`, its shape +may be inferred if there is a registered shape function for +`"Foo"`. See [`tf.RegisterShape()`](framework.md#RegisterShape) +for details of shape +functions and how to register them. Alternatively, the shape may be set +explicitly using [`Tensor.set_shape()`](framework.md#Tensor.set_shape). + +- - - + +#### tf.TensorShape.merge_with(other) {#TensorShape.merge_with} + +Returns a `TensorShape` combining the information in `self` and `other`. + +The dimensions in `self` and `other` are merged elementwise, +according to the rules defined for `Dimension.merge_with()`. + +##### Args: + + +* <b>other</b>: Another `TensorShape`. + +##### Returns: + + A `TensorShape` containing the combined information of `self` and + `other`. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` are not compatible. + + +- - - + +#### tf.TensorShape.concatenate(other) {#TensorShape.concatenate} + +Returns the concatenation of the dimension in `self` and `other`. + +*N.B.* If either `self` or `other` is completely unknown, +concatenation will discard information about the other shape. In +future, we might support concatenation that preserves this +information for use with slicing. + +##### Args: + + +* <b>other</b>: Another `TensorShape`. + +##### Returns: + + A `TensorShape` whose dimensions are the concatenation of the + dimensions in `self` and `other`. + + + +- - - + +#### tf.TensorShape.ndims {#TensorShape.ndims} + +Returns the rank of this shape, or None if it is unspecified. + +- - - + +#### tf.TensorShape.dims {#TensorShape.dims} + +Returns a list of Dimensions, or None if the shape is unspecified. + +- - - + +#### tf.TensorShape.as_list() {#TensorShape.as_list} + +Returns a list of integers or None for each dimension. + + +- - - + +#### tf.TensorShape.is_compatible_with(other) {#TensorShape.is_compatible_with} + +Returns True iff `self` is compatible with `other`. + +Two possibly-partially-defined shapes are compatible if there +exists a fully-defined shape that both shapes can represent. Thus, +compatibility allows the shape inference code to reason about +partially-defined shapes. For example: + +* TensorShape(None) is compatible with all shapes. + +* TensorShape([None, None]) is compatible with all two-dimensional + shapes, such as TensorShape([32, 784]), and also TensorShape(None). It is + not compatible with, for example, TensorShape([None]) or + TensorShape([None, None, None]). + +* TensorShape([32, None]) is compatible with all two-dimensional shapes + with size 32 in the 0th dimension, and also TensorShape([None, None]) + and TensorShape(None). It is not compatible with, for example, + TensorShape([32]), TensorShape([32, None, 1]) or TensorShape([64, None]). + +* TensorShape([32, 784]) is compatible with itself, and also + TensorShape([32, None]), TensorShape([None, 784]), TensorShape([None, + None]) and TensorShape(None). It is not compatible with, for example, + TensorShape([32, 1, 784]) or TensorShape([None]). + +The compatibility relation is reflexive and symmetric, but not +transitive. For example, TensorShape([32, 784]) is compatible with +TensorShape(None), and TensorShape(None) is compatible with +TensorShape([4, 4]), but TensorShape([32, 784]) is not compatible with +TensorShape([4, 4]). + +##### Args: + + +* <b>other</b>: Another TensorShape. + +##### Returns: + + True iff `self` is compatible with `other`. + + +- - - + +#### tf.TensorShape.is_fully_defined() {#TensorShape.is_fully_defined} + +Returns True iff `self` is fully defined in every dimension. + + + +- - - + +#### tf.TensorShape.with_rank(rank) {#TensorShape.with_rank} + +Returns a shape based on `self` with the given rank. + +This method promotes a completely unknown shape to one with a +known rank. + +##### Args: + + +* <b>rank</b>: An integer. + +##### Returns: + + A shape that is at least as specific as `self` with the given rank. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with the given `rank`. + + +- - - + +#### tf.TensorShape.with_rank_at_least(rank) {#TensorShape.with_rank_at_least} + +Returns a shape based on `self` with at least the given rank. + +##### Args: + + +* <b>rank</b>: An integer. + +##### Returns: + + A shape that is at least as specific as `self` with at least the given + rank. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with at least the given + `rank`. + + +- - - + +#### tf.TensorShape.with_rank_at_most(rank) {#TensorShape.with_rank_at_most} + +Returns a shape based on `self` with at most the given rank. + +##### Args: + + +* <b>rank</b>: An integer. + +##### Returns: + + A shape that is at least as specific as `self` with at most the given + rank. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with at most the given + `rank`. + + + +- - - + +#### tf.TensorShape.assert_has_rank(rank) {#TensorShape.assert_has_rank} + +Raises an exception if `self` is not compatible with the given `rank`. + +##### Args: + + +* <b>rank</b>: An integer. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with the given `rank`. + + +- - - + +#### tf.TensorShape.assert_same_rank(other) {#TensorShape.assert_same_rank} + +Raises an exception if `self` and `other` do not have compatible ranks. + +##### Args: + + +* <b>other</b>: Another `TensorShape`. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` do not represent shapes with the + same rank. + + +- - - + +#### tf.TensorShape.assert_is_compatible_with(other) {#TensorShape.assert_is_compatible_with} + +Raises exception if `self` and `other` do not represent the same shape. + +This method can be used to assert that there exists a shape that both +`self` and `other` represent. + +##### Args: + + +* <b>other</b>: Another TensorShape. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` do not represent the same shape. + + +- - - + +#### tf.TensorShape.assert_is_fully_defined() {#TensorShape.assert_is_fully_defined} + +Raises an exception if `self` is not fully defined in every dimension. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not have a known value for every dimension. + + + +#### Other Methods +- - - + +#### tf.TensorShape.__init__(dims) {#TensorShape.__init__} + +Creates a new TensorShape with the given dimensions. + +##### Args: + + +* <b>dims</b>: A list of Dimensions, or None if the shape is unspecified. +* <b>DEPRECATED</b>: A single integer is treated as a singleton list. + + +- - - + +#### tf.TensorShape.as_dimension_list() {#TensorShape.as_dimension_list} + +DEPRECATED: use as_list(). + + +- - - + +#### tf.TensorShape.num_elements() {#TensorShape.num_elements} + +Returns the total number of elements, or none for incomplete shapes. + + + +- - - + +### class tf.Dimension <div class="md-anchor" id="Dimension">{#Dimension}</div> + +Represents the value of one dimension in a TensorShape. +- - - + +#### tf.Dimension.__init__(value) {#Dimension.__init__} + +Creates a new Dimension with the given value. + + +- - - + +#### tf.Dimension.assert_is_compatible_with(other) {#Dimension.assert_is_compatible_with} + +Raises an exception if `other` is not compatible with this Dimension. + +##### Args: + + +* <b>other</b>: Another Dimension. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` are not compatible (see + is_compatible_with). + + +- - - + +#### tf.Dimension.is_compatible_with(other) {#Dimension.is_compatible_with} + +Returns true if `other` is compatible with this Dimension. + +Two known Dimensions are compatible if they have the same value. +An unknown Dimension is compatible with all other Dimensions. + +##### Args: + + +* <b>other</b>: Another Dimension. + +##### Returns: + + True if this Dimension and `other` are compatible. + + +- - - + +#### tf.Dimension.merge_with(other) {#Dimension.merge_with} + +Returns a Dimension that combines the information in `self` and `other`. + +Dimensions are combined as follows: + + Dimension(n) .merge_with(Dimension(n)) == Dimension(n) + Dimension(n) .merge_with(Dimension(None)) == Dimension(n) + Dimension(None).merge_with(Dimension(n)) == Dimension(n) + Dimension(None).merge_with(Dimension(None)) == Dimension(None) + Dimension(n) .merge_with(Dimension(m)) raises ValueError for n != m + +##### Args: + + +* <b>other</b>: Another Dimension. + +##### Returns: + + A Dimension containing the combined information of `self` and + `other`. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` are not compatible (see + is_compatible_with). + + +- - - + +#### tf.Dimension.value {#Dimension.value} + +The value of this dimension, or None if it is unknown. + + +- - - + +### tf.op_scope(*args, **kwds) <div class="md-anchor" id="op_scope">{#op_scope}</div> + +Returns a context manager for use when defining a Python op. + +This context manager validates that the given `values` are from the +same graph, ensures that that graph is the default graph, and pushes a +name scope. + +For example, to define a new Python op called `my_op`: + +```python +def my_op(a, b, c, name=None): + with tf.op_scope([a, b, c], name, "MyOp") as scope: + a = tf.convert_to_tensor(a, name="a") + b = tf.convert_to_tensor(b, name="b") + c = tf.convert_to_tensor(c, name="c") + # Define some computation that uses `a`, `b`, and `c`. + return foo_op(..., name=scope) +``` + +##### Args: + + +* <b>values</b>: The list of `Tensor` arguments that are passed to the op function. +* <b>name</b>: The name argument that is passed to the op function. +* <b>default_name</b>: The default name to use if the `name` argument is `None`. + +##### Returns: + + A context manager for use in defining a Python op. + + +- - - + +### tf.get_seed(op_seed) <div class="md-anchor" id="get_seed">{#get_seed}</div> + +Returns the local seeds an operation should use given an op-specific seed. + +Given operation-specific seed, `op_seed`, this helper function returns two +seeds derived from graph-level and op-level seeds. Many random operations +internally use the two seeds to allow user to change the seed globally for a +graph, or for only specific operations. + +For details on how the graph-level seed interacts with op seeds, see +[`set_random_seed`](constant_op.md#set_random_seed). + +##### Args: + + +* <b>op_seed</b>: integer. + +##### Returns: + + A tuple of two integers that should be used for the local seed of this + operation. + + diff --git a/tensorflow/g3doc/api_docs/python/image.md b/tensorflow/g3doc/api_docs/python/image.md new file mode 100644 index 0000000000..6b3d6c3ca7 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/image.md @@ -0,0 +1,857 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Images +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Encoding and Decoding.](#AUTOGENERATED-encoding-and-decoding.) + * [tf.image.decode_jpeg(contents, channels=None, ratio=None, fancy_upscaling=None, try_recover_truncated=None, acceptable_fraction=None, name=None)](#decode_jpeg) + * [tf.image.encode_jpeg(image, format=None, quality=None, progressive=None, optimize_size=None, chroma_downsampling=None, density_unit=None, x_density=None, y_density=None, xmp_metadata=None, name=None)](#encode_jpeg) + * [tf.image.decode_png(contents, channels=None, name=None)](#decode_png) + * [tf.image.encode_png(image, compression=None, name=None)](#encode_png) +* [Resizing.](#AUTOGENERATED-resizing.) + * [tf.image.resize_images(images, new_height, new_width, method=0)](#resize_images) + * [tf.image.resize_area(images, size, name=None)](#resize_area) + * [tf.image.resize_bicubic(images, size, name=None)](#resize_bicubic) + * [tf.image.resize_bilinear(images, size, name=None)](#resize_bilinear) + * [tf.image.resize_nearest_neighbor(images, size, name=None)](#resize_nearest_neighbor) +* [Cropping.](#AUTOGENERATED-cropping.) + * [tf.image.resize_image_with_crop_or_pad(image, target_height, target_width)](#resize_image_with_crop_or_pad) + * [tf.image.pad_to_bounding_box(image, offset_height, offset_width, target_height, target_width)](#pad_to_bounding_box) + * [tf.image.crop_to_bounding_box(image, offset_height, offset_width, target_height, target_width)](#crop_to_bounding_box) + * [tf.image.random_crop(image, size, seed=None, name=None)](#random_crop) + * [tf.image.extract_glimpse(input, size, offsets, centered=None, normalized=None, uniform_noise=None, name=None)](#extract_glimpse) +* [Flipping and Transposing.](#AUTOGENERATED-flipping-and-transposing.) + * [tf.image.flip_up_down(image)](#flip_up_down) + * [tf.image.random_flip_up_down(image, seed=None)](#random_flip_up_down) + * [tf.image.flip_left_right(image)](#flip_left_right) + * [tf.image.random_flip_left_right(image, seed=None)](#random_flip_left_right) + * [tf.image.transpose_image(image)](#transpose_image) +* [Image Adjustments.](#AUTOGENERATED-image-adjustments.) + * [tf.image.adjust_brightness(image, delta, min_value=None, max_value=None)](#adjust_brightness) + * [tf.image.random_brightness(image, max_delta, seed=None)](#random_brightness) + * [tf.image.adjust_contrast(images, contrast_factor, min_value=None, max_value=None)](#adjust_contrast) + * [tf.image.random_contrast(image, lower, upper, seed=None)](#random_contrast) + * [tf.image.per_image_whitening(image)](#per_image_whitening) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Encoding and Decoding. <div class="md-anchor" id="AUTOGENERATED-encoding-and-decoding.">{#AUTOGENERATED-encoding-and-decoding.}</div> + +TensorFlow provides Ops to decode and encode JPEG and PNG formats. Encoded +images are represented by scalar string Tensors, decoded images by 3-D uint8 +tensors of shape `[height, width, channels]`. + +The encode and decode Ops apply to one image at a time. Their input and output +are all of variable size. If you need fixed size images, pass the output of +the decode Ops to one of the cropping and resizing Ops. + +Note: The PNG encode and decode Ops support RGBA, but the conversions Ops +presently only support RGB, HSV, and GrayScale. + +- - - + +### tf.image.decode_jpeg(contents, channels=None, ratio=None, fancy_upscaling=None, try_recover_truncated=None, acceptable_fraction=None, name=None) <div class="md-anchor" id="decode_jpeg">{#decode_jpeg}</div> + +Decode a JPEG-encoded image to a uint8 tensor. + +The attr `channels` indicates the desired number of color channels for the +decoded image. + +Accepted values are: + +* 0: Use the number of channels in the JPEG-encoded image. +* 1: output a grayscale image. +* 3: output an RGB image. + +If needed, the JPEG-encoded image is transformed to match the requested number +of color channels. + +The attr `ratio` allows downscaling the image by an integer factor during +decoding. Allowed values are: 1, 2, 4, and 8. This is much faster than +downscaling the image later. + +##### Args: + + +* <b>contents</b>: A `Tensor` of type `string`. 0-D. The JPEG-encoded image. +* <b>channels</b>: An optional `int`. Defaults to `0`. + Number of color channels for the decoded image. +* <b>ratio</b>: An optional `int`. Defaults to `1`. Downscaling ratio. +* <b>fancy_upscaling</b>: An optional `bool`. Defaults to `True`. + If true use a slower but nicer upscaling of the + chroma planes (yuv420/422 only). +* <b>try_recover_truncated</b>: An optional `bool`. Defaults to `False`. + If true try to recover an image from truncated input. +* <b>acceptable_fraction</b>: An optional `float`. Defaults to `1`. + The minimum required fraction of lines before a truncated + input is accepted. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `uint8`. 3-D with shape `[height, width, channels]`.. + + +- - - + +### tf.image.encode_jpeg(image, format=None, quality=None, progressive=None, optimize_size=None, chroma_downsampling=None, density_unit=None, x_density=None, y_density=None, xmp_metadata=None, name=None) <div class="md-anchor" id="encode_jpeg">{#encode_jpeg}</div> + +JPEG-encode an image. + +`image` is a 3-D uint8 Tensor of shape `[height, width, channels]`. + +The attr `format` can be used to override the color format of the encoded +output. Values can be: + +* `''`: Use a default format based on the number of channels in the image. +* `grayscale`: Output a grayscale JPEG image. The `channels` dimension + of `image` must be 1. +* `rgb`: Output an RGB JPEG image. The `channels` dimension + of `image` must be 3. + +If `format` is not specified or is the empty string, a default format is picked +in function of the number of channels in `image`: + +* 1: Output a grayscale image. +* 3: Output an RGB image. + +##### Args: + + +* <b>image</b>: A `Tensor` of type `uint8`. + 3-D with shape `[height, width, channels]`. +* <b>format</b>: An optional `string` from: `"", "grayscale", "rgb"`. Defaults to `""`. + Per pixel image format. +* <b>quality</b>: An optional `int`. Defaults to `95`. + Quality of the compression from 0 to 100 (higher is better and slower). +* <b>progressive</b>: An optional `bool`. Defaults to `False`. + If True, create a JPEG that loads progressively (coarse to fine). +* <b>optimize_size</b>: An optional `bool`. Defaults to `False`. + If True, spend CPU/RAM to reduce size with no quality change. +* <b>chroma_downsampling</b>: An optional `bool`. Defaults to `True`. + See http://en.wikipedia.org/wiki/Chroma_subsampling. +* <b>density_unit</b>: An optional `string` from: `"in", "cm"`. Defaults to `"in"`. + Unit used to specify `x_density` and `y_density`: + pixels per inch (`'in'`) or centimeter (`'cm'`). +* <b>x_density</b>: An optional `int`. Defaults to `300`. + Horizontal pixels per density unit. +* <b>y_density</b>: An optional `int`. Defaults to `300`. + Vertical pixels per density unit. +* <b>xmp_metadata</b>: An optional `string`. Defaults to `""`. + If not empty, embed this XMP metadata in the image header. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. 0-D. JPEG-encoded image. + + + +- - - + +### tf.image.decode_png(contents, channels=None, name=None) <div class="md-anchor" id="decode_png">{#decode_png}</div> + +Decode a PNG-encoded image to a uint8 tensor. + +The attr `channels` indicates the desired number of color channels for the +decoded image. + +Accepted values are: + +* 0: Use the number of channels in the PNG-encoded image. +* 1: output a grayscale image. +* 3: output an RGB image. +* 4: output an RGBA image. + +If needed, the PNG-encoded image is transformed to match the requested number +of color channels. + +##### Args: + + +* <b>contents</b>: A `Tensor` of type `string`. 0-D. The PNG-encoded image. +* <b>channels</b>: An optional `int`. Defaults to `0`. + Number of color channels for the decoded image. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `uint8`. 3-D with shape `[height, width, channels]`. + + +- - - + +### tf.image.encode_png(image, compression=None, name=None) <div class="md-anchor" id="encode_png">{#encode_png}</div> + +PNG-encode an image. + +`image` is a 3-D uint8 Tensor of shape `[height, width, channels]` where +`channels` is: + +* 1: for grayscale. +* 3: for RGB. +* 4: for RGBA. + +The ZLIB compression level, `compression`, can be -1 for the PNG-encoder +default or a value from 0 to 9. 9 is the highest compression level, generating +the smallest output, but is slower. + +##### Args: + + +* <b>image</b>: A `Tensor` of type `uint8`. + 3-D with shape `[height, width, channels]`. +* <b>compression</b>: An optional `int`. Defaults to `-1`. Compression level. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. 0-D. PNG-encoded image. + + + +## Resizing. <div class="md-anchor" id="AUTOGENERATED-resizing.">{#AUTOGENERATED-resizing.}</div> + +The resizing Ops accept input images as tensors of several types. They always +output resized images as float32 tensors. + +The convenience function [resize_images()](#resize_images) supports both 4-D +and 3-D tensors as input and output. 4-D tensors are for batches of images, +3-D tensors for individual images. + +Other resizing Ops only support 3-D individual images as input: +[resize_area](#resize_area), [resize_bicubic](#resize_bicubic), +[resize_bilinear](#resize_bilinear), +[resize_nearest_neighbor](#resize_nearest_neighbor). + +Example: + +```python +# Decode a JPG image and resize it to 299 by 299. +image = tf.image.decode_jpeg(...) +resized_image = tf.image.resize_bilinear(image, [299, 299]) +``` + +<i>Maybe refer to the Queue examples that show how to add images to a Queue +after resizing them to a fixed size, and how to dequeue batches of resized +images from the Queue.</i> + +- - - + +### tf.image.resize_images(images, new_height, new_width, method=0) <div class="md-anchor" id="resize_images">{#resize_images}</div> + +Resize `images` to `new_width`, `new_height` using the specified `method`. + +Resized images will be distorted if their original aspect ratio is not +the same as `new_width`, `new_height`. To avoid distortions see +[resize_image_with_crop_or_pad](#resize_image_with_crop_or_pad). + +`method` can be one of: + +* <b>ResizeMethod.BILINEAR</b>: [Bilinear interpolation.] + (https://en.wikipedia.org/wiki/Bilinear_interpolation) +* <b>ResizeMethod.NEAREST_NEIGHBOR</b>: [Nearest neighbor interpolation.] + (https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation) +* <b>ResizeMethod.BICUBIC</b>: [Bicubic interpolation.] + (https://en.wikipedia.org/wiki/Bicubic_interpolation) +* <b>ResizeMethod.AREA</b>: Area interpolation. + +##### Args: + + +* <b>images</b>: 4-D Tensor of shape `[batch, height, width, channels]` or + 3-D Tensor of shape `[height, width, channels]`. +* <b>new_height</b>: integer. +* <b>new_width</b>: integer. +* <b>method</b>: ResizeMethod. Defaults to `ResizeMethod.BILINEAR`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `images` is incompatible with the + shape arguments to this function +* <b>ValueError</b>: if an unsupported resize method is specified. + +##### Returns: + + If `images` was 4-D, a 4-D float Tensor of shape + `[batch, new_height, new_width, channels]`. + If `images` was 3-D, a 3-D float Tensor of shape + `[new_height, new_width, channels]`. + + + +- - - + +### tf.image.resize_area(images, size, name=None) <div class="md-anchor" id="resize_area">{#resize_area}</div> + +Resize `images` to `size` using area interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + +- - - + +### tf.image.resize_bicubic(images, size, name=None) <div class="md-anchor" id="resize_bicubic">{#resize_bicubic}</div> + +Resize `images` to `size` using bicubic interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + +- - - + +### tf.image.resize_bilinear(images, size, name=None) <div class="md-anchor" id="resize_bilinear">{#resize_bilinear}</div> + +Resize `images` to `size` using bilinear interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + +- - - + +### tf.image.resize_nearest_neighbor(images, size, name=None) <div class="md-anchor" id="resize_nearest_neighbor">{#resize_nearest_neighbor}</div> + +Resize `images` to `size` using nearest neighbor interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `images`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + + + +## Cropping. <div class="md-anchor" id="AUTOGENERATED-cropping.">{#AUTOGENERATED-cropping.}</div> + +- - - + +### tf.image.resize_image_with_crop_or_pad(image, target_height, target_width) <div class="md-anchor" id="resize_image_with_crop_or_pad">{#resize_image_with_crop_or_pad}</div> + +Crops and/or pads an image to a target width and height. + +Resizes an image to a target width and height by either centrally +cropping the image or padding it evenly with zeros. + +If `width` or `height` is greater than the specified `target_width` or +`target_height` respectively, this op centrally crops along that dimension. +If `width` or `height` is smaller than the specified `target_width` or +`target_height` respectively, this op centrally pads with 0 along that +dimension. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape [height, width, channels] +* <b>target_height</b>: Target height. +* <b>target_width</b>: Target width. + +##### Raises: + + +* <b>ValueError</b>: if `target_height` or `target_width` are zero or negative. + +##### Returns: + + Cropped and/or padded image of shape + `[target_height, target_width, channels]` + + + +- - - + +### tf.image.pad_to_bounding_box(image, offset_height, offset_width, target_height, target_width) <div class="md-anchor" id="pad_to_bounding_box">{#pad_to_bounding_box}</div> + +Pad `image` with zeros to the specified `height` and `width`. + +Adds `offset_height` rows of zeros on top, `offset_width` columns of +zeros on the left, and then pads the image on the bottom and right +with zeros until it has dimensions `target_height`, `target_width`. + +This op does nothing if `offset_*` is zero and the image already has size +`target_height` by `target_width`. + +##### Args: + + +* <b>image</b>: 3-D tensor with shape `[height, width, channels]` +* <b>offset_height</b>: Number of rows of zeros to add on top. +* <b>offset_width</b>: Number of columns of zeros to add on the left. +* <b>target_height</b>: Height of output image. +* <b>target_width</b>: Width of output image. + +##### Returns: + + 3-D tensor of shape `[target_height, target_width, channels]` + +##### Raises: + + +* <b>ValueError</b>: If the shape of `image` is incompatible with the `offset_*` or + `target_*` arguments + + +- - - + +### tf.image.crop_to_bounding_box(image, offset_height, offset_width, target_height, target_width) <div class="md-anchor" id="crop_to_bounding_box">{#crop_to_bounding_box}</div> + +Crops an image to a specified bounding box. + +This op cuts a rectangular part out of `image`. The top-left corner of the +returned image is at `offset_height, offset_width` in `image`, and its +lower-right corner is at +`offset_height + target_height, offset_width + target_width'. + +##### Args: + + +* <b>image</b>: 3-D tensor with shape `[height, width, channels]` +* <b>offset_height</b>: Vertical coordinate of the top-left corner of the result in + the input. +* <b>offset_width</b>: Horizontal coordinate of the top-left corner of the result in + the input. +* <b>target_height</b>: Height of the result. +* <b>target_width</b>: Width of the result. + +##### Returns: + + 3-D tensor of image with shape `[target_height, target_width, channels]` + +##### Raises: + + +* <b>ValueError</b>: If the shape of `image` is incompatible with the `offset_*` or + `target_*` arguments + + +- - - + +### tf.image.random_crop(image, size, seed=None, name=None) <div class="md-anchor" id="random_crop">{#random_crop}</div> + +Randomly crops `image` to size `[target_height, target_width]`. + +The offset of the output within `image` is uniformly random. `image` always +fully contains the result. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]` +* <b>size</b>: 1-D tensor with two elements, specifying target `[height, width]` +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A cropped 3-D tensor of shape `[target_height, target_width, channels]`. + + +- - - + +### tf.image.extract_glimpse(input, size, offsets, centered=None, normalized=None, uniform_noise=None, name=None) <div class="md-anchor" id="extract_glimpse">{#extract_glimpse}</div> + +Extracts a glimpse from the input tensor. + +Returns a set of windows called glimpses extracted at location `offsets` +from the input tensor. If the windows only partially overlaps the inputs, the +non overlapping areas will be filled with random noise. + +The result is a 4-D tensor of shape `[batch_size, glimpse_height, +glimpse_width, channels]`. The channels and batch dimensions are the same as that +of the input tensor. The height and width of the output windows are +specified in the `size` parameter. + +The argument `normalized` and `centered` controls how the windows are built: +* If the coordinates are normalized but not centered, 0.0 and 1.0 + correspond to the minimum and maximum of each height and width dimension. +* If the coordinates are both normalized and centered, they range from -1.0 to + 1.0. The coordinates (-1.0, -1.0) correspond to the upper left corner, the + lower right corner is located at (1.0, 1.0) and the center is at (0, 0). +* If the coordinates are not normalized they are interpreted as numbers of pixels. + +##### Args: + + +* <b>input</b>: A `Tensor` of type `float32`. + A 4-D float tensor of shape `[batch_size, height, width, channels]`. +* <b>size</b>: A `Tensor` of type `int32`. + A 1-D tensor of 2 elements containing the size of the glimpses to extract. + The glimpse height must be specified first, following by the glimpse width. +* <b>offsets</b>: A `Tensor` of type `float32`. + A 2-D integer tensor of shape `[batch_size, 2]` containing the x, y + locations of the center of each window. +* <b>centered</b>: An optional `bool`. Defaults to `True`. + indicates if the offset coordinates are centered relative to + the image, in which case the (0, 0) offset is relative to the center of the + input images. If false, the (0,0) offset corresponds to the upper left corner + of the input images. +* <b>normalized</b>: An optional `bool`. Defaults to `True`. + indicates if the offset coordinates are normalized. +* <b>uniform_noise</b>: An optional `bool`. Defaults to `True`. + indicates if the noise should be generated using a + uniform distribution or a gaussian distribution. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + A tensor representing the glimpses `[batch_size, glimpse_height, + glimpse_width, channels]`. + + + +## Flipping and Transposing. <div class="md-anchor" id="AUTOGENERATED-flipping-and-transposing.">{#AUTOGENERATED-flipping-and-transposing.}</div> + +- - - + +### tf.image.flip_up_down(image) <div class="md-anchor" id="flip_up_down">{#flip_up_down}</div> + +Flip an image horizontally (upside down). + +Outputs the contents of `image` flipped along the first dimension, which is +`height`. + +See also `reverse()`. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + +- - - + +### tf.image.random_flip_up_down(image, seed=None) <div class="md-anchor" id="random_flip_up_down">{#random_flip_up_down}</div> + +Randomly flips an image vertically (upside down). + +With a 1 in 2 chance, outputs the contents of `image` flipped along the first +dimension, which is `height`. Otherwise output the image as-is. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + + +- - - + +### tf.image.flip_left_right(image) <div class="md-anchor" id="flip_left_right">{#flip_left_right}</div> + +Flip an image horizontally (left to right). + +Outputs the contents of `image` flipped along the second dimension, which is +`width`. + +See also `reverse()`. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + +- - - + +### tf.image.random_flip_left_right(image, seed=None) <div class="md-anchor" id="random_flip_left_right">{#random_flip_left_right}</div> + +Randomly flip an image horizontally (left to right). + +With a 1 in 2 chance, outputs the contents of `image` flipped along the +second dimension, which is `width`. Otherwise output the image as-is. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + + +- - - + +### tf.image.transpose_image(image) <div class="md-anchor" id="transpose_image">{#transpose_image}</div> + +Transpose an image by swapping the first and second dimension. + +See also `transpose()`. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]` + +##### Returns: + + A 3-D tensor of shape `[width, height, channels]` + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + + +## Image Adjustments. <div class="md-anchor" id="AUTOGENERATED-image-adjustments.">{#AUTOGENERATED-image-adjustments.}</div> + +TensorFlow provides functions to adjust images in various ways: brightness, +contrast, hue, and saturation. Each adjustment can be done with predefined +parameters or with random parameters picked from predefined intervals. Random +adjustments are often useful to expand a training set and reduce overfitting. + +- - - + +### tf.image.adjust_brightness(image, delta, min_value=None, max_value=None) <div class="md-anchor" id="adjust_brightness">{#adjust_brightness}</div> + +Adjust the brightness of RGB or Grayscale images. + +The value `delta` is added to all components of the tensor `image`. `image` +and `delta` are cast to `float` before adding, and the resulting values are +clamped to `[min_value, max_value]`. Finally, the result is cast back to +`images.dtype`. + +If `min_value` or `max_value` are not given, they are set to the minimum and +maximum allowed values for `image.dtype` respectively. + +##### Args: + + +* <b>image</b>: A tensor. +* <b>delta</b>: A scalar. Amount to add to the pixel values. +* <b>min_value</b>: Minimum value for output. +* <b>max_value</b>: Maximum value for output. + +##### Returns: + + A tensor of the same shape and type as `image`. + + +- - - + +### tf.image.random_brightness(image, max_delta, seed=None) <div class="md-anchor" id="random_brightness">{#random_brightness}</div> + +Adjust the brightness of images by a random factor. + +Equivalent to `adjust_brightness()` using a `delta` randomly picked in the +interval `[-max_delta, max_delta)`. + +Note that `delta` is picked as a float. Because for integer type images, +the brightness adjusted result is rounded before casting, integer images may +have modifications in the range `[-max_delta,max_delta]`. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]`. +* <b>max_delta</b>: float, must be non-negative. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + 3-D tensor of images of shape `[height, width, channels]` + +##### Raises: + + +* <b>ValueError</b>: if max_delta is negative. + + + +- - - + +### tf.image.adjust_contrast(images, contrast_factor, min_value=None, max_value=None) <div class="md-anchor" id="adjust_contrast">{#adjust_contrast}</div> + +Adjust contrast of RGB or grayscale images. + +`images` is a tensor of at least 3 dimensions. The last 3 dimensions are +interpreted as `[height, width, channels]`. The other dimensions only +represent a collection of images, such as `[batch, height, width, channels].` + +Contrast is adjusted independently for each channel of each image. + +For each channel, this Op first computes the mean of the image pixels in the +channel and then adjusts each component `x` of each pixel to +`(x - mean) * contrast_factor + mean`. + +The adjusted values are then clipped to fit in the `[min_value, max_value]` +interval. If `min_value` or `max_value` is not given, it is replaced with the +minimum and maximum values for the data type of `images` respectively. + +The contrast-adjusted image is always computed as `float`, and it is +cast back to its original type after clipping. + +##### Args: + + +* <b>images</b>: Images to adjust. At least 3-D. +* <b>contrast_factor</b>: A float multiplier for adjusting contrast. +* <b>min_value</b>: Minimum value for clipping the adjusted pixels. +* <b>max_value</b>: Maximum value for clipping the adjusted pixels. + +##### Returns: + + The constrast-adjusted image or images. + +##### Raises: + + +* <b>ValueError</b>: if the arguments are invalid. + + +- - - + +### tf.image.random_contrast(image, lower, upper, seed=None) <div class="md-anchor" id="random_contrast">{#random_contrast}</div> + +Adjust the contrase of an image by a random factor. + +Equivalent to `adjust_constrast()` but uses a `contrast_factor` randomly +picked in the interval `[lower, upper]`. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]`. +* <b>lower</b>: float. Lower bound for the random contrast factor. +* <b>upper</b>: float. Upper bound for the random contrast factor. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + 3-D tensor of shape `[height, width, channels]`. + +##### Raises: + + +* <b>ValueError</b>: if `upper <= lower` or if `lower < 0`. + + + +- - - + +### tf.image.per_image_whitening(image) <div class="md-anchor" id="per_image_whitening">{#per_image_whitening}</div> + +Linearly scales `image` to have zero mean and unit norm. + +This op computes `(x - mean) / adjusted_stddev`, where `mean` is the average +of all values in image, and +`adjusted_stddev = max(stddev, 1.0/srqt(image.NumElements()))`. + +`stddev` is the standard deviation of all values in `image`. It is capped +away from zero to protect against division by 0 when handling uniform images. + +Note that this implementation is limited: +* It only whitens based on the statistics of an individual image. +* It does not take into account the covariance structure. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]`. + +##### Returns: + + The whitened image with same shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of 'image' is incompatible with this function. + + diff --git a/tensorflow/g3doc/api_docs/python/index.md b/tensorflow/g3doc/api_docs/python/index.md new file mode 100644 index 0000000000..72c0a401ef --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/index.md @@ -0,0 +1,352 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# TensorFlow Python reference documentation + +* <b>[Building Graphs](framework.md)</b>: [class DType](framework.md#DType), + [class Dimension](framework.md#Dimension), + [class Graph](framework.md#Graph), + [class GraphKeys](framework.md#GraphKeys), + [NoGradient](framework.md#NoGradient), + [class Operation](framework.md#Operation), + [class RegisterGradient](framework.md#RegisterGradient), + [class RegisterShape](framework.md#RegisterShape), + [class Tensor](framework.md#Tensor), + [class TensorShape](framework.md#TensorShape), + [add_to_collection](framework.md#add_to_collection), + [as_dtype](framework.md#as_dtype), + [control_dependencies](framework.md#control_dependencies), + [convert_to_tensor](framework.md#convert_to_tensor), + [device](framework.md#device), + [get_collection](framework.md#get_collection), + [get_default_graph](framework.md#get_default_graph), + [get_seed](framework.md#get_seed), + [import_graph_def](framework.md#import_graph_def), + [name_scope](framework.md#name_scope), + [op_scope](framework.md#op_scope) + +* <b>[Constants, Sequences, and Random Values](constant_op.md)</b>: [constant](constant_op.md#constant), + [fill](constant_op.md#fill), + [linspace](constant_op.md#linspace), + [ones](constant_op.md#ones), + [ones_like](constant_op.md#ones_like), + [random_normal](constant_op.md#random_normal), + [random_shuffle](constant_op.md#random_shuffle), + [random_uniform](constant_op.md#random_uniform), + [range](constant_op.md#range), + [set_random_seed](constant_op.md#set_random_seed), + [truncated_normal](constant_op.md#truncated_normal), + [zeros](constant_op.md#zeros), + [zeros_like](constant_op.md#zeros_like) + +* <b>[Variables](state_ops.md)</b>: [class IndexedSlices](state_ops.md#IndexedSlices), + [class Saver](state_ops.md#Saver), + [class Variable](state_ops.md#Variable), + [all_variables](state_ops.md#all_variables), + [assert_variables_initialized](state_ops.md#assert_variables_initialized), + [assign](state_ops.md#assign), + [assign_add](state_ops.md#assign_add), + [assign_sub](state_ops.md#assign_sub), + [constant_initializer](state_ops.md#constant_initializer), + [count_up_to](state_ops.md#count_up_to), + [device](state_ops.md#device), + [get_checkpoint_state](state_ops.md#get_checkpoint_state), + [get_variable](state_ops.md#get_variable), + [get_variable_scope](state_ops.md#get_variable_scope), + [initialize_all_variables](state_ops.md#initialize_all_variables), + [initialize_variables](state_ops.md#initialize_variables), + [latest_checkpoint](state_ops.md#latest_checkpoint), + [random_normal_initializer](state_ops.md#random_normal_initializer), + [random_uniform_initializer](state_ops.md#random_uniform_initializer), + [scatter_add](state_ops.md#scatter_add), + [scatter_sub](state_ops.md#scatter_sub), + [scatter_update](state_ops.md#scatter_update), + [sparse_mask](state_ops.md#sparse_mask), + [trainable_variables](state_ops.md#trainable_variables), + [truncated_normal_initializer](state_ops.md#truncated_normal_initializer), + [uniform_unit_scaling_initializer](state_ops.md#uniform_unit_scaling_initializer), + [update_checkpoint_state](state_ops.md#update_checkpoint_state), + [variable_scope](state_ops.md#variable_scope), + [zeros_initializer](state_ops.md#zeros_initializer) + +* <b>[Tensor Transformations](array_ops.md)</b>: [cast](array_ops.md#cast), + [concat](array_ops.md#concat), + [dynamic_partition](array_ops.md#dynamic_partition), + [dynamic_stitch](array_ops.md#dynamic_stitch), + [expand_dims](array_ops.md#expand_dims), + [gather](array_ops.md#gather), + [pack](array_ops.md#pack), + [pad](array_ops.md#pad), + [rank](array_ops.md#rank), + [reshape](array_ops.md#reshape), + [reverse](array_ops.md#reverse), + [reverse_sequence](array_ops.md#reverse_sequence), + [shape](array_ops.md#shape), + [size](array_ops.md#size), + [slice](array_ops.md#slice), + [split](array_ops.md#split), + [squeeze](array_ops.md#squeeze), + [string_to_number](array_ops.md#string_to_number), + [tile](array_ops.md#tile), + [to_bfloat16](array_ops.md#to_bfloat16), + [to_double](array_ops.md#to_double), + [to_float](array_ops.md#to_float), + [to_int32](array_ops.md#to_int32), + [to_int64](array_ops.md#to_int64), + [transpose](array_ops.md#transpose), + [unpack](array_ops.md#unpack) + +* <b>[Math](math_ops.md)</b>: [abs](math_ops.md#abs), + [accumulate_n](math_ops.md#accumulate_n), + [add](math_ops.md#add), + [add_n](math_ops.md#add_n), + [argmax](math_ops.md#argmax), + [argmin](math_ops.md#argmin), + [batch_cholesky](math_ops.md#batch_cholesky), + [batch_matmul](math_ops.md#batch_matmul), + [batch_matrix_determinant](math_ops.md#batch_matrix_determinant), + [batch_matrix_inverse](math_ops.md#batch_matrix_inverse), + [ceil](math_ops.md#ceil), + [cholesky](math_ops.md#cholesky), + [complex](math_ops.md#complex), + [complex_abs](math_ops.md#complex_abs), + [conj](math_ops.md#conj), + [cos](math_ops.md#cos), + [diag](math_ops.md#diag), + [div](math_ops.md#div), + [edit_distance](math_ops.md#edit_distance), + [exp](math_ops.md#exp), + [floor](math_ops.md#floor), + [imag](math_ops.md#imag), + [inv](math_ops.md#inv), + [invert_permutation](math_ops.md#invert_permutation), + [listdiff](math_ops.md#listdiff), + [log](math_ops.md#log), + [matmul](math_ops.md#matmul), + [matrix_determinant](math_ops.md#matrix_determinant), + [matrix_inverse](math_ops.md#matrix_inverse), + [maximum](math_ops.md#maximum), + [minimum](math_ops.md#minimum), + [mod](math_ops.md#mod), + [mul](math_ops.md#mul), + [neg](math_ops.md#neg), + [pow](math_ops.md#pow), + [real](math_ops.md#real), + [reduce_all](math_ops.md#reduce_all), + [reduce_any](math_ops.md#reduce_any), + [reduce_max](math_ops.md#reduce_max), + [reduce_mean](math_ops.md#reduce_mean), + [reduce_min](math_ops.md#reduce_min), + [reduce_prod](math_ops.md#reduce_prod), + [reduce_sum](math_ops.md#reduce_sum), + [round](math_ops.md#round), + [rsqrt](math_ops.md#rsqrt), + [segment_max](math_ops.md#segment_max), + [segment_mean](math_ops.md#segment_mean), + [segment_min](math_ops.md#segment_min), + [segment_prod](math_ops.md#segment_prod), + [segment_sum](math_ops.md#segment_sum), + [sign](math_ops.md#sign), + [sin](math_ops.md#sin), + [sparse_segment_mean](math_ops.md#sparse_segment_mean), + [sparse_segment_sum](math_ops.md#sparse_segment_sum), + [sqrt](math_ops.md#sqrt), + [square](math_ops.md#square), + [sub](math_ops.md#sub), + [transpose](math_ops.md#transpose), + [unique](math_ops.md#unique), + [unsorted_segment_sum](math_ops.md#unsorted_segment_sum), + [where](math_ops.md#where) + +* <b>[Control Flow](control_flow_ops.md)</b>: [Assert](control_flow_ops.md#Assert), + [Print](control_flow_ops.md#Print), + [add_check_numerics_ops](control_flow_ops.md#add_check_numerics_ops), + [check_numerics](control_flow_ops.md#check_numerics), + [count_up_to](control_flow_ops.md#count_up_to), + [equal](control_flow_ops.md#equal), + [greater](control_flow_ops.md#greater), + [greater_equal](control_flow_ops.md#greater_equal), + [group](control_flow_ops.md#group), + [identity](control_flow_ops.md#identity), + [is_finite](control_flow_ops.md#is_finite), + [is_inf](control_flow_ops.md#is_inf), + [is_nan](control_flow_ops.md#is_nan), + [less](control_flow_ops.md#less), + [less_equal](control_flow_ops.md#less_equal), + [logical_and](control_flow_ops.md#logical_and), + [logical_not](control_flow_ops.md#logical_not), + [logical_or](control_flow_ops.md#logical_or), + [logical_xor](control_flow_ops.md#logical_xor), + [no_op](control_flow_ops.md#no_op), + [not_equal](control_flow_ops.md#not_equal), + [select](control_flow_ops.md#select), + [tuple](control_flow_ops.md#tuple), + [verify_tensor_all_finite](control_flow_ops.md#verify_tensor_all_finite), + [where](control_flow_ops.md#where) + +* <b>[Images](image.md)</b>: [adjust_brightness](image.md#adjust_brightness), + [adjust_contrast](image.md#adjust_contrast), + [crop_to_bounding_box](image.md#crop_to_bounding_box), + [decode_jpeg](image.md#decode_jpeg), + [decode_png](image.md#decode_png), + [encode_jpeg](image.md#encode_jpeg), + [encode_png](image.md#encode_png), + [extract_glimpse](image.md#extract_glimpse), + [flip_left_right](image.md#flip_left_right), + [flip_up_down](image.md#flip_up_down), + [pad_to_bounding_box](image.md#pad_to_bounding_box), + [per_image_whitening](image.md#per_image_whitening), + [random_brightness](image.md#random_brightness), + [random_contrast](image.md#random_contrast), + [random_crop](image.md#random_crop), + [random_flip_left_right](image.md#random_flip_left_right), + [random_flip_up_down](image.md#random_flip_up_down), + [resize_area](image.md#resize_area), + [resize_bicubic](image.md#resize_bicubic), + [resize_bilinear](image.md#resize_bilinear), + [resize_image_with_crop_or_pad](image.md#resize_image_with_crop_or_pad), + [resize_images](image.md#resize_images), + [resize_nearest_neighbor](image.md#resize_nearest_neighbor), + [transpose_image](image.md#transpose_image) + +* <b>[Sparse Tensors](sparse_ops.md)</b>: [class SparseTensor](sparse_ops.md#SparseTensor), + [class SparseTensorValue](sparse_ops.md#SparseTensorValue), + [shape](sparse_ops.md#shape), + [sparse_concat](sparse_ops.md#sparse_concat), + [sparse_fill_empty_rows](sparse_ops.md#sparse_fill_empty_rows), + [sparse_reorder](sparse_ops.md#sparse_reorder), + [sparse_retain](sparse_ops.md#sparse_retain), + [sparse_tensor_to_dense](sparse_ops.md#sparse_tensor_to_dense), + [sparse_to_dense](sparse_ops.md#sparse_to_dense), + [sparse_to_indicator](sparse_ops.md#sparse_to_indicator) + +* <b>[Inputs and Readers](io_ops.md)</b>: [class FIFOQueue](io_ops.md#FIFOQueue), + [class FixedLengthRecordReader](io_ops.md#FixedLengthRecordReader), + [class IdentityReader](io_ops.md#IdentityReader), + [class QueueBase](io_ops.md#QueueBase), + [class RandomShuffleQueue](io_ops.md#RandomShuffleQueue), + [class ReaderBase](io_ops.md#ReaderBase), + [class TFRecordReader](io_ops.md#TFRecordReader), + [class TextLineReader](io_ops.md#TextLineReader), + [class WholeFileReader](io_ops.md#WholeFileReader), + [batch](io_ops.md#batch), + [batch_join](io_ops.md#batch_join), + [decode_csv](io_ops.md#decode_csv), + [decode_raw](io_ops.md#decode_raw), + [limit_epochs](io_ops.md#limit_epochs), + [match_filenames_once](io_ops.md#match_filenames_once), + [matching_files](io_ops.md#matching_files), + [parse_example](io_ops.md#parse_example), + [parse_single_example](io_ops.md#parse_single_example), + [placeholder](io_ops.md#placeholder), + [range_input_producer](io_ops.md#range_input_producer), + [read_file](io_ops.md#read_file), + [shuffle_batch](io_ops.md#shuffle_batch), + [shuffle_batch_join](io_ops.md#shuffle_batch_join), + [size](io_ops.md#size), + [slice_input_producer](io_ops.md#slice_input_producer), + [string_input_producer](io_ops.md#string_input_producer) + +* <b>[Data IO (Python functions)](python_io.md)</b>: [class TFRecordWriter](python_io.md#TFRecordWriter), + [tf_record_iterator](python_io.md#tf_record_iterator) + +* <b>[Neural Network](nn.md)</b>: [avg_pool](nn.md#avg_pool), + [bias_add](nn.md#bias_add), + [compute_accidental_hits](nn.md#compute_accidental_hits), + [conv2d](nn.md#conv2d), + [depthwise_conv2d](nn.md#depthwise_conv2d), + [dropout](nn.md#dropout), + [embedding_lookup](nn.md#embedding_lookup), + [embedding_lookup_sparse](nn.md#embedding_lookup_sparse), + [fixed_unigram_candidate_sampler](nn.md#fixed_unigram_candidate_sampler), + [in_top_k](nn.md#in_top_k), + [l2_loss](nn.md#l2_loss), + [l2_normalize](nn.md#l2_normalize), + [learned_unigram_candidate_sampler](nn.md#learned_unigram_candidate_sampler), + [local_response_normalization](nn.md#local_response_normalization), + [log_uniform_candidate_sampler](nn.md#log_uniform_candidate_sampler), + [max_pool](nn.md#max_pool), + [max_pool_with_argmax](nn.md#max_pool_with_argmax), + [moments](nn.md#moments), + [nce_loss](nn.md#nce_loss), + [relu](nn.md#relu), + [relu6](nn.md#relu6), + [sampled_softmax_loss](nn.md#sampled_softmax_loss), + [separable_conv2d](nn.md#separable_conv2d), + [sigmoid](nn.md#sigmoid), + [sigmoid_cross_entropy_with_logits](nn.md#sigmoid_cross_entropy_with_logits), + [softmax](nn.md#softmax), + [softmax_cross_entropy_with_logits](nn.md#softmax_cross_entropy_with_logits), + [softplus](nn.md#softplus), + [tanh](nn.md#tanh), + [top_k](nn.md#top_k), + [uniform_candidate_sampler](nn.md#uniform_candidate_sampler) + +* <b>[Running Graphs](client.md)</b>: [class AbortedError](client.md#AbortedError), + [class AlreadyExistsError](client.md#AlreadyExistsError), + [class CancelledError](client.md#CancelledError), + [class DataLossError](client.md#DataLossError), + [class DeadlineExceededError](client.md#DeadlineExceededError), + [class FailedPreconditionError](client.md#FailedPreconditionError), + [class InternalError](client.md#InternalError), + [class InvalidArgumentError](client.md#InvalidArgumentError), + [class NotFoundError](client.md#NotFoundError), + [class OpError](client.md#OpError), + [class OutOfRangeError](client.md#OutOfRangeError), + [class PermissionDeniedError](client.md#PermissionDeniedError), + [class ResourceExhaustedError](client.md#ResourceExhaustedError), + [class Session](client.md#Session), + [class UnauthenticatedError](client.md#UnauthenticatedError), + [class UnavailableError](client.md#UnavailableError), + [class UnimplementedError](client.md#UnimplementedError), + [class UnknownError](client.md#UnknownError), + [get_default_session](client.md#get_default_session) + +* <b>[Training](train.md)</b>: [class AdagradOptimizer](train.md#AdagradOptimizer), + [class AdamOptimizer](train.md#AdamOptimizer), + [class AggregationMethod](train.md#AggregationMethod), + [class Coordinator](train.md#Coordinator), + [class ExponentialMovingAverage](train.md#ExponentialMovingAverage), + [class FtrlOptimizer](train.md#FtrlOptimizer), + [class GradientDescentOptimizer](train.md#GradientDescentOptimizer), + [class MomentumOptimizer](train.md#MomentumOptimizer), + [class Optimizer](train.md#Optimizer), + [class QueueRunner](train.md#QueueRunner), + [class RMSPropOptimizer](train.md#RMSPropOptimizer), + [class SummaryWriter](train.md#SummaryWriter), + [add_queue_runner](train.md#add_queue_runner), + [clip_by_average_norm](train.md#clip_by_average_norm), + [clip_by_global_norm](train.md#clip_by_global_norm), + [clip_by_norm](train.md#clip_by_norm), + [clip_by_value](train.md#clip_by_value), + [exponential_decay](train.md#exponential_decay), + [global_norm](train.md#global_norm), + [global_step](train.md#global_step), + [gradients](train.md#gradients), + [histogram_summary](train.md#histogram_summary), + [image_summary](train.md#image_summary), + [merge_all_summaries](train.md#merge_all_summaries), + [merge_summary](train.md#merge_summary), + [scalar_summary](train.md#scalar_summary), + [start_queue_runners](train.md#start_queue_runners), + [stop_gradient](train.md#stop_gradient), + [summary_iterator](train.md#summary_iterator), + [write_graph](train.md#write_graph), + [zero_fraction](train.md#zero_fraction) + +<div class="sections-order" style="display: none;"> +<!-- +<!-- framework.md --> +<!-- constant_op.md --> +<!-- state_ops.md --> +<!-- array_ops.md --> +<!-- math_ops.md --> +<!-- control_flow_ops.md --> +<!-- image.md --> +<!-- sparse_ops.md --> +<!-- io_ops.md --> +<!-- python_io.md --> +<!-- nn.md --> +<!-- client.md --> +<!-- train.md --> +--> +</div> diff --git a/tensorflow/g3doc/api_docs/python/io_ops.md b/tensorflow/g3doc/api_docs/python/io_ops.md new file mode 100644 index 0000000000..ab8c4aa146 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/io_ops.md @@ -0,0 +1,1956 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Inputs and Readers +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Placeholders](#AUTOGENERATED-placeholders) + * [tf.placeholder(dtype, shape=None, name=None)](#placeholder) +* [Readers](#AUTOGENERATED-readers) + * [class tf.ReaderBase](#ReaderBase) + * [class tf.TextLineReader](#TextLineReader) + * [class tf.WholeFileReader](#WholeFileReader) + * [class tf.IdentityReader](#IdentityReader) + * [class tf.TFRecordReader](#TFRecordReader) + * [class tf.FixedLengthRecordReader](#FixedLengthRecordReader) +* [Converting](#AUTOGENERATED-converting) + * [tf.decode_csv(records, record_defaults, field_delim=None, name=None)](#decode_csv) + * [tf.decode_raw(bytes, out_type, little_endian=None, name=None)](#decode_raw) + * [tf.parse_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseExample')](#parse_example) + * [tf.parse_single_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseSingleExample')](#parse_single_example) +* [Queues](#AUTOGENERATED-queues) + * [class tf.QueueBase](#QueueBase) + * [class tf.FIFOQueue](#FIFOQueue) + * [class tf.RandomShuffleQueue](#RandomShuffleQueue) +* [Dealing with the filesystem](#AUTOGENERATED-dealing-with-the-filesystem) + * [tf.matching_files(pattern, name=None)](#matching_files) + * [tf.read_file(filename, name=None)](#read_file) +* [Input pipeline](#AUTOGENERATED-input-pipeline) + * [Beginning of an input pipeline](#AUTOGENERATED-beginning-of-an-input-pipeline) + * [tf.train.match_filenames_once(pattern, name=None)](#match_filenames_once) + * [tf.train.limit_epochs(tensor, num_epochs=None, name=None)](#limit_epochs) + * [tf.train.range_input_producer(limit, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None)](#range_input_producer) + * [tf.train.slice_input_producer(tensor_list, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None)](#slice_input_producer) + * [tf.train.string_input_producer(string_tensor, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None)](#string_input_producer) + * [Batching at the end of an input pipeline](#AUTOGENERATED-batching-at-the-end-of-an-input-pipeline) + * [tf.train.batch(tensor_list, batch_size, num_threads=1, capacity=32, enqueue_many=False, shapes=None, name=None)](#batch) + * [tf.train.batch_join(tensor_list_list, batch_size, capacity=32, enqueue_many=False, shapes=None, name=None)](#batch_join) + * [tf.train.shuffle_batch(tensor_list, batch_size, capacity, min_after_dequeue, num_threads=1, seed=None, enqueue_many=False, shapes=None, name=None)](#shuffle_batch) + * [tf.train.shuffle_batch_join(tensor_list_list, batch_size, capacity, min_after_dequeue, seed=None, enqueue_many=False, shapes=None, name=None)](#shuffle_batch_join) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Placeholders <div class="md-anchor" id="AUTOGENERATED-placeholders">{#AUTOGENERATED-placeholders}</div> + +TensorFlow provides a placeholder operation that must be fed with data +on execution. For more info, see the section on [Feeding +data](../../how_tos/reading_data/index.md#feeding). + +- - - + +### tf.placeholder(dtype, shape=None, name=None) <div class="md-anchor" id="placeholder">{#placeholder}</div> + +Inserts a placeholder for a tensor that will be always fed. + +**Important**: This tensor will produce an error if evaluated. Its value must +be fed using the `feed_dict` optional argument to `Session.run()`, +`Tensor.eval()`, or `Operation.run()`. + +For example: + +```python +x = tf.placeholder(float, shape=(1024, 1024)) +y = tf.matmul(x, x) + +with tf.Session() as sess: + print sess.run(y) # ERROR: will fail because x was not fed. + + rand_array = np.random.rand(1024, 1024) + print sess.run(y, feed_dict={x: rand_array}) # Will succeed. +``` + +##### Args: + + +* <b>dtype</b>: The type of elements in the tensor to be fed. +* <b>shape</b>: The shape of the tensor to be fed (optional). If the shape is not + specified, you can feed a tensor of any shape. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` that may be used as a handle for feeding a value, but not + evaluated directly. + + + +## Readers <div class="md-anchor" id="AUTOGENERATED-readers">{#AUTOGENERATED-readers}</div> + +TensorFlow provides a set of Reader classes for reading data formats. +For more information on inputs and readers, see [Reading +data](../../how_tos/reading_data/index.md). + +- - - + +### class tf.ReaderBase <div class="md-anchor" id="ReaderBase">{#ReaderBase}</div> + +Base class for different Reader types, that produce a record every step. + +Conceptually, Readers convert string 'work units' into records (key, +value pairs). Typically the 'work units' are filenames and the +records are extracted from the contents of those files. We want a +single record produced per step, but a work unit can correspond to +many records. + +Therefore we introduce some decoupling using a queue. The queue +contains the work units and the Reader dequeues from the queue when +it is asked to produce a record (via Read()) but it has finished the +last work unit. +- - - + +#### tf.ReaderBase.__init__(reader_ref, supports_serialize=False) {#ReaderBase.__init__} + +Creates a new ReaderBase. + +##### Args: + + +* <b>reader_ref</b>: The operation that implements the reader. +* <b>supports_serialize</b>: True if the reader implementation can + serialize its state. + + +- - - + +#### tf.ReaderBase.num_records_produced(name=None) {#ReaderBase.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.ReaderBase.num_work_units_completed(name=None) {#ReaderBase.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.ReaderBase.read(queue, name=None) {#ReaderBase.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.ReaderBase.reader_ref {#ReaderBase.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.ReaderBase.reset(name=None) {#ReaderBase.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.ReaderBase.restore_state(state, name=None) {#ReaderBase.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.ReaderBase.serialize_state(name=None) {#ReaderBase.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.ReaderBase.supports_serialize {#ReaderBase.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.TextLineReader <div class="md-anchor" id="TextLineReader">{#TextLineReader}</div> + +A Reader that outputs the lines of a file delimited by newlines. + +Newlines are stripped from the output. +See ReaderBase for supported methods. +- - - + +#### tf.TextLineReader.__init__(skip_header_lines=None, name=None) {#TextLineReader.__init__} + +Create a TextLineReader. + +##### Args: + + +* <b>skip_header_lines</b>: An optional int. Defaults to 0. Number of lines + to skip from the beginning of every file. +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.TextLineReader.num_records_produced(name=None) {#TextLineReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TextLineReader.num_work_units_completed(name=None) {#TextLineReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TextLineReader.read(queue, name=None) {#TextLineReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.TextLineReader.reader_ref {#TextLineReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.TextLineReader.reset(name=None) {#TextLineReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TextLineReader.restore_state(state, name=None) {#TextLineReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TextLineReader.serialize_state(name=None) {#TextLineReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.TextLineReader.supports_serialize {#TextLineReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.WholeFileReader <div class="md-anchor" id="WholeFileReader">{#WholeFileReader}</div> + +A Reader that outputs the entire contents of a file as a value. + +To use, enqueue filenames in a Queue. The output of Read will +be a filename (key) and the contents of that file (value). + +See ReaderBase for supported methods. +- - - + +#### tf.WholeFileReader.__init__(name=None) {#WholeFileReader.__init__} + +Create a WholeFileReader. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.WholeFileReader.num_records_produced(name=None) {#WholeFileReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.WholeFileReader.num_work_units_completed(name=None) {#WholeFileReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.WholeFileReader.read(queue, name=None) {#WholeFileReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.WholeFileReader.reader_ref {#WholeFileReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.WholeFileReader.reset(name=None) {#WholeFileReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.WholeFileReader.restore_state(state, name=None) {#WholeFileReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.WholeFileReader.serialize_state(name=None) {#WholeFileReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.WholeFileReader.supports_serialize {#WholeFileReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.IdentityReader <div class="md-anchor" id="IdentityReader">{#IdentityReader}</div> + +A Reader that outputs the queued work as both the key and value. + +To use, enqueue strings in a Queue. Read will take the front +work string and output (work, work). + +See ReaderBase for supported methods. +- - - + +#### tf.IdentityReader.__init__(name=None) {#IdentityReader.__init__} + +Create a IdentityReader. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.IdentityReader.num_records_produced(name=None) {#IdentityReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.IdentityReader.num_work_units_completed(name=None) {#IdentityReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.IdentityReader.read(queue, name=None) {#IdentityReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.IdentityReader.reader_ref {#IdentityReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.IdentityReader.reset(name=None) {#IdentityReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.IdentityReader.restore_state(state, name=None) {#IdentityReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.IdentityReader.serialize_state(name=None) {#IdentityReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.IdentityReader.supports_serialize {#IdentityReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.TFRecordReader <div class="md-anchor" id="TFRecordReader">{#TFRecordReader}</div> + +A Reader that outputs the records from a TFRecords file. + +See ReaderBase for supported methods. +- - - + +#### tf.TFRecordReader.__init__(name=None) {#TFRecordReader.__init__} + +Create a TFRecordReader. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.TFRecordReader.num_records_produced(name=None) {#TFRecordReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TFRecordReader.num_work_units_completed(name=None) {#TFRecordReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TFRecordReader.read(queue, name=None) {#TFRecordReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.TFRecordReader.reader_ref {#TFRecordReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.TFRecordReader.reset(name=None) {#TFRecordReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TFRecordReader.restore_state(state, name=None) {#TFRecordReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TFRecordReader.serialize_state(name=None) {#TFRecordReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.TFRecordReader.supports_serialize {#TFRecordReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.FixedLengthRecordReader <div class="md-anchor" id="FixedLengthRecordReader">{#FixedLengthRecordReader}</div> + +A Reader that outputs fixed-length records from a file. + +See ReaderBase for supported methods. +- - - + +#### tf.FixedLengthRecordReader.__init__(record_bytes, header_bytes=None, footer_bytes=None, name=None) {#FixedLengthRecordReader.__init__} + +Create a FixedLengthRecordReader. + +##### Args: + + +* <b>record_bytes</b>: An int. +* <b>header_bytes</b>: An optional int. Defaults to 0. +* <b>footer_bytes</b>: An optional int. Defaults to 0. +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.FixedLengthRecordReader.num_records_produced(name=None) {#FixedLengthRecordReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.num_work_units_completed(name=None) {#FixedLengthRecordReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.read(queue, name=None) {#FixedLengthRecordReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.reader_ref {#FixedLengthRecordReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.FixedLengthRecordReader.reset(name=None) {#FixedLengthRecordReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.FixedLengthRecordReader.restore_state(state, name=None) {#FixedLengthRecordReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.FixedLengthRecordReader.serialize_state(name=None) {#FixedLengthRecordReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.supports_serialize {#FixedLengthRecordReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + + +## Converting <div class="md-anchor" id="AUTOGENERATED-converting">{#AUTOGENERATED-converting}</div> + +TensorFlow provides several operations that you can use to convert various data +formats into tensors. + +- - - + +### tf.decode_csv(records, record_defaults, field_delim=None, name=None) <div class="md-anchor" id="decode_csv">{#decode_csv}</div> + +Convert CSV records to tensors. Each column maps to one tensor. + +RFC 4180 format is expected for the CSV records. +(https://tools.ietf.org/html/rfc4180) +Note that we allow leading and trailing spaces with int or float field. + +##### Args: + + +* <b>records</b>: A `Tensor` of type `string`. + Each string is a record/row in the csv and all records should have + the same format. +* <b>record_defaults</b>: A list of `Tensor` objects with types from: `float32`, `int32`, `int64`, `string`. + One tensor per column of the input record, with either a + scalar default value for that column or empty if the column is required. +* <b>field_delim</b>: An optional `string`. Defaults to `","`. + delimiter to separate fields in a record. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A list of `Tensor` objects. Has the same type as `record_defaults`. + Each tensor will have the same shape as records. + + +- - - + +### tf.decode_raw(bytes, out_type, little_endian=None, name=None) <div class="md-anchor" id="decode_raw">{#decode_raw}</div> + +Reinterpret the bytes of a string as a vector of numbers. + +##### Args: + + +* <b>bytes</b>: A `Tensor` of type `string`. + All the elements must have the same length. +* <b>out_type</b>: A `tf.DType` from: `tf.float32, tf.float64, tf.int32, tf.uint8, tf.int16, tf.int8, tf.int64`. +* <b>little_endian</b>: An optional `bool`. Defaults to `True`. + Whether the input bytes are in little-endian order. + Ignored for out_types that are stored in a single byte like uint8. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `out_type`. + A Tensor with one more dimension than the input bytes. The + added dimension will have size equal to the length of the elements + of bytes divided by the number of bytes to represent out_type. + + +- - - + +### tf.parse_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseExample') <div class="md-anchor" id="parse_example">{#parse_example}</div> + +Parse Example protos. + +##### Args: + + +* <b>serialized</b>: string vector, a batch of binary serialized Example protos. +* <b>names</b>: A string vector, the names of the serialized protos. + "names" may contain, e.g., table key (descriptive) names for the + corresponding serialized protos. These are purely useful for debugging + purposes, and the presence of values here has no effect on the output. + "names" may be an empty vector, if no names are available. + If non-empty, this vector must be the same length as "serialized". +* <b>sparse_keys</b>: A string list of keys in the Examples' features. + These keys are associated with sparse values. +* <b>sparse_types</b>: A list of DTypes. + This list's length must match that of sparse_keys. Currently + parse_example supports tf.float32 (FloatList), tf.int64 (Int64List), + and tf.string (BytesList). +* <b>dense_keys</b>: A string list of keys in the Examples' features. + These keys are associated with dense values. +* <b>dense_types</b>: A list of DTypes. + This list's length must match that of dense_keys. Currently + parse_example supports tf.float32 (FloatList), tf.int64 (Int64List), + and tf.string (BytesList). +* <b>dense_defaults</b>: A dict of {key:Tensor} (some may be missing). + The keys of the dict must match the dense_keys of the feature. + If a key is not present in this dictionary, the corresponding dense + Feature is required in all elements of serialized. +* <b>dense_shapes</b>: A list of tuples. + Entries provide the shape of data in each dense Feature in features. + The length of dense_shapes must be the same as the length of dense_keys. + The number of elements in the Feature corresponding to dense_key[j] + must always have np.prod(dense_shapes[j]) entries. + If dense_shapes[j] == (D0, D1, ..., DN) then the the shape of output + Tensor dense_values[j] will be (|serialized|, D0, D1, ..., DN): + The dense outputs are just the inputs row-stacked by batch. +* <b>name</b>: (Optional) Name of Op in the graph. + +##### Returns: + + A dictionary mapping keys to Tensors and SparseTensors. + + The key dense_keys[j] is mapped to a tensor of type dense_types[j] and + of shape (serialized.size(),) + dense_shapes[j] (i.e., the dense outputs are + inputs, reshaped in row-major format and then row-stacked by batch). + + The key sparse_keys[j] is mapped to a SparseTensor of type sparse_types[j]. + The SparseTensor represents a ragged matrix. Its indices are [batch, index] + where "batch" is is the batch entry the value is from, and "index" is the + value's index in the list of values associated with that feature + and example. For example, if one expects a tf.float32 sparse feature "ft" + and three serialized examples are provided: + + serialized = [ + +* <b>features</b>: + { feature: [ key: { "ft" value: float_list: { value: [1.0, 2.0] } } ] }, +* <b>features</b>: + { feature: [] }, +* <b>features</b>: + { feature: [ key: { "ft" value: float_list: { value: [3.0] } } ] } + ] + + then the output will look like: + + {"ft": SparseTensor(indices=[[0, 0], [0, 1], [2, 0]], + values=[1.0, 2.0, 3.0], + shape=(3, 2)) } + +##### Raises: + + +* <b>ValueError</b>: If sparse and dense keys intersect, or input lengths do not + match up for sparse_* (similarly for dense_*). +* <b>TypeError</b>: If an input is malformed. + +Example input, format, and output: Just Sparse Inputs +================================================ + +Given two brain.Example input protos: + + +* <b>serialized</b>: // serialized versions of the protos below + [features: { + +* <b>feature</b>: { key: "kw" value: { bytes_list: { value: [ "knit", "big" ] } } } +* <b>feature</b>: { key: "gps" value: { float_list: { value: [] } } } + }, +* <b>features</b>: { +* <b>feature</b>: { key: "kw" value: { bytes_list: { value: [ "emmy" ] } } } +* <b>feature</b>: { key: "dank" value: { int64_list: { value: [ 42 ] } } } +* <b>feature</b>: { key: "gps" value: { } } + }] + +* <b>names</b>: ["input0", "input1"], +* <b>sparse_keys</b>: ["kw", "dank", "gps"] +* <b>sparse_types</b>: [DT_STRING, DT_INT64, DT_FLOAT] + +Then the expected output is a dictionary: +{ + "kw": SparseTensor( + indices=[[0, 0], [0, 1], [1, 0]], + values=["knit", "big", "emmy"] + shape=[2, 2]), + "dank": SparseTensor( + indices=[[1, 0]], + values=[42], + shape=[2, 1]), + "gps": SparseTensor( + indices=[], + values=[], + shape=[2, 0]), +} + + +Example input, format, and output: Dense Inputs (without defaults) +================================================================== + +Given two brain.Example input protos: + + +* <b>serialized</b>: // serialized versions of the protos below + [features: { + +* <b>feature</b>: { key: "age" value: { int64_list: { value: [ 0 ] } } } +* <b>feature</b>: { key: "gender" value: { bytes_list: { value: [ "f" ] } } } + }, +* <b>features</b>: { +* <b>feature</b>: { key: "age" value: { int64_list: { value: [] } } } +* <b>feature</b>: { key: "gender" value: { bytes_list: { value: [ "f" ] } } } + }] + +* <b>names</b>: ["input0", "input1"], +* <b>dense_keys</b>: np.array(["age", "gender"]) +* <b>dense_types</b>: [tf.int64, tf.string] +* <b>dense_defaults</b>: { + "age": -1 # defaults to -1 if missing + # "gender" has no specified default so it's required +} + +* <b>dense_shapes</b>: [(1,), (1,)] # age, gender, label, weight + +Then the expected output is a dictionary: +{ + "age": [[0], [-1]], + "gender": [["f"], ["f"]], +} + + +Example input, format, and output: Dense Inputs (with defaults) +=============================================================== + +Given two brain.Example input protos: + + +* <b>serialized</b>: // serialized versions of the protos below + [features: { + +* <b>feature</b>: { key: "weight" value: { float_list: { value: [ 1.0 ] } } } + }, +* <b>features</b>: { +* <b>feature</b>: { key: "label" value: { float_list: { value: [ -1.0, 0.0 ] } } } + }] + +* <b>names</b>: ["input0", "input1"], +* <b>dense_keys</b>: np.array(["label", "weight"]) +* <b>dense_defaults</b>: { + "label": [1.0, 2.0], # float (default: vector) + "weight": 5.0 # float (default: scalar, 5.0) +} + +* <b>dense_shapes</b>: [(2,), (1,)] # age, gender, label, weight + +Then the expected output is a dictionary: +{ + "label": [[1.0, 2.0], [-1.0, 0.0]], + "weight": [[1.0], [5.0]], +} + + +- - - + +### tf.parse_single_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseSingleExample') <div class="md-anchor" id="parse_single_example">{#parse_single_example}</div> + +Identical to parse_example but for scalar serialized and names. + +##### Args: + + +* <b>serialized</b>: A scalar string, a single serialized Example. + See parse_example documentation for more details. +* <b>names</b>: (Optional) A scalar string, the associated name. + See parse_example documentation for more details. +* <b>sparse_keys</b>: See parse_example documentation for more details. +* <b>sparse_types</b>: See parse_example documentation for more details. +* <b>dense_keys</b>: See parse_example documentation for more details. +* <b>dense_types</b>: See parse_example documentation for more details. +* <b>dense_defaults</b>: See parse_example documentation for more details. +* <b>dense_shapes</b>: See parse_example documentation for more details. +* <b>name</b>: Optional op name. + +##### Returns: + + A dictionary mapping keys to Tensors and SparseTensors. + + For dense tensors, the Tensor is identical to the output of parse_example, + except it is one less dimension (the first, batch, dimension is removed). + + For SparseTensors: + The first (batch) column of the indices matrix is removed + (it is now a column vector). + The values vector is unchanged. + The first (batch_size) entry of the shape vector is removed + (it is now a single element vector). + +##### Raises: + + +* <b>ValueError</b>: if "scalar" or "names" have known shapes, and are not scalars. + + + +## Queues <div class="md-anchor" id="AUTOGENERATED-queues">{#AUTOGENERATED-queues}</div> + +TensorFlow provides several implementations of 'Queues', which are +structures within the TensorFlow computation graph to stage pipelines +of tensors together. The following describe the basic Queue interface +and some implementations. To see an example use, see [Threading and +Queues](../../how_tos/threading_and_queues/index.md). + +- - - + +### class tf.QueueBase <div class="md-anchor" id="QueueBase">{#QueueBase}</div> + +Base class for queue implementations. + +A queue is a TensorFlow data structure that stores tensors across +multiple steps, and exposes operations that enqueue and dequeue +tensors. + +Each queue element is a tuple of one or more tensors, where each +tuple component has a static dtype, and may have a static shape. The +queue implementations support versions of enqueue and dequeue that +handle single elements, versions that support enqueuing and +dequeuing a batch of elements at once. + +See [`tf.FIFOQueue`](#FIFOQueue) and +[`tf.RandomShuffleQueue`](#RandomShuffleQueue) for concrete +implementations of this class, and instructions on how to create +them. + +- - - + +#### tf.QueueBase.enqueue(vals, name=None) {#QueueBase.enqueue} + +Enqueues one element to this queue. + +If the queue is full when this operation executes, it will block +until the element has been enqueued. + +##### Args: + + +* <b>vals</b>: The tuple of `Tensor` objects to be enqueued. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The operation that enqueues a new tuple of tensors to the queue. + + +- - - + +#### tf.QueueBase.enqueue_many(vals, name=None) {#QueueBase.enqueue_many} + +Enqueues zero or elements to this queue. + +This operation slices each component tensor along the 0th dimension to +make multiple queue elements. All of the tensors in `vals` must have the +same size in the 0th dimension. + +If the queue is full when this operation executes, it will block +until all of the elements have been enqueued. + +##### Args: + + +* <b>vals</b>: The tensor or tuple of tensors from which the queue elements + are taken. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The operation that enqueues a batch of tuples of tensors to the queue. + + + +- - - + +#### tf.QueueBase.dequeue(name=None) {#QueueBase.dequeue} + +Dequeues one element from this queue. + +If the queue is empty when this operation executes, it will block +until there is an element to dequeue. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The tuple of tensors that was dequeued. + + +- - - + +#### tf.QueueBase.dequeue_many(n, name=None) {#QueueBase.dequeue_many} + +Dequeues and concatenates `n` elements from this queue. + +This operation concatenates queue-element component tensors along +the 0th dimension to make a single component tensor. All of the +components in the dequeued tuple will have size `n` in the 0th dimension. + +If the queue contains fewer than `n` elements when this operation +executes, it will block until `n` elements have been dequeued. + +##### Args: + + +* <b>n</b>: A scalar `Tensor` containing the number of elements to dequeue. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The tuple of concatenated tensors that was dequeued. + + + +- - - + +#### tf.QueueBase.size(name=None) {#QueueBase.size} + +Compute the number of elements in this queue. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar tensor containing the number of elements in this queue. + + + +- - - + +#### tf.QueueBase.close(cancel_pending_enqueues=False, name=None) {#QueueBase.close} + +Closes this queue. + +This operation signals that no more elements will be enqueued in +the given queue. Subsequent `enqueue` and `enqueue_many` +operations will fail. Subsequent `dequeue` and `dequeue_many` +operations will continue to succeed if sufficient elements remain +in the queue. Subsequent `dequeue` and `dequeue_many` operations +that would block will fail immediately. + +If `cancel_pending_enqueues` is `True`, all pending requests will also +be cancelled. + +##### Args: + + +* <b>cancel_pending_enqueues</b>: (Optional.) A boolean, defaulting to + `False` (described above). +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The operation that closes the queue. + + + +#### Other Methods +- - - + +#### tf.QueueBase.__init__(dtypes, shapes, queue_ref) {#QueueBase.__init__} + +Constructs a queue object from a queue reference. + +##### Args: + + +* <b>dtypes</b>: A list of types. The length of dtypes must equal the number + of tensors in each element. +* <b>shapes</b>: Constraints on the shapes of tensors in an element: + A list of shape tuples or None. This list is the same length + as dtypes. If the shape of any tensors in the element are constrained, + all must be; shapes can be None if the shapes should not be constrained. +* <b>queue_ref</b>: The queue reference, i.e. the output of the queue op. + + +- - - + +#### tf.QueueBase.dtypes {#QueueBase.dtypes} + +The list of dtypes for each component of a queue element. + +- - - + +#### tf.QueueBase.name {#QueueBase.name} + +The name of the underlying queue. + +- - - + +#### tf.QueueBase.queue_ref {#QueueBase.queue_ref} + +The underlying queue reference. + + +- - - + +### class tf.FIFOQueue <div class="md-anchor" id="FIFOQueue">{#FIFOQueue}</div> + +A queue implementation that dequeues elements in first-in-first out order. + +See [`tf.QueueBase`](#QueueBase) for a description of the methods on +this class. + +- - - + +#### tf.FIFOQueue.__init__(capacity, dtypes, shapes=None, shared_name=None, name='fifo_queue') {#FIFOQueue.__init__} + +Creates a queue that dequeues elements in a first-in first-out order. + +A `FIFOQueue` has bounded capacity; supports multiple concurrent +producers and consumers; and provides exactly-once delivery. + +A `FIFOQueue` holds a list of up to `capacity` elements. Each +element is a fixed-length tuple of tensors whose dtypes are +described by `dtypes`, and whose shapes are optionally described +by the `shapes` argument. + +If the `shapes` argument is specified, each component of a queue +element must have the respective fixed shape. If it is +unspecified, different queue elements may have different shapes, +but the use of `dequeue_many` is disallowed. + +##### Args: + + +* <b>capacity</b>: An integer. The upper bound on the number of elements + that may be stored in this queue. +* <b>dtypes</b>: A list of `DType` objects. The length of `dtypes` must equal + the number of tensors in each queue element. +* <b>shapes</b>: (Optional.) A list of fully-defined `TensorShape` objects, + with the same length as `dtypes` or `None`. +* <b>shared_name</b>: (Optional.) If non-empty, this queue will be shared under + the given name across multiple sessions. +* <b>name</b>: Optional name for the queue operation. + + + +- - - + +### class tf.RandomShuffleQueue <div class="md-anchor" id="RandomShuffleQueue">{#RandomShuffleQueue}</div> + +A queue implementation that dequeues elements in a random order. + +See [`tf.QueueBase`](#QueueBase) for a description of the methods on +this class. + +- - - + +#### tf.RandomShuffleQueue.__init__(capacity, min_after_dequeue, dtypes, shapes=None, seed=None, shared_name=None, name='random_shuffle_queue') {#RandomShuffleQueue.__init__} + +Create a queue that dequeues elements in a random order. + +A `RandomShuffleQueue` has bounded capacity; supports multiple +concurrent producers and consumers; and provides exactly-once +delivery. + +A `RandomShuffleQueue` holds a list of up to `capacity` +elements. Each element is a fixed-length tuple of tensors whose +dtypes are described by `dtypes`, and whose shapes are optionally +described by the `shapes` argument. + +If the `shapes` argument is specified, each component of a queue +element must have the respective fixed shape. If it is +unspecified, different queue elements may have different shapes, +but the use of `dequeue_many` is disallowed. + +The `min_after_dequeue` argument allows the caller to specify a +minimum number of elements that will remain in the queue after a +`dequeue` or `dequeue_many` operation completes, to ensure a +minimum level of mixing of elements. This invariant is maintained +by blocking those operations until sufficient elements have been +enqueued. The `min_after_dequeue` argument is ignored after the +queue has been closed. + +##### Args: + + +* <b>capacity</b>: An integer. The upper bound on the number of elements + that may be stored in this queue. +* <b>min_after_dequeue</b>: An integer (described above). +* <b>dtypes</b>: A list of `DType` objects. The length of `dtypes` must equal + the number of tensors in each queue element. +* <b>shapes</b>: (Optional.) A list of fully-defined `TensorShape` objects, + with the same length as `dtypes` or `None`. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>shared_name</b>: (Optional.) If non-empty, this queue will be shared under + the given name across multiple sessions. +* <b>name</b>: Optional name for the queue operation. + + + + +## Dealing with the filesystem <div class="md-anchor" id="AUTOGENERATED-dealing-with-the-filesystem">{#AUTOGENERATED-dealing-with-the-filesystem}</div> + +- - - + +### tf.matching_files(pattern, name=None) <div class="md-anchor" id="matching_files">{#matching_files}</div> + +Returns the set of files matching a pattern. + +Note that this routine only supports wildcard characters in the +basename portion of the pattern, not in the directory portion. + +##### Args: + + +* <b>pattern</b>: A `Tensor` of type `string`. A (scalar) shell wildcard pattern. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. A vector of matching filenames. + + +- - - + +### tf.read_file(filename, name=None) <div class="md-anchor" id="read_file">{#read_file}</div> + +Reads and outputs the entire contents of the input filename. + +##### Args: + + +* <b>filename</b>: A `Tensor` of type `string`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. + + + +## Input pipeline <div class="md-anchor" id="AUTOGENERATED-input-pipeline">{#AUTOGENERATED-input-pipeline}</div> + +TensorFlow functions for setting up an input-prefetching pipeline. +Please see the [reading data how-to](../../how_tos/reading_data.md) +for context. + +### Beginning of an input pipeline <div class="md-anchor" id="AUTOGENERATED-beginning-of-an-input-pipeline">{#AUTOGENERATED-beginning-of-an-input-pipeline}</div> + +The "producer" functions add a queue to the graph and a corresponding +`QueueRunner` for running the subgraph that fills that queue. + +- - - + +### tf.train.match_filenames_once(pattern, name=None) <div class="md-anchor" id="match_filenames_once">{#match_filenames_once}</div> + +Save the list of files matching pattern, so it is only computed once. + +##### Args: + + +* <b>pattern</b>: A file pattern (glob). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A variable that is initialized to the list of files matching pattern. + + +- - - + +### tf.train.limit_epochs(tensor, num_epochs=None, name=None) <div class="md-anchor" id="limit_epochs">{#limit_epochs}</div> + +Returns tensor num_epochs times and then raises an OutOfRange error. + +##### Args: + + +* <b>tensor</b>: Any Tensor. +* <b>num_epochs</b>: An integer (optional). If specified, limits the number + of steps the output tensor may be evaluated. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + tensor or OutOfRange. + + +- - - + +### tf.train.range_input_producer(limit, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None) <div class="md-anchor" id="range_input_producer">{#range_input_producer}</div> + +Produces the integers from 0 to limit-1 in a queue. + +##### Args: + + +* <b>limit</b>: An int32 scalar tensor. +* <b>num_epochs</b>: An integer (optional). If specified, `range_input_producer` + produces each integer `num_epochs` times before generating an + OutOfRange error. If not specified, `range_input_producer` can cycle + through the integers an unlimited number of times. +* <b>shuffle</b>: Boolean. If true, the integers are randomly shuffled within each + epoch. +* <b>seed</b>: An integer (optional). Seed used if shuffle == True. +* <b>capacity</b>: An integer. Sets the queue capacity. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A Queue with the output integers. A QueueRunner for the Queue + is added to the current Graph's QUEUE_RUNNER collection. + + +- - - + +### tf.train.slice_input_producer(tensor_list, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None) <div class="md-anchor" id="slice_input_producer">{#slice_input_producer}</div> + +Produces a slice of each Tensor in tensor_list. + +Implemented using a Queue -- a QueueRunner for the Queue +is added to the current Graph's QUEUE_RUNNER collection. + +##### Args: + + +* <b>tensor_list</b>: A list of Tensors. Every Tensor in tensor_list must + have the same size in the first dimension. +* <b>num_epochs</b>: An integer (optional). If specified, `slice_input_producer` + produces each slice `num_epochs` times before generating + an OutOfRange error. If not specified, `slice_input_producer` can cycle + through the slices an unlimited number of times. +* <b>seed</b>: An integer (optional). Seed used if shuffle == True. +* <b>capacity</b>: An integer. Sets the queue capacity. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors, one for each element of tensor_list. If the tensor + in tensor_list has shape [N, a, b, .., z], then the corresponding output + tensor will have shape [a, b, ..., z]. + + +- - - + +### tf.train.string_input_producer(string_tensor, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None) <div class="md-anchor" id="string_input_producer">{#string_input_producer}</div> + +Output strings (e.g. filenames) to a queue for an input pipeline. + +##### Args: + + +* <b>string_tensor</b>: A 1-D string tensor with the strings to produce. +* <b>num_epochs</b>: An integer (optional). If specified, `string_input_producer` + produces each string from `string_tensor` `num_epochs` times before + generating an OutOfRange error. If not specified, `string_input_producer` + can cycle through the strings in `string_tensor` an unlimited number of + times. +* <b>shuffle</b>: Boolean. If true, the strings are randomly shuffled within each + epoch. +* <b>seed</b>: An integer (optional). Seed used if shuffle == True. +* <b>capacity</b>: An integer. Sets the queue capacity. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A queue with the output strings. A QueueRunner for the Queue + is added to the current Graph's QUEUE_RUNNER collection. + + + +### Batching at the end of an input pipeline <div class="md-anchor" id="AUTOGENERATED-batching-at-the-end-of-an-input-pipeline">{#AUTOGENERATED-batching-at-the-end-of-an-input-pipeline}</div> + +These functions add a queue to the graph to assemble a batch of examples, with +possible shuffling. They also add a `QueueRunner` for running the subgraph +that fills that queue. + +Use [batch](#batch) or [batch_join](#batch_join) for batching examples that have +already been well shuffled. Use [shuffle_batch](#shuffle_batch) or +[shuffle_batch_join](#shuffle_batch_join) for examples that +would benefit from additional shuffling. + +Use [batch](#batch) or [shuffle_batch](#shuffle_batch) if you want a +single thread producing examples to batch, or if you have a +single subgraph producing examples but you want to run it in N threads +(where you increase N until it can keep the queue full). Use +[batch_join](#batch_join) or [shuffle_batch_join](#shuffle_batch_join) +if you have N different subgraphs producing examples to batch and you +want them run by N threads. + +- - - + +### tf.train.batch(tensor_list, batch_size, num_threads=1, capacity=32, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="batch">{#batch}</div> + +Run tensor_list to fill a queue to create batches. + +Implemented using a queue -- a QueueRunner for the queue +is added to the current Graph's QUEUE_RUNNER collection. + +##### Args: + + +* <b>tensor_list</b>: The list of tensors to enqueue. +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>num_threads</b>: The number of threads enqueuing tensor_list. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>enqueue_many</b>: If False, tensor_list is assumed to represent a + single example. If True, tensor_list is assumed to represent + a batch of examples, where the first dimension is indexed by + example, and all members of tensor_list should have the same + size in the first dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list (leaving off the first dimension + if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as tensor_list. + If enqueue_many is false, then an input tensor with shape + `[x, y, z]` will be output as a tensor with shape + `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + +- - - + +### tf.train.batch_join(tensor_list_list, batch_size, capacity=32, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="batch_join">{#batch_join}</div> + +Run a list of tensors to fill a queue to create batches of examples. + +This version enqueues a different list of tensors in different threads. +Implemented using a queue -- a QueueRunner for the queue +is added to the current Graph's QUEUE_RUNNER collection. + +##### Args: + + +* <b>tensor_list_list</b>: A list of tuples of tensors to enqueue. + len(tensor_list_list) threads will be started, with the i-th + thread enqueuing the tensors from tensor_list[i]. + tensor_list[i1][j] must match tensor_list[i2][j] in type and + shape (except in the first dimension if enqueue_many is true). +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>enqueue_many</b>: If False, each tensor_list_list[i] is assumed to + represent a single example. If True, tensor_list_list[i] is + assumed to represent a batch of examples, where the first + dimension is indexed by example, and all members of + tensor_list_list[i] should have the same size in the first + dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list_list[i] (which must match, after + leaving off the first dimension if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as + tensor_list_list[i]. If enqueue_many is false, then an input + tensor with shape `[x, y, z]` will be output as a tensor with + shape `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + +- - - + +### tf.train.shuffle_batch(tensor_list, batch_size, capacity, min_after_dequeue, num_threads=1, seed=None, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="shuffle_batch">{#shuffle_batch}</div> + +Create batches by randomly shuffling tensors. + +This adds: + +* a shuffling queue into which tensors from tensor_list are enqueued. +* a dequeue many operation to create batches from the queue, +* and a QueueRunner is added to the current Graph's QUEUE_RUNNER collection, + to enqueue the tensors from tensor_list. + +##### Args: + + +* <b>tensor_list</b>: The list of tensors to enqueue. +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>min_after_dequeue</b>: Minimum number elements in the queue after a + dequeue, used to ensure a level of mixing of elements. +* <b>num_threads</b>: The number of threads enqueuing tensor_list. +* <b>seed</b>: Seed for the random shuffling within the queue. +* <b>enqueue_many</b>: If False, tensor_list is assumed to represent a + single example. If True, tensor_list is assumed to represent + a batch of examples, where the first dimension is indexed by + example, and all members of tensor_list should have the same + size in the first dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list (leaving off the first dimension + if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as tensor_list. + If enqueue_many is false, then an input tensor with shape + `[x, y, z]` will be output as a tensor with shape + `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + +- - - + +### tf.train.shuffle_batch_join(tensor_list_list, batch_size, capacity, min_after_dequeue, seed=None, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="shuffle_batch_join">{#shuffle_batch_join}</div> + +Create batches by randomly shuffling tensors. + +This version enqueues a different list of tensors in different threads. +It adds: + +* a shuffling queue into which tensors from tensor_list_list are enqueued. +* a dequeue many operation to create batches from the queue, +* and a QueueRunner is added to the current Graph's QUEUE_RUNNER collection, + to enqueue the tensors from tensor_list_list. + +##### Args: + + +* <b>tensor_list_list</b>: A list of tuples of tensors to enqueue. + len(tensor_list_list) threads will be started, with the i-th + thread enqueuing the tensors from tensor_list[i]. + tensor_list[i1][j] must match tensor_list[i2][j] in type and + shape (except in the first dimension if enqueue_many is true). +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>min_after_dequeue</b>: Minimum number elements in the queue after a + dequeue, used to ensure a level of mixing of elements. +* <b>seed</b>: Seed for the random shuffling within the queue. +* <b>enqueue_many</b>: If False, each tensor_list_list[i] is assumed to + represent a single example. If True, tensor_list_list[i] is + assumed to represent a batch of examples, where the first + dimension is indexed by example, and all members of + tensor_list_list[i] should have the same size in the first + dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list_list[i] (which must match, after + leaving off the first dimension if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as + tensor_list_list[i]. If enqueue_many is false, then an input + tensor with shape `[x, y, z]` will be output as a tensor with + shape `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + diff --git a/tensorflow/g3doc/api_docs/python/math_ops.md b/tensorflow/g3doc/api_docs/python/math_ops.md new file mode 100644 index 0000000000..fb93c38311 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/math_ops.md @@ -0,0 +1,1883 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Math +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Arithmetic Operators](#AUTOGENERATED-arithmetic-operators) + * [tf.add(x, y, name=None)](#add) + * [tf.sub(x, y, name=None)](#sub) + * [tf.mul(x, y, name=None)](#mul) + * [tf.div(x, y, name=None)](#div) + * [tf.mod(x, y, name=None)](#mod) +* [Basic Math Functions](#AUTOGENERATED-basic-math-functions) + * [tf.add_n(inputs, name=None)](#add_n) + * [tf.abs(x, name=None)](#abs) + * [tf.neg(x, name=None)](#neg) + * [tf.sign(x, name=None)](#sign) + * [tf.inv(x, name=None)](#inv) + * [tf.square(x, name=None)](#square) + * [tf.round(x, name=None)](#round) + * [tf.sqrt(x, name=None)](#sqrt) + * [tf.rsqrt(x, name=None)](#rsqrt) + * [tf.pow(x, y, name=None)](#pow) + * [tf.exp(x, name=None)](#exp) + * [tf.log(x, name=None)](#log) + * [tf.ceil(x, name=None)](#ceil) + * [tf.floor(x, name=None)](#floor) + * [tf.maximum(x, y, name=None)](#maximum) + * [tf.minimum(x, y, name=None)](#minimum) + * [tf.cos(x, name=None)](#cos) + * [tf.sin(x, name=None)](#sin) +* [Matrix Math Functions](#AUTOGENERATED-matrix-math-functions) + * [tf.diag(diagonal, name=None)](#diag) + * [tf.transpose(a, perm=None, name='transpose')](#transpose) + * [tf.matmul(a, b, transpose_a=False, transpose_b=False, a_is_sparse=False, b_is_sparse=False, name=None)](#matmul) + * [tf.batch_matmul(x, y, adj_x=None, adj_y=None, name=None)](#batch_matmul) + * [tf.matrix_determinant(input, name=None)](#matrix_determinant) + * [tf.batch_matrix_determinant(input, name=None)](#batch_matrix_determinant) + * [tf.matrix_inverse(input, name=None)](#matrix_inverse) + * [tf.batch_matrix_inverse(input, name=None)](#batch_matrix_inverse) + * [tf.cholesky(input, name=None)](#cholesky) + * [tf.batch_cholesky(input, name=None)](#batch_cholesky) +* [Complex Number Functions](#AUTOGENERATED-complex-number-functions) + * [tf.complex(real, imag, name=None)](#complex) + * [tf.complex_abs(x, name=None)](#complex_abs) + * [tf.conj(in_, name=None)](#conj) + * [tf.imag(in_, name=None)](#imag) + * [tf.real(in_, name=None)](#real) +* [Reduction](#AUTOGENERATED-reduction) + * [tf.reduce_sum(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_sum) + * [tf.reduce_prod(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_prod) + * [tf.reduce_min(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_min) + * [tf.reduce_max(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_max) + * [tf.reduce_mean(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_mean) + * [tf.reduce_all(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_all) + * [tf.reduce_any(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_any) + * [tf.accumulate_n(inputs, shape=None, tensor_dtype=None, name=None)](#accumulate_n) +* [Segmentation](#AUTOGENERATED-segmentation) + * [tf.segment_sum(data, segment_ids, name=None)](#segment_sum) + * [tf.segment_prod(data, segment_ids, name=None)](#segment_prod) + * [tf.segment_min(data, segment_ids, name=None)](#segment_min) + * [tf.segment_max(data, segment_ids, name=None)](#segment_max) + * [tf.segment_mean(data, segment_ids, name=None)](#segment_mean) + * [tf.unsorted_segment_sum(data, segment_ids, num_segments, name=None)](#unsorted_segment_sum) + * [tf.sparse_segment_sum(data, indices, segment_ids, name=None)](#sparse_segment_sum) + * [tf.sparse_segment_mean(data, indices, segment_ids, name=None)](#sparse_segment_mean) +* [Sequence Comparison and Indexing](#AUTOGENERATED-sequence-comparison-and-indexing) + * [tf.argmin(input, dimension, name=None)](#argmin) + * [tf.argmax(input, dimension, name=None)](#argmax) + * [tf.listdiff(x, y, name=None)](#listdiff) + * [tf.where(input, name=None)](#where) + * [tf.unique(x, name=None)](#unique) + * [tf.edit_distance(hypothesis, truth, normalize=True, name='edit_distance')](#edit_distance) + * [tf.invert_permutation(x, name=None)](#invert_permutation) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Arithmetic Operators <div class="md-anchor" id="AUTOGENERATED-arithmetic-operators">{#AUTOGENERATED-arithmetic-operators}</div> + +TensorFlow provides several operations that you can use to add basic arithmetic +operators to your graph. + +- - - + +### tf.add(x, y, name=None) <div class="md-anchor" id="add">{#add}</div> + +Returns x + y element-wise. + +*NOTE*: Add supports broadcasting. AddN does not. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int8`, `int16`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.sub(x, y, name=None) <div class="md-anchor" id="sub">{#sub}</div> + +Returns x - y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.mul(x, y, name=None) <div class="md-anchor" id="mul">{#mul}</div> + +Returns x * y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int8`, `int16`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.div(x, y, name=None) <div class="md-anchor" id="div">{#div}</div> + +Returns x / y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.mod(x, y, name=None) <div class="md-anchor" id="mod">{#mod}</div> + +Returns element-wise remainder of division. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`, `float32`, `float64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + + +## Basic Math Functions <div class="md-anchor" id="AUTOGENERATED-basic-math-functions">{#AUTOGENERATED-basic-math-functions}</div> + +TensorFlow provides several operations that you can use to add basic +mathematical functions to your graph. + +- - - + +### tf.add_n(inputs, name=None) <div class="md-anchor" id="add_n">{#add_n}</div> + +Add all input tensors element wise. + +##### Args: + + +* <b>inputs</b>: A list of at least 1 `Tensor` objects of the same type in: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Must all be the same size and shape. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `inputs`. + + +- - - + +### tf.abs(x, name=None) <div class="md-anchor" id="abs">{#abs}</div> + +Computes the absolute value of a tensor. + +Given a tensor of real numbers `x`, this operation returns a tensor +containing the absolute value of each element in `x`. For example, if x is +an input element and y is an output element, this operation computes +\\(y = |x|\\). + +See [`tf.complex_abs()`](#tf_complex_abs) to compute the absolute value of a complex +number. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `float`, `double`, `int32`, or `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` the same size and type as `x` with absolute values. + + +- - - + +### tf.neg(x, name=None) <div class="md-anchor" id="neg">{#neg}</div> + +Computes numerical negative value element-wise. + +I.e., \\(y = -x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.sign(x, name=None) <div class="md-anchor" id="sign">{#sign}</div> + +Returns an element-wise indication of the sign of a number. + +y = sign(x) = -1 if x < 0; 0 if x == 0; 1 if x > 0. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.inv(x, name=None) <div class="md-anchor" id="inv">{#inv}</div> + +Computes the reciprocal of x element-wise. + +I.e., \\(y = 1 / x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.square(x, name=None) <div class="md-anchor" id="square">{#square}</div> + +Computes square of x element-wise. + +I.e., \\(y = x * x = x^2\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.round(x, name=None) <div class="md-anchor" id="round">{#round}</div> + +Rounds the values of a tensor to the nearest integer, element-wise. + +For example: + +```python +# 'a' is [0.9, 2.5, 2.3, -4.4] +tf.round(a) ==> [ 1.0, 3.0, 2.0, -4.0 ] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `float` or `double`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of same shape and type as `x`. + + +- - - + +### tf.sqrt(x, name=None) <div class="md-anchor" id="sqrt">{#sqrt}</div> + +Computes square root of x element-wise. + +I.e., \\(y = \sqrt{x} = x^{1/2}\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.rsqrt(x, name=None) <div class="md-anchor" id="rsqrt">{#rsqrt}</div> + +Computes reciprocal of square root of x element-wise. + +I.e., \\(y = 1 / \sqrt{x}\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.pow(x, y, name=None) <div class="md-anchor" id="pow">{#pow}</div> + +Computes the power of one value to another. + +Given a tensor `x` and a tensor `y`, this operation computes \\(x^y\\) for +corresponding elements in `x` and `y`. For example: + +``` +# tensor 'x' is [[2, 2]], [3, 3]] +# tensor 'y' is [[8, 16], [2, 3]] +tf.pow(x, y) ==> [[256, 65536], [9, 27]] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `float`, `double`, `int32`, `complex64`, or `int64`. +* <b>y</b>: A `Tensor` of type `float`, `double`, `int32`, `complex64`, or `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. + + +- - - + +### tf.exp(x, name=None) <div class="md-anchor" id="exp">{#exp}</div> + +Computes exponential of x element-wise. \\(y = e^x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.log(x, name=None) <div class="md-anchor" id="log">{#log}</div> + +Computes natural logrithm of x element-wise. + +I.e., \\(y = \log_e x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.ceil(x, name=None) <div class="md-anchor" id="ceil">{#ceil}</div> + +Returns element-wise smallest integer in not less than x. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.floor(x, name=None) <div class="md-anchor" id="floor">{#floor}</div> + +Returns element-wise largest integer not greater than x. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.maximum(x, y, name=None) <div class="md-anchor" id="maximum">{#maximum}</div> + +Returns the max of x and y (i.e. x > y ? x : y) element-wise, broadcasts. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.minimum(x, y, name=None) <div class="md-anchor" id="minimum">{#minimum}</div> + +Returns the min of x and y (i.e. x < y ? x : y) element-wise, broadcasts. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.cos(x, name=None) <div class="md-anchor" id="cos">{#cos}</div> + +Computes cos of x element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.sin(x, name=None) <div class="md-anchor" id="sin">{#sin}</div> + +Computes sin of x element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + + +## Matrix Math Functions <div class="md-anchor" id="AUTOGENERATED-matrix-math-functions">{#AUTOGENERATED-matrix-math-functions}</div> + +TensorFlow provides several operations that you can use to add basic +mathematical functions for matrices to your graph. + +- - - + +### tf.diag(diagonal, name=None) <div class="md-anchor" id="diag">{#diag}</div> + +Returns a diagonal tensor with a given diagonal values. + +Given a `diagonal`, this operation returns a tensor with the `diagonal` and +everything else padded with zeros. The diagonal is computed as follows: + +Assume `diagonal` has dimensions [D1,..., Dk], then the output is a tensor of +rank 2k with dimensions [D1,..., Dk, D1,..., Dk] where: + +`output[i1,..., ik, i1,..., ik] = diagonal[i1, ..., ik]` and 0 everywhere else. + +For example: + +```prettyprint +# 'diagonal' is [1, 2, 3, 4] +tf.diag(diagonal) ==> [[1, 0, 0, 0] + [0, 2, 0, 0] + [0, 0, 3, 0] + [0, 0, 0, 4]] +``` + +##### Args: + + +* <b>diagonal</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. + Rank k tensor where k is at most 3. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `diagonal`. + + +- - - + +### tf.transpose(a, perm=None, name='transpose') <div class="md-anchor" id="transpose">{#transpose}</div> + +Transposes `a`. Permutes the dimensions according to `perm`. + +The returned tensor's dimension i will correspond to the input dimension +`perm[i]`. If `perm` is not given, it is set to (n-1...0), where n is +the rank of the input tensor. Hence by default, this operation performs a +regular matrix transpose on 2-D input Tensors. + +For example: + +```python +# 'x' is [[1 2 3] +# [4 5 6]] +tf.transpose(x) ==> [[1 4] + [2 5] + [3 6]] + +# Equivalently +tf.transpose(x perm=[0, 1]) ==> [[1 4] + [2 5] + [3 6]] + +# 'perm' is more useful for n-dimensional tensors, for n > 2 +# 'x' is [[[1 2 3] +# [4 5 6]] +# [[7 8 9] +# [10 11 12]]] +# Take the transpose of the matrices in dimension-0 +tf.transpose(b, perm=[0, 2, 1]) ==> [[[1 4] + [2 5] + [3 6]] + + [[7 10] + [8 11] + [9 12]]] +``` + +##### Args: + + +* <b>a</b>: A `Tensor`. +* <b>perm</b>: A permutation of the dimensions of `a`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A transposed `Tensor`. + + + +- - - + +### tf.matmul(a, b, transpose_a=False, transpose_b=False, a_is_sparse=False, b_is_sparse=False, name=None) <div class="md-anchor" id="matmul">{#matmul}</div> + +Multiplies matrix `a` by matrix `b`, producing `a` * `b`. + +The inputs must be two-dimensional matrices, with matching inner dimensions, +possibly after transposition. + +Both matrices must be of the same type. The supported types are: +`float`, `double`, `int32`, `complex64`. + +Either matrix can be transposed on the fly by setting the corresponding flag +to `True`. This is `False` by default. + +If one or both of the matrices contain a lot of zeros, a more efficient +multiplication algorithm can be used by setting the corresponding +`a_is_sparse` or `b_is_sparse` flag to `True`. These are `False` by default. + +For example: + +```python +# 2-D tensor `a` +a = tf.constant([1, 2, 3, 4, 5, 6], shape=[2, 3]) => [[1. 2. 3.] + [4. 5. 6.]] +# 2-D tensor `b` +b = tf.constant([7, 8, 9, 10, 11, 12], shape=[3, 2]) => [[7. 8.] + [9. 10.] + [11. 12.]] +c = tf.matmul(a, b) => [[58 64] + [139 154]] +``` + +##### Args: + + +* <b>a</b>: `Tensor` of type `float`, `double`, `int32` or `complex64`. +* <b>b</b>: `Tensor` with same type as `a`. +* <b>transpose_a</b>: If `True`, `a` is transposed before multiplication. +* <b>transpose_b</b>: If `True`, `b` is transposed before multiplication. +* <b>a_is_sparse</b>: If `True`, `a` is treated as a sparse matrix. +* <b>b_is_sparse</b>: If `True`, `b` is treated as a sparse matrix. +* <b>name</b>: Name for the operation (optional). + +##### Returns: + + A `Tensor` of the same type as `a`. + + +- - - + +### tf.batch_matmul(x, y, adj_x=None, adj_y=None, name=None) <div class="md-anchor" id="batch_matmul">{#batch_matmul}</div> + +Multiplies slices of two tensors in batches. + +Multiplies all slices of `Tensor` `x` and `y` (each slice can be +viewed as an element of a batch), and arranges the individual results +in a single output tensor of the same batch size. Each of the +individual slices can optionally be adjointed (to adjoint a matrix +means to transpose and conjugate it) before multiplication by setting +the `adj_x` or `adj_y` flag to `True`, which are by default `False`. + +The input tensors `x` and `y` are 3-D or higher with shape `[..., r_x, c_x]` +and `[..., r_y, c_y]`. + +The output tensor is 3-D or higher with shape `[..., r_o, c_o]`, where: + + r_o = c_x if adj_x else r_x + c_o = r_y if adj_y else c_y + +It is computed as: + + out[..., :, :] = matrix(x[..., :, :]) * matrix(y[..., :, :]) + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`. + 3-D or higher with shape `[..., r_x, c_x]`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. + 3-D or higher with shape `[..., r_y, c_y]`. +* <b>adj_x</b>: An optional `bool`. Defaults to `False`. + If `True`, adjoint the slices of `x`. Defaults to `False`. +* <b>adj_y</b>: An optional `bool`. Defaults to `False`. + If `True`, adjoint the slices of `y`. Defaults to `False`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + 3-D or higher with shape `[..., r_o, c_o]` + + + +- - - + +### tf.matrix_determinant(input, name=None) <div class="md-anchor" id="matrix_determinant">{#matrix_determinant}</div> + +Calculates the determinant of a square matrix. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + A tensor of shape `[M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + A scalar, equal to the determinant of the input. + + +- - - + +### tf.batch_matrix_determinant(input, name=None) <div class="md-anchor" id="batch_matrix_determinant">{#batch_matrix_determinant}</div> + +Calculates the determinants for a batch of square matrices. + +The input is a tensor of shape `[..., M, M]` whose inner-most 2 dimensions +form square matrices. The output is a 1-D tensor containing the determinants +for all input submatrices `[..., :, :]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + Shape is `[..., M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[...]`. + + + +- - - + +### tf.matrix_inverse(input, name=None) <div class="md-anchor" id="matrix_inverse">{#matrix_inverse}</div> + +Calculates the inverse of a square invertible matrix. Checks for invertibility. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + Shape is `[M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + Shape is `[M, M]` containing the matrix inverse of the input. + + +- - - + +### tf.batch_matrix_inverse(input, name=None) <div class="md-anchor" id="batch_matrix_inverse">{#batch_matrix_inverse}</div> + +Calculates the inverse of square invertible matrices. Checks for invertibility. + +The input is a tensor of shape `[..., M, M]` whose inner-most 2 dimensions +form square matrices. The output is a tensor of the same shape as the input +containing the inverse for all input submatrices `[..., :, :]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + Shape is `[..., M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[..., M, M]`. + + + +- - - + +### tf.cholesky(input, name=None) <div class="md-anchor" id="cholesky">{#cholesky}</div> + +Calculates the Cholesky decomposition of a square matrix. + +The input has to be symmetric and positive definite. Only the lower-triangular +part of the input will be used for this operation. The upper-triangular part +will not be read. + +The result is the lower-triangular matrix of the Cholesky decomposition of the +input. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float64`, `float32`. + Shape is `[M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[M, M]`. + + +- - - + +### tf.batch_cholesky(input, name=None) <div class="md-anchor" id="batch_cholesky">{#batch_cholesky}</div> + +Calculates the Cholesky decomposition of a batch of square matrices. + +The input is a tensor of shape `[..., M, M]` whose inner-most 2 dimensions +form square matrices, with the same constraints as the single matrix Cholesky +decomposition above. The output is a tensor of the same shape as the input +containing the Cholesky decompositions for all input submatrices `[..., :, :]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float64`, `float32`. + Shape is `[..., M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[..., M, M]`. + + + +## Complex Number Functions <div class="md-anchor" id="AUTOGENERATED-complex-number-functions">{#AUTOGENERATED-complex-number-functions}</div> + +TensorFlow provides several operations that you can use to add complex number +functions to your graph. + +- - - + +### tf.complex(real, imag, name=None) <div class="md-anchor" id="complex">{#complex}</div> + +Converts two real numbers to a complex number. + +Given a tensor `real` representing the real part of a complex number, and a +tensor `imag` representing the imaginary part of a complex number, this +operation computes complex numbers elementwise of the form \\(a + bj\\), +where *a* represents the `real` part and *b* represents the `imag` part. + +The input tensors `real` and `imag` must be the same shape. + +For example: + +``` +# tensor 'real' is [2.25, 3.25] +# tensor `imag` is [4.75, 5.75] +tf.complex(real, imag) ==> [[2.25 + 4.74j], [3.25 + 5.75j]] +``` + +##### Args: + + +* <b>real</b>: A `Tensor` of type `float`. +* <b>imag</b>: A `Tensor` of type `float`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `complex64`. + + +- - - + +### tf.complex_abs(x, name=None) <div class="md-anchor" id="complex_abs">{#complex_abs}</div> + +Computes the complex absolute value of a tensor. + +Given a tensor `x` of complex numbers, this operation returns a tensor of type +`float` that is the absolute value of each element in `x`. All elements in `x` +must be complex numbers of the form \\(a + bj\\). The absolute value is +computed as \\( \sqrt{a^2 + b^2}\\). + +For example: + +``` +# tensor 'x' is [[-2.25 + 4.75j], [-3.25 + 5.75j]] +tf.complex_abs(x) ==> [5.25594902, 6.60492229] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + +- - - + +### tf.conj(in_, name=None) <div class="md-anchor" id="conj">{#conj}</div> + +Returns the complex conjugate of a complex number. + +Given a tensor `in` of complex numbers, this operation returns a tensor of +complex numbers that are the complex conjugate of each element in `in`. The +complex numbers in `in` must be of the form \\(a + bj\\), where *a* is the real +part and *b* is the imaginary part. + +The complex conjugate returned by this operation is of the form \\(a - bj\\). + +For example: + +``` +# tensor 'in' is [-2.25 + 4.75j, 3.25 + 5.75j] +tf.conj(in) ==> [-2.25 - 4.75j, 3.25 - 5.75j] +``` + +##### Args: + + +* <b>in_</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `complex64`. + + +- - - + +### tf.imag(in_, name=None) <div class="md-anchor" id="imag">{#imag}</div> + +Returns the imaginary part of a complex number. + +Given a tensor `in` of complex numbers, this operation returns a tensor of type +`float` that is the imaginary part of each element in `in`. All elements in `in` +must be complex numbers of the form \\(a + bj\\), where *a* is the real part +and *b* is the imaginary part returned by this operation. + +For example: + +``` +# tensor 'in' is [-2.25 + 4.75j, 3.25 + 5.75j] +tf.imag(in) ==> [4.75, 5.75] +``` + +##### Args: + + +* <b>in_</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + +- - - + +### tf.real(in_, name=None) <div class="md-anchor" id="real">{#real}</div> + +Returns the real part of a complex number. + +Given a tensor `in` of complex numbers, this operation returns a tensor of type +`float` that is the real part of each element in `in`. All elements in `in` +must be complex numbers of the form \\(a + bj\\), where *a* is the real part +returned by this operation and *b* is the imaginary part. + +For example: + +``` +# tensor 'in' is [-2.25 + 4.75j, 3.25 + 5.75j] +tf.real(in) ==> [-2.25, 3.25] +``` + +##### Args: + + +* <b>in_</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + + +## Reduction <div class="md-anchor" id="AUTOGENERATED-reduction">{#AUTOGENERATED-reduction}</div> + +TensorFlow provides several operations that you can use to perform +common math computations that reduce various dimensions of a tensor. + +- - - + +### tf.reduce_sum(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_sum">{#reduce_sum}</div> + +Computes the sum of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[1, 1, 1]] +# [1, 1, 1]] +tf.reduce_sum(x) ==> 6 +tf.reduce_sum(x, 0) ==> [2, 2, 2] +tf.reduce_sum(x, 1) ==> [3, 3] +tf.reduce_sum(x, 1, keep_dims=True) ==> [[3], [3]] +tf.reduce_sum(x, [0, 1]) ==> 6 +``` + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_prod(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_prod">{#reduce_prod}</div> + +Computes the product of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_min(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_min">{#reduce_min}</div> + +Computes the minimum of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_max(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_max">{#reduce_max}</div> + +Computes the maximum of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_mean(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_mean">{#reduce_mean}</div> + +Computes the mean of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[1., 1. ]] +# [2., 2.]] +tf.reduce_mean(x) ==> 1.5 +tf.reduce_mean(x, 0) ==> [1.5, 1.5] +tf.reduce_mean(x, 1) ==> [1., 2.] +``` + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_all(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_all">{#reduce_all}</div> + +Computes the "logical and" of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[True, True]] +# [False, False]] +tf.reduce_all(x) ==> False +tf.reduce_all(x, 0) ==> [False, False] +tf.reduce_all(x, 1) ==> [True, False] +``` + +##### Args: + + +* <b>input_tensor</b>: The boolean tensor to reduce. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_any(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_any">{#reduce_any}</div> + +Computes the "logical or" of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[True, True]] +# [False, False]] +tf.reduce_any(x) ==> True +tf.reduce_any(x, 0) ==> [True, True] +tf.reduce_any(x, 1) ==> [True, False] +``` + +##### Args: + + +* <b>input_tensor</b>: The boolean tensor to reduce. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + + +- - - + +### tf.accumulate_n(inputs, shape=None, tensor_dtype=None, name=None) <div class="md-anchor" id="accumulate_n">{#accumulate_n}</div> + +Returns the element-wise sum of a list of tensors. + +Optionally, pass `shape` and `tensor_dtype` for shape and type checking, +otherwise, these are inferred. + +For example: + +```python +# tensor 'a' is [[1, 2], [3, 4] +# tensor `b` is [[5, 0], [0, 6]] +tf.accumulate_n([a, b, a]) ==> [[7, 4], [6, 14]] + +# Explicitly pass shape and type +tf.accumulate_n([a, b, a], shape=[2, 2], tensor_dtype=tf.int32) + ==> [[7, 4], [6, 14]] +``` + +##### Args: + + +* <b>inputs</b>: A list of `Tensor` objects, each with same shape and type. +* <b>shape</b>: Shape of elements of `inputs`. +* <b>tensor_dtype</b>: The type of `inputs`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of same shape and type as the elements of `inputs`. + +##### Raises: + + +* <b>ValueError</b>: If `inputs` don't all have same shape and dtype or the shape + cannot be inferred. + + + +## Segmentation <div class="md-anchor" id="AUTOGENERATED-segmentation">{#AUTOGENERATED-segmentation}</div> + +TensorFlow provides several operations that you can use to perform common +math computations on tensor segments. +Here a segmentation is a partitioning of a tensor along +the first dimension, i.e. it defines a mapping from the first dimension onto +`segment_ids`. The `segment_ids` tensor should be the size of +the first dimension, `d0`, with consecutive IDs in the range `0` to `k`, +where `k<d0`. +In particular, a segmentation of a matrix tensor is a mapping of rows to +segments. + +For example: + +```python +c = tf.constant([[1,2,3,4], [-1,-2,-3,-4], [5,6,7,8]]) +tf.segment_sum(c, tf.constant([0, 0, 1])) + ==> [[0 0 0 0] + [5 6 7 8]] +``` + +- - - + +### tf.segment_sum(data, segment_ids, name=None) <div class="md-anchor" id="segment_sum">{#segment_sum}</div> + +Computes the sum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \sum_j data_j\\) where sum is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentSum.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_prod(data, segment_ids, name=None) <div class="md-anchor" id="segment_prod">{#segment_prod}</div> + +Computes the product along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \prod_j data_j\\) where the product is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentProd.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_min(data, segment_ids, name=None) <div class="md-anchor" id="segment_min">{#segment_min}</div> + +Computes the minimum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \min_j(data_j)\\) where `min` is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentMin.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_max(data, segment_ids, name=None) <div class="md-anchor" id="segment_max">{#segment_max}</div> + +Computes the maximum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \max_j(data_j)\\) where `max` is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentMax.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_mean(data, segment_ids, name=None) <div class="md-anchor" id="segment_mean">{#segment_mean}</div> + +Computes the mean along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \frac{\sum_j data_j}{N}\\) where `mean` is +over `j` such that `segment_ids[j] == i` and `N` is the total number of +values summed. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentMean.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + + +- - - + +### tf.unsorted_segment_sum(data, segment_ids, num_segments, name=None) <div class="md-anchor" id="unsorted_segment_sum">{#unsorted_segment_sum}</div> + +Computes the sum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \sum_j data_j\\) where sum is over `j` such +that `segment_ids[j] == i`. Unlike `SegmentSum`, `segment_ids` +need not be sorted and need not cover all values in the full + range of valid values. + +If the sum is empty for a given segment ID `i`, `output[i] = 0`. + +`num_segments` should equal the number of distinct segment IDs. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/UnsortedSegmentSum.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. +* <b>num_segments</b>: A `Tensor` of type `int32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `num_segments`. + + + +- - - + +### tf.sparse_segment_sum(data, indices, segment_ids, name=None) <div class="md-anchor" id="sparse_segment_sum">{#sparse_segment_sum}</div> + +Computes the sum along sparse segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Like `SegmentSum`, but `segment_ids` can have rank less than `data`'s first +dimension, selecting a subset of dimension_0, specified by `indices`. + +For example: + +```prettyprint +c = tf.constant([[1,2,3,4], [-1,-2,-3,-4], [5,6,7,8]]) + +# Select two rows, one segment. +tf.sparse_segment_sum(c, tf.constant([0, 1]), tf.constant([0, 0])) + ==> [[0 0 0 0]] + +# Select two rows, two segment. +tf.sparse_segment_sum(c, tf.constant([0, 1]), tf.constant([0, 1])) + ==> [[ 1 2 3 4] + [-1 -2 -3 -4]] + +# Select all rows, two segments. +tf.sparse_segment_sum(c, tf.constant([0, 1, 2]), tf.constant([0, 0, 1])) + ==> [[0 0 0 0] + [5 6 7 8]] + +# Which is equivalent to: +tf.segment_sum(c, tf.constant([0, 0, 1])) +``` + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>indices</b>: A `Tensor` of type `int32`. + A 1-D tensor. Has same rank as `segment_ids`. +* <b>segment_ids</b>: A `Tensor` of type `int32`. + A 1-D tensor. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.sparse_segment_mean(data, indices, segment_ids, name=None) <div class="md-anchor" id="sparse_segment_mean">{#sparse_segment_mean}</div> + +Computes the mean along sparse segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Like `SegmentMean`, but `segment_ids` can have rank less than `data`'s first +dimension, selecting a subset of dimension_0, specified by `indices`. + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>indices</b>: A `Tensor` of type `int32`. + A 1-D tensor. Has same rank as `segment_ids`. +* <b>segment_ids</b>: A `Tensor` of type `int32`. + A 1-D tensor. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + + + +## Sequence Comparison and Indexing <div class="md-anchor" id="AUTOGENERATED-sequence-comparison-and-indexing">{#AUTOGENERATED-sequence-comparison-and-indexing}</div> + +TensorFlow provides several operations that you can use to add sequence +comparison and index extraction to your graph. You can use these operations to +determine sequence differences and determine the indexes of specific values in +a tensor. + +- - - + +### tf.argmin(input, dimension, name=None) <div class="md-anchor" id="argmin">{#argmin}</div> + +Returns the index with the smallest value across dimensions of a tensor. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. +* <b>dimension</b>: A `Tensor` of type `int32`. + int32, 0 <= dimension < rank(input). Describes which dimension + of the input Tensor to reduce across. For vectors, use dimension = 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + +- - - + +### tf.argmax(input, dimension, name=None) <div class="md-anchor" id="argmax">{#argmax}</div> + +Returns the index with the largest value across dimensions of a tensor. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. +* <b>dimension</b>: A `Tensor` of type `int32`. + int32, 0 <= dimension < rank(input). Describes which dimension + of the input Tensor to reduce across. For vectors, use dimension = 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + + +- - - + +### tf.listdiff(x, y, name=None) <div class="md-anchor" id="listdiff">{#listdiff}</div> + +Computes the difference between two lists of numbers. + +Given a list `x` and a list `y`, this operation returns a list `out` that +represents all numbers that are in `x` but not in `y`. The returned list `out` +is sorted in the same order that the numbers appear in `x` (duplicates are +preserved). This operation also returns a list `idx` that represents the +position of each `out` element in `x`. In other words: + +`out[i] = x[idx[i]] for i in [0, 1, ..., len(out) - 1]` + +For example, given this input: + +```prettyprint +x = [1, 2, 3, 4, 5, 6] +y = [1, 3, 5] +``` + +This operation would return: + +```prettyprint +out ==> [2, 4, 6] +idx ==> [1, 3, 5] +``` + +##### Args: + + +* <b>x</b>: A `Tensor`. 1-D. Values to keep. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. 1-D. Values to remove. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (out, idx). + +* <b>out</b>: A `Tensor`. Has the same type as `x`. 1-D. Values present in `x` but not in `y`. +* <b>idx</b>: A `Tensor` of type `int32`. 1-D. Positions of `x` values preserved in `out`. + + +- - - + +### tf.where(input, name=None) <div class="md-anchor" id="where">{#where}</div> + +Returns locations of true values in a boolean tensor. + +This operation returns the coordinates of true elements in `input`. The +coordinates are returned in a 2-D tensor where the first dimension (rows) +represents the number of true elements, and the second dimension (columns) +represents the coordinates of the true elements. Keep in mind, the shape of +the output tensor can vary depending on how many true values there are in +`input`. Indices are output in row-major order. + +For example: + +```prettyprint +# 'input' tensor is [[True, False] +# [True, False]] +# 'input' has two true values, so output has two coordinates. +# 'input' has rank of 2, so coordinates have two indices. +where(input) ==> [[0, 0], + [1, 0]] + +# `input` tensor is [[[True, False] +# [True, False]] +# [[False, True] +# [False, True]] +# [[False, False] +# [False, True]]] +# 'input' has 5 true values, so output has 5 coordinates. +# 'input' has rank of 3, so coordinates have three indices. +where(input) ==> [[0, 0, 0], + [0, 1, 0], + [1, 0, 1], + [1, 1, 1], + [2, 1, 1]] +``` + +##### Args: + + +* <b>input</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + +- - - + +### tf.unique(x, name=None) <div class="md-anchor" id="unique">{#unique}</div> + +Finds unique elements in a 1-D tensor. + +This operation returns a tensor `y` containing all of the unique elements of `x` +sorted in the same order that they occur in `x`. This operation also returns a +tensor `idx` the same size as `x` that contains the index of each value of `x` +in the unique output `y`. In other words: + +`y[idx[i]] = x[i] for i in [0, 1,...,rank(x) - 1]` + +For example: + +```prettyprint +# tensor 'x' is [1, 1, 2, 4, 4, 4, 7, 8, 8] +y, idx = unique(x) +y ==> [1, 2, 4, 7, 8] +idx ==> [0, 0, 1, 2, 2, 2, 3, 4, 4] +``` + +##### Args: + + +* <b>x</b>: A `Tensor`. 1-D. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (y, idx). + +* <b>y</b>: A `Tensor`. Has the same type as `x`. 1-D. +* <b>idx</b>: A `Tensor` of type `int32`. 1-D. + + + +- - - + +### tf.edit_distance(hypothesis, truth, normalize=True, name='edit_distance') <div class="md-anchor" id="edit_distance">{#edit_distance}</div> + +Computes the Levenshtein distance between sequences. + +This operation takes variable-length sequences (`hypothesis` and `truth`), +each provided as a `SparseTensor`, and computes the Levenshtein distance. +You can normalize the edit distance by length of `truth` by setting +`normalize` to true. + +For example, given the following input: + +```python +# 'hypothesis' is a tensor of shape `[2, 1]` with variable-length values: +# (0,0) = ["a"] +# (1,0) = ["b"] +hypothesis = tf.SparseTensor( + [[0, 0, 0], + [1, 0, 0]], + ["a", "b"] + (2, 1, 1)) + +# 'truth' is a tensor of shape `[2, 2]` with variable-length values: +# (0,0) = [] +# (0,1) = ["a"] +# (1,0) = ["b", "c"] +# (1,1) = ["a"] +truth = tf.SparseTensor( + [[0, 1, 0], + [1, 0, 0], + [1, 0, 1], + [1, 1, 0]] + ["a", "b", "c", "a"], + (2, 2, 2)) + +normalize = True +``` + +This operation would return the following: + +```python +# 'output' is a tensor of shape `[2, 2]` with edit distances normalized +# by 'truth' lengths. +output ==> [[inf, 1.0], # (0,0): no truth, (0,1): no hypothesis + [0.5, 1.0]] # (1,0): addition, (1,1): no hypothesis +``` + +##### Args: + + +* <b>hypothesis</b>: A `SparseTensor` containing hypothesis sequences. +* <b>truth</b>: A `SparseTensor` containing truth sequences. +* <b>normalize</b>: A `bool`. If `True`, normalizes the Levenshtein distance by + length of `truth.` +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A dense `Tensor` with rank `R - 1`, where R is the rank of the + `SparseTensor` inputs `hypothesis` and `truth`. + +##### Raises: + + +* <b>TypeError</b>: If either `hypothesis` or `truth` are not a `SparseTensor`. + + + +- - - + +### tf.invert_permutation(x, name=None) <div class="md-anchor" id="invert_permutation">{#invert_permutation}</div> + +Computes the inverse permutation of a tensor. + +This operation computes the inverse of an index permutation. It takes a 1-D +integer tensor `x`, which represents the indices of a zero-based array, and +swaps each value with its index position. In other words, for an ouput tensor +`y` and an input tensor `x`, this operation computes the following: + +`y[x[i]] = i for i in [0, 1, ..., len(x) - 1]` + +The values must include 0. There can be no duplicate values or negative values. + +For example: + +```prettyprint +# tensor `x` is [3, 4, 0, 2, 1] +invert_permutation(x) ==> [2, 4, 3, 0, 1] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `int32`. 1-D. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. 1-D. + + diff --git a/tensorflow/g3doc/api_docs/python/nn.md b/tensorflow/g3doc/api_docs/python/nn.md new file mode 100644 index 0000000000..91fab34255 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/nn.md @@ -0,0 +1,1306 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Neural Network +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Activation Functions](#AUTOGENERATED-activation-functions) + * [tf.nn.relu(features, name=None)](#relu) + * [tf.nn.relu6(features, name=None)](#relu6) + * [tf.nn.softplus(features, name=None)](#softplus) + * [tf.nn.dropout(x, keep_prob, noise_shape=None, seed=None, name=None)](#dropout) + * [tf.nn.bias_add(value, bias, name=None)](#bias_add) + * [tf.sigmoid(x, name=None)](#sigmoid) + * [tf.tanh(x, name=None)](#tanh) +* [Convolution](#AUTOGENERATED-convolution) + * [tf.nn.conv2d(input, filter, strides, padding, use_cudnn_on_gpu=None, name=None)](#conv2d) + * [tf.nn.depthwise_conv2d(input, filter, strides, padding, name=None)](#depthwise_conv2d) + * [tf.nn.separable_conv2d(input, depthwise_filter, pointwise_filter, strides, padding, name=None)](#separable_conv2d) +* [Pooling](#AUTOGENERATED-pooling) + * [tf.nn.avg_pool(value, ksize, strides, padding, name=None)](#avg_pool) + * [tf.nn.max_pool(value, ksize, strides, padding, name=None)](#max_pool) + * [tf.nn.max_pool_with_argmax(input, ksize, strides, padding, Targmax=None, name=None)](#max_pool_with_argmax) +* [Normalization](#AUTOGENERATED-normalization) + * [tf.nn.l2_normalize(x, dim, epsilon=1e-12, name=None)](#l2_normalize) + * [tf.nn.local_response_normalization(input, depth_radius=None, bias=None, alpha=None, beta=None, name=None)](#local_response_normalization) + * [tf.nn.moments(x, axes, name=None)](#moments) +* [Losses](#AUTOGENERATED-losses) + * [tf.nn.l2_loss(t, name=None)](#l2_loss) +* [Classification](#AUTOGENERATED-classification) + * [tf.nn.sigmoid_cross_entropy_with_logits(logits, targets, name=None)](#sigmoid_cross_entropy_with_logits) + * [tf.nn.softmax(logits, name=None)](#softmax) + * [tf.nn.softmax_cross_entropy_with_logits(logits, labels, name=None)](#softmax_cross_entropy_with_logits) +* [Embeddings](#AUTOGENERATED-embeddings) + * [tf.nn.embedding_lookup(params, ids, name=None)](#embedding_lookup) + * [tf.nn.embedding_lookup_sparse(params, sp_ids, sp_weights, name=None, combiner='mean')](#embedding_lookup_sparse) +* [Evaluation](#AUTOGENERATED-evaluation) + * [tf.nn.top_k(input, k, name=None)](#top_k) + * [tf.nn.in_top_k(predictions, targets, k, name=None)](#in_top_k) +* [Candidate Sampling](#AUTOGENERATED-candidate-sampling) + * [Sampled Loss Functions](#AUTOGENERATED-sampled-loss-functions) + * [tf.nn.nce_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=False, name='nce_loss')](#nce_loss) + * [tf.nn.sampled_softmax_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=True, name='sampled_softmax_loss')](#sampled_softmax_loss) + * [Candidate Samplers](#AUTOGENERATED-candidate-samplers) + * [tf.nn.uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None)](#uniform_candidate_sampler) + * [tf.nn.log_uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None)](#log_uniform_candidate_sampler) + * [tf.nn.learned_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None)](#learned_unigram_candidate_sampler) + * [tf.nn.fixed_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, vocab_file='', distortion=0.0, num_reserved_ids=0, num_shards=1, shard=0, unigrams=[], seed=None, name=None)](#fixed_unigram_candidate_sampler) + * [Miscellaneous candidate sampling utilities](#AUTOGENERATED-miscellaneous-candidate-sampling-utilities) + * [tf.nn.compute_accidental_hits(true_classes, sampled_candidates, num_true, seed=None, name=None)](#compute_accidental_hits) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Activation Functions <div class="md-anchor" id="AUTOGENERATED-activation-functions">{#AUTOGENERATED-activation-functions}</div> + +The activation ops provide different types of nonlinearities for use in +neural networks. These include smooth nonlinearities (`sigmoid`, +`tanh`, and `softplus`), continuous but not everywhere differentiable +functions (`relu`, `relu6`, and `relu_x`), and random regularization +(`dropout`). + +All activation ops apply componentwise, and produce a tensor of the same +shape as the input tensor. + +- - - + +### tf.nn.relu(features, name=None) <div class="md-anchor" id="relu">{#relu}</div> + +Computes rectified linear: `max(features, 0)`. + +##### Args: + + +* <b>features</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `features`. + + +- - - + +### tf.nn.relu6(features, name=None) <div class="md-anchor" id="relu6">{#relu6}</div> + +Computes Rectified Linear 6: `min(max(features, 0), 6)`. + +##### Args: + + +* <b>features</b>: A `Tensor` with type `float`, `double`, `int32`, `int64`, `uint8`, + `int16`, or `int8`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with the same type as `features`. + + +- - - + +### tf.nn.softplus(features, name=None) <div class="md-anchor" id="softplus">{#softplus}</div> + +Computes softplus: `log(exp(features) + 1)`. + +##### Args: + + +* <b>features</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `features`. + + +- - - + +### tf.nn.dropout(x, keep_prob, noise_shape=None, seed=None, name=None) <div class="md-anchor" id="dropout">{#dropout}</div> + +Computes dropout. + +With probability `keep_prob`, outputs the input element scaled up by +`1 / keep_prob`, otherwise outputs `0`. The scaling is so that the expected +sum is unchanged. + +By default, each element is kept or dropped independently. If `noise_shape` +is specified, it must be +[broadcastable](http://docs.scipy.org/doc/numpy/user/basics.broadcasting.html) +to the shape of `x`, and only dimensions with `noise_shape[i] == x.shape[i]` +will make independent decisions. For example, if `x.shape = [b, x, y, c]` and +`noise_shape = [b, 1, 1, c]`, each batch and channel component will be +kept independently and each row and column will be kept or not kept together. + +##### Args: + + +* <b>x</b>: A tensor. +* <b>keep_prob</b>: Float probability that each element is kept. +* <b>noise_shape</b>: Shape for randomly generated keep/drop flags. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A Tensor of the same shape of `x`. + +##### Raises: + + +* <b>ValueError</b>: If `keep_prob` is not in `(0, 1]`. + + +- - - + +### tf.nn.bias_add(value, bias, name=None) <div class="md-anchor" id="bias_add">{#bias_add}</div> + +Adds `bias` to `value`. + +This is (mostly) a special case of `tf.add` where `bias` is restricted to 1-D. +Broadcasting is supported, so `value` may have any number of dimensions. +Unlike `tf.add`, the type of `bias` is allowed to differ from `value` in the +case where both types are quantized. + +##### Args: + + +* <b>value</b>: A `Tensor` with type `float`, `double`, `int64`, `int32`, `uint8`, + `int16`, `int8`, or `complex64`. +* <b>bias</b>: A 1-D `Tensor` with size matching the last dimension of `value`. + Must be the same type as `value` unless `value` is a quantized type, + in which case a different quantized type may be used. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with the same type as `value`. + + +- - - + +### tf.sigmoid(x, name=None) <div class="md-anchor" id="sigmoid">{#sigmoid}</div> + +Computes sigmoid of `x` element-wise. + +Specifically, `y = 1 / (1 + exp(-x))`. + +##### Args: + + +* <b>x</b>: A Tensor with type `float`, `double`, `int32`, `complex64`, `int64`, + or `qint32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A Tensor with the same type as `x` if `x.dtype != qint32` + otherwise the return type is `quint8`. + + +- - - + +### tf.tanh(x, name=None) <div class="md-anchor" id="tanh">{#tanh}</div> + +Computes hyperbolic tangent of `x` element-wise. + +##### Args: + + +* <b>x</b>: A Tensor with type `float`, `double`, `int32`, `complex64`, `int64`, + or `qint32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A Tensor with the same type as `x` if `x.dtype != qint32` otherwise + the return type is `quint8`. + + + +## Convolution <div class="md-anchor" id="AUTOGENERATED-convolution">{#AUTOGENERATED-convolution}</div> + +The convolution ops sweep a 2-D filter over a batch of images, applying the +filter to each window of each image of the appropriate size. The different +ops trade off between generic vs. specific filters: + +* `conv2d`: Arbitrary filters that can mix channels together. +* `depthwise_conv2d`: Filters that operate on each channel independently. +* `separable_conv2d`: A depthwise spatial filter followed by a pointwise filter. + +Note that although these ops are called "convolution", they are strictly +speaking "cross-correlation" since the filter is combined with an input window +without reversing the filter. For details, see [the properties of +cross-correlation](https://en.wikipedia.org/wiki/Cross-correlation#Properties). + +The filter is applied to image patches of the same size as the filter and +strided according to the `strides` argument. `strides = [1, 1, 1, 1]` applies +the filter to a patch at every offset, `strides = [1, 2, 2, 1]` applies the +filter to every other image patch in each dimension, etc. + +Ignoring channels for the moment, the spatial semantics of the convolution ops +are as follows. If the 4-D `input` has shape +`[batch, in_height, in_width, ...]` and the 4-D `filter` has shape +`[filter_height, filter_width, ...]`, then + + output.shape = [batch, + (in_height - filter_height + 1) / strides[1], + (in_width - filter_width + 1) / strides[2], + ...] + + output[b, i, j, :] = + sum_{di, dj} input[b, strides[1] * i + di, strides[2] * j + dj, ...] * + filter[di, dj, ...] + +Since `input` is 4-D, each `input[b, i, j, :]` is a vector. For `conv2d`, these +vectors are multiplied by the `filter[di, dj, :, :]` matrices to produce new +vectors. For `depthwise_conv_2d`, each scalar component `input[b, i, j, k]` +is multiplied by a vector `filter[di, dj, k]`, and all the vectors are +concatenated. + +In the formula for `output.shape`, the rounding direction depends on padding: + +* `padding = 'SAME'`: Round down (only full size windows are considered). +* `padding = 'VALID'`: Round up (partial windows are included). + +- - - + +### tf.nn.conv2d(input, filter, strides, padding, use_cudnn_on_gpu=None, name=None) <div class="md-anchor" id="conv2d">{#conv2d}</div> + +Computes a 2-D convolution given 4-D `input` and `filter` tensors. + +Given an input tensor of shape `[batch, in_height, in_width, in_channels]` +and a filter / kernel tensor of shape +`[filter_height, filter_width, in_channels, out_channels]`, this op +performs the following: + +1. Flattens the filter to a 2-D matrix with shape + `[filter_height * filter_width * in_channels, output_channels]`. +2. Extracts image patches from the the input tensor to form a *virtual* + tensor of shape `[batch, out_height, out_width, + filter_height * filter_width * in_channels]`. +3. For each patch, right-multiplies the filter matrix and the image patch + vector. + +In detail, + + output[b, i, j, k] = + sum_{di, dj, q} input[b, strides[1] * i + di, strides[2] * j + dj, q] * + filter[di, dj, q, k] + +Must have `strides[0] = strides[3] = 1`. For the most common case of the same +horizontal and vertices strides, `strides = [1, stride, stride, 1]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>filter</b>: A `Tensor`. Must have the same type as `input`. +* <b>strides</b>: A list of `ints`. + 1-D of length 4. The stride of the sliding window for each dimension + of `input`. +* <b>padding</b>: A `string` from: `"SAME", "VALID"`. + The type of padding algorithm to use. +* <b>use_cudnn_on_gpu</b>: An optional `bool`. Defaults to `True`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.nn.depthwise_conv2d(input, filter, strides, padding, name=None) <div class="md-anchor" id="depthwise_conv2d">{#depthwise_conv2d}</div> + +Depthwise 2-D convolution. + +Given an input tensor of shape `[batch, in_height, in_width, in_channels]` +and a filter tensor of shape +`[filter_height, filter_width, in_channels, channel_multiplier]` +containing `in_channels` convolutional filters of depth 1, `depthwise_conv2d` +applies a different filter to each input channel (expanding from 1 channel +to `channel_multiplier` channels for each), then concatenates the results +together. The output has `in_channels * channel_multiplier` channels. + +In detail, + + output[b, i, j, k * channel_multiplier + q] = + sum_{di, dj} input[b, strides[1] * i + di, strides[2] * j + dj, k] * + filter[di, dj, k, q] + +Must have `strides[0] = strides[3] = 1`. For the most common case of the +same horizontal and vertical strides, `strides = [1, stride, stride, 1]`. + +##### Args: + + +* <b>input</b>: 4-D with shape `[batch, in_height, in_width, in_channels]`. +* <b>filter</b>: 4-D with shape + `[filter_height, filter_width, in_channels, channel_multiplier]`. +* <b>strides</b>: 1-D of size 4. The stride of the sliding window for each + dimension of `input`. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A 4-D `Tensor` of shape + `[batch, out_height, out_width, in_channels * channel_multiplier].` + + +- - - + +### tf.nn.separable_conv2d(input, depthwise_filter, pointwise_filter, strides, padding, name=None) <div class="md-anchor" id="separable_conv2d">{#separable_conv2d}</div> + +2-D convolution with separable filters. + +Performs a depthwise convolution that acts separately on channels followed by +a pointwise convolution that mixes channels. Note that this is separability +between dimensions `[1, 2]` and `3`, not spatial separability between +dimensions `1` and `2`. + +In detail, + + output[b, i, j, k] = sum_{di, dj, q, r] + input[b, strides[1] * i + di, strides[2] * j + dj, q] * + depthwise_filter[di, dj, q, r] * + pointwise_filter[0, 0, q * channel_multiplier + r, k] + +`strides` controls the strides for the depthwise convolution only, since +the pointwise convolution has implicit strides of `[1, 1, 1, 1]`. Must have +`strides[0] = strides[3] = 1`. For the most common case of the same +horizontal and vertical strides, `strides = [1, stride, stride, 1]`. + +##### Args: + + +* <b>input</b>: 4-D `Tensor` with shape `[batch, in_height, in_width, in_channels]`. +* <b>depthwise_filter</b>: 4-D `Tensor` with shape + `[filter_height, filter_width, in_channels, channel_multiplier]`. + Contains `in_channels` convolutional filters of depth 1. +* <b>pointwise_filter</b>: 4-D `Tensor` with shape + `[1, 1, channel_multiplier * in_channels, out_channels]`. Pointwise + filter to mix channels after `depthwise_filter` has convolved spatially. +* <b>strides</b>: 1-D of size 4. The strides for the depthwise convolution for + each dimension of `input`. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A 4-D `Tensor` of shape `[batch, out_height, out_width, out_channels]`. + + + +## Pooling <div class="md-anchor" id="AUTOGENERATED-pooling">{#AUTOGENERATED-pooling}</div> + +The pooling ops sweep a rectangular window over the input tensor, computing a +reduction operation for each window (average, max, or max with argmax). Each +pooling op uses rectangular windows of size `ksize` separated by offset +`strides`. For example, if `strides` is all ones every window is used, if +`strides` is all twos every other window is used in each dimension, etc. + +In detail, the output is + + output[i] = reduce(value[strides * i:strides * i + ksize]) + +for each tuple of indices `i`. The output shape is + + output.shape = (value.shape - ksize + 1) / strides + +where the rounding direction depends on padding: + +* `padding = 'SAME'`: Round down (only full size windows are considered). +* `padding = 'VALID'`: Round up (partial windows are included). + +- - - + +### tf.nn.avg_pool(value, ksize, strides, padding, name=None) <div class="md-anchor" id="avg_pool">{#avg_pool}</div> + +Performs the average pooling on the input. + +Each entry in `output` is the mean of the corresponding size `ksize` +window in `value`. + +##### Args: + + +* <b>value</b>: A 4-D `Tensor` of shape `[batch, height, width, channels]` and type + `float32`, `float64`, `qint8`, `quint8`, or `qint32`. +* <b>ksize</b>: A list of ints that has length >= 4. + The size of the window for each dimension of the input tensor. +* <b>strides</b>: A list of ints that has length >= 4. + The stride of the sliding window for each dimension of the + input tensor. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: Optional name for the operation. + +##### Returns: + + A `Tensor` with the same type as `value`. The average pooled output tensor. + + +- - - + +### tf.nn.max_pool(value, ksize, strides, padding, name=None) <div class="md-anchor" id="max_pool">{#max_pool}</div> + +Performs the max pooling on the input. + +##### Args: + + +* <b>value</b>: A 4-D `Tensor` with shape `[batch, height, width, channels]` and + type `float32`, `float64`, `qint8`, `quint8`, `qint32`. +* <b>ksize</b>: A list of ints that has length >= 4. The size of the window for + each dimension of the input tensor. +* <b>strides</b>: A list of ints that has length >= 4. The stride of the sliding + window for each dimension of the input tensor. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: Optional name for the operation. + +##### Returns: + + A `Tensor` with the same type as `value`. The max pooled output tensor. + + +- - - + +### tf.nn.max_pool_with_argmax(input, ksize, strides, padding, Targmax=None, name=None) <div class="md-anchor" id="max_pool_with_argmax">{#max_pool_with_argmax}</div> + +Performs max pooling on the input and outputs both max values and indices. + +The indices in `argmax` are flattened, so that a maximum value at position +`[b, y, x, c]` becomes flattened index +`((b * height + y) * width + x) * channels + c`. + +##### Args: + + +* <b>input</b>: A `Tensor` of type `float32`. + 4-D with shape `[batch, height, width, channels]`. Input to pool over. +* <b>ksize</b>: A list of `ints` that has length `>= 4`. + The size of the window for each dimension of the input tensor. +* <b>strides</b>: A list of `ints` that has length `>= 4`. + The stride of the sliding window for each dimension of the + input tensor. +* <b>padding</b>: A `string` from: `"SAME", "VALID"`. + The type of padding algorithm to use. +* <b>Targmax</b>: An optional `tf.DType` from: `tf.int32, tf.int64`. Defaults to `tf.int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (output, argmax). + +* <b>output</b>: A `Tensor` of type `float32`. The max pooled output tensor. +* <b>argmax</b>: A `Tensor` of type `Targmax`. 4-D. The flattened indices of the max values chosen for each output. + + + +## Normalization <div class="md-anchor" id="AUTOGENERATED-normalization">{#AUTOGENERATED-normalization}</div> + +Normalization is useful to prevent neurons from saturating when inputs may +have varying scale, and to aid generalization. + +- - - + +### tf.nn.l2_normalize(x, dim, epsilon=1e-12, name=None) <div class="md-anchor" id="l2_normalize">{#l2_normalize}</div> + +Normalizes along dimension `dim` using an L2 norm. + +For a 1-D tensor with `dim = 0`, computes + + output = x / sqrt(max(sum(x**2), epsilon)) + +For `x` with more dimensions, independently normalizes each 1-D slice along +dimension `dim`. + +##### Args: + + +* <b>x</b>: A `Tensor`. +* <b>dim</b>: Dimension along which to normalize. +* <b>epsilon</b>: A lower bound value for the norm. Will use `sqrt(epsilon)` as the + divisor if `norm < sqrt(epsilon)`. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A `Tensor` with the same shape as `x`. + + +- - - + +### tf.nn.local_response_normalization(input, depth_radius=None, bias=None, alpha=None, beta=None, name=None) <div class="md-anchor" id="local_response_normalization">{#local_response_normalization}</div> + +Local Response Normalization. + +The 4-D `input` tensor is treated as a 3-D array of 1-D vectors (along the last +dimension), and each vector is normalized independently. Within a given vector, +each component is divided by the weighted, squared sum of inputs within +`depth_radius`. In detail, + + sqr_sum[a, b, c, d] = + sum(input[a, b, c, d - depth_radius : d + depth_radius + 1] ** 2) + output = input / (bias + alpha * sqr_sum ** beta) + +For details, see [Krizhevsky et al., ImageNet classification with deep +convolutional neural networks (NIPS 2012)] +(http://papers.nips.cc/paper/4824-imagenet-classification-with-deep-convolutional-neural-networks). + +##### Args: + + +* <b>input</b>: A `Tensor` of type `float32`. 4-D. +* <b>depth_radius</b>: An optional `int`. Defaults to `5`. + 0-D. Half-width of the 1-D normalization window. +* <b>bias</b>: An optional `float`. Defaults to `1`. + An offset (usually positive to avoid dividing by 0). +* <b>alpha</b>: An optional `float`. Defaults to `1`. + A scale factor, usually positive. +* <b>beta</b>: An optional `float`. Defaults to `0.5`. An exponent. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + +- - - + +### tf.nn.moments(x, axes, name=None) <div class="md-anchor" id="moments">{#moments}</div> + +Calculate the mean and variance of `x`. + +The mean and variance are calculated by aggregating the contents of `x` +across `axes`. If `x` is 1-D and `axes = [0]` this is just the mean +and variance of a vector. + +For so-called "global normalization" needed for convolutional filters pass +`axes=[0, 1, 2]` (batch, height, width). For batch normalization pass +`axes=[0]` (batch). + +##### Args: + + +* <b>x</b>: A `Tensor`. +* <b>axes</b>: array of ints. Axes along which to compute mean and + variance. +* <b>name</b>: Name used to scope the operations that compute the moments. + +##### Returns: + + Two `Tensors`: `mean` and `variance`. + + + +## Losses <div class="md-anchor" id="AUTOGENERATED-losses">{#AUTOGENERATED-losses}</div> + +The loss ops measure error between two tensors, or between a tensor and zero. +These can be used for measuring accuracy of a network in a regression task +or for regularization purposes (weight decay). + +- - - + +### tf.nn.l2_loss(t, name=None) <div class="md-anchor" id="l2_loss">{#l2_loss}</div> + +L2 Loss. + +Computes half the L2 norm of a tensor without the `sqrt`: + + output = sum(t ** 2) / 2 + +##### Args: + + +* <b>t</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Typically 2-D, but may have any dimensions. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `t`. 0-D. + + + +## Classification <div class="md-anchor" id="AUTOGENERATED-classification">{#AUTOGENERATED-classification}</div> + +TensorFlow provides several operations that help you perform classification. + +- - - + +### tf.nn.sigmoid_cross_entropy_with_logits(logits, targets, name=None) <div class="md-anchor" id="sigmoid_cross_entropy_with_logits">{#sigmoid_cross_entropy_with_logits}</div> + +Computes sigmoid cross entropy given `logits`. + +Measures the probability error in discrete classification tasks in which each +class is independent and not mutually exclusive. For instance, one could +perform multilabel classification where a picture can contain both an elephant +and a dog at the same time. + +For brevity, let `x = logits`, `z = targets`. The logistic loss is + + x - x * z + log(1 + exp(-x)) + +To ensure stability and avoid overflow, the implementation uses + + max(x, 0) - x * z + log(1 + exp(-abs(x))) + +`logits` and `targets` must have the same type and shape. + +##### Args: + + +* <b>logits</b>: A `Tensor` of type `float32` or `float64`. +* <b>targets</b>: A `Tensor` of the same type and shape as `logits`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of the same shape as `logits` with the componentwise + logistic losses. + + +- - - + +### tf.nn.softmax(logits, name=None) <div class="md-anchor" id="softmax">{#softmax}</div> + +Computes softmax activations. + +For each batch `i` and class `j` we have + + softmax[i, j] = exp(logits[i, j]) / sum(exp(logits[i])) + +##### Args: + + +* <b>logits</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + 2-D with shape `[batch_size, num_classes]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `logits`. Same shape as `logits`. + + +- - - + +### tf.nn.softmax_cross_entropy_with_logits(logits, labels, name=None) <div class="md-anchor" id="softmax_cross_entropy_with_logits">{#softmax_cross_entropy_with_logits}</div> + +Computes softmax cross entropy between `logits` and `labels`. + +Measures the probability error in discrete classification tasks in which the +classes are mutually exclusive (each entry is in exactly one class). For +example, each CIFAR-10 image is labeled with one and only one label: an image +can be a dog or a truck, but not both. + +**WARNING:** This op expects unscaled logits, since it performs a `softmax` +on `logits` internally for efficiency. Do not call this op with the +output of `softmax`, as it will produce incorrect results. + +`logits` and `labels` must have the same shape `[batch_size, num_classes]` +and the same dtype (either `float32` or `float64`). + +##### Args: + + +* <b>logits</b>: Unscaled log probabilities. +* <b>labels</b>: Each row `labels[i]` must be a valid probability distribution. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A 1-D `Tensor` of length `batch_size` of the same type as `logits` with the + softmax cross entropy loss. + + + +## Embeddings <div class="md-anchor" id="AUTOGENERATED-embeddings">{#AUTOGENERATED-embeddings}</div> + +TensorFlow provides several operations that help you compute embeddings. + +- - - + +### tf.nn.embedding_lookup(params, ids, name=None) <div class="md-anchor" id="embedding_lookup">{#embedding_lookup}</div> + +Return a tensor of embedding values by looking up "ids" in "params". + +##### Args: + + +* <b>params</b>: List of tensors of the same shape. A single tensor is + treated as a singleton list. +* <b>ids</b>: Tensor of integers containing the ids to be looked up in + 'params'. Let P be len(params). If P > 1, then the ids are + partitioned by id % P, and we do separate lookups in params[p] + for 0 <= p < P, and then stitch the results back together into + a single result tensor. +* <b>name</b>: Optional name for the op. + +##### Returns: + + A tensor of shape ids.shape + params[0].shape[1:] containing the + values params[i % P][i] for each i in ids. + +##### Raises: + + +* <b>ValueError</b>: if some parameters are invalid. + + +- - - + +### tf.nn.embedding_lookup_sparse(params, sp_ids, sp_weights, name=None, combiner='mean') <div class="md-anchor" id="embedding_lookup_sparse">{#embedding_lookup_sparse}</div> + +Computes embeddings for the given ids and weights. + +This op assumes that there is at least one id for each row in the dense tensor +represented by sp_ids (i.e. there are no rows with empty features), and that +all the indices of sp_ids are in canonical row-major order. + +It also assumes that all id values lie in the range [0, p0), where p0 +is the sum of the size of params along dimension 0. + +##### Args: + + +* <b>params</b>: A single tensor representing the complete embedding tensor, + or a list of P tensors all of same shape except for the first dimension, + representing sharded embedding tensors. In the latter case, the ids are + partitioned by id % P, and we do separate lookups in params[p] for + 0 <= p < P, and then stitch the results back together into a single + result tensor. The first dimension is allowed to vary as the vocab + size is not necessarily a multiple of P. +* <b>sp_ids</b>: N x M SparseTensor of int64 ids (typically from FeatureValueToId), + where N is typically batch size and M is arbitrary. +* <b>sp_weights</b>: either a SparseTensor of float / double weights, or None to + indicate all weights should be taken to be 1. If specified, sp_weights + must have exactly the same shape and indices as sp_ids. +* <b>name</b>: Optional name for the op. +* <b>combiner</b>: A string specifying the reduction op. Currently "mean" and "sum" + are supported. + "sum" computes the weighted sum of the embedding results for each row. + "mean" is the weighted sum divided by the total weight. + +##### Returns: + + A dense tensor representing the combined embeddings for the + sparse ids. For each row in the dense tensor represented by sp_ids, the op + looks up the embeddings for all ids in that row, multiplies them by the + corresponding weight, and combines these embeddings as specified. + + In other words, if + shape(combined params) = [p0, p1, ..., pm] + and + shape(sp_ids) = shape(sp_weights) = [d0, d1, ..., dn] + then + shape(output) = [d0, d1, ..., dn-1, p1, ..., pm]. + + For instance, if params is a 10x20 matrix, and sp_ids / sp_weights are + + [0, 0]: id 1, weight 2.0 + [0, 1]: id 3, weight 0.5 + [1, 0]: id 0, weight 1.0 + [2, 3]: id 1, weight 3.0 + + with combiner="mean", then the output will be a 3x20 matrix where + output[0, :] = (params[1, :] * 2.0 + params[3, :] * 0.5) / (2.0 + 0.5) + output[1, :] = params[0, :] * 1.0 + output[2, :] = params[1, :] * 3.0 + +##### Raises: + + +* <b>TypeError</b>: If sp_ids is not a SparseTensor, or if sp_weights is neither + None nor SparseTensor. +* <b>ValueError</b>: If combiner is not one of {"mean", "sum"}. + + + +## Evaluation <div class="md-anchor" id="AUTOGENERATED-evaluation">{#AUTOGENERATED-evaluation}</div> + +The evaluation ops are useful for measuring the performance of a network. +Since they are nondifferentiable, they are typically used at evaluation time. + +- - - + +### tf.nn.top_k(input, k, name=None) <div class="md-anchor" id="top_k">{#top_k}</div> + +Returns the values and indices of the k largest elements for each row. + +\\(values_{i, j}\\) represents the j-th largest element in \\(input_i\\). + +\\(indices_{i, j}\\) gives the column index of the corresponding element, +such that \\(input_{i, indices_{i, j}} = values_{i, j}\\). If two +elements are equal, the lower-index element appears first. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. + A batch_size x classes tensor +* <b>k</b>: An `int` that is `>= 1`. + Number of top elements to look for within each row +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (values, indices). + +* <b>values</b>: A `Tensor`. Has the same type as `input`. A batch_size x k tensor with the k largest elements for each row, + sorted in descending order +* <b>indices</b>: A `Tensor` of type `int32`. A batch_size x k tensor with the index of each value within each row + + +- - - + +### tf.nn.in_top_k(predictions, targets, k, name=None) <div class="md-anchor" id="in_top_k">{#in_top_k}</div> + +Says whether the targets are in the top K predictions. + +This outputs a batch_size bool array, an entry out[i] is true if the +prediction for the target class is among the top k predictions among +all predictions for example i. Note that the behavior of InTopK differs +from the TopK op in its handling of ties; if multiple classes have the +same prediction value and straddle the top-k boundary, all of those +classes are considered to be in the top k. + +More formally, let + + \\(predictions_i\\) be the predictions for all classes for example i, + \\(targets_i\\) be the target class for example i, + \\(out_i\\) be the output for example i, + +$$out_i = predictions_{i, targets_i} \in TopKIncludingTies(predictions_i)$$ + +##### Args: + + +* <b>predictions</b>: A `Tensor` of type `float32`. A batch_size x classes tensor +* <b>targets</b>: A `Tensor` of type `int32`. A batch_size vector of class ids +* <b>k</b>: An `int`. Number of top elements to look at for computing precision +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. Computed Precision at k as a bool Tensor + + + +## Candidate Sampling <div class="md-anchor" id="AUTOGENERATED-candidate-sampling">{#AUTOGENERATED-candidate-sampling}</div> + +Do you want to train a multiclass or multilabel model with thousands +or millions of output classes (for example, a language model with a +large vocabulary)? Training with a full Softmax is slow in this case, +since all of the classes are evaluated for every training example. +Candidate Sampling training algorithms can speed up your step times by +only considering a small randomly-chosen subset of contrastive classes +(called candidates) for each batch of training examples. + +See our [Candidate Sampling Algorithms Reference] +(http://www.tensorflow.org/extras/candidate_sampling.pdf) + +### Sampled Loss Functions <div class="md-anchor" id="AUTOGENERATED-sampled-loss-functions">{#AUTOGENERATED-sampled-loss-functions}</div> + +TensorFlow provides the following sampled loss functions for faster training. + +- - - + +### tf.nn.nce_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=False, name='nce_loss') <div class="md-anchor" id="nce_loss">{#nce_loss}</div> + +Computes and returns the noise-contrastive estimation training loss. + +See [Noise-contrastive estimation: A new estimation principle for +unnormalized statistical models] +(http://www.jmlr.org/proceedings/papers/v9/gutmann10a/gutmann10a.pdf). +Also see our [Candidate Sampling Algorithms Reference] +(http://www.tensorflow.org/extras/candidate_sampling.pdf) + +Note: In the case where num_true > 1, we assign to each target class +the target probability 1 / num_true so that the target probabilities +sum to 1 per-example. + +Note: It would be useful to allow a variable number of target classes per +example. We hope to provide this functionality in a future release. +For now, if you have a variable number of target classes, you can pad them +out to a constant number by either repeating them or by padding +with an otherwise unused class. + +##### Args: + + +* <b>weights</b>: A `Tensor` of shape [num_classes, dim]. The class embeddings. +* <b>biases</b>: A `Tensor` of shape [num_classes]. The class biases. +* <b>inputs</b>: A `Tensor` of shape [batch_size, dim]. The forward + activations of the input network. +* <b>labels</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>num_classes</b>: An `int`. The number of possible classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>sampled_values</b>: a tuple of `(sampled_candidates, true_expected_count, + sampled_expected_count)` returned by a *_candidate_sampler function. + (if None, we default to LogUniformCandidateSampler) +* <b>remove_accidental_hits</b>: A `bool`. Whether to remove "accidental hits" + where a sampled class equals one of the target classes. If set to + `True`, this is a "Sampled Logistic" loss instead of NCE, and we are + learning to generate log-odds instead of log probabilities. See + our [Candidate Sampling Algorithms Reference] + (http://www.tensorflow.org/extras/candidate_sampling.pdf). + Default is False. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A batch_size 1-D tensor of per-example NCE losses. + + +- - - + +### tf.nn.sampled_softmax_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=True, name='sampled_softmax_loss') <div class="md-anchor" id="sampled_softmax_loss">{#sampled_softmax_loss}</div> + +Computes and returns the sampled softmax training loss. + +This is a faster way to train a softmax classifier over a huge number of +classes. + +This operation is for training only. It is generally an underestimate of +the full softmax loss. + +At inference time, you can compute full softmax probabilities with the +expression `tf.nn.softmax(tf.matmul(inputs, weights) + biases)`. + +See our [Candidate Sampling Algorithms Reference] +(http://www.tensorflow.org/extras/candidate_sampling.pdf) + +Also see Section 3 of http://arxiv.org/abs/1412.2007 for the math. + +##### Args: + + +* <b>weights</b>: A `Tensor` of shape [num_classes, dim]. The class embeddings. +* <b>biases</b>: A `Tensor` of shape [num_classes]. The class biases. +* <b>inputs</b>: A `Tensor` of shape [batch_size, dim]. The forward + activations of the input network. +* <b>labels</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. Note that this format differs from + the `labels` argument of `nn.softmax_cross_entropy_with_logits`. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>num_classes</b>: An `int`. The number of possible classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>sampled_values</b>: a tuple of `(sampled_candidates, true_expected_count, + sampled_expected_count)` returned by a *_candidate_sampler function. + (if None, we default to LogUniformCandidateSampler) +* <b>remove_accidental_hits</b>: A `bool`. whether to remove "accidental hits" + where a sampled class equals one of the target classes. Default is + True. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A batch_size 1-D tensor of per-example sampled softmax losses. + + + +### Candidate Samplers <div class="md-anchor" id="AUTOGENERATED-candidate-samplers">{#AUTOGENERATED-candidate-samplers}</div> + +TensorFlow provides the following samplers for randomly sampling candidate +classes when using one of the sampled loss functions above. + +- - - + +### tf.nn.uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None) <div class="md-anchor" id="uniform_candidate_sampler">{#uniform_candidate_sampler}</div> + +Samples a set of classes using a uniform base distribution. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution for this operation is the uniform distribution +over the range of integers `[0, range_max]`. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + +- - - + +### tf.nn.log_uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None) <div class="md-anchor" id="log_uniform_candidate_sampler">{#log_uniform_candidate_sampler}</div> + +Samples a set of classes using a log-uniform (Zipfian) base distribution. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution for this operation is an approximately log-uniform +or Zipfian distribution: + +`P(class) = (log(class + 2) - log(class + 1)) / log(range_max + 1)` + +This sampler is useful when the target classes approximately follow such +a distribution - for example, if the classes represent words in a lexicon +sorted in decreasing order of frequency. If your classes are not ordered by +decreasing frequency, do not use this op. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + +- - - + +### tf.nn.learned_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None) <div class="md-anchor" id="learned_unigram_candidate_sampler">{#learned_unigram_candidate_sampler}</div> + +Samples a set of classes from a distribution learned during training. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution for this operation is constructed on the fly +during training. It is a unigram distribution over the target +classes seen so far during training. Every integer in `[0, range_max]` +begins with a weight of 1, and is incremented by 1 each time it is +seen as a target class. The base distribution is not saved to checkpoints, +so it is reset when the model is reloaded. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + +- - - + +### tf.nn.fixed_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, vocab_file='', distortion=0.0, num_reserved_ids=0, num_shards=1, shard=0, unigrams=[], seed=None, name=None) <div class="md-anchor" id="fixed_unigram_candidate_sampler">{#fixed_unigram_candidate_sampler}</div> + +Samples a set of classes using the provided (fixed) base distribution. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution is read from a file or passed in as an +in-memory array. There is also an option to skew the distribution by +applying a distortion power to the weights. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>vocab_file</b>: Each valid line in this file (which should have a CSV-like + format) corresponds to a valid word ID. IDs are in sequential order, + starting from num_reserved_ids. The last entry in each line is expected + to be a value corresponding to the count or relative probability. Exactly + one of `vocab_file` and `unigrams` needs to be passed to this operation. +* <b>distortion</b>: The distortion is used to skew the unigram probability + distribution. Each weight is first raised to the distortion's power + before adding to the internal unigram distribution. As a result, + `distortion = 1.0` gives regular unigram sampling (as defined by the vocab + file), and `distortion = 0.0` gives a uniform distribution. +* <b>num_reserved_ids</b>: Optionally some reserved IDs can be added in the range + `[0, num_reserved_ids]` by the users. One use case is that a special + unknown word token is used as ID 0. These IDs will have a sampling + probability of 0. +* <b>num_shards</b>: A sampler can be used to sample from a subset of the original + range in order to speed up the whole computation through parallelism. This + parameter (together with `shard`) indicates the number of partitions that + are being used in the overall computation. +* <b>shard</b>: A sampler can be used to sample from a subset of the original range + in order to speed up the whole computation through parallelism. This + parameter (together with `num_shards`) indicates the particular partition + number of the operation, when partitioning is being used. +* <b>unigrams</b>: A list of unigram counts or probabilities, one per ID in + sequential order. Exactly one of `vocab_file` and `unigrams` should be + passed to this operation. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + + +### Miscellaneous candidate sampling utilities <div class="md-anchor" id="AUTOGENERATED-miscellaneous-candidate-sampling-utilities">{#AUTOGENERATED-miscellaneous-candidate-sampling-utilities}</div> + +- - - + +### tf.nn.compute_accidental_hits(true_classes, sampled_candidates, num_true, seed=None, name=None) <div class="md-anchor" id="compute_accidental_hits">{#compute_accidental_hits}</div> + +Compute the ids of positions in sampled_candidates matching true_classes. + +In Candidate Sampling, this operation facilitates virtually removing +sampled classes which happen to match target classes. This is done +in Sampled Softmax and Sampled Logistic. + +See our [Candidate Sampling Algorithms +Reference](http://www.tensorflow.org/extras/candidate_sampling.pdf). + +We presuppose that the `sampled_candidates` are unique. + +We call it an 'accidental hit' when one of the target classes +matches one of the sampled classes. This operation reports +accidental hits as triples `(index, id, weight)`, where `index` +represents the row number in `true_classes`, `id` represents the +position in `sampled_candidates`, and weight is `-FLOAT_MAX`. + +The result of this op should be passed through a `sparse_to_dense` +operation, then added to the logits of the sampled classes. This +removes the contradictory effect of accidentally sampling the true +target classes as noise classes for the same example. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled_candidates output of CandidateSampler. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>indices</b>: A `Tensor` of type `int32` and shape `[num_accidental_hits]`. + Values indicate rows in `true_classes`. +* <b>ids</b>: A `Tensor` of type `int64` and shape `[num_accidental_hits]`. + Values indicate positions in `sampled_candidates`. +* <b>weights</b>: A `Tensor` of type `float` and shape `[num_accidental_hits]`. + Each value is `-FLOAT_MAX`. + + diff --git a/tensorflow/g3doc/api_docs/python/ops.md b/tensorflow/g3doc/api_docs/python/ops.md new file mode 100644 index 0000000000..bb7d6e70e2 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/ops.md @@ -0,0 +1,10 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Leftovers, should be empty and removed +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + + diff --git a/tensorflow/g3doc/api_docs/python/python_io.md b/tensorflow/g3doc/api_docs/python/python_io.md new file mode 100644 index 0000000000..7ad4b65bd0 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/python_io.md @@ -0,0 +1,104 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Data IO (Python functions) +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Data IO (Python Functions)](#AUTOGENERATED-data-io--python-functions-) + * [class tf.python_io.TFRecordWriter](#TFRecordWriter) + * [tf.python_io.tf_record_iterator(path)](#tf_record_iterator) + * [TFRecords Format Details](#AUTOGENERATED-tfrecords-format-details) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Data IO (Python Functions) <div class="md-anchor" id="AUTOGENERATED-data-io--python-functions-">{#AUTOGENERATED-data-io--python-functions-}</div> + +A TFRecords file represents a sequence of (binary) strings. The format is not +random access, so it is suitable for streaming large amounts of data but not +suitable if fast sharding or other non-sequential access is desired. + +- - - + +### class tf.python_io.TFRecordWriter <div class="md-anchor" id="TFRecordWriter">{#TFRecordWriter}</div> + +A class to write records to a TFRecords file. + +This class implements `__enter__` and `__exit__`, and can be used +in `with` blocks like a normal file. + +- - - + +#### tf.python_io.TFRecordWriter.__init__(path) {#TFRecordWriter.__init__} + +Opens file `path` and creates a `TFRecordWriter` writing to it. + +##### Args: + + +* <b>path</b>: The path to the TFRecords file. + +##### Raises: + + +* <b>IOError</b>: If `path` cannot be opened for writing. + + +- - - + +#### tf.python_io.TFRecordWriter.write(record) {#TFRecordWriter.write} + +Write a string record to the file. + +##### Args: + + +* <b>record</b>: str + + +- - - + +#### tf.python_io.TFRecordWriter.close() {#TFRecordWriter.close} + +Close the file. + + + +- - - + +### tf.python_io.tf_record_iterator(path) <div class="md-anchor" id="tf_record_iterator">{#tf_record_iterator}</div> + +An iterator that read the records from a TFRecords file. + +##### Args: + + +* <b>path</b>: The path to the TFRecords file. + +##### Yields: + + Strings. + +##### Raises: + + +* <b>IOError</b>: If `path` cannot be opened for reading. + + + +- - - + +### TFRecords Format Details <div class="md-anchor" id="AUTOGENERATED-tfrecords-format-details">{#AUTOGENERATED-tfrecords-format-details}</div> + +A TFRecords file contains a sequence of strings with CRC hashes. Each record +has the format + + uint64 length + uint32 masked_crc32_of_length + byte data[length] + uint32 masked_crc32_of_data + +and the records are concatenated together to produce the file. The CRC32s +are [described here](https://en.wikipedia.org/wiki/Cyclic_redundancy_check), +and the mask of a CRC is + + masked_crc = ((crc >> 15) | (crc << 17)) + 0xa282ead8ul diff --git a/tensorflow/g3doc/api_docs/python/sparse_ops.md b/tensorflow/g3doc/api_docs/python/sparse_ops.md new file mode 100644 index 0000000000..7e9ab0775f --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/sparse_ops.md @@ -0,0 +1,502 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Sparse Tensors +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Sparse Tensor Representation.](#AUTOGENERATED-sparse-tensor-representation.) + * [class tf.SparseTensor](#SparseTensor) + * [class tf.SparseTensorValue](#SparseTensorValue) +* [Sparse to Dense Conversion.](#AUTOGENERATED-sparse-to-dense-conversion.) + * [tf.sparse_to_dense(sparse_indices, output_shape, sparse_values, default_value, name=None)](#sparse_to_dense) + * [tf.sparse_tensor_to_dense(sp_input, default_value, name=None)](#sparse_tensor_to_dense) + * [tf.sparse_to_indicator(sp_input, vocab_size, name=None)](#sparse_to_indicator) +* [Manipulation.](#AUTOGENERATED-manipulation.) + * [tf.sparse_concat(concat_dim, sp_inputs, name=None)](#sparse_concat) + * [tf.sparse_reorder(sp_input, name=None)](#sparse_reorder) + * [tf.sparse_retain(sp_input, to_retain)](#sparse_retain) + * [tf.sparse_fill_empty_rows(sp_input, default_value, name=None)](#sparse_fill_empty_rows) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Sparse Tensor Representation. <div class="md-anchor" id="AUTOGENERATED-sparse-tensor-representation.">{#AUTOGENERATED-sparse-tensor-representation.}</div> + +Tensorflow supports a `SparseTensor` representation for data that is sparse +in multiple dimensions. Contrast this representation with `IndexedSlices`, +which is efficient for representing tensors that are sparse in their first +dimension, and dense along all other dimensions. + +- - - + +### class tf.SparseTensor <div class="md-anchor" id="SparseTensor">{#SparseTensor}</div> + +Represents a sparse tensor. + +Tensorflow represents a sparse tensor as three separate dense tensors: +`indices`, `values`, and `dense_shape`. In Python, the three tensors are +collected into a `SparseTensor` class for ease of use. If you have separate +`indices`, `values`, and `dense_shape` tensors, wrap them in a `SparseTensor` +object before passing to the Ops below. + +Concretely, the sparse tensor `SparseTensor(values, indices, dense_shape)` is + +* `indices`: A 2-D int64 tensor of shape `[N, ndims]`. +* `values`: A 1-D tensor of any type and shape `[N]`. +* `dense_shape`: A 1-D int64 tensor of shape `[ndims]`. + +where `N` and `ndims` are the number of values, and number of dimensions in +the `SparseTensor` respectively. + +The corresponding dense tensor satisfies + +```python +dense.shape = dense_shape +dense[tuple(indices[i])] = values[i] +``` + +By convention, `indices` should be sorted in row-major order (or equivalently +lexigraphic order on the tuples `indices[i]`). This is not enforced when +`SparseTensor` objects are constructed, but most Ops assume correct ordering. +If the ordering is wrong, it can be fixed by calling `sparse_reorder` on the +misordered `SparseTensor`. + +Example: The sparse tensor + +```python + SparseTensor(values=[1, 2], indices=[[0, 0], [1, 2]], shape=[3, 4]) +``` + +represents the dense tensor + +```python + [[1, 0, 0, 0] + [0, 0, 2, 0] + [0, 0, 0, 0]] +``` + +- - - + +#### tf.SparseTensor.__init__(indices, values, shape) {#SparseTensor.__init__} + +Creates a `SparseTensor`. + +##### Args: + + +* <b>indices</b>: A 2-D int64 tensor of shape `[N, ndims]`. +* <b>values</b>: A 1-D tensor of any type and shape `[N]`. +* <b>dense_shape</b>: A 1-D int64 tensor of shape `[ndims]`. + +##### Returns: + + A `SparseTensor` + + +- - - + +#### tf.SparseTensor.indices {#SparseTensor.indices} + +The indices of non-zero values in the represented dense tensor. + +##### Returns: + + A 2-D Tensor of int64 with shape `[N, ndims]`, where `N` is the + number of non-zero values in the tensor, and `ndims` is the rank. + +- - - + +#### tf.SparseTensor.values {#SparseTensor.values} + +The non-zero values in the represented dense tensor. + +##### Returns: + + A 1-D Tensor of any data type. + +- - - + +#### tf.SparseTensor.dtype {#SparseTensor.dtype} + +The `DType` of elements in this tensor. + +- - - + +#### tf.SparseTensor.shape {#SparseTensor.shape} + +A 1-D Tensor of int64 representing the shape of the dense tensor. + +- - - + +#### tf.SparseTensor.graph {#SparseTensor.graph} + +The `Graph` that contains the index, value, and shape tensors. + + +- - - + +### class tf.SparseTensorValue <div class="md-anchor" id="SparseTensorValue">{#SparseTensorValue}</div> + +SparseTensorValue(indices, values, shape) +- - - + +#### tf.SparseTensorValue.indices {#SparseTensorValue.indices} + +Alias for field number 0 + +- - - + +#### tf.SparseTensorValue.shape {#SparseTensorValue.shape} + +Alias for field number 2 + +- - - + +#### tf.SparseTensorValue.values {#SparseTensorValue.values} + +Alias for field number 1 + + + +## Sparse to Dense Conversion. <div class="md-anchor" id="AUTOGENERATED-sparse-to-dense-conversion.">{#AUTOGENERATED-sparse-to-dense-conversion.}</div> + +- - - + +### tf.sparse_to_dense(sparse_indices, output_shape, sparse_values, default_value, name=None) <div class="md-anchor" id="sparse_to_dense">{#sparse_to_dense}</div> + +Converts a sparse representation into a dense tensor. + +Builds an array `dense` with shape `output_shape` such that + +```prettyprint +# If sparse_indices is scalar +dense[i] = (i == sparse_indices ? sparse_values : default_value) + +# If sparse_indices is a vector, then for each i +dense[sparse_indices[i]] = sparse_values[i] + +# If sparse_indices is an n by d matrix, then for each i in [0, n) +dense[sparse_indices[i][0], ..., sparse_indices[i][d-1]] = sparse_values[i] +``` + +All other values in `dense` are set to `default_value`. If `sparse_values` is a +scalar, all sparse indices are set to this single value. + +##### Args: + + +* <b>sparse_indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + 0-D, 1-D, or 2-D. `sparse_indices[i]` contains the complete + index where `sparse_values[i]` will be placed. +* <b>output_shape</b>: A `Tensor`. Must have the same type as `sparse_indices`. + 1-D. Shape of the dense output tensor. +* <b>sparse_values</b>: A `Tensor`. + 1-D. Values corresponding to each row of `sparse_indices`, + or a scalar value to be used for all sparse indices. +* <b>default_value</b>: A `Tensor`. Must have the same type as `sparse_values`. + Scalar value to set for indices not specified in + `sparse_indices`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `sparse_values`. + Dense output tensor of shape `output_shape`. + + +- - - + +### tf.sparse_tensor_to_dense(sp_input, default_value, name=None) <div class="md-anchor" id="sparse_tensor_to_dense">{#sparse_tensor_to_dense}</div> + +Converts a `SparseTensor` into a dense tensor. + +This op is a convenience wrapper around `sparse_to_dense` for `SparseTensor`s. + +For example, if `sp_input` has shape `[3, 5]` and non-empty string values: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + +and `default_value` is `x`, then the output will be a dense `[3, 5]` +string tensor with values: + + [[x a x b x] + [x x x x x] + [c x x x x]] + +##### Args: + + +* <b>sp_input</b>: The input `SparseTensor`. +* <b>default_value</b>: Scalar value to set for indices not specified in + `sp_input`. +* <b>name</b>: A name prefix for the returned tensors (optional). + +##### Returns: + + A dense tensor with shape `sp_input.shape` and values specified by + the non-empty values in `sp_input`. Indices not in `sp_input` are assigned + `default_value`. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + +- - - + +### tf.sparse_to_indicator(sp_input, vocab_size, name=None) <div class="md-anchor" id="sparse_to_indicator">{#sparse_to_indicator}</div> + +Converts a `SparseTensor` of ids into a dense bool indicator tensor. + +The last dimension of `sp_input` is discarded and replaced with the values of +`sp_input`. If `sp_input.shape = [D0, D1, ..., Dn, K]`, then +`output.shape = [D0, D1, ..., Dn, vocab_size]`, where + + output[d_0, d_1, ..., d_n, sp_input[d_0, d_1, ..., d_n, k]] = True + +and False elsewhere in `output`. + +For example, if `sp_input.shape = [2, 3, 4]` with non-empty values: + + [0, 0, 0]: 0 + [0, 1, 0]: 10 + [1, 0, 3]: 103 + [1, 1, 2]: 112 + [1, 1, 3]: 113 + [1, 2, 1]: 121 + +and `vocab_size = 200`, then the output will be a `[2, 3, 200]` dense bool +tensor with False everywhere except at positions + + (0, 0, 0), (0, 1, 10), (1, 0, 103), (1, 1, 112), (1, 1, 113), (1, 2, 121). + +This op is useful for converting `SparseTensor`s into dense formats for +compatibility with ops that expect dense tensors. + +The input `SparseTensor` must be in row-major order. + +##### Args: + + +* <b>sp_input</b>: A `SparseTensor` of type `int32` or `int64`. +* <b>vocab_size</b>: The new size of the last dimension, with + `all(0 <= sp_input.values < vocab_size)`. +* <b>name</b>: A name prefix for the returned tensors (optional) + +##### Returns: + + A dense bool indicator tensor representing the indices with specified value. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + + +## Manipulation. <div class="md-anchor" id="AUTOGENERATED-manipulation.">{#AUTOGENERATED-manipulation.}</div> + +- - - + +### tf.sparse_concat(concat_dim, sp_inputs, name=None) <div class="md-anchor" id="sparse_concat">{#sparse_concat}</div> + +Concatenates a list of `SparseTensor` along the specified dimension. + +Concatenation is with respect to the dense versions of each sparse input. +It is assumed that each inputs is a `SparseTensor` whose elements are ordered +along increasing dimension number. + +All inputs' shapes must match, except for the concat dimension. The +`indices`, `values`, and `shapes` lists must have the same length. + +The output shape is identical to the inputs', except along the concat +dimension, where it is the sum of the inputs' sizes along that dimension. + +The output elements will be resorted to preserve the sort order along +increasing dimension number. + +This op runs in `O(M log M)` time, where `M` is the total number of non-empty +values across all inputs. This is due to the need for an internal sort in +order to concatenate efficiently across an arbitrary dimension. + +For example, if `concat_dim = 1` and the inputs are + + sp_inputs[0]: shape = [2, 3] + [0, 2]: "a" + [1, 0]: "b" + [1, 1]: "c" + + sp_inputs[1]: shape = [2, 4] + [0, 1]: "d" + [0, 2]: "e" + +then the output will be + + shape = [2, 7] + [0, 2]: "a" + [0, 4]: "d" + [0, 5]: "e" + [1, 0]: "b" + [1, 1]: "c" + +Graphically this is equivalent to doing + + [ a] concat [ d e ] = [ a d e ] + [b c ] [ ] [b c ] + +##### Args: + + +* <b>concat_dim</b>: Dimension to concatenate along. +* <b>sp_inputs</b>: List of `SparseTensor` to concatenate. +* <b>name</b>: A name prefix for the returned tensors (optional). + +##### Returns: + + A `SparseTensor` with the concatenated output. + +##### Raises: + + +* <b>TypeError</b>: If `sp_inputs` is not a list of `SparseTensor`. + + +- - - + +### tf.sparse_reorder(sp_input, name=None) <div class="md-anchor" id="sparse_reorder">{#sparse_reorder}</div> + +Reorders a `SparseTensor` into the canonical, row-major ordering. + +Note that by convention, all sparse ops preserve the canonical ordering +along increasing dimension number. The only time ordering can be violated +is during manual manipulation of the indices and values to add entries. + +Reordering does not affect the shape of the `SparseTensor`. + +For example, if sp_input has shape `[4, 5]` and `indices` / `values`: + + [0, 3]: b + [0, 1]: a + [3, 1]: d + [2, 0]: c + +then the output will be a `SparseTensor` of shape `[4, 5]` and +`indices` / `values`: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + [3, 1]: d + +##### Args: + + +* <b>sp_input</b>: The input `SparseTensor`. +* <b>name</b>: A name prefix for the returned tensors (optional) + +##### Returns: + + A `SparseTensor` with the same shape and non-empty values, but in + canonical ordering. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + +- - - + +### tf.sparse_retain(sp_input, to_retain) <div class="md-anchor" id="sparse_retain">{#sparse_retain}</div> + +Retains specified non-empty values within a `SparseTensor`. + +For example, if `sp_input` has shape `[4, 5]` and 4 non-empty string values: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + [3, 1]: d + +and `to_retain = [True, False, False, True]`, then the output will +be a `SparseTensor` of shape `[4, 5]` with 2 non-empty values: + + [0, 1]: a + [3, 1]: d + +##### Args: + + +* <b>sp_input</b>: The input `SparseTensor` with `N` non-empty elements. +* <b>to_retain</b>: A bool vector of length `N` with `M` true values. + +##### Returns: + + A `SparseTensor` with the same shape as the input and `M` non-empty + elements corresponding to the true positions in `to_retain`. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + +- - - + +### tf.sparse_fill_empty_rows(sp_input, default_value, name=None) <div class="md-anchor" id="sparse_fill_empty_rows">{#sparse_fill_empty_rows}</div> + +Fills empty rows in the input 2-D `SparseTensor` with a default value. + +This op adds entries with the specified `default_value` at index +`[row, 0]` for any row in the input that does not already have a value. + +For example, suppose `sp_input` has shape `[5, 6]` and non-empty values: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + [3, 1]: d + +Rows 1 and 4 are empty, so the output will be of shape `[5, 6]` with values: + + [0, 1]: a + [0, 3]: b + [1, 0]: default_value + [2, 0]: c + [3, 1]: d + [4, 0]: default_value + +Note that the input may have empty columns at the end, with no effect on +this op. + +The output `SparseTensor` will be in row-major order and will have the +same shape as the input. + +This op also returns an indicator vector such that + + empty_row_indicator[i] = True iff row i was an empty row. + +##### Args: + + +* <b>sp_input</b>: A `SparseTensor` with shape `[N, M]`. +* <b>default_value</b>: The value to fill for empty rows, with the same type as + `sp_input.` +* <b>name</b>: A name prefix for the returned tensors (optional) + +##### Returns: + + +* <b>sp_ordered_output</b>: A `SparseTensor` with shape `[N, M]`, and with all empty + rows filled in with `default_value`. +* <b>empty_row_indicator</b>: A bool vector of length `N` indicating whether each + input row was empty. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + diff --git a/tensorflow/g3doc/api_docs/python/state_ops.md b/tensorflow/g3doc/api_docs/python/state_ops.md new file mode 100644 index 0000000000..70d912178b --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/state_ops.md @@ -0,0 +1,1383 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Variables +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Variables](#AUTOGENERATED-variables) + * [class tf.Variable](#Variable) +* [Variable helper functions](#AUTOGENERATED-variable-helper-functions) + * [tf.all_variables()](#all_variables) + * [tf.trainable_variables()](#trainable_variables) + * [tf.initialize_all_variables()](#initialize_all_variables) + * [tf.initialize_variables(var_list, name='init')](#initialize_variables) + * [tf.assert_variables_initialized(var_list=None)](#assert_variables_initialized) +* [Saving and Restoring Variables.](#AUTOGENERATED-saving-and-restoring-variables.) + * [class tf.train.Saver](#Saver) + * [tf.train.latest_checkpoint(checkpoint_dir, latest_filename=None)](#latest_checkpoint) + * [tf.train.get_checkpoint_state(checkpoint_dir, latest_filename=None)](#get_checkpoint_state) + * [tf.train.update_checkpoint_state(save_dir, model_checkpoint_path, all_model_checkpoint_paths=None, latest_filename=None)](#update_checkpoint_state) +* [Sharing Variables](#AUTOGENERATED-sharing-variables) + * [tf.get_variable(name, shape=None, dtype=tf.float32, initializer=None, trainable=True, collections=None)](#get_variable) + * [tf.get_variable_scope()](#get_variable_scope) + * [tf.variable_scope(*args, **kwds)](#variable_scope) + * [tf.constant_initializer(value=0.0)](#constant_initializer) + * [tf.random_normal_initializer(mean=0.0, stddev=1.0, seed=None)](#random_normal_initializer) + * [tf.truncated_normal_initializer(mean=0.0, stddev=1.0, seed=None)](#truncated_normal_initializer) + * [tf.random_uniform_initializer(minval=0.0, maxval=1.0, seed=None)](#random_uniform_initializer) + * [tf.uniform_unit_scaling_initializer(factor=1.0, seed=None)](#uniform_unit_scaling_initializer) + * [tf.zeros_initializer(shape, dtype=tf.float32)](#zeros_initializer) +* [Sparse Variable Updates](#AUTOGENERATED-sparse-variable-updates) + * [tf.scatter_update(ref, indices, updates, use_locking=None, name=None)](#scatter_update) + * [tf.scatter_add(ref, indices, updates, use_locking=None, name=None)](#scatter_add) + * [tf.scatter_sub(ref, indices, updates, use_locking=None, name=None)](#scatter_sub) + * [tf.sparse_mask(a, mask_indices, name=None)](#sparse_mask) + * [class tf.IndexedSlices](#IndexedSlices) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Variables <div class="md-anchor" id="AUTOGENERATED-variables">{#AUTOGENERATED-variables}</div> + +- - - + +### class tf.Variable <div class="md-anchor" id="Variable">{#Variable}</div> + +See the [Variables How To](../../how_tos/variables/index.md) for a high +level overview. + +A variable maintains state in the graph across calls to `run()`. You add a +variable to the graph by constructing an instance of the class `Variable`. + +The `Variable()` constructor requires an initial value for the variable, +which can be a `Tensor` of any type and shape. The initial value defines the +type and shape of the variable. After construction, the type and shape of +the variable are fixed. The value can be changed using one of the assign +methods. + +If you want to change the shape of a variable later you have to use an +`assign` Op with `validate_shape=False`. + +Just like any `Tensor`, variables created with `Variable()` can be used as +inputs for other Ops in the graph. Additionally, all the operators +overloaded for the `Tensor` class are carried over to variables, so you can +also add nodes to the graph by just doing arithmetic on variables. + +```python +import tensorflow as tf + +# Create a variable. +w = tf.Variable(<initial-value>, name=<optional-name>) + +# Use the variable in the graph like any Tensor. +y = tf.matmul(w, ...another variable or tensor...) + +# The overloaded operators are available too. +z = tf.sigmoid(w + b) + +# Assign a new value to the variable with `assign()` or a related method. +w.assign(w + 1.0) +w.assign_add(1.0) +``` + +When you launch the graph, variables have to be explicitly initialized before +you can run Ops that use their value. You can initialize a variable by +running its *initializer op*, restoring the variable from a save file, or +simply running an `assign` Op that assigns a value to the variable. In fact, +the variable *initializer op* is just an `assign` Op that assigns the +variable's initial value to the variable itself. + +```python +# Launch the graph in a session. +with tf.Session() as sess: + # Run the variable initializer. + sess.run(w.initializer) + # ...you now can run ops that use the value of 'w'... +``` + +The most common initialization pattern is to use the convenience function +`initialize_all_variables()` to add an Op to the graph that initializes +all the variables. You then run that Op after launching the graph. + +```python +# Add an Op to initialize all variables. +init_op = tf.initialize_all_variables() + +# Launch the graph in a session. +with tf.Session() as sess: + # Run the Op that initializes all variables. + sess.run(init_op) + # ...you can now run any Op that uses variable values... +``` + +If you need to create a variable with an initial value dependent on another +variable, use the other variable's `initialized_value()`. This ensures that +variables are initialized in the right order. + +All variables are automatically collected in the graph where they are +created. By default, the constructor adds the new variable to the graph +collection `GraphKeys.VARIABLES`. The convenience function +`all_variables()` returns the contents of that collection. + +When building a machine learning model it is often convenient to distinguish +betwen variables holding the trainable model parameters and other variables +such as a `global step` variable used to count training steps. To make this +easier, the variable constructor supports a `trainable=<bool>` parameter. If +`True`, the new variable is also added to the graph collection +`GraphKeys.TRAINABLE_VARIABLES`. The convenience function +`trainable_variables()` returns the contents of this collection. The +various `Optimizer` classes use this collection as the default list of +variables to optimize. + + +Creating a variable. + +- - - + +#### tf.Variable.__init__(initial_value, trainable=True, collections=None, validate_shape=True, name=None) {#Variable.__init__} + +Creates a new variable with value `initial_value`. + +The new variable is added to the graph collections listed in `collections`, +which defaults to `[GraphKeys.VARIABLES]`. + +If `trainable` is `True` the variable is also added to the graph collection +`GraphKeys.TRAINABLE_VARIABLES`. + +This constructor creates both a `variable` Op and an `assign` Op to set the +variable to its initial value. + +##### Args: + + +* <b>initial_value</b>: A `Tensor`, or Python object convertible to a `Tensor`. + The initial value for the Variable. Must have a shape specified unless + `validate_shape` is set to False. +* <b>trainable</b>: If `True`, the default, also adds the variable to the graph + collection `GraphKeys.TRAINABLE_VARIABLES`. This collection is used as + the default list of variables to use by the `Optimizer` classes. +* <b>collections</b>: List of graph collections keys. The new variable is added to + these collections. Defaults to `[GraphKeys.VARIABLES]`. +* <b>validate_shape</b>: If `False`, allows the variable to be initialized with a + value of unknown shape. If `True`, the default, the shape of + `initial_value` must be known. +* <b>name</b>: Optional name for the variable. Defaults to `'Variable'` and gets + uniquified automatically. + +##### Returns: + + A Variable. + +##### Raises: + + +* <b>ValueError</b>: If the initial value does not have a shape and + `validate_shape` is `True`. + + +- - - + +#### tf.Variable.initialized_value() {#Variable.initialized_value} + +Returns the value of the initialized variable. + +You should use this instead of the variable itself to initialize another +variable with a value that depends on the value of this variable. + +```python +# Initialize 'v' with a random tensor. +v = tf.Variable(tf.truncated_normal([10, 40])) +# Use `initialized_value` to guarantee that `v` has been +# initialized before its value is used to initialize `w`. +# The random values are picked only once. +w = tf.Variable(v.initialized_value() * 2.0) +``` + +##### Returns: + + A `Tensor` holding the value of this variable after its initializer + has run. + + + +Changing a variable value. + +- - - + +#### tf.Variable.assign(value, use_locking=False) {#Variable.assign} + +Assigns a new value to the variable. + +This is essentially a shortcut for `assign(self, value)`. + +##### Args: + + +* <b>value</b>: A `Tensor`. The new value for this variable. +* <b>use_locking</b>: If `True`, use locking during the assignment. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the assignment has completed. + + +- - - + +#### tf.Variable.assign_add(delta, use_locking=False) {#Variable.assign_add} + +Adds a value to this variable. + + This is essentially a shortcut for `assign_add(self, delta)`. + +##### Args: + + +* <b>delta</b>: A `Tensor`. The value to add to this variable. +* <b>use_locking</b>: If `True`, use locking during the operation. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the addition has completed. + + +- - - + +#### tf.Variable.assign_sub(delta, use_locking=False) {#Variable.assign_sub} + +Subtracts a value from this variable. + +This is essentially a shortcut for `assign_sub(self, delta)`. + +##### Args: + + +* <b>delta</b>: A `Tensor`. The value to subtract from this variable. +* <b>use_locking</b>: If `True`, use locking during the operation. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the subtraction has completed. + + +- - - + +#### tf.Variable.scatter_sub(sparse_delta, use_locking=False) {#Variable.scatter_sub} + +Subtracts `IndexedSlices` from this variable. + +This is essentially a shortcut for `scatter_sub(self, sparse_delta.indices, +sparse_delta.values)`. + +##### Args: + + +* <b>sparse_delta</b>: `IndexedSlices` to be subtracted from this variable. +* <b>use_locking</b>: If `True`, use locking during the operation. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the scattered subtraction has completed. + +##### Raises: + + +* <b>ValueError</b>: if `sparse_delta` is not an `IndexedSlices`. + + +- - - + +#### tf.Variable.count_up_to(limit) {#Variable.count_up_to} + +Increments this variable until it reaches `limit`. + +When that Op is run it tries to increment the variable by `1`. If +incrementing the variable would bring it above `limit` then the Op raises +the exception `OutOfRangeError`. + +If no error is raised, the Op outputs the value of the variable before +the increment. + +This is essentially a shortcut for `count_up_to(self, limit)`. + +##### Args: + + +* <b>limit</b>: value at which incrementing the variable raises an error. + +##### Returns: + + A `Tensor` that will hold the variable value before the increment. If no + other Op modifies this variable, the values produced will all be + distinct. + + + +- - - + +#### tf.Variable.eval(session=None) {#Variable.eval} + +In a session, computes and returns the value of this variable. + +This is not a graph construction method, it does not add ops to the graph. + +This convenience method requires a session where the graph containing this +variable has been launched. If no session is passed, the default session is +used. See the [Session class](../client.md#Session) for more information on +launching a graph and on sessions. + +```python +v = tf.Variable([1, 2]) +init = tf.initialize_all_variables() + +with tf.Session() as sess: + sess.run(init) + # Usage passing the session explicitly. + print v.eval(sess) + # Usage with the default session. The 'with' block + # above makes 'sess' the default session. + print v.eval() +``` + +##### Args: + + +* <b>session</b>: The session to use to evaluate this variable. If + none, the default session is used. + +##### Returns: + + A numpy `ndarray` with a copy of the value of this variable. + + + +Properties. + +- - - + +#### tf.Variable.name {#Variable.name} + +The name of this variable. + +- - - + +#### tf.Variable.dtype {#Variable.dtype} + +The `DType` of this variable. + +- - - + +#### tf.Variable.get_shape() {#Variable.get_shape} + +The `TensorShape` of this variable. + +##### Returns: + + A `TensorShape`. + + +- - - + +#### tf.Variable.device {#Variable.device} + +The device of this variable. + +- - - + +#### tf.Variable.initializer {#Variable.initializer} + +The initializer operation for this variable. + +- - - + +#### tf.Variable.graph {#Variable.graph} + +The `Graph` of this variable. + +- - - + +#### tf.Variable.op {#Variable.op} + +The `Operation` of this variable. + + + +## Variable helper functions <div class="md-anchor" id="AUTOGENERATED-variable-helper-functions">{#AUTOGENERATED-variable-helper-functions}</div> + +TensorFlow provides a set of functions to help manage the set of variables +collected in the graph. + +- - - + +### tf.all_variables() <div class="md-anchor" id="all_variables">{#all_variables}</div> + +Returns all variables collected in the graph. + +The `Variable()` constructor automatically adds new variables to the graph +collection `GraphKeys.VARIABLES`. This convenience function returns the +contents of that collection. + +##### Returns: + + A list of `Variable` objects. + + +- - - + +### tf.trainable_variables() <div class="md-anchor" id="trainable_variables">{#trainable_variables}</div> + +Returns all variables created with `trainable=True`. + +When passed `trainable=True`, the `Variable()` constructor automatically +adds new variables to the graph collection +`GraphKeys.TRAINABLE_VARIABLES`. This convenience function returns the +contents of that collection. + +##### Returns: + + A list of Variable objects. + + + +- - - + +### tf.initialize_all_variables() <div class="md-anchor" id="initialize_all_variables">{#initialize_all_variables}</div> + +Returns an Op that initializes all variables. + +This is just a shortcut for `initialize_variables(all_variables())` + +##### Returns: + + An Op that initializes all variables in the graph. + + +- - - + +### tf.initialize_variables(var_list, name='init') <div class="md-anchor" id="initialize_variables">{#initialize_variables}</div> + +Returns an Op that initializes a list of variables. + +After you launch the graph in a session, you can run the returned Op to +initialize all the variables in `var_list`. This Op runs all the +initializers of the variables in `var_list` in parallel. + +Calling `initialize_variables()` is equivalent to passing the list of +initializers to `Group()`. + +If `var_list` is empty, however, the function still returns an Op that can +be run. That Op just has no effect. + +##### Args: + + +* <b>var_list</b>: List of `Variable` objects to initialize. +* <b>name</b>: Optional name for the returned operation. + +##### Returns: + + An Op that run the initializers of all the specified variables. + + +- - - + +### tf.assert_variables_initialized(var_list=None) <div class="md-anchor" id="assert_variables_initialized">{#assert_variables_initialized}</div> + +Returns an Op to check if variables are initialized. + +When run, the returned Op will raise the exception `FailedPreconditionError` +if any of the variables has not yet been initialized. + +Note: This function is implemented by trying to fetch the values of the +variables. If one of the variables is not initialized a message may be +logged by the C++ runtime. This is expected. + +##### Args: + + +* <b>var_list</b>: List of `Variable` objects to check. Defaults to the + value of `all_variables().` + +##### Returns: + + An Op, or None if there are no variables. + + + +## Saving and Restoring Variables. <div class="md-anchor" id="AUTOGENERATED-saving-and-restoring-variables.">{#AUTOGENERATED-saving-and-restoring-variables.}</div> + +- - - + +### class tf.train.Saver <div class="md-anchor" id="Saver">{#Saver}</div> + +Saves and restores variables. + +See [Variables](../../how_tos/variables/index.md) +for an overview of variables, saving and restoring. + +The `Saver` class adds ops to save and restore variables to and from +*checkpoints*. It also provides convenience methods to run these ops. + +Checkpoints are binary files in a proprietary format which map variable names +to tensor values. The best way to examine the contents of a checkpoint is to +load it using a `Saver`. + +Savers can automatically number checkpoint filenames with a provided counter. +This lets you keep multiple checkpoints at different steps while training a +model. For example you can number the checkpoint filenames with the training +step number. To avoid filling up disks, savers manage checkpoint files +automatically. For example, they can keep only the N most recent files, or +one checkpoint for every N hours of training. + +You number checkpoint filenames by passing a value to the optional +`global_step` argument to `save()`: + +```python +saver.save('my-model', global_step=0) ==> filename: 'my-model-0' +... +saver.save('my-model', global_step=1000) ==> filename: 'my-model-1000' +``` + +Additionally, optional arguments to the `Saver()` constructor let you control +the proliferation of checkpoint files on disk: + +* `max_to_keep` indicates the maximum number of recent checkpoint files to + keep. As new files are created, older files are deleted. If None or 0, + all checkpoint files are kept. Defaults to 5 (that is, the 5 most recent + checkpoint files are kept.) + +* `keep_checkpoint_every_n_hours`: In addition to keeping the most recent + `max_to_keep` checkpoint files, you might want to keep one checkpoint file + for every N hours of training. This can be useful if you want to later + analyze how a model progressed during a long training session. For + example, passing `keep_checkpoint_every_n_hours=2` ensures that you keep + one checkpoint file for every 2 hours of training. The default value of + 10,000 hours effectively disables the feature. + +Note that you still have to call the `save()` method to save the model. +Passing these arguments to the constructor will not save variables +automatically for you. + +A training program that saves regularly looks like: + +```python +... +# Create a saver. +saver = tf.train.Saver(...variables...) +# Launch the graph and train, saving the model every 1,000 steps. +sess = tf.Session() +for step in xrange(1000000): + sess.run(..training_op..) + if step % 1000 == 0: + # Append the step number to the checkpoint name: + saver.save(sess, 'my-model', global_step=step) +``` + +In addition to checkpoint files, savers keep a protocol buffer on disk with +the list of recent checkpoints. This is used to manage numbered checkpoint +files and by `latest_checkpoint()`, which makes it easy to discover the path +to the most recent checkpoint. That protocol buffer is stored in a file named +'checkpoint' next to the checkpoint files. + +If you create several savers, you can specify a different filename for the +protocol buffer file in the call to `save()`. + +- - - + +#### tf.train.Saver.__init__(var_list=None, reshape=False, sharded=False, max_to_keep=5, keep_checkpoint_every_n_hours=10000.0, name=None, restore_sequentially=False, saver_def=None, builder=None) {#Saver.__init__} + +Creates a `Saver`. + +The constructor adds ops to save and restore variables. + +`var_list` specifies the variables that will be saved and restored. It can +be passed as a `dict` or a list: + +* A `dict` of names to variables: The keys are the names that will be + used to save or restore the variables in the checkpoint files. +* A list of variables: The variables will be keyed with their op name in + the checkpoint files. + +For example: + +```python +v1 = tf.Variable(..., name='v1') +v2 = tf.Variable(..., name='v2') + +# Pass the variables as a dict: +saver = tf.train.Saver({'v1': v1, 'v2': v2}) + +# Or pass them as a list. +saver = tf.train.Saver([v1, v2]) +# Passing a list is equivalent to passing a dict with the variable op names +# as keys: +saver = tf.train.Saver({v.op.name: v for v in [v1, v2]}) +``` + +The optional `reshape` argument, if True, allows restoring a variable from +a save file where the variable had a different shape, but the same number +of elements and type. This is useful if you have reshaped a variable and +want to reload it from an older checkpoint. + +The optional `sharded` argument, if True, instructs the saver to shard +checkpoints per device. + +##### Args: + + +* <b>var_list</b>: A list of Variables or a dictionary mapping names to + Variables. If None, defaults to the list of all variables. +* <b>reshape</b>: If True, allows restoring parameters from a checkpoint + where the variables have a different shape. +* <b>sharded</b>: If True, shard the checkpoints, one per device. +* <b>max_to_keep</b>: maximum number of recent checkpoints to keep. + Defaults to 10,000 hours. +* <b>keep_checkpoint_every_n_hours</b>: How often to keep checkpoints. + Defaults to 10,000 hours. +* <b>name</b>: string. Optional name to use as a prefix when adding operations. +* <b>restore_sequentially</b>: A Bool, which if true, causes restore of different + variables to happen sequentially within each device. This can lower + memory usage when restoring very large models. +* <b>saver_def</b>: Optional SaverDef proto to use instead of running the builder. + This is only useful for specialty code that wants to recreate a Saver + object for a previously built Graph that had a Saver. The saver_def + proto should be the one returned by the as_saver_def() call of the + Saver that was created for that Graph. +* <b>builder</b>: Optional SaverBuilder to use if a saver_def was not provided. + Defaults to BaseSaverBuilder(). + +##### Raises: + + +* <b>TypeError</b>: If `var_list` is invalid. +* <b>ValueError</b>: If any of the keys or values in `var_list` is not unique. + + +- - - + +#### tf.train.Saver.save(sess, save_path, global_step=None, latest_filename=None) {#Saver.save} + +Saves variables. + +This method runs the ops added by the constructor for saving variables. +It requires a session in which the graph was launched. The variables to +save must also have been initialized. + +The method returns the path of the newly created checkpoint file. This +path can be passed directly to a call to `restore()`. + +##### Args: + + +* <b>sess</b>: A Session to use to save the variables.. +* <b>save_path</b>: string. Path to the checkpoint filename. If the saver is + `sharded`, this is the prefix of the sharded checkpoint filename. +* <b>global_step</b>: If provided the global step number is appended to + `save_path` to create the checkpoint filename. The optional argument + can be a Tensor, a Tensor name or an integer. +* <b>latest_filename</b>: Optional name for the protocol buffer file that will + contains the list of most recent checkpoint filenames. That file, + kept in the same directory as the checkpoint files, is automatically + managed by the saver to keep track of recent checkpoints. Defaults to + 'checkpoint'. + +##### Returns: + + A string: path at which the variables were saved. If the saver is + sharded, this string ends with: '-?????-of-nnnnn' where 'nnnnn' + is the number of shards created. + +##### Raises: + + +* <b>TypeError</b>: If `sess` is not a Session. + + +- - - + +#### tf.train.Saver.restore(sess, save_path) {#Saver.restore} + +Restores previously saved variables. + +This method runs the ops added by the constructor for restoring variables. +It requires a session in which the graph was launched. The variables to +restore do not have to have been initialized, as restoring is itself a way +to initialize variables. + +The `save_path` argument is typically a value previously returned from a +`save()` call, or a call to `latest_checkpoint()`. + +##### Args: + + +* <b>sess</b>: A Session to use to restore the parameters. +* <b>save_path</b>: Path where parameters were previously saved. + + + +Other utility methods. + +- - - + +#### tf.train.Saver.last_checkpoints {#Saver.last_checkpoints} + +List of not-yet-deleted checkpoint filenames. + +You can pass any of the returned values to `restore()`. + +##### Returns: + + A list of checkpoint filenames, sorted from oldest to newest. + +- - - + +#### tf.train.Saver.set_last_checkpoints(last_checkpoints) {#Saver.set_last_checkpoints} + +Sets the list of not-yet-deleted checkpoint filenames. + +##### Args: + + +* <b>last_checkpoints</b>: a list of checkpoint filenames. + +##### Raises: + + +* <b>AssertionError</b>: if the list of checkpoint filenames has already been set. + + +- - - + +#### tf.train.Saver.as_saver_def() {#Saver.as_saver_def} + +Generates a `SaverDef` representation of this saver. + +##### Returns: + + A `SaverDef` proto. + + + + +- - - + +### tf.train.latest_checkpoint(checkpoint_dir, latest_filename=None) <div class="md-anchor" id="latest_checkpoint">{#latest_checkpoint}</div> + +Finds the filename of latest saved checkpoint file. + +##### Args: + + +* <b>checkpoint_dir</b>: Directory where the variables were saved. +* <b>latest_filename</b>: Optional name for the protocol buffer file that + contains the list of most recent checkpoint filenames. + See the corresponding argument to `Saver.save()`. + +##### Returns: + + The full path to the latest checkpoint or None if no checkpoint was found. + + + +- - - + +### tf.train.get_checkpoint_state(checkpoint_dir, latest_filename=None) <div class="md-anchor" id="get_checkpoint_state">{#get_checkpoint_state}</div> + +Returns CheckpointState proto from the "checkpoint" file. + +If the "checkpoint" file contains a valid CheckpointState +proto, returns it. + +##### Args: + + +* <b>checkpoint_dir</b>: The directory of checkpoints. +* <b>latest_filename</b>: Optional name of the checkpoint file. Default to + 'checkpoint'. + +##### Returns: + + A CheckpointState if the state was available, None + otherwise. + + +- - - + +### tf.train.update_checkpoint_state(save_dir, model_checkpoint_path, all_model_checkpoint_paths=None, latest_filename=None) <div class="md-anchor" id="update_checkpoint_state">{#update_checkpoint_state}</div> + +Updates the content of the 'checkpoint' file. + +This updates the checkpoint file containing a CheckpointState +proto. + +##### Args: + + +* <b>save_dir</b>: Directory where the model was saved. +* <b>model_checkpoint_path</b>: The checkpoint file. +* <b>all_model_checkpoint_paths</b>: list of strings. Paths to all not-yet-deleted + checkpoints, sorted from oldest to newest. If this is a non-empty list, + the last element must be equal to model_checkpoint_path. These paths + are also saved in the CheckpointState proto. +* <b>latest_filename</b>: Optional name of the checkpoint file. Default to + 'checkpoint'. + +##### Raises: + + +* <b>RuntimeError</b>: If the save paths conflict. + + + +## Sharing Variables <div class="md-anchor" id="AUTOGENERATED-sharing-variables">{#AUTOGENERATED-sharing-variables}</div> + +TensorFlow provides several classes and operations that you can use to +create variables contingent on certain conditions. + +- - - + +### tf.get_variable(name, shape=None, dtype=tf.float32, initializer=None, trainable=True, collections=None) <div class="md-anchor" id="get_variable">{#get_variable}</div> + +Gets an existing variable with these parameters or create a new one. + +This function prefixes the name with the current variable scope +and performs reuse checks. See the +[Variable Scope How To](../../how_tos/variable_scope/index.md) +for an extensive description of how reusing works. Here is a basic example: + +```python +with tf.variable_scope("foo"): + v = get_variable("v", [1]) # v.name == "foo/v:0" + w = get_variable("w", [1]) # w.name == "foo/w:0" +with tf.variable_scope("foo", reuse=True) + v1 = get_variable("v") # The same as v above. +``` + +If initializer is `None` (the default), the default initializer passed in +the constructor is used. If that one is `None` too, a +`UniformUnitScalingInitializer` will be used. + +##### Args: + + +* <b>name</b>: the name of the new or existing variable. +* <b>shape</b>: shape of the new or existing variable. +* <b>dtype</b>: type of the new or existing variable (defaults to `DT_FLOAT`). +* <b>initializer</b>: initializer for the variable if one is created. +* <b>trainable</b>: If `True` also add the variable to the graph collection + `GraphKeys.TRAINABLE_VARIABLES` (see variables.Variable). +* <b>collections</b>: List of graph collections keys to add the Variable to. + Defaults to `[GraphKeys.VARIABLES]` (see variables.Variable). + +##### Returns: + + The created or existing variable. + +##### Raises: + + +* <b>ValueError</b>: when creating a new variable and shape is not declared, + or when violating reuse during variable creation. Reuse is set inside + `variable_scope`. + + +- - - + +### tf.get_variable_scope() <div class="md-anchor" id="get_variable_scope">{#get_variable_scope}</div> + +Returns the current variable scope. + + +- - - + +### tf.variable_scope(*args, **kwds) <div class="md-anchor" id="variable_scope">{#variable_scope}</div> + +Returns a context for variable scope. + +Variable scope allows to create new variables and to share already created +ones while providing checks to not create or share by accident. For details, +see the [Variable Scope How To](../../how_tos/variable_scope/index.md), +here we present only a few basic examples. + +Simple example of how to create a new variable: + +```python +with tf.variable_scope("foo"): + with tf.variable_scope("bar"): + v = tf.get_variable("v", [1]) + assert v.name == "foo/bar/v:0" +``` + +Basic example of sharing a variable: + +```python +with tf.variable_scope("foo"): + v = get_variable("v", [1]) +with tf.variable_scope("foo", reuse=True): + v1 = tf.get_variable("v", [1]) +assert v1 == v +``` + +Sharing a variable by capturing a scope and setting reuse: + +```python +with tf.variable_scope("foo") as scope. + v = get_variable("v", [1]) + scope.reuse_variables() + v1 = tf.get_variable("v", [1]) +assert v1 == v +``` + +To prevent accidental sharing of variables, we raise an exception when +getting an existing variable in a non-reusing scope. + +```python +with tf.variable_scope("foo") as scope. + v = get_variable("v", [1]) + v1 = tf.get_variable("v", [1]) + # Raises ValueError("... v already exists ..."). +``` + +Similarly, we raise an exception when trying to get a variable that +does not exist in reuse mode. + +```python +with tf.variable_scope("foo", reuse=True): + v = get_variable("v", [1]) + # Raises ValueError("... v does not exists ..."). +``` + +Note that the `reuse` flag is inherited: if we open a reusing scope, +then all its sub-scopes become reusing as well. + +##### Args: + + +* <b>name_or_scope</b>: `string` or `VariableScope`: the scope to open. +* <b>reuse</b>: `True` or `None`; if `True`, we go into reuse mode for this scope as + well as all sub-scopes; if `None`, we just inherit the parent scope reuse. +* <b>initializer</b>: default initializer for variables within this scope. + +##### Yields: + + A scope that can be to captured and reused. + +##### Raises: + + +* <b>ValueError</b>: when trying to reuse within a create scope, or create within + a reuse scope, or if reuse is not `None` or `True`. +* <b>TypeError</b>: when the types of some arguments are not appropriate. + + + +- - - + +### tf.constant_initializer(value=0.0) <div class="md-anchor" id="constant_initializer">{#constant_initializer}</div> + +Returns an initializer that generates Tensors with a single value. + +##### Args: + + +* <b>value</b>: A Python scalar. All elements of the initialized variable + will be set to this value. + +##### Returns: + + An initializer that generates Tensors with a single value. + + +- - - + +### tf.random_normal_initializer(mean=0.0, stddev=1.0, seed=None) <div class="md-anchor" id="random_normal_initializer">{#random_normal_initializer}</div> + +Returns an initializer that generates Tensors with a normal distribution. + +##### Args: + + +* <b>mean</b>: a python scalar or a scalar tensor. Mean of the random values + to generate. +* <b>stddev</b>: a python scalar or a scalar tensor. Standard deviation of the + random values to generate. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates Tensors with a normal distribution. + + +- - - + +### tf.truncated_normal_initializer(mean=0.0, stddev=1.0, seed=None) <div class="md-anchor" id="truncated_normal_initializer">{#truncated_normal_initializer}</div> + +Returns an initializer that generates a truncated normal distribution. + +These values are similar to values from a random_normal_initializer +except that values more than two standard deviations from the mean +are discarded and re-drawn. This is the recommended initializer for +neural network weights and filters. + +##### Args: + + +* <b>mean</b>: a python scalar or a scalar tensor. Mean of the random values + to generate. +* <b>stddev</b>: a python scalar or a scalar tensor. Standard deviation of the + random values to generate. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates Tensors with a truncated normal + distribution. + + +- - - + +### tf.random_uniform_initializer(minval=0.0, maxval=1.0, seed=None) <div class="md-anchor" id="random_uniform_initializer">{#random_uniform_initializer}</div> + +Returns an initializer that generates Tensors with a uniform distribution. + +##### Args: + + +* <b>minval</b>: a python scalar or a scalar tensor. lower bound of the range + of random values to generate. +* <b>maxval</b>: a python scalar or a scalar tensor. upper bound of the range + of random values to generate. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates Tensors with a uniform distribution. + + +- - - + +### tf.uniform_unit_scaling_initializer(factor=1.0, seed=None) <div class="md-anchor" id="uniform_unit_scaling_initializer">{#uniform_unit_scaling_initializer}</div> + +Returns an initializer that generates tensors without scaling variance. + +When initializing a deep network, it is in principle advantageous to keep +the scale of the input variance constant, so it does not explode or diminish +by reaching the final layer. If the input is `x` and the operation `x * W`, +and we want to initialize `W` uniformly at random, we need to pick `W` from + + [-sqrt(3) / sqrt(dim), sqrt(3) / sqrt(dim)] + +to keep the scale intact, where `dim = W.shape[0]` (the size of the input). +A similar calculation for convolutional networks gives an analogous result +with `dim` equal to the product of the first 3 dimensions. When +nonlinearities are present, we need to multiply this by a constant `factor`. +See <https://arxiv.org/pdf/1412.6558v3.pdf> for deeper motivation, experiments +and the calculation of constants. In section 2.3 there, the constants were +numerically computed: for a linear layer it's 1.0, relu: ~1.43, tanh: ~1.15. + +##### Args: + + +* <b>factor</b>: Float. A multiplicative factor by which the values will be scaled. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates tensors with unit variance. + + +- - - + +### tf.zeros_initializer(shape, dtype=tf.float32) <div class="md-anchor" id="zeros_initializer">{#zeros_initializer}</div> + +An adaptor for zeros() to match the Initializer spec. + + + +## Sparse Variable Updates <div class="md-anchor" id="AUTOGENERATED-sparse-variable-updates">{#AUTOGENERATED-sparse-variable-updates}</div> + +The sparse update ops modify a subset of the entries in a dense `Variable`, +either overwriting the entries or adding / subtracting a delta. These are +useful for training embedding models and similar lookup-based networks, since +only a small subset of embedding vectors change in any given step. + +Since a sparse update of a large tensor may be generated automatically during +gradient computation (as in the gradient of [`tf.gather`](array_ops.md#gather)), +an [`IndexedSlices`](#IndexedSlices) class is provided that encapsulates a set +of sparse indices and values. `IndexedSlices` objects are detected and handled +automatically by the optimizers in most cases. + +- - - + +### tf.scatter_update(ref, indices, updates, use_locking=None, name=None) <div class="md-anchor" id="scatter_update">{#scatter_update}</div> + +Applies sparse updates to a variable reference. + +This operation computes + + # Scalar indices + ref[indices, ...] = updates[...] + + # Vector indices (for each i) + ref[indices[i], ...] = updates[i, ...] + + # High rank indices (for each i, ..., j) + ref[indices[i, ..., j], ...] = updates[i, ..., j, ...] + +This operation outputs `ref` after the update is done. +This makes it easier to chain operations that need to use the reset value. + +If `indices` contains duplicate entries, lexicographically later entries +override earlier entries. + +Requires `updates.shape = indices.shape + ref.shape[1:]`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/ScatterUpdate.png" alt> +</div> + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Should be from a `Variable` node. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A tensor of indices into the first dimension of `ref`. +* <b>updates</b>: A `Tensor`. Must have the same type as `ref`. + A tensor of updated values to store in `ref`. +* <b>use_locking</b>: An optional `bool`. Defaults to `True`. + If True, the assignment will be protected by a lock; + otherwise the behavior is undefined, but may exhibit less contention. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same as `ref`. Returned as a convenience for operations that want + to use the updated values after the update is done. + + +- - - + +### tf.scatter_add(ref, indices, updates, use_locking=None, name=None) <div class="md-anchor" id="scatter_add">{#scatter_add}</div> + +Adds sparse updates to a variable reference. + +This operation computes + + # Scalar indices + ref[indices, ...] += updates[...] + + # Vector indices (for each i) + ref[indices[i], ...] += updates[i, ...] + + # High rank indices (for each i, ..., j) + ref[indices[i, ..., j], ...] += updates[i, ..., j, ...] + +This operation outputs `ref` after the update is done. +This makes it easier to chain operations that need to use the reset value. + +Duplicate entries are handled correctly: if multiple `indices` reference +the same location, their contributions add. + +Requires `updates.shape = indices.shape + ref.shape[1:]`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/ScatterAdd.png" alt> +</div> + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Should be from a `Variable` node. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A tensor of indices into the first dimension of `ref`. +* <b>updates</b>: A `Tensor`. Must have the same type as `ref`. + A tensor of updated values to add to `ref`. +* <b>use_locking</b>: An optional `bool`. Defaults to `False`. + If True, the addition will be protected by a lock; + otherwise the behavior is undefined, but may exhibit less contention. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same as `ref`. Returned as a convenience for operations that want + to use the updated values after the update is done. + + +- - - + +### tf.scatter_sub(ref, indices, updates, use_locking=None, name=None) <div class="md-anchor" id="scatter_sub">{#scatter_sub}</div> + +Subtracts sparse updates to a variable reference. + + # Scalar indices + ref[indices, ...] -= updates[...] + + # Vector indices (for each i) + ref[indices[i], ...] -= updates[i, ...] + + # High rank indices (for each i, ..., j) + ref[indices[i, ..., j], ...] -= updates[i, ..., j, ...] + +This operation outputs `ref` after the update is done. +This makes it easier to chain operations that need to use the reset value. + +Duplicate entries are handled correctly: if multiple `indices` reference +the same location, their (negated) contributions add. + +Requires `updates.shape = indices.shape + ref.shape[1:]`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/ScatterSub.png" alt> +</div> + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Should be from a `Variable` node. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A tensor of indices into the first dimension of `ref`. +* <b>updates</b>: A `Tensor`. Must have the same type as `ref`. + A tensor of updated values to subtract from `ref`. +* <b>use_locking</b>: An optional `bool`. Defaults to `False`. + If True, the subtraction will be protected by a lock; + otherwise the behavior is undefined, but may exhibit less contention. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same as `ref`. Returned as a convenience for operations that want + to use the updated values after the update is done. + + +- - - + +### tf.sparse_mask(a, mask_indices, name=None) <div class="md-anchor" id="sparse_mask">{#sparse_mask}</div> + +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 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 of 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. + + +- - - + +### class tf.IndexedSlices <div class="md-anchor" id="IndexedSlices">{#IndexedSlices}</div> + +A sparse representation of a set of tensor slices at given indices. + +This class is a simple wrapper for a pair of `Tensor` objects: + +* `values`: A `Tensor` of any dtype with shape `[D0, D1, ..., Dn]`. +* `indices`: A 1-D integer `Tensor` with shape `[D0]`. + +An `IndexedSlices` is typically used to represent a subset of a larger +tensor `dense` of shape `[LARGE0, D1, .. , DN]` where `LARGE0 >> D0`. +The values in `indices` are the indices in the first dimension of +the slices that have been extracted from the larger tensor. + +The dense tensor `dense` represented by an `IndexedSlices` `slices` has + +```python +dense[slices.indices[i], :, :, :, ...] = slices.values[i, :, :, :, ...] +``` + +The `IndexedSlices` class is used principally in the definition of +gradients for operations that have sparse gradients +(e.g. [`tf.gather`](array_ops.md#gather)). + +Contrast this representation with +[`SparseTensor`](sparse_ops.md#SparseTensor), +which uses multi-dimensional indices and scalar values. + +- - - + +#### tf.IndexedSlices.__init__(values, indices, dense_shape=None) {#IndexedSlices.__init__} + +Creates an `IndexedSlices`. + + + +- - - + +#### tf.IndexedSlices.values {#IndexedSlices.values} + +A `Tensor` containing the values of the slices. + +- - - + +#### tf.IndexedSlices.indices {#IndexedSlices.indices} + +A 1-D `Tensor` containing the indices of the slices. + +- - - + +#### tf.IndexedSlices.dense_shape {#IndexedSlices.dense_shape} + +A 1-D `Tensor` containing the shape of the corresponding dense tensor. + + +- - - + +#### tf.IndexedSlices.name {#IndexedSlices.name} + +The name of this `IndexedSlices`. + +- - - + +#### tf.IndexedSlices.dtype {#IndexedSlices.dtype} + +The `DType` of elements in this tensor. + +- - - + +#### tf.IndexedSlices.device {#IndexedSlices.device} + +The name of the device on which `values` will be produced, or `None`. + +- - - + +#### tf.IndexedSlices.op {#IndexedSlices.op} + +The `Operation` that produces `values` as an output. + + diff --git a/tensorflow/g3doc/api_docs/python/train.md b/tensorflow/g3doc/api_docs/python/train.md new file mode 100644 index 0000000000..0c88968c5d --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/train.md @@ -0,0 +1,1825 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Training +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Optimizers.](#AUTOGENERATED-optimizers.) + * [class tf.train.Optimizer](#Optimizer) + * [Usage](#AUTOGENERATED-usage) + * [Processing gradients before applying them.](#AUTOGENERATED-processing-gradients-before-applying-them.) + * [Gating Gradients](#AUTOGENERATED-gating-gradients) + * [Slots](#AUTOGENERATED-slots) + * [class tf.train.GradientDescentOptimizer](#GradientDescentOptimizer) + * [class tf.train.AdagradOptimizer](#AdagradOptimizer) + * [class tf.train.MomentumOptimizer](#MomentumOptimizer) + * [class tf.train.AdamOptimizer](#AdamOptimizer) + * [class tf.train.FtrlOptimizer](#FtrlOptimizer) + * [class tf.train.RMSPropOptimizer](#RMSPropOptimizer) +* [Gradient Computation.](#AUTOGENERATED-gradient-computation.) + * [tf.gradients(ys, xs, grad_ys=None, name='gradients', colocate_gradients_with_ops=False, gate_gradients=False, aggregation_method=None)](#gradients) + * [class tf.AggregationMethod](#AggregationMethod) + * [tf.stop_gradient(input, name=None)](#stop_gradient) +* [Gradient Clipping](#AUTOGENERATED-gradient-clipping) + * [tf.clip_by_value(t, clip_value_min, clip_value_max, name=None)](#clip_by_value) + * [tf.clip_by_norm(t, clip_norm, name=None)](#clip_by_norm) + * [tf.clip_by_average_norm(t, clip_norm, name=None)](#clip_by_average_norm) + * [tf.clip_by_global_norm(t_list, clip_norm, use_norm=None, name=None)](#clip_by_global_norm) + * [tf.global_norm(t_list, name=None)](#global_norm) +* [Decaying the learning rate.](#AUTOGENERATED-decaying-the-learning-rate.) + * [tf.train.exponential_decay(learning_rate, global_step, decay_steps, decay_rate, staircase=False, name=None)](#exponential_decay) +* [Moving Averages.](#AUTOGENERATED-moving-averages.) + * [class tf.train.ExponentialMovingAverage](#ExponentialMovingAverage) +* [Coordinator and QueueRunner.](#AUTOGENERATED-coordinator-and-queuerunner.) + * [class tf.train.Coordinator](#Coordinator) + * [class tf.train.QueueRunner](#QueueRunner) + * [tf.train.add_queue_runner(qr, collection='queue_runners')](#add_queue_runner) + * [tf.train.start_queue_runners(sess=None, coord=None, daemon=True, start=True, collection='queue_runners')](#start_queue_runners) +* [Summary Operations.](#AUTOGENERATED-summary-operations.) + * [tf.scalar_summary(tags, values, collections=None, name=None)](#scalar_summary) + * [tf.image_summary(tag, tensor, max_images=None, collections=None, name=None)](#image_summary) + * [tf.histogram_summary(tag, values, collections=None, name=None)](#histogram_summary) + * [tf.nn.zero_fraction(value, name=None)](#zero_fraction) + * [tf.merge_summary(inputs, collections=None, name=None)](#merge_summary) + * [tf.merge_all_summaries(key='summaries')](#merge_all_summaries) +* [Adding Summaries to Event Files.](#AUTOGENERATED-adding-summaries-to-event-files.) + * [class tf.train.SummaryWriter](#SummaryWriter) + * [tf.train.summary_iterator(path)](#summary_iterator) +* [Training utilities.](#AUTOGENERATED-training-utilities.) + * [tf.train.global_step(sess, global_step_tensor)](#global_step) + * [tf.train.write_graph(graph_def, logdir, name, as_text=True)](#write_graph) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +This library provides a set of classes and functions that helps train models. + +## Optimizers. <div class="md-anchor" id="AUTOGENERATED-optimizers.">{#AUTOGENERATED-optimizers.}</div> + +The Optimizer base class provides methods to compute gradients for a loss and +apply gradients to variables. A collection of subclasses implement classic +optimization algorithms such as GradientDescent and Adagrad. + +You never instantiate the Optimizer class itself, but instead instantiate one +of the subclasses. + +- - - + +### class tf.train.Optimizer <div class="md-anchor" id="Optimizer">{#Optimizer}</div> + +Base class for optimizers. + +This class defines the API to add Ops to train a model. You never use this +class directly, but instead instantiate one of its subclasses such as +`GradientDescentOptimizer`, `AdagradOptimizer`, or `MomentumOptimizer`. + +### Usage <div class="md-anchor" id="AUTOGENERATED-usage">{#AUTOGENERATED-usage}</div> + +``` +# Create an optimizer with the desired parameters. +opt = GradientDescentOptimizer(learning_rate=0.1) +# Add Ops to the graph to minimize a cost by updating a list of variables. +# "cost" is a Tensor, and the list of variables contains variables.Variable +# objects. +opt_op = opt.minimize(cost, <list of variables>) +``` + +In the training program you will just have to run the returned Op. + +``` +# Execute opt_op to do one step of training: +opt_op.run() +``` + +### Processing gradients before applying them. <div class="md-anchor" id="AUTOGENERATED-processing-gradients-before-applying-them.">{#AUTOGENERATED-processing-gradients-before-applying-them.}</div> + +Calling `minimize()` takes care of both computing the gradients and +applying them to the variables. If you want to process the gradients +before applying them you can instead use the optimizer in three steps: + +1. Compute the gradients with `compute_gradients()`. +2. Process the gradients as you wish. +3. Apply the processed gradients with `apply_gradients()`. + +Example: + +``` +# Create an optimizer. +opt = GradientDescentOptimizer(learning_rate=0.1) + +# Compute the gradients for a list of variables. +grads_and_vars = opt.compute_gradients(loss, <list of variables>) + +# grads_and_vars is a list of tuples (gradient, variable). Do whatever you +# need to the 'gradient' part, for example cap them, etc. +capped_grads_and_vars = [(MyCapper(gv[0]), gv[1])) for gv in grads_and_vars] + +# Ask the optimizer to apply the capped gradients. +opt.apply_gradients(capped_grads_and_vars) +``` + +- - - + +#### tf.train.Optimizer.__init__(use_locking, name) {#Optimizer.__init__} + +Create a new Optimizer. + +This must be called by the constructors of subclasses. + +##### Args: + + +* <b>use_locking</b>: Bool. If True apply use locks to prevent concurrent updates + to variables. +* <b>name</b>: A non-empty string. The name to use for accumulators created + for the optimizer. + +##### Raises: + + +* <b>ValueError</b>: if name is malformed. + + + +- - - + +#### tf.train.Optimizer.minimize(loss, global_step=None, var_list=None, gate_gradients=1, name=None) {#Optimizer.minimize} + +Add operations to minimize 'loss' by updating 'var_list'. + +This method simply combines calls compute_gradients() and +apply_gradients(). If you want to process the gradient before applying them +call compute_gradients() and apply_gradients() explicitly instead of using +this function. + +##### Args: + + +* <b>loss</b>: A Tensor containing the value to minimize. +* <b>global_step</b>: Optional Variable to increment by one after the + variables have been updated. +* <b>var_list</b>: Optional list of variables.Variable to update to minimize + 'loss'. Defaults to the list of variables collected in the graph + under the key GraphKeys.TRAINABLE_VARIABLES. +* <b>gate_gradients</b>: How to gate the computation of gradients. Can be + GATE_NONE, GATE_OP, or GATE_GRAPH. +* <b>name</b>: Optional name for the returned operation. + +##### Returns: + + An Operation that updates the variables in 'var_list'. If 'global_step' + was not None, that operation also increments global_step. + +##### Raises: + + +* <b>ValueError</b>: if some of the variables are not variables.Variable objects. + + +- - - + +#### tf.train.Optimizer.compute_gradients(loss, var_list=None, gate_gradients=1) {#Optimizer.compute_gradients} + +Compute gradients of "loss" for the variables in "var_list". + +This is the first part of minimize(). It returns a list +of (gradient, variable) pairs where "gradient" is the gradient +for "variable". Note that "gradient" can be a Tensor, a +IndexedSlices, or None if there is no gradient for the +given variable. + +##### Args: + + +* <b>loss</b>: A Tensor containing the value to minimize. +* <b>var_list</b>: Optional list of variables.Variable to update to minimize + "loss". Defaults to the list of variables collected in the graph + under the key GraphKey.TRAINABLE_VARIABLES. +* <b>gate_gradients</b>: How to gate the computation of gradients. Can be + GATE_NONE, GATE_OP, or GATE_GRAPH. + +##### Returns: + + A list of (gradient, variable) pairs. + +##### Raises: + + +* <b>TypeError</b>: If var_list contains anything else than variables.Variable. +* <b>ValueError</b>: If some arguments are invalid. + + +- - - + +#### tf.train.Optimizer.apply_gradients(grads_and_vars, global_step=None, name=None) {#Optimizer.apply_gradients} + +Apply gradients to variables. + +This is the second part of minimize(). It returns an Operation that +applies gradients. + +##### Args: + + +* <b>grads_and_vars</b>: List of (gradient, variable) pairs as returned by + compute_gradients(). +* <b>global_step</b>: Optional Variable to increment by one after the + variables have been updated. +* <b>name</b>: Optional name for the returned operation. Default to the + name passed to the Optimizer constructor. + +##### Returns: + + An Operation that applies the specified gradients. If 'global_step' + was not None, that operation also increments global_step. + +##### Raises: + + +* <b>TypeError</b>: if grads_and_vars is malformed. + + + +### Gating Gradients <div class="md-anchor" id="AUTOGENERATED-gating-gradients">{#AUTOGENERATED-gating-gradients}</div> + +Both `minimize()` and `compute_gradients()` accept a `gate_gradient` argument +that controls the degree of parallelism during the application of the +gradients. + +The possible values are: `GATE_NONE`, `GATE_OP`, and `GATE_GRAPH`. + +<b>GATE_NONE</b>: Compute and apply gradients in parallel. This provides the +maximum parallelism in execution, at the cost of some non-reproducibility in +the results. For example the two gradients of MatMul depend on the input +values: With `GATE_NONE` one of the gradients could be applied to one of the +inputs _before_ the other gradient is computed resulting in non-reproducible +results. + +<b>GATE_OP</b>: For each Op, make sure all gradients are computed before they +are used. This prevents race conditions for Ops that generate gradients for +multiple inputs where the gradients depend on the inputs. + +<b>GATE_GRAPH</b>: Make sure all gradients for all variables are computed +before any one of them is used. This provides the least parallelism but can +be useful if you want to process all gradients before applying any of them. + +### Slots <div class="md-anchor" id="AUTOGENERATED-slots">{#AUTOGENERATED-slots}</div> + +Some optimizer subclasses, such as `MomentumOptimizer` and `AdagradOptimizer` +allocate and manage additional variables associated with the variables to +train. These are called <i>Slots</i>. Slots have names and you can ask the +optimizer for the names of the slots that it uses. Once you have a slot name +you can ask the optimizer for the variable it created to hold the slot value. + +This can be useful if you want to log debug a training algorithm, report stats +about the slots, etc. + +- - - + +#### tf.train.Optimizer.get_slot_names() {#Optimizer.get_slot_names} + +Return a list of the names of slots created by the Optimizer. + +See get_slot(). + +##### Returns: + + A list of strings. + + +- - - + +#### tf.train.Optimizer.get_slot(var, name) {#Optimizer.get_slot} + +Return a slot named "name" created for "var" by the Optimizer. + +Some Optimizer subclasses use additional variables. For example +Momentum and Adagrad use variables to accumulate updates. This method +gives access to these Variables if for some reason you need them. + +Use get_slot_names() to get the list of slot names created by the Optimizer. + +##### Args: + + +* <b>var</b>: A variable passed to minimize() or apply_gradients(). +* <b>name</b>: A string. + +##### Returns: + + The Variable for the slot if it was created, None otherwise. + + + + +- - - + +### class tf.train.GradientDescentOptimizer <div class="md-anchor" id="GradientDescentOptimizer">{#GradientDescentOptimizer}</div> + +Optimizer that implements the gradient descent algorithm. + +- - - + +#### tf.train.GradientDescentOptimizer.__init__(learning_rate, use_locking=False, name='GradientDescent') {#GradientDescentOptimizer.__init__} + +Construct a new gradient descent optimizer. + +##### Args: + + +* <b>learning_rate</b>: A Tensor or a floating point value. The learning + rate to use. +* <b>use_locking</b>: If True use locks for update operation.s +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "GradientDescent". + + + +- - - + +### class tf.train.AdagradOptimizer <div class="md-anchor" id="AdagradOptimizer">{#AdagradOptimizer}</div> + +Optimizer that implements the Adagrad algorithm. + +- - - + +#### tf.train.AdagradOptimizer.__init__(learning_rate, initial_accumulator_value=0.1, use_locking=False, name='Adagrad') {#AdagradOptimizer.__init__} + +Construct a new Adagrad optimizer. + +##### Args: + + +* <b>learning_rate</b>: A `Tensor` or a floating point value. The learning rate. +* <b>initial_accumulator_value</b>: A floating point value. + Starting value for the accumulators, must be positive. +* <b>use_locking</b>: If `True` use locks for update operations. +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "Adagrad". + +##### Raises: + + +* <b>ValueError</b>: If the initial_accumulator_value is invalid. + + + +- - - + +### class tf.train.MomentumOptimizer <div class="md-anchor" id="MomentumOptimizer">{#MomentumOptimizer}</div> + +Optimizer that implements the Momentum algorithm. + +- - - + +#### tf.train.MomentumOptimizer.__init__(learning_rate, momentum, use_locking=False, name='Momentum') {#MomentumOptimizer.__init__} + +Construct a new Momentum optimizer. + +##### Args: + + +* <b>learning_rate</b>: A `Tensor` or a floating point value. The learning rate. +* <b>momentum</b>: A `Tensor` or a floating point value. The momentum. +* <b>use_locking</b>: If `True` use locks for update operations. +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "Momentum". + + + +- - - + +### class tf.train.AdamOptimizer <div class="md-anchor" id="AdamOptimizer">{#AdamOptimizer}</div> + +Optimizer that implements the Adam algorithm. + +- - - + +#### tf.train.AdamOptimizer.__init__(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, use_locking=False, name='Adam') {#AdamOptimizer.__init__} + +Construct a new Adam optimizer. + +Implementation is based on: http://arxiv.org/pdf/1412.6980v7.pdf + +Initialization: + +``` +m_0 <- 0 (Initialize initial 1st moment vector) +v_0 <- 0 (Initialize initial 2nd moment vector) +t <- 0 (Initialize timestep) +``` + +The update rule for `variable` with gradient `g` uses an optimization +described at the end of section2 of the paper: + +``` +t <- t + 1 +lr_t <- learning_rate * sqrt(1 - beta2^t) / (1 - beta1^t) + +m_t <- beta1 * m_{t-1} + (1 - beta1) * g +v_t <- beta2 * v_{t-1} + (1 - beta2) * g * g +variable <- variable - lr_t * m_t / (sqrt(v_t) + epsilon) +``` + +The default value of 1e-8 for epsilon might not be a good default in +general. For example, when training an Inception network on ImageNet a +current good choice is 1.0 or 0.1. + +##### Args: + + +* <b>learning_rate</b>: A Tensor or a floating point value. The learning rate. +* <b>beta1</b>: A float value or a constant float tensor. + The exponential decay rate for the 1st moment estimates. +* <b>beta2</b>: A float value or a constant float tensor. + The exponential decay rate for the 2st moment estimates. +* <b>epsilon</b>: A small constant for numerical stability. +* <b>use_locking</b>: If True use locks for update operation.s +* <b>name</b>: Optional name for the operations created when applying gradients. + Defaults to "Adam". + + + +- - - + +### class tf.train.FtrlOptimizer <div class="md-anchor" id="FtrlOptimizer">{#FtrlOptimizer}</div> + +Optimizer that implements the FTRL algorithm. + +- - - + +#### tf.train.FtrlOptimizer.__init__(learning_rate, learning_rate_power=-0.5, initial_accumulator_value=0.1, l1_regularization_strength=0.0, l2_regularization_strength=0.0, use_locking=False, name='Ftrl') {#FtrlOptimizer.__init__} + +Construct a new FTRL optimizer. + +The Ftrl-proximal algorithm, abbreviated for Follow-the-regularized-leader, +is described in the paper [Ad Click Prediction: a View from the Trenches]( +https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf). + +It can give a good performance vs. sparsity tradeoff. + +Ftrl-proximal uses its own global base learning rate and can behave like +Adagrad with `learning_rate_power=-0.5`, or like gradient descent with +`learning_rate_power=0.0`. + +The effective learning rate is adjusted per parameter, relative to this +base learning rate as: + +``` +effective_learning_rate_i = (learning_rate / + pow(k + summed_squared_gradients_for_i, learning_rate_power)); +``` + +where k is the small constant `initial_accumulator_value`. + +Note that the real regularization coefficient of `|w|^2` for objective +function is `1 / lambda_2` if specifying `l2 = lambda_2` as argument when +using this function. + +##### Args: + + +* <b>learning_rate</b>: A float value or a constant float `Tensor`. +* <b>learning_rate_power</b>: A float value, must be less or equal to zero. +* <b>initial_accumulator_value</b>: The starting value for accumulators. + Only positive values are allowed. +* <b>l1_regularization_strength</b>: A float value, must be greater than or + equal to zero. +* <b>l2_regularization_strength</b>: A float value, must be greater than or + equal to zero. +* <b>use_locking</b>: If `True` use locks for update operations. +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "Ftrl". + +##### Raises: + + +* <b>ValueError</b>: if one of the arguments is invalid. + + + +- - - + +### class tf.train.RMSPropOptimizer <div class="md-anchor" id="RMSPropOptimizer">{#RMSPropOptimizer}</div> + +Optimizer that implements the RMSProp algorithm. + +- - - + +#### tf.train.RMSPropOptimizer.__init__(learning_rate, decay, momentum=0.0, epsilon=1e-10, use_locking=False, name='RMSProp') {#RMSPropOptimizer.__init__} + +Construct a new RMSProp optimizer. + +##### Args: + + +* <b>learning_rate</b>: A Tensor or a floating point value. The learning rate. +* <b>decay</b>: discounting factor for the history/coming gradient +* <b>momentum</b>: a scalar tensor. +* <b>epsilon</b>: small value to avoid zero denominator. +* <b>use_locking</b>: If True use locks for update operation. +* <b>name</b>: Optional name prefic for the operations created when applying + gradients. Defaults to "RMSProp". + + + + +## Gradient Computation. <div class="md-anchor" id="AUTOGENERATED-gradient-computation.">{#AUTOGENERATED-gradient-computation.}</div> + +TensorFlow provides functions to compute the derivatives for a given +TensorFlow computation graph, adding operations to the graph. The +optimizer classes automatically compute derivatives on your graph, but +creators of new Optimizers or expert users can call the lower-level +functions below. + +- - - + +### tf.gradients(ys, xs, grad_ys=None, name='gradients', colocate_gradients_with_ops=False, gate_gradients=False, aggregation_method=None) <div class="md-anchor" id="gradients">{#gradients}</div> + +Constructs symbolic partial derivatives of `ys` w.r.t. x in `xs`. + +`ys` and `xs` are each a `Tensor` or a list of tensors. `grad_ys` +is a list of `Tensor`, holding the gradients received by the +`ys`. The list must be the same length as `ys`. + +`gradients()` adds ops to the graph to output the partial +derivatives of `ys` with respect to `xs`. It returns a list of +`Tensor` of length `len(xs)` where each tensor is the `sum(dy/dx)` +for y in `ys`. + +`grad_ys` is a list of tensors of the same length as `ys` that holds +the initial gradients for each y in `ys`. When `grad_ys` is None, +we fill in a tensor of '1's of the shape of y for each y in `ys`. A +user can provide their own initial 'grad_ys` to compute the +derivatives using a different initial gradient for each y (e.g., if +one wanted to weight the gradient differently for each value in +each y). + +##### Args: + + +* <b>ys</b>: A `Tensor` or list of tensors to be differentiated. +* <b>xs</b>: A `Tensor` or list of tensors to be used for differentiation. +* <b>grad_ys</b>: Optional. A `Tensor` or list of tensors the same size as + `ys` and holding the gradients computed for each y in `ys`. +* <b>name</b>: Optional name to use for grouping all the gradient ops together. + defaults to 'gradients'. +* <b>colocate_gradients_with_ops</b>: If True, try colocating gradients with + the corresponding op. +* <b>gate_gradients</b>: If True, add a tuple around the gradients returned + for an operations. This avoids some race conditions. +* <b>aggregation_method</b>: Specifies the method used to combine gradient terms. + Accepted values are constants defined in the class `AggregationMethod`. + +##### Returns: + + A list of `sum(dy/dx)` for each x in `xs`. + +##### Raises: + + +* <b>LookupError</b>: if one of the operations between `x` and `y` does not + have a registered gradient function. +* <b>ValueError</b>: if the arguments are invalid. + + +- - - + +### class tf.AggregationMethod <div class="md-anchor" id="AggregationMethod">{#AggregationMethod}</div> + +A class listing aggregation methods used to combine gradients. + +Computing partial derivatives can require aggregating gradient +contributions. This class lists the various methods that can +be used to combine gradients in the graph: + +* `ADD_N`: All of the gradient terms are summed as part of one + operation using the "AddN" op. It has the property that all + gradients must be ready before any aggregation is performed. +* `DEFAULT`: The system-chosen default aggregation method. + + +- - - + +### tf.stop_gradient(input, name=None) <div class="md-anchor" id="stop_gradient">{#stop_gradient}</div> + +Stops gradient computation. + +When executed in a graph, this op outputs its input tensor as-is. + +When building ops to compute gradients, this op prevents the contribution of +its inputs to be taken into account. Normally, the gradient generator adds ops +to a graph to compute the derivatives of a specified 'loss' by recursively +finding out inputs that contributed to its computation. If you insert this op +in the graph it inputs are masked from the gradient generator. They are not +taken into account for computing gradients. + +This is useful any time you want to compute a value with TensorFlow but need +to pretend that the value was a constant. Some examples include: + +* The *EM* algorithm where the *M-step* should not involve backpropagation + through the output of the *E-step*. +* Contrastive divergence training of Boltzmann machines where, when + differentiating the energy function, the training must not backpropagate + through the graph that generated the samples from the model. +* Adversarial training, where no backprop should happen through the adversarial + example generation process. + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + + + +## Gradient Clipping <div class="md-anchor" id="AUTOGENERATED-gradient-clipping">{#AUTOGENERATED-gradient-clipping}</div> + +TensorFlow provides several operations that you can use to add clipping +functions to your graph. You can use these functions to perform general data +clipping, but they're particularly useful for handling exploding or vanishing +gradients. + +- - - + +### tf.clip_by_value(t, clip_value_min, clip_value_max, name=None) <div class="md-anchor" id="clip_by_value">{#clip_by_value}</div> + +Clips tensor values to a specified min and max. + +Given a tensor `t`, this operation returns a tensor of the same type and +shape as `t` with its values clipped to `clip_value_min` and `clip_value_max`. +Any values less than `clip_value_min` are set to `clip_value_min`. Any values +greater than `clip_value_max` are set to `clip_value_max`. + +##### Args: + + +* <b>t</b>: A `Tensor`. +* <b>clip_value_min</b>: A 0-D (scalar) `Tensor`. The minimum value to clip by. +* <b>clip_value_max</b>: A 0-D (scalar) `Tensor`. The maximum value to clip by. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A clipped `Tensor`. + + +- - - + +### tf.clip_by_norm(t, clip_norm, name=None) <div class="md-anchor" id="clip_by_norm">{#clip_by_norm}</div> + +Clips tensor values to a maximum L2-norm. + +Given a tensor `t`, and a maximum clip value `clip_norm`, this operation +normalizes `t` so that its L2-norm is less than or equal to `clip_norm'. +Specifically, if the L2-norm is already less than or equal to `clip_norm`, +then `t` is not modified. If the L2-norm is greater than `clip_norm`, then +this operation returns a tensor of the same type and shape as `t` with its +values set to: + +`t * clip_norm / l2norm(t)` + +In this case, the L2-norm of the output tensor is `clip_norm`. + +This operation is typically used to clip gradients before applying them with +an optimizer. + +##### Args: + + +* <b>t</b>: A `Tensor`. +* <b>clip_norm</b>: A 0-D (scalar) `Tensor` > 0. A maximum clipping value. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A clipped `Tensor`. + + +- - - + +### tf.clip_by_average_norm(t, clip_norm, name=None) <div class="md-anchor" id="clip_by_average_norm">{#clip_by_average_norm}</div> + +Clips tensor values to a maximum average L2-norm. + +Given a tensor `t`, and a maximum clip value `clip_norm`, this operation +normalizes `t` so that its average L2-norm is less than or equal to +`clip_norm'. Specifically, if the average L2-norm is already less than or +equal to `clip_norm`, then `t` is not modified. If the average L2-norm is +greater than `clip_norm`, then this operation returns a tensor of the same +type and shape as `t` with its values set to: + +`t * clip_norm / l2norm_avg(t)` + +In this case, the average L2-norm of the output tensor is `clip_norm`. + +This operation is typically used to clip gradients before applying them with +an optimizer. + +##### Args: + + +* <b>t</b>: A `Tensor`. +* <b>clip_norm</b>: A 0-D (scalar) `Tensor` > 0. A maximum clipping value. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A clipped `Tensor`. + + +- - - + +### tf.clip_by_global_norm(t_list, clip_norm, use_norm=None, name=None) <div class="md-anchor" id="clip_by_global_norm">{#clip_by_global_norm}</div> + +Clips values of multiple tensors by the ratio of the sum of their norms. + +Given a tuple or list of tensors `t_list`, and a clipping ratio `clip_norm`, +this operation returns a list of clipped tensors `list_clipped` +and the global norm (`global_norm`) of all tensors in `t_list`. Optionally, +if you've already computed the global norm for `t_list`, you can specify +the global norm with `use_norm`. + +To perform the clipping, the values t_list[i] are set to: + +`t_list[i] * clip_norm / max(global_norm, clip_norm)` + +where: + +`global_norm = sqrt(sum([l2norm(t)**2 for t in t_list]))` + +If `clip_norm > global_norm` then the entries in `t_list` remain as they are, +otherwise they're all shrunk by the global ratio. + +Any of the entries of `t_list` that are of type None are ignored. + +This is the correct way to perform gradient clipping (for example, see +R. Pascanu, T. Mikolov, and Y. Bengio, "On the difficulty of training +Recurrent Neural Networks". http://arxiv.org/abs/1211.5063) + +However, it is slower than `clip_by_norm()` because all the parameters must be +ready before the clipping operation can be performed. + +##### Args: + + +* <b>t_list</b>: A tuple or list of mixed `Tensors`, `IndexedSlices`, or None. +* <b>clip_norm</b>: A 0-D (scalar) `Tensor` > 0. The clipping ratio. +* <b>use_norm</b>: A 0-D (scalar) `Tensor` of type `float` (optional). The global + norm to use. If not provided, `global_norm()` is used to compute the norm. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>list_clipped</b>: A list of `Tensors` of the same type as `list_t`. +* <b>global_norm</b>: A 0-D (scalar) `Tensor` representing the global norm. + +##### Raises: + + +* <b>TypeError</b>: If `t_list` is not a sequence. + + +- - - + +### tf.global_norm(t_list, name=None) <div class="md-anchor" id="global_norm">{#global_norm}</div> + +Computes the global norm of multiple tensors. + +Given a tuple or list of tensors `t_list`, this operation returns the +global norm of the elements in all tensors in `t_list`. The global norm is +computed as: + +`global_norm = sqrt(sum([l2norm(t)**2 for t in t_list]))` + +Any entries in `t_list` that are of type None are ignored. + +##### Args: + + +* <b>t_list</b>: A tuple or list of mixed `Tensors`, `IndexedSlices`, or None. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A 0-D (scalar) `Tensor` of type `float`. + +##### Raises: + + +* <b>TypeError</b>: If `t_list` is not a sequence. + + + +## Decaying the learning rate. <div class="md-anchor" id="AUTOGENERATED-decaying-the-learning-rate.">{#AUTOGENERATED-decaying-the-learning-rate.}</div> +- - - + +### tf.train.exponential_decay(learning_rate, global_step, decay_steps, decay_rate, staircase=False, name=None) <div class="md-anchor" id="exponential_decay">{#exponential_decay}</div> + +Applies exponential decay to the learning rate. + +When training a model, it is often recommended to lower the learning rate as +the training progresses. This function applies an exponential decay function +to a provided initial learning rate. It requires a `global_step` value to +compute the decayed learning rate. You can just pass a TensorFlow variable +that you increment at each training step. + +The function returns the decayed learning rate. It is computed as: + +```python +decayed_learning_rate = learning_rate * + decay_rate ^ (global_step / decay_steps) +``` + +If the argument `staircase` is `True`, then `global_step /decay_steps` is an +integer division and the decayed learning rate follows a staircase function. + +Example: decay every 100000 steps with a base of 0.96: + +```python +... +global_step = tf.Variable(0, trainable=False) +starter_learning_rate = 0.1 +learning_rate = tf.exponential_decay(starter_learning_rate, global_step, + 100000, 0.96, staircase=True) +optimizer = tf.GradientDescent(learning_rate) +# Passing global_step to minimize() will increment it at each step. +optimizer.minimize(...my loss..., global_step=global_step) +``` + +##### Args: + + +* <b>learning_rate</b>: A scalar `float32` or `float64` `Tensor` or a + Python number. The initial learning rate. +* <b>global_step</b>: A scalar `int32` or `int64` `Tensor` or a Python number. + Global step to use for the decay computation. Must not be negative. +* <b>decay_steps</b>: A scalar `int32` or `int64` `Tensor` or a Python number. + Must be positive. See the decay computation above. +* <b>decay_rate</b>: A scalar `float32` or `float64` `Tensor` or a + Python number. The decay rate. +* <b>staircase</b>: Boolean. It `True` decay the learning rate at discrete intervals. +* <b>name</b>: string. Optional name of the operation. Defaults to 'ExponentialDecay' + +##### Returns: + + A scalar `Tensor` of the same type as `learning_rate`. The decayed + learning rate. + + + +## Moving Averages. <div class="md-anchor" id="AUTOGENERATED-moving-averages.">{#AUTOGENERATED-moving-averages.}</div> + +Some training algorithms, such as GradientDescent and Momentum often benefit +from maintaining a moving average of variables during optimization. Using the +moving averages for evaluations often improve results significantly. + +- - - + +### class tf.train.ExponentialMovingAverage <div class="md-anchor" id="ExponentialMovingAverage">{#ExponentialMovingAverage}</div> + +Maintains moving averages of variables by employing and exponential decay. + +When training a model, it is often beneficial to maintain moving averages of +the trained parameters. Evaluations that use averaged parameters sometimes +produce significantly better results than the final trained values. + +The `apply()` method adds shadow copies of trained variables and add ops that +maintain a moving average of the trained variables in their shadow copies. +It is used when building the training model. The ops that maintain moving +averages are typically run after each training step. +The `average()` and `average_name()` methods give access to the shadow +variables and their names. They are useful when building an evaluation +model, or when restoring a model from a checkpoint file. They help use the +moving averages in place of the last trained values for evaluations. + +The moving averages are computed using exponential decay. You specify the +decay value when creating the `ExponentialMovingAverage` object. The shadow +variables are initialized with the same initial values as the trained +variables. When you run the ops to maintain the moving averages, each +shadow variable is updated with the formula: + + `shadow_variable -= (1 - decay) * (shadow_variable - variable)` + +This is mathematically equivalent to the classic formula below, but the use +of an `assign_sub` op (the `"-="` in the formula) allows concurrent lockless +updates to the variables: + + `shadow_variable = decay * shadow_variable + (1 - decay) * variable` + +Reasonable values for `decay` are close to 1.0, typically in the +multiple-nines range: 0.999, 0.9999, etc. + +Example usage when creating a training model: + +```python +# Create variables. +var0 = tf.Variable(...) +var1 = tf.Variable(...) +# ... use the variables to build a training model... +... +# Create an op that applies the optimizer. This is what we usually +# would use as a training op. +opt_op = opt.minimize(my_loss, [var0, var1]) + +# Create an ExponentialMovingAverage object +ema = tf.train.ExponentialMovingAverage(decay=0.9999) + +# Create the shadow variables, and add ops to maintain moving averages +# of var0 and var1. +maintain_averages_op = ema.apply([var0, var1]) + +# Create an op that will update the moving averages after each training +# step. This is what we will use in place of the usuall trainig op. +with tf.control_dependencies([opt_op]): + training_op = tf.group(maintain_averages_op) + +...train the model by running training_op... +``` + +There are two ways to use the moving averages for evaluations: + +* Build a model that uses the shadow variables instead of the variables. + For this, use the `average()` method which returns the shadow variable + for a given variable. +* Build a model normally but load the checkpoint files to evaluate by using + the shadow variable names. For this use the `average_name()` method. See + the [Saver class](train.md#Saver) for more information on restoring saved + variables. + +Example of restoring the shadow variable values: + +```python +# Create a Saver that loads variables from their saved shadow values. +shadow_var0_name = ema.average_name(var0) +shadow_var1_name = ema.average_name(var1) +saver = tf.train.Saver({shadow_var0_name: var0, shadow_var1_name: var1}) +saver.restore(...checkpoint filename...) +# var0 and var1 now hold the moving average values +``` + +- - - + +#### tf.train.ExponentialMovingAverage.__init__(decay, num_updates=None, name='ExponentialMovingAverage') {#ExponentialMovingAverage.__init__} + +Creates a new ExponentialMovingAverage object. + +The `Apply()` method has to be called to create shadow variables and add +ops to maintain moving averages. + +The optional `num_updates` parameter allows one to tweak the decay rate +dynamically. . It is typical to pass the count of training steps, usually +kept in a variable that is incremented at each step, in which case the +decay rate is lower at the start of training. This makes moving averages +move faster. If passed, the actual decay rate used is: + + `min(decay, (1 + num_updates) / (10 + num_updates))` + +##### Args: + + +* <b>decay</b>: Float. The decay to use. +* <b>num_updates</b>: Optional count of number of updates applied to variables. +* <b>name</b>: String. Optional prefix name to use for the name of ops added in + `Apply()`. + + +- - - + +#### tf.train.ExponentialMovingAverage.apply(var_list=None) {#ExponentialMovingAverage.apply} + +Maintains moving averages of variables. + +`var_list` must be a list of `Variable` or `Tensor` objects. This method +creates shadow variables for all elements of `var_list`. Shadow variables +for `Variable` objects are initialized to the variable's initial value. +For `Tensor` objects, the shadow variables are initialized to 0. + +shadow variables are created with `trainable=False` and added to the +`GraphKeys.ALL_VARIABLES` collection. They will be returned by calls to +`tf.all_variables()`. + +Returns an op that updates all shadow variables as described above. + +Note that `apply()` can be called multiple times with different lists of +variables. + +##### Args: + + +* <b>var_list</b>: A list of Variable or Tensor objects. The variables + and Tensors must be of types float32 or float64. + +##### Returns: + + An Operation that updates the moving averages. + +##### Raises: + + +* <b>TypeError</b>: If the arguments are not all float32 or float64. +* <b>ValueError</b>: If the moving average of one of the variables is already + being computed. + + +- - - + +#### tf.train.ExponentialMovingAverage.average_name(var) {#ExponentialMovingAverage.average_name} + +Returns the name of the `Variable` holding the average for `var`. + +The typical scenario for `ExponentialMovingAverage` is to compute moving +averages of variables during training, and restore the variables from the +computed moving averages during evaluations. + +To restore variables, you have to know the name of the shadow variables. +That name and the original variable can then be passed to a `Saver()` object +to restore the variable from the moving average value with: + `saver = tf.train.Saver({ema.average_name(var): var})` + +`average_name()` can be called whether or not `apply()` has been called. + +##### Args: + + +* <b>var</b>: A `Variable` object. + +##### Returns: + + A string: the name of the variable that will be used or was used + by the `ExponentialMovingAverage class` to hold the moving average of + `var`. + + +- - - + +#### tf.train.ExponentialMovingAverage.average(var) {#ExponentialMovingAverage.average} + +Returns the `Variable` holding the average of `var`. + +##### Args: + + +* <b>var</b>: A `Variable` object. + +##### Returns: + + A `Variable` object or `None` if the moving average of `var` + is not maintained.. + + + + +## Coordinator and QueueRunner. <div class="md-anchor" id="AUTOGENERATED-coordinator-and-queuerunner.">{#AUTOGENERATED-coordinator-and-queuerunner.}</div> + +See [Threading and Queues](../../how_tos/threading_and_queues/index.md) +for how to use threads and queues. For documentation on the Queue API, +see [Queues](../../api_docs/python/io_ops.md#queues). + +- - - + +### class tf.train.Coordinator <div class="md-anchor" id="Coordinator">{#Coordinator}</div> + +A coordinator for threads. + +This class implements a simple mechanism to coordinate the termination of a +set of threads. + +#### Usage: + +```python +# Create a coordinator. +coord = Coordinator() +# Start a number of threads, passing the coordinator to each of them. +...start thread 1...(coord, ...) +...start thread N...(coord, ...) +# Wait for all the threads to terminate. +coord.join(threads) +``` + +Any of the threads can call `coord.request_stop()` to ask for all the threads +to stop. To cooperate with the requests, each thread must check for +`coord.should_stop()` on a regular basis. `coord.should_stop()` returns +`True` as soon as `coord.request_stop()` has been called. + +A typical thread running with a Coordinator will do something like: + +```python +while not coord.should_stop(): + ...do some work... +``` + +#### Exception handling: + +A thread can report an exception to the Coordinator as part of the +`should_stop()` call. The exception will be re-raised from the +`coord.join()` call. + +Thread code: + +```python +try: + while not coord.should_stop(): + ...do some work... +except Exception, e: + coord.request_stop(e) +``` + +Main code: + +```python +try: + ... + coord = Coordinator() + # Start a number of threads, passing the coordinator to each of them. + ...start thread 1...(coord, ...) + ...start thread N...(coord, ...) + # Wait for all the threads to terminate. + coord.join(threads) +except Exception, e: + ...exception that was passed to coord.request_stop() +``` + +#### Grace period for stopping: + +After a thread has called `coord.request_stop()` the other threads have a +fixed time to stop, this is called the 'stop grace period' and defaults to 2 +minutes. If any of the threads is still alive after the grace period expires +`coord.join()` raises a RuntimeException reporting the laggards. + +``` +try: + ... + coord = Coordinator() + # Start a number of threads, passing the coordinator to each of them. + ...start thread 1...(coord, ...) + ...start thread N...(coord, ...) + # Wait for all the threads to terminate, give them 10s grace period + coord.join(threads, stop_grace_period_secs=10) +except RuntimeException: + ...one of the threads took more than 10s to stop after request_stop() + ...was called. +except Exception: + ...exception that was passed to coord.request_stop() +``` +- - - + +#### tf.train.Coordinator.__init__() {#Coordinator.__init__} + +Create a new Coordinator. + + +- - - + +#### tf.train.Coordinator.join(threads, stop_grace_period_secs=120) {#Coordinator.join} + +Wait for threads to terminate. + +Blocks until all 'threads' have terminated or request_stop() is called. + +After the threads stop, if an 'exc_info' was passed to request_stop, that +exception is re-reaised. + +Grace period handling: When request_stop() is called, threads are given +'stop_grace_period_secs' seconds to terminate. If any of them is still +alive after that period expires, a RuntimeError is raised. Note that if +an 'exc_info' was passed to request_stop() then it is raised instead of +that RuntimeError. + +##### Args: + + +* <b>threads</b>: List threading.Threads. The started threads to join. +* <b>stop_grace_period_secs</b>: Number of seconds given to threads to stop after + request_stop() has been called. + +##### Raises: + + +* <b>RuntimeError</b>: If any thread is still alive after request_stop() + is called and the grace period expires. + + +- - - + +#### tf.train.Coordinator.request_stop(ex=None) {#Coordinator.request_stop} + +Request that the threads stop. + +After this is called, calls to should_stop() will return True. + +##### Args: + + +* <b>ex</b>: Optional Exception, or Python 'exc_info' tuple as returned by + sys.exc_info(). If this is the first call to request_stop() the + corresponding exception is recorded and re-raised from join(). + + +- - - + +#### tf.train.Coordinator.should_stop() {#Coordinator.should_stop} + +Check if stop was requested. + +##### Returns: + + True if a stop was requested. + + +- - - + +#### tf.train.Coordinator.wait_for_stop(timeout=None) {#Coordinator.wait_for_stop} + +Wait till the Coordinator is told to stop. + +##### Args: + + +* <b>timeout</b>: float. Sleep for up to that many seconds waiting for + should_stop() to become True. + +##### Returns: + + True if the Coordinator is told stop, False if the timeout expired. + + + +- - - + +### class tf.train.QueueRunner <div class="md-anchor" id="QueueRunner">{#QueueRunner}</div> + +Holds a list of enqueue operations for a queue, each to be run in a thread. + +Queues are a convenient TensorFlow mechanism to compute tensors +asynchronously using multiple threads. For example in the canonical 'Input +Reader' setup one set of threads generates filenames in a queue; a second set +of threads read records from the files, processes them, and enqueues tensors +on a second queue; a third set of threads dequeues these input records to +construct batches and runs them through training operations. + +There are several delicate issues when running multiple threads that way: +closing the queues in sequence as the input is exhausted, correctly catching +and reporting exceptions, etc. + +The `QueueRunner`, combined with the `Coordinator`, helps handle these issues. +- - - + +#### tf.train.QueueRunner.__init__(queue, enqueue_ops) {#QueueRunner.__init__} + +Create a QueueRunner. + +On construction the `QueueRunner` adds an op to close the queue. That op +will be run if the enqueue ops raise exceptions. + +When you later call the `create_threads()` method, the `QueueRunner` will +create one thread for each op in `enqueue_ops`. Each thread will run its +enqueue op in parallel with the other threads. The enqueue ops do not have +to all be the same op, but it is expected that they all enqueue tensors in +`queue`. + +##### Args: + + +* <b>queue</b>: A `Queue`. +* <b>enqueue_ops</b>: List of enqueue ops to run in threads later. + + +- - - + +#### tf.train.QueueRunner.create_threads(sess, coord=None, daemon=False, start=False) {#QueueRunner.create_threads} + +Create threads to run the enqueue ops. + +This method requires a session in which the graph was launched. It creates +a list of threads, optionally starting them. There is one thread for each +op passed in `enqueue_ops`. + +The `coord` argument is an optional coordinator, that the threads will use +to terminate together and report exceptions. If a coordinator is given, +this method starts an additional thread to close the queue when the +coordinator requests a stop. + +This method may be called again as long as all threads from a previous call +have stopped. + +##### Args: + + +* <b>sess</b>: A `Session`. +* <b>coord</b>: Optional `Coordinator` object for reporting errors and checking + stop conditions. +* <b>daemon</b>: Boolean. If `True` make the threads daemon threads. +* <b>start</b>: Boolean. If `True` starts the threads. If `False` the + caller must call the `start()` method of the returned threads. + +##### Returns: + + A list of threads. + +##### Raises: + + +* <b>RuntimeError</b>: If threads from a previous call to `create_threads()` are + still running. + + +- - - + +#### tf.train.QueueRunner.exceptions_raised {#QueueRunner.exceptions_raised} + +Exceptions raised but not handled by the `QueueRunner` threads. + +Exceptions raised in queue runner threads are handled in one of two ways +depending on whether or not a `Coordinator` was passed to +`create_threads()`: + +* With a `Coordinator`, exceptions are reported to the coordinator and + forgotten by the `QueueRunner`. +* Without a `Coordinator`, exceptions are captured by the `QueueRunner` and + made available in this `exceptions_raised` property. + +##### Returns: + + A list of Python `Exception` objects. The list is empty if no exception + was captured. (No exceptions are captured when using a Coordinator.) + + +- - - + +### tf.train.add_queue_runner(qr, collection='queue_runners') <div class="md-anchor" id="add_queue_runner">{#add_queue_runner}</div> + +Adds a `QueueRunner` to a collection in the graph. + +When building a complex model that uses many queues it is often difficult to +gather all the queue runners that need to be run. This convenience function +allows you to add a queue runner to a well known collection in the graph. + +The companion method `start_queue_runners()` can be used to start threads for +all the collected queue runners. + +##### Args: + + +* <b>qr</b>: A `QueueRunner`. +* <b>collection</b>: A `GraphKey` specifying the graph collection to add + the queue runner to. Defaults to `GraphKeys.QUEUE_RUNNERS`. + + +- - - + +### tf.train.start_queue_runners(sess=None, coord=None, daemon=True, start=True, collection='queue_runners') <div class="md-anchor" id="start_queue_runners">{#start_queue_runners}</div> + +Starts all queue runners collected in the graph. + +This is a companion method to `add_queue_runner()`. It just starts +threads for all queue runners collected in the graph. It returns +the list of all threads. + +##### Args: + + +* <b>sess</b>: `Session` used to run the queue ops. Defaults to the + default session. +* <b>coord</b>: Optional `Coordinator` for coordinating the started threads. +* <b>daemon</b>: Whether the threads should be marked as `daemons`, meaning + they don't block program exit. +* <b>start</b>: Set to `False` to only create the threads, not start them. +* <b>collection</b>: A `GraphKey` specifying the graph collection to + get the queue runners from. Defaults to `GraphKeys.QUEUE_RUNNERS`. + +##### Returns: + + A list of threads. + + + +## Summary Operations. <div class="md-anchor" id="AUTOGENERATED-summary-operations.">{#AUTOGENERATED-summary-operations.}</div> + +The following ops output +[`Summary`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +protocol buffers as serialized string tensors. + +You can fetch the output of a summary op in a session, and pass it to a +[SummaryWriter](train.md#SummaryWriter) to append it to an event file. You can +then use TensorBoard to visualize the contents of the event files. See +[TensorBoard and Summaries](../../how_tos/summaries_and_tensorboard/index.md) +for more details. + +- - - + +### tf.scalar_summary(tags, values, collections=None, name=None) <div class="md-anchor" id="scalar_summary">{#scalar_summary}</div> + +Outputs a `Summary` protocol buffer with scalar values. + +The input `tags` and `values` must have the same shape. The generated +summary has a summary value for each tag-value pair in `tags` and `values`. + +##### Args: + + +* <b>tags</b>: A 1-D `string` `Tensor`. Tags for the summaries. +* <b>values</b>: A 1-D `float32` or `float64` Tensor. Values for the summaries. +* <b>collections</b>: Optional list of graph collections keys. The new summary op is + added to these collections. Defaults to `[GraphKeys.SUMMARIES]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer. + + +- - - + +### tf.image_summary(tag, tensor, max_images=None, collections=None, name=None) <div class="md-anchor" id="image_summary">{#image_summary}</div> + +Outputs a `Summary` protocol buffer with images. + +The summary has up to `max_images` summary values containing images. The +images are built from `tensor` which must be 4-D with shape `[batch_size, +height, width, channels]` and where `channels` can be: + +* 1: `tensor` is interpreted as Grayscale. +* 3: `tensor` is interpreted as RGB. +* 4: `tensor` is interpreted as RGBA. + +The images have the same number of channels as the input tensor. Their values +are normalized, one image at a time, to fit in the range `[0, 255]`. The +op uses two different normalization algorithms: + +* If the input values are all positive, they are rescaled so the largest one + is 255. + +* If any input value is negative, the values are shifted so input value 0.0 + is at 127. They are then rescaled so that either the smallest value is 0, + or the largest one is 255. + +The `tag` argument is a scalar `Tensor` of type `string`. It is used to +build the `tag` of the summary values: + +* If `max_images` is 1, the summary value tag is '*tag*/image'. +* If `max_images` is greater than 1, the summary value tags are + generated sequentially as '*tag*/image/0', '*tag*/image/1', etc. + +##### Args: + + +* <b>tag</b>: A scalar `Tensor` of type `string`. Used to build the `tag` + of the summary values. +* <b>tensor</b>: A 4-D `float32` `Tensor` of shape `[batch_size, height, width, + channels]` where `channels` is 1, 3, or 4. +* <b>max_images</b>: Max number of batch elements to generate images for. +* <b>collections</b>: Optional list of ops.GraphKeys. The collections to add the + summary to. Defaults to [ops.GraphKeys.SUMMARIES] +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer. + + +- - - + +### tf.histogram_summary(tag, values, collections=None, name=None) <div class="md-anchor" id="histogram_summary">{#histogram_summary}</div> + +Outputs a `Summary` protocol buffer with a histogram. + +The generated +[`Summary`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +has one summary value containing a histogram for `values`. + +This op reports an `OutOfRange` error if any value is not finite. + +##### Args: + + +* <b>tag</b>: A `string` `Tensor`. 0-D. Tag to use for the summary value. +* <b>values</b>: A `float32` `Tensor`. Any shape. Values to use to build the + histogram. +* <b>collections</b>: Optional list of graph collections keys. The new summary op is + added to these collections. Defaults to `[GraphKeys.SUMMARIES]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer. + + +- - - + +### tf.nn.zero_fraction(value, name=None) <div class="md-anchor" id="zero_fraction">{#zero_fraction}</div> + +Returns the fraction of zeros in `value`. + +If `value` is empty, the result is `nan`. + +This is useful in summaries to measure and report sparsity. For example, + + z = tf.Relu(...) + summ = tf.scalar_summary('sparsity', tf.zero_fraction(z)) + +##### Args: + + +* <b>value</b>: A tensor of numeric type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The fraction of zeros in `value`, with type `float32`. + + + +- - - + +### tf.merge_summary(inputs, collections=None, name=None) <div class="md-anchor" id="merge_summary">{#merge_summary}</div> + +Merges summaries. + +This op creates a +[`Summary`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +protocol buffer that contains the union of all the values in the input +summaries. + +When the Op is run, it reports an `InvalidArgument` error if multiple values +in the summaries to merge use the same tag. + +##### Args: + + +* <b>inputs</b>: A list of `string` `Tensor` objects containing serialized `Summary` + protocol buffers. +* <b>collections</b>: Optional list of graph collections keys. The new summary op is + added to these collections. Defaults to `[GraphKeys.SUMMARIES]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer resulting from the merging. + + +- - - + +### tf.merge_all_summaries(key='summaries') <div class="md-anchor" id="merge_all_summaries">{#merge_all_summaries}</div> + +Merges all summaries collected in the default graph. + +##### Args: + + +* <b>key</b>: `GraphKey` used to collect the summaries. Defaults to + `GraphKeys.SUMMARIES`. + +##### Returns: + + If no summaries were collected, returns None. Otherwise returns a scalar + `Tensor` of type`string` containing the serialized `Summary` protocol + buffer resulting from the merging. + + + +## Adding Summaries to Event Files. <div class="md-anchor" id="AUTOGENERATED-adding-summaries-to-event-files.">{#AUTOGENERATED-adding-summaries-to-event-files.}</div> + +See [Summaries and +TensorBoard](../../how_tos/summaries_and_tensorboard/index.md) for an +overview of summaries, event files, and visualization in TensorBoard. + +- - - + +### class tf.train.SummaryWriter <div class="md-anchor" id="SummaryWriter">{#SummaryWriter}</div> + +Writes `Summary` protocol buffers to event files. + +The `SummaryWriter` class provides a mechanism to create an event file in a +given directory and add summaries and events to it. The class updates the +file contents asynchronously. This allows a training program to call methods +to add data to the file directly from the training loop, without slowing down +training. + +- - - + +#### tf.train.SummaryWriter.__init__(logdir, graph_def=None, max_queue=10, flush_secs=120) {#SummaryWriter.__init__} + +Creates a `SummaryWriter` and an event file. + +On construction the summary writer creates a new event file in `logdir`. +This event file will contain `Event` protocol buffers constructed when you +call one of the following functions: `add_summary()`, `add_event()`, or +`add_graph()`. + +If you pass a `graph_def` protocol buffer to the constructor it is added to +the event file. (This is equivalent to calling `add_graph()` later). + +TensorBoard will pick the graph from the file and display it graphically so +you can interactively explore the graph you built. You will usually pass +the graph from the session in which you launched it: + +```python +...create a graph... +# Launch the graph in a session. +sess = tf.Session() +# Create a summary writer, add the 'graph_def' to the event file. +writer = tf.train.SummaryWriter(<some-directory>, sess.graph_def) +``` + +The other arguments to the constructor control the asynchronous writes to +the event file: + +* `flush_secs`: How often, in seconds, to flush the added summaries + and events to disk. +* `max_queue`: Maximum number of summaries or events pending to be + written to disk before one of the 'add' calls block. + +##### Args: + + +* <b>logdir</b>: A string. Directory where event file will be written. +* <b>graph_def</b>: A `GraphDef` protocol buffer. +* <b>max_queue</b>: Integer. Size of the queue for pending events and summaries. +* <b>flush_secs</b>: Number. How often, in seconds, to flush the + pending events and summaries to disk. + + + +- - - + +#### tf.train.SummaryWriter.add_summary(summary, global_step=None) {#SummaryWriter.add_summary} + +Adds a `Summary` protocol buffer to the event file. + +This method wraps the provided summary in an `Event` procotol buffer +and adds it to the event file. + +You can pass the output of any summary op, as-is, to this function. You +can also pass a `Summary` procotol buffer that you manufacture with your +own data. This is commonly done to report evaluation results in event +files. + +##### Args: + + +* <b>summary</b>: A `Summary` protocol buffer, optionally serialized as a string. +* <b>global_step</b>: Number. Optional global step value to record with the + summary. + + +- - - + +#### tf.train.SummaryWriter.add_event(event) {#SummaryWriter.add_event} + +Adds an event to the event file. + +##### Args: + + +* <b>event</b>: An `Event` protocol buffer. + + +- - - + +#### tf.train.SummaryWriter.add_graph(graph_def, global_step=None) {#SummaryWriter.add_graph} + +Adds a `GraphDef` protocol buffer to the event file. + +The graph described by the protocol buffer will be displayed by +TensorBoard. Most users pass a graph in the constructor instead. + +##### Args: + + +* <b>graph_def</b>: A `GraphDef` protocol buffer. +* <b>global_step</b>: Number. Optional global step counter to record with the + graph. + + + +- - - + +#### tf.train.SummaryWriter.flush() {#SummaryWriter.flush} + +Flushes the event file to disk. + +Call this method to make sure that all pending events have been written to +disk. + + +- - - + +#### tf.train.SummaryWriter.close() {#SummaryWriter.close} + +Flushes the event file to disk and close the file. + +Call this method when you do not need the summary writer anymore. + + + +- - - + +### tf.train.summary_iterator(path) <div class="md-anchor" id="summary_iterator">{#summary_iterator}</div> + +An iterator for reading `Event` protocol buffers from an event file. + +You can use this function to read events written to an event file. It returns +a Python iterator that yields `Event` protocol buffers. + +Example: Print the contents of an events file. + +```python +for e in tf.summary_iterator(path to events file): + print e +``` + +Example: Print selected summary values. + +```python +# This example supposes that the events file contains summaries with a +# summary value tag 'loss'. These could have been added by calling +# `add_summary()`, passing the output of a scalar summary op created with +# with: `tf.scalar_summary(['loss'], loss_tensor)`. +for e in tf.summary_iterator(path to events file): + for v in e.summary.value: + if v.tag == 'loss': + print v.simple_value +``` + +See the protocol buffer definitions of +[Event](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/util/event.proto) +and +[Summary](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +for more information about their attributes. + +##### Args: + + +* <b>path</b>: The path to an event file created by a `SummaryWriter`. + +##### Yields: + + `Event` protocol buffers. + + + +## Training utilities. <div class="md-anchor" id="AUTOGENERATED-training-utilities.">{#AUTOGENERATED-training-utilities.}</div> + +- - - + +### tf.train.global_step(sess, global_step_tensor) <div class="md-anchor" id="global_step">{#global_step}</div> + +Small helper to get the global step. + +```python +# Creates a variable to hold the global_step. +global_step_tensor = tf.Variable(10, trainable=False, name='global_step') +# Creates a session. +sess = tf.Session() +# Initializes the variable. +sess.run(global_step_tensor.initializer) +print 'global_step:', tf.train.global_step(sess, global_step_tensor) + +global_step: 10 +``` + +##### Args: + + +* <b>sess</b>: A brain `Session` object. +* <b>global_step_tensor</b>: `Tensor` or the `name` of the operation that contains + the global step. + +##### Returns: + + The global step value. + + +- - - + +### tf.train.write_graph(graph_def, logdir, name, as_text=True) <div class="md-anchor" id="write_graph">{#write_graph}</div> + +Writes a graph proto on disk. + +The graph is written as a binary proto unless as_text is `True`. + +```python +v = tf.Variable(0, name='my_variable') +sess = tf.Session() +tf.train.write_graph(sess.graph_def, '/tmp/my-model', 'train.pbtxt') +``` + +##### Args: + + +* <b>graph_def</b>: A `GraphDef` protocol buffer. +* <b>logdir</b>: Directory where to write the graph. +* <b>name</b>: Filename for the graph. +* <b>as_text</b>: If `True`, writes the graph as an ASCII proto. + + |