TensorFlow - Running Graph

Running Graph

Contents

• Running Graphs
• Session management
• class tf.Session
• class tf.InteractiveSession
• tf.get_default_session()
• Error classes
• class tf.OpError
• class tf.errors.CancelledError
• class tf.errors.UnknownError
• class tf.errors.InvalidArgumentError
• class tf.errors.DeadlineExceededError
• class tf.errors.NotFoundError
• class tf.errors.AlreadyExistsError
• class tf.errors.PermissionDeniedError
• class tf.errors.UnauthenticatedError
• class tf.errors.ResourceExhaustedError
• class tf.errors.FailedPreconditionError
• class tf.errors.AbortedError
• class tf.errors.OutOfRangeError
• class tf.errors.UnimplementedError
• class tf.errors.InternalError
• class tf.errors.UnavailableError
• class tf.errors.DataLossError

This library contains classes for launching graphs and executing operations.

The basic usage guide hasexamples of how a graph is launched in a tf.Session.

Session management

---

class tf.Session

A class for running TensorFlow operations.

A Session object encapsulates the environment in which Operationobjects are executed, and Tensor objects are evaluated. Forexample:

# Build a graph.a = tf.constant(5.0)b = tf.constant(6.0)c = a * b# Launch the graph in a session.sess = tf.Session()# Evaluate the tensor `c`.print(sess.run(c))

A session may own resources, such asvariables, queues,and readers. It is important to releasethese resources when they are no longer required. To do this, eitherinvoke the close() method on the session, or usethe session as a context manager. The following two examples areequivalent:

# Using the `close()` method.sess = tf.Session()sess.run(...)sess.close()# Using the context manager.with tf.Session() as sess:  sess.run(...)

The ConfigProtoprotocol buffer exposes various configuration options for asession. For example, to create a session that uses soft constraintsfor device placement, and log the resulting placement decisions,create a session as follows:

# Launch the graph in a session that allows soft device placement and# logs the placement decisions.sess = tf.Session(config=tf.ConfigProto(allow_soft_placement=True,                                        log_device_placement=True))

---

tf.Session.__init__(target='', graph=None, config=None)

Creates a new TensorFlow session.

