Scope (TensorFlow Core API Library 0.4.2 API)

All Known Implementing Classes:: GradientScope, OpScope

public interface 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.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`OperationBuilder`	`apply(OperationBuilder builder)` Applies device specification and 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.
`boolean`	`isInit()` Get whether this scope is building init ops.
`static boolean`	`isValidOpName(String name)` Check whether `name` is a valid name for an operation.
`String`	`makeOpName(String defaultName)` Create a unique name for an operator and reserves it, using a provided default if necessary.
`String`	`makeUnique(String id)` Makes a unique name from `id` and reserves it.
`void`	`onOpCreated(Operation op)` Handle op creation, like registering it as an init op if the scope is init.
`default OperationBuilder`	`opBuilder(String type, String name)` Returns a builder to create a new `Operation`.
`void`	`refreshNames()` Refresh the used name list (used for uniquifying names) from the underlying graph.
`default Scope`	`withControlDependencies(Iterable<Op> controls)` Returns a new scope where added operations will have the provided control dependencies.
`Scope`	`withControlDependencyOps(Iterable<Operation> controls)` Returns a new scope where added operations will have the provided control dependencies.
`Scope`	`withDevice(DeviceSpec newDevice)` Return a new scope that uses the provided device specification for an op.
`Scope`	`withInitScope()` Get an extension of this scope that generates initialization ops.
`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.

- Method Detail
  - env
```
ExecutionEnvironment env()
```
    Returns the execution environment used by this scope.
  - withSubScope
```
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
```
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
  - withNameAsSubScope
```
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
  - withDevice
```
Scope withDevice(DeviceSpec newDevice)
```
    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:
    
    newDevice - device specification for an operator in the returned scope
    
    Returns:
    
    a new Scope that uses opName for operations.
  - withInitScope
```
Scope withInitScope()
```
    Get an extension of this scope that generates initialization ops.
  - makeOpName
```
String makeOpName(String defaultName)
```
    Create a unique name for an operator and reserves it, 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.
  - makeUnique
```
String makeUnique(String id)
```
    Makes a unique name from id and reserves it.
  - refreshNames
```
void refreshNames()
```
    Refresh the used name list (used for uniquifying names) from the underlying graph.
    Should be used if you made changes to the graph from non-Scope APIs.
  - withControlDependencies
```
default 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.
    Init ops will be ignored when used as control dependencies, they are assumed to be executed during session initialization.
    
    Parameters:
    
    controls - control dependencies for ops created with the returned scope
    
    Returns:
    
    a new scope with the provided control dependencies
  - withControlDependencyOps
```
Scope withControlDependencyOps(Iterable<Operation> 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.
    Init ops will be ignored when used as control dependencies, they are assumed to be executed during session initialization.
    
    Parameters:
    
    controls - control dependencies for ops created with the returned scope
    
    Returns:
    
    a new scope with the provided control dependencies
  - opBuilder
```
default OperationBuilder opBuilder(String type,
                                   String name)
```
    Returns a builder to create a new Operation.
    Note that name is automatically made unique.
    
    Parameters:
    
    type - of the Operation (i.e., identifies the computation to be performed)
    
    name - to refer to the created Operation in this environment scope. Is uniquified.
    
    Returns:
    
    an OperationBuilder to create an Operation when OperationBuilder.build() is invoked. If OperationBuilder.build() is not invoked, then some resources may leak.
  - isValidOpName
```
static boolean isValidOpName(String name)
```
    Check whether name is a valid name for an operation.
  - apply
```
OperationBuilder apply(OperationBuilder builder)
```
    Applies device specification and adds each Operand in controlDependencies as a control input to the provided builder.
    Should only be used from OperationBuilder implementations
    
    Parameters:
    
    builder - OperationBuilder to add control inputs and device specification to
  - onOpCreated
```
void onOpCreated(Operation op)
```
    Handle op creation, like registering it as an init op if the scope is init.
    FOR INTERNAL USE ONLY
  - getDeviceString
```
String getDeviceString()
```
    Returns device string from the scope.
  - isInit
```
boolean isInit()
```
    Get whether this scope is building init ops.

Interface Scope

Method Summary

Method Detail

env

withSubScope

withName

withNameAsSubScope

withDevice

withInitScope

makeOpName

makeUnique

refreshNames

withControlDependencies

withControlDependencyOps

opBuilder

isValidOpName

apply

onOpCreated

getDeviceString

isInit