Mailing-List: contact commits-help@singa.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@singa.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
From: wangwei@apache.org
To: commits@singa.incubator.apache.org
Date: Wed, 17 Aug 2016 18:02:51 -0000
Message-Id: <0704f3ea924143a689314da296571d39@git.apache.org>
In-Reply-To: <f12e81afa180432caccf4327be38925b@git.apache.org>
References: <f12e81afa180432caccf4327be38925b@git.apache.org>
Subject: [30/51] [abbrv] incubator-singa git commit: SINGA-237 New
 documentation files for SINGA v1.0
archived-at: Wed, 17 Aug 2016 18:02:36 -0000

SINGA-237 New documentation files for SINGA v1.0

1. copy the 'examples' folder into docs/ to generate htmls files using the README.md files
2. add software_stack.md to describe the major data structures of v1.0
3. add device.rst to introduce the Device APIs


Project: http://git-wip-us.apache.org/repos/asf/incubator-singa/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-singa/commit/e963363a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-singa/tree/e963363a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-singa/diff/e963363a

Branch: refs/heads/master
Commit: e963363a6d99825d8f4472130559814347845194
Parents: 6b2ff3c
Author: Wei Wang <wangwei@comp.nus.edu.sg>
Authored: Thu Aug 11 23:13:12 2016 +0800
Committer: Wei Wang <wangwei@comp.nus.edu.sg>
Committed: Mon Aug 15 21:02:47 2016 +0800

----------------------------------------------------------------------
 doc/Makefile                      |   1 +
 doc/_static/images/singav1-sw.png | Bin 0 -> 24326 bytes
 doc/conf.py                       |  18 +++---
 doc/docs.rst                      |   6 +-
 doc/docs/device.rst               |  38 +++++++++++++
 doc/docs/examples.rst             |   6 ++
 doc/docs/index.rst                |  16 ++----
 doc/docs/jp/index.md              |  23 --------
 doc/docs/kr/index.md              |  23 --------
 doc/docs/software_stack.md        |  99 +++++++++++++++++++++++++++++++++
 doc/docs/tensor.rst               |  54 ++++++++++++++++++
 doc/docs/zh/index.md              |  10 ++--
 doc/index.rst                     |  28 +++++-----
 examples/index.rst                |   6 ++
 src/python/singa/device.py        |  31 +++++++++++
 src/python/singa/tensor.py        |  49 +++++++++++++---
 16 files changed, 311 insertions(+), 97 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/Makefile
----------------------------------------------------------------------
diff --git a/doc/Makefile b/doc/Makefile
index 62a2236..c6eddf1 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -50,6 +50,7 @@ clean:
 
 .PHONY: html
 html:
+	cp -rf ../examples docs/
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/_static/images/singav1-sw.png
----------------------------------------------------------------------
diff --git a/doc/_static/images/singav1-sw.png b/doc/_static/images/singav1-sw.png
new file mode 100644
index 0000000..e443c6e
Binary files /dev/null and b/doc/_static/images/singav1-sw.png differ

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/conf.py
----------------------------------------------------------------------
diff --git a/doc/conf.py b/doc/conf.py
index 86dc031..9d4480e 100755
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,9 +16,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(1, os.path.abspath('../build/python'))
 
 # -- General configuration ------------------------------------------------
 from recommonmark.parser import CommonMarkParser
@@ -34,9 +35,8 @@ source_parsers = {
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-   
-]
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+napoleon_google_docstring = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -49,7 +49,7 @@ source_suffix = ['.rst', '.md']
 
 # The encoding of source files.
 #
-# source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
@@ -149,7 +149,7 @@ html_theme = 'sphinx_rtd_theme'
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-html_logo = '/singa.png'
+html_logo = 'image/singa.png'
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -202,7 +202,7 @@ html_static_path = ['_static']
 
 # If true, links to the reST sources are added to the pages.
 #
-html_show_sourcelink = False
+# html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs.rst
----------------------------------------------------------------------
diff --git a/doc/docs.rst b/doc/docs.rst
index 2ebea60..400b12a 100644
--- a/doc/docs.rst
+++ b/doc/docs.rst
@@ -2,7 +2,5 @@ Documentation
 =============
 
 .. toctree::
