1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
/* Copyright 2017 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 org.tensorflow.Graph;
/**
* Manages groups of related properties when creating Tensorflow Operations, such as a common name
* prefix.
*
* <p>A {@code Scope} is a container for common properties applied to TensorFlow Ops. Normal user
* code initializes a {@code Scope} and provides it to Operation building classes. For example:
*
* <pre>{@code
* Scope scope = new Scope(graph);
* Constant c = Constant.create(scope, 42);
* }</pre>
*
* <p>An Operation building class acquires a Scope, and uses it to set properties on the underlying
* Tensorflow ops. For example:
*
* <pre>{@code
* // An operator class that adds a constant.
* public class Constant {
* public static Constant create(Scope scope, ...) {
* scope.graph().opBuilder(
* "Const", scope.makeOpName("Const"))
* .setAttr(...)
* .build()
* ...
* }
* }
* }</pre>
*
* <p><b>Scope hierarchy:</b>
*
* <p>A {@code Scope} provides various {@code with()} methods that create a new scope. The new scope
* typically has one property changed while other properties are inherited from the parent scope.
*
* <p>An example using {@code Constant} implemented as before:
*
* <pre>{@code
* Scope root = new Scope(graph);
*
* // The linear subscope will generate names like linear/...
* Scope linear = Scope.withSubScope("linear");
*
* // This op name will be "linear/W"
* Constant.create(linear.withName("W"), ...);
*
* // This op will be "linear/Const", using the default
* // name provided by Constant
* Constant.create(linear, ...);
*
* // This op will be "linear/Const_1", using the default
* // name provided by Constant and making it unique within
* // this scope
* Constant.create(linear, ...);
* }</pre>
*
* <p>Scope objects are <b>not</b> thread-safe.
*/
public final class Scope {
/**
* Create a new top-level scope.
*
* @param graph The graph instance to be managed by the scope.
*/
public Scope(Graph graph) {
this(graph, new NameScope());
}
/** Returns the graph managed by this scope. */
public Graph graph() {
return graph;
}
/**
* Returns a new scope where added operations will have the provided name prefix.
*
* <p>Ops created with this scope will have {@code name/childScopeName/} as the prefix. The actual
* name will be unique in the returned scope. All other properties are inherited from the current
* scope.
*
* <p>The child scope name must match the regular expression {@code [A-Za-z0-9.][A-Za-z0-9_.\-]*}
*
* @param childScopeName name for the new child scope
* @return a new subscope
* @throws IllegalArgumentException if the name is invalid
*/
public Scope withSubScope(String childScopeName) {
return new Scope(graph, nameScope.withSubScope(childScopeName));
}
/**
* Return a new scope that uses the provided name for an op.
*
* <p>Operations created within this scope will have a name of the form {@code
* name/opName[_suffix]}. This lets you name a specific operator more meaningfully.
*
* <p>Names must match the regular expression {@code [A-Za-z0-9.][A-Za-z0-9_.\-]*}
*
* @param opName name for an operator in the returned scope
* @return a new Scope that uses opName for operations.
* @throws IllegalArgumentException if the name is invalid
*/
public Scope withName(String opName) {
return new Scope(graph, nameScope.withName(opName));
}
/**
* Create a unique name for an operator, using a provided default if necessary.
*
* <p>This is normally called only by operator building classes.
*
* <p>This method generates a unique name, appropriate for the name scope controlled by this
* instance. Typical operator building code might look like
*
* <pre>{@code
* scope.graph().opBuilder("Const", scope.makeOpName("Const"))...
* }</pre>
*
* <p><b>Note:</b> if you provide a composite operator building class (i.e, a class that adds a
* set of related operations to the graph by calling other operator building code) you should also
* create a {@link #withSubScope(String)} scope for the underlying operators to group them under a
* meaningful name.
*
* <pre>{@code
* public static Stddev create(Scope scope, ...) {
* // group sub-operations under a common name
* Scope group = scope.withSubScope("stddev");
* ... Sqrt.create(group, Mean.create(group, ...))
* }
* }</pre>
*
* @param defaultName name for the underlying operator.
* @return unique name for the operator.
* @throws IllegalArgumentException if the default name is invalid.
*/
public String makeOpName(String defaultName) {
return nameScope.makeOpName(defaultName);
}
/**
* The name prefix of this scope.
* <p>
* This value is the combination of the name of this scope and all of its parents, seperated by a '/', e.g.
* <pre>{@code
* Scope scope = new Scope(graph);
* assertEquals(scope.withSubScope("sub1").withSubScope("sub2").prefix(), "sub1/sub2");
* }</pre>
*/
public String prefix() {
return nameScope.opPrefix();
}
private Scope(Graph graph, NameScope nameScope) {
this.graph = graph;
this.nameScope = nameScope;
}
private final Graph graph;
private final NameScope nameScope;
}
|
