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(Graph graph) Create a new top-level scope.

Method Summary

Modifier and Type	Method and Description
Graph	graph() Returns the graph managed by this scope.
String	makeOpName(String defaultName) Create a unique name for an operator, using a provided default if necessary.
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(Graph graph)

Create a new top-level scope.

Parameters:

graph - The graph instance to be managed by the scope.

Method Detail

graph

public Graph graph()

Returns the graph managed 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.graph().opBuilder("Const", scope.makeOpName("Const"))...
 

Note: 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 withSubScope(String) scope for the underlying operators to group them under a meaningful name.

 public static Stddev create(Scope scope, ...) {
   // group sub-operations under a common name
   Scope group = scope.withSubScope("stddev");
   ... Sqrt.create(group, Mean.create(group, ...))
 }
 

Parameters:

defaultName - name for the underlying operator.

Returns:

unique name for the operator.

Throws:

IllegalArgumentException - if the default name is invalid.