-	docs/index
- 	docs/zh/index
-	docs/jp/index
-	docs/kr/index
+   docs/index
+   docs/zh/index

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/device.rst
----------------------------------------------------------------------
diff --git a/doc/docs/device.rst b/doc/docs/device.rst
new file mode 100644
index 0000000..e79d87a
--- /dev/null
+++ b/doc/docs/device.rst
@@ -0,0 +1,38 @@
+Device
+=======
+
+
+The Device abstract represents any hardware device with memory and compuation units.
+All [Tensor operations](tensor.html) are scheduled by the resident device for execution.
+Tensor memory is also managed by the device's memory manager. Therefore, optimization
+of memory and execution are implemented in the Device class.
+
+Specific devices
+----------------
+Currently, SINGA has three Device implmentations,
+
+1. CudaGPU for an Nvidia GPU card which runs Cuda code
+2. CppCPU for a CPU which runs Cpp code
+3. OpenclGPU for a GPU card which runs OpenCL code
+
+
+Python API
+----------
+
+.. automodule:: singa.device
+   :members: create_cuda_gpus, create_cuda_gpus_on, get_default_device
+
+
+The following code provides examples of creating devices,
+
+.. code:: python
+
+   from singa import device
+   cuda = device.create_cuda_gpu_on(0)  # use GPU card of ID 0
+   host = device.get_default_device()  # get the default host device (a CppCPU)
+   ary1 = device.create_cuda_gpus(2)  # create 2 devices, starting from ID 0
+   ary2 = device.create_cuda_gpus([0,2])  # create 2 devices on ID 0 and 2
+
+
+CPP API
+---------

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/examples.rst
----------------------------------------------------------------------
diff --git a/doc/docs/examples.rst b/doc/docs/examples.rst
new file mode 100644
index 0000000..b0b2af8
--- /dev/null
+++ b/doc/docs/examples.rst
@@ -0,0 +1,6 @@
+Examples
+========
+
+.. toctree::
+
+   examples/index

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/index.rst
----------------------------------------------------------------------
diff --git a/doc/docs/index.rst b/doc/docs/index.rst
index a6a1b49..2f6352e 100644
--- a/doc/docs/index.rst
+++ b/doc/docs/index.rst
@@ -2,15 +2,9 @@ English
 =======
 
 .. toctree::
-	overview
-        installation
-	quick-start
-        programming-guide
-        distributed-training
-        data
-        checkpoint
-        python
-        test
-        gpu
-        examples
 
+   installation
+   software_stack
+   device
+   tensor
+   examples

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/jp/index.md
----------------------------------------------------------------------
diff --git a/doc/docs/jp/index.md b/doc/docs/jp/index.md
deleted file mode 100644
index 6679198..0000000
--- a/doc/docs/jp/index.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# 最新ドキュメント
-
----
-
-* [イントロダクション](overview.html)
-* [インストール](installation.html)
-* [クイックスタート](quick-start.html)
-* [プログラミング ガイド](programming-guide.html)
-    * [NeuralNet](neural-net.html)
-        * [Layer](layer.html)
-        * [Param](param.html)
-    * [TrainOneBatch](train-one-batch.html)
-    * [Updater](updater.html)
-* [分散 トレーニング](distributed-training.html)
-* [データの準備](data.html)
-* [Checkpoint と Resume](checkpoint.html)
-* [パフォーマンステスト と 特徴抽出](test.html)
-* [サンプル](examples.html)
-    * Feed-forward モデル
-        * [CNN](cnn.html)
-        * [MLP](mlp.html)
-    * [RBM + Auto-encoder](rbm.html)
-    * [RNN](rnn.html)

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/kr/index.md
----------------------------------------------------------------------
diff --git a/doc/docs/kr/index.md b/doc/docs/kr/index.md
deleted file mode 100644
index 990d5d9..0000000
--- a/doc/docs/kr/index.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# 최신 문서
-
----
-
-* [개요](overview.html)
-* [인스톨](installation.html)
-* [퀵 스타트](quick-start.html)
-* [프로그래밍 가이드](programming-guide.html)
-    * [NeuralNet](neural-net.html)
-        * [Layer](layer.html)
-        * [Param](param.html)
-    * [TrainOneBatch](train-one-batch.html)
-    * [Updater](updater.html)
-* [분산 트레이닝](distributed-training.html)
-* [데이터 준비](data.html)
-* [Checkpoint 와 Resume](checkpoint.html)
-* [성능테스트 및 특징추출](test.html)
-* [샘플](examples.html)
-    * Feed-forward 모델
-        * [CNN](cnn.html)
-        * [MLP](mlp.html)
-    * [RBM + Auto-encoder](rbm.html)
-    * [RNN](rnn.html)

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/software_stack.md
----------------------------------------------------------------------
diff --git a/doc/docs/software_stack.md b/doc/docs/software_stack.md
new file mode 100644
index 0000000..c60b6a5
--- /dev/null
+++ b/doc/docs/software_stack.md
@@ -0,0 +1,99 @@
+# Software Stack
+
+SINGA's software stack includes three major components, namely, core, IO and
+model. Figure 1 illustrates these components together with the hardware.
+The core component provides memory management and tensor operations;
+IO has classes for reading (and writing) data from (to) disk and network; The
+model component provides data structures and algorithms for machine learning models,
+e.g., layers for neural network models, optimizers/initializer/metric/loss for
+general machine learning models.
+
+
+<img src="../_static/images/singav1-sw.png" align="center" width="500px"/>
+<br/>
+<span><strong>Figure 1 - SINGA V1 software stack.</strong></span>
+
+## Core
+
+[Tensor](tensor.html) and [Device](device.html) are two core abstractions in SINGA. Tensor class represents a
+multi-dimensional array, which stores model variables and provides linear algebra
+operations for machine learning
+algorithms, including matrix multiplication and random functions. Each tensor
+instance (i.e. a tensor) is allocated on a Device instance.
+Each Device instance (i.e. a device) is created against one hardware device,
+e.g. a GPU card or a CPU core. Devices manage the memory of tensors and execute
+tensor operations on its execution units, e.g. CPU threads or CUDA streams.
+
+Depending on the hardware and the programming language, SINGA have implemented
+the following specific device classes:
+
+* **CudaGPU** represents an Nvidia GPU card. The execution units are the CUDA streams.
+* **CppCPU** represents a normal CPU. The execution units are the CPU threads.
+* **OpenclGPU** represents normal GPU card from both Nvidia and AMD.
+  The execution units are the CommandQueues. Given that OpenCL is compatible with
+  many hardware devices, e.g. FPGA and ARM, the OpenclGPU has the potential to be
+  extended for other devices.
+
+Different types of devices use different programming languages to write the kernel
+functions for tensor operations,
+
+* CppMath (tensor_math_cpp.h) implements the tensor operations using Cpp for CppCPU
+* CudaMath (tensor_math_cuda.h) implements the tensor operations using CUDA for CudaGPU
+* OpenclMath (tensor_math_opencl.h) implements the tensor operations using OpenCL for OpenclGPU
+
+In addition, different types of data, such as float32 and float16, could be supported by adding
+the corresponding tensor functions.
+
+Typically, users would create a device instance and pass it to create multiple
+tensor instances. When users call the Tensor functions, these function would invoke
+the corresponding implementation (CppMath/CudaMath/OpenclMath) automatically. In
+other words, the implementation of Tensor operations is transparent to users.
+
+Most machine learning algorithms could be expressed using (dense or sparse) tensors.
+Therefore, with the Tensor abstraction, SINGA would be able to run a wide range of models,
+including deep learning models and other traditional machine learning models.
+
+The Tensor and Device abstractions are extensible to support a wide range of hardware device
+using different programming languages. A new hardware device would be supported by
+adding a new Device subclass and the corresponding implementation of the Tensor
+operations (xxxMath).
+
+Optimizations in terms of speed and memory could be implemented by Device, which
+manages both operation execution and memory malloc/free. More optimization details
+would be described in the [Device page](device.html).
+
+
+## Model
+
+On top of the Tensor and Device abstractions, SINGA provides some higher level
+classes for machine learning modules.
+
+* [Layer](layer.html) and its subclasses are specific for neural networks. Every layer provides
+  functions for forward propagating features and backward propagating gradients w.r.t the training loss functions.
+  They wraps the complex layer operations so that users can easily create neural nets
+  by connecting a set of layers.
+
+* [Initializer](initializer.html) and its subclasses provide variant methods of initializing
+  model parameters (stored in Tensor instances), following Uniform, Gaussian, etc.
+
+* [Loss](loss.html) and its subclasses defines the training objective loss functions.
+  Both functions of computing the loss values and computing the gradient of the prediction w.r.t the
+  objective loss are implemented. Example loss functions include squared error and cross entropy.
+
+* [Metric](metric.html) and its subclasses provide the function to measure the
+  performance of the model, e.g., the accuracy.
+
+* [Optimizer](optimizer.html) and its subclasses implement the methods for updating
+  model parameter values using parameter gradients, including SGD, AdaGrad, RMSProp etc.
+
+
+## IO
+
+The IO module consists of classes for data loading, data preprocessing and message passing.
+
+* Reader and its subclasses load string records from disk files
+* Writer and its subclasses write string records to disk files
+* Encoder and its subclasses encode Tensor instances into string records
+* Decoder and its subclasses decodes string records into Tensor instances
+* Endpoint represents a communication endpoint which provides functions for passing messages to each other.
+* Message represents communication messages between Endpoint instances. It carries both meta data and payload.

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/tensor.rst
----------------------------------------------------------------------
diff --git a/doc/docs/tensor.rst b/doc/docs/tensor.rst
new file mode 100644
index 0000000..87d26ea
--- /dev/null
+++ b/doc/docs/tensor.rst
@@ -0,0 +1,54 @@
+Tensor
+========
+
+Each Tensor instance is a multi-dimensional array allocated on a specific
+Device instance. Tensor instances store variables and provide
+linear algebra operations over different types of hardware devices without user
+awareness. Note that users need to make sure the tensor operands are
+allocated on the same device except copy functions.
+
+
+Tensor implementation
+---------------------
+
+SINGA has three different sets of implmentations of Tensor functions, one for each
+type of Device.
+
+* 'tensor_math_cpp.h' implements operations using Cpp (with CBLAS) for CppGPU devices.
+* 'tensor_math_cuda.h' implements operations using Cuda (with cuBLAS) for CudaGPU devices.
+* 'tensor_math_opencl.h' implements operations using OpenCL for OpenclGPU devices.
+
+Python API
+----------
+
+There are two set of tensor functions,
+1. Tensor member functions, which would change the internal state of the Tensor instance.
+2. tensor module functions, which accepts Tensor instances as arguments and return
+Tensor instances.
+
+
+Create Tensor instances
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: singa.tensor.Tensor
+
+
+Tensor instances can be constructed from Numpy array,
+
+.. automodule:: singa.tensor
+   :members: from_numpy
+
+
+Set Tensor values
+~~~~~~~~~~~~~~~~~
+
+
+
+
+
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/docs/zh/index.md
----------------------------------------------------------------------
diff --git a/doc/docs/zh/index.md b/doc/docs/zh/index.md
index c44a2cf..4b49d5f 100644
--- a/doc/docs/zh/index.md
+++ b/doc/docs/zh/index.md
@@ -1,7 +1,9 @@
 SINGA 中文文档
----
+==============
 
-* [简介](overview.html)
-* [安装](installation_source.html)
-* [使用指南](programming-guide.html)
+.. toctree::
+
+   overview
+   installation_source
+   programming-guide
 

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/doc/index.rst
----------------------------------------------------------------------
diff --git a/doc/index.rst b/doc/index.rst
index ec727b1..50c65d7 100755
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -7,9 +7,9 @@ Welcome to Apache Singa
 =======================
 
 Recent News
-===========
+-----------
 
-* The **third release** is now available, 20 April, 2016. `Download SINGA v0.3.0 <downloads.html>`_ 
+* The **third release** is now available, 20 April, 2016. `Download SINGA v0.3.0 <downloads.html>`_
 
 * The **second release** is now available, 14 Jan, 2016. `Download SINGA v0.2.0 <downloads.html>`_.
 
@@ -34,7 +34,7 @@ Recent News
 * SINGA has been accepted by `Apache Incubator <http://incubator.apache.org/>`_, 17 March, 2015.
 
 Getting Started
-===============
+---------------
 * The `Introduction <docs/overview.html>`_ page gives an overview of SINGA.
 
 * The `Installation <docs/installation.html>`_ guide describes details on downloading and installing SINGA.
@@ -42,7 +42,7 @@ Getting Started
 * Please follow the `Quick Start <docs/quick-start.html>`_ guide to run simple applications on SINGA.
 
 Documentation
-=============
+-------------
 
 * Documentations are listed `here <docs.html>`_.
 
@@ -51,8 +51,8 @@ Documentation
 * Research publication list is available `here <http://www.comp.nus.edu.sg/~dbsystem/singa/research/publication/>`_.
 
 How to contribute
-=================
-  
+----------------------
+
 * Please subscribe to our development mailing list dev-subscribe@singa.incubator.apache.org.
 
 * If you find any issues using SINGA, please report it to the `Issue Tracker <https://issues.apache.org/jira/browse/singa>`_.
@@ -62,17 +62,17 @@ How to contribute
 More details on contributing to SINGA is described `here <develop/how-contribute.html>`_ .
 
 Citing SINGA
-============
+------------
 
 Please cite the following two papers if you use SINGA in your research:
 
 * B. C. Ooi, K.-L. Tan, S. Wang, W. Wang, Q. Cai, G. Chen, J. Gao, Z. Luo, A. K. H. Tung, Y. Wang, Z. Xie, M. Zhang, and K. Zheng. `SINGA: A distributed deep learning platform <http://www.comp.nus.edu.sg/~ooibc/singaopen-mm15.pdf>`_. ACM Multimedia (Open Source Software Competition) 2015 (`BibTex <http://www.comp.nus.edu.sg/~dbsystem/singa//assets/file/bib-oss.txt>`_).
 
-* W. Wang, G. Chen, T. T. A. Dinh, B. C. Ooi, K.-L.Tan, J. Gao, and S. Wang. `SINGA: putting deep learning in the hands of multimedia users <http://www.comp.nus.edu.sg/~ooibc/singa-mm15.pdf>`_. ACM Multimedia 2015 (`BibTex <http://www.comp.nus.edu.sg/~dbsystem/singa//assets/file/bib-singa.txt>`_, `Slides <files/mm2015.ppt>`_). 
+* W. Wang, G. Chen, T. T. A. Dinh, B. C. Ooi, K.-L.Tan, J. Gao, and S. Wang. `SINGA: putting deep learning in the hands of multimedia users <http://www.comp.nus.edu.sg/~ooibc/singa-mm15.pdf>`_. ACM Multimedia 2015 (`BibTex <http://www.comp.nus.edu.sg/~dbsystem/singa//assets/file/bib-singa.txt>`_, `Slides <files/mm2015.ppt>`_).
 
 .. toctree::
    :hidden:
-   
+
    downloads
    docs
 
@@ -85,25 +85,25 @@ Please cite the following two papers if you use SINGA in your research:
    develop/how-contribute
    develop/contribute-code
    develop/contribute-docs
-   
+
 .. toctree::
    :hidden:
    :maxdepth: 2
    :caption: Community
-   
+
    community/source-repository
    community/mail-lists
    community/issue-tracking
    community/team-list
-   
+
 
 
 License
-=======
+----------
 SINGA is released under `Apache License Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
 
 Disclaimers
-===========
+-----------
 
 Apache SINGA is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
 

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/examples/index.rst
----------------------------------------------------------------------
diff --git a/examples/index.rst b/examples/index.rst
new file mode 100644
index 0000000..d6faf5d
--- /dev/null
+++ b/examples/index.rst
@@ -0,0 +1,6 @@
+.. toctree::
+
+   char-rnn/README
+   imagenet/README
+
+

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/src/python/singa/device.py
----------------------------------------------------------------------
diff --git a/src/python/singa/device.py b/src/python/singa/device.py
index aff3587..eff6783 100644
--- a/src/python/singa/device.py
+++ b/src/python/singa/device.py
@@ -68,21 +68,52 @@ def device_query(id, verbose=False):
 
 
 def create_cuda_gpus(num):
+    '''Create a list of CudaGPU devices.
+
+    Args:
+        num (int): number of device to create.
+    Returns:
+        a list of swig converted CudaGPU devices.
+    '''
+
     return singa.Platform.CreateCudaGPUs(num)
 
 
 def create_cuda_gpu():
+    '''Create a single CudaGPU device.
+
+    Returns:
+        a swig converted CudaGPU device.
+    '''
+
     return singa.Platform.CreateCudaGPUs(1)[0]
 
 
 def create_cuda_gpus_on(device_ids):
+    '''Create a list of CudaGPU devices.
+
+    Args:
+        device_ids (list): a list of GPU card IDs.
+
+    Returns:
+        a list of swig converted CudaGPU devices.
+    '''
     return singa.Platform.CreateCudaGPUsOn(device_ids)
 
 
 def create_cuda_gpu_on(device_id):
+    '''Create a CudaGPU device on the given device ID.
+
+    Args:
+        device_id (int): GPU card ID.
+
+    Returns:
+        a swig converted CudaGPU device.
+    '''
     devices = create_cuda_gpus_on([device_id])
     return devices[0]
 
 
 def get_default_device():
+    '''Get the default host device which is a CppCPU device'''
     return singa.Platform.GetDefaultDevice()

http://git-wip-us.apache.org/repos/asf/incubator-singa/blob/e963363a/src/python/singa/tensor.py
----------------------------------------------------------------------
diff --git a/src/python/singa/tensor.py b/src/python/singa/tensor.py
index 6e84a4f..3645ff8 100644
--- a/src/python/singa/tensor.py
+++ b/src/python/singa/tensor.py
@@ -21,17 +21,21 @@ to call singa::Tensor and its methods
 """
 
 import numpy as np
+from functools import reduce
 from .proto import core_pb2
 from . import singa_wrap as singa
-from functools import reduce
+import device
 
 
 class Tensor(object):
-    ''' Class and member functions for singa::Tensor
-    '''
-
-    def __init__(self, shape=None, device=None, dtype=core_pb2.kFloat32):
-        ''' shape = (tuple)
+    def __init__(self, shape=None, device=None, dtype=core_pb.kFloat32):
+        '''Create a Py Tensor, which wraps a swig converted Tensor from SINGA
+            Tensor.
+        Args:
+            shape (list), a list of integers for the tensor shape. If shape is not specified, the created tensor is called a dummy tensor.
+            device, a Device instance created from ::py:mod:device. If it is
+                None, then the default host device would be used.
+            dtype, data type. currently, most operations only accept kFloat32.
         '''
         if shape is None:
             # call constructor of singa::Tensor
@@ -111,11 +115,19 @@ class Tensor(object):
         return self.singa_tensor.L1()
 
     def set_value(self, x):
+        '''Set all elements of the tensor to be the give value.
+
+        Args:
+            x (float), a float value to be set to all elements.
+        '''
         # assert type(x) == float, 'set value only accepts float input'
         # if isinstance(x, float):
         self.singa_tensor.floatSetValue(x)
 
     def copy_data(self, t):
+        '''Copy data from other Tensor instance.
+        '''
+        assert type(t) == Tensor, 't must be a singa Tensor instance'
         self.singa_tensor.CopyData(t.singa_tensor)
 
     def clone(self):
@@ -285,16 +297,35 @@ def copy_data_to_from(dst, src, size, dst_offset=0, src_offset=0):
 
 
 def from_numpy(np_array):
+    '''Create a Tensor instance with the shape, dtype and values from the numpy
+        array.
+
+    Args:
+        np_array: the numpy array.
+
+    Returns:
+        A Tensor instance allocated on the default CppCPU device.
+    '''
     ret = Tensor(np_array.shape)
     ret.copy_from_numpy(np_array)
     return ret
 
 
 def to_numpy(t):
-    ''' this method gets the values of tensor data and
-        returns it as numpy array
-        TODO(wangwei) clone t to host
+    '''Convert the tensor into a numpy array.
+
+    Since numpy array is allocated on CPU devices, the input Tensor instance
+    must be on the default CppCPU device.
+
+    Args:
+        t (Tensor), a Tensor on the default CppCPU device.
+
+    Returns:
+        a numpy array
     '''
+    assert t.device == device.get_default_device() or t.device == None, \
+        'Please move the tensor onto the default host device'
+
     if t.dtype == core_pb2.kFloat32:
         np_array = t.singa_tensor.floatGetValue(int(t.size()))
     elif t.dtype == core_pb2.kInt: