Kotlin API

CONTRIBUTING.md

@@ -170,10 +170,11 @@ For dependencies, we can use anything compliant with [this list](https://opensou
 
 ### Code generation
 
-Code generation for `Ops` and related classes is done during `tensorflow-core-api`'s `compile` phase, using the annotation processor in
-`tensorflow-core-generator`. If you change or add any operator classes (annotated with `org.tensorflow.op.annotation.Operator`), endpoint methods (
-annotated with `org.tensorflow.op.annotation.Endpoint`), or change the annotation processor, be sure to re-run a
-`mvn install` in `tensorflow-core-api` (`-Pdev` is fine for this, it just needs to run the annotation processor).
+Code generation for `Ops` and related classes is done during `tensorflow-core-api` and `tensorflow-core-kotlin`'s `compile` phase, 
+using the annotation processors in `tensorflow-core-generator` and `tensorflow-kotlin-generator`, respectively. If you change or add any 
+operator classes (annotated with `org.tensorflow.op.annotation.Operator`), endpoint methods (annotated with `org.tensorflow.op.annotation.Endpoint`), 
+or change the annotation processor, be sure to re-run a `mvn compile` in `tensorflow-core-api` **and** `tensorflow-core-kotlin` 
+(`-Pdev` is fine for this, it just needs to run the annotation processor).
 
 ### Working with Bazel generation
 
@@ -189,6 +190,19 @@ bazel-out/k8-opt/bin/external/org_tensorflow/tensorflow/libtensorflow_cc.so --ou
 
 (called in `tensorflow-core-api`).
 
+### Kotlin API
+
+The Kotlin api should be kept to a thin wrapper of the Java API, using extension functions and codegen wherever possible.
+We do not want to get into a situation where we are maintaining two separate but related APIs.
+
+The codegen (`tensorflow-core-kotlin-generator`) is an annotation processor that reads the `@Operator` classes from the `tensorflow-core-api` Java sources.
+If you add operators or re-generate them from the native library, be sure to re-run a `mvn install` in `tensorflow-core-kotlin-api`.
+
+#### Formatting
+
+[ktfmt](https://github.com/facebookincubator/ktfmt) is used to format the Kotlin files.  This is
+checked and done via maven in the same way as Java formatting.  To do the formatting via IntelliJ see
+ktfmt's repo.
 
 ## Adding Gradients
 

README.md

@@ -21,8 +21,13 @@ The following describes the layout of the repository and its different artifacts
 * `tensorflow-core`
   * All artifacts that build up the core language bindings of TensorFlow for Java
   * Intended audience: projects that provide their own APIs or frameworks on top of 
-    TensorFlow and just want a thin layer to access the TensorFlow runtime from the JVM 
+    TensorFlow and just want a thin layer to access the TensorFlow runtime from the JVM
 
+* `tensorflow-core-kotlin`
+  * Kotlin API bindings for `tensorflow-core`.  These are thin wrappers around the core APIs
+    to make them more idiomatic for use in Kotlin, such as using parameters with default values
+    operation builders instead of an `Options` vararg.
+
 * `tensorflow-framework`
   * Primary API for building and training neural networks with TensorFlow
   * Intended audience: neural network developers
@@ -112,6 +117,12 @@ the platforms you are targeting. For this purpose the `-platform` artifacts incl
 the conventions established on this page:
 * [Reducing the Number of Dependencies](https://github.com/bytedeco/javacpp-presets/wiki/Reducing-the-Number-of-Dependencies)
 
+### Kotlin API
+
+Since the Kotlin API is just a wrapper of the Java API, it uses the Java platform artifacts instead of providing its own.
+To use, follow the instructions above for the Java API, but add `tensorflow-core-kotlin-api`, 
+replacing `tensorflow-core-api` if you have explicitly included it.
+
 ### Snapshots
 
 Snapshots of TensorFlow Java artifacts are automatically distributed after each update in the code. To use them, you need

pom.xml

@@ -32,6 +32,7 @@
 
   <modules>
     <module>tensorflow-core</module>
+    <module>tensorflow-kotlin-parent</module>
     <module>tensorflow-framework</module>
   </modules>
 

tensorflow-core/tensorflow-core-api/pom.xml

@@ -20,7 +20,7 @@
     <javacpp.parser.skip>${native.build.skip}</javacpp.parser.skip>
     <javacpp.compiler.skip>${native.build.skip}</javacpp.compiler.skip>
     <java.module.name>org.tensorflow.core.api</java.module.name>
-    <ndarray.version>0.3.3</ndarray.version>
+    <ndarray.version>0.4.0-SNAPSHOT</ndarray.version>
     <truth.version>1.0.1</truth.version>
   </properties>
 

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

@@ -340,7 +340,7 @@
  * }
  * }</pre>
  */
-public final class Ops {
+public final class Ops implements WithOps {
   public final NnOps nn;
 
   public final SummaryOps summary;
@@ -371,10 +371,10 @@ public final class Ops {
 
   public final TpuOps tpu;
 
-  public final AudioOps audio;
-
   public final MathOps math;
 
+  public final AudioOps audio;
+
   public final SignalOps signal;
 
   public final TrainOps train;
@@ -400,8 +400,8 @@ public final class Ops {
     sparse = new SparseOps(this);
     bitwise = new BitwiseOps(this);
     tpu = new TpuOps(this);
-    audio = new AudioOps(this);
     math = new MathOps(this);
+    audio = new AudioOps(this);
     signal = new SignalOps(this);
     train = new TrainOps(this);
     quantization = new QuantizationOps(this);
@@ -8068,11 +8068,15 @@ public <T extends TType> ZerosLike<T> zerosLike(Operand<T> x) {
     return ZerosLike.create(scope, x);
   }
 
+  @Override
+  public Ops tf() {
+    return this;
+  }
+
   /**
-   * Returns an API that builds operations with the provided name prefix.
-   *
-   * @see {@link Scope#withSubScope(String)}
+   * {@inheritDoc}
    */
+  @Override
   public Ops withSubScope(String childScopeName) {
     return new Ops(scope.withSubScope(childScopeName));
   }
@@ -8109,28 +8113,25 @@ public <T extends Operand> T liftToInitScope(T op) {
   }
 
   /**
-   * Returns an API that uses the provided name for an op.
-   *
-   * @see {@link Scope#withName(String)}
+   * {@inheritDoc}
    */
+  @Override
   public Ops withName(String opName) {
     return new Ops(scope.withName(opName));
   }
 
   /**
-   * Returns an API that places the created operations on the device(s) matching the provided spec.
-   *
-   * @see {@link Scope#withDevice(DeviceSpec)}
+   * {@inheritDoc}
    */
+  @Override
   public Ops withDevice(DeviceSpec deviceSpec) {
     return new Ops(scope.withDevice(deviceSpec));
   }
 
   /**
-   * Returns an API that adds operations to the graph with the provided control dependencies.
-   *
-   * @see {@link Scope#withControlDependencies(Iterable<Op<?>>)}
+   * {@inheritDoc}
    */
+  @Override
   public Ops withControlDependencies(Iterable<Op> controls) {
     return new Ops(scope.withControlDependencies(controls));
   }

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/ExecutionEnvironment.java

@@ -16,10 +16,12 @@
 package org.tensorflow;
 
 import org.tensorflow.op.Op;
+import org.tensorflow.op.Ops;
 import org.tensorflow.op.Scope;
+import org.tensorflow.op.WithOps;
 
 /** Defines an environment for creating and executing TensorFlow {@link Operation}s. */
-public interface ExecutionEnvironment {
+public interface ExecutionEnvironment extends WithOps {
 
   enum Types {
     GRAPH,
@@ -126,4 +128,9 @@ default ExecutionEnvironment initEnv() {
    * <p><b>Should generally only be used internally.</b>
    */
   boolean isInitOp(Operation op);
+
+  @Override
+  default Ops tf() {
+    return Ops.create(this);
+  }
 }

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/Signature.java

@@ -1,18 +1,18 @@
 /* Copyright 2020-2021 The TensorFlow Authors. All Rights Reserved.
 
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
- =======================================================================
- */
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+=======================================================================
+*/
 package org.tensorflow;
 
 import java.util.Collections;
@@ -161,7 +161,7 @@ private static TensorInfo toTensorInfo(Output<?> operand) {
       Shape shape = operand.shape();
       TensorShapeProto.Builder tensorShapeBuilder = TensorShapeProto.newBuilder();
       for (int i = 0; i < shape.numDimensions(); ++i) {
-        tensorShapeBuilder.addDim(Dim.newBuilder().setSize(shape.size(i)));
+        tensorShapeBuilder.addDim(Dim.newBuilder().setSize(shape.get(i)));
       }
       return TensorInfo.newBuilder()
           .setDtype(operand.dataType())

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

@@ -0,0 +1,73 @@
+/*
+ Copyright 2021 The TensorFlow Authors. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+=======================================================================
+
+*/
+package org.tensorflow.op;
+
+import java.util.Arrays;
+import org.tensorflow.DeviceSpec;
+
+/** A context that provides a TensorFlow op builder. */
+public interface WithOps {
+
+  /** Get the op builder for this context. */
+  Ops tf();
+
+  /**
+   * Returns an API that builds operations with the provided name prefix.
+   *
+   * @see Scope#withSubScope(String)
+   */
+  default WithOps withSubScope(String childScopeName) {
+    return tf().withSubScope(childScopeName);
+  }
+
+  /**
+   * Returns an API that uses the provided name for an op.
+   *
+   * @see Scope#withName(String)
+   */
+  default WithOps withName(String opName) {
+    return tf().withName(opName);
+  }
+
+  /**
+   * Returns an API that places the created operations on the device(s) matching the provided spec.
+   *
+   * @see Scope#withDevice(DeviceSpec)
+   */
+  default WithOps withDevice(DeviceSpec deviceSpec) {
+    return tf().withDevice(deviceSpec);
+  }
+
+  /**
+   * Returns an API that adds operations to the graph with the provided control dependencies.
+   *
+   * @see Scope#withControlDependencies(Iterable)
+   */
+  default WithOps withControlDependencies(Iterable<Op> controls) {
+    return tf().withControlDependencies(controls);
+  }
+
+  /**
+   * Returns an API that adds operations to the graph with the provided control dependencies.
+   *
+   * @see Scope#withControlDependencies(Iterable)
+   */
+  default WithOps withControlDependencies(Op... controls) {
+    return withControlDependencies(Arrays.asList(controls));
+  }
+}

tensorflow-core/tensorflow-core-api/src/test/java/org/tensorflow/EagerOperationTest.java

@@ -55,8 +55,8 @@ public void outputDataTypeAndShape() {
               .setAttr("value", t)
               .build();
       assertEquals(DataType.DT_INT32, op.dtype(0));
-      assertEquals(2, op.shape(0).size(0));
-      assertEquals(3, op.shape(0).size(1));
+      assertEquals(2, op.shape(0).get(0));
+      assertEquals(3, op.shape(0).get(1));
     }
   }
 

tensorflow-core/tensorflow-core-api/src/test/java/org/tensorflow/GraphOperationBuilderTest.java

@@ -144,8 +144,8 @@ public void setAttrShape() {
               .build()
               .output(0);
       assertEquals(2, n.shape().numDimensions());
-      assertEquals(-1, n.shape().size(0));
-      assertEquals(784, n.shape().size(1));
+      assertEquals(-1, n.shape().get(0));
+      assertEquals(784, n.shape().get(1));
       assertEquals(DataType.DT_FLOAT, n.dataType());
     }
   }

tensorflow-core/tensorflow-core-api/src/test/java/org/tensorflow/SavedModelBundleTest.java

@@ -200,7 +200,7 @@ public void exportFunctionWithVariables() throws IOException {
       assertNotNull(inputInfo);
       assertEquals(xyShape.numDimensions(), inputInfo.getTensorShape().getDimCount());
       for (int i = 0; i < xyShape.numDimensions(); ++i) {
-        assertEquals(xyShape.size(i), inputInfo.getTensorShape().getDim(i).getSize());
+        assertEquals(xyShape.get(i), inputInfo.getTensorShape().getDim(i).getSize());
       }
 
       TensorInfo outputInfo = signatureDef.getOutputsMap().get("reducedSum");