# tensorflow::Scope

`#include <scope.h>`

A `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` object represents a set of related TensorFlow ops that have the same properties such as a common name prefix.

## Summary

A [Scope](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope) object is a container for TensorFlow Op properties. Op constructors get a [Scope](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_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()) { ... }
```

<br />

[Scope](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope) hierarchy:

The [Scope](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_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()](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1aa716951887f54604c548553e1302fdb3) 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"
```

<br />

[Scope](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope) lifetime:

A new scope is created by calling [Scope::NewRootScope](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a2bd1e548f919654da8f57402f844326c). 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](https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/status#classtensorflow_1_1_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 `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` object is NOT thread-safe. Threads cannot concurrently call op-constructor functions on the same `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` object.

| ### Constructors and Destructors ||
|---|---|
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a1570deec3468ec4b858094b5b1a2f727(const https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope & other)` ||
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1aa3b7d137ed47ff8d5fcc1cc114a181df()` ||

| ### Public functions ||
|---|---|
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a385a544bd9ed2ef7805edf79e7be684f() const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Clear all colocation constraints. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a6ad18f3a902eb624f93051812e19705a(const https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/operation#classtensorflow_1_1_operation & op) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a0968351b7ff04a358364e7754008fbac(const https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output & out) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Convenience function for above. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1ad3fd7ca2c3691a174d4ec3d7571277f8() const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1aaf707349b4c310fd8eb2198037d590cd(const string & composite_op_name) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/struct/tensorflow/composite-op-scopes#structtensorflow_1_1_composite_op_scopes` |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1adc0862bbd6f5dd7e801e85aef1b3d244(const string & default_name) const ` | `string` Return a unique name, using default_name if an op name has not been specified. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1af9f03ca7ef0fdefd9b49378c19421210(const string & child_scope_name) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a48c527e5fd2d3735cf89474714fe1fb8(GraphDef *gdef) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/status#classtensorflow_1_1_status` If status() is Status::OK(), convert the Graph object stored in this scope to a GraphDef proto and return Status::OK(). |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a3b4f0dbfe674d44c09fe3abb8ad8d743(const https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/status#classtensorflow_1_1_status & s) const ` | `void` Update the status on this scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1ad8e5fff9ad2614f43b59e370525adaec(const string & assigned_device) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Returns a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a1df93e2ab5b0ab40ebba3028ac8b34c7(const gtl::ArraySlice< https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/operation#classtensorflow_1_1_operation > & control_deps) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1ae11bf1782c17453f8ed2f6338b6e3c18(const https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output & control_dep) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Same as above, but convenient to add control dependency on the operation producing the control_dep output. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a89df9fb352b5c7a258cd05aaf4b244f0(const string & device) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a56c8e5b2a135d7149ec21b7c959d2e76(const string & kernel_label) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a36af05b4dc1259caefd99539679e3733() const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1aa716951887f54604c548553e1302fdb3(Ty... fragments) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Return a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a4944da564e7de504b29c534f5f88bfa9(const string & xla_cluster) const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` Returns a new scope. |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a910cb669ff111f1b3b60a2fb1b18d0c7() const ` | `const std::vector< https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/operation#classtensorflow_1_1_operation > &` |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a19ac1f773b43a58ac8bbb02d6b57e6a0() const ` | `Graph *` |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a4e2e9083eaf863ee2269ecc069dc8544() const ` | `std::shared_ptr< Graph >` |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1ab12601e783c660848b2a1d396cddcb03() const ` | `bool` |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a5d0e6525c7a10d5ff62035281656f25a(const https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope & other)` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope &` |
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1ac00d31d253853dacaab991a685fad31c() const ` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/status#classtensorflow_1_1_status` |

| ### Public static functions ||
|---|---|
| `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope_1a2bd1e548f919654da8f57402f844326c()` | `https://www.tensorflow.org/versions/r1.15/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope` 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 Status::OK(), convert the Graph object stored in this scope to a GraphDef proto and return Status::OK().

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 Status::OK() 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.