# tf.compat.v1.DeviceSpec

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L420-L485) |

Represents a (possibly partial) specification for a TensorFlow device.

Inherits From: [`DeviceSpec`](https://www.tensorflow.org/versions/r2.13/api_docs/python/tf/DeviceSpec)

    tf.compat.v1.DeviceSpec(
        job=None, replica=None, task=None, device_type=None, device_index=None
    )

`DeviceSpec`s are used throughout TensorFlow to describe where state is stored
and computations occur. Using `DeviceSpec` allows you to parse device spec
strings to verify their validity, merge them or compose them programmatically.

#### Example:

    # Place the operations on device "GPU:0" in the "ps" job.
    device_spec = DeviceSpec(job="ps", device_type="GPU", device_index=0)
    with tf.device(device_spec.to_string()):
      # Both my_var and squared_var will be placed on /job:ps/device:GPU:0.
      my_var = tf.Variable(..., name="my_variable")
      squared_var = tf.square(my_var)

With eager execution disabled (by default in TensorFlow 1.x and by calling
disable_eager_execution() in TensorFlow 2.x), the following syntax
can be used:

    tf.compat.v1.disable_eager_execution()

    # Same as previous
    device_spec = DeviceSpec(job="ps", device_type="GPU", device_index=0)
    # No need of .to_string() method.
    with tf.device(device_spec):
      my_var = tf.Variable(..., name="my_variable")
      squared_var = tf.square(my_var)

If a `DeviceSpec` is partially specified, it will be merged with other
`DeviceSpec`s according to the scope in which it is defined. `DeviceSpec`
components defined in inner scopes take precedence over those defined in
outer scopes.

    gpu0_spec = DeviceSpec(job="ps", device_type="GPU", device_index=0)
    with tf.device(DeviceSpec(job="train").to_string()):
      with tf.device(gpu0_spec.to_string()):
        # Nodes created here will be assigned to /job:ps/device:GPU:0.
      with tf.device(DeviceSpec(device_type="GPU", device_index=1).to_string()):
        # Nodes created here will be assigned to /job:train/device:GPU:1.

A `DeviceSpec` consists of 5 components -- each of
which is optionally specified:

- Job: The job name.
- Replica: The replica index.
- Task: The task index.
- Device type: The device type string (e.g. "CPU" or "GPU").
- Device index: The device index.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `job` | string. Optional job name. |
| `replica` | int. Optional replica index. |
| `task` | int. Optional task index. |
| `device_type` | Optional device type string (e.g. "CPU" or "GPU") |
| `device_index` | int. Optional device index. If left unspecified, device represents 'any' device_index. |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `device_index` | <br /> <br /> |
| `device_type` | <br /> <br /> |
| `job` | <br /> <br /> |
| `replica` | <br /> <br /> |
| `task` | <br /> <br /> |

<br />

## Methods

### `from_string`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L145-L158)

    @classmethod
    from_string(
        spec
    )

Construct a `DeviceSpec` from a string.

<br />

<br />

<br />

| Args ||
|---|---|
| `spec` | a string of the form /job:/replica:/task:/device:CPU: or /job:/replica:/task:/device:GPU: as cpu and gpu are mutually exclusive. All entries are optional. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A DeviceSpec. ||

<br />

### `make_merged_spec`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L215-L237)

    make_merged_spec(
        dev
    )

Returns a new DeviceSpec which incorporates `dev`.

When combining specs, `dev` will take precedence over the current spec.
So for instance:

    first_spec = tf.DeviceSpec(job=0, device_type="CPU")
    second_spec = tf.DeviceSpec(device_type="GPU")
    combined_spec = first_spec.make_merged_spec(second_spec)

is equivalent to:

    combined_spec = tf.DeviceSpec(job=0, device_type="GPU")

<br />

<br />

<br />

| Args ||
|---|---|
| `dev` | a `DeviceSpec` |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A new `DeviceSpec` which combines `self` and `dev` ||

<br />

### `merge_from`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L471-L481)

    merge_from(
        dev
    )

Merge the properties of "dev" into this `DeviceSpec`.

> [!NOTE]
> **Note:** Will be removed in TensorFlow 2.x since DeviceSpecs will become immutable.

<br />

<br />

<br />

| Args ||
|---|---|
| `dev` | a `DeviceSpec`. |

<br />

### `parse_from_string`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L465-L469)

    parse_from_string(
        spec
    )

Parse a `DeviceSpec` name into its components.

**2.x behavior change**:

In TensorFlow 1.x, this function mutates its own state and returns itself.
In 2.x, DeviceSpecs are immutable, and this function will return a
DeviceSpec which contains the spec.

- Recommended:

      # my_spec and my_updated_spec are unrelated.
      my_spec = tf.DeviceSpec.from_string("/CPU:0")
      my_updated_spec = tf.DeviceSpec.from_string("/GPU:0")
      with tf.device(my_updated_spec):
        ...

- Will work in 1.x and 2.x (though deprecated in 2.x):

      my_spec = tf.DeviceSpec.from_string("/CPU:0")
      my_updated_spec = my_spec.parse_from_string("/GPU:0")
      with tf.device(my_updated_spec):
        ...

- Will NOT work in 2.x:

      my_spec = tf.DeviceSpec.from_string("/CPU:0")
      my_spec.parse_from_string("/GPU:0")  # <== Will not update my_spec
      with tf.device(my_spec):
        ...

In general, [`DeviceSpec.from_string`](https://www.tensorflow.org/api_docs/python/tf/DeviceSpec#from_string) should completely replace
[`DeviceSpec.parse_from_string`](https://www.tensorflow.org/api_docs/python/tf/DeviceSpec#parse_from_string), and [`DeviceSpec.replace`](https://www.tensorflow.org/api_docs/python/tf/DeviceSpec#replace) should
completely replace setting attributes directly.

<br />

<br />

<br />

| Args ||
|---|---|
| `spec` | an optional string of the form /job:/replica:/task:/device:CPU: or /job:/replica:/task:/device:GPU: as cpu and gpu are mutually exclusive. All entries are optional. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The `DeviceSpec`. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | if the spec was not valid. |

<br />

### `replace`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L239-L264)

    replace(
        **kwargs
    )

Convenience method for making a new DeviceSpec by overriding fields.

#### For instance:

    my_spec = DeviceSpec=(job="my_job", device="CPU")
    my_updated_spec = my_spec.replace(device="GPU")
    my_other_spec = my_spec.replace(device=None)

<br />

<br />

<br />

| Args ||
|---|---|
| `**kwargs` | This method takes the same args as the DeviceSpec constructor |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A DeviceSpec with the fields specified in kwargs overridden. ||

<br />

### `to_string`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L455-L463)

    to_string()

Return a string representation of this `DeviceSpec`.

<br />

<br />

<br />

| Returns ||
|---|---|
| a string of the form /job:/replica:/task:/device::. ||

<br />

### `__eq__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.13.1/tensorflow/python/framework/device_spec.py#L395-L409)

    __eq__(
        other
    )

Checks if the `other` DeviceSpec is same as the current instance, eg have

same value for all the internal fields.

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another DeviceSpec |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| Return `True` if `other` is also a DeviceSpec instance and has same value as the current instance. Return `False` otherwise. ||

<br />