Defining new operations

class tf.RegisterGradient

A decorator for registering the gradient function for an op type.

This decorator is only used when defining a new op type. For an op with m inputs and n outputs, the gradient function is a function that takes the original Operation and n Tensor objects (representing the gradients with respect to each output of the op), and returns m Tensor objects (representing the partial gradients with respect to each input of the op).

For example, assuming that operations of type "Sub" take two inputs x and y, and return a single output x - y, the following gradient function would be registered:

@tf.RegisterGradient("Sub")
def _sub_grad(unused_op, grad):
  return grad, tf.neg(grad)

The decorator argument op_type is the string type of an operation. This corresponds to the OpDef.name field for the proto that defines the operation.


tf.RegisterGradient.__init__(op_type) {:#RegisterGradient.init}

Creates a new decorator with op_type as the Operation type.

Args:
  • op_type: The string type of an operation. This corresponds to the OpDef.name field for the proto that defines the operation.

Other Methods


tf.RegisterGradient.__call__(f) {:#RegisterGradient.call}

Registers the function f as gradient function for op_type.


tf.NotDifferentiable(op_type)

Specifies that ops of type op_type is not differentiable.

This function should not be used for operations that have a well-defined gradient that is not yet implemented.

This function is only used when defining a new op type. It may be used for ops such as tf.size() that are not differentiable. For example:

tf.NotDifferentiable("Size")

The gradient computed for 'op_type' will then propagate zeros.

For ops that have a well-defined gradient but are not yet implemented, no declaration should be made, and an error must be thrown if an attempt to request its gradient is made.

Args:
  • op_type: The string type of an operation. This corresponds to the OpDef.name field for the proto that defines the operation.
Raises:
  • TypeError: If op_type is not a string.

tf.NoGradient(op_type)

Specifies that ops of type op_type is not differentiable.

This function should not be used for operations that have a well-defined gradient that is not yet implemented.

This function is only used when defining a new op type. It may be used for ops such as tf.size() that are not differentiable. For example:

tf.NotDifferentiable("Size")

The gradient computed for 'op_type' will then propagate zeros.

For ops that have a well-defined gradient but are not yet implemented, no declaration should be made, and an error must be thrown if an attempt to request its gradient is made.

Args:
  • op_type: The string type of an operation. This corresponds to the OpDef.name field for the proto that defines the operation.
Raises:
  • TypeError: If op_type is not a string.

class tf.RegisterShape

A decorator for registering the shape function for an op type.

Soon to be removed. Shape functions should be registered via the SetShapeFn on the original Op specification in C++.


tf.RegisterShape.__call__(f) {:#RegisterShape.call}

Registers "f" as the shape function for "op_type".


tf.RegisterShape.__init__(op_type) {:#RegisterShape.init}

Saves the op_type as the Operation type.


class tf.TensorShape

Represents the shape of a Tensor.

A TensorShape represents a possibly-partial shape specification for a Tensor. It may be one of the following:

  • Fully-known shape: has a known number of dimensions and a known size for each dimension.
  • Partially-known shape: has a known number of dimensions, and an unknown size for one or more dimension.
  • Unknown shape: has an unknown number of dimensions, and an unknown size in all dimensions.

If a tensor is produced by an operation of type "Foo", its shape may be inferred if there is a registered shape function for "Foo". See Shape functions in C++ for details of shape functions and how to register them. Alternatively, the shape may be set explicitly using Tensor.set_shape().


tf.TensorShape.merge_with(other)

Returns a TensorShape combining the information in self and other.

The dimensions in self and other are merged elementwise, according to the rules defined for Dimension.merge_with().

Args:
  • other: Another TensorShape.
Returns:

A TensorShape containing the combined information of self and other.

Raises:
  • ValueError: If self and other are not compatible.

tf.TensorShape.concatenate(other)

Returns the concatenation of the dimension in self and other.

N.B. If either self or other is completely unknown, concatenation will discard information about the other shape. In future, we might support concatenation that preserves this information for use with slicing.

Args:
  • other: Another TensorShape.
Returns:

A TensorShape whose dimensions are the concatenation of the dimensions in self and other.


tf.TensorShape.ndims

Returns the rank of this shape, or None if it is unspecified.


tf.TensorShape.dims

Returns a list of Dimensions, or None if the shape is unspecified.


tf.TensorShape.as_list()

Returns a list of integers or None for each dimension.

Returns:

A list of integers or None for each dimension.

Raises:
  • ValueError: If self is an unknown shape with an unknown rank.

tf.TensorShape.as_proto()

Returns this shape as a TensorShapeProto.


tf.TensorShape.is_compatible_with(other)

Returns True iff self is compatible with other.

Two possibly-partially-defined shapes are compatible if there exists a fully-defined shape that both shapes can represent. Thus, compatibility allows the shape inference code to reason about partially-defined shapes. For example:

  • TensorShape(None) is compatible with all shapes.

  • TensorShape([None, None]) is compatible with all two-dimensional shapes, such as TensorShape([32, 784]), and also TensorShape(None). It is not compatible with, for example, TensorShape([None]) or TensorShape([None, None, None]).

  • TensorShape([32, None]) is compatible with all two-dimensional shapes with size 32 in the 0th dimension, and also TensorShape([None, None]) and TensorShape(None). It is not compatible with, for example, TensorShape([32]), TensorShape([32, None, 1]) or TensorShape([64, None]).

  • TensorShape([32, 784]) is compatible with itself, and also TensorShape([32, None]), TensorShape([None, 784]), TensorShape([None, None]) and TensorShape(None). It is not compatible with, for example, TensorShape([32, 1, 784]) or TensorShape([None]).

The compatibility relation is reflexive and symmetric, but not transitive. For example, TensorShape([32, 784]) is compatible with TensorShape(None), and TensorShape(None) is compatible with TensorShape([4, 4]), but TensorShape([32, 784]) is not compatible with TensorShape([4, 4]).

Args:
  • other: Another TensorShape.
Returns:

True iff self is compatible with other.


tf.TensorShape.is_fully_defined()

Returns True iff self is fully defined in every dimension.


tf.TensorShape.with_rank(rank)

Returns a shape based on self with the given rank.

This method promotes a completely unknown shape to one with a known rank.

Args:
  • rank: An integer.
Returns:

A shape that is at least as specific as self with the given rank.

Raises:
  • ValueError: If self does not represent a shape with the given rank.

tf.TensorShape.with_rank_at_least(rank)

Returns a shape based on self with at least the given rank.

Args:
  • rank: An integer.
Returns:

A shape that is at least as specific as self with at least the given rank.

Raises:
  • ValueError: If self does not represent a shape with at least the given rank.

tf.TensorShape.with_rank_at_most(rank)

Returns a shape based on self with at most the given rank.

Args:
  • rank: An integer.
Returns:

A shape that is at least as specific as self with at most the given rank.

Raises:
  • ValueError: If self does not represent a shape with at most the given rank.

tf.TensorShape.assert_has_rank(rank)

Raises an exception if self is not compatible with the given rank.

Args:
  • rank: An integer.
Raises:
  • ValueError: If self does not represent a shape with the given rank.

tf.TensorShape.assert_same_rank(other)

Raises an exception if self and other do not have compatible ranks.

Args:
  • other: Another TensorShape.
Raises:
  • ValueError: If self and other do not represent shapes with the same rank.

tf.TensorShape.assert_is_compatible_with(other)

Raises exception if self and other do not represent the same shape.

This method can be used to assert that there exists a shape that both self and other represent.

Args:
  • other: Another TensorShape.
Raises:
  • ValueError: If self and other do not represent the same shape.

tf.TensorShape.assert_is_fully_defined()

Raises an exception if self is not fully defined in every dimension.

Raises:
  • ValueError: If self does not have a known value for every dimension.

Other Methods


tf.TensorShape.__bool__() {:#TensorShape.bool}

Returns True if this shape contains non-zero information.


tf.TensorShape.__eq__(other) {:#TensorShape.eq}

Returns True if self is equivalent to other.


tf.TensorShape.__getitem__(key) {:#TensorShape.getitem}

Returns the value of a dimension or a shape, depending on the key.

Args:
  • key: If key is an integer, returns the dimension at that index; otherwise if key is a slice, returns a TensorShape whose dimensions are those selected by the slice from self.
Returns:

A dimension if key is an integer, or a TensorShape if key is a slice.

Raises:
  • ValueError: If key is a slice, and any of its elements are negative, or if self is completely unknown and the step is set.

tf.TensorShape.__init__(dims) {:#TensorShape.init}

Creates a new TensorShape with the given dimensions.

Args:
  • dims: A list of Dimensions, or None if the shape is unspecified.
  • DEPRECATED: A single integer is treated as a singleton list.
Raises:
  • TypeError: If dims cannot be converted to a list of dimensions.

tf.TensorShape.__iter__() {:#TensorShape.iter}

Returns self.dims if the rank is known, otherwise raises ValueError.


tf.TensorShape.__len__() {:#TensorShape.len}

Returns the rank of this shape, or raises ValueError if unspecified.


tf.TensorShape.__ne__(other) {:#TensorShape.ne}

Returns True if self is known to be different from other.


tf.TensorShape.__nonzero__() {:#TensorShape.nonzero}

Returns True if this shape contains non-zero information.


tf.TensorShape.__repr__() {:#TensorShape.repr}


tf.TensorShape.__str__() {:#TensorShape.str}


tf.TensorShape.num_elements()

Returns the total number of elements, or none for incomplete shapes.


class tf.Dimension

Represents the value of one dimension in a TensorShape.


tf.Dimension.__add__(other) {:#Dimension.add}

Returns the sum of self and other.

Dimensions are summed as follows:

Dimension(m) + Dimension(n) == Dimension(m + n) Dimension(m) + Dimension(None) == Dimension(None) Dimension(None) + Dimension(n) == Dimension(None) Dimension(None) + Dimension(None) == Dimension(None)

Args:
  • other: Another Dimension.
Returns:

A Dimension whose value is the sum of self and other.


tf.Dimension.__div__(other) {:#Dimension.div}

DEPRECATED: Use __floordiv__ via x // y instead.

This function exists only for backwards compatibility purposes; new code should use __floordiv__ via the syntax x // y. Using x // y communicates clearly that the result rounds down, and is forward compatible to Python 3.

Args:
  • other: Another Dimension.
Returns:

A Dimension whose value is the integer quotient of self and other.


tf.Dimension.__eq__(other) {:#Dimension.eq}

Returns true if other has the same known value as this Dimension.


tf.Dimension.__floordiv__(other) {:#Dimension.floordiv}

Returns the quotient of self and other rounded down.

Dimensions are divided as follows:

Dimension(m) // Dimension(n) == Dimension(m // n) Dimension(m) // Dimension(None) == Dimension(None) Dimension(None) // Dimension(n) == Dimension(None) Dimension(None) // Dimension(None) == Dimension(None)

Args:
  • other: Another Dimension.
Returns:

A Dimension whose value is the integer quotient of self and other.


tf.Dimension.__ge__(other) {:#Dimension.ge}

Returns True if self is known to be greater than or equal to other.

Dimensions are compared as follows:

Dimension(m) >= Dimension(n) == m >= n Dimension(m) >= Dimension(None) == None Dimension(None) >= Dimension(n) == None Dimension(None) >= Dimension(None) == None

Args:
  • other: Another Dimension.
Returns:

The value of self.value >= other.value if both are known, otherwise None.


tf.Dimension.__gt__(other) {:#Dimension.gt}

Returns True if self is known to be greater than other.

Dimensions are compared as follows:

Dimension(m) > Dimension(n) == m > n Dimension(m) > Dimension(None) == None Dimension(None) > Dimension(n) == None Dimension(None) > Dimension(None) == None

Args:
  • other: Another Dimension.
Returns:

The value of self.value > other.value if both are known, otherwise None.


tf.Dimension.__index__() {:#Dimension.index}


tf.Dimension.__init__(value) {:#Dimension.init}

Creates a new Dimension with the given value.


tf.Dimension.__int__() {:#Dimension.int}


tf.Dimension.__le__(other) {:#Dimension.le}

Returns True if self is known to be less than or equal to other.

Dimensions are compared as follows:

Dimension(m) <= Dimension(n) == m <= n Dimension(m) <= Dimension(None) == None Dimension(None) <= Dimension(n) == None Dimension(None) <= Dimension(None) == None

Args:
  • other: Another Dimension.
Returns:

The value of self.value <= other.value if both are known, otherwise None.


tf.Dimension.__lt__(other) {:#Dimension.lt}

Returns True if self is known to be less than other.

Dimensions are compared as follows:

Dimension(m) < Dimension(n) == m < n Dimension(m) < Dimension(None) == None Dimension(None) < Dimension(n) == None Dimension(None) < Dimension(None) == None

Args:
  • other: Another Dimension.
Returns:

The value of self.value < other.value if both are known, otherwise None.


tf.Dimension.__mod__(other) {:#Dimension.mod}

Returns self modulo `other.

Dimension moduli are computed as follows:

Dimension(m) % Dimension(n) == Dimension(m % n) Dimension(m) % Dimension(None) == Dimension(None) Dimension(None) % Dimension(n) == Dimension(None) Dimension(None) % Dimension(None) == Dimension(None)

Args:
  • other: Another Dimension.
Returns:

A Dimension whose value is self modulo other.


tf.Dimension.__mul__(other) {:#Dimension.mul}

Returns the product of self and other.

Dimensions are summed as follows:

  Dimension(m)    * Dimension(n)    == Dimension(m * n)
  Dimension(m)    * Dimension(None) == Dimension(None)
  Dimension(None) * Dimension(n)    == Dimension(None)
  Dimension(None) * Dimension(None) == Dimension(None)
Args:
  • other: Another Dimension.
Returns:

A Dimension whose value is the product of self and other.


tf.Dimension.__ne__(other) {:#Dimension.ne}

Returns true if other has a different known value from self.


tf.Dimension.__repr__() {:#Dimension.repr}


tf.Dimension.__str__() {:#Dimension.str}


tf.Dimension.__sub__(other) {:#Dimension.sub}

Returns the subtraction of other from self.

Dimensions are subtracted as follows:

Dimension(m) - Dimension(n) == Dimension(m - n) Dimension(m) - Dimension(None) == Dimension(None) Dimension(None) - Dimension(n) == Dimension(None) Dimension(None) - Dimension(None) == Dimension(None)

Args:
  • other: Another Dimension.
Returns:

A Dimension whose value is the subtraction of sum of other from self.


tf.Dimension.assert_is_compatible_with(other)

Raises an exception if other is not compatible with this Dimension.

Args:
  • other: Another Dimension.
Raises:
  • ValueError: If self and other are not compatible (see is_compatible_with).

tf.Dimension.is_compatible_with(other)

Returns true if other is compatible with this Dimension.

Two known Dimensions are compatible if they have the same value. An unknown Dimension is compatible with all other Dimensions.

Args:
  • other: Another Dimension.
Returns:

True if this Dimension and other are compatible.


tf.Dimension.merge_with(other)

Returns a Dimension that combines the information in self and other.

Dimensions are combined as follows:

    Dimension(n)   .merge_with(Dimension(n))    == Dimension(n)
    Dimension(n)   .merge_with(Dimension(None)) == Dimension(n)
    Dimension(None).merge_with(Dimension(n))    == Dimension(n)
    Dimension(None).merge_with(Dimension(None)) == Dimension(None)
    Dimension(n)   .merge_with(Dimension(m)) raises ValueError for n != m
Args:
  • other: Another Dimension.
Returns:

A Dimension containing the combined information of self and other.

Raises:
  • ValueError: If self and other are not compatible (see is_compatible_with).

tf.Dimension.value

The value of this dimension, or None if it is unknown.


tf.op_scope(values, name, default_name=None)

DEPRECATED. Same as name_scope above, just different argument order.


tf.get_seed(op_seed)

Returns the local seeds an operation should use given an op-specific seed.

Given operation-specific seed, op_seed, this helper function returns two seeds derived from graph-level and op-level seeds. Many random operations internally use the two seeds to allow user to change the seed globally for a graph, or for only specific operations.

For details on how the graph-level seed interacts with op seeds, see set_random_seed.

Args:
  • op_seed: integer.
Returns:

A tuple of two integers that should be used for the local seed of this operation.