![]() |
See the Variables Guide.
Inherits From: Variable
tf.compat.v1.Variable(
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.compat.v1.VariableAggregation.NONE, shape=None
)
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.
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.
Args | |
---|---|
initial_value
|
A Tensor , or Python object convertible to a Tensor ,
which is the initial value for the Variable. The initial value must have
a shape specified unless validate_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
|
If True , also adds the variable to the graph collection
GraphKeys.TRAINABLE_VARIABLES . This collection is used as the default
list of variables to use by the Optimizer classes. Defaults to True ,
unless synchronization is set to ON_READ , in which case it defaults
to False .
|
collections
|
List of graph collections keys. The new variable is added to
these collections. Defaults to [GraphKeys.GLOBAL_VARIABLES] .
|
validate_shape
|
If False , allows the variable to be initialized with a
value of unknown shape. If True , the default, the shape of
initial_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 not
None , caches on another device. Typical use is to cache on the device
where the Ops using the Variable reside, to deduplicate copying through
Switch and other conditional statements.
|
name
|
Optional name for the variable. Defaults to 'Variable' and gets
uniquified automatically.
|
variable_def
|
VariableDef protocol buffer. If not None , 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. If
None , either the datatype will be kept (if initial_value is a
Tensor), or convert_to_tensor will decide.
|
expected_shape
|
A TensorShape. If set, initial_value is expected to have this shape. |
import_scope
|
Optional string . Name scope to add to the Variable. Only
used when initializing from protocol buffer.
|
constraint
|
An optional projection function to be applied to the variable
after being updated by an Optimizer (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 class
tf.VariableSynchronization . By default the synchronization is set to
AUTO and the current DistributionStrategy chooses when to
synchronize.
|
aggregation
|
Indicates how a distributed variable will be aggregated.
Accepted values are constants defined in the class
tf.VariableAggregation .
|
shape
|
(optional) The shape of this variable. If None, the shape of
initial_value will be used. When setting this argument to
tf.TensorShape(None) (representing an unspecified shape), the variable
can be assigned with values of different shapes.
|
Raises | |
---|---|
ValueError
|
If both variable_def and initial_value are specified.
|
ValueError
|
If the initial value is not specified, or does not have a
shape and validate_shape is True .
|
RuntimeError
|
If eager execution is enabled. |
Attributes | |
---|---|
aggregation
|
|
constraint
|
Returns the constraint function associated with this variable. |
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 |
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.
|
synchronization
|
|
trainable
|
Child Classes
Methods
assign
assign(
value, use_locking=False, name=None, read_value=True
)
Assigns a new value to the variable.
This is essentially a shortcut for assign(self, value)
.
Args | |
---|---|
value
|
A Tensor . The new value for this variable.
|
use_locking
|
If True , use locking during the assignment.
|
name
|
The name of the operation to be created |
read_value
|
if True, will return something which evaluates to the new value of the variable; if False will return the assign op. |
Returns | |
---|---|
The updated variable. If read_value is false, instead returns None in
Eager mode and the assign op in graph mode.
|
assign_add
assign_add(
delta, use_locking=False, name=None, read_value=True
)
Adds a value to this variable.
This is essentially a shortcut for assign_add(self, delta)
.
Args | |
---|---|
delta
|
A Tensor . The value to add to this variable.
|
use_locking
|
If True , use locking during the operation.
|
name
|
The name of the operation to be created |
read_value
|
if True, will return something which evaluates to the new value of the variable; if False will return the assign op. |
Returns | |
---|---|
The updated variable. If read_value is false, instead returns None in
Eager mode and the assign op in graph mode.
|
assign_sub
assign_sub(
delta, use_locking=False, name=None, read_value=True
)
Subtracts a value from this variable.
This is essentially a shortcut for assign_sub(self, delta)
.
Args | |
---|---|
delta
|
A Tensor . The value to subtract from this variable.
|
use_locking
|
If True , use locking during the operation.
|
name
|
The name of the operation to be created |
read_value
|
if True, will return something which evaluates to the new value of the variable; if False will return the assign op. |
Returns | |
---|---|
The updated variable. I |