If no graph argument is specified when constructing the session,the default graph will be launched in the session. If you areusing more than one graph (created with tf.Graph() in the sameprocess, you will have to use different sessions for each graph,but each graph can be used in multiple sessions. In this case, itis often clearer to pass the graph to be launched explicitly tothe session constructor.

Args:

• target: (Optional.) The execution engine to connect to.Defaults to using an in-process engine. At present, no valueother than the empty string is supported.
• graph: (Optional.) The Graph to be launched (described above).
• config: (Optional.) A ConfigProtoprotocol buffer with configuration options for the session.

---

tf.Session.run(fetches, feed_dict=None, options=None, run_metadata=None)

Runs the operations and evaluates the tensors in fetches.

This method runs one "step" of TensorFlow computation, byrunning the necessary graph fragment to execute every Operationand evaluate every Tensor in fetches, substituting the values infeed_dict for the corresponding input values.

The fetches argument may be a list of graph elements or a singlegraph element, and these determine the return value of thismethod. A graph element can be one of the following types:

• If the *i*th element of fetches is anOperation, the *i*threturn value will be None.
• If the *i*th element of fetches is aTensor, the *i*th returnvalue will be a numpy ndarray containing the value of that tensor.
• If the *i*th element of fetches is aSparseTensor,the *i*th return value will be aSparseTensorValuecontaining the value of that sparse tensor.
• If the *i*th element of fetches is produced by a get_tensor_handle op,the *i*th return value will be a numpy ndarray containing the handle ofthat tensor.

The optional feed_dict argument allows the caller to overridethe value of tensors in the graph. Each key in feed_dict can beone of the following types:

• If the key is a Tensor, thevalue may be a Python scalar, string, list, or numpy ndarraythat can be converted to the same dtype as thattensor. Additionally, if the key is aplaceholder, the shape ofthe value will be checked for compatibility with the placeholder.
• If the key is aSparseTensor,the value should be aSparseTensorValue.

The optional options argument expects a [RunOptions] proto. The optionsallow controlling the behavior of this particular step (e.g. turning tracingon).

The optional run_metadata argument expects a [RunMetadata] proto. Whenappropriate, the non-Tensor output of this step will be collected there. Forexample, when users turn on tracing in options, the profiled info will becollected into this argument and passed back.

Args:

• fetches: A single graph element, or a list of graph elements(described above).
• feed_dict: A dictionary that maps graph elements to values(described above).
• options: A [RunOptions] protocol buffer
• run_metadata: A [RunMetadata] protocol buffer

Returns:

Either a single value if fetches is a single graph element, or a list of values if fetches is a list (described above).

Raises:

• RuntimeError: If this Session is in an invalid state (e.g. has beenclosed).
• TypeError: If fetches or feed_dict keys are of an inappropriate type.
• ValueError: If fetches or feed_dict keys are invalid or refer to aTensor that doesn't exist.

---

tf.Session.close()

Closes this session.

Calling this method frees all resources associated with the session.

Raises:

• RuntimeError: If an error occurs while closing the session.

---

tf.Session.graph

The graph that was launched in this session.

---

tf.Session.as_default()

Returns a context manager that makes this object the default session.

Use with the with keyword to specify that calls toOperation.run() orTensor.run() should beexecuted in this session.

c = tf.constant(..)sess = tf.Session()with sess.as_default():  assert tf.get_default_session() is sess  print(c.eval())

To get the current default session, usetf.get_default_session().

N.B. The as_default context manager does not close thesession when you exit the context, and you must close the sessionexplicitly.

c = tf.constant(...)sess = tf.Session()with sess.as_default():  print(c.eval())# ...with sess.as_default():  print(c.eval())sess.close()

Alternatively, you can use with tf.Session(): to create asession that is automatically closed on exiting the context,including when an uncaught exception is raised.

N.B. The default graph is a property of the current thread. If youcreate a new thread, and wish to use the default session in thatthread, you must explicitly add a with sess.as_default(): in thatthread's function.

Returns:

A context manager using this session as the default session.

---

class tf.InteractiveSession

A TensorFlow Session for use in interactive contexts, such as a shell.

The only difference with a regular Session is that an InteractiveSessioninstalls itself as the default session on construction.The methods Tensor.eval()and Operation.run()will use that session to run ops.

This is convenient in interactive shells and IPythonnotebooks, as it avoids having to pass an explicitSession object to run ops.

For example:

sess = tf.InteractiveSession()a = tf.constant(5.0)b = tf.constant(6.0)c = a * b# We can just use 'c.eval()' without passing 'sess'print(c.eval())sess.close()

Note that a regular session installs itself as the default session when itis created in a with statement. The common usage in non-interactiveprograms is to follow that pattern:

a = tf.constant(5.0)b = tf.constant(6.0)c = a * bwith tf.Session():  # We can also use 'c.eval()' here.  print(c.eval())

---

tf.InteractiveSession.__init__(target='', graph=None, config=None)

Creates a new interactive TensorFlow session.

If no graph argument is specified when constructing the session,the default graph will be launched in the session. If you areusing more than one graph (created with tf.Graph() in the sameprocess, you will have to use different sessions for each graph,but each graph can be used in multiple sessions. In this case, itis often clearer to pass the graph to be launched explicitly tothe session constructor.

Args:

• target: (Optional.) The execution engine to connect to.Defaults to using an in-process engine. At present, no valueother than the empty string is supported.
• graph: (Optional.) The Graph to be launched (described above).
• config: (Optional) ConfigProto proto used to configure the session.

---

tf.InteractiveSession.close()

Closes an InteractiveSession.

---

tf.get_default_session()

Returns the default session for the current thread.

The returned Session will be the innermost session on which aSession or Session.as_default() context has been entered.

NOTE: The default session is a property of the current thread. If youcreate a new thread, and wish to use the default session in thatthread, you must explicitly add a with sess.as_default(): in thatthread's function.

Returns:

The default Session being used in the current thread.

Error classes

---

class tf.OpError

A generic error that is raised when TensorFlow execution fails.

Whenever possible, the session will raise a more specific subclassof OpError from the tf.errors module.

---

tf.OpError.op

The operation that failed, if known.

N.B. If the failed op was synthesized at runtime, e.g. a Sendor Recv op, there will be no correspondingOperationobject. In that case, this will return None, and you shouldinstead use the OpError.node_def todiscover information about the op.

Returns:

The Operation that failed, or None.

---

tf.OpError.node_def

The NodeDef proto representing the op that failed.

Other Methods

---

tf.OpError.__init__(node_def, op, message, error_code)

Creates a new OpError indicating that a particular op failed.

Args:

• node_def: The graph_pb2.NodeDef proto representing the op that failed,if known; otherwise None.
• op: The ops.Operation that failed, if known; otherwise None.
• message: The message string describing the failure.
• error_code: The error_codes_pb2.Code describing the error.

---

tf.OpError.error_code

The integer error code that describes the error.

---

tf.OpError.message

The error message that describes the error.

---

class tf.errors.CancelledError

Raised when an operation or step is cancelled.

For example, a long-running operation (e.g.queue.enqueue() may becancelled by running another operation (e.g.queue.close(cancel_pending_enqueues=True),or by closing the session.A step that is running such a long-running operation will fail by raisingCancelledError.

---

tf.errors.CancelledError.__init__(node_def, op, message)

Creates a CancelledError.

---

class tf.errors.UnknownError

Unknown error.

An example of where this error may be returned is if a Status valuereceived from another address space belongs to an error-space thatis not known to this address space. Also errors raised by APIs thatdo not return enough error information may be converted to thiserror.

---

tf.errors.UnknownError.__init__(node_def, op, message, error_code=2)

Creates an UnknownError.

---

class tf.errors.InvalidArgumentError

Raised when an operation receives an invalid argument.

This may occur, for example, if an operation is receives an inputtensor that has an invalid value or shape. For example, thetf.matmul() op will raise thiserror if it receives an input that is not a matrix, and thetf.reshape() op will raisethis error if the new shape does not match the number of elements in the inputtensor.

---

tf.errors.InvalidArgumentError.__init__(node_def, op, message)

Creates an InvalidArgumentError.

---

class tf.errors.DeadlineExceededError

Raised when a deadline expires before an operation could complete.

This exception is not currently used.

---

tf.errors.DeadlineExceededError.__init__(node_def, op, message)

Creates a DeadlineExceededError.

---

class tf.errors.NotFoundError

Raised when a requested entity (e.g., a file or directory) was not found.

For example, running thetf.WholeFileReader.read()operation could raise NotFoundError if it receives the name of a file thatdoes not exist.

---

tf.errors.NotFoundError.__init__(node_def, op, message)

Creates a NotFoundError.

---

class tf.errors.AlreadyExistsError

Raised when an entity that we attempted to create already exists.

For example, running an operation that saves a file(e.g. tf.train.Saver.save())could potentially raise this exception if an explicit filename for anexisting file was passed.

---

tf.errors.AlreadyExistsError.__init__(node_def, op, message)

Creates an AlreadyExistsError.

---

class tf.errors.PermissionDeniedError

Raised when the caller does not have permission to run an operation.

For example, running thetf.WholeFileReader.read()operation could raise PermissionDeniedError if it receives the name of afile for which the user does not have the read file permission.

---

tf.errors.PermissionDeniedError.__init__(node_def, op, message)

Creates a PermissionDeniedError.

---

class tf.errors.UnauthenticatedError

The request does not have valid authentication credentials.

This exception is not currently used.

---

tf.errors.UnauthenticatedError.__init__(node_def, op, message)

Creates an UnauthenticatedError.

---

class tf.errors.ResourceExhaustedError

Some resource has been exhausted.

For example, this error might be raised if a per-user quota isexhausted, or perhaps the entire file system is out of space.

---

tf.errors.ResourceExhaustedError.__init__(node_def, op, message)

Creates a ResourceExhaustedError.

---

class tf.errors.FailedPreconditionError

Operation was rejected because the system is not in a state to execute it.

This exception is most commonly raised when running an operationthat reads a tf.Variablebefore it has been initialized.

---

tf.errors.FailedPreconditionError.__init__(node_def, op, message)

Creates a FailedPreconditionError.

---

class tf.errors.AbortedError

The operation was aborted, typically due to a concurrent action.

For example, running aqueue.enqueue()operation may raise AbortedError if aqueue.close() operationpreviously ran.

---

tf.errors.AbortedError.__init__(node_def, op, message)

Creates an AbortedError.

---

class tf.errors.OutOfRangeError

Raised when an operation iterates past the valid input range.

This exception is raised in "end-of-file" conditions, such as when aqueue.dequeue()operation is blocked on an empty queue, and aqueue.close()operation executes.

---

tf.errors.OutOfRangeError.__init__(node_def, op, message)

Creates an OutOfRangeError.

---

class tf.errors.UnimplementedError

Raised when an operation has not been implemented.

Some operations may raise this error when passed otherwise-validarguments that it does not currently support. For example, runningthe tf.nn.max_pool() operationwould raise this error if pooling was requested on the batch dimension,because this is not yet supported.

---

tf.errors.UnimplementedError.__init__(node_def, op, message)

Creates an UnimplementedError.

---

class tf.errors.InternalError

Raised when the system experiences an internal error.

This exception is raised when some invariant expected by the runtimehas been broken. Catching this exception is not recommended.

---

tf.errors.InternalError.__init__(node_def, op, message)

Creates an InternalError.

---

class tf.errors.UnavailableError

Raised when the runtime is currently unavailable.

This exception is not currently used.

---

tf.errors.UnavailableError.__init__(node_def, op, message)

Creates an UnavailableError.

---

class tf.errors.DataLossError

Raised when unrecoverable data loss or corruption is encountered.

For example, this may be raised by running atf.WholeFileReader.read()operation, if the file is truncated while it is being read.

---

tf.errors.DataLossError.__init__(node_def, op, message)

Creates a DataLossError.