diff options
Diffstat (limited to 'tensorflow/g3doc')
94 files changed, 25709 insertions, 0 deletions
diff --git a/tensorflow/g3doc/__init__.py b/tensorflow/g3doc/__init__.py new file mode 100755 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/__init__.py diff --git a/tensorflow/g3doc/api_docs/cc/ClassEnv.md b/tensorflow/g3doc/api_docs/cc/ClassEnv.md new file mode 100644 index 0000000000..0fdb3d32c7 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassEnv.md @@ -0,0 +1,146 @@ +#Class tensorflow::Env + +An interface used by the tensorflow implementation to access operating system functionality like the filesystem etc. + +Callers may wish to provide a custom Env object to get fine grain control. + +All Env implementations are safe for concurrent access from multiple threads without any external synchronization. + +##Member Summary + +* [tensorflow::Env::Env](#tensorflow_Env_Env) +* [virtual tensorflow::Env::~Env](#virtual_tensorflow_Env_Env) +* [virtual Status tensorflow::Env::NewRandomAccessFile](#virtual_Status_tensorflow_Env_NewRandomAccessFile) + * Creates a brand new random access read-only file with the specified name. +* [virtual Status tensorflow::Env::NewWritableFile](#virtual_Status_tensorflow_Env_NewWritableFile) + * Creates an object that writes to a new file with the specified name. +* [virtual Status tensorflow::Env::NewAppendableFile](#virtual_Status_tensorflow_Env_NewAppendableFile) + * Creates an object that either appends to an existing file, or writes to a new file (if the file does not exist to begin with). +* [virtual bool tensorflow::Env::FileExists](#virtual_bool_tensorflow_Env_FileExists) + * Returns true iff the named file exists. +* [virtual Status tensorflow::Env::GetChildren](#virtual_Status_tensorflow_Env_GetChildren) + * Stores in *result the names of the children of the specified directory. The names are relative to "dir". +* [virtual Status tensorflow::Env::DeleteFile](#virtual_Status_tensorflow_Env_DeleteFile) + * Deletes the named file. +* [virtual Status tensorflow::Env::CreateDir](#virtual_Status_tensorflow_Env_CreateDir) + * Creates the specified directory. +* [virtual Status tensorflow::Env::DeleteDir](#virtual_Status_tensorflow_Env_DeleteDir) + * Deletes the specified directory. +* [virtual Status tensorflow::Env::GetFileSize](#virtual_Status_tensorflow_Env_GetFileSize) + * Stores the size of fname in *file_size. +* [virtual Status tensorflow::Env::RenameFile](#virtual_Status_tensorflow_Env_RenameFile) + * Renames file src to target. If target already exists, it will be replaced. +* [virtual uint64 tensorflow::Env::NowMicros](#virtual_uint64_tensorflow_Env_NowMicros) + * Returns the number of micro-seconds since some fixed point in time. Only useful for computing deltas of time. +* [virtual void tensorflow::Env::SleepForMicroseconds](#virtual_void_tensorflow_Env_SleepForMicroseconds) + * Sleeps/delays the thread for the prescribed number of micro-seconds. +* [virtual Thread* tensorflow::Env::StartThread](#virtual_Thread_tensorflow_Env_StartThread) + * Returns a new thread that is running fn() and is identified (for debugging/performance-analysis) by "name". +* [static Env* tensorflow::Env::Default](#static_Env_tensorflow_Env_Default) + * Returns a default environment suitable for the current operating system. + +##Member Details + +#### tensorflow::Env::Env() {#tensorflow_Env_Env} + + + + + +#### virtual tensorflow::Env::~Env() {#virtual_tensorflow_Env_Env} + + + + + +#### virtual Status tensorflow::Env::NewRandomAccessFile(const string &fname, RandomAccessFile **result)=0 {#virtual_Status_tensorflow_Env_NewRandomAccessFile} + +Creates a brand new random access read-only file with the specified name. + +On success, stores a pointer to the new file in *result and returns OK. On failure stores NULL in *result and returns non-OK. If the file does not exist, returns a non-OK status. + +The returned file may be concurrently accessed by multiple threads. + +#### virtual Status tensorflow::Env::NewWritableFile(const string &fname, WritableFile **result)=0 {#virtual_Status_tensorflow_Env_NewWritableFile} + +Creates an object that writes to a new file with the specified name. + +Deletes any existing file with the same name and creates a new file. On success, stores a pointer to the new file in *result and returns OK. On failure stores NULL in *result and returns non-OK. + +The returned file will only be accessed by one thread at a time. + +#### virtual Status tensorflow::Env::NewAppendableFile(const string &fname, WritableFile **result)=0 {#virtual_Status_tensorflow_Env_NewAppendableFile} + +Creates an object that either appends to an existing file, or writes to a new file (if the file does not exist to begin with). + +On success, stores a pointer to the new file in *result and returns OK. On failure stores NULL in *result and returns non-OK. + +The returned file will only be accessed by one thread at a time. + +#### virtual bool tensorflow::Env::FileExists(const string &fname)=0 {#virtual_bool_tensorflow_Env_FileExists} + +Returns true iff the named file exists. + + + +#### virtual Status tensorflow::Env::GetChildren(const string &dir, std::vector< string > *result)=0 {#virtual_Status_tensorflow_Env_GetChildren} + +Stores in *result the names of the children of the specified directory. The names are relative to "dir". + +Original contents of *results are dropped. + +#### virtual Status tensorflow::Env::DeleteFile(const string &fname)=0 {#virtual_Status_tensorflow_Env_DeleteFile} + +Deletes the named file. + + + +#### virtual Status tensorflow::Env::CreateDir(const string &dirname)=0 {#virtual_Status_tensorflow_Env_CreateDir} + +Creates the specified directory. + + + +#### virtual Status tensorflow::Env::DeleteDir(const string &dirname)=0 {#virtual_Status_tensorflow_Env_DeleteDir} + +Deletes the specified directory. + + + +#### virtual Status tensorflow::Env::GetFileSize(const string &fname, uint64 *file_size)=0 {#virtual_Status_tensorflow_Env_GetFileSize} + +Stores the size of fname in *file_size. + + + +#### virtual Status tensorflow::Env::RenameFile(const string &src, const string &target)=0 {#virtual_Status_tensorflow_Env_RenameFile} + +Renames file src to target. If target already exists, it will be replaced. + + + +#### virtual uint64 tensorflow::Env::NowMicros()=0 {#virtual_uint64_tensorflow_Env_NowMicros} + +Returns the number of micro-seconds since some fixed point in time. Only useful for computing deltas of time. + + + +#### virtual void tensorflow::Env::SleepForMicroseconds(int micros)=0 {#virtual_void_tensorflow_Env_SleepForMicroseconds} + +Sleeps/delays the thread for the prescribed number of micro-seconds. + + + +#### virtual Thread* tensorflow::Env::StartThread(const ThreadOptions &thread_options, const string &name, std::function< void()> fn) TF_MUST_USE_RESULT=0 {#virtual_Thread_tensorflow_Env_StartThread} + +Returns a new thread that is running fn() and is identified (for debugging/performance-analysis) by "name". + +Caller takes ownership of the result and must delete it eventually (the deletion will block until fn() stops running). + +#### static Env* tensorflow::Env::Default() {#static_Env_tensorflow_Env_Default} + +Returns a default environment suitable for the current operating system. + +Sophisticated users may wish to provide their own Env implementation instead of relying on this default environment. + +The result of Default() belongs to this library and must never be deleted. diff --git a/tensorflow/g3doc/api_docs/cc/ClassEnvWrapper.md b/tensorflow/g3doc/api_docs/cc/ClassEnvWrapper.md new file mode 100644 index 0000000000..2c6af82113 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassEnvWrapper.md @@ -0,0 +1,143 @@ +#Class tensorflow::EnvWrapper + +An implementation of Env that forwards all calls to another Env . + +May be useful to clients who wish to override just part of the functionality of another Env . + +##Member Summary + +* [tensorflow::EnvWrapper::EnvWrapper](#tensorflow_EnvWrapper_EnvWrapper) + * Initializes an EnvWrapper that delegates all calls to *t. +* [virtual tensorflow::EnvWrapper::~EnvWrapper](#virtual_tensorflow_EnvWrapper_EnvWrapper) +* [Env* tensorflow::EnvWrapper::target](#Env_tensorflow_EnvWrapper_target) + * Returns the target to which this Env forwards all calls. +* [Status tensorflow::EnvWrapper::NewRandomAccessFile](#Status_tensorflow_EnvWrapper_NewRandomAccessFile) + * Creates a brand new random access read-only file with the specified name. +* [Status tensorflow::EnvWrapper::NewWritableFile](#Status_tensorflow_EnvWrapper_NewWritableFile) + * Creates an object that writes to a new file with the specified name. +* [Status tensorflow::EnvWrapper::NewAppendableFile](#Status_tensorflow_EnvWrapper_NewAppendableFile) + * Creates an object that either appends to an existing file, or writes to a new file (if the file does not exist to begin with). +* [bool tensorflow::EnvWrapper::FileExists](#bool_tensorflow_EnvWrapper_FileExists) + * Returns true iff the named file exists. +* [Status tensorflow::EnvWrapper::GetChildren](#Status_tensorflow_EnvWrapper_GetChildren) + * Stores in *result the names of the children of the specified directory. The names are relative to "dir". +* [Status tensorflow::EnvWrapper::DeleteFile](#Status_tensorflow_EnvWrapper_DeleteFile) + * Deletes the named file. +* [Status tensorflow::EnvWrapper::CreateDir](#Status_tensorflow_EnvWrapper_CreateDir) + * Creates the specified directory. +* [Status tensorflow::EnvWrapper::DeleteDir](#Status_tensorflow_EnvWrapper_DeleteDir) + * Deletes the specified directory. +* [Status tensorflow::EnvWrapper::GetFileSize](#Status_tensorflow_EnvWrapper_GetFileSize) + * Stores the size of fname in *file_size. +* [Status tensorflow::EnvWrapper::RenameFile](#Status_tensorflow_EnvWrapper_RenameFile) + * Renames file src to target. If target already exists, it will be replaced. +* [uint64 tensorflow::EnvWrapper::NowMicros](#uint64_tensorflow_EnvWrapper_NowMicros) + * Returns the number of micro-seconds since some fixed point in time. Only useful for computing deltas of time. +* [void tensorflow::EnvWrapper::SleepForMicroseconds](#void_tensorflow_EnvWrapper_SleepForMicroseconds) + * Sleeps/delays the thread for the prescribed number of micro-seconds. +* [Thread* tensorflow::EnvWrapper::StartThread](#Thread_tensorflow_EnvWrapper_StartThread) + * Returns a new thread that is running fn() and is identified (for debugging/performance-analysis) by "name". + +##Member Details + +#### tensorflow::EnvWrapper::EnvWrapper(Env *t) {#tensorflow_EnvWrapper_EnvWrapper} + +Initializes an EnvWrapper that delegates all calls to *t. + + + +#### virtual tensorflow::EnvWrapper::~EnvWrapper() {#virtual_tensorflow_EnvWrapper_EnvWrapper} + + + + + +#### Env* tensorflow::EnvWrapper::target() const {#Env_tensorflow_EnvWrapper_target} + +Returns the target to which this Env forwards all calls. + + + +#### Status tensorflow::EnvWrapper::NewRandomAccessFile(const string &f, RandomAccessFile **r) override {#Status_tensorflow_EnvWrapper_NewRandomAccessFile} + +Creates a brand new random access read-only file with the specified name. + +On success, stores a pointer to the new file in *result and returns OK. On failure stores NULL in *result and returns non-OK. If the file does not exist, returns a non-OK status. + +The returned file may be concurrently accessed by multiple threads. + +#### Status tensorflow::EnvWrapper::NewWritableFile(const string &f, WritableFile **r) override {#Status_tensorflow_EnvWrapper_NewWritableFile} + +Creates an object that writes to a new file with the specified name. + +Deletes any existing file with the same name and creates a new file. On success, stores a pointer to the new file in *result and returns OK. On failure stores NULL in *result and returns non-OK. + +The returned file will only be accessed by one thread at a time. + +#### Status tensorflow::EnvWrapper::NewAppendableFile(const string &f, WritableFile **r) override {#Status_tensorflow_EnvWrapper_NewAppendableFile} + +Creates an object that either appends to an existing file, or writes to a new file (if the file does not exist to begin with). + +On success, stores a pointer to the new file in *result and returns OK. On failure stores NULL in *result and returns non-OK. + +The returned file will only be accessed by one thread at a time. + +#### bool tensorflow::EnvWrapper::FileExists(const string &f) override {#bool_tensorflow_EnvWrapper_FileExists} + +Returns true iff the named file exists. + + + +#### Status tensorflow::EnvWrapper::GetChildren(const string &dir, std::vector< string > *r) override {#Status_tensorflow_EnvWrapper_GetChildren} + +Stores in *result the names of the children of the specified directory. The names are relative to "dir". + +Original contents of *results are dropped. + +#### Status tensorflow::EnvWrapper::DeleteFile(const string &f) override {#Status_tensorflow_EnvWrapper_DeleteFile} + +Deletes the named file. + + + +#### Status tensorflow::EnvWrapper::CreateDir(const string &d) override {#Status_tensorflow_EnvWrapper_CreateDir} + +Creates the specified directory. + + + +#### Status tensorflow::EnvWrapper::DeleteDir(const string &d) override {#Status_tensorflow_EnvWrapper_DeleteDir} + +Deletes the specified directory. + + + +#### Status tensorflow::EnvWrapper::GetFileSize(const string &f, uint64 *s) override {#Status_tensorflow_EnvWrapper_GetFileSize} + +Stores the size of fname in *file_size. + + + +#### Status tensorflow::EnvWrapper::RenameFile(const string &s, const string &t) override {#Status_tensorflow_EnvWrapper_RenameFile} + +Renames file src to target. If target already exists, it will be replaced. + + + +#### uint64 tensorflow::EnvWrapper::NowMicros() override {#uint64_tensorflow_EnvWrapper_NowMicros} + +Returns the number of micro-seconds since some fixed point in time. Only useful for computing deltas of time. + + + +#### void tensorflow::EnvWrapper::SleepForMicroseconds(int micros) override {#void_tensorflow_EnvWrapper_SleepForMicroseconds} + +Sleeps/delays the thread for the prescribed number of micro-seconds. + + + +#### Thread* tensorflow::EnvWrapper::StartThread(const ThreadOptions &thread_options, const string &name, std::function< void()> fn) override {#Thread_tensorflow_EnvWrapper_StartThread} + +Returns a new thread that is running fn() and is identified (for debugging/performance-analysis) by "name". + +Caller takes ownership of the result and must delete it eventually (the deletion will block until fn() stops running). diff --git a/tensorflow/g3doc/api_docs/cc/ClassRandomAccessFile.md b/tensorflow/g3doc/api_docs/cc/ClassRandomAccessFile.md new file mode 100644 index 0000000000..3538c2ca11 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassRandomAccessFile.md @@ -0,0 +1,38 @@ +#Class tensorflow::RandomAccessFile + +A file abstraction for randomly reading the contents of a file. + + + +##Member Summary + +* [tensorflow::RandomAccessFile::RandomAccessFile](#tensorflow_RandomAccessFile_RandomAccessFile) +* [virtual tensorflow::RandomAccessFile::~RandomAccessFile](#virtual_tensorflow_RandomAccessFile_RandomAccessFile) +* [virtual Status tensorflow::RandomAccessFile::Read](#virtual_Status_tensorflow_RandomAccessFile_Read) + * Reads up to "n" bytes from the file starting at "offset". + +##Member Details + +#### tensorflow::RandomAccessFile::RandomAccessFile() {#tensorflow_RandomAccessFile_RandomAccessFile} + + + + + +#### virtual tensorflow::RandomAccessFile::~RandomAccessFile() {#virtual_tensorflow_RandomAccessFile_RandomAccessFile} + + + + + +#### virtual Status tensorflow::RandomAccessFile::Read(uint64 offset, size_t n, StringPiece *result, char *scratch) const =0 {#virtual_Status_tensorflow_RandomAccessFile_Read} + +Reads up to "n" bytes from the file starting at "offset". + +"scratch[0..n-1]" may be written by this routine. Sets "*result" to the data that was read (including if fewer than "n" bytes were successfully read). May set "*result" to point at data in "scratch[0..n-1]", so "scratch[0..n-1]" must be live when "*result" is used. + +On OK returned status: "n" bytes have been stored in "*result". On non-OK returned status: [0..n] bytes have been stored in "*result". + +Returns OUT_OF_RANGE if fewer than n bytes were stored in "*result" because of EOF. + +Safe for concurrent use by multiple threads. diff --git a/tensorflow/g3doc/api_docs/cc/ClassSession.md b/tensorflow/g3doc/api_docs/cc/ClassSession.md new file mode 100644 index 0000000000..f2f9d8f762 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassSession.md @@ -0,0 +1,88 @@ +#Class tensorflow::Session + +A Session instance lets a caller drive a TensorFlow graph computation. + +When a Session is created with a given target, a new Session object is bound to the universe of resources specified by that target. Those resources are available to this session to perform computation described in the GraphDef. After extending the session with a graph, the caller uses the Run() API to perform the computation and potentially fetch outputs as Tensors. + +Example: tensorflow::GraphDef graph; +// ... Create or load graph into 'graph'. + +// This example uses the default options which connects +// to a local runtime. +tensorflow::SessionOptions options; +std::unique_ptr<tensorflow::Session> +session(tensorflow::NewSession(options)); + +// Create the session with this graph. +tensorflow::Status s = session->Create(graph); +if (!s.ok()) { ... } + +// Run the graph and fetch the first output of the "output" +// operation, and also run to but do not return anything +// for the "update_state" operation. +std::vector<tensorflow::Tensor> outputs; +s = session->Run({}, {"output:0"}, {"update_state"}, &outputs); +if (!s.ok()) { ... } + +// Map the output as a flattened float tensor, and do something +// with it. +auto output_tensor = outputs[0].flat<float>(); +if (output_tensor(0) > 0.5) { ... } + +// Close the session to release the resources associated with +// this session. +session->Close() + +A Session allows concurrent calls to Run() , though a Session must be created / extended by a single thread. + +Only one thread must call Close() , and Close() must only be called after all other calls to Run() have returned. + +##Member Summary + +* [virtual Status tensorflow::Session::Create](#virtual_Status_tensorflow_Session_Create) + * Create the graph to be used for the session. +* [virtual Status tensorflow::Session::Extend](#virtual_Status_tensorflow_Session_Extend) + * Adds operations to the graph that is already registered with the Session . +* [virtual Status tensorflow::Session::Run](#virtual_Status_tensorflow_Session_Run) + * Runs the graph with the provided input tensors and fills 'outputs' for the endpoints specified in 'output_tensor_names'. Runs to but does not return Tensors for the nodes in 'target_node_names'. +* [virtual Status tensorflow::Session::Close](#virtual_Status_tensorflow_Session_Close) + * Closes this session. +* [virtual tensorflow::Session::~Session](#virtual_tensorflow_Session_Session) + +##Member Details + +#### virtual Status tensorflow::Session::Create(const GraphDef &graph)=0 {#virtual_Status_tensorflow_Session_Create} + +Create the graph to be used for the session. + +Returns an error if this session has already been created with a graph. To re-use the session with a different graph, the caller must Close() the session first. + +#### virtual Status tensorflow::Session::Extend(const GraphDef &graph)=0 {#virtual_Status_tensorflow_Session_Extend} + +Adds operations to the graph that is already registered with the Session . + +The names of new operations in "graph" must not exist in the graph that is already registered. + +#### virtual Status tensorflow::Session::Run(const std::vector< std::pair< string, Tensor > > &inputs, const std::vector< string > &output_tensor_names, const std::vector< string > &target_node_names, std::vector< Tensor > *outputs)=0 {#virtual_Status_tensorflow_Session_Run} + +Runs the graph with the provided input tensors and fills 'outputs' for the endpoints specified in 'output_tensor_names'. Runs to but does not return Tensors for the nodes in 'target_node_names'. + +The order of tensors in 'outputs' will match the order provided by 'output_tensor_names'. + +If Run returns OK(), then outputs->size() will be equal to output_tensor_names.size(). If Run does not return OK(), the state of outputs is undefined. + +REQUIRES: The name of each Tensor of the input or output must match a "Tensor endpoint" in the GraphDef passed to Create() . + +REQUIRES: outputs is not nullptr if output_tensor_names is non-empty. + +#### virtual Status tensorflow::Session::Close()=0 {#virtual_Status_tensorflow_Session_Close} + +Closes this session. + +Closing a session releases the resources used by this session on the TensorFlow runtime (specified during session creation by the ' SessionOptions::target ' field). + +#### virtual tensorflow::Session::~Session() {#virtual_tensorflow_Session_Session} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/ClassStatus.md b/tensorflow/g3doc/api_docs/cc/ClassStatus.md new file mode 100644 index 0000000000..d5ef48b14d --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassStatus.md @@ -0,0 +1,107 @@ +#Class tensorflow::Status + + + + + +##Member Summary + +* [tensorflow::Status::Status](#tensorflow_Status_Status) + * Create a success status. +* [tensorflow::Status::~Status](#tensorflow_Status_Status) +* [tensorflow::Status::Status](#tensorflow_Status_Status) + * Create a status with the specified error code and msg as a human-readable string containing more detailed information. +* [tensorflow::Status::Status](#tensorflow_Status_Status) + * Copy the specified status. +* [void tensorflow::Status::operator=](#void_tensorflow_Status_operator_) +* [bool tensorflow::Status::ok](#bool_tensorflow_Status_ok) + * Returns true iff the status indicates success. +* [tensorflow::error::Code tensorflow::Status::code](#tensorflow_error_Code_tensorflow_Status_code) +* [const string& tensorflow::Status::error_message](#const_string_amp_tensorflow_Status_error_message) +* [bool tensorflow::Status::operator==](#bool_tensorflow_Status_operator_) +* [bool tensorflow::Status::operator!=](#bool_tensorflow_Status_operator_) +* [void tensorflow::Status::Update](#void_tensorflow_Status_Update) + * If "ok()", stores "new_status" into *this. If "!ok()", preserves the current status, but may augment with additional information about "new_status". +* [string tensorflow::Status::ToString](#string_tensorflow_Status_ToString) + * Return a string representation of this status suitable for printing. Returns the string "OK" for success. +* [static Status tensorflow::Status::OK](#static_Status_tensorflow_Status_OK) + +##Member Details + +#### tensorflow::Status::Status() {#tensorflow_Status_Status} + +Create a success status. + + + +#### tensorflow::Status::~Status() {#tensorflow_Status_Status} + + + + + +#### tensorflow::Status::Status(tensorflow::error::Code code, tensorflow::StringPiece msg) {#tensorflow_Status_Status} + +Create a status with the specified error code and msg as a human-readable string containing more detailed information. + + + +#### tensorflow::Status::Status(const Status &s) {#tensorflow_Status_Status} + +Copy the specified status. + + + +#### void tensorflow::Status::operator=(const Status &s) {#void_tensorflow_Status_operator_} + + + + + +#### bool tensorflow::Status::ok() const {#bool_tensorflow_Status_ok} + +Returns true iff the status indicates success. + + + +#### tensorflow::error::Code tensorflow::Status::code() const {#tensorflow_error_Code_tensorflow_Status_code} + + + + + +#### const string& tensorflow::Status::error_message() const {#const_string_amp_tensorflow_Status_error_message} + + + + + +#### bool tensorflow::Status::operator==(const Status &x) const {#bool_tensorflow_Status_operator_} + + + + + +#### bool tensorflow::Status::operator!=(const Status &x) const {#bool_tensorflow_Status_operator_} + + + + + +#### void tensorflow::Status::Update(const Status &new_status) {#void_tensorflow_Status_Update} + +If "ok()", stores "new_status" into *this. If "!ok()", preserves the current status, but may augment with additional information about "new_status". + +Convenient way of keeping track of the first error encountered. Instead of: if (overall_status.ok()) overall_status = new_status Use: overall_status.Update(new_status); + +#### string tensorflow::Status::ToString() const {#string_tensorflow_Status_ToString} + +Return a string representation of this status suitable for printing. Returns the string "OK" for success. + + + +#### static Status tensorflow::Status::OK() {#static_Status_tensorflow_Status_OK} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/ClassTensor.md b/tensorflow/g3doc/api_docs/cc/ClassTensor.md new file mode 100644 index 0000000000..7ecc7688f3 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassTensor.md @@ -0,0 +1,361 @@ +#Class tensorflow::Tensor + +Represents an n-dimensional array of values. + + + +##Member Summary + +* [tensorflow::Tensor::Tensor](#tensorflow_Tensor_Tensor) + * Default Tensor constructor. Creates a 1-dimension, 0-element float tensor. +* [tensorflow::Tensor::Tensor](#tensorflow_Tensor_Tensor) + * Creates a Tensor of the given datatype and shape. +* [tensorflow::Tensor::Tensor](#tensorflow_Tensor_Tensor) + * Creates a tensor with the input datatype and shape, using the allocator 'a' to allocate the underlying buffer. +* [tensorflow::Tensor::Tensor](#tensorflow_Tensor_Tensor) + * Creates an uninitialized Tensor of the given data type. +* [tensorflow::Tensor::Tensor](#tensorflow_Tensor_Tensor) +* [tensorflow::Tensor::~Tensor](#tensorflow_Tensor_Tensor) + * Copy constructor. +* [DataType tensorflow::Tensor::dtype](#DataType_tensorflow_Tensor_dtype) + * Returns the data type. +* [const TensorShape& tensorflow::Tensor::shape](#const_TensorShape_amp_tensorflow_Tensor_shape) + * Returns the shape of the tensor. +* [int tensorflow::Tensor::dims](#int_tensorflow_Tensor_dims) + * Convenience accessor for the tensor shape. +* [int64 tensorflow::Tensor::dim_size](#int64_tensorflow_Tensor_dim_size) + * Convenience accessor for the tensor shape. +* [int64 tensorflow::Tensor::NumElements](#int64_tensorflow_Tensor_NumElements) + * Convenience accessor for the tensor shape. +* [bool tensorflow::Tensor::IsSameSize](#bool_tensorflow_Tensor_IsSameSize) +* [bool tensorflow::Tensor::IsInitialized](#bool_tensorflow_Tensor_IsInitialized) + * Has this Tensor been initialized? +* [size_t tensorflow::Tensor::TotalBytes](#size_t_tensorflow_Tensor_TotalBytes) + * Returns the estimated memory usage of this tensor. +* [Tensor& tensorflow::Tensor::operator=](#Tensor_amp_tensorflow_Tensor_operator_) + * Assign operator. This tensor shares other's underlying storage. +* [bool tensorflow::Tensor::CopyFrom](#bool_tensorflow_Tensor_CopyFrom) + * Copy the other tensor into this tensor and reshape it. +* [Tensor tensorflow::Tensor::Slice](#Tensor_tensorflow_Tensor_Slice) + * Slice this tensor along the 1st dimension. +* [bool tensorflow::Tensor::FromProto](#bool_tensorflow_Tensor_FromProto) + * Parse "other' and construct the tensor. +* [bool tensorflow::Tensor::FromProto](#bool_tensorflow_Tensor_FromProto) +* [void tensorflow::Tensor::AsProtoField](#void_tensorflow_Tensor_AsProtoField) + * Fills in "proto" with "*this" tensor's content. +* [void tensorflow::Tensor::AsProtoTensorContent](#void_tensorflow_Tensor_AsProtoTensorContent) +* [TTypes<T>::Vec tensorflow::Tensor::vec](#TTypes_lt_T_gt_Vec_tensorflow_Tensor_vec) + * Return the Tensor data as an Eigen::Tensor with the type and sizes of this Tensor . +* [TTypes<T>::Matrix tensorflow::Tensor::matrix](#TTypes_lt_T_gt_Matrix_tensorflow_Tensor_matrix) +* [TTypes< T, NDIMS >::Tensor tensorflow::Tensor::tensor](#TTypes_lt_T_NDIMS_gt_Tensor_tensorflow_Tensor_tensor) +* [TTypes<T>::Flat tensorflow::Tensor::flat](#TTypes_lt_T_gt_Flat_tensorflow_Tensor_flat) + * Return the Tensor data as an Eigen::Tensor of the data type and a specified shape. +* [TTypes<T>::UnalignedFlat tensorflow::Tensor::unaligned_flat](#TTypes_lt_T_gt_UnalignedFlat_tensorflow_Tensor_unaligned_flat) +* [TTypes<T>::Matrix tensorflow::Tensor::flat_inner_dims](#TTypes_lt_T_gt_Matrix_tensorflow_Tensor_flat_inner_dims) +* [TTypes<T>::Matrix tensorflow::Tensor::flat_outer_dims](#TTypes_lt_T_gt_Matrix_tensorflow_Tensor_flat_outer_dims) +* [TTypes< T, NDIMS >::Tensor tensorflow::Tensor::shaped](#TTypes_lt_T_NDIMS_gt_Tensor_tensorflow_Tensor_shaped) +* [TTypes< T, NDIMS >::UnalignedTensor tensorflow::Tensor::unaligned_shaped](#TTypes_lt_T_NDIMS_gt_UnalignedTensor_tensorflow_Tensor_unaligned_shaped) +* [TTypes< T >::Scalar tensorflow::Tensor::scalar](#TTypes_lt_T_gt_Scalar_tensorflow_Tensor_scalar) + * Return the Tensor data as a Tensor Map of fixed size 1: TensorMap<TensorFixedSize<T, 1>>. +* [TTypes<T>::ConstVec tensorflow::Tensor::vec](#TTypes_lt_T_gt_ConstVec_tensorflow_Tensor_vec) + * Const versions of all the methods above. +* [TTypes<T>::ConstMatrix tensorflow::Tensor::matrix](#TTypes_lt_T_gt_ConstMatrix_tensorflow_Tensor_matrix) +* [TTypes< T, NDIMS >::ConstTensor tensorflow::Tensor::tensor](#TTypes_lt_T_NDIMS_gt_ConstTensor_tensorflow_Tensor_tensor) +* [TTypes<T>::ConstFlat tensorflow::Tensor::flat](#TTypes_lt_T_gt_ConstFlat_tensorflow_Tensor_flat) +* [TTypes<T>::ConstUnalignedFlat tensorflow::Tensor::unaligned_flat](#TTypes_lt_T_gt_ConstUnalignedFlat_tensorflow_Tensor_unaligned_flat) +* [TTypes<T>::ConstMatrix tensorflow::Tensor::flat_inner_dims](#TTypes_lt_T_gt_ConstMatrix_tensorflow_Tensor_flat_inner_dims) +* [TTypes<T>::ConstMatrix tensorflow::Tensor::flat_outer_dims](#TTypes_lt_T_gt_ConstMatrix_tensorflow_Tensor_flat_outer_dims) +* [TTypes< T, NDIMS >::ConstTensor tensorflow::Tensor::shaped](#TTypes_lt_T_NDIMS_gt_ConstTensor_tensorflow_Tensor_shaped) +* [TTypes< T, NDIMS >::ConstUnalignedTensor tensorflow::Tensor::unaligned_shaped](#TTypes_lt_T_NDIMS_gt_ConstUnalignedTensor_tensorflow_Tensor_unaligned_shaped) +* [TTypes< T >::ConstScalar tensorflow::Tensor::scalar](#TTypes_lt_T_gt_ConstScalar_tensorflow_Tensor_scalar) +* [string tensorflow::Tensor::SummarizeValue](#string_tensorflow_Tensor_SummarizeValue) + * Render the first max_entries values in *this into a string. +* [string tensorflow::Tensor::DebugString](#string_tensorflow_Tensor_DebugString) + * A human-readable summary of the Tensor suitable for debugging. +* [void tensorflow::Tensor::FillDescription](#void_tensorflow_Tensor_FillDescription) +* [StringPiece tensorflow::Tensor::tensor_data](#StringPiece_tensorflow_Tensor_tensor_data) + * Returns a StringPiece mapping the current tensor's buffer. + +##Member Details + +#### tensorflow::Tensor::Tensor() {#tensorflow_Tensor_Tensor} + +Default Tensor constructor. Creates a 1-dimension, 0-element float tensor. + + + +#### tensorflow::Tensor::Tensor(DataType type, const TensorShape &shape) {#tensorflow_Tensor_Tensor} + +Creates a Tensor of the given datatype and shape. + +The underlying buffer is allocated using a CPUAllocator. + +#### tensorflow::Tensor::Tensor(Allocator *a, DataType type, const TensorShape &shape) {#tensorflow_Tensor_Tensor} + +Creates a tensor with the input datatype and shape, using the allocator 'a' to allocate the underlying buffer. + +'a' must outlive the lifetime of this Tensor . + +#### tensorflow::Tensor::Tensor(DataType type) {#tensorflow_Tensor_Tensor} + +Creates an uninitialized Tensor of the given data type. + + + +#### tensorflow::Tensor::Tensor(const Tensor &other) {#tensorflow_Tensor_Tensor} + + + + + +#### tensorflow::Tensor::~Tensor() {#tensorflow_Tensor_Tensor} + +Copy constructor. + + + +#### DataType tensorflow::Tensor::dtype() const {#DataType_tensorflow_Tensor_dtype} + +Returns the data type. + + + +#### const TensorShape& tensorflow::Tensor::shape() const {#const_TensorShape_amp_tensorflow_Tensor_shape} + +Returns the shape of the tensor. + + + +#### int tensorflow::Tensor::dims() const {#int_tensorflow_Tensor_dims} + +Convenience accessor for the tensor shape. + +For all shape accessors, see comments for relevant methods of TensorShape in tensor_shape.h . + +#### int64 tensorflow::Tensor::dim_size(int d) const {#int64_tensorflow_Tensor_dim_size} + +Convenience accessor for the tensor shape. + + + +#### int64 tensorflow::Tensor::NumElements() const {#int64_tensorflow_Tensor_NumElements} + +Convenience accessor for the tensor shape. + + + +#### bool tensorflow::Tensor::IsSameSize(const Tensor &b) const {#bool_tensorflow_Tensor_IsSameSize} + + + + + +#### bool tensorflow::Tensor::IsInitialized() const {#bool_tensorflow_Tensor_IsInitialized} + +Has this Tensor been initialized? + + + +#### size_t tensorflow::Tensor::TotalBytes() const {#size_t_tensorflow_Tensor_TotalBytes} + +Returns the estimated memory usage of this tensor. + + + +#### Tensor& tensorflow::Tensor::operator=(const Tensor &other) {#Tensor_amp_tensorflow_Tensor_operator_} + +Assign operator. This tensor shares other's underlying storage. + + + +#### bool tensorflow::Tensor::CopyFrom(const Tensor &other, const TensorShape &shape) TF_MUST_USE_RESULT {#bool_tensorflow_Tensor_CopyFrom} + +Copy the other tensor into this tensor and reshape it. + +This tensor shares other's underlying storage. Returns true iff other.shape() has the same number of elements of the given "shape". + +#### Tensor tensorflow::Tensor::Slice(int64 dim0_start, int64 dim0_limit) const {#Tensor_tensorflow_Tensor_Slice} + +Slice this tensor along the 1st dimension. + +I.e., the returned tensor satisifies returned[i, ...] == this[dim0_start + i, ...]. The returned tensor shares the underlying tensor buffer with this tensor. + +NOTE: The returned tensor may not satisfies the same alignment requirement as this tensor depending on the shape. The caller must check the returned tensor's alignment before calling certain methods that have alignment requirement (e.g., flat() , tensor()). + +REQUIRES: dims() >= 1 REQUIRES: 0 <= dim0_start <= dim0_limit <= dim_size(0) + +#### bool tensorflow::Tensor::FromProto(const TensorProto &other) TF_MUST_USE_RESULT {#bool_tensorflow_Tensor_FromProto} + +Parse "other' and construct the tensor. + +Returns true iff the parsing succeeds. If the parsing fails, the state of "*this" is unchanged. + +#### bool tensorflow::Tensor::FromProto(Allocator *a, const TensorProto &other) TF_MUST_USE_RESULT {#bool_tensorflow_Tensor_FromProto} + + + + + +#### void tensorflow::Tensor::AsProtoField(TensorProto *proto) const {#void_tensorflow_Tensor_AsProtoField} + +Fills in "proto" with "*this" tensor's content. + +AsProtoField() fills in the repeated field for proto.dtype(), while AsProtoTensorContent() encodes the content in proto.tensor_content() in a compact form. + +#### void tensorflow::Tensor::AsProtoTensorContent(TensorProto *proto) const {#void_tensorflow_Tensor_AsProtoTensorContent} + + + + + +#### TTypes<T>::Vec tensorflow::Tensor::vec() {#TTypes_lt_T_gt_Vec_tensorflow_Tensor_vec} + +Return the Tensor data as an Eigen::Tensor with the type and sizes of this Tensor . + +Use these methods when you know the data type and the number of dimensions of the Tensor and you want an Eigen::Tensor automatically sized to the Tensor sizes. The implementation check fails if either type or sizes mismatch. + +Example: typedef float T; Tensor my_mat(...built with Shape{rows: 3, cols: 5}...); auto mat = my_mat.matrix<T>(); // 2D Eigen::Tensor, 3 x 5. auto mat = my_mat.tensor<T, 2>(); // 2D Eigen::Tensor, 3 x 5. auto vec = my_mat.vec<T>(); // CHECK fails as my_mat is 2D. auto vec = my_mat.tensor<T, 3>(); // CHECK fails as my_mat is 2D. auto mat = my_mat.matrix<int32>();// CHECK fails as type mismatch. + +#### TTypes<T>::Matrix tensorflow::Tensor::matrix() {#TTypes_lt_T_gt_Matrix_tensorflow_Tensor_matrix} + + + + + +#### TTypes< T, NDIMS >::Tensor tensorflow::Tensor::tensor() {#TTypes_lt_T_NDIMS_gt_Tensor_tensorflow_Tensor_tensor} + + + + + +#### TTypes<T>::Flat tensorflow::Tensor::flat() {#TTypes_lt_T_gt_Flat_tensorflow_Tensor_flat} + +Return the Tensor data as an Eigen::Tensor of the data type and a specified shape. + +These methods allow you to access the data with the dimensions and sizes of your choice. You do not need to know the number of dimensions of the Tensor to call them. However, they CHECK that the type matches and the dimensions requested creates an Eigen::Tensor with the same number of elements as the Tensor . + +Example: typedef float T; Tensor my_ten(...built with Shape{planes: 4, rows: 3, cols: 5}...); // 1D Eigen::Tensor, size 60: auto flat = my_ten.flat<T>(); // 2D Eigen::Tensor 12 x 5: auto inner = my_ten.flat_inner_dims<T>(); // 2D Eigen::Tensor 4 x 15: auto outer = my_ten.shaped<T, 2>({4, 15}); // CHECK fails, bad num elements: auto outer = my_ten.shaped<T, 2>({4, 8}); // 3D Eigen::Tensor 6 x 5 x 2: auto weird = my_ten.shaped<T, 3>({6, 5, 2}); // CHECK fails, type mismatch: auto bad = my_ten.flat<int32>(); + +#### TTypes<T>::UnalignedFlat tensorflow::Tensor::unaligned_flat() {#TTypes_lt_T_gt_UnalignedFlat_tensorflow_Tensor_unaligned_flat} + + + + + +#### TTypes<T>::Matrix tensorflow::Tensor::flat_inner_dims() {#TTypes_lt_T_gt_Matrix_tensorflow_Tensor_flat_inner_dims} + + + +Returns the data as an Eigen::Tensor with 2 dimensions, collapsing all Tensor dimensions but the last one into the first dimension of the result. + +#### TTypes<T>::Matrix tensorflow::Tensor::flat_outer_dims() {#TTypes_lt_T_gt_Matrix_tensorflow_Tensor_flat_outer_dims} + + + +Returns the data as an Eigen::Tensor with 2 dimensions, collapsing all Tensor dimensions but the first one into the last dimension of the result. + +#### TTypes< T, NDIMS >::Tensor tensorflow::Tensor::shaped(gtl::ArraySlice< int64 > new_sizes) {#TTypes_lt_T_NDIMS_gt_Tensor_tensorflow_Tensor_shaped} + + + + + +#### TTypes< T, NDIMS >::UnalignedTensor tensorflow::Tensor::unaligned_shaped(gtl::ArraySlice< int64 > new_sizes) {#TTypes_lt_T_NDIMS_gt_UnalignedTensor_tensorflow_Tensor_unaligned_shaped} + + + + + +#### TTypes< T >::Scalar tensorflow::Tensor::scalar() {#TTypes_lt_T_gt_Scalar_tensorflow_Tensor_scalar} + +Return the Tensor data as a Tensor Map of fixed size 1: TensorMap<TensorFixedSize<T, 1>>. + +Using scalar() allows the compiler to perform optimizations as the size of the tensor is known at compile time. + +#### TTypes<T>::ConstVec tensorflow::Tensor::vec() const {#TTypes_lt_T_gt_ConstVec_tensorflow_Tensor_vec} + +Const versions of all the methods above. + + + +#### TTypes<T>::ConstMatrix tensorflow::Tensor::matrix() const {#TTypes_lt_T_gt_ConstMatrix_tensorflow_Tensor_matrix} + + + + + +#### TTypes< T, NDIMS >::ConstTensor tensorflow::Tensor::tensor() const {#TTypes_lt_T_NDIMS_gt_ConstTensor_tensorflow_Tensor_tensor} + + + + + +#### TTypes<T>::ConstFlat tensorflow::Tensor::flat() const {#TTypes_lt_T_gt_ConstFlat_tensorflow_Tensor_flat} + + + + + +#### TTypes<T>::ConstUnalignedFlat tensorflow::Tensor::unaligned_flat() const {#TTypes_lt_T_gt_ConstUnalignedFlat_tensorflow_Tensor_unaligned_flat} + + + + + +#### TTypes<T>::ConstMatrix tensorflow::Tensor::flat_inner_dims() const {#TTypes_lt_T_gt_ConstMatrix_tensorflow_Tensor_flat_inner_dims} + + + + + +#### TTypes<T>::ConstMatrix tensorflow::Tensor::flat_outer_dims() const {#TTypes_lt_T_gt_ConstMatrix_tensorflow_Tensor_flat_outer_dims} + + + + + +#### TTypes< T, NDIMS >::ConstTensor tensorflow::Tensor::shaped(gtl::ArraySlice< int64 > new_sizes) const {#TTypes_lt_T_NDIMS_gt_ConstTensor_tensorflow_Tensor_shaped} + + + + + +#### TTypes< T, NDIMS >::ConstUnalignedTensor tensorflow::Tensor::unaligned_shaped(gtl::ArraySlice< int64 > new_sizes) const {#TTypes_lt_T_NDIMS_gt_ConstUnalignedTensor_tensorflow_Tensor_unaligned_shaped} + + + + + +#### TTypes< T >::ConstScalar tensorflow::Tensor::scalar() const {#TTypes_lt_T_gt_ConstScalar_tensorflow_Tensor_scalar} + + + + + +#### string tensorflow::Tensor::SummarizeValue(int64 max_entries) const {#string_tensorflow_Tensor_SummarizeValue} + +Render the first max_entries values in *this into a string. + + + +#### string tensorflow::Tensor::DebugString() const {#string_tensorflow_Tensor_DebugString} + +A human-readable summary of the Tensor suitable for debugging. + + + +#### void tensorflow::Tensor::FillDescription(TensorDescription *description) const {#void_tensorflow_Tensor_FillDescription} + + + +Fill in the TensorDescription proto with metadata about the Tensor that is useful for monitoring and debugging. + +#### StringPiece tensorflow::Tensor::tensor_data() const {#StringPiece_tensorflow_Tensor_tensor_data} + +Returns a StringPiece mapping the current tensor's buffer. + +The returned StringPiece may point to memory location on devices that the CPU cannot address directly. + +NOTE: The underlying Tensor buffer is refcounted, so the lifetime of the contents mapped by the StringPiece matches the lifetime of the buffer; callers should arrange to make sure the buffer does not get destroyed while the StringPiece is still used. + +REQUIRES: DataTypeCanUseMemcpy( dtype() ). diff --git a/tensorflow/g3doc/api_docs/cc/ClassTensorBuffer.md b/tensorflow/g3doc/api_docs/cc/ClassTensorBuffer.md new file mode 100644 index 0000000000..9f2c6a23be --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassTensorBuffer.md @@ -0,0 +1,52 @@ +#Class tensorflow::TensorBuffer + + + + + +##Member Summary + +* [tensorflow::TensorBuffer::~TensorBuffer](#tensorflow_TensorBuffer_TensorBuffer) +* [virtual void* tensorflow::TensorBuffer::data](#virtual_void_tensorflow_TensorBuffer_data) +* [virtual size_t tensorflow::TensorBuffer::size](#virtual_size_t_tensorflow_TensorBuffer_size) +* [virtual TensorBuffer* tensorflow::TensorBuffer::root_buffer](#virtual_TensorBuffer_tensorflow_TensorBuffer_root_buffer) +* [virtual void tensorflow::TensorBuffer::FillAllocationDescription](#virtual_void_tensorflow_TensorBuffer_FillAllocationDescription) +* [T* tensorflow::TensorBuffer::base](#T_tensorflow_TensorBuffer_base) + +##Member Details + +#### tensorflow::TensorBuffer::~TensorBuffer() override {#tensorflow_TensorBuffer_TensorBuffer} + + + + + +#### virtual void* tensorflow::TensorBuffer::data() const =0 {#virtual_void_tensorflow_TensorBuffer_data} + + + + + +#### virtual size_t tensorflow::TensorBuffer::size() const =0 {#virtual_size_t_tensorflow_TensorBuffer_size} + + + + + +#### virtual TensorBuffer* tensorflow::TensorBuffer::root_buffer()=0 {#virtual_TensorBuffer_tensorflow_TensorBuffer_root_buffer} + + + + + +#### virtual void tensorflow::TensorBuffer::FillAllocationDescription(AllocationDescription *proto) const =0 {#virtual_void_tensorflow_TensorBuffer_FillAllocationDescription} + + + + + +#### T* tensorflow::TensorBuffer::base() const {#T_tensorflow_TensorBuffer_base} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/ClassTensorShape.md b/tensorflow/g3doc/api_docs/cc/ClassTensorShape.md new file mode 100644 index 0000000000..47a105a76e --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassTensorShape.md @@ -0,0 +1,196 @@ +#Class tensorflow::TensorShape + +Manages the dimensions of a Tensor and their sizes. + + + +##Member Summary + +* [tensorflow::TensorShape::TensorShape](#tensorflow_TensorShape_TensorShape) + * Construct a TensorShape from the provided sizes.. REQUIRES: dim_sizes[i] >= 0. +* [tensorflow::TensorShape::TensorShape](#tensorflow_TensorShape_TensorShape) +* [tensorflow::TensorShape::TensorShape](#tensorflow_TensorShape_TensorShape) + * REQUIRES: IsValid(proto) +* [tensorflow::TensorShape::TensorShape](#tensorflow_TensorShape_TensorShape) +* [void tensorflow::TensorShape::Clear](#void_tensorflow_TensorShape_Clear) + * Clear a tensor shape. +* [void tensorflow::TensorShape::AddDim](#void_tensorflow_TensorShape_AddDim) + * Add a dimension to the end ("inner-most"). REQUIRES: size >= 0. +* [void tensorflow::TensorShape::AppendShape](#void_tensorflow_TensorShape_AppendShape) + * Appends all the dimensions from shape. +* [void tensorflow::TensorShape::InsertDim](#void_tensorflow_TensorShape_InsertDim) + * Insert a dimension somewhere in the TensorShape . REQUIRES: "0 <= d <= dims()" REQUIRES: size >= 0. +* [void tensorflow::TensorShape::set_dim](#void_tensorflow_TensorShape_set_dim) + * Modifies the size of the dimension 'd' to be 'size' REQUIRES: "0 <= d < dims()" REQUIRES: size >= 0. +* [void tensorflow::TensorShape::RemoveDim](#void_tensorflow_TensorShape_RemoveDim) + * Removes dimension 'd' from the TensorShape . REQUIRES: "0 <= d < dims()". +* [int tensorflow::TensorShape::dims](#int_tensorflow_TensorShape_dims) + * Return the number of dimensions in the tensor. +* [int64 tensorflow::TensorShape::dim_size](#int64_tensorflow_TensorShape_dim_size) + * Returns the number of elements in dimension "d". REQUIRES: "0 <= d < dims()". +* [gtl::ArraySlice<int64> tensorflow::TensorShape::dim_sizes](#gtl_ArraySlice_lt_int64_gt_tensorflow_TensorShape_dim_sizes) + * Returns sizes of all dimensions. +* [int64 tensorflow::TensorShape::num_elements](#int64_tensorflow_TensorShape_num_elements) + * Returns the number of elements in the tensor. +* [bool tensorflow::TensorShape::IsSameSize](#bool_tensorflow_TensorShape_IsSameSize) + * Returns true if *this and b have the same sizes. Ignores dimension names. +* [bool tensorflow::TensorShape::operator==](#bool_tensorflow_TensorShape_operator_) +* [void tensorflow::TensorShape::AsProto](#void_tensorflow_TensorShape_AsProto) + * Fill *proto from *this. +* [Eigen::DSizes< Eigen::DenseIndex, NDIMS > tensorflow::TensorShape::AsEigenDSizes](#Eigen_DSizes_lt_Eigen_DenseIndex_NDIMS_gt_tensorflow_TensorShape_AsEigenDSizes) + * Fill *dsizes from *this. +* [Eigen::DSizes< Eigen::DenseIndex, NDIMS > tensorflow::TensorShape::AsEigenDSizesWithPadding](#Eigen_DSizes_lt_Eigen_DenseIndex_NDIMS_gt_tensorflow_TensorShape_AsEigenDSizesWithPadding) +* [TensorShapeIter tensorflow::TensorShape::begin](#TensorShapeIter_tensorflow_TensorShape_begin) + * For iterating through the dimensions. +* [TensorShapeIter tensorflow::TensorShape::end](#TensorShapeIter_tensorflow_TensorShape_end) +* [string tensorflow::TensorShape::DebugString](#string_tensorflow_TensorShape_DebugString) + * For error messages. +* [string tensorflow::TensorShape::ShortDebugString](#string_tensorflow_TensorShape_ShortDebugString) +* [static bool tensorflow::TensorShape::IsValid](#static_bool_tensorflow_TensorShape_IsValid) + * Returns true iff "proto" is a valid tensor shape. + +##Member Details + +#### tensorflow::TensorShape::TensorShape(gtl::ArraySlice< int64 > dim_sizes) {#tensorflow_TensorShape_TensorShape} + +Construct a TensorShape from the provided sizes.. REQUIRES: dim_sizes[i] >= 0. + + + +#### tensorflow::TensorShape::TensorShape(std::initializer_list< int64 > dim_sizes) {#tensorflow_TensorShape_TensorShape} + + + + + +#### tensorflow::TensorShape::TensorShape(const TensorShapeProto &proto) {#tensorflow_TensorShape_TensorShape} + +REQUIRES: IsValid(proto) + + + +#### tensorflow::TensorShape::TensorShape() {#tensorflow_TensorShape_TensorShape} + + + +Create a tensor shape with no dimensions and one element, which you can then call AddDim() on. + +#### void tensorflow::TensorShape::Clear() {#void_tensorflow_TensorShape_Clear} + +Clear a tensor shape. + + + +#### void tensorflow::TensorShape::AddDim(int64 size) {#void_tensorflow_TensorShape_AddDim} + +Add a dimension to the end ("inner-most"). REQUIRES: size >= 0. + + + +#### void tensorflow::TensorShape::AppendShape(const TensorShape &shape) {#void_tensorflow_TensorShape_AppendShape} + +Appends all the dimensions from shape. + + + +#### void tensorflow::TensorShape::InsertDim(int d, int64 size) {#void_tensorflow_TensorShape_InsertDim} + +Insert a dimension somewhere in the TensorShape . REQUIRES: "0 <= d <= dims()" REQUIRES: size >= 0. + + + +#### void tensorflow::TensorShape::set_dim(int d, int64 size) {#void_tensorflow_TensorShape_set_dim} + +Modifies the size of the dimension 'd' to be 'size' REQUIRES: "0 <= d < dims()" REQUIRES: size >= 0. + + + +#### void tensorflow::TensorShape::RemoveDim(int d) {#void_tensorflow_TensorShape_RemoveDim} + +Removes dimension 'd' from the TensorShape . REQUIRES: "0 <= d < dims()". + + + +#### int tensorflow::TensorShape::dims() const {#int_tensorflow_TensorShape_dims} + +Return the number of dimensions in the tensor. + + + +#### int64 tensorflow::TensorShape::dim_size(int d) const {#int64_tensorflow_TensorShape_dim_size} + +Returns the number of elements in dimension "d". REQUIRES: "0 <= d < dims()". + + + +#### gtl::ArraySlice<int64> tensorflow::TensorShape::dim_sizes() const {#gtl_ArraySlice_lt_int64_gt_tensorflow_TensorShape_dim_sizes} + +Returns sizes of all dimensions. + + + +#### int64 tensorflow::TensorShape::num_elements() const {#int64_tensorflow_TensorShape_num_elements} + +Returns the number of elements in the tensor. + +We use int64 and not size_t to be compatible with Eigen::Tensor which uses ptr_fi + +#### bool tensorflow::TensorShape::IsSameSize(const TensorShape &b) const {#bool_tensorflow_TensorShape_IsSameSize} + +Returns true if *this and b have the same sizes. Ignores dimension names. + + + +#### bool tensorflow::TensorShape::operator==(const TensorShape &b) const {#bool_tensorflow_TensorShape_operator_} + + + + + +#### void tensorflow::TensorShape::AsProto(TensorShapeProto *proto) const {#void_tensorflow_TensorShape_AsProto} + +Fill *proto from *this. + + + +#### Eigen::DSizes< Eigen::DenseIndex, NDIMS > tensorflow::TensorShape::AsEigenDSizes() const {#Eigen_DSizes_lt_Eigen_DenseIndex_NDIMS_gt_tensorflow_TensorShape_AsEigenDSizes} + +Fill *dsizes from *this. + + + +#### Eigen::DSizes< Eigen::DenseIndex, NDIMS > tensorflow::TensorShape::AsEigenDSizesWithPadding() const {#Eigen_DSizes_lt_Eigen_DenseIndex_NDIMS_gt_tensorflow_TensorShape_AsEigenDSizesWithPadding} + + + +Same as AsEigenDSizes() but allows for NDIMS > dims() in which case we pad the rest of the sizes with 1. + +#### TensorShapeIter tensorflow::TensorShape::begin() const {#TensorShapeIter_tensorflow_TensorShape_begin} + +For iterating through the dimensions. + + + +#### TensorShapeIter tensorflow::TensorShape::end() const {#TensorShapeIter_tensorflow_TensorShape_end} + + + + + +#### string tensorflow::TensorShape::DebugString() const {#string_tensorflow_TensorShape_DebugString} + +For error messages. + + + +#### string tensorflow::TensorShape::ShortDebugString() const {#string_tensorflow_TensorShape_ShortDebugString} + + + + + +#### static bool tensorflow::TensorShape::IsValid(const TensorShapeProto &proto) {#static_bool_tensorflow_TensorShape_IsValid} + +Returns true iff "proto" is a valid tensor shape. + + diff --git a/tensorflow/g3doc/api_docs/cc/ClassTensorShapeIter.md b/tensorflow/g3doc/api_docs/cc/ClassTensorShapeIter.md new file mode 100644 index 0000000000..2f198168a2 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassTensorShapeIter.md @@ -0,0 +1,45 @@ +#Class tensorflow::TensorShapeIter + + + + + +##Member Summary + +* [tensorflow::TensorShapeIter::TensorShapeIter](#tensorflow_TensorShapeIter_TensorShapeIter) +* [bool tensorflow::TensorShapeIter::operator==](#bool_tensorflow_TensorShapeIter_operator_) +* [bool tensorflow::TensorShapeIter::operator!=](#bool_tensorflow_TensorShapeIter_operator_) +* [void tensorflow::TensorShapeIter::operator++](#void_tensorflow_TensorShapeIter_operator_) +* [TensorShapeDim tensorflow::TensorShapeIter::operator*](#TensorShapeDim_tensorflow_TensorShapeIter_operator_) + +##Member Details + +#### tensorflow::TensorShapeIter::TensorShapeIter(const TensorShape *shape, int d) {#tensorflow_TensorShapeIter_TensorShapeIter} + + + + + +#### bool tensorflow::TensorShapeIter::operator==(const TensorShapeIter &rhs) {#bool_tensorflow_TensorShapeIter_operator_} + + + + + +#### bool tensorflow::TensorShapeIter::operator!=(const TensorShapeIter &rhs) {#bool_tensorflow_TensorShapeIter_operator_} + + + + + +#### void tensorflow::TensorShapeIter::operator++() {#void_tensorflow_TensorShapeIter_operator_} + + + + + +#### TensorShapeDim tensorflow::TensorShapeIter::operator*() {#TensorShapeDim_tensorflow_TensorShapeIter_operator_} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/ClassTensorShapeUtils.md b/tensorflow/g3doc/api_docs/cc/ClassTensorShapeUtils.md new file mode 100644 index 0000000000..7b81eb62a8 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassTensorShapeUtils.md @@ -0,0 +1,81 @@ +#Class tensorflow::TensorShapeUtils + +Static helper routines for TensorShape . Includes a few common predicates on a tensor shape. + + + +##Member Summary + +* [static bool tensorflow::TensorShapeUtils::IsScalar](#static_bool_tensorflow_TensorShapeUtils_IsScalar) +* [static bool tensorflow::TensorShapeUtils::IsVector](#static_bool_tensorflow_TensorShapeUtils_IsVector) +* [static bool tensorflow::TensorShapeUtils::IsLegacyScalar](#static_bool_tensorflow_TensorShapeUtils_IsLegacyScalar) +* [static bool tensorflow::TensorShapeUtils::IsLegacyVector](#static_bool_tensorflow_TensorShapeUtils_IsLegacyVector) +* [static bool tensorflow::TensorShapeUtils::IsVectorOrHigher](#static_bool_tensorflow_TensorShapeUtils_IsVectorOrHigher) +* [static bool tensorflow::TensorShapeUtils::IsMatrix](#static_bool_tensorflow_TensorShapeUtils_IsMatrix) +* [static bool tensorflow::TensorShapeUtils::IsMatrixOrHigher](#static_bool_tensorflow_TensorShapeUtils_IsMatrixOrHigher) +* [static TensorShape tensorflow::TensorShapeUtils::MakeShape](#static_TensorShape_tensorflow_TensorShapeUtils_MakeShape) + * Returns a TensorShape whose dimensions are dims[0], dims[1], ..., dims[n-1]. +* [static string tensorflow::TensorShapeUtils::ShapeListString](#static_string_tensorflow_TensorShapeUtils_ShapeListString) +* [static bool tensorflow::TensorShapeUtils::StartsWith](#static_bool_tensorflow_TensorShapeUtils_StartsWith) + +##Member Details + +#### static bool tensorflow::TensorShapeUtils::IsScalar(const TensorShape &shape) {#static_bool_tensorflow_TensorShapeUtils_IsScalar} + + + + + +#### static bool tensorflow::TensorShapeUtils::IsVector(const TensorShape &shape) {#static_bool_tensorflow_TensorShapeUtils_IsVector} + + + + + +#### static bool tensorflow::TensorShapeUtils::IsLegacyScalar(const TensorShape &shape) {#static_bool_tensorflow_TensorShapeUtils_IsLegacyScalar} + + + + + +#### static bool tensorflow::TensorShapeUtils::IsLegacyVector(const TensorShape &shape) {#static_bool_tensorflow_TensorShapeUtils_IsLegacyVector} + + + + + +#### static bool tensorflow::TensorShapeUtils::IsVectorOrHigher(const TensorShape &shape) {#static_bool_tensorflow_TensorShapeUtils_IsVectorOrHigher} + + + + + +#### static bool tensorflow::TensorShapeUtils::IsMatrix(const TensorShape &shape) {#static_bool_tensorflow_TensorShapeUtils_IsMatrix} + + + + + +#### static bool tensorflow::TensorShapeUtils::IsMatrixOrHigher(const TensorShape &shape) {#static_bool_tensorflow_TensorShapeUtils_IsMatrixOrHigher} + + + + + +#### static TensorShape tensorflow::TensorShapeUtils::MakeShape(const T *dims, int n) {#static_TensorShape_tensorflow_TensorShapeUtils_MakeShape} + +Returns a TensorShape whose dimensions are dims[0], dims[1], ..., dims[n-1]. + + + +#### static string tensorflow::TensorShapeUtils::ShapeListString(const gtl::ArraySlice< TensorShape > &shapes) {#static_string_tensorflow_TensorShapeUtils_ShapeListString} + + + + + +#### static bool tensorflow::TensorShapeUtils::StartsWith(const TensorShape &shape0, const TensorShape &shape1) {#static_bool_tensorflow_TensorShapeUtils_StartsWith} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/ClassThread.md b/tensorflow/g3doc/api_docs/cc/ClassThread.md new file mode 100644 index 0000000000..32bb286206 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassThread.md @@ -0,0 +1,25 @@ +#Class tensorflow::Thread + + + + + +##Member Summary + +* [tensorflow::Thread::Thread](#tensorflow_Thread_Thread) +* [virtual tensorflow::Thread::~Thread](#virtual_tensorflow_Thread_Thread) + * Blocks until the thread of control stops running. + +##Member Details + +#### tensorflow::Thread::Thread() {#tensorflow_Thread_Thread} + + + + + +#### virtual tensorflow::Thread::~Thread() {#virtual_tensorflow_Thread_Thread} + +Blocks until the thread of control stops running. + + diff --git a/tensorflow/g3doc/api_docs/cc/ClassWritableFile.md b/tensorflow/g3doc/api_docs/cc/ClassWritableFile.md new file mode 100644 index 0000000000..e1b2132b4f --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/ClassWritableFile.md @@ -0,0 +1,52 @@ +#Class tensorflow::WritableFile + +A file abstraction for sequential writing. + +The implementation must provide buffering since callers may append small fragments at a time to the file. + +##Member Summary + +* [tensorflow::WritableFile::WritableFile](#tensorflow_WritableFile_WritableFile) +* [virtual tensorflow::WritableFile::~WritableFile](#virtual_tensorflow_WritableFile_WritableFile) +* [virtual Status tensorflow::WritableFile::Append](#virtual_Status_tensorflow_WritableFile_Append) +* [virtual Status tensorflow::WritableFile::Close](#virtual_Status_tensorflow_WritableFile_Close) +* [virtual Status tensorflow::WritableFile::Flush](#virtual_Status_tensorflow_WritableFile_Flush) +* [virtual Status tensorflow::WritableFile::Sync](#virtual_Status_tensorflow_WritableFile_Sync) + +##Member Details + +#### tensorflow::WritableFile::WritableFile() {#tensorflow_WritableFile_WritableFile} + + + + + +#### virtual tensorflow::WritableFile::~WritableFile() {#virtual_tensorflow_WritableFile_WritableFile} + + + + + +#### virtual Status tensorflow::WritableFile::Append(const StringPiece &data)=0 {#virtual_Status_tensorflow_WritableFile_Append} + + + + + +#### virtual Status tensorflow::WritableFile::Close()=0 {#virtual_Status_tensorflow_WritableFile_Close} + + + + + +#### virtual Status tensorflow::WritableFile::Flush()=0 {#virtual_Status_tensorflow_WritableFile_Flush} + + + + + +#### virtual Status tensorflow::WritableFile::Sync()=0 {#virtual_Status_tensorflow_WritableFile_Sync} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/StructSessionOptions.md b/tensorflow/g3doc/api_docs/cc/StructSessionOptions.md new file mode 100644 index 0000000000..99044997c9 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/StructSessionOptions.md @@ -0,0 +1,49 @@ +#Struct tensorflow::SessionOptions + +Configuration information for a Session . + + + +##Member Summary + +* [Env* tensorflow::SessionOptions::env](#Env_tensorflow_SessionOptions_env) + * The environment to use. +* [string tensorflow::SessionOptions::target](#string_tensorflow_SessionOptions_target) + * The TensorFlow runtime to connect to. +* [ConfigProto tensorflow::SessionOptions::config](#ConfigProto_tensorflow_SessionOptions_config) + * Configuration options. +* [tensorflow::SessionOptions::SessionOptions](#tensorflow_SessionOptions_SessionOptions) + +##Member Details + +#### Env* tensorflow::SessionOptions::env {#Env_tensorflow_SessionOptions_env} + +The environment to use. + + + +#### string tensorflow::SessionOptions::target {#string_tensorflow_SessionOptions_target} + +The TensorFlow runtime to connect to. + +If 'target' is empty or unspecified, the local TensorFlow runtime implementation will be used. Otherwise, the TensorFlow engine defined by 'target' will be used to perform all computations. + +"target" can be either a single entry or a comma separated list of entries. Each entry is a resolvable address of the following format: local ip:port host:port ... other system-specific formats to identify tasks and jobs ... + +NOTE: at the moment 'local' maps to an in-process service-based runtime. + +Upon creation, a single session affines itself to one of the remote processes, with possible load balancing choices when the "target" resolves to a list of possible processes. + +If the session disconnects from the remote process during its lifetime, session calls may fail immediately. + +#### ConfigProto tensorflow::SessionOptions::config {#ConfigProto_tensorflow_SessionOptions_config} + +Configuration options. + + + +#### tensorflow::SessionOptions::SessionOptions() {#tensorflow_SessionOptions_SessionOptions} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/StructState.md b/tensorflow/g3doc/api_docs/cc/StructState.md new file mode 100644 index 0000000000..d031b50370 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/StructState.md @@ -0,0 +1,24 @@ +#Struct tensorflow::Status::State + + + + + +##Member Summary + +* [tensorflow::error::Code tensorflow::Status::State::code](#tensorflow_error_Code_tensorflow_Status_State_code) +* [string tensorflow::Status::State::msg](#string_tensorflow_Status_State_msg) + +##Member Details + +#### tensorflow::error::Code tensorflow::Status::State::code {#tensorflow_error_Code_tensorflow_Status_State_code} + + + + + +#### string tensorflow::Status::State::msg {#string_tensorflow_Status_State_msg} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/StructTensorShapeDim.md b/tensorflow/g3doc/api_docs/cc/StructTensorShapeDim.md new file mode 100644 index 0000000000..711743ac85 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/StructTensorShapeDim.md @@ -0,0 +1,24 @@ +#Struct tensorflow::TensorShapeDim + + + + + +##Member Summary + +* [int tensorflow::TensorShapeDim::size](#int_tensorflow_TensorShapeDim_size) +* [tensorflow::TensorShapeDim::TensorShapeDim](#tensorflow_TensorShapeDim_TensorShapeDim) + +##Member Details + +#### int tensorflow::TensorShapeDim::size {#int_tensorflow_TensorShapeDim_size} + + + + + +#### tensorflow::TensorShapeDim::TensorShapeDim(int64 s) {#tensorflow_TensorShapeDim_TensorShapeDim} + + + + diff --git a/tensorflow/g3doc/api_docs/cc/StructThreadOptions.md b/tensorflow/g3doc/api_docs/cc/StructThreadOptions.md new file mode 100644 index 0000000000..b568855d6e --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/StructThreadOptions.md @@ -0,0 +1,26 @@ +#Struct tensorflow::ThreadOptions + +Options to configure a Thread . + +Note that the options are all hints, and the underlying implementation may choose to ignore it. + +##Member Summary + +* [size_t tensorflow::ThreadOptions::stack_size](#size_t_tensorflow_ThreadOptions_stack_size) + * Thread stack size to use (in bytes). +* [size_t tensorflow::ThreadOptions::guard_size](#size_t_tensorflow_ThreadOptions_guard_size) + * Guard area size to use near thread stacks to use (in bytes) + +##Member Details + +#### size_t tensorflow::ThreadOptions::stack_size {#size_t_tensorflow_ThreadOptions_stack_size} + +Thread stack size to use (in bytes). + + + +#### size_t tensorflow::ThreadOptions::guard_size {#size_t_tensorflow_ThreadOptions_guard_size} + +Guard area size to use near thread stacks to use (in bytes) + + diff --git a/tensorflow/g3doc/api_docs/cc/index.md b/tensorflow/g3doc/api_docs/cc/index.md new file mode 100644 index 0000000000..82aafc7486 --- /dev/null +++ b/tensorflow/g3doc/api_docs/cc/index.md @@ -0,0 +1,75 @@ +# TensorFlow C++ Session API reference documentation + +TensorFlow's public C++ API includes only the API for executing graphs, as of +version 0.5. To control the execution of a graph from C++: + +1. Build the computation graph using the [Python API](../python/). +1. Use [tf.train.write_graph()](../python/train.md?cl=head#write_graph) to +write the graph to a file. +1. Load the graph using the C++ Session API. For example: + + ```c++ + // Reads a model graph definition from disk, and creates a session object you + // can use to run it. + Status LoadGraph(string graph_file_name, Session** session) { + GraphDef graph_def; + TF_RETURN_IF_ERROR( + ReadBinaryProto(Env::Default(), graph_file_name, &graph_def)); + TF_RETURN_IF_ERROR(NewSession(SessionOptions(), session)); + TF_RETURN_IF_ERROR((*session)->Create(graph_def)); + return Status::OK(); + } +``` + +1. Run the graph with a call to `session->Run()` + + +##Classes + +* [tensorflow::Env](ClassEnv.md) +* [tensorflow::EnvWrapper](ClassEnvWrapper.md) +* [tensorflow::RandomAccessFile](ClassRandomAccessFile.md) +* [tensorflow::Session](ClassSession.md) +* [tensorflow::Status](ClassStatus.md) +* [tensorflow::Tensor](ClassTensor.md) +* [tensorflow::TensorBuffer](ClassTensorBuffer.md) +* [tensorflow::TensorShape](ClassTensorShape.md) +* [tensorflow::TensorShapeIter](ClassTensorShapeIter.md) +* [tensorflow::TensorShapeUtils](ClassTensorShapeUtils.md) +* [tensorflow::Thread](ClassThread.md) +* [tensorflow::WritableFile](ClassWritableFile.md) + +##Structs + +* [tensorflow::SessionOptions](StructSessionOptions.md) +* [tensorflow::Status::State](StructState.md) +* [tensorflow::TensorShapeDim](StructTensorShapeDim.md) +* [tensorflow::ThreadOptions](StructThreadOptions.md) + + +<div class='sections-order' style="display: none;"> +<!-- +<!-- ClassEnv.md --> +<!-- ClassEnvWrapper.md --> +<!-- ClassRandomAccessFile.md --> +<!-- ClassSession.md --> +<!-- ClassStatus.md --> +<!-- ClassTensor.md --> +<!-- ClassTensorBuffer.md --> +<!-- ClassTensorShape.md --> +<!-- ClassTensorShapeIter.md --> +<!-- ClassTensorShapeUtils.md --> +<!-- ClassThread.md --> +<!-- ClassWritableFile.md --> +<!-- StructSessionOptions.md --> +<!-- StructState.md --> +<!-- StructTensorShapeDim.md --> +<!-- StructThreadOptions.md --> +--> +</div> + + + + + + diff --git a/tensorflow/g3doc/api_docs/index.md b/tensorflow/g3doc/api_docs/index.md new file mode 100644 index 0000000000..7234bf45a8 --- /dev/null +++ b/tensorflow/g3doc/api_docs/index.md @@ -0,0 +1,15 @@ +# Overview + +TensorFlow has APIs available in several languages both for constructing and +executing a TensorFlow graph. The Python API is at present the most complete +and the easiest to use, but the C++ API may offer some performance advantages +in graph execution, and supports deployment to small devices such as Android. + +Over time, we hope that the TensorFlow community will develop front ends for +languages like Go, Java, Javascript, Lua R, and perhaps others. With SWIG, it's +relatively easy to contribute a TensorFlow interface to your favorite language. + +Note: Many practical aspects of ssage are covered in the Mechanics tab, and +some additional documentation not specific to any particular language API is +available in the Resources tab. + diff --git a/tensorflow/g3doc/api_docs/python/array_ops.md b/tensorflow/g3doc/api_docs/python/array_ops.md new file mode 100644 index 0000000000..eecb442f1c --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/array_ops.md @@ -0,0 +1,1025 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Tensor Transformations +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Casting](#AUTOGENERATED-casting) + * [tf.string_to_number(string_tensor, out_type=None, name=None)](#string_to_number) + * [tf.to_double(x, name='ToDouble')](#to_double) + * [tf.to_float(x, name='ToFloat')](#to_float) + * [tf.to_bfloat16(x, name='ToBFloat16')](#to_bfloat16) + * [tf.to_int32(x, name='ToInt32')](#to_int32) + * [tf.to_int64(x, name='ToInt64')](#to_int64) + * [tf.cast(x, dtype, name=None)](#cast) +* [Shapes and Shaping](#AUTOGENERATED-shapes-and-shaping) + * [tf.shape(input, name=None)](#shape) + * [tf.size(input, name=None)](#size) + * [tf.rank(input, name=None)](#rank) + * [tf.reshape(tensor, shape, name=None)](#reshape) + * [tf.squeeze(input, squeeze_dims=None, name=None)](#squeeze) + * [tf.expand_dims(input, dim, name=None)](#expand_dims) +* [Slicing and Joining](#AUTOGENERATED-slicing-and-joining) + * [tf.slice(input_, begin, size, name=None)](#slice) + * [tf.split(split_dim, num_split, value, name='split')](#split) + * [tf.tile(input, multiples, name=None)](#tile) + * [tf.pad(input, paddings, name=None)](#pad) + * [tf.concat(concat_dim, values, name='concat')](#concat) + * [tf.pack(values, name='pack')](#pack) + * [tf.unpack(value, num=None, name='unpack')](#unpack) + * [tf.reverse_sequence(input, seq_lengths, seq_dim, name=None)](#reverse_sequence) + * [tf.reverse(tensor, dims, name=None)](#reverse) + * [tf.transpose(a, perm=None, name='transpose')](#transpose) + * [tf.gather(params, indices, name=None)](#gather) + * [tf.dynamic_partition(data, partitions, num_partitions, name=None)](#dynamic_partition) + * [tf.dynamic_stitch(indices, data, name=None)](#dynamic_stitch) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Casting <div class="md-anchor" id="AUTOGENERATED-casting">{#AUTOGENERATED-casting}</div> + +TensorFlow provides several operations that you can use to cast tensor data +types in your graph. + +- - - + +### tf.string_to_number(string_tensor, out_type=None, name=None) <div class="md-anchor" id="string_to_number">{#string_to_number}</div> + +Converts each string in the input Tensor to the specified numeric type. + +(Note that int32 overflow results in an error while float overflow +results in a rounded value.) + +##### Args: + + +* <b>string_tensor</b>: A `Tensor` of type `string`. +* <b>out_type</b>: An optional `tf.DType` from: `tf.float32, tf.int32`. Defaults to `tf.float32`. + The numeric type to interpret each string in string_tensor as. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `out_type`. + A Tensor of the same shape as the input string_tensor. + + +- - - + +### tf.to_double(x, name='ToDouble') <div class="md-anchor" id="to_double">{#to_double}</div> + +Casts a tensor to type `float64`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `float64`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `float64`. + + +- - - + +### tf.to_float(x, name='ToFloat') <div class="md-anchor" id="to_float">{#to_float}</div> + +Casts a tensor to type `float32`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `float32`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `float32`. + + +- - - + +### tf.to_bfloat16(x, name='ToBFloat16') <div class="md-anchor" id="to_bfloat16">{#to_bfloat16}</div> + +Casts a tensor to type `bfloat16`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `bfloat16`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `bfloat16`. + + +- - - + +### tf.to_int32(x, name='ToInt32') <div class="md-anchor" id="to_int32">{#to_int32}</div> + +Casts a tensor to type `int32`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `int32`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `int32`. + + +- - - + +### tf.to_int64(x, name='ToInt64') <div class="md-anchor" id="to_int64">{#to_int64}</div> + +Casts a tensor to type `int64`. + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x` with type `int64`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `int64`. + + +- - - + +### tf.cast(x, dtype, name=None) <div class="md-anchor" id="cast">{#cast}</div> + +Casts a tensor to a new type. + +The operation casts `x` (in case of `Tensor`) or `x.values` +(in case of `SparseTensor`) to `dtype`. + +For example: + +```python +# tensor `a` is [1.8, 2.2], dtype=tf.float +tf.cast(a, tf.int32) ==> [1, 2] # dtype=tf.int32 +``` + +##### Args: + + +* <b>x</b>: A `Tensor` or `SparseTensor`. +* <b>dtype</b>: The destination type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` or `SparseTensor` with same shape as `x`. + +##### Raises: + + +* <b>TypeError</b>: If `x` cannot be cast to the `dtype`. + + + +## Shapes and Shaping <div class="md-anchor" id="AUTOGENERATED-shapes-and-shaping">{#AUTOGENERATED-shapes-and-shaping}</div> + +TensorFlow provides several operations that you can use to determine the shape +of a tensor and change the shape of a tensor. + +- - - + +### tf.shape(input, name=None) <div class="md-anchor" id="shape">{#shape}</div> + +Returns the shape of a tensor. + +This operation returns a 1-D integer tensor representing the shape of `input`. + +For example: + +```prettyprint +# 't' is [[[1, 1, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]] +shape(t) ==> [2, 2, 3] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. + + +- - - + +### tf.size(input, name=None) <div class="md-anchor" id="size">{#size}</div> + +Returns the size of a tensor. + +This operation returns an integer representing the number of elements in +`input`. + +For example: + +```prettyprint +# 't' is [[[1, 1,, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]]] +size(t) ==> 12 +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. + + +- - - + +### tf.rank(input, name=None) <div class="md-anchor" id="rank">{#rank}</div> + +Returns the rank of a tensor. + +This operation returns an integer representing the rank of `input`. + +For example: + +```prettyprint +# 't' is [[[1, 1, 1], [2, 2, 2]], [[3, 3, 3], [4, 4, 4]]] +# shape of tensor 't' is [2, 2, 3] +rank(t) ==> 3 +``` + +**Note**: The rank of a tensor is not the same as the rank of a matrix. The rank +of a tensor is the number of indices required to uniquely select each element +of the tensor. Rank is also known as "order", "degree", or "ndims." + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. + + +- - - + +### tf.reshape(tensor, shape, name=None) <div class="md-anchor" id="reshape">{#reshape}</div> + +Reshapes a tensor. + +Given `tensor`, this operation returns a tensor that has the same values +as `tensor` with shape `shape`. + +If `shape` is the special value `[-1]`, then `tensor` is flattened and the +operation outputs a 1-D tensor with all elements of `tensor`. + +If `shape` is 1-D or higher, then the operation returns a tensor with shape +`shape` filled with the values of `tensor`. In this case, the number of elements +implied by `shape` must be the same as the number of elements in `tensor`. + +For example: + +```prettyprint +# tensor 't' is [1, 2, 3, 4, 5, 6, 7, 8, 9] +# tensor 't' has shape [9] +reshape(t, [3, 3]) ==> [[1, 2, 3] + [4, 5, 6] + [7, 8, 9]] + +# tensor 't' is [[[1, 1], [2, 2]] +# [[3, 3], [4, 4]]] +# tensor 't' has shape [2, 2] +reshape(t, [2, 4]) ==> [[1, 1, 2, 2] + [3, 3, 4, 4]] + +# tensor 't' is [[[1, 1, 1], +# [2, 2, 2]], +# [[3, 3, 3], +# [4, 4, 4]], +# [[5, 5, 5], +# [6, 6, 6]]] +# tensor 't' has shape [3, 2, 3] +# pass '[-1]' to flatten 't' +reshape(t, [-1]) ==> [1, 1, 1, 2, 2, 2, 3, 3, 3, 4, 4, 4, 5, 5, 5, 6, 6, 6] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. +* <b>shape</b>: A `Tensor` of type `int32`. Defines the shape of the output tensor. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `tensor`. + + +- - - + +### tf.squeeze(input, squeeze_dims=None, name=None) <div class="md-anchor" id="squeeze">{#squeeze}</div> + +Removes dimensions of size 1 from the shape of a tensor. + +Given a tensor `input`, this operation returns a tensor of the same type with +all dimensions of size 1 removed. If you don't want to remove all size 1 +dimensions, you can remove specific size 1 dimensions by specifying +`squeeze_dims`. + +For example: + +```prettyprint +# 't' is a tensor of shape [1, 2, 1, 3, 1, 1] +shape(squeeze(t)) ==> [2, 3] +``` + +Or, to remove specific size 1 dimensions: + +```prettyprint +# 't' is a tensor of shape [1, 2, 1, 3, 1, 1] +shape(squeeze(t, [2, 4])) ==> [1, 2, 3, 1] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. The `input` to squeeze. +* <b>squeeze_dims</b>: An optional list of `ints`. Defaults to `[]`. + If specified, only squeezes the dimensions listed. The dimension + index starts at 0. It is an error to squeeze a dimension that is not 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + Contains the same data as `input`, but has one or more dimensions of + size 1 removed. + + +- - - + +### tf.expand_dims(input, dim, name=None) <div class="md-anchor" id="expand_dims">{#expand_dims}</div> + +Inserts a dimension of 1 into a tensor's shape. + +Given a tensor `input`, this operation inserts a dimension of 1 at the +dimension index `dim` of `input`'s shape. The dimension index `dim` starts at +zero; if you specify a negative number for `dim` it is counted backward from +the end. + +This operation is useful if you want to add a batch dimension to a single +element. For example, if you have a single image of shape `[height, width, +channels]`, you can make it a batch of 1 image with `expand_dims(image, 0)`, +which will make the shape `[1, height, width, channels]`. + +Other examples: + +```prettyprint +# 't' is a tensor of shape [2] +shape(expand_dims(t, 0)) ==> [1, 2] +shape(expand_dims(t, 1)) ==> [2, 1] +shape(expand_dims(t, -1)) ==> [2, 1] + +# 't2' is a tensor of shape [2, 3, 5] +shape(expand_dims(t2, 0)) ==> [1, 2, 3, 5] +shape(expand_dims(t2, 2)) ==> [2, 3, 1, 5] +shape(expand_dims(t2, 3)) ==> [2, 3, 5, 1] +``` + +This operation requires that: + +`-1-input.dims() <= dim <= input.dims()` + +This operation is related to `squeeze()`, which removes dimensions of +size 1. + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>dim</b>: A `Tensor` of type `int32`. + 0-D (scalar). Specifies the dimension index at which to + expand the shape of `input`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + Contains the same data as `input`, but its shape has an additional + dimension of size 1 added. + + + +## Slicing and Joining <div class="md-anchor" id="AUTOGENERATED-slicing-and-joining">{#AUTOGENERATED-slicing-and-joining}</div> + +TensorFlow provides several operations to slice or extract parts of a tensor, +or join multiple tensors together. + +- - - + +### tf.slice(input_, begin, size, name=None) <div class="md-anchor" id="slice">{#slice}</div> + +Extracts a slice from a tensor. + +This operation extracts a slice of size `size` from a tensor `input` starting +at the location specified by `begin`. The slice `size` is represented as a +tensor shape, where `size[i]` is the number of elements of the 'i'th dimension +of `input` that you want to slice. The starting location (`begin`) for the +slice is represented as an offset in each dimension of `input`. In other +words, `begin[i]` is the offset into the 'i'th dimension of `input` that you +want to slice from. + +`begin` is zero-based; `size` is one-based. If `size[i]` is -1, +all remaining elements in dimension i are included in the +slice. In other words, this is equivalent to setting: + +`size[i] = input.dim_size(i) - begin[i]` + +This operation requires that: + +`0 <= begin[i] <= begin[i] + size[i] <= Di for i in [0, n]` + +For example: + +``` +# 'input' is [[[1, 1, 1], [2, 2, 2]], +# [[3, 3, 3], [4, 4, 4]], +# [[5, 5, 5], [6, 6, 6]]] +tf.slice(input, [1, 0, 0], [1, 1, 3]) ==> [[[3, 3, 3]]] +tf.slice(input, [1, 0, 0], [1, 2, 3]) ==> [[[3, 3, 3], + [4, 4, 4]]] +tf.slice(input, [1, 0, 0], [2, 1, 3]) ==> [[[3, 3, 3]], + [[5, 5, 5]]] +``` + +##### Args: + + +* <b>input_</b>: A `Tensor`. +* <b>begin</b>: An `int32` or `int64` `Tensor`. +* <b>size</b>: An `int32` or `int64` `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` the same type as `input`. + + +- - - + +### tf.split(split_dim, num_split, value, name='split') <div class="md-anchor" id="split">{#split}</div> + +Splits a tensor into `num_split` tensors along one dimension. + +Splits `value` along dimension `split_dim` into `num_split` smaller tensors. +Requires that `num_split` evenly divide `value.shape[split_dim]`. + +For example: + +```python +# 'value' is a tensor with shape [5, 30] +# Split 'value' into 3 tensors along dimension 1 +split0, split1, split2 = tf.split(1, 3, value) +tf.shape(split0) ==> [5, 10] +``` + +##### Args: + + +* <b>split_dim</b>: A 0-D `int32` `Tensor`. The dimension along which to split. + Must be in the range `[0, rank(value))`. +* <b>num_split</b>: A 0-D `int32` `Tensor`. The number of ways to split. +* <b>value</b>: The `Tensor` to split. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + `num_split` `Tensor` objects resulting from splitting `value`. + + +- - - + +### tf.tile(input, multiples, name=None) <div class="md-anchor" id="tile">{#tile}</div> + +Constructs a tensor by tiling a given tensor. + +This operation creates a new tensor by replicating `input` `multiples` times. +The output tensor's i'th dimension has `input.dims(i) * multiples[i]` elements, +and the values of `input` are replicated `multiples[i]` times along the 'i'th +dimension. For example, tiling `[a b c d]` by `[2]` produces +`[a b c d a b c d]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. 1-D or higher. +* <b>multiples</b>: A `Tensor` of type `int32`. + 1-D. Length must be the same as the number of dimensions in `input` +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.pad(input, paddings, name=None) <div class="md-anchor" id="pad">{#pad}</div> + +Pads a tensor with zeros. + +This operation pads a `input` with zeros according to the `paddings` you +specify. `paddings` is an integer tensor with shape `[Dn, 2]`, where n is the +rank of `input`. For each dimension D of `input`, `paddings[D, 0]` indicates +how many zeros to add before the contents of `input` in that dimension, and +`paddings[D, 1]` indicates how many zeros to add after the contents of `input` +in that dimension. + +The padded size of each dimension D of the output is: + +`paddings(D, 0) + input.dim_size(D) + paddings(D, 1)` + +For example: + +```prettyprint +# 't' is [[1, 1], [2, 2]] +# 'paddings' is [[1, 1]], [2, 2]] +# rank of 't' is 2 +pad(t, paddings) ==> [[0, 0, 0, 0, 0] + [0, 0, 0, 0, 0] + [0, 1, 1, 0, 0] + [[0, 2, 2, 0, 0] + [0, 0, 0, 0, 0]] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>paddings</b>: A `Tensor` of type `int32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.concat(concat_dim, values, name='concat') <div class="md-anchor" id="concat">{#concat}</div> + +Concatenates tensors along one dimension. + +Concatenates the list of tensors `values` along dimension `concat_dim`. If +`values[i].shape = [D0, D1, ... Dconcat_dim(i), ...Dn]`, the concatenated +result has shape + + [D0, D1, ... Rconcat_dim, ...Dn] + +where + + Rconcat_dim = sum(Dconcat_dim(i)) + +That is, the data from the input tensors is joined along the `concat_dim` +dimension. + +The number of dimensions of the input tensors must match, and all dimensions +except `concat_dim` must be equal. + +For example: + +```python +t1 = [[1, 2, 3], [4, 5, 6]] +t2 = [[7, 8, 9], [10, 11, 12]] +tf.concat(0, [t1, t2]) ==> [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]] +tf.concat(1, [t1, t2]) ==> [[1, 2, 3, 7, 8, 9], [4, 5, 6, 10, 11, 12]] + +# tensor t3 with shape [2, 3] +# tensor t4 with shape [2, 3] +tf.shape(tf.concat(0, [t3, t4])) ==> [4, 3] +tf.shape(tf.concat(1, [t3, t4])) ==> [2, 6] +``` + +##### Args: + + +* <b>concat_dim</b>: 0-D `int32` `Tensor`. Dimension along which to concatenate. +* <b>values</b>: A list of `Tensor` objects or a single `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` resulting from concatenation of the input tensors. + + +- - - + +### tf.pack(values, name='pack') <div class="md-anchor" id="pack">{#pack}</div> + +Packs a list of rank-`R` tensors into one rank-`(R+1)` tensor. + +Packs tensors in `values` into a tensor with rank one higher than each tensor +in `values` and shape `[len(values)] + values[0].shape`. The output satisfies +`output[i, ...] = values[i][...]`. + +This is the opposite of unpack. The numpy equivalent is + + tf.pack([x, y, z]) = np.asarray([x, y, z]) + +##### Args: + + +* <b>values</b>: A list of `Tensor` objects with the same shape and type. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + +* <b>output</b>: A packed `Tensor` with the same type as `values`. + + +- - - + +### tf.unpack(value, num=None, name='unpack') <div class="md-anchor" id="unpack">{#unpack}</div> + +Unpacks the outer dimension of a rank-`R` tensor into rank-`(R-1)` tensors. + +Unpacks `num` tensors from `value` along the first dimension. +If `num` is not specified (the default), it is inferred from `value`'s shape. +If `value.shape[0]` is not known, `ValueError` is raised. + +The ith tensor in `output` is the slice `value[i, ...]`. Each tensor in +`output` has shape `value.shape[1:]`. + +This is the opposite of pack. The numpy equivalent is + + tf.unpack(x, n) = list(x) + +##### Args: + + +* <b>value</b>: A rank `R > 0` `Tensor` to be unpacked. +* <b>num</b>: An `int`. The first dimension of value. Automatically inferred if + `None` (the default). +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The list of `Tensor` objects unpacked from `value`. + +##### Raises: + + +* <b>ValueError</b>: If `num` is unspecified and cannot be inferred. + + +- - - + +### tf.reverse_sequence(input, seq_lengths, seq_dim, name=None) <div class="md-anchor" id="reverse_sequence">{#reverse_sequence}</div> + +Reverses variable length slices in dimension `seq_dim`. + +This op first slices `input` along the first dimension, and for each slice `i`, +reverses the first `seq_lengths[i]` elements along the dimension `seq_dim`. + +The elements of `seq_lengths` must obey `seq_lengths[i] < input.dims[seq_dim]`, +and `seq_lengths` must be a vector of length `input.dims(0)`. + +The output slice `i` along dimension 0 is then given by input slice `i`, with +the first `seq_lengths[i]` slices along dimension `seq_dim` reversed. + +For example: + +```prettyprint +# Given this: +seq_dim = 1 +input.dims = (4, ...) +seq_lengths = [7, 2, 3, 5] + +# then slices of input are reversed on seq_dim, but only up to seq_lengths: +output[0, 0:7, :, ...] = input[0, 7:0:-1, :, ...] +output[1, 0:2, :, ...] = input[1, 2:0:-1, :, ...] +output[2, 0:3, :, ...] = input[2, 3:0:-1, :, ...] +output[3, 0:5, :, ...] = input[3, 5:0:-1, :, ...] + +# while entries past seq_lens are copied through: +output[0, 7:, :, ...] = input[0, 7:, :, ...] +output[1, 2:, :, ...] = input[1, 2:, :, ...] +output[2, 3:, :, ...] = input[2, 3:, :, ...] +output[3, 2:, :, ...] = input[3, 2:, :, ...] +``` + +##### Args: + + +* <b>input</b>: A `Tensor`. The input to reverse. +* <b>seq_lengths</b>: A `Tensor` of type `int64`. + 1-D with length `input.dims(0)` and + `max(seq_lengths) < input.dims(seq_dim)` +* <b>seq_dim</b>: An `int`. The dimension which is partially reversed. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + The partially reversed input. It has the same shape as `input`. + + +- - - + +### tf.reverse(tensor, dims, name=None) <div class="md-anchor" id="reverse">{#reverse}</div> + +Reverses specific dimensions of a tensor. + +Given a `tensor`, and a `bool` tensor `dims` representing the dimensions +of `tensor`, this operation reverses each dimension i of `tensor` where +`dims[i]` is `True`. + +`tensor` can have up to 8 dimensions. The number of dimensions +of `tensor` must equal the number of elements in `dims`. In other words: + +`rank(tensor) = size(dims)` + +For example: + +```prettyprint +# tensor 't' is [[[[ 0, 1, 2, 3], +# [ 4, 5, 6, 7], +# [ 8, 9, 10, 11]], +# [[12, 13, 14, 15], +# [16, 17, 18, 19], +# [20, 21, 22, 23]]]] +# tensor 't' shape is [1, 2, 3, 4] + +# 'dims' is [False, False, False, True] +reverse(t, dims) ==> [[[[ 3, 2, 1, 0], + [ 7, 6, 5, 4], + [ 11, 10, 9, 8]], + [[15, 14, 13, 12], + [19, 18, 17, 16], + [23, 22, 21, 20]]]] + +# 'dims' is [False, True, False, False] +reverse(t, dims) ==> [[[[12, 13, 14, 15], + [16, 17, 18, 19], + [20, 21, 22, 23] + [[ 0, 1, 2, 3], + [ 4, 5, 6, 7], + [ 8, 9, 10, 11]]]] + +# 'dims' is [False, False, True, False] +reverse(t, dims) ==> [[[[8, 9, 10, 11], + [4, 5, 6, 7], + [0, 1, 2, 3]] + [[20, 21, 22, 23], + [16, 17, 18, 19], + [12, 13, 14, 15]]]] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `bool`, `float32`, `float64`. + Up to 8-D. +* <b>dims</b>: A `Tensor` of type `bool`. 1-D. The dimensions to reverse. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `tensor`. The same shape as `tensor`. + + +- - - + +### tf.transpose(a, perm=None, name='transpose') <div class="md-anchor" id="transpose">{#transpose}</div> + +Transposes `a`. Permutes the dimensions according to `perm`. + +The returned tensor's dimension i will correspond to the input dimension +`perm[i]`. If `perm` is not given, it is set to (n-1...0), where n is +the rank of the input tensor. Hence by default, this operation performs a +regular matrix transpose on 2-D input Tensors. + +For example: + +```python +# 'x' is [[1 2 3] +# [4 5 6]] +tf.transpose(x) ==> [[1 4] + [2 5] + [3 6]] + +# Equivalently +tf.transpose(x perm=[0, 1]) ==> [[1 4] + [2 5] + [3 6]] + +# 'perm' is more useful for n-dimensional tensors, for n > 2 +# 'x' is [[[1 2 3] +# [4 5 6]] +# [[7 8 9] +# [10 11 12]]] +# Take the transpose of the matrices in dimension-0 +tf.transpose(b, perm=[0, 2, 1]) ==> [[[1 4] + [2 5] + [3 6]] + + [[7 10] + [8 11] + [9 12]]] +``` + +##### Args: + + +* <b>a</b>: A `Tensor`. +* <b>perm</b>: A permutation of the dimensions of `a`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A transposed `Tensor`. + + +- - - + +### tf.gather(params, indices, name=None) <div class="md-anchor" id="gather">{#gather}</div> + +Gather slices from `params` according to `indices`. + +`indices` must be an integer tensor of any dimension (usually 0-D or 1-D). +Produces an output tensor with shape `indices.shape + params.shape[1:]` where: + + # Scalar indices + output[:, ..., :] = params[indices, :, ... :] + + # Vector indices + output[i, :, ..., :] = params[indices[i], :, ... :] + + # Higher rank indices + output[i, ..., j, :, ... :] = params[indices[i, ..., j], :, ..., :] + +If `indices` is a permutation and `len(indices) == params.shape[0]` then +this operation will permute `params` accordingly. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/Gather.png" alt> +</div> + +##### Args: + + +* <b>params</b>: A `Tensor`. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `params`. + + +- - - + +### tf.dynamic_partition(data, partitions, num_partitions, name=None) <div class="md-anchor" id="dynamic_partition">{#dynamic_partition}</div> + +Partitions `data` into `num_partitions` tensors using indices from `partitions`. + +For each index tuple `js` of size `partitions.ndim`, the slice `data[js, ...]` +becomes part of `outputs[partitions[js]]`. The slices with `partitions[js] = i` +are placed in `outputs[i]` in lexicographic order of `js`, and the first +dimension of `outputs[i]` is the number of entries in `partitions` equal to `i`. +In detail, + + outputs[i].shape = [sum(partitions == i)] + data.shape[partitions.ndim:] + + outputs[i] = pack([data[js, ...] for js if partitions[js] == i]) + +`data.shape` must start with `partitions.shape`. + +For example: + + # Scalar partitions + partitions = 1 + num_partitions = 2 + data = [10, 20] + outputs[0] = [] # Empty with shape [0, 2] + outputs[1] = [[10, 20]] + + # Vector partitions + partitions = [0, 0, 1, 1, 0] + num_partitions = 2 + data = [10, 20, 30, 40, 50] + outputs[0] = [10, 20, 50] + outputs[1] = [30, 40] + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/DynamicPartition.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. +* <b>partitions</b>: A `Tensor` of type `int32`. + Any shape. Indices in the range `[0, num_partitions)`. +* <b>num_partitions</b>: An `int` that is `>= 1`. + The number of partitions to output. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A list of `num_partitions` `Tensor` objects of the same type as data. + + +- - - + +### tf.dynamic_stitch(indices, data, name=None) <div class="md-anchor" id="dynamic_stitch">{#dynamic_stitch}</div> + +Interleave the values from the `data` tensors into a single tensor. + +Builds a merged tensor such that + + merged[indices[m][i, ..., j], ...] = data[m][i, ..., j, ...] + +For example, if each `indices[m]` is scalar or vector, we have + + # Scalar indices + merged[indices[m], ...] = data[m][...] + + # Vector indices + merged[indices[m][i], ...] = data[m][i, ...] + +Each `data[i].shape` must start with the corresponding `indices[i].shape`, +and the rest of `data[i].shape` must be constant w.r.t. `i`. That is, we +must have `data[i].shape = indices[i].shape + constant`. In terms of this +`constant`, the output shape is + + merged.shape = [max(indices)] + constant + +Values are merged in order, so if an index appears in both `indices[m][i]` and +`indices[n][j]` for `(m,i) < (n,j)` the slice `data[n][j]` will appear in the +merged result. + +For example: + + indices[0] = 6 + indices[1] = [4, 1] + indices[2] = [[5, 2], [0, 3]] + data[0] = [61, 62] + data[1] = [[41, 42], [11, 12]] + data[2] = [[[51, 52], [21, 22]], [[1, 2], [31, 32]]] + merged = [[1, 2], [11, 12], [21, 22], [31, 32], [41, 42], + [51, 52], [61, 62]] + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/DynamicStitch.png" alt> +</div> + +##### Args: + + +* <b>indices</b>: A list of at least 2 `Tensor` objects of type `int32`. +* <b>data</b>: A list with the same number of `Tensor` objects as `indices` of `Tensor` objects of the same type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + + diff --git a/tensorflow/g3doc/api_docs/python/client.md b/tensorflow/g3doc/api_docs/python/client.md new file mode 100644 index 0000000000..b37057e4b5 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/client.md @@ -0,0 +1,638 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Running Graphs +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Session management](#AUTOGENERATED-session-management) + * [class tf.Session](#Session) + * [tf.get_default_session()](#get_default_session) +* [Error classes](#AUTOGENERATED-error-classes) + * [class tf.OpError](#OpError) + * [class tf.errors.CancelledError](#CancelledError) + * [class tf.errors.UnknownError](#UnknownError) + * [class tf.errors.InvalidArgumentError](#InvalidArgumentError) + * [class tf.errors.DeadlineExceededError](#DeadlineExceededError) + * [class tf.errors.NotFoundError](#NotFoundError) + * [class tf.errors.AlreadyExistsError](#AlreadyExistsError) + * [class tf.errors.PermissionDeniedError](#PermissionDeniedError) + * [class tf.errors.UnauthenticatedError](#UnauthenticatedError) + * [class tf.errors.ResourceExhaustedError](#ResourceExhaustedError) + * [class tf.errors.FailedPreconditionError](#FailedPreconditionError) + * [class tf.errors.AbortedError](#AbortedError) + * [class tf.errors.OutOfRangeError](#OutOfRangeError) + * [class tf.errors.UnimplementedError](#UnimplementedError) + * [class tf.errors.InternalError](#InternalError) + * [class tf.errors.UnavailableError](#UnavailableError) + * [class tf.errors.DataLossError](#DataLossError) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +This library contains classes for launching graphs and executing operations. + +The [basic usage](../../get_started/index.md#basic-usage) guide has +examples of how a graph is launched in a [`tf.Session`](#Session). + +## Session management <div class="md-anchor" id="AUTOGENERATED-session-management">{#AUTOGENERATED-session-management}</div> + +- - - + +### class tf.Session <div class="md-anchor" id="Session">{#Session}</div> + +A class for running TensorFlow operations. + +A `Session` object encapsulates the environment in which `Operation` +objects are executed, and `Tensor` objects are evaluated. For +example: + +```python +# 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 as +[variables](state_ops.md#Variable), [queues](io_ops.md#QueueBase), +and [readers](io_ops.md#ReaderBase). It is important to release +these resources when they are no longer required. To do this, either +invoke the [`close()`](#Session.close) method on the session, or use +the session as a context manager. The following two examples are +equivalent: + +```python +# Using the `close()` method. +sess = tf.Session() +sess.run(...) +sess.close() + +# Using the context manager. +with tf.Session() as sess: + sess.run(...) +``` + +The [`ConfigProto`] +(https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/config.proto) +protocol buffer exposes various configuration options for a +session. For example, to create a session that uses soft constraints +for device placement, and log the resulting placement decisions, +create a session as follows: + +```python +# 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) {#Session.__init__} + +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 are +using more than one graph (created with `tf.Graph()` in the same +process, you will have to use different sessions for each graph, +but each graph can be used in multiple sessions. In this case, it +is often clearer to pass the graph to be launched explicitly to +the session constructor. + +##### Args: + + +* <b>target</b>: (Optional.) The execution engine to connect to. + Defaults to using an in-process engine. At present, no value + other than the empty string is supported. +* <b>graph</b>: (Optional.) The `Graph` to be launched (described above). +* <b>config</b>: (Optional.) A [`ConfigProto`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/config.proto) + protocol buffer with configuration options for the session. + + +- - - + +#### tf.Session.run(fetches, feed_dict=None) {#Session.run} + +Runs the operations and evaluates the tensors in `fetches`. + +This method runs one "step" of TensorFlow computation, by +running the necessary graph fragment to execute every `Operation` +and evaluate every `Tensor` in `fetches`, substituting the values in +`feed_dict` for the corresponding input values. + +The `fetches` argument may be a list of graph elements or a single +graph element, and these determine the return value of this +method. A graph element can be one of the following types: + +* If the *i*th element of `fetches` is an + [`Operation`](framework.md#Operation), the *i*th return value + will be `None`. +* If the *i*th element of `fetches` is a + [`Tensor`](framework.md#Tensor), the *i*th return value will + be a numpy ndarray containing the value of that tensor. +* If the *i*th element of `fetches` is a + [`SparseTensor`](sparse_ops.md#SparseTensor), the *i*th + return value will be a + [`SparseTensorValue`](sparse_ops.md#SparseTensorValue) + containing the value of that sparse tensor. + +The optional `feed_dict` argument allows the caller to override +the value of tensors in the graph. Each key in `feed_dict` can be +one of the following types: + +* If the key is a [`Tensor`](framework.md#Tensor), the + value may be a Python scalar, string, list, or numpy ndarray + that can be converted to the same `dtype` as that + tensor. Additionally, if the key is a + [placeholder](io_ops.md#placeholder), the shape of the value + will be checked for compatibility with the placeholder. +* If the key is a [`SparseTensor`](sparse_ops.md#SparseTensor), + the value should be a + [`SparseTensorValue`](sparse_ops.md#SparseTensorValue). + +##### Args: + + +* <b>fetches</b>: A single graph element, or a list of graph elements + (described above). +* <b>feed_dict</b>: A dictionary that maps graph elements to values + (described above). + +##### 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: + + +* <b>RuntimeError</b>: If this `Session` is in an invalid state (e.g. has been + closed). +* <b>TypeError</b>: If `fetches` or `feed_dict` keys are of an inappropriate type. +* <b>ValueError</b>: If `fetches` or `feed_dict` keys are invalid or refer to a + `Tensor` that doesn't exist. + + +- - - + +#### tf.Session.close() {#Session.close} + +Closes this session. + +Calling this method frees all resources associated with the session. + +##### Raises: + + +* <b>RuntimeError</b>: If an error occurs while closing the session. + + + +- - - + +#### tf.Session.graph {#Session.graph} + +The graph that was launched in this session. + + +- - - + +#### tf.Session.as_default() {#Session.as_default} + +Returns a context manager that makes this object the default session. + +Use with the `with` keyword to specify that calls to +[`Operation.run()`](framework.md#Operation.run) or +[`Tensor.run()`](framework.md#Tensor.run) should be executed in +this session. + +```python +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, use +[`tf.get_default_session()`](#get_default_session). + + +*N.B.* The `as_default` context manager *does not* close the +session when you exit the context, and you must close the session +explicitly. + +```python +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 a +session 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 you +create a new thread, and wish to use the default session in that +thread, you must explicitly add a `with sess.as_default():` in that +thread's function. + +##### Returns: + + A context manager using this session as the default session. + + + + +- - - + +### tf.get_default_session() <div class="md-anchor" id="get_default_session">{#get_default_session}</div> + +Returns the default session for the current thread. + +The returned `Session` will be the innermost session on which a +`Session` or `Session.as_default()` context has been entered. + +*N.B.* The default session is a property of the current thread. If you +create a new thread, and wish to use the default session in that +thread, you must explicitly add a `with sess.as_default():` in that +thread's function. + +##### Returns: + + The default `Session` being used in the current thread. + + + +## Error classes <div class="md-anchor" id="AUTOGENERATED-error-classes">{#AUTOGENERATED-error-classes}</div> + +- - - + +### class tf.OpError <div class="md-anchor" id="OpError">{#OpError}</div> + +A generic error that is raised when TensorFlow execution fails. + +Whenever possible, the session will raise a more specific subclass +of `OpError` from the `tf.errors` module. + +- - - + +#### tf.OpError.op {#OpError.op} + +The operation that failed, if known. + +*N.B.* If the failed op was synthesized at runtime, e.g. a `Send` +or `Recv` op, there will be no corresponding +[`Operation`](framework.md#Operation) object. In that case, this +will return `None`, and you should instead use the +[`node_def`](OpError.node_def) to discover information about the op. + +##### Returns: + + The `Operation` that failed, or None. + +- - - + +#### tf.OpError.node_def {#OpError.node_def} + +The `NodeDef` proto representing the op that failed. + + +#### Other Methods +- - - + +#### tf.OpError.__init__(node_def, op, message, error_code) {#OpError.__init__} + +Creates a new OpError indicating that a particular op failed. + +##### Args: + + +* <b>node_def</b>: The graph_pb2.NodeDef proto representing the op that failed. +* <b>op</b>: The ops.Operation that failed, if known; otherwise None. +* <b>message</b>: The message string describing the failure. +* <b>error_code</b>: The error_codes_pb2.Code describing the error. + + +- - - + +#### tf.OpError.error_code {#OpError.error_code} + +The integer error code that describes the error. + +- - - + +#### tf.OpError.message {#OpError.message} + +The error message that describes the error. + + +- - - + +### class tf.errors.CancelledError <div class="md-anchor" id="CancelledError">{#CancelledError}</div> + +Raised when an operation or step is cancelled. + +For example, a long-running operation (e.g. +[`queue.enqueue()`](io_ops.md#QueueBase.enqueue) may be cancelled by +running another operation (e.g. +[`queue.close(cancel_pending_enqueues=True)`](io_ops.md#QueueBase.close), +or by [closing the session](client.md#Session.close). A step that is +running such a long-running operation will fail by raising `CancelledError`. + +- - - + +#### tf.errors.CancelledError.__init__(node_def, op, message) {#CancelledError.__init__} + +Creates a `CancelledError`. + + + +- - - + +### class tf.errors.UnknownError <div class="md-anchor" id="UnknownError">{#UnknownError}</div> + +Unknown error. + +An example of where this error may be returned is if a Status value +received from another address space belongs to an error-space that +is not known to this address space. Also errors raised by APIs that +do not return enough error information may be converted to this +error. + +- - - + +#### tf.errors.UnknownError.__init__(node_def, op, message, error_code=2) {#UnknownError.__init__} + +Creates an `UnknownError`. + + + +- - - + +### class tf.errors.InvalidArgumentError <div class="md-anchor" id="InvalidArgumentError">{#InvalidArgumentError}</div> + +Raised when an operation receives an invalid argument. + +This may occur, for example, if an operation is receives an input +tensor that has an invalid value or shape. For example, the +[`tf.matmul()`](math_ops.md#matmul) op will raise this error if it +receives an input that is not a matrix, and the +[`tf.reshape()`](array_ops.md#reshape) op will raise this error if +the new shape does not match the number of elements in the input +tensor. + +- - - + +#### tf.errors.InvalidArgumentError.__init__(node_def, op, message) {#InvalidArgumentError.__init__} + +Creates an `InvalidArgumentError`. + + + +- - - + +### class tf.errors.DeadlineExceededError <div class="md-anchor" id="DeadlineExceededError">{#DeadlineExceededError}</div> + +Raised when a deadline expires before an operation could complete. + +This exception is not currently used. + +- - - + +#### tf.errors.DeadlineExceededError.__init__(node_def, op, message) {#DeadlineExceededError.__init__} + +Creates a `DeadlineExceededError`. + + + +- - - + +### class tf.errors.NotFoundError <div class="md-anchor" id="NotFoundError">{#NotFoundError}</div> + +Raised when a requested entity (e.g., a file or directory) was not found. + +For example, running the +[`tf.WholeFileReader.read()`](io_ops.md#WholeFileReader) operation +could raise `NotFoundError` if it receives the name of a file that +does not exist. + +- - - + +#### tf.errors.NotFoundError.__init__(node_def, op, message) {#NotFoundError.__init__} + +Creates a `NotFoundError`. + + + +- - - + +### class tf.errors.AlreadyExistsError <div class="md-anchor" id="AlreadyExistsError">{#AlreadyExistsError}</div> + +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()`](train.md#Saver.save)) could +potentially raise this exception if an explicit filename for an +existing file was passed. + +- - - + +#### tf.errors.AlreadyExistsError.__init__(node_def, op, message) {#AlreadyExistsError.__init__} + +Creates an `AlreadyExistsError`. + + + +- - - + +### class tf.errors.PermissionDeniedError <div class="md-anchor" id="PermissionDeniedError">{#PermissionDeniedError}</div> + +Raised when the caller does not have permission to run an operation. + +For example, running the +[`tf.WholeFileReader.read()`](io_ops.md#WholeFileReader) operation +could raise `PermissionDeniedError` if it receives the name of a +file for which the user does not have the read file permission. + +- - - + +#### tf.errors.PermissionDeniedError.__init__(node_def, op, message) {#PermissionDeniedError.__init__} + +Creates a `PermissionDeniedError`. + + + +- - - + +### class tf.errors.UnauthenticatedError <div class="md-anchor" id="UnauthenticatedError">{#UnauthenticatedError}</div> + +The request does not have valid authentication credentials. + +This exception is not currently used. + +- - - + +#### tf.errors.UnauthenticatedError.__init__(node_def, op, message) {#UnauthenticatedError.__init__} + +Creates an `UnauthenticatedError`. + + + +- - - + +### class tf.errors.ResourceExhaustedError <div class="md-anchor" id="ResourceExhaustedError">{#ResourceExhaustedError}</div> + +Some resource has been exhausted. + +For example, this error might be raised if a per-user quota is +exhausted, or perhaps the entire file system is out of space. + +- - - + +#### tf.errors.ResourceExhaustedError.__init__(node_def, op, message) {#ResourceExhaustedError.__init__} + +Creates a `ResourceExhaustedError`. + + + +- - - + +### class tf.errors.FailedPreconditionError <div class="md-anchor" id="FailedPreconditionError">{#FailedPreconditionError}</div> + +Operation was rejected because the system is not in a state to execute it. + +This exception is most commonly raised when running an operation +that reads a [`tf.Variable`](state_ops.md#Variable) before it has +been initialized. + +- - - + +#### tf.errors.FailedPreconditionError.__init__(node_def, op, message) {#FailedPreconditionError.__init__} + +Creates a `FailedPreconditionError`. + + + +- - - + +### class tf.errors.AbortedError <div class="md-anchor" id="AbortedError">{#AbortedError}</div> + +The operation was aborted, typically due to a concurrent action. + +For example, running a [`queue.enqueue()`](io_ops.md#QueueBase.enqueue) +operation may raise `AbortedError` if a +[`queue.close()`](io_ops.md@QueueBase.close) operation previously ran. + +- - - + +#### tf.errors.AbortedError.__init__(node_def, op, message) {#AbortedError.__init__} + +Creates an `AbortedError`. + + + +- - - + +### class tf.errors.OutOfRangeError <div class="md-anchor" id="OutOfRangeError">{#OutOfRangeError}</div> + +Raised when an operation executed past the valid range. + +This exception is raised in "end-of-file" conditions, such as when a +[`queue.dequeue()`](io_ops.md#QueueBase.dequeue) operation is +blocked on an empty queue, and a +[`queue.close()`](io_ops.md#QueueBase.close) operation executes. + +- - - + +#### tf.errors.OutOfRangeError.__init__(node_def, op, message) {#OutOfRangeError.__init__} + +Creates an `OutOfRangeError`. + + + +- - - + +### class tf.errors.UnimplementedError <div class="md-anchor" id="UnimplementedError">{#UnimplementedError}</div> + +Raised when an operation has not been implemented. + +Some operations may raise this error when passed otherwise-valid +arguments that it does not currently support. For example, running +the [`tf.nn.max_pool()`](nn.md#max_pool) operation would 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) {#UnimplementedError.__init__} + +Creates an `UnimplementedError`. + + + +- - - + +### class tf.errors.InternalError <div class="md-anchor" id="InternalError">{#InternalError}</div> + +Raised when the system experiences an internal error. + +This exception is raised when some invariant expected by the runtime +has been broken. Catching this exception is not recommended. + +- - - + +#### tf.errors.InternalError.__init__(node_def, op, message) {#InternalError.__init__} + +Creates an `InternalError`. + + + +- - - + +### class tf.errors.UnavailableError <div class="md-anchor" id="UnavailableError">{#UnavailableError}</div> + +Raised when the runtime is currently unavailable. + +This exception is not currently used. + +- - - + +#### tf.errors.UnavailableError.__init__(node_def, op, message) {#UnavailableError.__init__} + +Creates an `UnavailableError`. + + + +- - - + +### class tf.errors.DataLossError <div class="md-anchor" id="DataLossError">{#DataLossError}</div> + +Raised when unrecoverable data loss or corruption is encountered. + +For example, this may be raised by running a +[`tf.WholeFileReader.read()`](io_ops.md#WholeFileReader) operation, +if the file is truncated while it is being read. + +- - - + +#### tf.errors.DataLossError.__init__(node_def, op, message) {#DataLossError.__init__} + +Creates a `DataLossError`. + + + diff --git a/tensorflow/g3doc/api_docs/python/constant_op.md b/tensorflow/g3doc/api_docs/python/constant_op.md new file mode 100644 index 0000000000..34d2b511ab --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/constant_op.md @@ -0,0 +1,565 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Constants, Sequences, and Random Values +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Constant Value Tensors](#AUTOGENERATED-constant-value-tensors) + * [tf.zeros(shape, dtype=tf.float32, name=None)](#zeros) + * [tf.zeros_like(tensor, dtype=None, name=None)](#zeros_like) + * [tf.ones(shape, dtype=tf.float32, name=None)](#ones) + * [tf.ones_like(tensor, dtype=None, name=None)](#ones_like) + * [tf.fill(dims, value, name=None)](#fill) + * [tf.constant(value, dtype=None, shape=None, name='Const')](#constant) +* [Sequences](#AUTOGENERATED-sequences) + * [tf.linspace(start, stop, num, name=None)](#linspace) + * [tf.range(start, limit, delta=1, name='range')](#range) +* [Random Tensors](#AUTOGENERATED-random-tensors) + * [Examples:](#AUTOGENERATED-examples-) + * [tf.random_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None)](#random_normal) + * [tf.truncated_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None)](#truncated_normal) + * [tf.random_uniform(shape, minval=0.0, maxval=1.0, dtype=tf.float32, seed=None, name=None)](#random_uniform) + * [tf.random_shuffle(value, seed=None, name=None)](#random_shuffle) + * [tf.set_random_seed(seed)](#set_random_seed) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Constant Value Tensors <div class="md-anchor" id="AUTOGENERATED-constant-value-tensors">{#AUTOGENERATED-constant-value-tensors}</div> + +TensorFlow provides several operations that you can use to generate constants. + +- - - + +### tf.zeros(shape, dtype=tf.float32, name=None) <div class="md-anchor" id="zeros">{#zeros}</div> + +Creates a tensor with all elements set to zero. + +This operation returns a tensor of type `dtype` with shape `shape` and +all elements set to zero. + +For example: + +```python +tf.zeros([3, 4], int32) ==> [[0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]] +``` + +##### Args: + + +* <b>shape</b>: Either a list of integers, or a 1-D `Tensor` of type `int32`. +* <b>dtype</b>: The type of an element in the resulting `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to zero. + + +- - - + +### tf.zeros_like(tensor, dtype=None, name=None) <div class="md-anchor" id="zeros_like">{#zeros_like}</div> + +Creates a tensor with all elements set to zero. + +Given a single tensor (`tensor`), this operation returns a tensor of the +same type and shape as `tensor` with all elements set to zero. Optionally, +you can use `dtype` to specify a new type for the returned tensor. + +For example: + +```python +# 'tensor' is [[1, 2, 3], [4, 5, 6]] +tf.zeros_like(tensor) ==> [[0, 0, 0], [0, 0, 0]] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. +* <b>dtype</b>: A type for the returned `Tensor`. Must be `float32`, `float64`, + `int8`, `int16`, `int32`, `int64`, `uint8`, or `complex64`. + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to zero. + + + +- - - + +### tf.ones(shape, dtype=tf.float32, name=None) <div class="md-anchor" id="ones">{#ones}</div> + +Creates a tensor with all elements set to 1. + +This operation returns a tensor of type `dtype` with shape `shape` and all +elements set to 1. + +For example: + +```python +tf.ones([2, 3], int32) ==> [[1, 1, 1], [1, 1, 1]] +``` + +##### Args: + + +* <b>shape</b>: Either a list of integers, or a 1-D `Tensor` of type `int32`. +* <b>dtype</b>: The type of an element in the resulting `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to 1. + + +- - - + +### tf.ones_like(tensor, dtype=None, name=None) <div class="md-anchor" id="ones_like">{#ones_like}</div> + +Creates a tensor with all elements set to 1. + +Given a single tensor (`tensor`), this operation returns a tensor of the same +type and shape as `tensor` with all elements set to 1. Optionally, you can +specify a new type (`dtype`) for the returned tensor. + +For example: + +```python +# 'tensor' is [[1, 2, 3], [4, 5, 6]] +tf.ones_like(tensor) ==> [[1, 1, 1], [1, 1, 1]] +``` + +##### Args: + + +* <b>tensor</b>: A `Tensor`. +* <b>dtype</b>: A type for the returned `Tensor`. Must be `float32`, `float64`, + `int8`, `int16`, `int32`, `int64`, `uint8`, or `complex64`. + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with all elements set to 1. + + + +- - - + +### tf.fill(dims, value, name=None) <div class="md-anchor" id="fill">{#fill}</div> + +Creates a tensor filled with a scalar value. + +This operation creates a tensor of shape `dims` and fills it with `value`. + +For example: + +```prettyprint +# output tensor shape needs to be [2, 3] +# so 'dims' is [2, 3] +fill(dims, 9) ==> [[9, 9, 9] + [9, 9, 9]] +``` + +##### Args: + + +* <b>dims</b>: A `Tensor` of type `int32`. + 1-D. Represents the shape of the output tensor. +* <b>value</b>: A `Tensor`. 0-D (scalar). Value to fill the returned tensor. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `value`. + + + +- - - + +### tf.constant(value, dtype=None, shape=None, name='Const') <div class="md-anchor" id="constant">{#constant}</div> + +Creates a constant tensor. + + The resulting tensor is populated with values of type `dtype`, as + specified by arguments `value` and (optionally) `shape` (see examples + below). + + The argument `value` can be a constant value, or a list of values of type + `dtype`. If `value` is a list, then the length of the list must be less + than or equal to the number of elements implied by the `shape` argument (if + specified). In the case where the list length is less than the number of + elements specified by `shape`, the last element in the list will be used + to fill the remaining entries. + + The argument `shape` is optional. If present, it specifies the dimensions + of the resulting tensor. If not present, then the tensor is a scalar (0-D) + if `value` is a scalar, or 1-D otherwise. + + If the argument `dtype` is not specified, then the type is inferred from + the type of `value`. + + For example: + + ```python + # Constant 1-D Tensor populated with value list. + tensor = tf.constant([1, 2, 3, 4, 5, 6, 7]) => [1 2 3 4 5 6 7] + + # Constant 2-D tensor populated with scalar value -1. + tensor = tf.constant(-1.0, shape=[2, 3]) => [[-1. -1. -1.] + [-1. -1. -1.]] + ``` + +##### Args: + + +* <b>value</b>: A constant value (or list) of output type `dtype`. + + +* <b>dtype</b>: The type of the elements of the resulting tensor. + + +* <b>shape</b>: Optional dimensions of resulting tensor. + + +* <b>name</b>: Optional name for the tensor. + +##### Returns: + + A Constant Tensor. + + + +## Sequences <div class="md-anchor" id="AUTOGENERATED-sequences">{#AUTOGENERATED-sequences}</div> + +- - - + +### tf.linspace(start, stop, num, name=None) <div class="md-anchor" id="linspace">{#linspace}</div> + +Generates values in an interval. + +A sequence of `num` evenly-spaced values are generated beginning at `start`. +If `num > 1`, the values in the sequence increase by `stop - start / num - 1`, +so that the last one is exactly `stop`. + +For example: + +``` +tf.linspace(10.0, 12.0, 3, name="linspace") => [ 10.0 11.0 12.0] +``` + +##### Args: + + +* <b>start</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + First entry in the range. +* <b>stop</b>: A `Tensor`. Must have the same type as `start`. + Last entry in the range. +* <b>num</b>: A `Tensor` of type `int32`. Number of values to generate. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `start`. 1-D. The generated values. + + + +- - - + +### tf.range(start, limit, delta=1, name='range') <div class="md-anchor" id="range">{#range}</div> + +Creates a sequence of integers. + +This operation creates a sequence of integers that begins at `start` and +extends by increments of `delta` up to but not including `limit`. + +For example: + +``` +# 'start' is 3 +# 'limit' is 18 +# 'delta' is 3 +tf.range(start, limit, delta) ==> [3, 6, 9, 12, 15] +``` + +##### Args: + + +* <b>start</b>: A 0-D (scalar) of type `int32`. First entry in sequence. +* <b>limit</b>: A 0-D (scalar) of type `int32`. Upper limit of sequence, + exclusive. +* <b>delta</b>: A 0-D `Tensor` (scalar) of type `int32`. Optional. Default is 1. + Number that increments `start`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An 1-D `int32` `Tensor`. + + + +## Random Tensors <div class="md-anchor" id="AUTOGENERATED-random-tensors">{#AUTOGENERATED-random-tensors}</div> + +TensorFlow has several ops that create random tensors with different +distributions. The random ops are stateful, and create new random values each +time they are evaluated. + +The `seed` keyword argument in these functions acts in conjunction with +the graph-level random seed. Changing either the graph-level seed using +[`set_random_seed`](constant_op.md#set_random_seed) or the op-level seed +will change the underlying seed of these operations. Setting neither graph-level +nor op-level seed, results in a random seed for all operations. +See [`set_random_seed`](constant_op.md#set_random_seed) for details on the +interaction between operation-level and graph-level random seeds. + +### Examples: <div class="md-anchor" id="AUTOGENERATED-examples-">{#AUTOGENERATED-examples-}</div> + +```python +# Create a tensor of shape [2, 3] consisting of random normal values, with mean +# -1 and standard deviation 4. +norm = tf.random_normal([2, 3], mean=-1, stddev=4) + +# Shuffle the first dimension of a tensor +c = tf.constant([[1, 2], [3, 4], [5, 6]]) +shuff = tf.random_shuffle(c) + +# Each time we run these ops, different results are generated +sess = tf.Session() +print sess.run(norm) +print sess.run(norm) + +# Set an op-level seed to generate repeatable sequences across sessions. +c = tf.constant([[1, 2], [3, 4], [5, 6]]) +sess = tf.Session() +norm = tf.random_normal(c, seed=1234) +print sess.run(norm) +print sess.run(norm) +``` + +Another common use of random values is the intialization of variables. Also see +the [Variables How To](../../how_tos/variables/index.md). + +```python +# Use random uniform values in [0, 1) as the initializer for a variable of shape +# [2, 3]. The default type is float32. +var = tf.Variable(tf.random_uniform([2, 3]), name="var") +init = tf.initialize_all_variables() + +sess = tf.Session() +sess.run(init) +print sess.run(var) +``` + +- - - + +### tf.random_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None) <div class="md-anchor" id="random_normal">{#random_normal}</div> + +Outputs random values from a normal distribution. + +##### Args: + + +* <b>shape</b>: A 1-D integer Tensor or Python array. The shape of the output tensor. +* <b>mean</b>: A 0-D Tensor or Python value of type `dtype`. The mean of the normal + distribution. +* <b>stddev</b>: A 0-D Tensor or Python value of type `dtype`. The standard deviation + of the normal distribution. +* <b>dtype</b>: The type of the output. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of the specified shape filled with random normal values. + + +- - - + +### tf.truncated_normal(shape, mean=0.0, stddev=1.0, dtype=tf.float32, seed=None, name=None) <div class="md-anchor" id="truncated_normal">{#truncated_normal}</div> + +Outputs random values from a truncated normal distribution. + +The generated values follow a normal distribution with specified mean and +standard deviation, except that values whose magnitude is more than 2 standard +deviations from the mean are dropped and re-picked. + +##### Args: + + +* <b>shape</b>: A 1-D integer Tensor or Python array. The shape of the output tensor. +* <b>mean</b>: A 0-D Tensor or Python value of type `dtype`. The mean of the + truncated normal distribution. +* <b>stddev</b>: A 0-D Tensor or Python value of type `dtype`. The standard deviation + of the truncated normal distribution. +* <b>dtype</b>: The type of the output. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of the specified shape filled with random truncated normal values. + + +- - - + +### tf.random_uniform(shape, minval=0.0, maxval=1.0, dtype=tf.float32, seed=None, name=None) <div class="md-anchor" id="random_uniform">{#random_uniform}</div> + +Outputs random values from a uniform distribution. + +The generated values follow a uniform distribution in the range +`[minval, maxval)`. The lower bound `minval` is included in the range, while +the upper bound `maxval` is excluded. + +##### Args: + + +* <b>shape</b>: A 1-D integer Tensor or Python array. The shape of the output tensor. +* <b>minval</b>: A 0-D Tensor or Python value of type `dtype`. The lower bound on the + range of random values to generate. +* <b>maxval</b>: A 0-D Tensor or Python value of type `dtype`. The upper bound on + the range of random values to generate. +* <b>dtype</b>: The type of the output. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of the specified shape filled with random uniform values. + + +- - - + +### tf.random_shuffle(value, seed=None, name=None) <div class="md-anchor" id="random_shuffle">{#random_shuffle}</div> + +Randomly shuffles a tensor along its first dimension. + +The tensor is shuffled along dimension 0, such that each `value[j]` is mapped +to one and only one `output[i]`. For example, a mapping that might occur for a +3x2 tensor is: + +```python +[[1, 2], [[5, 6], + [3, 4], ==> [1, 2], + [5, 6]] [3, 4]] +``` + +##### Args: + + +* <b>value</b>: A Tensor to be shuffled. +* <b>seed</b>: A Python integer. Used to create a random seed for the distribution. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tensor of same shape and type as `value`, shuffled along its first + dimension. + + +- - - + +### tf.set_random_seed(seed) <div class="md-anchor" id="set_random_seed">{#set_random_seed}</div> + +Sets the graph-level random seed. + +Operations that rely on a random seed actually derive it from two seeds: +the graph-level and operation-level seeds. This sets the graph-level seed. + +Its interactions with operation-level seeds is as follows: + + 1. If neither the graph-level nor the operation seed is set: + A random seed is used for this op. + 2. If the graph-level seed is set, but the operation seed is not: + The system deterministically picks an operation seed in conjunction + with the graph-level seed so that it gets a unique random sequence. + 3. If the graph-level seed is not set, but the operation seed is set: + A default graph-level seed and the specified operation seed are used to + determine the random sequence. + 4. If both the graph-level and the operation seed are set: + Both seeds are used in conjunction to determine the random sequence. + +To illustrate the user-visible effects, consider these examples: + +To generate different sequences across sessions, set neither +graph-level nor op-level seeds: + +```python +a = tf.random_uniform([1]) +b = tf.random_normal([1]) + +print "Session 1" +with tf.Session() as sess1: + print sess1.run(a) # generates 'A1' + print sess1.run(a) # generates 'A2' + print sess1.run(b) # generates 'B1' + print sess1.run(b) # generates 'B2' + +print "Session 2" +with tf.Session() as sess2: + print sess2.run(a) # generates 'A3' + print sess2.run(a) # generates 'A4' + print sess2.run(b) # generates 'B3' + print sess2.run(b) # generates 'B4' +``` + +To generate the same repeatable sequence for an op across sessions, set the +seed for the op: + +```python +a = tf.random_uniform([1], seed=1) +b = tf.random_normal([1]) + +# Repeatedly running this block with the same graph will generate the same +# sequence of values for 'a', but different sequences of values for 'b'. +print "Session 1" +with tf.Session() as sess1: + print sess1.run(a) # generates 'A1' + print sess1.run(a) # generates 'A2' + print sess1.run(b) # generates 'B1' + print sess1.run(b) # generates 'B2' + +print "Session 2" +with tf.Session() as sess2: + print sess2.run(a) # generates 'A1' + print sess2.run(a) # generates 'A2' + print sess2.run(b) # generates 'B3' + print sess2.run(b) # generates 'B4' +``` + +To make the random sequences generated by all ops be repeatable across +sessions, set a graph-level seed: + +```python +tf.set_random_seed(1234) +a = tf.random_uniform([1]) +b = tf.random_normal([1]) + +# Repeatedly running this block with the same graph will generate different +# sequences of 'a' and 'b'. +print "Session 1" +with tf.Session() as sess1: + print sess1.run(a) # generates 'A1' + print sess1.run(a) # generates 'A2' + print sess1.run(b) # generates 'B1' + print sess1.run(b) # generates 'B2' + +print "Session 2" +with tf.Session() as sess2: + print sess2.run(a) # generates 'A1' + print sess2.run(a) # generates 'A2' + print sess2.run(b) # generates 'B1' + print sess2.run(b) # generates 'B2' +``` + +##### Args: + + +* <b>seed</b>: integer. + + diff --git a/tensorflow/g3doc/api_docs/python/control_flow_ops.md b/tensorflow/g3doc/api_docs/python/control_flow_ops.md new file mode 100644 index 0000000000..ad4321f01b --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/control_flow_ops.md @@ -0,0 +1,590 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Control Flow +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Control Flow Operations](#AUTOGENERATED-control-flow-operations) + * [tf.identity(input, name=None)](#identity) + * [tf.tuple(tensors, name=None, control_inputs=None)](#tuple) + * [tf.group(*inputs, **kwargs)](#group) + * [tf.no_op(name=None)](#no_op) + * [tf.count_up_to(ref, limit, name=None)](#count_up_to) +* [Logical Operators](#AUTOGENERATED-logical-operators) + * [tf.logical_and(x, y, name=None)](#logical_and) + * [tf.logical_not(x, name=None)](#logical_not) + * [tf.logical_or(x, y, name=None)](#logical_or) + * [tf.logical_xor(x, y, name='LogicalXor')](#logical_xor) +* [Comparison Operators](#AUTOGENERATED-comparison-operators) + * [tf.equal(x, y, name=None)](#equal) + * [tf.not_equal(x, y, name=None)](#not_equal) + * [tf.less(x, y, name=None)](#less) + * [tf.less_equal(x, y, name=None)](#less_equal) + * [tf.greater(x, y, name=None)](#greater) + * [tf.greater_equal(x, y, name=None)](#greater_equal) + * [tf.select(condition, t, e, name=None)](#select) + * [tf.where(input, name=None)](#where) +* [Debugging Operations](#AUTOGENERATED-debugging-operations) + * [tf.is_finite(x, name=None)](#is_finite) + * [tf.is_inf(x, name=None)](#is_inf) + * [tf.is_nan(x, name=None)](#is_nan) + * [tf.verify_tensor_all_finite(t, msg, name=None)](#verify_tensor_all_finite) + * [tf.check_numerics(tensor, message, name=None)](#check_numerics) + * [tf.add_check_numerics_ops()](#add_check_numerics_ops) + * [tf.Assert(condition, data, summarize=None, name=None)](#Assert) + * [tf.Print(input_, data, message=None, first_n=None, summarize=None, name=None)](#Print) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Control Flow Operations <div class="md-anchor" id="AUTOGENERATED-control-flow-operations">{#AUTOGENERATED-control-flow-operations}</div> + +TensorFlow provides several operations and classes that you can use to control +the execution of operations and add conditional dependencies to your graph. + +- - - + +### tf.identity(input, name=None) <div class="md-anchor" id="identity">{#identity}</div> + +Return a tensor with the same shape and contents as the input tensor or value. + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.tuple(tensors, name=None, control_inputs=None) <div class="md-anchor" id="tuple">{#tuple}</div> + +Group tensors together. + +This creates a tuple of tensors with the same values as the `tensors` +argument, except that the value of each tensor is only returned after the +values of all tensors have been computed. + +`control_inputs` contains additional ops that have to finish before this op +finishes, but whose outputs are not returned. + +This can be used as a "join" mechanism for parallel computations: all the +argument tensors can be computed in parallel, but the values of any tensor +returned by `tuple` are only available after all the parallel computations +are done. + +See also `group` and `with_dependencies`. + +##### Args: + + +* <b>tensors</b>: A list of `Tensor`s or `IndexedSlices`, some entries can be `None`. +* <b>name</b>: (optional) A name to use as a `name_scope` for the operation. +* <b>control_inputs</b>: List of additional ops to finish before returning. + +##### Returns: + + Same as `tensors`. + +##### Raises: + + +* <b>ValueError</b>: If `tensors` does not contain any `Tensor` or `IndexedSlices`. + + +- - - + +### tf.group(*inputs, **kwargs) <div class="md-anchor" id="group">{#group}</div> + +Create an op that groups multiple operations. + +When this op finishes, all ops in `input` have finished. This op has no +output. + +See also `tuple` and `with_dependencies`. + +##### Args: + + +* <b>*inputs</b>: One or more tensors to group. +* <b>**kwargs</b>: Optional parameters to pass when constructing the NodeDef. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + An Operation that executes all its inputs. + +##### Raises: + + +* <b>ValueError</b>: If an unknown keyword argument is provided, or if there are + no inputs. + + +- - - + +### tf.no_op(name=None) <div class="md-anchor" id="no_op">{#no_op}</div> + +Does nothing. Only useful as a placeholder for control edges. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +### tf.count_up_to(ref, limit, name=None) <div class="md-anchor" id="count_up_to">{#count_up_to}</div> + +Increments 'ref' until it reaches 'limit'. + +This operation outputs "ref" after the update is done. This makes it +easier to chain operations that need to use the updated value. + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Must be one of the following types: `int32`, `int64`. + Should be from a scalar `Variable` node. +* <b>limit</b>: An `int`. + If incrementing ref would bring it above limit, instead generates an + 'OutOfRange' error. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `ref`. + A copy of the input before increment. If nothing else modifies the + input, the values produced will all be distinct. + + + +## Logical Operators <div class="md-anchor" id="AUTOGENERATED-logical-operators">{#AUTOGENERATED-logical-operators}</div> + +TensorFlow provides several operations that you can use to add logical operators +to your graph. + +- - - + +### tf.logical_and(x, y, name=None) <div class="md-anchor" id="logical_and">{#logical_and}</div> + +Returns the truth value of x AND y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `bool`. +* <b>y</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.logical_not(x, name=None) <div class="md-anchor" id="logical_not">{#logical_not}</div> + +Returns the truth value of NOT x element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.logical_or(x, y, name=None) <div class="md-anchor" id="logical_or">{#logical_or}</div> + +Returns the truth value of x OR y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `bool`. +* <b>y</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.logical_xor(x, y, name='LogicalXor') <div class="md-anchor" id="logical_xor">{#logical_xor}</div> + +x ^ y = (x | y) & ~(x & y). + + + +## Comparison Operators <div class="md-anchor" id="AUTOGENERATED-comparison-operators">{#AUTOGENERATED-comparison-operators}</div> + +TensorFlow provides several operations that you can use to add comparison +operators to your graph. + +- - - + +### tf.equal(x, y, name=None) <div class="md-anchor" id="equal">{#equal}</div> + +Returns the truth value of (x == y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `complex64`, `quint8`, `qint8`, `qint32`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.not_equal(x, y, name=None) <div class="md-anchor" id="not_equal">{#not_equal}</div> + +Returns the truth value of (x != y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `complex64`, `quint8`, `qint8`, `qint32`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.less(x, y, name=None) <div class="md-anchor" id="less">{#less}</div> + +Returns the truth value of (x < y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.less_equal(x, y, name=None) <div class="md-anchor" id="less_equal">{#less_equal}</div> + +Returns the truth value of (x <= y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.greater(x, y, name=None) <div class="md-anchor" id="greater">{#greater}</div> + +Returns the truth value of (x > y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.greater_equal(x, y, name=None) <div class="md-anchor" id="greater_equal">{#greater_equal}</div> + +Returns the truth value of (x >= y) element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.select(condition, t, e, name=None) <div class="md-anchor" id="select">{#select}</div> + +Selects elements from `t` or `e`, depending on `condition`. + +The `condition`, `t`, and `e` tensors must all have the same shape, +and the output will also have that shape. The `condition` tensor acts +as an element-wise mask that chooses, based on the value at each +element, whether the corresponding element in the output should be +taken from `t` (if true) or `e` (if false). For example: + +For example: + +```prettyprint +# 'condition' tensor is [[True, False] +# [True, False]] +# 't' is [[1, 1], +# [1, 1]] +# 'e' is [[2, 2], +# [2, 2]] +select(condition, t, e) ==> [[1, 2], + [1, 2]] +``` + +##### Args: + + +* <b>condition</b>: A `Tensor` of type `bool`. +* <b>t</b>: A `Tensor` with the same shape as `condition`. +* <b>e</b>: A `Tensor` with the same type and shape as `t`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with the same type and shape as `t` and `e`. + + +- - - + +### tf.where(input, name=None) <div class="md-anchor" id="where">{#where}</div> + +Returns locations of true values in a boolean tensor. + +This operation returns the coordinates of true elements in `input`. The +coordinates are returned in a 2-D tensor where the first dimension (rows) +represents the number of true elements, and the second dimension (columns) +represents the coordinates of the true elements. Keep in mind, the shape of +the output tensor can vary depending on how many true values there are in +`input`. Indices are output in row-major order. + +For example: + +```prettyprint +# 'input' tensor is [[True, False] +# [True, False]] +# 'input' has two true values, so output has two coordinates. +# 'input' has rank of 2, so coordinates have two indices. +where(input) ==> [[0, 0], + [1, 0]] + +# `input` tensor is [[[True, False] +# [True, False]] +# [[False, True] +# [False, True]] +# [[False, False] +# [False, True]]] +# 'input' has 5 true values, so output has 5 coordinates. +# 'input' has rank of 3, so coordinates have three indices. +where(input) ==> [[0, 0, 0], + [0, 1, 0], + [1, 0, 1], + [1, 1, 1], + [2, 1, 1]] +``` + +##### Args: + + +* <b>input</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + + +## Debugging Operations <div class="md-anchor" id="AUTOGENERATED-debugging-operations">{#AUTOGENERATED-debugging-operations}</div> + +TensorFlow provides several operations that you can use to validate values and +debug your graph. + +- - - + +### tf.is_finite(x, name=None) <div class="md-anchor" id="is_finite">{#is_finite}</div> + +Returns which elements of x are finite. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.is_inf(x, name=None) <div class="md-anchor" id="is_inf">{#is_inf}</div> + +Returns which elements of x are Inf. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.is_nan(x, name=None) <div class="md-anchor" id="is_nan">{#is_nan}</div> + +Returns which elements of x are NaN. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. + + +- - - + +### tf.verify_tensor_all_finite(t, msg, name=None) <div class="md-anchor" id="verify_tensor_all_finite">{#verify_tensor_all_finite}</div> + +Assert that the tensor does not contain any NaN's or Inf's. + +##### Args: + + +* <b>t</b>: Tensor to check. +* <b>msg</b>: Message to log on failure. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + Same tensor as `t`. + + +- - - + +### tf.check_numerics(tensor, message, name=None) <div class="md-anchor" id="check_numerics">{#check_numerics}</div> + +Checks a tensor for NaN and Inf values. + +When run, reports an `InvalidArgument` error if `tensor` has any values +that are not a number (NaN) or infinity (Inf). Otherwise, passes `tensor` as-is. + +##### Args: + + +* <b>tensor</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>message</b>: A `string`. Prefix of the error message. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `tensor`. + + +- - - + +### tf.add_check_numerics_ops() <div class="md-anchor" id="add_check_numerics_ops">{#add_check_numerics_ops}</div> + +Connect a check_numerics to every floating point tensor. + +`check_numerics` operations themselves are added for each `float` or `double` +tensor in the graph. For all ops in the graph, the `check_numerics` op for +all of its (`float` or `double`) inputs is guaranteed to run before the +`check_numerics` op on any of its outputs. + +##### Returns: + + A `group` op depending on all `check_numerics` ops added. + + +- - - + +### tf.Assert(condition, data, summarize=None, name=None) <div class="md-anchor" id="Assert">{#Assert}</div> + +Asserts that the given condition is true. + +If `condition` evaluates to false, print the list of tensors in `data`. +`summarize` determines how many entries of the tensors to print. + +##### Args: + + +* <b>condition</b>: The condition to evaluate. +* <b>data</b>: The tensors to print out when condition is false. +* <b>summarize</b>: Print this many entries of each tensor. +* <b>name</b>: A name for this operation (optional). + + +- - - + +### tf.Print(input_, data, message=None, first_n=None, summarize=None, name=None) <div class="md-anchor" id="Print">{#Print}</div> + +Prints a list of tensors. + +This is an identity op with the side effect of printing `data` when +evaluating. + +##### Args: + + +* <b>input_</b>: A tensor passed through this op. +* <b>data</b>: A list of tensors to print out when op is evaluated. +* <b>message</b>: A string, prefix of the error message. +* <b>first_n</b>: Only log `first_n` number of times. Negative numbers log always; + this is the default. +* <b>summarize</b>: Only print this many entries of each tensor. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same tensor as `input_`. + + diff --git a/tensorflow/g3doc/api_docs/python/framework.md b/tensorflow/g3doc/api_docs/python/framework.md new file mode 100644 index 0000000000..e28daaa77a --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/framework.md @@ -0,0 +1,2079 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Building Graphs +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Core graph data structures](#AUTOGENERATED-core-graph-data-structures) + * [class tf.Graph](#Graph) + * [class tf.Operation](#Operation) + * [class tf.Tensor](#Tensor) +* [Tensor types](#AUTOGENERATED-tensor-types) + * [class tf.DType](#DType) + * [tf.as_dtype(type_value)](#as_dtype) +* [Utility functions](#AUTOGENERATED-utility-functions) + * [tf.device(dev)](#device) + * [tf.name_scope(name)](#name_scope) + * [tf.control_dependencies(control_inputs)](#control_dependencies) + * [tf.convert_to_tensor(value, dtype=None, name=None)](#convert_to_tensor) + * [tf.get_default_graph()](#get_default_graph) + * [tf.import_graph_def(graph_def, input_map=None, return_elements=None, name=None, op_dict=None)](#import_graph_def) +* [Graph collections](#AUTOGENERATED-graph-collections) + * [tf.add_to_collection(name, value)](#add_to_collection) + * [tf.get_collection(key, scope=None)](#get_collection) + * [class tf.GraphKeys](#GraphKeys) +* [Defining new operations](#AUTOGENERATED-defining-new-operations) + * [class tf.RegisterGradient](#RegisterGradient) + * [tf.NoGradient(op_type)](#NoGradient) + * [class tf.RegisterShape](#RegisterShape) + * [class tf.TensorShape](#TensorShape) + * [class tf.Dimension](#Dimension) + * [tf.op_scope(*args, **kwds)](#op_scope) + * [tf.get_seed(op_seed)](#get_seed) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +Import names from the framework library. + +## Core graph data structures <div class="md-anchor" id="AUTOGENERATED-core-graph-data-structures">{#AUTOGENERATED-core-graph-data-structures}</div> + +- - - + +### class tf.Graph <div class="md-anchor" id="Graph">{#Graph}</div> + +A TensorFlow computation, represented as a dataflow graph. + +A `Graph` contains a set of [`Operation`](framework.md#Operation) objects, +which represent units of computation; and [`Tensor`](framework.md#Tensor) +objects, which represent the units of data that flow between operations. + +A default `Graph` is always registered, and accessible by calling +[`tf.get_default_graph()`](framework.md#get_default_graph). To add an +operation to the default graph, simply call one of the functions that defines +a new `Operation`: + +``` +c = tf.constant(4.0) +assert c.graph is tf.get_default_graph() +``` + +Another typical usage involves the +[`Graph.as_default()`](framework.md#Graph.as_default) +context manager, which overrides the current default graph for the +lifetime of the context: + +```python +g = tf.Graph() +with g.as_default(): + # Define operations and tensors in `g`. + c = tf.constant(30.0) + assert c.graph is g +``` + +Important note: This class *is not* thread-safe for graph construction. All +operations should be created from a single thread, or external +synchronization must be provided. Unless otherwise specified, all methods +are not thread-safe. + +- - - + +#### tf.Graph.__init__() {#Graph.__init__} + +Creates a new, empty Graph. + + +- - - + +#### tf.Graph.as_default() {#Graph.as_default} + +Returns a context manager that makes this `Graph` the default graph. + +This method should be used if you want to create multiple graphs +in the same process. For convenience, a global default graph is +provided, and all ops will be added to this graph if you do not +create a new graph explicitly. Use this method the `with` keyword +to specify that ops created within the scope of a block should be +added to this graph. + +The default graph is a property of the current thread. If you +create a new thread, and wish to use the default graph in that +thread, you must explicitly add a `with g.as_default():` in that +thread's function. + +The following code examples are equivalent: + +```python +# 1. Using Graph.as_default(): +g = tf.Graph() +with g.as_default(): + c = tf.constant(5.0) + assert c.graph is g + +# 2. Constructing and making default: +with tf.Graph().as_default() as g: + c = tf.constant(5.0) + assert c.graph is g +``` + +##### Returns: + + A context manager for using this graph as the default graph. + + +- - - + +#### tf.Graph.as_graph_def(from_version=None) {#Graph.as_graph_def} + +Returns a serialized `GraphDef` representation of this graph. + +This method is thread-safe. + +##### Args: + + +* <b>from_version</b>: Optional. If this is set, returns a `GraphDef` + containing only the nodes that were added to this graph since + its `version` property had the given value. + +##### Returns: + + A + [`GraphDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/graph.proto) + protocol buffer. + + +- - - + +#### tf.Graph.finalize() {#Graph.finalize} + +Finalizes this graph, making it read-only. + +After calling `g.finalize()`, no new operations can be added to +`g`. This method is used to ensure that no operations are added +to a graph when it is shared between multiple threads, for example +when using a [`QueueRunner`](train.md#QueueRunner). + + +- - - + +#### tf.Graph.finalized {#Graph.finalized} + +True if this graph has been finalized. + + +- - - + +#### tf.Graph.control_dependencies(control_inputs) {#Graph.control_dependencies} + +Returns a context manager that specifies control dependencies. + +Use with the `with` keyword to specify that all operations constructed +within the context should have control dependencies on +`control_inputs`. For example: + +```python +with g.control_dependencies([a, b, c]): + # `d` and `e` will only run after `a`, `b`, and `c` have executed. + d = ... + e = ... +``` + +Multiple calls to `control_dependencies()` can be nested, and in +that case a new `Operation` will have control dependencies on the union +of `control_inputs` from all active contexts. + +```python +with g.control_dependencies([a, b]): + # Ops declared here run after `a` and `b`. + with g.control_dependencies([c, d]): + # Ops declared here run after `a`, `b`, `c`, and `d`. +``` + +*N.B.* The control dependencies context applies *only* to ops that +are constructed within the context. Merely using an op or tensor +in the context does not add a control dependency. The following +example illustrates this point: + +```python +# WRONG +def my_func(pred, tensor): + t = tf.matmul(tensor, tensor) + with tf.control_dependencies([pred]): + # The matmul op is created outside the context, so no control + # dependency will be added. + return t + +# RIGHT +def my_func(pred, tensor): + with tf.control_dependencies([pred]): + # The matmul op is created in the context, so a control dependency + # will be added. + return tf.matmul(tensor, tensor) +``` + +##### Args: + + +* <b>control_inputs</b>: A list of `Operation` or `Tensor` objects, which + must be executed or computed before running the operations + defined in the context. + +##### Returns: + + A context manager that specifies control dependencies for all + operations constructed within the context. + +##### Raises: + + +* <b>TypeError</b>: If `control_inputs` is not a list of `Operation` or + `Tensor` objects. + + +- - - + +#### tf.Graph.device(*args, **kwds) {#Graph.device} + +Returns a context manager that specifies the default device to use. + +The `device_name_or_function` argument may either be a device name +string, a device function, or None: + +* If it is a device name string, all operations constructed in + this context will be assigned to the device with that name. +* If it is a function, it will be treated as function from + Operation objects to device name strings, and invoked each time + a new Operation is created. The Operation will be assigned to + the device with the returned name. +* If it is None, the default device will be cleared. + +For example: + +```python +with g.device('/gpu:0'): + # All operations constructed in this context will be placed + # on GPU 0. + with g.device(None): + # All operations constructed in this context will have no + # assigned device. + +# Defines a function from `Operation` to device string. +def matmul_on_gpu(n): + if n.type == "MatMul": + return "/gpu:0" + else: + return "/cpu:0" + +with g.device(matmul_on_gpu): + # All operations of type "MatMul" constructed in this context + # will be placed on GPU 0; all other operations will be placed + # on CPU 0. +``` + +##### Args: + + +* <b>device_name_or_function</b>: The device name or function to use in + the context. + +##### Returns: + + A context manager that specifies the default device to use for newly + created ops. + + +- - - + +#### tf.Graph.name_scope(*args, **kwds) {#Graph.name_scope} + +Returns a context manager that creates hierarchical names for operations. + +A graph maintains a stack of name scopes. A `with name_scope(...):` +statement pushes a new name onto the stack for the lifetime of the context. + +The `name` argument will be interpreted as follows: + +* A string (not ending with '/') will create a new name scope, in which + `name` is appended to the prefix of all operations created in the + context. If `name` has been used before, it will be made unique by + calling `self.unique_name(name)`. +* A scope previously captured from a `with g.name_scope(...) as + scope:` statement will be treated as an "absolute" name scope, which + makes it possible to re-enter existing scopes. +* A value of `None` or the empty string will reset the current name scope + to the top-level (empty) name scope. + +For example: + +```python +with tf.Graph().as_default() as g: + c = tf.constant(5.0, name="c") + assert c_1.name == "c" + c_1 = tf.constant(6.0, name="c") + assert c_1.name == "c_1" + + # Creates a scope called "nested" + with g.name_scope("nested") as scope: + nested_c = tf.constant(10.0, name="c") + assert nested_c.name == "nested/c" + + # Creates a nested scope called "inner". + with g.name_scope("inner"): + nested_inner_c = tf.constant(20.0, name="c") + assert nested_inner_c.name == "nested/inner/c" + + # Create a nested scope called "inner_1". + with g.name_scope("inner"): + nested_inner_1_c = tf.constant(30.0, name="c") + assert nested_inner_1_c.name == "nested/inner_1/c" + + # Treats `scope` as an absolute name scope, and + # switches to the "nested/" scope. + with g.name_scope(scope): + nested_d = tf.constant(40.0, name="d") + assert nested_d.name == "nested/d" + + with g.name_scope(""): + e = tf.constant(50.0, name="e") + assert e.name == "e" +``` + +The name of the scope itself can be captured by `with +g.name_scope(...) as scope:`, which stores the name of the scope +in the variable `scope`. This value can be used to name an +operation that represents the overall result of executing the ops +in a scope. For example: + +```python +inputs = tf.constant(...) +with g.name_scope('my_layer') as scope: + weights = tf.Variable(..., name="weights") + biases = tf.Variable(..., name="biases") + affine = tf.matmul(inputs, weights) + biases + output = tf.nn.relu(affine, name=scope) +``` + + +##### Args: + + +* <b>name</b>: A name for the scope. + +##### Returns: + + A context manager that installs `name` as a new name scope. + + + +A `Graph` instance supports an arbitrary number of "collections" +that are identified by name. For convenience when building a large +graph, collections can store groups of related objects: for +example, the `tf.Variable` uses a collection (named +[`tf.GraphKeys.VARIABLES`](framework.md#GraphKeys)) for all variables that are +created during the construction of a graph. The caller may define +additional collections by specifying a new name. + +- - - + +#### tf.Graph.add_to_collection(name, value) {#Graph.add_to_collection} + +Stores `value` in the collection with the given `name`. + +##### Args: + + +* <b>name</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>value</b>: The value to add to the collection. + + +- - - + +#### tf.Graph.get_collection(name, scope=None) {#Graph.get_collection} + +Returns a list of values in the collection with the given `name`. + +##### Args: + + +* <b>key</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>scope</b>: (Optional.) If supplied, the resulting list is filtered to include + only items whose name begins with this string. + +##### Returns: + + The list of values in the collection with the given `name`, or + an empty list if no value has been added to that collection. The + list contains the values in the order under which they were + collected. + + + +- - - + +#### tf.Graph.as_graph_element(obj, allow_tensor=True, allow_operation=True) {#Graph.as_graph_element} + +Returns the object referred to by `obj`, as an `Operation` or `Tensor`. + +This function validates that `obj` represents an element of this +graph, and gives an informative error message if it is not. + +This function is the canonical way to get/validate an object of +one of the allowed types from an external argument reference in the +Session API. + +This method may be called concurrently from multiple threads. + +##### Args: + + +* <b>obj</b>: A `Tensor`, an `Operation`, or the name of a tensor or operation. + Can also be any object with an `_as_graph_element()` method that returns + a value of one of these types. +* <b>allow_tensor</b>: If true, `obj` may refer to a `Tensor`. +* <b>allow_operation</b>: If true, `obj` may refer to an `Operation`. + +##### Returns: + + The `Tensor` or `Operation` in the Graph corresponding to `obj`. + +##### Raises: + + +* <b>TypeError</b>: If `obj` is not a type we support attempting to convert + to types. +* <b>ValueError</b>: If `obj` is of an appropriate type but invalid. For + example, an invalid string. +* <b>KeyError</b>: If `obj` is not an object in the graph. + + +- - - + +#### tf.Graph.get_operation_by_name(name) {#Graph.get_operation_by_name} + +Returns the `Operation` with the given `name`. + +This method may be called concurrently from multiple threads. + +##### Args: + + +* <b>name</b>: The name of the `Operation` to return. + +##### Returns: + + The `Operation` with the given `name`. + +##### Raises: + + +* <b>TypeError</b>: If `name` is not a string. +* <b>KeyError</b>: If `name` does not correspond to an operation in this graph. + + +- - - + +#### tf.Graph.get_tensor_by_name(name) {#Graph.get_tensor_by_name} + +Returns the `Tensor` with the given `name`. + +This method may be called concurrently from multiple threads. + +##### Args: + + +* <b>name</b>: The name of the `Tensor` to return. + +##### Returns: + + The `Tensor` with the given `name`. + +##### Raises: + + +* <b>TypeError</b>: If `name` is not a string. +* <b>KeyError</b>: If `name` does not correspond to a tensor in this graph. + + +- - - + +#### tf.Graph.get_operations() {#Graph.get_operations} + +Return the list of operations in the graph. + +You can modify the operations in place, but modifications +to the list such as inserts/delete have no effect on the +list of operations known to the graph. + +This method may be called concurrently from multiple threads. + +##### Returns: + + A list of Operations. + + + +- - - + +#### tf.Graph.get_default_device() {#Graph.get_default_device} + +Returns the default device. + +##### Returns: + + A string. + + +- - - + +#### tf.Graph.seed {#Graph.seed} + + + +- - - + +#### tf.Graph.unique_name(name) {#Graph.unique_name} + +Return a unique Operation name for "name". + +Note: You rarely need to call unique_name() directly. Most of the time you +just need to create "with g.name_scope()" blocks to generate structured +names. + +`unique_name` is used to generate structured names, separated by "/", +to help identify Operations when debugging a Graph. Operation names +are displayed in error messages reported by the TensorFlow runtime, +and in various visualization tools such as TensorBoard. + +##### Args: + + +* <b>name</b>: The name for an `Operation`. + +##### Returns: + + A string to be passed to `create_op()` that will be used + to name the operation being created. + + +- - - + +#### tf.Graph.version {#Graph.version} + +Returns a version number that increases as ops are added to the graph. + + +- - - + +#### tf.Graph.create_op(op_type, inputs, dtypes, input_types=None, name=None, attrs=None, op_def=None, compute_shapes=True) {#Graph.create_op} + +Creates an `Operation` in this graph. + +This is a low-level interface for creating an `Operation`. Most +programs will not call this method directly, and instead use the +Python op constructors, such as `tf.constant()`, which add ops to +the default graph. + +##### Args: + + +* <b>op_type</b>: The `Operation` type to create. This corresponds to the + `OpDef.name` field for the proto that defines the operation. +* <b>inputs</b>: A list of `Tensor` objects that will be inputs to the `Operation`. +* <b>dtypes</b>: A list of `DType` objects that will be the types of the tensors + that the operation produces. +* <b>input_types</b>: (Optional.) A list of `DType`s that will be the types of + the tensors that the operation consumes. By default, uses the base + `DType` of each input in `inputs`. Operations that expect + reference-typed inputs must specify `input_types` explicitly. +* <b>name</b>: (Optional.) A string name for the operation. If not specified, a + name is generated based on `op_type`. +* <b>attrs</b>: (Optional.) A list of `AttrValue` protos for the `attr` field of + the `NodeDef` proto that will represent the operation. +* <b>op_def</b>: (Optional.) The `OpDef` proto that describes the `op_type` that + the operation will have. +* <b>compute_shapes</b>: (Optional.) If True, shape inference will be performed + to compute the shapes of the outputs. + +##### Raises: + + +* <b>TypeError</b>: if any of the inputs is not a `Tensor`. + +##### Returns: + + An `Operation` object. + + +- - - + +#### tf.Graph.gradient_override_map(*args, **kwds) {#Graph.gradient_override_map} + +EXPERIMENTAL: A context manager for overriding gradient functions. + +This context manager can be used to override the gradient function +that will be used for ops within the scope of the context. + +For example: + +```python +@tf.RegisterGradient("CustomSquare") +def _custom_square_grad(op, inputs): + # ... + +with tf.Graph().as_default() as g: + c = tf.constant(5.0) + s_1 = tf.square(c) # Uses the default gradient for tf.square. + with g.gradient_override_map({"Square": "CustomSquare"}): + s_2 = tf.square(s_2) # Uses _custom_square_grad to compute the + # gradient of s_2. +``` + +##### Args: + + +* <b>op_type_map</b>: A dictionary mapping op type strings to alternative op + type strings. + +##### Returns: + + A context manager that sets the alternative op type to be used for one + or more ops created in that context. + +##### Raises: + + +* <b>TypeError</b>: If `op_type_map` is not a dictionary mapping strings to + strings. + + + +- - - + +### class tf.Operation <div class="md-anchor" id="Operation">{#Operation}</div> + +Represents a graph node that performs computation on tensors. + +An `Operation` is a node in a TensorFlow `Graph` that takes zero or +more `Tensor` objects as input, and produces zero or more `Tensor` +objects as output. Objects of type `Operation` are created by +calling a Python op constructor (such as [`tf.matmul()`](math_ops.md#matmul)) +or [`Graph.create_op()`](framework.md#Graph.create_op). + +For example `c = tf.matmul(a, b)` creates an `Operation` of type +"MatMul" that takes tensors `a` and `b` as input, and produces `c` +as output. + +After the graph has been launched in a session, an `Operation` can +be executed by passing it to [`Session.run()`](client.md#Session.run). +`op.run()` is a shortcut for calling `tf.get_default_session().run(op)`. + +- - - + +#### tf.Operation.name {#Operation.name} + +The full name of this operation. + +- - - + +#### tf.Operation.type {#Operation.type} + +The type of the op (e.g. `"MatMul"`). + +- - - + +#### tf.Operation.inputs {#Operation.inputs} + +The list of `Tensor` objects representing the data inputs of this op. + +- - - + +#### tf.Operation.control_inputs {#Operation.control_inputs} + +The `Operation` objects on which this op has a control dependency. + +Before this op is executed, TensorFlow will ensure that the +operations in `self.control_inputs` have finished executing. This +mechanism can be used to run ops sequentially for performance +reasons, or to ensure that the side effects of an op are observed +in the correct order. + +##### Returns: + + A list of `Operation` objects. + +- - - + +#### tf.Operation.outputs {#Operation.outputs} + +The list of `Tensor` objects representing the outputs of this op. + +- - - + +#### tf.Operation.device {#Operation.device} + +The name of the device to which this op has been assigned, if any. + +##### Returns: + + The string name of the device to which this op has been + assigned, or None if it has not been assigned to a device. + +- - - + +#### tf.Operation.graph {#Operation.graph} + +The `Graph` that contains this operation. + + +- - - + +#### tf.Operation.run(feed_dict=None, session=None) {#Operation.run} + +Runs this operation in a `Session`. + +Calling this method will execute all preceding operations that +produce the inputs needed for this operation. + +*N.B.* Before invoking `Operation.run()`, its graph must have been +launched in a session, and either a default session must be +available, or `session` must be specified explicitly. + +##### Args: + + +* <b>feed_dict</b>: A dictionary that maps `Tensor` objects to feed values. + See [`Session.run()`](client.md#Session.run) for a description of the + valid feed values. +* <b>session</b>: (Optional.) The `Session` to be used to run to this operation. If + none, the default session will be used. + + + +- - - + +#### tf.Operation.get_attr(name) {#Operation.get_attr} + +Returns the value of the attr of this op with the given `name`. + +##### Args: + + +* <b>name</b>: The name of the attr to fetch. + +##### Returns: + + The value of the attr, as a Python object. + +##### Raises: + + +* <b>ValueError</b>: If this op does not have an attr with the given `name`. + + +- - - + +#### tf.Operation.traceback {#Operation.traceback} + +Returns the call stack from when this operation was constructed. + + +#### Other Methods +- - - + +#### tf.Operation.__init__(node_def, g, inputs=None, output_types=None, control_inputs=None, input_types=None, original_op=None, op_def=None) {#Operation.__init__} + +Creates an `Operation`. + +NOTE: This constructor validates the name of the Operation (passed +as "node_def.name"). Valid Operation names match the following +regular expression: + + [A-Za-z0-9.][A-Za-z0-9_.\-/]* + +##### Args: + + +* <b>node_def</b>: graph_pb2.NodeDef. NodeDef for the Operation. + Used for attributes of graph_pb2.NodeDef, typically "name", + "op", and "device". The "input" attribute is irrelevant here + as it will be computed when generating the model. +* <b>g</b>: Graph. The parent graph. +* <b>inputs</b>: list of Tensor objects. The inputs to this Operation. +* <b>output_types</b>: list of types_pb2.DataType. List of the types of the + Tensors computed by this operation. The length of this list indicates + the number of output endpoints of the Operation. +* <b>control_inputs</b>: list of operations or tensors from which to have a + control dependency. +* <b>input_types</b>: List of types_pb2.DataType representing the + types of the Tensors accepted by the Operation. By default + uses [x.dtype.base_dtype for x in inputs]. Operations that expect + reference-typed inputs must specify these explicitly. +* <b>original_op</b>: Optional. Used to associate the new Operation with an + existing Operation (for example, a replica with the op that was + replicated). +* <b>op_def</b>: Optional. The op_def_pb2.OpDef proto that describes the + op type that this Operation represents. + +##### Raises: + + +* <b>TypeError</b>: if control inputs are not Operations or Tensors, + or if node_def is not a NodeDef, + or if g is not a Graph, + or if inputs are not Tensors, + or if inputs and input_types are incompatible. +* <b>ValueError</b>: if the node_def name is not valid. + + +- - - + +#### tf.Operation.node_def {#Operation.node_def} + +Returns a serialized `NodeDef` representation of this operation. + +##### Returns: + + A + [`NodeDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/graph.proto) + protocol buffer. + +- - - + +#### tf.Operation.op_def {#Operation.op_def} + +Returns the `OpDef` proto that represents the type of this op. + +##### Returns: + + An + [`OpDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/op_def.proto) + protocol buffer. + +- - - + +#### tf.Operation.values() {#Operation.values} + +DEPRECATED: Use outputs. + + + +- - - + +### class tf.Tensor <div class="md-anchor" id="Tensor">{#Tensor}</div> + +Represents a value produced by an `Operation`. + +A `Tensor` is a symbolic handle to one of the outputs of an +`Operation`. It does not hold the values of that operation's output, +but instead provides a means of computing those values in a +TensorFlow [`Session`](client.md#Session). + +This class has two primary purposes: + +1. A `Tensor` can be passed as an input to another `Operation`. + This builds a dataflow connection between operations, which + enables TensorFlow to execute an entire `Graph` that represents a + large, multi-step computation. + +2. After the graph has been launched in a session, the value of the + `Tensor` can be computed by passing it to + [`Session.run()`](client.md#Session.run). + `t.eval()` is a shortcut for calling + `tf.get_default_session().run(t)`. + +In the following example, `c`, `d`, and `e` are symbolic `Tensor` +objects, whereas `result` is a numpy array that stores a concrete +value: + +```python +# Build a dataflow graph. +c = tf.constant([[1.0, 2.0], [3.0, 4.0]]) +d = tf.constant([[1.0, 1.0], [0.0, 1.0]]) +e = tf.matmul(c, d) + +# Construct a `Session` to execut the graph. +sess = tf.Session() + +# Execute the graph and store the value that `e` represents in `result`. +result = sess.run(e) +``` + +- - - + +#### tf.Tensor.dtype {#Tensor.dtype} + +The `DType` of elements in this tensor. + +- - - + +#### tf.Tensor.name {#Tensor.name} + +The string name of this tensor. + +- - - + +#### tf.Tensor.value_index {#Tensor.value_index} + +The index of this tensor in the outputs of its `Operation`. + +- - - + +#### tf.Tensor.graph {#Tensor.graph} + +The `Graph` that contains this tensor. + +- - - + +#### tf.Tensor.op {#Tensor.op} + +The `Operation` that produces this tensor as an output. + +- - - + +#### tf.Tensor.consumers() {#Tensor.consumers} + +Returns a list of `Operation`s that consume this tensor. + +##### Returns: + + A list of `Operation`s. + + + +- - - + +#### tf.Tensor.eval(feed_dict=None, session=None) {#Tensor.eval} + +Evaluates this tensor in a `Session`. + +Calling this method will execute all preceding operations that +produce the inputs needed for the operation that produces this +tensor. + +*N.B.* Before invoking `Tensor.eval()`, its graph must have been +launched in a session, and either a default session must be +available, or `session` must be specified explicitly. + +##### Args: + + +* <b>feed_dict</b>: A dictionary that maps `Tensor` objects to feed values. + See [`Session.run()`](client.md#Session.run) for a description of + the valid feed values. +* <b>session</b>: (Optional.) The `Session` to be used to evaluate this tensor. If + none, the default session will be used. + +##### Returns: + + A numpy array corresponding to the value of this tensor. + + + +- - - + +#### tf.Tensor.get_shape() {#Tensor.get_shape} + +Returns the `TensorShape` that represents the shape of this tensor. + +The shape is computed using shape inference functions that are +registered for each `Operation` type using `tf.RegisterShape`. +See [`TensorShape`](framework.md#TensorShape) for more details of what a shape +represents. + +The inferred shape of a tensor is used to provide shape +information without having to launch the graph in a session. This +can be used for debugging, and providing early error messages. For +example: + +```python +c = tf.constant([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]) + +print c.get_shape() +==> TensorShape([Dimension(2), Dimension(3)]) + +d = tf.constant([[1.0, 0.0], [0.0, 1.0], [1.0, 0.0], [0.0, 1.0]]) + +print d.get_shape() +==> TensorShape([Dimension(4), Dimension(2)]) + +# Raises a ValueError, because `c` and `d` do not have compatible +# inner dimensions. +e = tf.matmul(c, d) + +f = tf.matmul(c, d, transpose_a=True, transpose_b=True) + +print f.get_shape() +==> TensorShape([Dimension(3), Dimension(4)]) +``` + +In some cases, the inferred shape may have unknown dimensions. If +the caller has additional information about the values of these +dimensions, `Tensor.set_shape()` can be used to augment the +inferred shape. + +##### Returns: + + A `TensorShape` representing the shape of this tensor. + + +- - - + +#### tf.Tensor.set_shape(shape) {#Tensor.set_shape} + +Updates the shape of this tensor. + +This method can be called multiple times, and will merge the given +`shape` with the current shape of this tensor. It can be used to +provide additional information about the shape of this tensor that +cannot be inferred from the graph alone. For example, this can be used +to provide additional information about the shapes of images: + +```python +_, image_data = tf.TFRecordReader(...).read(...) +image = tf.image.decode_png(image_data, channels=3) + +# The height and width dimensions of `image` are data dependent, and +# cannot be computed without executing the op. +print image.get_shape() +==> TensorShape([Dimension(None), Dimension(None), Dimension(3)]) + +# We know that each image in this dataset is 28 x 28 pixels. +image.set_shape([28, 28, 3]) +print image.get_shape() +==> TensorShape([Dimension(28), Dimension(28), Dimension(3)]) +``` + +##### Args: + + +* <b>shape</b>: A `TensorShape` representing the shape of this tensor. + +##### Raises: + + +* <b>ValueError</b>: If `shape` is not compatible with the current shape of + this tensor. + + + +#### Other Methods +- - - + +#### tf.Tensor.__init__(op, value_index, dtype) {#Tensor.__init__} + +Creates a new `Tensor`. + +##### Args: + + +* <b>op</b>: An `Operation`. `Operation` that computes this tensor. +* <b>value_index</b>: An `int`. Index of the operation's endpoint that produces + this tensor. +* <b>dtype</b>: A `types.DType`. Type of data stored in this tensor. + +##### Raises: + + +* <b>TypeError</b>: If the op is not an `Operation`. + + +- - - + +#### tf.Tensor.device {#Tensor.device} + +The name of the device on which this tensor will be produced, or None. + + + +## Tensor types <div class="md-anchor" id="AUTOGENERATED-tensor-types">{#AUTOGENERATED-tensor-types}</div> + +- - - + +### class tf.DType <div class="md-anchor" id="DType">{#DType}</div> + +Represents the type of the elements in a `Tensor`. + +The following `DType` objects are defined: + +* `tf.float32`: 32-bit single-precision floating-point. +* `tf.float64`: 64-bit double-precision floating-point. +* `tf.bfloat16`: 16-bit truncated floating-point. +* `tf.complex64`: 64-bit single-precision complex. + +* `tf.int8`: 8-bit signed integer. +* `tf.uint8`: 8-bit unsigned integer. +* `tf.int32`: 32-bit signed integer. +* `tf.int64`: 64-bit signed integer. + +* `tf.bool`: Boolean. + +* `tf.string`: String. + +* `tf.qint8`: Quantized 8-bit signed integer. +* `tf.quint8`: Quantized 8-bit unsigned integer. +* `tf.qint32`: Quantized 32-bit signed integer. + +In addition, variants of these types with the `_ref` suffix are +defined for reference-typed tensors. + +The `tf.as_dtype()` function converts numpy types and string type +names to a `DType` object. + +- - - + +#### tf.DType.is_compatible_with(other) {#DType.is_compatible_with} + +Returns True if the `other` DType will be converted to this DType. + +The conversion rules are as follows: + +``` +DType(T) .is_compatible_with(DType(T)) == True +DType(T) .is_compatible_with(DType(T).as_ref) == True +DType(T).as_ref.is_compatible_with(DType(T)) == False +DType(T).as_ref.is_compatible_with(DType(T).as_ref) == True +``` + +##### Args: + + +* <b>other</b>: A `DType` (or object that may be converted to a `DType`). + +##### Returns: + + True if a Tensor of the `other` `DType` will be implicitly converted to + this `DType`. + + +- - - + +#### tf.DType.name {#DType.name} + +Returns the string name for this `DType`. + +- - - + +#### tf.DType.base_dtype {#DType.base_dtype} + +Returns a non-reference `DType` based on this `DType`. + +- - - + +#### tf.DType.is_ref_dtype {#DType.is_ref_dtype} + +Returns `True` if this `DType` represents a reference type. + +- - - + +#### tf.DType.as_ref {#DType.as_ref} + +Returns a reference `DType` based on this `DType`. + +- - - + +#### tf.DType.is_integer {#DType.is_integer} + +Returns whether this is a (non-quantized) integer type. + +- - - + +#### tf.DType.is_quantized {#DType.is_quantized} + +Returns whether this is a quantized data type. + + +- - - + +#### tf.DType.as_numpy_dtype {#DType.as_numpy_dtype} + +Returns a `numpy.dtype` based on this `DType`. + +- - - + +#### tf.DType.as_datatype_enum {#DType.as_datatype_enum} + +Returns a `types_pb2.DataType` enum value based on this `DType`. + + +#### Other Methods +- - - + +#### tf.DType.__init__(type_enum) {#DType.__init__} + +Creates a new `DataType`. + +NOTE(mrry): In normal circumstances, you should not need to +construct a DataType object directly. Instead, use the +types.as_dtype() function. + +##### Args: + + +* <b>type_enum</b>: A `types_pb2.DataType` enum value. + +##### Raises: + + +* <b>TypeError</b>: If `type_enum` is not a value `types_pb2.DataType`. + + +- - - + +#### tf.DType.max {#DType.max} + +Returns the maximum representable value in this data type. + +##### Raises: + + +* <b>TypeError</b>: if this is a non-numeric, unordered, or quantized type. + +- - - + +#### tf.DType.min {#DType.min} + +Returns the minimum representable value in this data type. + +##### Raises: + + +* <b>TypeError</b>: if this is a non-numeric, unordered, or quantized type. + + +- - - + +### tf.as_dtype(type_value) <div class="md-anchor" id="as_dtype">{#as_dtype}</div> + +Converts the given `type_value` to a `DType`. + +##### Args: + + +* <b>type_value</b>: A value that can be converted to a `tf.DType` + object. This may currently be a `tf.DType` object, a + [`DataType` enum](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/types.proto), + a string type name, or a `numpy.dtype`. + +##### Returns: + + A `DType` corresponding to `type_value`. + +##### Raises: + + +* <b>TypeError</b>: If `type_value` cannot be converted to a `DType`. + + + +## Utility functions <div class="md-anchor" id="AUTOGENERATED-utility-functions">{#AUTOGENERATED-utility-functions}</div> + +- - - + +### tf.device(dev) <div class="md-anchor" id="device">{#device}</div> + +Wrapper for `Graph.device()` using the default graph. + +See [`Graph.name_scope()`](framework.md#Graph.name_scope) for more details. + +##### Args: + + +* <b>device_name_or_function</b>: The device name or function to use in + the context. + +##### Returns: + + A context manager that specifies the default device to use for newly + created ops. + + +- - - + +### tf.name_scope(name) <div class="md-anchor" id="name_scope">{#name_scope}</div> + +Wrapper for `Graph.name_scope()` using the default graph. + +See [`Graph.name_scope()`](framework.md#Graph.name_scope) for more details. + +##### Args: + + +* <b>name</b>: A name for the scope. + +##### Returns: + + A context manager that installs `name` as a new name scope in the + default graph. + + +- - - + +### tf.control_dependencies(control_inputs) <div class="md-anchor" id="control_dependencies">{#control_dependencies}</div> + +Wrapper for `Graph.control_dependencies()` using the default graph. + +See [`Graph.control_dependencies()`](framework.md#Graph.control_dependencies) +for more details. + +##### Args: + + +* <b>control_inputs</b>: A list of `Operation` or `Tensor` objects, which + must be executed or computed before running the operations + defined in the context. + +##### Returns: + + A context manager that specifies control dependencies for all + operations constructed within the context. + + +- - - + +### tf.convert_to_tensor(value, dtype=None, name=None) <div class="md-anchor" id="convert_to_tensor">{#convert_to_tensor}</div> + +Converts the given `value` to a `Tensor`. + +This function converts Python objects of various types to `Tensor` +objects. It accepts `Tensor` objects, numpy arrays, Python lists, +and Python scalars. For example: + +```python +import numpy as np +array = np.random.rand((32, 100, 100)) + +def my_func(arg): + arg = tf.convert_to_tensor(arg, dtype=tf.float32) + return tf.matmul(arg, arg) + arg + +# The following calls are equivalent. +value_1 = my_func(tf.constant([[1.0, 2.0], [3.0, 4.0])) +value_2 = my_func([[1.0, 2.0], [3.0, 4.0]]) +value_3 = my_func(numpy.array([[1.0, 2.0], [3.0, 4.0]], dtype=numpy.float32)) +``` + +This function can be useful when composing a new operation in Python +(such as `my_func` in the example above). All standard Python op +constructors apply this function to each of their Tensor-valued +inputs, which allows those ops to accept numpy arrays, Python lists, +and scalars in addition to `Tensor` objects. + +##### Args: + + +* <b>value</b>: An object whose type has a registered `Tensor` conversion function. +* <b>dtype</b>: Optional element type for the returned tensor. If missing, the + type is inferred from the type of `value`. +* <b>name</b>: Optional name to use if a new `Tensor` is created. + +##### Returns: + + A `Tensor` based on `value`. + +##### Raises: + + +* <b>TypeError</b>: If no conversion function is registered for `value`. +* <b>RuntimeError</b>: If a registered conversion function returns an invalid value. + + +- - - + +### tf.get_default_graph() <div class="md-anchor" id="get_default_graph">{#get_default_graph}</div> + +Returns the default graph for the current thread. + +The returned graph will be the innermost graph on which a +`Graph.as_default()` context has been entered, or a global default +graph if none has been explicitly created. + +*N.B.* The default graph is a property of the current thread. If you +create a new thread, and wish to use the default graph in that +thread, you must explicitly add a `with g.as_default():` in that +thread's function. + +##### Returns: + + The default `Graph` being used in the current thread. + + +- - - + +### tf.import_graph_def(graph_def, input_map=None, return_elements=None, name=None, op_dict=None) <div class="md-anchor" id="import_graph_def">{#import_graph_def}</div> + +Imports the TensorFlow graph in `graph_def` into the Python `Graph`. + +This function provides a way to import a serialized TensorFlow +[`GraphDef`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/graph.proto) +protocol buffer, and extract individual objects in the `GraphDef` as +[`Tensor`](#Tensor) and [`Operation`](#Operation) objects. See +[`Graph.as_graph_def()`](#Graph.as_graph_def) for a way to create a +`GraphDef` proto. + +##### Args: + + +* <b>graph_def</b>: A `GraphDef` proto containing operations to be imported into + the default graph. +* <b>input_map</b>: A dictionary mapping input names (as strings) in `graph_def` + to `Tensor` objects. The values of the named input tensors in the + imported graph will be re-mapped to the respective `Tensor` values. +* <b>return_elements</b>: A list of strings containing operation names in + `graph_def` that will be returned as `Operation` objects; and/or + tensor names in `graph_def` that will be returned as `Tensor` objects. +* <b>name</b>: (Optional.) A prefix that will be prepended to the names in + `graph_def`. Defaults to `"import"`. +* <b>op_dict</b>: (Optional.) A dictionary mapping op type names to `OpDef` protos. + Must contain an `OpDef` proto for each op type named in `graph_def`. + If omitted, uses the `OpDef` protos registered in the global registry. + +##### Returns: + + A list of `Operation` and/or `Tensor` objects from the imported graph, + corresponding to the names in `return_elements'. + +##### Raises: + + +* <b>TypeError</b>: If `graph_def` is not a `GraphDef` proto, + `input_map' is not a dictionary mapping strings to `Tensor` objects, + or `return_elements` is not a list of strings. +* <b>ValueError</b>: If `input_map`, or `return_elements` contains names that + do not appear in `graph_def`, or `graph_def` is not well-formed (e.g. + it refers to an unknown tensor). + + + +## Graph collections <div class="md-anchor" id="AUTOGENERATED-graph-collections">{#AUTOGENERATED-graph-collections}</div> + +- - - + +### tf.add_to_collection(name, value) <div class="md-anchor" id="add_to_collection">{#add_to_collection}</div> + +Wrapper for `Graph.add_to_collection()` using the default graph. + +See [`Graph.add_to_collection()`](framework.md#Graph.add_to_collection) +for more details. + +##### Args: + + +* <b>name</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>value</b>: The value to add to the collection. + + +- - - + +### tf.get_collection(key, scope=None) <div class="md-anchor" id="get_collection">{#get_collection}</div> + +Wrapper for `Graph.get_collection()` using the default graph. + +See [`Graph.get_collection()`](framework.md#Graph.get_collection) +for more details. + +##### Args: + + +* <b>key</b>: The key for the collection. For example, the `GraphKeys` class + contains many standard names for collections. +* <b>scope</b>: (Optional.) If supplied, the resulting list is filtered to include + only items whose name begins with this string. + +##### Returns: + + The list of values in the collection with the given `name`, or + an empty list if no value has been added to that collection. The + list contains the values in the order under which they were + collected. + + +- - - + +### class tf.GraphKeys <div class="md-anchor" id="GraphKeys">{#GraphKeys}</div> + +Standard names to use for graph collections. + +The standard library uses various well-known names to collect and +retrieve values associated with a graph. For example, the +`tf.Optimizer` subclasses default to optimizing the variables +collected under `tf.GraphKeys.TRAINABLE_VARIABLES` if none is +specified, but it is also possible to pass an explicit list of +variables. + +The following standard keys are defined: + +* `VARIABLES`: the `Variable` objects that comprise a model, and + must be saved and restored together. See + [`tf.all_variables()`](state_ops.md#all_variables) for more details. +* `TRAINABLE_VARIABLES`: the subset of `Variable` objects that will + be trained by an optimizer. See + [`tf.trainable_variables()`](state_ops.md#trainable_variables) + for more details. +* `SUMMARIES`: the summary `Tensor` objects that have been created + in the graph. See [`tf.merge_all_summaries()`](train.md#merge_all_summaries) + for more details. +* `QUEUE_RUNNERS`: the `QueueRunner` objects that are used to + produce input for a computation. See + [`tf.start_queue_runners()`](train.md#start_queue_runners) for more details. + + +## Defining new operations <div class="md-anchor" id="AUTOGENERATED-defining-new-operations">{#AUTOGENERATED-defining-new-operations}</div> + +- - - + +### class tf.RegisterGradient <div class="md-anchor" id="RegisterGradient">{#RegisterGradient}</div> + +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` inputs, 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: + +```python +@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: + + +* <b>op_type</b>: The string type of an operation. This corresponds to the + `OpDef.name` field for the proto that defines the operation. + + + +- - - + +### tf.NoGradient(op_type) <div class="md-anchor" id="NoGradient">{#NoGradient}</div> + +Specifies that ops of type `op_type` do not have a defined gradient. + +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: + +```python +tf.NoGradient("Size") +``` + +##### Args: + + +* <b>op_type</b>: The string type of an operation. This corresponds to the + `OpDef.name` field for the proto that defines the operation. + +##### Raises: + + +* <b>TypeError</b>: If `op_type` is not a string. + + +- - - + +### class tf.RegisterShape <div class="md-anchor" id="RegisterShape">{#RegisterShape}</div> + +A decorator for registering the shape function for an op type. + +This decorator is only used when defining a new op type. A shape +function is a function from an `Operation` object to a list of +`TensorShape` objects, with one `TensorShape` for each output of the +operation. + +For example, assuming that operations of type `"Sub"` take two +inputs `x` and `y`, and return a single output `x - y`, all with the +same shape, the following shape function would be registered: + +```python +@tf.RegisterShape("Sub") +def _sub_shape(op): + return [op.inputs[0].get_shape().merge_with(op.inputs[1].get_shape())] +``` + +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.RegisterShape.__init__(op_type) {#RegisterShape.__init__} + +Saves the "op_type" as the Operation type. + + + +- - - + +### class tf.TensorShape <div class="md-anchor" id="TensorShape">{#TensorShape}</div> + +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 [`tf.RegisterShape()`](framework.md#RegisterShape) +for details of shape +functions and how to register them. Alternatively, the shape may be set +explicitly using [`Tensor.set_shape()`](framework.md#Tensor.set_shape). + +- - - + +#### tf.TensorShape.merge_with(other) {#TensorShape.merge_with} + +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: + + +* <b>other</b>: Another `TensorShape`. + +##### Returns: + + A `TensorShape` containing the combined information of `self` and + `other`. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` are not compatible. + + +- - - + +#### tf.TensorShape.concatenate(other) {#TensorShape.concatenate} + +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: + + +* <b>other</b>: Another `TensorShape`. + +##### Returns: + + A `TensorShape` whose dimensions are the concatenation of the + dimensions in `self` and `other`. + + + +- - - + +#### tf.TensorShape.ndims {#TensorShape.ndims} + +Returns the rank of this shape, or None if it is unspecified. + +- - - + +#### tf.TensorShape.dims {#TensorShape.dims} + +Returns a list of Dimensions, or None if the shape is unspecified. + +- - - + +#### tf.TensorShape.as_list() {#TensorShape.as_list} + +Returns a list of integers or None for each dimension. + + +- - - + +#### tf.TensorShape.is_compatible_with(other) {#TensorShape.is_compatible_with} + +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: + + +* <b>other</b>: Another TensorShape. + +##### Returns: + + True iff `self` is compatible with `other`. + + +- - - + +#### tf.TensorShape.is_fully_defined() {#TensorShape.is_fully_defined} + +Returns True iff `self` is fully defined in every dimension. + + + +- - - + +#### tf.TensorShape.with_rank(rank) {#TensorShape.with_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: + + +* <b>rank</b>: An integer. + +##### Returns: + + A shape that is at least as specific as `self` with the given rank. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with the given `rank`. + + +- - - + +#### tf.TensorShape.with_rank_at_least(rank) {#TensorShape.with_rank_at_least} + +Returns a shape based on `self` with at least the given rank. + +##### Args: + + +* <b>rank</b>: An integer. + +##### Returns: + + A shape that is at least as specific as `self` with at least the given + rank. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with at least the given + `rank`. + + +- - - + +#### tf.TensorShape.with_rank_at_most(rank) {#TensorShape.with_rank_at_most} + +Returns a shape based on `self` with at most the given rank. + +##### Args: + + +* <b>rank</b>: An integer. + +##### Returns: + + A shape that is at least as specific as `self` with at most the given + rank. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with at most the given + `rank`. + + + +- - - + +#### tf.TensorShape.assert_has_rank(rank) {#TensorShape.assert_has_rank} + +Raises an exception if `self` is not compatible with the given `rank`. + +##### Args: + + +* <b>rank</b>: An integer. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not represent a shape with the given `rank`. + + +- - - + +#### tf.TensorShape.assert_same_rank(other) {#TensorShape.assert_same_rank} + +Raises an exception if `self` and `other` do not have compatible ranks. + +##### Args: + + +* <b>other</b>: Another `TensorShape`. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` do not represent shapes with the + same rank. + + +- - - + +#### tf.TensorShape.assert_is_compatible_with(other) {#TensorShape.assert_is_compatible_with} + +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: + + +* <b>other</b>: Another TensorShape. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` do not represent the same shape. + + +- - - + +#### tf.TensorShape.assert_is_fully_defined() {#TensorShape.assert_is_fully_defined} + +Raises an exception if `self` is not fully defined in every dimension. + +##### Raises: + + +* <b>ValueError</b>: If `self` does not have a known value for every dimension. + + + +#### Other Methods +- - - + +#### tf.TensorShape.__init__(dims) {#TensorShape.__init__} + +Creates a new TensorShape with the given dimensions. + +##### Args: + + +* <b>dims</b>: A list of Dimensions, or None if the shape is unspecified. +* <b>DEPRECATED</b>: A single integer is treated as a singleton list. + + +- - - + +#### tf.TensorShape.as_dimension_list() {#TensorShape.as_dimension_list} + +DEPRECATED: use as_list(). + + +- - - + +#### tf.TensorShape.num_elements() {#TensorShape.num_elements} + +Returns the total number of elements, or none for incomplete shapes. + + + +- - - + +### class tf.Dimension <div class="md-anchor" id="Dimension">{#Dimension}</div> + +Represents the value of one dimension in a TensorShape. +- - - + +#### tf.Dimension.__init__(value) {#Dimension.__init__} + +Creates a new Dimension with the given value. + + +- - - + +#### tf.Dimension.assert_is_compatible_with(other) {#Dimension.assert_is_compatible_with} + +Raises an exception if `other` is not compatible with this Dimension. + +##### Args: + + +* <b>other</b>: Another Dimension. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` are not compatible (see + is_compatible_with). + + +- - - + +#### tf.Dimension.is_compatible_with(other) {#Dimension.is_compatible_with} + +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: + + +* <b>other</b>: Another Dimension. + +##### Returns: + + True if this Dimension and `other` are compatible. + + +- - - + +#### tf.Dimension.merge_with(other) {#Dimension.merge_with} + +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: + + +* <b>other</b>: Another Dimension. + +##### Returns: + + A Dimension containing the combined information of `self` and + `other`. + +##### Raises: + + +* <b>ValueError</b>: If `self` and `other` are not compatible (see + is_compatible_with). + + +- - - + +#### tf.Dimension.value {#Dimension.value} + +The value of this dimension, or None if it is unknown. + + +- - - + +### tf.op_scope(*args, **kwds) <div class="md-anchor" id="op_scope">{#op_scope}</div> + +Returns a context manager for use when defining a Python op. + +This context manager validates that the given `values` are from the +same graph, ensures that that graph is the default graph, and pushes a +name scope. + +For example, to define a new Python op called `my_op`: + +```python +def my_op(a, b, c, name=None): + with tf.op_scope([a, b, c], name, "MyOp") as scope: + a = tf.convert_to_tensor(a, name="a") + b = tf.convert_to_tensor(b, name="b") + c = tf.convert_to_tensor(c, name="c") + # Define some computation that uses `a`, `b`, and `c`. + return foo_op(..., name=scope) +``` + +##### Args: + + +* <b>values</b>: The list of `Tensor` arguments that are passed to the op function. +* <b>name</b>: The name argument that is passed to the op function. +* <b>default_name</b>: The default name to use if the `name` argument is `None`. + +##### Returns: + + A context manager for use in defining a Python op. + + +- - - + +### tf.get_seed(op_seed) <div class="md-anchor" id="get_seed">{#get_seed}</div> + +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`](constant_op.md#set_random_seed). + +##### Args: + + +* <b>op_seed</b>: integer. + +##### Returns: + + A tuple of two integers that should be used for the local seed of this + operation. + + diff --git a/tensorflow/g3doc/api_docs/python/image.md b/tensorflow/g3doc/api_docs/python/image.md new file mode 100644 index 0000000000..6b3d6c3ca7 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/image.md @@ -0,0 +1,857 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Images +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Encoding and Decoding.](#AUTOGENERATED-encoding-and-decoding.) + * [tf.image.decode_jpeg(contents, channels=None, ratio=None, fancy_upscaling=None, try_recover_truncated=None, acceptable_fraction=None, name=None)](#decode_jpeg) + * [tf.image.encode_jpeg(image, format=None, quality=None, progressive=None, optimize_size=None, chroma_downsampling=None, density_unit=None, x_density=None, y_density=None, xmp_metadata=None, name=None)](#encode_jpeg) + * [tf.image.decode_png(contents, channels=None, name=None)](#decode_png) + * [tf.image.encode_png(image, compression=None, name=None)](#encode_png) +* [Resizing.](#AUTOGENERATED-resizing.) + * [tf.image.resize_images(images, new_height, new_width, method=0)](#resize_images) + * [tf.image.resize_area(images, size, name=None)](#resize_area) + * [tf.image.resize_bicubic(images, size, name=None)](#resize_bicubic) + * [tf.image.resize_bilinear(images, size, name=None)](#resize_bilinear) + * [tf.image.resize_nearest_neighbor(images, size, name=None)](#resize_nearest_neighbor) +* [Cropping.](#AUTOGENERATED-cropping.) + * [tf.image.resize_image_with_crop_or_pad(image, target_height, target_width)](#resize_image_with_crop_or_pad) + * [tf.image.pad_to_bounding_box(image, offset_height, offset_width, target_height, target_width)](#pad_to_bounding_box) + * [tf.image.crop_to_bounding_box(image, offset_height, offset_width, target_height, target_width)](#crop_to_bounding_box) + * [tf.image.random_crop(image, size, seed=None, name=None)](#random_crop) + * [tf.image.extract_glimpse(input, size, offsets, centered=None, normalized=None, uniform_noise=None, name=None)](#extract_glimpse) +* [Flipping and Transposing.](#AUTOGENERATED-flipping-and-transposing.) + * [tf.image.flip_up_down(image)](#flip_up_down) + * [tf.image.random_flip_up_down(image, seed=None)](#random_flip_up_down) + * [tf.image.flip_left_right(image)](#flip_left_right) + * [tf.image.random_flip_left_right(image, seed=None)](#random_flip_left_right) + * [tf.image.transpose_image(image)](#transpose_image) +* [Image Adjustments.](#AUTOGENERATED-image-adjustments.) + * [tf.image.adjust_brightness(image, delta, min_value=None, max_value=None)](#adjust_brightness) + * [tf.image.random_brightness(image, max_delta, seed=None)](#random_brightness) + * [tf.image.adjust_contrast(images, contrast_factor, min_value=None, max_value=None)](#adjust_contrast) + * [tf.image.random_contrast(image, lower, upper, seed=None)](#random_contrast) + * [tf.image.per_image_whitening(image)](#per_image_whitening) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Encoding and Decoding. <div class="md-anchor" id="AUTOGENERATED-encoding-and-decoding.">{#AUTOGENERATED-encoding-and-decoding.}</div> + +TensorFlow provides Ops to decode and encode JPEG and PNG formats. Encoded +images are represented by scalar string Tensors, decoded images by 3-D uint8 +tensors of shape `[height, width, channels]`. + +The encode and decode Ops apply to one image at a time. Their input and output +are all of variable size. If you need fixed size images, pass the output of +the decode Ops to one of the cropping and resizing Ops. + +Note: The PNG encode and decode Ops support RGBA, but the conversions Ops +presently only support RGB, HSV, and GrayScale. + +- - - + +### tf.image.decode_jpeg(contents, channels=None, ratio=None, fancy_upscaling=None, try_recover_truncated=None, acceptable_fraction=None, name=None) <div class="md-anchor" id="decode_jpeg">{#decode_jpeg}</div> + +Decode a JPEG-encoded image to a uint8 tensor. + +The attr `channels` indicates the desired number of color channels for the +decoded image. + +Accepted values are: + +* 0: Use the number of channels in the JPEG-encoded image. +* 1: output a grayscale image. +* 3: output an RGB image. + +If needed, the JPEG-encoded image is transformed to match the requested number +of color channels. + +The attr `ratio` allows downscaling the image by an integer factor during +decoding. Allowed values are: 1, 2, 4, and 8. This is much faster than +downscaling the image later. + +##### Args: + + +* <b>contents</b>: A `Tensor` of type `string`. 0-D. The JPEG-encoded image. +* <b>channels</b>: An optional `int`. Defaults to `0`. + Number of color channels for the decoded image. +* <b>ratio</b>: An optional `int`. Defaults to `1`. Downscaling ratio. +* <b>fancy_upscaling</b>: An optional `bool`. Defaults to `True`. + If true use a slower but nicer upscaling of the + chroma planes (yuv420/422 only). +* <b>try_recover_truncated</b>: An optional `bool`. Defaults to `False`. + If true try to recover an image from truncated input. +* <b>acceptable_fraction</b>: An optional `float`. Defaults to `1`. + The minimum required fraction of lines before a truncated + input is accepted. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `uint8`. 3-D with shape `[height, width, channels]`.. + + +- - - + +### tf.image.encode_jpeg(image, format=None, quality=None, progressive=None, optimize_size=None, chroma_downsampling=None, density_unit=None, x_density=None, y_density=None, xmp_metadata=None, name=None) <div class="md-anchor" id="encode_jpeg">{#encode_jpeg}</div> + +JPEG-encode an image. + +`image` is a 3-D uint8 Tensor of shape `[height, width, channels]`. + +The attr `format` can be used to override the color format of the encoded +output. Values can be: + +* `''`: Use a default format based on the number of channels in the image. +* `grayscale`: Output a grayscale JPEG image. The `channels` dimension + of `image` must be 1. +* `rgb`: Output an RGB JPEG image. The `channels` dimension + of `image` must be 3. + +If `format` is not specified or is the empty string, a default format is picked +in function of the number of channels in `image`: + +* 1: Output a grayscale image. +* 3: Output an RGB image. + +##### Args: + + +* <b>image</b>: A `Tensor` of type `uint8`. + 3-D with shape `[height, width, channels]`. +* <b>format</b>: An optional `string` from: `"", "grayscale", "rgb"`. Defaults to `""`. + Per pixel image format. +* <b>quality</b>: An optional `int`. Defaults to `95`. + Quality of the compression from 0 to 100 (higher is better and slower). +* <b>progressive</b>: An optional `bool`. Defaults to `False`. + If True, create a JPEG that loads progressively (coarse to fine). +* <b>optimize_size</b>: An optional `bool`. Defaults to `False`. + If True, spend CPU/RAM to reduce size with no quality change. +* <b>chroma_downsampling</b>: An optional `bool`. Defaults to `True`. + See http://en.wikipedia.org/wiki/Chroma_subsampling. +* <b>density_unit</b>: An optional `string` from: `"in", "cm"`. Defaults to `"in"`. + Unit used to specify `x_density` and `y_density`: + pixels per inch (`'in'`) or centimeter (`'cm'`). +* <b>x_density</b>: An optional `int`. Defaults to `300`. + Horizontal pixels per density unit. +* <b>y_density</b>: An optional `int`. Defaults to `300`. + Vertical pixels per density unit. +* <b>xmp_metadata</b>: An optional `string`. Defaults to `""`. + If not empty, embed this XMP metadata in the image header. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. 0-D. JPEG-encoded image. + + + +- - - + +### tf.image.decode_png(contents, channels=None, name=None) <div class="md-anchor" id="decode_png">{#decode_png}</div> + +Decode a PNG-encoded image to a uint8 tensor. + +The attr `channels` indicates the desired number of color channels for the +decoded image. + +Accepted values are: + +* 0: Use the number of channels in the PNG-encoded image. +* 1: output a grayscale image. +* 3: output an RGB image. +* 4: output an RGBA image. + +If needed, the PNG-encoded image is transformed to match the requested number +of color channels. + +##### Args: + + +* <b>contents</b>: A `Tensor` of type `string`. 0-D. The PNG-encoded image. +* <b>channels</b>: An optional `int`. Defaults to `0`. + Number of color channels for the decoded image. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `uint8`. 3-D with shape `[height, width, channels]`. + + +- - - + +### tf.image.encode_png(image, compression=None, name=None) <div class="md-anchor" id="encode_png">{#encode_png}</div> + +PNG-encode an image. + +`image` is a 3-D uint8 Tensor of shape `[height, width, channels]` where +`channels` is: + +* 1: for grayscale. +* 3: for RGB. +* 4: for RGBA. + +The ZLIB compression level, `compression`, can be -1 for the PNG-encoder +default or a value from 0 to 9. 9 is the highest compression level, generating +the smallest output, but is slower. + +##### Args: + + +* <b>image</b>: A `Tensor` of type `uint8`. + 3-D with shape `[height, width, channels]`. +* <b>compression</b>: An optional `int`. Defaults to `-1`. Compression level. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. 0-D. PNG-encoded image. + + + +## Resizing. <div class="md-anchor" id="AUTOGENERATED-resizing.">{#AUTOGENERATED-resizing.}</div> + +The resizing Ops accept input images as tensors of several types. They always +output resized images as float32 tensors. + +The convenience function [resize_images()](#resize_images) supports both 4-D +and 3-D tensors as input and output. 4-D tensors are for batches of images, +3-D tensors for individual images. + +Other resizing Ops only support 3-D individual images as input: +[resize_area](#resize_area), [resize_bicubic](#resize_bicubic), +[resize_bilinear](#resize_bilinear), +[resize_nearest_neighbor](#resize_nearest_neighbor). + +Example: + +```python +# Decode a JPG image and resize it to 299 by 299. +image = tf.image.decode_jpeg(...) +resized_image = tf.image.resize_bilinear(image, [299, 299]) +``` + +<i>Maybe refer to the Queue examples that show how to add images to a Queue +after resizing them to a fixed size, and how to dequeue batches of resized +images from the Queue.</i> + +- - - + +### tf.image.resize_images(images, new_height, new_width, method=0) <div class="md-anchor" id="resize_images">{#resize_images}</div> + +Resize `images` to `new_width`, `new_height` using the specified `method`. + +Resized images will be distorted if their original aspect ratio is not +the same as `new_width`, `new_height`. To avoid distortions see +[resize_image_with_crop_or_pad](#resize_image_with_crop_or_pad). + +`method` can be one of: + +* <b>ResizeMethod.BILINEAR</b>: [Bilinear interpolation.] + (https://en.wikipedia.org/wiki/Bilinear_interpolation) +* <b>ResizeMethod.NEAREST_NEIGHBOR</b>: [Nearest neighbor interpolation.] + (https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation) +* <b>ResizeMethod.BICUBIC</b>: [Bicubic interpolation.] + (https://en.wikipedia.org/wiki/Bicubic_interpolation) +* <b>ResizeMethod.AREA</b>: Area interpolation. + +##### Args: + + +* <b>images</b>: 4-D Tensor of shape `[batch, height, width, channels]` or + 3-D Tensor of shape `[height, width, channels]`. +* <b>new_height</b>: integer. +* <b>new_width</b>: integer. +* <b>method</b>: ResizeMethod. Defaults to `ResizeMethod.BILINEAR`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `images` is incompatible with the + shape arguments to this function +* <b>ValueError</b>: if an unsupported resize method is specified. + +##### Returns: + + If `images` was 4-D, a 4-D float Tensor of shape + `[batch, new_height, new_width, channels]`. + If `images` was 3-D, a 3-D float Tensor of shape + `[new_height, new_width, channels]`. + + + +- - - + +### tf.image.resize_area(images, size, name=None) <div class="md-anchor" id="resize_area">{#resize_area}</div> + +Resize `images` to `size` using area interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + +- - - + +### tf.image.resize_bicubic(images, size, name=None) <div class="md-anchor" id="resize_bicubic">{#resize_bicubic}</div> + +Resize `images` to `size` using bicubic interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + +- - - + +### tf.image.resize_bilinear(images, size, name=None) <div class="md-anchor" id="resize_bilinear">{#resize_bilinear}</div> + +Resize `images` to `size` using bilinear interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + +- - - + +### tf.image.resize_nearest_neighbor(images, size, name=None) <div class="md-anchor" id="resize_nearest_neighbor">{#resize_nearest_neighbor}</div> + +Resize `images` to `size` using nearest neighbor interpolation. + +Input images can be of different types but output images are always float. + +##### Args: + + +* <b>images</b>: A `Tensor`. Must be one of the following types: `uint8`, `int8`, `int32`, `float32`, `float64`. + 4-D with shape `[batch, height, width, channels]`. +* <b>size</b>: A 1-D int32 Tensor of 2 elements: `new_height, new_width`. The + new size for the images. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `images`. 4-D with shape + `[batch, new_height, new_width, channels]`. + + + + +## Cropping. <div class="md-anchor" id="AUTOGENERATED-cropping.">{#AUTOGENERATED-cropping.}</div> + +- - - + +### tf.image.resize_image_with_crop_or_pad(image, target_height, target_width) <div class="md-anchor" id="resize_image_with_crop_or_pad">{#resize_image_with_crop_or_pad}</div> + +Crops and/or pads an image to a target width and height. + +Resizes an image to a target width and height by either centrally +cropping the image or padding it evenly with zeros. + +If `width` or `height` is greater than the specified `target_width` or +`target_height` respectively, this op centrally crops along that dimension. +If `width` or `height` is smaller than the specified `target_width` or +`target_height` respectively, this op centrally pads with 0 along that +dimension. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape [height, width, channels] +* <b>target_height</b>: Target height. +* <b>target_width</b>: Target width. + +##### Raises: + + +* <b>ValueError</b>: if `target_height` or `target_width` are zero or negative. + +##### Returns: + + Cropped and/or padded image of shape + `[target_height, target_width, channels]` + + + +- - - + +### tf.image.pad_to_bounding_box(image, offset_height, offset_width, target_height, target_width) <div class="md-anchor" id="pad_to_bounding_box">{#pad_to_bounding_box}</div> + +Pad `image` with zeros to the specified `height` and `width`. + +Adds `offset_height` rows of zeros on top, `offset_width` columns of +zeros on the left, and then pads the image on the bottom and right +with zeros until it has dimensions `target_height`, `target_width`. + +This op does nothing if `offset_*` is zero and the image already has size +`target_height` by `target_width`. + +##### Args: + + +* <b>image</b>: 3-D tensor with shape `[height, width, channels]` +* <b>offset_height</b>: Number of rows of zeros to add on top. +* <b>offset_width</b>: Number of columns of zeros to add on the left. +* <b>target_height</b>: Height of output image. +* <b>target_width</b>: Width of output image. + +##### Returns: + + 3-D tensor of shape `[target_height, target_width, channels]` + +##### Raises: + + +* <b>ValueError</b>: If the shape of `image` is incompatible with the `offset_*` or + `target_*` arguments + + +- - - + +### tf.image.crop_to_bounding_box(image, offset_height, offset_width, target_height, target_width) <div class="md-anchor" id="crop_to_bounding_box">{#crop_to_bounding_box}</div> + +Crops an image to a specified bounding box. + +This op cuts a rectangular part out of `image`. The top-left corner of the +returned image is at `offset_height, offset_width` in `image`, and its +lower-right corner is at +`offset_height + target_height, offset_width + target_width'. + +##### Args: + + +* <b>image</b>: 3-D tensor with shape `[height, width, channels]` +* <b>offset_height</b>: Vertical coordinate of the top-left corner of the result in + the input. +* <b>offset_width</b>: Horizontal coordinate of the top-left corner of the result in + the input. +* <b>target_height</b>: Height of the result. +* <b>target_width</b>: Width of the result. + +##### Returns: + + 3-D tensor of image with shape `[target_height, target_width, channels]` + +##### Raises: + + +* <b>ValueError</b>: If the shape of `image` is incompatible with the `offset_*` or + `target_*` arguments + + +- - - + +### tf.image.random_crop(image, size, seed=None, name=None) <div class="md-anchor" id="random_crop">{#random_crop}</div> + +Randomly crops `image` to size `[target_height, target_width]`. + +The offset of the output within `image` is uniformly random. `image` always +fully contains the result. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]` +* <b>size</b>: 1-D tensor with two elements, specifying target `[height, width]` +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A cropped 3-D tensor of shape `[target_height, target_width, channels]`. + + +- - - + +### tf.image.extract_glimpse(input, size, offsets, centered=None, normalized=None, uniform_noise=None, name=None) <div class="md-anchor" id="extract_glimpse">{#extract_glimpse}</div> + +Extracts a glimpse from the input tensor. + +Returns a set of windows called glimpses extracted at location `offsets` +from the input tensor. If the windows only partially overlaps the inputs, the +non overlapping areas will be filled with random noise. + +The result is a 4-D tensor of shape `[batch_size, glimpse_height, +glimpse_width, channels]`. The channels and batch dimensions are the same as that +of the input tensor. The height and width of the output windows are +specified in the `size` parameter. + +The argument `normalized` and `centered` controls how the windows are built: +* If the coordinates are normalized but not centered, 0.0 and 1.0 + correspond to the minimum and maximum of each height and width dimension. +* If the coordinates are both normalized and centered, they range from -1.0 to + 1.0. The coordinates (-1.0, -1.0) correspond to the upper left corner, the + lower right corner is located at (1.0, 1.0) and the center is at (0, 0). +* If the coordinates are not normalized they are interpreted as numbers of pixels. + +##### Args: + + +* <b>input</b>: A `Tensor` of type `float32`. + A 4-D float tensor of shape `[batch_size, height, width, channels]`. +* <b>size</b>: A `Tensor` of type `int32`. + A 1-D tensor of 2 elements containing the size of the glimpses to extract. + The glimpse height must be specified first, following by the glimpse width. +* <b>offsets</b>: A `Tensor` of type `float32`. + A 2-D integer tensor of shape `[batch_size, 2]` containing the x, y + locations of the center of each window. +* <b>centered</b>: An optional `bool`. Defaults to `True`. + indicates if the offset coordinates are centered relative to + the image, in which case the (0, 0) offset is relative to the center of the + input images. If false, the (0,0) offset corresponds to the upper left corner + of the input images. +* <b>normalized</b>: An optional `bool`. Defaults to `True`. + indicates if the offset coordinates are normalized. +* <b>uniform_noise</b>: An optional `bool`. Defaults to `True`. + indicates if the noise should be generated using a + uniform distribution or a gaussian distribution. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + A tensor representing the glimpses `[batch_size, glimpse_height, + glimpse_width, channels]`. + + + +## Flipping and Transposing. <div class="md-anchor" id="AUTOGENERATED-flipping-and-transposing.">{#AUTOGENERATED-flipping-and-transposing.}</div> + +- - - + +### tf.image.flip_up_down(image) <div class="md-anchor" id="flip_up_down">{#flip_up_down}</div> + +Flip an image horizontally (upside down). + +Outputs the contents of `image` flipped along the first dimension, which is +`height`. + +See also `reverse()`. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + +- - - + +### tf.image.random_flip_up_down(image, seed=None) <div class="md-anchor" id="random_flip_up_down">{#random_flip_up_down}</div> + +Randomly flips an image vertically (upside down). + +With a 1 in 2 chance, outputs the contents of `image` flipped along the first +dimension, which is `height`. Otherwise output the image as-is. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + + +- - - + +### tf.image.flip_left_right(image) <div class="md-anchor" id="flip_left_right">{#flip_left_right}</div> + +Flip an image horizontally (left to right). + +Outputs the contents of `image` flipped along the second dimension, which is +`width`. + +See also `reverse()`. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + +- - - + +### tf.image.random_flip_left_right(image, seed=None) <div class="md-anchor" id="random_flip_left_right">{#random_flip_left_right}</div> + +Randomly flip an image horizontally (left to right). + +With a 1 in 2 chance, outputs the contents of `image` flipped along the +second dimension, which is `width`. Otherwise output the image as-is. + +##### Args: + + +* <b>image</b>: A 3-D tensor of shape `[height, width, channels].` +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + A 3-D tensor of the same type and shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + + +- - - + +### tf.image.transpose_image(image) <div class="md-anchor" id="transpose_image">{#transpose_image}</div> + +Transpose an image by swapping the first and second dimension. + +See also `transpose()`. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]` + +##### Returns: + + A 3-D tensor of shape `[width, height, channels]` + +##### Raises: + + +* <b>ValueError</b>: if the shape of `image` not supported. + + + +## Image Adjustments. <div class="md-anchor" id="AUTOGENERATED-image-adjustments.">{#AUTOGENERATED-image-adjustments.}</div> + +TensorFlow provides functions to adjust images in various ways: brightness, +contrast, hue, and saturation. Each adjustment can be done with predefined +parameters or with random parameters picked from predefined intervals. Random +adjustments are often useful to expand a training set and reduce overfitting. + +- - - + +### tf.image.adjust_brightness(image, delta, min_value=None, max_value=None) <div class="md-anchor" id="adjust_brightness">{#adjust_brightness}</div> + +Adjust the brightness of RGB or Grayscale images. + +The value `delta` is added to all components of the tensor `image`. `image` +and `delta` are cast to `float` before adding, and the resulting values are +clamped to `[min_value, max_value]`. Finally, the result is cast back to +`images.dtype`. + +If `min_value` or `max_value` are not given, they are set to the minimum and +maximum allowed values for `image.dtype` respectively. + +##### Args: + + +* <b>image</b>: A tensor. +* <b>delta</b>: A scalar. Amount to add to the pixel values. +* <b>min_value</b>: Minimum value for output. +* <b>max_value</b>: Maximum value for output. + +##### Returns: + + A tensor of the same shape and type as `image`. + + +- - - + +### tf.image.random_brightness(image, max_delta, seed=None) <div class="md-anchor" id="random_brightness">{#random_brightness}</div> + +Adjust the brightness of images by a random factor. + +Equivalent to `adjust_brightness()` using a `delta` randomly picked in the +interval `[-max_delta, max_delta)`. + +Note that `delta` is picked as a float. Because for integer type images, +the brightness adjusted result is rounded before casting, integer images may +have modifications in the range `[-max_delta,max_delta]`. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]`. +* <b>max_delta</b>: float, must be non-negative. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + 3-D tensor of images of shape `[height, width, channels]` + +##### Raises: + + +* <b>ValueError</b>: if max_delta is negative. + + + +- - - + +### tf.image.adjust_contrast(images, contrast_factor, min_value=None, max_value=None) <div class="md-anchor" id="adjust_contrast">{#adjust_contrast}</div> + +Adjust contrast of RGB or grayscale images. + +`images` is a tensor of at least 3 dimensions. The last 3 dimensions are +interpreted as `[height, width, channels]`. The other dimensions only +represent a collection of images, such as `[batch, height, width, channels].` + +Contrast is adjusted independently for each channel of each image. + +For each channel, this Op first computes the mean of the image pixels in the +channel and then adjusts each component `x` of each pixel to +`(x - mean) * contrast_factor + mean`. + +The adjusted values are then clipped to fit in the `[min_value, max_value]` +interval. If `min_value` or `max_value` is not given, it is replaced with the +minimum and maximum values for the data type of `images` respectively. + +The contrast-adjusted image is always computed as `float`, and it is +cast back to its original type after clipping. + +##### Args: + + +* <b>images</b>: Images to adjust. At least 3-D. +* <b>contrast_factor</b>: A float multiplier for adjusting contrast. +* <b>min_value</b>: Minimum value for clipping the adjusted pixels. +* <b>max_value</b>: Maximum value for clipping the adjusted pixels. + +##### Returns: + + The constrast-adjusted image or images. + +##### Raises: + + +* <b>ValueError</b>: if the arguments are invalid. + + +- - - + +### tf.image.random_contrast(image, lower, upper, seed=None) <div class="md-anchor" id="random_contrast">{#random_contrast}</div> + +Adjust the contrase of an image by a random factor. + +Equivalent to `adjust_constrast()` but uses a `contrast_factor` randomly +picked in the interval `[lower, upper]`. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]`. +* <b>lower</b>: float. Lower bound for the random contrast factor. +* <b>upper</b>: float. Upper bound for the random contrast factor. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + 3-D tensor of shape `[height, width, channels]`. + +##### Raises: + + +* <b>ValueError</b>: if `upper <= lower` or if `lower < 0`. + + + +- - - + +### tf.image.per_image_whitening(image) <div class="md-anchor" id="per_image_whitening">{#per_image_whitening}</div> + +Linearly scales `image` to have zero mean and unit norm. + +This op computes `(x - mean) / adjusted_stddev`, where `mean` is the average +of all values in image, and +`adjusted_stddev = max(stddev, 1.0/srqt(image.NumElements()))`. + +`stddev` is the standard deviation of all values in `image`. It is capped +away from zero to protect against division by 0 when handling uniform images. + +Note that this implementation is limited: +* It only whitens based on the statistics of an individual image. +* It does not take into account the covariance structure. + +##### Args: + + +* <b>image</b>: 3-D tensor of shape `[height, width, channels]`. + +##### Returns: + + The whitened image with same shape as `image`. + +##### Raises: + + +* <b>ValueError</b>: if the shape of 'image' is incompatible with this function. + + diff --git a/tensorflow/g3doc/api_docs/python/index.md b/tensorflow/g3doc/api_docs/python/index.md new file mode 100644 index 0000000000..72c0a401ef --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/index.md @@ -0,0 +1,352 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# TensorFlow Python reference documentation + +* <b>[Building Graphs](framework.md)</b>: [class DType](framework.md#DType), + [class Dimension](framework.md#Dimension), + [class Graph](framework.md#Graph), + [class GraphKeys](framework.md#GraphKeys), + [NoGradient](framework.md#NoGradient), + [class Operation](framework.md#Operation), + [class RegisterGradient](framework.md#RegisterGradient), + [class RegisterShape](framework.md#RegisterShape), + [class Tensor](framework.md#Tensor), + [class TensorShape](framework.md#TensorShape), + [add_to_collection](framework.md#add_to_collection), + [as_dtype](framework.md#as_dtype), + [control_dependencies](framework.md#control_dependencies), + [convert_to_tensor](framework.md#convert_to_tensor), + [device](framework.md#device), + [get_collection](framework.md#get_collection), + [get_default_graph](framework.md#get_default_graph), + [get_seed](framework.md#get_seed), + [import_graph_def](framework.md#import_graph_def), + [name_scope](framework.md#name_scope), + [op_scope](framework.md#op_scope) + +* <b>[Constants, Sequences, and Random Values](constant_op.md)</b>: [constant](constant_op.md#constant), + [fill](constant_op.md#fill), + [linspace](constant_op.md#linspace), + [ones](constant_op.md#ones), + [ones_like](constant_op.md#ones_like), + [random_normal](constant_op.md#random_normal), + [random_shuffle](constant_op.md#random_shuffle), + [random_uniform](constant_op.md#random_uniform), + [range](constant_op.md#range), + [set_random_seed](constant_op.md#set_random_seed), + [truncated_normal](constant_op.md#truncated_normal), + [zeros](constant_op.md#zeros), + [zeros_like](constant_op.md#zeros_like) + +* <b>[Variables](state_ops.md)</b>: [class IndexedSlices](state_ops.md#IndexedSlices), + [class Saver](state_ops.md#Saver), + [class Variable](state_ops.md#Variable), + [all_variables](state_ops.md#all_variables), + [assert_variables_initialized](state_ops.md#assert_variables_initialized), + [assign](state_ops.md#assign), + [assign_add](state_ops.md#assign_add), + [assign_sub](state_ops.md#assign_sub), + [constant_initializer](state_ops.md#constant_initializer), + [count_up_to](state_ops.md#count_up_to), + [device](state_ops.md#device), + [get_checkpoint_state](state_ops.md#get_checkpoint_state), + [get_variable](state_ops.md#get_variable), + [get_variable_scope](state_ops.md#get_variable_scope), + [initialize_all_variables](state_ops.md#initialize_all_variables), + [initialize_variables](state_ops.md#initialize_variables), + [latest_checkpoint](state_ops.md#latest_checkpoint), + [random_normal_initializer](state_ops.md#random_normal_initializer), + [random_uniform_initializer](state_ops.md#random_uniform_initializer), + [scatter_add](state_ops.md#scatter_add), + [scatter_sub](state_ops.md#scatter_sub), + [scatter_update](state_ops.md#scatter_update), + [sparse_mask](state_ops.md#sparse_mask), + [trainable_variables](state_ops.md#trainable_variables), + [truncated_normal_initializer](state_ops.md#truncated_normal_initializer), + [uniform_unit_scaling_initializer](state_ops.md#uniform_unit_scaling_initializer), + [update_checkpoint_state](state_ops.md#update_checkpoint_state), + [variable_scope](state_ops.md#variable_scope), + [zeros_initializer](state_ops.md#zeros_initializer) + +* <b>[Tensor Transformations](array_ops.md)</b>: [cast](array_ops.md#cast), + [concat](array_ops.md#concat), + [dynamic_partition](array_ops.md#dynamic_partition), + [dynamic_stitch](array_ops.md#dynamic_stitch), + [expand_dims](array_ops.md#expand_dims), + [gather](array_ops.md#gather), + [pack](array_ops.md#pack), + [pad](array_ops.md#pad), + [rank](array_ops.md#rank), + [reshape](array_ops.md#reshape), + [reverse](array_ops.md#reverse), + [reverse_sequence](array_ops.md#reverse_sequence), + [shape](array_ops.md#shape), + [size](array_ops.md#size), + [slice](array_ops.md#slice), + [split](array_ops.md#split), + [squeeze](array_ops.md#squeeze), + [string_to_number](array_ops.md#string_to_number), + [tile](array_ops.md#tile), + [to_bfloat16](array_ops.md#to_bfloat16), + [to_double](array_ops.md#to_double), + [to_float](array_ops.md#to_float), + [to_int32](array_ops.md#to_int32), + [to_int64](array_ops.md#to_int64), + [transpose](array_ops.md#transpose), + [unpack](array_ops.md#unpack) + +* <b>[Math](math_ops.md)</b>: [abs](math_ops.md#abs), + [accumulate_n](math_ops.md#accumulate_n), + [add](math_ops.md#add), + [add_n](math_ops.md#add_n), + [argmax](math_ops.md#argmax), + [argmin](math_ops.md#argmin), + [batch_cholesky](math_ops.md#batch_cholesky), + [batch_matmul](math_ops.md#batch_matmul), + [batch_matrix_determinant](math_ops.md#batch_matrix_determinant), + [batch_matrix_inverse](math_ops.md#batch_matrix_inverse), + [ceil](math_ops.md#ceil), + [cholesky](math_ops.md#cholesky), + [complex](math_ops.md#complex), + [complex_abs](math_ops.md#complex_abs), + [conj](math_ops.md#conj), + [cos](math_ops.md#cos), + [diag](math_ops.md#diag), + [div](math_ops.md#div), + [edit_distance](math_ops.md#edit_distance), + [exp](math_ops.md#exp), + [floor](math_ops.md#floor), + [imag](math_ops.md#imag), + [inv](math_ops.md#inv), + [invert_permutation](math_ops.md#invert_permutation), + [listdiff](math_ops.md#listdiff), + [log](math_ops.md#log), + [matmul](math_ops.md#matmul), + [matrix_determinant](math_ops.md#matrix_determinant), + [matrix_inverse](math_ops.md#matrix_inverse), + [maximum](math_ops.md#maximum), + [minimum](math_ops.md#minimum), + [mod](math_ops.md#mod), + [mul](math_ops.md#mul), + [neg](math_ops.md#neg), + [pow](math_ops.md#pow), + [real](math_ops.md#real), + [reduce_all](math_ops.md#reduce_all), + [reduce_any](math_ops.md#reduce_any), + [reduce_max](math_ops.md#reduce_max), + [reduce_mean](math_ops.md#reduce_mean), + [reduce_min](math_ops.md#reduce_min), + [reduce_prod](math_ops.md#reduce_prod), + [reduce_sum](math_ops.md#reduce_sum), + [round](math_ops.md#round), + [rsqrt](math_ops.md#rsqrt), + [segment_max](math_ops.md#segment_max), + [segment_mean](math_ops.md#segment_mean), + [segment_min](math_ops.md#segment_min), + [segment_prod](math_ops.md#segment_prod), + [segment_sum](math_ops.md#segment_sum), + [sign](math_ops.md#sign), + [sin](math_ops.md#sin), + [sparse_segment_mean](math_ops.md#sparse_segment_mean), + [sparse_segment_sum](math_ops.md#sparse_segment_sum), + [sqrt](math_ops.md#sqrt), + [square](math_ops.md#square), + [sub](math_ops.md#sub), + [transpose](math_ops.md#transpose), + [unique](math_ops.md#unique), + [unsorted_segment_sum](math_ops.md#unsorted_segment_sum), + [where](math_ops.md#where) + +* <b>[Control Flow](control_flow_ops.md)</b>: [Assert](control_flow_ops.md#Assert), + [Print](control_flow_ops.md#Print), + [add_check_numerics_ops](control_flow_ops.md#add_check_numerics_ops), + [check_numerics](control_flow_ops.md#check_numerics), + [count_up_to](control_flow_ops.md#count_up_to), + [equal](control_flow_ops.md#equal), + [greater](control_flow_ops.md#greater), + [greater_equal](control_flow_ops.md#greater_equal), + [group](control_flow_ops.md#group), + [identity](control_flow_ops.md#identity), + [is_finite](control_flow_ops.md#is_finite), + [is_inf](control_flow_ops.md#is_inf), + [is_nan](control_flow_ops.md#is_nan), + [less](control_flow_ops.md#less), + [less_equal](control_flow_ops.md#less_equal), + [logical_and](control_flow_ops.md#logical_and), + [logical_not](control_flow_ops.md#logical_not), + [logical_or](control_flow_ops.md#logical_or), + [logical_xor](control_flow_ops.md#logical_xor), + [no_op](control_flow_ops.md#no_op), + [not_equal](control_flow_ops.md#not_equal), + [select](control_flow_ops.md#select), + [tuple](control_flow_ops.md#tuple), + [verify_tensor_all_finite](control_flow_ops.md#verify_tensor_all_finite), + [where](control_flow_ops.md#where) + +* <b>[Images](image.md)</b>: [adjust_brightness](image.md#adjust_brightness), + [adjust_contrast](image.md#adjust_contrast), + [crop_to_bounding_box](image.md#crop_to_bounding_box), + [decode_jpeg](image.md#decode_jpeg), + [decode_png](image.md#decode_png), + [encode_jpeg](image.md#encode_jpeg), + [encode_png](image.md#encode_png), + [extract_glimpse](image.md#extract_glimpse), + [flip_left_right](image.md#flip_left_right), + [flip_up_down](image.md#flip_up_down), + [pad_to_bounding_box](image.md#pad_to_bounding_box), + [per_image_whitening](image.md#per_image_whitening), + [random_brightness](image.md#random_brightness), + [random_contrast](image.md#random_contrast), + [random_crop](image.md#random_crop), + [random_flip_left_right](image.md#random_flip_left_right), + [random_flip_up_down](image.md#random_flip_up_down), + [resize_area](image.md#resize_area), + [resize_bicubic](image.md#resize_bicubic), + [resize_bilinear](image.md#resize_bilinear), + [resize_image_with_crop_or_pad](image.md#resize_image_with_crop_or_pad), + [resize_images](image.md#resize_images), + [resize_nearest_neighbor](image.md#resize_nearest_neighbor), + [transpose_image](image.md#transpose_image) + +* <b>[Sparse Tensors](sparse_ops.md)</b>: [class SparseTensor](sparse_ops.md#SparseTensor), + [class SparseTensorValue](sparse_ops.md#SparseTensorValue), + [shape](sparse_ops.md#shape), + [sparse_concat](sparse_ops.md#sparse_concat), + [sparse_fill_empty_rows](sparse_ops.md#sparse_fill_empty_rows), + [sparse_reorder](sparse_ops.md#sparse_reorder), + [sparse_retain](sparse_ops.md#sparse_retain), + [sparse_tensor_to_dense](sparse_ops.md#sparse_tensor_to_dense), + [sparse_to_dense](sparse_ops.md#sparse_to_dense), + [sparse_to_indicator](sparse_ops.md#sparse_to_indicator) + +* <b>[Inputs and Readers](io_ops.md)</b>: [class FIFOQueue](io_ops.md#FIFOQueue), + [class FixedLengthRecordReader](io_ops.md#FixedLengthRecordReader), + [class IdentityReader](io_ops.md#IdentityReader), + [class QueueBase](io_ops.md#QueueBase), + [class RandomShuffleQueue](io_ops.md#RandomShuffleQueue), + [class ReaderBase](io_ops.md#ReaderBase), + [class TFRecordReader](io_ops.md#TFRecordReader), + [class TextLineReader](io_ops.md#TextLineReader), + [class WholeFileReader](io_ops.md#WholeFileReader), + [batch](io_ops.md#batch), + [batch_join](io_ops.md#batch_join), + [decode_csv](io_ops.md#decode_csv), + [decode_raw](io_ops.md#decode_raw), + [limit_epochs](io_ops.md#limit_epochs), + [match_filenames_once](io_ops.md#match_filenames_once), + [matching_files](io_ops.md#matching_files), + [parse_example](io_ops.md#parse_example), + [parse_single_example](io_ops.md#parse_single_example), + [placeholder](io_ops.md#placeholder), + [range_input_producer](io_ops.md#range_input_producer), + [read_file](io_ops.md#read_file), + [shuffle_batch](io_ops.md#shuffle_batch), + [shuffle_batch_join](io_ops.md#shuffle_batch_join), + [size](io_ops.md#size), + [slice_input_producer](io_ops.md#slice_input_producer), + [string_input_producer](io_ops.md#string_input_producer) + +* <b>[Data IO (Python functions)](python_io.md)</b>: [class TFRecordWriter](python_io.md#TFRecordWriter), + [tf_record_iterator](python_io.md#tf_record_iterator) + +* <b>[Neural Network](nn.md)</b>: [avg_pool](nn.md#avg_pool), + [bias_add](nn.md#bias_add), + [compute_accidental_hits](nn.md#compute_accidental_hits), + [conv2d](nn.md#conv2d), + [depthwise_conv2d](nn.md#depthwise_conv2d), + [dropout](nn.md#dropout), + [embedding_lookup](nn.md#embedding_lookup), + [embedding_lookup_sparse](nn.md#embedding_lookup_sparse), + [fixed_unigram_candidate_sampler](nn.md#fixed_unigram_candidate_sampler), + [in_top_k](nn.md#in_top_k), + [l2_loss](nn.md#l2_loss), + [l2_normalize](nn.md#l2_normalize), + [learned_unigram_candidate_sampler](nn.md#learned_unigram_candidate_sampler), + [local_response_normalization](nn.md#local_response_normalization), + [log_uniform_candidate_sampler](nn.md#log_uniform_candidate_sampler), + [max_pool](nn.md#max_pool), + [max_pool_with_argmax](nn.md#max_pool_with_argmax), + [moments](nn.md#moments), + [nce_loss](nn.md#nce_loss), + [relu](nn.md#relu), + [relu6](nn.md#relu6), + [sampled_softmax_loss](nn.md#sampled_softmax_loss), + [separable_conv2d](nn.md#separable_conv2d), + [sigmoid](nn.md#sigmoid), + [sigmoid_cross_entropy_with_logits](nn.md#sigmoid_cross_entropy_with_logits), + [softmax](nn.md#softmax), + [softmax_cross_entropy_with_logits](nn.md#softmax_cross_entropy_with_logits), + [softplus](nn.md#softplus), + [tanh](nn.md#tanh), + [top_k](nn.md#top_k), + [uniform_candidate_sampler](nn.md#uniform_candidate_sampler) + +* <b>[Running Graphs](client.md)</b>: [class AbortedError](client.md#AbortedError), + [class AlreadyExistsError](client.md#AlreadyExistsError), + [class CancelledError](client.md#CancelledError), + [class DataLossError](client.md#DataLossError), + [class DeadlineExceededError](client.md#DeadlineExceededError), + [class FailedPreconditionError](client.md#FailedPreconditionError), + [class InternalError](client.md#InternalError), + [class InvalidArgumentError](client.md#InvalidArgumentError), + [class NotFoundError](client.md#NotFoundError), + [class OpError](client.md#OpError), + [class OutOfRangeError](client.md#OutOfRangeError), + [class PermissionDeniedError](client.md#PermissionDeniedError), + [class ResourceExhaustedError](client.md#ResourceExhaustedError), + [class Session](client.md#Session), + [class UnauthenticatedError](client.md#UnauthenticatedError), + [class UnavailableError](client.md#UnavailableError), + [class UnimplementedError](client.md#UnimplementedError), + [class UnknownError](client.md#UnknownError), + [get_default_session](client.md#get_default_session) + +* <b>[Training](train.md)</b>: [class AdagradOptimizer](train.md#AdagradOptimizer), + [class AdamOptimizer](train.md#AdamOptimizer), + [class AggregationMethod](train.md#AggregationMethod), + [class Coordinator](train.md#Coordinator), + [class ExponentialMovingAverage](train.md#ExponentialMovingAverage), + [class FtrlOptimizer](train.md#FtrlOptimizer), + [class GradientDescentOptimizer](train.md#GradientDescentOptimizer), + [class MomentumOptimizer](train.md#MomentumOptimizer), + [class Optimizer](train.md#Optimizer), + [class QueueRunner](train.md#QueueRunner), + [class RMSPropOptimizer](train.md#RMSPropOptimizer), + [class SummaryWriter](train.md#SummaryWriter), + [add_queue_runner](train.md#add_queue_runner), + [clip_by_average_norm](train.md#clip_by_average_norm), + [clip_by_global_norm](train.md#clip_by_global_norm), + [clip_by_norm](train.md#clip_by_norm), + [clip_by_value](train.md#clip_by_value), + [exponential_decay](train.md#exponential_decay), + [global_norm](train.md#global_norm), + [global_step](train.md#global_step), + [gradients](train.md#gradients), + [histogram_summary](train.md#histogram_summary), + [image_summary](train.md#image_summary), + [merge_all_summaries](train.md#merge_all_summaries), + [merge_summary](train.md#merge_summary), + [scalar_summary](train.md#scalar_summary), + [start_queue_runners](train.md#start_queue_runners), + [stop_gradient](train.md#stop_gradient), + [summary_iterator](train.md#summary_iterator), + [write_graph](train.md#write_graph), + [zero_fraction](train.md#zero_fraction) + +<div class="sections-order" style="display: none;"> +<!-- +<!-- framework.md --> +<!-- constant_op.md --> +<!-- state_ops.md --> +<!-- array_ops.md --> +<!-- math_ops.md --> +<!-- control_flow_ops.md --> +<!-- image.md --> +<!-- sparse_ops.md --> +<!-- io_ops.md --> +<!-- python_io.md --> +<!-- nn.md --> +<!-- client.md --> +<!-- train.md --> +--> +</div> diff --git a/tensorflow/g3doc/api_docs/python/io_ops.md b/tensorflow/g3doc/api_docs/python/io_ops.md new file mode 100644 index 0000000000..ab8c4aa146 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/io_ops.md @@ -0,0 +1,1956 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Inputs and Readers +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Placeholders](#AUTOGENERATED-placeholders) + * [tf.placeholder(dtype, shape=None, name=None)](#placeholder) +* [Readers](#AUTOGENERATED-readers) + * [class tf.ReaderBase](#ReaderBase) + * [class tf.TextLineReader](#TextLineReader) + * [class tf.WholeFileReader](#WholeFileReader) + * [class tf.IdentityReader](#IdentityReader) + * [class tf.TFRecordReader](#TFRecordReader) + * [class tf.FixedLengthRecordReader](#FixedLengthRecordReader) +* [Converting](#AUTOGENERATED-converting) + * [tf.decode_csv(records, record_defaults, field_delim=None, name=None)](#decode_csv) + * [tf.decode_raw(bytes, out_type, little_endian=None, name=None)](#decode_raw) + * [tf.parse_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseExample')](#parse_example) + * [tf.parse_single_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseSingleExample')](#parse_single_example) +* [Queues](#AUTOGENERATED-queues) + * [class tf.QueueBase](#QueueBase) + * [class tf.FIFOQueue](#FIFOQueue) + * [class tf.RandomShuffleQueue](#RandomShuffleQueue) +* [Dealing with the filesystem](#AUTOGENERATED-dealing-with-the-filesystem) + * [tf.matching_files(pattern, name=None)](#matching_files) + * [tf.read_file(filename, name=None)](#read_file) +* [Input pipeline](#AUTOGENERATED-input-pipeline) + * [Beginning of an input pipeline](#AUTOGENERATED-beginning-of-an-input-pipeline) + * [tf.train.match_filenames_once(pattern, name=None)](#match_filenames_once) + * [tf.train.limit_epochs(tensor, num_epochs=None, name=None)](#limit_epochs) + * [tf.train.range_input_producer(limit, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None)](#range_input_producer) + * [tf.train.slice_input_producer(tensor_list, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None)](#slice_input_producer) + * [tf.train.string_input_producer(string_tensor, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None)](#string_input_producer) + * [Batching at the end of an input pipeline](#AUTOGENERATED-batching-at-the-end-of-an-input-pipeline) + * [tf.train.batch(tensor_list, batch_size, num_threads=1, capacity=32, enqueue_many=False, shapes=None, name=None)](#batch) + * [tf.train.batch_join(tensor_list_list, batch_size, capacity=32, enqueue_many=False, shapes=None, name=None)](#batch_join) + * [tf.train.shuffle_batch(tensor_list, batch_size, capacity, min_after_dequeue, num_threads=1, seed=None, enqueue_many=False, shapes=None, name=None)](#shuffle_batch) + * [tf.train.shuffle_batch_join(tensor_list_list, batch_size, capacity, min_after_dequeue, seed=None, enqueue_many=False, shapes=None, name=None)](#shuffle_batch_join) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Placeholders <div class="md-anchor" id="AUTOGENERATED-placeholders">{#AUTOGENERATED-placeholders}</div> + +TensorFlow provides a placeholder operation that must be fed with data +on execution. For more info, see the section on [Feeding +data](../../how_tos/reading_data/index.md#feeding). + +- - - + +### tf.placeholder(dtype, shape=None, name=None) <div class="md-anchor" id="placeholder">{#placeholder}</div> + +Inserts a placeholder for a tensor that will be always fed. + +**Important**: This tensor will produce an error if evaluated. Its value must +be fed using the `feed_dict` optional argument to `Session.run()`, +`Tensor.eval()`, or `Operation.run()`. + +For example: + +```python +x = tf.placeholder(float, shape=(1024, 1024)) +y = tf.matmul(x, x) + +with tf.Session() as sess: + print sess.run(y) # ERROR: will fail because x was not fed. + + rand_array = np.random.rand(1024, 1024) + print sess.run(y, feed_dict={x: rand_array}) # Will succeed. +``` + +##### Args: + + +* <b>dtype</b>: The type of elements in the tensor to be fed. +* <b>shape</b>: The shape of the tensor to be fed (optional). If the shape is not + specified, you can feed a tensor of any shape. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` that may be used as a handle for feeding a value, but not + evaluated directly. + + + +## Readers <div class="md-anchor" id="AUTOGENERATED-readers">{#AUTOGENERATED-readers}</div> + +TensorFlow provides a set of Reader classes for reading data formats. +For more information on inputs and readers, see [Reading +data](../../how_tos/reading_data/index.md). + +- - - + +### class tf.ReaderBase <div class="md-anchor" id="ReaderBase">{#ReaderBase}</div> + +Base class for different Reader types, that produce a record every step. + +Conceptually, Readers convert string 'work units' into records (key, +value pairs). Typically the 'work units' are filenames and the +records are extracted from the contents of those files. We want a +single record produced per step, but a work unit can correspond to +many records. + +Therefore we introduce some decoupling using a queue. The queue +contains the work units and the Reader dequeues from the queue when +it is asked to produce a record (via Read()) but it has finished the +last work unit. +- - - + +#### tf.ReaderBase.__init__(reader_ref, supports_serialize=False) {#ReaderBase.__init__} + +Creates a new ReaderBase. + +##### Args: + + +* <b>reader_ref</b>: The operation that implements the reader. +* <b>supports_serialize</b>: True if the reader implementation can + serialize its state. + + +- - - + +#### tf.ReaderBase.num_records_produced(name=None) {#ReaderBase.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.ReaderBase.num_work_units_completed(name=None) {#ReaderBase.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.ReaderBase.read(queue, name=None) {#ReaderBase.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.ReaderBase.reader_ref {#ReaderBase.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.ReaderBase.reset(name=None) {#ReaderBase.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.ReaderBase.restore_state(state, name=None) {#ReaderBase.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.ReaderBase.serialize_state(name=None) {#ReaderBase.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.ReaderBase.supports_serialize {#ReaderBase.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.TextLineReader <div class="md-anchor" id="TextLineReader">{#TextLineReader}</div> + +A Reader that outputs the lines of a file delimited by newlines. + +Newlines are stripped from the output. +See ReaderBase for supported methods. +- - - + +#### tf.TextLineReader.__init__(skip_header_lines=None, name=None) {#TextLineReader.__init__} + +Create a TextLineReader. + +##### Args: + + +* <b>skip_header_lines</b>: An optional int. Defaults to 0. Number of lines + to skip from the beginning of every file. +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.TextLineReader.num_records_produced(name=None) {#TextLineReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TextLineReader.num_work_units_completed(name=None) {#TextLineReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TextLineReader.read(queue, name=None) {#TextLineReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.TextLineReader.reader_ref {#TextLineReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.TextLineReader.reset(name=None) {#TextLineReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TextLineReader.restore_state(state, name=None) {#TextLineReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TextLineReader.serialize_state(name=None) {#TextLineReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.TextLineReader.supports_serialize {#TextLineReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.WholeFileReader <div class="md-anchor" id="WholeFileReader">{#WholeFileReader}</div> + +A Reader that outputs the entire contents of a file as a value. + +To use, enqueue filenames in a Queue. The output of Read will +be a filename (key) and the contents of that file (value). + +See ReaderBase for supported methods. +- - - + +#### tf.WholeFileReader.__init__(name=None) {#WholeFileReader.__init__} + +Create a WholeFileReader. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.WholeFileReader.num_records_produced(name=None) {#WholeFileReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.WholeFileReader.num_work_units_completed(name=None) {#WholeFileReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.WholeFileReader.read(queue, name=None) {#WholeFileReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.WholeFileReader.reader_ref {#WholeFileReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.WholeFileReader.reset(name=None) {#WholeFileReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.WholeFileReader.restore_state(state, name=None) {#WholeFileReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.WholeFileReader.serialize_state(name=None) {#WholeFileReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.WholeFileReader.supports_serialize {#WholeFileReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.IdentityReader <div class="md-anchor" id="IdentityReader">{#IdentityReader}</div> + +A Reader that outputs the queued work as both the key and value. + +To use, enqueue strings in a Queue. Read will take the front +work string and output (work, work). + +See ReaderBase for supported methods. +- - - + +#### tf.IdentityReader.__init__(name=None) {#IdentityReader.__init__} + +Create a IdentityReader. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.IdentityReader.num_records_produced(name=None) {#IdentityReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.IdentityReader.num_work_units_completed(name=None) {#IdentityReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.IdentityReader.read(queue, name=None) {#IdentityReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.IdentityReader.reader_ref {#IdentityReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.IdentityReader.reset(name=None) {#IdentityReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.IdentityReader.restore_state(state, name=None) {#IdentityReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.IdentityReader.serialize_state(name=None) {#IdentityReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.IdentityReader.supports_serialize {#IdentityReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.TFRecordReader <div class="md-anchor" id="TFRecordReader">{#TFRecordReader}</div> + +A Reader that outputs the records from a TFRecords file. + +See ReaderBase for supported methods. +- - - + +#### tf.TFRecordReader.__init__(name=None) {#TFRecordReader.__init__} + +Create a TFRecordReader. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.TFRecordReader.num_records_produced(name=None) {#TFRecordReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TFRecordReader.num_work_units_completed(name=None) {#TFRecordReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.TFRecordReader.read(queue, name=None) {#TFRecordReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.TFRecordReader.reader_ref {#TFRecordReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.TFRecordReader.reset(name=None) {#TFRecordReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TFRecordReader.restore_state(state, name=None) {#TFRecordReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.TFRecordReader.serialize_state(name=None) {#TFRecordReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.TFRecordReader.supports_serialize {#TFRecordReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + +- - - + +### class tf.FixedLengthRecordReader <div class="md-anchor" id="FixedLengthRecordReader">{#FixedLengthRecordReader}</div> + +A Reader that outputs fixed-length records from a file. + +See ReaderBase for supported methods. +- - - + +#### tf.FixedLengthRecordReader.__init__(record_bytes, header_bytes=None, footer_bytes=None, name=None) {#FixedLengthRecordReader.__init__} + +Create a FixedLengthRecordReader. + +##### Args: + + +* <b>record_bytes</b>: An int. +* <b>header_bytes</b>: An optional int. Defaults to 0. +* <b>footer_bytes</b>: An optional int. Defaults to 0. +* <b>name</b>: A name for the operation (optional). + + +- - - + +#### tf.FixedLengthRecordReader.num_records_produced(name=None) {#FixedLengthRecordReader.num_records_produced} + +Returns the number of records this reader has produced. + +This is the same as the number of Read executions that have +succeeded. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.num_work_units_completed(name=None) {#FixedLengthRecordReader.num_work_units_completed} + +Returns the number of work units this reader has finished processing. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + An int64 Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.read(queue, name=None) {#FixedLengthRecordReader.read} + +Returns the next record (key, value pair) produced by a reader. + +Will dequeue a work unit from queue if necessary (e.g. when the +Reader needs to start reading from a new file since it has +finished with the previous file). + +##### Args: + + +* <b>queue</b>: A Queue or a mutable string Tensor representing a handle + to a Queue, with string work items. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of Tensors (key, value). + +* <b>key</b>: A string scalar Tensor. +* <b>value</b>: A string scalar Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.reader_ref {#FixedLengthRecordReader.reader_ref} + +Op that implements the reader. + +- - - + +#### tf.FixedLengthRecordReader.reset(name=None) {#FixedLengthRecordReader.reset} + +Restore a reader to its initial clean state. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.FixedLengthRecordReader.restore_state(state, name=None) {#FixedLengthRecordReader.restore_state} + +Restore a reader to a previously saved state. + +Not all Readers support being restored, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>state</b>: A string Tensor. + Result of a SerializeState of a Reader with matching type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The created Operation. + + +- - - + +#### tf.FixedLengthRecordReader.serialize_state(name=None) {#FixedLengthRecordReader.serialize_state} + +Produce a string tensor that encodes the state of a reader. + +Not all Readers support being serialized, so this can produce an +Unimplemented error. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A string Tensor. + + +- - - + +#### tf.FixedLengthRecordReader.supports_serialize {#FixedLengthRecordReader.supports_serialize} + +Whether the Reader implementation can serialize its state. + + + +## Converting <div class="md-anchor" id="AUTOGENERATED-converting">{#AUTOGENERATED-converting}</div> + +TensorFlow provides several operations that you can use to convert various data +formats into tensors. + +- - - + +### tf.decode_csv(records, record_defaults, field_delim=None, name=None) <div class="md-anchor" id="decode_csv">{#decode_csv}</div> + +Convert CSV records to tensors. Each column maps to one tensor. + +RFC 4180 format is expected for the CSV records. +(https://tools.ietf.org/html/rfc4180) +Note that we allow leading and trailing spaces with int or float field. + +##### Args: + + +* <b>records</b>: A `Tensor` of type `string`. + Each string is a record/row in the csv and all records should have + the same format. +* <b>record_defaults</b>: A list of `Tensor` objects with types from: `float32`, `int32`, `int64`, `string`. + One tensor per column of the input record, with either a + scalar default value for that column or empty if the column is required. +* <b>field_delim</b>: An optional `string`. Defaults to `","`. + delimiter to separate fields in a record. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A list of `Tensor` objects. Has the same type as `record_defaults`. + Each tensor will have the same shape as records. + + +- - - + +### tf.decode_raw(bytes, out_type, little_endian=None, name=None) <div class="md-anchor" id="decode_raw">{#decode_raw}</div> + +Reinterpret the bytes of a string as a vector of numbers. + +##### Args: + + +* <b>bytes</b>: A `Tensor` of type `string`. + All the elements must have the same length. +* <b>out_type</b>: A `tf.DType` from: `tf.float32, tf.float64, tf.int32, tf.uint8, tf.int16, tf.int8, tf.int64`. +* <b>little_endian</b>: An optional `bool`. Defaults to `True`. + Whether the input bytes are in little-endian order. + Ignored for out_types that are stored in a single byte like uint8. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `out_type`. + A Tensor with one more dimension than the input bytes. The + added dimension will have size equal to the length of the elements + of bytes divided by the number of bytes to represent out_type. + + +- - - + +### tf.parse_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseExample') <div class="md-anchor" id="parse_example">{#parse_example}</div> + +Parse Example protos. + +##### Args: + + +* <b>serialized</b>: string vector, a batch of binary serialized Example protos. +* <b>names</b>: A string vector, the names of the serialized protos. + "names" may contain, e.g., table key (descriptive) names for the + corresponding serialized protos. These are purely useful for debugging + purposes, and the presence of values here has no effect on the output. + "names" may be an empty vector, if no names are available. + If non-empty, this vector must be the same length as "serialized". +* <b>sparse_keys</b>: A string list of keys in the Examples' features. + These keys are associated with sparse values. +* <b>sparse_types</b>: A list of DTypes. + This list's length must match that of sparse_keys. Currently + parse_example supports tf.float32 (FloatList), tf.int64 (Int64List), + and tf.string (BytesList). +* <b>dense_keys</b>: A string list of keys in the Examples' features. + These keys are associated with dense values. +* <b>dense_types</b>: A list of DTypes. + This list's length must match that of dense_keys. Currently + parse_example supports tf.float32 (FloatList), tf.int64 (Int64List), + and tf.string (BytesList). +* <b>dense_defaults</b>: A dict of {key:Tensor} (some may be missing). + The keys of the dict must match the dense_keys of the feature. + If a key is not present in this dictionary, the corresponding dense + Feature is required in all elements of serialized. +* <b>dense_shapes</b>: A list of tuples. + Entries provide the shape of data in each dense Feature in features. + The length of dense_shapes must be the same as the length of dense_keys. + The number of elements in the Feature corresponding to dense_key[j] + must always have np.prod(dense_shapes[j]) entries. + If dense_shapes[j] == (D0, D1, ..., DN) then the the shape of output + Tensor dense_values[j] will be (|serialized|, D0, D1, ..., DN): + The dense outputs are just the inputs row-stacked by batch. +* <b>name</b>: (Optional) Name of Op in the graph. + +##### Returns: + + A dictionary mapping keys to Tensors and SparseTensors. + + The key dense_keys[j] is mapped to a tensor of type dense_types[j] and + of shape (serialized.size(),) + dense_shapes[j] (i.e., the dense outputs are + inputs, reshaped in row-major format and then row-stacked by batch). + + The key sparse_keys[j] is mapped to a SparseTensor of type sparse_types[j]. + The SparseTensor represents a ragged matrix. Its indices are [batch, index] + where "batch" is is the batch entry the value is from, and "index" is the + value's index in the list of values associated with that feature + and example. For example, if one expects a tf.float32 sparse feature "ft" + and three serialized examples are provided: + + serialized = [ + +* <b>features</b>: + { feature: [ key: { "ft" value: float_list: { value: [1.0, 2.0] } } ] }, +* <b>features</b>: + { feature: [] }, +* <b>features</b>: + { feature: [ key: { "ft" value: float_list: { value: [3.0] } } ] } + ] + + then the output will look like: + + {"ft": SparseTensor(indices=[[0, 0], [0, 1], [2, 0]], + values=[1.0, 2.0, 3.0], + shape=(3, 2)) } + +##### Raises: + + +* <b>ValueError</b>: If sparse and dense keys intersect, or input lengths do not + match up for sparse_* (similarly for dense_*). +* <b>TypeError</b>: If an input is malformed. + +Example input, format, and output: Just Sparse Inputs +================================================ + +Given two brain.Example input protos: + + +* <b>serialized</b>: // serialized versions of the protos below + [features: { + +* <b>feature</b>: { key: "kw" value: { bytes_list: { value: [ "knit", "big" ] } } } +* <b>feature</b>: { key: "gps" value: { float_list: { value: [] } } } + }, +* <b>features</b>: { +* <b>feature</b>: { key: "kw" value: { bytes_list: { value: [ "emmy" ] } } } +* <b>feature</b>: { key: "dank" value: { int64_list: { value: [ 42 ] } } } +* <b>feature</b>: { key: "gps" value: { } } + }] + +* <b>names</b>: ["input0", "input1"], +* <b>sparse_keys</b>: ["kw", "dank", "gps"] +* <b>sparse_types</b>: [DT_STRING, DT_INT64, DT_FLOAT] + +Then the expected output is a dictionary: +{ + "kw": SparseTensor( + indices=[[0, 0], [0, 1], [1, 0]], + values=["knit", "big", "emmy"] + shape=[2, 2]), + "dank": SparseTensor( + indices=[[1, 0]], + values=[42], + shape=[2, 1]), + "gps": SparseTensor( + indices=[], + values=[], + shape=[2, 0]), +} + + +Example input, format, and output: Dense Inputs (without defaults) +================================================================== + +Given two brain.Example input protos: + + +* <b>serialized</b>: // serialized versions of the protos below + [features: { + +* <b>feature</b>: { key: "age" value: { int64_list: { value: [ 0 ] } } } +* <b>feature</b>: { key: "gender" value: { bytes_list: { value: [ "f" ] } } } + }, +* <b>features</b>: { +* <b>feature</b>: { key: "age" value: { int64_list: { value: [] } } } +* <b>feature</b>: { key: "gender" value: { bytes_list: { value: [ "f" ] } } } + }] + +* <b>names</b>: ["input0", "input1"], +* <b>dense_keys</b>: np.array(["age", "gender"]) +* <b>dense_types</b>: [tf.int64, tf.string] +* <b>dense_defaults</b>: { + "age": -1 # defaults to -1 if missing + # "gender" has no specified default so it's required +} + +* <b>dense_shapes</b>: [(1,), (1,)] # age, gender, label, weight + +Then the expected output is a dictionary: +{ + "age": [[0], [-1]], + "gender": [["f"], ["f"]], +} + + +Example input, format, and output: Dense Inputs (with defaults) +=============================================================== + +Given two brain.Example input protos: + + +* <b>serialized</b>: // serialized versions of the protos below + [features: { + +* <b>feature</b>: { key: "weight" value: { float_list: { value: [ 1.0 ] } } } + }, +* <b>features</b>: { +* <b>feature</b>: { key: "label" value: { float_list: { value: [ -1.0, 0.0 ] } } } + }] + +* <b>names</b>: ["input0", "input1"], +* <b>dense_keys</b>: np.array(["label", "weight"]) +* <b>dense_defaults</b>: { + "label": [1.0, 2.0], # float (default: vector) + "weight": 5.0 # float (default: scalar, 5.0) +} + +* <b>dense_shapes</b>: [(2,), (1,)] # age, gender, label, weight + +Then the expected output is a dictionary: +{ + "label": [[1.0, 2.0], [-1.0, 0.0]], + "weight": [[1.0], [5.0]], +} + + +- - - + +### tf.parse_single_example(serialized, names=None, sparse_keys=None, sparse_types=None, dense_keys=None, dense_types=None, dense_defaults=None, dense_shapes=None, name='ParseSingleExample') <div class="md-anchor" id="parse_single_example">{#parse_single_example}</div> + +Identical to parse_example but for scalar serialized and names. + +##### Args: + + +* <b>serialized</b>: A scalar string, a single serialized Example. + See parse_example documentation for more details. +* <b>names</b>: (Optional) A scalar string, the associated name. + See parse_example documentation for more details. +* <b>sparse_keys</b>: See parse_example documentation for more details. +* <b>sparse_types</b>: See parse_example documentation for more details. +* <b>dense_keys</b>: See parse_example documentation for more details. +* <b>dense_types</b>: See parse_example documentation for more details. +* <b>dense_defaults</b>: See parse_example documentation for more details. +* <b>dense_shapes</b>: See parse_example documentation for more details. +* <b>name</b>: Optional op name. + +##### Returns: + + A dictionary mapping keys to Tensors and SparseTensors. + + For dense tensors, the Tensor is identical to the output of parse_example, + except it is one less dimension (the first, batch, dimension is removed). + + For SparseTensors: + The first (batch) column of the indices matrix is removed + (it is now a column vector). + The values vector is unchanged. + The first (batch_size) entry of the shape vector is removed + (it is now a single element vector). + +##### Raises: + + +* <b>ValueError</b>: if "scalar" or "names" have known shapes, and are not scalars. + + + +## Queues <div class="md-anchor" id="AUTOGENERATED-queues">{#AUTOGENERATED-queues}</div> + +TensorFlow provides several implementations of 'Queues', which are +structures within the TensorFlow computation graph to stage pipelines +of tensors together. The following describe the basic Queue interface +and some implementations. To see an example use, see [Threading and +Queues](../../how_tos/threading_and_queues/index.md). + +- - - + +### class tf.QueueBase <div class="md-anchor" id="QueueBase">{#QueueBase}</div> + +Base class for queue implementations. + +A queue is a TensorFlow data structure that stores tensors across +multiple steps, and exposes operations that enqueue and dequeue +tensors. + +Each queue element is a tuple of one or more tensors, where each +tuple component has a static dtype, and may have a static shape. The +queue implementations support versions of enqueue and dequeue that +handle single elements, versions that support enqueuing and +dequeuing a batch of elements at once. + +See [`tf.FIFOQueue`](#FIFOQueue) and +[`tf.RandomShuffleQueue`](#RandomShuffleQueue) for concrete +implementations of this class, and instructions on how to create +them. + +- - - + +#### tf.QueueBase.enqueue(vals, name=None) {#QueueBase.enqueue} + +Enqueues one element to this queue. + +If the queue is full when this operation executes, it will block +until the element has been enqueued. + +##### Args: + + +* <b>vals</b>: The tuple of `Tensor` objects to be enqueued. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The operation that enqueues a new tuple of tensors to the queue. + + +- - - + +#### tf.QueueBase.enqueue_many(vals, name=None) {#QueueBase.enqueue_many} + +Enqueues zero or elements to this queue. + +This operation slices each component tensor along the 0th dimension to +make multiple queue elements. All of the tensors in `vals` must have the +same size in the 0th dimension. + +If the queue is full when this operation executes, it will block +until all of the elements have been enqueued. + +##### Args: + + +* <b>vals</b>: The tensor or tuple of tensors from which the queue elements + are taken. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The operation that enqueues a batch of tuples of tensors to the queue. + + + +- - - + +#### tf.QueueBase.dequeue(name=None) {#QueueBase.dequeue} + +Dequeues one element from this queue. + +If the queue is empty when this operation executes, it will block +until there is an element to dequeue. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The tuple of tensors that was dequeued. + + +- - - + +#### tf.QueueBase.dequeue_many(n, name=None) {#QueueBase.dequeue_many} + +Dequeues and concatenates `n` elements from this queue. + +This operation concatenates queue-element component tensors along +the 0th dimension to make a single component tensor. All of the +components in the dequeued tuple will have size `n` in the 0th dimension. + +If the queue contains fewer than `n` elements when this operation +executes, it will block until `n` elements have been dequeued. + +##### Args: + + +* <b>n</b>: A scalar `Tensor` containing the number of elements to dequeue. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The tuple of concatenated tensors that was dequeued. + + + +- - - + +#### tf.QueueBase.size(name=None) {#QueueBase.size} + +Compute the number of elements in this queue. + +##### Args: + + +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar tensor containing the number of elements in this queue. + + + +- - - + +#### tf.QueueBase.close(cancel_pending_enqueues=False, name=None) {#QueueBase.close} + +Closes this queue. + +This operation signals that no more elements will be enqueued in +the given queue. Subsequent `enqueue` and `enqueue_many` +operations will fail. Subsequent `dequeue` and `dequeue_many` +operations will continue to succeed if sufficient elements remain +in the queue. Subsequent `dequeue` and `dequeue_many` operations +that would block will fail immediately. + +If `cancel_pending_enqueues` is `True`, all pending requests will also +be cancelled. + +##### Args: + + +* <b>cancel_pending_enqueues</b>: (Optional.) A boolean, defaulting to + `False` (described above). +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The operation that closes the queue. + + + +#### Other Methods +- - - + +#### tf.QueueBase.__init__(dtypes, shapes, queue_ref) {#QueueBase.__init__} + +Constructs a queue object from a queue reference. + +##### Args: + + +* <b>dtypes</b>: A list of types. The length of dtypes must equal the number + of tensors in each element. +* <b>shapes</b>: Constraints on the shapes of tensors in an element: + A list of shape tuples or None. This list is the same length + as dtypes. If the shape of any tensors in the element are constrained, + all must be; shapes can be None if the shapes should not be constrained. +* <b>queue_ref</b>: The queue reference, i.e. the output of the queue op. + + +- - - + +#### tf.QueueBase.dtypes {#QueueBase.dtypes} + +The list of dtypes for each component of a queue element. + +- - - + +#### tf.QueueBase.name {#QueueBase.name} + +The name of the underlying queue. + +- - - + +#### tf.QueueBase.queue_ref {#QueueBase.queue_ref} + +The underlying queue reference. + + +- - - + +### class tf.FIFOQueue <div class="md-anchor" id="FIFOQueue">{#FIFOQueue}</div> + +A queue implementation that dequeues elements in first-in-first out order. + +See [`tf.QueueBase`](#QueueBase) for a description of the methods on +this class. + +- - - + +#### tf.FIFOQueue.__init__(capacity, dtypes, shapes=None, shared_name=None, name='fifo_queue') {#FIFOQueue.__init__} + +Creates a queue that dequeues elements in a first-in first-out order. + +A `FIFOQueue` has bounded capacity; supports multiple concurrent +producers and consumers; and provides exactly-once delivery. + +A `FIFOQueue` holds a list of up to `capacity` elements. Each +element is a fixed-length tuple of tensors whose dtypes are +described by `dtypes`, and whose shapes are optionally described +by the `shapes` argument. + +If the `shapes` argument is specified, each component of a queue +element must have the respective fixed shape. If it is +unspecified, different queue elements may have different shapes, +but the use of `dequeue_many` is disallowed. + +##### Args: + + +* <b>capacity</b>: An integer. The upper bound on the number of elements + that may be stored in this queue. +* <b>dtypes</b>: A list of `DType` objects. The length of `dtypes` must equal + the number of tensors in each queue element. +* <b>shapes</b>: (Optional.) A list of fully-defined `TensorShape` objects, + with the same length as `dtypes` or `None`. +* <b>shared_name</b>: (Optional.) If non-empty, this queue will be shared under + the given name across multiple sessions. +* <b>name</b>: Optional name for the queue operation. + + + +- - - + +### class tf.RandomShuffleQueue <div class="md-anchor" id="RandomShuffleQueue">{#RandomShuffleQueue}</div> + +A queue implementation that dequeues elements in a random order. + +See [`tf.QueueBase`](#QueueBase) for a description of the methods on +this class. + +- - - + +#### tf.RandomShuffleQueue.__init__(capacity, min_after_dequeue, dtypes, shapes=None, seed=None, shared_name=None, name='random_shuffle_queue') {#RandomShuffleQueue.__init__} + +Create a queue that dequeues elements in a random order. + +A `RandomShuffleQueue` has bounded capacity; supports multiple +concurrent producers and consumers; and provides exactly-once +delivery. + +A `RandomShuffleQueue` holds a list of up to `capacity` +elements. Each element is a fixed-length tuple of tensors whose +dtypes are described by `dtypes`, and whose shapes are optionally +described by the `shapes` argument. + +If the `shapes` argument is specified, each component of a queue +element must have the respective fixed shape. If it is +unspecified, different queue elements may have different shapes, +but the use of `dequeue_many` is disallowed. + +The `min_after_dequeue` argument allows the caller to specify a +minimum number of elements that will remain in the queue after a +`dequeue` or `dequeue_many` operation completes, to ensure a +minimum level of mixing of elements. This invariant is maintained +by blocking those operations until sufficient elements have been +enqueued. The `min_after_dequeue` argument is ignored after the +queue has been closed. + +##### Args: + + +* <b>capacity</b>: An integer. The upper bound on the number of elements + that may be stored in this queue. +* <b>min_after_dequeue</b>: An integer (described above). +* <b>dtypes</b>: A list of `DType` objects. The length of `dtypes` must equal + the number of tensors in each queue element. +* <b>shapes</b>: (Optional.) A list of fully-defined `TensorShape` objects, + with the same length as `dtypes` or `None`. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>shared_name</b>: (Optional.) If non-empty, this queue will be shared under + the given name across multiple sessions. +* <b>name</b>: Optional name for the queue operation. + + + + +## Dealing with the filesystem <div class="md-anchor" id="AUTOGENERATED-dealing-with-the-filesystem">{#AUTOGENERATED-dealing-with-the-filesystem}</div> + +- - - + +### tf.matching_files(pattern, name=None) <div class="md-anchor" id="matching_files">{#matching_files}</div> + +Returns the set of files matching a pattern. + +Note that this routine only supports wildcard characters in the +basename portion of the pattern, not in the directory portion. + +##### Args: + + +* <b>pattern</b>: A `Tensor` of type `string`. A (scalar) shell wildcard pattern. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. A vector of matching filenames. + + +- - - + +### tf.read_file(filename, name=None) <div class="md-anchor" id="read_file">{#read_file}</div> + +Reads and outputs the entire contents of the input filename. + +##### Args: + + +* <b>filename</b>: A `Tensor` of type `string`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `string`. + + + +## Input pipeline <div class="md-anchor" id="AUTOGENERATED-input-pipeline">{#AUTOGENERATED-input-pipeline}</div> + +TensorFlow functions for setting up an input-prefetching pipeline. +Please see the [reading data how-to](../../how_tos/reading_data.md) +for context. + +### Beginning of an input pipeline <div class="md-anchor" id="AUTOGENERATED-beginning-of-an-input-pipeline">{#AUTOGENERATED-beginning-of-an-input-pipeline}</div> + +The "producer" functions add a queue to the graph and a corresponding +`QueueRunner` for running the subgraph that fills that queue. + +- - - + +### tf.train.match_filenames_once(pattern, name=None) <div class="md-anchor" id="match_filenames_once">{#match_filenames_once}</div> + +Save the list of files matching pattern, so it is only computed once. + +##### Args: + + +* <b>pattern</b>: A file pattern (glob). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A variable that is initialized to the list of files matching pattern. + + +- - - + +### tf.train.limit_epochs(tensor, num_epochs=None, name=None) <div class="md-anchor" id="limit_epochs">{#limit_epochs}</div> + +Returns tensor num_epochs times and then raises an OutOfRange error. + +##### Args: + + +* <b>tensor</b>: Any Tensor. +* <b>num_epochs</b>: An integer (optional). If specified, limits the number + of steps the output tensor may be evaluated. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + tensor or OutOfRange. + + +- - - + +### tf.train.range_input_producer(limit, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None) <div class="md-anchor" id="range_input_producer">{#range_input_producer}</div> + +Produces the integers from 0 to limit-1 in a queue. + +##### Args: + + +* <b>limit</b>: An int32 scalar tensor. +* <b>num_epochs</b>: An integer (optional). If specified, `range_input_producer` + produces each integer `num_epochs` times before generating an + OutOfRange error. If not specified, `range_input_producer` can cycle + through the integers an unlimited number of times. +* <b>shuffle</b>: Boolean. If true, the integers are randomly shuffled within each + epoch. +* <b>seed</b>: An integer (optional). Seed used if shuffle == True. +* <b>capacity</b>: An integer. Sets the queue capacity. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A Queue with the output integers. A QueueRunner for the Queue + is added to the current Graph's QUEUE_RUNNER collection. + + +- - - + +### tf.train.slice_input_producer(tensor_list, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None) <div class="md-anchor" id="slice_input_producer">{#slice_input_producer}</div> + +Produces a slice of each Tensor in tensor_list. + +Implemented using a Queue -- a QueueRunner for the Queue +is added to the current Graph's QUEUE_RUNNER collection. + +##### Args: + + +* <b>tensor_list</b>: A list of Tensors. Every Tensor in tensor_list must + have the same size in the first dimension. +* <b>num_epochs</b>: An integer (optional). If specified, `slice_input_producer` + produces each slice `num_epochs` times before generating + an OutOfRange error. If not specified, `slice_input_producer` can cycle + through the slices an unlimited number of times. +* <b>seed</b>: An integer (optional). Seed used if shuffle == True. +* <b>capacity</b>: An integer. Sets the queue capacity. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors, one for each element of tensor_list. If the tensor + in tensor_list has shape [N, a, b, .., z], then the corresponding output + tensor will have shape [a, b, ..., z]. + + +- - - + +### tf.train.string_input_producer(string_tensor, num_epochs=None, shuffle=True, seed=None, capacity=32, name=None) <div class="md-anchor" id="string_input_producer">{#string_input_producer}</div> + +Output strings (e.g. filenames) to a queue for an input pipeline. + +##### Args: + + +* <b>string_tensor</b>: A 1-D string tensor with the strings to produce. +* <b>num_epochs</b>: An integer (optional). If specified, `string_input_producer` + produces each string from `string_tensor` `num_epochs` times before + generating an OutOfRange error. If not specified, `string_input_producer` + can cycle through the strings in `string_tensor` an unlimited number of + times. +* <b>shuffle</b>: Boolean. If true, the strings are randomly shuffled within each + epoch. +* <b>seed</b>: An integer (optional). Seed used if shuffle == True. +* <b>capacity</b>: An integer. Sets the queue capacity. +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A queue with the output strings. A QueueRunner for the Queue + is added to the current Graph's QUEUE_RUNNER collection. + + + +### Batching at the end of an input pipeline <div class="md-anchor" id="AUTOGENERATED-batching-at-the-end-of-an-input-pipeline">{#AUTOGENERATED-batching-at-the-end-of-an-input-pipeline}</div> + +These functions add a queue to the graph to assemble a batch of examples, with +possible shuffling. They also add a `QueueRunner` for running the subgraph +that fills that queue. + +Use [batch](#batch) or [batch_join](#batch_join) for batching examples that have +already been well shuffled. Use [shuffle_batch](#shuffle_batch) or +[shuffle_batch_join](#shuffle_batch_join) for examples that +would benefit from additional shuffling. + +Use [batch](#batch) or [shuffle_batch](#shuffle_batch) if you want a +single thread producing examples to batch, or if you have a +single subgraph producing examples but you want to run it in N threads +(where you increase N until it can keep the queue full). Use +[batch_join](#batch_join) or [shuffle_batch_join](#shuffle_batch_join) +if you have N different subgraphs producing examples to batch and you +want them run by N threads. + +- - - + +### tf.train.batch(tensor_list, batch_size, num_threads=1, capacity=32, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="batch">{#batch}</div> + +Run tensor_list to fill a queue to create batches. + +Implemented using a queue -- a QueueRunner for the queue +is added to the current Graph's QUEUE_RUNNER collection. + +##### Args: + + +* <b>tensor_list</b>: The list of tensors to enqueue. +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>num_threads</b>: The number of threads enqueuing tensor_list. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>enqueue_many</b>: If False, tensor_list is assumed to represent a + single example. If True, tensor_list is assumed to represent + a batch of examples, where the first dimension is indexed by + example, and all members of tensor_list should have the same + size in the first dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list (leaving off the first dimension + if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as tensor_list. + If enqueue_many is false, then an input tensor with shape + `[x, y, z]` will be output as a tensor with shape + `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + +- - - + +### tf.train.batch_join(tensor_list_list, batch_size, capacity=32, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="batch_join">{#batch_join}</div> + +Run a list of tensors to fill a queue to create batches of examples. + +This version enqueues a different list of tensors in different threads. +Implemented using a queue -- a QueueRunner for the queue +is added to the current Graph's QUEUE_RUNNER collection. + +##### Args: + + +* <b>tensor_list_list</b>: A list of tuples of tensors to enqueue. + len(tensor_list_list) threads will be started, with the i-th + thread enqueuing the tensors from tensor_list[i]. + tensor_list[i1][j] must match tensor_list[i2][j] in type and + shape (except in the first dimension if enqueue_many is true). +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>enqueue_many</b>: If False, each tensor_list_list[i] is assumed to + represent a single example. If True, tensor_list_list[i] is + assumed to represent a batch of examples, where the first + dimension is indexed by example, and all members of + tensor_list_list[i] should have the same size in the first + dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list_list[i] (which must match, after + leaving off the first dimension if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as + tensor_list_list[i]. If enqueue_many is false, then an input + tensor with shape `[x, y, z]` will be output as a tensor with + shape `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + +- - - + +### tf.train.shuffle_batch(tensor_list, batch_size, capacity, min_after_dequeue, num_threads=1, seed=None, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="shuffle_batch">{#shuffle_batch}</div> + +Create batches by randomly shuffling tensors. + +This adds: + +* a shuffling queue into which tensors from tensor_list are enqueued. +* a dequeue many operation to create batches from the queue, +* and a QueueRunner is added to the current Graph's QUEUE_RUNNER collection, + to enqueue the tensors from tensor_list. + +##### Args: + + +* <b>tensor_list</b>: The list of tensors to enqueue. +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>min_after_dequeue</b>: Minimum number elements in the queue after a + dequeue, used to ensure a level of mixing of elements. +* <b>num_threads</b>: The number of threads enqueuing tensor_list. +* <b>seed</b>: Seed for the random shuffling within the queue. +* <b>enqueue_many</b>: If False, tensor_list is assumed to represent a + single example. If True, tensor_list is assumed to represent + a batch of examples, where the first dimension is indexed by + example, and all members of tensor_list should have the same + size in the first dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list (leaving off the first dimension + if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as tensor_list. + If enqueue_many is false, then an input tensor with shape + `[x, y, z]` will be output as a tensor with shape + `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + +- - - + +### tf.train.shuffle_batch_join(tensor_list_list, batch_size, capacity, min_after_dequeue, seed=None, enqueue_many=False, shapes=None, name=None) <div class="md-anchor" id="shuffle_batch_join">{#shuffle_batch_join}</div> + +Create batches by randomly shuffling tensors. + +This version enqueues a different list of tensors in different threads. +It adds: + +* a shuffling queue into which tensors from tensor_list_list are enqueued. +* a dequeue many operation to create batches from the queue, +* and a QueueRunner is added to the current Graph's QUEUE_RUNNER collection, + to enqueue the tensors from tensor_list_list. + +##### Args: + + +* <b>tensor_list_list</b>: A list of tuples of tensors to enqueue. + len(tensor_list_list) threads will be started, with the i-th + thread enqueuing the tensors from tensor_list[i]. + tensor_list[i1][j] must match tensor_list[i2][j] in type and + shape (except in the first dimension if enqueue_many is true). +* <b>batch_size</b>: The new batch size pulled from the queue. +* <b>capacity</b>: Maximum number of elements in the queue, controls the + how far ahead the prefetching allowed is allowed to get and + memory usage. +* <b>min_after_dequeue</b>: Minimum number elements in the queue after a + dequeue, used to ensure a level of mixing of elements. +* <b>seed</b>: Seed for the random shuffling within the queue. +* <b>enqueue_many</b>: If False, each tensor_list_list[i] is assumed to + represent a single example. If True, tensor_list_list[i] is + assumed to represent a batch of examples, where the first + dimension is indexed by example, and all members of + tensor_list_list[i] should have the same size in the first + dimension. +* <b>shapes</b>: Optional. The shapes for each example. Defaults to the + inferred shapes for tensor_list_list[i] (which must match, after + leaving off the first dimension if enqueue_many is True). +* <b>name</b>: A name for the operations (optional). + +##### Returns: + + A list of tensors with the same number and types as + tensor_list_list[i]. If enqueue_many is false, then an input + tensor with shape `[x, y, z]` will be output as a tensor with + shape `[batch_size, x, y, z]`. If enqueue_many is True, and an + input tensor has shape `[*, x, y, z]`, the the output will have + shape `[batch_size, x, y, z]`. + + diff --git a/tensorflow/g3doc/api_docs/python/math_ops.md b/tensorflow/g3doc/api_docs/python/math_ops.md new file mode 100644 index 0000000000..fb93c38311 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/math_ops.md @@ -0,0 +1,1883 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Math +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Arithmetic Operators](#AUTOGENERATED-arithmetic-operators) + * [tf.add(x, y, name=None)](#add) + * [tf.sub(x, y, name=None)](#sub) + * [tf.mul(x, y, name=None)](#mul) + * [tf.div(x, y, name=None)](#div) + * [tf.mod(x, y, name=None)](#mod) +* [Basic Math Functions](#AUTOGENERATED-basic-math-functions) + * [tf.add_n(inputs, name=None)](#add_n) + * [tf.abs(x, name=None)](#abs) + * [tf.neg(x, name=None)](#neg) + * [tf.sign(x, name=None)](#sign) + * [tf.inv(x, name=None)](#inv) + * [tf.square(x, name=None)](#square) + * [tf.round(x, name=None)](#round) + * [tf.sqrt(x, name=None)](#sqrt) + * [tf.rsqrt(x, name=None)](#rsqrt) + * [tf.pow(x, y, name=None)](#pow) + * [tf.exp(x, name=None)](#exp) + * [tf.log(x, name=None)](#log) + * [tf.ceil(x, name=None)](#ceil) + * [tf.floor(x, name=None)](#floor) + * [tf.maximum(x, y, name=None)](#maximum) + * [tf.minimum(x, y, name=None)](#minimum) + * [tf.cos(x, name=None)](#cos) + * [tf.sin(x, name=None)](#sin) +* [Matrix Math Functions](#AUTOGENERATED-matrix-math-functions) + * [tf.diag(diagonal, name=None)](#diag) + * [tf.transpose(a, perm=None, name='transpose')](#transpose) + * [tf.matmul(a, b, transpose_a=False, transpose_b=False, a_is_sparse=False, b_is_sparse=False, name=None)](#matmul) + * [tf.batch_matmul(x, y, adj_x=None, adj_y=None, name=None)](#batch_matmul) + * [tf.matrix_determinant(input, name=None)](#matrix_determinant) + * [tf.batch_matrix_determinant(input, name=None)](#batch_matrix_determinant) + * [tf.matrix_inverse(input, name=None)](#matrix_inverse) + * [tf.batch_matrix_inverse(input, name=None)](#batch_matrix_inverse) + * [tf.cholesky(input, name=None)](#cholesky) + * [tf.batch_cholesky(input, name=None)](#batch_cholesky) +* [Complex Number Functions](#AUTOGENERATED-complex-number-functions) + * [tf.complex(real, imag, name=None)](#complex) + * [tf.complex_abs(x, name=None)](#complex_abs) + * [tf.conj(in_, name=None)](#conj) + * [tf.imag(in_, name=None)](#imag) + * [tf.real(in_, name=None)](#real) +* [Reduction](#AUTOGENERATED-reduction) + * [tf.reduce_sum(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_sum) + * [tf.reduce_prod(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_prod) + * [tf.reduce_min(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_min) + * [tf.reduce_max(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_max) + * [tf.reduce_mean(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_mean) + * [tf.reduce_all(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_all) + * [tf.reduce_any(input_tensor, reduction_indices=None, keep_dims=False, name=None)](#reduce_any) + * [tf.accumulate_n(inputs, shape=None, tensor_dtype=None, name=None)](#accumulate_n) +* [Segmentation](#AUTOGENERATED-segmentation) + * [tf.segment_sum(data, segment_ids, name=None)](#segment_sum) + * [tf.segment_prod(data, segment_ids, name=None)](#segment_prod) + * [tf.segment_min(data, segment_ids, name=None)](#segment_min) + * [tf.segment_max(data, segment_ids, name=None)](#segment_max) + * [tf.segment_mean(data, segment_ids, name=None)](#segment_mean) + * [tf.unsorted_segment_sum(data, segment_ids, num_segments, name=None)](#unsorted_segment_sum) + * [tf.sparse_segment_sum(data, indices, segment_ids, name=None)](#sparse_segment_sum) + * [tf.sparse_segment_mean(data, indices, segment_ids, name=None)](#sparse_segment_mean) +* [Sequence Comparison and Indexing](#AUTOGENERATED-sequence-comparison-and-indexing) + * [tf.argmin(input, dimension, name=None)](#argmin) + * [tf.argmax(input, dimension, name=None)](#argmax) + * [tf.listdiff(x, y, name=None)](#listdiff) + * [tf.where(input, name=None)](#where) + * [tf.unique(x, name=None)](#unique) + * [tf.edit_distance(hypothesis, truth, normalize=True, name='edit_distance')](#edit_distance) + * [tf.invert_permutation(x, name=None)](#invert_permutation) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Arithmetic Operators <div class="md-anchor" id="AUTOGENERATED-arithmetic-operators">{#AUTOGENERATED-arithmetic-operators}</div> + +TensorFlow provides several operations that you can use to add basic arithmetic +operators to your graph. + +- - - + +### tf.add(x, y, name=None) <div class="md-anchor" id="add">{#add}</div> + +Returns x + y element-wise. + +*NOTE*: Add supports broadcasting. AddN does not. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int8`, `int16`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.sub(x, y, name=None) <div class="md-anchor" id="sub">{#sub}</div> + +Returns x - y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.mul(x, y, name=None) <div class="md-anchor" id="mul">{#mul}</div> + +Returns x * y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int8`, `int16`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.div(x, y, name=None) <div class="md-anchor" id="div">{#div}</div> + +Returns x / y element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.mod(x, y, name=None) <div class="md-anchor" id="mod">{#mod}</div> + +Returns element-wise remainder of division. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`, `float32`, `float64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + + +## Basic Math Functions <div class="md-anchor" id="AUTOGENERATED-basic-math-functions">{#AUTOGENERATED-basic-math-functions}</div> + +TensorFlow provides several operations that you can use to add basic +mathematical functions to your graph. + +- - - + +### tf.add_n(inputs, name=None) <div class="md-anchor" id="add_n">{#add_n}</div> + +Add all input tensors element wise. + +##### Args: + + +* <b>inputs</b>: A list of at least 1 `Tensor` objects of the same type in: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Must all be the same size and shape. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `inputs`. + + +- - - + +### tf.abs(x, name=None) <div class="md-anchor" id="abs">{#abs}</div> + +Computes the absolute value of a tensor. + +Given a tensor of real numbers `x`, this operation returns a tensor +containing the absolute value of each element in `x`. For example, if x is +an input element and y is an output element, this operation computes +\\(y = |x|\\). + +See [`tf.complex_abs()`](#tf_complex_abs) to compute the absolute value of a complex +number. + +##### Args: + + +* <b>x</b>: A `Tensor` of type `float`, `double`, `int32`, or `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` the same size and type as `x` with absolute values. + + +- - - + +### tf.neg(x, name=None) <div class="md-anchor" id="neg">{#neg}</div> + +Computes numerical negative value element-wise. + +I.e., \\(y = -x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.sign(x, name=None) <div class="md-anchor" id="sign">{#sign}</div> + +Returns an element-wise indication of the sign of a number. + +y = sign(x) = -1 if x < 0; 0 if x == 0; 1 if x > 0. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.inv(x, name=None) <div class="md-anchor" id="inv">{#inv}</div> + +Computes the reciprocal of x element-wise. + +I.e., \\(y = 1 / x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.square(x, name=None) <div class="md-anchor" id="square">{#square}</div> + +Computes square of x element-wise. + +I.e., \\(y = x * x = x^2\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.round(x, name=None) <div class="md-anchor" id="round">{#round}</div> + +Rounds the values of a tensor to the nearest integer, element-wise. + +For example: + +```python +# 'a' is [0.9, 2.5, 2.3, -4.4] +tf.round(a) ==> [ 1.0, 3.0, 2.0, -4.0 ] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `float` or `double`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of same shape and type as `x`. + + +- - - + +### tf.sqrt(x, name=None) <div class="md-anchor" id="sqrt">{#sqrt}</div> + +Computes square root of x element-wise. + +I.e., \\(y = \sqrt{x} = x^{1/2}\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.rsqrt(x, name=None) <div class="md-anchor" id="rsqrt">{#rsqrt}</div> + +Computes reciprocal of square root of x element-wise. + +I.e., \\(y = 1 / \sqrt{x}\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.pow(x, y, name=None) <div class="md-anchor" id="pow">{#pow}</div> + +Computes the power of one value to another. + +Given a tensor `x` and a tensor `y`, this operation computes \\(x^y\\) for +corresponding elements in `x` and `y`. For example: + +``` +# tensor 'x' is [[2, 2]], [3, 3]] +# tensor 'y' is [[8, 16], [2, 3]] +tf.pow(x, y) ==> [[256, 65536], [9, 27]] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `float`, `double`, `int32`, `complex64`, or `int64`. +* <b>y</b>: A `Tensor` of type `float`, `double`, `int32`, `complex64`, or `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. + + +- - - + +### tf.exp(x, name=None) <div class="md-anchor" id="exp">{#exp}</div> + +Computes exponential of x element-wise. \\(y = e^x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.log(x, name=None) <div class="md-anchor" id="log">{#log}</div> + +Computes natural logrithm of x element-wise. + +I.e., \\(y = \log_e x\\). + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.ceil(x, name=None) <div class="md-anchor" id="ceil">{#ceil}</div> + +Returns element-wise smallest integer in not less than x. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.floor(x, name=None) <div class="md-anchor" id="floor">{#floor}</div> + +Returns element-wise largest integer not greater than x. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.maximum(x, y, name=None) <div class="md-anchor" id="maximum">{#maximum}</div> + +Returns the max of x and y (i.e. x > y ? x : y) element-wise, broadcasts. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.minimum(x, y, name=None) <div class="md-anchor" id="minimum">{#minimum}</div> + +Returns the min of x and y (i.e. x < y ? x : y) element-wise, broadcasts. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.cos(x, name=None) <div class="md-anchor" id="cos">{#cos}</div> + +Computes cos of x element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + +- - - + +### tf.sin(x, name=None) <div class="md-anchor" id="sin">{#sin}</div> + +Computes sin of x element-wise. + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`, `int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + + + +## Matrix Math Functions <div class="md-anchor" id="AUTOGENERATED-matrix-math-functions">{#AUTOGENERATED-matrix-math-functions}</div> + +TensorFlow provides several operations that you can use to add basic +mathematical functions for matrices to your graph. + +- - - + +### tf.diag(diagonal, name=None) <div class="md-anchor" id="diag">{#diag}</div> + +Returns a diagonal tensor with a given diagonal values. + +Given a `diagonal`, this operation returns a tensor with the `diagonal` and +everything else padded with zeros. The diagonal is computed as follows: + +Assume `diagonal` has dimensions [D1,..., Dk], then the output is a tensor of +rank 2k with dimensions [D1,..., Dk, D1,..., Dk] where: + +`output[i1,..., ik, i1,..., ik] = diagonal[i1, ..., ik]` and 0 everywhere else. + +For example: + +```prettyprint +# 'diagonal' is [1, 2, 3, 4] +tf.diag(diagonal) ==> [[1, 0, 0, 0] + [0, 2, 0, 0] + [0, 0, 3, 0] + [0, 0, 0, 4]] +``` + +##### Args: + + +* <b>diagonal</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`. + Rank k tensor where k is at most 3. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `diagonal`. + + +- - - + +### tf.transpose(a, perm=None, name='transpose') <div class="md-anchor" id="transpose">{#transpose}</div> + +Transposes `a`. Permutes the dimensions according to `perm`. + +The returned tensor's dimension i will correspond to the input dimension +`perm[i]`. If `perm` is not given, it is set to (n-1...0), where n is +the rank of the input tensor. Hence by default, this operation performs a +regular matrix transpose on 2-D input Tensors. + +For example: + +```python +# 'x' is [[1 2 3] +# [4 5 6]] +tf.transpose(x) ==> [[1 4] + [2 5] + [3 6]] + +# Equivalently +tf.transpose(x perm=[0, 1]) ==> [[1 4] + [2 5] + [3 6]] + +# 'perm' is more useful for n-dimensional tensors, for n > 2 +# 'x' is [[[1 2 3] +# [4 5 6]] +# [[7 8 9] +# [10 11 12]]] +# Take the transpose of the matrices in dimension-0 +tf.transpose(b, perm=[0, 2, 1]) ==> [[[1 4] + [2 5] + [3 6]] + + [[7 10] + [8 11] + [9 12]]] +``` + +##### Args: + + +* <b>a</b>: A `Tensor`. +* <b>perm</b>: A permutation of the dimensions of `a`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A transposed `Tensor`. + + + +- - - + +### tf.matmul(a, b, transpose_a=False, transpose_b=False, a_is_sparse=False, b_is_sparse=False, name=None) <div class="md-anchor" id="matmul">{#matmul}</div> + +Multiplies matrix `a` by matrix `b`, producing `a` * `b`. + +The inputs must be two-dimensional matrices, with matching inner dimensions, +possibly after transposition. + +Both matrices must be of the same type. The supported types are: +`float`, `double`, `int32`, `complex64`. + +Either matrix can be transposed on the fly by setting the corresponding flag +to `True`. This is `False` by default. + +If one or both of the matrices contain a lot of zeros, a more efficient +multiplication algorithm can be used by setting the corresponding +`a_is_sparse` or `b_is_sparse` flag to `True`. These are `False` by default. + +For example: + +```python +# 2-D tensor `a` +a = tf.constant([1, 2, 3, 4, 5, 6], shape=[2, 3]) => [[1. 2. 3.] + [4. 5. 6.]] +# 2-D tensor `b` +b = tf.constant([7, 8, 9, 10, 11, 12], shape=[3, 2]) => [[7. 8.] + [9. 10.] + [11. 12.]] +c = tf.matmul(a, b) => [[58 64] + [139 154]] +``` + +##### Args: + + +* <b>a</b>: `Tensor` of type `float`, `double`, `int32` or `complex64`. +* <b>b</b>: `Tensor` with same type as `a`. +* <b>transpose_a</b>: If `True`, `a` is transposed before multiplication. +* <b>transpose_b</b>: If `True`, `b` is transposed before multiplication. +* <b>a_is_sparse</b>: If `True`, `a` is treated as a sparse matrix. +* <b>b_is_sparse</b>: If `True`, `b` is treated as a sparse matrix. +* <b>name</b>: Name for the operation (optional). + +##### Returns: + + A `Tensor` of the same type as `a`. + + +- - - + +### tf.batch_matmul(x, y, adj_x=None, adj_y=None, name=None) <div class="md-anchor" id="batch_matmul">{#batch_matmul}</div> + +Multiplies slices of two tensors in batches. + +Multiplies all slices of `Tensor` `x` and `y` (each slice can be +viewed as an element of a batch), and arranges the individual results +in a single output tensor of the same batch size. Each of the +individual slices can optionally be adjointed (to adjoint a matrix +means to transpose and conjugate it) before multiplication by setting +the `adj_x` or `adj_y` flag to `True`, which are by default `False`. + +The input tensors `x` and `y` are 3-D or higher with shape `[..., r_x, c_x]` +and `[..., r_y, c_y]`. + +The output tensor is 3-D or higher with shape `[..., r_o, c_o]`, where: + + r_o = c_x if adj_x else r_x + c_o = r_y if adj_y else c_y + +It is computed as: + + out[..., :, :] = matrix(x[..., :, :]) * matrix(y[..., :, :]) + +##### Args: + + +* <b>x</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `complex64`. + 3-D or higher with shape `[..., r_x, c_x]`. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. + 3-D or higher with shape `[..., r_y, c_y]`. +* <b>adj_x</b>: An optional `bool`. Defaults to `False`. + If `True`, adjoint the slices of `x`. Defaults to `False`. +* <b>adj_y</b>: An optional `bool`. Defaults to `False`. + If `True`, adjoint the slices of `y`. Defaults to `False`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `x`. + 3-D or higher with shape `[..., r_o, c_o]` + + + +- - - + +### tf.matrix_determinant(input, name=None) <div class="md-anchor" id="matrix_determinant">{#matrix_determinant}</div> + +Calculates the determinant of a square matrix. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + A tensor of shape `[M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + A scalar, equal to the determinant of the input. + + +- - - + +### tf.batch_matrix_determinant(input, name=None) <div class="md-anchor" id="batch_matrix_determinant">{#batch_matrix_determinant}</div> + +Calculates the determinants for a batch of square matrices. + +The input is a tensor of shape `[..., M, M]` whose inner-most 2 dimensions +form square matrices. The output is a 1-D tensor containing the determinants +for all input submatrices `[..., :, :]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + Shape is `[..., M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[...]`. + + + +- - - + +### tf.matrix_inverse(input, name=None) <div class="md-anchor" id="matrix_inverse">{#matrix_inverse}</div> + +Calculates the inverse of a square invertible matrix. Checks for invertibility. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + Shape is `[M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + Shape is `[M, M]` containing the matrix inverse of the input. + + +- - - + +### tf.batch_matrix_inverse(input, name=None) <div class="md-anchor" id="batch_matrix_inverse">{#batch_matrix_inverse}</div> + +Calculates the inverse of square invertible matrices. Checks for invertibility. + +The input is a tensor of shape `[..., M, M]` whose inner-most 2 dimensions +form square matrices. The output is a tensor of the same shape as the input +containing the inverse for all input submatrices `[..., :, :]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + Shape is `[..., M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[..., M, M]`. + + + +- - - + +### tf.cholesky(input, name=None) <div class="md-anchor" id="cholesky">{#cholesky}</div> + +Calculates the Cholesky decomposition of a square matrix. + +The input has to be symmetric and positive definite. Only the lower-triangular +part of the input will be used for this operation. The upper-triangular part +will not be read. + +The result is the lower-triangular matrix of the Cholesky decomposition of the +input. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float64`, `float32`. + Shape is `[M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[M, M]`. + + +- - - + +### tf.batch_cholesky(input, name=None) <div class="md-anchor" id="batch_cholesky">{#batch_cholesky}</div> + +Calculates the Cholesky decomposition of a batch of square matrices. + +The input is a tensor of shape `[..., M, M]` whose inner-most 2 dimensions +form square matrices, with the same constraints as the single matrix Cholesky +decomposition above. The output is a tensor of the same shape as the input +containing the Cholesky decompositions for all input submatrices `[..., :, :]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float64`, `float32`. + Shape is `[..., M, M]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. Shape is `[..., M, M]`. + + + +## Complex Number Functions <div class="md-anchor" id="AUTOGENERATED-complex-number-functions">{#AUTOGENERATED-complex-number-functions}</div> + +TensorFlow provides several operations that you can use to add complex number +functions to your graph. + +- - - + +### tf.complex(real, imag, name=None) <div class="md-anchor" id="complex">{#complex}</div> + +Converts two real numbers to a complex number. + +Given a tensor `real` representing the real part of a complex number, and a +tensor `imag` representing the imaginary part of a complex number, this +operation computes complex numbers elementwise of the form \\(a + bj\\), +where *a* represents the `real` part and *b* represents the `imag` part. + +The input tensors `real` and `imag` must be the same shape. + +For example: + +``` +# tensor 'real' is [2.25, 3.25] +# tensor `imag` is [4.75, 5.75] +tf.complex(real, imag) ==> [[2.25 + 4.74j], [3.25 + 5.75j]] +``` + +##### Args: + + +* <b>real</b>: A `Tensor` of type `float`. +* <b>imag</b>: A `Tensor` of type `float`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `complex64`. + + +- - - + +### tf.complex_abs(x, name=None) <div class="md-anchor" id="complex_abs">{#complex_abs}</div> + +Computes the complex absolute value of a tensor. + +Given a tensor `x` of complex numbers, this operation returns a tensor of type +`float` 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: + +``` +# tensor 'x' is [[-2.25 + 4.75j], [-3.25 + 5.75j]] +tf.complex_abs(x) ==> [5.25594902, 6.60492229] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + +- - - + +### tf.conj(in_, name=None) <div class="md-anchor" id="conj">{#conj}</div> + +Returns the complex conjugate of a complex number. + +Given a tensor `in` of complex numbers, this operation returns a tensor of +complex numbers that are the complex conjugate of each element in `in`. The +complex numbers in `in` must be of the form \\(a + bj\\), where *a* is the real +part and *b* is the imaginary part. + +The complex conjugate returned by this operation is of the form \\(a - bj\\). + +For example: + +``` +# tensor 'in' is [-2.25 + 4.75j, 3.25 + 5.75j] +tf.conj(in) ==> [-2.25 - 4.75j, 3.25 - 5.75j] +``` + +##### Args: + + +* <b>in_</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `complex64`. + + +- - - + +### tf.imag(in_, name=None) <div class="md-anchor" id="imag">{#imag}</div> + +Returns the imaginary part of a complex number. + +Given a tensor `in` of complex numbers, this operation returns a tensor of type +`float` that is the imaginary part of each element in `in`. All elements in `in` +must be complex numbers of the form \\(a + bj\\), where *a* is the real part +and *b* is the imaginary part returned by this operation. + +For example: + +``` +# tensor 'in' is [-2.25 + 4.75j, 3.25 + 5.75j] +tf.imag(in) ==> [4.75, 5.75] +``` + +##### Args: + + +* <b>in_</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + +- - - + +### tf.real(in_, name=None) <div class="md-anchor" id="real">{#real}</div> + +Returns the real part of a complex number. + +Given a tensor `in` of complex numbers, this operation returns a tensor of type +`float` that is the real part of each element in `in`. All elements in `in` +must be complex numbers of the form \\(a + bj\\), where *a* is the real part +returned by this operation and *b* is the imaginary part. + +For example: + +``` +# tensor 'in' is [-2.25 + 4.75j, 3.25 + 5.75j] +tf.real(in) ==> [-2.25, 3.25] +``` + +##### Args: + + +* <b>in_</b>: A `Tensor` of type `complex64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + + +## Reduction <div class="md-anchor" id="AUTOGENERATED-reduction">{#AUTOGENERATED-reduction}</div> + +TensorFlow provides several operations that you can use to perform +common math computations that reduce various dimensions of a tensor. + +- - - + +### tf.reduce_sum(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_sum">{#reduce_sum}</div> + +Computes the sum of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[1, 1, 1]] +# [1, 1, 1]] +tf.reduce_sum(x) ==> 6 +tf.reduce_sum(x, 0) ==> [2, 2, 2] +tf.reduce_sum(x, 1) ==> [3, 3] +tf.reduce_sum(x, 1, keep_dims=True) ==> [[3], [3]] +tf.reduce_sum(x, [0, 1]) ==> 6 +``` + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_prod(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_prod">{#reduce_prod}</div> + +Computes the product of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_min(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_min">{#reduce_min}</div> + +Computes the minimum of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_max(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_max">{#reduce_max}</div> + +Computes the maximum of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_mean(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_mean">{#reduce_mean}</div> + +Computes the mean of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[1., 1. ]] +# [2., 2.]] +tf.reduce_mean(x) ==> 1.5 +tf.reduce_mean(x, 0) ==> [1.5, 1.5] +tf.reduce_mean(x, 1) ==> [1., 2.] +``` + +##### Args: + + +* <b>input_tensor</b>: The tensor to reduce. Should have numeric type. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_all(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_all">{#reduce_all}</div> + +Computes the "logical and" of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[True, True]] +# [False, False]] +tf.reduce_all(x) ==> False +tf.reduce_all(x, 0) ==> [False, False] +tf.reduce_all(x, 1) ==> [True, False] +``` + +##### Args: + + +* <b>input_tensor</b>: The boolean tensor to reduce. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + +- - - + +### tf.reduce_any(input_tensor, reduction_indices=None, keep_dims=False, name=None) <div class="md-anchor" id="reduce_any">{#reduce_any}</div> + +Computes the "logical or" of elements across dimensions of a tensor. + +Reduces `input_tensor` along the dimensions given in `reduction_indices`. +Unless `keep_dims` is true, the rank of the tensor is reduced by 1 for each +entry in `reduction_indices`. If `keep_dims` is true, the reduced dimensions +are retained with length 1. + +If `reduction_indices` has no entries, all dimensions are reduced, and a +tensor with a single element is returned. + +For example: + +```python +# 'x' is [[True, True]] +# [False, False]] +tf.reduce_any(x) ==> True +tf.reduce_any(x, 0) ==> [True, True] +tf.reduce_any(x, 1) ==> [True, False] +``` + +##### Args: + + +* <b>input_tensor</b>: The boolean tensor to reduce. +* <b>reduction_indices</b>: The dimensions to reduce. If `None` (the defaut), + reduces all dimensions. +* <b>keep_dims</b>: If true, retains reduced dimensions with length 1. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The reduced tensor. + + + +- - - + +### tf.accumulate_n(inputs, shape=None, tensor_dtype=None, name=None) <div class="md-anchor" id="accumulate_n">{#accumulate_n}</div> + +Returns the element-wise sum of a list of tensors. + +Optionally, pass `shape` and `tensor_dtype` for shape and type checking, +otherwise, these are inferred. + +For example: + +```python +# tensor 'a' is [[1, 2], [3, 4] +# tensor `b` is [[5, 0], [0, 6]] +tf.accumulate_n([a, b, a]) ==> [[7, 4], [6, 14]] + +# Explicitly pass shape and type +tf.accumulate_n([a, b, a], shape=[2, 2], tensor_dtype=tf.int32) + ==> [[7, 4], [6, 14]] +``` + +##### Args: + + +* <b>inputs</b>: A list of `Tensor` objects, each with same shape and type. +* <b>shape</b>: Shape of elements of `inputs`. +* <b>tensor_dtype</b>: The type of `inputs`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of same shape and type as the elements of `inputs`. + +##### Raises: + + +* <b>ValueError</b>: If `inputs` don't all have same shape and dtype or the shape + cannot be inferred. + + + +## Segmentation <div class="md-anchor" id="AUTOGENERATED-segmentation">{#AUTOGENERATED-segmentation}</div> + +TensorFlow provides several operations that you can use to perform common +math computations on tensor segments. +Here a segmentation is a partitioning of a tensor along +the first dimension, i.e. it defines a mapping from the first dimension onto +`segment_ids`. The `segment_ids` tensor should be the size of +the first dimension, `d0`, with consecutive IDs in the range `0` to `k`, +where `k<d0`. +In particular, a segmentation of a matrix tensor is a mapping of rows to +segments. + +For example: + +```python +c = tf.constant([[1,2,3,4], [-1,-2,-3,-4], [5,6,7,8]]) +tf.segment_sum(c, tf.constant([0, 0, 1])) + ==> [[0 0 0 0] + [5 6 7 8]] +``` + +- - - + +### tf.segment_sum(data, segment_ids, name=None) <div class="md-anchor" id="segment_sum">{#segment_sum}</div> + +Computes the sum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \sum_j data_j\\) where sum is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentSum.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_prod(data, segment_ids, name=None) <div class="md-anchor" id="segment_prod">{#segment_prod}</div> + +Computes the product along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \prod_j data_j\\) where the product is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentProd.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_min(data, segment_ids, name=None) <div class="md-anchor" id="segment_min">{#segment_min}</div> + +Computes the minimum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \min_j(data_j)\\) where `min` is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentMin.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_max(data, segment_ids, name=None) <div class="md-anchor" id="segment_max">{#segment_max}</div> + +Computes the maximum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \max_j(data_j)\\) where `max` is over `j` such +that `segment_ids[j] == i`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentMax.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.segment_mean(data, segment_ids, name=None) <div class="md-anchor" id="segment_mean">{#segment_mean}</div> + +Computes the mean along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \frac{\sum_j data_j}{N}\\) where `mean` is +over `j` such that `segment_ids[j] == i` and `N` is the total number of +values summed. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/SegmentMean.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + + +- - - + +### tf.unsorted_segment_sum(data, segment_ids, num_segments, name=None) <div class="md-anchor" id="unsorted_segment_sum">{#unsorted_segment_sum}</div> + +Computes the sum along segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Computes a tensor such that +\\(output_i = \sum_j data_j\\) where sum is over `j` such +that `segment_ids[j] == i`. Unlike `SegmentSum`, `segment_ids` +need not be sorted and need not cover all values in the full + range of valid values. + +If the sum is empty for a given segment ID `i`, `output[i] = 0`. + +`num_segments` should equal the number of distinct segment IDs. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/UnsortedSegmentSum.png" alt> +</div> + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>segment_ids</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A 1-D tensor whose rank is equal to the rank of `data`'s + first dimension. +* <b>num_segments</b>: A `Tensor` of type `int32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `num_segments`. + + + +- - - + +### tf.sparse_segment_sum(data, indices, segment_ids, name=None) <div class="md-anchor" id="sparse_segment_sum">{#sparse_segment_sum}</div> + +Computes the sum along sparse segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Like `SegmentSum`, but `segment_ids` can have rank less than `data`'s first +dimension, selecting a subset of dimension_0, specified by `indices`. + +For example: + +```prettyprint +c = tf.constant([[1,2,3,4], [-1,-2,-3,-4], [5,6,7,8]]) + +# Select two rows, one segment. +tf.sparse_segment_sum(c, tf.constant([0, 1]), tf.constant([0, 0])) + ==> [[0 0 0 0]] + +# Select two rows, two segment. +tf.sparse_segment_sum(c, tf.constant([0, 1]), tf.constant([0, 1])) + ==> [[ 1 2 3 4] + [-1 -2 -3 -4]] + +# Select all rows, two segments. +tf.sparse_segment_sum(c, tf.constant([0, 1, 2]), tf.constant([0, 0, 1])) + ==> [[0 0 0 0] + [5 6 7 8]] + +# Which is equivalent to: +tf.segment_sum(c, tf.constant([0, 0, 1])) +``` + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>indices</b>: A `Tensor` of type `int32`. + A 1-D tensor. Has same rank as `segment_ids`. +* <b>segment_ids</b>: A `Tensor` of type `int32`. + A 1-D tensor. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + +- - - + +### tf.sparse_segment_mean(data, indices, segment_ids, name=None) <div class="md-anchor" id="sparse_segment_mean">{#sparse_segment_mean}</div> + +Computes the mean along sparse segments of a tensor. + +Read [the section on Segmentation](../python/math_ops.md#segmentation) +for an explanation of segments. + +Like `SegmentMean`, but `segment_ids` can have rank less than `data`'s first +dimension, selecting a subset of dimension_0, specified by `indices`. + +##### Args: + + +* <b>data</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>indices</b>: A `Tensor` of type `int32`. + A 1-D tensor. Has same rank as `segment_ids`. +* <b>segment_ids</b>: A `Tensor` of type `int32`. + A 1-D tensor. Values should be sorted and can be repeated. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `data`. + Has same shape as data, except for dimension_0 which + has size `k`, the number of segments. + + + + +## Sequence Comparison and Indexing <div class="md-anchor" id="AUTOGENERATED-sequence-comparison-and-indexing">{#AUTOGENERATED-sequence-comparison-and-indexing}</div> + +TensorFlow provides several operations that you can use to add sequence +comparison and index extraction to your graph. You can use these operations to +determine sequence differences and determine the indexes of specific values in +a tensor. + +- - - + +### tf.argmin(input, dimension, name=None) <div class="md-anchor" id="argmin">{#argmin}</div> + +Returns the index with the smallest value across dimensions of a tensor. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. +* <b>dimension</b>: A `Tensor` of type `int32`. + int32, 0 <= dimension < rank(input). Describes which dimension + of the input Tensor to reduce across. For vectors, use dimension = 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + +- - - + +### tf.argmax(input, dimension, name=None) <div class="md-anchor" id="argmax">{#argmax}</div> + +Returns the index with the largest value across dimensions of a tensor. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. +* <b>dimension</b>: A `Tensor` of type `int32`. + int32, 0 <= dimension < rank(input). Describes which dimension + of the input Tensor to reduce across. For vectors, use dimension = 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + + +- - - + +### tf.listdiff(x, y, name=None) <div class="md-anchor" id="listdiff">{#listdiff}</div> + +Computes the difference between two lists of numbers. + +Given a list `x` and a list `y`, this operation returns a list `out` that +represents all numbers that are in `x` but not in `y`. The returned list `out` +is sorted in the same order that the numbers appear in `x` (duplicates are +preserved). This operation also returns a list `idx` that represents the +position of each `out` element in `x`. In other words: + +`out[i] = x[idx[i]] for i in [0, 1, ..., len(out) - 1]` + +For example, given this input: + +```prettyprint +x = [1, 2, 3, 4, 5, 6] +y = [1, 3, 5] +``` + +This operation would return: + +```prettyprint +out ==> [2, 4, 6] +idx ==> [1, 3, 5] +``` + +##### Args: + + +* <b>x</b>: A `Tensor`. 1-D. Values to keep. +* <b>y</b>: A `Tensor`. Must have the same type as `x`. 1-D. Values to remove. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (out, idx). + +* <b>out</b>: A `Tensor`. Has the same type as `x`. 1-D. Values present in `x` but not in `y`. +* <b>idx</b>: A `Tensor` of type `int32`. 1-D. Positions of `x` values preserved in `out`. + + +- - - + +### tf.where(input, name=None) <div class="md-anchor" id="where">{#where}</div> + +Returns locations of true values in a boolean tensor. + +This operation returns the coordinates of true elements in `input`. The +coordinates are returned in a 2-D tensor where the first dimension (rows) +represents the number of true elements, and the second dimension (columns) +represents the coordinates of the true elements. Keep in mind, the shape of +the output tensor can vary depending on how many true values there are in +`input`. Indices are output in row-major order. + +For example: + +```prettyprint +# 'input' tensor is [[True, False] +# [True, False]] +# 'input' has two true values, so output has two coordinates. +# 'input' has rank of 2, so coordinates have two indices. +where(input) ==> [[0, 0], + [1, 0]] + +# `input` tensor is [[[True, False] +# [True, False]] +# [[False, True] +# [False, True]] +# [[False, False] +# [False, True]]] +# 'input' has 5 true values, so output has 5 coordinates. +# 'input' has rank of 3, so coordinates have three indices. +where(input) ==> [[0, 0, 0], + [0, 1, 0], + [1, 0, 1], + [1, 1, 1], + [2, 1, 1]] +``` + +##### Args: + + +* <b>input</b>: A `Tensor` of type `bool`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int64`. + + +- - - + +### tf.unique(x, name=None) <div class="md-anchor" id="unique">{#unique}</div> + +Finds unique elements in a 1-D tensor. + +This operation returns a tensor `y` containing all of the unique elements of `x` +sorted in the same order that they occur in `x`. This operation also returns a +tensor `idx` the same size as `x` that contains the index of each value of `x` +in the unique output `y`. In other words: + +`y[idx[i]] = x[i] for i in [0, 1,...,rank(x) - 1]` + +For example: + +```prettyprint +# tensor 'x' is [1, 1, 2, 4, 4, 4, 7, 8, 8] +y, idx = unique(x) +y ==> [1, 2, 4, 7, 8] +idx ==> [0, 0, 1, 2, 2, 2, 3, 4, 4] +``` + +##### Args: + + +* <b>x</b>: A `Tensor`. 1-D. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (y, idx). + +* <b>y</b>: A `Tensor`. Has the same type as `x`. 1-D. +* <b>idx</b>: A `Tensor` of type `int32`. 1-D. + + + +- - - + +### tf.edit_distance(hypothesis, truth, normalize=True, name='edit_distance') <div class="md-anchor" id="edit_distance">{#edit_distance}</div> + +Computes the Levenshtein distance between sequences. + +This operation takes variable-length sequences (`hypothesis` and `truth`), +each provided as a `SparseTensor`, and computes the Levenshtein distance. +You can normalize the edit distance by length of `truth` by setting +`normalize` to true. + +For example, given the following input: + +```python +# 'hypothesis' is a tensor of shape `[2, 1]` with variable-length values: +# (0,0) = ["a"] +# (1,0) = ["b"] +hypothesis = tf.SparseTensor( + [[0, 0, 0], + [1, 0, 0]], + ["a", "b"] + (2, 1, 1)) + +# 'truth' is a tensor of shape `[2, 2]` with variable-length values: +# (0,0) = [] +# (0,1) = ["a"] +# (1,0) = ["b", "c"] +# (1,1) = ["a"] +truth = tf.SparseTensor( + [[0, 1, 0], + [1, 0, 0], + [1, 0, 1], + [1, 1, 0]] + ["a", "b", "c", "a"], + (2, 2, 2)) + +normalize = True +``` + +This operation would return the following: + +```python +# 'output' is a tensor of shape `[2, 2]` with edit distances normalized +# by 'truth' lengths. +output ==> [[inf, 1.0], # (0,0): no truth, (0,1): no hypothesis + [0.5, 1.0]] # (1,0): addition, (1,1): no hypothesis +``` + +##### Args: + + +* <b>hypothesis</b>: A `SparseTensor` containing hypothesis sequences. +* <b>truth</b>: A `SparseTensor` containing truth sequences. +* <b>normalize</b>: A `bool`. If `True`, normalizes the Levenshtein distance by + length of `truth.` +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A dense `Tensor` with rank `R - 1`, where R is the rank of the + `SparseTensor` inputs `hypothesis` and `truth`. + +##### Raises: + + +* <b>TypeError</b>: If either `hypothesis` or `truth` are not a `SparseTensor`. + + + +- - - + +### tf.invert_permutation(x, name=None) <div class="md-anchor" id="invert_permutation">{#invert_permutation}</div> + +Computes the inverse permutation of a tensor. + +This operation computes the inverse of an index permutation. It takes a 1-D +integer tensor `x`, which represents the indices of a zero-based array, and +swaps each value with its index position. In other words, for an ouput tensor +`y` and an input tensor `x`, this operation computes the following: + +`y[x[i]] = i for i in [0, 1, ..., len(x) - 1]` + +The values must include 0. There can be no duplicate values or negative values. + +For example: + +```prettyprint +# tensor `x` is [3, 4, 0, 2, 1] +invert_permutation(x) ==> [2, 4, 3, 0, 1] +``` + +##### Args: + + +* <b>x</b>: A `Tensor` of type `int32`. 1-D. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `int32`. 1-D. + + diff --git a/tensorflow/g3doc/api_docs/python/nn.md b/tensorflow/g3doc/api_docs/python/nn.md new file mode 100644 index 0000000000..91fab34255 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/nn.md @@ -0,0 +1,1306 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Neural Network +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Activation Functions](#AUTOGENERATED-activation-functions) + * [tf.nn.relu(features, name=None)](#relu) + * [tf.nn.relu6(features, name=None)](#relu6) + * [tf.nn.softplus(features, name=None)](#softplus) + * [tf.nn.dropout(x, keep_prob, noise_shape=None, seed=None, name=None)](#dropout) + * [tf.nn.bias_add(value, bias, name=None)](#bias_add) + * [tf.sigmoid(x, name=None)](#sigmoid) + * [tf.tanh(x, name=None)](#tanh) +* [Convolution](#AUTOGENERATED-convolution) + * [tf.nn.conv2d(input, filter, strides, padding, use_cudnn_on_gpu=None, name=None)](#conv2d) + * [tf.nn.depthwise_conv2d(input, filter, strides, padding, name=None)](#depthwise_conv2d) + * [tf.nn.separable_conv2d(input, depthwise_filter, pointwise_filter, strides, padding, name=None)](#separable_conv2d) +* [Pooling](#AUTOGENERATED-pooling) + * [tf.nn.avg_pool(value, ksize, strides, padding, name=None)](#avg_pool) + * [tf.nn.max_pool(value, ksize, strides, padding, name=None)](#max_pool) + * [tf.nn.max_pool_with_argmax(input, ksize, strides, padding, Targmax=None, name=None)](#max_pool_with_argmax) +* [Normalization](#AUTOGENERATED-normalization) + * [tf.nn.l2_normalize(x, dim, epsilon=1e-12, name=None)](#l2_normalize) + * [tf.nn.local_response_normalization(input, depth_radius=None, bias=None, alpha=None, beta=None, name=None)](#local_response_normalization) + * [tf.nn.moments(x, axes, name=None)](#moments) +* [Losses](#AUTOGENERATED-losses) + * [tf.nn.l2_loss(t, name=None)](#l2_loss) +* [Classification](#AUTOGENERATED-classification) + * [tf.nn.sigmoid_cross_entropy_with_logits(logits, targets, name=None)](#sigmoid_cross_entropy_with_logits) + * [tf.nn.softmax(logits, name=None)](#softmax) + * [tf.nn.softmax_cross_entropy_with_logits(logits, labels, name=None)](#softmax_cross_entropy_with_logits) +* [Embeddings](#AUTOGENERATED-embeddings) + * [tf.nn.embedding_lookup(params, ids, name=None)](#embedding_lookup) + * [tf.nn.embedding_lookup_sparse(params, sp_ids, sp_weights, name=None, combiner='mean')](#embedding_lookup_sparse) +* [Evaluation](#AUTOGENERATED-evaluation) + * [tf.nn.top_k(input, k, name=None)](#top_k) + * [tf.nn.in_top_k(predictions, targets, k, name=None)](#in_top_k) +* [Candidate Sampling](#AUTOGENERATED-candidate-sampling) + * [Sampled Loss Functions](#AUTOGENERATED-sampled-loss-functions) + * [tf.nn.nce_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=False, name='nce_loss')](#nce_loss) + * [tf.nn.sampled_softmax_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=True, name='sampled_softmax_loss')](#sampled_softmax_loss) + * [Candidate Samplers](#AUTOGENERATED-candidate-samplers) + * [tf.nn.uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None)](#uniform_candidate_sampler) + * [tf.nn.log_uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None)](#log_uniform_candidate_sampler) + * [tf.nn.learned_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None)](#learned_unigram_candidate_sampler) + * [tf.nn.fixed_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, vocab_file='', distortion=0.0, num_reserved_ids=0, num_shards=1, shard=0, unigrams=[], seed=None, name=None)](#fixed_unigram_candidate_sampler) + * [Miscellaneous candidate sampling utilities](#AUTOGENERATED-miscellaneous-candidate-sampling-utilities) + * [tf.nn.compute_accidental_hits(true_classes, sampled_candidates, num_true, seed=None, name=None)](#compute_accidental_hits) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Activation Functions <div class="md-anchor" id="AUTOGENERATED-activation-functions">{#AUTOGENERATED-activation-functions}</div> + +The activation ops provide different types of nonlinearities for use in +neural networks. These include smooth nonlinearities (`sigmoid`, +`tanh`, and `softplus`), continuous but not everywhere differentiable +functions (`relu`, `relu6`, and `relu_x`), and random regularization +(`dropout`). + +All activation ops apply componentwise, and produce a tensor of the same +shape as the input tensor. + +- - - + +### tf.nn.relu(features, name=None) <div class="md-anchor" id="relu">{#relu}</div> + +Computes rectified linear: `max(features, 0)`. + +##### Args: + + +* <b>features</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `features`. + + +- - - + +### tf.nn.relu6(features, name=None) <div class="md-anchor" id="relu6">{#relu6}</div> + +Computes Rectified Linear 6: `min(max(features, 0), 6)`. + +##### Args: + + +* <b>features</b>: A `Tensor` with type `float`, `double`, `int32`, `int64`, `uint8`, + `int16`, or `int8`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with the same type as `features`. + + +- - - + +### tf.nn.softplus(features, name=None) <div class="md-anchor" id="softplus">{#softplus}</div> + +Computes softplus: `log(exp(features) + 1)`. + +##### Args: + + +* <b>features</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `features`. + + +- - - + +### tf.nn.dropout(x, keep_prob, noise_shape=None, seed=None, name=None) <div class="md-anchor" id="dropout">{#dropout}</div> + +Computes dropout. + +With probability `keep_prob`, outputs the input element scaled up by +`1 / keep_prob`, otherwise outputs `0`. The scaling is so that the expected +sum is unchanged. + +By default, each element is kept or dropped independently. If `noise_shape` +is specified, it must be +[broadcastable](http://docs.scipy.org/doc/numpy/user/basics.broadcasting.html) +to the shape of `x`, and only dimensions with `noise_shape[i] == x.shape[i]` +will make independent decisions. For example, if `x.shape = [b, x, y, c]` and +`noise_shape = [b, 1, 1, c]`, each batch and channel component will be +kept independently and each row and column will be kept or not kept together. + +##### Args: + + +* <b>x</b>: A tensor. +* <b>keep_prob</b>: Float probability that each element is kept. +* <b>noise_shape</b>: Shape for randomly generated keep/drop flags. +* <b>seed</b>: A Python integer. Used to create a random seed. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A Tensor of the same shape of `x`. + +##### Raises: + + +* <b>ValueError</b>: If `keep_prob` is not in `(0, 1]`. + + +- - - + +### tf.nn.bias_add(value, bias, name=None) <div class="md-anchor" id="bias_add">{#bias_add}</div> + +Adds `bias` to `value`. + +This is (mostly) a special case of `tf.add` where `bias` is restricted to 1-D. +Broadcasting is supported, so `value` may have any number of dimensions. +Unlike `tf.add`, the type of `bias` is allowed to differ from `value` in the +case where both types are quantized. + +##### Args: + + +* <b>value</b>: A `Tensor` with type `float`, `double`, `int64`, `int32`, `uint8`, + `int16`, `int8`, or `complex64`. +* <b>bias</b>: A 1-D `Tensor` with size matching the last dimension of `value`. + Must be the same type as `value` unless `value` is a quantized type, + in which case a different quantized type may be used. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` with the same type as `value`. + + +- - - + +### tf.sigmoid(x, name=None) <div class="md-anchor" id="sigmoid">{#sigmoid}</div> + +Computes sigmoid of `x` element-wise. + +Specifically, `y = 1 / (1 + exp(-x))`. + +##### Args: + + +* <b>x</b>: A Tensor with type `float`, `double`, `int32`, `complex64`, `int64`, + or `qint32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A Tensor with the same type as `x` if `x.dtype != qint32` + otherwise the return type is `quint8`. + + +- - - + +### tf.tanh(x, name=None) <div class="md-anchor" id="tanh">{#tanh}</div> + +Computes hyperbolic tangent of `x` element-wise. + +##### Args: + + +* <b>x</b>: A Tensor with type `float`, `double`, `int32`, `complex64`, `int64`, + or `qint32`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A Tensor with the same type as `x` if `x.dtype != qint32` otherwise + the return type is `quint8`. + + + +## Convolution <div class="md-anchor" id="AUTOGENERATED-convolution">{#AUTOGENERATED-convolution}</div> + +The convolution ops sweep a 2-D filter over a batch of images, applying the +filter to each window of each image of the appropriate size. The different +ops trade off between generic vs. specific filters: + +* `conv2d`: Arbitrary filters that can mix channels together. +* `depthwise_conv2d`: Filters that operate on each channel independently. +* `separable_conv2d`: A depthwise spatial filter followed by a pointwise filter. + +Note that although these ops are called "convolution", they are strictly +speaking "cross-correlation" since the filter is combined with an input window +without reversing the filter. For details, see [the properties of +cross-correlation](https://en.wikipedia.org/wiki/Cross-correlation#Properties). + +The filter is applied to image patches of the same size as the filter and +strided according to the `strides` argument. `strides = [1, 1, 1, 1]` applies +the filter to a patch at every offset, `strides = [1, 2, 2, 1]` applies the +filter to every other image patch in each dimension, etc. + +Ignoring channels for the moment, the spatial semantics of the convolution ops +are as follows. If the 4-D `input` has shape +`[batch, in_height, in_width, ...]` and the 4-D `filter` has shape +`[filter_height, filter_width, ...]`, then + + output.shape = [batch, + (in_height - filter_height + 1) / strides[1], + (in_width - filter_width + 1) / strides[2], + ...] + + output[b, i, j, :] = + sum_{di, dj} input[b, strides[1] * i + di, strides[2] * j + dj, ...] * + filter[di, dj, ...] + +Since `input` is 4-D, each `input[b, i, j, :]` is a vector. For `conv2d`, these +vectors are multiplied by the `filter[di, dj, :, :]` matrices to produce new +vectors. For `depthwise_conv_2d`, each scalar component `input[b, i, j, k]` +is multiplied by a vector `filter[di, dj, k]`, and all the vectors are +concatenated. + +In the formula for `output.shape`, the rounding direction depends on padding: + +* `padding = 'SAME'`: Round down (only full size windows are considered). +* `padding = 'VALID'`: Round up (partial windows are included). + +- - - + +### tf.nn.conv2d(input, filter, strides, padding, use_cudnn_on_gpu=None, name=None) <div class="md-anchor" id="conv2d">{#conv2d}</div> + +Computes a 2-D convolution given 4-D `input` and `filter` tensors. + +Given an input tensor of shape `[batch, in_height, in_width, in_channels]` +and a filter / kernel tensor of shape +`[filter_height, filter_width, in_channels, out_channels]`, this op +performs the following: + +1. Flattens the filter to a 2-D matrix with shape + `[filter_height * filter_width * in_channels, output_channels]`. +2. Extracts image patches from the the input tensor to form a *virtual* + tensor of shape `[batch, out_height, out_width, + filter_height * filter_width * in_channels]`. +3. For each patch, right-multiplies the filter matrix and the image patch + vector. + +In detail, + + output[b, i, j, k] = + sum_{di, dj, q} input[b, strides[1] * i + di, strides[2] * j + dj, q] * + filter[di, dj, q, k] + +Must have `strides[0] = strides[3] = 1`. For the most common case of the same +horizontal and vertices strides, `strides = [1, stride, stride, 1]`. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. +* <b>filter</b>: A `Tensor`. Must have the same type as `input`. +* <b>strides</b>: A list of `ints`. + 1-D of length 4. The stride of the sliding window for each dimension + of `input`. +* <b>padding</b>: A `string` from: `"SAME", "VALID"`. + The type of padding algorithm to use. +* <b>use_cudnn_on_gpu</b>: An optional `bool`. Defaults to `True`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + +- - - + +### tf.nn.depthwise_conv2d(input, filter, strides, padding, name=None) <div class="md-anchor" id="depthwise_conv2d">{#depthwise_conv2d}</div> + +Depthwise 2-D convolution. + +Given an input tensor of shape `[batch, in_height, in_width, in_channels]` +and a filter tensor of shape +`[filter_height, filter_width, in_channels, channel_multiplier]` +containing `in_channels` convolutional filters of depth 1, `depthwise_conv2d` +applies a different filter to each input channel (expanding from 1 channel +to `channel_multiplier` channels for each), then concatenates the results +together. The output has `in_channels * channel_multiplier` channels. + +In detail, + + output[b, i, j, k * channel_multiplier + q] = + sum_{di, dj} input[b, strides[1] * i + di, strides[2] * j + dj, k] * + filter[di, dj, k, q] + +Must have `strides[0] = strides[3] = 1`. For the most common case of the +same horizontal and vertical strides, `strides = [1, stride, stride, 1]`. + +##### Args: + + +* <b>input</b>: 4-D with shape `[batch, in_height, in_width, in_channels]`. +* <b>filter</b>: 4-D with shape + `[filter_height, filter_width, in_channels, channel_multiplier]`. +* <b>strides</b>: 1-D of size 4. The stride of the sliding window for each + dimension of `input`. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A 4-D `Tensor` of shape + `[batch, out_height, out_width, in_channels * channel_multiplier].` + + +- - - + +### tf.nn.separable_conv2d(input, depthwise_filter, pointwise_filter, strides, padding, name=None) <div class="md-anchor" id="separable_conv2d">{#separable_conv2d}</div> + +2-D convolution with separable filters. + +Performs a depthwise convolution that acts separately on channels followed by +a pointwise convolution that mixes channels. Note that this is separability +between dimensions `[1, 2]` and `3`, not spatial separability between +dimensions `1` and `2`. + +In detail, + + output[b, i, j, k] = sum_{di, dj, q, r] + input[b, strides[1] * i + di, strides[2] * j + dj, q] * + depthwise_filter[di, dj, q, r] * + pointwise_filter[0, 0, q * channel_multiplier + r, k] + +`strides` controls the strides for the depthwise convolution only, since +the pointwise convolution has implicit strides of `[1, 1, 1, 1]`. Must have +`strides[0] = strides[3] = 1`. For the most common case of the same +horizontal and vertical strides, `strides = [1, stride, stride, 1]`. + +##### Args: + + +* <b>input</b>: 4-D `Tensor` with shape `[batch, in_height, in_width, in_channels]`. +* <b>depthwise_filter</b>: 4-D `Tensor` with shape + `[filter_height, filter_width, in_channels, channel_multiplier]`. + Contains `in_channels` convolutional filters of depth 1. +* <b>pointwise_filter</b>: 4-D `Tensor` with shape + `[1, 1, channel_multiplier * in_channels, out_channels]`. Pointwise + filter to mix channels after `depthwise_filter` has convolved spatially. +* <b>strides</b>: 1-D of size 4. The strides for the depthwise convolution for + each dimension of `input`. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A 4-D `Tensor` of shape `[batch, out_height, out_width, out_channels]`. + + + +## Pooling <div class="md-anchor" id="AUTOGENERATED-pooling">{#AUTOGENERATED-pooling}</div> + +The pooling ops sweep a rectangular window over the input tensor, computing a +reduction operation for each window (average, max, or max with argmax). Each +pooling op uses rectangular windows of size `ksize` separated by offset +`strides`. For example, if `strides` is all ones every window is used, if +`strides` is all twos every other window is used in each dimension, etc. + +In detail, the output is + + output[i] = reduce(value[strides * i:strides * i + ksize]) + +for each tuple of indices `i`. The output shape is + + output.shape = (value.shape - ksize + 1) / strides + +where the rounding direction depends on padding: + +* `padding = 'SAME'`: Round down (only full size windows are considered). +* `padding = 'VALID'`: Round up (partial windows are included). + +- - - + +### tf.nn.avg_pool(value, ksize, strides, padding, name=None) <div class="md-anchor" id="avg_pool">{#avg_pool}</div> + +Performs the average pooling on the input. + +Each entry in `output` is the mean of the corresponding size `ksize` +window in `value`. + +##### Args: + + +* <b>value</b>: A 4-D `Tensor` of shape `[batch, height, width, channels]` and type + `float32`, `float64`, `qint8`, `quint8`, or `qint32`. +* <b>ksize</b>: A list of ints that has length >= 4. + The size of the window for each dimension of the input tensor. +* <b>strides</b>: A list of ints that has length >= 4. + The stride of the sliding window for each dimension of the + input tensor. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: Optional name for the operation. + +##### Returns: + + A `Tensor` with the same type as `value`. The average pooled output tensor. + + +- - - + +### tf.nn.max_pool(value, ksize, strides, padding, name=None) <div class="md-anchor" id="max_pool">{#max_pool}</div> + +Performs the max pooling on the input. + +##### Args: + + +* <b>value</b>: A 4-D `Tensor` with shape `[batch, height, width, channels]` and + type `float32`, `float64`, `qint8`, `quint8`, `qint32`. +* <b>ksize</b>: A list of ints that has length >= 4. The size of the window for + each dimension of the input tensor. +* <b>strides</b>: A list of ints that has length >= 4. The stride of the sliding + window for each dimension of the input tensor. +* <b>padding</b>: A string, either `'VALID'` or `'SAME'`. The padding algorithm. +* <b>name</b>: Optional name for the operation. + +##### Returns: + + A `Tensor` with the same type as `value`. The max pooled output tensor. + + +- - - + +### tf.nn.max_pool_with_argmax(input, ksize, strides, padding, Targmax=None, name=None) <div class="md-anchor" id="max_pool_with_argmax">{#max_pool_with_argmax}</div> + +Performs max pooling on the input and outputs both max values and indices. + +The indices in `argmax` are flattened, so that a maximum value at position +`[b, y, x, c]` becomes flattened index +`((b * height + y) * width + x) * channels + c`. + +##### Args: + + +* <b>input</b>: A `Tensor` of type `float32`. + 4-D with shape `[batch, height, width, channels]`. Input to pool over. +* <b>ksize</b>: A list of `ints` that has length `>= 4`. + The size of the window for each dimension of the input tensor. +* <b>strides</b>: A list of `ints` that has length `>= 4`. + The stride of the sliding window for each dimension of the + input tensor. +* <b>padding</b>: A `string` from: `"SAME", "VALID"`. + The type of padding algorithm to use. +* <b>Targmax</b>: An optional `tf.DType` from: `tf.int32, tf.int64`. Defaults to `tf.int64`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (output, argmax). + +* <b>output</b>: A `Tensor` of type `float32`. The max pooled output tensor. +* <b>argmax</b>: A `Tensor` of type `Targmax`. 4-D. The flattened indices of the max values chosen for each output. + + + +## Normalization <div class="md-anchor" id="AUTOGENERATED-normalization">{#AUTOGENERATED-normalization}</div> + +Normalization is useful to prevent neurons from saturating when inputs may +have varying scale, and to aid generalization. + +- - - + +### tf.nn.l2_normalize(x, dim, epsilon=1e-12, name=None) <div class="md-anchor" id="l2_normalize">{#l2_normalize}</div> + +Normalizes along dimension `dim` using an L2 norm. + +For a 1-D tensor with `dim = 0`, computes + + output = x / sqrt(max(sum(x**2), epsilon)) + +For `x` with more dimensions, independently normalizes each 1-D slice along +dimension `dim`. + +##### Args: + + +* <b>x</b>: A `Tensor`. +* <b>dim</b>: Dimension along which to normalize. +* <b>epsilon</b>: A lower bound value for the norm. Will use `sqrt(epsilon)` as the + divisor if `norm < sqrt(epsilon)`. +* <b>name</b>: A name for this operation (optional). + +##### Returns: + + A `Tensor` with the same shape as `x`. + + +- - - + +### tf.nn.local_response_normalization(input, depth_radius=None, bias=None, alpha=None, beta=None, name=None) <div class="md-anchor" id="local_response_normalization">{#local_response_normalization}</div> + +Local Response Normalization. + +The 4-D `input` tensor is treated as a 3-D array of 1-D vectors (along the last +dimension), and each vector is normalized independently. Within a given vector, +each component is divided by the weighted, squared sum of inputs within +`depth_radius`. In detail, + + sqr_sum[a, b, c, d] = + sum(input[a, b, c, d - depth_radius : d + depth_radius + 1] ** 2) + output = input / (bias + alpha * sqr_sum ** beta) + +For details, see [Krizhevsky et al., ImageNet classification with deep +convolutional neural networks (NIPS 2012)] +(http://papers.nips.cc/paper/4824-imagenet-classification-with-deep-convolutional-neural-networks). + +##### Args: + + +* <b>input</b>: A `Tensor` of type `float32`. 4-D. +* <b>depth_radius</b>: An optional `int`. Defaults to `5`. + 0-D. Half-width of the 1-D normalization window. +* <b>bias</b>: An optional `float`. Defaults to `1`. + An offset (usually positive to avoid dividing by 0). +* <b>alpha</b>: An optional `float`. Defaults to `1`. + A scale factor, usually positive. +* <b>beta</b>: An optional `float`. Defaults to `0.5`. An exponent. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `float32`. + + +- - - + +### tf.nn.moments(x, axes, name=None) <div class="md-anchor" id="moments">{#moments}</div> + +Calculate the mean and variance of `x`. + +The mean and variance are calculated by aggregating the contents of `x` +across `axes`. If `x` is 1-D and `axes = [0]` this is just the mean +and variance of a vector. + +For so-called "global normalization" needed for convolutional filters pass +`axes=[0, 1, 2]` (batch, height, width). For batch normalization pass +`axes=[0]` (batch). + +##### Args: + + +* <b>x</b>: A `Tensor`. +* <b>axes</b>: array of ints. Axes along which to compute mean and + variance. +* <b>name</b>: Name used to scope the operations that compute the moments. + +##### Returns: + + Two `Tensors`: `mean` and `variance`. + + + +## Losses <div class="md-anchor" id="AUTOGENERATED-losses">{#AUTOGENERATED-losses}</div> + +The loss ops measure error between two tensors, or between a tensor and zero. +These can be used for measuring accuracy of a network in a regression task +or for regularization purposes (weight decay). + +- - - + +### tf.nn.l2_loss(t, name=None) <div class="md-anchor" id="l2_loss">{#l2_loss}</div> + +L2 Loss. + +Computes half the L2 norm of a tensor without the `sqrt`: + + output = sum(t ** 2) / 2 + +##### Args: + + +* <b>t</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Typically 2-D, but may have any dimensions. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `t`. 0-D. + + + +## Classification <div class="md-anchor" id="AUTOGENERATED-classification">{#AUTOGENERATED-classification}</div> + +TensorFlow provides several operations that help you perform classification. + +- - - + +### tf.nn.sigmoid_cross_entropy_with_logits(logits, targets, name=None) <div class="md-anchor" id="sigmoid_cross_entropy_with_logits">{#sigmoid_cross_entropy_with_logits}</div> + +Computes sigmoid cross entropy given `logits`. + +Measures the probability error in discrete classification tasks in which each +class is independent and not mutually exclusive. For instance, one could +perform multilabel classification where a picture can contain both an elephant +and a dog at the same time. + +For brevity, let `x = logits`, `z = targets`. The logistic loss is + + x - x * z + log(1 + exp(-x)) + +To ensure stability and avoid overflow, the implementation uses + + max(x, 0) - x * z + log(1 + exp(-abs(x))) + +`logits` and `targets` must have the same type and shape. + +##### Args: + + +* <b>logits</b>: A `Tensor` of type `float32` or `float64`. +* <b>targets</b>: A `Tensor` of the same type and shape as `logits`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of the same shape as `logits` with the componentwise + logistic losses. + + +- - - + +### tf.nn.softmax(logits, name=None) <div class="md-anchor" id="softmax">{#softmax}</div> + +Computes softmax activations. + +For each batch `i` and class `j` we have + + softmax[i, j] = exp(logits[i, j]) / sum(exp(logits[i])) + +##### Args: + + +* <b>logits</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`. + 2-D with shape `[batch_size, num_classes]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `logits`. Same shape as `logits`. + + +- - - + +### tf.nn.softmax_cross_entropy_with_logits(logits, labels, name=None) <div class="md-anchor" id="softmax_cross_entropy_with_logits">{#softmax_cross_entropy_with_logits}</div> + +Computes softmax cross entropy between `logits` and `labels`. + +Measures the probability error in discrete classification tasks in which the +classes are mutually exclusive (each entry is in exactly one class). For +example, each CIFAR-10 image is labeled with one and only one label: an image +can be a dog or a truck, but not both. + +**WARNING:** This op expects unscaled logits, since it performs a `softmax` +on `logits` internally for efficiency. Do not call this op with the +output of `softmax`, as it will produce incorrect results. + +`logits` and `labels` must have the same shape `[batch_size, num_classes]` +and the same dtype (either `float32` or `float64`). + +##### Args: + + +* <b>logits</b>: Unscaled log probabilities. +* <b>labels</b>: Each row `labels[i]` must be a valid probability distribution. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A 1-D `Tensor` of length `batch_size` of the same type as `logits` with the + softmax cross entropy loss. + + + +## Embeddings <div class="md-anchor" id="AUTOGENERATED-embeddings">{#AUTOGENERATED-embeddings}</div> + +TensorFlow provides several operations that help you compute embeddings. + +- - - + +### tf.nn.embedding_lookup(params, ids, name=None) <div class="md-anchor" id="embedding_lookup">{#embedding_lookup}</div> + +Return a tensor of embedding values by looking up "ids" in "params". + +##### Args: + + +* <b>params</b>: List of tensors of the same shape. A single tensor is + treated as a singleton list. +* <b>ids</b>: Tensor of integers containing the ids to be looked up in + 'params'. Let P be len(params). If P > 1, then the ids are + partitioned by id % P, and we do separate lookups in params[p] + for 0 <= p < P, and then stitch the results back together into + a single result tensor. +* <b>name</b>: Optional name for the op. + +##### Returns: + + A tensor of shape ids.shape + params[0].shape[1:] containing the + values params[i % P][i] for each i in ids. + +##### Raises: + + +* <b>ValueError</b>: if some parameters are invalid. + + +- - - + +### tf.nn.embedding_lookup_sparse(params, sp_ids, sp_weights, name=None, combiner='mean') <div class="md-anchor" id="embedding_lookup_sparse">{#embedding_lookup_sparse}</div> + +Computes embeddings for the given ids and weights. + +This op assumes that there is at least one id for each row in the dense tensor +represented by sp_ids (i.e. there are no rows with empty features), and that +all the indices of sp_ids are in canonical row-major order. + +It also assumes that all id values lie in the range [0, p0), where p0 +is the sum of the size of params along dimension 0. + +##### Args: + + +* <b>params</b>: A single tensor representing the complete embedding tensor, + or a list of P tensors all of same shape except for the first dimension, + representing sharded embedding tensors. In the latter case, the ids are + partitioned by id % P, and we do separate lookups in params[p] for + 0 <= p < P, and then stitch the results back together into a single + result tensor. The first dimension is allowed to vary as the vocab + size is not necessarily a multiple of P. +* <b>sp_ids</b>: N x M SparseTensor of int64 ids (typically from FeatureValueToId), + where N is typically batch size and M is arbitrary. +* <b>sp_weights</b>: either a SparseTensor of float / double weights, or None to + indicate all weights should be taken to be 1. If specified, sp_weights + must have exactly the same shape and indices as sp_ids. +* <b>name</b>: Optional name for the op. +* <b>combiner</b>: A string specifying the reduction op. Currently "mean" and "sum" + are supported. + "sum" computes the weighted sum of the embedding results for each row. + "mean" is the weighted sum divided by the total weight. + +##### Returns: + + A dense tensor representing the combined embeddings for the + sparse ids. For each row in the dense tensor represented by sp_ids, the op + looks up the embeddings for all ids in that row, multiplies them by the + corresponding weight, and combines these embeddings as specified. + + In other words, if + shape(combined params) = [p0, p1, ..., pm] + and + shape(sp_ids) = shape(sp_weights) = [d0, d1, ..., dn] + then + shape(output) = [d0, d1, ..., dn-1, p1, ..., pm]. + + For instance, if params is a 10x20 matrix, and sp_ids / sp_weights are + + [0, 0]: id 1, weight 2.0 + [0, 1]: id 3, weight 0.5 + [1, 0]: id 0, weight 1.0 + [2, 3]: id 1, weight 3.0 + + with combiner="mean", then the output will be a 3x20 matrix where + output[0, :] = (params[1, :] * 2.0 + params[3, :] * 0.5) / (2.0 + 0.5) + output[1, :] = params[0, :] * 1.0 + output[2, :] = params[1, :] * 3.0 + +##### Raises: + + +* <b>TypeError</b>: If sp_ids is not a SparseTensor, or if sp_weights is neither + None nor SparseTensor. +* <b>ValueError</b>: If combiner is not one of {"mean", "sum"}. + + + +## Evaluation <div class="md-anchor" id="AUTOGENERATED-evaluation">{#AUTOGENERATED-evaluation}</div> + +The evaluation ops are useful for measuring the performance of a network. +Since they are nondifferentiable, they are typically used at evaluation time. + +- - - + +### tf.nn.top_k(input, k, name=None) <div class="md-anchor" id="top_k">{#top_k}</div> + +Returns the values and indices of the k largest elements for each row. + +\\(values_{i, j}\\) represents the j-th largest element in \\(input_i\\). + +\\(indices_{i, j}\\) gives the column index of the corresponding element, +such that \\(input_{i, indices_{i, j}} = values_{i, j}\\). If two +elements are equal, the lower-index element appears first. + +##### Args: + + +* <b>input</b>: A `Tensor`. Must be one of the following types: `float32`, `float64`, `int32`, `int64`, `uint8`, `int16`, `int8`. + A batch_size x classes tensor +* <b>k</b>: An `int` that is `>= 1`. + Number of top elements to look for within each row +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A tuple of `Tensor` objects (values, indices). + +* <b>values</b>: A `Tensor`. Has the same type as `input`. A batch_size x k tensor with the k largest elements for each row, + sorted in descending order +* <b>indices</b>: A `Tensor` of type `int32`. A batch_size x k tensor with the index of each value within each row + + +- - - + +### tf.nn.in_top_k(predictions, targets, k, name=None) <div class="md-anchor" id="in_top_k">{#in_top_k}</div> + +Says whether the targets are in the top K predictions. + +This outputs a batch_size bool array, an entry out[i] is true if the +prediction for the target class is among the top k predictions among +all predictions for example i. Note that the behavior of InTopK differs +from the TopK op in its handling of ties; if multiple classes have the +same prediction value and straddle the top-k boundary, all of those +classes are considered to be in the top k. + +More formally, let + + \\(predictions_i\\) be the predictions for all classes for example i, + \\(targets_i\\) be the target class for example i, + \\(out_i\\) be the output for example i, + +$$out_i = predictions_{i, targets_i} \in TopKIncludingTies(predictions_i)$$ + +##### Args: + + +* <b>predictions</b>: A `Tensor` of type `float32`. A batch_size x classes tensor +* <b>targets</b>: A `Tensor` of type `int32`. A batch_size vector of class ids +* <b>k</b>: An `int`. Number of top elements to look at for computing precision +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor` of type `bool`. Computed Precision at k as a bool Tensor + + + +## Candidate Sampling <div class="md-anchor" id="AUTOGENERATED-candidate-sampling">{#AUTOGENERATED-candidate-sampling}</div> + +Do you want to train a multiclass or multilabel model with thousands +or millions of output classes (for example, a language model with a +large vocabulary)? Training with a full Softmax is slow in this case, +since all of the classes are evaluated for every training example. +Candidate Sampling training algorithms can speed up your step times by +only considering a small randomly-chosen subset of contrastive classes +(called candidates) for each batch of training examples. + +See our [Candidate Sampling Algorithms Reference] +(http://www.tensorflow.org/extras/candidate_sampling.pdf) + +### Sampled Loss Functions <div class="md-anchor" id="AUTOGENERATED-sampled-loss-functions">{#AUTOGENERATED-sampled-loss-functions}</div> + +TensorFlow provides the following sampled loss functions for faster training. + +- - - + +### tf.nn.nce_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=False, name='nce_loss') <div class="md-anchor" id="nce_loss">{#nce_loss}</div> + +Computes and returns the noise-contrastive estimation training loss. + +See [Noise-contrastive estimation: A new estimation principle for +unnormalized statistical models] +(http://www.jmlr.org/proceedings/papers/v9/gutmann10a/gutmann10a.pdf). +Also see our [Candidate Sampling Algorithms Reference] +(http://www.tensorflow.org/extras/candidate_sampling.pdf) + +Note: In the case where num_true > 1, we assign to each target class +the target probability 1 / num_true so that the target probabilities +sum to 1 per-example. + +Note: It would be useful to allow a variable number of target classes per +example. We hope to provide this functionality in a future release. +For now, if you have a variable number of target classes, you can pad them +out to a constant number by either repeating them or by padding +with an otherwise unused class. + +##### Args: + + +* <b>weights</b>: A `Tensor` of shape [num_classes, dim]. The class embeddings. +* <b>biases</b>: A `Tensor` of shape [num_classes]. The class biases. +* <b>inputs</b>: A `Tensor` of shape [batch_size, dim]. The forward + activations of the input network. +* <b>labels</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>num_classes</b>: An `int`. The number of possible classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>sampled_values</b>: a tuple of `(sampled_candidates, true_expected_count, + sampled_expected_count)` returned by a *_candidate_sampler function. + (if None, we default to LogUniformCandidateSampler) +* <b>remove_accidental_hits</b>: A `bool`. Whether to remove "accidental hits" + where a sampled class equals one of the target classes. If set to + `True`, this is a "Sampled Logistic" loss instead of NCE, and we are + learning to generate log-odds instead of log probabilities. See + our [Candidate Sampling Algorithms Reference] + (http://www.tensorflow.org/extras/candidate_sampling.pdf). + Default is False. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A batch_size 1-D tensor of per-example NCE losses. + + +- - - + +### tf.nn.sampled_softmax_loss(weights, biases, inputs, labels, num_sampled, num_classes, num_true=1, sampled_values=None, remove_accidental_hits=True, name='sampled_softmax_loss') <div class="md-anchor" id="sampled_softmax_loss">{#sampled_softmax_loss}</div> + +Computes and returns the sampled softmax training loss. + +This is a faster way to train a softmax classifier over a huge number of +classes. + +This operation is for training only. It is generally an underestimate of +the full softmax loss. + +At inference time, you can compute full softmax probabilities with the +expression `tf.nn.softmax(tf.matmul(inputs, weights) + biases)`. + +See our [Candidate Sampling Algorithms Reference] +(http://www.tensorflow.org/extras/candidate_sampling.pdf) + +Also see Section 3 of http://arxiv.org/abs/1412.2007 for the math. + +##### Args: + + +* <b>weights</b>: A `Tensor` of shape [num_classes, dim]. The class embeddings. +* <b>biases</b>: A `Tensor` of shape [num_classes]. The class biases. +* <b>inputs</b>: A `Tensor` of shape [batch_size, dim]. The forward + activations of the input network. +* <b>labels</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. Note that this format differs from + the `labels` argument of `nn.softmax_cross_entropy_with_logits`. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>num_classes</b>: An `int`. The number of possible classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>sampled_values</b>: a tuple of `(sampled_candidates, true_expected_count, + sampled_expected_count)` returned by a *_candidate_sampler function. + (if None, we default to LogUniformCandidateSampler) +* <b>remove_accidental_hits</b>: A `bool`. whether to remove "accidental hits" + where a sampled class equals one of the target classes. Default is + True. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A batch_size 1-D tensor of per-example sampled softmax losses. + + + +### Candidate Samplers <div class="md-anchor" id="AUTOGENERATED-candidate-samplers">{#AUTOGENERATED-candidate-samplers}</div> + +TensorFlow provides the following samplers for randomly sampling candidate +classes when using one of the sampled loss functions above. + +- - - + +### tf.nn.uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None) <div class="md-anchor" id="uniform_candidate_sampler">{#uniform_candidate_sampler}</div> + +Samples a set of classes using a uniform base distribution. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution for this operation is the uniform distribution +over the range of integers `[0, range_max]`. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + +- - - + +### tf.nn.log_uniform_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None) <div class="md-anchor" id="log_uniform_candidate_sampler">{#log_uniform_candidate_sampler}</div> + +Samples a set of classes using a log-uniform (Zipfian) base distribution. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution for this operation is an approximately log-uniform +or Zipfian distribution: + +`P(class) = (log(class + 2) - log(class + 1)) / log(range_max + 1)` + +This sampler is useful when the target classes approximately follow such +a distribution - for example, if the classes represent words in a lexicon +sorted in decreasing order of frequency. If your classes are not ordered by +decreasing frequency, do not use this op. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + +- - - + +### tf.nn.learned_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None) <div class="md-anchor" id="learned_unigram_candidate_sampler">{#learned_unigram_candidate_sampler}</div> + +Samples a set of classes from a distribution learned during training. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution for this operation is constructed on the fly +during training. It is a unigram distribution over the target +classes seen so far during training. Every integer in `[0, range_max]` +begins with a weight of 1, and is incremented by 1 each time it is +seen as a target class. The base distribution is not saved to checkpoints, +so it is reset when the model is reloaded. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + +- - - + +### tf.nn.fixed_unigram_candidate_sampler(true_classes, num_true, num_sampled, unique, range_max, vocab_file='', distortion=0.0, num_reserved_ids=0, num_shards=1, shard=0, unigrams=[], seed=None, name=None) <div class="md-anchor" id="fixed_unigram_candidate_sampler">{#fixed_unigram_candidate_sampler}</div> + +Samples a set of classes using the provided (fixed) base distribution. + +This operation randomly samples a tensor of sampled classes +(`sampled_candidates`) from the range of integers `[0, range_max]`. + +The elements of `sampled_candidates` are drawn without replacement +(if `unique=True`) or with replacement (if `unique=False`) from +the base distribution. + +The base distribution is read from a file or passed in as an +in-memory array. There is also an option to skew the distribution by +applying a distortion power to the weights. + +In addition, this operation returns tensors `true_expected_count` +and `sampled_expected_count` representing the number of times each +of the target classes (`true_classes`) and the sampled +classes (`sampled_candidates`) is expected to occur in an average +tensor of sampled classes. These values correspond to `Q(y|x)` +defined in [this +document](http://www.tensorflow.org/extras/candidate_sampling.pdf). +If `unique=True`, then these are post-rejection probabilities and we +compute them approximately. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>num_sampled</b>: An `int`. The number of classes to randomly sample per batch. +* <b>unique</b>: A `bool`. Determines whether all sampled classes in a batch are + unique. +* <b>range_max</b>: An `int`. The number of possible classes. +* <b>vocab_file</b>: Each valid line in this file (which should have a CSV-like + format) corresponds to a valid word ID. IDs are in sequential order, + starting from num_reserved_ids. The last entry in each line is expected + to be a value corresponding to the count or relative probability. Exactly + one of `vocab_file` and `unigrams` needs to be passed to this operation. +* <b>distortion</b>: The distortion is used to skew the unigram probability + distribution. Each weight is first raised to the distortion's power + before adding to the internal unigram distribution. As a result, + `distortion = 1.0` gives regular unigram sampling (as defined by the vocab + file), and `distortion = 0.0` gives a uniform distribution. +* <b>num_reserved_ids</b>: Optionally some reserved IDs can be added in the range + `[0, num_reserved_ids]` by the users. One use case is that a special + unknown word token is used as ID 0. These IDs will have a sampling + probability of 0. +* <b>num_shards</b>: A sampler can be used to sample from a subset of the original + range in order to speed up the whole computation through parallelism. This + parameter (together with `shard`) indicates the number of partitions that + are being used in the overall computation. +* <b>shard</b>: A sampler can be used to sample from a subset of the original range + in order to speed up the whole computation through parallelism. This + parameter (together with `num_shards`) indicates the particular partition + number of the operation, when partitioning is being used. +* <b>unigrams</b>: A list of unigram counts or probabilities, one per ID in + sequential order. Exactly one of `vocab_file` and `unigrams` should be + passed to this operation. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled classes. +* <b>true_expected_count</b>: A tensor of type `float`. Same shape as + `true_classes`. The expected counts under the sampling distribution + of each of `true_classes`. +* <b>sampled_expected_count</b>: A tensor of type `float`. Same shape as + `sampled_candidates`. The expected counts under the sampling distribution + of each of `sampled_candidates`. + + + +### Miscellaneous candidate sampling utilities <div class="md-anchor" id="AUTOGENERATED-miscellaneous-candidate-sampling-utilities">{#AUTOGENERATED-miscellaneous-candidate-sampling-utilities}</div> + +- - - + +### tf.nn.compute_accidental_hits(true_classes, sampled_candidates, num_true, seed=None, name=None) <div class="md-anchor" id="compute_accidental_hits">{#compute_accidental_hits}</div> + +Compute the ids of positions in sampled_candidates matching true_classes. + +In Candidate Sampling, this operation facilitates virtually removing +sampled classes which happen to match target classes. This is done +in Sampled Softmax and Sampled Logistic. + +See our [Candidate Sampling Algorithms +Reference](http://www.tensorflow.org/extras/candidate_sampling.pdf). + +We presuppose that the `sampled_candidates` are unique. + +We call it an 'accidental hit' when one of the target classes +matches one of the sampled classes. This operation reports +accidental hits as triples `(index, id, weight)`, where `index` +represents the row number in `true_classes`, `id` represents the +position in `sampled_candidates`, and weight is `-FLOAT_MAX`. + +The result of this op should be passed through a `sparse_to_dense` +operation, then added to the logits of the sampled classes. This +removes the contradictory effect of accidentally sampling the true +target classes as noise classes for the same example. + +##### Args: + + +* <b>true_classes</b>: A `Tensor` of type `int64` and shape `[batch_size, + num_true]`. The target classes. +* <b>sampled_candidates</b>: A tensor of type `int64` and shape `[num_sampled]`. + The sampled_candidates output of CandidateSampler. +* <b>num_true</b>: An `int`. The number of target classes per training example. +* <b>seed</b>: An `int`. An operation-specific seed. Default is 0. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>indices</b>: A `Tensor` of type `int32` and shape `[num_accidental_hits]`. + Values indicate rows in `true_classes`. +* <b>ids</b>: A `Tensor` of type `int64` and shape `[num_accidental_hits]`. + Values indicate positions in `sampled_candidates`. +* <b>weights</b>: A `Tensor` of type `float` and shape `[num_accidental_hits]`. + Each value is `-FLOAT_MAX`. + + diff --git a/tensorflow/g3doc/api_docs/python/ops.md b/tensorflow/g3doc/api_docs/python/ops.md new file mode 100644 index 0000000000..bb7d6e70e2 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/ops.md @@ -0,0 +1,10 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Leftovers, should be empty and removed +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + + diff --git a/tensorflow/g3doc/api_docs/python/python_io.md b/tensorflow/g3doc/api_docs/python/python_io.md new file mode 100644 index 0000000000..7ad4b65bd0 --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/python_io.md @@ -0,0 +1,104 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Data IO (Python functions) +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Data IO (Python Functions)](#AUTOGENERATED-data-io--python-functions-) + * [class tf.python_io.TFRecordWriter](#TFRecordWriter) + * [tf.python_io.tf_record_iterator(path)](#tf_record_iterator) + * [TFRecords Format Details](#AUTOGENERATED-tfrecords-format-details) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Data IO (Python Functions) <div class="md-anchor" id="AUTOGENERATED-data-io--python-functions-">{#AUTOGENERATED-data-io--python-functions-}</div> + +A TFRecords file represents a sequence of (binary) strings. The format is not +random access, so it is suitable for streaming large amounts of data but not +suitable if fast sharding or other non-sequential access is desired. + +- - - + +### class tf.python_io.TFRecordWriter <div class="md-anchor" id="TFRecordWriter">{#TFRecordWriter}</div> + +A class to write records to a TFRecords file. + +This class implements `__enter__` and `__exit__`, and can be used +in `with` blocks like a normal file. + +- - - + +#### tf.python_io.TFRecordWriter.__init__(path) {#TFRecordWriter.__init__} + +Opens file `path` and creates a `TFRecordWriter` writing to it. + +##### Args: + + +* <b>path</b>: The path to the TFRecords file. + +##### Raises: + + +* <b>IOError</b>: If `path` cannot be opened for writing. + + +- - - + +#### tf.python_io.TFRecordWriter.write(record) {#TFRecordWriter.write} + +Write a string record to the file. + +##### Args: + + +* <b>record</b>: str + + +- - - + +#### tf.python_io.TFRecordWriter.close() {#TFRecordWriter.close} + +Close the file. + + + +- - - + +### tf.python_io.tf_record_iterator(path) <div class="md-anchor" id="tf_record_iterator">{#tf_record_iterator}</div> + +An iterator that read the records from a TFRecords file. + +##### Args: + + +* <b>path</b>: The path to the TFRecords file. + +##### Yields: + + Strings. + +##### Raises: + + +* <b>IOError</b>: If `path` cannot be opened for reading. + + + +- - - + +### TFRecords Format Details <div class="md-anchor" id="AUTOGENERATED-tfrecords-format-details">{#AUTOGENERATED-tfrecords-format-details}</div> + +A TFRecords file contains a sequence of strings with CRC hashes. Each record +has the format + + uint64 length + uint32 masked_crc32_of_length + byte data[length] + uint32 masked_crc32_of_data + +and the records are concatenated together to produce the file. The CRC32s +are [described here](https://en.wikipedia.org/wiki/Cyclic_redundancy_check), +and the mask of a CRC is + + masked_crc = ((crc >> 15) | (crc << 17)) + 0xa282ead8ul diff --git a/tensorflow/g3doc/api_docs/python/sparse_ops.md b/tensorflow/g3doc/api_docs/python/sparse_ops.md new file mode 100644 index 0000000000..7e9ab0775f --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/sparse_ops.md @@ -0,0 +1,502 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Sparse Tensors +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Sparse Tensor Representation.](#AUTOGENERATED-sparse-tensor-representation.) + * [class tf.SparseTensor](#SparseTensor) + * [class tf.SparseTensorValue](#SparseTensorValue) +* [Sparse to Dense Conversion.](#AUTOGENERATED-sparse-to-dense-conversion.) + * [tf.sparse_to_dense(sparse_indices, output_shape, sparse_values, default_value, name=None)](#sparse_to_dense) + * [tf.sparse_tensor_to_dense(sp_input, default_value, name=None)](#sparse_tensor_to_dense) + * [tf.sparse_to_indicator(sp_input, vocab_size, name=None)](#sparse_to_indicator) +* [Manipulation.](#AUTOGENERATED-manipulation.) + * [tf.sparse_concat(concat_dim, sp_inputs, name=None)](#sparse_concat) + * [tf.sparse_reorder(sp_input, name=None)](#sparse_reorder) + * [tf.sparse_retain(sp_input, to_retain)](#sparse_retain) + * [tf.sparse_fill_empty_rows(sp_input, default_value, name=None)](#sparse_fill_empty_rows) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Sparse Tensor Representation. <div class="md-anchor" id="AUTOGENERATED-sparse-tensor-representation.">{#AUTOGENERATED-sparse-tensor-representation.}</div> + +Tensorflow supports a `SparseTensor` representation for data that is sparse +in multiple dimensions. Contrast this representation with `IndexedSlices`, +which is efficient for representing tensors that are sparse in their first +dimension, and dense along all other dimensions. + +- - - + +### class tf.SparseTensor <div class="md-anchor" id="SparseTensor">{#SparseTensor}</div> + +Represents a sparse tensor. + +Tensorflow represents a sparse tensor as three separate dense tensors: +`indices`, `values`, and `dense_shape`. In Python, the three tensors are +collected into a `SparseTensor` class for ease of use. If you have separate +`indices`, `values`, and `dense_shape` tensors, wrap them in a `SparseTensor` +object before passing to the Ops below. + +Concretely, the sparse tensor `SparseTensor(values, indices, dense_shape)` is + +* `indices`: A 2-D int64 tensor of shape `[N, ndims]`. +* `values`: A 1-D tensor of any type and shape `[N]`. +* `dense_shape`: A 1-D int64 tensor of shape `[ndims]`. + +where `N` and `ndims` are the number of values, and number of dimensions in +the `SparseTensor` respectively. + +The corresponding dense tensor satisfies + +```python +dense.shape = dense_shape +dense[tuple(indices[i])] = values[i] +``` + +By convention, `indices` should be sorted in row-major order (or equivalently +lexigraphic order on the tuples `indices[i]`). This is not enforced when +`SparseTensor` objects are constructed, but most Ops assume correct ordering. +If the ordering is wrong, it can be fixed by calling `sparse_reorder` on the +misordered `SparseTensor`. + +Example: The sparse tensor + +```python + SparseTensor(values=[1, 2], indices=[[0, 0], [1, 2]], shape=[3, 4]) +``` + +represents the dense tensor + +```python + [[1, 0, 0, 0] + [0, 0, 2, 0] + [0, 0, 0, 0]] +``` + +- - - + +#### tf.SparseTensor.__init__(indices, values, shape) {#SparseTensor.__init__} + +Creates a `SparseTensor`. + +##### Args: + + +* <b>indices</b>: A 2-D int64 tensor of shape `[N, ndims]`. +* <b>values</b>: A 1-D tensor of any type and shape `[N]`. +* <b>dense_shape</b>: A 1-D int64 tensor of shape `[ndims]`. + +##### Returns: + + A `SparseTensor` + + +- - - + +#### tf.SparseTensor.indices {#SparseTensor.indices} + +The indices of non-zero values in the represented dense tensor. + +##### Returns: + + A 2-D Tensor of int64 with shape `[N, ndims]`, where `N` is the + number of non-zero values in the tensor, and `ndims` is the rank. + +- - - + +#### tf.SparseTensor.values {#SparseTensor.values} + +The non-zero values in the represented dense tensor. + +##### Returns: + + A 1-D Tensor of any data type. + +- - - + +#### tf.SparseTensor.dtype {#SparseTensor.dtype} + +The `DType` of elements in this tensor. + +- - - + +#### tf.SparseTensor.shape {#SparseTensor.shape} + +A 1-D Tensor of int64 representing the shape of the dense tensor. + +- - - + +#### tf.SparseTensor.graph {#SparseTensor.graph} + +The `Graph` that contains the index, value, and shape tensors. + + +- - - + +### class tf.SparseTensorValue <div class="md-anchor" id="SparseTensorValue">{#SparseTensorValue}</div> + +SparseTensorValue(indices, values, shape) +- - - + +#### tf.SparseTensorValue.indices {#SparseTensorValue.indices} + +Alias for field number 0 + +- - - + +#### tf.SparseTensorValue.shape {#SparseTensorValue.shape} + +Alias for field number 2 + +- - - + +#### tf.SparseTensorValue.values {#SparseTensorValue.values} + +Alias for field number 1 + + + +## Sparse to Dense Conversion. <div class="md-anchor" id="AUTOGENERATED-sparse-to-dense-conversion.">{#AUTOGENERATED-sparse-to-dense-conversion.}</div> + +- - - + +### tf.sparse_to_dense(sparse_indices, output_shape, sparse_values, default_value, name=None) <div class="md-anchor" id="sparse_to_dense">{#sparse_to_dense}</div> + +Converts a sparse representation into a dense tensor. + +Builds an array `dense` with shape `output_shape` such that + +```prettyprint +# If sparse_indices is scalar +dense[i] = (i == sparse_indices ? sparse_values : default_value) + +# If sparse_indices is a vector, then for each i +dense[sparse_indices[i]] = sparse_values[i] + +# If sparse_indices is an n by d matrix, then for each i in [0, n) +dense[sparse_indices[i][0], ..., sparse_indices[i][d-1]] = sparse_values[i] +``` + +All other values in `dense` are set to `default_value`. If `sparse_values` is a +scalar, all sparse indices are set to this single value. + +##### Args: + + +* <b>sparse_indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + 0-D, 1-D, or 2-D. `sparse_indices[i]` contains the complete + index where `sparse_values[i]` will be placed. +* <b>output_shape</b>: A `Tensor`. Must have the same type as `sparse_indices`. + 1-D. Shape of the dense output tensor. +* <b>sparse_values</b>: A `Tensor`. + 1-D. Values corresponding to each row of `sparse_indices`, + or a scalar value to be used for all sparse indices. +* <b>default_value</b>: A `Tensor`. Must have the same type as `sparse_values`. + Scalar value to set for indices not specified in + `sparse_indices`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `sparse_values`. + Dense output tensor of shape `output_shape`. + + +- - - + +### tf.sparse_tensor_to_dense(sp_input, default_value, name=None) <div class="md-anchor" id="sparse_tensor_to_dense">{#sparse_tensor_to_dense}</div> + +Converts a `SparseTensor` into a dense tensor. + +This op is a convenience wrapper around `sparse_to_dense` for `SparseTensor`s. + +For example, if `sp_input` has shape `[3, 5]` and non-empty string values: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + +and `default_value` is `x`, then the output will be a dense `[3, 5]` +string tensor with values: + + [[x a x b x] + [x x x x x] + [c x x x x]] + +##### Args: + + +* <b>sp_input</b>: The input `SparseTensor`. +* <b>default_value</b>: Scalar value to set for indices not specified in + `sp_input`. +* <b>name</b>: A name prefix for the returned tensors (optional). + +##### Returns: + + A dense tensor with shape `sp_input.shape` and values specified by + the non-empty values in `sp_input`. Indices not in `sp_input` are assigned + `default_value`. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + +- - - + +### tf.sparse_to_indicator(sp_input, vocab_size, name=None) <div class="md-anchor" id="sparse_to_indicator">{#sparse_to_indicator}</div> + +Converts a `SparseTensor` of ids into a dense bool indicator tensor. + +The last dimension of `sp_input` is discarded and replaced with the values of +`sp_input`. If `sp_input.shape = [D0, D1, ..., Dn, K]`, then +`output.shape = [D0, D1, ..., Dn, vocab_size]`, where + + output[d_0, d_1, ..., d_n, sp_input[d_0, d_1, ..., d_n, k]] = True + +and False elsewhere in `output`. + +For example, if `sp_input.shape = [2, 3, 4]` with non-empty values: + + [0, 0, 0]: 0 + [0, 1, 0]: 10 + [1, 0, 3]: 103 + [1, 1, 2]: 112 + [1, 1, 3]: 113 + [1, 2, 1]: 121 + +and `vocab_size = 200`, then the output will be a `[2, 3, 200]` dense bool +tensor with False everywhere except at positions + + (0, 0, 0), (0, 1, 10), (1, 0, 103), (1, 1, 112), (1, 1, 113), (1, 2, 121). + +This op is useful for converting `SparseTensor`s into dense formats for +compatibility with ops that expect dense tensors. + +The input `SparseTensor` must be in row-major order. + +##### Args: + + +* <b>sp_input</b>: A `SparseTensor` of type `int32` or `int64`. +* <b>vocab_size</b>: The new size of the last dimension, with + `all(0 <= sp_input.values < vocab_size)`. +* <b>name</b>: A name prefix for the returned tensors (optional) + +##### Returns: + + A dense bool indicator tensor representing the indices with specified value. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + + +## Manipulation. <div class="md-anchor" id="AUTOGENERATED-manipulation.">{#AUTOGENERATED-manipulation.}</div> + +- - - + +### tf.sparse_concat(concat_dim, sp_inputs, name=None) <div class="md-anchor" id="sparse_concat">{#sparse_concat}</div> + +Concatenates a list of `SparseTensor` along the specified dimension. + +Concatenation is with respect to the dense versions of each sparse input. +It is assumed that each inputs is a `SparseTensor` whose elements are ordered +along increasing dimension number. + +All inputs' shapes must match, except for the concat dimension. The +`indices`, `values`, and `shapes` lists must have the same length. + +The output shape is identical to the inputs', except along the concat +dimension, where it is the sum of the inputs' sizes along that dimension. + +The output elements will be resorted to preserve the sort order along +increasing dimension number. + +This op runs in `O(M log M)` time, where `M` is the total number of non-empty +values across all inputs. This is due to the need for an internal sort in +order to concatenate efficiently across an arbitrary dimension. + +For example, if `concat_dim = 1` and the inputs are + + sp_inputs[0]: shape = [2, 3] + [0, 2]: "a" + [1, 0]: "b" + [1, 1]: "c" + + sp_inputs[1]: shape = [2, 4] + [0, 1]: "d" + [0, 2]: "e" + +then the output will be + + shape = [2, 7] + [0, 2]: "a" + [0, 4]: "d" + [0, 5]: "e" + [1, 0]: "b" + [1, 1]: "c" + +Graphically this is equivalent to doing + + [ a] concat [ d e ] = [ a d e ] + [b c ] [ ] [b c ] + +##### Args: + + +* <b>concat_dim</b>: Dimension to concatenate along. +* <b>sp_inputs</b>: List of `SparseTensor` to concatenate. +* <b>name</b>: A name prefix for the returned tensors (optional). + +##### Returns: + + A `SparseTensor` with the concatenated output. + +##### Raises: + + +* <b>TypeError</b>: If `sp_inputs` is not a list of `SparseTensor`. + + +- - - + +### tf.sparse_reorder(sp_input, name=None) <div class="md-anchor" id="sparse_reorder">{#sparse_reorder}</div> + +Reorders a `SparseTensor` into the canonical, row-major ordering. + +Note that by convention, all sparse ops preserve the canonical ordering +along increasing dimension number. The only time ordering can be violated +is during manual manipulation of the indices and values to add entries. + +Reordering does not affect the shape of the `SparseTensor`. + +For example, if sp_input has shape `[4, 5]` and `indices` / `values`: + + [0, 3]: b + [0, 1]: a + [3, 1]: d + [2, 0]: c + +then the output will be a `SparseTensor` of shape `[4, 5]` and +`indices` / `values`: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + [3, 1]: d + +##### Args: + + +* <b>sp_input</b>: The input `SparseTensor`. +* <b>name</b>: A name prefix for the returned tensors (optional) + +##### Returns: + + A `SparseTensor` with the same shape and non-empty values, but in + canonical ordering. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + +- - - + +### tf.sparse_retain(sp_input, to_retain) <div class="md-anchor" id="sparse_retain">{#sparse_retain}</div> + +Retains specified non-empty values within a `SparseTensor`. + +For example, if `sp_input` has shape `[4, 5]` and 4 non-empty string values: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + [3, 1]: d + +and `to_retain = [True, False, False, True]`, then the output will +be a `SparseTensor` of shape `[4, 5]` with 2 non-empty values: + + [0, 1]: a + [3, 1]: d + +##### Args: + + +* <b>sp_input</b>: The input `SparseTensor` with `N` non-empty elements. +* <b>to_retain</b>: A bool vector of length `N` with `M` true values. + +##### Returns: + + A `SparseTensor` with the same shape as the input and `M` non-empty + elements corresponding to the true positions in `to_retain`. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + +- - - + +### tf.sparse_fill_empty_rows(sp_input, default_value, name=None) <div class="md-anchor" id="sparse_fill_empty_rows">{#sparse_fill_empty_rows}</div> + +Fills empty rows in the input 2-D `SparseTensor` with a default value. + +This op adds entries with the specified `default_value` at index +`[row, 0]` for any row in the input that does not already have a value. + +For example, suppose `sp_input` has shape `[5, 6]` and non-empty values: + + [0, 1]: a + [0, 3]: b + [2, 0]: c + [3, 1]: d + +Rows 1 and 4 are empty, so the output will be of shape `[5, 6]` with values: + + [0, 1]: a + [0, 3]: b + [1, 0]: default_value + [2, 0]: c + [3, 1]: d + [4, 0]: default_value + +Note that the input may have empty columns at the end, with no effect on +this op. + +The output `SparseTensor` will be in row-major order and will have the +same shape as the input. + +This op also returns an indicator vector such that + + empty_row_indicator[i] = True iff row i was an empty row. + +##### Args: + + +* <b>sp_input</b>: A `SparseTensor` with shape `[N, M]`. +* <b>default_value</b>: The value to fill for empty rows, with the same type as + `sp_input.` +* <b>name</b>: A name prefix for the returned tensors (optional) + +##### Returns: + + +* <b>sp_ordered_output</b>: A `SparseTensor` with shape `[N, M]`, and with all empty + rows filled in with `default_value`. +* <b>empty_row_indicator</b>: A bool vector of length `N` indicating whether each + input row was empty. + +##### Raises: + + +* <b>TypeError</b>: If `sp_input` is not a `SparseTensor`. + + diff --git a/tensorflow/g3doc/api_docs/python/state_ops.md b/tensorflow/g3doc/api_docs/python/state_ops.md new file mode 100644 index 0000000000..70d912178b --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/state_ops.md @@ -0,0 +1,1383 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Variables +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Variables](#AUTOGENERATED-variables) + * [class tf.Variable](#Variable) +* [Variable helper functions](#AUTOGENERATED-variable-helper-functions) + * [tf.all_variables()](#all_variables) + * [tf.trainable_variables()](#trainable_variables) + * [tf.initialize_all_variables()](#initialize_all_variables) + * [tf.initialize_variables(var_list, name='init')](#initialize_variables) + * [tf.assert_variables_initialized(var_list=None)](#assert_variables_initialized) +* [Saving and Restoring Variables.](#AUTOGENERATED-saving-and-restoring-variables.) + * [class tf.train.Saver](#Saver) + * [tf.train.latest_checkpoint(checkpoint_dir, latest_filename=None)](#latest_checkpoint) + * [tf.train.get_checkpoint_state(checkpoint_dir, latest_filename=None)](#get_checkpoint_state) + * [tf.train.update_checkpoint_state(save_dir, model_checkpoint_path, all_model_checkpoint_paths=None, latest_filename=None)](#update_checkpoint_state) +* [Sharing Variables](#AUTOGENERATED-sharing-variables) + * [tf.get_variable(name, shape=None, dtype=tf.float32, initializer=None, trainable=True, collections=None)](#get_variable) + * [tf.get_variable_scope()](#get_variable_scope) + * [tf.variable_scope(*args, **kwds)](#variable_scope) + * [tf.constant_initializer(value=0.0)](#constant_initializer) + * [tf.random_normal_initializer(mean=0.0, stddev=1.0, seed=None)](#random_normal_initializer) + * [tf.truncated_normal_initializer(mean=0.0, stddev=1.0, seed=None)](#truncated_normal_initializer) + * [tf.random_uniform_initializer(minval=0.0, maxval=1.0, seed=None)](#random_uniform_initializer) + * [tf.uniform_unit_scaling_initializer(factor=1.0, seed=None)](#uniform_unit_scaling_initializer) + * [tf.zeros_initializer(shape, dtype=tf.float32)](#zeros_initializer) +* [Sparse Variable Updates](#AUTOGENERATED-sparse-variable-updates) + * [tf.scatter_update(ref, indices, updates, use_locking=None, name=None)](#scatter_update) + * [tf.scatter_add(ref, indices, updates, use_locking=None, name=None)](#scatter_add) + * [tf.scatter_sub(ref, indices, updates, use_locking=None, name=None)](#scatter_sub) + * [tf.sparse_mask(a, mask_indices, name=None)](#sparse_mask) + * [class tf.IndexedSlices](#IndexedSlices) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Variables <div class="md-anchor" id="AUTOGENERATED-variables">{#AUTOGENERATED-variables}</div> + +- - - + +### class tf.Variable <div class="md-anchor" id="Variable">{#Variable}</div> + +See the [Variables How To](../../how_tos/variables/index.md) for a high +level overview. + +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. + +```python +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 + b) + +# 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. + +```python +# Launch the graph in a session. +with tf.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 +`initialize_all_variables()` to add an Op to the graph that initializes +all the variables. You then run that Op after launching the graph. + +```python +# Add an Op to initialize all variables. +init_op = tf.initialize_all_variables() + +# Launch the graph in a session. +with tf.Session() as sess: + # Run the Op that initializes all 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.VARIABLES`. The convenience function +`all_variables()` returns the contents of that collection. + +When building a machine learning model it is often convenient to distinguish +betwen 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. + + +Creating a variable. + +- - - + +#### tf.Variable.__init__(initial_value, trainable=True, collections=None, validate_shape=True, name=None) {#Variable.__init__} + +Creates a new variable with value `initial_value`. + +The new variable is added to the graph collections listed in `collections`, +which defaults to `[GraphKeys.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: + + +* <b>initial_value</b>: A `Tensor`, or Python object convertible to a `Tensor`. + The initial value for the Variable. Must have a shape specified unless + `validate_shape` is set to False. +* <b>trainable</b>: If `True`, the default, 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. +* <b>collections</b>: List of graph collections keys. The new variable is added to + these collections. Defaults to `[GraphKeys.VARIABLES]`. +* <b>validate_shape</b>: 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. +* <b>name</b>: Optional name for the variable. Defaults to `'Variable'` and gets + uniquified automatically. + +##### Returns: + + A Variable. + +##### Raises: + + +* <b>ValueError</b>: If the initial value does not have a shape and + `validate_shape` is `True`. + + +- - - + +#### tf.Variable.initialized_value() {#Variable.initialized_value} + +Returns the value of the initialized variable. + +You should use this instead of the variable itself to initialize another +variable with a value that depends on the value of this variable. + +```python +# Initialize 'v' with a random tensor. +v = tf.Variable(tf.truncated_normal([10, 40])) +# Use `initialized_value` to guarantee that `v` has been +# initialized before its value is used to initialize `w`. +# The random values are picked only once. +w = tf.Variable(v.initialized_value() * 2.0) +``` + +##### Returns: + + A `Tensor` holding the value of this variable after its initializer + has run. + + + +Changing a variable value. + +- - - + +#### tf.Variable.assign(value, use_locking=False) {#Variable.assign} + +Assigns a new value to the variable. + +This is essentially a shortcut for `assign(self, value)`. + +##### Args: + + +* <b>value</b>: A `Tensor`. The new value for this variable. +* <b>use_locking</b>: If `True`, use locking during the assignment. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the assignment has completed. + + +- - - + +#### tf.Variable.assign_add(delta, use_locking=False) {#Variable.assign_add} + +Adds a value to this variable. + + This is essentially a shortcut for `assign_add(self, delta)`. + +##### Args: + + +* <b>delta</b>: A `Tensor`. The value to add to this variable. +* <b>use_locking</b>: If `True`, use locking during the operation. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the addition has completed. + + +- - - + +#### tf.Variable.assign_sub(delta, use_locking=False) {#Variable.assign_sub} + +Subtracts a value from this variable. + +This is essentially a shortcut for `assign_sub(self, delta)`. + +##### Args: + + +* <b>delta</b>: A `Tensor`. The value to subtract from this variable. +* <b>use_locking</b>: If `True`, use locking during the operation. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the subtraction has completed. + + +- - - + +#### tf.Variable.scatter_sub(sparse_delta, use_locking=False) {#Variable.scatter_sub} + +Subtracts `IndexedSlices` from this variable. + +This is essentially a shortcut for `scatter_sub(self, sparse_delta.indices, +sparse_delta.values)`. + +##### Args: + + +* <b>sparse_delta</b>: `IndexedSlices` to be subtracted from this variable. +* <b>use_locking</b>: If `True`, use locking during the operation. + +##### Returns: + + A `Tensor` that will hold the new value of this variable after + the scattered subtraction has completed. + +##### Raises: + + +* <b>ValueError</b>: if `sparse_delta` is not an `IndexedSlices`. + + +- - - + +#### tf.Variable.count_up_to(limit) {#Variable.count_up_to} + +Increments this variable until it reaches `limit`. + +When that Op is run it tries to increment the variable by `1`. If +incrementing the variable would bring it above `limit` then the Op raises +the exception `OutOfRangeError`. + +If no error is raised, the Op outputs the value of the variable before +the increment. + +This is essentially a shortcut for `count_up_to(self, limit)`. + +##### Args: + + +* <b>limit</b>: value at which incrementing the variable raises an error. + +##### Returns: + + A `Tensor` that will hold the variable value before the increment. If no + other Op modifies this variable, the values produced will all be + distinct. + + + +- - - + +#### tf.Variable.eval(session=None) {#Variable.eval} + +In a session, computes and returns the value of this variable. + +This is not a graph construction method, it does not add ops to the graph. + +This convenience method requires a session where the graph containing this +variable has been launched. If no session is passed, the default session is +used. See the [Session class](../client.md#Session) for more information on +launching a graph and on sessions. + +```python +v = tf.Variable([1, 2]) +init = tf.initialize_all_variables() + +with tf.Session() as sess: + sess.run(init) + # Usage passing the session explicitly. + print v.eval(sess) + # Usage with the default session. The 'with' block + # above makes 'sess' the default session. + print v.eval() +``` + +##### Args: + + +* <b>session</b>: The session to use to evaluate this variable. If + none, the default session is used. + +##### Returns: + + A numpy `ndarray` with a copy of the value of this variable. + + + +Properties. + +- - - + +#### tf.Variable.name {#Variable.name} + +The name of this variable. + +- - - + +#### tf.Variable.dtype {#Variable.dtype} + +The `DType` of this variable. + +- - - + +#### tf.Variable.get_shape() {#Variable.get_shape} + +The `TensorShape` of this variable. + +##### Returns: + + A `TensorShape`. + + +- - - + +#### tf.Variable.device {#Variable.device} + +The device of this variable. + +- - - + +#### tf.Variable.initializer {#Variable.initializer} + +The initializer operation for this variable. + +- - - + +#### tf.Variable.graph {#Variable.graph} + +The `Graph` of this variable. + +- - - + +#### tf.Variable.op {#Variable.op} + +The `Operation` of this variable. + + + +## Variable helper functions <div class="md-anchor" id="AUTOGENERATED-variable-helper-functions">{#AUTOGENERATED-variable-helper-functions}</div> + +TensorFlow provides a set of functions to help manage the set of variables +collected in the graph. + +- - - + +### tf.all_variables() <div class="md-anchor" id="all_variables">{#all_variables}</div> + +Returns all variables collected in the graph. + +The `Variable()` constructor automatically adds new variables to the graph +collection `GraphKeys.VARIABLES`. This convenience function returns the +contents of that collection. + +##### Returns: + + A list of `Variable` objects. + + +- - - + +### tf.trainable_variables() <div class="md-anchor" id="trainable_variables">{#trainable_variables}</div> + +Returns all variables created with `trainable=True`. + +When passed `trainable=True`, the `Variable()` constructor automatically +adds new variables to the graph collection +`GraphKeys.TRAINABLE_VARIABLES`. This convenience function returns the +contents of that collection. + +##### Returns: + + A list of Variable objects. + + + +- - - + +### tf.initialize_all_variables() <div class="md-anchor" id="initialize_all_variables">{#initialize_all_variables}</div> + +Returns an Op that initializes all variables. + +This is just a shortcut for `initialize_variables(all_variables())` + +##### Returns: + + An Op that initializes all variables in the graph. + + +- - - + +### tf.initialize_variables(var_list, name='init') <div class="md-anchor" id="initialize_variables">{#initialize_variables}</div> + +Returns an Op that initializes a list of variables. + +After you launch the graph in a session, you can run the returned Op to +initialize all the variables in `var_list`. This Op runs all the +initializers of the variables in `var_list` in parallel. + +Calling `initialize_variables()` is equivalent to passing the list of +initializers to `Group()`. + +If `var_list` is empty, however, the function still returns an Op that can +be run. That Op just has no effect. + +##### Args: + + +* <b>var_list</b>: List of `Variable` objects to initialize. +* <b>name</b>: Optional name for the returned operation. + +##### Returns: + + An Op that run the initializers of all the specified variables. + + +- - - + +### tf.assert_variables_initialized(var_list=None) <div class="md-anchor" id="assert_variables_initialized">{#assert_variables_initialized}</div> + +Returns an Op to check if variables are initialized. + +When run, the returned Op will raise the exception `FailedPreconditionError` +if any of the variables has not yet been initialized. + +Note: This function is implemented by trying to fetch the values of the +variables. If one of the variables is not initialized a message may be +logged by the C++ runtime. This is expected. + +##### Args: + + +* <b>var_list</b>: List of `Variable` objects to check. Defaults to the + value of `all_variables().` + +##### Returns: + + An Op, or None if there are no variables. + + + +## Saving and Restoring Variables. <div class="md-anchor" id="AUTOGENERATED-saving-and-restoring-variables.">{#AUTOGENERATED-saving-and-restoring-variables.}</div> + +- - - + +### class tf.train.Saver <div class="md-anchor" id="Saver">{#Saver}</div> + +Saves and restores variables. + +See [Variables](../../how_tos/variables/index.md) +for an overview of variables, saving and restoring. + +The `Saver` class adds ops to save and restore variables to and from +*checkpoints*. It also provides convenience methods to run these ops. + +Checkpoints are binary files in a proprietary format which map variable names +to tensor values. The best way to examine the contents of a checkpoint is to +load it using a `Saver`. + +Savers can automatically number checkpoint filenames with a provided counter. +This lets you keep multiple checkpoints at different steps while training a +model. For example you can number the checkpoint filenames with the training +step number. To avoid filling up disks, savers manage checkpoint files +automatically. For example, they can keep only the N most recent files, or +one checkpoint for every N hours of training. + +You number checkpoint filenames by passing a value to the optional +`global_step` argument to `save()`: + +```python +saver.save('my-model', global_step=0) ==> filename: 'my-model-0' +... +saver.save('my-model', global_step=1000) ==> filename: 'my-model-1000' +``` + +Additionally, optional arguments to the `Saver()` constructor let you control +the proliferation of checkpoint files on disk: + +* `max_to_keep` indicates the maximum number of recent checkpoint files to + keep. As new files are created, older files are deleted. If None or 0, + all checkpoint files are kept. Defaults to 5 (that is, the 5 most recent + checkpoint files are kept.) + +* `keep_checkpoint_every_n_hours`: In addition to keeping the most recent + `max_to_keep` checkpoint files, you might want to keep one checkpoint file + for every N hours of training. This can be useful if you want to later + analyze how a model progressed during a long training session. For + example, passing `keep_checkpoint_every_n_hours=2` ensures that you keep + one checkpoint file for every 2 hours of training. The default value of + 10,000 hours effectively disables the feature. + +Note that you still have to call the `save()` method to save the model. +Passing these arguments to the constructor will not save variables +automatically for you. + +A training program that saves regularly looks like: + +```python +... +# Create a saver. +saver = tf.train.Saver(...variables...) +# Launch the graph and train, saving the model every 1,000 steps. +sess = tf.Session() +for step in xrange(1000000): + sess.run(..training_op..) + if step % 1000 == 0: + # Append the step number to the checkpoint name: + saver.save(sess, 'my-model', global_step=step) +``` + +In addition to checkpoint files, savers keep a protocol buffer on disk with +the list of recent checkpoints. This is used to manage numbered checkpoint +files and by `latest_checkpoint()`, which makes it easy to discover the path +to the most recent checkpoint. That protocol buffer is stored in a file named +'checkpoint' next to the checkpoint files. + +If you create several savers, you can specify a different filename for the +protocol buffer file in the call to `save()`. + +- - - + +#### tf.train.Saver.__init__(var_list=None, reshape=False, sharded=False, max_to_keep=5, keep_checkpoint_every_n_hours=10000.0, name=None, restore_sequentially=False, saver_def=None, builder=None) {#Saver.__init__} + +Creates a `Saver`. + +The constructor adds ops to save and restore variables. + +`var_list` specifies the variables that will be saved and restored. It can +be passed as a `dict` or a list: + +* A `dict` of names to variables: The keys are the names that will be + used to save or restore the variables in the checkpoint files. +* A list of variables: The variables will be keyed with their op name in + the checkpoint files. + +For example: + +```python +v1 = tf.Variable(..., name='v1') +v2 = tf.Variable(..., name='v2') + +# Pass the variables as a dict: +saver = tf.train.Saver({'v1': v1, 'v2': v2}) + +# Or pass them as a list. +saver = tf.train.Saver([v1, v2]) +# Passing a list is equivalent to passing a dict with the variable op names +# as keys: +saver = tf.train.Saver({v.op.name: v for v in [v1, v2]}) +``` + +The optional `reshape` argument, if True, allows restoring a variable from +a save file where the variable had a different shape, but the same number +of elements and type. This is useful if you have reshaped a variable and +want to reload it from an older checkpoint. + +The optional `sharded` argument, if True, instructs the saver to shard +checkpoints per device. + +##### Args: + + +* <b>var_list</b>: A list of Variables or a dictionary mapping names to + Variables. If None, defaults to the list of all variables. +* <b>reshape</b>: If True, allows restoring parameters from a checkpoint + where the variables have a different shape. +* <b>sharded</b>: If True, shard the checkpoints, one per device. +* <b>max_to_keep</b>: maximum number of recent checkpoints to keep. + Defaults to 10,000 hours. +* <b>keep_checkpoint_every_n_hours</b>: How often to keep checkpoints. + Defaults to 10,000 hours. +* <b>name</b>: string. Optional name to use as a prefix when adding operations. +* <b>restore_sequentially</b>: A Bool, which if true, causes restore of different + variables to happen sequentially within each device. This can lower + memory usage when restoring very large models. +* <b>saver_def</b>: Optional SaverDef proto to use instead of running the builder. + This is only useful for specialty code that wants to recreate a Saver + object for a previously built Graph that had a Saver. The saver_def + proto should be the one returned by the as_saver_def() call of the + Saver that was created for that Graph. +* <b>builder</b>: Optional SaverBuilder to use if a saver_def was not provided. + Defaults to BaseSaverBuilder(). + +##### Raises: + + +* <b>TypeError</b>: If `var_list` is invalid. +* <b>ValueError</b>: If any of the keys or values in `var_list` is not unique. + + +- - - + +#### tf.train.Saver.save(sess, save_path, global_step=None, latest_filename=None) {#Saver.save} + +Saves variables. + +This method runs the ops added by the constructor for saving variables. +It requires a session in which the graph was launched. The variables to +save must also have been initialized. + +The method returns the path of the newly created checkpoint file. This +path can be passed directly to a call to `restore()`. + +##### Args: + + +* <b>sess</b>: A Session to use to save the variables.. +* <b>save_path</b>: string. Path to the checkpoint filename. If the saver is + `sharded`, this is the prefix of the sharded checkpoint filename. +* <b>global_step</b>: If provided the global step number is appended to + `save_path` to create the checkpoint filename. The optional argument + can be a Tensor, a Tensor name or an integer. +* <b>latest_filename</b>: Optional name for the protocol buffer file that will + contains the list of most recent checkpoint filenames. That file, + kept in the same directory as the checkpoint files, is automatically + managed by the saver to keep track of recent checkpoints. Defaults to + 'checkpoint'. + +##### Returns: + + A string: path at which the variables were saved. If the saver is + sharded, this string ends with: '-?????-of-nnnnn' where 'nnnnn' + is the number of shards created. + +##### Raises: + + +* <b>TypeError</b>: If `sess` is not a Session. + + +- - - + +#### tf.train.Saver.restore(sess, save_path) {#Saver.restore} + +Restores previously saved variables. + +This method runs the ops added by the constructor for restoring variables. +It requires a session in which the graph was launched. The variables to +restore do not have to have been initialized, as restoring is itself a way +to initialize variables. + +The `save_path` argument is typically a value previously returned from a +`save()` call, or a call to `latest_checkpoint()`. + +##### Args: + + +* <b>sess</b>: A Session to use to restore the parameters. +* <b>save_path</b>: Path where parameters were previously saved. + + + +Other utility methods. + +- - - + +#### tf.train.Saver.last_checkpoints {#Saver.last_checkpoints} + +List of not-yet-deleted checkpoint filenames. + +You can pass any of the returned values to `restore()`. + +##### Returns: + + A list of checkpoint filenames, sorted from oldest to newest. + +- - - + +#### tf.train.Saver.set_last_checkpoints(last_checkpoints) {#Saver.set_last_checkpoints} + +Sets the list of not-yet-deleted checkpoint filenames. + +##### Args: + + +* <b>last_checkpoints</b>: a list of checkpoint filenames. + +##### Raises: + + +* <b>AssertionError</b>: if the list of checkpoint filenames has already been set. + + +- - - + +#### tf.train.Saver.as_saver_def() {#Saver.as_saver_def} + +Generates a `SaverDef` representation of this saver. + +##### Returns: + + A `SaverDef` proto. + + + + +- - - + +### tf.train.latest_checkpoint(checkpoint_dir, latest_filename=None) <div class="md-anchor" id="latest_checkpoint">{#latest_checkpoint}</div> + +Finds the filename of latest saved checkpoint file. + +##### Args: + + +* <b>checkpoint_dir</b>: Directory where the variables were saved. +* <b>latest_filename</b>: Optional name for the protocol buffer file that + contains the list of most recent checkpoint filenames. + See the corresponding argument to `Saver.save()`. + +##### Returns: + + The full path to the latest checkpoint or None if no checkpoint was found. + + + +- - - + +### tf.train.get_checkpoint_state(checkpoint_dir, latest_filename=None) <div class="md-anchor" id="get_checkpoint_state">{#get_checkpoint_state}</div> + +Returns CheckpointState proto from the "checkpoint" file. + +If the "checkpoint" file contains a valid CheckpointState +proto, returns it. + +##### Args: + + +* <b>checkpoint_dir</b>: The directory of checkpoints. +* <b>latest_filename</b>: Optional name of the checkpoint file. Default to + 'checkpoint'. + +##### Returns: + + A CheckpointState if the state was available, None + otherwise. + + +- - - + +### tf.train.update_checkpoint_state(save_dir, model_checkpoint_path, all_model_checkpoint_paths=None, latest_filename=None) <div class="md-anchor" id="update_checkpoint_state">{#update_checkpoint_state}</div> + +Updates the content of the 'checkpoint' file. + +This updates the checkpoint file containing a CheckpointState +proto. + +##### Args: + + +* <b>save_dir</b>: Directory where the model was saved. +* <b>model_checkpoint_path</b>: The checkpoint file. +* <b>all_model_checkpoint_paths</b>: list of strings. Paths to all not-yet-deleted + checkpoints, sorted from oldest to newest. If this is a non-empty list, + the last element must be equal to model_checkpoint_path. These paths + are also saved in the CheckpointState proto. +* <b>latest_filename</b>: Optional name of the checkpoint file. Default to + 'checkpoint'. + +##### Raises: + + +* <b>RuntimeError</b>: If the save paths conflict. + + + +## Sharing Variables <div class="md-anchor" id="AUTOGENERATED-sharing-variables">{#AUTOGENERATED-sharing-variables}</div> + +TensorFlow provides several classes and operations that you can use to +create variables contingent on certain conditions. + +- - - + +### tf.get_variable(name, shape=None, dtype=tf.float32, initializer=None, trainable=True, collections=None) <div class="md-anchor" id="get_variable">{#get_variable}</div> + +Gets an existing variable with these parameters or create a new one. + +This function prefixes the name with the current variable scope +and performs reuse checks. See the +[Variable Scope How To](../../how_tos/variable_scope/index.md) +for an extensive description of how reusing works. Here is a basic example: + +```python +with tf.variable_scope("foo"): + v = get_variable("v", [1]) # v.name == "foo/v:0" + w = get_variable("w", [1]) # w.name == "foo/w:0" +with tf.variable_scope("foo", reuse=True) + v1 = get_variable("v") # The same as v above. +``` + +If initializer is `None` (the default), the default initializer passed in +the constructor is used. If that one is `None` too, a +`UniformUnitScalingInitializer` will be used. + +##### Args: + + +* <b>name</b>: the name of the new or existing variable. +* <b>shape</b>: shape of the new or existing variable. +* <b>dtype</b>: type of the new or existing variable (defaults to `DT_FLOAT`). +* <b>initializer</b>: initializer for the variable if one is created. +* <b>trainable</b>: If `True` also add the variable to the graph collection + `GraphKeys.TRAINABLE_VARIABLES` (see variables.Variable). +* <b>collections</b>: List of graph collections keys to add the Variable to. + Defaults to `[GraphKeys.VARIABLES]` (see variables.Variable). + +##### Returns: + + The created or existing variable. + +##### Raises: + + +* <b>ValueError</b>: when creating a new variable and shape is not declared, + or when violating reuse during variable creation. Reuse is set inside + `variable_scope`. + + +- - - + +### tf.get_variable_scope() <div class="md-anchor" id="get_variable_scope">{#get_variable_scope}</div> + +Returns the current variable scope. + + +- - - + +### tf.variable_scope(*args, **kwds) <div class="md-anchor" id="variable_scope">{#variable_scope}</div> + +Returns a context for variable scope. + +Variable scope allows to create new variables and to share already created +ones while providing checks to not create or share by accident. For details, +see the [Variable Scope How To](../../how_tos/variable_scope/index.md), +here we present only a few basic examples. + +Simple example of how to create a new variable: + +```python +with tf.variable_scope("foo"): + with tf.variable_scope("bar"): + v = tf.get_variable("v", [1]) + assert v.name == "foo/bar/v:0" +``` + +Basic example of sharing a variable: + +```python +with tf.variable_scope("foo"): + v = get_variable("v", [1]) +with tf.variable_scope("foo", reuse=True): + v1 = tf.get_variable("v", [1]) +assert v1 == v +``` + +Sharing a variable by capturing a scope and setting reuse: + +```python +with tf.variable_scope("foo") as scope. + v = get_variable("v", [1]) + scope.reuse_variables() + v1 = tf.get_variable("v", [1]) +assert v1 == v +``` + +To prevent accidental sharing of variables, we raise an exception when +getting an existing variable in a non-reusing scope. + +```python +with tf.variable_scope("foo") as scope. + v = get_variable("v", [1]) + v1 = tf.get_variable("v", [1]) + # Raises ValueError("... v already exists ..."). +``` + +Similarly, we raise an exception when trying to get a variable that +does not exist in reuse mode. + +```python +with tf.variable_scope("foo", reuse=True): + v = get_variable("v", [1]) + # Raises ValueError("... v does not exists ..."). +``` + +Note that the `reuse` flag is inherited: if we open a reusing scope, +then all its sub-scopes become reusing as well. + +##### Args: + + +* <b>name_or_scope</b>: `string` or `VariableScope`: the scope to open. +* <b>reuse</b>: `True` or `None`; if `True`, we go into reuse mode for this scope as + well as all sub-scopes; if `None`, we just inherit the parent scope reuse. +* <b>initializer</b>: default initializer for variables within this scope. + +##### Yields: + + A scope that can be to captured and reused. + +##### Raises: + + +* <b>ValueError</b>: when trying to reuse within a create scope, or create within + a reuse scope, or if reuse is not `None` or `True`. +* <b>TypeError</b>: when the types of some arguments are not appropriate. + + + +- - - + +### tf.constant_initializer(value=0.0) <div class="md-anchor" id="constant_initializer">{#constant_initializer}</div> + +Returns an initializer that generates Tensors with a single value. + +##### Args: + + +* <b>value</b>: A Python scalar. All elements of the initialized variable + will be set to this value. + +##### Returns: + + An initializer that generates Tensors with a single value. + + +- - - + +### tf.random_normal_initializer(mean=0.0, stddev=1.0, seed=None) <div class="md-anchor" id="random_normal_initializer">{#random_normal_initializer}</div> + +Returns an initializer that generates Tensors with a normal distribution. + +##### Args: + + +* <b>mean</b>: a python scalar or a scalar tensor. Mean of the random values + to generate. +* <b>stddev</b>: a python scalar or a scalar tensor. Standard deviation of the + random values to generate. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates Tensors with a normal distribution. + + +- - - + +### tf.truncated_normal_initializer(mean=0.0, stddev=1.0, seed=None) <div class="md-anchor" id="truncated_normal_initializer">{#truncated_normal_initializer}</div> + +Returns an initializer that generates a truncated normal distribution. + +These values are similar to values from a random_normal_initializer +except that values more than two standard deviations from the mean +are discarded and re-drawn. This is the recommended initializer for +neural network weights and filters. + +##### Args: + + +* <b>mean</b>: a python scalar or a scalar tensor. Mean of the random values + to generate. +* <b>stddev</b>: a python scalar or a scalar tensor. Standard deviation of the + random values to generate. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates Tensors with a truncated normal + distribution. + + +- - - + +### tf.random_uniform_initializer(minval=0.0, maxval=1.0, seed=None) <div class="md-anchor" id="random_uniform_initializer">{#random_uniform_initializer}</div> + +Returns an initializer that generates Tensors with a uniform distribution. + +##### Args: + + +* <b>minval</b>: a python scalar or a scalar tensor. lower bound of the range + of random values to generate. +* <b>maxval</b>: a python scalar or a scalar tensor. upper bound of the range + of random values to generate. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates Tensors with a uniform distribution. + + +- - - + +### tf.uniform_unit_scaling_initializer(factor=1.0, seed=None) <div class="md-anchor" id="uniform_unit_scaling_initializer">{#uniform_unit_scaling_initializer}</div> + +Returns an initializer that generates tensors without scaling variance. + +When initializing a deep network, it is in principle advantageous to keep +the scale of the input variance constant, so it does not explode or diminish +by reaching the final layer. If the input is `x` and the operation `x * W`, +and we want to initialize `W` uniformly at random, we need to pick `W` from + + [-sqrt(3) / sqrt(dim), sqrt(3) / sqrt(dim)] + +to keep the scale intact, where `dim = W.shape[0]` (the size of the input). +A similar calculation for convolutional networks gives an analogous result +with `dim` equal to the product of the first 3 dimensions. When +nonlinearities are present, we need to multiply this by a constant `factor`. +See <https://arxiv.org/pdf/1412.6558v3.pdf> for deeper motivation, experiments +and the calculation of constants. In section 2.3 there, the constants were +numerically computed: for a linear layer it's 1.0, relu: ~1.43, tanh: ~1.15. + +##### Args: + + +* <b>factor</b>: Float. A multiplicative factor by which the values will be scaled. +* <b>seed</b>: A Python integer. Used to create random seeds. + See [`set_random_seed`](constant_op.md#set_random_seed) for behavior. + +##### Returns: + + An initializer that generates tensors with unit variance. + + +- - - + +### tf.zeros_initializer(shape, dtype=tf.float32) <div class="md-anchor" id="zeros_initializer">{#zeros_initializer}</div> + +An adaptor for zeros() to match the Initializer spec. + + + +## Sparse Variable Updates <div class="md-anchor" id="AUTOGENERATED-sparse-variable-updates">{#AUTOGENERATED-sparse-variable-updates}</div> + +The sparse update ops modify a subset of the entries in a dense `Variable`, +either overwriting the entries or adding / subtracting a delta. These are +useful for training embedding models and similar lookup-based networks, since +only a small subset of embedding vectors change in any given step. + +Since a sparse update of a large tensor may be generated automatically during +gradient computation (as in the gradient of [`tf.gather`](array_ops.md#gather)), +an [`IndexedSlices`](#IndexedSlices) class is provided that encapsulates a set +of sparse indices and values. `IndexedSlices` objects are detected and handled +automatically by the optimizers in most cases. + +- - - + +### tf.scatter_update(ref, indices, updates, use_locking=None, name=None) <div class="md-anchor" id="scatter_update">{#scatter_update}</div> + +Applies sparse updates to a variable reference. + +This operation computes + + # Scalar indices + ref[indices, ...] = updates[...] + + # Vector indices (for each i) + ref[indices[i], ...] = updates[i, ...] + + # High rank indices (for each i, ..., j) + ref[indices[i, ..., j], ...] = updates[i, ..., j, ...] + +This operation outputs `ref` after the update is done. +This makes it easier to chain operations that need to use the reset value. + +If `indices` contains duplicate entries, lexicographically later entries +override earlier entries. + +Requires `updates.shape = indices.shape + ref.shape[1:]`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/ScatterUpdate.png" alt> +</div> + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Should be from a `Variable` node. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A tensor of indices into the first dimension of `ref`. +* <b>updates</b>: A `Tensor`. Must have the same type as `ref`. + A tensor of updated values to store in `ref`. +* <b>use_locking</b>: An optional `bool`. Defaults to `True`. + If True, the assignment will be protected by a lock; + otherwise the behavior is undefined, but may exhibit less contention. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same as `ref`. Returned as a convenience for operations that want + to use the updated values after the update is done. + + +- - - + +### tf.scatter_add(ref, indices, updates, use_locking=None, name=None) <div class="md-anchor" id="scatter_add">{#scatter_add}</div> + +Adds sparse updates to a variable reference. + +This operation computes + + # Scalar indices + ref[indices, ...] += updates[...] + + # Vector indices (for each i) + ref[indices[i], ...] += updates[i, ...] + + # High rank indices (for each i, ..., j) + ref[indices[i, ..., j], ...] += updates[i, ..., j, ...] + +This operation outputs `ref` after the update is done. +This makes it easier to chain operations that need to use the reset value. + +Duplicate entries are handled correctly: if multiple `indices` reference +the same location, their contributions add. + +Requires `updates.shape = indices.shape + ref.shape[1:]`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/ScatterAdd.png" alt> +</div> + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Should be from a `Variable` node. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A tensor of indices into the first dimension of `ref`. +* <b>updates</b>: A `Tensor`. Must have the same type as `ref`. + A tensor of updated values to add to `ref`. +* <b>use_locking</b>: An optional `bool`. Defaults to `False`. + If True, the addition will be protected by a lock; + otherwise the behavior is undefined, but may exhibit less contention. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same as `ref`. Returned as a convenience for operations that want + to use the updated values after the update is done. + + +- - - + +### tf.scatter_sub(ref, indices, updates, use_locking=None, name=None) <div class="md-anchor" id="scatter_sub">{#scatter_sub}</div> + +Subtracts sparse updates to a variable reference. + + # Scalar indices + ref[indices, ...] -= updates[...] + + # Vector indices (for each i) + ref[indices[i], ...] -= updates[i, ...] + + # High rank indices (for each i, ..., j) + ref[indices[i, ..., j], ...] -= updates[i, ..., j, ...] + +This operation outputs `ref` after the update is done. +This makes it easier to chain operations that need to use the reset value. + +Duplicate entries are handled correctly: if multiple `indices` reference +the same location, their (negated) contributions add. + +Requires `updates.shape = indices.shape + ref.shape[1:]`. + +<div style="width:70%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="../images/ScatterSub.png" alt> +</div> + +##### Args: + + +* <b>ref</b>: A mutable `Tensor`. Must be one of the following types: `float32`, `float64`, `int64`, `int32`, `uint8`, `int16`, `int8`, `complex64`, `qint8`, `quint8`, `qint32`. + Should be from a `Variable` node. +* <b>indices</b>: A `Tensor`. Must be one of the following types: `int32`, `int64`. + A tensor of indices into the first dimension of `ref`. +* <b>updates</b>: A `Tensor`. Must have the same type as `ref`. + A tensor of updated values to subtract from `ref`. +* <b>use_locking</b>: An optional `bool`. Defaults to `False`. + If True, the subtraction will be protected by a lock; + otherwise the behavior is undefined, but may exhibit less contention. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + Same as `ref`. Returned as a convenience for operations that want + to use the updated values after the update is done. + + +- - - + +### tf.sparse_mask(a, mask_indices, name=None) <div class="md-anchor" id="sparse_mask">{#sparse_mask}</div> + +Masks elements of `IndexedSlices`. + +Given an `IndexedSlices` instance `a`, returns another `IndexedSlices` that +contains a subset of the slices of `a`. Only the slices at indices specified +in `mask_indices` are returned. + +This is useful when you need to extract a subset of slices in an +`IndexedSlices` object. + +For example: + +```python +# `a` contains slices at indices [12, 26, 37, 45] from a large tensor +# with shape [1000, 10] +a.indices => [12, 26, 37, 45] +tf.shape(a.values) => [4, 10] + +# `b` will be the subset of `a` slices at its second and third indices, so +# we want to mask of its first and last indices (which are at absolute +# indices 12, 45) +b = tf.sparse_mask(a, [12, 45]) + +b.indices => [26, 37] +tf.shape(b.values) => [2, 10] + +``` + +##### Args: + + * `a`: An `IndexedSlices` instance. + * `mask_indices`: Indices of elements to mask. + * `name`: A name for the operation (optional). + +##### Returns: + + The masked `IndexedSlices` instance. + + +- - - + +### class tf.IndexedSlices <div class="md-anchor" id="IndexedSlices">{#IndexedSlices}</div> + +A sparse representation of a set of tensor slices at given indices. + +This class is a simple wrapper for a pair of `Tensor` objects: + +* `values`: A `Tensor` of any dtype with shape `[D0, D1, ..., Dn]`. +* `indices`: A 1-D integer `Tensor` with shape `[D0]`. + +An `IndexedSlices` is typically used to represent a subset of a larger +tensor `dense` of shape `[LARGE0, D1, .. , DN]` where `LARGE0 >> D0`. +The values in `indices` are the indices in the first dimension of +the slices that have been extracted from the larger tensor. + +The dense tensor `dense` represented by an `IndexedSlices` `slices` has + +```python +dense[slices.indices[i], :, :, :, ...] = slices.values[i, :, :, :, ...] +``` + +The `IndexedSlices` class is used principally in the definition of +gradients for operations that have sparse gradients +(e.g. [`tf.gather`](array_ops.md#gather)). + +Contrast this representation with +[`SparseTensor`](sparse_ops.md#SparseTensor), +which uses multi-dimensional indices and scalar values. + +- - - + +#### tf.IndexedSlices.__init__(values, indices, dense_shape=None) {#IndexedSlices.__init__} + +Creates an `IndexedSlices`. + + + +- - - + +#### tf.IndexedSlices.values {#IndexedSlices.values} + +A `Tensor` containing the values of the slices. + +- - - + +#### tf.IndexedSlices.indices {#IndexedSlices.indices} + +A 1-D `Tensor` containing the indices of the slices. + +- - - + +#### tf.IndexedSlices.dense_shape {#IndexedSlices.dense_shape} + +A 1-D `Tensor` containing the shape of the corresponding dense tensor. + + +- - - + +#### tf.IndexedSlices.name {#IndexedSlices.name} + +The name of this `IndexedSlices`. + +- - - + +#### tf.IndexedSlices.dtype {#IndexedSlices.dtype} + +The `DType` of elements in this tensor. + +- - - + +#### tf.IndexedSlices.device {#IndexedSlices.device} + +The name of the device on which `values` will be produced, or `None`. + +- - - + +#### tf.IndexedSlices.op {#IndexedSlices.op} + +The `Operation` that produces `values` as an output. + + diff --git a/tensorflow/g3doc/api_docs/python/train.md b/tensorflow/g3doc/api_docs/python/train.md new file mode 100644 index 0000000000..0c88968c5d --- /dev/null +++ b/tensorflow/g3doc/api_docs/python/train.md @@ -0,0 +1,1825 @@ +<!-- This file is machine generated: DO NOT EDIT! --> + +# Training +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Optimizers.](#AUTOGENERATED-optimizers.) + * [class tf.train.Optimizer](#Optimizer) + * [Usage](#AUTOGENERATED-usage) + * [Processing gradients before applying them.](#AUTOGENERATED-processing-gradients-before-applying-them.) + * [Gating Gradients](#AUTOGENERATED-gating-gradients) + * [Slots](#AUTOGENERATED-slots) + * [class tf.train.GradientDescentOptimizer](#GradientDescentOptimizer) + * [class tf.train.AdagradOptimizer](#AdagradOptimizer) + * [class tf.train.MomentumOptimizer](#MomentumOptimizer) + * [class tf.train.AdamOptimizer](#AdamOptimizer) + * [class tf.train.FtrlOptimizer](#FtrlOptimizer) + * [class tf.train.RMSPropOptimizer](#RMSPropOptimizer) +* [Gradient Computation.](#AUTOGENERATED-gradient-computation.) + * [tf.gradients(ys, xs, grad_ys=None, name='gradients', colocate_gradients_with_ops=False, gate_gradients=False, aggregation_method=None)](#gradients) + * [class tf.AggregationMethod](#AggregationMethod) + * [tf.stop_gradient(input, name=None)](#stop_gradient) +* [Gradient Clipping](#AUTOGENERATED-gradient-clipping) + * [tf.clip_by_value(t, clip_value_min, clip_value_max, name=None)](#clip_by_value) + * [tf.clip_by_norm(t, clip_norm, name=None)](#clip_by_norm) + * [tf.clip_by_average_norm(t, clip_norm, name=None)](#clip_by_average_norm) + * [tf.clip_by_global_norm(t_list, clip_norm, use_norm=None, name=None)](#clip_by_global_norm) + * [tf.global_norm(t_list, name=None)](#global_norm) +* [Decaying the learning rate.](#AUTOGENERATED-decaying-the-learning-rate.) + * [tf.train.exponential_decay(learning_rate, global_step, decay_steps, decay_rate, staircase=False, name=None)](#exponential_decay) +* [Moving Averages.](#AUTOGENERATED-moving-averages.) + * [class tf.train.ExponentialMovingAverage](#ExponentialMovingAverage) +* [Coordinator and QueueRunner.](#AUTOGENERATED-coordinator-and-queuerunner.) + * [class tf.train.Coordinator](#Coordinator) + * [class tf.train.QueueRunner](#QueueRunner) + * [tf.train.add_queue_runner(qr, collection='queue_runners')](#add_queue_runner) + * [tf.train.start_queue_runners(sess=None, coord=None, daemon=True, start=True, collection='queue_runners')](#start_queue_runners) +* [Summary Operations.](#AUTOGENERATED-summary-operations.) + * [tf.scalar_summary(tags, values, collections=None, name=None)](#scalar_summary) + * [tf.image_summary(tag, tensor, max_images=None, collections=None, name=None)](#image_summary) + * [tf.histogram_summary(tag, values, collections=None, name=None)](#histogram_summary) + * [tf.nn.zero_fraction(value, name=None)](#zero_fraction) + * [tf.merge_summary(inputs, collections=None, name=None)](#merge_summary) + * [tf.merge_all_summaries(key='summaries')](#merge_all_summaries) +* [Adding Summaries to Event Files.](#AUTOGENERATED-adding-summaries-to-event-files.) + * [class tf.train.SummaryWriter](#SummaryWriter) + * [tf.train.summary_iterator(path)](#summary_iterator) +* [Training utilities.](#AUTOGENERATED-training-utilities.) + * [tf.train.global_step(sess, global_step_tensor)](#global_step) + * [tf.train.write_graph(graph_def, logdir, name, as_text=True)](#write_graph) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +This library provides a set of classes and functions that helps train models. + +## Optimizers. <div class="md-anchor" id="AUTOGENERATED-optimizers.">{#AUTOGENERATED-optimizers.}</div> + +The Optimizer base class provides methods to compute gradients for a loss and +apply gradients to variables. A collection of subclasses implement classic +optimization algorithms such as GradientDescent and Adagrad. + +You never instantiate the Optimizer class itself, but instead instantiate one +of the subclasses. + +- - - + +### class tf.train.Optimizer <div class="md-anchor" id="Optimizer">{#Optimizer}</div> + +Base class for optimizers. + +This class defines the API to add Ops to train a model. You never use this +class directly, but instead instantiate one of its subclasses such as +`GradientDescentOptimizer`, `AdagradOptimizer`, or `MomentumOptimizer`. + +### Usage <div class="md-anchor" id="AUTOGENERATED-usage">{#AUTOGENERATED-usage}</div> + +``` +# Create an optimizer with the desired parameters. +opt = GradientDescentOptimizer(learning_rate=0.1) +# Add Ops to the graph to minimize a cost by updating a list of variables. +# "cost" is a Tensor, and the list of variables contains variables.Variable +# objects. +opt_op = opt.minimize(cost, <list of variables>) +``` + +In the training program you will just have to run the returned Op. + +``` +# Execute opt_op to do one step of training: +opt_op.run() +``` + +### Processing gradients before applying them. <div class="md-anchor" id="AUTOGENERATED-processing-gradients-before-applying-them.">{#AUTOGENERATED-processing-gradients-before-applying-them.}</div> + +Calling `minimize()` takes care of both computing the gradients and +applying them to the variables. If you want to process the gradients +before applying them you can instead use the optimizer in three steps: + +1. Compute the gradients with `compute_gradients()`. +2. Process the gradients as you wish. +3. Apply the processed gradients with `apply_gradients()`. + +Example: + +``` +# Create an optimizer. +opt = GradientDescentOptimizer(learning_rate=0.1) + +# Compute the gradients for a list of variables. +grads_and_vars = opt.compute_gradients(loss, <list of variables>) + +# grads_and_vars is a list of tuples (gradient, variable). Do whatever you +# need to the 'gradient' part, for example cap them, etc. +capped_grads_and_vars = [(MyCapper(gv[0]), gv[1])) for gv in grads_and_vars] + +# Ask the optimizer to apply the capped gradients. +opt.apply_gradients(capped_grads_and_vars) +``` + +- - - + +#### tf.train.Optimizer.__init__(use_locking, name) {#Optimizer.__init__} + +Create a new Optimizer. + +This must be called by the constructors of subclasses. + +##### Args: + + +* <b>use_locking</b>: Bool. If True apply use locks to prevent concurrent updates + to variables. +* <b>name</b>: A non-empty string. The name to use for accumulators created + for the optimizer. + +##### Raises: + + +* <b>ValueError</b>: if name is malformed. + + + +- - - + +#### tf.train.Optimizer.minimize(loss, global_step=None, var_list=None, gate_gradients=1, name=None) {#Optimizer.minimize} + +Add operations to minimize 'loss' by updating 'var_list'. + +This method simply combines calls compute_gradients() and +apply_gradients(). If you want to process the gradient before applying them +call compute_gradients() and apply_gradients() explicitly instead of using +this function. + +##### Args: + + +* <b>loss</b>: A Tensor containing the value to minimize. +* <b>global_step</b>: Optional Variable to increment by one after the + variables have been updated. +* <b>var_list</b>: Optional list of variables.Variable to update to minimize + 'loss'. Defaults to the list of variables collected in the graph + under the key GraphKeys.TRAINABLE_VARIABLES. +* <b>gate_gradients</b>: How to gate the computation of gradients. Can be + GATE_NONE, GATE_OP, or GATE_GRAPH. +* <b>name</b>: Optional name for the returned operation. + +##### Returns: + + An Operation that updates the variables in 'var_list'. If 'global_step' + was not None, that operation also increments global_step. + +##### Raises: + + +* <b>ValueError</b>: if some of the variables are not variables.Variable objects. + + +- - - + +#### tf.train.Optimizer.compute_gradients(loss, var_list=None, gate_gradients=1) {#Optimizer.compute_gradients} + +Compute gradients of "loss" for the variables in "var_list". + +This is the first part of minimize(). It returns a list +of (gradient, variable) pairs where "gradient" is the gradient +for "variable". Note that "gradient" can be a Tensor, a +IndexedSlices, or None if there is no gradient for the +given variable. + +##### Args: + + +* <b>loss</b>: A Tensor containing the value to minimize. +* <b>var_list</b>: Optional list of variables.Variable to update to minimize + "loss". Defaults to the list of variables collected in the graph + under the key GraphKey.TRAINABLE_VARIABLES. +* <b>gate_gradients</b>: How to gate the computation of gradients. Can be + GATE_NONE, GATE_OP, or GATE_GRAPH. + +##### Returns: + + A list of (gradient, variable) pairs. + +##### Raises: + + +* <b>TypeError</b>: If var_list contains anything else than variables.Variable. +* <b>ValueError</b>: If some arguments are invalid. + + +- - - + +#### tf.train.Optimizer.apply_gradients(grads_and_vars, global_step=None, name=None) {#Optimizer.apply_gradients} + +Apply gradients to variables. + +This is the second part of minimize(). It returns an Operation that +applies gradients. + +##### Args: + + +* <b>grads_and_vars</b>: List of (gradient, variable) pairs as returned by + compute_gradients(). +* <b>global_step</b>: Optional Variable to increment by one after the + variables have been updated. +* <b>name</b>: Optional name for the returned operation. Default to the + name passed to the Optimizer constructor. + +##### Returns: + + An Operation that applies the specified gradients. If 'global_step' + was not None, that operation also increments global_step. + +##### Raises: + + +* <b>TypeError</b>: if grads_and_vars is malformed. + + + +### Gating Gradients <div class="md-anchor" id="AUTOGENERATED-gating-gradients">{#AUTOGENERATED-gating-gradients}</div> + +Both `minimize()` and `compute_gradients()` accept a `gate_gradient` argument +that controls the degree of parallelism during the application of the +gradients. + +The possible values are: `GATE_NONE`, `GATE_OP`, and `GATE_GRAPH`. + +<b>GATE_NONE</b>: Compute and apply gradients in parallel. This provides the +maximum parallelism in execution, at the cost of some non-reproducibility in +the results. For example the two gradients of MatMul depend on the input +values: With `GATE_NONE` one of the gradients could be applied to one of the +inputs _before_ the other gradient is computed resulting in non-reproducible +results. + +<b>GATE_OP</b>: For each Op, make sure all gradients are computed before they +are used. This prevents race conditions for Ops that generate gradients for +multiple inputs where the gradients depend on the inputs. + +<b>GATE_GRAPH</b>: Make sure all gradients for all variables are computed +before any one of them is used. This provides the least parallelism but can +be useful if you want to process all gradients before applying any of them. + +### Slots <div class="md-anchor" id="AUTOGENERATED-slots">{#AUTOGENERATED-slots}</div> + +Some optimizer subclasses, such as `MomentumOptimizer` and `AdagradOptimizer` +allocate and manage additional variables associated with the variables to +train. These are called <i>Slots</i>. Slots have names and you can ask the +optimizer for the names of the slots that it uses. Once you have a slot name +you can ask the optimizer for the variable it created to hold the slot value. + +This can be useful if you want to log debug a training algorithm, report stats +about the slots, etc. + +- - - + +#### tf.train.Optimizer.get_slot_names() {#Optimizer.get_slot_names} + +Return a list of the names of slots created by the Optimizer. + +See get_slot(). + +##### Returns: + + A list of strings. + + +- - - + +#### tf.train.Optimizer.get_slot(var, name) {#Optimizer.get_slot} + +Return a slot named "name" created for "var" by the Optimizer. + +Some Optimizer subclasses use additional variables. For example +Momentum and Adagrad use variables to accumulate updates. This method +gives access to these Variables if for some reason you need them. + +Use get_slot_names() to get the list of slot names created by the Optimizer. + +##### Args: + + +* <b>var</b>: A variable passed to minimize() or apply_gradients(). +* <b>name</b>: A string. + +##### Returns: + + The Variable for the slot if it was created, None otherwise. + + + + +- - - + +### class tf.train.GradientDescentOptimizer <div class="md-anchor" id="GradientDescentOptimizer">{#GradientDescentOptimizer}</div> + +Optimizer that implements the gradient descent algorithm. + +- - - + +#### tf.train.GradientDescentOptimizer.__init__(learning_rate, use_locking=False, name='GradientDescent') {#GradientDescentOptimizer.__init__} + +Construct a new gradient descent optimizer. + +##### Args: + + +* <b>learning_rate</b>: A Tensor or a floating point value. The learning + rate to use. +* <b>use_locking</b>: If True use locks for update operation.s +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "GradientDescent". + + + +- - - + +### class tf.train.AdagradOptimizer <div class="md-anchor" id="AdagradOptimizer">{#AdagradOptimizer}</div> + +Optimizer that implements the Adagrad algorithm. + +- - - + +#### tf.train.AdagradOptimizer.__init__(learning_rate, initial_accumulator_value=0.1, use_locking=False, name='Adagrad') {#AdagradOptimizer.__init__} + +Construct a new Adagrad optimizer. + +##### Args: + + +* <b>learning_rate</b>: A `Tensor` or a floating point value. The learning rate. +* <b>initial_accumulator_value</b>: A floating point value. + Starting value for the accumulators, must be positive. +* <b>use_locking</b>: If `True` use locks for update operations. +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "Adagrad". + +##### Raises: + + +* <b>ValueError</b>: If the initial_accumulator_value is invalid. + + + +- - - + +### class tf.train.MomentumOptimizer <div class="md-anchor" id="MomentumOptimizer">{#MomentumOptimizer}</div> + +Optimizer that implements the Momentum algorithm. + +- - - + +#### tf.train.MomentumOptimizer.__init__(learning_rate, momentum, use_locking=False, name='Momentum') {#MomentumOptimizer.__init__} + +Construct a new Momentum optimizer. + +##### Args: + + +* <b>learning_rate</b>: A `Tensor` or a floating point value. The learning rate. +* <b>momentum</b>: A `Tensor` or a floating point value. The momentum. +* <b>use_locking</b>: If `True` use locks for update operations. +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "Momentum". + + + +- - - + +### class tf.train.AdamOptimizer <div class="md-anchor" id="AdamOptimizer">{#AdamOptimizer}</div> + +Optimizer that implements the Adam algorithm. + +- - - + +#### tf.train.AdamOptimizer.__init__(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, use_locking=False, name='Adam') {#AdamOptimizer.__init__} + +Construct a new Adam optimizer. + +Implementation is based on: http://arxiv.org/pdf/1412.6980v7.pdf + +Initialization: + +``` +m_0 <- 0 (Initialize initial 1st moment vector) +v_0 <- 0 (Initialize initial 2nd moment vector) +t <- 0 (Initialize timestep) +``` + +The update rule for `variable` with gradient `g` uses an optimization +described at the end of section2 of the paper: + +``` +t <- t + 1 +lr_t <- learning_rate * sqrt(1 - beta2^t) / (1 - beta1^t) + +m_t <- beta1 * m_{t-1} + (1 - beta1) * g +v_t <- beta2 * v_{t-1} + (1 - beta2) * g * g +variable <- variable - lr_t * m_t / (sqrt(v_t) + epsilon) +``` + +The default value of 1e-8 for epsilon might not be a good default in +general. For example, when training an Inception network on ImageNet a +current good choice is 1.0 or 0.1. + +##### Args: + + +* <b>learning_rate</b>: A Tensor or a floating point value. The learning rate. +* <b>beta1</b>: A float value or a constant float tensor. + The exponential decay rate for the 1st moment estimates. +* <b>beta2</b>: A float value or a constant float tensor. + The exponential decay rate for the 2st moment estimates. +* <b>epsilon</b>: A small constant for numerical stability. +* <b>use_locking</b>: If True use locks for update operation.s +* <b>name</b>: Optional name for the operations created when applying gradients. + Defaults to "Adam". + + + +- - - + +### class tf.train.FtrlOptimizer <div class="md-anchor" id="FtrlOptimizer">{#FtrlOptimizer}</div> + +Optimizer that implements the FTRL algorithm. + +- - - + +#### tf.train.FtrlOptimizer.__init__(learning_rate, learning_rate_power=-0.5, initial_accumulator_value=0.1, l1_regularization_strength=0.0, l2_regularization_strength=0.0, use_locking=False, name='Ftrl') {#FtrlOptimizer.__init__} + +Construct a new FTRL optimizer. + +The Ftrl-proximal algorithm, abbreviated for Follow-the-regularized-leader, +is described in the paper [Ad Click Prediction: a View from the Trenches]( +https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf). + +It can give a good performance vs. sparsity tradeoff. + +Ftrl-proximal uses its own global base learning rate and can behave like +Adagrad with `learning_rate_power=-0.5`, or like gradient descent with +`learning_rate_power=0.0`. + +The effective learning rate is adjusted per parameter, relative to this +base learning rate as: + +``` +effective_learning_rate_i = (learning_rate / + pow(k + summed_squared_gradients_for_i, learning_rate_power)); +``` + +where k is the small constant `initial_accumulator_value`. + +Note that the real regularization coefficient of `|w|^2` for objective +function is `1 / lambda_2` if specifying `l2 = lambda_2` as argument when +using this function. + +##### Args: + + +* <b>learning_rate</b>: A float value or a constant float `Tensor`. +* <b>learning_rate_power</b>: A float value, must be less or equal to zero. +* <b>initial_accumulator_value</b>: The starting value for accumulators. + Only positive values are allowed. +* <b>l1_regularization_strength</b>: A float value, must be greater than or + equal to zero. +* <b>l2_regularization_strength</b>: A float value, must be greater than or + equal to zero. +* <b>use_locking</b>: If `True` use locks for update operations. +* <b>name</b>: Optional name prefix for the operations created when applying + gradients. Defaults to "Ftrl". + +##### Raises: + + +* <b>ValueError</b>: if one of the arguments is invalid. + + + +- - - + +### class tf.train.RMSPropOptimizer <div class="md-anchor" id="RMSPropOptimizer">{#RMSPropOptimizer}</div> + +Optimizer that implements the RMSProp algorithm. + +- - - + +#### tf.train.RMSPropOptimizer.__init__(learning_rate, decay, momentum=0.0, epsilon=1e-10, use_locking=False, name='RMSProp') {#RMSPropOptimizer.__init__} + +Construct a new RMSProp optimizer. + +##### Args: + + +* <b>learning_rate</b>: A Tensor or a floating point value. The learning rate. +* <b>decay</b>: discounting factor for the history/coming gradient +* <b>momentum</b>: a scalar tensor. +* <b>epsilon</b>: small value to avoid zero denominator. +* <b>use_locking</b>: If True use locks for update operation. +* <b>name</b>: Optional name prefic for the operations created when applying + gradients. Defaults to "RMSProp". + + + + +## Gradient Computation. <div class="md-anchor" id="AUTOGENERATED-gradient-computation.">{#AUTOGENERATED-gradient-computation.}</div> + +TensorFlow provides functions to compute the derivatives for a given +TensorFlow computation graph, adding operations to the graph. The +optimizer classes automatically compute derivatives on your graph, but +creators of new Optimizers or expert users can call the lower-level +functions below. + +- - - + +### tf.gradients(ys, xs, grad_ys=None, name='gradients', colocate_gradients_with_ops=False, gate_gradients=False, aggregation_method=None) <div class="md-anchor" id="gradients">{#gradients}</div> + +Constructs symbolic partial derivatives of `ys` w.r.t. x in `xs`. + +`ys` and `xs` are each a `Tensor` or a list of tensors. `grad_ys` +is a list of `Tensor`, holding the gradients received by the +`ys`. The list must be the same length as `ys`. + +`gradients()` adds ops to the graph to output the partial +derivatives of `ys` with respect to `xs`. It returns a list of +`Tensor` of length `len(xs)` where each tensor is the `sum(dy/dx)` +for y in `ys`. + +`grad_ys` is a list of tensors of the same length as `ys` that holds +the initial gradients for each y in `ys`. When `grad_ys` is None, +we fill in a tensor of '1's of the shape of y for each y in `ys`. A +user can provide their own initial 'grad_ys` to compute the +derivatives using a different initial gradient for each y (e.g., if +one wanted to weight the gradient differently for each value in +each y). + +##### Args: + + +* <b>ys</b>: A `Tensor` or list of tensors to be differentiated. +* <b>xs</b>: A `Tensor` or list of tensors to be used for differentiation. +* <b>grad_ys</b>: Optional. A `Tensor` or list of tensors the same size as + `ys` and holding the gradients computed for each y in `ys`. +* <b>name</b>: Optional name to use for grouping all the gradient ops together. + defaults to 'gradients'. +* <b>colocate_gradients_with_ops</b>: If True, try colocating gradients with + the corresponding op. +* <b>gate_gradients</b>: If True, add a tuple around the gradients returned + for an operations. This avoids some race conditions. +* <b>aggregation_method</b>: Specifies the method used to combine gradient terms. + Accepted values are constants defined in the class `AggregationMethod`. + +##### Returns: + + A list of `sum(dy/dx)` for each x in `xs`. + +##### Raises: + + +* <b>LookupError</b>: if one of the operations between `x` and `y` does not + have a registered gradient function. +* <b>ValueError</b>: if the arguments are invalid. + + +- - - + +### class tf.AggregationMethod <div class="md-anchor" id="AggregationMethod">{#AggregationMethod}</div> + +A class listing aggregation methods used to combine gradients. + +Computing partial derivatives can require aggregating gradient +contributions. This class lists the various methods that can +be used to combine gradients in the graph: + +* `ADD_N`: All of the gradient terms are summed as part of one + operation using the "AddN" op. It has the property that all + gradients must be ready before any aggregation is performed. +* `DEFAULT`: The system-chosen default aggregation method. + + +- - - + +### tf.stop_gradient(input, name=None) <div class="md-anchor" id="stop_gradient">{#stop_gradient}</div> + +Stops gradient computation. + +When executed in a graph, this op outputs its input tensor as-is. + +When building ops to compute gradients, this op prevents the contribution of +its inputs to be taken into account. Normally, the gradient generator adds ops +to a graph to compute the derivatives of a specified 'loss' by recursively +finding out inputs that contributed to its computation. If you insert this op +in the graph it inputs are masked from the gradient generator. They are not +taken into account for computing gradients. + +This is useful any time you want to compute a value with TensorFlow but need +to pretend that the value was a constant. Some examples include: + +* The *EM* algorithm where the *M-step* should not involve backpropagation + through the output of the *E-step*. +* Contrastive divergence training of Boltzmann machines where, when + differentiating the energy function, the training must not backpropagate + through the graph that generated the samples from the model. +* Adversarial training, where no backprop should happen through the adversarial + example generation process. + +##### Args: + + +* <b>input</b>: A `Tensor`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A `Tensor`. Has the same type as `input`. + + + + +## Gradient Clipping <div class="md-anchor" id="AUTOGENERATED-gradient-clipping">{#AUTOGENERATED-gradient-clipping}</div> + +TensorFlow provides several operations that you can use to add clipping +functions to your graph. You can use these functions to perform general data +clipping, but they're particularly useful for handling exploding or vanishing +gradients. + +- - - + +### tf.clip_by_value(t, clip_value_min, clip_value_max, name=None) <div class="md-anchor" id="clip_by_value">{#clip_by_value}</div> + +Clips tensor values to a specified min and max. + +Given a tensor `t`, this operation returns a tensor of the same type and +shape as `t` with its values clipped to `clip_value_min` and `clip_value_max`. +Any values less than `clip_value_min` are set to `clip_value_min`. Any values +greater than `clip_value_max` are set to `clip_value_max`. + +##### Args: + + +* <b>t</b>: A `Tensor`. +* <b>clip_value_min</b>: A 0-D (scalar) `Tensor`. The minimum value to clip by. +* <b>clip_value_max</b>: A 0-D (scalar) `Tensor`. The maximum value to clip by. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A clipped `Tensor`. + + +- - - + +### tf.clip_by_norm(t, clip_norm, name=None) <div class="md-anchor" id="clip_by_norm">{#clip_by_norm}</div> + +Clips tensor values to a maximum L2-norm. + +Given a tensor `t`, and a maximum clip value `clip_norm`, this operation +normalizes `t` so that its L2-norm is less than or equal to `clip_norm'. +Specifically, if the L2-norm is already less than or equal to `clip_norm`, +then `t` is not modified. If the L2-norm is greater than `clip_norm`, then +this operation returns a tensor of the same type and shape as `t` with its +values set to: + +`t * clip_norm / l2norm(t)` + +In this case, the L2-norm of the output tensor is `clip_norm`. + +This operation is typically used to clip gradients before applying them with +an optimizer. + +##### Args: + + +* <b>t</b>: A `Tensor`. +* <b>clip_norm</b>: A 0-D (scalar) `Tensor` > 0. A maximum clipping value. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A clipped `Tensor`. + + +- - - + +### tf.clip_by_average_norm(t, clip_norm, name=None) <div class="md-anchor" id="clip_by_average_norm">{#clip_by_average_norm}</div> + +Clips tensor values to a maximum average L2-norm. + +Given a tensor `t`, and a maximum clip value `clip_norm`, this operation +normalizes `t` so that its average L2-norm is less than or equal to +`clip_norm'. Specifically, if the average L2-norm is already less than or +equal to `clip_norm`, then `t` is not modified. If the average L2-norm is +greater than `clip_norm`, then this operation returns a tensor of the same +type and shape as `t` with its values set to: + +`t * clip_norm / l2norm_avg(t)` + +In this case, the average L2-norm of the output tensor is `clip_norm`. + +This operation is typically used to clip gradients before applying them with +an optimizer. + +##### Args: + + +* <b>t</b>: A `Tensor`. +* <b>clip_norm</b>: A 0-D (scalar) `Tensor` > 0. A maximum clipping value. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A clipped `Tensor`. + + +- - - + +### tf.clip_by_global_norm(t_list, clip_norm, use_norm=None, name=None) <div class="md-anchor" id="clip_by_global_norm">{#clip_by_global_norm}</div> + +Clips values of multiple tensors by the ratio of the sum of their norms. + +Given a tuple or list of tensors `t_list`, and a clipping ratio `clip_norm`, +this operation returns a list of clipped tensors `list_clipped` +and the global norm (`global_norm`) of all tensors in `t_list`. Optionally, +if you've already computed the global norm for `t_list`, you can specify +the global norm with `use_norm`. + +To perform the clipping, the values t_list[i] are set to: + +`t_list[i] * clip_norm / max(global_norm, clip_norm)` + +where: + +`global_norm = sqrt(sum([l2norm(t)**2 for t in t_list]))` + +If `clip_norm > global_norm` then the entries in `t_list` remain as they are, +otherwise they're all shrunk by the global ratio. + +Any of the entries of `t_list` that are of type None are ignored. + +This is the correct way to perform gradient clipping (for example, see +R. Pascanu, T. Mikolov, and Y. Bengio, "On the difficulty of training +Recurrent Neural Networks". http://arxiv.org/abs/1211.5063) + +However, it is slower than `clip_by_norm()` because all the parameters must be +ready before the clipping operation can be performed. + +##### Args: + + +* <b>t_list</b>: A tuple or list of mixed `Tensors`, `IndexedSlices`, or None. +* <b>clip_norm</b>: A 0-D (scalar) `Tensor` > 0. The clipping ratio. +* <b>use_norm</b>: A 0-D (scalar) `Tensor` of type `float` (optional). The global + norm to use. If not provided, `global_norm()` is used to compute the norm. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + +* <b>list_clipped</b>: A list of `Tensors` of the same type as `list_t`. +* <b>global_norm</b>: A 0-D (scalar) `Tensor` representing the global norm. + +##### Raises: + + +* <b>TypeError</b>: If `t_list` is not a sequence. + + +- - - + +### tf.global_norm(t_list, name=None) <div class="md-anchor" id="global_norm">{#global_norm}</div> + +Computes the global norm of multiple tensors. + +Given a tuple or list of tensors `t_list`, this operation returns the +global norm of the elements in all tensors in `t_list`. The global norm is +computed as: + +`global_norm = sqrt(sum([l2norm(t)**2 for t in t_list]))` + +Any entries in `t_list` that are of type None are ignored. + +##### Args: + + +* <b>t_list</b>: A tuple or list of mixed `Tensors`, `IndexedSlices`, or None. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A 0-D (scalar) `Tensor` of type `float`. + +##### Raises: + + +* <b>TypeError</b>: If `t_list` is not a sequence. + + + +## Decaying the learning rate. <div class="md-anchor" id="AUTOGENERATED-decaying-the-learning-rate.">{#AUTOGENERATED-decaying-the-learning-rate.}</div> +- - - + +### tf.train.exponential_decay(learning_rate, global_step, decay_steps, decay_rate, staircase=False, name=None) <div class="md-anchor" id="exponential_decay">{#exponential_decay}</div> + +Applies exponential decay to the learning rate. + +When training a model, it is often recommended to lower the learning rate as +the training progresses. This function applies an exponential decay function +to a provided initial learning rate. It requires a `global_step` value to +compute the decayed learning rate. You can just pass a TensorFlow variable +that you increment at each training step. + +The function returns the decayed learning rate. It is computed as: + +```python +decayed_learning_rate = learning_rate * + decay_rate ^ (global_step / decay_steps) +``` + +If the argument `staircase` is `True`, then `global_step /decay_steps` is an +integer division and the decayed learning rate follows a staircase function. + +Example: decay every 100000 steps with a base of 0.96: + +```python +... +global_step = tf.Variable(0, trainable=False) +starter_learning_rate = 0.1 +learning_rate = tf.exponential_decay(starter_learning_rate, global_step, + 100000, 0.96, staircase=True) +optimizer = tf.GradientDescent(learning_rate) +# Passing global_step to minimize() will increment it at each step. +optimizer.minimize(...my loss..., global_step=global_step) +``` + +##### Args: + + +* <b>learning_rate</b>: A scalar `float32` or `float64` `Tensor` or a + Python number. The initial learning rate. +* <b>global_step</b>: A scalar `int32` or `int64` `Tensor` or a Python number. + Global step to use for the decay computation. Must not be negative. +* <b>decay_steps</b>: A scalar `int32` or `int64` `Tensor` or a Python number. + Must be positive. See the decay computation above. +* <b>decay_rate</b>: A scalar `float32` or `float64` `Tensor` or a + Python number. The decay rate. +* <b>staircase</b>: Boolean. It `True` decay the learning rate at discrete intervals. +* <b>name</b>: string. Optional name of the operation. Defaults to 'ExponentialDecay' + +##### Returns: + + A scalar `Tensor` of the same type as `learning_rate`. The decayed + learning rate. + + + +## Moving Averages. <div class="md-anchor" id="AUTOGENERATED-moving-averages.">{#AUTOGENERATED-moving-averages.}</div> + +Some training algorithms, such as GradientDescent and Momentum often benefit +from maintaining a moving average of variables during optimization. Using the +moving averages for evaluations often improve results significantly. + +- - - + +### class tf.train.ExponentialMovingAverage <div class="md-anchor" id="ExponentialMovingAverage">{#ExponentialMovingAverage}</div> + +Maintains moving averages of variables by employing and exponential decay. + +When training a model, it is often beneficial to maintain moving averages of +the trained parameters. Evaluations that use averaged parameters sometimes +produce significantly better results than the final trained values. + +The `apply()` method adds shadow copies of trained variables and add ops that +maintain a moving average of the trained variables in their shadow copies. +It is used when building the training model. The ops that maintain moving +averages are typically run after each training step. +The `average()` and `average_name()` methods give access to the shadow +variables and their names. They are useful when building an evaluation +model, or when restoring a model from a checkpoint file. They help use the +moving averages in place of the last trained values for evaluations. + +The moving averages are computed using exponential decay. You specify the +decay value when creating the `ExponentialMovingAverage` object. The shadow +variables are initialized with the same initial values as the trained +variables. When you run the ops to maintain the moving averages, each +shadow variable is updated with the formula: + + `shadow_variable -= (1 - decay) * (shadow_variable - variable)` + +This is mathematically equivalent to the classic formula below, but the use +of an `assign_sub` op (the `"-="` in the formula) allows concurrent lockless +updates to the variables: + + `shadow_variable = decay * shadow_variable + (1 - decay) * variable` + +Reasonable values for `decay` are close to 1.0, typically in the +multiple-nines range: 0.999, 0.9999, etc. + +Example usage when creating a training model: + +```python +# Create variables. +var0 = tf.Variable(...) +var1 = tf.Variable(...) +# ... use the variables to build a training model... +... +# Create an op that applies the optimizer. This is what we usually +# would use as a training op. +opt_op = opt.minimize(my_loss, [var0, var1]) + +# Create an ExponentialMovingAverage object +ema = tf.train.ExponentialMovingAverage(decay=0.9999) + +# Create the shadow variables, and add ops to maintain moving averages +# of var0 and var1. +maintain_averages_op = ema.apply([var0, var1]) + +# Create an op that will update the moving averages after each training +# step. This is what we will use in place of the usuall trainig op. +with tf.control_dependencies([opt_op]): + training_op = tf.group(maintain_averages_op) + +...train the model by running training_op... +``` + +There are two ways to use the moving averages for evaluations: + +* Build a model that uses the shadow variables instead of the variables. + For this, use the `average()` method which returns the shadow variable + for a given variable. +* Build a model normally but load the checkpoint files to evaluate by using + the shadow variable names. For this use the `average_name()` method. See + the [Saver class](train.md#Saver) for more information on restoring saved + variables. + +Example of restoring the shadow variable values: + +```python +# Create a Saver that loads variables from their saved shadow values. +shadow_var0_name = ema.average_name(var0) +shadow_var1_name = ema.average_name(var1) +saver = tf.train.Saver({shadow_var0_name: var0, shadow_var1_name: var1}) +saver.restore(...checkpoint filename...) +# var0 and var1 now hold the moving average values +``` + +- - - + +#### tf.train.ExponentialMovingAverage.__init__(decay, num_updates=None, name='ExponentialMovingAverage') {#ExponentialMovingAverage.__init__} + +Creates a new ExponentialMovingAverage object. + +The `Apply()` method has to be called to create shadow variables and add +ops to maintain moving averages. + +The optional `num_updates` parameter allows one to tweak the decay rate +dynamically. . It is typical to pass the count of training steps, usually +kept in a variable that is incremented at each step, in which case the +decay rate is lower at the start of training. This makes moving averages +move faster. If passed, the actual decay rate used is: + + `min(decay, (1 + num_updates) / (10 + num_updates))` + +##### Args: + + +* <b>decay</b>: Float. The decay to use. +* <b>num_updates</b>: Optional count of number of updates applied to variables. +* <b>name</b>: String. Optional prefix name to use for the name of ops added in + `Apply()`. + + +- - - + +#### tf.train.ExponentialMovingAverage.apply(var_list=None) {#ExponentialMovingAverage.apply} + +Maintains moving averages of variables. + +`var_list` must be a list of `Variable` or `Tensor` objects. This method +creates shadow variables for all elements of `var_list`. Shadow variables +for `Variable` objects are initialized to the variable's initial value. +For `Tensor` objects, the shadow variables are initialized to 0. + +shadow variables are created with `trainable=False` and added to the +`GraphKeys.ALL_VARIABLES` collection. They will be returned by calls to +`tf.all_variables()`. + +Returns an op that updates all shadow variables as described above. + +Note that `apply()` can be called multiple times with different lists of +variables. + +##### Args: + + +* <b>var_list</b>: A list of Variable or Tensor objects. The variables + and Tensors must be of types float32 or float64. + +##### Returns: + + An Operation that updates the moving averages. + +##### Raises: + + +* <b>TypeError</b>: If the arguments are not all float32 or float64. +* <b>ValueError</b>: If the moving average of one of the variables is already + being computed. + + +- - - + +#### tf.train.ExponentialMovingAverage.average_name(var) {#ExponentialMovingAverage.average_name} + +Returns the name of the `Variable` holding the average for `var`. + +The typical scenario for `ExponentialMovingAverage` is to compute moving +averages of variables during training, and restore the variables from the +computed moving averages during evaluations. + +To restore variables, you have to know the name of the shadow variables. +That name and the original variable can then be passed to a `Saver()` object +to restore the variable from the moving average value with: + `saver = tf.train.Saver({ema.average_name(var): var})` + +`average_name()` can be called whether or not `apply()` has been called. + +##### Args: + + +* <b>var</b>: A `Variable` object. + +##### Returns: + + A string: the name of the variable that will be used or was used + by the `ExponentialMovingAverage class` to hold the moving average of + `var`. + + +- - - + +#### tf.train.ExponentialMovingAverage.average(var) {#ExponentialMovingAverage.average} + +Returns the `Variable` holding the average of `var`. + +##### Args: + + +* <b>var</b>: A `Variable` object. + +##### Returns: + + A `Variable` object or `None` if the moving average of `var` + is not maintained.. + + + + +## Coordinator and QueueRunner. <div class="md-anchor" id="AUTOGENERATED-coordinator-and-queuerunner.">{#AUTOGENERATED-coordinator-and-queuerunner.}</div> + +See [Threading and Queues](../../how_tos/threading_and_queues/index.md) +for how to use threads and queues. For documentation on the Queue API, +see [Queues](../../api_docs/python/io_ops.md#queues). + +- - - + +### class tf.train.Coordinator <div class="md-anchor" id="Coordinator">{#Coordinator}</div> + +A coordinator for threads. + +This class implements a simple mechanism to coordinate the termination of a +set of threads. + +#### Usage: + +```python +# Create a coordinator. +coord = Coordinator() +# Start a number of threads, passing the coordinator to each of them. +...start thread 1...(coord, ...) +...start thread N...(coord, ...) +# Wait for all the threads to terminate. +coord.join(threads) +``` + +Any of the threads can call `coord.request_stop()` to ask for all the threads +to stop. To cooperate with the requests, each thread must check for +`coord.should_stop()` on a regular basis. `coord.should_stop()` returns +`True` as soon as `coord.request_stop()` has been called. + +A typical thread running with a Coordinator will do something like: + +```python +while not coord.should_stop(): + ...do some work... +``` + +#### Exception handling: + +A thread can report an exception to the Coordinator as part of the +`should_stop()` call. The exception will be re-raised from the +`coord.join()` call. + +Thread code: + +```python +try: + while not coord.should_stop(): + ...do some work... +except Exception, e: + coord.request_stop(e) +``` + +Main code: + +```python +try: + ... + coord = Coordinator() + # Start a number of threads, passing the coordinator to each of them. + ...start thread 1...(coord, ...) + ...start thread N...(coord, ...) + # Wait for all the threads to terminate. + coord.join(threads) +except Exception, e: + ...exception that was passed to coord.request_stop() +``` + +#### Grace period for stopping: + +After a thread has called `coord.request_stop()` the other threads have a +fixed time to stop, this is called the 'stop grace period' and defaults to 2 +minutes. If any of the threads is still alive after the grace period expires +`coord.join()` raises a RuntimeException reporting the laggards. + +``` +try: + ... + coord = Coordinator() + # Start a number of threads, passing the coordinator to each of them. + ...start thread 1...(coord, ...) + ...start thread N...(coord, ...) + # Wait for all the threads to terminate, give them 10s grace period + coord.join(threads, stop_grace_period_secs=10) +except RuntimeException: + ...one of the threads took more than 10s to stop after request_stop() + ...was called. +except Exception: + ...exception that was passed to coord.request_stop() +``` +- - - + +#### tf.train.Coordinator.__init__() {#Coordinator.__init__} + +Create a new Coordinator. + + +- - - + +#### tf.train.Coordinator.join(threads, stop_grace_period_secs=120) {#Coordinator.join} + +Wait for threads to terminate. + +Blocks until all 'threads' have terminated or request_stop() is called. + +After the threads stop, if an 'exc_info' was passed to request_stop, that +exception is re-reaised. + +Grace period handling: When request_stop() is called, threads are given +'stop_grace_period_secs' seconds to terminate. If any of them is still +alive after that period expires, a RuntimeError is raised. Note that if +an 'exc_info' was passed to request_stop() then it is raised instead of +that RuntimeError. + +##### Args: + + +* <b>threads</b>: List threading.Threads. The started threads to join. +* <b>stop_grace_period_secs</b>: Number of seconds given to threads to stop after + request_stop() has been called. + +##### Raises: + + +* <b>RuntimeError</b>: If any thread is still alive after request_stop() + is called and the grace period expires. + + +- - - + +#### tf.train.Coordinator.request_stop(ex=None) {#Coordinator.request_stop} + +Request that the threads stop. + +After this is called, calls to should_stop() will return True. + +##### Args: + + +* <b>ex</b>: Optional Exception, or Python 'exc_info' tuple as returned by + sys.exc_info(). If this is the first call to request_stop() the + corresponding exception is recorded and re-raised from join(). + + +- - - + +#### tf.train.Coordinator.should_stop() {#Coordinator.should_stop} + +Check if stop was requested. + +##### Returns: + + True if a stop was requested. + + +- - - + +#### tf.train.Coordinator.wait_for_stop(timeout=None) {#Coordinator.wait_for_stop} + +Wait till the Coordinator is told to stop. + +##### Args: + + +* <b>timeout</b>: float. Sleep for up to that many seconds waiting for + should_stop() to become True. + +##### Returns: + + True if the Coordinator is told stop, False if the timeout expired. + + + +- - - + +### class tf.train.QueueRunner <div class="md-anchor" id="QueueRunner">{#QueueRunner}</div> + +Holds a list of enqueue operations for a queue, each to be run in a thread. + +Queues are a convenient TensorFlow mechanism to compute tensors +asynchronously using multiple threads. For example in the canonical 'Input +Reader' setup one set of threads generates filenames in a queue; a second set +of threads read records from the files, processes them, and enqueues tensors +on a second queue; a third set of threads dequeues these input records to +construct batches and runs them through training operations. + +There are several delicate issues when running multiple threads that way: +closing the queues in sequence as the input is exhausted, correctly catching +and reporting exceptions, etc. + +The `QueueRunner`, combined with the `Coordinator`, helps handle these issues. +- - - + +#### tf.train.QueueRunner.__init__(queue, enqueue_ops) {#QueueRunner.__init__} + +Create a QueueRunner. + +On construction the `QueueRunner` adds an op to close the queue. That op +will be run if the enqueue ops raise exceptions. + +When you later call the `create_threads()` method, the `QueueRunner` will +create one thread for each op in `enqueue_ops`. Each thread will run its +enqueue op in parallel with the other threads. The enqueue ops do not have +to all be the same op, but it is expected that they all enqueue tensors in +`queue`. + +##### Args: + + +* <b>queue</b>: A `Queue`. +* <b>enqueue_ops</b>: List of enqueue ops to run in threads later. + + +- - - + +#### tf.train.QueueRunner.create_threads(sess, coord=None, daemon=False, start=False) {#QueueRunner.create_threads} + +Create threads to run the enqueue ops. + +This method requires a session in which the graph was launched. It creates +a list of threads, optionally starting them. There is one thread for each +op passed in `enqueue_ops`. + +The `coord` argument is an optional coordinator, that the threads will use +to terminate together and report exceptions. If a coordinator is given, +this method starts an additional thread to close the queue when the +coordinator requests a stop. + +This method may be called again as long as all threads from a previous call +have stopped. + +##### Args: + + +* <b>sess</b>: A `Session`. +* <b>coord</b>: Optional `Coordinator` object for reporting errors and checking + stop conditions. +* <b>daemon</b>: Boolean. If `True` make the threads daemon threads. +* <b>start</b>: Boolean. If `True` starts the threads. If `False` the + caller must call the `start()` method of the returned threads. + +##### Returns: + + A list of threads. + +##### Raises: + + +* <b>RuntimeError</b>: If threads from a previous call to `create_threads()` are + still running. + + +- - - + +#### tf.train.QueueRunner.exceptions_raised {#QueueRunner.exceptions_raised} + +Exceptions raised but not handled by the `QueueRunner` threads. + +Exceptions raised in queue runner threads are handled in one of two ways +depending on whether or not a `Coordinator` was passed to +`create_threads()`: + +* With a `Coordinator`, exceptions are reported to the coordinator and + forgotten by the `QueueRunner`. +* Without a `Coordinator`, exceptions are captured by the `QueueRunner` and + made available in this `exceptions_raised` property. + +##### Returns: + + A list of Python `Exception` objects. The list is empty if no exception + was captured. (No exceptions are captured when using a Coordinator.) + + +- - - + +### tf.train.add_queue_runner(qr, collection='queue_runners') <div class="md-anchor" id="add_queue_runner">{#add_queue_runner}</div> + +Adds a `QueueRunner` to a collection in the graph. + +When building a complex model that uses many queues it is often difficult to +gather all the queue runners that need to be run. This convenience function +allows you to add a queue runner to a well known collection in the graph. + +The companion method `start_queue_runners()` can be used to start threads for +all the collected queue runners. + +##### Args: + + +* <b>qr</b>: A `QueueRunner`. +* <b>collection</b>: A `GraphKey` specifying the graph collection to add + the queue runner to. Defaults to `GraphKeys.QUEUE_RUNNERS`. + + +- - - + +### tf.train.start_queue_runners(sess=None, coord=None, daemon=True, start=True, collection='queue_runners') <div class="md-anchor" id="start_queue_runners">{#start_queue_runners}</div> + +Starts all queue runners collected in the graph. + +This is a companion method to `add_queue_runner()`. It just starts +threads for all queue runners collected in the graph. It returns +the list of all threads. + +##### Args: + + +* <b>sess</b>: `Session` used to run the queue ops. Defaults to the + default session. +* <b>coord</b>: Optional `Coordinator` for coordinating the started threads. +* <b>daemon</b>: Whether the threads should be marked as `daemons`, meaning + they don't block program exit. +* <b>start</b>: Set to `False` to only create the threads, not start them. +* <b>collection</b>: A `GraphKey` specifying the graph collection to + get the queue runners from. Defaults to `GraphKeys.QUEUE_RUNNERS`. + +##### Returns: + + A list of threads. + + + +## Summary Operations. <div class="md-anchor" id="AUTOGENERATED-summary-operations.">{#AUTOGENERATED-summary-operations.}</div> + +The following ops output +[`Summary`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +protocol buffers as serialized string tensors. + +You can fetch the output of a summary op in a session, and pass it to a +[SummaryWriter](train.md#SummaryWriter) to append it to an event file. You can +then use TensorBoard to visualize the contents of the event files. See +[TensorBoard and Summaries](../../how_tos/summaries_and_tensorboard/index.md) +for more details. + +- - - + +### tf.scalar_summary(tags, values, collections=None, name=None) <div class="md-anchor" id="scalar_summary">{#scalar_summary}</div> + +Outputs a `Summary` protocol buffer with scalar values. + +The input `tags` and `values` must have the same shape. The generated +summary has a summary value for each tag-value pair in `tags` and `values`. + +##### Args: + + +* <b>tags</b>: A 1-D `string` `Tensor`. Tags for the summaries. +* <b>values</b>: A 1-D `float32` or `float64` Tensor. Values for the summaries. +* <b>collections</b>: Optional list of graph collections keys. The new summary op is + added to these collections. Defaults to `[GraphKeys.SUMMARIES]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer. + + +- - - + +### tf.image_summary(tag, tensor, max_images=None, collections=None, name=None) <div class="md-anchor" id="image_summary">{#image_summary}</div> + +Outputs a `Summary` protocol buffer with images. + +The summary has up to `max_images` summary values containing images. The +images are built from `tensor` which must be 4-D with shape `[batch_size, +height, width, channels]` and where `channels` can be: + +* 1: `tensor` is interpreted as Grayscale. +* 3: `tensor` is interpreted as RGB. +* 4: `tensor` is interpreted as RGBA. + +The images have the same number of channels as the input tensor. Their values +are normalized, one image at a time, to fit in the range `[0, 255]`. The +op uses two different normalization algorithms: + +* If the input values are all positive, they are rescaled so the largest one + is 255. + +* If any input value is negative, the values are shifted so input value 0.0 + is at 127. They are then rescaled so that either the smallest value is 0, + or the largest one is 255. + +The `tag` argument is a scalar `Tensor` of type `string`. It is used to +build the `tag` of the summary values: + +* If `max_images` is 1, the summary value tag is '*tag*/image'. +* If `max_images` is greater than 1, the summary value tags are + generated sequentially as '*tag*/image/0', '*tag*/image/1', etc. + +##### Args: + + +* <b>tag</b>: A scalar `Tensor` of type `string`. Used to build the `tag` + of the summary values. +* <b>tensor</b>: A 4-D `float32` `Tensor` of shape `[batch_size, height, width, + channels]` where `channels` is 1, 3, or 4. +* <b>max_images</b>: Max number of batch elements to generate images for. +* <b>collections</b>: Optional list of ops.GraphKeys. The collections to add the + summary to. Defaults to [ops.GraphKeys.SUMMARIES] +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer. + + +- - - + +### tf.histogram_summary(tag, values, collections=None, name=None) <div class="md-anchor" id="histogram_summary">{#histogram_summary}</div> + +Outputs a `Summary` protocol buffer with a histogram. + +The generated +[`Summary`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +has one summary value containing a histogram for `values`. + +This op reports an `OutOfRange` error if any value is not finite. + +##### Args: + + +* <b>tag</b>: A `string` `Tensor`. 0-D. Tag to use for the summary value. +* <b>values</b>: A `float32` `Tensor`. Any shape. Values to use to build the + histogram. +* <b>collections</b>: Optional list of graph collections keys. The new summary op is + added to these collections. Defaults to `[GraphKeys.SUMMARIES]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer. + + +- - - + +### tf.nn.zero_fraction(value, name=None) <div class="md-anchor" id="zero_fraction">{#zero_fraction}</div> + +Returns the fraction of zeros in `value`. + +If `value` is empty, the result is `nan`. + +This is useful in summaries to measure and report sparsity. For example, + + z = tf.Relu(...) + summ = tf.scalar_summary('sparsity', tf.zero_fraction(z)) + +##### Args: + + +* <b>value</b>: A tensor of numeric type. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + The fraction of zeros in `value`, with type `float32`. + + + +- - - + +### tf.merge_summary(inputs, collections=None, name=None) <div class="md-anchor" id="merge_summary">{#merge_summary}</div> + +Merges summaries. + +This op creates a +[`Summary`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +protocol buffer that contains the union of all the values in the input +summaries. + +When the Op is run, it reports an `InvalidArgument` error if multiple values +in the summaries to merge use the same tag. + +##### Args: + + +* <b>inputs</b>: A list of `string` `Tensor` objects containing serialized `Summary` + protocol buffers. +* <b>collections</b>: Optional list of graph collections keys. The new summary op is + added to these collections. Defaults to `[GraphKeys.SUMMARIES]`. +* <b>name</b>: A name for the operation (optional). + +##### Returns: + + A scalar `Tensor` of type `string`. The serialized `Summary` protocol + buffer resulting from the merging. + + +- - - + +### tf.merge_all_summaries(key='summaries') <div class="md-anchor" id="merge_all_summaries">{#merge_all_summaries}</div> + +Merges all summaries collected in the default graph. + +##### Args: + + +* <b>key</b>: `GraphKey` used to collect the summaries. Defaults to + `GraphKeys.SUMMARIES`. + +##### Returns: + + If no summaries were collected, returns None. Otherwise returns a scalar + `Tensor` of type`string` containing the serialized `Summary` protocol + buffer resulting from the merging. + + + +## Adding Summaries to Event Files. <div class="md-anchor" id="AUTOGENERATED-adding-summaries-to-event-files.">{#AUTOGENERATED-adding-summaries-to-event-files.}</div> + +See [Summaries and +TensorBoard](../../how_tos/summaries_and_tensorboard/index.md) for an +overview of summaries, event files, and visualization in TensorBoard. + +- - - + +### class tf.train.SummaryWriter <div class="md-anchor" id="SummaryWriter">{#SummaryWriter}</div> + +Writes `Summary` protocol buffers to event files. + +The `SummaryWriter` class provides a mechanism to create an event file in a +given directory and add summaries and events to it. The class updates the +file contents asynchronously. This allows a training program to call methods +to add data to the file directly from the training loop, without slowing down +training. + +- - - + +#### tf.train.SummaryWriter.__init__(logdir, graph_def=None, max_queue=10, flush_secs=120) {#SummaryWriter.__init__} + +Creates a `SummaryWriter` and an event file. + +On construction the summary writer creates a new event file in `logdir`. +This event file will contain `Event` protocol buffers constructed when you +call one of the following functions: `add_summary()`, `add_event()`, or +`add_graph()`. + +If you pass a `graph_def` protocol buffer to the constructor it is added to +the event file. (This is equivalent to calling `add_graph()` later). + +TensorBoard will pick the graph from the file and display it graphically so +you can interactively explore the graph you built. You will usually pass +the graph from the session in which you launched it: + +```python +...create a graph... +# Launch the graph in a session. +sess = tf.Session() +# Create a summary writer, add the 'graph_def' to the event file. +writer = tf.train.SummaryWriter(<some-directory>, sess.graph_def) +``` + +The other arguments to the constructor control the asynchronous writes to +the event file: + +* `flush_secs`: How often, in seconds, to flush the added summaries + and events to disk. +* `max_queue`: Maximum number of summaries or events pending to be + written to disk before one of the 'add' calls block. + +##### Args: + + +* <b>logdir</b>: A string. Directory where event file will be written. +* <b>graph_def</b>: A `GraphDef` protocol buffer. +* <b>max_queue</b>: Integer. Size of the queue for pending events and summaries. +* <b>flush_secs</b>: Number. How often, in seconds, to flush the + pending events and summaries to disk. + + + +- - - + +#### tf.train.SummaryWriter.add_summary(summary, global_step=None) {#SummaryWriter.add_summary} + +Adds a `Summary` protocol buffer to the event file. + +This method wraps the provided summary in an `Event` procotol buffer +and adds it to the event file. + +You can pass the output of any summary op, as-is, to this function. You +can also pass a `Summary` procotol buffer that you manufacture with your +own data. This is commonly done to report evaluation results in event +files. + +##### Args: + + +* <b>summary</b>: A `Summary` protocol buffer, optionally serialized as a string. +* <b>global_step</b>: Number. Optional global step value to record with the + summary. + + +- - - + +#### tf.train.SummaryWriter.add_event(event) {#SummaryWriter.add_event} + +Adds an event to the event file. + +##### Args: + + +* <b>event</b>: An `Event` protocol buffer. + + +- - - + +#### tf.train.SummaryWriter.add_graph(graph_def, global_step=None) {#SummaryWriter.add_graph} + +Adds a `GraphDef` protocol buffer to the event file. + +The graph described by the protocol buffer will be displayed by +TensorBoard. Most users pass a graph in the constructor instead. + +##### Args: + + +* <b>graph_def</b>: A `GraphDef` protocol buffer. +* <b>global_step</b>: Number. Optional global step counter to record with the + graph. + + + +- - - + +#### tf.train.SummaryWriter.flush() {#SummaryWriter.flush} + +Flushes the event file to disk. + +Call this method to make sure that all pending events have been written to +disk. + + +- - - + +#### tf.train.SummaryWriter.close() {#SummaryWriter.close} + +Flushes the event file to disk and close the file. + +Call this method when you do not need the summary writer anymore. + + + +- - - + +### tf.train.summary_iterator(path) <div class="md-anchor" id="summary_iterator">{#summary_iterator}</div> + +An iterator for reading `Event` protocol buffers from an event file. + +You can use this function to read events written to an event file. It returns +a Python iterator that yields `Event` protocol buffers. + +Example: Print the contents of an events file. + +```python +for e in tf.summary_iterator(path to events file): + print e +``` + +Example: Print selected summary values. + +```python +# This example supposes that the events file contains summaries with a +# summary value tag 'loss'. These could have been added by calling +# `add_summary()`, passing the output of a scalar summary op created with +# with: `tf.scalar_summary(['loss'], loss_tensor)`. +for e in tf.summary_iterator(path to events file): + for v in e.summary.value: + if v.tag == 'loss': + print v.simple_value +``` + +See the protocol buffer definitions of +[Event](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/util/event.proto) +and +[Summary](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/summary.proto) +for more information about their attributes. + +##### Args: + + +* <b>path</b>: The path to an event file created by a `SummaryWriter`. + +##### Yields: + + `Event` protocol buffers. + + + +## Training utilities. <div class="md-anchor" id="AUTOGENERATED-training-utilities.">{#AUTOGENERATED-training-utilities.}</div> + +- - - + +### tf.train.global_step(sess, global_step_tensor) <div class="md-anchor" id="global_step">{#global_step}</div> + +Small helper to get the global step. + +```python +# Creates a variable to hold the global_step. +global_step_tensor = tf.Variable(10, trainable=False, name='global_step') +# Creates a session. +sess = tf.Session() +# Initializes the variable. +sess.run(global_step_tensor.initializer) +print 'global_step:', tf.train.global_step(sess, global_step_tensor) + +global_step: 10 +``` + +##### Args: + + +* <b>sess</b>: A brain `Session` object. +* <b>global_step_tensor</b>: `Tensor` or the `name` of the operation that contains + the global step. + +##### Returns: + + The global step value. + + +- - - + +### tf.train.write_graph(graph_def, logdir, name, as_text=True) <div class="md-anchor" id="write_graph">{#write_graph}</div> + +Writes a graph proto on disk. + +The graph is written as a binary proto unless as_text is `True`. + +```python +v = tf.Variable(0, name='my_variable') +sess = tf.Session() +tf.train.write_graph(sess.graph_def, '/tmp/my-model', 'train.pbtxt') +``` + +##### Args: + + +* <b>graph_def</b>: A `GraphDef` protocol buffer. +* <b>logdir</b>: Directory where to write the graph. +* <b>name</b>: Filename for the graph. +* <b>as_text</b>: If `True`, writes the graph as an ASCII proto. + + diff --git a/tensorflow/g3doc/extras/README.txt b/tensorflow/g3doc/extras/README.txt new file mode 100644 index 0000000000..2c9682d2fb --- /dev/null +++ b/tensorflow/g3doc/extras/README.txt @@ -0,0 +1,2 @@ +This directory holds extra files we'd like to be able +to link to and serve from within tensorflow.org diff --git a/tensorflow/g3doc/extras/tensorflow-whitepaper2015.bib b/tensorflow/g3doc/extras/tensorflow-whitepaper2015.bib new file mode 100644 index 0000000000..d04168ab39 --- /dev/null +++ b/tensorflow/g3doc/extras/tensorflow-whitepaper2015.bib @@ -0,0 +1,45 @@ +@misc{tensorflow2015-whitepaper, +title={{TensorFlow}: Large-Scale Machine Learning on Heterogeneous Systems}, +url={http://www.tensorflow.org/extras/tensorflow-whitepaper2015.pdf}, +note={Software available from www.tensorflow.org}, +author={ + Martin~Abadi and + Ashish~Agarwal and + Paul~Barham and + Eugene~Brevdo and + Zhifeng~Chen and + Craig~Citro and + Greg~Corrado and + Andy~Davis and + Jeffrey~Dean and + Matthieu~Devin and + Sanjay~Ghemawat and + Ian~Goodfellow and + Andrew~Harp and + Geoffrey~Irving and + Michael~Isard and + Yangqing Jia and + Lukasz~Kaiser and + Manjunath~Kudlur and + Josh~Levenberg and + Dan~Man\'{e} and + Rajat~Monga and + Sherry~Moore and + Derek~Murray and + Chris~Olah and + Jonathon~Shlens and + Benoit~Steiner and + Ilya~Sutskever and + Kunal~Talwar and + Paul~Tucker and + Vincent~Vanhoucke and + Vijay~Vasudevan and + Fernanda~Vi\'{e}gas, + Oriol~Vinyals and + Pete~Warden and + Martin~Wattenberg, + Martin~Wicke and + Yuan~Yu and + Xiaoqiang~Zheng}, + year={2015}, +} diff --git a/tensorflow/g3doc/get_started/basic_usage.md b/tensorflow/g3doc/get_started/basic_usage.md new file mode 100644 index 0000000000..04c3334028 --- /dev/null +++ b/tensorflow/g3doc/get_started/basic_usage.md @@ -0,0 +1,273 @@ +# Basic Usage + +To use TensorFlow you need to understand how TensorFlow: + +* Represents computations as graphs. +* Executes graphs in the context of `Sessions`. +* Represents data as tensors. +* Maintains state with `Variables`. +* Uses feeds and fetches to get data into and out of arbitrary operations. + +## Overview + +TensorFlow is a programming system in which you represent computations as +graphs. Nodes in the graph are called *ops* (short for operations). An op +takes zero or more `Tensors`, performs some computation, and produces zero or +more `Tensors`. A `Tensor` is a typed multi-dimensional array. For example, +you can represent a mini-batch of images as a 4-D array of floating point +numbers with dimensions `[batch, height, width, channels]`). + +A TensorFlow graph is a *description* of computations. To compute anything, +a graph must be launched in a `Session`. A `Session` places the graph ops onto +`Devices`, such as CPUs or GPUs, and provides methods to execute them. These +methods return tensors produced by ops as [numpy](http://www.numpy.org) +`ndarray` objects in Python, and as `tensorflow::Tensor` instances in C and +C++. + +## The computation graph + +TensorFlow programs are usually structured into a construction phase, that +assembles a graph, and an execution phase that uses a session to execute ops in +the graph. + +For example, it is common to create a graph to represent and train a neural +network in the construction phase, and then repeatedly execute a set of +training ops in the graph in the execution phase. + +TensorFlow can be used from C, C++, and Python programs. It is presently much +easier to use the Python library to assemble graphs, as it provides a large set +of helper functions not available in the C and C++ libraries. + +The session libraries have equivalent functionalities for the three languages. + +### Building the graph + +To build a graph start with ops that do not need any input (source ops), such as +`Constant`, and pass their output to other ops that do computation. + +The ops constructors in the Python library return objects that stand for the +output of the constructed ops. You can pass these to other ops constructors to +use as inputs. + +The TensorFlow Python library has a *default graph* to which ops constructors +add nodes. The default graph is sufficient for many applications. See the +[Graph class](../api_docs/python/framework.md#Graph) documentation for how +to explicitly manage multiple graphs. + +```python +import tensorflow as tf + +# Create a Constant op that produces a 1x2 matrix. The op is +# added as a node to the default graph. +# +# The value returned by the constructor represents the output +# of the Constant op. +matrix1 = tf.constant([[3., 3.]]) + +# Create another Constant that produces a 2x1 matrix. +matrix2 = tf.constant([[2.],[2.]]) + +# Create a Matmul op that takes 'matrix1' and 'matrix2' as inputs. +# The returned value, 'product', represents the result of the matrix +# multiplication. +product = tf.matmul(matrix1, matrix2) +``` + +The default graph now has three nodes: two `constant()` ops and one `matmul()` +op. To actually multiply the matrices, and get the result of the multiplication, +you must launch the graph in a session. + +## Launching the graph in a Session + +Launching follows construction. To launch a graph, create a `Session` object. +Without arguments the session constructor launches the default graph. + +See the [Session class](../api_docs/python/client.md#session-management) for +the complete session API. + +```python +# Launch the default graph. +sess = tf.Session() + +# To run the matmul op we call the session 'run()' method, passing 'product' +# which represents the output of the matmul op. This indicates to the call +# that we want to get the output of the matmul op back. +# +# All inputs needed by the op are run automatically by the session. They +# typically are run in parallel. +# +# The call 'run(product)' thus causes the execution of threes ops in the +# graph: the two constants and matmul. +# +# The output of the op is returned in 'result' as a numpy `ndarray` object. +result = sess.run(product) +print result + +# Close the Session when we're done. +sess.close() + + +# Stdout output ==> [[ 12.]] +``` + +Sessions should be closed to release resources. You can also enter a `Session` +with a "with" block. The `Session` closes automatically at the end of the +`with` block. + + + +```python +with tf.Session() as sess: + result = sess.run([product]) + print result +``` + +The TensorFlow implementation translates the graph definition into executable +operations distributed across available compute resources, such as the CPU or +one of your computer's GPU cards. In general you do not have to specify CPUs +or GPUs explicitly. TensorFlow uses your first GPU, if you have one, for as +many operations as possible. + +If you have more than one GPU available on your machine, to use a GPU beyond +the first you must assign ops to it explicitly. Use `with...Device` statements +to specify which CPU or GPU to use for operations: + +```python +with tf.Session() as sess: + with tf.device("/gpu:1"): + matrix1 = tf.constant([[3., 3.]]) + matrix2 = tf.constant([[2.],[2.]]) + product = tf.matmul(matrix1, matrix2) + ... +``` + +Devices are specified with strings. The currently supported devices are: + +* `"/cpu:0"`: The CPU of your machine. +* `"/gpu:0"`: The GPU of your machine, if you have one. +* `"/gpu:1"`: The second GPU of your machine, etc. + +See [Using GPUs](../how_tos/using_gpu/index.md) for more information about GPUs +and TensorFlow. + +## Tensors + +TensorFlow programs use a tensor data structure to represent all data -- only +tensors are passed between operations in the computation graph. You can think +of a TensorFlow tensor as an n-dimensional array or list. A tensor has a +static type a rank, and a shape. To learn more about how TensorFlow handles +these concepts, see the [Rank, Shape, and Type](../resources/dims_types.md) +reference. + + +# output: +# [array([ 21.], dtype=float32), array([ 7.], dtype=float32)] + + + + + +## Variables + +Variables maintain state across executions of the graph. The following example +shows a variable serving as a simple counter. See +[Variables](../how_tos/variables/index.md) for more details. + +```python +# Create a Variable, that will be initialized to the scalar value 0. +var = tf.Variable(0, name="counter") + +# Create an Op to add one to `var`. + +one = tf.constant(1) +new_value = tf.add(state, one) +update = tf.assign(state, new_value) + +# Variables must be initialized by running an `init` Op after having + +# launched the graph. We first have to add the `init` Op to the graph. +init_op = tf.initialize_all_variables() + +# Launch the graph and run the ops. +with tf.Session() as sess: + # Run the 'init' op + sess.run(init_op) + # Print the initial value of 'var' + print sess.run(var) + # Run the op that updates 'var' and print 'var'. + for _ in range(3): + sess.run(update) + print sess.run(var) + +# output: + +# 0 +# 1 +# 2 +# 3 +``` + +The `assign()` operation in this code is a part of the expression graph just +like the `add()` operation, so it does not actually perform the assignment +until `run()` executes the expression. + +You typically represent the parameters of a statistical model as a set of +Variables. For example, you would store the weights for a neural network as a +tensor in a Variable. During training you update this tensor by running a +training graph repeatedly. + +## Fetches + +To fetch the outputs of operations, execute the graph with a `run()` call on +the `Session` object and pass in the tensors to retrieve. In the previous +example we fetched the single node `var`, but you can also fetch multiple +tensors: + +```python +input1 = tf.constant(3.0) +input2 = tf.constant(2.0) +input3 = tf.constant(5.0) +intermed = tf.add(input2, input3) +mul = tf.mul(input1, intermed) + +with tf.Session(): + result = sess.run([mul, intermed]) + print result + +# output: +# [array([ 21.], dtype=float32), array([ 7.], dtype=float32)] +``` + +All the ops needed to produce the values of the requested tensors are run once +(not once per requested tensor). + +## Feeds + +The examples above introduce tensors into the computation graph by storing them +in `Constants` and `Variables`. TensorFlow also provides a feed mechanism for +patching a tensor directly into any operation in the graph. + +A feed temporarily replaces the output of an operation with a tensor value. +You supply feed data as an argument to a `run()` call. The feed is only used for +the run call to which it is passed. The most common use case involves +designating specific operations to be "feed" operations by using +tf.placeholder() to create them: + +```python + +input1 = tf.placeholder(tf.types.float32) +input2 = tf.placeholder(tf.types.float32) +output = tf.mul(input1, input2) + +with tf.Session() as sess: + print sess.run([output], feed_dict={input1:[7.], input2:[2.]}) + +# output: +# [array([ 14.], dtype=float32)] +``` + +A `placeholder()` operation generates an error if you do not supply a feed for +it. See the [MNIST fully-connected feed +tutorial](../tutorials/mnist/fully_connected_feed.py) for a larger-scale +example of feeds. + diff --git a/tensorflow/g3doc/get_started/blue_pill.jpg b/tensorflow/g3doc/get_started/blue_pill.jpg new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/get_started/blue_pill.jpg diff --git a/tensorflow/g3doc/get_started/index.md b/tensorflow/g3doc/get_started/index.md new file mode 100644 index 0000000000..5b92e6e53f --- /dev/null +++ b/tensorflow/g3doc/get_started/index.md @@ -0,0 +1,84 @@ +# Introduction + +Let's get you up and running with TensorFlow! + +But before we even get started, let's give you a sneak peak at what TensorFlow +code looks like in the Python API, just so you have a sense of where we're +headed. + +Here's a little Python program that makes up some data in three dimensions, and +then fits a plane to it. + +```python +import tensorflow as tf +import numpy as np + +# Make 100 phony data points in NumPy. +x_data = np.float32(np.random.rand(2, 100)) # Random input +y_data = np.dot([0.100, 0.200], x_data) + 0.300 + +# Construct a linear model. +b = tf.Variable(tf.zeros([1])) +W = tf.Variable(tf.random_uniform([1, 2], -1.0, 1.0)) +y = tf.matmul(W, x_data) + b + +# Minimize the squared errors. +loss = tf.reduce_mean(tf.square(y - y_data)) +optimizer = tf.train.GradientDescentOptimizer(0.5) +train = optimizer.minimize(loss) + +# For initializing the variables. +init = tf.initialize_all_variables() + +# Launch the graph +sess = tf.Session() +sess.run(init) + +# Fit the plane. +for step in xrange(0, 201): + sess.run(train) + if step % 20 == 0: + print step, sess.run(W), sess.run(b) + +# Learns best fit is W: [[0.100 0.200]], b: [0.300] +``` + +To whet your appetite further, we suggest you check out what a classical +machine learning problem looks like in TensorFlow. In the land of neural +networks the most "classic" classical problem is the MNIST handwritten digit +classification. We offer two introductions here, one for machine learning +newbies, and one for pros. If you've already trained dozens of MNIST models in +other software packages, please take the red pill. If you've never even heard +of MNIST, definitely take the blue pill. If you're somewhere in between, we +suggest skimming blue, then red. + +TODO(danmane): Add in creative commons attribution for these images. +Also, make sure the sizes are precisely the same. + +<div style="width:100%; margin:auto; margin-bottom:10px; margin-top:20px; display: flex; flex-direction: row"> + <a href="../tutorials/mnist/beginners/index.md"> + <img style="flex-grow:1; flex-shrink:1;border: 1px solid black;" src="./blue_pill.jpg"> + </a> + <a href="../tutorials/mnist/pros/index.md"> + <img style="flex-grow:1; flex-shrink:1; border: 1px solid black;" src="./red_pill.jpg"> + </a> +</div> + +If you're already sure you want to learn and install TensorFlow you can skip +these and charge ahead. Don't worry, you'll still get to see MNIST -- we'll +also use MNIST as an example in our technical tutorial where we elaborate on +TensorFlow features. + +## Recommended Next Steps: +* [Download and Setup](os_setup.md) +* [Basic Usage](basic_usage.md) +* [TensorFlow Mechanics 101](../tutorials/mnist/tf/index.md) + + +<div class='sections-order' style="display: none;"> +<!-- +<!-- os_setup.md --> +<!-- basic_usage.md --> +--> +</div> + diff --git a/tensorflow/g3doc/get_started/os_setup.md b/tensorflow/g3doc/get_started/os_setup.md new file mode 100644 index 0000000000..01e6fde788 --- /dev/null +++ b/tensorflow/g3doc/get_started/os_setup.md @@ -0,0 +1,261 @@ +# Download and Setup + +## Binary Installation + +### Ubuntu/Linux + +Make sure you have `pip` and `numpy` installed : + +```sh +$ sudo apt-get install python-pip python-numpy +``` + +Install TensorFlow: + +```sh +# For CPU-only version +$ sudo pip install https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-0.5.0-cp27-none-linux_x86_64.whl + +# For GPU-enabled version +$ sudo pip install https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow-0.5.0-cp27-none-linux_x86_64.whl +``` + +### Mac OS X + +Make sure you have `pip` installed: + +If using `easy_install`: + +```sh +$ sudo easy_install pip +``` + +Install TensorFlow (only CPU binary version is currently available). + +```sh +$ sudo pip install https://storage.googleapis.com/tensorflow/mac/tensorflow-0.5.0-py2-none-any.whl +``` + +### Try your first TensorFlow program + +```sh +$ python + +>>> import tensorflow as tf +>>> hello = tf.constant('Hello, TensorFlow!') +>>> sess = tf.Session() +>>> print sess.run(hello) +Hello, TensorFlow! +>>> a = tf.constant(10) +>>> b = tf.constant(32) +>>> print sess.run(a+b) +42 +>>> + +``` + +If you are running the GPU version and you see +```sh +ImportError: libcudart.so.7.0: cannot open shared object file: No such file or directory +``` + +you most likely need to set your `LD_LIBRARY_PATH` to point to the location of +your CUDA libraries. + +### Train the MNIST neural net model + +```sh +$ python tensorflow/models/image/mnist/convolutional.py +Succesfully downloaded train-images-idx3-ubyte.gz 9912422 bytes. +Succesfully downloaded train-labels-idx1-ubyte.gz 28881 bytes. +Succesfully downloaded t10k-images-idx3-ubyte.gz 1648877 bytes. +Succesfully downloaded t10k-labels-idx1-ubyte.gz 4542 bytes. +Extracting data/train-images-idx3-ubyte.gz +Extracting data/train-labels-idx1-ubyte.gz +Extracting data/t10k-images-idx3-ubyte.gz +Extracting data/t10k-labels-idx1-ubyte.gz +can't determine number of CPU cores: assuming 4 +I tensorflow/core/common_runtime/local_device.cc:25] Local device intra op +parallelism threads: 3 +can't determine number of CPU cores: assuming 4 +I tensorflow/core/common_runtime/local_session.cc:45] Local session inter op +parallelism threads: 4 +Initialized! +Epoch 0.00 +Minibatch loss: 12.054, learning rate: 0.010000 +Minibatch error: 90.6% +Validation error: 84.6% +... +... + +``` + +## Source Installation {#source} + +### Clone the TensorFlow repository + +TODO(keveman): Supply clone command for external users. + +```sh +$ git clone --recurse-submodules https://YOUR_WHITELISTED_EMAIL_WITH_AT_REPLACED_BY_DOT@tensorflow.googlesource.com/tf3 +``` + + +### Installation for Linux + +#### Install Bazel + + +Follow instructions [here](http://bazel.io/docs/install.html) to install the +dependencies for Bazel. Then download and build the Bazel source with the +following commands: + +```sh +$ git clone https://github.com/bazelbuild/bazel.git +$ cd bazel +$ git checkout tags/0.1.0 +$ ./compile.sh +``` + +These commands use the commit tag `0.1.0`, which is known to work with +TensorFlow. `HEAD` may be unstable. + +Add the executable `output/bazel` to your `$PATH` environment variable. + +#### Install other dependencies + +```sh +$ sudo apt-get install python-numpy swig python-dev +``` + +#### Optional: Install CUDA (GPUs on Linux) + +In order to build TensorFlow with GPU support, both Cuda Toolkit 7.0 and CUDNN +6.5 V2 from NVIDIA need to be installed. + +##### Download and install Cuda Toolkit 7.0 + +https://developer.nvidia.com/cuda-toolkit-70 + +Install the toolkit into e.g. `/usr/local/cuda` + +##### Download and install CUDNN Toolkit 6.5 + +https://developer.nvidia.com/rdp/cudnn-archive + +Uncompress and copy the cudnn files into the toolkit directory. Assuming the +toolkit is installed in `/usr/local/cuda`: + +``` bash +tar xvzf cudnn-6.5-linux-x64-v2.tgz +sudo cp cudnn-6.5-linux-x64-v2/cudnn.h /usr/local/cuda/include +sudo cp cudnn-6.5-linux-x64-v2/libcudnn* /usr/local/cuda/lib64 +``` + +##### Configure TensorFlow's canonical view of Cuda libraries +From the root of your source tree, run: + +``` bash +$ ./configure +Do you wish to bulid TensorFlow with GPU support? [y/n] y +GPU support will be enabled for TensorFlow + +Please specify the location where CUDA 7.0 toolkit is installed. Refer to +README.md for more details. [default is: /usr/local/cuda]: /usr/local/cuda +CUDA 7.0 toolkit found + +Please specify the location where CUDNN 6.5 V2 library is installed. Refer to +README.md for more details. [default is: /usr/local/cuda]: /usr/local/cuda +CUDNN 6.5 V2 library found + +Setting up Cuda include +Setting up Cuda lib64 +Setting up Cuda bin +Setting up Cuda nvvm +Configuration finished +``` + +This creates a canonical set of symbolic links to the Cuda libraries on your system. +Every time you change the Cuda library paths you need to run this step again before +you invoke the bazel build command. + +##### Build your target with GPU support. +From the root of your source tree, run: + +```sh +$ bazel build -c opt --config=cuda //tensorflow/cc:tutorials_example_trainer + +$ bazel-bin/tensorflow/cc/tutorials_example_trainer --use_gpu +# Lots of output. This tutorial iteratively calculates the major eigenvalue of +# a 2x2 matrix, on GPU. The last few lines look like this. +000009/000005 lambda = 2.000000 x = [0.894427 -0.447214] y = [1.788854 -0.894427] +000006/000001 lambda = 2.000000 x = [0.894427 -0.447214] y = [1.788854 -0.894427] +000009/000009 lambda = 2.000000 x = [0.894427 -0.447214] y = [1.788854 -0.894427] +000006/000008 lambda = 2.000000 x = [0.894427 -0.447214] y = [1.788854 -0.894427] +000009/000003 lambda = 2.000000 x = [0.894427 -0.447214] y = [1.788854 -0.894427] +000006/000006 lambda = 2.000000 x = [0.894427 -0.447214] y = [1.788854 -0.894427] +``` + +Note that "--config=cuda" is needed to enable the GPU support. + +##### Known issues + +* Although it is possible to build both Cuda and non-Cuda configs under the same +source tree, we recommend to run "bazel clean" when switching between these two +configs in the same source tree. + +* You have to run configure before running bazel build. Otherwise, the build +will fail with a clear error message. In the future, we might consider making +this more conveninent by including the configure step in our build process, +given necessary bazel new feature support. + +### Installation for Mac OS X + +Mac needs the same set of dependencies as Linux, however their installing those +dependencies is different. Here is a set of useful links to help with installing +the dependencies on Mac OS X : + +#### Bazel + +Look for installation instructions for Mac OS X on +[this](http://bazel.io/docs/install.html) page. + +#### SWIG + +[Mac OS X installation](http://www.swig.org/Doc3.0/Preface.html#Preface_osx_installation). + +Notes : You need to install +[PCRE](ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/) and *NOT* PCRE2. + +#### Numpy + +Follow installation instructions [here](http://docs.scipy.org/doc/numpy/user/install.html). + +### Build and train your first TensorFlow neural net model + +```sh +$ cd tf3 + +$ bazel build tensorflow/models/image/mnist:convolutional + +$ bazel-bin/tensorflow/models/image/mnist/convolutional +Succesfully downloaded train-images-idx3-ubyte.gz 9912422 bytes. +Succesfully downloaded train-labels-idx1-ubyte.gz 28881 bytes. +Succesfully downloaded t10k-images-idx3-ubyte.gz 1648877 bytes. +Succesfully downloaded t10k-labels-idx1-ubyte.gz 4542 bytes. +Extracting data/train-images-idx3-ubyte.gz +Extracting data/train-labels-idx1-ubyte.gz +Extracting data/t10k-images-idx3-ubyte.gz +Extracting data/t10k-labels-idx1-ubyte.gz +Initialized! +Epoch 0.00 +Minibatch loss: 12.054, learning rate: 0.010000 +Minibatch error: 90.6% +Validation error: 84.6% +Epoch 0.12 +Minibatch loss: 3.285, learning rate: 0.010000 +Minibatch error: 6.2% +Validation error: 7.0% +... +... +``` diff --git a/tensorflow/g3doc/get_started/red_pill.jpg b/tensorflow/g3doc/get_started/red_pill.jpg new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/get_started/red_pill.jpg diff --git a/tensorflow/g3doc/how_tos/__init__.py b/tensorflow/g3doc/how_tos/__init__.py new file mode 100755 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/how_tos/__init__.py diff --git a/tensorflow/g3doc/how_tos/adding_an_op/__init__.py b/tensorflow/g3doc/how_tos/adding_an_op/__init__.py new file mode 100755 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/how_tos/adding_an_op/__init__.py diff --git a/tensorflow/g3doc/how_tos/adding_an_op/attr_examples.cc b/tensorflow/g3doc/how_tos/adding_an_op/attr_examples.cc new file mode 100644 index 0000000000..84e54c7219 --- /dev/null +++ b/tensorflow/g3doc/how_tos/adding_an_op/attr_examples.cc @@ -0,0 +1,31 @@ +#include <stdio.h> +#include "tensorflow/core/framework/op.h" + +REGISTER_OP("RestrictedTypeExample").Attr("t: {int32, float, bool}"); + +REGISTER_OP("NumberType").Attr("t: numbertype"); + +REGISTER_OP("EnumExample").Attr("e: {'apple', 'orange'}"); + +REGISTER_OP("MinIntExample").Attr("a: int >= 2"); + +REGISTER_OP("TypeListExample").Attr("a: list({int32, float}) >= 3"); + +REGISTER_OP("AttrDefaultExample").Attr("i: int = 0"); + +REGISTER_OP("AttrDefaultExampleForAllTypes") + .Attr("s: string = 'foo'") + .Attr("i: int = 0") + .Attr("f: float = 1.0") + .Attr("b: bool = true") + .Attr("ty: type = DT_INT32") + .Attr("sh: shape = { dim { size: 1 } dim { size: 2 } }") + .Attr("te: tensor = { dtype: DT_INT32 int_val: 5 }") + .Attr("l_empty: list(int) = []") + .Attr("l_int: list(int) = [2, 3, 5, 7]"); + +int main(int argc, char* argv[]) { + printf("All registered ops:\n%s\n", + tensorflow::OpRegistry::Global()->DebugString(false).c_str()); + return 0; +} diff --git a/tensorflow/g3doc/how_tos/adding_an_op/fact_test.py b/tensorflow/g3doc/how_tos/adding_an_op/fact_test.py new file mode 100644 index 0000000000..17a7028d98 --- /dev/null +++ b/tensorflow/g3doc/how_tos/adding_an_op/fact_test.py @@ -0,0 +1,16 @@ +"""Test that user ops can be used as expected.""" + +import tensorflow.python.platform + +import tensorflow as tf + + +class FactTest(tf.test.TestCase): + + def test(self): + with self.test_session(): + print tf.user_ops.my_fact().eval() + + +if __name__ == '__main__': + tf.test.main() diff --git a/tensorflow/g3doc/how_tos/adding_an_op/index.md b/tensorflow/g3doc/how_tos/adding_an_op/index.md new file mode 100644 index 0000000000..5c6243cd9c --- /dev/null +++ b/tensorflow/g3doc/how_tos/adding_an_op/index.md @@ -0,0 +1,1015 @@ +# Adding a New Op to TensorFlow + +PREREQUISITES: + +* Some familiarity with C++. +* Must have [downloaded TensorFlow source](../../get_started/index.md#source), + and be able to build it. + +If you'd like to incorporate an operation that isn't covered by the existing +library, you can create a custom Op. To incorporate your custom Op, you'll need +to: + +* Register the new Op in a C++ file. The Op registration is independent of the + implementation, and describes the semantics of how the Op is invoked. For + example, it defines the Op name, and specifies its inputs and outputs. +* Implement the Op in C++. This implementation is called a "kernel", and there + can be multiple kernels for different architectures (e.g. CPUs, GPUs) or + input / output types. +* Create a Python wrapper. This wrapper is the public API to create the Op. A + default wrapper is generated from the Op registration, which can be used + directly or added to. +* Optionally, write a function to compute gradients for the Op. +* Optionally, write a function that describes the input and output shapes + for the Op. This allows shape inference to work with your Op. +* Test the Op, typically in Python. If you define gradients, verify them with + the Python [`GradientChecker`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/kernel_tests/gradient_checker.py). + +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Define the Op's interface](#define_interface) +* [Implement the kernel for the Op](#AUTOGENERATED-implement-the-kernel-for-the-op) +* [Generate the client wrapper](#AUTOGENERATED-generate-the-client-wrapper) + * [The Python Op wrapper](#AUTOGENERATED-the-python-op-wrapper) + * [The C++ Op wrapper](#AUTOGENERATED-the-c---op-wrapper) +* [Verify it works](#AUTOGENERATED-verify-it-works) +* [Validation](#validation) +* [Op registration](#AUTOGENERATED-op-registration) + * [Attrs](#AUTOGENERATED-attrs) + * [Attr types](#AUTOGENERATED-attr-types) + * [Polymorphism](#polymorphism) + * [Inputs and Outputs](#AUTOGENERATED-inputs-and-outputs) + * [Backwards compatibility](#AUTOGENERATED-backwards-compatibility) +* [GPU Support](#mult-archs) +* [Implement the gradient in Python](#AUTOGENERATED-implement-the-gradient-in-python) +* [Implement a shape function in Python](#AUTOGENERATED-implement-a-shape-function-in-python) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Define the Op's interface <div class="md-anchor" id="define_interface">{#define_interface}</div> + +You define the interface of an Op by registering it with the TensorFlow system. +In the registration, you specify the name of your Op, its inputs (types and +names) and outputs (types and names), as well as [docstrings](#docstrings) and +any [attrs](#attrs) the Op might require. + +To see how this works, suppose you'd like to create an Op that takes a tensor of +`int32`s and outputs a copy of the tensor, with all but the first element set to +zero. Create file [`tensorflow/core/user_ops`][user_ops]`/zero_out.cc` and +add a call to the `REGISTER_OP` macro that defines the interface for such an Op: + +```c++ +#include "tensorflow/core/framework/op.h" + +REGISTER_OP("ZeroOut") + .Input("to_zero: int32") + .Output("zeroed: int32"); +``` + +This `ZeroOut` Op takes one tensor `to_zero` of 32-bit integers as input, and +outputs a tensor `zeroed` of 32-bit integers. + +> A note on naming: The name of the Op should be unique and CamelCase. Names +> starting with an underscore (`_`) are reserved for internal use. + +## Implement the kernel for the Op <div class="md-anchor" id="AUTOGENERATED-implement-the-kernel-for-the-op">{#AUTOGENERATED-implement-the-kernel-for-the-op}</div> + +After you define the interface, provide one or more implementations of the Op. +To create one of these kernels, create a class that extends `OpKernel` and +overrides the `Compute` method. The `Compute` method provides one `context` +argument of type `OpKernelContext*`, from which you can access useful things +like the input and output tensors. + +Add your kernel to the file you created above. The kernel might look something +like this: + +```c++ +#include "tensorflow/core/framework/op_kernel.h" + +using namespace tensorflow; + +class ZeroOutOp : public OpKernel { + public: + explicit ZeroOutOp(OpKernelConstruction* context) : OpKernel(context) {} + + void Compute(OpKernelContext* context) override { + // Grab the input tensor + const Tensor& input_tensor = context->input(0); + auto input = input_tensor.flat<int32>(); + + // Create an output tensor + Tensor* output_tensor = NULL; + OP_REQUIRES_OK(context, context->allocate_output(0, input_tensor.shape(), + &output_tensor)); + auto output = output_tensor->template flat<int32>(); + + // Set all but the first element of the output tensor to 0. + const int N = input.size(); + for (int i = 1; i < N; i++) { + output(i) = 0; + } + + // Preserve the first input value if possible. + if (N > 0) output(0) = input(0); + } +}; +``` + +After implementing your kernel, you register it with the TensorFlow system. In +the registration, you specify different constraints under which this kernel +will run. For example, you might have one kernel made for CPUs, and a separate +one for GPUs. + +To do this for the `ZeroOut` op, add the following to `zero_out.cc`: + +```c++ +REGISTER_KERNEL_BUILDER(Name("ZeroOut").Device(DEVICE_CPU), ZeroOutOp); +``` + +TODO: instructions or pointer to building TF + +At this point, the Tensorflow system can reference and use the Op when +requested. + +## Generate the client wrapper <div class="md-anchor" id="AUTOGENERATED-generate-the-client-wrapper">{#AUTOGENERATED-generate-the-client-wrapper}</div> +### The Python Op wrapper <div class="md-anchor" id="AUTOGENERATED-the-python-op-wrapper">{#AUTOGENERATED-the-python-op-wrapper}</div> + +Python op wrappers are created automatically in +`bazel-genfiles/tensorflow/python/ops/gen_user_ops.py` for all ops placed in the +[`tensorflow/core/user_ops`][user_ops] directory when you build Tensorflow. +Those ops are imported into +[`tensorflow/python/user_ops/user_ops.py`][python-user_ops] with the statement: + +```python +from tensorflow.python.ops.gen_user_ops import * +``` + +You may optionally use your own function instead. To do this, you first hide +the generated code for that op by adding its name to the `hidden` list in the +`"user_ops"` rule in +[`tensorflow/python/BUILD`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/BUILD): + +```python +tf_gen_op_wrapper_py( + name = "user_ops", + hidden = [ + "Fact", + ], + require_shape_functions = False, +) +``` + +List your op next to `"Fact"`. Next you add your replacement function to +[`tensorflow/python/user_ops/user_ops.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/user_ops/user_ops.py). +Typically your function will call the generated function to actually add the op +to the graph. The hidden version of the generated function will be in the +`gen_user_ops` package and start with an underscore ("`_`"). For example: + +```python +def my_fact(): + """Example of overriding the generated code for an Op.""" + return gen_user_ops._fact() +``` + +### The C++ Op wrapper <div class="md-anchor" id="AUTOGENERATED-the-c---op-wrapper">{#AUTOGENERATED-the-c---op-wrapper}</div> + +C++ op wrappers are created automatically for all ops placed in the +[`tensorflow/core/user_ops`][user_ops] directory, when you build Tensorflow. For +example, ops in `tensorflow/core/user_ops/zero_out.cc` will generate wrappers in +`bazel-genfiles/tensorflow/cc/ops/user_ops.{h,cc}`. + +All generated wrappers for user ops are automatically +imported into [`tensorflow/cc/ops/standard_ops.h`][standard_ops-cc] with the +statement + +```c++ +#include "tensorflow/cc/ops/user_ops.h" +``` + +## Verify it works <div class="md-anchor" id="AUTOGENERATED-verify-it-works">{#AUTOGENERATED-verify-it-works}</div> + +A good way to verify that you've successfully implemented your Op is to write a +test for it. Create the file +`tensorflow/python/kernel_tests/zero_out_op_test.py` with the contents: +[TODO]:# (put tests somewhere else and make sure it works) + +```python +import tensorflow as tf + + +class ZeroOutTest(tf.test.TestCase): + def testZeroOut(self): + with self.test_session(): + result = tf.user_ops.zero_out([5, 4, 3, 2, 1]) + self.assertAllEqual(result.eval(), [5, 0, 0, 0, 0]) +``` + +Then run your test: + +```sh +$ bazel test tensorflow/python:zero_out_op_test +``` + +## Validation <div class="md-anchor" id="validation">{#validation}</div> + +The example above assumed that the Op applied to a tensor of any shape. What +if it only applied to vectors? That means adding a check to the above OpKernel +implementation. + +```c++ + void Compute(OpKernelContext* context) override { + // Grab the input tensor + const Tensor& input_tensor = context->input(0); + + OP_REQUIRES(context, TensorShapeUtils::IsVector(input_tensor.shape()), + errors::InvalidArgument("ZeroOut expects a 1-D vector.")); + // ... + } +``` + +This asserts that the input is a vector, and returns having set the +`InvalidArgument` status if it isn't. The +[OP_REQUIRES macro][validation-macros] takes three arguments: + +* The `context`, which can either be an `OpKernelContext` or + `OpKernelConstruction` pointer (see + [`tensorflow/core/framework/op_kernel.h`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/op_kernel.h)), + for its `SetStatus()` method. +* The condition. For example, there are functions for validating the shape + of a tensor in [`tensorflow/core/public/tensor_shape.h`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/public/tensor_shape.h) +* The error itself, which is represented by a `Status` object, see + [`tensorflow/core/public/status.h`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/public/status.h). A + `Status` has both a type (frequently `InvalidArgument`, but see the list of + types) and a message. Functions for constructing an error may be found in + [`tensorflow/core/lib/core/errors.h`][validation-macros]. + +Alternatively, if you want to test whether a `Status` object returned from some +function is an error, and if so return it, use +[`OP_REQUIRES_OK`][validation-macros]. Both of these macros return from the +function on error. + +## Op registration <div class="md-anchor" id="AUTOGENERATED-op-registration">{#AUTOGENERATED-op-registration}</div> + +### Attrs <div class="md-anchor" id="AUTOGENERATED-attrs">{#AUTOGENERATED-attrs}</div> + +Ops can have attrs, whose values are set when the Op is added to a graph. These +are used to configure the Op, and their values can be accessed both within the +kernel implementation and in the types of inputs and outputs in the Op +registration. Prefer using an input instead of an attr when possible, since +inputs are more flexible. They can change every step, be set using a feed, etc. +Attrs are used for things that can't be done with inputs: any configuration +that affects the signature (number or type of inputs or outputs) or that +can't change from step-to-step. + +You define an attr when you register the Op, by specifying its name and type +using the `Attr` method, which expects a spec of the form: + +``` +<name>: <attr-type-expr> +``` + +where `<name>` begins with a letter and can be composed of alphanumeric +characters and underscores, and `<attr-type-expr>` is a type expression of the +form [described below](#attr-types) + +For example, if you'd like the `ZeroOut` Op to preserve a user-specified index, +instead of only the 0th element, you can register the Op like so: + +<code class="lang-c++"><pre> +REGISTER\_OP("ZeroOut") + <b>.Attr("preserve_index: int")</b> + .Input("to_zero: int32") + .Output("zeroed: int32"); +</pre></code> + +Your kernel can then access this attr in its constructor via the `context` +parameter: + +<code class="lang-c++"><pre> +class ZeroOutOp : public OpKernel { + public: + explicit ZeroOutOp(OpKernelConstruction\* context) : OpKernel(context) {<b> + // Get the index of the value to preserve + OP_REQUIRES_OK(context->GetAttr("preserve\_index", &preserve\_index\_)); + </b>} + void Compute(OpKernelContext\* context) override { + // ... + } + <b>private: + int preserve\_index\_;</b> +} +</pre></code> + +which can then be used in the `Compute` method: + +<code class="lang-c++"><pre> + void Compute(OpKernelContext\* context) override { + // ... + // Set all the elements of the output tensor to 0 + const int N = input.size(); + for (int i=0; i < N; i++) { + output\_flat(i) = 0; + }<br> + <b>// Preserve the requested input value + output\_flat(preserve\_index\_) = input(preserve\_index\_);</b> + } +</pre></code> + +[TODO]:# (check the code in this section in and test it) + +> To preserve [backwards compatibility](#backwards-compatibility), you should +> specify a [default value](#default-values-constraints) when adding an attr to +> an existing op: +> +> <code class="lang-c++"><pre> +> REGISTER\_OP("ZeroOut") +> <b>.Attr("preserve\_index: int = 0")</b> +> .Input("to_zero: int32") +> .Output("zeroed: int32"); +> </pre></code> + +### Attr types <div class="md-anchor" id="AUTOGENERATED-attr-types">{#AUTOGENERATED-attr-types}</div> + +The following types are supported in an attr: + +* `string`: Any sequence of bytes (not required to be UTF8). +* `int`: A signed integer. +* `float`: A floating point number. +* `bool`: True or false. +* `type`: One of the (non-ref) values of [`DataType`][DataTypeString]. +* `shape`: A [`TensorShapeProto`][TensorShapeProto]. +* `tensor`: A [`TensorProto`][TensorProto]. +* `list(<type>)`: A list of `<type>`, where `<type>` is one of the above types. + Note that `list(list(<type>))` is invalid. + +See also: [op_def_builder.cc:FinalizeAttr][FinalizeAttr] for a definitive list. + +#### Default values & constraints + +Attrs may have default values, and some types of attrs can have constraints. To +define an attr with constraints, you can use the following `<attr-type-expr>`s: + +* `{'<string1>', '<string2>'}`: The value must be a string that has either the + value `<string1>` or `<string2>`. The name of the type, `string`, is implied + when you use this syntax. This emulates an enum: + + ```c++ + REGISTER_OP("EnumExample") + .Attr("e: {'apple', 'orange'}"); + ``` + +* `{<type1>, <type2>}`: The value is of type `type`, and must be one of + `<type1>` or `<type2>`, where `<type1>` and `<type2>` are supported + [tensor types](../../resources/dims_types.md#data-types). You don't specify + that the type of the attr is `type`. This is implied when you have a list of + types in `{...}`. For example, in this case the attr `t` is a type that must + be an `int32`, a `float`, or a `bool`: + + ```c++ + REGISTER_OP("RestrictedTypeExample") + .Attr("t: {int32, float, bool}"); + ``` + +* There are shortcuts for common type constraints: + * `numbertype`: Type `type` restricted to the numeric (non-string and + non-bool) types. + * `realnumbertype`: Like `numbertype` without complex types. + * `quantizedtype`: Like `numbertype` but just the quantized number types. + + The specific lists of types allowed by these are defined by the functions + (like `NumberTypes()`) in + [`tensorflow/core/framework/types.h`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/types.h). + In this example the attr `t` must be one of the numeric types: + + ```c++ + REGISTER_OP("NumberType") + .Attr("t: numbertype"); + ``` + + For this op: + + ```python + tf.number_type(t=tf.int32) # Valid + tf.number_type(t=tf.bool) # Invalid + ``` + +* `int >= <n>`: The value must be an int whose value is greater than or equal to + `<n>`, where `<n>` is a natural number. + + For example, the following Op registration specifies that the attr `a` must + have a value that is at least `2`: + + ```c++ + REGISTER_OP("MinIntExample") + .Attr("a: int >= 2"); + ``` + +* `list(<type>) >= <n>`: A list of type `<type>` whose length is greater than + or equal to `<n>`. + + For example, the following Op registration specifies that the attr `a` is a + list of types (either `int32` or `float`), and that there must be at least 3 + of them: + + ```c++ + REGISTER_OP("TypeListExample") + .Attr("a: list({int32, float}) >= 3"); + ``` + +To set a default value for an attr (making it optional in the generated code), +add `= <default>` to the end, as in: + +```c++ +REGISTER_OP("AttrDefaultExample") + .Attr("i: int = 0"); +``` + +The supported syntax of the default value is what would be used in the proto +representation of the resulting GraphDef definition. + +Here are examples for how to specify a default for all types: + +```c++ +REGISTER_OP("AttrDefaultExampleForAllTypes") + .Attr("s: string = 'foo'") + .Attr("i: int = 0") + .Attr("f: float = 1.0") + .Attr("b: bool = true") + .Attr("ty: type = DT_INT32") + .Attr("sh: shape = { dim { size: 1 } dim { size: 2 } }") + .Attr("te: tensor = { dtype: DT_INT32 int_val: 5 }") + .Attr("l_empty: list(int) = []") + .Attr("l_int: list(int) = [2, 3, 5, 7]"); +``` + +Note in particular that the values of type `type` use [the `DT_*` names +for the types](../../resources/dims_types.md#data-types). + +### Polymorphism <div class="md-anchor" id="polymorphism">{#polymorphism}</div> +#### Type Polymorphism {#type-polymorphism} + +For ops that can take different types as input or produce different output +types, you can specify [an attr](#attrs) in +[an input or output type](#inputs-outputs) in the Op registration. Typically +you would then register an `OpKernel` for each supported type. + +For instance, if you'd like the `ZeroOut` Op to work on `float`s +in addition to `int32`s, your Op registration might look like: + +<code class="lang-c++"><pre> +REGISTER\_OP("ZeroOut") + <b>.Attr("T: {float, int32}")</b> + .Input("to_zero: <b>T</b>") + .Output("zeroed: <b>T</b>"); +</pre></code> + +Your Op registration now specifies that the input's type must be `float`, or +`int32`, and that its output will be the same type, since both have type `T`. + +> A note on naming:{#naming} Inputs, outputs, and attrs generally should be +> given snake_case names. The one exception is attrs that are used as the type +> of an input or in the type of an input. Those attrs can be inferred when the +> op is added to the graph and so don't appear in the op's function. For +> example, this last definition of ZeroOut will generate a Python function that +> looks like: +> +> ```python +> def zero_out(to_zero, name=None): +> """... +> Args: +> to_zero: A `Tensor`. Must be one of the following types: +> `float32`, `int32`. +> name: A name for the operation (optional). +> +> Returns: +> A `Tensor`. Has the same type as `x`. +> """ +> ``` +> +> If `to_zero` is passed an `int32` tensor, then `T` is automatically set to +> `int32` (well, actually `DT_INT32`). Those inferred attrs are given +> Capitalized or CamelCase names. +> +> Compare this with an op that has a type attr that determines the output +> type: +> +> ```c++ +> REGISTER_OP("StringToNumber") +> .Input("string_tensor: string") +> .Output("output: out_type") +> .Attr("out_type: {float, int32}"); +> .Doc(R"doc( +> Converts each string in the input Tensor to the specified numeric type. +> )doc"); +> ``` +> +> In this case, the user has to specify the output type, as in the generated +> Python: +> +> ```python +> def string_to_number(string_tensor, out_type=None, name=None): +> """Converts each string in the input Tensor to the specified numeric type. +> +> Args: +> string_tensor: A `Tensor` of type `string`. +> out_type: An optional `tf.DType` from: `tf.float32, tf.int32`. +> Defaults to `tf.float32`. +> name: A name for the operation (optional). +> +> Returns: +> A `Tensor` of type `out_type`. +> """ +> ``` + +<code class="lang-c++"><pre> +\#include "tensorflow/core/framework/op_kernel.h"<br/> +class ZeroOut<b>Int32</b>Op : public OpKernel { + // as before +};<br/> +class ZeroOut<b>Float</b>Op : public OpKernel { + public: + explicit ZeroOut<b>Float</b>Op(OpKernelConstruction\* context) + : OpKernel(context) {}<br/> + void Compute(OpKernelContext\* context) override { + // Grab the input tensor + const Tensor& input\_tensor = context->input(0); + auto input = input\_tensor.flat<<b>float</b>>();<br/> + // Create an output tensor + Tensor* output = NULL; + OP\_REQUIRES\_OK(context, + context->allocate\_output(0, input_tensor.shape(), &output)); + auto output\_flat = output->template flat<<b>float</b>>();<br/> + // Set all the elements of the output tensor to 0 + const int N = input.size(); + for (int i = 0; i < N; i++) { + output\_flat(i) = 0; + }<br/> + // Preserve the first input value + if (N > 0) output\_flat(0) = input(0); + } +};<br/><b> +// Note that TypeConstraint<int32>("T") means that attr "T" (defined +// in the Op registration above) must be "int32" to use this template +// instantiation.</b> +REGISTER\_KERNEL\_BUILDER( + Name("ZeroOut") + .Device(DEVICE\_CPU) + <b>.TypeConstraint<int32>("T"),</b> + ZeroOutOp<b>Int32</b>); +<b>REGISTER\_KERNEL\_BUILDER( + Name("ZeroOut") + .Device(DEVICE\_CPU) + .TypeConstraint<float>("T"), + ZeroOutFloatOp); +</b></pre></code> + +> To preserve [backwards compatibility](#backwards-compatibility), you should +> specify a [default value](#default-values-constraints) when adding an attr to +> an existing op: +> +> <code class="lang-c++"><pre> +> REGISTER\_OP("ZeroOut") +> <b>.Attr("T: {float, int32} = DT_INT32")</b> +> .Input("to_zero: T") +> .Output("zeroed: T") +> </pre></code> + +Lets say you wanted to add more types, say `double`: + +<code class="lang-c++"><pre> +REGISTER\_OP("ZeroOut") + <b>.Attr("T: {float, <b>double,</b> int32}")</b> + .Input("to_zero: <b>T</b>") + .Output("zeroed: <b>T</b>"); +</pre></code> + +Instead of writing another `OpKernel` with redundant code as above, often you +will be able to use a C++ template instead. You will still have one kernel +registration (`REGISTER\_KERNEL\_BUILDER` call) per overload. + +<code class="lang-c++"><pre> +<b>template <typename T></b> +class ZeroOutOp : public OpKernel { + public: + explicit ZeroOutOp(OpKernelConstruction\* context) : OpKernel(context) {}<br/> + void Compute(OpKernelContext\* context) override { + // Grab the input tensor + const Tensor& input\_tensor = context->input(0); + auto input = input\_tensor.flat<b><T></b>();<br/> + // Create an output tensor + Tensor* output = NULL; + OP\_REQUIRES\_OK(context, + context->allocate\_output(0, input_tensor.shape(), &output)); + auto output\_flat = output->template flat<b><T></b>();<br/> + // Set all the elements of the output tensor to 0 + const int N = input.size(); + for (int i = 0; i < N; i++) { + output\_flat(i) = 0; + }<br/> + // Preserve the first input value + if (N > 0) output\_flat(0) = input(0); + } +};<br/> +// Note that TypeConstraint<int32>("T") means that attr "T" (defined +// in the Op registration above) must be "int32" to use this template +// instantiation.</b> +REGISTER\_KERNEL\_BUILDER( + Name("ZeroOut") + .Device(DEVICE\_CPU) + .TypeConstraint<int32>("T"), + <b>ZeroOutOp<int32></b>); +REGISTER\_KERNEL\_BUILDER( + Name("ZeroOut") + .Device(DEVICE\_CPU) + .TypeConstraint<float>("T"), + <b>ZeroOutOp<float></b>); +<b>REGISTER\_KERNEL\_BUILDER( + Name("ZeroOut") + .Device(DEVICE\_CPU) + .TypeConstraint<double>("T"), + ZeroOutOp<double>); +</b></pre></code> + +If you have more than a couple overloads, you can put the registration in a +macro. + +```c++ +#include "tensorflow/core/framework/op_kernel.h" + +#define REGISTER_KERNEL(type) \ + REGISTER_KERNEL_BUILDER( \ + Name("ZeroOut").Device(DEVICE_CPU).TypeConstraint<type>("T"), \ + ZeroOutOp<type>) + +REGISTER_KERNEL(int32); +REGISTER_KERNEL(float); +REGISTER_KERNEL(double); + +#undef REGISTER_KERNEL +``` + +Depending on the list of types you are registering the kernel for, you may be +able to use a macro provided by +[`tensorflow/core/framework/register_types.h`][register_types]: + +```c++ +#include "tensorflow/core/framework/op_kernel.h" +#include "tensorflow/core/framework/register_types.h" + +REGISTER_OP("ZeroOut") + .Attr("T: realnumbertypes") + .Input("to_zero: T") + .Output("zeroed: T"); + +template <typename T> +class ZeroOutOp : public OpKernel { ... }; + +#define REGISTER_KERNEL(type) \ + REGISTER_KERNEL_BUILDER( \ + Name("ZeroOut").Device(DEVICE_CPU).TypeConstraint<type>("T"), \ + ZeroOutOp<type>) + +TF_CALL_REAL_NUMBER_TYPES(REGISTER_KERNEL); + +#undef REGISTER_KERNEL +``` + +#### List Inputs and Outputs {#list-input-output} + +In addition to being able to accept or produce different types, ops can consume +or produce a variable number of tensors. + +In the next example, the attr `T` holds a *list* of types, and is used as the +type of both the input `in` and the output `out`. The input and output are +lists of tensors of that type (and the number and types of tensors in the output +are the same as the input, since both have type `T`). + +```c++ +REGISTER_OP("PolymorphicListExample") + .Attr("T: list(type)") + .Input("in: T") + .Output("out: T"); +``` + +You can also place restrictions on what types can be specified in the list. In +this next case, the input is a list of `float` and `double` tensors. The Op +accepts, for example, input types `(float, double, float)` and in that case the +output type would also be `(float, double, float)`. + +```c++ +REGISTER_OP("ListTypeRestrictionExample") + .Attr("T: list({float, double})") + .Input("in: T") + .Output("out: T"); +``` + +If you want all the tensors in a list to be of the same type, you might do +something like: + +```c++ +REGISTER_OP("IntListInputExample") + .Attr("N: int") + .Input("in: N * int32") + .Output("out: int32"); +``` + +This accepts a list of `int32` tensors, and uses an `int` attr `N` to +specify the length of the list. + +This can be made [type polymorphic](#type-polymorphism) as well. In the next +example, the input is a list of tensors (with length `"N"`) of the same (but +unspecified) type (`"T"`), and the output is a single tensor of matching type: + +```c++ +REGISTER_OP("SameListInputExample") + .Attr("N: int") + .Attr("T: type") + .Input("in: N * T") + .Output("out: T"); +``` + +By default, tensor lists have a minimum length of 1. You can change that default +using +[a `">="` constraint on the corresponding attr](#default-values-constraints). +In this next example, the input is a list of at least 2 `int32` tensors: + +```c++ +REGISTER_OP("MinLengthIntListExample") + .Attr("N: int >= 2") + .Input("in: N * int32") + .Output("out: int32"); +``` + +The same syntax works with `"list(type)"` attrs: + +```c++ +REGISTER_OP("MinimumLengthPolymorphicListExample") + .Attr("T: list(type) >= 3") + .Input("in: T") + .Output("out: T"); +``` + +### Inputs and Outputs <div class="md-anchor" id="AUTOGENERATED-inputs-and-outputs">{#AUTOGENERATED-inputs-and-outputs}</div> + +To summarize the above, an Op registration can have multiple inputs and outputs: + +```c++ +REGISTER_OP("MultipleInsAndOuts") + .Input("y: int32") + .Input("z: float") + .Output("a: string") + .Output("b: int32"); +``` + +Each input or output spec is of the form: + +``` +<name>: <io-type-expr> +``` + +where `<name>` begins with a letter and can be composed of alphanumeric +characters and underscores. `<io-type-expr>` is one of the following type +expressions: + +* `<type>`, where `<type>` is a supported input type (e.g. `float`, `int32`, + `string`). This specifies a single tensor of the given type. + + See + [the list of supported Tensor types](../../resources/dims_types.md#data-types). + + ```c++ + REGISTER_OP("BuiltInTypesExample") + .Input("integers: int32") + .Input("complex_numbers: scomplex64"); + ``` + +* `<attr-type>`, where `<attr-type>` is the name of an [Attr](#attrs) with type + `type` or `list(type)` (with a possible type restriction). This syntax allows + for [polymorphic ops](#polymorphism). + + ```c++ + REGISTER_OP("PolymorphicSingleInput") + .Attr("T: type") + .Input("in: T); + + REGISTER_OP("RestrictedPolymorphicSingleInput") + .Attr("T: {int32, int64}") + .Input("in: T); + ``` + + Referencing an attr of type `list(type)` allows you to accept a sequence of + tensors. + + ```c++ + REGISTER_OP("ArbitraryTensorSequenceExample") + .Attr("T: list(type)") + .Input("in: T") + .Output("out: T"); + + REGISTER_OP("RestrictedTensorSequenceExample") + .Attr("T: list({int32, int64})") + .Input("in: T") + .Output("out: T"); + ``` + + Note that the number and types of tensors in the output `out` is the same as + in the input `in`, since both are of type `T`. + +* For a sequence of tensors with the same type: `<number> * <type>`, where + `<number>` is the name of an [Attr](#attrs) with type `int`. The `<type>` can + either be + [a specific type like `int32` or `float`](../../resources/dims_types.md#data-types), + or the name of an attr with type `type`. As an example of the first, this + Op accepts a list of `int32` tensors: + + ```c++ + REGISTER_OP("Int32SequenceExample") + .Attr("NumTensors: int") + .Input("in: NumTensors * int32") + ``` + + Whereas this Op accepts a list of tensors of any type, as long as they are all + the same: + + ```c++ + REGISTER_OP("SameTypeSequenceExample") + .Attr("NumTensors: int") + .Attr("T: type") + .Input("in: NumTensors * T") + ``` + +* For a reference to a tensor: `Ref(<type>)`, where `<type>` is one of the + previous types. + +> A note on naming: Any attr used in the type of an input will be inferred. By +> convention those inferred attrs use capital names (like `T` or `N`). +> Otherwise inputs, outputs, and attrs have names like function parameters +> (e.g. `num_outputs`). For more details, see the +> [earlier note on naming](#naming). + +For more details, see +[`tensorflow/core/framework/op_def_builder.h`][op_def_builder]. + +### Backwards compatibility <div class="md-anchor" id="AUTOGENERATED-backwards-compatibility">{#AUTOGENERATED-backwards-compatibility}</div> + +In general, changes to specifications must be backwards-compatible: changing the +specification of an Op must not break prior serialized GraphDefs constructed +from older specfications. + +There are several ways to preserve backwards-compatibility. + +1. Any new attrs added to an operation must have default values defined, and + with that default value the Op must have the original behavior. To change an + operation from not polymorphic to polymorphic, you *must* give a default + value to the new type attr to preserve the original signature by default. For + example, if your operation was: + + ```c++ + REGISTER_OP("MyGeneralUnaryOp") + .Input("in: float") + .Output("out: float"); + ``` + + you can make it polymorphic in a backwards-compatible way using: + + ```c++ + REGISTER_OP("MyGeneralUnaryOp") + .Input("in: T") + .Output("out: T") + .Attr("T: numerictype = float"); + ``` + +1. You can safely make a constraint on an attr less restrictive. For example, + you can change from `{int32, int64}` to `{int32, int64, float}` or from + `{"apple", "orange"}` to `{"apple", "banana", "orange"}`. + +1. Namespace any new Ops you create, by prefixing the Op names with something + unique to your project. This avoids having your Op colliding with any Ops + that might be included in future versions of Tensorflow. + +1. Plan ahead! Try to anticipate future uses for the Op. Some signature changes + can't be done in a compatible way (for example, adding an input, or making a + single input into a list). + +If you cannot make your change to an operation backwards compatible, then +create a new operation with a new name with the new semantics. + +## GPU Support <div class="md-anchor" id="mult-archs">{#mult-archs}</div> + +You can implement different OpKernels and register one for CPU and another for +GPU, just like you can [register kernels for different types](#polymorphism). +There are several examples of kernels with GPU support in +[tensorflow/core/kernels/](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/). +Notice some kernels have a CPU version in a `.cc` file, a GPU version in a file +ending in `_gpu.cu.cc`, and some code shared in common in a `.h` file. + +For example, the [`pad` op](../../api_docs/python/array_ops.md#pad) has +everything but the GPU kernel in [`tensorflow/core/kernels/pad_op.cc`][pad_op]. +The GPU kernel is in +[`tensorflow/core/kernels/pad_op_gpu.cu.cc`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/pad_op_gpu.cu.cc), +and the shared code is a templated class defined in +[`tensorflow/core/kernels/pad_op.h`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/pad_op.h). +One thing to note, even when the GPU kernel version of `pad` is used, it still +needs its `"paddings"` input in CPU memory. To mark that inputs or outputs are +kept on the CPU, add a `HostMemory()` call to the kernel registration, e.g.: + +```c++ +#define REGISTER_GPU_KERNEL(T) \ + REGISTER_KERNEL_BUILDER(Name("Pad") \ + .Device(DEVICE_GPU) \ + .TypeConstraint<T>("T") \ + .HostMemory("paddings"), \ + PadOp<GPUDevice, T>) +``` + +## Implement the gradient in Python <div class="md-anchor" id="AUTOGENERATED-implement-the-gradient-in-python">{#AUTOGENERATED-implement-the-gradient-in-python}</div> + +[TODO]:# (Write this!) + +## Implement a shape function in Python <div class="md-anchor" id="AUTOGENERATED-implement-a-shape-function-in-python">{#AUTOGENERATED-implement-a-shape-function-in-python}</div> + +The TensorFlow Python API has a feature called "shape inference" that provides +information about the shapes of tensors without having to execute the +graph. Shape inference is supported by "shape functions" that are registered for +each op type, and perform two roles: asserting that the shapes of the inputs are +compatible, and specifying the shapes for the outputs. A shape function is a +Python function that takes an +[`Operation`](../../api_docs/python/framework.md#Operation) as input, and +returns a list of +[`TensorShape`](../../api_docs/python/framework.md#TensorShape) objects (one per +output of the op). To register a shape function, apply the +[`tf.RegisterShape` decorator](../../api_docs/python/framework.md#RegisterShape) +to a shape function. For example, the +[ZeroOut op defined above](#define_interface) would have a shape function like +the following: + +```python +@tf.RegisterShape("ZeroOut"): +def _zero_out_shape(op): + """Shape function for the ZeroOut op. + + This is the unconstrained version of ZeroOut, which produces an output + with the same shape as its input. + """ + return [op.inputs[0].get_shape()] +``` + +A shape function can also constrain the shape of an input. For the version of +[ZeroOut with a vector shape constraint](#validation), the shape function +would be as follows: + +```python +@tf.RegisterShape("ZeroOut"): +def _zero_out_shape(op): + """Shape function for the ZeroOut op. + + This is the constrained version of ZeroOut, which requires the input to + have rank 1 (a vector). + """ + input_shape = op.inputs[0].get_shape().with_rank(1) + return [input_shape] +``` + +If your op is [polymorphic with multiple inputs](#polymorphism), use the +properties of the operation to determine the number of shapes to check: + +``` +@tf.RegisterShape("IntListInputExample") +def _int_list_input_example_shape(op): + """Shape function for the "IntListInputExample" op. + + All inputs and the output are matrices of the same size. + """ + output_shape = tf.TensorShape(None) + for input in op.inputs: + output_shape = output_shape.merge_with(input.get_shape().with_rank(2)) + return [output_shape] +``` + +Since shape inference is an optional feature, and the shapes of tensors may vary +dynamically, shape functions must be robust to incomplete shape information for +any of the inputs. The [`merge_with()`](../../api_docs/python/framework.md) +method allows the caller to assert that two shapes are the same, even if either +or both of them do not have complete information. Shape functions are defined +for all of the +[standard Python ops](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/ops/), +and provide many different usage examples. + +[core-array_ops]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/ops/array_ops.cc +[python-user_ops]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/user_ops/user_ops.py +[tf-kernels]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/ +[user_ops]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/user_ops/ +[pad_op]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/pad_op.cc +[standard_ops-py]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/ops/standard_ops.py +[standard_ops-cc]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/cc/ops/standard_ops.h +[python-BUILD]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/BUILD +[validation-macros]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/lib/core/errors.h +[op_def_builder]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/op_def_builder.h +[register_types]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/register_types.h +[FinalizeAttr]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/op_def_builder.cc#FinalizeAttr +[DataTypeString]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/types.cc#DataTypeString +[python-BUILD]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/BUILD +[types-proto]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/types.proto +[TensorShapeProto]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/tensor_shape.proto +[TensorProto]:https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/tensor.proto diff --git a/tensorflow/g3doc/how_tos/adding_an_op/register_kernels.cc b/tensorflow/g3doc/how_tos/adding_an_op/register_kernels.cc new file mode 100644 index 0000000000..3d2f50d16e --- /dev/null +++ b/tensorflow/g3doc/how_tos/adding_an_op/register_kernels.cc @@ -0,0 +1,64 @@ +#include "tensorflow/core/framework/op_kernel.h" +#include "tensorflow/core/framework/register_types.h" + +using namespace tensorflow; + +template <typename T> +class ZeroOutOp : public OpKernel { + public: + explicit ZeroOutOp(OpKernelConstruction* context) : OpKernel(context) {} + + void Compute(OpKernelContext* context) override { + // Grab the input tensor + const Tensor& input_tensor = context->input(0); + auto input = input_tensor.flat<T>(); + + // Create an output tensor + Tensor* output = NULL; + OP_REQUIRES_OK(context, + context->allocate_output(0, input_tensor.shape(), &output)); + auto output_flat = output->template flat<T>(); + + // Set all the elements of the output tensor to 0 + const int N = input.size(); + for (int i = 0; i < N; i++) { + output_flat(i) = 0; + } + + // Preserve the first input value + if (N > 0) output_flat(0) = input(0); + } +}; + +REGISTER_KERNEL_BUILDER(Name("ZeroOut") + .Device(DEVICE_CPU) + .TypeConstraint<float>("T"), + ZeroOutOp<float>); +REGISTER_KERNEL_BUILDER(Name("ZeroOut") + .Device(DEVICE_CPU) + .TypeConstraint<double>("T"), + ZeroOutOp<double>); +REGISTER_KERNEL_BUILDER(Name("ZeroOut") + .Device(DEVICE_CPU) + .TypeConstraint<int>("T"), + ZeroOutOp<int>); + +#define REGISTER_KERNEL(type) \ + REGISTER_KERNEL_BUILDER( \ + Name("ZeroOut").Device(DEVICE_CPU).TypeConstraint<type>("T"), \ + ZeroOutOp<type>) + +REGISTER_KERNEL(float); +REGISTER_KERNEL(double); +REGISTER_KERNEL(int32); + +#undef REGISTER_KERNEL + +#define REGISTER_KERNEL(type) \ + REGISTER_KERNEL_BUILDER( \ + Name("ZeroOut").Device(DEVICE_CPU).TypeConstraint<type>("T"), \ + ZeroOutOp<type>) + +TF_CALL_REAL_NUMBER_TYPES(REGISTER_KERNEL); + +#undef REGISTER_KERNEL diff --git a/tensorflow/g3doc/how_tos/adding_an_op/zero_out_1_test.py b/tensorflow/g3doc/how_tos/adding_an_op/zero_out_1_test.py new file mode 100644 index 0000000000..321f603adf --- /dev/null +++ b/tensorflow/g3doc/how_tos/adding_an_op/zero_out_1_test.py @@ -0,0 +1,18 @@ +"""Test for version 1 of the zero_out op.""" + +import tensorflow.python.platform + +import tensorflow as tf +from tensorflow.g3doc.how_tos.adding_an_op import gen_zero_out_op_1 + + +class ZeroOut1Test(tf.test.TestCase): + + def test(self): + with self.test_session(): + result = gen_zero_out_op_1.zero_out([5, 4, 3, 2, 1]) + self.assertAllEqual(result.eval(), [5, 0, 0, 0, 0]) + + +if __name__ == '__main__': + tf.test.main() diff --git a/tensorflow/g3doc/how_tos/adding_an_op/zero_out_op_kernel_1.cc b/tensorflow/g3doc/how_tos/adding_an_op/zero_out_op_kernel_1.cc new file mode 100644 index 0000000000..e960adc047 --- /dev/null +++ b/tensorflow/g3doc/how_tos/adding_an_op/zero_out_op_kernel_1.cc @@ -0,0 +1,43 @@ +#include "tensorflow/core/framework/op.h" +#include "tensorflow/core/framework/op_kernel.h" + +using namespace tensorflow; + +REGISTER_OP("ZeroOut") + .Input("to_zero: int32") + .Output("zeroed: int32") + .Doc(R"doc( +Zeros out all but the first value of a Tensor. + +zeroed: A Tensor whose first value is identical to `to_zero`, and 0 + otherwise. + +)doc"); + +class ZeroOutOp : public OpKernel { + public: + explicit ZeroOutOp(OpKernelConstruction* context) : OpKernel(context) {} + + void Compute(OpKernelContext* context) override { + // Grab the input tensor + const Tensor& input_tensor = context->input(0); + auto input = input_tensor.flat<int32>(); + + // Create an output tensor + Tensor* output_tensor = NULL; + OP_REQUIRES_OK(context, context->allocate_output(0, input_tensor.shape(), + &output_tensor)); + auto output = output_tensor->template flat<int32>(); + + // Set all but the first element of the output tensor to 0. + const int N = input.size(); + for (int i = 1; i < N; i++) { + output(i) = 0; + } + + // Preserve the first input value. + if (N > 0) output(0) = input(0); + } +}; + +REGISTER_KERNEL_BUILDER(Name("ZeroOut").Device(DEVICE_CPU), ZeroOutOp); diff --git a/tensorflow/g3doc/how_tos/graph_viz/index.md b/tensorflow/g3doc/how_tos/graph_viz/index.md new file mode 100644 index 0000000000..f0a1fc2fe7 --- /dev/null +++ b/tensorflow/g3doc/how_tos/graph_viz/index.md @@ -0,0 +1,205 @@ +# TensorBoard: Visualizing Your Graph + +TensorFlow computation graphs are powerful but complicated. The graph visualization can help you understand and debug them. Here's an example of the visualization at work. + + +*Visualization of a TensorFlow graph.* + +To see your own graph, run TensorBoard pointing it to the log directory of the job, click on the graph tab on the top pane and select the appropriate run using the menu at the upper left corner. For in depth information on how to run TensorBoard and make sure you are logging all the necessary information, see [Summaries and TensorBoard](../summaries_and_tensorboard/index.md). + +## Name scoping and nodes + +Typical TensorFlow graphs can have many thousands of nodes--far too many to see easily all at once, or even to lay out using standard graph tools. To simplify, variable's name can be scoped and the visualization uses this information to define a hierarchy structure on the nodes in the graph, and by default only shows the top of this hierarchy. Here is an example that defines three operations under the `hidden` name scope using [`tf.name_scope()`](https://tensorflow.org/api_docs/python/framework.html?cl=head#name_scope): + +```python +import tensorflow as tf + +with tf.name_scope('hidden') as scope: + a = tf.constant(5, name='alpha') + W = tf.Variable(tf.random_uniform([1, 2], -1.0, 1.0), name='weights') + b = tf.Variable(tf.zeros([1]), name='biases') +``` + +This results in the following three op names: + +* *hidden*/alpha +* *hidden*/weights +* *hidden*/biases + +The visualization will, by default, collapse all three into a node labeled `hidden`. +The extra detail isn't lost. You can double-click, or click +on the orange `+` sign in the top right to expand the node, and then you'll see +three subnodes, for `alpha`, `weights` and `biases`. + +Here's a real-life example of a more complicated node in its initial and +expanded states. + +<table width="100%;"> + <tr> + <td style="width: 50%;"> + <img src="./pool1_collapsed.png" alt="Unexpanded name scope" title="Unexpanded name scope" /> + </td> + <td style="width: 50%;"> + <img src="./pool1_expanded.png" alt="Expanded name scope" title="Expanded name scope" /> + </td> + </tr> + <tr> + <td style="width: 50%;"> + Initial view of top-level name scope <code>pool_1</code>. Clicking on the orange <code>+</code> button on the top right or double-clicking on the node itself will expand it. + </td> + <td style="width: 50%;"> + Expanded view of <code>pool_1</code> name scope. Clicking on the orange <code>-</code> button on the top right or double-clicking on the node itself will collapse the name scope. + </td> + </tr> +</table> + +Grouping nodes by name scopes is critical to making a legible graph. If you're +building a model, name scopes give you control over the resulting visualization. +**The better your name scopes, the better your visualization.** + +The figure above illustrates a second aspect of the visualization. TensorFlow +graphs have two kinds of connections: data dependencies and control +dependencies. Data dependencies show the flow of tensors between two ops and +are shown as solid arrows, while control dependencies use dotted lines. In the +expanded view (right side of the figure above) all the connections are data +dependencies with the exception of the dotted line connecting `CheckNumerics` +and `control_dependency`. + +There's a second trick to simplifying the layout. Most TensorFlow graphs have a +few nodes with many connections to other nodes. For example, many nodes might +have a control dependencies on an initialization step. Drawing all edges +between the `init` node and its dependencies would create a very cluttered +view. + +To reduce clutter, the visualization separates out all high-degree nodes to an +"auxiliary" area on the right and doesn't draw lines to represent their edges. +Instead of lines, we draw small "node icons" to indicate the connections. +Separating out the auxiliary nodes typically doesn't remove critical +information since these nodes are usually related to bookkeeping functions. + +<table width="100%;"> + <tr> + <td style="width: 50%;"> + <img src="./conv_1.png" alt="conv_1 is part of the main graph" title="conv_1 is part of the main graph" /> + </td> + <td style="width: 50%;"> + <img src="./save.png" alt="save is extracted as auxiliary node" title="save is extracted as auxiliary node" /> + </td> + </tr> + <tr> + <td style="width: 50%;"> + Node <code>conv_1</code> is connected to <code>save</code>. Note the little <code>save</code> node icon on its right. + </td> + <td style="width: 50%;"> + <code>save</code> has a high degree, and will appear as an auxiliary node. The connection with <code>conv_1</code> is shown as a node icon on its left. To further reduce clutter, since <code>save</code> has a lot of connections, we show the first 5 and abbreviate the others as <code>... 12 more</code>. + </td> + </tr> +</table> + +One last structural simplification is "series collapsing". Sequential +motifs--that is, nodes whose names differ by a number at the end and have +isomorphic structures--are collapsed into a single "stack" of nodes, as shown +below. For networks with long sequences, this greatly simplifies the view. As +with hierarchical nodes, double-clicking expands the series. + +<table width="100%;"> + <tr> + <td style="width: 50%;"> + <img src="./series.png" alt="Sequence of nodes" title="Sequence of nodes" /> + </td> + <td style="width: 50%;"> + <img src="./series_expanded.png" alt="Expanded sequence of nodes" title="Expanded sequence of nodes" /> + </td> + </tr> + <tr> + <td style="width: 50%;"> + A collapsed view of a node sequence. + </td> + <td style="width: 50%;"> + A small piece of the expanded view, after double-click. + </td> + </tr> +</table> + +Finally, as one last aid to legibility, the visualization uses special icons +for constants and summary nodes. To summarize, here's a table of node symbols: + +Symbol | Meaning +--- | --- + | "High-level" node representing a name scope. Double-click to expand a high-level node. + | Sequence of numbered nodes that are not connected to each other. + | Sequence of numbered nodes that are connected to each other. + | An individual operation node. + | A constant. + | A summary node. + | Edge showing the data flow between operations. + | Edge showing the control dependency between operations. + | A reference edge showing that the outgoing operation node can mutate the incoming tensor. + +## Interaction + +Navigate the graph by panning and zooming. Click and drag to pan, and use a +scroll gesture to zoom. Double-click on a node, or click on its `+` button, to +expand a name scope that represents a group of operations. To easily keep +track of the current viewpoint when zooming and panning, there is a minimap in +the bottom right corner. + +To close an open node, double-click it again or click its `-` button. You can +also click once to select a node. It will turn a darker color, and details +about it and the nodes it connects to will appear in the info card at upper +right corner of the visualization. + +<table width="100%;"> + <tr> + <td style="width: 50%;"> + <img src="./infocard.png" alt="Info card of a name scope" title="Info card of a name scope" /> + </td> + <td style="width: 50%;"> + <img src="./infocard_op.png" alt="Info card of operation node" title="Info card of operation node" /> + </td> + </tr> + <tr> + <td style="width: 50%;"> + Info card showing detailed information for the <code>conv2</code> name scope. The inputs and outputs are combined from the inputs and outputs of the operation nodes inside the name scope. For name scopes no attributes are shown. + </td> + <td style="width: 50%;"> + Info card showing detailed information for the <code>DecodeRaw</code> operation node. In addition to inputs and outputs, the card shows the device and the attributes associated with the current operation. + </td> + </tr> +</table> + +Selection can also be helpful in understanding high-degree nodes. Select any +high-degree node, and the corresponding "node icons" for its other connections +will be selected as well. This makes it easy, for example, to see which nodes +are being saved--and which aren't. + +Clicking on a node name in the info card will select it. If necessary, the +viewpoint will automatically pan so that the node is visible. + +Finally, you can choose two color schemes for your graph, using the color menu +above the legend. The default "Structure View" shows structure: when two +high-level nodes have the same structure, they appear in the same color of the +rainbow. Uniquely structured nodes are gray. There's a second view, which shows +what device the different operations run on. Name scopes are colored +proportionally to the fraction of devices for the operations inside them. + +The images below give an illustration for a piece of a real-life graph. + +<table width="100%;"> + <tr> + <td style="width: 50%;"> + <img src="./colorby_structure.png" alt="Color by structure" title="Color by structure" /> + </td> + <td style="width: 50%;"> + <img src="./colorby_device.png" alt="Color by device" title="Color by device" /> + </td> + </tr> + <tr> + <td style="width: 50%;"> + Structure view: The gray nodes have unique structure. The orange <code>conv1</code> and <code>conv2</code> nodes have the same structure, and analogously for nodes with other colors. + </td> + <td style="width: 50%;"> + Device view: Name scopes are colored proportionally to the fraction of devices of the operation nodes inside them. Here, purple means GPU and the green is CPU. + </td> + </tr> +</table> diff --git a/tensorflow/g3doc/how_tos/index.md b/tensorflow/g3doc/how_tos/index.md new file mode 100644 index 0000000000..f5c74715e8 --- /dev/null +++ b/tensorflow/g3doc/how_tos/index.md @@ -0,0 +1,102 @@ +# Overview + + +## Variables: Creation, Initializing, Saving, and Restoring + +TensorFlow Variables are in-memory buffers containing tensors. Learn how to +use them to hold and update model parameters during training. + +[View Tutorial](variables/index.md) + + +## TensorFlow Mechanics 101 + +A step-by-step walk through of the details of using TensorFlow infrastructure +to train models at scale, using MNIST handwritten digit recognition as a toy +example. + +[View Tutorial](../tutorials/mnist/tf/index.md) + + +## TensorBoard: Visualizing Your Training + +TensorBoard is a useful tool for visualizing the training and evaluation of +your model(s). This tutorial describes how to build and run TensorBoard as well +as how to add Summary ops to automatically output data to the Events files that +TensorBoard uses for display. + +[View Tutorial](summaries_and_tensorboard/index.md) + + +## TensorBoard: Visualizing Your Graph + +This tutorial describes how to use the graph visualizer in TensorBoard to help +you understand the dataflow graph and debug it. + +[View Tutorial](graph_viz/index.md) + + +## Reading Data + +This tutorial describes the three main methods of getting data into your +TensorFlow program: Feeding, Reading and Preloading. + +[View Tutorial](reading_data/index.md) + + +## Threading and Queues + +This tutorial describes the various constructs implemented by TensorFlow +to facilitate asynchronous and concurrent training. + +[View Tutorial](threading_and_queues/index.md) + + +## Adding a New Op + +TensorFlow already has a large suite of node operations from which you can +compose in your graph, but here are the details of how to add you own custom Op. + +[View Tutorial](adding_an_op/index.md) + + +## New Data Formats + +If you have a sizable custom data set, you may want to consider extending +TensorFlow to read your data directly in it's native format. Here's how. + +[View Tutorial](new_data_formats/index.md) + + +## Using One or More GPUs + +This tutorial describes how to construct and execute models on GPU(s). + +[View Tutorial](using_gpu/index.md) + + +## Sharing Variables + +When deploying large models on multiple GPUs, or when unrolling complex LSTMs +or RNNs, it is often necessary to access the same Variable objects from +different locations in the model construction code. + +The "Variable Scope" mechanism is designed to facilitate that. + +[View Tutorial](variable_scope/index.md) + +<div class='sections-order' style="display: none;"> +<!-- +<!-- variables/index.md --> +<!-- ../tutorials/mnist/tf/index.md --> +<!-- summaries_and_tensorboard/index.md --> +<!-- graph_viz/index.md --> +<!-- reading_data/index.md --> +<!-- threading_and_queues/index.md --> +<!-- adding_an_op/index.md --> +<!-- new_data_formats/index.md --> +<!-- using_gpu/index.md --> +<!-- variable_scope/index.md --> +--> +</div> + diff --git a/tensorflow/g3doc/how_tos/new_data_formats/index.md b/tensorflow/g3doc/how_tos/new_data_formats/index.md new file mode 100644 index 0000000000..b1b09fe1ff --- /dev/null +++ b/tensorflow/g3doc/how_tos/new_data_formats/index.md @@ -0,0 +1,225 @@ +# Extending TF: Supporting new data formats + +PREREQUISITES: + +* Some familiarity with C++. +* Must have + [downloaded TensorFlow source](../../get_started/os_setup.md#source), and be + able to build it. + +We divide the task of supporting a file format into two pieces: + +* File formats: We use a *Reader* Op to read a *record* (which can be any + string) from a file. +* Record formats: We use decoder or parsing Ops to turn a string record + into tensors usable by TensorFlow. + +For example, to read a +[CSV file](https://en.wikipedia.org/wiki/Comma-separated_values), we use +[a Reader for text files](../../api_docs/python/io_ops.md#TextLineReader) +followed by +[an Op that parses CSV data from a line of text](../../api_docs/python/io_ops.md#decode_csv). + +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Writing a Reader for a file format](#AUTOGENERATED-writing-a-reader-for-a-file-format) +* [Writing an Op for a record format](#AUTOGENERATED-writing-an-op-for-a-record-format) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Writing a Reader for a file format <div class="md-anchor" id="AUTOGENERATED-writing-a-reader-for-a-file-format">{#AUTOGENERATED-writing-a-reader-for-a-file-format}</div> + +A `Reader` is something that reads records from a file. There are some examples +of Reader Ops already built into TensorFlow: + +* [`tf.TFRecordReader`](../../api_docs/python/io_ops.md#TFRecordReader) + ([source in kernels/tf_record_reader_op.cc](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/tf_record_reader_op.cc)) +* [`tf.FixedLengthRecordReader`](../../api_docs/python/io_ops.md#FixedLengthRecordReader) + ([source in kernels/fixed_length_record_reader_op.cc](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/fixed_length_record_reader_op.cc)) +* [`tf.TextLineReader`](../../api_docs/python/io_ops.md#TextLineReader) + ([source in kernels/text_line_reader_op.cc](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/text_line_reader_op.cc)) + +You can see these all expose the same interface, the only differences +are in their constructors. The most important method is `read()`. +It takes a queue argument, which is where it gets filenames to +read from whenever it needs one (e.g. when the `read` op first runs, or +the previous `read` reads the last record from a file). It produces +two scalar tensors: a string key and and a string value. + +To create a new reader called `SomeReader`, you will need to: + +1. In C++, define a subclass of + [`tensorflow::ReaderBase`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/reader_base.h) + called `SomeReader`. +2. In C++, register a new reader op and kernel with the name `"SomeReader"`. +3. In Python, define a subclass of [`tf.ReaderBase`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/ops/io_ops.py) called `SomeReader`. + +You can put all the C++ code in a file in +`tensorflow/core/user_ops/some_reader_op.cc`. The code to read a file will live +in a descendant of the C++ `ReaderBase` class, which is defined in +[tensorflow/core/kernels/reader_base.h](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/kernels/reader_base.h). +You will need to implement the following methods: + +* `OnWorkStartedLocked`: open the next file +* `ReadLocked`: read a record or report EOF/error +* `OnWorkFinishedLocked`: close the current file, and +* `ResetLocked`: get a clean slate after, e.g., an error + +These methods have names ending in "Locked" since `ReaderBase` makes sure +to acquire a mutex before calling any of these methods, so you generally don't +have to worry about thread safety (though that only protects the members of the +class, not global state). + +For `OnWorkStartedLocked`, the name of the file to open is the value returned by +the `current_work()` method. `ReadLocked()` has this signature: + +```c++ +Status ReadLocked(string* key, string* value, bool* produced, bool* at_end) +``` + +If `ReadLocked()` successfully reads a record from the file, it should fill in: + +* `*key`: with an identifier for the record, that a human could use to find + this record again. You can include the filename from `current_work()`, + and append a record number or whatever. +* `*value`: with the contents of the record. +* `*produced`: set to `true`. + +If you hit the end of a file (EOF), set `*at_end` to `true`. In either case, +return `Status::OK()`. If there is an error, simply return it using one of the +helper functions from +[tensorflow/core/lib/core/errors.h](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/lib/core/errors.h) +without modifying any arguments. + +Next you will create the actual Reader op. It will help if you are familiar +with [the adding an op how-to](../adding_an_op/index.md). The main steps +are: + +* Registering the op. +* Define and register an `OpKernel`. + +To register the op, you will use a `REGISTER_OP()` call defined in +[tensorflow/core/framework/op.h](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/op.h). +Reader ops never take any input and always have a single output with type +`Ref(string)`. They should always call `SetIsStateful()`, and have a string +`container` and `shared_name` attrs. You may optionally define additional attrs +for configuration or include documentation in a `Doc()`. For examples, see +[tensorflow/core/ops/io_ops.cc](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/ops/io_ops.cc), +e.g.: + +```c++ +#include "tensorflow/core/framework/op.h" + +REGISTER_OP("TextLineReader") + .Output("reader_handle: Ref(string)") + .Attr("skip_header_lines: int = 0") + .Attr("container: string = ''") + .Attr("shared_name: string = ''") + .SetIsStateful() + .Doc(R"doc( +A Reader that outputs the lines of a file delimited by '\n'. +)doc"); +``` + +To define an `OpKernel`, Readers can use the shortcut of descending from +`ReaderOpKernel`, defined in +[tensorflow/core/framework/reader_op_kernel.h](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/framework/reader_op_kernel.h), +and implement a constructor that calls `SetReaderFactory()`. After defining +your class, you will need to register it using `REGISTER_KERNEL_BUILDER(...)`. +An example with no attrs: + +```c++ +#include "tensorflow/core/framework/reader_op_kernel.h" + +class TFRecordReaderOp : public ReaderOpKernel { + public: + explicit TFRecordReaderOp(OpKernelConstruction* context) + : ReaderOpKernel(context) { + Env* env = context->env(); + SetReaderFactory([this, env]() { return new TFRecordReader(name(), env); }); + } +}; + +REGISTER_KERNEL_BUILDER(Name("TFRecordReader").Device(DEVICE_CPU), + TFRecordReaderOp); +``` + +An example with attrs: + +```c++ +#include "tensorflow/core/framework/reader_op_kernel.h" + +class TextLineReaderOp : public ReaderOpKernel { + public: + explicit TextLineReaderOp(OpKernelConstruction* context) + : ReaderOpKernel(context) { + int skip_header_lines = -1; + OP_REQUIRES_OK(context, + context->GetAttr("skip_header_lines", &skip_header_lines)); + OP_REQUIRES(context, skip_header_lines >= 0, + errors::InvalidArgument("skip_header_lines must be >= 0 not ", + skip_header_lines)); + Env* env = context->env(); + SetReaderFactory([this, skip_header_lines, env]() { + return new TextLineReader(name(), skip_header_lines, env); + }); + } +}; + +REGISTER_KERNEL_BUILDER(Name("TextLineReader").Device(DEVICE_CPU), + TextLineReaderOp); +``` + +The last step is to add the Python wrapper. You will import +`tensorflow.python.ops.io_ops` in +[tensorflow/python/user_ops/user_ops.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/user_ops/user_ops.py) +and add a descendant of [`io_ops.ReaderBase`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/ops/io_ops.py). + +```python +from tensorflow.python.framework import ops +from tensorflow.python.ops import common_shapes +from tensorflow.python.ops import io_ops + +class SomeReader(io_ops.ReaderBase): + + def __init__(self, name=None): + rr = gen_user_ops.some_reader(name=name) + super(SomeReader, self).__init__(rr) + + +ops.NoGradient("SomeReader") +ops.RegisterShape("SomeReader")(common_shapes.scalar_shape) +``` + +You can see some examples in +[`tensorflow/python/ops/io_ops.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/python/ops/io_ops.py). + +## Writing an Op for a record format <div class="md-anchor" id="AUTOGENERATED-writing-an-op-for-a-record-format">{#AUTOGENERATED-writing-an-op-for-a-record-format}</div> + +Generally this is an ordinary op that takes a scalar string record as input, and +so follow [the instructions to add an Op](../adding_an_op/index.md). You may +optionally take a scalar string key as input, and include that in error messages +reporting improperly formatted data. That way users can more easily track down +where the bad data came from. + +Examples of Ops useful for decoding records: + +* [`tf.parse_single_example`](../../api_docs/python/io_ops.md#parse_single_example) + (and + [`tf.parse_example`](../../api_docs/python/io_ops.md#parse_example)) +* [`tf.decode_csv`](../../api_docs/python/io_ops.md#decode_csv) +* [`tf.decode_raw`](../../api_docs/python/io_ops.md#decode_raw) + +Note that it can be useful to use multiple Ops to decode a particular record +format. For example, you may have an image saved as a string in +[a tf.train.Example protocol buffer](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/example/example.proto). +Depending on the format of that image, you might take the corresponding output +from a +[`tf.parse_single_example`](../../api_docs/python/io_ops.md#parse_single_example) +op and call [`tf.decode_jpeg`](../../api_docs/python/image.md#decode_jpeg), +[`tf.decode_png`](../../api_docs/python/image.md#decode_png), or +[`tf.decode_raw`](../../api_docs/python/io_ops.md#decode_raw). It is common to +take the output of `tf.decode_raw` and use +[`tf.slice`](../../api_docs/python/array_ops.md#slice) and +[`tf.reshape`](../../api_docs/python/array_ops.md#reshape) to extract pieces. diff --git a/tensorflow/g3doc/how_tos/reading_data/__init__.py b/tensorflow/g3doc/how_tos/reading_data/__init__.py new file mode 100755 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/how_tos/reading_data/__init__.py diff --git a/tensorflow/g3doc/how_tos/reading_data/convert_to_records.py b/tensorflow/g3doc/how_tos/reading_data/convert_to_records.py new file mode 100644 index 0000000000..1d510cdfa9 --- /dev/null +++ b/tensorflow/g3doc/how_tos/reading_data/convert_to_records.py @@ -0,0 +1,87 @@ +"""Converts MNIST data to TFRecords file format with Example protos.""" + +import os +import tensorflow.python.platform + +import numpy +import tensorflow as tf +from tensorflow.g3doc.tutorials.mnist import input_data + + +TRAIN_IMAGES = 'train-images-idx3-ubyte.gz' # MNIST filenames +TRAIN_LABELS = 'train-labels-idx1-ubyte.gz' +TEST_IMAGES = 't10k-images-idx3-ubyte.gz' +TEST_LABELS = 't10k-labels-idx1-ubyte.gz' + + +tf.app.flags.DEFINE_string('directory', 'data', + 'Directory to download data files and write the ' + 'converted result') +tf.app.flags.DEFINE_integer('validation_size', 5000, + 'Number of examples to separate from the training ' + 'data for the validation set.') +FLAGS = tf.app.flags.FLAGS + + +def _int64_feature(value): + return tf.train.Feature(int64_list=tf.train.Int64List(value=[value])) + + +def _bytes_feature(value): + return tf.train.Feature(bytes_list=tf.train.BytesList(value=[value])) + + +def convert_to(images, labels, name): + num_examples = labels.shape[0] + if images.shape[0] != num_examples: + raise ValueError("Images size %d does not match label size %d." % + (dat.shape[0], num_examples)) + rows = images.shape[1] + cols = images.shape[2] + depth = images.shape[3] + + filename = os.path.join(FLAGS.directory, name + '.tfrecords') + print 'Writing', filename + writer = tf.python_io.TFRecordWriter(filename) + for index in range(num_examples): + image_raw = images[index].tostring() + example = tf.train.Example(features=tf.train.Features(feature={ + 'height':_int64_feature(rows), + 'width':_int64_feature(cols), + 'depth':_int64_feature(depth), + 'label':_int64_feature(int(labels[index])), + 'image_raw':_bytes_feature(image_raw)})) + writer.write(example.SerializeToString()) + + +def main(argv): + # Get the data. + train_images_filename = input_data.maybe_download( + TRAIN_IMAGES, FLAGS.directory) + train_labels_filename = input_data.maybe_download( + TRAIN_LABELS, FLAGS.directory) + test_images_filename = input_data.maybe_download( + TEST_IMAGES, FLAGS.directory) + test_labels_filename = input_data.maybe_download( + TEST_LABELS, FLAGS.directory) + + # Extract it into numpy arrays. + train_images = input_data.extract_images(train_images_filename) + train_labels = input_data.extract_labels(train_labels_filename) + test_images = input_data.extract_images(test_images_filename) + test_labels = input_data.extract_labels(test_labels_filename) + + # Generate a validation set. + validation_images = train_images[:FLAGS.validation_size, :, :, :] + validation_labels = train_labels[:FLAGS.validation_size] + train_images = train_images[FLAGS.validation_size:, :, :, :] + train_labels = train_labels[FLAGS.validation_size:] + + # Convert to Examples and write the result to TFRecords. + convert_to(train_images, train_labels, 'train') + convert_to(validation_images, validation_labels, 'validation') + convert_to(test_images, test_labels, 'test') + + +if __name__ == '__main__': + tf.app.run() diff --git a/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded.py b/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded.py new file mode 100644 index 0000000000..b2436cd2ab --- /dev/null +++ b/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded.py @@ -0,0 +1,134 @@ +"""Trains the MNIST network using preloaded data in a constant. + +Command to run this py_binary target: + +bazel run -c opt \ + <...>/tensorflow/g3doc/how_tos/reading_data:fully_connected_preloaded +""" +import os.path +import time + +import tensorflow.python.platform +import numpy +import tensorflow as tf + +from tensorflow.g3doc.tutorials.mnist import input_data +from tensorflow.g3doc.tutorials.mnist import mnist + + +# Basic model parameters as external flags. +flags = tf.app.flags +FLAGS = flags.FLAGS +flags.DEFINE_float('learning_rate', 0.01, 'Initial learning rate.') +flags.DEFINE_integer('num_epochs', 2, 'Number of epochs to run trainer.') +flags.DEFINE_integer('hidden1', 128, 'Number of units in hidden layer 1.') +flags.DEFINE_integer('hidden2', 32, 'Number of units in hidden layer 2.') +flags.DEFINE_integer('batch_size', 100, 'Batch size. ' + 'Must divide evenly into the dataset sizes.') +flags.DEFINE_string('train_dir', 'data', 'Directory to put the training data.') +flags.DEFINE_boolean('fake_data', False, 'If true, uses fake data ' + 'for unit testing.') + + +def run_training(): + """Train MNIST for a number of epochs.""" + # Get the sets of images and labels for training, validation, and + # test on MNIST. + data_sets = input_data.read_data_sets(FLAGS.train_dir, FLAGS.fake_data) + + # Tell TensorFlow that the model will be built into the default Graph. + with tf.Graph().as_default(): + with tf.name_scope('input'): + # Input data + input_images = tf.constant(data_sets.train.images) + input_labels = tf.constant(data_sets.train.labels) + + image, label = tf.train.slice_input_producer( + [input_images, input_labels], num_epochs=FLAGS.num_epochs) + label = tf.cast(label, tf.int32) + images, labels = tf.train.batch( + [image, label], batch_size=FLAGS.batch_size) + + # Build a Graph that computes predictions from the inference model. + logits = mnist.inference(images, FLAGS.hidden1, FLAGS.hidden2) + + # Add to the Graph the Ops for loss calculation. + loss = mnist.loss(logits, labels) + + # Add to the Graph the Ops that calculate and apply gradients. + train_op = mnist.training(loss, FLAGS.learning_rate) + + # Add the Op to compare the logits to the labels during evaluation. + eval_correct = mnist.evaluation(logits, labels) + + # Build the summary operation based on the TF collection of Summaries. + summary_op = tf.merge_all_summaries() + + # Create a saver for writing training checkpoints. + saver = tf.train.Saver() + + # Create the op for initializing variables. + init_op = tf.initialize_all_variables() + + # Create a session for running Ops on the Graph. + sess = tf.Session() + + # Run the Op to initialize the variables. + sess.run(init_op) + + # Instantiate a SummaryWriter to output summaries and the Graph. + summary_writer = tf.train.SummaryWriter(FLAGS.train_dir, + graph_def=sess.graph_def) + + # Start input enqueue threads. + coord = tf.train.Coordinator() + threads = tf.train.start_queue_runners(sess=sess, coord=coord) + + # And then after everything is built, start the training loop. + try: + step = 0 + while not coord.should_stop(): + start_time = time.time() + + # Run one step of the model. + _, loss_value = sess.run([train_op, loss]) + + duration = time.time() - start_time + + # Write the summaries and print an overview fairly often. + if step % 100 == 0: + # Print status to stdout. + print 'Step %d: loss = %.2f (%.3f sec)' % (step, + loss_value, + duration) + # Update the events file. + summary_str = sess.run(summary_op) + summary_writer.add_summary(summary_str, step) + step += 1 + + # Save a checkpoint periodically. + if (step + 1) % 1000 == 0: + print 'Saving' + saver.save(sess, FLAGS.train_dir, global_step=step) + + step += 1 + except tf.errors.OutOfRangeError: + print 'Saving' + saver.save(sess, FLAGS.train_dir, global_step=step) + print 'Done training for %d epochs, %d steps.' % ( + FLAGS.num_epochs, step) + finally: + # When done, ask the threads to stop. + coord.request_stop() + + # Wait for threads to finish. + coord.join(threads) + sess.close() + + +def main(_): + run_training() + + +if __name__ == '__main__': + tf.app.run() diff --git a/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded_var.py b/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded_var.py new file mode 100644 index 0000000000..89abd60d0e --- /dev/null +++ b/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded_var.py @@ -0,0 +1,146 @@ +"""Trains the MNIST network using preloaded data stored in a variable. + +Command to run this py_binary target: + +bazel run -c opt \ + <...>/tensorflow/g3doc/how_tos/reading_data:fully_connected_preloaded_var +""" +import os.path +import time + +import tensorflow.python.platform +import numpy +import tensorflow as tf + +from tensorflow.g3doc.tutorials.mnist import input_data +from tensorflow.g3doc.tutorials.mnist import mnist + + +# Basic model parameters as external flags. +flags = tf.app.flags +FLAGS = flags.FLAGS +flags.DEFINE_float('learning_rate', 0.01, 'Initial learning rate.') +flags.DEFINE_integer('num_epochs', 2, 'Number of epochs to run trainer.') +flags.DEFINE_integer('hidden1', 128, 'Number of units in hidden layer 1.') +flags.DEFINE_integer('hidden2', 32, 'Number of units in hidden layer 2.') +flags.DEFINE_integer('batch_size', 100, 'Batch size. ' + 'Must divide evenly into the dataset sizes.') +flags.DEFINE_string('train_dir', 'data', 'Directory to put the training data.') +flags.DEFINE_boolean('fake_data', False, 'If true, uses fake data ' + 'for unit testing.') + + +def run_training(): + """Train MNIST for a number of epochs.""" + # Get the sets of images and labels for training, validation, and + # test on MNIST. + data_sets = input_data.read_data_sets(FLAGS.train_dir, FLAGS.fake_data) + + # Tell TensorFlow that the model will be built into the default Graph. + with tf.Graph().as_default(): + with tf.name_scope('input'): + # Input data + images_initializer = tf.placeholder( + dtype=data_sets.train.images.dtype, + shape=data_sets.train.images.shape) + labels_initializer = tf.placeholder( + dtype=data_sets.train.labels.dtype, + shape=data_sets.train.labels.shape) + input_images = tf.Variable( + images_initializer, trainable=False, collections=[]) + input_labels = tf.Variable( + labels_initializer, trainable=False, collections=[]) + + image, label = tf.train.slice_input_producer( + [input_images, input_labels], num_epochs=FLAGS.num_epochs) + label = tf.cast(label, tf.int32) + images, labels = tf.train.batch( + [image, label], batch_size=FLAGS.batch_size) + + # Build a Graph that computes predictions from the inference model. + logits = mnist.inference(images, FLAGS.hidden1, FLAGS.hidden2) + + # Add to the Graph the Ops for loss calculation. + loss = mnist.loss(logits, labels) + + # Add to the Graph the Ops that calculate and apply gradients. + train_op = mnist.training(loss, FLAGS.learning_rate) + + # Add the Op to compare the logits to the labels during evaluation. + eval_correct = mnist.evaluation(logits, labels) + + # Build the summary operation based on the TF collection of Summaries. + summary_op = tf.merge_all_summaries() + + # Create a saver for writing training checkpoints. + saver = tf.train.Saver() + + # Create the op for initializing variables. + init_op = tf.initialize_all_variables() + + # Create a session for running Ops on the Graph. + sess = tf.Session() + + # Run the Op to initialize the variables. + sess.run(init_op) + sess.run(input_images.initializer, + feed_dict={images_initializer: data_sets.train.images}) + sess.run(input_labels.initializer, + feed_dict={labels_initializer: data_sets.train.labels}) + + # Instantiate a SummaryWriter to output summaries and the Graph. + summary_writer = tf.train.SummaryWriter(FLAGS.train_dir, + graph_def=sess.graph_def) + + # Start input enqueue threads. + coord = tf.train.Coordinator() + threads = tf.train.start_queue_runners(sess=sess, coord=coord) + + # And then after everything is built, start the training loop. + try: + step = 0 + while not coord.should_stop(): + start_time = time.time() + + # Run one step of the model. + _, loss_value = sess.run([train_op, loss]) + + duration = time.time() - start_time + + # Write the summaries and print an overview fairly often. + if step % 100 == 0: + # Print status to stdout. + print 'Step %d: loss = %.2f (%.3f sec)' % (step, + loss_value, + duration) + # Update the events file. + summary_str = sess.run(summary_op) + summary_writer.add_summary(summary_str, step) + step += 1 + + # Save a checkpoint periodically. + if (step + 1) % 1000 == 0: + print 'Saving' + saver.save(sess, FLAGS.train_dir, global_step=step) + + step += 1 + except tf.errors.OutOfRangeError: + print 'Saving' + saver.save(sess, FLAGS.train_dir, global_step=step) + print 'Done training for %d epochs, %d steps.' % ( + FLAGS.num_epochs, step) + finally: + # When done, ask the threads to stop. + coord.request_stop() + + # Wait for threads to finish. + coord.join(threads) + sess.close() + + +def main(_): + run_training() + + +if __name__ == '__main__': + tf.app.run() diff --git a/tensorflow/g3doc/how_tos/reading_data/fully_connected_reader.py b/tensorflow/g3doc/how_tos/reading_data/fully_connected_reader.py new file mode 100644 index 0000000000..f1e10ca34e --- /dev/null +++ b/tensorflow/g3doc/how_tos/reading_data/fully_connected_reader.py @@ -0,0 +1,180 @@ +"""Train and Eval the MNIST network. + +This version is like fully_connected_feed.py but uses data converted +to a TFRecords file containing tf.train.Example protocol buffers. +See tensorflow/g3doc/how_tos/reading_data.md#reading-from-files +for context. + +YOU MUST run convert_to_records before running this (but you only need to +run it once). +""" + +import os.path +import time + +import tensorflow.python.platform +import numpy +import tensorflow as tf + +from tensorflow.g3doc.tutorials.mnist import mnist + + +# Basic model parameters as external flags. +flags = tf.app.flags +FLAGS = flags.FLAGS +flags.DEFINE_float('learning_rate', 0.01, 'Initial learning rate.') +flags.DEFINE_integer('num_epochs', 2, 'Number of epochs to run trainer.') +flags.DEFINE_integer('hidden1', 128, 'Number of units in hidden layer 1.') +flags.DEFINE_integer('hidden2', 32, 'Number of units in hidden layer 2.') +flags.DEFINE_integer('batch_size', 100, 'Batch size.') +flags.DEFINE_string('train_dir', 'data', 'Directory with the training data.') + +# Constants used for dealing with the files, matches convert_to_records. +TRAIN_FILE = 'train.tfrecords' +VALIDATION_FILE = 'validation.tfrecords' + + +def read_and_decode(filename_queue): + reader = tf.TFRecordReader() + _, serialized_example = reader.read(filename_queue) + features = tf.parse_single_example( + serialized_example, + dense_keys=['image_raw', 'label'], + # Defaults are not specified since both keys are required. + dense_types=[tf.string, tf.int64]) + + # Convert from a scalar string tensor (whose single string has + # length mnist.IMAGE_PIXELS) to a uint8 tensor with shape + # [mnist.IMAGE_PIXELS]. + image = tf.decode_raw(features['image_raw'], tf.uint8) + image.set_shape([mnist.IMAGE_PIXELS]) + + # OPTIONAL: Could reshape into a 28x28 image and apply distortions + # here. Since we are not applying any distortions in this + # example, and the next step expects the image to be flattened + # into a vector, we don't bother. + + # Convert from [0, 255] -> [-0.5, 0.5] floats. + image = tf.cast(image, tf.float32) * (1. / 255) - 0.5 + + # Convert label from a scalar uint8 tensor to an int32 scalar. + label = tf.cast(features['label'], tf.int32) + + return image, label + + +def inputs(train, batch_size, num_epochs): + """Reads input data num_epochs times. + + Args: + train: Selects between the training (True) and validation (False) data. + batch_size: Number of examples per returned batch. + num_epochs: Number of times to read the input data, or 0/None to + train forever. + + Returns: + A tuple (images, labels), where: + * images is a float tensor with shape [batch_size, mnist.IMAGE_PIXELS] + in the range [-0.5, 0.5]. + * labels is an int32 tensor with shape [batch_size] with the true label, + a number in the range [0, mnist.NUM_CLASSES). + Note that an tf.train.QueueRunner is added to the graph, which + must be run using e.g. tf.train.start_queue_runners(). + """ + if not num_epochs: num_epochs = None + filename = os.path.join(FLAGS.train_dir, + TRAIN_FILE if train else VALIDATION_FILE) + + with tf.name_scope('input'): + filename_queue = tf.train.string_input_producer( + [filename], num_epochs=num_epochs) + + # Even when reading in multiple threads, share the filename + # queue. + image, label = read_and_decode(filename_queue) + + # Shuffle the examples and collect them into batch_size batches. + # (Internally uses a RandomShuffleQueue.) + # We run this in two threads to avoid being a bottleneck. + images, sparse_labels = tf.train.shuffle_batch( + [image, label], batch_size=batch_size, num_threads=2, + capacity=1000 + 3 * batch_size, + # Ensures a minimum amount of shuffling of examples. + min_after_dequeue=1000) + + return images, sparse_labels + + +def run_training(): + """Train MNIST for a number of steps.""" + + # Tell TensorFlow that the model will be built into the default Graph. + with tf.Graph().as_default(): + # Input images and labels. + images, labels = inputs(train=True, batch_size=FLAGS.batch_size, + num_epochs=FLAGS.num_epochs) + + # Build a Graph that computes predictions from the inference model. + logits = mnist.inference(images, + FLAGS.hidden1, + FLAGS.hidden2) + + # Add to the Graph the loss calculation. + loss = mnist.loss(logits, labels) + + # Add to the Graph operations that train the model. + train_op = mnist.training(loss, FLAGS.learning_rate) + + # The op for initializing the variables. + init_op = tf.initialize_all_variables(); + + # Create a session for running operations in the Graph. + sess = tf.Session() + + # Initialize the variables (the trained variables and the + # epoch counter). + sess.run(init_op) + + # Start input enqueue threads. + coord = tf.train.Coordinator() + threads = tf.train.start_queue_runners(sess=sess, coord=coord) + + try: + step = 0 + while not coord.should_stop(): + start_time = time.time() + + # Run one step of the model. The return values are + # the activations from the `train_op` (which is + # discarded) and the `loss` op. To inspect the values + # of your ops or variables, you may include them in + # the list passed to sess.run() and the value tensors + # will be returned in the tuple from the call. + _, loss_value = sess.run([train_op, loss]) + + duration = time.time() - start_time + + # Print an overview fairly often. + if step % 100 == 0: + print 'Step %d: loss = %.2f (%.3f sec)' % (step, + loss_value, + duration) + step += 1 + except tf.errors.OutOfRangeError: + print 'Done training for %d epochs, %d steps.' % ( + FLAGS.num_epochs, step) + finally: + # When done, ask the threads to stop. + coord.request_stop() + + # Wait for threads to finish. + coord.join(threads) + sess.close() + + +def main(_): + run_training() + + +if __name__ == '__main__': + tf.app.run() diff --git a/tensorflow/g3doc/how_tos/reading_data/index.md b/tensorflow/g3doc/how_tos/reading_data/index.md new file mode 100644 index 0000000000..2b305f9333 --- /dev/null +++ b/tensorflow/g3doc/how_tos/reading_data/index.md @@ -0,0 +1,495 @@ +# Reading data + +There are three main methods of getting data into a TensorFlow program: + +* Feeding: Python code provides the data when running each step. +* Reading from files: an input pipeline reads the data from files + at the beginning of a TensorFlow graph. +* Preloaded data: a constant or variable in the TensorFlow graph holds + all the data (for small data sets). + +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents +* [Feeding](#Feeding) +* [Reading from files](#AUTOGENERATED-reading-from-files) + * [Filenames, shuffling, and epoch limits](#AUTOGENERATED-filenames--shuffling--and-epoch-limits) + * [File formats](#AUTOGENERATED-file-formats) + * [Preprocessing](#AUTOGENERATED-preprocessing) + * [Batching](#AUTOGENERATED-batching) + * [Creating threads to prefetch using `QueueRunner` objects](#QueueRunner) + * [Filtering records or producing multiple examples per record](#AUTOGENERATED-filtering-records-or-producing-multiple-examples-per-record) + * [Sparse input data](#AUTOGENERATED-sparse-input-data) +* [Preloaded data](#AUTOGENERATED-preloaded-data) +* [Multiple input pipelines](#AUTOGENERATED-multiple-input-pipelines) + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +## Feeding <div class="md-anchor" id="Feeding">{#Feeding}</div> + +TensorFlow's feed mechanism lets you inject data into any Tensor in a +computation graph. A python computation can thus feed data directly into the +graph. + +Supply feed data through the `feed_dict` argument to a run() or eval() call +that initiates computation. + +```python +with tf.Session(): + input = tf.placeholder(tf.float32) + classifier = ... + print classifier.eval(feed_dict={input: my_python_preprocessing_fn()}) +``` + +While you can replace any Tensor with feed data, including variables and +constants, the best practice is to use a +[`placeholder` op](../../api_docs/python/io_ops.md#placeholder) node. A +`placeholder` exists solely to serve as the target of feeds. It is not +initialized and contains no data. A placeholder generates an error if +it is executed without a feed, so you won't forget to feed it. + +An example using `placeholder` and feeding to train on MNIST data can be found +in +[tensorflow/g3doc/tutorials/mnist/fully_connected_feed.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/g3doc/tutorials/mnist/fully_connected_feed.py), +and is described in the [MNIST tutorial](../../tutorials/mnist/tf/index.md). + +## Reading from files <div class="md-anchor" id="AUTOGENERATED-reading-from-files">{#AUTOGENERATED-reading-from-files}</div> + +A typical pipeline for reading records from files has the following stages: + +1. The list of filenames +2. *Optional* filename shuffling +3. *Optional* epoch limit +4. Filename queue +5. A Reader for the file format +6. A decoder for a record read by the reader +7. *Optional* preprocessing +8. Example queue + +### Filenames, shuffling, and epoch limits <div class="md-anchor" id="AUTOGENERATED-filenames--shuffling--and-epoch-limits">{#AUTOGENERATED-filenames--shuffling--and-epoch-limits}</div> + +For the list of filenames, use either a constant string Tensor (like +`["file0", "file1"]` or `[("file%d" % i) for i in range(2)]`) or the +[tf.train.match_filenames_once +function](../../api_docs/python/io_ops.md#match_filenames_once). + +Pass the list of filenames to the [tf.train.string_input_producer +function](../../api_docs/python/io_ops.md#string_input_producer). +`string_input_producer` creates a FIFO queue for holding the filenames until +the reader needs them. + +`string_input_producer` has options for shuffling and setting a maximum number +of epochs. A queue runner adds the whole list of filenames to the queue once +for each epoch, shuffling the filenames within an epoch if `shuffle=True`. +This procedure provides a uniform sampling of files, so that examples are not +under- or over- sampled relative to each other. + +The queue runner works in a thread separate from the reader that pulls +filenames from the queue, so the shuffling and enqueuing process does not +block the reader. + +### File formats <div class="md-anchor" id="AUTOGENERATED-file-formats">{#AUTOGENERATED-file-formats}</div> + +Select the reader that matches your input file format and pass the filename +queue to the reader's read method. The read method outputs a key identifying +the file and record (useful for debugging if you have some weird records), and +a scalar string value. Use one (or more) of the decoder and conversion ops to +decode this string into the tensors that make up an example. + +#### CSV files + +To read text files in [comma-separated value (CSV) +format](https://tools.ietf.org/html/rfc4180), use a +[TextLineReader](../../api_docs/python/io_ops.md#TextLineReader) with the +[decode_csv](../../api_docs/python/io_ops.md#decode_csv) operation. For example: + +```python +filename_queue = tf.train.string_input_producer(["file0.csv", "file1.csv"]) + +reader = tf.TextLineReader() +key, value = reader.read(filename_queue) + +# Default values, in case of empty columns. Also specifies the type of the +# decoded result. +record_defaults = [[1], [1], [1], [1], [1]] +col1, col2, col3, col4, col5 = tf.decode_csv( + value, record_defaults=record_defaults) +features = tf.concat(0, [col1, col2, col3, col4]) + +with tf.Session() as sess: + # Start populating the filename queue. + coord = tf.train.Coordinator() + threads = tf.train.start_queue_runners(coord=coord) + + for i in range(1200): + # Retrieve a single instance: + example, label = sess.run([features, col5]) + + coord.request_stop() + coord.join(threads) +``` + +Each execution of `read()` reads a single line from the file. The +`decode_csv()` op then parses the result into a list of tensors. The +`record_defaults` argument determines the type of the resulting tensors and +sets the default value to use if a value is missing in the input string. + +You must call `tf.train.start_queue_runners()` to populate the queue before +you call `run()` or `eval()` to execute the `read()`. Otherwise `read()` will +block while it waits for filenames from the queue. + +#### Fixed length records + +To read binary files in which each record is a fixed number of bytes, use +[tf.FixedLengthRecordReader](../../api_docs/python/io_ops.md#FixedLengthRecordReader) +with the [tf.decode_raw](../../api_docs/python/io_ops.md#decode_raw) operation. +The `decode_raw` op converts from a string to a uint8 tensor. + +For example, [the CIFAR-10 dataset](http://www.cs.toronto.edu/~kriz/cifar.html) +uses a file format where each record is represented using a fixed number of +bytes: 1 byte for the label followed by 3072 bytes of image data. Once you have +a uint8 tensor, standard operations can slice out each piece and reformat as +needed. For CIFAR-10, you can see how to do the reading and decoding in +[tensorflow/models/image/cifar10/cifar10_input.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10_input.py) +and described in +[this tutorial](../../tutorials/deep_cnn/index.md#prepare-the-data). + +#### Standard TensorFlow format + +Another approach is to convert whatever data you have into a supported format. +This approach makes it easier to mix and match data sets and network +architectures. The recommended format for TensorFlow is a TFRecords file +containing +[tf.train.Example protocol buffers](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/example/example.proto) +(which contain +[`Features`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/example/feature.proto) +as a field). You write a little program that gets your data, stuffs it in an +`Example` protocol buffer, serializes the protocol buffer to a string, and then +writes the string to a TFRecords file using the +[tf.python_io.TFRecordWriter class](../../api_docs/python/python_io.md#TFRecordWriter). +For example, +[tensorflow/g3doc/how_tos/reading_data/convert_to_records.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/g3doc/how_tos/reading_data/convert_to_records.py) +converts MNIST data to this format. + +To read a file of TFRecords, use +[tf.TFRecordReader](../../api_docs/python/io_ops.md#TFRecordReader) with +the [tf.parse_single_example](../../api_docs/python/io_ops.md#parse_single_example) +decoder. The `parse_single_example` op decodes the example protocol buffers into +tensors. An MNIST example using the data produced by `convert_to_records` can be +found in +[tensorflow/g3doc/how_tos/reading_data/fully_connected_reader.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/g3doc/how_tos/reading_data/fully_connected_reader.py), +which you can compare with the `fully_connected_feed` version. + +### Preprocessing <div class="md-anchor" id="AUTOGENERATED-preprocessing">{#AUTOGENERATED-preprocessing}</div> + +You can then do any preprocessing of these examples you want. This would be any +processing that doesn't depend on trainable parameters. Examples include +normalization of your data, picking a random slice, adding noise or distortions, +etc. See +[tensorflow/models/image/cifar10/cifar10.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10.py) +for an example. + +### Batching <div class="md-anchor" id="AUTOGENERATED-batching">{#AUTOGENERATED-batching}</div> + +At the end of the pipeline we use another queue to batch together examples for +training, evaluation, or inference. For this we use a queue that randomizes the +order of examples, using the +[tf.train.shuffle_batch function](../../api_docs/python/io_ops.md#shuffle_batch). + +Example: + +``` +def read_my_file_format(filename_queue): + reader = tf.SomeReader() + key, record_string = reader.read(filename_queue) + example, label = tf.some_decoder(record_string) + processed_example = some_processing(example) + return processed_example, label + +def input_pipeline(filenames, batch_size, num_epochs=None): + filename_queue = tf.train.string_input_producer( + filenames, num_epochs=num_epochs, shuffle=True) + example, label = read_my_file_format(filename_queue) + # min_after_dequeue defines how big a buffer we will randomly sample + # from -- bigger means better shuffling but slower start up and more + # memory used. + # capacity must be larger than min_after_dequeue and the amount larger + # determines the maximum we will prefetch. Recommendation: + # min_after_dequeue + (num_threads + a small safety margin) * batch_size + min_after_dequeue = 10000 + capacity = min_after_dequeue + 3 * batch_size + example_batch, label_batch = tf.train.shuffle_batch( + [example, label], batch_size=batch_size, capacity=capacity, + min_after_dequeue=min_after_dequeue) + return example_batch, label_batch +``` + +If you need more parallelism or shuffling of examples between files, use +multiple reader instances using the +[tf.train.shuffle_batch_join function](../../api_docs/python/io_ops.md#shuffle_batch_join). +For example: + +``` +def read_my_file_format(filename_queue): + # Same as above + +def input_pipeline(filenames, batch_size, read_threads, num_epochs=None): + filename_queue = tf.train.string_input_producer( + filenames, num_epochs=num_epochs, shuffle=True) + example_list = [read_my_file_format(filename_queue) + for _ in range(read_threads)] + min_after_dequeue = 10000 + capacity = min_after_dequeue + 3 * batch_size + example_batch, label_batch = tf.train.shuffle_batch_join( + example_list, batch_size=batch_size, capacity=capacity, + min_after_dequeue=min_after_dequeue) + return example_batch, label_batch +``` + +You still only use a single filename queue that is shared by all the readers. +That way we ensure that the different readers use different files from the same +epoch until all the files from the epoch have been started. (It is also usually +sufficient to have a single thread filling the filename queue.) + +An alternative is to use a single reader via the +[tf.train.shuffle_batch function](../../api_docs/python/io_ops.md#shuffle_batch) +with `num_threads` bigger than 1. This will make it read from a single file at +the same time (but faster than with 1 thread), instead of N files at once. +This can be important: + +* If you have more reading threads than input files, to avoid the risk that + you will have two threads reading the same example from the same file near + each other. +* Or if reading N files in parallel causes too many disk seeks. + +How many threads do you need? the `tf.train.shuffle_batch*` functions add a +summary to the graph that indicates how full the example queue is. If you have +enough reading threads, that summary will stay above zero. You can +[view your summaries as training progresses using TensorBoard](../summaries_and_tensorboard/index.md). + +### Creating threads to prefetch using `QueueRunner` objects <div class="md-anchor" id="QueueRunner">{#QueueRunner}</div> + +The short version: many of the `tf.train` functions listed above add +[`QueueRunner`](../../api_docs/python/train.md#QueueRunner) objects to your +graph. These require that you call +[tf.train.start_queue_runners](../../api_docs/python/train.md#start_queue_runners) +before running any training or inference steps, or it will hang forever. This +will start threads that run the input pipeline, filling the example queue so +that the dequeue to get the examples will succeed. This is best combined with a +[tf.train.Coordinator](../../api_docs/python/train.md#Coordinator) to cleanly +shut down these threads when there are errors. If you set a limit on the number +of epochs, that will use an epoch counter that will need to be intialized. The +recommended code pattern combining these is: + +```python +# Create the graph, etc. +init_op = tf.initialize_all_variables() + +# Create a session for running operations in the Graph. +sess = tf.Session() + +# Initialize the variables (like the epoch counter). +sess.run(init_op) + +# Start input enqueue threads. +coord = tf.train.Coordinator() +threads = tf.train.start_queue_runners(sess=sess, coord=coord) + +try: + while not coord.should_stop(): + # Run training steps or whatever + sess.run(train_op) + +except tf.errors.OutOfRangeError: + print 'Done training -- epoch limit reached' +finally: + # When done, ask the threads to stop. + coord.request_stop() + +# Wait for threads to finish. +coord.join(threads) +sess.close() +``` + +#### Aside: What is happening here? + +First we create the graph. It will have a few pipeline stages that are +connected by queues. The first stage will generate filenames to read and enqueue +them in the filename queue. The second stage consumes filenames (using a +`Reader`), produces examples, and enqueues them in an example queue. Depending +on how you have set things up, you may actually have a few independent copies of +the second stage, so that you can read from multiple files in parallel. At the +end of these stages is an enqueue operation, which enqueues into a queue that +the next stage dequeues from. We want to start threads running these enqueuing +operations, so that our training loop can dequeue examples from the example +queue. + +<div style="width:70%; margin-left:12%; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="AnimatedFileQueues.gif"> +</div> + +The helpers in `tf.train` that create these queues and enqueuing operations add +a [tf.train.QueueRunner docs](../../api_docs/python/train.md#QueueRunner) to the +graph using the +[tf.train.add_queue_runner](../../api_docs/python/train.md#add_queue_runner) +function. Each `QueueRunner` is responsible for one stage, and holds the list of +enqueue operations that need to be run in threads. Once the graph is +constructed, the +[tf.train.start_queue_runners](../../api_docs/python/train.md#start_queue_runners) +function asks each QueueRunner in the graph to start its threads running the +enqueuing operations. + +If all goes well, you can now run your training steps and the queues will be +filled by the background threads. If you have set an epoch limit, at some point +an attempt to dequeue examples will get an +[`tf.OutOfRangeError`](../../api_docs/python/client.md#OutOfRangeError). This +is the TensorFlow equivalent of "end of file" (EOF) -- this means the epoch +limit has been reached and no more examples are available. + +The last ingredient is the +[Coordinator](../../api_docs/python/train.md#Coordinator). This is responsible +for letting all the threads know if anything has signalled a shut down. Most +commonly this would be because an exception was raised, for example one of the +threads got an error when running some operation (or an ordinary Python +exception). + +For more about threading, queues, QueueRunners, and Coordinators +[see here](../threading_and_queues/index.md). + +#### Aside: How clean shut-down when limiting epochs works + +Imagine you have a model that has set a limit on the number of epochs to train +on. That means that the thread generating filenames will only run that many +times before generating an `OutOfRange` error. The QueueRunner will catch that +error, close the filename queue, and exit the thread. Closing the queue does two +things: + +* Any future attempt to enqueue in the filename queue will generate an error. + At this point there shouldn't be any threads trying to do that, but this + is helpful when queues are closed due to other errors. +* Any current or future dequeue will either succeed (if there are enough + elements left) or fail (with an `OutOfRange` error) immediately. They won't + block waiting for more elements to be enqueued, since by the previous point + that can't happen. + +The point is that when the filename queue is closed, there will likely still be +many filenames in that queue, so the next stage of the pipeline (with the reader +and other preprocessing) may continue running for some time. Once the filename +queue is exhausted, though, the next attempt to dequeue a filename (e.g. from a +reader that has finished with the file it was working on) will trigger an +`OutOfRange` error. In this case, though, you might have multiple threads +associated with a single QueueRunner. If this isn't the last thread in the +QueueRunner, the `OutOfRange` error just causes the one thread to exit. This +allows the other threads, which are still finishing up their last file, to +proceed until they finish as well. (Assuming you are using a +[tf.train.Coordinator](../../api_docs/python/train.md#Coordinator), +other types of errors will cause all the threads to stop.) Once all the reader +threads hit the `OutOfRange` error, only then does the next queue, the example +queue, gets closed. + +Again, the example queue will have some elements queued, so training will +continue until those are exhausted. If the example queue is a +[RandomShuffleQueue](../../api_docs/python/io_ops.md#RandomShuffleQueue), say +because you are using `shuffle_batch` or `shuffle_batch_join`, it normally will +avoid ever going having fewer than its `min_after_dequeue` attr elements +buffered. However, once the queue is closed that restriction will be lifted and +the queue will eventually empty. At that point the actual training threads, +when they try and dequeue from example queue, will start getting `OutOfRange` +errors and exiting. Once all the training threads are done, +[tf.train.Coordinator.join()](../../api_docs/python/train.md#Coordinator.join) +will return and you can exit cleanly. + +### Filtering records or producing multiple examples per record <div class="md-anchor" id="AUTOGENERATED-filtering-records-or-producing-multiple-examples-per-record">{#AUTOGENERATED-filtering-records-or-producing-multiple-examples-per-record}</div> + +Instead of examples with shapes `[x, y, z]`, you will produce a batch of +examples with shape `[batch, x, y, z]`. The batch size can be 0 if you want to +filter this record out (maybe it is in a hold-out set?), or bigger than 1 if you +are producing multiple examples per record. Then simply set `enqueue_many=True` +when calling one of the batching functions (such as `shuffle_batch` or +`shuffle_batch_join`). + +### Sparse input data <div class="md-anchor" id="AUTOGENERATED-sparse-input-data">{#AUTOGENERATED-sparse-input-data}</div> + +SparseTensors don't play well with queues. If you use SparseTensors you have +to decode the string records using +[tf.parse_example](../../api_docs/python/io_ops.md#parse_example) **after** +batching (instead of using `tf.parse_single_example` before batching). + +## Preloaded data <div class="md-anchor" id="AUTOGENERATED-preloaded-data">{#AUTOGENERATED-preloaded-data}</div> + +This is only used for small data sets that can be loaded entirely in memory. +There are two approaches: + +* Store the data in a constant. +* Store the data in a variable, that you initialize and then never change. + +Using a constant is a bit simpler, but uses more memory (since the constant is +stored inline in the graph data structure, which may be duplicated a few times). + +```python +training_data = ... +training_labels = ... +with tf.Session(): + input_data = tf.constant(training_data) + input_labels = tf.constant(training_labels) + ... +``` + +To instead use a variable, you need to also initialize it after the graph has been built. + +```python +training_data = ... +training_labels = ... +with tf.Session() as sess: + data_initializer = tf.placeholder(dtype=training_data.dtype, + shape=training_data.shape) + label_initializer = tf.placeholder(dtype=training_labels.dtype, + shape=training_labels.shape) + input_data = tf.Variable(data_initalizer, trainable=False, collections=[]) + input_labels = tf.Variable(label_initalizer, trainable=False, collections=[]) + ... + sess.run(input_data.initializer, + feed_dict={data_initializer: training_data}) + sess.run(input_labels.initializer, + feed_dict={label_initializer: training_lables}) +``` + +Setting `trainable=False` keeps the variable out of the +`GraphKeys.TRAINABLE_VARIABLES` collection in the graph, so we won't try and +update it when training. Setting `collections=[]` keeps the variable out of the +`GraphKeys.VARIABLES` collection used for saving and restoring checkpoints. + +Either way, +[tf.train.slice_input_producer function](../../api_docs/python/io_ops.md#slice_input_producer) +can be used to produce a slice at a time. This shuffles the examples across an +entire epoch, so further shuffling when batching is undesirable. So instead of +using the `shuffle_batch` functions, we use the plain +[tf.train.batch function](../../api_docs/python/io_ops.md#batch). To use +multiple preprocessing threads, set the `num_threads` parameter to a number +bigger than 1. + +An MNIST example that preloads the data using constants can be found in +[tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded.py), and one that preloads the data using variables can be found in +[tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded_var.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/g3doc/how_tos/reading_data/fully_connected_preloaded_var.py), +You can compare these with the `fully_connected_feed` and +`fully_connected_reader` versions above. + +## Multiple input pipelines <div class="md-anchor" id="AUTOGENERATED-multiple-input-pipelines">{#AUTOGENERATED-multiple-input-pipelines}</div> + +Commonly you will want to train on one dataset and evaluate (or "eval") on +another. One way to do this is to actually have two separate processes: + +* The training process reads training input data and periodically writes + checkpoint files with all the trained variables. +* The evaluation process restores the checkpoint files into an inference + model that reads validation input data. + +This is what is done in +[the example CIFAR-10 model](../../tutorials/deep_cnn/index.md#save-and-restore-checkpoints). This has a couple of benefits: + +* The eval is performed on a single snapshot of the trained variables. +* You can perform the eval even after training has completed and exited. + +You can have the train and eval in the same graph in the same process, and share +their trained variables. See +[the shared variables tutorial](../variable_scope/index.md). diff --git a/tensorflow/g3doc/how_tos/summaries_and_tensorboard/index.md b/tensorflow/g3doc/how_tos/summaries_and_tensorboard/index.md new file mode 100644 index 0000000000..18f4b4260e --- /dev/null +++ b/tensorflow/g3doc/how_tos/summaries_and_tensorboard/index.md @@ -0,0 +1,102 @@ +# TensorBoard: Visualizing Your Training + +The computations you'll use TensorBoard for - like training a massive +deep neural network - can be complex and confusing. To make it easier to +understand, debug, and optimize TensorFlow programs, we've included a suite of +visualization tools called TensorBoard. You can use TensorBoard to visualize +your TensorFlow graph, quantitative metrics about the execution of your graph, +and even additional data like images that pass through it. When TensorBoard is +fully configured, it looks like this: + +TODO(danmane): Enable a live TensorBoard + + +## Serializing the data + +TensorBoard operates by reading TensorFlow events files, which contain summary +data that you can generate when running TensorFlow. Here's the general +lifecycle for summary data within TensorBoard. + +First, create the TensorFlow graph that you'd like to collect summary +data from, and decide which nodes you would like to annotate with +[summary operations] +(../../api_docs/python/train.md#summary-operations). + +For example, suppose that you are creating a convolutional neural network for +training MNIST digits recognition. You'd like to record how the learning rate +varies over time, and how the objective function is changing. Collect these by +attaching [`scalar_summary`](../../api_docs/python/train.md#scalar_summary) ops +to the nodes that output the learning rate and loss respectively. Then, give +each `scalar_summary` a meaningful `tag`, like `'learning rate'` and `'loss +function'`. + +Perhaps you'd also like to visualize the distributions of activations coming +off a particular layer, or the distribution of gradients or weights. Collect +this data by attaching +[`histogram_summary`](../../api_docs/python/train.md#histogram_summary) ops to +the gradient outputs and to the variable that holds your weights, respectively. + +For details on all of the summary operations avaiable, check out the docs on +[summary operations] +(../../api_docs/python/train.md#summary-operations). + +Operations in TensorFlow don't do anything until you run them, or an op that +depends on their output. And the summary nodes that we've just created are +peripheral to your graph: none of the ops you are currently running depend on +them. So, to generate summaries, we need to run all of these summary nodes. +Managing them by hand would be tedious, so use +[`tf.merge_all_summaries`](../../api_docs/python/train.md#merge_all_summaries) +to combine them into a single op that generates all the summary data. + +Then, you can just run the merged summary op, which will generate a serialized +`Summary` protobuf object with all of your summary data at a given step. +Finally, to write this summary data to disk, pass the summary protobuf to a +[`tf.train.SummaryWriter`](../../api_docs/python/train.md#SummaryWriter). + +The `SummaryWriter` takes a logdir in its constructor - this logdir is quite +important, it's the directory where all of the events will be written out. +Also, the `SummaryWriter` can optionally take a `GraphDef` in its constructor. +If it receives one, then TensorBoard will visualize your graph as well. + +Now that you've modified your graph and have a `SummaryWriter`, you're ready to +start runing your network! If you want, you could run the merged summary op +every single step, and record a ton of training data. That's likely to be more +data than you need, though. Instead, consider running the merged summary op +every hundred steps or so, as in the following code example. + +```python +merged_summary_op = tf.merge_all_summaries() +summary_writer = tf.train.SummaryWriter('/tmp/mnist_logs', sess.graph) +total_step = 0 +while training: + total_step += 1 + session.run(training_op) + if total_step % 100 == 0: + summary_str = session.run(merged_summary_op) + summary_writer.add_summary(summary_str, total_step) +``` + +You're now all set to visualize this data using TensorBoard. + + +## Launching TensorBoard + +To run TensorBoard, use the command +`python tensorflow/tensorboard/tensorboard.py --logdir=path/to/logs`, where +`logdir` points to the directory where the `SummaryWriter` serialized its data. +If this `logdir` directory contains sub-directories which contain serialized +data from separate runs, then TensorBoard will visualize the data from all of +those runs. Once TensorBoard is running, navigate your web browser to +localhost:6006 to view the TensorBoard. + +If you have pip installed TensorBoard, you can just simply type the command +`tensorboard --logidr=/path/to/logs` in order to run it. + +When looking at TensorBoard, you will see the navigation tabs in the top right +corner. Each tab represents a set of serialized data that can be visualized. +For any tab you are looking at, if the logs being looked at by TensorBoard do +not contain any data relevant to that tab, a message will be displayed +indicating how to serialize data that is applicable to that tab. + +For in depth information on how to use the "graph" tab to visualize your graph, +see [TensorBoard: Visualizing your graph](../graph_viz/index.md). diff --git a/tensorflow/g3doc/how_tos/threading_and_queues/index.md b/tensorflow/g3doc/how_tos/threading_and_queues/index.md new file mode 100644 index 0000000000..c472de18c5 --- /dev/null +++ b/tensorflow/g3doc/how_tos/threading_and_queues/index.md @@ -0,0 +1,146 @@ +# Threading and Queues + +Queues, such as `FIFOQueue` and `RandomShuffleQueue`, are important TensorFlow +objects for computing tensors asynchronously in a graph. + +For example, a typical input architecture is to use a `RandomShuffleQueue` to +prepare inputs for training a model: + +* Multiple threads prepare training examples and push them in the queue. +* A training thread executes a training op that dequeues mini-batches from the + queue + +This architecture has many benefits, as highlighted in the +[Reading data how to](../reading_data), which also gives an overview of +functions that simplify the construction of input pipelines. + +The TensorFlow `Session` object is multithreaded, so multiple threads can +easily use the same session and run ops in parallel. However, it is not always +easy to implement a Python program that drives threads as described above. All +threads must be able to stop together, exceptions must be caught and +reported, and queues must be properly closed when stopping. + +TensorFlow provides two classes to help: +[tf.Coordinator](../../api_docs/python/train.md#Coordinator) and +[tf.QueueRunner](../../api_docs/python/train.md#QueueRunner). These two classes +are designed to be used together. The `Coordinator` class helps multiple threads +stop together and report exceptions to a program that waits for them to stop. +The `QueueRunner` class is used to create a number of threads cooperating to +enqueue tensors in the same queue. + +## Coordinator + +The Coordinator class helps multiple threads stop together. + +Its key methods are: + +* `should_stop()`: returns True if the threads should stop. +* `request_stop(<exception>)`: requests that threads should stop. +* `join(<list of threads>)`: waits until the specified threads have stopped. + +You first create a `Coordinator` object, and then create a number of threads +that use the coordinator. The threads typically run loops that stop when +`should_stop()` returns `True`. + +Any thread can decide that the computation should stop. It only has to call +`request_stop()` and the other threads will stop as `should_stop()` will then +return `True`. + +```python +# Thread body: loop until the coordinator indicates a stop was requested. +# If some condition becomes true, ask the coordinator to stop. +def MyLoop(coord): + while not coord.should_stop(): + ...do something... + if ...some condition...: + coord.request_stop() + +# Main code: create a coordinator. +coord = Coordinator() + +# Create 10 threads that run 'MyLoop()' +threads = [threading.Thread(target=MyLoop, args=(coord)) for i in xrange(10)] + +# Start the threads and wait for all of them to stop. +for t in threads: t.start() +coord.join(threads) +``` + +Obviously, the coordinator can manage threads doing very different things. +They don't have to be all the same as in the example above. The coordinator +also has support to capture and report exceptions. See the [Coordinator class](../../api_docs/python/train.md#Coordinator) documentation for more details. + +## QueueRunner + +The `QueueRunner` class creates a number of threads that repeatedly run an +enqueue op. These threads can use a coordinator to stop together. In +addition, a queue runner runs a *closer thread* that automatically closes the +queue if an exception is reported to the coordinator. + +You can use a queue runner to implement the architecture described above. + +First build a graph that uses a `Queue` for input examples. Add ops that +process examples and enqueue them in the queue. Add training ops that start by +dequeueing from the queue. + +```python +example = ...ops to create one example... +# Create a queue, and an op that enqueues examples one at a time in the queue. +queue = tf.RandomShuffleQueue(...) +enqueue_op = queue.enqueue(example) +# Create a training graph that starts by dequeuing a batch of examples. +inputs = queue.dequeue_many(batch_size) +train_op = ...use 'inputs' to build the training part of the graph... +``` + +In the Python training program, create a `QueueRunner` that will run a few +threads to process and enqueue examples. Create a `Coordinator` and ask the +queue runner to start its threads with the coordinator. Write a training loop +that also uses the coordinator. + +``` +# Create a queue runner that will run 4 threads in parallel to enqueue +# examples. +qr = tf.train.QueueRunner(queue, [enqueue_op] * 4) + +# Launch the graph. +sess = tf.Session() +# Create a coordinator, launch the queue runner threads. +coord = tf.train.Coordinator() +enqueue_threads = qr.create_threads(sess, coord=coord, start=True) +# Run the training loop, controlling termination with the coordinator. +for step in xrange(1000000): + if coord.should_stop(): + break + sess.run(train_op) +# When done, ask the threads to stop. +coord.request_stop() +# And wait for them to actually do it. +coord.join(threads) +``` + +## Handling Exceptions + +Threads started by queue runners do more than just run the enqueue ops. They +also catch and handle exceptions generated by queues, including +`OutOfRangeError` which is used to report that a queue was closed. + +A training program that uses a coordinator must similarly catch and report +exceptions in its main loop. + +Here is an improved version of the training loop above. + +```python +try: + for step in xrange(1000000): + if coord.should_stop(): + break + sess.run(train_op) +except Exception, e: + # Report exceptions to the coordinator. + coord.request_stop(e) + +# Terminate as usual. It is innocuous to request stop twice. +coord.request_stop() +coord.join(threads) +``` diff --git a/tensorflow/g3doc/how_tos/using_gpu/index.md b/tensorflow/g3doc/how_tos/using_gpu/index.md new file mode 100644 index 0000000000..c0bdc5a7cb --- /dev/null +++ b/tensorflow/g3doc/how_tos/using_gpu/index.md @@ -0,0 +1,174 @@ +# Using GPUs + +## Supported devices + +On a typical system, there are multiple computing devices. In TensorFlow, the +supported device types are `CPU` and `GPU`. They are represented as +`strings`. For example: + +* `"/cpu:0"`: The CPU of your machine. +* `"/gpu:0"`: The GPU of your machine, if you have one. +* `"/gpu:1"`: The second GPU of your machine, etc. + +If a TensorFlow operation has both CPU and GPU implementations, the +GPU devices will be given priority when the operation is assigned to +a device. For example, `matmul` has both CPU and GPU kernels. On a +system with devices `cpu:0` and `gpu:0`, `gpu:0` will be selected to run +`matmul`. + +## Logging Device placement + +To find out which devices your operations and tensors are assigned to, create +the session with `log_device_placement` configuration option set to `True`. + +```python +# Creates a graph. +a = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[2, 3], name='a') +b = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[3, 2], name='b') +c = tf.matmul(a, b) +# Creates a session with log_device_placement set to True. +sess = tf.Session(config=tf.ConfigProto(log_device_placement=True)) +# Runs the op. +print sess.run(c) +``` + +You should see the following output: + +``` +Device mapping: +/job:localhost/replica:0/task:0/gpu:0 -> device: 0, name: Tesla K40c, pci bus +id: 0000:05:00.0 +b: /job:localhost/replica:0/task:0/gpu:0 +a: /job:localhost/replica:0/task:0/gpu:0 +MatMul: /job:localhost/replica:0/task:0/gpu:0 +[[ 22. 28.] + [ 49. 64.]] + +``` + +## Manual device placement + +If you would like a particular operation to run on a device of your +choice instead of what's automatically selected for you, you can use +`with tf.device` to create a device context such that all the operations +within that context will have the same device assignment. + +```python +# Creates a graph. +with tf.device('/cpu:0'): + a = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[2, 3], name='a') + b = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[3, 2], name='b') +c = tf.matmul(a, b) +# Creates a session with log_device_placement set to True. +sess = tf.Session(config=tf.ConfigProto(log_device_placement=True)) +# Runs the op. +print sess.run(c) +``` + +You will see that now `a` and `b` are assigned to `cpu:0`. + +``` +Device mapping: +/job:localhost/replica:0/task:0/gpu:0 -> device: 0, name: Tesla K40c, pci bus +id: 0000:05:00.0 +b: /job:localhost/replica:0/task:0/cpu:0 +a: /job:localhost/replica:0/task:0/cpu:0 +MatMul: /job:localhost/replica:0/task:0/gpu:0 +[[ 22. 28.] + [ 49. 64.]] +``` + +## Using a single GPU on a multi-GPU system + +If you have more than one GPU in your system, the GPU with the lowest ID will be +selected by default. If you would like to run on a different GPU, you will need +to specify the preference explicitly: + +```python +# Creates a graph. +with tf.device('/gpu:2'): + a = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[2, 3], name='a') + b = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[3, 2], name='b') + c = tf.matmul(a, b) +# Creates a session with log_device_placement set to True. +sess = tf.Session(config=tf.ConfigProto(log_device_placement=True)) +# Runs the op. +print sess.run(c) +``` + +If the device you have specified does not exist, you will get +`InvalidArgumentError`: + +``` +InvalidArgumentError: Invalid argument: Cannot assign a device to node 'b': +Could not satisfy explicit device specification '/gpu:2' + [[Node: b = Const[dtype=DT_FLOAT, value=Tensor<type: float shape: [3,2] + values: 1 2 3...>, _device="/gpu:2"]()]] +``` + +If you would like TensorFlow to automatically choose an existing and +supported device to run the operations in case the specified one doesn't +exist, you can set `allow_soft_placement` to `True` in the configuration +option when creating the session. + +```python +# Creates a graph. +with tf.device('/gpu:2'): + a = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[2, 3], name='a') + b = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[3, 2], name='b') + c = tf.matmul(a, b) +# Creates a session with allow_soft_placement and log_device_placement set +# to True. +sess = tf.Session(config=tf.ConfigProto( + allow_soft_placement=True, log_device_placement=True)) +# Runs the op. +print sess.run(c) +``` + +## Using multiple GPUs + +If you would like to run TensorFlow on multiple GPUs, you can construct your +model in a multi-tower fashion where each tower is assigned to a different GPU. +For example: + +``` +# Creates a graph. +c = [] +for d in ['/gpu:2', '/gpu:3']: + with tf.device(d): + a = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[2, 3]) + b = tf.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape=[3, 2]) + c.append(tf.matmul(a, b)) +with tf.device('/cpu:0'): + sum = tf.add_n(c) +# Creates a session with log_device_placement set to True. +sess = tf.Session(config=tf.ConfigProto(log_device_placement=True)) +# Runs the op. +print sess.run(sum) +``` + +You will see the following output. + +``` +Device mapping: +/job:localhost/replica:0/task:0/gpu:0 -> device: 0, name: Tesla K20m, pci bus +id: 0000:02:00.0 +/job:localhost/replica:0/task:0/gpu:1 -> device: 1, name: Tesla K20m, pci bus +id: 0000:03:00.0 +/job:localhost/replica:0/task:0/gpu:2 -> device: 2, name: Tesla K20m, pci bus +id: 0000:83:00.0 +/job:localhost/replica:0/task:0/gpu:3 -> device: 3, name: Tesla K20m, pci bus +id: 0000:84:00.0 +Const_3: /job:localhost/replica:0/task:0/gpu:3 +Const_2: /job:localhost/replica:0/task:0/gpu:3 +MatMul_1: /job:localhost/replica:0/task:0/gpu:3 +Const_1: /job:localhost/replica:0/task:0/gpu:2 +Const: /job:localhost/replica:0/task:0/gpu:2 +MatMul: /job:localhost/replica:0/task:0/gpu:2 +AddN: /job:localhost/replica:0/task:0/cpu:0 +[[ 44. 56.] + [ 98. 128.]] +``` + +The [cifar10 tutorial](../../tutorials/deep_cnn/index.md) is a good example +demonstrating how to do training with multiple GPUs. diff --git a/tensorflow/g3doc/how_tos/variable_scope/index.md b/tensorflow/g3doc/how_tos/variable_scope/index.md new file mode 100644 index 0000000000..f9221b207b --- /dev/null +++ b/tensorflow/g3doc/how_tos/variable_scope/index.md @@ -0,0 +1,372 @@ +# Sharing Variables + +You can create, initialize, save and load single variables +in the way described in the [Variables HowTo](../variables/index.md). +But when building complex models you often need to share large sets of +variables and you might want to initialize all of them in one place. +This tutorial shows how this can be done using `tf.variable_scope()` and +the `tf.get_variable()`. + +## The Problem + +Imagine you create a simple model for image filters, similar to our +[Convolutional Neural Networks Tutorial](../../tutorials/deep_cnn/index.md) +model but with only 2 convolutions (for simplicity of this example). If you use +just `tf.Variable`, as explained in [Variables HowTo](../variables/index.md), +your model might look like this. + +```python +def my_image_filter(input_images): + conv1_weights = tf.Variable(tf.random_normal([5, 5, 32, 32]), + name="conv1_weights") + conv1_biases = tf.Variable(tf.zeros([32]), name="conv1_biases") + conv1 = tf.nn.conv2d(input_images, conv1_weights, + strides=[1, 1, 1, 1], padding='SAME') + relu1 = tf.nn.relu(conv1 + conv1_biases) + + conv2_weights = tf.Variable(tf.random_normal([5, 5, 32, 32]), + name="conv2_weights") + conv2_biases = tf.Variable(tf.zeros([32]), name="conv2_biases") + conv2 = tf.nn.conv2d(relu1, conv2_weights, + strides=[1, 1, 1, 1], padding='SAME') + return tf.nn.relu(conv2 + conv2_biases) +``` + +As you can easily imagine, models quickly get much more complicated than +this one, and even here we already have 4 different variables: `conv1_weights`, +`conv1_biases`, `conv2_weights`, and `conv2_biases`. + +The problem arises when you want to reuse this model. Assume you want to +apply your image filter to 2 different images, `image1` and `image2`. +You want both images processed by the same filer with the same parameters. +You can call `my_image_filter()` twice, but this will create two sets +of variables: + +```python +# First call creates one set of variables. +result1 = my_image_filter(image1) +# Another set is created in the second call. +result2 = my_image_filter(image2) +``` + +A common way to share variables is to create them in a separate piece of code +and pass them to functions that use them. For example by using a dictionary: + +```python +variables_dict = { + "conv1_weights": tf.Variable(tf.random_normal([5, 5, 32, 32]), + name="conv1_weights") + "conv1_biases": tf.Variable(tf.zeros([32]), name="conv1_biases") + ... etc. ... +} + +def my_image_filter(input_images, variables_dict): + conv1 = tf.nn.conv2d(input_images, variables_dict["conv1_weights"], + strides=[1, 1, 1, 1], padding='SAME') + relu1 = tf.nn.relu(conv1 + variables_dict["conv1_biases"]) + + conv2 = tf.nn.conv2d(relu1, variables_dict["conv2_weights"], + strides=[1, 1, 1, 1], padding='SAME') + return tf.nn.relu(conv2 + variables_dict["conv2_biases"]) + +# The 2 calls to my_image_filter() now use the same variables +result1 = my_image_filter(image1, variables_dict) +result2 = my_image_filter(image2, variables_dict) +``` + +While convenient, creating variables like above, +outside of the code, breaks encapsulation: + +* The code that builds the graph must document the names, types, + and shapes of variables to create. +* When the code changes, the callers may have to create more, or less, + or different variables. + +One way to address the problem is to use classes to create a model, +where the classes take care of managing the variables they need. +For a lighter solution, not involving classes, TensorFlow provides +a *Variable Scope* mechanism that allows to easily share named variables +while constructing a graph. + +## Variable Scope Example + +Variable Scope mechanism in TensorFlow consists of 2 main functions: + +* `tf.get_variable(<name>, <shape>, <initializer>)`: + Creates or returns a variable with a given name. +* `tf.variable_scope(<scope_name>)`: + Manages namespaces for names passed to `tf.get_variable()`. + +The function `tf.get_variable()` is used to get or create a variable instead +of a direct call to `tf.Variable`. It uses an *initializer* instead of passing +the value directly, as in `tf.Variable`. An initializer is a function that +takes the shape and provides a tensor with that shape. Here are some +initializers available in TensorFlow: + +* `tf.constant_initializer(value)` initializes everything to the provided value, +* `tf.random_uniform_initializer(a, b)` initializes uniformly from [a, b], +* `tf.random_normal_initializer(mean, stddev)` initializes from the normal + distribution with the given mean and standard deviation. + +To see how `tf.get_variable()` solves the problem discussed +before, let's refactor the code that created one convolution into +a separate function, named `conv_relu`: + +```python +def conv_relu(input, kernel_shape, bias_shape): + # Create variable named "weights". + weights = tf.get_variable("weights", kernel_shape, + initializer=tf.random_normal_initializer()) + # Create variable named "biases". + biases = tf.get_variable("biases", bias_shape, + initializer=tf.constant_intializer(0.0)) + conv = tf.nn.conv2d(input, weights, + strides=[1, 1, 1, 1], padding='SAME') + return tf.nn.relu(conv + biases) +``` + +This function uses short names `"weights"` and `"biases"`. +We'd like to use it for both `conv1` and `conv2`, but +the variables need to have different names. +This is where `tf.variable_scope()` comes into play: +it pushes a namespace for variables. + +```python +def my_image_filter(input_images): + with tf.variable_scope("conv1"): + # Variables created here will be named "conv1/weights", "conv1/biases". + relu1 = conv_relu(input_images, [5, 5, 32, 32], [32]) + with tf.variable_scope("conv2"): + # Variables created here will be named "conv2/weights", "conv2/biases". + return conv_relu(relu1, [5, 5, 32, 32], [32]) +``` + +Now, let's see what happens when we call `my_image_filter()` twice. + +``` +result1 = my_image_filter(image1) +result2 = my_image_filter(image2) +# Raises ValueError(... conv1/weights already exists ...) +``` + +As you can see, `tf.get_variable()` checks that already existing variables +are not shared by accident. If you want to share them, you need to specify +it by setting `reuse_variables()` as follows. + +``` +with tf.variable_scope("image_filters") as scope: + result1 = my_image_filter(image1) + scope.reuse_variables() + result2 = my_image_filter(image2) +``` + +This is a good way to share variables, lightweight and safe. + +## How Does Variable Scope Work? + +### Understanding `tf.get_variable()` + +To understand variable scope it is necessary to first +fully understand how `tf.get_variable()` works. +Here is how `tf.get_variable` is usually called. + +```python +v = tf.get_variable(name, shape, dtype, initializer) +``` + +This call does one of two things depending on the scope it is called in. +Here are the two options. + +* Case 1: the scope is set for creating new variables, as evidenced by +`tf.get_variable_scope().reuse == False`. + +In this case, `v` will be a newly created `tf.Variable` with the provided +shape and data type. The full name of the created variable will be set to +the current variable scope name + the provided `name` and a check will be +performed to ensure that no variable with this full name exists yet. +If a variable with this full name already exists, the funtion will +raise a `ValueError`. If a new variable is created, it will be +initialized to the value `initializer(shape)`. For example: + +```python +with tf.variable_scope("foo"): + v = tf.get_variable("v", [1]) +assert v.name == "foo/v:0" +``` + +* Case 2: the scope is set for reusing variables, as evidenced by +`tf.get_variable_scope().reuse == True`. + +In this case, the call will search for an already existing variable with +name equal to the current variable scope name + the provided `name`. +If no such variable exists, a `ValueError` will be raised. If the variable +is found, it will be returned. For example: + +```python +with tf.variable_scope("foo"): + v = tf.get_variable("v", [1]) +with tf.variable_scope("foo", reuse=True): + v1 = tf.get_variable("v", [1]) +assert v1 == v +``` + +### Basics of `tf.variable_scope()` + +Knowing how `tf.get_variable()` works makes it easy to understand variable +scope. The primary function of variable scope is to carry a name that will +be used as prefix for variable names and a reuse-flag to distinguish the two +cases described above. Nesting variable scopes appends their names in a way +analogous to how directories work: + +```python +with tf.variable_scope("foo"): + with tf.variable_scope("bar"): + v = tf.get_variable("v", [1]) +assert v.name == "foo/bar/v:0" +``` + +The current variable scope can be retrieved using `tf.get_variable_scope()` +and the `reuse` flag of the current variable scope can be set to `True` by +calling `tf.get_variable_scope().reuse_variables()`: + +```python +with tf.variable_scope("foo"): + v = tf.get_variable("v", [1]) + tf.get_variable_scope().reuse_variables() + v1 = tf.get_variable("v", [1]) +assert v1 == v +``` + +Note that you *cannot* set the `reuse` flag to `False`. The reason behind +this is to allow to compose functions that create models. Imagine you write +a function `my_image_filter(inputs)` as before. Someone calling the function +in a variable scope with `reuse=True` would expect all inner variables to be +reused as well. Allowing to force `reuse=False` inside the function would break +this contract and make it hard to share parameters in this way. + +Even though you cannot set `reuse` to `False` explicitly, you can enter +a reusing variable scope and then exit it, going back to a non-reusing one. +This can be done using a `reuse=True` parameter when opening a variable scope. +Note also that, for the same reason as above, the `reuse` parameter is +inherited. So when you open a reusing variable scope, all sub-scopes will +be reusing too. + +```python +with tf.variable_scope("root"): + # At start, the scope is not reusing. + assert tf.get_variable_scope().reuse == False + with tf.variable_scope("foo"): + # Opened a sub-scope, still not reusing. + assert tf.get_variable_scope().reuse == False + with tf.variable_scope("foo", reuse=True): + # Explicitly opened a reusing scope. + assert tf.get_variable_scope().reuse == True + with tf.variable_scope("bar"): + # Now sub-scope inherits the reuse flag. + assert tf.get_variable_scope().reuse == True + # Exited the reusing scope, back to a non-reusing one. + assert tf.get_variable_scope().reuse == False +``` + +### Capturing variable scope + +In all examples presented above, we shared parameters only because their +names agreed, that is, because we opened a reusing variable scope with +exactly the same string. In more complex cases, it might be useful to pass +a VariableScope object rather than rely on getting the names right. +To this end, variable scopes can be captured and used instead of names +when opening a new variable scope. + +```python +with tf.variable_scope("foo") as foo_scope: + v = tf.get_variable("v", [1]) +with tf.variable_scope(foo_scope) + w = tf.get_variable("w", [1]) +with tf.variable_scope(foo_scope, reuse=True) + v1 = tf.get_variable("v", [1]) + w1 = tf.get_variable("w", [1]) +assert v1 == v +assert w1 == w +``` + +When opening a variable scope using a previously existing scope +we jump out of the current variable scope prefix to an entirely +different one. This is fully independent of where we do it. + +```python +with tf.variable_scope("foo") as foo_scope: + assert foo_scope.name == "foo" +with tf.variable_scope("bar") + with tf.variable_scope("baz") as other_scope: + assert other_scope.name == "bar/baz" + with tf.variable_scope(foo_scope) as foo_scope2: + assert foo_scope2.name == "foo" # Not changed. +``` + +### Initializers in variable scope + +Using `tf.get_variable()` allows to write functions that create or reuse +variables and can be transparently called from outside. But what if we wanted +to change the initializer of the created variables? Do we need to pass an extra +argument to every function that creates variables? What about the most common +case, when we want to set the default initializer for all variables in one +place, on top of all functions? To help with these cases, variable scope +can carry a default initializer. It is inherited by sub-scopes and passed +to each `tf.get_variable()` call. But it will be overridden if another +initializer is specified explicitly. + +```python +with tf.variable_scope("foo", initializer=tf.constant_initializer(0.4)): + v = tf.get_variable("v", [1]) + assert v.eval() == 0.4 # Default initializer as set above. + w = tf.get_variable("w", [1], initializer=tf.constant_initializer(0.3)): + assert w.eval() == 0.3 # Specific initializer overrides the default. + with tf.variable_scope("bar"): + v = get_variable("v", [1]) + assert v.eval() == 0.4 # Inherited default initializer. + with tf.variable_scope("baz", initializer=tf.constant_initializer(0.2)): + v = get_variable("v", [1]) + assert v.eval() == 0.2 # Changed default initializer. +``` + +### Names of ops in `tf.variable_scope()` + +We discussed how `tf.variable_scope` governs the names of variables. +But how does it influence the names of other ops in the scope? +It is natural that ops created inside a variable scope should also +share that name. For this reason, when we do `with tf.variable_scope("name")`, +this implicitly opens a `tf.name_scope("name")`. For example: + +```python +with tf.variable_scope("foo"): + x = 1.0 + tf.get_variable("v", [1]) +assert x.op.name == "foo/add" +``` + +Name scopes can be openend in addition to a variable scope, and then +they will only affect the names of the ops, but not of variables. + +```python +with tf.variable_scope("foo"): + with tf.name_scope("bar"): + v = tf.get_variable("v", [1]) + x = 1.0 + v +assert v.name == "foo/v:0" +assert x.op.name == "foo/bar/add" +``` + +When opening a variable scope using a captured object instead of a string, +we do not alter the current name scope for ops. + + +## Examples of Use + +Here are pointers to a few files that make use of variable scope. +In particular, it is heavily used for recurrent neural networks +and sequence-to-sequence models. + +File | What's in it? +--- | --- +`models/image/cifar10.py` | Model for detecting objects in images. +`models/rnn/rnn_cell.py` | Cell functions for recurrent neural networks. +`models/rnn/seq2seq.py` | Functions for building sequence-to-sequence models. diff --git a/tensorflow/g3doc/how_tos/variables/index.md b/tensorflow/g3doc/how_tos/variables/index.md new file mode 100644 index 0000000000..4ad8f8a266 --- /dev/null +++ b/tensorflow/g3doc/how_tos/variables/index.md @@ -0,0 +1,215 @@ +# Variables: Creation, Initialization, Saving, and Loading + +When you train a model, you use [Variables](../../api_docs/python/state_ops.md) +to hold and update parameters. Variables are in-memory buffers containing +tensors. They need to be explicitly initialized and can be saved to disk during +and after training. You can later restore saved values to exercise or analyse +the model. + +This document references the following TensorFlow classes. Follow the links to +their reference manual for a complete description of their API: + +* The `Variable` class [tf.Variable](../../api_docs/python/state_ops.md#Variable). +* The `Saver` class [tf.train.Saver](../../api_docs/python/state_ops.md#Saver). + + +## Creation + +When you create a [Variable](../../api_docs/python/state_ops.md) you pass a +`Tensor` as its initial value to the `Variable()` constructor. TensorFlow +provides a collection of Ops that produce tensors often used for initialization +from [constants or random values](../../api_docs/python/constant_op.md). + +Note that all these Ops require you to specify the shape of the tensors. That +shape automatically becomes the shape of the variable. Variables generally +have a fixed shape, but TensorFlow provides advanced mechanisms to reshape +variables. + +```python +# Create two variables. +weights = tf.Variable(tf.random_normal([784, 200], stddev=0.35), + name="weights") +biases = tf.Variable(tf.zeros([200]), name="biases") +``` + +Calling `tf.Variable()` adds a few Ops to the graph: + +* A `variable` Op that holds the variable value. +* An initializer Op that sets the variable to its initial value. This is + actually a `tf.assign` Op. +* The Ops for the initial value, such as the `zeros` Op for the `biases` + variable in the example are also added to the graph. + +The value returned by `tf.Variable()` value is an instance of the Python class +`tf.Variable`. + +## Initialization + +Variable initializers must be run explicitly before other Ops in your model can +be run. The easiest way to do that is to add an Op that runs all the variable +initializers, and run that Op before using the model. + +You can alternatively restore variable values from a checkpoint file, see +below. + +Use `tf.initialize_all_variables()` to add an Op to run variable initializers. +Only run that Op after you have fully constructed your model and launched it in +a session. + +```python +# Create two variables. +weights = tf.Variable(tf.random_normal([784, 200], stddev=0.35), + name="weights") +biases = tf.Variable(tf.zeros([200]), name="biases") +... +# Add an Op to initialize the variables. +init_op = tf.initialize_all_variables() + +# Later, when launching the model +with tf.Session() as sess: + # Run the init operation. + sess.Run(init_op) + ... + # Use the model + ... +``` + +### Initialization from another Variable + +You sometimes need to initialize a variable from the initial value of another +variable. As the Op added by `tf.initialize_all_variables()` initializes all +variables in parallel you have to be careful when this is needed. + +To initialize a new variable from the value of another variable use the other +variable's `initialized_value()` property. You can use the initialized value +directly as the initial value for the new variable, or you can use it as any +other tensor to compute a value for the new variable. + + +```python +# Create a variable with a random value. +weights = tf.Variable(tf.random_normal([784, 200], stddev=0.35), + name="weights") +# Create another variable with the same value as 'weights'. +w2 = tf.Variable(weights.initialized_value(), name="w2") +# Create another variable with twice the value of 'weights' +w_twice = tf.Variable(weights.initialized_value() * 0.2, name="w_twice") +``` + +### Custom Initialization + +The convenience function `tf.initialize_all_variables()` adds an Op to +initialize *all variables* in the model. You can also pass it an explicit list +of variables to initialize. See the +[Variables Documentation](../../api_docs/python/state_op.md) for more options, +including checking if variables are initialized. + +## Saving and Restoring + +The easiest way to save and restore a model is to use a `tf.train.Saver` +object. The constructor adds `save` and `restore` Ops to the graph for all, or +a specified list, of variables. The saver object provides methods to run these +Ops, specifying paths for the checkpoint files to write to or read from. + +### Checkpoint Files + +Variables are saved in binary files that, roughly, contains a map from variable +names to tensors. + +When you create a `Saver` object, you can optionally chose names for the +variables in the checkpoint files. By default, it uses the names passed to the +`tf.Variable()` call. + +### Saving Variables + +Create a `Saver` with `tf.train.Saver()` to manage all variables in +the model. + +```python +# Create some variables. +v1 = tf.Variable(..., name="v1") +v2 = tf.Variable(..., name="v2") +... +# Add an Op to initialize the variables. +init_op = tf.initialize_all_variables() + +# Add Ops to save and restore all the variables. +saver = tf.train.Saver() + +# Later, launch the model, initialize the variables, do some work, save the +# variables to disk. +with tf.Session() as sess: + sess.Run(init_op) + # Do some work with the model. + .. + # Save the variables to disk. + save_path = saver.Save(sess, "/tmp/model.ckpt") + print "Model saved in file: ", save_path +``` + +### Restoring Variables + +The same `Saver` object is used to restore variables. Note that when you +restore variables form a file you do not have to initialize them beforehand. + +```python +# Create some variables. +v1 = tf.Variable(..., name="v1") +v2 = tf.Variable(..., name="v2") +... +# Add Ops to save and restore all the variables. +saver = tf.train.Saver() + +# Later, launch the model, use the saver to restore variables from disk, and +# do some work with the model. +with tf.Session() as sess: + # Restore variables from disk. + saver.Restore(sess, "/tmp/model.ckpt") + print "Model restored." + # Do some work with the model + ... +``` + +### Chosing which Variables to Save and Restore + +If you do not pass any argument to `tf.train.Saver()` the saver +handles all variables. Each one of them is saved under the name that was +passed when the variable was created. + +It is sometimes useful to explicitly specify names for variables in the +checkpoint files. For example, you may have trained a model with a variable +named `"weights"` whose value you want to restore in a new variable named +`"params"`. + +It is also sometimes useful to only save or restore a subset of the variables +used by a model. For example, you may have trained a neural net with 5 layers, +and you now want to train a new model with 6 layers, restoring the parameters +from the 5 layers of the previously trained model into the first 5 layers of +the new model. + +You can easily specify the names and variables to save by passing to the +`tf.train.Saver()` constructor a Python dictionary: keys are the +names to use, values are the variables to manage. + +Notes: + +* You can create as many saver objects as you want if you need to save and + restore different subsets of the model variables. The same variable can be + listed in multiple saver objects, its value is only changed when the saver + `Restore()` method is run. + +* If you only restore a subset of the model variables at the start + of a session, you have to run an initialize Op for the other variables. See + [`tf.initialize_variables()`](../../api_docs/python/state_ops.md#initialize_variables) + for more information. + +```python +# Create some variables. +v1 = tf.Variable(..., name="v1") +v2 = tf.Variable(..., name="v2") +... +# Add Ops to save and restore only 'v2' using the name "my_v2" +saver = tf.train.Saver({"my_v2": v2}) +# Use the saver object normally after that. +... +``` diff --git a/tensorflow/g3doc/images/getting_started.dot b/tensorflow/g3doc/images/getting_started.dot new file mode 100644 index 0000000000..a9cae6c4b1 --- /dev/null +++ b/tensorflow/g3doc/images/getting_started.dot @@ -0,0 +1,14 @@ +digraph Dependencies { + node [shape = oval]; + "predictions: MatMul()" -> "data: Concat()" + "data: Concat()" -> data_left + "data: Concat()" -> data_right + "predictions: MatMul()" -> "weight_matrix: Reshape()" + "weight_matrix: Reshape()" -> "new_weights: Add()" + "new_weights: Add()" -> weights + "new_weights: Add()" -> deltas + "update: Assign()" -> weights + "update: Assign()" -> "new_weights: Add()" + "InitializeAllVariables()" -> weights + "InitializeAllVariables()" -> init_value +}
\ No newline at end of file diff --git a/tensorflow/g3doc/index.md b/tensorflow/g3doc/index.md new file mode 100644 index 0000000000..dabc083ca8 --- /dev/null +++ b/tensorflow/g3doc/index.md @@ -0,0 +1,21 @@ +# TensorFlow + +<!-- Note: This file is ignored in building the external site tensorflow.org --> + +## Introduction + +TensorFlow™ is an open source software library for numerical computation +using data flow graphs. Nodes in the graph represent mathematical operations, +while the graph edges represent the multidimensional data arrays (tensors) that +flow between them. This flexible architecture allows you to deploy computation +to one or more CPUs or GPUs in a desktop, server, or mobile device without +rewriting code. TensorFlow was originally developed by researchers and +engineers working on the Google Brain team within Google's Machine Intelligence +research organization for the purposes of conducting machine learning and deep +neural networks research. The system is general enough to be applicable in a +wide variety of other domains as well. The following documents show you how +to set up and use the TensorFlow system. + +## Table of Contents +<!--#include virtual="sitemap.md" --> + diff --git a/tensorflow/g3doc/resources/dims_types.md b/tensorflow/g3doc/resources/dims_types.md new file mode 100644 index 0000000000..eebd80efaa --- /dev/null +++ b/tensorflow/g3doc/resources/dims_types.md @@ -0,0 +1,68 @@ +# Tensor Ranks, Shapes, and Types + +TensorFlow programs use a tensor data structure to represent all data. You can +think of a TensorFlow tensor as an n-dimensional array or list. +A tensor has a static type and dynamic dimensions. Only tensors may be passed +between nodes in the computation graph. + +## Rank + +In the TensorFlow system, tensors are described by a unit of dimensionality +known as *rank*. Tensor rank is not the same as matrix rank. Tensor rank +(sometimes referred to as *order* or *degree* or *n-dimension*) is the number +of dimensions of the tensor. For example, the following tensor (defined as a +Python list) has a rank of 2: + + t = [[1, 2, 3], [4, 5, 6], [7, 8, 9]] + +A rank two tensor is what we typically think of as a matrix, a rank on tensor +is a vector. For a rank two tensor you can acccess any element with the syntax +`t[i, j]`. For a rank three tensor you would need to address an element with +'t[i, j, k]'. + +Rank | Math entity | Python example +--- | --- | --- +0 | Scalar (magnitude only) | `s = 483` +1 | Vector (magnitude and direction) | `v = [1.1, 2.2, 3.3]` +2 | Matrix (table of numbers) | `m = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]` +3 | 3-Tensor (cube of numbers] | `t = [[[2], [4], [6]], [[8], [10], [12]], [[14], [16], [18]]]` +n | n-Tensor (you get the idea) | `....` + +## Shape + +The TensorFlow documentation uses three notational conventions to describe +tensor dimensionality: rank, shape, and dimension number. The following table +shows how these relate to one another: + +Rank | Shape | Dimension number | Example +--- | --- | --- | --- +0 | [] | 0-D | A 0-D tensor. A scalar. +1 | [D0] | 1-D | A 1-D tensor with shape [5]. +2 | [D0, D1] | 2-D | A 2-D tensor with shape [3, 4]. +3 | [D0, D1, D2] | 3-D | A 3-D tensor with shape [1, 4, 3]. +n | [D0, D1, ... Dn] | n-D | A tensor with shape [D0, D1, ... Dn]. + +Shapes can be represented via Python lists / tuples of ints, or with the +[`TensorShape` class](../api_docs/python/framework.md#TensorShape). + +## Data types + +In addition to dimensionality, Tensors have a data type. You can assign any one +of the following data types to a tensor: + +Data type | Python type | Description +--- | --- | --- +`DT_FLOAT` | `tf.float32` | 32 bits floating point. +`DT_DOUBLE` | `tf.float64` | 64 bits floating point. +`DT_INT64` | `tf.int64` | 64 bits signed integer. +`DT_INT32` | `tf.int32` | 32 bits signed integer. +`DT_INT16` | `tf.int16` | 16 bits signed integer. +`DT_INT8` | `tf.int8` | 8 bits signed integer. +`DT_UINT8` | `tf.uint8` | 8 bits unsigned integer. +`DT_STRING` | `tf.string` | Variable length byte arrays. Each element of a Tensor is a byte array. +`DT_BOOL` | `tf.bool` | Boolean. +`DT_COMPLEX64` | `tf.complex64` | Complex number made of two 32 bits floating points: real and imaginary parts. +`DT_QINT32` | `tf.qint32` | 32 bits signed integer used in quantized Ops. +`DT_QINT8` | `tf.qint8` | 8 bits signed integer used in quantized Ops. +`DT_QUINT8` | `tf.quint8` | 8 bits unsigned integer used in quantized Ops. + diff --git a/tensorflow/g3doc/resources/faq.md b/tensorflow/g3doc/resources/faq.md new file mode 100644 index 0000000000..fcdc8d1e33 --- /dev/null +++ b/tensorflow/g3doc/resources/faq.md @@ -0,0 +1,309 @@ +# Frequently Asked Questions + +This document provides answers to some of the frequently asked questions about +TensorFlow. If you have a question that is not covered here, please +[get in touch](index.md). + +<!-- TOC-BEGIN This section is generated by neural network: DO NOT EDIT! --> +## Contents + + +<!-- TOC-END This section was generated by neural network, THANKS FOR READING! --> + +#### Building a TensorFlow graph + +See also the +[API documentation on building graphs](../api_docs/python/framework.md). + +##### Why does `c = tf.matmul(a, b)` not execute the matrix multiplication immediately? + +In the TensorFlow Python API, `a`, `b`, and `c` are +[`Tensor`](../api_docs/python/framework.md#Tensor) objects. A `Tensor` object is +a symbolic handle to the result of an operation, but does not actually hold the +values of the operation's output. Instead, TensorFlow encourages users to build +up complicated expressions (such as entire neural networks and its gradients) as +a dataflow graph. You then offload the computation of the entire dataflow graph +(or a subgraph of it) to a TensorFlow +[`Session`](../api_docs/python/client.md#Session), which is able to execute the +whole computation much more efficiently than executing the operations +one-by-one. + +##### How are devices named? + +The supported device names are `"/device:CPU:0"` (or `"/cpu:0"`) for the CPU +device, and `"/device:GPU:i"` (or `"/gpu:i"`) for the *i*th GPU device. + +##### How do I place operations on a particular device? + +To place a group of operations on a device, create them within a +[`with tf.device(name):`](../api_docs/python/framework.md#device) context. See +the how-to documentation on +[using GPUs with TensorFlow](../how_tos/using_gpu/index.md) for details of how +TensorFlow assigns operations to devices, and the +[CIFAR-10 tutorial](../tutorials/deep_cnn/index.md) for an example model that +uses multiple GPUs. + +##### What are the different types of tensors that are available? + +TensorFlow supports a variety of different data types and tensor shapes. See the +[ranks, shapes, and types reference](dims_types.md) for more details. + +#### Running a TensorFlow computation + +See also the +[API documentation on running graphs](../api_docs/python/client.md). + +##### What's the deal with feeding and placeholders? + +Feeding is a mechanism in the TensorFlow Session API that allows you to +substitute different values for one or more tensors at run time. The `feed_dict` +argument to [`Session.run()`](../api_docs/python/client.md#Session.run) is a +dictionary that maps [`Tensor`](../api_docs/python/framework.md) objects to +numpy arrays (and some other types), which will be used as the values of those +tensors in the execution of a step. + +Often, you have certain tensors, such as inputs, that will always be fed. The +[`tf.placeholder()`] op allows you to define tensors that *must* be fed, and +optionally allows you to constrain their shape as well. See the +[beginners' MNIST tutorial](../tutorials/mnist/beginners/index.md) for an +example of how placeholders and feeding can be used to provide the training data +for a neural network. + +##### What is the difference between `Session.run()` and `Tensor.eval()`? + +If `t` is a [`Tensor`](../api_docs/python/framework.md#Tensor) object, +[`t.eval()`](../api_docs/python/framework.md#Tensor.eval) is shorthand for +[`sess.run(t)`](../api_docs/python/client.md#Session.run) (where `sess` is the +current [default session](../api_docs/python/client.md#get_default_session). The +two following snippets of code are equivalent: + +```python +# Using `Session.run()`. +sess = tf.Session() +c = tf.constant(5.0) +print sess.run(c) + +# Using `Tensor.eval()`. +c = tf.constant(5.0) +with tf.Session(): + print c.eval() +``` + +In the second example, the session acts as a +[context manager](https://docs.python.org/2.7/reference/compound_stmts.html#with), +which has the effect of installing it as the default session for the lifetime of +the `with` block. The context manager approach can lead to more concise code for +simple use cases (like unit tests); if your code deals with multiple graphs and +sessions, it may be more straightforward to explicit calls to `Session.run()`. + +##### Do Sessions have a lifetime? What about intermediate tensors? + +Sessions can own resources, such +[variables](../api_docs/python/state_ops.md#Variable), +[queues](../api_docs/python/io_ops.md#QueueBase), and +[readers](../api_docs/python/io_ops.md#ReaderBase); and these resources can use +a significant amount of memory. These resources (and the associated memory) are +released when the session is closed, by calling +[`Session.close()`](../api_docs/python/client.md#Session.close). + +The intermediate tensors that are created as part of a call to +[`Session.run()`](../api_docs/python/client.md) will be freed at or before the +end of the call. + +##### Can I run distributed training on multiple computers? + +The initial open-source release of TensorFlow supports multiple devices (CPUs +and GPUs) in a single computer. We are working on a distributed version as well: +if you are interested, please let us know so we can prioritize accordingly. + +##### Does the runtime parallelize parts of graph execution? + +The TensorFlow runtime parallelizes graph execution across many different +dimensions: + +* The individual ops have parallel implementations, using multiple cores in a + CPU, or multiple threads in a GPU. +* Independent nodes in a TensorFlow graph can run in parallel on multiple + devices, which makes it possible to speed up + [CIFAR-10 training using multiple GPUs](../tutorials/deep_cnn/index.md). +* The Session API allows multiple concurrent steps (i.e. calls to + [Session.run()](../api_docs/python/client.md#Session.run) in parallel. This + enables the runtime to get higher throughput, if a single step does not use + all of the resources in your computer. + +##### Which client languages are supported in TensorFlow? + +TensorFlow is designed to support multiple client languages. Currently, the +best-supported client language is [Python](../api_docs/python/index.md). The +[C++ client API](../api_docs/cc/index.md) provides an interface for launching +graphs and running steps; we also have an experimental API for +[building graphs in C++](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/cc/tutorials/example_trainer.cc). + +We would like to support more client languages, as determined by community +interest. TensorFlow has a +[C-based client API](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/core/public/tensor_c_api.h) +that makes it easy to build a client in many different languages. We invite +contributions of new language bindings. + +##### Does TensorFlow make use of all the devices (GPUs and CPUs) available on my machine? + +TensorFlow supports multiple GPUs and CPUs. See the how-to documentation on +[using GPUs with TensorFlow](../how_tos/using_gpu/index.md) for details of how +TensorFlow assigns operations to devices, and the +[CIFAR-10 tutorial](../tutorials/deep_cnn/index.md) for an example model that +uses multiple GPUs. + +Note that TensorFlow only uses GPU devices with a compute capability greater +than 3.5. + +##### Why does `Session.run()` hang when using a reader or a queue? + +The [reader](../api_docs/io_ops.md#ReaderBase) and +[queue](../api_docs/io_ops.md#QueueBase) classes provide special operations that +can *block* until input (or free space in a bounded queue) becomes +available. These operations allow you to build sophisticated +[input pipelines](../how_tos/reading_data/index.md), at the cost of making the +TensorFlow computation somewhat more complicated. See the how-to documentation +for +[using `QueueRunner` objects to drive queues and readers](../how_tos/reading_data/index.md#QueueRunners) +for more information on how to use them. + +#### Variables + +See also the how-to documentation on [variables](../how_tos/variables/index.md) +and [variable scopes](../how_tos/variable_scope/index.md), and +[the API documentation for variables](../api_docs/python/state_ops.md). + +##### What is the lifetime of a variable? + +A variable is created when you first run the +[`tf.Variable.initializer`](../api_docs/python/state_ops.md#Variable.initializer) +operation for that variable in a session. It is destroyed when that +[`session is closed`](../api_docs/python/client.md#Session.close). + +##### How do variables behave when they are concurrently accessed? + +Variables allow concurrent read and write operations. The value read from a +variable may change it is concurrently updated. By default, concurrent assigment +operations to a variable are allowed to run with no mutual exclusion. To acquire +a lock when assigning to a variable, pass `use_locking=True` to +[`Variable.assign()`](../api_docs/python/state_ops.md#Variable.assign). + +#### Tensor shapes + +See also the +[`TensorShape` API documentation](../api_docs/python/framework.md#TensorShape). + +##### How can I determine the shape of a tensor in Python? + +In TensorFlow, a tensor has both a static (inferred) shape and a dynamic (true) +shape. The static shape can be read using the +[`tf.Tensor.get_shape()`](../api_docs/python/framework.md#Tensor.get_shape) +method: this shape is inferred from the operations that were used to create the +tensor, and may be +[partially complete](../api_docs/python/framework.md#TensorShape). If the static +shape is not fully defined, the dynamic shape of a `Tensor` `t` can be +determined by evaluating [`tf.shape(t)`](../api_docs/python/array_ops.md#shape). + +##### What is the difference between `x.set_shape()` and `x = tf.reshape(x)`? + +The [`tf.Tensor.set_shape()`](../api_docs/python/framework.md) method updates +the static shape of a `Tensor` object, and it is typically used to provide +additional shape information when this cannot be inferred directly. It does not +change the dynamic shape of the tensor. + +The [`tf.reshape()`](../api_docs/python/array_ops.md#reshape) operation creates +a new tensor with a different dynamic shape. + +##### How do I build a graph that works with variable batch sizes? + +It is often useful to build a graph that works with variable batch sizes, for +example so that the same code can be used for (mini-)batch training, and +single-instance inference. The resulting graph can be +[saved as a protocol buffer](../api_docs/python/framework.md#Graph.as_graph_def) +and +[imported into another program](../api_docs/python/framework.md#import_graph_def). + +When building a variable-size graph, the most important thing to remember is not +to encode the batch size as a Python constant, but instead to use a symbolic +`Tensor` to represent it. The following tips may be useful: + +* Use [`batch_size = tf.shape(input)[0]`](../api_docs/python/array_ops.md#shape) + to extract the batch dimension from a `Tensor` called `input`, and store it in + a `Tensor` called `batch_size`. + +* Use [`tf.reduce_mean()`](../api_docs/python/math_ops.md#reduce_mean) instead + of `tf.reduce_sum(...) / batch_size`. + +* If you use + [placeholders for feeding input](../how_tos/reading_data/index.md#Feeding), + you can specify a variable batch dimension by creating the placeholder with + [`tf.placeholder(..., shape=[None, ...])`](../api_docs/python/io_ops.md#placeholder). The + `None` element of the shape corresponds to a variable-sized dimension. + +#### TensorBoard + +See also the +[how-to documentation on TensorBoard](../how_tos/graph_viz/index.md). + +##### What is the simplest way to send data to tensorboard? # TODO(danmane) + +Add summary_ops to your TensorFlow graph, and use a SummaryWriter to write all +of these summaries to a log directory. Then, startup TensorBoard using +<SOME_COMMAND> and pass the --logdir flag so that it points to your +log directory. For more details, see <YET_UNWRITTEN_TENSORBOARD_TUTORIAL>. + +#### Extending TensorFlow + +See also the how-to documentation for +[adding a new operation to TensorFlow](../how_tos/adding_an_op/index.md). + +##### My data is in a custom format. How do I read it using TensorFlow? + +There are two main options for dealing with data in a custom format. + +The easier option is to write parsing code in Python that transforms the data +into a numpy array, then feed a +[tf.placeholder()](../api_docs/python/io_ops.md#placeholder) a tensor with that +data. See the documentation on +[using placeholders for input](../how_tos/reading_data/index.md#Feeding) for +more details. This approach is easy to get up and running, but the parsing can +be a performance bottleneck. + +The more efficient option is to +[add a new op written in C++](../how_tos/adding_an_op/index.md) that parses your +data format. The +[guide to handling new data formats](../how_tos/new_data_formats/index.md) has +more information about the steps for doing this. + +##### How do I define an operation that takes a variable number of inputs? + +The TensorFlow op registration mechanism allows you to define inputs that are a +single tensor, a list of tensors with the same type (for example when adding +together a variable-length list of tensors), or a list of tensors with different +types (for example when enqueuing a tuple of tensors to a queue). See the +how-to documentation for +[adding an op with a list of inputs or outputs](../how_tos/adding_an_op/index.md#list-input-output) +for more details of how to define these different input types. + +#### Miscellaneous + +##### Does TensorFlow work with Python 3? + +We have only tested TensorFlow using Python 2.7. We are aware of some changes +that will be required for Python 3 compatibility, and welcome contributions +towards this effort. + +##### What is TensorFlow's coding style convention? + +The TensorFlow Python API adheres to the +[PEP8](https://www.python.org/dev/peps/pep-0008/) conventions.<sup>*</sup> In +particular, we use `CamelCase` names for classes, and `snake_case` names for +functions, methods, and properties. We also adhere to the +[Google Python style guide](https://google.github.io/styleguide/pyguide.html). + +The TensorFlow C++ code base adheres to the +[Google C++ style guide](http://google.github.io/styleguide/cppguide.html). + +(<sup>*</sup> With one exception: we use 2-space indentation instead of 4-space +indentation.) diff --git a/tensorflow/g3doc/resources/glossary.md b/tensorflow/g3doc/resources/glossary.md new file mode 100644 index 0000000000..ab1fc4eb27 --- /dev/null +++ b/tensorflow/g3doc/resources/glossary.md @@ -0,0 +1,149 @@ +# Glossary + +**Broadcasting operation** + +An operation that uses [numpy-style broadcasting](http://docs.scipy.org/doc/numpy/user/basics.broadcasting.html) +to make the shapes of its tensor arguments compatible. + +**Device** + +A piece of hardware that can run computation and has its own address space, +like a GPU or CPU. + +**eval** + +A method of `Tensor` that returns the value of the `Tensor`, triggering any +graph computation required to determine the value. You may only call `eval()` +on a `Tensor` in a graph that has been launched in a session. + +**Feed** + +TensorFlow's mechanism for patching a tensor directly into any node in a graph +launched in a session. You apply feeds when you trigger the execution of a +graph, not when you build the graph. A feed temporarily replaces a node with a +tensor value. You supply feed data as an argument to a run() or eval() call +that initiates computation. After the run the feed disappears and the original +node definition remains. You usually designate specific nodes to be "feed" +nodes by using tf.placeholder() to create them. See +[Basic Usage](../get_started/basic_usage.md) for more information. + +**Fetch** + +TensorFlow's mechanism for retrieving tensors from a graph launched in a +session. You retrieve fetches when you trigger the execution of a graph, not +when you build the graph. To fetch the tensor value of a node or nodes, +execute the graph with a run() call on the Session object and pass a list of +names of nodes to retrieve. See [Basic Usage](../get_started/basic_usage.md) +for more information. + +**Graph** + +Describes a computation as a directed acyclic +graph. Nodes in the graph represent operations that must be +performed. Edges in the graph represent either data or control +dependencies. GraphDef is the proto used to describe a graph to the +system (it is the API), and consists of a collection of NodeDefs (see +below). A GraphDef may be converted to a (C++) Graph object which is +easier to operate on. + +**IndexedSlices** + +In the Python API, TensorFlow's representation of a tensor that is sparse +along only its first dimension. If the tensor is k-dimensional, an +IndexedSlices instance logically represents a collection of (k-1)-dimensional +slices along the tensor's first dimension. The indices of the slices are +stored concatenated into a single 1-dimensional vector, and the corresponding +slices are concatenated to form a single k-dimensional tensor. Use +SparseTensor if the sparsity is not restricted to the first dimension. + +**Node** + +An element of a graph. + +Describes how to invoke a specific Op as one node in a specific computation +Graph, including the values for any attrs needed to configure the Op. For Ops +that are polymorphic, the attrs include sufficient information to completely +determine the signature of the Node. See graph.proto for details. + +**Op (operation)** + +In the TensorFlow runtime: A type of computation such as 'add' or 'matmul' or +'concat'. You can add new ops to the runtime as described [how to add an +op](../how_tos/adding_an_op/index.md). + +In the Python API: A node in the graph. Ops are represented by instances of +the class [tf.Operation](../api_docs/python/framework.md#Operation). The +`type` property of an `Operation` indicates the run operation for the node, +such as 'add' or 'matmul'. + +**Quantization** + +A reduction of numerical precision. Quantization maps floating-point values +onto a smaller set of values, and is particular useful for improving the +efficiency of neural networks. See TensorFlow's [neural network +operations](../api_docs/python/nn.md?cl=head#quantized_avg_pool) for more +information about TensorFlow's quantization support. + +**Run** + +The action of executing ops in a launched graph. Requires that the graph be launched +in a Session. + +In the Python API: A method of the Session class: +[tf.Session.run](../api_docs/python/client.md#Session). You can pass tensors +to feed and fetch to the `run()` call. + +In the C++ API: A method of the [tensorflow::Session](../api_docs/cc/ClassSession.md). + +**Session** + +A runtime object representing a launched graph. Provides methods to execute +ops in the graph. + +In the Python API: [tf.Session](../api_docs/python/client.md#Session) + +In the C++ API: class used to launch a graph and run operations +[tensorflow::Session](../api_docs/cc/ClassSession.md). + +**Shape** + +The number of dimensions of a tensor and their sizes. + +In a launched graph: Property of the tensors that flow between nodes. Some ops +have strong requirements on the shape of their inputs and report errors at +runtime if these are not met. + +In the Python API: Attribute of a Python Tensor in the graph construction +API. During constructions the shape of tensors can be only partially known, or +even unknown. See +[tf.TensorShape](../api_docs/python/framework.md#TensorShape) + +In the C++ API: class used to represent the shape of tensors +[tensorflow::TensorShape](../api_docs/cc/ClassTensorShape.md). + +**SparseTensor** + +In the Python API, TensorFlow's representation of a tensor that is sparse in +arbitrary positions. A SparseTensor stores only the non-empty values along +with their indices, using a dictionary-of-keys format. In other words, if +there are m non-empty values, it maintains a length-m vector of values and +a matrix with m rows of indices. For efficiency, SparseTensor requires the +indices to be sorted along increasing dimension number, i.e. in row-major +order. Use IndexedSlices if the sparsity is only along the first dimension. + +**Tensor** + +A `Tensor` is a typed multi-dimensional array. For example, a 4-D +array of floating point numbers representing a mini-batch of images with +dimensions `[batch, height, width, channel]`. + +In a launched graph: Type of the data that flow between nodes. + +In the Python API: class used to represent the output and inputs of Ops added +to the graph [tf.Tensor](../api_docs/python/framework.md#Tensor). Instances of +this class do not hold data. + +In the C++ API: class used to represent tensors returned from a +[Session::Run()](../api_docs/cc/ClassSession.md) call +[tensorflow::Tensor](../api_docs/cc/ClassTensor.md). +Instances of this class hold data. diff --git a/tensorflow/g3doc/resources/index.md b/tensorflow/g3doc/resources/index.md new file mode 100644 index 0000000000..c9b88f4512 --- /dev/null +++ b/tensorflow/g3doc/resources/index.md @@ -0,0 +1,41 @@ +# Additional Resources + + +## TensorFlow WhitePaper + +Additional details about the TensorFlow programming model and the underlying +implementation can be found in out white paper: + +* [TensorFlow: Large-scale machine learning on heterogeneous systems](../extras/tensorflow-whitepaper2015.pdf) + +### Citation + +If you use TensorFlow in your research and would like to cite the TensorFlow +system, we suggest you cite the paper above. You can use this [BibTeX +entry](../extras/tensorflow-whitepaper2015.bib). As the project progresses, we +may update the suggested citation with new papers. + + +## Community + +TODO(rajatmonga): Write this! + +* NO - google group +* YES, ASAP - internal support mailing list +* YES, ASAP - stack overflow presence +* SOON - slack + + + + + +<div class='sections-order' style="display: none;"> +<!-- +<!-- uses.md --> +<!-- faq.md --> +<!-- glossary.md --> +<!-- dims_types.md --> +--> +</div> + + diff --git a/tensorflow/g3doc/resources/uses.md b/tensorflow/g3doc/resources/uses.md new file mode 100644 index 0000000000..ac42b1f8e7 --- /dev/null +++ b/tensorflow/g3doc/resources/uses.md @@ -0,0 +1,42 @@ +# Example Uses + +This page describes some of the current uses of the TensorFlow system. + +> If you are using TensorFlow for research, for education, or for production +> usage in some product, we would love to add something about your usage here. +> Please feel free to email us a brief description of how you're using +> TensorFlow, or send us a pull request to add an entry to this file. + +Listed below are some of the many uses of TensorFlow. + +* **RankBrain** + * **Organization**: Google + * **Domain**: Information Retrieval + * **Description**: A large-scale deployment of deep neural nets for search ranking on www.google.com. + * **More info**: ["Google Turning Over Its Lucrative Search to AI Machines"](http://www.bloomberg.com/news/articles/2015-10-26/google-turning-its-lucrative-web-search-over-to-ai-machines) + +* **Inception Image Classification Model** + * **Organization**: Google + * **Description**: Baseline model and follow on research into highly accurate computer vision models, starting with the model that won the 2014 Imagenet iamge classification challenge + * **More Info**: Baseline model described in [Arxiv paper](http://arxiv.org/abs/1409.4842) + +* **SmartReply** + * **Organization**: Google + * **Description**: Deep LSTM model to automatically generate email responses + * **More Info**: [Google research blog post](http://googleresearch.blogspot.com/2015/11/computer-respond-to-this-email.html) + +* **Massively Multitask Networks for Drug Discovery** + * **Organization**: Google and Stanford University + * **Domain**: Drug discovery + * **Description**: A deep neural network model for identifying promising drug candidates. + * **More info**: [Arxiv paper](http://arxiv.org/abs/1502.02072) + +* **On-Device Computer Vision for OCR** + * **Organization**: Google + * **Description**: On-device computer vision model to do optical character recoignition to enable real-time translation. + * **More info**: [Google Research blog post](http://googleresearch.blogspot.com/2015/07/how-google-translate-squeezes-deep.html) +} + +* TODO(opensource): Add several other research projects +* TODO(opensource): Pointer Sets? +* TODO(opensource): Others diff --git a/tensorflow/g3doc/tutorials/BUILD b/tensorflow/g3doc/tutorials/BUILD new file mode 100644 index 0000000000..5642ade160 --- /dev/null +++ b/tensorflow/g3doc/tutorials/BUILD @@ -0,0 +1,19 @@ +# Description: +# Top-level tutorials files + +package(default_visibility = ["//tensorflow:internal"]) + +licenses(["notice"]) # Apache 2.0 + +exports_files(["LICENSE"]) + +filegroup( + name = "all_files", + srcs = glob( + ["**/*"], + exclude = [ + "**/METADATA", + "**/OWNERS", + ], + ), +) diff --git a/tensorflow/g3doc/tutorials/__init__.py b/tensorflow/g3doc/tutorials/__init__.py new file mode 100755 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/tutorials/__init__.py diff --git a/tensorflow/g3doc/tutorials/deep_cnn/cifar_tensorboard.html b/tensorflow/g3doc/tutorials/deep_cnn/cifar_tensorboard.html new file mode 100644 index 0000000000..266faf042e --- /dev/null +++ b/tensorflow/g3doc/tutorials/deep_cnn/cifar_tensorboard.html @@ -0,0 +1,21 @@ +<html> + +<head> + <title>TensorBoard Demo</title> + <script src="/tensorboard/webcomponents-lite.min.js"></script> + <link rel="import" href="/tensorboard/tf-tensorboard-demo.html"> + <style> + + html,body { + margin: 0; + padding: 0; + height: 100%; + font-family: "RobotoDraft","Roboto",sans-serif; + } + +</style> +</head> +<body> + <tf-tensorboard-demo data-dir="/tensorboard/cifar"></tf-tensorboard-demo> +</body> +</html> diff --git a/tensorflow/g3doc/tutorials/deep_cnn/index.md b/tensorflow/g3doc/tutorials/deep_cnn/index.md new file mode 100644 index 0000000000..f40a94ba7a --- /dev/null +++ b/tensorflow/g3doc/tutorials/deep_cnn/index.md @@ -0,0 +1,462 @@ +# Convolutional Neural Networks for Object Recognition + +**NOTE:** This tutorial is intended for *advanced* users of TensorFlow +and assumes expertise and experience in machine learning. + +## Overview + +CIFAR-10 classification is a common benchmark problem in machine learning. The +problem is to classify RGB 32x32 pixel images across 10 categories: +```airplane, automobile, bird, cat, deer, dog, frog, horse, ship, and truck.``` + + + +For more details refer to the [CIFAR-10 page](http://www.cs.toronto.edu/~kriz/cifar.html) +and a [Tech Report](http://www.cs.toronto.edu/~kriz/learning-features-2009-TR.pdf) +by Alex Krizhevsky. + +### Goals + +The goal of this tutorial is to build a relatively small convolutional neural +network (CNN) for recognizing images. In the process this tutorial: + +1. Highlights a canonical organization for network architecture, +training and evaluation. +2. Provides a template for constructing larger and more sophisticated models. + +The reason CIFAR-10 was selected was because it contains enough complexity to +exercise much of TensorFlow's ability to scale to large models. At the same +time, the model is small enough to train fast in order to test new ideas and +experiments. + +### Highlights of the Tutorial +The CIFAR-10 tutorial demonstrates several important constructs for +designing larger and more sophisticated models in TensorFlow: + +* Core mathematical components including +[convolution](../../api_docs/python/nn.md#conv2d), +[rectified linear activations](../../api_docs/python/nn.md#relu), +[max pooling](../../api_docs/python/nn.md#max_pool) and +[local response normalization](../../api_docs/python/nn.md#local_response_normalization). +* [Visualization](../../how_tos/summaries_and_tensorboard/index.md) +of network activity during training including input images, +losses and distributions of activations and gradients. +* Routines for calculating the +[moving average](../../api_docs/python/train.md#ExponentialMovingAverage) +of learned parameters and using these averages +during evaluation to boost predictive performance. +* Implementation of a +[learning rate schedule](../../api_docs/python/train.md#exponential_decay) +that systematically decrements over time. +* Prefetching [queues](../../api_docs/python/io_ops.md#shuffle_batch) +for input +data to isolate the model from disk latency and expensive image pre-processing. + +We also provide a multi-GPU version of the model which demonstrates: + +* Configuring a model to train across multiple GPU cards in parallel. +* Sharing and updating variables between multiple GPUs. + +We hope that this tutorial provides a launch point for building larger CNNs for +vision tasks on TensorFlow. + +### Model Architecture + +The model in this CIFAR-10 tutorial is a multi-layer architecture consisting of +alternating convolutions and nonlinearities. These layers are followed by fully +connected layers leading into a softmax classifier. The model follows the +architecture described by +[Alex Krizhevsky](https://code.google.com/p/cuda-convnet/), with a few +differences in the top few layers. + +This model achieves a peak performance of about 86% accuracy within a few hours +of training time on a GPU. Please see [below](#evaluating-a-model) and the code +for details. It consists of 1,068,298 learnable parameters and requires about +19.5M multiply-add operations to compute inference on a single image. + +## Code Organization + +The code for this tutorial resides in +[`tensorflow/models/image/cifar10/`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/). + +File | Purpose +--- | --- +[`cifar10_input.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10_input.py) | Read the native CIFAR-10 binary file format. +[`cifar10.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10.py) | Build the CIFAR-10 model. +[`cifar10_train.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10_train.py) | Train a CIFAR-10 model on a single machine. +[`cifar10_multi_gpu_train.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10_multi_gpu_train.py) | Train a CIFAR-10 model on multiple GPUs. +[`cifar10_eval.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10_eval.py) | Evaluates the predictive performance of a CIFAR-10 model. + + +## CIFAR-10 Model + +The CIFAR-10 network is largely contained in +[`cifar10.py`](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/image/cifar10/cifar10.py). +The complete training +graph contains roughly 765 operations. We find that we can make the code most +reusable by constructing the graph with the following modules: + +1. [**Model inputs:**](#model-inputs) `inputs()` and `distorted_inputs()` add +operations that read and preprocess CIFAR images for evaluation and training, +respectively. +1. [**Model prediction:**](#model-prediction) `inference()` +adds operations that perform inference, i.e. classification, on supplied images. +1. [**Model training:**](#model-training) `loss()` and `train()` +add operations that compute the loss, +gradients, variable updates and visualization summaries. + +### Model Inputs + +The input part of the model is built by the functions `inputs()` and +`distorted_inputs()` which read images from the CIFAR-10 binary data files. +These files contain fixed byte length records, so we use +[`tf.FixedLengthRecordReader`](../../api_docs/python/io_ops.md#FixedLengthRecordReader). +See [`Reading Data`](../../how_tos/reading_data/index.md#reading-from-files) to +learn more about how the `Reader` class works. + +The images are processed as follows: + +* They are cropped to 24 x 24 pixels, centrally for evaluation or + [randomly](../../api_docs/python/image.md#random_crop) for training. +* They are [approximately whitened](../../api_docs/python/image.md#per_image_whitening) + to make the model insensitive to dynamic range. + +For training, we additionally apply a series of random distortions to +artificially increase the data set size: + +* [Randomly flip](../../api_docs/python/image.md#random_flip_left_right) the image from left to right. +* Randomly distort the [image brightness](../../api_docs/python/image.md#random_brightness). +* Randomly distort the [image contrast](../../api_docs/python/image.md#tf_image_random_contrast). + +Please see the [`Images`](../../api_docs/python/image.md) page for the list of +available distortions. We also attach an +[`image_summary`](../../api_docs/python/train.md?#image_summary) to the images +so that we may visualize them in TensorBoard. This is a good practice to verify +that inputs are built correctly. + +<div style="width:50%; margin:auto; margin-bottom:10px; margin-top:20px;"> + <img style="width:70%" src="./cifar_image_summary.png"> +</div> + +Reading images from disk and distorting them can use a non-trivial amount of +processing time. To prevent these operations from slowing down training, we run +them inside 16 separate threads which continuously fill a TensorFlow +[queue](../../api_docs/python/io_ops.md#shuffle_batch). + +### Model Prediction + +The prediction part of the model is constructed by the `inference()` function +which adds operations to compute the *logits* of the predictions. That part of +the model is organized as follows: + +Layer Name | Description +--- | --- +`conv1` | [convolution](../../api_docs/python/nn.md#conv2d) and [rectified linear](../../api_docs/python/nn.md#relu) activation. +`pool1` | [max pooling](../../api_docs/python/nn.md#max_pool). +`norm1` | [local response normalization](../../api_docs/python/nn.md#local_response_normalization). +`conv2` | [convolution](../../api_docs/python/nn.md#conv2d) and [rectified linear](../../api_docs/python/nn.md#relu) activation. +`norm2` | [local response normalization](../../api_docs/python/nn.md#local_response_normalization). +`pool2` | [max pooling](../../api_docs/python/nn.md#max_pool). +`local3` | [fully connected layer with rectified linear activation](../../api_docs/python/nn.md). +`local4` | [fully connected layer with rectified linear activation](../../api_docs/python/nn.md). +`softmax_linear` | linear transformation to produce logits. + +Here is a graph generated from TensorBoard describing the inference operation: + +<div style="width:15%; margin:auto; margin-bottom:10px; margin-top:20px;"> + <img style="width:100%" src="./cifar_graph.png"> +</div> + +> **EXERCISE**: The output of `inference` are un-normalized logits. Try editing +the network architecture to return normalized predictions using [`tf.softmax()`] +(../../api_docs/python/nn.md?cl=head#softmax). + +The `inputs()` and `inference()` functions provide all of the components +necessary to perform evaluation on a model. We now shift our focus towards +building operations for training a model. + +> **EXERCISE:** The model architecture in `inference()` differs slightly from +the CIFAR-10 model specified in +[cuda-convnet](https://code.google.com/p/cuda-convnet/). In particular, the top +layers are locally connected and not fully connected. Try editing the +architecture to exactly replicate that fully connected model. + +### Model Training + +The usual method for training a network to perform N-way classification is +[multinomial logistic regression](https://en.wikipedia.org/wiki/Multinomial_logistic_regression), +aka. *softmax regression*. Softmax regression applies a +[softmax](../../api_docs/python/nn.md#softmax) nonlinearity to the +output of the network and calculates the +[cross-entropy](../../api_docs/python/nn.md#softmax_cross_entropy_with_logits) +between the normalized predictions and a +[1-hot encoding](../../api_docs/python/sparse_ops.md#sparse_to_dense) of the label. +For regularization, we also apply the usual +[weight decay](../../api_docs/python/nn.md#l2_loss) losses to all learned +variables. The objective function for the model is the sum of the cross entropy +loss and all these weight decay terms, as returned by the `loss()` function. + +We visualize it in TensorBoard with a [scalar_summary](../../api_docs/python/train.md?#scalar_summary): + +[](#TODO(migmigmig)#TODO(danmane)) + +We train the model using standard +[gradient descent](https://en.wikipedia.org/wiki/Gradient_descent) +algorithm (see [Training](../../api_docs/python/train.md) for other methods) +with a learning rate that +[exponentially decays](../../api_docs/python/train.md#exponential_decay) +over time. + +[](#TODO(migmigmig)#TODO(danmane)) + +The `train()` function adds the operations needed to minimize the objective by +calculating the gradient and updating the learned variables (see +[`GradientDescentOptimizer`](../../api_docs/python/train.md#GradientDescentOptimizer) +for details). It returns an operation that executes all of the calculations +needed to train and update the model for one batch of images. + +## Launching and Training the Model + +We have built the model, let's now launch it and run the training operation with +the script `cifar10_train.py`. + +```shell +python cifar10_train.py +``` + +**NOTE:** The first time your run any target in the CIFAR-10 tutorial, +the CIFAR-10 dataset is automatically downloaded. The data set is ~160MB +so you may want to grab a quick cup of coffee for your first run. + +You should see the output: + +```shell +Filling queue with 20000 CIFAR images before starting to train. This will take a few minutes. +2015-11-04 11:45:45.927302: step 0, loss = 4.68 (2.0 examples/sec; 64.221 sec/batch) +2015-11-04 11:45:49.133065: step 10, loss = 4.66 (533.8 examples/sec; 0.240 sec/batch) +2015-11-04 11:45:51.397710: step 20, loss = 4.64 (597.4 examples/sec; 0.214 sec/batch) +2015-11-04 11:45:54.446850: step 30, loss = 4.62 (391.0 examples/sec; 0.327 sec/batch) +2015-11-04 11:45:57.152676: step 40, loss = 4.61 (430.2 examples/sec; 0.298 sec/batch) +2015-11-04 11:46:00.437717: step 50, loss = 4.59 (406.4 examples/sec; 0.315 sec/batch) +... +``` + +The script reports the total loss every 10 steps as well the speed at which +the last batch of data was processed. A few comments: + +* The first batch of data can be inordinately slow (e.g. several minutes) as the +preprocessing threads fill up the shuffling queue with 20,000 processed CIFAR +images. + +* The reported loss is the average loss of the most recent batch. Remember that +this loss is the sum of the cross entropy and all weight decay terms. + +* Keep an eye on the processing speed of a batch. The numbers shown above were +run on a Tesla K40c. If you are running on a CPU, expect slower performance. + + +> **EXERCISE:** When experimenting, it is sometimes annoying that the first +training step can take so long. Try decreasing the number of images initially +that initially fill up the queue. Search for `NUM_EXAMPLES_PER_EPOCH_FOR_TRAIN` +in `cifar10.py`. + +`cifar10_train.py` periodically [saves](../../api_docs/python/state_ops.md#Saver) +all model parameters in +[checkpoint files](../../how_tos/variables.md#saving-and-restoring) +but it does *not* evaluate the model. The checkpoint file +will be used by `cifar10_eval.py` to measure the predictive +performance (see [Evaluating a Model](#evaluating-a-model) below). + + +If you followed the previous steps, then you have now started training +a CIFAR-10 model. [Congratulations!](https://www.youtube.com/watch?v=9bZkp7q19f0) + +The terminal text returned from `cifar10_train.py` provides minimal insight into +how the model is training. We want more insight into the model during training: + +* Is the loss *really* decreasing or is that just noise? +* Is the model being provided appropriate images? +* Are the gradients, activations and weights reasonable? +* What is the learning rate currently at? + +[TensorBoard](../../how_tos/summaries_and_tensorboard/index.md) provides this +functionality, displaying data exported periodically from `cifar10_train.py` via +a +[`SummaryWriter`](../../api_docs/python/train.md#SummaryWriter). + +For instance, we can watch how the distribution of activations and degree of +sparsity in `local3` features evolve during training: + +<div style="width:100%; margin:auto; margin-bottom:10px; margin-top:20px; display: flex; flex-direction: row"> + <img style="flex-grow:1; flex-shrink:1;" src="./cifar_sparsity.png"> + <img style="flex-grow:1; flex-shrink:1;" src="./cifar_activations.png"> +</div> + +Individual loss functions, as well as the total loss, are particularly +interesting to track over time. However, the loss exhibits a considerable amount +of noise due to the small batch size employed by training. In practice we find +it extremely useful to visualize their moving averages in addition to their raw +values. See how the scripts use +[ExponentialMovingAverage](../../api_docs/python/train.md#ExponentialMovingAverage) +for this purpose. + +## Evaluating a Model + +Let us now evaluate how well the trained model performs on a hold-out data set. +the model is evaluated by the script `cifar10_eval.py`. It constructs the model +with the `inference()` function and uses all 10,000 images in the evaluation set +of CIFAR-10. It calculates the *precision at 1:* how often the top prediction +matches the true label of the image. + +To monitor how the model improves during training, the evaluation script runs +periodically on the latest checkpoint files created by the `cifar10_train.py`. + +```shell +python cifar10_eval.py +``` + +> Be careful not to run the evaluation and training binary on the same GPU or +else you might run out of memory. Consider running the evaluation on +a separate GPU if available or suspending the training binary while running +the evaluation on the same GPU. + +You should see the output: + +```shell +2015-11-06 08:30:44.391206: precision @ 1 = 0.860 +... +``` + +The script merely returns the precision @ 1 periodically -- in this case +it returned 86% accuracy. `cifar10_eval.py` also +exports summaries that may be visualized in TensorBoard. These summaries +provide additional insight into the model during evaluation. + +The training script calculates the +[moving average](../../api_docs/python/train.md#ExponentialMovingAverage) +version of all learned variables. The evaluation script substitutes +all learned model parameters with the moving average version. This +substitution boosts model performance at evaluation time. + +> **EXERCISE:** Employing averaged parameters may boost predictive performance +by about 3% as measured by precision@1. Edit `cifar10_eval.py` to not employ the +averaged parameters for the model and verify that the predictive performance +drops. + + +## Training a Model Using Multiple GPU Cards + +Modern workstations may contain multiple GPUs for scientific computation. +TensorFlow can leverage this environment to run the training operation +concurrently across multiple cards. + +Training a model in a parallel, distributed fashion requires +coordinating training processes. For what follows we term *model replica* +to be one copy of a model training on a subset of data. + +Naively employing asynchronous updates of model parameters +leads to sub-optimal training performance +because an individual model replica might be trained on a stale +copy of the model parameters. Conversely, employing fully synchronous +updates will be as slow as the slowest model replica. + +In a workstation with multiple GPU cards, each GPU will have similar speed +and contain enough memory to run an entire CIFAR-10 model. Thus, we opt to +design our training system in the following manner: + +* Place an individual model replica on each GPU. +* Update model parameters synchronously by waiting for all GPUs to finish +processing a batch of data. + +Here is a diagram of this model: + +<div style="width:40%; margin:auto; margin-bottom:10px; margin-top:20px;"> + <img style="width:100%" src="./Parallelism.png"> +</div> + +Note that each GPU computes inference as well as the gradients for a unique +batch of data. This setup effectively permits dividing up a larger batch +of data across the GPUs. + +This setup requires that all GPUs share the model parameters. A well-known +fact is that transferring data to and from GPUs is quite slow. For this +reason, we decide to store and update all model parameters on the CPU (see +green box). A fresh set of model parameters are transferred to the GPU +when a new batch of data is processed by all GPUs. + +The GPUs are synchronized in operation. All gradients are accumulated from +the GPUs and averaged (see green box). The model parameters are updated with +the gradients averaged across all model replicas. + +### Placing Variables and Operations on Devices + +Placing operations and variables on devices requires some special +abstractions. + +The first abstraction we require is a function for computing inference and +gradients for a single model replica. In the code we term this abstraction +a *tower*. We must set two attributes for each tower: + +* A unique name for all operations within a tower. +[`tf.name_scope()`](../../api_docs/python/framework.md#name_scope) provides +this unique name by prepending a scope. For instance, all operations in +the first tower are prepended with `tower_0`, e.g. `tower_0/conv1/Conv2D`. + +* A preferred hardware device to run the operation within a tower. +[`tf.device()`](../../api_docs/python/framework.md#device) specifies this. For +instance, all operations in the first tower reside within `device('/gpu:0')` +scope indicating that they should be run on the first GPU. + +All variables are pinned to the CPU and accessed via +[`tf.get_variable()`](../../api_docs/python/state_ops.md#get_variable) +in order to share them in a multi-GPU version. +See how-to on [Sharing Variables](../../how_tos/variable_scope/index.md). + +### Launching and Training the Model on Multiple GPU cards + +If you have several GPU cards installed on your machine you can use them to +train the model faster with the `cifar10_multi_gpu_train.py` script. It is a +variation of the training script that parallelizes the model across multiple GPU +cards. + +```shell +python cifar10_multi_gpu_train.py --num_gpus=2 +``` + +The training script should output: + +```shell +Filling queue with 20000 CIFAR images before starting to train. This will take a few minutes. +2015-11-04 11:45:45.927302: step 0, loss = 4.68 (2.0 examples/sec; 64.221 sec/batch) +2015-11-04 11:45:49.133065: step 10, loss = 4.66 (533.8 examples/sec; 0.240 sec/batch) +2015-11-04 11:45:51.397710: step 20, loss = 4.64 (597.4 examples/sec; 0.214 sec/batch) +2015-11-04 11:45:54.446850: step 30, loss = 4.62 (391.0 examples/sec; 0.327 sec/batch) +2015-11-04 11:45:57.152676: step 40, loss = 4.61 (430.2 examples/sec; 0.298 sec/batch) +2015-11-04 11:46:00.437717: step 50, loss = 4.59 (406.4 examples/sec; 0.315 sec/batch) +... +``` + +Note that the number of GPU cards used defaults to 1. Additionally, if only 1 +GPU is available on your machine, all computations will be placed on it, even if +you ask for more. + +> **EXERCISE:** The default settings for `cifar10_train.py` is to +run on a batch size of 128. Try running `cifar10_multi_gpu_train.py` on 2 GPUs +with a batch size of 64 and compare the training speed. + +## Next Steps + +[Congratulations!](https://www.youtube.com/watch?v=9bZkp7q19f0). You have +completed the CIFAR-10 tutorial. + +If you are now interested in developing and training your own image +classification system, we recommend forking this tutorial and replacing +components to build address your image classification problem. + +> **EXERCISE:** Download the +[Street View House Numbers (SVHN)](http://ufldl.stanford.edu/housenumbers/) data set. +Fork the CIFAR-10 tutorial and swap in the SVHN as the input data. Try adapting +the network architecture to improve predictive performance. + + + diff --git a/tensorflow/g3doc/tutorials/index.md b/tensorflow/g3doc/tutorials/index.md new file mode 100644 index 0000000000..726a5c6687 --- /dev/null +++ b/tensorflow/g3doc/tutorials/index.md @@ -0,0 +1,142 @@ +# Overview + + +## ML for Beginners + +If you're new to machine learning, we recommend starting here. You'll learn +about a classic problem, handwritten digit classification (MNIST), and get a +gentle introduction to multiclass classification. + +[View Tutorial](mnist/beginners/index.md) + + +## MNIST for Pros + +If you're already familiar with other deep learning software packages, and are +already familiar with MNIST, this tutorial with give you a very brief primer on +TensorFlow. + +[View Tutorial](mnist/pros/index.md) + + +## TensorFlow Mechanics 101 + +This is a technical tutorial, where we walk you through the details of using +TensorFlow infrastructure to train models at scale. We use again MNIST as the +example. + +[View Tutorial](mnist/tf/index.md) + + +## Convolutional Neural Networks + +An introduction to convolutional neural networks using the CIFAR-10 data set. +Convolutional neural nets are particularly tailored to images, since they +exploit translation invariance to yield more compact and effective +representations of visual content. + +[View Tutorial](deep_cnn/index.md) + + +## Vector Representations of Words + +This tutorial motivates why it is useful to learn to represent words as vectors +(called *word embeddings*). It introduces the word2vec model as an efficient +method for learning embeddings. It also covers the high-level details behind +noise-contrastive training methods (the biggest recent advance in training +embeddings). + +[View Tutorial](word2vec/index.md) + + +## Recurrent Neural Networks + +An introduction to RNNs, wherein we train an LSTM network to predict the next +word in an English sentence. (A task sometimes called language modeling.) + +[View Tutorial](recurrent/index.md) + + +## Sequence-to-Sequence Models + +A follow on to the RNN tutorial, where we assemble a sequence-to-sequence model +for machine translation. You will learn to build your own English-to-French +translator, entirely machine learned, end-to-end. + +[View Tutorial](seq2seq/index.md) + + +## Mandelbrot Set + +TensorFlow can be used for computation that has nothing to do with machine +learning. Here's a naive implementation of Mandelbrot set visualization. + +[View Tutorial](mandelbrot/index.md) + + +## Partial Differential Equations + +As another example of non-machine learning computation, we offer an example of +a naive PDE simulation of raindrops landing on a pond. + +[View Tutorial](pdes/index.md) + + +## MNIST Data Download + +Details about downloading the MNIST handwritten digits data set. Exciting +stuff. + +[View Tutorial](mnist/download/index.md) + + +## Sparse Linear Regression + +In many practical machine learning settings we have a large number input +features, only very few of which are active for any given example. TensorFlow +has great tools for learning predictive models in these settings. + +COMING SOON + + +## Visual Object Recognition + +We will be releasing our state-of-the-art Inception object recognition model, +complete and already trained. + +COMING SOON + + +## Deep Dream Visual Hallucinations + +Building on the Inception recognition model, we will release a TensorFlow +version of the [Deep Dream](https://github.com/google/deepdream) neural network +visual hallucination software. + +COMING SOON + + +## Automated Image Captioning + +TODO(vinyals): Write me, three lines max. + +COMING SOON + + + +<div class='sections-order' style="display: none;"> +<!-- +<!-- mnist/beginners/index.md --> +<!-- mnist/pros/index.md --> +<!-- mnist/tf/index.md --> +<!-- deep_cnn/index.md --> +<!-- word2vec/index.md --> +<!-- recurrent/index.md --> +<!-- seq2seq/index.md --> +<!-- mandelbrot/index.md --> +<!-- pdes/index.md --> +<!-- mnist/download/index.md --> +--> +</div> + + diff --git a/tensorflow/g3doc/tutorials/mandelbrot/index.md b/tensorflow/g3doc/tutorials/mandelbrot/index.md new file mode 100755 index 0000000000..7c6adcb4e8 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mandelbrot/index.md @@ -0,0 +1,97 @@ + + +``` +#Import libraries for simulation +import tensorflow as tf +import numpy as np + +#Imports for visualization +import PIL.Image +from cStringIO import StringIO +from IPython.display import clear_output, Image, display +import scipy.ndimage as nd +``` + + +``` +def DisplayFractal(a, fmt='jpeg'): + """Display an array of iteration counts as a + colorful picture of a fractal.""" + a_cyclic = (6.28*a/20.0).reshape(list(a.shape)+[1]) + img = np.concatenate([10+20*np.cos(a_cyclic), + 30+50*np.sin(a_cyclic), + 155-80*np.cos(a_cyclic)], 2) + img[a==a.max()] = 0 + a = img + a = np.uint8(np.clip(a, 0, 255)) + f = StringIO() + PIL.Image.fromarray(a).save(f, fmt) + display(Image(data=f.getvalue())) +``` + + +``` +sess = tf.InteractiveSession() +``` + + Exception AssertionError: AssertionError() in <bound method InteractiveSession.__del__ of <tensorflow.python.client.session.InteractiveSession object at 0x6247390>> ignored + + + +``` +# Use NumPy to create a 2D array of complex numbers on [-2,2]x[-2,2] + +Y, X = np.mgrid[-1.3:1.3:0.005, -2:1:0.005] +Z = X+1j*Y +``` + + +``` +xs = tf.constant(Z.astype("complex64")) +zs = tf.Variable(xs) +ns = tf.Variable(tf.zeros_like(xs, "float32")) +``` + + +``` +tf.InitializeAllVariables().run() +``` + + +``` +# Compute the new values of z: z^2 + x +zs_ = zs*zs + xs + +# Have we diverged with this new value? +not_diverged = tf.complex_abs(zs_) < 4 + +# Operation to update the zs and the iteration count. +#t +# Note: We keep computing zs after they diverge! This +# is very wasteful! There are better, if a little +# less simple, ways to do this. +# +step = tf.group( + zs.assign(zs_), + ns.assign_add(tf.cast(not_diverged, "float32")) + ) +``` + + +``` +for i in range(200): step.run() +``` + + +``` +DisplayFractal(ns.eval()) +``` + + + + + + +``` + +``` diff --git a/tensorflow/g3doc/tutorials/mandelbrot/output_8_0.jpe b/tensorflow/g3doc/tutorials/mandelbrot/output_8_0.jpe Binary files differnew file mode 100755 index 0000000000..8e261d44a8 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mandelbrot/output_8_0.jpe diff --git a/tensorflow/g3doc/tutorials/mnist/__init__.py b/tensorflow/g3doc/tutorials/mnist/__init__.py new file mode 100755 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/__init__.py diff --git a/tensorflow/g3doc/tutorials/mnist/beginners/index.md b/tensorflow/g3doc/tutorials/mnist/beginners/index.md new file mode 100644 index 0000000000..8ccb69d977 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/beginners/index.md @@ -0,0 +1,420 @@ +# MNIST Softmax Regression (For Beginners) + +*This tutorial is intended for readers who are new to both machine learning and +TensorFlow. If you already +know what MNIST is, and what softmax (multinomial logistic) regression is, +you might prefer this [faster paced tutorial](../pros/index.md).* + +When one learns how to program, there's a tradition that the first thing you do +is print "Hello World." Just like programming has Hello World, machine learning +has MNIST. + +MNIST is a simple computer vision dataset. It consists of images of handwritten +digits like these: + +<div style="width:40%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/MNIST.png"> +</div> + +It also includes labels for each image, telling us which digit it is. For +example, the labels for the above images are 5, 0, 4, and 1. + +In this tutorial, we're going to train a model to look at images and predict +what digits they are. Our goal isn't to train a really elaborate model that +achieves state-of-the-art performance -- although we'll give you code to do that +later! -- but rather to dip a toe into using TensorFlow. As such, we're going +to start with a very simple model, called a Softmax Regression. + +The actual code for this tutorial is very short, and all the interesting +stuff happens in just three lines. However, it is very +important to understand the ideas behind it: both how TensorFlow works and the +core machine learning concepts. Because of this, we are going to very carefully +work through the code. + +## The MNIST Data + +The MNIST data is hosted on +[Yann LeCun's website](http://yann.lecun.com/exdb/mnist/). +For your convenience, we've included some python code to download and install +the data automatically. You can either download [the code](../input_data.py) and +import it as below, or simply copy and paste it in. + +```python +import input_data +mnist = input_data.read_data_sets("MNIST_data/", one_hot=True) +``` + +The downloaded data is split into two parts, 60,000 data points of training +data (`mnist.train`) and 10,000 points of test data (`mnist.test`). This +split is very important: it's essential in machine learning that we +have separate data which we don't learn from so that we can make sure +that what we've learned actually generalizes! + +As mentioned earlier, every MNIST data point has two parts: an image of a +handwritten digit and a corresponding label. We will call the images "xs" and +the labels "ys". Both the training set and test set contain xs and ys, for +example the training images are `mnist.train.images` and the train labels are +`mnist.train.labels`. + +Each image is 28 pixels by 28 pixels. We can interpret this as a big array of +numbers: + +<div style="width:50%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/MNIST-Matrix.png"> +</div> + +We can flatten this array into a vector of 28x28 = 784 numbers. It doesn't +matter how we flatten the array, as long as we're consistent between images. +From this perspective, the MNIST images are just a bunch of points in a +784-dimensional vector space, with a +[very rich structure](http://colah.github.io/posts/2014-10-Visualizing-MNIST/) +(warning: computationally intensive visualizations). + +Flattening the data throws away information about the 2D structure of the image. +Isn't that bad? Well, the best computer vision methods do exploit this +structure, and we will in later tutorials. But the simple method we will be +using here, a softmax regression, won't. + +The result is that `mnist.train.images` is a tensor (an n-dimensional array) with a +shape of `[60000, 784]`. The first dimension indexes the images and the second +dimension indexes the pixels in each image. Each entry in the tensor is the +pixel intensity between 0 and 1, for a particular pixel in a particular image. + +<div style="width:40%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/mnist-train-xs.png"> +</div> + +The corresponding labels in MNIST are numbers between 0 and 9, describing +which digit a given image is of. +For the purposes of this tutorial, we're going to want our labels as +as "one-hot vectors". A one-hot vector is a vector which is 0 in most +dimensions, and 1 in a single dimension. In this case, the $$n$$th digit will be +represented as a vector which is 1 in the $$n$$th dimensions. For example, 0 +would be $$[1,0,0,0,0,0,0,0,0,0,0]$$. +Consequently, `mnist.train.labels` is a +`[60000, 10]` array of floats. + +<div style="width:40%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/mnist-train-ys.png"> +</div> + +We're now ready to actually make our model! + +## Softmax Regressions + +We know that every image in MNIST is a digit, whether it's a zero or a nine. We +want to be able to look at an image and give probabilities for it being each +digit. For example, our model might look at a picture of a nine and be 80% sure +it's a nine, but give a 5% chance to it being an eight (because of the top loop) +and a bit of probability to all the others because it isn't sure. + +This is a classic case where a softmax regression is a natural, simple model. +If you want to assign probabilities to an object being one of several different +things, softmax is the thing to do. Even later on, when we train more +sophisticated models, the final step will be a layer of softmax. + +A softmax regression has two steps: first we add up the evidence of our input +being in certain classes, and then we convert that evidence into probabilities. + +To tally up the evidence that a given image is in a particular class, we do a +weighted sum of the pixel intensities. The weight is negative if that pixel +having a high intensity is evidence against the image being in that class, +and positive if it is evidence in favor. + +The following diagram shows the weights one model learned for each of these +classes. Red represents negative weights, while blue represents positive +weights. + +<div style="width:40%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/softmax-weights.png"> +</div> + +We also add some extra evidence called a bias. Basically, we want to be able +to say that some things are more likely independent of the input. The result is +that the evidence for a class $$i$$ given an input $$x$$ is: + +$$\text{evidence}_i = \sum_j W_{i,~ j} x_j + b_i$$ + +where $$W_i$$ is the weights and $$b_i$$ is the bias for class $$i$$, and $$j$$ +is an index for summing over the pixels in our input image $$x$$. We then +convert the evidence tallies into our predicted probabilities +$$y$$ using the "softmax" function: + +$$y = \text{softmax}(\text{evidence})$$ + +Here softmax is serving as an "activation" or "link" function, shaping +the output of our linear function into the form we want -- in this case, a +probability distribution over 10 cases. +You can think of it as converting tallies +of evidence into probabilities of our input being in each class. +It's defined as: + +$$\text{softmax}(x) = \text{normalize}(\exp(x))$$ + +If you expand that equation out, you get: + +$$\text{softmax}(x)_i = \frac{\exp(x_i)}{\sum_j \exp(x_j)}$$ + +But it's often more helpful to think of softmax the first way: +exponentiating its inputs and then normalizing them. The exponentiation +means that one unit more evidence increases the weight given to any hypothesis +multiplicatively. And conversely, having one less unit of evidence means that a +hypothesis gets a fraction of its earlier weight. No hypothesis ever has zero +or negative weight. Softmax then normalizes these weights, so that they add up +to one, forming a valid probability distribution. (To get more intuition about +the softmax function, check out the +[section](http://neuralnetworksanddeeplearning.com/chap3.html#softmax) +on it in Michael Nieslen's book, complete with an interactive visualization.) + + +You can picture our softmax regression as looking something like the following, +although with a lot more $$x$$s. For each output, we compute a weighted sum of +the $$x$$s, add a bias, and then apply softmax. + +<div style="width:55%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/softmax-regression-scalargraph.png"> +</div> + +If we write that out as equations, we get: + +<div style="width:52%; margin-left:25%; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/softmax-regression-scalarequation.png"> +</div> + +We can "vectorize" this procedure, turning it into a matrix multiplication +and vector addition. This is helpful for computational efficiency. (It's also +a useful way to think.) + +<div style="width:50%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/softmax-regression-vectorequation.png"> +</div> + +More compactly, we can just write: + +$$y = \text{softmax}(Wx + b)$$ + + +## Implementing the Regression + + +To do efficient numerical computing in Python, we typically use libraries like +NumPy that do expensive operations such as matrix multiplication outside Python, +using highly efficient code implemented in another language. +Unfortunately, there can still be a lot of overhead from switching back to +Python every operation. This overhead is especially bad if you want to run +computations on GPUs or in a distributed manner, where there can be a high cost +to transferring data. + +TensorFlow also does its heavy lifting outside python, +but it takes things a step further to avoid this overhead. +Instead of running a single expensive operation independently +from Python, TensorFlow lets us describe a graph of interacting operations that +run entirely outside Python. (Approaches like this can be seen in a few +machine learning libraries.) + +To run computations, TensorFlow needs to connect to its backend. This connection +is called a `Session`. To use TensorFlow, we need to import it and create a +session. + +```python +import tensorflow as tf +sess = tf.InteractiveSession() +``` + +(Using an `InteractiveSession` makes TensorFlow a bit more flexible about how +you structure your code. In particular, it's helpful for work in interactive +contexts like iPython.) + +We describe these interacting operations by manipulating symbolic variables. +Let's create one: + +```python +x = tf.placeholder("float", [None, 784]) +``` + +`x` isn't a specific value. It's a `placeholder`, a value that we'll input when +we ask TensorFlow to run a computation. We want to be able to input any number +of MNIST images, each flattened into a 784-dimensional vector. We represent +this as a 2d tensor of floating point numbers, with a shape `[None, 784]`. +(Here `None` means that a dimension can be of any length.) + +We also need the weights and biases for our model. We could imagine treating +these like additional inputs, but TensorFlow has an even better way to handle +it: `Variable`. +A `Variable` is a modifiable tensor that lives in TensorFlow's graph of +interacting +operations. It can be used and even modified by the computation. For machine +learning applications, one generally has the model parameters be `Variable`s. + +```python +W = tf.Variable(tf.zeros([784,10])) +b = tf.Variable(tf.zeros([10])) +``` + +We create these `Variable`s by giving `tf.Variable` the initial value of the +`Variable`: in this case, we initialize both `W` and `b` as tensors full of +zeros. Since we are going to learn `W` and `b`, it doesn't matter very much +what they initially are. + +Notice that `W` has a shape of [784, 10] because we want to multiply the +784-dimensional image vectors by it to produce 10-dimensional vectors of +evidence for the difference classes. `b` has a shape of [10] so we can add it +to the output. + +We can now implement our model. It only takes one line! + +```python +y = tf.nn.softmax(tf.matmul(x,W) + b) +``` + +First, we multiply `x` by `W` with the expression `tf.matmul(x,W)`. This is +flipped from when we multiplied them in our equation, where we had $$Wx$$, as a +small trick +to deal with `x` being a 2D tensor with multiple inputs. We then add `b`, and +finally apply `tf.nn.softmax`. + +That's it. It only took us one line to define our model, after a couple short +lines of setup. That isn't because TensorFlow is designed to make a softmax +regression particularly easy: it's just a very flexible way to describe many +kinds of numerical computations, from machine learning models to physics +simulations. And once defined, our model can be run on different devices: +your computer's CPU, GPUs, and even phones! + + +## Training + +In order to train our model, we need to define what it means for the model to +be good. Well, actually, in machine learning we typically define what it means +for a model to be bad, called the cost or loss, and then try to minimize how bad +it is. But the two are equivalent. + +One very common, very nice cost function is "cross-entropy." Surprisingly, +cross-entropy arises from thinking about information compressing codes in +information theory but it winds up being an important idea in lots of areas, +from gambling to machine learning. It's defined: + +$$H_{y'}(y) = -\sum_i y'_i \log(y_i)$$ + +Where $$y$$ is our predicted probability distribution, and $$y'$$ is the true +distribution (the one-hot vector we'll input). In some rough sense, the +cross-entropy is measuring how inefficient our predictions are for describing +the truth. Going into more detail about cross-entropy is beyond the scope of +this tutorial, but it's well worth +[understanding](http://colah.github.io/posts/2015-09-Visual-Information/). + +To implement cross-entropy we need to first add a new placeholder to input +the correct answers: + +```python +y_ = tf.placeholder("float", [None,10]) +``` + +Then we can implement the cross-entropy, $$-\sum y'\log(y)$$: + +```python +cross_entropy = -tf.reduce_sum(y_*tf.log(y)) +``` + +First, `tf.log` computes the logarithm of each element of `y`. Next, we multiply +each element of `y_` with the corresponding element of `tf.log(y_)`. Finally, +`tf.reduce_sum` adds all the elements of the tensor. (Note that this isn't +just the cross-entropy of the truth with a single prediction, but the sum of the +cross-entropies for all 100 images we looked at. How well we are doing on 100 +data points is a much better description of how good our model is than a single +data point.) + +Now that we know what we want our model to do, it's very easy to have TensorFlow +train it to do so. +Because TensorFlow know the entire graph of your computations, it +can automatically use the [backpropagation +algorithm](http://colah.github.io/posts/2015-08-Backprop/) +to efficiently determine how your variables affect the cost you ask it minimize. +Then it can apply your choice of optimization algorithm to modify the variables +and reduce the cost. + +```python +train_step = tf.train.GradientDescentOptimizer(0.01).minimize(cross_entropy) +``` + +In this case, we ask TensorFlow to minimize `cross_entropy` using the gradient +descent algorithm with a learning rate of 0.01. Gradient descent is a simple +procedure, where TensorFlow simply shifts each variable a little bit in the +direction that reduces the cost. But TensorFlow also provides +[many other optimization algorithms] +(../../../api_docs/python/train.md?#optimizers): using one is as simple as +tweaking one line. + +What TensorFlow actually does here, behind the scenes, is it adds new operations +to your graph which +implement backpropagation and gradient descent. Then it gives you back a +single operation which, when run, will do a step of gradient descent training, +slightly tweaking your variables to reduce the cost. + +Now we have our model set up to train. But before we start, we need to +initialize the variables we created: + +```python +tf.initialize_all_variables().run() +``` + +Let's train -- we'll run the training step 1000 times! + +```python +for i in range(1000): + batch_xs, batch_ys = mnist.train.next_batch(100) + train_step.run({x: batch_xs, y_: batch_ys}) +``` + +Each step of the loop, we get a "batch" of one hundred random data points from +our training set. We run `train_step` feeding in the batches data to replace +the `placeholder`s. + +Using small batches of random data is called stochastic training -- in +this case, stochastic gradient descent. Ideally, we'd like to use all our data +for every step of training because that would give us a better sense of what +we should be doing, but that's expensive. So, instead, we use a different subset +every time. Doing this is cheap and has much of the same benefit. + + + +## Evaluating Our Model + +How well does our model do? + +Well, first let's figure out where we predicted the correct label. `tf.argmax` +is an extremely useful function which gives you the index of the highest entry +in a tensor along some axis. For example, `tf.argmax(y,1)` is the label our +model thinks is most likely for each input, while `tf.argmax(y_,1)` is the +correct label. We can use `tf.equal` to check if our prediction matches the +truth. + +```python +correct_prediction = tf.equal(tf.argmax(y,1), tf.argmax(y_,1)) +``` + +That gives us a list of booleans. To determine what fraction are correct, we +cast to floating point numbers and then take the mean. For example, +`[True, False, True, True]` would become `[1,0,1,1]` which would become `0.75`. + +```python +accuracy = tf.reduce_mean(tf.cast(correct_prediction, "float")) +``` + +Finally, we ask for our accuracy on our test data. + +```python +print accuracy.eval({x: mnist.test.images, y_: mnist.test.labels}) +``` + +This should be about 91%. + +Is that good? Well, not really. In fact, it's pretty bad. This is because we're +using a very simple model. With some small changes, we can get to +97%. The best models can get to over 99.7% accuracy! (For more information, have +a look at this +[list of results](http://rodrigob.github.io/are_we_there_yet/build/classification_datasets_results.html).) + +What matters is that we learned from this model. Still, if you're feeling a bit +down about these results, check out [the next tutorial](../../index.md) where we +do a lot better, and learn how to build more sophisticated models using +TensorFlow! diff --git a/tensorflow/g3doc/tutorials/mnist/download/index.md b/tensorflow/g3doc/tutorials/mnist/download/index.md new file mode 100644 index 0000000000..dc11e727d8 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/download/index.md @@ -0,0 +1,85 @@ +# Downloading MNIST + +Code: [tensorflow/g3doc/tutorials/mnist/](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/g3doc/tutorials/mnist/) + +The goal of this tutorial is to show how to download the dataset files required +for handwritten digit classification using the (classic) MNIST data set. + +## Tutorial Files + +This tutorial references the following files: + +File | Purpose +--- | --- +[`input_data.py`](../input_data.py) | The code to download the MNIST dataset for training and evaluation. + +## Prepare the Data + +MNIST is a classic problem in machine learning. The problem is to look at +greyscale 28x28 pixel images of handwritten digits and determine which digit +the image represents, for all the digits from zero to nine. + + + +For more information, refer to [Yann LeCun's MNIST page](http://yann.lecun.com/exdb/mnist/) +or [Chris Olah's visualizations of MNIST](http://colah.github.io/posts/2014-10-Visualizing-MNIST/). + +### Download + +[Yann LeCun's MNIST page](http://yann.lecun.com/exdb/mnist/) +also hosts the training and test data for download. + +File | Purpose +--- | --- +[`train-images-idx3-ubyte.gz`](http://yann.lecun.com/exdb/mnist/train-images-idx3-ubyte.gz) | training set images - 55000 training images, 5000 validation images +[`train-labels-idx1-ubyte.gz`](http://yann.lecun.com/exdb/mnist/train-labels-idx1-ubyte.gz) | training set labels matching the images +[`t10k-images-idx3-ubyte.gz`](http://yann.lecun.com/exdb/mnist/t10k-images-idx3-ubyte.gz) | test set images - 10000 images +[`t10k-labels-idx1-ubyte.gz`](http://yann.lecun.com/exdb/mnist/t10k-labels-idx1-ubyte.gz) | test set labels matching the images + +In the `input_data.py` file, the `maybe_download()` function will ensure these +files are downloaded into a local data folder for training. + +The folder name is specified in a flag variable at the top of the +`fully_connected_feed.py` file and may be changed to fit your needs. + +### Unpack and Reshape + +The files themselves are not in any standard image format and are manually +unpacked (following the instructions available at the website) by the +`extract_images()` and `extract_labels()` functions in `input_data.py`. + +The image data is extracted into a 2d tensor of: `[image index, pixel index]` +where each entry is the intensity value of a specific pixel in a specific +image, rescaled from `[0, 255]` to `[-0.5, 0.5]`. The "image index" corresponds +to an image in the dataset, counting up from zero to the size of the dataset. +And the "pixel index" corresponds to a specific pixel in that image, ranging +from zero to the number of pixels in the image. + +The 60000 examples in the `train-*` files are then split into 55000 examples +for training and 5000 examples for validation. For all of the 28x28 +pixel greyscale images in the datasets the image size is 784 and so the output +tensor for the training set images is of shape `[55000, 784]`. + +The label data is extracted into a 1d tensor of: `[image index]` +with the class identifier for each example as the value. For the training set +labels, this would then be of shape `[55000]`. + +### DataSet Object + +The underlying code will download, unpack, and reshape images and labels for +the following datasets: + +Dataset | Purpose +--- | --- +`data_sets.train` | 55000 images and labels, for primary training. +`data_sets.validation` | 5000 images and labels, for iterative validation of training accuracy. +`data_sets.test` | 10000 images and labels, for final testing of trained accuracy. + +The `read_data_sets()` function will return a dictionary with a `DataSet` +instance for each of these three sets of data. The `DataSet.next_batch()` +method can be used to fetch a tuple consisting of `batch_size` lists of images +and labels to be fed into the running TensorFlow session. + +```python +images_feed, labels_feed = data_set.next_batch(FLAGS.batch_size) +``` diff --git a/tensorflow/g3doc/tutorials/mnist/fully_connected_feed.py b/tensorflow/g3doc/tutorials/mnist/fully_connected_feed.py new file mode 100644 index 0000000000..618c8f47cb --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/fully_connected_feed.py @@ -0,0 +1,219 @@ +"""Trains and Evaluates the MNIST network using a feed dictionary. + +TensorFlow install instructions: +https://tensorflow.org/get_started/os_setup.html + +MNIST tutorial: +https://tensorflow.org/tutorials/mnist/tf/index.html + +""" +# pylint: disable=missing-docstring +import os.path +import time + +import tensorflow.python.platform +import numpy +import tensorflow as tf + +from tensorflow.g3doc.tutorials.mnist import input_data +from tensorflow.g3doc.tutorials.mnist import mnist + + +# Basic model parameters as external flags. +flags = tf.app.flags +FLAGS = flags.FLAGS +flags.DEFINE_float('learning_rate', 0.01, 'Initial learning rate.') +flags.DEFINE_integer('max_steps', 2000, 'Number of steps to run trainer.') +flags.DEFINE_integer('hidden1', 128, 'Number of units in hidden layer 1.') +flags.DEFINE_integer('hidden2', 32, 'Number of units in hidden layer 2.') +flags.DEFINE_integer('batch_size', 100, 'Batch size. ' + 'Must divide evenly into the dataset sizes.') +flags.DEFINE_string('train_dir', 'data', 'Directory to put the training data.') +flags.DEFINE_boolean('fake_data', False, 'If true, uses fake data ' + 'for unit testing.') + + +def placeholder_inputs(batch_size): + """Generate placeholder variables to represent the the input tensors. + + These placeholders are used as inputs by the rest of the model building + code and will be fed from the downloaded data in the .run() loop, below. + + Args: + batch_size: The batch size will be baked into both placeholders. + + Returns: + images_placeholder: Images placeholder. + labels_placeholder: Labels placeholder. + """ + # Note that the shapes of the placeholders match the shapes of the full + # image and label tensors, except the first dimension is now batch_size + # rather than the full size of the train or test data sets. + images_placeholder = tf.placeholder(tf.float32, shape=(batch_size, + mnist.IMAGE_PIXELS)) + labels_placeholder = tf.placeholder(tf.int32, shape=(batch_size)) + return images_placeholder, labels_placeholder + + +def fill_feed_dict(data_set, images_pl, labels_pl): + """Fills the feed_dict for training the given step. + + A feed_dict takes the form of: + feed_dict = { + <placeholder>: <tensor of values to be passed for placeholder>, + .... + } + + Args: + data_set: The set of images and labels, from input_data.read_data_sets() + images_pl: The images placeholder, from placeholder_inputs(). + labels_pl: The labels placeholder, from placeholder_inputs(). + + Returns: + feed_dict: The feed dictionary mapping from placeholders to values. + """ + # Create the feed_dict for the placeholders filled with the next + # `batch size ` examples. + images_feed, labels_feed = data_set.next_batch(FLAGS.batch_size, + FLAGS.fake_data) + feed_dict = { + images_pl: images_feed, + labels_pl: labels_feed, + } + return feed_dict + + +def do_eval(sess, + eval_correct, + images_placeholder, + labels_placeholder, + data_set): + """Runs one evaluation against the full epoch of data. + + Args: + sess: The session in which the model has been trained. + eval_correct: The Tensor that returns the number of correct predictions. + images_placeholder: The images placeholder. + labels_placeholder: The labels placeholder. + data_set: The set of images and labels to evaluate, from + input_data.read_data_sets(). + """ + # And run one epoch of eval. + true_count = 0 # Counts the number of correct predictions. + steps_per_epoch = int(data_set.num_examples / FLAGS.batch_size) + num_examples = steps_per_epoch * FLAGS.batch_size + for step in xrange(steps_per_epoch): + feed_dict = fill_feed_dict(data_set, + images_placeholder, + labels_placeholder) + true_count += sess.run(eval_correct, feed_dict=feed_dict) + precision = float(true_count) / float(num_examples) + print ' Num examples: %d Num correct: %d Precision @ 1: %0.04f' % ( + num_examples, true_count, precision) + + +def run_training(): + """Train MNIST for a number of steps.""" + # Get the sets of images and labels for training, validation, and + # test on MNIST. + data_sets = input_data.read_data_sets(FLAGS.train_dir, FLAGS.fake_data) + + # Tell TensorFlow that the model will be built into the default Graph. + with tf.Graph().as_default(): + # Generate placeholders for the images and labels. + images_placeholder, labels_placeholder = placeholder_inputs( + FLAGS.batch_size) + + # Build a Graph that computes predictions from the inference model. + logits = mnist.inference(images_placeholder, + FLAGS.hidden1, + FLAGS.hidden2) + + # Add to the Graph the Ops for loss calculation. + loss = mnist.loss(logits, labels_placeholder) + + # Add to the Graph the Ops that calculate and apply gradients. + train_op = mnist.training(loss, FLAGS.learning_rate) + + # Add the Op to compare the logits to the labels during evaluation. + eval_correct = mnist.evaluation(logits, labels_placeholder) + + # Build the summary operation based on the TF collection of Summaries. + summary_op = tf.merge_all_summaries() + + # Create a saver for writing training checkpoints. + saver = tf.train.Saver() + + # Create a session for running Ops on the Graph. + sess = tf.Session() + + # Run the Op to initialize the variables. + init = tf.initialize_all_variables() + sess.run(init) + + # Instantiate a SummaryWriter to output summaries and the Graph. + summary_writer = tf.train.SummaryWriter(FLAGS.train_dir, + graph_def=sess.graph_def) + + # And then after everything is built, start the training loop. + for step in xrange(FLAGS.max_steps): + start_time = time.time() + + # Fill a feed dictionary with the actual set of images and labels + # for this particular training step. + feed_dict = fill_feed_dict(data_sets.train, + images_placeholder, + labels_placeholder) + + # Run one step of the model. The return values are the activations + # from the `train_op` (which is discarded) and the `loss` Op. To + # inspect the values of your Ops or variables, you may include them + # in the list passed to sess.run() and the value tensors will be + # returned in the tuple from the call. + _, loss_value = sess.run([train_op, loss], + feed_dict=feed_dict) + + duration = time.time() - start_time + + # Write the summaries and print an overview fairly often. + if step % 100 == 0: + # Print status to stdout. + print 'Step %d: loss = %.2f (%.3f sec)' % (step, + loss_value, + duration) + # Update the events file. + summary_str = sess.run(summary_op, feed_dict=feed_dict) + summary_writer.add_summary(summary_str, step) + + # Save a checkpoint and evaluate the model periodically. + if (step + 1) % 1000 == 0 or (step + 1) == FLAGS.max_steps: + saver.save(sess, FLAGS.train_dir, global_step=step) + # Evaluate against the training set. + print 'Training Data Eval:' + do_eval(sess, + eval_correct, + images_placeholder, + labels_placeholder, + data_sets.train) + # Evaluate against the validation set. + print 'Validation Data Eval:' + do_eval(sess, + eval_correct, + images_placeholder, + labels_placeholder, + data_sets.validation) + # Evaluate against the test set. + print 'Test Data Eval:' + do_eval(sess, + eval_correct, + images_placeholder, + labels_placeholder, + data_sets.test) + + +def main(_): + run_training() + + +if __name__ == '__main__': + tf.app.run() diff --git a/tensorflow/g3doc/tutorials/mnist/input_data.py b/tensorflow/g3doc/tutorials/mnist/input_data.py new file mode 100644 index 0000000000..88892027ff --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/input_data.py @@ -0,0 +1,175 @@ +"""Functions for downloading and reading MNIST data.""" +import gzip +import os +import urllib + +import numpy + +SOURCE_URL = 'http://yann.lecun.com/exdb/mnist/' + + +def maybe_download(filename, work_directory): + """Download the data from Yann's website, unless it's already here.""" + if not os.path.exists(work_directory): + os.mkdir(work_directory) + filepath = os.path.join(work_directory, filename) + if not os.path.exists(filepath): + filepath, _ = urllib.urlretrieve(SOURCE_URL + filename, filepath) + statinfo = os.stat(filepath) + print 'Succesfully downloaded', filename, statinfo.st_size, 'bytes.' + return filepath + + +def _read32(bytestream): + dt = numpy.dtype(numpy.uint32).newbyteorder('>') + return numpy.frombuffer(bytestream.read(4), dtype=dt) + + +def extract_images(filename): + """Extract the images into a 4D uint8 numpy array [index, y, x, depth].""" + print 'Extracting', filename + with gzip.open(filename) as bytestream: + magic = _read32(bytestream) + if magic != 2051: + raise ValueError( + 'Invalid magic number %d in MNIST image file: %s' % + (magic, filename)) + num_images = _read32(bytestream) + rows = _read32(bytestream) + cols = _read32(bytestream) + buf = bytestream.read(rows * cols * num_images) + data = numpy.frombuffer(buf, dtype=numpy.uint8) + data = data.reshape(num_images, rows, cols, 1) + return data + + +def dense_to_one_hot(labels_dense, num_classes=10): + """Convert class labels from scalars to one-hot vectors.""" + num_labels = labels_dense.shape[0] + index_offset = numpy.arange(num_labels) * num_classes + labels_one_hot = numpy.zeros((num_labels, num_classes)) + labels_one_hot.flat[index_offset + labels_dense.ravel()] = 1 + return labels_one_hot + + +def extract_labels(filename, one_hot=False): + """Extract the labels into a 1D uint8 numpy array [index].""" + print 'Extracting', filename + with gzip.open(filename) as bytestream: + magic = _read32(bytestream) + if magic != 2049: + raise ValueError( + 'Invalid magic number %d in MNIST label file: %s' % + (magic, filename)) + num_items = _read32(bytestream) + buf = bytestream.read(num_items) + labels = numpy.frombuffer(buf, dtype=numpy.uint8) + if one_hot: + return dense_to_one_hot(labels) + return labels + + +class DataSet(object): + + def __init__(self, images, labels, fake_data=False): + if fake_data: + self._num_examples = 10000 + else: + assert images.shape[0] == labels.shape[0], ( + "images.shape: %s labels.shape: %s" % (images.shape, + labels.shape)) + self._num_examples = images.shape[0] + + # Convert shape from [num examples, rows, columns, depth] + # to [num examples, rows*columns] (assuming depth == 1) + assert images.shape[3] == 1 + images = images.reshape(images.shape[0], + images.shape[1] * images.shape[2]) + # Convert from [0, 255] -> [0.0, 1.0]. + images = images.astype(numpy.float32) + images = numpy.multiply(images, 1.0 / 255.0) + self._images = images + self._labels = labels + self._epochs_completed = 0 + self._index_in_epoch = 0 + + @property + def images(self): + return self._images + + @property + def labels(self): + return self._labels + + @property + def num_examples(self): + return self._num_examples + + @property + def epochs_completed(self): + return self._epochs_completed + + def next_batch(self, batch_size, fake_data=False): + """Return the next `batch_size` examples from this data set.""" + if fake_data: + fake_image = [1.0 for _ in xrange(784)] + fake_label = 0 + return [fake_image for _ in xrange(batch_size)], [ + fake_label for _ in xrange(batch_size)] + start = self._index_in_epoch + self._index_in_epoch += batch_size + if self._index_in_epoch > self._num_examples: + # Finished epoch + self._epochs_completed += 1 + # Shuffle the data + perm = numpy.arange(self._num_examples) + numpy.random.shuffle(perm) + self._images = self._images[perm] + self._labels = self._labels[perm] + # Start next epoch + start = 0 + self._index_in_epoch = batch_size + assert batch_size <= self._num_examples + end = self._index_in_epoch + return self._images[start:end], self._labels[start:end] + + +def read_data_sets(train_dir, fake_data=False, one_hot=False): + class DataSets(object): + pass + data_sets = DataSets() + + if fake_data: + data_sets.train = DataSet([], [], fake_data=True) + data_sets.validation = DataSet([], [], fake_data=True) + data_sets.test = DataSet([], [], fake_data=True) + return data_sets + + TRAIN_IMAGES = 'train-images-idx3-ubyte.gz' + TRAIN_LABELS = 'train-labels-idx1-ubyte.gz' + TEST_IMAGES = 't10k-images-idx3-ubyte.gz' + TEST_LABELS = 't10k-labels-idx1-ubyte.gz' + VALIDATION_SIZE = 5000 + + local_file = maybe_download(TRAIN_IMAGES, train_dir) + train_images = extract_images(local_file) + + local_file = maybe_download(TRAIN_LABELS, train_dir) + train_labels = extract_labels(local_file, one_hot=one_hot) + + local_file = maybe_download(TEST_IMAGES, train_dir) + test_images = extract_images(local_file) + + local_file = maybe_download(TEST_LABELS, train_dir) + test_labels = extract_labels(local_file, one_hot=one_hot) + + validation_images = train_images[:VALIDATION_SIZE] + validation_labels = train_labels[:VALIDATION_SIZE] + train_images = train_images[VALIDATION_SIZE:] + train_labels = train_labels[VALIDATION_SIZE:] + + data_sets.train = DataSet(train_images, train_labels) + data_sets.validation = DataSet(validation_images, validation_labels) + data_sets.test = DataSet(test_images, test_labels) + + return data_sets diff --git a/tensorflow/g3doc/tutorials/mnist/mnist.py b/tensorflow/g3doc/tutorials/mnist/mnist.py new file mode 100644 index 0000000000..acf4d01dd1 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/mnist.py @@ -0,0 +1,148 @@ +"""Builds the MNIST network. + +Implements the inference/loss/training pattern for model building. + +1. inference() - Builds the model as far as is required for running the network +forward to make predictions. +2. loss() - Adds to the inference model the layers required to generate loss. +3. training() - Adds to the loss model the Ops required to generate and +apply gradients. + +This file is used by the various "fully_connected_*.py" files and not meant to +be run. + +TensorFlow install instructions: +https://tensorflow.org/get_started/os_setup.html + +MNIST tutorial: +https://tensorflow.org/tutorials/mnist/tf/index.html +""" +import math + +import tensorflow.python.platform +import tensorflow as tf + +# The MNIST dataset has 10 classes, representing the digits 0 through 9. +NUM_CLASSES = 10 + +# The MNIST images are always 28x28 pixels. +IMAGE_SIZE = 28 +IMAGE_PIXELS = IMAGE_SIZE * IMAGE_SIZE + + +def inference(images, hidden1_units, hidden2_units): + """Build the MNIST model up to where it may be used for inference. + + Args: + images: Images placeholder, from inputs(). + hidden1: Size of the first hidden layer. + hidden2: Size of the second hidden layer. + + Returns: + softmax_linear: Output tensor with the computed logits. + """ + # Hidden 1 + with tf.name_scope('hidden1') as scope: + weights = tf.Variable( + tf.truncated_normal([IMAGE_PIXELS, hidden1_units], + stddev=1.0 / math.sqrt(float(IMAGE_PIXELS))), + name='weights') + biases = tf.Variable(tf.zeros([hidden1_units]), + name='biases') + hidden1 = tf.nn.relu(tf.matmul(images, weights) + biases) + # Hidden 2 + with tf.name_scope('hidden2') as scope: + weights = tf.Variable( + tf.truncated_normal([hidden1_units, hidden2_units], + stddev=1.0 / math.sqrt(float(hidden1_units))), + name='weights') + biases = tf.Variable(tf.zeros([hidden2_units]), + name='biases') + hidden2 = tf.nn.relu(tf.matmul(hidden1, weights) + biases) + # Linear + with tf.name_scope('softmax_linear') as scope: + weights = tf.Variable( + tf.truncated_normal([hidden2_units, NUM_CLASSES], + stddev=1.0 / math.sqrt(float(hidden2_units))), + name='weights') + biases = tf.Variable(tf.zeros([NUM_CLASSES]), + name='biases') + logits = tf.matmul(hidden2, weights) + biases + return logits + + +def loss(logits, labels): + """Calculates the loss from the logits and the labels. + + Args: + logits: Logits tensor, float - [batch_size, NUM_CLASSES]. + labels: Labels tensor, int32 - [batch_size]. + + Returns: + loss: Loss tensor of type float. + """ + # Convert from sparse integer labels in the range [0, NUM_CLASSSES) + # to 1-hot dense float vectors (that is we will have batch_size vectors, + # each with NUM_CLASSES values, all of which are 0.0 except there will + # be a 1.0 in the entry corresponding to the label). + batch_size = tf.size(labels) + labels = tf.expand_dims(labels, 1) + indices = tf.expand_dims(tf.range(0, batch_size, 1), 1) + concated = tf.concat(1, [indices, labels]) + onehot_labels = tf.sparse_to_dense( + concated, tf.pack([batch_size, NUM_CLASSES]), 1.0, 0.0) + cross_entropy = tf.nn.softmax_cross_entropy_with_logits(logits, + onehot_labels, + name='xentropy') + loss = tf.reduce_mean(cross_entropy, name='xentropy_mean') + return loss + + +def training(loss, learning_rate): + """Sets up the training Ops. + + Creates a summarizer to track the loss over time in TensorBoard. + + Creates an optimizer and applies the gradients to all trainable variables. + + The Op returned by this function is what must be passed to the + `sess.run()` call to cause the model to train. + + Args: + loss: Loss tensor, from loss(). + learning_rate: The learning rate to use for gradient descent. + + Returns: + train_op: The Op for training. + """ + # Add a scalar summary for the snapshot loss. + tf.scalar_summary(loss.op.name, loss) + # Create the gradient descent optimizer with the given learning rate. + optimizer = tf.train.GradientDescentOptimizer(learning_rate) + # Create a variable to track the global step. + global_step = tf.Variable(0, name='global_step', trainable=False) + # Use the optimizer to apply the gradients that minimize the loss + # (and also increment the global step counter) as a single training step. + train_op = optimizer.minimize(loss, global_step=global_step) + return train_op + + +def evaluation(logits, labels): + """Evaluate the quality of the logits at predicting the label. + + Args: + logits: Logits tensor, float - [batch_size, NUM_CLASSES]. + labels: Labels tensor, int32 - [batch_size], with values in the + range [0, NUM_CLASSES). + + Returns: + A scalar int32 tensor with the number of examples (out of batch_size) + that were predicted correctly. + """ + # For a classifier model, we can use the in_top_k Op. + # It returns a bool tensor with shape [batch_size] that is true for + # the examples where the label's is was in the top k (here k=1) + # of all logits for that example. + correct = tf.nn.in_top_k(logits, labels, 1) + # Return the number of true entries. + return tf.reduce_sum(tf.cast(correct, tf.int32)) diff --git a/tensorflow/g3doc/tutorials/mnist/mnist_softmax.py b/tensorflow/g3doc/tutorials/mnist/mnist_softmax.py new file mode 100644 index 0000000000..640ea29dac --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/mnist_softmax.py @@ -0,0 +1,33 @@ +"""A very simple MNIST classifer. + +See extensive documentation at ??????? (insert public URL) +""" + +# Import data +import input_data +mnist = input_data.read_data_sets("/tmp/data/", one_hot=True) + +import tensorflow as tf +sess = tf.InteractiveSession() + +# Create the model +x = tf.placeholder("float", [None, 784]) +W = tf.Variable(tf.zeros([784,10])) +b = tf.Variable(tf.zeros([10])) +y = tf.nn.softmax(tf.matmul(x,W) + b) + +# Define loss and optimizer +y_ = tf.placeholder("float", [None,10]) +cross_entropy = -tf.reduce_sum(y_*tf.log(y)) +train_step = tf.train.GradientDescentOptimizer(0.01).minimize(cross_entropy) + +# Train +tf.initialize_all_variables().run() +for i in range(1000): + batch_xs, batch_ys = mnist.train.next_batch(100) + train_step.run({x: batch_xs, y_: batch_ys}) + +# Test trained model +correct_prediction = tf.equal(tf.argmax(y,1), tf.argmax(y_,1)) +accuracy = tf.reduce_mean(tf.cast(correct_prediction, "float")) +print accuracy.eval({x: mnist.test.images, y_: mnist.test.labels}) diff --git a/tensorflow/g3doc/tutorials/mnist/pros/index.md b/tensorflow/g3doc/tutorials/mnist/pros/index.md new file mode 100644 index 0000000000..17696712b0 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/pros/index.md @@ -0,0 +1,390 @@ +# MNIST Deep Learning Example (For Experts) + +TensorFlow is a powerful library for doing large-scale numerical computation. +One of the tasks at which it excels is implementing and training deep neural +networks. +In this tutorial we will learn the basic building blocks of a TensorFlow model +while constructing a deep convolutional MNIST classifier. + +*This introduction assumes familiarity with neural networks and the MNIST +dataset. If you don't have +a background with them, check out the +[introduction for beginners](../beginners/index.md).* + +## Setup + +Before we create our model, we will first load the MNIST dataset, and start a +TensorFlow session. + +### Load MNIST Data + +For your convenience, we've included [a script](../input_data.py) which +automatically downloads and imports the MNIST dataset. It will create a +directory `'MNIST_data'` in which to store the data files. + +```python +import input_data +mnist = input_data.read_data_sets('MNIST_data', one_hot=True) +``` + +Here `mnist` is a lightweight class which stores the training, validation, and +testing sets as NumPy arrays. +It also provides a function for iterating through data minibatches, which we +will use below. + +### Start TensorFlow Session + +Tensorflow relies on a highly efficient C++ backend to do its computation. The +connection to this backend is called a session. We will need to create a session +before we can do any computation. + +```python +import tensorflow as tf +sess = tf.InteractiveSession() +``` + +Using an `InteractiveSession` makes TensorFlow more flexible about how you +structure your code. +It allows you to interleave operations which build a +[computation graph](../../../get_started/basic_usage.md#the-computation-graph) +with ones that run the graph. +This is particularly convenient when working in interactive contexts like +iPython. +If you are not using an `InteractiveSession`, then you should build +the entire computation graph before starting a session and [launching the +graph](../../../get_started/basic_usage.md#launching-the-graph-in-a-session). + +#### Computation Graph + +To do efficient numerical computing in Python, we typically use libraries like +NumPy that do expensive operations such as matrix multiplication outside Python, +using highly efficient code implemented in another language. +Unfortunately, there can still be a lot of overhead from switching back to +Python every operation. This overhead is especially bad if you want to run +computations on GPUs or in a distributed manner, where there can be a high cost +to transferring data. + +TensorFlow also does its heavy lifting outside Python, +but it takes things a step further to avoid this overhead. +Instead of running a single expensive operation independently +from Python, TensorFlow lets us describe a graph of interacting operations that +run entirely outside Python. +This approach is similar to that used in Theano or Torch. + +The role of the Python code is therefore to build this external computation +graph, and to dictate which parts of the computation graph should be run. See +the +[Computation Graph](../../../get_started/basic_usage.md#the-computation-graph) +section of +[Basic Usage](../../../get_started/basic_usage.md) +for more detail. + +## Build a Softmax Regression Model + +In this section we will build a softmax regression model with a single linear +layer. In the next section, we will extend this to the case of softmax +regression with a multilayer convolutional network. + +### Placeholders + +We start building the computation graph by creating nodes for the +input images and target output classes. + +```python +x = tf.placeholder("float", shape=[None, 784]) +y_ = tf.placeholder("float", shape=[None, 10]) +``` + +Here `x` and `y_` aren't specific values. Rather, they are each a `placeholder` +-- a value that we'll input when we ask TensorFlow to run a computation. + +The input images `x` will consist of a 2d tensor of floating point numbers. +Here we assign it a `shape` of `[None, 784]`, where `784` is the dimensionality of +a single flattened MNIST image, and `None` indicates that the first dimension, +corresponding to the batch size, can be of any size. +The target output classes `y_` will also consist of a 2d tensor, +where each row is a one-hot 10-dimensional vector indicating +which digit class the corresponding MNIST image belongs to. + +The `shape` argument to `placeholder` is optional, but it allows TensorFlow +to automatically catch bugs stemming from inconsistent tensor shapes. + +### Variables + +We now define the weights `W` and biases `b` for our model. We could imagine treating +these like additional inputs, but TensorFlow has an even better way to handle +them: `Variable`. +A `Variable` is a value that lives in TensorFlow's computation graph. +It can be used and even modified by the computation. In machine +learning applications, one generally has the model paramaters be `Variable`s. + +```python +W = tf.Variable(tf.zeros([784,10])) +b = tf.Variable(tf.zeros([10])) +``` + +We pass the initial value for each parameter in the call to `tf.Variable`. +In this case, we initialize both `W` and `b` as tensors full of +zeros. `W` is a 784x10 matrix (because we have 784 input features +and 10 outputs) and `b` is a 10-dimensional vector (because we have 10 classes). + +Before `Variable`s can be used within a session, they must be initialized using +that session. +This step takes the initial values (in this case tensors full of zeros) that +have already been specified, and assigns them to each `Variable`. This can be +done for all `Variables` at once. + +```python +sess.run(tf.initialize_all_variables()) +``` + +### Predicted Class and Cost Function + +We can now implement our regression model. It only takes one line! +We multiply the vectorized input images `x` by the weight matrix `W`, add +the bias `b`, and compute the softmax probabilities that are assigned to each +class. + +```python +y = tf.nn.softmax(tf.matmul(x,W) + b) +``` + +The cost function to be minimized during training can be specified just as +easily. Our cost function will be the cross-entropy between the target and the +model's prediction. + +```python +cross_entropy = -tf.reduce_sum(y_*tf.log(y)) +``` + +Note that `tf.reduce_sum` sums across all images in the minibatch, as well as +all classes. We are computing the cross entropy for the entire minibatch. + +## Train the Model + +Now that we have defined our model and training cost function, it is +straightforward to train using TensorFlow. +Because TensorFlow knows the entire computation graph, it +can use automatic differentiation to find the gradients of the cost with +respect to each of the variables. +TensorFlow has a variety of +[builtin optimization algorithms] +(../../../api_docs/python/train.md?#optimizers). +For this example, we will use steepest gradient descent, with a step length of +0.01, to descend the cross entropy. + +```python +train_step = tf.train.GradientDescentOptimizer(0.01).minimize(cross_entropy) +``` + +What TensorFlow actually did in that single line was to add new operations to +the computation graph. These operations included ones to compute gradients, +compute parameter update steps, and apply update steps to the parameters. + +The returned operation `train_step`, when run, will apply the gradient +descent updates to the parameters. Training the model can therefore be +accomplished by repeatedly running `train_step`. + +```python +for i in range(1000): + batch = mnist.train.next_batch(50) + train_step.run(feed_dict={x: batch[0], y_: batch[1]}) +``` + +Each training iteration we load 50 training examples. We then run the +`train_step` operation, using `feed_dict` to replace the `placeholder` tensors +`x` and `y_` with the training examples. +Note that you can replace any tensor in your computation graph using `feed_dict` +-- it's not restricted to just `placeholder`s. + +### Evaluate the Model + +How well did our model do? + +First we'll figure out where we predicted the correct label. `tf.argmax` +is an extremely useful function which gives you the index of the highest entry +in a tensor along some axis. For example, `tf.argmax(y,1)` is the label our +model thinks is most likely for each input, while `tf.argmax(y_,1)` is the +true label. We can use `tf.equal` to check if our prediction matches the +truth. + +```python +correct_prediction = tf.equal(tf.argmax(y,1), tf.argmax(y_,1)) +``` + +That gives us a list of booleans. To determine what fraction are correct, we +cast to floating point numbers and then take the mean. For example, +`[True, False, True, True]` would become `[1,0,1,1]` which would become `0.75`. + +```python +accuracy = tf.reduce_mean(tf.cast(correct_prediction, "float")) +``` + +Finally, we can evaluate our accuracy on the test data. This should be about +91% correct. + +```python +print accuracy.eval(feed_dict={x: mnist.test.images, y_: mnist.test.labels}) +``` + +## Build a Multilayer Convolutional Network + +Getting 91% accuracy on MNIST is bad. It's almost embarrassingly bad. In this +section, we'll fix that, jumping from a very simple model to something moderatly +sophisticated: a small convolutional neural network. This will get us to around +99.2% accuracy -- not state of the art, but respectable. + +### Weight Initialization + +To create this model, we're going to need to create a lot of weights and biases. +One should generally initialize weights with a small amount of noise for +symmetry breaking, and to prevent 0 gradients. Since we're using ReLU neurons, +it is also good practice to initialize them with a slightly positive initial +bias to avoid "dead neurons." Instead of doing this repeatedly while we build +the model, let's create two handy functions to do it for us. + +```python +def weight_variable(shape): + initial = tf.truncated_normal(shape, stddev=0.1) + return tf.Variable(initial) + +def bias_variable(shape): + initial = tf.constant(0.1, shape=shape) + return tf.Variable(initial) +``` + +### Convolution and Pooling + +TensorFlow also gives us a lot of flexibility in convolution and pooling +operations. How do we handle the boundaries? What is our stride size? +In this example, we're always going to choose the vanilla version. +Our convolutions uses a stride of one and are zero padded so that the +output is the same size as the input. Our pooling is plain old max pooling +over 2x2 blocks. To keep our code cleaner, let's also abstract those operations +into functions. + +```python +def conv2d(x, W): + return tf.nn.conv2d(x, W, strides=[1, 1, 1, 1], padding='SAME') + +def max_pool_2x2(x): + return tf.nn.max_pool(x, ksize=[1, 2, 2, 1], + strides=[1, 2, 2, 1], padding='SAME') +``` + +### First Convolutional Layer + +We can now implement our first layer. It will consist of convolution, followed +by max pooling. The convolutional will compute 32 features for each 5x5 patch. +Its weight tensor will have a shape of `[5, 5, 1, 32]`. The first two +dimensions are the patch size, the next is the number of input channels, and +the last is the number of output channels. We will also have a bias vector with +a component for each output channel. + +```python +W_conv1 = weight_variable([5, 5, 1, 32]) +b_conv1 = bias_variable([32]) +``` + +To apply the layer, we first reshape `x` to a 4d tensor, with the second and +third dimensions corresponding to image width and height, and the final +dimension corresponding to the number of color channels. + +```python +x_image = tf.reshape(x, [-1,28,28,1]) +``` + +We then convolve `x_image` with the weight tensor, add the +bias, apply the ReLU function, and finally max pool. + +```python +h_conv1 = tf.nn.relu(conv2d(x_image, W_conv1) + b_conv1) +h_pool1 = max_pool_2x2(h_conv1) +``` + +### Second Convolutional Layer + +In order to build a deep network, we stack several layers of this type. The +second layer will have 64 features for each 5x5 patch. + +```python +W_conv2 = weight_variable([5, 5, 32, 64]) +b_conv2 = bias_variable([64]) + +h_conv2 = tf.nn.relu(conv2d(h_pool1, W_conv2) + b_conv2) +h_pool2 = max_pool_2x2(h_conv2) +``` + +### Densely Connected Layer + +Now that the image size has been reduced to 7x7, we add a fully-connected layer +with 1024 neurons to allow processing on the entire image. We reshape the tensor +from the pooling layer into a batch of vectors, +multiply by a weight matrix, add a bias, and apply a ReLU. + +```python +W_fc1 = weight_variable([7 * 7 * 64, 1024]) +b_fc1 = bias_variable([1024]) + +h_pool2_flat = tf.reshape(h_pool2, [-1, 7*7*64]) +h_fc1 = tf.nn.relu(tf.matmul(h_pool2_flat, W_fc1) + b_fc1) +``` + +#### Dropout + +To reduce overfitting, we will apply dropout before the readout layer. +We create a `placeholder` for the probability that a neuron's output is kept +during dropout. This allows us to turn dropout on during training, and turn it +off during testing. +TensorFlow's `tf.nn.dropout` op automatically handles scaling neuron outputs in +addition to masking them, so dropout just works without any additional scaling. + +```python +keep_prob = tf.placeholder("float") +h_fc1_drop = tf.nn.dropout(h_fc1, keep_prob) +``` + +### Readout Layer + +Finally, we add a softmax layer, just like for the one layer softmax regression +above. + +```python +W_fc2 = weight_variable([1024, 10]) +b_fc2 = bias_variable([10]) + +y_conv=tf.nn.softmax(tf.matmul(h_fc1_drop, W_fc2) + b_fc2) +``` + +### Train and Evaluate the Model + +How well does this model do? +To train and evaluate it we will use code that is nearly identical to that for +the simple one layer SoftMax network above. +The differences are that: we will replace the steepest gradient descent +optimizer with the more sophisticated ADAM optimizer; we will include the +additional parameter `keep_prob` in `feed_dict` to control the dropout rate; +and we will add logging to every 100th iteration in the training process. + +```python +cross_entropy = -tf.reduce_sum(y_*tf.log(y_conv)) +train_step = tf.train.AdamOptimizer(1e-4).minimize(cross_entropy) +correct_prediction = tf.equal(tf.argmax(y_conv,1), tf.argmax(y_,1)) +accuracy = tf.reduce_mean(tf.cast(correct_prediction, "float")) +sess.run(tf.initialize_all_variables()) +for i in range(20000): + batch = mnist.train.next_batch(50) + if i%100 == 0: + train_accuracy = accuracy.eval(feed_dict={ + x:batch[0], y_: batch[1], keep_prob: 1.0}) + print "step %d, training accuracy %g"%(i, train_accuracy) + train_step.run(feed_dict={x: batch[0], y_: batch[1], keep_prob: 0.5}) + +print "test accuracy %g"%accuracy.eval(feed_dict={ + x: mnist.test.images, y_: mnist.test.labels, keep_prob: 1.0}) +``` + +The final test set accuracy after running this code should be approximately 99.2%. + +We have learned how to quickly and easily build, train, and evaluate a +fairly sophisticated deep learning model using TensorFlow. diff --git a/tensorflow/g3doc/tutorials/mnist/tf/index.md b/tensorflow/g3doc/tutorials/mnist/tf/index.md new file mode 100644 index 0000000000..86f3296287 --- /dev/null +++ b/tensorflow/g3doc/tutorials/mnist/tf/index.md @@ -0,0 +1,513 @@ +# Handwritten Digit Classification + +Code: [tensorflow/g3doc/tutorials/mnist/](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/g3doc/tutorials/mnist/) + +The goal of this tutorial is to show how to use TensorFlow to train and +evaluate a simple feed-forward neural network for handwritten digit +classification using the (classic) MNIST data set. The intended audience for +this tutorial is experienced machine learning users interested in using +TensorFlow. + +These tutorials are not intended for teaching Machine Learning in general. + +Please ensure you have followed the instructions to [`Install TensorFlow`](../../../get_started/os_setup.md). + +## Tutorial Files + +This tutorial references the following files: + +File | Purpose +--- | --- +[`mnist.py`](../mnist.py) | The code to build a fully-connected MNIST model. +[`fully_connected_feed.py`](../fully_connected_feed.py) | The main code, to train the built MNIST model against the downloaded dataset using a feed dictionary. + +Simply run the `fully_connected_feed.py` file directly to start training: + +`python fully_connected_feed.py` + +## Prepare the Data + +MNIST is a classic problem in machine learning. The problem is to look at +greyscale 28x28 pixel images of handwritten digits and determine which digit +the image represents, for all the digits from zero to nine. + + + +For more information, refer to [Yann LeCun's MNIST page](http://yann.lecun.com/exdb/mnist/) +or [Chris Olah's visualizations of MNIST](http://colah.github.io/posts/2014-10-Visualizing-MNIST/). + +### Download + +At the top of the `run_training()` method, the `input_data.read_data_sets()` +function will ensure that the correct data has been downloaded to your local +training folder and then unpack that data to return a dictionary of `DataSet` +instances. + +```python +data_sets = input_data.read_data_sets(FLAGS.train_dir, FLAGS.fake_data) +``` + +**NOTE**: The `fake_data` flag is used for unit-testing purposes and may be +safely ignored by the reader. + +Dataset | Purpose +--- | --- +`data_sets.train` | 55000 images and labels, for primary training. +`data_sets.validation` | 5000 images and labels, for iterative validation of training accuracy. +`data_sets.test` | 10000 images and labels, for final testing of trained accuracy. + +For more information about the data, please read the [`Download`](../download/index.md) +tutorial. + +### Inputs and Placeholders + +The `placeholder_inputs()` function creates two [`tf.placeholder`](../../../api_docs/python/io_ops.md#placeholder) +ops that define the shape of the inputs, including the `batch_size`, to the +rest of the graph and into which the actual training examples will be fed. + +```python +images_placeholder = tf.placeholder(tf.float32, shape=(batch_size, + IMAGE_PIXELS)) +labels_placeholder = tf.placeholder(tf.int32, shape=(batch_size)) +``` + +Further down, in the training loop, the full image and label datasets are +sliced to fit the `batch_size` for each step, matched with these placeholder +ops, and then passed into the `sess.run()` function using the `feed_dict` +parameter. + +## Build the Graph + +After creating placeholders for the data, the graph is built from the +`mnist.py` file according to a 3-stage pattern: `inference()`, `loss()`, and +`training()`. + +1. `inference()` - Builds the graph as far as is required for running +the network forward to make predictions. +1. `loss()` - Adds to the inference graph the ops required to generate +loss. +1. `training()` - Adds to the loss graph the ops required to compute +and apply gradients. + +<div style="width:95%; margin:auto; margin-bottom:10px; margin-top:20px;"> + <img style="width:100%" src="./mnist_subgraph.png"> +</div> + +### Inference + +The `inference()` function builds the graph as far as needed to +return the tensor that would contain the output predictions. + +It takes the images placeholder as input and builds on top +of it a pair of fully connected layers with ReLu activation followed by a ten +node linear layer specifying the output logits. + +Each layer is created beneath a unique [`tf.name_scope`](../../../api_docs/python/framework.md#name_scope) +that acts as a prefix to the items created within that scope. + +```python +with tf.name_scope('hidden1') as scope: +``` + +Within the defined scope, the weights and biases to be used by each of these +layers are generated into [`tf.Variable`](../../../api_docs/python/state_ops.md#Variable) +instances, with their desired shapes: + +```python +weights = tf.Variable( + tf.truncated_normal([IMAGE_PIXELS, hidden1_units], + stddev=1.0 / math.sqrt(float(IMAGE_PIXELS))), + name='weights') +biases = tf.Variable(tf.zeros([hidden1_units]), + name='biases') +``` + +When, for instance, these are created under the `hidden1` scope, the unique +name given to the weights variable would be "`hidden1/weights`". + +Each variable is given initializer ops as part of their construction. + +In this most common case, the weights are initialized with the +[`tf.truncated_normal`](../../../api_docs/python/constant_op.md#truncated_normal) +and given their shape of a 2d tensor with +the first dim representing the number of units in the layer from which the +weights connect and the second dim representing the number of +units in the layer to which the weights connect. For the first layer, named +`hidden1`, the dimensions are `[IMAGE_PIXELS, hidden1_units]` because the +weights are connecting the image inputs to the hidden1 layer. The +`tf.truncated_normal` initializer generates a random distribution with a given +mean and standard deviation. + +Then the biases are initialized with [`tf.zeros`](../../../api_docs/python/constant_op.md#zeros) +to ensure they start with all zero values, and their shape is simply the number +of units in the layer to which they connect. + +The graph's three primary ops -- two [`tf.nn.relu`](../../../api_docs/python/nn.md#relu) +ops wrapping [`tf.matmul`](../../../api_docs/python/math_ops.md#matmul) +for the hidden layers and one extra `tf.matmul` for the logits -- are then +created, each in turn, with their `tf.Variable` instances connected to the +input placeholder or the output tensor of the layer beneath each. + +```python +hidden1 = tf.nn.relu(tf.matmul(images, weights) + biases) +``` + +```python +hidden2 = tf.nn.relu(tf.matmul(hidden1, weights) + biases) +``` + +```python +logits = tf.matmul(hidden2, weights) + biases +``` + +Finally, the `logits` tensor that will contain the output is returned. + +### Loss + +The `loss()` function further builds the graph by adding the required loss +ops. + +First, the values from the label_placeholder are encoded as a tensor of 1-hot +values. For example, if the class identifier is '3' the value is converted to: +<br>`[0, 0, 0, 1, 0, 0, 0, 0, 0, 0]` + +```python +batch_size = tf.size(labels) +labels = tf.expand_dims(labels, 1) +indices = tf.expand_dims(tf.range(0, batch_size, 1), 1) +concated = tf.concat(1, [indices, labels]) +onehot_labels = tf.sparse_to_dense( + concated, tf.pack([batch_size, NUM_CLASSES]), 1.0, 0.0) +``` + +A [`tf.nn.softmax_cross_entropy_with_logits`](../../../api_docs/python/nn.md#softmax_cross_entropy_with_logits) +op is then added to compare the output logits from the `inference()` function +and the 1-hot labels. + +```python +cross_entropy = tf.nn.softmax_cross_entropy_with_logits(logits, + onehot_labels, + name='xentropy') +``` + +It then uses [`tf.reduce_mean`](../../../api_docs/python/math_ops.md#reduce_mean) +to average the cross entropy values across the batch dimension (the first +dimension) as the total loss. + +```python +loss = tf.reduce_mean(cross_entropy, name='xentropy_mean') +``` + +And the tensor that will then contain the loss value is returned. + +> Note: Cross-entropy is an idea from information theory that allows us +> to describe how bad it is to believe the predictions of the neural network, +> given what is actually true. For more information, read the blog post Visual +> Information Theory (http://colah.github.io/posts/2015-09-Visual-Information/) + +### Training + +The `training()` function adds the operations needed to minimize the loss via +gradient descent. + +Firstly, it takes the loss tensor from the `loss()` function and hands it to a +[`tf.scalar_summary`](../../../api_docs/python/train.md#scalar_summary), +an op for generating summary values into the events file when used with a +`SummaryWriter` (see below). In this case, it will emit the snapshot value of +the loss every time the summaries are written out. + +```python +tf.scalar_summary(loss.op.name, loss) +``` + +Next, we instantiate a [`tf.train.GradientDescentOptimizer`](../../../api_docs/python/train.md#GradientDescentOptimizer) +responsible for applying gradients with the requested learning rate. + +```python +optimizer = tf.train.GradientDescentOptimizer(FLAGS.learning_rate) +``` + +We then generate a single variable to contain a counter for the global +training step and the [`minimize()`](../../../api_docs/python/train.md#Optimizer.minimize) +op is used to both update the trainable weights in the system and increment the +global step. This is, by convention, known as the `train_op` and is what must +be run by a TensorFlow session in order to induce one full step of training +(see below). + +```python +global_step = tf.Variable(0, name='global_step', trainable=False) +train_op = optimizer.minimize(loss, global_step=global_step) +``` + +The tensor containing the outputs of the training op is returned. + +## Train the Model + +Once the graph is built, it can be iteratively trained and evaluated in a loop +controlled by the user code in `fully_connected_feed.py`. + +### The Graph + +At the top of the `run_training()` function is a python `with` command that +indicates all of the built ops are to be associated with the default +global [`tf.Graph`](../../../api_docs/python/framework.md#Graph) +instance. + +```python +with tf.Graph().as_default(): +``` + +A `tf.Graph` is a collection of ops that may be executed together as a group. +Most TensorFlow uses will only need to rely on the single default graph. + +More complicated uses with multiple graphs are possible, but beyond the scope of +this simple tutorial. + +### The Session + +Once all of the build preparation has been completed and all of the necessary +ops generated, a [`tf.Session`](../../../api_docs/python/client.md#Session) +is created for running the graph. + +```python +sess = tf.Session() +``` + +Alternately, a `Session` may be generated into a `with` block for scoping: + +```python +with tf.Session() as sess: +``` + +The empty parameter to session indicates that this code will attach to +(or create if not yet created) the default local session. + +Immediately after creating the session, all of the `tf.Variable` +instances are initialized by calling `sess.run()` on their initialization op. + +```python +init = tf.initialize_all_variables() +sess.run(init) +``` + +The [`sess.run()`](../../../api_docs/python/client.md#Session.run) +method will run the complete subset of the graph that +corresponds to the op(s) passed as parameters. In this first call, the `init` +op is a [`tf.group`](../../../api_docs/python/control_flow_ops.md#group) +that contains only the initializers for the variables. None of the rest of the +graph is run here, that happens in the training loop below. + +### Train Loop + +After initializing the variables with the session, training may begin. + +The user code controls the training per step, and the simplest loop that +can do useful training is: + +```python +for step in xrange(max_steps): + sess.run([train_op]) +``` + +However, this tutorial is slightly more complicated in that it must also slice +up the input data for each step to match the previously generated placeholders. + +#### Feed the Graph + +For each step, the code will generate a feed dictionary that will contain the +set of examples on which to train for the step, keyed by the placeholder +ops they represent. + +In the `fill_feed_dict()` function, the given `DataSet` is queried for its next +`batch_size` set of images and labels, and tensors matching the placeholders are +filled containing the next images and labels. + +```python +images_feed, labels_feed = data_set.next_batch(FLAGS.batch_size) +``` + +A python dictionary object is then generated with the placeholders as keys and +the representative feed tensors as values. + +```python +feed_dict = { + images_placeholder: images_feed, + labels_placeholder: labels_feed, +} +``` + +This is passed into the `sess.run()` function's `feed_dict` parameter to provide +the input examples for this step of training. + +#### Check the Status + +The code specifies two op-tensors in its run call: `[train_op, loss]`: + +```python +for step in xrange(FLAGS.max_steps): + feed_dict = fill_feed_dict(data_sets.train, + images_placeholder, + labels_placeholder) + _, loss_value = sess.run([train_op, loss], + feed_dict=feed_dict) +``` + +Because there are two tensors passed as parameters, the return from +`sess.run()` is a tuple with two items. The returned items are themselves +tensors, filled with the values of the passed op-tensors during this step of +training. + +The value of the `train_op` is actually `None` and, thus, discarded. But the +value of the `loss` tensor may become NaN if the model diverges during training. + +Assuming that the training runs fine without NaNs, the training loop also +prints a simple status text every 100 steps to let the user know the state of +training. + +```python +if step % 100 == 0: + print 'Step %d: loss = %.2f (%.3f sec)' % (step, loss_value, duration) +``` + +#### Visualize the Status + +In order to emit the events files used by [TensorBoard](../../../how_tos/summaries_and_tensorboard/index.md), +all of the summaries (in this case, only one) are collected into a single op +during the graph building phase. + +```python +summary_op = tf.merge_all_summaries() +``` + +And then after the Session is generated, a [`tf.train.SummaryWriter`](../../../api_docs/python/train.md#SummaryWriter) +may be instantiated to output into the given directory the events files, +containing the Graph itself and the values of the summaries. + +```python +summary_writer = tf.train.SummaryWriter(FLAGS.train_dir, + graph_def=sess.graph_def) +``` + +Lastly, the events file will be updated with new summary values every time the +`summary_op` is run and the ouput passed to the writer's `add_summary()` +function. + +```python +summary_str = sess.run(summary_op, feed_dict=feed_dict) +summary_writer.add_summary(summary_str, step) +``` + +When the events files are written, TensorBoard may be run against the training +folder to display the values from the summaries. + + + +**NOTE**: For more info about how to build and run Tensorboard, please see the accompanying tutorial [Tensorboard: Visualizing Your Training](../../../how_tos/summaries_and_tensorboard/index.md). + +#### Save a Checkpoint + +In order to emit a checkpoint file that may be used to later restore a model +for further training or evaluation, we instantiate a +[`tf.train.Saver`](../../../api_docs/python/state_ops.md#Saver). + +```python +saver = tf.train.Saver() +``` + +In the training loop, the [`saver.save()`](../../../api_docs/python/state_ops.md#Saver.save) +method will periodically be called to write a checkpoint file to the training +directory with the current values of all the trainable variables. + +```python +saver.save(sess, FLAGS.train_dir, global_step=step) +``` + +At some later point in the future, training might be resumed by using the +[`saver.restore()`](../../../api_docs/python/state_ops.md#Saver.restore) +method to reload the model parameters. + +```python +saver.restore(sess, FLAGS.train_dir) +``` + +## Evaluate the Model + +Every thousand steps, the code will attempt to evaluate the model against both +the training and test datasets. The `do_eval()` function is called thrice, for +the training, validation, and test datasets. + +```python +print 'Training Data Eval:' +do_eval(sess, + eval_correct, + images_placeholder, + labels_placeholder, + data_sets.train) +print 'Validation Data Eval:' +do_eval(sess, + eval_correct, + images_placeholder, + labels_placeholder, + data_sets.validation) +print 'Test Data Eval:' +do_eval(sess, + eval_correct, + images_placeholder, + labels_placeholder, + data_sets.test) +``` + +> Note that more complicated usage would usually sequester the `data_sets.test` +> to only be checked after significant amounts of hyperparameter tuning. For +> the sake of a simple little MNIST problem, however, we evaluate against all of +> the data. + +### Build the Eval Graph + +Before opening the default Graph, the test data should have been fetched by +calling the `get_data(train=False)` function with the parameter set to grab +the test dataset. + +```python +test_all_images, test_all_labels = get_data(train=False) +``` + +Before entering the training loop, the Eval op should have been built +by calling the `evaluation()` function from `mnist.py` with the same +logits/labels parameters as the `loss()` function. + +```python +eval_correct = mnist.evaluation(logits, labels_placeholder) +``` + +The `evaluation()` function simply generates a [`tf.nn.in_top_k`](../../../api_docs/python/nn.md#in_top_k) +op that can automatically score each model output as correct if the true label +can be found in the K most-likely predictions. In this case, we set the value +of K to 1 to only consider a prediction correct if it is for the true label. + +```python +eval_correct = tf.nn.in_top_k(logits, labels, 1) +``` + +### Eval Output + +One can then create a loop for filling a `feed_dict` and calling `sess.run()` +against the `eval_correct` op to evaluate the model on the given dataset. + +```python +for step in xrange(steps_per_epoch): + feed_dict = fill_feed_dict(data_set, + images_placeholder, + labels_placeholder) + true_count += sess.run(eval_correct, feed_dict=feed_dict) +``` + +The `true_count` variable simply accumulates all of the predictions that the +`in_top_k` op has determined to be correct. From there, the precision may be +calculated from simply dividing by the total number of examples. + +```python +precision = float(true_count) / float(num_examples) +print ' Num examples: %d Num correct: %d Precision @ 1: %0.02f' % ( + num_examples, true_count, precision) +``` diff --git a/tensorflow/g3doc/tutorials/pdes/index.md b/tensorflow/g3doc/tutorials/pdes/index.md new file mode 100755 index 0000000000..1f29e4037c --- /dev/null +++ b/tensorflow/g3doc/tutorials/pdes/index.md @@ -0,0 +1,129 @@ + +## Basic Setup + + +``` +#Import libraries for simulation +import tensorflow as tf +import numpy as np + +#Imports for visualization +import PIL.Image +from cStringIO import StringIO +from IPython.display import clear_output, Image, display +``` + + +``` +def DisplayArray(a, fmt='jpeg', rng=[0,1]): + """Display an array as a picture.""" + a = (a - rng[0])/float(rng[1] - rng[0])*255 + a = np.uint8(np.clip(a, 0, 255)) + f = StringIO() + PIL.Image.fromarray(a).save(f, fmt) + display(Image(data=f.getvalue())) +``` + + +``` +sess = tf.InteractiveSession() +``` + +## Computational Convenience Functions + + +``` +def make_kernel(a): + """Transform a 2D array into a convolution kernel""" + a = np.asarray(a) + a = a.reshape(list(a.shape) + [1,1]) + return tf.constant(a, dtype=1) + +def simple_conv(x, k): + """A simplified 2D convolution operation""" + x = tf.expand_dims(tf.expand_dims(x, 0), -1) + y = tf.nn.depthwise_conv2d(x, k, [1, 1, 1, 1], padding='SAME') + return y[0, :, :, 0] + +def laplace(x): + """Compute the 2D laplacian of an array""" + laplace_k = make_kernel([[0.5, 1.0, 0.5], + [1.0, -6., 1.0], + [0.5, 1.0, 0.5]]) + return simple_conv(x, laplace_k) +``` + +## Define the PDE + + +``` +N = 500 +``` + + +``` +# Initial Conditions -- some rain drops hit a pond + +# Set everything to zero +u_init = np.zeros([N, N], dtype="float32") +ut_init = np.zeros([N, N], dtype="float32") + +# Some rain drops hit a pond at random points +for n in range(40): + a,b = np.random.randint(0, N, 2) + u_init[a,b] = np.random.uniform() + +DisplayArray(u_init, rng=[-0.1, 0.1]) +``` + + + + + + +``` +# paramaters +# eps -- time resolution +# damping -- wave damping +eps = tf.placeholder('float', shape=()) +damping = tf.placeholder('float', shape=()) + +# create variables for simulation state +U = tf.Variable(u_init) +Ut = tf.Variable(ut_init) + +# discretized PDE update rules +U_ = U + eps*Ut +Ut_ = Ut + eps*(laplace(U) - damping*Ut) + +# operation to update the state +step = tf.group( + U.Assign(U_), + Ut.Assign(Ut_) ) +``` + +## Run The Simulation + + +``` +# initialize state to initial conditions +tf.InitializeAllVariables().Run() + +# Run 1000 steps of PDE +for i in range(1000): + # Step simulation + step.Run({eps: 0.03, damping: 0.04}) + # Visualize every 50 steps + if i % 50 == 0: + clear_output() + DisplayArray(U.eval(), rng=[-0.1, 0.1]) +``` + + + + + + +``` + +``` diff --git a/tensorflow/g3doc/tutorials/pdes/output_11_0.jpe b/tensorflow/g3doc/tutorials/pdes/output_11_0.jpe Binary files differnew file mode 100755 index 0000000000..8cd8cf02b5 --- /dev/null +++ b/tensorflow/g3doc/tutorials/pdes/output_11_0.jpe diff --git a/tensorflow/g3doc/tutorials/pdes/output_8_0.jpe b/tensorflow/g3doc/tutorials/pdes/output_8_0.jpe Binary files differnew file mode 100755 index 0000000000..97954effc0 --- /dev/null +++ b/tensorflow/g3doc/tutorials/pdes/output_8_0.jpe diff --git a/tensorflow/g3doc/tutorials/recurrent/index.md b/tensorflow/g3doc/tutorials/recurrent/index.md new file mode 100644 index 0000000000..29d058cd5d --- /dev/null +++ b/tensorflow/g3doc/tutorials/recurrent/index.md @@ -0,0 +1,209 @@ +# Recurrent Neural Networks + +## Introduction + +Take a look at [this great article] +(http://colah.github.io/posts/2015-08-Understanding-LSTMs/) +for an introduction to recurrent neural networks and LSTMs in particular. + +## Language Modeling + +In this tutorial we will show how to train a recurrent neural network on +a challenging task of language modeling. The goal of the problem is to fit a +probabilistic model which assigns probablities to sentences. It does so by +predicting next words in a text given a history of previous words. For this +purpose we will use the Penn Tree Bank (PTB) dataset, which is a popular +benchmark for measuring quality of these models, whilst being small and +relatively fast to train. + +Language modeling is key to many interesting problems such as speech +recognition, machine translation, or image captioning. It is also fun, too -- +take a look [here] (http://karpathy.github.io/2015/05/21/rnn-effectiveness/). + +For the purpose of this tutorial, we will reproduce the results from +[Zaremba et al., 2014] (http://arxiv.org/abs/1409.2329), which achieves very +good results on the PTB dataset. + +## Tutorial Files + +This tutorial references the following files from `models/rnn/ptb`: + +File | Purpose +--- | --- +`ptb_word_lm.py` | The code to train a language model on the PTB dataset. +`reader.py` | The code to read the dataset. + +## Download and Prepare the Data + +The data required for this tutorial is in the data/ directory of the +PTB dataset from Tomas Mikolov's webpage: +http://www.fit.vutbr.cz/~imikolov/rnnlm/simple-examples.tgz + +The dataset is already preprocessed and contains overall 10000 different words, +including the end-of-sentence marker and a special symbol (\<unk\>) for rare +words. We convert all of them in the `reader.py` to unique integer identifiers +to make it easy for the neural network to process. + +## The Model + +### LSTM + +The core of the model consists of an LSTM cell that processes one word at the +time and computes probabilities of the possible continuations of the sentence. +The memory state of the network is initialized with a vector of zeros and gets +updated after reading each word. Also, for computational reasons, we will +process data in mini-batches of size `batch_size`. + +The basic pseudocode looks as follows: + +```python +lstm = rnn_cell.BasicLSTMCell(lstm_size) +# Initial state of the LSTM memory. +state = tf.zeros([batch_size, lstm.state_size]) + +loss = 0.0 +for current_batch_of_words in words_in_dataset: + # The value of state is updated after processing each batch of words. + output, state = lstm(current_batch_of_words, state) + + # The LSTM output can be used to make next word predictions + logits = tf.matmul(output, softmax_w) + softmax_b + probabilities = tf.nn.softmax(logits) + loss += loss_function(probabilities, target_words) +``` + +### Truncated Backpropagation + +In order to make the learning process tractable, it is a common practice to +truncate the gradients for backpropagation to a fixed number (`num_steps`) +of unrolled steps. +This is easy to implement by feeding inputs of length `num_steps` at a time and +doing backward pass after each iteration. + +A simplifed version of the code for the graph creation for truncated +backpropagation: + +```python +# Placeholder for the inputs in a given iteration. +words = tf.placeholder(tf.int32, [batch_size, num_steps]) + +lstm = rnn_cell.BasicLSTMCell(lstm_size) +# Initial state of the LSTM memory. +initial_state = state = tf.zeros([batch_size, lstm.state_size]) + +for i in range(len(num_steps)): + # The value of state is updated after processing each batch of words. + output, state = lstm(words[:, i], state) + + # The rest of the code. + # ... + +final_state = state +``` + +And this is how to implement an iteration over the whole dataset: + +```python +# A numpy array holding the state of LSTM after each batch of words. +numpy_state = initial_state.eval() +total_loss = 0.0 +for current_batch_of_words in words_in_dataset: + numpy_state, current_loss = session.run([final_state, loss], + # Initialize the LSTM state from the previous iteration. + feed_dict={initial_state: numpy_state, words: current_batch_of_words}) + total_loss += current_loss +``` + +### Inputs + +The word IDs will be embedded into a dense representation (see the +[Vectors Representations Tutorial](../word2vec/index.md)) before feeding to +the LSTM. This allows the model to efficiently represent the knowledge about +particular words. It is also easy to write: + +```python +# embedding_matrix is a tensor of shape [vocabulary_size, embedding size] +word_embeddings = tf.nn.embedding_lookup(embedding_matrix, word_ids) +``` + +The embedding matrix will be initialized randomly and the model will learn to +differentiate the meaning of words just by looking at the data. + +### Loss Fuction + +We want to minimize the average negative log probability of the target words: + +$$ \text{loss} = -\frac{1}{N}\sum_{i=1}^{N} \ln p_{\text{target}_i} $$ + +It is not very difficult to implement but the function +`sequence_loss_by_example` is already available, so we can just use it here. + +The typical measure reported in the papers is average per-word perplexity (often +just called perplexity), which is equal to + +$$e^{-\frac{1}{N}\sum_{i=1}^{N} \ln p_{\text{target}_i}} = e^{\text{loss}} $$ + +and we will monitor its value throughout the training process. + +### Stacking multiple LSTMs + +To give the model more expressive power, we can add multiple layers of LSTMs +to process the data. The output of the first layer will become the input of +the second and so on. + +We have a class called `MultiRNNCell` that makes the implementation seemless: + +```python +lstm = rnn_cell.BasicLSTMCell(lstm_size) +stacked_lstm = rnn_cell.MultiRNNCell([lstm] * number_of_layers) + +initial_state = state = stacked_lstm.zero_state(batch_size, tf.float32) +for i in range(len(num_steps)): + # The value of state is updated after processing each batch of words. + output, state = stacked_lstm(words[:, i], state) + + # The rest of the code. + # ... + +final_state = state +``` + +## Compile and Run the Code + +First, the library needs to be built. To compile it on CPU: + +``` +bazel build -c opt tensorflow/models/rnn/ptb:ptb_word_lm +``` + +And if you have a fast GPU, run the following: + +``` +bazel build -c opt tensorflow --config=cuda \ + tensorflow/models/rnn/ptb:ptb_word_lm +``` + +Now we can run the model: + +``` +bazel-bin/.../ptb_word_lm \ + --data_path=/tmp/simple-examples/data/ --alsologtostderr --model small +``` + +There are 3 supported model configurations in the tutorial code: "small", +"medium" and "large". The difference between them is in size of the LSTMs and +the set of hyperparameters used for training. + +The larger the model, the better results it should get. The `small` model should +be able to reach perplexity below 120 on the test set and the `large` one below +80, though it might take several hours to train. + +## What Next? + +There are several tricks that we haven't mentioned that make the model better, +including: + +* decreasing learning rate schedule, +* dropout between the LSTM layers. + +Study the code and modify it to improve the model even further. diff --git a/tensorflow/g3doc/tutorials/seq2seq/index.md b/tensorflow/g3doc/tutorials/seq2seq/index.md new file mode 100644 index 0000000000..e421c814aa --- /dev/null +++ b/tensorflow/g3doc/tutorials/seq2seq/index.md @@ -0,0 +1,331 @@ +# Sequence-to-Sequence Models: Learning to Translate + +Recurrent neural networks can learn to model language, as already discussed +in the [RNN Tutorial](../recurrent/index.md) +(if you did not read it, please go through it before proceeding with this one). +This raises an interesting question: could we condition the generated words on +some input and generate a meaningful response? For example, could we train +a neural network to translate from English to French? It turns out that +the answer is *yes*. + +This tutorial will show you how to build and train such a system end-to-end. +You can start by running this binary. + +``` +bazel run -c opt <...>/models/rnn/translate/translate.py + --data_dir [your_data_directory] +``` + +It will download English-to-French translation data from the +[WMT'15 Website](http://www.statmt.org/wmt15/translation-task.html) +prepare it for training and train. It takes about 20GB of disk space, +and a while to download and prepare (see [later](#run_it) for details), +so you can start and leave it running while reading this tutorial. + +This tutorial references the following files from `models/rnn`. + +File | What's in it? +--- | --- +`seq2seq.py` | Library for building sequence-to-sequence models. +`translate/seq2seq_model.py` | Neural translation sequence-to-sequence model. +`translate/data_utils.py` | Helper functions for preparing translation data. +`translate/translate.py` | Binary that trains and runs the translation model. + + +## Sequence-to-Sequence Basics + +A basic sequence-to-sequence model, as introduced in +[Cho et al., 2014](http://arxiv.org/pdf/1406.1078v3.pdf), +consists of two recurrent neural networks (RNNs): an *encoder* that +processes the input and a *decoder* that generates the output. +This basic architecture is depicted below. + +<div style="width:80%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="basic_seq2seq.png" /> +</div> + +Each box in the picture above represents a cell of the RNN, most commonly +a GRU cell or an LSTM cell (see the [RNN Tutorial](../recurrent/index.md) +for an explanation of those). Encoder and decoder can share weights or, +as is more common, use a different set of parameters. Mutli-layer cells +have been successfully used in sequence-to-sequence models too, e.g. for +translation [Sutskever et al., 2014](http://arxiv.org/abs/1409.3215). + +In the basic model depicted above, every input has to be encoded into +a fixed-size state vector, as that is the only thing passed to the decoder. +To allow the decoder more direct access to the input, an *attention* mechanism +was introduced in [Bahdanu et al., 2014](http://arxiv.org/abs/1409.0473). +We will not go into the details of the attention mechanism (see the paper), +suffice it to say that it allows the decoder to peek into the input at every +decoding step. A multi-layer sequence-to-sequence network with LSTM cells and +attention mechanism in the decoder looks like this. + +<div style="width:80%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="attention_seq2seq.png" /> +</div> + +## TensorFlow seq2seq Library + +As you can see above, there are many different sequence-to-sequence +models. Each of these models can use different RNN cells, but all +of them accept encoder inputs and decoder inputs. This motivates +the interfaces in the TensorFlow seq2seq library (`models/rnn/seq2seq.py`). +The basic RNN encoder-decoder sequence-to-sequence model works as follows. + +```python +outputs, states = basic_rnn_seq2seq(encoder_inputs, decoder_inputs, cell) +``` + +In the above call, `encoder_inputs` are a list of tensors representing inputs +to the encoder, i.e., corresponding to the letters *A, B, C* in the first +picture above. Similarly, `decoder_inputs` are tensors representing inputs +to the decoder, *GO, W, X, Y, Z* on the first picture. + +The `cell` argument is an instance of the `models.rnn.rnn_cell.RNNCell` class +that determines which cell will be used inside the model. You can use +an existing cell, such as `GRUCell` or `LSTMCell`, or you can write your own. +Moreover, `rnn_cell` provides wrappers to construct multi-layer cells, +add dropout to cell inputs or outputs, or to do other transformations, +see the [RNN Tutorial](../recurrent/index.md) for examples. + +The call to `basic_rnn_seq2seq` returns two arguments: `outputs` and `states`. +Both of them are lists of tensors of the same length as `decoder_inputs`. +Naturally, `outputs` correspond to the outputs of the decoder in each time-step, +in the first picture above that would be *W, X, Y, Z, EOS*. The returned +`states` represent the internal state of the decoder at every time-step. + +In many applications of sequence-to-sequence models, the output of the decoder +at time t is fed back and becomes the input of the decoder at time t+1. At test +time, when decoding a sequence, this is how the sequence is constructed. +During training, on the other hand, it is common to provide the correct input +to the decoder at every time-step, even if the decoder made a mistake before. +Functions in `seq2seq.py` support both modes using the `feed_previous` argument. +For example, let's analyze the following use of an embedding RNN model. + +```python +outputs, states = embedding_rnn_seq2seq( + encoder_inputs, decoder_inputs, cell, + num_encoder_symbols, num_decoder_symbols, + output_projection=None, feed_previous=False) +``` + +In the `embedding_rnn_seq2seq` model, all inputs (both `encoder_inputs` and +`decoder_inputs`) are integer-tensors that represent discrete values. +They will be embedded into a dense representation (see the +[Vectors Representations Tutorial](../word2vec/index.md) for more details +on embeddings), but to construct these embeddings we need to specify +the maximum number of discrete symbols that will appear: `num_encoder_symbols` +on the encoder side, and `num_decoder_symbols` on the decoder side. + +In the above invocation, we set `feed_previous` to False. This means that the +decoder will use `decoder_inputs` tensors as provided. If we set `feed_previous` +to True, the decoder would only use the first element of `decoder_inputs`. +All other tensors from this list would be ignored, and instead the previous +output of the encoder would be used. This is used for decoding translations +in our translation model, but it can also be used during training, to make +the model more robust to its own mistakes, similar +to [Bengio et al., 2015](http://arxiv.org/pdf/1506.03099v2.pdf). + +One more important argument used above is `output_projection`. If not specified, +the outputs of the embedding model will be tensors of shape batch-size by +`num_decoder_symbols` as they represent the logits for each generated symbol. +When training models with large output vocabularies, i.e., when +`num_decoder_symbols` is large, it is not practical to store these large +tensors. Instead, it is better to return smaller output tensors, which will +later be projected onto a large output tensor using `output_projection`. +This allows to use our seq2seq models with a sampled softmax loss, as described +in [Jean et. al., 2015](http://arxiv.org/pdf/1412.2007v2.pdf). + +In addition to `basic_rnn_seq2seq` and `embedding_rnn_seq2seq` there are a few +more sequence-to-sequence models in `seq2seq.py`, take a look there. They all +have similar interfaces, so we will not describe them in detail. We will use +`embedding_attention_seq2seq` for our translation model below. + +## Neural Translation Model + +While the core of the sequence-to-sequence model is constructed by +the functions in `models/rnn/seq2seq.py`, there are still a few tricks +that are worth mentioning that are used in our translation model in +`models/rnn/translate/seq2seq_model.py`. + +### Sampled softmax and output projection + +For one, as already mentioned above, we want to use sampled softmax to +handle large output vocabulary. To decode from it, we need to keep track +of the output projection. Both the sampled softmax loss and the output +projections are constructed by the following code in `seq2seq_model.py`. + +```python + if num_samples > 0 and num_samples < self.target_vocab_size: + w = tf.get_variable("proj_w", [size, self.target_vocab_size]) + w_t = tf.transpose(w) + b = tf.get_variable("proj_b", [self.target_vocab_size]) + output_projection = (w, b) + + def sampled_loss(inputs, labels): + labels = tf.reshape(labels, [-1, 1]) + return tf.nn.sampled_softmax_loss(w_t, b, inputs, labels, num_samples, + self.target_vocab_size) +``` + +First, note that we only construct a sampled softmax if the number of samples +(512 by default) is smaller that the target vocabulary size. For vocabularies +smaller than 512 it might be a better idea to just use a standard softmax loss. + +Then, as you can see, we construct an output projection. It is a pair, +consisting of a weight matrix and a bias vector. If used, the rnn cell +will return vectors of shape batch-size by `size`, rather than batch-size +by `target_vocab_size`. To recover logits, we need to multiply by the weight +matrix and add the biases, as is done in lines 124-126 in `seq2seq_model.py`. + +```python +if output_projection is not None: + self.outputs[b] = [tf.matmul(output, output_projection[0]) + + output_projection[1] for ...] +``` + +### Bucketing and padding + +In addition to sampled softmax, our translation model also makes use +of *bucketing*, which is a method to efficiently handle sentences of +different lengths. Let us first clarify the problem. When translating +English to French, we will have English sentences of different lengths L1 +on input, and French sentences of different lengths L2 on output. Since +the English sentence is passed as `encoder_inputs`, and the French sentence +comes as `decoder_inputs` (prefixed by a GO symbol), we should in principle +create a seq2seq model for every pair (L1, L2+1) of lengths of an English +and French sentence. This would result in an enormous graph consisting of +many very similar subgraphs. On the other hand, we could just pad every +sentence with a special PAD symbol. Then we'd need only one seq2seq model, +for the padded lengths. But on shorter sentence our model would be inefficient, +encoding and decoding many PAD symbols that are useless. + +As a compromise between contructing a graph for every pair of lengths and +padding to a single length, we use a number of *buckets* and pad each sentence +to the length of the bucket above it. In `translate.py` we use the following +default buckets. + +```python +buckets = [(5, 10), (10, 15), (20, 25), (40, 50)] +``` + +This means that if the input is an English sentence with 3 tokens, +and the corresponding output is a French sentence with 6 tokens, +then they will be put in the first bucket and padded to length 5 for +encoder inputs, and length 10 for decoder inputs. If we have an English +sentence with 8 tokens and the corresponding French sentence has 18 tokens, +then they will not fit into the (10, 15) bucket, and so the (20, 25) bucket +will be used, i.e. the English sentence will be padded to 20, and the French +one to 25. + +Remember that when constructing decoder inputs we prepend the special `GO` +symbol to the input data. This is done in the `get_batch()` function in +`seq2seq_model.py`, which also reverses the input English sentence. +Reversing the inputs was shown to improve results for the neural translation +model in [Sutskever et al., 2014](http://arxiv.org/abs/1409.3215). +To put it all together, imagine we have the sentence "I go.", tokenized +as `["I", "go", "."]` as input and the sentence "Je vais." as output, +tokenized `["Je", "vais", "."]`. It will be put in the (5, 10) bucket, +with encoder inputs representing `[PAD PAD "." "go" "I"]` and decoder +inputs `[GO "Je" "vais" "." EOS PAD PAD PAD PAD PAD]`. + + +## Let's Run It {#run_it} + +To train the model described above, we need to a large English-French corpus. +We will use the *10^9-French-English corpus* from the +[WMT'15 Website](http://www.statmt.org/wmt15/translation-task.html) +for training, and the 2013 news test from the same site as development set. +Both data-sets will be downloaded to `data_dir` and training will start, +saving checkpoints in `train_dir`, when this command is run. + +``` +bazel run -c opt <...>/models/rnn/translate:translate + --data_dir [your_data_directory] --train_dir [checkpoints_directory] + --en_vocab_size=40000 --fr_vocab_size=40000 +``` + +It takes about 18GB of disk space and several hours to prepare the training +corpus. It is unpacked, vocabulary files are created in `data_dir`, and then +the corpus is tokenized and converted to integer ids. Note the parameters +that determine vocabulary sizes. In the example above, all words outside +the 40K most common ones will be converted to an `UNK` token representing +unknown words. So if you change vocabulary size, the binary will re-map +the corpus to token-ids again. + +After the data is prepared, training starts. Default parameters in `translate` +are set to quite large values. Large models trained over a long time give good +results, but it might take too long or use too much memory for your GPU. +You can request to train a smaller model as in the following example. + +``` +bazel run -c opt <...>/models/rnn/translate:translate + --data_dir [your_data_directory] --train_dir [checkpoints_directory] + --size=256 --num_layers=2 --steps_per_checkpoint=50 +``` + +The above command will train a model with 2 layers (the default is 3), +each layer with 256 units (default is 1024), and will save a checkpoint +every 50 steps (the default is 200). You can play with these parameters +to find out how large a model can be to fit into the memory of your GPU. + +During training, every `steps_per_checkpoint` steps the binary will print +out statistics from recent steps. With the default parameters (3 layers +of size 1024), first messages look like this. + +``` +global step 200 learning rate 0.5000 step-time 1.39 perplexity 1720.62 + eval: bucket 0 perplexity 184.97 + eval: bucket 1 perplexity 248.81 + eval: bucket 2 perplexity 341.64 + eval: bucket 3 perplexity 469.04 +global step 400 learning rate 0.5000 step-time 1.38 perplexity 379.89 + eval: bucket 0 perplexity 151.32 + eval: bucket 1 perplexity 190.36 + eval: bucket 2 perplexity 227.46 + eval: bucket 3 perplexity 238.66 +``` + +You can see that each step takes just under 1.4 seconds, the perplexity +on the training set and the perplexities on the development set +for each bucket. After about 30K steps, we see perplexities on short +sentences (bucket 0 and 1) going into single digits. +Since the training corpus contains ~22M sentences, one epoch (going through +the training data once) takes about 340K steps with batch-size of 64. At this +point the model can be used for translating English sentences to French +using the `--decode` option. + +``` +bazel run -c opt <...>/models/rnn/translate:translate --decode + --data_dir [your_data_directory] --train_dir [checkpoints_directory] + +Reading model parameters from /tmp/translate.ckpt-340000 +> Who is the president of the United States? + Qui est le président des États-Unis ? +``` + +## What Next? + +The example above shows how you can build your own English-to-French +translator, end-to-end. Run it and see how the model performs for yourself. +While it has reasonable quality, the default parameters will not give you +the best translation model. Here are a few things you can improve. + +First of all, we use a very promitive tokenizer, the `basic_tokenizer` function +in `data_utils`. A better tokenizer can be found on the +[WMT'15 Website](http://www.statmt.org/wmt15/translation-task.html). +Using that tokenizer, and a larger vocabulary, should improve your translations. + +Also, the default parameters of the translation model are not tuned. +You can try changing the learning rate, decay, or initializing the weights +of your model in a different way. You can also change the default +`GradientDescentOptimizer` in `seq2seq_model.py` to a more advanced one, such +as `AdagradOptimizer`. Try these things and see how they improve your results! + +Finally, the model presented above can be used for any sequence-to-sequence +task, not only for translation. Even if you want to transform a sequence to +a tree, for example to generate a parsing tree, the same model as above can +give state-of-the-art results, as demonstrated in +[Vinyals & Kaiser et al., 2015](http://arxiv.org/abs/1412.7449). +So you can not only build your own translator, you can also build a parser, +a chat-bot, or any program that comes to your mind. Experiment! diff --git a/tensorflow/g3doc/tutorials/word2vec/__init__.py b/tensorflow/g3doc/tutorials/word2vec/__init__.py new file mode 100755 index 0000000000..e69de29bb2 --- /dev/null +++ b/tensorflow/g3doc/tutorials/word2vec/__init__.py diff --git a/tensorflow/g3doc/tutorials/word2vec/index.md b/tensorflow/g3doc/tutorials/word2vec/index.md new file mode 100644 index 0000000000..8779f33ad7 --- /dev/null +++ b/tensorflow/g3doc/tutorials/word2vec/index.md @@ -0,0 +1,396 @@ +# Learning Vector Representations of Words + +In this tutorial we look at the word2vec model by +[Mikolov et al.](http://papers.nips.cc/paper/5021-distributed-representations-of-words-and-phrases-and-their-compositionality.pdf). +This model is used for learning vector representations of words, called *word +embeddings*. + +## Highlights + +This tutorial is meant to highlight the interesting, substantive parts of +building a word2vec model in TensorFlow. + +* We start by giving the motivation for why we would want to +represent words as vectors. +* We look at the intuition behind the model and how it is trained +(with a splash of math for good measure). +* We also show a simple implementation of the model in TensorFlow. +* Finally, we look at ways to make the naive version scale better. + +We walk through the code later during the tutorial, but if you'd prefer to +dive straight in, feel free to look at the minimalistic implementation in +[tensorflow/g3doc/tutorials/word2vec/word2vec_basic.py](./word2vec_basic.py) +This basic example contains the code needed to download some data, train on it +a bit and visualize the result. Once you get +comfortable with reading and running the basic version, you can graduate to +[tensorflow/models/embedding/word2vec.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/embedding/word2vec.py) +which is a more serious implementation that showcases some more advanced +TensorFlow principles about how to efficiently use threads to move data into a +text model, how to checkpoint during training, etc. + +But first, let's look at why we would want to learn word embeddings in the first +place. Feel free to skip this section if you're an Embedding Pro and you'd just +like to get your hands dirty with the details. + +## Motivation: Why Learn Word Embeddings? + +Image and audio processing systems work with rich, high-dimensional datasets +encoded as vectors of the individual raw pixel-intensities for image data, or +e.g. power spectral density coefficients for audio data. For tasks like object +or speech recognition we know that all the information required to successfully +perform the task is encoded in the data (because humans can perform these tasks +from the raw data). However, natural language processing systems traditionally +treat words as discrete atomic symbols, and therefore 'cat' may be represented +as `Id537` and 'dog' as `Id143`. These encodings are arbitrary, and provide +no useful information to the system regarding the relationships that may exist +between the individual symbols. This means that the model can leverage +very little of what it has learned about 'cats' when it is processing data about +'dogs' (such that they are both animals, four-legged, pets, etc.). Representing +words as unique, discrete ids furthermore leads to data sparsity, and usually +means that we may need more data in order to successfully train statistical +models. Using vector representations can overcome some of these obstacles. + +<div style="width:100%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/audio-image-text.png" alt> +</div> + +[Vector space models](https://en.wikipedia.org/wiki/Vector_space_model) (VSMs) +represent (embed) words in a continuous vector space where semantically +similar words are mapped to nearby points ('are embedded nearby each other'). +VSMs have a long, rich history in NLP, but all methods depend in some way or +another on the +[Distributional Hypothesis](https://en.wikipedia.org/wiki/Distributional_semantics#Distributional_Hypothesis), +which states that words that appear in the same contexts share +semantic meaning. The different approaches that leverage this principle can be +divided into two categories: *count-based methods* (e.g. +[Latent Semantic Analysis](https://en.wikipedia.org/wiki/Latent_semantic_analysis)), +and *predictive methods* (e.g. +[neural probabilistic language models](http://www.scholarpedia.org/article/Neural_net_language_models)). + +This distinction is elaborated in much more detail by +[Baroni et al.](http://clic.cimec.unitn.it/marco/publications/acl2014/baroni-etal-countpredict-acl2014.pdf), +but in a nutshell: Count-based methods compute the statistics of +how often some word co-occurs with its neighbor words in a large text corpus, +and then map these count-statistics down to a small, dense vector for each word. +Predictive models directly try to predict a word from its neighbors in terms of +learned small, dense *embedding vectors* (considered parameters of the +model). + +Word2vec is a particularly computationally-efficient predictive model for +learning word embeddings from raw text. It comes in two flavors, the Continuous +Bag-of-Words model (CBOW) and the Skip-Gram model. Algorithmically, these +models are similar, except that CBOW predicts target words (e.g. 'mat') from +source context words ('the cat sits on the'), while the skip-gram does the +inverse and predicts source context-words from the target words. This inversion +might seem like an arbitrary choice, but statistically it has the effect that +CBOW smoothes over a lot of the distributional information (by treating an +entire context as one observation). For the most part, this turns out to be a +useful thing for smaller datasets. However, skip-gram treats each context-target +pair as a new observation, and this tends to do better when we have larger +datasets. We will focus on the skip-gram model in the rest of this tutorial. + + +## Scaling up with Noise-Contrastive Training + +Neural probabilistic language models are traditionally trained using the +[maximum likelihood](https://en.wikipedia.org/wiki/Maximum_likelihood) (ML) +principle to maximize the probability of the next word $$w_t$$ (for 'target) +given the previous words $$h$$ (for 'history') in terms of a +[*softmax* function](https://en.wikipedia.org/wiki/Softmax_function), + +$$ +\begin{align} +P(w_t | h) &= \text{softmax}(\exp \{ \text{score}(w_t, h) \}) \\ + &= \frac{\exp \{ \text{score}(w_t, h) \} } + {\sum_\text{Word w' in Vocab} \exp \{ \text{score}(w', h) \} }. +\end{align} +$$ + +where $$\text{score}(w_t, h)$$ computes the compatibility of word $$w_t$$ with +the context $$h$$ (a dot product is commonly used). We train this model by +maximizing its log-likelihood on the training set, i.e. by maximizing + +$$ +\begin{align} + J_\text{ML} &= \log P(w_t | h) \\ + &= \text{score}(w_t, h) - + \log \left( \sum_\text{Word w' in Vocab} \exp \{ \text{score}(w', h) \} \right) +\end{align} +$$ + +This yields a properly normalized probabilistic model for language modeling. +However this is very expensive, because we need to compute and normalize each +probability using the score for all other $$V$$ words $$w'$$ in the current +context $$h$$, *at every training step*. + +<div style="width:60%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/softmax-nplm.png" alt> +</div> + +On the other hand, for feature learning in word2vec we do not need a full +probabilistic model. The CBOW and skip-gram models are instead trained using a +binary classification objective (logistic regression) to discriminate the real +target words $$w_t$$ from $$k$$ imaginary (noise) words $$\tilde w$$, in the +same context. We illustrate this below for a CBOW model. For skip-gram the +direction is simply inverted. + +<div style="width:60%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/nce-nplm.png" alt> +</div> + +Mathematically, the objective (for each example) is to maximize + +$$J_\text{NEG} = \log Q_\theta(D=1 |w_t, h) + + k \mathop{\mathbb{E}}_{\tilde w \sim P_\text{noise}} + \left[ \log Q_\theta(D = 0 |\tilde w, h) \right]$$, + +where $$Q_\theta(D=1 | w, h)$$ is the binary logistic regression probability +under the model of seeing the word $$w$$ in the context $$h$$ in the dataset +$$D$$, calculated in terms of the learned embedding vectors $$\theta$$. In +practice we approximate the expectation by drawing $$k$$ constrastive words +from the noise distribution (i.e. we compute a +[Monte Carlo average](https://en.wikipedia.org/wiki/Monte_Carlo_integration)). + +This objective is maximized when the model assigns high probabilities +to the real words, and low probabilities to noise words. Technically, this is +called +[Negative Sampling](http://papers.nips.cc/paper/5021-distributed-representations-of-words-and-phrases-and-their-compositionality.pdf), +and there is good mathematical motivation for using this loss function: +The updates it proposes approximate the updates of the softmax function in the +limit. But computationally it is especially appealing because computing the +loss function now scales only with the number of *noise words* that we +select ($$k$$), and not *all words* in the vocabulary ($$V$$). This makes it +much faster to train. We will actually make use of the very similar +[noise-contrastive estimation (NCE)](http://papers.nips.cc/paper/5165-learning-word-embeddings-efficiently-with-noise-contrastive-estimation.pdf) +loss, for which TensorFlow has a handy helper function `tf.nn.nce_loss()`. + +Let's get an intuitive feel for how this would work in practice! + +## The Skip-gram Model + +As an example, let's consider the dataset + +`the quick brown fox jumped over the lazy dog` + +We first form a dataset of words and the contexts in which they appear. We +could define 'context' in any way that makes sense, and in fact people have +looked at syntactic contexts (i.e. the syntactic dependents of the current +target word, see e.g. +[Levy et al.](https://levyomer.files.wordpress.com/2014/04/dependency-based-word-embeddings-acl-2014.pdf)), +words-to-the-left of the target, words-to-the-right of the target, etc. For now, +let's stick to the vanilla definition and define 'context' as the window +of words to the left and to the right of a target word. Using a window +size of 1, we then have the dataset + +`([the, brown], quick), ([quick, fox], brown), ([brown, jumped], fox), ...` + +of `(context, target)` pairs. Recall that skip-gram inverts contexts and +targets, and tries to predict each context word from its target word, so the +task becomes to predict 'the' and 'brown' from 'quick', 'quick' and 'fox' from +'brown', etc. Therefore our dataset becomes + +`(quick, the), (quick, brown), (brown, quick), (brown, fox), ...` + +of `(input, output)` pairs. The objective function is defined over the entire +dataset, but we typically optimize this with +[stochastic gradient descent](https://en.wikipedia.org/wiki/Stochastic_gradient_descent) +(SGD) using one example at a time (or a 'minibatch' of `batch_size` examples, +where typically `16 <= batch_size <= 512`). So let's look at one step of +this process. + +Let's imagine at training step $$t$$ we observe the first training case above, +where the goal is to predict `the` from `quick`. We select `num_noise` number +of noisy (contrastive) examples by drawing from some noise distribution, +typically the unigram distribution, $$P(w)$$. For simplicity let's say +`num_noise=1` and we select `sheep` as a noisy example. Next we compute the +loss for this pair of observed and noisy examples, i.e. the objective at time +step $$t$$ becomes + +$$J^{(t)}_\text{NEG} = \log Q_\theta(D=1 | \text{the, quick}) + + \log(Q_\theta(D=0 | \text{sheep, quick}))$$. + +The goal is to make an update to the embedding parameters $$\theta$$ to improve +(in this case, maximize) this objective function. We do this by deriving the +gradient of the loss with respect to the embedding parameters $$\theta$$, i.e. +$$\frac{\partial}{\partial \theta} J_\text{NEG}$$ (luckily TensorFlow provides +easy helper functions for doing this!). We then perform an update to the +embeddings by taking a small step in the direction of the gradient. When this +process is repeated over the entire training set, this has the effect of +'moving' the embedding vectors around for each word until the model is +successful at discriminating real words from noise words. + +We can visualize the learned vectors by projecting them down to 2 dimensions +using for instance something like the +[t-SNE dimensionality reduction technique](http://lvdmaaten.github.io/tsne/). +When we inspect these visualizations it becomes apparent that the vectors +capture some general, and in fact quite useful, semantic information about +words and their relationships to one another. It was very interesting when we +first discovered that certain directions in the induced vector space specialize +towards certain semantic relationships, e.g. *male-female*, *gender* and +even *country-capital* relationships between words, as illustrated in the figure +below (see also for example +[Mikolov et al., 2013](http://www.aclweb.org/anthology/N13-1090)). + +<div style="width:100%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/linear-relationships.png" alt> +</div> + +This explains why these vectors are also useful as features for many canonical +NLP prediction tasks, such as part-of-speech tagging or named entity recognition +(see for example the original work by +[Collobert et al.](http://arxiv.org/pdf/1103.0398v1.pdf), or follow-up work by +[Turian et al.](http://www.aclweb.org/anthology/P10-1040)). + +But for now, let's just use them to draw pretty pictures! + +## Building the Graph + +This is all about embeddings, so let's define our embedding matrix. +This is just a big random matrix to start. We'll initialize the values to be +uniform in the unit cube. + +```python +embeddings = tf.Variable( + tf.random_uniform([vocabulary_size, embedding_size], -1.0, 1.0)) +``` + +The noise-contrastive estimation loss is defined in terms a logistic regression +model. For this, we need to define the weights and biases for each word in the +vocabulary (also called the `output weights` as opposed to the `input +embeddings`). So let's define that. + +```python +nce_weights = tf.Variable( + tf.truncated_normal([vocabulary_size, embedding_size], + stddev=1.0 / math.sqrt(embedding_size))) +nce_biases = tf.Variable(tf.zeros([vocabulary_size])) +``` + +Now that we have the parameters in place, we can define our skip-gram model +graph. For simplicity, let's suppose we've already integerized our text corpus +with a vocabulary so that each word is represented as an integer (see +[tensorflow/g3doc/tutorials/word2vec/word2vec_basic.py](./word2vec_basic.py) for +the details). The skip-gram model takes two inputs. One is a batch full of +integers representing the source context words, the other is for the target +words. Let's create placeholder nodes for these inputs, so that we can feed in +data later. + +```python +# Placeholders for inputs +train_inputs = tf.placeholder(tf.int32, shape=[batch_size]) +train_labels = tf.placeholder(tf.int32, shape=[batch_size, 1]) +``` + +Now what we need to do is look up the vector for each of the source words in +the batch. TensorFlow has handy helpers that make this easy. + +```python +embed = tf.nn.embedding_lookup(embeddings, train_inputs) +``` + +Ok, now that we have the embeddings for each word, we'd like to try to predict +the target word using the noise-contrastive training objective. + +```python +# Compute the NCE loss, using a sample of the negative labels each time. +loss = tf.reduce_mean( + tf.nn.nce_loss(nce_weights, nce_biases, embed, train_labels, + num_sampled, vocabulary_size)) +``` + +Now that we have a loss node, we need to add the nodes required to compute +gradients and update the parameters, etc. For this we will use stochastic +gradient descent, and TensorFlow has handy helpers to make this easy. + +```python +# We use the SGD optimizer. +optimizer = tf.train.GradientDescentOptimizer(learning_rate=1.0).minimize(loss) +``` + +## Training the Model + +Training the model is then as simple as using a `feed_dict` to push data into +the placeholders and calling `session.run` with this new data in a loop. + +```python +for inputs, labels in generate_batch(...): + feed_dict = {training_inputs: inputs, training_labels: labels} + _, cur_loss = session.run([optimizer, loss], feed_dict=feed_dict) +``` + +See the full example code in +[tensorflow/g3doc/tutorials/word2vec/word2vec_basic.py](./word2vec_basic.py). + +## Visualizing the Learned Embeddings + +After training has finished we can visualize the learned embeddings using +t-SNE. + +<div style="width:100%; margin:auto; margin-bottom:10px; margin-top:20px;"> +<img style="width:100%" src="img/tsne.png" alt> +</div> + +Et voila! As expected, words that are similar end up clustering nearby each +other. For a more heavyweight implementation of word2vec that showcases more of +the advanced features of TensorFlow, see the implementation in +[tensorflow/models/embedding/word2vec.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/embedding/word2vec.py). + +## Evaluating Embeddings: Analogical Reasoning + +Embeddings are useful for a wide variety of prediction tasks in NLP. Short of +training a full-blown part-of-speech model or named-entity model, one simple way +to evaluate embeddings is to directly use them to predict syntactic and semantic +relationships like `king is to queen as father is to ?`. This is called +*analogical reasoning* and the task was introduced by +[Mikolov and colleagues](http://msr-waypoint.com/en-us/um/people/gzweig/Pubs/NAACL2013Regularities.pdf), +and the dataset can be downloaded from here: +https://word2vec.googlecode.com/svn/trunk/questions-words.txt. + +To see how we do this evaluation, have a look at the `build_eval_graph()` and +`eval()` functions in +[tensorflow/models/embedding/word2vec.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/embedding/word2vec.py). + +The choice of hyperparameters can strongly influence the accuracy on this task. +To achieve state-of-the-art performance on this task requires training over a +very large dataset, carefully tuning the hyperparameters and making use of +tricks like subsampling the data, which is out of the scope of this tutorial. + + +## Optimizing the Implementation + +Our vanilla implementation showcases the flexibility of TensorFlow. For +example, changing the training objective is as simple as swapping out the call +to `tf.nn.nce_loss()` for an off-the-shelf alternative such as +`tf.nn.sampled_softmax_loss()`. If you have a new idea for a loss function, you +can manually write an expression for the new objective in TensorFlow and let +the optimizer compute its derivatives. This flexibility is invaluable in the +exploratory phase of machine learning model development, where we are trying +out several different ideas and iterating quickly. + +Once you have a model structure you're satisfied with, it may be worth +optimizing your implementation to run more efficiently (and cover more data in +less time). For example, the naive code we used in this tutorial would suffer +compromised speed because we use Python for reading and feeding data items -- +each of which require very little work on the TensorFlow back-end. If you find +your model is seriously bottlenecked on input data, you may want to implement a +custom data reader for your problem, as described in [New Data +Formats](../how_tos/new_data_formats/index.md). For the case of Skip-Gram +modeling, we've actually already done this for you as an example in +[tensorflow/models/embedding/word2vec.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/embedding/word2vec.py). + +If your model is no longer I/O bound but you want still more performance, you +can take things further by writing your own TensorFlow Ops, as described in +[Adding a New Op](../how_tos/adding_an_op/index.md). Again we've provided an +example of this for the Skip-Gram case +[tensorflow/models/embedding/word2vec_optimized.py](https://tensorflow.googlesource.com/tensorflow/+/master/tensorflow/models/embedding/word2vec_optimized.py). +Feel free to benchmark these against each other to measure performance +improvements at each stage. + +## Conclusion + +In this tutorial we covered the word2vec model, a computationally efficient +model for learning word embeddings. We motivated why embeddings are useful, +discussed efficient training techniques and showed how to implement all of this +in TensorFlow. Overall, we hope that this has show-cased how TensorFlow affords +you the flexibility you need for early experimentation, and the control you +later need for bespoke optimized implementation. diff --git a/tensorflow/g3doc/tutorials/word2vec/word2vec_basic.py b/tensorflow/g3doc/tutorials/word2vec/word2vec_basic.py new file mode 100644 index 0000000000..0a981570fa --- /dev/null +++ b/tensorflow/g3doc/tutorials/word2vec/word2vec_basic.py @@ -0,0 +1,219 @@ +import collections +import math +import numpy as np +import os +import random +import tensorflow as tf +import urllib +import zipfile + +# Step 1: Download the data. +url = 'http://mattmahoney.net/dc/' + +def maybe_download(filename, expected_bytes): + """Download a file if not present, and make sure it's the right size.""" + if not os.path.exists(filename): + filename, _ = urllib.urlretrieve(url + filename, filename) + statinfo = os.stat(filename) + if statinfo.st_size == expected_bytes: + print 'Found and verified', filename + else: + print statinfo.st_size + raise Exception( + 'Failed to verify ' + filename + '. Can you get to it with a browser?') + return filename + +filename = maybe_download('text8.zip', 31344016) + +# Read the data into a string. +def read_data(filename): + f = zipfile.ZipFile(filename) + for name in f.namelist(): + return f.read(name).split() + f.close() + +words = read_data(filename) +print 'Data size', len(words) + +# Step 2: Build the dictionary and replace rare words with UNK token. +vocabulary_size = 50000 + +def build_dataset(words): + count = [['UNK', -1]] + count.extend(collections.Counter(words).most_common(vocabulary_size - 1)) + dictionary = dict() + for word, _ in count: + dictionary[word] = len(dictionary) + data = list() + unk_count = 0 + for word in words: + if word in dictionary: + index = dictionary[word] + else: + index = 0 # dictionary['UNK'] + unk_count = unk_count + 1 + data.append(index) + count[0][1] = unk_count + reverse_dictionary = dict(zip(dictionary.values(), dictionary.keys())) + return data, count, dictionary, reverse_dictionary + +data, count, dictionary, reverse_dictionary = build_dataset(words) +del words # Hint to reduce memory. +print 'Most common words (+UNK)', count[:5] +print 'Sample data', data[:10] + +data_index = 0 + +# Step 4: Function to generate a training batch for the skip-gram model. +def generate_batch(batch_size, num_skips, skip_window): + global data_index + assert batch_size % num_skips == 0 + assert num_skips <= 2 * skip_window + batch = np.ndarray(shape=(batch_size), dtype=np.int32) + labels = np.ndarray(shape=(batch_size, 1), dtype=np.int32) + span = 2 * skip_window + 1 # [ skip_window target skip_window ] + buffer = collections.deque(maxlen=span) + for _ in range(span): + buffer.append(data[data_index]) + data_index = (data_index + 1) % len(data) + for i in range(batch_size / num_skips): + target = skip_window # target label at the center of the buffer + targets_to_avoid = [ skip_window ] + for j in range(num_skips): + while target in targets_to_avoid: + target = random.randint(0, span - 1) + targets_to_avoid.append(target) + batch[i * num_skips + j] = buffer[skip_window] + labels[i * num_skips + j, 0] = buffer[target] + buffer.append(data[data_index]) + data_index = (data_index + 1) % len(data) + return batch, labels + +batch, labels = generate_batch(batch_size=8, num_skips=2, skip_window=1) +for i in range(8): + print batch[i], '->', labels[i, 0] + print reverse_dictionary[batch[i]], '->', reverse_dictionary[labels[i, 0]] + +# Step 5: Build and train a skip-gram model. + +batch_size = 128 +embedding_size = 128 # Dimension of the embedding vector. +skip_window = 1 # How many words to consider left and right. +num_skips = 2 # How many times to reuse an input to generate a label. + +# We pick a random validation set to sample nearest neighbors. Here we limit the +# validation samples to the words that have a low numeric ID, which by +# construction are also the most frequent. +valid_size = 16 # Random set of words to evaluate similarity on. +valid_window = 100 # Only pick dev samples in the head of the distribution. +valid_examples = np.array(random.sample(xrange(valid_window), valid_size)) +num_sampled = 64 # Number of negative examples to sample. + +graph = tf.Graph() + +with graph.as_default(): + + # Input data. + train_inputs = tf.placeholder(tf.int32, shape=[batch_size]) + train_labels = tf.placeholder(tf.int32, shape=[batch_size, 1]) + valid_dataset = tf.constant(valid_examples, dtype=tf.int32) + + # Construct the variables. + embeddings = tf.Variable( + tf.random_uniform([vocabulary_size, embedding_size], -1.0, 1.0)) + nce_weights = tf.Variable( + tf.truncated_normal([vocabulary_size, embedding_size], + stddev=1.0 / math.sqrt(embedding_size))) + nce_biases = tf.Variable(tf.zeros([vocabulary_size])) + + # Look up embeddings for inputs. + embed = tf.nn.embedding_lookup(embeddings, train_inputs) + + # Compute the average NCE loss for the batch. + # tf.nce_loss automatically draws a new sample of the negative labels each + # time we evaluate the loss. + loss = tf.reduce_mean( + tf.nn.nce_loss(nce_weights, nce_biases, embed, train_labels, + num_sampled, vocabulary_size)) + + # Construct the SGD optimizer using a learning rate of 1.0. + optimizer = tf.train.GradientDescentOptimizer(1.0).minimize(loss) + + # Compute the cosine similarity between minibatch examples and all embeddings. + norm = tf.sqrt(tf.reduce_sum(tf.square(embeddings), 1, keep_dims=True)) + normalized_embeddings = embeddings / norm + valid_embeddings = tf.nn.embedding_lookup( + normalized_embeddings, valid_dataset) + similarity = tf.matmul( + valid_embeddings, normalized_embeddings, transpose_b=True) + +# Step 6: Begin training +num_steps = 100001 + +with tf.Session(graph=graph) as session: + # We must initialize all variables before we use them. + tf.initialize_all_variables().run() + print "Initialized" + + average_loss = 0 + for step in xrange(num_steps): + batch_inputs, batch_labels = generate_batch( + batch_size, num_skips, skip_window) + feed_dict = {train_inputs : batch_inputs, train_labels : batch_labels} + + # We perform one update step by evaluating the optimizer op (including it + # in the list of returned values for session.run() + _, loss_val = session.run([optimizer, loss], feed_dict=feed_dict) + average_loss += loss_val + + if step % 2000 == 0: + if step > 0: + average_loss = average_loss / 2000 + # The average loss is an estimate of the loss over the last 2000 batches. + print "Average loss at step ", step, ": ", average_loss + average_loss = 0 + + # note that this is expensive (~20% slowdown if computed every 500 steps) + if step % 10000 == 0: + sim = similarity.eval() + for i in xrange(valid_size): + valid_word = reverse_dictionary[valid_examples[i]] + top_k = 8 # number of nearest neighbors + nearest = (-sim[i, :]).argsort()[1:top_k+1] + log_str = "Nearest to %s:" % valid_word + for k in xrange(top_k): + close_word = reverse_dictionary[nearest[k]] + log_str = "%s %s," % (log_str, close_word) + print log_str + final_embeddings = normalized_embeddings.eval() + +# Step 7: Visualize the embeddings. + +def plot_with_labels(low_dim_embs, labels, filename='tsne.png'): + assert low_dim_embs.shape[0] >= len(labels), "More labels than embeddings" + plt.figure(figsize=(18, 18)) #in inches + for i, label in enumerate(labels): + x, y = low_dim_embs[i,:] + plt.scatter(x, y) + plt.annotate(label, + xy=(x, y), + xytext=(5, 2), + textcoords='offset points', + ha='right', + va='bottom') + + plt.savefig(filename) + +try: + from sklearn.manifold import TSNE + import matplotlib.pyplot as plt + + tsne = TSNE(perplexity=30, n_components=2, init='pca', n_iter=5000) + plot_only = 500 + low_dim_embs = tsne.fit_transform(final_embeddings[:plot_only,:]) + labels = dictionary.keys()[:plot_only] + plot_with_labels(low_dim_embs, labels) + +except ImportError: + print "Please install sklearn and matplotlib to visualize embeddings." + |
