![]() |
![]() |
Class Variable
See the Variables Guide.
Inherits From: Variable
Aliases:
- Class
tf.compat.v1.Variable
A variable maintains state in the graph across calls to run()
. You add a
variable to the graph by constructing an instance of the class Variable
.
The Variable()
constructor requires an initial value for the variable,
which can be a Tensor
of any type and shape. The initial value defines the
type and shape of the variable. After construction, the type and shape of
the variable are fixed. The value can be changed using one of the assign
methods.
If you want to change the shape of a variable later you have to use an
assign
Op with validate_shape=False
.
Just like any Tensor
, variables created with Variable()
can be used as
inputs for other Ops in the graph. Additionally, all the operators
overloaded for the Tensor
class are carried over to variables, so you can
also add nodes to the graph by just doing arithmetic on variables.
import tensorflow as tf
# Create a variable.
w = tf.Variable(<initial-value>, name=<optional-name>)
# Use the variable in the graph like any Tensor.
y = tf.matmul(w, ...another variable or tensor...)
# The overloaded operators are available too.
z = tf.sigmoid(w + y)
# Assign a new value to the variable with `assign()` or a related method.
w.assign(w + 1.0)
w.assign_add(1.0)
When you launch the graph, variables have to be explicitly initialized before
you can run Ops that use their value. You can initialize a variable by
running its initializer op, restoring the variable from a save file, or
simply running an assign
Op that assigns a value to the variable. In fact,
the variable initializer op is just an assign
Op that assigns the
variable's initial value to the variable itself.
# Launch the graph in a session.
with tf.compat.v1.Session() as sess:
# Run the variable initializer.
sess.run(w.initializer)
# ...you now can run ops that use the value of 'w'...
The most common initialization pattern is to use the convenience function
global_variables_initializer()
to add an Op to the graph that initializes
all the variables. You then run that Op after launching the graph.
# Add an Op to initialize global variables.
init_op = tf.compat.v1.global_variables_initializer()
# Launch the graph in a session.
with tf.compat.v1.Session() as sess:
# Run the Op that initializes global variables.
sess.run(init_op)
# ...you can now run any Op that uses variable values...
If you need to create a variable with an initial value dependent on another
variable, use the other variable's initialized_value()
. This ensures that
variables are initialized in the right order.
All variables are automatically collected in the graph where they are
created. By default, the constructor adds the new variable to the graph
collection GraphKeys.GLOBAL_VARIABLES
. The convenience function
global_variables()
returns the contents of that collection.
When building a machine learning model it is often convenient to distinguish
between variables holding the trainable model parameters and other variables
such as a global step
variable used to count training steps. To make this
easier, the variable constructor supports a trainable=<bool>
parameter. If
True
, the new variable is also added to the graph collection
GraphKeys.TRAINABLE_VARIABLES
. The convenience function
trainable_variables()
returns the contents of this collection. The
various Optimizer
classes use this collection as the default list of
variables to optimize.
WARNING: tf.Variable objects by default have a non-intuitive memory model. A
Variable is represented internally as a mutable Tensor which can
non-deterministically alias other Tensors in a graph. The set of operations
which consume a Variable and can lead to aliasing is undetermined and can
change across TensorFlow versions. Avoid writing code which relies on the
value of a Variable either changing or not changing as other operations
happen. For example, using Variable objects or simple functions thereof as
predicates in a tf.cond
is dangerous and error-prone:
v = tf.Variable(True)
tf.cond(v, lambda: v.assign(False), my_false_fn) # Note: this is broken.
Here, adding use_resource=True
when constructing the variable will
fix any nondeterminism issues:
v = tf.Variable(True, use_resource=True)
tf.cond(v, lambda: v.assign(False), my_false_fn)
To use the replacement for variables which does not have these issues:
- Add
use_resource=True
when constructingtf.Variable
; - Call
tf.compat.v1.get_variable_scope().set_use_resource(True)
inside atf.compat.v1.variable_scope
before thetf.compat.v1.get_variable()
call.
__init__
__init__(
initial_value=None,
trainable=None,
collections=None,
validate_shape=True,
caching_device=None,
name=None,
variable_def=None,
dtype=None,
expected_shape=None,
import_scope=None,
constraint=None,
use_resource=None,
synchronization=tf.VariableSynchronization.AUTO,
aggregation=tf.VariableAggregation.NONE,
shape=None
)
Creates a new variable with value initial_value
.
The new variable is added to the graph collections listed in collections
,
which defaults to [GraphKeys.GLOBAL_VARIABLES]
.
If trainable
is True
the variable is also added to the graph collection
GraphKeys.TRAINABLE_VARIABLES
.
This constructor creates both a variable
Op and an assign
Op to set the
variable to its initial value.
Args:
initial_value
: ATensor
, or Python object convertible to aTensor
, which is the initial value for the Variable. The initial value must have a shape specified unlessvalidate_shape
is set to False. Can also be a callable with no argument that returns the initial value when called. In that case,dtype
must be specified. (Note that initializer functions from init_ops.py must first be bound to a shape before being used here.)trainable
: IfTrue
, also adds the variable to the graph collectionGraphKeys.TRAINABLE_VARIABLES
. This collection is used as the default list of variables to use by theOptimizer
classes. Defaults toTrue
, unlesssynchronization
is set toON_READ
, in which case it defaults toFalse
.collections
: List of graph collections keys. The new variable is added to these collections. Defaults to[GraphKeys.GLOBAL_VARIABLES]
.validate_shape
: IfFalse
, allows the variable to be initialized with a value of unknown shape. IfTrue
, the default, the shape ofinitial_value
must be known.caching_device
: Optional device string describing where the Variable should be cached for reading. Defaults to the Variable's device. If notNone
, caches on another device. Typical use is to cache on the device where the Ops using the Variable reside, to deduplicate copying throughSwitch
and other conditional statements.name
: Optional name for the variable. Defaults to'Variable'
and gets uniquified automatically.variable_def
:VariableDef
protocol buffer. If notNone
, recreates the Variable object with its contents, referencing the variable's nodes in the graph, which must already exist. The graph is not changed.variable_def
and the other arguments are mutually exclusive.dtype
: If set, initial_value will be converted to the given type. IfNone
, either the datatype will be kept (ifinitial_value
is a Tensor), orconvert_to_tensor
will decide.expected_shape
: A TensorShape. If set, initial_value is expected to have this shape.import_scope
: Optionalstring
. Name scope to add to theVariable.
Only used when initializing from protocol buffer.constraint
: An optional projection function to be applied to the variable after being updated by anOptimizer
(e.g. used to implement norm constraints or value constraints for layer weights). The function must take as input the unprojected Tensor representing the value of the variable and return the Tensor for the projected value (which must have the same shape). Constraints are not safe to use when doing asynchronous distributed training.use_resource
: whether to use resource variables.synchronization
: Indicates when a distributed a variable will be aggregated. Accepted values are constants defined in the classtf.VariableSynchronization
. By default the synchronization is set toAUTO
and the currentDistributionStrategy
chooses when to synchronize.aggregation
: Indicates how a distributed variable will be aggregated. Accepted values are constants defined in the classtf.VariableAggregation
.shape
: (optional) The shape of this variable. If None, the shape ofinitial_value
will be used. When setting this argument totf.TensorShape(None)
(representing an unspecified shape), the variable can be assigned with values of different shapes.
Raises:
ValueError
: If bothvariable_def
and initial_value are specified.ValueError
: If the initial value is not specified, or does not have a shape andvalidate_shape
isTrue
.RuntimeError
: If eager execution is enabled.
Child Classes
Properties
aggregation
constraint
Returns the constraint function associated with this variable.
Returns:
The constraint function that was passed to the variable constructor.
Can be None
if no constraint was passed.
device
The device of this variable.
dtype
The DType
of this variable.
graph
The Graph
of this variable.
initial_value
Returns the Tensor used as the initial value for the variable.
Note that this is different from initialized_value()
which runs
the op that initializes the variable before returning its value.
This method returns the tensor that is used by the op that initializes
the variable.
Returns:
A Tensor
.
initializer
The initializer operation for this variable.
name
The name of this variable.
op
The Operation
of this variable.
shape
The TensorShape
of this variable.
Returns:
A TensorShape
.
synchronization
trainable
Methods
__abs__
__abs__(
x,
name=None
)
Computes the absolute value of a tensor.
Given a tensor of integer or floating-point values, this operation returns a tensor of the same type, where each element contains the absolute value of the corresponding element in the input.
Given a tensor x
of complex numbers, this operation returns a tensor of type
float32
or float64
that is the absolute value of each element in x
. All
elements in x
must be complex numbers of the form \(a + bj\). The
absolute value is computed as \( \sqrt{a^2 + b^2}\). For example:
x = tf.constant([[-2.25 + 4.75j], [-3.25 + 5.75j]])
tf.abs(x) # [5.25594902, 6.60492229]
Args:
x
: ATensor
orSparseTensor
of typefloat16
,float32
,float64
,int32
,int64
,complex64
orcomplex128
.name
: A name for the operation (optional).
Returns:
A Tensor
or SparseTensor
the same size, type, and sparsity as x
with
absolute values.
Note, for complex64
or complex128
input, the returned Tensor
will be
of type float32
or float64
, respectively.
__add__
__add__(
a,
*args,
**kwargs
)
Dispatches to add for strings and add_v2 for all other types.
__and__
__and__(
a,
*args,
**kwargs
)
Returns the truth value of x AND y element-wise.
NOTE: math.logical_and
supports broadcasting. More about broadcasting
here
Args:
x
: ATensor
of typebool
.y
: ATensor
of typebool
.name
: A name for the operation (optional).
Returns:
A Tensor
of type bool
.
__div__
__div__(
a,
*args,
**kwargs
)
Divide two values using Python 2 semantics.
Used for Tensor.div.
Args:
x
:Tensor
numerator of real numeric type.y
:Tensor
denominator of real numeric type.name
: A name for the operation (optional).
Returns:
x / y
returns the quotient of x and y.
__eq__
__eq__(other)
Compares two variables element-wise for equality.
__floordiv__
__floordiv__(
a,
*args,
**kwargs
)
Divides x / y
elementwise, rounding toward the most negative integer.
The same as tf.compat.v1.div(x,y)
for integers, but uses
tf.floor(tf.compat.v1.div(x,y))
for
floating point arguments so that the result is always an integer (though
possibly an integer represented as floating point). This op is generated by
x // y
floor division in Python 3 and in Python 2.7 with
from __future__ import division
.
x
and y
must have the same type, and the result will have the same type
as well.
Args:
x
:Tensor
numerator of real numeric type.y
:Tensor
denominator of real numeric type.name
: A name for the operation (optional).
Returns:
x / y
rounded down.
Raises:
TypeError
: If the inputs are complex.
__ge__
__ge__(
a,
*args,
**kwargs
)
Returns the truth value of (x >= y) element-wise.
NOTE: math.greater_equal
supports broadcasting. More about broadcasting
here
Args:
x
: ATensor
. Must be one of the following types:float32
,float64
,int32
,uint8
,int16
,int8
,int64
,bfloat16
,uint16
,half
,uint32
,uint64
.y
: ATensor
. Must have the same type asx
.name
: A name for the operation (optional).
Returns:
A Tensor
of type bool
.
__getitem__
__getitem__(
var,
slice_spec
)
Creates a slice helper object given a variable.
This allows creating a sub-tensor from part of the current contents
of a variable. See tf.Tensor.getitem
for detailed examples
of slicing.
This function in addition also allows assignment to a sliced range.
This is similar to __setitem__
functionality in Python. However,
the syntax is different so that the user can capture the assignment
operation for grouping or passing to sess.run()
.
For example,
import tensorflow as tf
A = tf.Variable([[1,2,3], [4,5,6], [7,8,9]], dtype=tf.float32)
with tf.compat.v1.Session() as sess:
sess.run(tf.compat.v1.global_variables_initializer())
print(sess.run(A[:2, :2])) # => [[1,2], [4,5]]
op = A[:2,:2].assign(22. * tf.ones((2, 2)))
print(sess.run(op)) # => [[22, 22, 3], [22, 22, 6], [7,8,9]]
Note that assignments currently do not support NumPy broadcasting semantics.
Args:
var
: Anops.Variable
object.slice_spec
: The arguments toTensor.getitem
.
Returns:
The appropriate slice of "tensor", based on "slice_spec".
As an operator. The operator also has a assign()
method
that can be used to generate an assignment operator.
Raises:
ValueError
: If a slice range is negative size.TypeError
: TypeError: If the slice indices aren't int, slice, ellipsis, tf.newaxis or int32/int64 tensors.
__gt__
__gt__(
a,
*args,
**kwargs
)
Returns the truth value of (x > y) element-wise.
NOTE: math.greater
supports broadcasting. More about broadcasting
here
Args:
x
: ATensor
. Must be one of the following types:float32
,float64
,int32
,uint8
,int16
,int8
,int64
,bfloat16
,uint16
,