Javadoc and rebase

Signed-off-by: Ryan Nett <[email protected]>

Author: rnett

ndarray/src/main/java/org/tensorflow/ndarray/index/At.java

@@ -71,12 +71,4 @@ public String toString() {
         .add("keepDim=" + keepDim)
         .toString();
   }
-
-  @Override
-  public String toString() {
-    return new StringJoiner(", ", At.class.getSimpleName() + "(", ")")
-        .add("coord=" + coord)
-        .add("keepDim=" + keepDim)
-        .toString();
-  }
 }

ndarray/src/main/java/org/tensorflow/ndarray/index/Ellipsis.java

@@ -45,9 +45,4 @@ public boolean isEllipsis() {
   public String toString() {
     return Ellipsis.class.getSimpleName() + "()";
   }
-
-  @Override
-  public String toString() {
-    return "Ellipsis()";
-  }
 }

ndarray/src/main/java/org/tensorflow/ndarray/index/NewAxis.java

@@ -50,9 +50,4 @@ public boolean isNewAxis() {
   public String toString() {
     return NewAxis.class.getSimpleName() + "()";
   }
-
-  @Override
-  public String toString() {
-    return NewAxis.class.getSimpleName() + "()";
-  }
 }

tensorflow-core/tensorflow-core-api/src/gen/annotations/org/tensorflow/op/Ops.java

@@ -60,6 +60,7 @@
 import org.tensorflow.op.core.BatchToSpaceNd;
 import org.tensorflow.op.core.Bitcast;
 import org.tensorflow.op.core.BooleanMask;
+import org.tensorflow.op.core.BooleanMaskUpdate;
 import org.tensorflow.op.core.BroadcastDynamicShape;
 import org.tensorflow.op.core.BroadcastTo;
 import org.tensorflow.op.core.Bucketize;
@@ -95,7 +96,6 @@
 import org.tensorflow.op.core.Identity;
 import org.tensorflow.op.core.IdentityN;
 import org.tensorflow.op.core.ImmutableConst;
-import org.tensorflow.op.core.Indexing;
 import org.tensorflow.op.core.Init;
 import org.tensorflow.op.core.InitializeTable;
 import org.tensorflow.op.core.InitializeTableFromTextFile;
@@ -349,10 +349,10 @@ public final class Ops {
 
   public final SignalOps signal;
 
-  public final QuantizationOps quantization;
-
   public final TrainOps train;
 
+  public final QuantizationOps quantization;
+
   private final Scope scope;
 
   private Ops(Scope scope) {
@@ -374,8 +374,8 @@ private Ops(Scope scope) {
     math = new MathOps(this);
     audio = new AudioOps(this);
     signal = new SignalOps(this);
-    quantization = new QuantizationOps(this);
     train = new TrainOps(this);
+    quantization = new QuantizationOps(this);
   }
 
   /**
@@ -992,9 +992,9 @@ public <U extends TType> Bitcast<U> bitcast(Operand<? extends TType> input, Clas
   }
 
   /**
-   * Apply boolean mask to tensor.
+   * Apply boolean mask to tensor.  Returns the flat array of each element corresponding to a {@code true} in the mask.
    *  <p>
-   *  Numpy equivalent is `tensor[mask]`.
+   *  Numpy equivalent is {@code tensor[mask]}.
    *  <p>
    *  In general, {@code 0 < dim(mask) = K <= dim(tensor)}, and {@code mask}'s shape must match
    *  the first K dimensions of {@code tensor}'s shape.  We then have:
@@ -1016,6 +1016,36 @@ public <T extends TType> Operand<T> booleanMask(Operand<T> tensor, Operand<TBool
     return BooleanMask.create(scope, tensor, mask, options);
   }
 
+  /**
+   * Updates a tensor at the masked values, and returns the updated tensor.  Does not mutate the input tensors.  {@code
+   *  updates} will be broadcasted by default
+   *  <p>
+   *  Numpy equivalent is `tensor[mask] = updates`.
+   *  <p>
+   *  In general, {@code 0 < dim(mask) = K <= dim(tensor)}, and {@code mask}'s shape must match the first K dimensions of
+   *  {@code tensor}'s shape.  We then have: {@code booleanMask(tensor, mask)[i, j1,...,jd] =
+   *  tensor[i1,...,iK,j1,...,jd]} where {@code (i1,...,iK)} is the ith {@code true} entry of {@code mask} (row-major
+   *  order).
+   *  <p>
+   *  The {@code axis} could be used with {@code mask} to indicate the axis to mask from (it's 0 by default). In that
+   *  case, {@code axis + dim(mask) <= dim(tensor)} and {@code mask}'s shape must match the first {@code axis +
+   *  dim(mask)} dimensions of {@code tensor}'s shape.
+   *  <p>
+   *  The shape of {@code updates} should be {@code [n, t_1, t_2, ...]} where {@code n} is the number of true values in
+   *  {@code mask} and {@code t_i} is the {@code i}th dimension of {@code tensor} after {@code axis} and {@code mask}.
+   *  {@code updates} will be broadcasted to this shape by default, which can be disabled using {@code options}.
+   *
+   * @param tensor The tensor to mask.
+   * @param mask The mask to apply.
+   * @param updates the new values
+   * @param options carries optional attributes values
+   * @return The masked tensor.
+   */
+  public <T extends TType> Operand<T> booleanMaskUpdate(Operand<T> tensor, Operand<TBool> mask,
+      Operand<T> updates, BooleanMaskUpdate.Options... options) {
+    return BooleanMaskUpdate.create(scope, tensor, mask, updates, options);
+  }
+
   /**
    * Return the shape of s0 op s1 with broadcast.
    *  <p>
@@ -1861,13 +1891,14 @@ public Constant<TInt32> constant(Shape shape, IntDataBuffer data) {
   }
 
   /**
-   * Creates a scalar of {@code type}, with the value of {@code number}.
-   *  {@code number} may be truncated if it does not fit in the target type.
+   * Creates a scalar of {@code type}, with the value of {@code number}. {@code number} may be truncated if it does not
+   *  fit in the target type.
    *
    * @param type the type of tensor to create.  Must be concrete (i.e. not {@link org.tensorflow.types.family.TFloating})
    * @param number the value of the tensor
    * @return a constant of the passed type
-   * @throws IllegalArgumentException if the type is abstract (i.e. {@link org.tensorflow.types.family.TFloating}) or unknown.
+   * @throws IllegalArgumentException if the type is abstract (i.e. {@link org.tensorflow.types.family.TFloating}) or
+   *  unknown.
    */
   public <T extends TNumber> Constant<T> constant(Class<T> type, Number number) {
     return Constant.tensorOf(scope, type, number);
@@ -1919,14 +1950,14 @@ public <T extends TType> Constant<T> constantOf(T tensor) {
   }
 
   /**
-   * Creates a scalar of the same type as {@code toMatch}, with the value of {@code number}.
-   *  {@code number} may be truncated if it does not fit in the target type.
+   * Creates a scalar of the same type as {@code toMatch}, with the value of {@code number}. {@code number} may be
+   *  truncated if it does not fit in the target type.
    *
    * @param toMatch the operand providing the target type
    * @param number the value of the tensor
    * @return a constant with the same type as {@code toMatch}
-   * @see Ops#constant(Class, Number)
    * @throws IllegalArgumentException if the type is unknown (which should be impossible).
+   * @see Ops#constant(Class, Number)
    */
   public <T extends TNumber> Constant<T> constantOfSameType(Operand<T> toMatch, Number number) {
     return Constant.tensorOfSameType(scope, toMatch, number);
@@ -5950,61 +5981,6 @@ public <T extends TType> StopGradient<T> stopGradient(Operand<T> input) {
     return StopGradient.create(scope, input);
   }
 
-  /**
-   * Return a strided slice from `input`.
-   *   <p>
-   *   The goal of this op is to produce a new tensor with a subset of
-   *   the elements from the `n` dimensional `input` tensor. The subset is chosen using
-   *   a sequence of `m` sparse range specifications encoded into the arguments
-   *   of this function. Note, in some cases
-   *   `m` could be equal to `n`, but this need not be the case. Each
-   *   range specification entry can be one of the following:
-   *   <p>
-   *   - An ellipsis (...) using {@link Index#ellipses()}. Ellipses are used to imply zero or more
-   *     dimensions of full-dimension selection and are produced using
-   *     `ellipsis_mask`. For example, `foo[...]` is the identity slice.
-   *   <p>
-   *   - A new axis using {@link Index#newAxis()}. This is used to insert a new shape=1 dimension and is
-   *     produced using `new_axis_mask`. For example, `foo[:, ...]` where
-   *     `foo` is shape `(3, 4)` produces a `(1, 3, 4)` tensor.
-   *   <p>
-   *   - A range `begin:end:stride` using {@link Index#slice(Singular, Singular, int) Index.slice()} or {@link Index#all()}. This is used to specify how much to choose from
-   *     a given dimension. `stride` can be any integer but 0.  `begin` is an integer
-   *     which represents the index of the first value to select while `end` represents
-   *     the index of the last value to select. The number of values selected in each
-   *     dimension is `end - begin` if `stride > 0` and `begin - end` if `stride < 0`.
-   *     `begin` and `end` can be negative where `-1` is the last element, `-2` is
-   *     the second to last. `begin_mask` controls whether to replace the explicitly
-   *     given `begin` with an implicit effective value of `0` if `stride > 0` and
-   *     `-1` if `stride < 0`. `end_mask` is analogous but produces the number
-   *     required to create the largest open interval. For example, given a shape
-   *     `(3,)` tensor `foo[:]`, the effective `begin` and `end` are `0` and `3`. Do
-   *     not assume this is equivalent to `foo[0:-1]` which has an effective `begin`
-   *     and `end` of `0` and `2`. Another example is `foo[-2::-1]` which reverses the
-   *     first dimension of a tensor while dropping the last two (in the original
-   *     order elements). For example `foo = [1,2,3,4]; foo[-2::-1]` is `[4,3]`.
-   *   <p>
-   *   - A single index using {@link Index#point(int)}. This is used to keep only elements that have a given
-   *     index. For example (`foo[2, :]` on a shape `(5,6)` tensor produces a
-   *     shape `(6,)` tensor. This is encoded in `begin` and `end` and
-   *     `shrink_axis_mask`.
-   *   <p>
-   *
-   *   <i>Requirements</i>:
-   *     `0 != strides[i] for i in [0, m)`
-   *     Only one ellipsis.
-   *
-   * @param scope current scope
-   * @param <T> data type for {@code output()} output
-   * @param input
-   * @param indices The indices to slice.  See {@link Index}.
-   * @return a new instance of StridedSlice
-   * @see Index
-   */
-  public <T extends TType> StridedSlice<T> stridedSlice(Operand<T> input, Index... indices) {
-    return Indexing.stridedSlice(scope, input, indices);
-  }
-
   /**
    * Return a strided slice from `input`.
    *  <p>
@@ -6167,29 +6143,6 @@ public <T extends TType, U extends TNumber> StridedSlice<T> stridedSlice(Operand
     return StridedSlice.create(scope, input, begin, end, strides, options);
   }
 
-  /**
-   * Assign `value` to the sliced l-value reference of `ref`.
-   *   <p>
-   *   The values of `value` are assigned to the positions in the variable
-   *   `ref` that are selected by the slice parameters. The slice parameters
-   *   `begin`, `end`, `strides`, etc. work exactly as in `StridedSlice`.
-   *   <p>
-   *   NOTE this op currently does not support broadcasting and so `value`'s
-   *   shape must be exactly the shape produced by the slice of `ref`.
-   *
-   * @param <T> data type for {@code outputRef()} output
-   * @param scope current scope
-   * @param ref the tensor to assign to.
-   * @param value the value to assign.
-   * @param indices The indices to slice.  See {@link Index}.
-   * @return a new instance of StridedSliceAssign
-   * @see org.tensorflow.op.Ops#stridedSlice(Operand, Index...)
-   */
-  public <T extends TType> StridedSliceAssign<T> stridedSliceAssign(Operand<T> ref,
-      Operand<T> value, Index... indices) {
-    return Indexing.stridedSliceAssign(scope, ref, value, indices);
-  }
-
   /**
    * Assign `value` to the sliced l-value reference of `ref`.
    *  <p>

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/op/core/BooleanMask.java

@@ -21,7 +21,6 @@
 import org.tensorflow.Operand;
 import org.tensorflow.ndarray.Shape;
 import org.tensorflow.ndarray.index.Indices;
-import org.tensorflow.op.Ops;
 import org.tensorflow.op.Scope;
 import org.tensorflow.op.annotation.Endpoint;
 import org.tensorflow.op.annotation.Operator;
@@ -36,7 +35,7 @@ public abstract class BooleanMask {
   /**
    * Apply boolean mask to tensor.  Returns the flat array of each element corresponding to a {@code true} in the mask.
    * <p>
-   * Numpy equivalent is `tensor[mask]`.
+   * Numpy equivalent is {@code tensor[mask]}.
    * <p>
    * In general, {@code 0 < dim(mask) = K <= dim(tensor)}, and {@code mask}'s shape must match
    * the first K dimensions of {@code tensor}'s shape.  We then have:

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/op/core/BooleanMaskUpdate.java

@@ -17,7 +17,6 @@
 package org.tensorflow.op.core;
 
 import java.util.Arrays;
-import java.util.Collections;
 import org.tensorflow.Operand;
 import org.tensorflow.ndarray.Shape;
 import org.tensorflow.ndarray.index.Indices;
@@ -32,50 +31,24 @@
 @Operator
 public abstract class BooleanMaskUpdate {
 
-  /*
-  Python:
-  def boolean_mask_update(tensor, mask, update, axis=0, name="boolean_mask_update"):
-  with tf.name_scope(name):
-    tensor = tf.convert_to_tensor(tensor, name="tensor")
-    mask = tf.convert_to_tensor(mask, name="mask")
-    update = tf.convert_to_tensor(update, name="value")
-
-    shape_mask = mask.get_shape()
-    ndims_mask = shape_mask.ndims
-    shape_tensor = tensor.get_shape()
-    if ndims_mask == 0:
-      raise ValueError("mask cannot be scalar.")
-    if ndims_mask is None:
-      raise ValueError(
-          "Number of mask dimensions must be specified, even if some dimensions"
-          " are None.  E.g. shape=[None] is ok, but shape=None is not.")
-    axis = 0 if axis is None else axis
-    axis_value = tf.constant(axis)
-    if axis_value is not None:
-      axis = axis_value
-      shape_tensor[axis:axis + ndims_mask].assert_is_compatible_with(shape_mask)
-
-    leading_size = tf.reduce_prod(tf.shape(tensor)[:axis + ndims_mask], [0])
-    innerShape = tf.shape(tensor)[axis + ndims_mask:]
-
-    tensor = tf.reshape(
-        tensor,
-        tf.concat([
-          [leading_size],
-          innerShape
-        ], 0))
-
-    indices = tf.where(mask)
-
-    updateShape = tf.concat([tf.shape(indices)[:-1], innerShape], 0)
-
-    update = tf.broadcast_to(update, updateShape)
-    result = tf.tensor_scatter_nd_update(tensor, indices, update)
-    return tf.reshape(result, shape_tensor)
-   */
-
   /**
-   * TODO
+   * Updates a tensor at the masked values, and returns the updated tensor.  Does not mutate the input tensors.  {@code
+   * updates} will be broadcasted by default
+   * <p>
+   * Numpy equivalent is `tensor[mask] = updates`.
+   * <p>
+   * In general, {@code 0 < dim(mask) = K <= dim(tensor)}, and {@code mask}'s shape must match the first K dimensions of
+   * {@code tensor}'s shape.  We then have: {@code booleanMask(tensor, mask)[i, j1,...,jd] =
+   * tensor[i1,...,iK,j1,...,jd]} where {@code (i1,...,iK)} is the ith {@code true} entry of {@code mask} (row-major
+   * order).
+   * <p>
+   * The {@code axis} could be used with {@code mask} to indicate the axis to mask from (it's 0 by default). In that
+   * case, {@code axis + dim(mask) <= dim(tensor)} and {@code mask}'s shape must match the first {@code axis +
+   * dim(mask)} dimensions of {@code tensor}'s shape.
+   * <p>
+   * The shape of {@code updates} should be {@code [n, t_1, t_2, ...]} where {@code n} is the number of true values in
+   * {@code mask} and {@code t_i} is the {@code i}th dimension of {@code tensor} after {@code axis} and {@code mask}.
+   * {@code updates} will be broadcasted to this shape by default, which can be disabled using {@code options}.
    *
    * @param tensor The tensor to mask.
    * @param mask The mask to apply.
@@ -147,8 +120,9 @@ public static <T extends TType> Operand<T> create(Scope scope, Operand<T> tensor
 
     Operand<TInt64> indices = Where.create(scope, mask);
 
-    if(broadcast) {
+    if (broadcast) {
       Operand<TInt32> indicesShape = org.tensorflow.op.core.Shape.create(scope, indices);
+      // this is the number of true values
       Operand<TInt32> batchShape = StridedSliceHelper.stridedSlice(scope, indicesShape, Indices.sliceTo(-1));
 
       Operand<TInt32> updateShape = Concat.create(
@@ -180,7 +154,7 @@ public static Options axis(Integer axis) {
   /**
    * Whether to try broadcasting update.  True by default.
    */
-  public static Options broadcast(Boolean broadcast){
+  public static Options broadcast(Boolean broadcast) {
     return new Options().broadcast(broadcast);
   }