Javadocs cleanup, new names

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

Author: rnett

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

@@ -64,11 +64,6 @@ public long end() {
     return coord + 1;
   }
 
-  @Override
-  public boolean shrinkAxisMask() {
-    return !keepDim;
-  }
-
   @Override
   public String toString() {
     return new StringJoiner(", ", At.class.getSimpleName() + "(", ")")

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

@@ -41,11 +41,6 @@ public boolean isEllipsis() {
     return true;
   }
 
-  @Override
-  public boolean ellipsisMask() {
-    return true;
-  }
-
   @Override
   public String toString() {
     return Ellipsis.class.getSimpleName() + "()";

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

@@ -197,7 +197,7 @@ public static Index step(long stepLength) {
    * @param start coordinate of the first element of the sequence
    * @return index
    */
-  public static Index from(long start) {
+  public static Index sliceFrom(long start) {
     return slice(start, null);
   }
 
@@ -211,10 +211,42 @@ public static Index from(long start) {
    * @param end coordinate of the last element of the sequence (exclusive)
    * @return index
    */
-  public static Index to(long end) {
+  public static Index sliceTo(long end) {
     return slice(null, end);
   }
 
+  /**
+   * An index that returns only elements on a given dimension starting at a
+   * specific coordinate, using the given stride.
+   *
+   * <p>For example, given a vector with {@code n} elements on the {@code x} axis, and {@code n > k},
+   * {@code from(k)} returns x<sub>k</sub>, x<sub>k+1</sub>, ..., x<sub>n-1</sub>
+   *
+   * @param start coordinate of the first element of the sequence
+   * @param stride the stride to use
+   * @return index
+   * @see #slice(long, long, long)
+   */
+  public static Index sliceFrom(long start, long stride) {
+    return slice(start, null, stride);
+  }
+
+  /**
+   * An index that returns only elements on a given dimension up to a
+   * specific coordinate, using the given stride.
+   *
+   * <p>For example, given a vector with {@code n} elements on the {@code x} axis, and {@code n > k},
+   * {@code to(k)} returns x<sub>0</sub>, x<sub>1</sub>, ..., x<sub>k</sub>
+   *
+   * @param end coordinate of the last element of the sequence (exclusive)
+   * @param stride the stride to use
+   * @return index
+   * @see #slice(long, long, long)
+   */
+  public static Index sliceTo(long end, long stride) {
+    return slice(null, end, stride);
+  }
+
   /**
    * An index that returns only elements on a given dimension between two coordinates.
    *

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

@@ -46,11 +46,6 @@ public boolean isNewAxis() {
     return true;
   }
 
-  @Override
-  public boolean newAxisMask() {
-    return true;
-  }
-
   @Override
   public String toString() {
     return NewAxis.class.getSimpleName() + "()";

ndarray/src/test/java/org/tensorflow/ndarray/NdArrayTestBase.java

@@ -24,11 +24,11 @@
 import static org.tensorflow.ndarray.index.Indices.at;
 import static org.tensorflow.ndarray.index.Indices.even;
 import static org.tensorflow.ndarray.index.Indices.flip;
-import static org.tensorflow.ndarray.index.Indices.from;
+import static org.tensorflow.ndarray.index.Indices.sliceFrom;
 import static org.tensorflow.ndarray.index.Indices.odd;
 import static org.tensorflow.ndarray.index.Indices.range;
 import static org.tensorflow.ndarray.index.Indices.seq;
-import static org.tensorflow.ndarray.index.Indices.to;
+import static org.tensorflow.ndarray.index.Indices.sliceTo;
 
 import java.nio.BufferOverflowException;
 import java.nio.BufferUnderflowException;
@@ -212,13 +212,13 @@ public void slices() {
     assertEquals(val101, vector10_flip.getObject(3));
 
     // Vector (1,0,[from 1]) from vector (1,0,*)
-    NdArray<T> vector10_1toX = vector10X.slice(from(1));
+    NdArray<T> vector10_1toX = vector10X.slice(sliceFrom(1));
     assertEquals(vector10_1toX.shape(), Shape.of(4));
     assertEquals(val101, vector10_1toX.getObject(0));
     assertEquals(val102, vector10_1toX.getObject(1));
 
     // Vector (1,0,[to 1]) from vector (1,0,*)
-    NdArray<T> vector10_Xto1 = vector10X.slice(to(2));
+    NdArray<T> vector10_Xto1 = vector10X.slice(sliceTo(2));
     assertEquals(vector10_Xto1.shape(), Shape.of(2));
     assertEquals(val100, vector10_Xto1.getObject(0));
     assertEquals(val101, vector10_Xto1.getObject(1));

ndarray/src/test/java/org/tensorflow/ndarray/impl/dense/DenseNdArrayTest.java

@@ -40,7 +40,7 @@ public void equalsAndHashCodeOnSlices() {
         {{3, 4}, {6, 7}}
     });
 
-    assertTrue(vector1.equals(vector2.slice(Indices.from(2))));
+    assertTrue(vector1.equals(vector2.slice(Indices.sliceFrom(2))));
     assertTrue(vector1.equals(matrix1.get(1)));
     assertTrue(vector1.equals(matrix2.get(1).slice(Indices.even())));
     assertTrue(matrix1.equals(matrix2.slice(Indices.all(), Indices.even())));

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

@@ -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);
   }
 
   /**
@@ -5905,51 +5905,46 @@ public <T extends TType> StopGradient<T> stopGradient(Operand<T> 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 Indices#ellipsis()}. 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 Indices#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 Indices#slice(Long, Long, long)}  Index.slice()}. 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 Indices#at(long)}. 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.
+   *  <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 Indices#ellipsis()}. Ellipses are used to imply zero or more dimensions of
+   *  full-dimension selection. For example, {@code stridedSlice(foo, Indices.ellipsis()} is the identity slice.
+   *  <p>
+   *  - A new axis using {@link Indices#newAxis()}. This is used to insert a new shape=1 dimension.
+   *  For example, `{@code stridedSlice(foo, Indices.newAxis())} where {@code foo} is shape {@code (3, 4)} 
+   *  produces a {@code (1, 3, 4)} tensor.
+   *  <p>
+   *  - A range {@code begin:end:stride} using {@link Indices#slice(Long, Long, long)}  Index.slice()} or {@link Indices#all()}. This is used to specify
+   *  how much to choose from a given dimension. {@code stride} can be any integer but 0.  {@code begin} is an integer which
+   *  represents the index of the first value to select while {@code end} represents the index of the last value to select 
+   *  (exclusive). Begin and end can be null, in which case the index begins or ends at the beginning or end of the dimension,
+   *  respectively (reversed if stride is negative).  When both are null, {@code slice()} is the same as {@code all()}.
+   *  The number of values selected in each dimension is {@code end - begin} if {@code stride > 0} and {@code begin - end}
+   *  if {@code stride < 0}. {@code begin} and {@code end} can be negative where {@code -1} is the last element, {@code -2}
+   *  is the second to last. For example, given a shape {@code (3,)} tensor {@code stridedSlice(foo, Indices.all())}, the
+   *  effective {@code begin} and {@code end} are {@code 0} and {@code 3}. Do not assume this is equivalent to
+   *  {@code stridedSlice(foo, Indices.slice(0, -1))} which has an effective {@code begin} and {@code end} of {@code 0} and
+   *  {@code 2}. Another example is {@code stridedSlice(foo, Indices.slice(-2, null, -1))} which reverses the first dimension
+   *  of a tensor while dropping the last two (in the original order elements). For example {@code foo = [1,2,3,4];
+   *  stridedSlice(foo, Indices.slice(-2, null, -1)} is {@code [4,3]}.
+   *  <p>
+   *  - A single index using {@link Indices#at(long)}. This is used to keep only elements that have a given index. For
+   *  example ({@code stridedSlice(foo, Indices.at(2))} on a shape {@code (5,6)} tensor produces a shape {@code (6,)} tensor.
+   *  The dimension can be kept with size one using {@link Indices#at(long, boolean)}.
+   *  <p>
+   *  These semantics generally follow NumPy's indexing semantics, which can be found here:
+   *  <a href="https://numpy.org/doc/stable/reference/arrays.indexing.html">https://numpy.org/doc/stable/reference/arrays.indexing.html</a>
+   *  <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 Indices}.
    * @return a new instance of StridedSlice
    * @see Indices
@@ -6072,13 +6067,12 @@ public <T extends TType, U extends TNumber> StridedSlice<T> stridedSlice(Operand
 
   /**
    * 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`.
+   *  <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

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

@@ -128,26 +128,32 @@ static StridedSliceArgs mergeIndexes(Index[] indices) {
    * entry can be one of the following:
    * <p>
    * - An ellipsis (...) using {@link Indices#ellipsis()}. 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.
+   * full-dimension selection. For example, {@code stridedSlice(foo, Indices.ellipsis()} is the identity slice.
    * <p>
-   * - A new axis using {@link Indices#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.
+   * - A new axis using {@link Indices#newAxis()}. This is used to insert a new shape=1 dimension.
+   * For example, `{@code stridedSlice(foo, Indices.newAxis())} where {@code foo} is shape {@code (3, 4)} 
+   * produces a {@code (1, 3, 4)} tensor.
    * <p>
-   * - A range `begin:end:stride` using {@link Indices#slice(Long, Long, long)}  Index.slice()}. 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]`.
+   * - A range {@code begin:end:stride} using {@link Indices#slice(Long, Long, long)}  Index.slice()} or {@link Indices#all()}. This is used to specify
+   * how much to choose from a given dimension. {@code stride} can be any integer but 0.  {@code begin} is an integer which
+   * represents the index of the first value to select while {@code end} represents the index of the last value to select 
+   * (exclusive). Begin and end can be null, in which case the index begins or ends at the beginning or end of the dimension,
+   * respectively (reversed if stride is negative).  When both are null, {@code slice()} is the same as {@code all()}.
+   * The number of values selected in each dimension is {@code end - begin} if {@code stride > 0} and {@code begin - end}
+   * if {@code stride < 0}. {@code begin} and {@code end} can be negative where {@code -1} is the last element, {@code -2}
+   * is the second to last. For example, given a shape {@code (3,)} tensor {@code stridedSlice(foo, Indices.all())}, the
+   * effective {@code begin} and {@code end} are {@code 0} and {@code 3}. Do not assume this is equivalent to
+   * {@code stridedSlice(foo, Indices.slice(0, -1))} which has an effective {@code begin} and {@code end} of {@code 0} and
+   * {@code 2}. Another example is {@code stridedSlice(foo, Indices.slice(-2, null, -1))} which reverses the first dimension
+   * of a tensor while dropping the last two (in the original order elements). For example {@code foo = [1,2,3,4];
+   * stridedSlice(foo, Indices.slice(-2, null, -1)} is {@code [4,3]}.
    * <p>
    * - A single index using {@link Indices#at(long)}. 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`.
+   * example ({@code stridedSlice(foo, Indices.at(2))} on a shape {@code (5,6)} tensor produces a shape {@code (6,)} tensor.
+   * The dimension can be kept with size one using {@link Indices#at(long, boolean)}.
+   * <p>
+   * These semantics generally follow NumPy's indexing semantics, which can be found here:
+   * <a href="https://numpy.org/doc/stable/reference/arrays.indexing.html">https://numpy.org/doc/stable/reference/arrays.indexing.html</a>
    * <p>
    *
    * <i>Requirements</i>: