Manages groups of related properties when creating Tensorflow Operations, such as a common name prefix.
A Scope
is a container for common properties applied to TensorFlow Ops. Normal user
code initializes a Scope
and provides it to Operation building classes. For example:
Scope scope = new Scope(graph);
Constant c = Constant.create(scope, 42);
An Operation building class acquires a Scope, and uses it to set properties on the underlying Tensorflow ops. For example:
// 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()
...
}
}
Scope hierarchy:
A Scope
provides various with()
methods that create a new scope. The new scope
typically has one property changed while other properties are inherited from the parent scope.
An example using Constant
implemented as before:
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, ...);
Scope objects are not thread-safe.
Public Constructors
Public Methods
OperationBuilder |
applyControlDependencies(OperationBuilder builder)
Adds each Operand in controlDependencies as a control input to the provided builder.
|
ExecutionEnvironment |
env()
Returns the execution environment used by this scope.
|
String |
makeOpName(String defaultName)
Create a unique name for an operator, using a provided default if necessary.
|
Scope |
withControlDependencies(Iterable<Operand<?>> controls)
Returns a new scope where added operations will have the provided control dependencies.
|
Scope |
withName(String opName)
Return a new scope that uses the provided name for an op.
|
Scope |
withSubScope(String childScopeName)
Returns a new scope where added operations will have the provided name prefix.
|
Inherited Methods
Public Constructors
public Scope (ExecutionEnvironment env)
Create a new top-level scope.
Parameters
env | The execution environment used by the scope. |
---|
Public Methods
public OperationBuilder applyControlDependencies (OperationBuilder builder)
Adds each Operand in controlDependencies as a control input to the provided builder.
Parameters
builder | OperationBuilder to add control inputs to |
---|
public String makeOpName (String defaultName)
Create a unique name for an operator, using a provided default if necessary.
This is normally called only by operator building classes.
This method generates a unique name, appropriate for the name scope controlled by this instance. Typical operator building code might look like
scope.env().opBuilder("Const", scope.makeOpName("Const"))...
Note: if you provide a composite operator building class (i.e, a class that creates a set of related operations by calling other operator building code), the provided name will act as a subscope to all underlying operators.
Parameters
defaultName | name for the underlying operator. |
---|
Returns
- unique name for the operator.
Throws
IllegalArgumentException | if the default name is invalid. |
---|
public Scope withControlDependencies (Iterable<Operand<?>> controls)
Returns a new scope where added operations will have the provided control dependencies.
Ops created with this scope will have a control edge from each of the provided controls. All other properties are inherited from the current scope.
Parameters
controls | control dependencies for ops created with the returned scope |
---|
Returns
- a new scope with the provided control dependencies
public Scope withName (String opName)
Return a new scope that uses the provided name for an op.
Operations created within this scope will have a name of the form name/opName[_suffix]
. This lets you name a specific operator more meaningfully.
Names must match the regular expression [A-Za-z0-9.][A-Za-z0-9_.\-]*
Parameters
opName | name for an operator in the returned scope |
---|
Returns
- a new Scope that uses opName for operations.
Throws
IllegalArgumentException | if the name is invalid |
---|
public Scope withSubScope (String childScopeName)
Returns a new scope where added operations will have the provided name prefix.
Ops created with this scope will have name/childScopeName/
as the prefix. The actual
name will be unique in the returned scope. All other properties are inherited from the current
scope.
The child scope name must match the regular expression [A-Za-z0-9.][A-Za-z0-9_.\-]*
Parameters
childScopeName | name for the new child scope |
---|
Returns
- a new subscope
Throws
IllegalArgumentException | if the name is invalid |
---|