org.tensorflow.op

Class Scope

java.lang.Object

org.tensorflow.op.Scope

public final class Scope
extends Object

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.

Constructor Summary

Constructors

Constructor and Description
Scope(ExecutionEnvironment env) Create a new top-level scope.

Method Summary

Modifier and Type	Method and Description
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Scope

public Scope(ExecutionEnvironment env)

Create a new top-level scope.

Parameters:

env - The execution environment used by the scope.

Method Detail

env

public ExecutionEnvironment env()

Returns the execution environment used by this scope.

withSubScope

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

withName

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

makeOpName

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.

withControlDependencies

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

applyControlDependencies

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