diff options
Diffstat (limited to 'tensorflow/g3doc/get_started')
| -rw-r--r-- | tensorflow/g3doc/get_started/basic_usage.md | 273 | ||||
| -rw-r--r-- | tensorflow/g3doc/get_started/blue_pill.jpg | 0 | ||||
| -rw-r--r-- | tensorflow/g3doc/get_started/index.md | 84 | ||||
| -rw-r--r-- | tensorflow/g3doc/get_started/os_setup.md | 261 | ||||
| -rw-r--r-- | tensorflow/g3doc/get_started/red_pill.jpg | 0 |
5 files changed, 618 insertions, 0 deletions
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 |
