Scope

public final class Scope

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

Scope(ExecutionEnvironment env)

Create a new top-level scope.

Public Methods

OperationBuilder	apply(OperationBuilder builder) Applies device specification and adds each Operand in controlDependencies as a control input to the provided builder.
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	getDeviceString() Returns device string from the scope.
String	makeOpName(String defaultName) Create a unique name for an operator, using a provided default if necessary.
Scope	withControlDependencies(Iterable<Op> controls) Returns a new scope where added operations will have the provided control dependencies.
Scope	withDevice(DeviceSpec deviceSpec) Return a new scope that uses the provided device specification for an op.
Scope	withName(String opName) Return a new scope that uses the provided name for an op.
Scope	withNameAsSubScope(String defaultName) Returns a new scope where added operations will be prefixed by this scope's op name (set by `withName(String)`), or the given default if it is unset.
Scope	withSubScope(String childScopeName) Returns a new scope where added operations will have the provided name prefix.

Inherited Methods

From class java.lang.Object

boolean	equals(Object arg0)
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

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 apply (OperationBuilder builder)

Applies device specification and adds each Operand in controlDependencies as a control input to the provided builder.

Parameters

builder	OperationBuilder to add control inputs and device specification to

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 ExecutionEnvironment env ()

Returns the execution environment used by this scope.

public String getDeviceString ()

Returns device string from the scope.

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<Op> 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 withDevice (DeviceSpec deviceSpec)

Return a new scope that uses the provided device specification for an op.

Operations created within this scope will place the created operations on the device(s) matching the provided spec.

Parameters

deviceSpec	device specification for an operator in the returned scope

Returns

a new Scope that uses opName for operations.

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 withNameAsSubScope (String defaultName)

Returns a new scope where added operations will be prefixed by this scope's op name (set by withName(String)), or the given default if it is unset. This is intended to be used for composite ops.

Ops created with this scope will have name/opName/ as the prefix. The actual name will be unique in the returned scope. All other properties are inherited from the current scope.

The default child scope name must match the regular expression [A-Za-z0-9.][A-Za-z0-9_.\-]*

Parameters

defaultName	name of the sub scope if this scope's name hasn't been set.

Returns

a new subscope

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