Finishing Function for TensorFlow 1.4.0

Author: RockfordWei

GUIDE.md

@@ -504,4 +504,42 @@ let dev = try g.runner().session.devices
 print(dev)
 // sample output:
 // ["/job:localhost/replica:0/task:0/cpu:0": (type: "CPU", memory: 268435456)]
+```
+
+### Functions of a Graph
+
+Since TensorFlow 1.4.0+, a new feature named `Function` has been introduced as a nested class of Graph.
+
+A `Function` object can be either built by `graph.toFunction()` or imported by its definition protocol buffer:
+
+``` swift 
+// build a function from the current graph
+let function = try graph.toFunction("funcName", 
+	operations:[], inputs:[] outputs: [operation.asOutput(0)], 
+	outputNames: [], description: "myFunc")
+
+// get the function definition buffer:
+guard let def = function.definition else {
+	// something wrong
+}
+
+// import a function from its definition buffer
+let function2 = try TF.Graph.Function(importDefinition: def)
+// now function == function2
+```
+
+The purpose of `Function` is to copy its gradient function from one graph to another:
+
+``` swift
+let function = try graph1.toFunction(...)
+try graph.copy(function: function)
+```
+
+You can also get and set a function object's attribute:
+
+``` swift
+// assuming value is a TF.AttrValue protocol buffer
+try function.setAttributeFor("foo_attr", value: value)
+let value2 = try function.getAttributeFor("foo_attr")
+// now value2 should be the same as value
 ```

GUIDE.zh_CN.md

@@ -498,4 +498,42 @@ let dev = try g.runner().session.devices
 print(dev)
 // 样本输出：
 // ["/job:localhost/replica:0/task:0/cpu:0": (type: "CPU", memory: 268435456)]
+```
+
+### 运算流程图中的函数
+
+自 TensorFlow 1.4.0 版本开始，本函数库新增了一个内置对象类 `Function` 用于表达流程图中的运算函数。
+
+一个函数对象可以通过运算流程图`graph.toFunction()`方法创建，或者从其定义缓冲字节中导入：
+
+``` swift 
+// 从当前流程图中创建一个函数
+let function = try graph.toFunction("函数名", 
+	operations:[], inputs:[] outputs: [operation.asOutput(0)], 
+	outputNames: [], description: "我的函数")
+
+// 获取函数的协议缓冲字节
+guard let def = function.definition else {
+	// something wrong
+}
+
+// 或者从已经保存的协议缓冲字节中导入一个函数
+let function2 = try TF.Graph.Function(importDefinition: def)
+// now function == function2
+```
+
+运算流程图中函数对象的设置是为了方便地把一组运算（的梯度函数）从一个流程图复制到另外一个流程图上去：
+
+``` swift
+let function = try graph1.toFunction(...)
+try graph.copy(function: function)
+```
+
+同时还可以随时读取或者设置函数对象的属性：
+
+``` swift
+// 假设value是一个 TF.AttrValue 协议缓冲字节
+try function.setAttributeFor("某属性", value: value)
+let value2 = try function.getAttributeFor("某属性")
+// 现在 value 和 value2 应该是完全一致的
 ```

README.md

@@ -56,8 +56,8 @@ These files are the key part of Perfect-TensorFlow:
 ```
 Sources
 ├── PerfectTensorFlow
-│   ├── APILoader.swift (928 lines, translated from tensorflow/c/c_api.h)
-│   ├── PerfectTensorFlow.swift (2436 lines)
+│   ├── APILoader.swift (1099 lines, translated from tensorflow/c/c_api.h)
+│   ├── PerfectTensorFlow.swift (2701 lines)
 └── TensorFlowAPI
     ├── TensorFlowAPI.c (72 lines)
     └── include

README.zh_CN.md

@@ -56,8 +56,8 @@
 ```
 Sources
 ├── PerfectTensorFlow
-│   ├── APILoader.swift (928 行代码，直接从tensorflow/c/c_api.h翻译而来)
-│   ├── PerfectTensorFlow.swift (2436 行代码)
+│   ├── APILoader.swift (1099 行代码，直接从tensorflow/c/c_api.h翻译而来)
+│   ├── PerfectTensorFlow.swift (2701 行代码)
 └── TensorFlowAPI
     ├── TensorFlowAPI.c (72 行代码)
     └── include

Tests/PerfectTensorFlowTests/PerfectTensorFlowTests.swift

@@ -167,6 +167,7 @@ class PerfectTensorFlowTests: XCTestCase {
     do {
       let funcName = "MyFunc"
       let nodeName = "MyFunc_0"
+      let attrName = "foo_attr"
       let funcGraph = try TF.Graph()
       let hostGraph = try TF.Graph()
       let c = try funcGraph.scalar(10, name: "scalar10")
@@ -194,6 +195,17 @@ class PerfectTensorFlowTests: XCTestCase {
         return
       }
       XCTAssertEqual(ret, "scalar10_0:output:0")
+
+      let function2 = try TF.Graph.Function(importDefinition: def)
+      guard let def2 = function2.definition else {
+        XCTFail("function import / export failure")
+        return
+      }
+      let node2 = def2.nodeDef[0]
+      XCTAssertEqual(node, node2)
+      try function2.setAttributeFor(attrName, value: value)
+      let value2 = try function2.getAttributeFor(attrName)
+      XCTAssertEqual(value, value2)
     }catch {
       XCTFail("functions: \(error)")
     }