tensorflow::Scope

#include <scope.h>

A Scope object represents a set of related TensorFlow ops that have the same properties such as a common name prefix.

Summary

A Scope object is a container for TensorFlow Op properties. Op constructors get a Scope object as a mandatory first argument and the constructed op acquires the properties in the object.

A simple example: 

using namespace ops;
Scope root = Scope::NewRootScope();
auto c1 = Const(root, { {1, 1} });
auto m = MatMul(root, c1, { {41}, {1} });
GraphDef gdef;
Status s = root.ToGraphDef(&gdef);
if (!s.ok()) { ... }

Scope hierarchy:

The Scope class provides various With<> functions that create a new scope. The new scope typically has one property changed while other properties are inherited from the parent scope. NewSubScope(name) method appends name to the prefix of names for ops created within the scope, and WithOpName() changes the suffix which otherwise defaults to the type of the op.

Name examples: 

Scope root = Scope::NewRootScope();
Scope linear = root.NewSubScope("linear");
// W will be named "linear/W"
auto W = Variable(linear.WithOpName("W"),
                  {2, 2}, DT_FLOAT);
// b will be named "linear/b_3"
int idx = 3;
auto b = Variable(linear.WithOpName("b_", idx),
                  {2}, DT_FLOAT);
auto x = Const(linear, {...});  // name: "linear/Const"
auto m = MatMul(linear, x, W);  // name: "linear/MatMul"
auto r = BiasAdd(linear, m, b); // name: "linear/BiasAdd"

Scope lifetime:

A new scope is created by calling Scope::NewRootScope. This creates some resources that are shared by all the child scopes that inherit from this scope, directly or transitively. For instance, a new scope creates a new Graph object to which operations are added when the new scope or its children are used by an Op constructor. The new scope also has a Status object which will be used to indicate errors by Op-constructor functions called on any child scope. The Op-constructor functions have to check the scope's status by calling the ok() method before proceeding to construct the op.

Thread safety:

A Scope object is NOT thread-safe. Threads cannot concurrently call op-constructor functions on the same Scope object.

Constructors and Destructors
Scope(const Scope & other)
~Scope()

Public functions
ClearColocation() const
Clear all colocation constraints.
ColocateWith(const Operation & op) const
Return a new scope.
ColocateWith(const Output & out) const
Convenience function for above.
ExitOnError() const
Return a new scope.
GetCompositeOpScopes(const string & composite_op_name) const
GetUniqueNameForOp(const string & default_name) const
string
Return a unique name, using default_name if an op name has not been specified.
NewSubScope(const string & child_scope_name) const
Return a new scope.
ToGraphDef(GraphDef *gdef) const
Status
If status() is ok, convert the Graph object stored in this scope to a GraphDef proto and return an ok Status.
UpdateStatus(const Status & s) const
void
Update the status on this scope.
WithAssignedDevice(const string & assigned_device) const
Returns a new scope.
WithControlDependencies(const gtl::ArraySlice< Operation > & control_deps) const
Return a new scope.
WithControlDependencies(const Output & control_dep) const
Same as above, but convenient to add control dependency on the operation producing the control_dep output.
WithDevice(const string & device) const
Return a new scope.
WithKernelLabel(const string & kernel_label) const
Return a new scope.
WithNoControlDependencies() const
Return a new scope.
WithOpName(Ty... fragments) const
Return a new scope.
WithXlaCluster(const string & xla_cluster) const
Returns a new scope.
control_deps() const
const std::vector< Operation > &
graph() const
Graph *
graph_as_shared_ptr() const
std::shared_ptr< Graph >
ok() const
bool
operator=(const Scope & other)
Scope &
status() const
Status

Public static functions
NewRootScope()
Return a new scope.

Public functions

ClearColocation

Scope ClearColocation() const

Clear all colocation constraints.

ColocateWith

Scope ColocateWith(
  const Operation & op
) const

Return a new scope.

All ops created within the returned scope will be co-located on the device where op is placed. NOTE: This function is intended to be use internal libraries only for controlling placement of ops on to devices. Public use is not encouraged because the implementation of device placement is subject to change.

ColocateWith

Scope ColocateWith(
  const Output & out
) const

Convenience function for above.

ExitOnError

Scope ExitOnError() const

Return a new scope.

The op-constructor functions taking the returned scope as the scope argument will exit as soon as an error is detected, instead of setting the status on the scope.

GetCompositeOpScopes

CompositeOpScopes GetCompositeOpScopes(
  const string & composite_op_name
) const

GetUniqueNameForOp

string GetUniqueNameForOp(
  const string & default_name
) const

Return a unique name, using default_name if an op name has not been specified.

NewSubScope

Scope NewSubScope(
  const string & child_scope_name
) const

Return a new scope.

Ops created with this scope will have name/child_scope_name as the prefix. The actual name will be unique in the current scope. All other properties are inherited from the current scope. If child_scope_name is empty, the / is elided.

Scope

 Scope(
  const Scope & other
)

ToGraphDef

Status ToGraphDef(
  GraphDef *gdef
) const

If status() is ok, convert the Graph object stored in this scope to a GraphDef proto and return an ok Status.

Otherwise, return the error status as is without performing GraphDef conversion.

UpdateStatus

void UpdateStatus(
  const Status & s
) const

Update the status on this scope.

Note: The status object is shared between all children of this scope. If the resulting status is not OkStatus() and exit_on_error_ is set on this scope, this function exits by calling LOG(FATAL).

WithAssignedDevice

Scope WithAssignedDevice(
  const string & assigned_device
) const

Returns a new scope.

All ops created within the returned scope will have their assigned device set to assigned_device.

WithControlDependencies

Scope WithControlDependencies(
  const gtl::ArraySlice< Operation > & control_deps
) const

Return a new scope.

All ops created within the returned scope will have as control dependencies the union of operations in the control_deps vector and the control dependencies of the current scope.

WithControlDependencies

Scope WithControlDependencies(
  const Output & control_dep
) const

Same as above, but convenient to add control dependency on the operation producing the control_dep output.

WithDevice

Scope WithDevice(
  const string & device
) const

Return a new scope.

All ops created within the returned scope will have the device field set to 'device'.

WithKernelLabel

Scope WithKernelLabel(
  const string & kernel_label
) const

Return a new scope.

All ops created with the new scope will have kernel_label as the value for their '_kernel' attribute;

WithNoControlDependencies

Scope WithNoControlDependencies() const

Return a new scope.

All ops created within the returned scope will have no control dependencies on other operations.

WithOpName

Scope WithOpName(
  Ty... fragments
) const

Return a new scope.

All ops created within the returned scope will have names of the form name/StrCat(fragments...)[_suffix]

WithXlaCluster

Scope WithXlaCluster(
  const string & xla_cluster
) const

Returns a new scope.

All ops created within the returned scope will have their _XlaCluster attribute set to xla_cluster.

control_deps

const std::vector< Operation > & control_deps() const

graph

Graph * graph() const

graph_as_shared_ptr

std::shared_ptr< Graph > graph_as_shared_ptr() const

ok

bool ok() const

operator=

Scope & operator=(
  const Scope & other
)

status

Status status() const

~Scope

 ~Scope()

Public static functions

NewRootScope

Scope NewRootScope()

Return a new scope.

This creates a new graph and all operations constructed in this graph should use the returned object as the "root" scope.