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 <[email protected]> Authored: Thu Aug 11 23:13:12 2016 +0800 Committer: Wei Wang <[email protected]> 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 [email protected]. * 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:
