You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@singa.apache.org by wa...@apache.org on 2016/08/17 18:02:51 UTC
[30/51] [abbrv] incubator-singa git commit: SINGA-237 New
documentation files for SINGA v1.0
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 <wa...@comp.nus.edu.sg>
Authored: Thu Aug 11 23:13:12 2016 +0800
Committer: Wei Wang <wa...@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 @@
-# \u6700\u65b0\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8
-
----
-
-* [\u30a4\u30f3\u30c8\u30ed\u30c0\u30af\u30b7\u30e7\u30f3](overview.html)
-* [\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb](installation.html)
-* [\u30af\u30a4\u30c3\u30af\u30b9\u30bf\u30fc\u30c8](quick-start.html)
-* [\u30d7\u30ed\u30b0\u30e9\u30df\u30f3\u30b0 \u30ac\u30a4\u30c9](programming-guide.html)
- * [NeuralNet](neural-net.html)
- * [Layer](layer.html)
- * [Param](param.html)
- * [TrainOneBatch](train-one-batch.html)
- * [Updater](updater.html)
-* [\u5206\u6563 \u30c8\u30ec\u30fc\u30cb\u30f3\u30b0](distributed-training.html)
-* [\u30c7\u30fc\u30bf\u306e\u6e96\u5099](data.html)
-* [Checkpoint \u3068 Resume](checkpoint.html)
-* [\u30d1\u30d5\u30a9\u30fc\u30de\u30f3\u30b9\u30c6\u30b9\u30c8 \u3068 \u7279\u5fb4\u62bd\u51fa](test.html)
-* [\u30b5\u30f3\u30d7\u30eb](examples.html)
- * Feed-forward \u30e2\u30c7\u30eb
- * [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 @@
-# \ucd5c\uc2e0 \ubb38\uc11c
-
----
-
-* [\uac1c\uc694](overview.html)
-* [\uc778\uc2a4\ud1a8](installation.html)
-* [\ud035 \uc2a4\ud0c0\ud2b8](quick-start.html)
-* [\ud504\ub85c\uadf8\ub798\ubc0d \uac00\uc774\ub4dc](programming-guide.html)
- * [NeuralNet](neural-net.html)
- * [Layer](layer.html)
- * [Param](param.html)
- * [TrainOneBatch](train-one-batch.html)
- * [Updater](updater.html)
-* [\ubd84\uc0b0 \ud2b8\ub808\uc774\ub2dd](distributed-training.html)
-* [\ub370\uc774\ud130 \uc900\ube44](data.html)
-* [Checkpoint \uc640 Resume](checkpoint.html)
-* [\uc131\ub2a5\ud14c\uc2a4\ud2b8 \ubc0f \ud2b9\uc9d5\ucd94\ucd9c](test.html)
-* [\uc0d8\ud50c](examples.html)
- * Feed-forward \ubaa8\ub378
- * [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 \u4e2d\u6587\u6587\u6863
----
+==============
-* [\u7b80\u4ecb](overview.html)
-* [\u5b89\u88c5](installation_source.html)
-* [\u4f7f\u7528\u6307\u5357](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: