TensorFlow: Upstream changes to git.

Changes:

- Update a lot of documentation, installation instructions,
  requirements, etc.

- Add RNN models directory for recurrent neural network
  examples to go along with the tutorials.

Base CL: 107290480

Author: Vijay Vasudevan

CONTRIBUTING.md

@@ -15,3 +15,14 @@ Follow either of the two links above to access the appropriate CLA and instructi
 
 ***NOTE***: Only original source code from you and other people that have signed the CLA can be accepted into the main repository.
 
+## Contributing code
+
+We currently use Gerrit to host and handle code changes to TensorFlow.  The main
+site is
+[https://tensorflow-review.googlesource.com/](https://tensorflow-review.googlesource.com/).
+See Gerrit [docs](https://gerrit-review.googlesource.com/Documentation/) for
+information on how Gerrit's code review system works.
+
+We are currently working on improving our external acceptance process, so
+please be patient with us as we work out the details.
+

README.md

@@ -14,7 +14,7 @@ variety of other domains, as well.
 # Download and Setup
 
 For detailed installation instructions, see
-[here](g3doc/get_started/os_setup.md).
+[here](tensorflow/g3doc/get_started/os_setup.md).
 
 ## Binary Installation
 

tensorflow/g3doc/api_docs/python/framework.md

@@ -27,7 +27,7 @@
   * [class tf.RegisterShape](#RegisterShape)
   * [class tf.TensorShape](#TensorShape)
   * [class tf.Dimension](#Dimension)
-  * [tf.op_scope(*args, **kwds)](#op_scope)
+  * [tf.op_scope(values, name, default_name)](#op_scope)
   * [tf.get_seed(op_seed)](#get_seed)
 
 
@@ -235,7 +235,7 @@ def my_func(pred, tensor):
 
 - - -
 
-#### tf.Graph.device(*args, **kwds) {#Graph.device}
+#### tf.Graph.device(device_name_or_function) {#Graph.device}
 
 Returns a context manager that specifies the default device to use.
 
@@ -287,7 +287,7 @@ with g.device(matmul_on_gpu):
 
 - - -
 
-#### tf.Graph.name_scope(*args, **kwds) {#Graph.name_scope}
+#### tf.Graph.name_scope(name) {#Graph.name_scope}
 
 Returns a context manager that creates hierarchical names for operations.
 
@@ -611,7 +611,7 @@ the default graph.
 
 - - -
 
-#### tf.Graph.gradient_override_map(*args, **kwds) {#Graph.gradient_override_map}
+#### tf.Graph.gradient_override_map(op_type_map) {#Graph.gradient_override_map}
 
 EXPERIMENTAL: A context manager for overriding gradient functions.
 
@@ -2023,7 +2023,7 @@ 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>
+### tf.op_scope(values, name, default_name) <div class="md-anchor" id="op_scope">{#op_scope}</div>
 
 Returns a context manager for use when defining a Python op.
 

tensorflow/g3doc/api_docs/python/index.md

@@ -267,7 +267,6 @@
   * [`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)

tensorflow/g3doc/api_docs/python/nn.md

@@ -35,7 +35,6 @@ accepted by [`tf.convert_to_tensor`](framework.md#convert_to_tensor).
   * [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)
@@ -130,17 +129,18 @@ 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
+to the shape of `x`, and only dimensions with `noise_shape[i] == shape(x)[i]`
+will make independent decisions.  For example, if `shape(x) = [k, l, m, n]`
+and `noise_shape = [k, 1, 1, n]`, 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>keep_prob</b>: A Python float. The probability that each element is kept.
+*  <b>noise_shape</b>: A 1-D `Tensor` of type `int32`, representing the
+    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).
@@ -247,10 +247,10 @@ 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],
-                    ...]
+    shape(output) = [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, ...] *
@@ -262,7 +262,7 @@ 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:
+In the formula for `shape(output)`, the rounding direction depends on padding:
 
 * `padding = 'SAME'`: Round down (only full size windows are considered).
 * `padding = 'VALID'`: Round up (partial windows are included).
@@ -411,7 +411,7 @@ In detail, the output is
 
 for each tuple of indices `i`.  The output shape is
 
-    output.shape = (value.shape - ksize + 1) / strides
+    shape(output) = (shape(value) - ksize + 1) / strides
 
 where the rounding direction depends on padding:
 
@@ -722,103 +722,43 @@ and the same dtype (either `float32` or `float64`).
 
 ## Embeddings <div class="md-anchor" id="AUTOGENERATED-embeddings">{#AUTOGENERATED-embeddings}</div>
 
-TensorFlow provides several operations that help you compute embeddings.
+TensorFlow provides library support for looking up values in embedding
+tensors.
 
 - - -
 
 ### 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".
+Looks up `ids` in a list of embedding tensors.
 
-##### 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.
+This function is used to perform parallel lookups on the list of
+tensors in `params`.  It is a generalization of
+[`tf.gather()`](array_ops.md#gather), where `params` is interpreted
+as a partition of a larger embedding tensor.
 
+If `len(params) > 1`, each element `id` of `ids` is partitioned between
+the elements of `params` by computing `p = id % len(params)`, and is
+then used to look up the slice `params[p][id // len(params), ...]`.
 
-- - -
-
-### 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.
+The results of the lookup are then concatenated into a dense
+tensor. The returned tensor has shape `shape(ids) + shape(params)[1:]`.
 
 ##### 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.
+*  <b>params</b>: A list of tensors with the same shape and type.
+*  <b>ids</b>: A `Tensor` with type `int32` containing the ids to be looked
+    up in `params`.
+*  <b>name</b>: A name for the operation (optional).
 
 ##### 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
+  A `Tensor` with the same type as the tensors in `params`.
 
 ##### 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"}.
+*  <b>ValueError</b>: If `params` is empty.
 
 
 

tensorflow/g3doc/api_docs/python/state_ops.md

@@ -23,7 +23,7 @@ accepted by [`tf.convert_to_tensor`](framework.md#convert_to_tensor).
 * [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.variable_scope(name_or_scope, reuse=None, initializer=None)](#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)
@@ -896,7 +896,7 @@ Returns the current variable scope.
 
 - - -
 
-### tf.variable_scope(*args, **kwds) <div class="md-anchor" id="variable_scope">{#variable_scope}</div>
+### tf.variable_scope(name_or_scope, reuse=None, initializer=None) <div class="md-anchor" id="variable_scope">{#variable_scope}</div>
 
 Returns a context for variable scope.
 

tensorflow/g3doc/get_started/os_setup.md

@@ -36,7 +36,33 @@ Install TensorFlow (only CPU binary version is currently available).
 $ sudo pip install https://storage.googleapis.com/tensorflow/mac/tensorflow-0.5.0-py2-none-any.whl
 ```
 
-### Try your first TensorFlow program
+## Docker-based installation
+
+We also support running TensorFlow via [Docker](http://docker.com/), which lets
+you avoid worrying about setting up dependencies.
+
+First, [install Docker](http://docs.docker.com/engine/installation/). Once
+Docker is up and running, you can start a container with one command:
+
+```sh
+$ docker run -it b.gcr.io/tensorflow/tensorflow
+```
+
+This will start a container with TensorFlow and all its dependencies already
+installed.
+
+### Additional images
+
+The default Docker image above contains just a minimal set of libraries for
+getting up and running with TensorFlow. We also have several other containers,
+which you can use in the `docker run` command above:
+
+* `b.gcr.io/tensorflow/tensorflow-full`: Contains a complete TensorFlow source
+  installation, including all utilities needed to build and run TensorFlow. This
+  makes it easy to experiment directly with the source, without needing to
+  install any of the dependencies described above.
+
+## Try your first TensorFlow program
 
 ```sh
 $ python
@@ -133,6 +159,13 @@ $ sudo apt-get install python-numpy swig python-dev
 In order to build TensorFlow with GPU support, both Cuda Toolkit 7.0 and CUDNN
 6.5 V2 from NVIDIA need to be installed.
 
+TensorFlow GPU support requires having a GPU card with NVidia Compute Capability >= 3.5.  Supported cards include but are not limited to:
+
+* NVidia Titan
+* NVidia Titan X
+* NVidia K20
+* NVidia K40
+
 ##### Download and install Cuda Toolkit 7.0
 
 https://developer.nvidia.com/cuda-toolkit-70
@@ -227,7 +260,7 @@ Notes : You need to install
 Follow installation instructions [here](http://docs.scipy.org/doc/numpy/user/install.html).
 
 
-### Create the pip package and install
+### Create the pip package and install {#create-pip}
 
 ```sh
 $ bazel build -c opt //tensorflow/tools/pip_package:build_pip_package
@@ -238,7 +271,7 @@ $ bazel-bin/tensorflow/tools/pip_package/build_pip_package /tmp/tensorflow_pkg
 $ pip install /tmp/tensorflow_pkg/tensorflow-0.5.0-cp27-none-linux_x86_64.whl
 ```
 
-### Train your first TensorFlow neural net model
+## Train your first TensorFlow neural net model
 
 From the root of your source tree, run:
 

tensorflow/g3doc/how_tos/adding_an_op/index.md

@@ -127,10 +127,9 @@ To do this for the `ZeroOut` op, add the following to `zero_out.cc`:
 REGISTER_KERNEL_BUILDER(Name("ZeroOut").Device(DEVICE_CPU), ZeroOutOp);
 ```
 
-TODO: instructions or pointer to building TF
-
-At this point, the Tensorflow system can reference and use the Op when
-requested.
+Once you
+[build and reinstall TensorFlow](../../get_started/os_setup.md#create-pip), the
+Tensorflow system can reference and use the Op when requested.
 
 ## Generate the client wrapper <div class="md-anchor" id="AUTOGENERATED-generate-the-client-wrapper">{#AUTOGENERATED-generate-the-client-wrapper}</div>
 ### The Python Op wrapper <div class="md-anchor" id="AUTOGENERATED-the-python-op-wrapper">{#AUTOGENERATED-the-python-op-wrapper}</div>

tensorflow/g3doc/how_tos/variables/index.md

@@ -101,7 +101,7 @@ w_twice = tf.Variable(weights.initialized_value() * 0.2, name="w_twice")
 The convenience function `tf.initialize_all_variables()` adds an Op to
 initialize *all variables* in the model.  You can also pass it an explicit list
 of variables to initialize.  See the
-[Variables Documentation](../../api_docs/python/state_op.md) for more options,
+[Variables Documentation](../../api_docs/python/state_ops.md) for more options,
 including checking if variables are initialized.
 
 ## Saving and Restoring